Advanced Concepts. SilkPerformer 2010 R2. Advanced Concepts

Transcription

1 Advanced Concepts SilkPerformer 2010 R2 Advanced Concepts

2 Borland Software Corporation 4 Hutton Centre Dr., Suite 900 Santa Ana, CA Copyright 2010 Micro Focus (IP) Limited. All Rights Reserved. SilkPerformer contains derivative works of Borland Software Corporation, Copyright Borland Software Corporation (a Micro Focus company). MICRO FOCUS and the Micro Focus logo, among others, are trademarks or registered trademarks of Micro Focus (IP) Limited or its subsidiaries or affiliated companies in the United States, United Kingdom and other countries. BORLAND, the Borland logo and SilkPerformer are trademarks or registered trademarks of Borland Software Corporation or its subsidiaries or affiliated companies in the United States, United Kingdom and other countries. All other marks are the property of their respective owners. November 2010

3 Contents Chapter 1 Client IP Address Simulation 1 Overview Multiple IP Addresses per NIC Adding IP Addresses via the System Configuration Wizard Setting Dynamic User IP Addresses Using Automatic Round-Robin Setting Dynamic User IP Addresses Using Script Functions Routing Principles Routing Problems Due to Client IP Address Simulation Solutions Testing Chapter 2 Remote Agent Connection 17 Overview Configuration Settings Default Settings for Remote Agent Connection. 20 Connecting through TCP/IP Firewalls Connecting through HTTP Firewalls Connecting through SOCKS Firewalls Connecting through Multiple Firewalls Chapter 3 Rule-Based Recording 27 Overview Recording Rule Files General Attributes of Recording Rules HTTP Parsing Rules TCP/IP Protocol Rules StringScriptingRule HttpScriptingRule ProxyEngineRule Conditions Troubleshooting Chapter 4 Web Context Management 97 Overview The Basics SilkPerformer's Page-level API How the Recorder Loses Context Advanced Context Management Techniques in SilkPerformer's Page-level API When to change record settings Limitations Chapter 5 Enhanced SNMP Support for SilkPerformer 125 Overview Data Source Definition Using Enhanced SNMP in Performance Explorer128 Chapter 6 Generating BDL Monitoring Projects for Performance Explorer 131 Overview Concepts Workflow Tutorial Best Practices Chapter 7 Load Testing SOAP Web Services 153 Overview Simple Object Access Protocol Load Testing SOAP over HTTP Based Web Services 155 Chapter 8 Load Testing Legacy and SilkPerformer Advanced Concepts iii

4 Custom TCP/IP Based Protocols 159 Overview Introduction Script Customization - General Tasks Telnet, TN3270e, and Custom Protocols Recorder Settings Summary Chapter 9 Load Testing Microsoft Based Distributed Applications 185 Overview Introduction The Sample Application Test Environment Test Goals and Procedures Specification of Test Scenarios First Load Test Applying Optimization Second Load Test Performance Comparison Back-End Test Testing Duwamish Online - A Case Study Glossary Chapter 10 Load Testing COM and ADO Based Applications 217 Overview Basic Concepts Enhancements in SilkPerformer Recording Replaying Monitoring Tips & Tricks Glossary Chapter 11 Load Testing Streaming Protocols 249 Overview Introduction to Streaming Media Using SilkPerformer's Streaming Feature Measured Data Streaming Function Overview Chapter 12 Load Testing Flash Remoting Applications 261 Configuring SilkPerformer Script Modeling Understanding Recorded Scripts Customizing Scripts Chapter 13 Load Testing Siebel 6 CRM Applications 271 Overview Architecture of Siebel 6 CRM Applications Installation and Requirements Key Management with Siebel Applications Formatting Scripts for Siebel Applications Recording and Customizing a Siebel Application283 References Chapter 14 Load Testing Siebel 7 CRM Applications 293 Overview Siebel 7 CRM Application Architecture Configuring SilkPerformer Dynamic Information in Siebel 7 Web Client HTTP Traffic Tips, Hints, & Best Practices Summary Chapter 15 Load Testing PeopleSoft Overview Configuring SilkPerformer Script Modeling Application Level Errors Parameterization Chapter 16 Load Testing Oracle Forms 333 Overview Basic Concepts Installation and Requirements Record and Replay Oracle Forms TrueLogs Monitoring Root Cause Analysis iv SilkPerformer Advanced Concepts

5 Tips & Tricks Chapter 17 Load Testing SAP GUI 377 Overview Basic Concepts Installation and Requirements Recording and Replay TrueLog Preparing for Large Load Tests Monitoring Tips & Tricks SilkPerformer Advanced Concepts v

6 vi SilkPerformer Advanced Concepts

7 1 Client 1Chapter IP Address Simulation Introduction What you will learn Using SilkPerformer's System Configuration Manager This chapter contains the following sections: Section Page Overview 1 Multiple IP Addresses per NIC 2 Adding IP Addresses via the System Configuration Wizard 2 Setting Dynamic User IP Addresses Using Automatic Round-Robin 6 Setting Dynamic User IP Addresses Using Script Functions 7 Routing Principles 8 Routing Problems Due to Client IP Address Simulation 10 Solutions 11 Testing 14 Overview This chapter explores SilkPerformer's client IP address simulation feature. Its 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. SilkPerformer Advanced Concepts 1

8 1 CLIENT IP ADDRESS SIMULATION Multiple IP Addresses per NIC Multiple IP Addresses per NIC When 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: 1 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. For details, see the next chapter. - Requirements: NT 4, SP 4 - 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. 2 Multiple NICs per physical network (physical multi-homed): - No restrictions other than hardware. 3 Multiple networks and media types: - No restrictions other than hardware and media support. See the Network Interface Card/Driver section of the Windows NT Server White Paper to learn about supported media types. Adding IP Addresses via the System Configuration Wizard 1 Disable DHCP, add gateway and DNS addresses. 2 SilkPerformer Advanced Concepts

9 1 CLIENT IP ADDRESS SIMULATION Adding IP Addresses via the System Configuration Wizard 2 Launch the SilkPerformer System Configuration Wizard. From the Tools menu, select System Configuration Manager. 3 Connect to the machine to which you wish to add new IP addresses. SilkPerformer Advanced Concepts 3

10 1 CLIENT IP ADDRESS SIMULATION Adding IP Addresses via the System Configuration Wizard Note By default you will be connected to the localhost. If you aren't able to connect to a particular host, ensure that that host's Silk Launcher Service is running. 4 Select the IP Address Manager tab. 5 Select the network adapter to which you wish to add new IP addresses. 6 Using the Add IP Address dialog, specify the IP addresses you wish to add. 4 SilkPerformer Advanced Concepts

11 1 CLIENT IP ADDRESS SIMULATION Adding IP Addresses via the System Configuration Wizard Number - The number of sequential IP addresses to be added subsequent to the one specified in the From IP address entry. 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 When using the From IP address and To IP address fields, ensure that the To IP address is higher than the From IP address (e.g., From: , To: ). 7 Reboot the machine. 8 To verify that the IP addresses you added are valid, either: a b 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. SilkPerformer Advanced Concepts 5

12 1 CLIENT IP ADDRESS SIMULATION Setting Dynamic User IP Addresses Using Automatic Round-Robin Note By clicking the Check button with the Host name or IP address field blank, the System Configuration Manager checks that all added IP Addresses are functioning 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 Setting Dynamic User IP Addresses Using Automatic Round- Robin 1 From the main SilkPerformer window, select the Settings menu and the Active Profile menu item. 2 On the left side of the Profile Settings dialog, select the Internet icon. 3 Place a check in the Client IP address multiplexing checkbox. 4 Run your test and use a utility such as TCPView to verify your IP address multiplexing. 6 SilkPerformer Advanced Concepts

13 1 CLIENT IP ADDRESS SIMULATION Setting Dynamic User IP Addresses Using Script Functions Setting Dynamic User IP Addresses Using Script Functions For sample applications, review the WebMultipleClientIpAddresses01.bdf file. WebSetLocalAddress Description Include file Sets the local IP address WebAPI.bdh Syntax WebSetLocalAddress(in saddress string) : boolean; saddress IP address Return value true if the local IP address has been set successfully false otherwise WebTcpipConnect Include file Syntax WebAPI.bdh WebTcpipConnect( out hweb : number, in shost : string, in nport : number, in nsecurity : number optional in naddress : string optional ): boolean; hweb shost Vriable recieving a handle to the Web connection Domain name or IP address, for example, hostname.com or SilkPerformer Advanced Concepts 7

14 1 CLIENT IP ADDRESS SIMULATION Routing Principles nport nsecurity naddress 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 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 binds the IP address to the socket Return value true if the function succeeds, and the function stores a valid handle in hweb false otherwise Routing Principles Routing is one of the most important functions performed by IP. Routing is performed not only by routers, but also by each host that wants to send an IP packet. Fundamentally, routing is a decision made about where a packet should be sent, regardless of the packet's origin (i.e., from its own host or from another host). Each host maintains a routing table, which is processed each time a routing decision is made. 8 SilkPerformer Advanced Concepts

15 1 CLIENT IP ADDRESS SIMULATION Routing Principles Example Procedure To do this, Internet Protocol requires that the following steps be performed: 1 Search for a matching host address (netmask: ) 2 Search for a matching network address 3 Search for a default entry To compare a given IP address with routing-table entries, look at the Network Destination / Netmask pair. The netmask specifies the bits, which you may use or ignore. For example, the step by step procedure for comparing the IP address with the following entry in the table is: Network Netmask Gateway Interface Metric Destination Convert the addresses to their binary form: : : : Compare only those bits in which the corresponding netmask bit is 1 3 If they are all identical (as shown in the above example), the routingtable entry matches the IP address. Here is a Windows NT routing-table: (C:\>route print) ====================================================== Interface List 0x1...MS TCP Loopback interface 0x a 25 1b 08..3Com 3C90x Ethernet Adapter ====================================================== ====================================================== Active Routes: Network Destination Netmask Gateway Interface Metric =========================================================================== SilkPerformer Advanced Concepts 9

16 1 CLIENT IP ADDRESS SIMULATION Routing Problems Due to Client IP Address Simulation Interpretation of the entries: : Default Gateway If IP doesn't find any other matching entry it looks for this line and sends the packet to the specified Gateway ( ). If no such line exists, IP generates an error : Local loopback - Datagrams are sent to the loopback interface : Subnet address Any address beginning with is sent via the interface ( ) to the local subnet : Local IP address - Datagrams sent to this address are sent to (the loopback address) : Subnet broadcast address : IP multicast address : General IP broadcast address When IP finds the first matching Network Destination / Netmask pair (remember the search order), it looks up the gateway entry and sends the packet to the found gateway address (using the specified interface). Some special gateway entries include: (loopback-address): Sends to the loopback interface Its own IP address: IP address is on the local network - just send it. Routing Problems Due to Client IP Address Simulation 1 Sending packets from multi-homed clients to servers: With multi-homed clients, the destination IP address is always that of the selected server. Therefore there aren't differences between network operations and problems don't normally arise when delivering packets from multi-homed clients. 2 Sending packets from servers to multi-homed clients: Problems arise when a server attempts to send back a reply to a multihomed 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 10 SilkPerformer Advanced Concepts

17 1 CLIENT IP ADDRESS SIMULATION Solutions the server's routing-table. If the selected IP address doesn't belong to the local subnet, and the server doesn't find another matching entry in its routing-table (normal behavior when entries haven't been added) it sends the packet to the default-gateway (using the default entry). If it doesn't find a default entry, it generates a network unreachable error. Solutions There are several options for configuring servers to send responses to multihomed clients. Two options for different network configurations are detailed below: 1 Server and agent on the same subnet If you don't have a router between the agent and server (as shown in Figure 1), you only have to add entries to the server's routing table. If the generated clients' IP addresses begin with the same two numbers (e.g., ) you'll only need to add one entry to the server's routing table (route add mask <your normal IP address>). The server will then consider the client to be the appropriate router for all such addresses (beginning with ). Agent1 - Multi-homed Controller Agent Gateway Server Figure 1 SilkPerformer Advanced Concepts 11

18 1 CLIENT IP ADDRESS SIMULATION Solutions In the example in Figure 1, Server 1 receives a packet from Agent 1 and attempts to send its answer from to Without modifications to the server configuration (the server doesn't know that Agent 1 is multi-homed), Server 1 will send the packet to the default gateway, because there is only one matching routing-table entry: Network Netmask Gateway Interface Metric Destination If you call (at Server 1), route add mask a new entry will be added, that looks like this: Network Netmask Gateway Interface Metric Destination Because this entry has a higher priority than that of the default gateway, Server 1 will send all packets with a destination address type of x.x to Agent 1 (believing that this is the correct gateway). 2 A router or load-balancer is positioned between the server and the agent (As shown in Figure 2) In such instances, you need to alter the router's routing-table. 12 SilkPerformer Advanced Concepts

19 1 CLIENT IP ADDRESS SIMULATION Solutions Agent1 - Multi-homed Controller Agent Gateway Router Load Balancer Server Server Figure 2 If Agent 1 sends a packet to Server 1 (from to ) and Agent 1 is configured correctly, i.e it has a routingtable entry such as: Network Netmask Gateway Interface Metric Destination Agent 1 will send the packet to the router, which will in turn forward the packet to Server 1. SilkPerformer Advanced Concepts 13

20 1 CLIENT IP ADDRESS SIMULATION Testing Now Server 1 wants to send a response to Agent 1's request (from to ). Because of its default entry in the routing-table, Server 1 sends the packet to the router. Problems arise now however because the router knows nothing of Agent 1's new IP addresses and will use its default route: Network Netmask Gateway Interface Metric Destination and send the packet to the gateway. If you call (at the router): route add mask a new entry will be added, that looks like this: Network Netmask Gateway Interface Metric Destination Because this entry has a higher priority than that of the default gateway, the router will send all packets with a destination address type of x.x to Agent 1 (believing this to be the correct gateway) Note It is possible to configure your subnet's default gateway to forward all packets from the server to the multi-homed agent. However, there is a problem in that 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. Testing You can use the System Configuration Manager to determine if newly added IP addresses and routing adaptations work correctly. Launch the SilkPerformer System Configuration Wizard. Select System Configuration Manager from the Tools menu. Connect to the machine to which you added new IP addresses. 14 SilkPerformer Advanced Concepts

21 1 CLIENT IP ADDRESS SIMULATION Testing Note By default, you will be connected to the localhost. If you cannot connect to a particular host, ensure that that host's Silk Launcher Service is running. Select the IP Address Manager tab. Select the network adapter to which you added new IP addresses. In the network section, enter the host name or IP address of the server you wish to load test. Click the Check button and watch for an error window. If an error window doesn't appear, all listed IP addresses will have a route is up mark in the Test result section of the list window. SilkPerformer Advanced Concepts 15

22 1 CLIENT IP ADDRESS SIMULATION Testing 16 SilkPerformer Advanced Concepts

23 2 Remote 2Chapter Agent Connection What you will learn This chapter contains the following sections: Section Page Overview 17 Configuration Settings 17 Default Settings for Remote Agent Connection 20 Connecting through TCP/IP Firewalls 22 Connecting through HTTP Firewalls 23 Connecting through SOCKS Firewalls 24 Connecting through Multiple Firewalls 25 Overview This chapter explains how the SilkPerformer Controller connects to remote agents. It shows the communication architecture between the controller and remote agents and describes various configuration options. This chapter is especially helpful when configuring SilkPerformer in a distributed secure environment. It offers instructions for configuring SilkPerformer agents behind firewalls and connecting through HTTP and SOCKS proxies. Configuration Settings Remote connection settings for SilkPerformer remote agents are configured from the following two dialogs: Agent Machine: System Configuration Manager SilkPerformer Advanced Concepts 17

24 2 REMOTE AGENT CONNECTION Configuration Settings Controller Machine: Agent Connection Properties System Configuration Manager To launch the System Configuration Manager, go to the Tools menu and select System Configuration Manager. On the SilkPerformer tab, adjust the configuration options for both local and remote SilkPerformer agents. The following configuration options are available (see Figure 1): Agent connection port: The TCP/IP listener port for unsecured controller/agent connections (this is the default port used by the controller to connect to agents). Agent connection secure port: 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). Password: A password can be used to secure controller/agent communication. If you specify a password for an agent, the controller must supply a password to connect to that remote agent. Figure 1 - Configuring Remote Connection Settings (System Configuration Manager) 18 SilkPerformer Advanced Concepts

25 2 REMOTE AGENT CONNECTION Configuration Settings Agent Connection Properties On the Agent Connection Properties dialog you can configure how the controller connects to remote agents. In the SilkPerformer menu bar, select Settings/System. On the Agent Pool tab you can choose to configure one of the agents you have already connected by selecting that agent in the window - just double-click the name and computer icon of the agent. If you have not yet selected an agent for connection, click the Add WAN Agent button. After naming an agent, proceed as follows: The following configuration options are available (see Figure 2): Security - Encryption (SSL): By selecting this option you force the controller to use a secure connection to the remote agent. Security - Authenticate/Password: By selecting this option and supplying a password, the controller will connect to the remote agent using a password. The password must be identical to the password specified in the System Configuration Manager. Connection - Connect to port: The controller connects to the agent using this port if you have turned off security. The port must be identical to the agent connection port specified in the System Configuration Manager. Connection - Connect to secure port: The controller connects to the agent using this port if you have turned on the security option. The port must be identical to the agent connection secure port you specified in the System Configuration Manager. Firewall - Use the HTTP proxy server: The controller connects to the agent via an HTTP firewall by tunneling the controller/agent communication in the HTTP protocol. SilkPerformer Advanced Concepts 19

26 2 REMOTE AGENT CONNECTION Default Settings for Remote Agent Connection Firewall - Use SOCKS proxy server: The controller connects to the agent via a SOCKS firewall by tunneling the controller/agent communication in the SOCKS protocol. Figure 2 - Configuring Remote Connection Settings (Agent Connection Properties) Default Settings for Remote Agent Connection Figure 3 shows the connection diagram of a direct remote agent connection (i.e., no firewall is involved). Figure 3 - Connection Diagram of a Direct Remote Agent Connection In this environment, the following ports are used to connect to the remote agent: 20 SilkPerformer Advanced Concepts

27 2 REMOTE AGENT CONNECTION Default Settings for Remote Agent Connection UDP 19200: Used for the broadcast (hard-coded, does not change) TCP 19200: Initial unsecured connection to Silk Launcher Service. Accessible via the System Configuration Manager on the agent, accessible via System Settings-Agent Pool-Properties on the controller. TCP 19202: Connects to the SilkPerformer agent. 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) > 19202]. SilkPerformer Advanced Concepts 21

28 2 REMOTE AGENT CONNECTION Connecting through TCP/IP Firewalls Figure 4 - Default Agent Settings in the System Configuration Manager Figure 5 - Default Agent Connection Settings for the Controller Connecting through TCP/IP Firewalls For a SilkPerformer default installation, you only have to open the TCP ports 19200, (when using secure connections), and 19202, in the firewall. If you want to open other ports in the firewall as the SilkPerformer default connection ports, you can change the ports SilkPerformer uses to connect to remote agents. Example Port Secure Port: Ports to open on the firewall: 20000: Default connection port to Silk Launcher Service 20020: Secure connection to ACS (you only have to open this port if you want a secure connection) 20021, (20022*): Used to connect to the SilkPerformer Simulation Controller Agent and System Configuration Manager Agent. *This is only needed if you want to use the System Configuration Manager and a Simulation Controller Agent simultaneously. 22 SilkPerformer Advanced Concepts

29 2 REMOTE AGENT CONNECTION Connecting through HTTP Firewalls Connecting through HTTP Firewalls Figure 6 shows the connection diagram of a remote agent connection through an HTTP firewall. Figure 7 shows the corresponding settings in the agent's connection properties. Figure 6 - Diagram of a Remote Agent Connection through an HTTP Firewall Figure 7 - HTTP Tunneling Connection Settings for the Controller SilkPerformer Advanced Concepts 23

30 2 REMOTE AGENT CONNECTION Connecting through SOCKS Firewalls Connecting through SOCKS Firewalls Figure 8 shows the connection diagram of a remote agent connection through a SOCKS firewall. Figure 9 shows the corresponding settings in the agent's connection properties. Figure 8 - Connection Diagram of a Remote Agent Connection through a SOCKS Firewall Figure 9 - SOCKS Tunneling Connection Settings for the Controller 24 SilkPerformer Advanced Concepts

31 2 REMOTE AGENT CONNECTION Connecting through Multiple Firewalls Connecting through Multiple Firewalls You can configure a SilkPerformer 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. Figure 10 shows the connection diagram of such a scenario. Figure 11 shows the corresponding settings in the agent's connection properties. Figure 10 - Connection Diagram of a Remote Agent Connection through Multiple Firewalls Figure 11 - Multiple Firewall Connection Settings for the Controller SilkPerformer Advanced Concepts 25

32 2 REMOTE AGENT CONNECTION Connecting through Multiple Firewalls 26 SilkPerformer Advanced Concepts

33 3 Rule-Based 3Chapter Recording What you will learn This chapter contains the following sections: Section Page Overview 27 Recording Rule Files 28 General Attributes of Recording Rules 31 HTTP Parsing Rules 32 TCP/IP Protocol Rules 54 StringScriptingRule 61 HttpScriptingRule 65 ProxyEngineRule 72 Conditions 76 Troubleshooting 94 Overview This chapter explains how to configure SilkPerformer's Recorder (HTTP, TCP/ IP) using recording rule files. Note Manual scripting of recording rules, as outlined in this chapter, is not your only option for creating recording rules. SilkPerformer also enables you to create recording rules based on templates via the Recording Rules tab (System Settings/Recorder/Recording Rules) See SilkPerformer Help for full details. Recording rules allow users to configure the Recorder in a number of ways: SilkPerformer Advanced Concepts 27

34 3 RULE-BASED RECORDING Recording Rule Files 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. This chapter discusses the structure and syntax of recording rules, and offers guided recording rule file design examples. Recording rules are an advanced SilkPerformer concept. To successfully write recording rules, one requires extensive experience using SilkPerformer and a thorough understanding of the involved protocols (TCP/IP, HTTP and HTML). Recording Rule Files Recording rule files are XML-based files that contain the rules by which SilkPerformer's Recorder functions. Locating Recording Rule Files Recording rule files carry the file extension.xrl. Project specific recording rules are stored in the Documents directory of the current project. Example "C:\Program Files\Silk\SilkPerformer 2010 R2\Working\Projects\TestProj\Documents\" Global recording rule files are stored in SilkPerformer's Include directory. Example "C:\Program Files\Silk\SilkPerformer 2010 R2\Working\Include\" Formatting Recording Rule Files Recording rule files are written in XML. Recording rule files may contain any number of recording rules. The root node for all recording rule file node trees is RecordingRuleSet (see Figure 3). There are three types of recording rules: HTTP parsing rules:xml node HttpParsingRule TCP rules for WebTcpipRecvProto(Ex):XML node TcpRuleRecvProto TCP rules for WebTcpipRecvUntil:XML node TcpRuleRecvUntil 28 SilkPerformer Advanced Concepts

35 3 RULE-BASED RECORDING Recording Rule Files Writing XML Files Consider the following encoding requirements when writing XML files: Encoding Special Characters Some characters and symbols must be encoded for proper XML syntax. See the list below: Description Character XML representation Less Than < < Greater Than > > Quote " " Ampersand & & Figure 12 - Encoding Special Characters in XML Files Encoding Binary Data Binary data must be encoded in hexadecimal notation. See the examples below: Description CR, (carriage return) LF, (line feed) NULL-byte XML representation &#x00; Figure 13 - Encoding Binary Data in XML Files Recording Rule File Example Example <?xml version="1.0" encoding="utf-8"?> <RecordingRuleSet> <HttpParsingRule> <Name>Siebel Session Cookie</Name>... </HttpParsingRule> <TcpRuleRecvProto> <Name>Siebel TCP Protocol</Name>... SilkPerformer Advanced Concepts 29

36 3 RULE-BASED RECORDING Recording Rule Files </TcpRuleRecvProto> <TcpRuleRecvUntil> <Name>Telnet screen</name>... </TcpRuleRecvUntil> </RecordingRuleSet> Naming Conventions Used in This Document: XML nodes are referred to by their full path names. Example Example RecordingRuleSet\HttpParsingRule\Search\LB\RegExpr When base paths are clear, the relative paths of XML nodes are used. Search\LB\RegExpr Recording Rule Data Types Recording rule attributes come in a variety of data types. All valid data types, and associated attribute descriptions, are listed below. Strings All string values, including binary data (except NULL-Bytes), are valid. Please see Writing XML Files for information regarding specifying binary data in XML files. Binary Data All binary data, including NULL-Bytes, are valid. Please see Writing XML Files for information regarding specifying binary data in XML files. Numbers Unsigned numbers in the range of 0 thru are valid. The value is the Max unsigned number. Signed Numbers Signed numbers in the range of thru are valid. The value is the Max signed number. 30 SilkPerformer Advanced Concepts

37 3 RULE-BASED RECORDING General Attributes of Recording Rules 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 are dependent upon, and are listed along with, specific attributes. Distinct Value Lists Comma-Separated Value (CSV) lists are valid. Valid values are dependent upon, and are listed along with, specific attributes below. Structured Data Compound data types consisting of nested XML nodes are valid. General Attributes of Recording Rules All recording rule types allow users to specify both Name and Active attributes. Name Attribute Data type: Strings Default value: Unnamed Rule SilkPerformer Advanced Concepts 31

38 3 RULE-BASED RECORDING HTTP Parsing Rules This attribute specifies a name for a given recording rule. Names need not have special meaning or syntax. They may appear in recorded script comments. 3.2Active 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. HTTP Parsing Rules Introduction 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-based browser-level API Browser-level API with/without automatic page detection The Recorder does not apply HTTP parsing rules when recording HTTP traffic with the following settings: TCP/IP-level API Generate WAP script 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. 32 SilkPerformer Advanced Concepts

39 3 RULE-BASED RECORDING HTTP Parsing Rules Finding Possible Replacements Scripting Parsing Functions Details regarding both steps can be specified in HTTP parsing rules. 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. 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 To keep the two values separate, HTTP parsing rules consist of two sections named Search and ScriptGen. Basic structure of a HTTP Parsing Rule <?xml version="1.0" encoding="utf-8"?> <RecordingRuleSet> <HttpParsingRule> <Name>Example Rule</Name> <Active>true</Active> <Search>... </Search> <ScriptGen>... </ScriptGen> </HttpParsingRule> </RecordingRuleSet> The remainder of this chapter explains HTTP parsing rules through a guided example ( Guided HTTP Parsing Rule Example ) and offers a complete reference of attributes ( Section Search - Finding Rule Hits and Scripting Parsing Functions and Replacements ). Guided HTTP Parsing Rule Example This chapter steps through the process of designing a HTTP parsing rule for the sample application, ShopIt V 6.0, which ships with SilkPerformer. SilkPerformer Advanced Concepts 33

40 3 RULE-BASED RECORDING HTTP Parsing Rules Recording ShopIt V 6.0 Without Parsing Rules The SilkPerformer 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. Example WebPageUrl(sParsedUrl, "Unnamed page", SHOPITV60_ KINDOFPAYMENT_ASP002); // dclform SHOPITV60_KINDOFPAYMENT_ASP002: "choice" := "CreditCard", "price" := "69.9", "sid" := " "; Customizing ShopIt V 6.0 with TrueLog Explorer In executing a Try Script run, the hard-coded session ID causes a replay error, as shown in Figure SilkPerformer Advanced Concepts

41 3 RULE-BASED RECORDING HTTP Parsing Rules Figure 14 - Replay Error Due to Non-Customized Session ID The session handling customization feature of TrueLog Explorer solves this problem, modifying the script as shown in the following example. 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(" "Unnamed page", SHOPITV60_KINDOFPAYMENT_ASP003); dclform SHOPITV60_KINDOFPAYMENT_ASP003: "choice" := "CreditCard", "price" := "15.9", // "sid" := " "; "sid" := sformsid1; A second Try Script run reveals that the customization was successful and that the script now runs correctly. 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. SilkPerformer Advanced Concepts 35

42 3 RULE-BASED RECORDING HTTP Parsing Rules 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 Figure 8 and the following example. Figure 15 - Locating ShopIt V 6.0 Session ID using TrueLog Explorer Example <script LANGUAGE="JavaScript"> function doprocess(mylink) { scheme=" server="u2"; serverport=""; path="/shopitv60/"; file="kindofpayment.asp?"; name=" "; price="15.9"; choice="creditcard"; 36 SilkPerformer Advanced Concepts

43 3 RULE-BASED RECORDING HTTP Parsing Rules 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. Example <?xml version="1.0" encoding="utf-8"?> <RecordingRuleSet> <HttpParsingRule> <Name>ShopIt V6.0 Session Id</Name> <Search> <SearchIn>Body</SearchIn> <LB> <Str>name="</Str> </LB> <RB> <Str>"</Str> </RB> </Search> <ScriptGen> <VarName>ShopItSessionId</VarName> </ScriptGen> </HttpParsingRule> </RecordingRuleSet> This rule file may be saved to the Include directory of SilkPerformer-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 SilkPerformer 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 """. SilkPerformer Advanced Concepts 37

44 3 RULE-BASED RECORDING HTTP Parsing Rules 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. Try the Recording Rule When the rule is used in a recording session, the result is a recorded script with lots of variables. Script Recorded using a Simple Rule var gsshopitsessionid : string; // Confirm-Button gsshopitsessionid_001 : string; // 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 := " ", 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. 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. 38 SilkPerformer Advanced Concepts

45 3 RULE-BASED RECORDING HTTP Parsing Rules Limit The Number of Rule Hits 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. A more specific rule can be created based on the unique characteristics of ShopIt V 6.0 Session ID's. 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, as shown in Figure 12. Limit 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="</Str> </LB> <RB> <Str>"</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 don't match this regular expression are dropped. The regular expression in the example above specifies that only rule hits consisting of digits are relevant. SilkPerformer Advanced Concepts 39

46 3 RULE-BASED RECORDING HTTP Parsing Rules 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; // dclform SHOPITV60_KINDOFPAYMENT_ASP003: "choice" := "CreditCard", "price" := "15.9", "sid" := gsshopitsessionid; // value: " " MYFORM004: "address" := "a", // changed "city" := "b", // changed "state" := "c", // changed "zip" := "" <SUPPRESS>, // value: "" "ZipCode" := "d", // added "cardtype" := "Visa", // added "cardnumber" := " ", // changed "expiration" := "07.04", // changed "sid" := "" <USE_HTML_VAL> ;//value:" " Specify Allowed Usage of Rule Hits Be More Specific in Script Generation 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. <?xml version="1.0" encoding="utf-8"?> <RecordingRuleSet> <HttpParsingRule> <Name>ShopIt V6.0 Session Id</Name> <Search> <SearchIn>Body</SearchIn> <LB> <Str>name="</Str> </LB> <RB> 40 SilkPerformer Advanced Concepts

47 3 RULE-BASED RECORDING HTTP Parsing Rules <Str>"</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 ( Specify Allowed Usage of Rule Hits ). 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 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. SilkPerformer Advanced Concepts 41

48 3 RULE-BASED RECORDING HTTP Parsing Rules Applying Regular Expressions 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. 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. Please see SilkPerformer's online help for a description of regular expressions and how to define tagged sub-expressions. LB\Str Attribute Type: Binary Data Default: (empty) 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="</Str> </LB> 42 SilkPerformer Advanced Concepts

49 3 RULE-BASED RECORDING HTTP Parsing Rules <LB> <Str>BV_EngineID=</Str> </LB> LB\RegExpr Attribute Type: Strings Default: (empty) 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. Example <LB> <RegExpr>name *= *["']</RegExpr> </LB> LB\Offset Attribute Type: Signed Numbers Default: (empty) 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> RB\Str Attribute Example <RB> Type: Binary Data Default: (empty) 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. SilkPerformer Advanced Concepts 43

50 3 RULE-BASED RECORDING HTTP Parsing Rules <Str>"</Str> </RB> RB\CharType Attribute Type: Distinct Value Lists Default: (empty) 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> RB\RegExpr Attribute Type: Strings Default: (empty) 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. 44 SilkPerformer Advanced Concepts

51 3 RULE-BASED RECORDING HTTP Parsing Rules Example <RB> <RegExpr>["' *value]</regexpr> </RB> RB\Length Attribute Type: Signed Numbers Default: (empty) 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> RegExpr and RegExprTag Attribute Types: Strings, Numbers Default: (empty), 0 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. Please see SilkPerformer's online help for a description of regular expressions and information on defining tagged sub-expressions. Example <RegExpr>name="\([0-9]+\)"<RegExpr> <RegExprTag>1<RegExprTag> SearchIn Attribute Type: Distinct Value Lists Default: All SilkPerformer Advanced Concepts 45

52 3 RULE-BASED RECORDING HTTP Parsing Rules Allowed values are: All Header Body This is an abbreviation for the complete list of other values Search HTTP response headers Search HTTP response bodies This attribute specifies where to search for rule hits, either in response headers, response bodies, or both. Example <SearchIn>Body</SearchIn> <SearchIn>Header</SearchIn> CaseSensitive Attribute Type: Boolean Values Default: false 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. IgnoreWhiteSpaces Attribute Type: Boolean Values Default: true 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. CondContentType Attribute Type: Strings Default: (empty) 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> 46 SilkPerformer Advanced Concepts

53 3 RULE-BASED RECORDING HTTP Parsing Rules This restricts the searching for rule hits to server responses with a content type such as "text/html" or "text/plain." CondRegExpr Attribute Type: Strings Default: (empty) 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> CondResultLen Attribute Type: Numeric Ranges Default: 2- 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. Conditions Attribute Type: Structured Data 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 Condition Evaluation Environment for more information regarding what may be subject to conditions. SilkPerformer Advanced Concepts 47

54 3 RULE-BASED RECORDING HTTP Parsing Rules 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. Introduction 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 Type: Strings Default: (empty) 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. OnlyIfCompleteResult Attribute Type: Boolean Values Default: false 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. MaxLbLen Attribute Type: Numbers Default: Max unsigned 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. ReplaceIn Attribute Type: Distinct Value Lists Default: All 48 SilkPerformer Advanced Concepts

55 3 RULE-BASED RECORDING HTTP Parsing Rules This attribute specifies script locations that may contain hits to be replaced. Valid values are: All Url LinkName FormName PostedData FormFieldName FormFieldValue SetCookie This is an abbreviation for the complete list of other values Replace in URL parameters (various functions, e.g. WebPageUrl) Replace in link names (function WebPageLink). Link names that result from WebPageParseUrl are not replaced. Replace in form names (function WebPageSubmit) Replace in binary posted data (various functions, e.g. WebPagePost) Form field name in the dclform section of the script Form field value in the dclform section of the script Parameter of the function WebCookieSet AlwaysNewFunc Attribute Type: Boolean Values Default: false 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. CommentToVar Attribute Type: Boolean Values Default: true 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. CommentToFunc Attribute Type: Boolean Values Default: false 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. SilkPerformer Advanced Concepts 49

56 3 RULE-BASED RECORDING HTTP Parsing Rules GenBytesReadVar Attribute Type: Boolean Values Default: false This attribute specifies whether or not to generate a variable for the number of bytes parsed by a parsing function (see SilkPerformer's online help for the function WebParseDataBoundEx, parameter nbytesparsed). GenDebugPrint Attribute Type: Boolean Values Default: false 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 SilkPerformer's controller output window is scripted. Conditions Attribute Type: Structured Data This attribute specifies conditions that are applied to determine whether or not a rule hit within a string being scripted should actually be replaced. The conditions are evaluated within an environment that allows access to the HTTP request/response that is currently being scripted. If the conditions do not lead to a result of true, no replacement or parsing functions are scripted. See Conditions for more information regarding conditions. See section Condition Evaluation Environment for more information regarding what may be subject to conditions. Tokenizing of Rule Hits The Search section used both in HttpParsingRules and StringScriptingRules contains a new feature that allows to extract rule hits by tokenizing the search result. The idea is that each substring extracted (e.g. 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. 50 SilkPerformer Advanced Concepts

57 3 RULE-BASED RECORDING HTTP Parsing Rules 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 Example for SiebelTokenApplet The search result ["TestName","TestSite","USD","02/21/2003","N","1-2T"] will be tokenized and results in the following rule hits: TestName TestSite USD 02/21/2003 N 1-2T The search result 19*02/21/ :20:176*SADMIN4*Note5*1-1P5 will be tokenized and results in the following rule hits: 02/21/ :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. Example 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> SilkPerformer Advanced Concepts 51

58 3 RULE-BASED RECORDING HTTP Parsing Rules Example </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/ :20:176*SADMIN4*Note5*1-1P5 //... //... dclform //... WebParseDataBoundEx(gsRowValArray_003, sizeof(gsrowvalarray_003), "ValueArray`", WEB_OCCURENCE_LAST, "`", WEB_FLAG_IGNORE_WHITE_SPACE, 1); WebPageForm(" SALES_ENU_START_SWE026, "Account Note Applet: InvokeMethod: NewRecord"); Print("Parsed \"RowValArray_003\", result: \"" + gsrowvalarray_003 + "\""); // Was "0*19*02/21/ :20:176*SADMIN4*Note5*1-1P5" when recording 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/ :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: " " 52 SilkPerformer Advanced Concepts

59 3 RULE-BASED RECORDING HTTP Parsing Rules Section ScriptGen There are new options in the ScriptGen section. MinRbLen, MinLbLen 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. Type: Numbers Default: 1 LastOccurence 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. Type: Boolean Values Default: false 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. Example Instead of "SomeText" + gsparsedvalue + "some other text" the recorder will generate "SomeText" + bin(gsparsedvalue) + "some other text" Default: false New Script Locations HTTP parsing rules, as well as StringScriptingRules, are now also applied for the parameters of the function WebHeaderAdd. Therefore, there are two new script locations allowed in the ReplaceIn tag of a HttpParsingRule and in the SearchIn tag of a StringScriptingRule: HeaderName Refers to the 1st parameter of the function WebHeaderAdd. SilkPerformer Advanced Concepts 53

60 3 RULE-BASED RECORDING TCP/IP Protocol Rules HeaderValue Refers to the 2nd parameter of the function WebHeaderAdd. TCP/IP Protocol Rules Introduction 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 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. 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> 54 SilkPerformer Advanced Concepts

61 3 RULE-BASED RECORDING TCP/IP Protocol Rules </Identify> <Conditions> </Conditions> </TcpRuleRecvProto> <TcpRuleRecvUntil> <Name>Sample TCP RecvUntil Rule</Name> <Active>true</Active> <Identify> </Identify> <Conditions> </Conditions> </TcpRuleRecvUntil> 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 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). SilkPerformer Advanced Concepts 55

62 3 RULE-BASED RECORDING TCP/IP Protocol Rules Identify\LengthLen Attribute 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). Identify\OptionFlags Attribute 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). See SilkPerformer's online help for a description of these option flags. The empty default value means: big endian. Valid values are: LittleEndian ProtoIncluded Option TCP_FLAG_LITTLE_ENDIAN Option TCP_FLAG_INCLUDE_PROTO Identify\LengthFactor Attribute 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. Identify\LengthAdd Attribute 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. 56 SilkPerformer Advanced Concepts

63 3 RULE-BASED RECORDING TCP/IP Protocol Rules 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. GenVerify Attribute Of Conditions 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. 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, "\h " // "\h c c " // "\h c " // X "\h ", 52); // WebTcpipRecvExact(hWeb0, NULL, 40); Server responses can be analyzed with the help of TrueLog Explorer. SilkPerformer Advanced Concepts 57

64 3 RULE-BASED RECORDING TCP/IP Protocol Rules Figure 16 - Analyzing Server Responses with 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, "\h " // "\h c c " // "\h f c " // X "\h ", 52); // 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. 58 SilkPerformer Advanced Concepts

65 3 RULE-BASED RECORDING 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 Type: Binary Data Default: (empty) This attribute specifies the terminating byte sequence of the protocol. Identify\IgnoreWhiteSpaces Attribute 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. 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. 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); SilkPerformer Advanced Concepts 59

66 3 RULE-BASED RECORDING TCP/IP Protocol Rules WebTcpipRecvExact(hWeb0, NULL, 1220); TrueLog Explorer is used to analyze server responses. Each server response ends with a command prompt such as shown in Figure 17. Figure 17 - Server Response in a Telnet Session 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. 60 SilkPerformer Advanced Concepts

67 3 RULE-BASED RECORDING StringScriptingRule 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. 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 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). Example <StringScriptingRule> <Name>Replace TimeStamp</Name> <Active>true</Active> <Search> <SearchIn>FormFieldValue</SearchIn> SilkPerformer Advanced Concepts 61

68 3 RULE-BASED RECORDING StringScriptingRule <LB> <Offset>0</Offset> </LB> <RB> <Length>0</Length> </RB> </Search> <ScriptGen> <Action>CheckTimeStamp</Action> </ScriptGen> </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. Example <StringScriptingRule> <Name>SiebelParam Function Call</Name> <Active>true</Active> <Search> <SearchIn>FormFieldValue</SearchIn> <Special>SiebelParam</Special> <Conditions> 62 SilkPerformer Advanced Concepts

69 3 RULE-BASED RECORDING StringScriptingRule </Conditions> </Search> <ScriptGen> <Action>CheckSiebelParam</Action> </ScriptGen> </StringScriptingRule> Section ScriptGen The section ScriptGen of a StringScriptingRule is different from the section ScriptGen of a HttpParsingRule. The following attributes are allowed. CreateVariable CheckTimeStamp CheckSiebelParam DecodeSiebelJavaScri ptstring CheckSiebelDateTime Attribute Action This attribute specifies which action should be taken for the substring identified by the Search section. The following values are allowed: 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. This will create the function call GetTimeStamp() instead of the original string, if the original string indeed looks like a plausible timestamp value. 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") 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. 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. SilkPerformer Advanced Concepts 63

70 3 RULE-BASED RECORDING StringScriptingRule CheckSiebelDate CheckSiebelTime CheckSiebelPhone The same as CheckSiebelDateTime, but for dates only. Records the wrapper function SiebelDate. The same as CheckSiebelDateTime, but for times only. Records the wrapper function SiebelTime. 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> Attributes VarName, VarNamePrefix, IsExternalVar These attributes are only applicable if the Action attribute is CreateVariable. This allows to specifiy eiter a variable name (attribute VarName) or a prefix for the variable name (attribute VarNamePrefix). In the latter case, the actual 64 SilkPerformer Advanced Concepts

71 3 RULE-BASED RECORDING HttpScriptingRule 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. 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 The basic structure of a HttpScriptingRule is quite simple. The only tag allowed, additional to the commen 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. Example <HttpScriptingRule> <Name>Suppress some cookie</name> <Active>true</Active> <Action>SuppressCookie</Action> <Conditions>... </Conditions> </HttpScriptingRule> 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. SilkPerformer Advanced Concepts 65

72 3 RULE-BASED RECORDING HttpScriptingRule Example Example Example 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> 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> 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> 66 SilkPerformer Advanced Concepts

73 3 RULE-BASED RECORDING HttpScriptingRule <FindData> <ApplyTo>Http.Initial.Request.Url.QueryData</ ApplyTo> <Data>sid=</Data> </FindData> </Conditions> </HttpScriptingRule> NoDynUrlParsing, ForceDynUrlParsing These Actions of a HttpScriptingRule can be used to override the setting "Dynamic URL parsing" from the profile settings for individual HTTP requests. Example NoUrlEncoded, ForceUrlEncoded With HTTP POST requests, the recorder needs to decide if the request body should be scripted as a form in the dclform section or if it is better to use a *Bin function (WebPagePostBin and friends) instead. These Actions can be used to override the default decision of the recorder. By default, the recorder looks at the content-type request header. The recorder will script a form in the dclform section if the content-type is application/x-wwwform-urlencoded and will script a *Bin function otherwise. This can be used to get better recording results for ill-behaved applications. A common example are applications which send XML data with a POST request, but incorrectly send the content-type header application/x-www-formurlencoded. The following rule is an example for handling this case. <HttpScriptingRule> <Name>Suppress XML to form conversion</name> <Active>true</Active> <Action>NoUrlEncoded</Action> <Conditions> <CompareData> <ApplyTo>Http.Initial.Request.Body</ApplyTo> <Data><?xml</Data> </CompareData> </Conditions> </HttpScriptingRule> 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. SilkPerformer Advanced Concepts 67

74 3 RULE-BASED RECORDING HttpScriptingRule 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. Example <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> 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. Example 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> 68 SilkPerformer Advanced Concepts

75 3 RULE-BASED RECORDING HttpScriptingRule <Active>true</Active> <Action>SuppressCookie</Action> <Conditions> <CompareData> <ApplyTo>Cookie</ApplyTo> <Data>PS_TOKENEXPIRE</Data> </CompareData> </Conditions> </HttpScriptingRule> Example 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 e.g. 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> 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, e.g. in a BDH file, for the script to be compileable) instead of the original function. Such a wrapper SilkPerformer Advanced Concepts 69

76 3 RULE-BASED RECORDING HttpScriptingRule Example 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> 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. 70 SilkPerformer Advanced Concepts

77 3 RULE-BASED RECORDING HttpScriptingRule Example <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; SilkPerformer allows the tag Location with the following values: TInit TMainBegin TMainEnd 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 (e.g. 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. SuppressRecording This Action can be used to suppress the recording of individual HTTP requests. It is used by SilkPerformer s Oracle Forms support to suppress the recording of SilkPerformer Advanced Concepts 71

78 3 RULE-BASED RECORDING ProxyEngineRule HTTP requests which come from an Oracle Forms applet which is recorded at a different API level. 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. Example 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, e.g. 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. NoQueryToForm, ForceQueryToForm These Actions can be used to override the profile setting "Convert URL query strings to forms" on a per HTTP request basis. ProxyEngineRule The rule type ProxyEngineRule allows to control some aspects of the ProxyEngine's operation. 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. Example <ProxyEngineRule> <Name>Switch on GUI recording for Jacada</Name> <Active>true</Active> <Action>AddAppletParam</Action> 72 SilkPerformer Advanced Concepts

79 3 RULE-BASED RECORDING ProxyEngineRule <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> ProxyEngineRule Actions 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. 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. SilkPerformer Advanced Concepts 73

80 3 RULE-BASED RECORDING ProxyEngineRule The conditions can access the name and value of the applet parameter by "Param.Name" and "Param.Value". Example <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> 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 DontModifyRequestHeader, DontModifyResponseHeader The recorder routinely modifies some request/response headers of HTTP traffic to ensure best recording results with common browsers. However, some not so common user agents may misbehave when recorded. 74 SilkPerformer Advanced Concepts

81 3 RULE-BASED RECORDING ProxyEngineRule Example These Actions allow to suppress the modification of request/response HTTP headers for individual requests, and thus allow to solve such recording problems. Conditions can reference the header name and value which are subject to be modified in the ApplyTo tag with the values HeaderName, respectively HeaderValue. This example is from the Flash Remoting 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> 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 supress detecting HTTP in such cases. The conditions can assess the following pieces of information in the ApplyTo tag: SilkPerformer Advanced Concepts 75

82 3 RULE-BASED RECORDING Conditions PeekData The first chunk of data sent by the client. 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 Compound Conditions Complex conditions can be created using Boolean operators And, Or and Not. Example <And> <Or> <SomeBasicCondition> <SomeBasicCondition> <Not> <SomeBasicCondition> </Not> </Or> <Not> <And> <SomeBasicCondition> </And> </Not> </And> <SomeBasicCondition> </SomeBasicCondition> </SomeBasicCondition> </SomeBasicCondition> </SomeBasicCondition> </SomeBasicCondition> 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. 76 SilkPerformer Advanced Concepts

83 3 RULE-BASED RECORDING Conditions 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. 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 SilkPerformer Advanced Concepts 77

84 3 RULE-BASED RECORDING Conditions IfNull UseDataAvail The basic idea is: 1 ApplyTo specifies a block of data (e.g., a request URL, a response body, the string to be scripted, etc.). 2 Offset and Length are optionally used to target data subsets. ApplyTo Type: Strings Default: Self 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. See section Condition Evaluation Environment for details. Literal Additional ApplyTo values 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. Example: <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 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 (see Access to special strings ), there are four new possibilities: CustomUrlName The current name of a custom URL, if used in a function WebPageLink, WebPageSetActionUrl or WebPageQueryParsedUrl. 78 SilkPerformer Advanced Concepts

85 3 RULE-BASED RECORDING Conditions PostedData HeaderName HeaderValue 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). 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 (see Access to HTTP request/response pairs for detailed information). Encoding Specifies the encoding to be scripted (e.g. ENCODE_BLANKS) Examples: <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. SilkPerformer Advanced Concepts 79

86 3 RULE-BASED RECORDING Conditions Encoding means one of the following: "ENCODE_FORM" etc. (see online help for encodings). Usage means one of the following: "SUPPRESS", "USE_HTML_VAL", "USE_SCRIPT_VAL". Examples: <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> First, Offset is applied: Second, Length is applied: Offset, Length Type: Signed Numbers Default value: 0 Offset and Length can be used to target subsets of data referenced with ApplyTo. 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. 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. Example 1: Example 2: Offset and Length calculations may not be possible, or may be only partially possible. ApplyTo returns 30 Bytes of data, Offset specifies "40" => Offset calculation is not possible. In this case the resulting data has the value Null. 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." 80 SilkPerformer Advanced Concepts

87 3 RULE-BASED RECORDING Conditions 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. UseDataAvail Type: Boolean Values Default value: true 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. IfNull Type: Extended Boolean Values Default value: unknown This attribute specifies the return value of the condition if there is no data to operate on (i.e., if calculations with ApplyTo, Offset, Length and UseDataAvail return Null). 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 Type: Strings This attribute causes the data to be saved and specifies the name of the temporary variable to which the data is saved to. SilkPerformer Advanced Concepts 81

88 3 RULE-BASED RECORDING Conditions SaveIfTrue, SaveIfUnknown, SaveIfFalse Type: Boolean Values These attributes specify if the data should be saved in case the result of the condition is true, unknown or false. Default Values: SaveIfTrue: true SaveIfUnknown: false SaveIfFalse: false SaveMode Type: Distinct Values Default value: IfNew 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. PrependSeparator 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. SaveTag Type: Numbers Default value: 0 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. Only the portion of the entire data that corresponds to the tagged sub-expression is saved. 82 SilkPerformer Advanced Concepts

89 3 RULE-BASED RECORDING Conditions SaveWhat Type: Distinct Values Default value: Self 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. complete data specified by ApplyTo - Left - data extracted by the condition - Right - 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:\([^<]+\)<</Data> <SaveAs>Instructions</SaveAs> <SaveTag>1</SaveTag> </RegExpr> <FindData> <ApplyTo>Instructions</ApplyTo> <Data>Download</Data> </FindData> </Conditions> 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 HttpParsingRule, TcpRuleRecvProto and TcpRuleRecvUntil rule types can reference the strings All, Self, Left, Right and Rest. SilkPerformer Advanced Concepts 83

90 3 RULE-BASED RECORDING Conditions Figure 18 - Common Condition Environment Configuration 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> Access to HTTP request/response pairs Conditions used within HttpParsingRule rules can access details of HTTP requests / responses with the ApplyTo property. Syntax: "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. 84 SilkPerformer Advanced Concepts

91 3 RULE-BASED RECORDING Conditions 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 SilkPerformer Advanced Concepts 85

92 3 RULE-BASED RECORDING Conditions 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> 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 CompareData. Data Attribute Type: Binary Data Default: (empty) The Data attribute specifies what data is to be compared to the data referenced by ApplyTo, Offset and Length. CaseSensitive Attribute Type: Boolean Values 86 SilkPerformer Advanced Concepts

93 3 RULE-BASED RECORDING Conditions Default: false 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> 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) 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 Specifies whether to search for the data in case-sensitive or case-insensitive format. SilkPerformer Advanced Concepts 87

94 3 RULE-BASED RECORDING Conditions IgnoreWhiteSpaces Attribute Type: Boolean Values Default: false 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> 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. See SilkPerformer's online help for a syntax description of regular expressions. Data Attribute Type: Binary Data Default: (empty) 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 Specifies if the regular expression must match the complete data or if any substring matching the regular expression is sufficient. 88 SilkPerformer Advanced Concepts

95 3 RULE-BASED RECORDING Conditions Allowed values are: Any Complete Matching any substring is sufficient. 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><html>.*&lt/html></Data> </RegExpr> 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: - Specifies the allowed range for the numeric value. Convert Attribute Type: Distinct Values Default: Length Specifies how to convert the data (obtained through the properties ApplyTo, Offset, Length, and UseDataAvail) into a number. SilkPerformer Advanced Concepts 89

96 3 RULE-BASED RECORDING Conditions Allowed values are: Length (default): Parse: LittleEndian: BigEndian: The data is converted to a number by measuring the length (number of bytes) of the data. 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. 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. 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> </Range> <Convert>Parse</Convert> </CheckRange> 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 isn't specified in the Range attribute, but directly within the ResultLen - tag. Example <ResultLen>5-15</ResultLen> NoBlockSplit Condition The NoBlockSplit condition is only applicable within TcpRuleRecvProto and TcpRuleRecvUntil rules. 90 SilkPerformer Advanced Concepts

97 3 RULE-BASED RECORDING Conditions 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. Examples <NoBlockSplit></NoBlockSplit> <NoBlockSplit> <ApplyTo>Left<ApplyTo> </NoBlockSplit> Scripting Condition The Scripting condition doesn't operate on specific data, therefore the attributes ApplyTo, Offset, Length, UseDataAvail and IfNull aren't available. Attribute Type: Distinct Value Lists Default: All The attribute value is specified directly within the Scripting tag, not within a sub node of the condition. SilkPerformer Advanced Concepts 91

98 3 RULE-BASED RECORDING Conditions Allowed values are: All Url LinkName FormName PostedData FormFieldName FormFieldValue SetCookie An abbreviation for the complete list of other values Scripting any URL parameter Scripting a link name of WebPageLink Scripting a form name of WebPageSubmit Scripting binary posted data (e.g., WebPagePost) Scripting a form field name in the dclform section Scripting a form field value in the dclform section 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> 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 tag of conditions. 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> 92 SilkPerformer Advanced Concepts

99 3 RULE-BASED RECORDING Conditions Loop Condition Example 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. This example is taken from the FlashRemoting 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="\([^"]*\)</Data> <SaveAs>operation</SaveAs> <SaveMode>Replace</SaveMode> <SaveTag>1</SaveTag> </RegExpr> <RegExpr> <ApplyTo>RestOfBody</ApplyTo> <Data>operation="\([^"]*\)</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> SilkPerformer Advanced Concepts 93

100 3 RULE-BASED RECORDING Troubleshooting <Exists> <ApplyTo>operation</ApplyTo> <SaveAs>OperationList</SaveAs> <SaveMode>Append</SaveMode> </Exists> </Loop> <Exists> <ApplyTo>OperationList</ApplyTo> <SaveAs>PageName</SaveAs> <SaveMode>Replace</SaveMode> </Exists> </Conditions> Troubleshooting This chapter offers some recommendations for troubleshooting recording rules that don't operate as expected. The Recorder outputs diagnostic information to the "Log" tab window, as shown in Figure 19. 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). Figure 19 - Diagnostic Output of the Recorder If a rule file doesn't appear in this diagnostic output, check the following: 94 SilkPerformer Advanced Concepts

101 3 RULE-BASED RECORDING Troubleshooting Is the rule file in the Documents directory of the current project or the Include directory of SilkPerformer? Does the file have the extension ".xrl"? Ensure that the setting "Hide file extensions for known file types" is not checked in the "Folder Options" Windows Explorer settings dialog box, as shown in Figure 20. Otherwise windows may show a file name such as "Rule.xrl" when the file name is actually "Rule.xrl.txt". SilkPerformer Advanced Concepts 95

102 3 RULE-BASED RECORDING Troubleshooting Figure 20 - Windows Explorer Folder Options 96 SilkPerformer Advanced Concepts

103 4 Web 4Chapter Context Management What you will learn This chapter contains the following sections: Section Page Overview 97 The Basics 98 SilkPerformer's Page-level API 99 How the Recorder Loses Context 105 Advanced Context Management Techniques in SilkPerformer's Page-level API 108 When to change record settings 120 Limitations 123 Overview This chapter explains the concepts that facilitate advanced context management (i.e, state information management in SilkPerformer). It begins by introducing the benefits of automatic context management in Web load testing. The techniques used by Web applications to transfer context information between browsers and Web/application servers are then explained. The chapter continues with an exploration of the techniques used by SilkPerformer's Web API to facilitate automatic context management. Finally an explanation of how to optimally configure SilkPerformer's Web recorder to generate scripts that automatically maintain state information is offered. This chapter explains how to: Configure the Web recorder for quality recording results specific to the Web application under test SilkPerformer Advanced Concepts 97

104 4 WEB CONTEXT MANAGEMENT The Basics Understand and interpret recorded scripts Gain the benefits of automatic context management as a load testing QA engineer Troubleshoot when automatic context management fails This chapter assumes that the reader has some basic knowledge of important Web technologies: HTTP: URL's, header/body, request/response, cookies, redirections, and status codes HTML: Frames, links, and forms JavaScript The Basics The Value of Context Management 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 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 - be they on the same TCP/IP connection or on another connection - don't bear any relationship to one another. Web applications on the other hand have become increasingly complex and 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 (shopping cart, registered customer, etc.) 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 are meaningless. Therefore load testing tools must be able to handle all of the techniques that browsers use to maintain state information. 98 SilkPerformer Advanced Concepts

105 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API When Load Testing Tools Don't Maintain State Information Results may be invalid Poor context management can result in load testing scripts in which - amongst other problems - each virtual user logs in to the same session, uses the same account, or uses the same shopping cart. In such cases, the load impact on the Web/application server will be quite different from a comparable load that might be experienced by a live application - and therefore the test results will be meaningless. Errors go unnoticed Web servers often don't 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 (e.g., "server overloaded," "session timed out," etc). If the next instruction in the script doesn't refer to previous results (e.g., 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't 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 tremendous 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 load testing costs. SilkPerformer's Page-level API To take advantage of SilkPerformer's advanced context management techniques, you must use the high level page-based browser-level API - also referred to as page-level API - instead of the lower level browser-level API. This is the default SilkPerformer Advanced Concepts 99

106 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API option if you select the Web business transaction project type in the Outline project dialog. Figure 21 - Project settings for SilkPerformer's page-level API Basic Concepts The basic idea behind the page-level API is to describe the user's actions at a higher level of abstraction. 100 SilkPerformer Advanced Concepts

107 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API Page-level API vs. browser-level API Low-level browser-level API describes network interactions in terms of single HTTP requests. For single Web pages, browsers typically send numerous HTTP requests to servers. Browser-level scripts therefore tend to be rather long, with each single function containing a parameter that specifies an URL from which to download. This makes browser-level scripts unsuitable for automatic context management. Browser-level scripts can also be difficult to read because they don't describe actions from the user's perspective. In contrast, high-level "page-level API" is designed to describe 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 browser-level API is that it incorporates a 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 SilkPerformer virtual user can be limited to manage system resources (the default is "5"). Note however that this limit doesn't 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" by the WebPageStoreContext function. While the page will still be dropped from the history if necessary, it won't be deleted from memory and 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. SilkPerformer Advanced Concepts 101

108 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API Context-less vs. Context-full The terms "context-less" and "context-full" are also used when referring to advanced context management. Context-less functions Context-less functions don't refer to previous events or results during script execution. Therefore they work without requiring information from previous events. This means that for context-less function calls, all information that's required to perform functions must be specified in scripts. Scripting and recording of context-less functions is therefore the reason of session or other dynamic information in scripts. A typical feature of context-less functions is that they include parameters that specify URL's for download. Context-less functions in SilkPerformer's page-level API include: WebPageUrl WebPageForm WebPagePost, WebPagePostFile WebPageCustomRequest, WebPageCustomRequestBin, WebPageCustomRequestFile If any of these functions uses a form from the "dclform" section of a script, the form will be used context-less. This is because there isn't a corresponding HTML form from which unchanged (e.g., hidden) values can be taken. All form values must be specified in the script. 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 doesn't incorporate dynamic data. Context-full functions in SilkPerformer's page-level API include: WebPageLink WebPageSubmit WebPageSubmitBin WebPageLink The WebPageLink function downloads the target URL of a link. Example HTML code: <a href= Account</a> 102 SilkPerformer Advanced Concepts

109 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API WebPageSubmit Example HTML code: This link contains load balancing information ("www4") and a session id ("5423") in the target URL. Assume the user clicks this link. This could be modeled in BDL using the WebPageUrl function: WebPageUrl(" account"); The problem with this is that the dynamic components of the URL are hard coded in the script. Alternately, the WebPageLink function could be used: WebPageLink("Edit Account"); This solution is better because SilkPerformer's replay engine will, using its HTML parser, use the actual URL that's associated with the link name "Edit Account" during replay. While it's still possible that a link name will change dynamically, it's 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="@@@@ @@@@"> <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 could be modeled in BDL using the context-less WebPageForm function with a corresponding form definition: WebPageForm(" FORM_BASKET_1);... dclform FORM_BASKET_1: "quantity" := "3", "BV_SessionID" := "@@@@ @@@@", "BV_EngineID" := "dadccfjhgjehbemgcfkmcfifdnf.0"; SilkPerformer Advanced Concepts 103

110 4 WEB CONTEXT MANAGEMENT SilkPerformer's Page-level API The problem with this solution is that everything is hard coded in 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 a HTML form from a previous server response by name. SilkPerformer's 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 need not be specified in the script. Form Definitions in BDL In SilkPerformer, the syntax of form definitions in BDL scripts has been enhanced so that it's now possible to specify whether individual fields should use values included in scripts, from HTML code, or be suppressed (i.e., not send anything). Such specification is achieved via a new syntactical element called form attributes. Please refer to SilkPerformer's online help for a detailed syntax description. Form attributes are also used to specify encoding types for form fields, see Form Data Encoding for details. For forms that are used context-fully (i.e., with the WebPageSubmit function), the following so-called 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 therefore should be 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 a 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. 104 SilkPerformer Advanced Concepts

111 4 WEB CONTEXT MANAGEMENT How the Recorder Loses Context How the Recorder Loses Context When one says that the recorder "loses context" it means that the recorder observes an HTTP request that can't be interpreted as an embedded object, a frame, a link, or a form submission. The following section discusses scenarios that can lead to loss of context in the absence of the advanced context management techniques such as those introduced in SilkPerformer. 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 (e.g., HTTP status code "302 Document moved" for redirections). Example HTML code: Example <html> <title>login</title> <META http-equiv=refresh content="0; URL= 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. SilkPerformer's replay engine doesn't 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 SilkPerformer's 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= login.html"> </head> <body onload="location=' login.html'> </body> </html> SilkPerformer Advanced Concepts 105

112 4 WEB CONTEXT MANAGEMENT How the Recorder Loses Context 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 SilkPerformer's replay engine automatically downloaded the URL specified in the "meta" tag, it would be behavior different from any modern browser, and therefore inaccurate. JavaScript JavaScript gives Web developers countless options for doing things that can't be achieved through HTML techniques, and therefore can't be simulated with SilkPerformer's replay engine by simply parsing HTML. This makes JavaScript a leading cause of context loss. HTTP requests that result from JavaScript actions often can't be described in terms of WebPageLink or WebPageSubmit functions, therefore the recorder has to generate context-less functions. This chapter offers some examples, but is by no means a complete listing of scenarios that may be encountered. JavaScript redirection/reload Example HTML code: <html> <head> <title>login</title> </head> <body onload="location=' login.asp'"> </body> </html> This example demonstrates how JavaScript can be used to redirect to another URL, thereby introducing state information (load balancing, session Ids, etc). Embedded objects loaded by JavaScript Example HTML code: <html> <head> <title>login</title> </head> <body onload="preloadimages('right_arrow.gif', 'left_ arrow.gif', 'up_arrow.gif', 'down_arrow.gif')"> </body> </html> This example shows how JavaScript can be used to load embedded objects. SilkPerformer's HTML parser however doesn't see these URL's as embedded 106 SilkPerformer Advanced Concepts

113 4 WEB CONTEXT MANAGEMENT How the Recorder Loses Context objects, so the recorder has to generate a script function, otherwise the images wouldn't be downloaded by the replay engine. Note also that the URL's of these embedded objects are specified relatively. The browser resolves these relative URL's to absolute URL's using the base URL of the HTML document that contains them. So resulting URL's may well contain dynamic information, e.g., " arrow.gif". Dynamic HTML The document.write( ) JavaScript function allows you to dynamically change HTML code on the client side. Ad servers commonly use this technique, though its use is not limited to ad servers. Example HTML code: document.write('<script language=javascript src=" + escape(date) + '"></scr'+'ipt>'); Form submission 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; SilkPerformer Advanced Concepts 107

114 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API } document.tabform.submit(); This example demonstrates how JavaScript can submit a form. The form definition in HTML is just a template that's manipulated by JavaScript before it's 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". Example HTML code (modified action URL): 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="@@@@ @@@@"> </form> <a href="javascript:submitsearch(' search.asp')"> Search this site</a> <a href="javascript:submitsearch(' search.asp')"> Search mirror site</a> This example demonstrates how JavaScript can be used to change the action URL of a form. Advanced Context Management Techniques in SilkPerformer's Page-level API Now that the challenges of context management have been explained in the previous chapter, let's explore approaches to dealing with these challenges. The good news is that SilkPerformer's page-level API incorporates advanced techniques that allow the writing of context-full scripts that automatically deal with context management issues. Even better, SilkPerformer's recorder handles this work for you. The purpose of this chapter is to explain the features that are offered by the page-level API and show how they are used by the recorder to generate contextfull scripts that don't require manual customization for context management. 108 SilkPerformer Advanced Concepts

115 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API This chapter makes frequent reference to the "Advanced Context Management Settings" dialog. You'll find this dialog as illustrated in Figure 22: Figure 22 - "Advanced Context Management Settings" Dialog 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 aren't covered by SilkPerformer's HTML parser (see Embedded objects loaded by JavaScript ). While the WebPageAddUrl function isn't new to SilkPerformer's page-level API, improvements have been made to it that facilitate better context management and more readable scripts. The main new feature is that the URL to download can be specified relative to the base URL of the document that's downloaded by the subsequent page-level API call. Example script: WebPageAddUrl(" mastercard.gif"); WebPageAddUrl(" WebPageLink("Choose payment"); The same script in SilkPerformer, assuming the WebPageLink call downloads the URL WebPageAddUrl("/images/mastercard.gif"); WebPageAddUrl("/images/visa.gif"); WebPageLink("Choose payment"); SilkPerformer Advanced Concepts 109

116 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API 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 SilkPerformer's recorder generates WebPageAddUrl calls whenever appropriate, and generates relative URL's for WebPageAddUrl calls whenever possible. Parsed URL's Extensible HTML parser SilkPerformer introduces a completely new feature: the extensible HTML parser. SilkPerformer adds the concept of parsed URL's (also known as custom URL's). In addition to embedded objects, frames, links and forms, parsed URL's are a category of HTML element that is detected by the HTML parser. Figure 23 - Parsed URL's and SilkPerformer's HTML parser Extending the HTML parser: WebPageParseUrl To enable the HTML parser to parse custom URL's, you need to specify a parsing rule before the page-level function where the custom URL parsing is to be in effect. The API function for this purpose is WebPageParseUrl. WebPageParseUrl works much like the WebParseDataBound function. Please refer to online help for a detailed description of parameters. A parsed URL gets a name (this corresponds to the name of a link); the name is specified in the first parameter of WebPageParseUrl. The second and third 110 SilkPerformer Advanced Concepts

117 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API parameters are the left and right boundaries, the fourth parameter is options (e.g., to ignore white spaces when parsing for the boundaries). A single custom URL parsing specification can result in multiple parsed URL's, since parsing doesn't stop after the first URL is found. More than one WebPageParseUrl statement can be placed before a page-level API call, which will result in multiple parsing rules applied concurrently during page download. Parsing relative URL's In parsing custom URL's, the HTML parser applies the same rules that are in effect for resolving relative URL's for links, frames, etc. This means that you can parse, for example, only for a filename, and receive a complete absolute URL. This gives parsed URL's much of their power. Example HTML code: Assumption: This HTML document was generated by submitting a login form. It has the base URL <a href="javascript:window.open('account.asp')">edit Account</a> When the user clicks this link, the browser opens the URL www4.company.com/user/6543/account.asp in a new browser window. This can be modeled in SilkPerformer 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 URL's, once parsed, can be used in a variety of ways. The following sections of this chapter explain some common usage patterns. Parsed URL's and WebPageLink A parsed URL that's parsed using the WEB_FLAG_PARSE_LINK flag can be used anywhere where a link can be used (e.g., for the WebPageLink or WebPageQueryLink functions). Note that if you don't specify the WEB_ FLAG_PARSE_LINK and WEB_FLAG_PARSE_URL flags, both flags will be in effect by default. Now the example from Parsing relative URL's can be completed: WebPageParseUrl("Javascript window open", "open('", "'"); WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer"); WebPageLink("Javascript window open"); SilkPerformer Advanced Concepts 111

118 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API Note SilkPerformer's 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, check the "Dynamic link parsing" option in the "Advanced Context Management Settings" dialog box. Parsed URL's and context-less functions: WebPageQueryParsedUrl Parsed URL's can be retrieved and saved in string variables using the WebPageQueryParsedUrl function. Please see online help for detailed information regarding the parameters of this function. Such a string variable can then be used as a parameter for all page-level or browser-level functions that require URL parameters, in addition to other purposes (e.g., diagnostics output, StrSearchDelimited, etc). Example HTML code: Assumption: This HTML document resulted by submitting a login form. It has the base URL <!-- 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 www4.company.com/user/6543/products.asp?cat=hd&vendor=wd into a frame named "content". How can this be modeled in BDL? The approach discussed in Parsed URL's and WebPageLink won't work - that would require that parsing boundaries could be found for one of the following strings: 112 SilkPerformer Advanced Concepts

119 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API 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 doesn't seem possible. Consider the following: WebPageSubmit("login", FORM_LOGIN, "LoginPageTimer"); WebPageUrl( " "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 products.asp?cat=hd&vendor=wd can't be parsed, the shorter URL 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"; SilkPerformer Advanced Concepts 113

120 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API 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 SilkPerformer's recorder can automatically generate WebPageParseUrl calls and query the parsed URL's 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 URL parsing" option on the "Advanced Context Management Settings" dialog box. Parsed URL's and modified action URL's Parsed URL's can also be used to specify modified action URL's for form submission. See Specifying a different parsed action URL for more details. Changed Action URL's on Form Submission JavaScript can be used to change the action URL of a form; see the example in Form submission with JavaScript. The same sample HTML code is used in this example: 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="@@@@ @@@@"> </form> <a href="javascript:submitsearch(' search.asp')"> Search this site</a> <a href="javascript:submitsearch(' search.asp')"> Search mirror site</a> 114 SilkPerformer Advanced Concepts

121 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API Specifying a different absolute action URL Assume that this page was downloaded by the function call WebPageLink("Advanced Search"); Using SilkPerformer's 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, SilkPerformer 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(" search.asp"); WebPageSubmit("searchForm", FORM_SEARCH);... dclform FORM_SEARCH: "searchstring" := "discount", "BV_SessionID" := "" <USE_HTML_VAL>; Note Note how the use of WebPageSetActionUrlAbs allows us to use the context-full WebPageSubmit function rather than the context-less WebPageForm function, and so allows us to use the FORM_SEARCH form in a context-full way. Note SilkPerformer's 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 URL's" option on the "Advanced Context Management Settings" dialog box. Specifying a different parsed action URL While specifying a different absolute action URL (as shown in Specifying a different absolute action URL ) is a huge advantage because it allows for the use of a context-full form, the URL is still context-less and hard coded in the script. If the action URL also contains state information, the action URL needs to be specified context-fully. SilkPerformer Advanced Concepts 115

122 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API This can be done using the WebPageSetActionUrl function. Unlike the WebPageSetActionUrlAbs function, the WebPageSetActionUrl function receives the name of a parsed URL (see Extending the HTML parser: WebPageParseUrl ) rather than an absolute URL. It's possible to parse custom URL's 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 " The script can handle state information that may be contained in the action URL. Note SilkPerformer's 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" option on the "Advanced Context Management Settings" dialog box. Modified Forms JavaScript can modify forms that are defined in HTML before they're submitted. Form submission with JavaScript offers some examples. Removing or renaming individual form fields can be particularly challenging. Usage attributes for form fields (see Form Definitions in BDL ) now allow for better context management in such situations. To demonstrate this, consider the HTML example in Form submission with JavaScript. Without form usage attributes, it must be modeled in a context-less way. When taking advantage of form usage attributes however, it can be modeled context-fully. <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> 116 SilkPerformer Advanced Concepts

123 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API <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"); and has the base URL Then the user clicks the link "Stock Watch List". Without form usage attributes, a corresponding BDL script would look like this: WebPageLink("My portfolio"); WebPageForm(" 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 to the script. By taking advantage of SilkPerformer's 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 SilkPerformer Advanced Concepts 117

124 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API "tabeventparam" := "" <SUPPRESS>, // suppressed "TabIndex" := "3"; // added This version eliminates the state information from the script, thereby providing automatic context management. Figure 24 - Combining an HTML form and posted data Note SilkPerformer's recorder can automatically generate WebPageSubmit calls using HTML forms that don't 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 in the "Advanced Context Management Settings" dialog box. Form Data Encoding SilkPerformer's 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 URL's. 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, SilkPerformer 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. 118 SilkPerformer Advanced Concepts

125 4 WEB CONTEXT MANAGEMENT Advanced Context Management Techniques in SilkPerformer's Page-level API Encoding types Encoding type "ENCODE_FORM" Encoding type "ENCODE_ESCAPE" Encoding type "ENCODE_BLANKS" Encoding type "ENCODE_NONE" 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 doesn't 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 URL's of links. The encoding type ENCODE_NONE doesn't 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" := " ", "~requesttime" := "01/01/2002"; FORM_REDIR_LOGIN <ENCODE_NONE> : "~language" := "EN", "~logingroup" := "GUEST", "~transaction" := "TEST", "~exiturl" := " 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"; SilkPerformer Advanced Concepts 119

126 4 WEB CONTEXT MANAGEMENT When to change record settings Note SilkPerformer's 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. When to change record settings General Profile Settings The profile settings dialog that's used to configure the Web recorder is shown in Figure 25. Figure 25 - Profile settings for the Web recorder Choose "Page-based browser-level API (HTML/HTTP)" to instruct the recorder to generate a page-level API script. The option "Convert URL query strings to forms" means that, for context-less function calls, query strings that are part of URL parameters are converted into forms. If this option is not selected, query strings will not be converted to forms, but rather kept as parts of URL's. It's recommended that you select this option as it makes the "Dynamic URL parsing" setting applicable in more cases. 120 SilkPerformer Advanced Concepts

127 4 WEB CONTEXT MANAGEMENT When to change record settings Advanced Context Management Settings The dialog used to configure advanced context management techniques for the recorder is shown in Figure 26. Figure 26 - Advanced Context Management Settings The techniques that correspond to these settings are described in detail in chapter Advanced Context Management Techniques in SilkPerformer's Page-level API. 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. Also see Modified Forms Tip Always select this option. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site doesn't use JavaScript, this option won't cause any harm. Allowing modified action URL's 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. Also see Specifying a different absolute action URL SilkPerformer Advanced Concepts 121

128 4 WEB CONTEXT MANAGEMENT When to change record settings Tip Always select this option. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site doesn't use JavaScript, this option won't cause any harm. Dynamic action URL parsing Selecting this option instructs the recorder to generate the WebPageSetActionUrl function rather than WebPageSetActionUrlAbs when it's possible to generate a WebPageParseUrl function for the required URL. Also see Specifying a different parsed action URL Tip Always select this option. If the site under test uses JavaScript to modify forms, this option will offer better context management. If the site doesn't use JavaScript, this option won't cause any harm. Dynamic link parsing Checking this option instructs the recorder to generate the WebPageLink function for HTTP GET requests that don't correspond to a standard HTML link, rather than a context-less function when it's possible to generate the WebPageParseUrl function for the required URL. Also see Parsed URL's and WebPageLink Tip Always check this option. If the site under test uses JavaScript for enhanced functionality, 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 URL's as parameters to context-less page-level API functions. Note: The need for generating context-less API functions is greatly reduced when the other four advanced context management options are selected. Also see Parsed URL's and context-less functions: WebPageQueryParsedUrl Tip Check this option 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 URL's that seem to incorporate state information. 122 SilkPerformer Advanced Concepts

129 4 WEB CONTEXT MANAGEMENT Limitations Predefined Settings The profile settings dialog (Figure 25) 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)" type projects. Table 4-1: Predefined settings for advanced context management Limitations In spite of the strategies covered in this chapter, you may still encounter situations in which advanced techniques won't guarantee automatic context management. Common reasons include: An URL can't 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. Example The solution: The sample application "ShopIt", which accompanies SilkPerformer, was deliberately built in such a way that the advanced context management techniques of the SilkPerformer Web recorder can't generate a completely context-full script. Use Truelog Explorer to customize context management. Truelog Explorer supports customization of context management via a "point and click" interface. SilkPerformer Advanced Concepts 123

130 4 WEB CONTEXT MANAGEMENT Limitations 124 SilkPerformer Advanced Concepts

131 5 Enhanced 5Chapter SNMP Support for SilkPerformer What you will learn This chapter contains the following sections: Section Page Overview 125 Data Source Definition 126 Using Enhanced SNMP in Performance Explorer 128 Overview Standard SilkPerformer 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 and 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 SilkPerformer 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 SilkPerformer. 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. SilkPerformer Advanced Concepts 125

132 5 ENHANCED SNMP SUPPORT FOR SILKPERFORMER Data Source Definition 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: <Instance ID> Without enhanced SNMP support, you have to provide: OID of the table containing the values 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: <Instance ID> for Object Names and <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 Data Source Definition Note For SilkPerformer 7.0, this is not part of the REALTIME.INI because the file is split and there is a separate file for each data source. As this advanced concept paper is written for 7.0, it must be adapted once the new structure has been defined. By searching for WebLogic and ESNMP in the REALTIME.INI file, you ll find the following entries: S= Application Server\BEA WebLogic preconfigured\snmp, ESNMP:BEA- WEBLOGIC-MIB, M= ESNMP: , BEA WebLogic\JVM Runtime\HeapFreeCurrent, eavgonlycounter, 0, kbytes, 0, 1, 2, 3, 4, 5, Current Heap Free, measurematchname=runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\JVM Runtime\HeapSizeCurrent, eavgonlycounter, 0, kbytes, 0, 1, 2, 3, 4, 5, Current Heap Size, measurematchname=runtime Object Name;measureMatchOID= ; 126 SilkPerformer Advanced Concepts

133 5 ENHANCED SNMP SUPPORT FOR SILKPERFORMER Data Source Definition M= ESNMP: , BEA WebLogic\Queue Runtime\ExecuteThreadCurrentIdleCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Thread Idle Count, measurematchname=queue Runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\Queue Runtime\PendingRequestCurrentCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Current Requests, measurematchname=queue Runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\Queue Runtime\ServicedRequestTotalCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Total Requests, measurematchname=queue Runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\WebApp Component Runtime\OpenSessionsCurrentCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Open sessions, measurematchname=runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\WebApp Component Runtime\OpenSessionsHighCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Session High Count, measurematchname=runtime Object Name;measureMatchOID= ; M= ESNMP: , BEA WebLogic\Execute Queue\ThreadCount, eavgonlycounter, 0,, 0, 1, 2, 3, 4, 5, Thread Count, measurematchname=queue Object Name;measureMatchOID= ; 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. If you want to define a new data source, you should not edit the REALTIME.INI file, because you would loose the changes when you upgrade your SilkPerformer version. To avoid that, create a new file in the sub-folder <SilkPerformer installpath>\working\include\datasrcwzd, for example myesnmp_realtime.ini. This file has to contain the S= and the M= lines of your data source definition. Subsequent lines are for the individual measures: Following the M= is the OID that is to be queried, without the instance ID (e.g., ). Following that is the name of the measure as it will appear in the GUI. Note that the back slashes are used to create the hierarchy (e.g., BEA WebLogic\JDBC Connection Pool\Active Connections). Following that are standard entries: measure class, scale, unit, scale factor, and five unused fields (e.g., 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. SilkPerformer Advanced Concepts 127

134 5 ENHANCED SNMP SUPPORT FOR SILKPERFORMER Using Enhanced SNMP in Performance Explorer The last entry is divided into two parts: - omeasurematchname= This is used in the data source wizard to describe the instances (e.g., JDBC Connection Pool Runtime Object Name). - omeasurematchoid= This is the OID of the table that contains the instance names (e.g., ). Note that 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 look like this: M= ESNMP: , 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= ; Using Enhanced SNMP in Performance Explorer After adding the key (see previous section) to the REALTIME.INI file below the other WebLogic ESNMP keys, open Performance Explorer and add a data source. Select SNMP of the BEA WebLogic preconfigured data source. 128 SilkPerformer Advanced Concepts

135 5 ENHANCED SNMP SUPPORT FOR SILKPERFORMER Using Enhanced SNMP in Performance Explorer Fill in the Hostname, Port, and Community fields. Here you can see the effects of the strings in the ESNMP key. Select your newly created measure and select the Selected instance(s) radio button to query a list of instance names. Choose one or more instance names and add them. SilkPerformer Advanced Concepts 129

136 5 ENHANCED SNMP SUPPORT FOR SILKPERFORMER Using Enhanced SNMP in Performance Explorer Select all measures and click Finish to view the measures in Performance Explorer. 130 SilkPerformer Advanced Concepts

137 6 Generating 6Chapter BDL Monitoring Projects for Performance Explorer What you will learn This chapter contains the following sections: Section Page Overview 131 Concepts 132 Workflow 132 Tutorial 138 Best Practices 151 Overview SilkPerformer projects, or more precisely BDL scripts, can be used to collect performance data for monitored systems. This chapter 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. SilkPerformer Advanced Concepts 131

138 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Concepts Concepts 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. We allow one to many measures within one transaction. Furthermore a monitoring project may use exactly one script defining exactly one usergroup. This usergroup may define one init transaction, one end transaction and one main transaction. In practice, we will use special wrapper functions defined in "bdlmonitor.bdh" which covers some additional functionality absolutely necessary for BDL realtime monitoring. See the tutorials on how to use these functions: MonitorInc MonitorIncFloat MonitorStart and MonitorStop MonitorSet MonitorSetFloat MonitorSetTimer Workflow This section introduces the workflow required to generate BDL monitoring projects for Performance Explorer via SilkPerformer. 1 Launch SilkPerformer and create a BDL monitoring project a Click the Outline Project button on the Workflow bar. The Workflow - Outline Project dialog then opens. 132 SilkPerformer Advanced Concepts

139 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Workflow b c d Enter a name for the project in the Project name text field. Select "Bdl Monitor for Performance Explorer" (under "Monitoring") from the Application type list. Click OK. 2 Create a monitoring script Once the project has been created, click the Model Script button on the Workflow bar. Choose Open existing script and click OK. This brings up a pre-configured monitoring script that can be used as a template. 3 Define project attributes SilkPerformer Advanced Concepts 133

140 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Workflow Each measure exported to Performance Explorer requires a fixed set of project attributes. To open the project attributes go to "Project/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 cummulative value. Enabled: Reserved. Always set to true. 4 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 ( : ); 134 SilkPerformer Advanced Concepts

141 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Workflow rrandf : RndExpF ( ); 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; 5 Edit the.conf File The sample.conf file is available in the project panel under Data Files, just below the Script node. Change the value of the Type entry. This indicates where in the Performance Explorer hierarchy the project will be SilkPerformer Advanced Concepts 135

142 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Workflow located. For example, use type Bdl Monitoring\Sample Project to locate the monitoring project in Performance Explorer under Monitor/Add DataSource/Predefined Data Sources. 6 Exporting Monitoring Projects Export the project to a single zip file. Go to "File\Export Project". Check "zip to single archive" and export your file to "$(SilkPerformerHome)\Working\Monitors\BdlMonitorSample.sep". Note Save the file with an ".sep" extension. 7 Start a Realtime BDL Monitoring Project Launch Performance Explorer and go to Monitor\Add Data Source. Select the Select from predefined Data Sources radio button and click Next. Select the newly created monitoring project and click Next. Enter the name of the host that is to be monitored (select localhost or the host recommended by Performance Explorer and click Next). 136 SilkPerformer Advanced Concepts

143 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Workflow This brings up a dialog on which project attributes can be modified (only one attribute can be modified in this instance). Enter a value greater than 0. This value will be used in the monitoring project. See the sample script for details. Click OK. This brings up a choice of measures specified in the BDL monitoring project. Select both measures and click Finish. This launches the monitoring project. The values can be seen in real-time using a monitoring graph. SilkPerformer Advanced Concepts 137

144 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial 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. Use Case 1 In this use case we'll 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 yoursunhost. The goal here is to continuously track and display this value in a Performance Explorer real-time chart. Create a new SilkPerformer Project Enter a simple project description that reflects the overall purpose of the monitoring project to be displayed in Performance Explorer - for example, "A 138 SilkPerformer Advanced Concepts

145 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial powerful project used to collect the number of running processes on SunOs systems." 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 AnotherCounter 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. The values in italics must be transferred into the project's attributes. Open the attribute editor under Project\Project Attributes. SilkPerformer Advanced Concepts 139

146 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial 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 Use Case #2). 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 the has to be executed on the remoe 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); 140 SilkPerformer Advanced Concepts

147 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial 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 SilkPerformer's 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 that were specified in section Planning Project Attributes. 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 that attribute names are case sensitive. SilkPerformer Advanced Concepts 141

148 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial 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 under Project\Project Attributes and add these additional attributes. All are of type "string" except for the attribute password which is of 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. 142 SilkPerformer Advanced Concepts

149 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial Packaging the Project To export the project as a single zip file, go to File\Export Project. Check zip to single archive and export the file to C:\Program Files\Silk\SilkPerformer 2010 R2\Working\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: <?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. Using the Montoring Project inside Performance Explorer Launch Performance Explorer and go to Monitor\Add Data Source. Select the Select from predefined Data Sources radio button and click Next. Select the newly created monitoring project and click Next. 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 were set in section Creating a BDL Monitoring Script (except for the host which was specified previously). Therefore, the dialog will display following attributes: user SilkPerformer Advanced Concepts 143

150 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial password command 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. Use Case #2 This use case involves a project with two user groups - the user group from the previous use case and a new user group that measures HTTP requests. Two URI's and the host are configurable through project attributes. Creating a SilkPerformer 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." Planning Project Attributes Begin by defining three measures. Pick 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 via WebUrl): 144 SilkPerformer Advanced Concepts

151 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial SunOs\Processes\CountNrOfProcesses SunOs\Http Server\URI1 SunOs\Http Server\URI2 '\' reflects the intended hierarchy which will look like: 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 Use Case #1, 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\CountNrOf Processes #BDLMonitor1.Type string AvgCounter SilkPerformer Advanced Concepts 145

152 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial Name Type Value #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 Create your BDL Monitor Script Make a copy of Use Case #1's BDL script and add functions and transactions as described in this section. Begin with the function that takes care of the HTTP hit: // self explanatory function HttpHit(sURL : string) begin WebUrl(sURL); 146 SilkPerformer Advanced Concepts

153 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial end HttpHit; Wrapper functions for SilkPerformer's MeasureStart and MeasureStop functions are built to read measure names from project attributes. These wrapper functions can also be imported from SilkPerformer's bdh file, bdlmonitor.bdh. // MonitorStart will be passed a number such identifying // a measure as defined in // the project attributes: // Example MonitorStart(1) is #BDLMonitor1, // the name of the measure is // "SunOs\Processes\CountNrOfProcesses" function MonitorStart(nMon : number) var smeasure : string; begin if AttributeGetBoolean("#BDLMonitor" + string(nmon) + ".Enabled") then AttributeGetString("#BDLMonitor" + string(nmon) + ".Name", smeasure, sizeof(smeasure)); MeasureStart(sMeasure); end; end MonitorStart; // MonitorStop does the corresponding MeasureStop function MonitorStop(nMon : number) var smeasure : string; begin if AttributeGetBoolean("#BDLMonitor" + string(nmon) + ".Enabled") then AttributeGetString("#BDLMonitor" + string(nmon) + ".Name", smeasure, sizeof(smeasure)); MeasureStop(sMeasure); end; end MonitorStop Equipped with these new functions you can move on to the new transaction. There are three measures. Two of them can be found in the TWebSnap transaction. The third measure in the transaction should be copied from Use Case #1. In transaction TWebSnap you'll see project attribute values that will be set later be Performance Explorer; for now simply note the sample values. use "bdlmonitor.bdh" use "webapi.bdh" SilkPerformer Advanced Concepts 147

154 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial const nmeasure1 := 1; nmeasure2 := 2; nmeasure3 := 3; dcluser user VMonitor transactions TSnap : 1; user VWebMon transactions TWebSnap : 1; dclfunc // Your function HttpHit transaction TWebSnap var shost : string; suri1 : string; suri2 : string; surl1 : string; surl2 : string; begin AttributeGetString("host", shost, sizeof(shost)); AttributeGetString("URI1", suri1, sizeof(suri1)); AttributeGetString("URI2", suri2, sizeof(suri2)); surl1 := " + shost + suri1; surl2 := " + shost + suri2; MonitorStart(nMeasure2); HttpHit(sURL1); MonitorStop(nMeasure2); MonitorStart(nMeasure3); HttpHit(sURL2); MonitorStop(nMeasure3); end TWebSnap; Execute a "Try script" run to verify that the script runs accurately. 148 SilkPerformer Advanced Concepts

155 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial Packaging it all up 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\ SilkPerformer 2010 R2\Working\Monitors\Advanced.sep. Note 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 ("\"). Using the Monitoring Project within Performance Explorer Launch Performance Explorer and go to Monitor\Add Data Source. Choose Select from predefined Data Sources. Select the newly created monitoring project and click Next. Enter the name of the server that is to be monitored. For example, enter "sunserver" and click Next. A dialog on which project attributes must be set appears. The dialog contains the following attributes, which must be set by the user. SilkPerformer Advanced Concepts 149

156 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Tutorial command: As with Use Case #1, a command that counts the number of processes. user: As with Use Case #1, a valid user account to access 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. 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. 150 SilkPerformer Advanced Concepts

157 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Best Practices Best Practices This section outlines suggestions for working with real-time monitoring projects as they pertain to the writing of monitoring scripts. Loops Example Performance Explorer executes transactions that run snapshots at equidistant intervals. For example a snapshot transaction might be executed every ten seconds. In such a case, Performance Explorer assumes that the entire transaction is executed within this one interval. Otherwise Performance Explorer will return a warning stating that it can't collect the interval's snapshot. Do not use endless loops like // Forbidden transaction TSnap begin while true do Snap(); end; end TSnap; 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 ; end TSnap; Initialization Don't place function calls in TInit transactions that may halt runtime. For example OraLogon may fire a ProcessExit on a failed logon. Performance Explorer won't catch this message and will assume that the project is still running. Of course, Performance Explorer will report that it can't gather data, but it won't be able to report why this is happening. SilkPerformer Advanced Concepts 151

158 6 GENERATING BDL MONITORING PROJECTS FOR PERFORMANCE EXPLORER Best Practices Name Length Attribute value lengths must not exceed 79 characters. Performing a Try Script run for the Project Execute a TryScript run to verify that the project is working before you create a sep file. Special Project Attributes A special monitoring project attribute is "host". This attribute can be accessed within BDL scripts using the following function call: AttributeGetString("host", shost, sizeof(shost)); Instead of "host" an attribute named '#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: 152 SilkPerformer Advanced Concepts

159 7 Load 7Chapter Testing SOAP Web Services What you will learn This chapter contains the following sections: Section Page Overview 153 Simple Object Access Protocol 153 Load Testing SOAP over HTTP Based Web Services 155 Overview This chapter explains the basics of SOAP based Web Services and details how they can be tested. Note For information regarding testing SOAP Web Services using SilkPerformer.NET Framework and the Visual Studio.NET Add-In, see the.net Explorer User Guide and the.net Framework Developer Guide. For information regarding testing SOAP Web Services using SilkPerformer Java Framework, see the Java Explorer User Guide and the Java Framework Developer Guide. Simple Object Access Protocol SOAP (Simple Object Access Protocol) is a lightweight XML-based protocol used for the exchange of information in decentralized, distributed application SilkPerformer Advanced Concepts 153

160 7 LOAD TESTING SOAP WEB SERVICES Simple Object Access Protocol environments. SOAP messages can be transmitted in any way that applications require, as long as both client and server agree upon the method. However, the current specification describes only a single transport protocol binding: HTTP. SOAP fits perfectly 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 via HTTP. [1] 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 SOAP's greatest advocates and has incorporated it as a standard interface in its.net architecture. SOAP client requests are encapsulated within HTTP POST (or M-POST) packets. The following example is taken from the Internet-draft specification: SOAP client requests are encapsulated within an HTTP POST (or M-POST) packet. The following example is taken from the Internet-draft specification: POST /StockQuote HTTP/1.1 Host: Content-Type: text/xml; charset="utf-8" Content-Length: nnnn SOAPAction: "Some-URI" <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:soap-env=" SOAP-ENV:encodingStyle=" <SOAP-ENV:Body> <m:getlasttradeprice xmlns:m="some-uri"> <symbol>dis</symbol> </m:getlasttradeprice> </SOAP-ENV:Body> </SOAP-ENV:Envelope> The first four lines in the above example 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 can be used to indicate the intent of a SOAP HTTP request. The value is a URI that identifies the intent. The content of SOAPAction header fields can be used by servers (e.g., firewalls) to appropriately filter SOAP request messages in HTTP. The empty string ("") 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 as to the intent of the message. 154 SilkPerformer Advanced Concepts

161 7 LOAD TESTING SOAP WEB SERVICES Load Testing SOAP over HTTP Based Web Services The XML code is also 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 needs only to understand how to frame a request in a SOAP compliant XML message and how to send it via HTTP. In the example below, the program knows how to format a request for a stock price. The HTTP server receiving this message knows that it is a SOAP message because it recognizes the HTTP header SOAPAction; it then proceeds to process 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 requests. The previous example is an example of a call; the following response example comes in answer to the call: HTTP/ OK Content-Type: text/xml; charset="utf-8" Content-Length: nnnn <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:soap-env=" SOAP-ENV:encodingStyle=" <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 are standard HTTP. The first line indicates a response code to the previous POST request, the second and third lines indicate content type and length. XML headers enclose actual SOAP payloads. The XML element <GetLastTradePriceResponse> contains a response to the request for a trading price; its child element is <return>, which indicates the value to be returned to the request. Load Testing SOAP over HTTP Based Web Services SilkPerformer offers three options for load testing SOAP over HTTP based services: 1 Recording/Replaying HTTP Traffic 2.NET Explorer in combination with SilkPerformer's.NET Framework (Refer to the.net Explorer User Guide) SilkPerformer Advanced Concepts 155

162 7 LOAD TESTING SOAP WEB SERVICES Load Testing SOAP over HTTP Based Web Services 3 Java Explorer in combination with SilkPerformer's Java Framework (Refer to the Java Explorer User Guide) Your customer's environment and prerequisites will determine which of these options are best suited for your needs. Recording/Replaying HTTP Traffic Recording the SOAP protocol over HTTP is as straightforward as recording any Web application running in a browser. The application that is recorded is the application that executes the SOAP Web Service calls. This can be either a client application or a part of the Web application itself. Creating a new project The first step is to create a new SilkPerformer project of the Web Services/XML/ SOAP application type: This application type automatically configures its profile settings that SOAPAction HTTP headers that are used by SOAP based applications when calling Web Services are to be recorded. Creating the application profile The next step is to create an application profile for the client application that you wish to record. Procedure To access the Application Profile dialog: 1 From the SilkPerformer menu bar, select Settings / System. 156 SilkPerformer Advanced Concepts

163 7 LOAD TESTING SOAP WEB SERVICES Load Testing SOAP over HTTP Based Web Services 2 The System Settings - Workbench dialog appears, open at the Agent Pool tab of the Workbench group. 3 Click the Recorder icon on the left of the dialog. The Recorder group opens at the Applications tab. 4 Click the Add button to add a new application profile to the list. Recording a script Begin recording a new script with your created application profile. Interact with your client application; the recorder will record all SOAP requests that are executed over HTTP/HTTPS. When you're finished, close the application and save the recorded script. Script customization For each SOAP request that is recorded you will see a scripted WebHeaderAdd and WebUrlPostBin API call (see the example below). WebHeaderAdd("SOAPAction", "\" WebUrlPostBin( " "<?xml version=\"1.0\" encoding=\"utf-8\"?>" "<soap:envelope xmlns:soap=\" \" "xmlns:xsi=\" "xmlns:xsd=\" "<soap:body>" SilkPerformer Advanced Concepts 157

164 7 LOAD TESTING SOAP WEB SERVICES Load Testing SOAP over HTTP Based Web Services Chapter References "<Login xmlns=\" "<susername>myuser</susername>" "<spassword>mypass</spassword>" "</Login>" "</soap:body>" "</soap:envelope>", STRING_COMPLETE, "text/xml; charset=utf-8"); 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 TryScript. Then use the XML control to customize the XML nodes that represent the input parameters. Replaying the script Once you've finished script customization, you can replay your script - either in another TryScript run, as part of baseline identification, or in a load test. As the Web Service calls are performed along with Web API functions, you will receive the same measures you receive when testing any Web application - including detailed protocol-specific statistics. [1] Session, Roger SOAP. An overview of the Simple Object Access Protocol, March [2] W3C Simple Object Access Protocol (SOAP) 1.1, Dec [3] UN/CEFACT, OASIS Enabling Electronic Business with ebxml, December [4] Geyer, Carol ebxml Integrates SOAP Into Messaging Services Specification, March March 2001 [5] Open Financial Exchange Open Financial Exchange Specification 2.0, April SilkPerformer Advanced Concepts

165 8 Load 8Chapter Testing Legacy and Custom TCP/IP Based Protocols What you will learn This chapter contains the following sections: Section Page Overview 159 Introduction 160 Script Customization - General Tasks 161 Telnet, TN3270e, and Custom Protocols 167 Recorder Settings 181 Summary 184 Overview This chapter explains how to develop load test scripts for applications that use legacy or custom TCP/IP based protocols. The first half of this chapter 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. In the second half of this chapter, 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, the reader is guided through the process of SilkPerformer Advanced Concepts 159

166 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Introduction recording an application, analyzing traffic, configuring recording rules, and customizing a script. 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 Introduction Though SilkPerformer supports the testing of numerous protocols and technologies directly out of the box, there are some protocols - many of them socalled legacy systems - for which SilkPerformer requires some customization. Note Since SilkPerformer 7.3, the following protocols are directly supported and no longer need the customizations which are described in this chapter: - TN TN VT100 - VT200+ All of the protocols discussed in this article are based on TCP/IP. With SilkPerformer, you can record protocols at the TCP level and customize the resulting scripts using WebTcpip functions. With SilkPerformer's enhanced TCP/IP support, the new TCP/IP TrueLog Explorer, and rule-based recording, this process is easier than ever. This article has two main goals: 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. In section, Script Customization - General Tasks, the challenges of load testing at the TCP level are discussed in general terms. This chapter gives you some ideas on approaching script customization. 160 SilkPerformer Advanced Concepts

167 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks The section, Telnet, TN3270e, and Custom Protocols, contains three examples of TCP/IP based traffic: An application based on the Telnet protocol The TN3270e protocol (emulation of 3270 devices) An entirely customized, application-specific TCP based protocol The first two protocols are commonly used. The third protocol is an example of a true custom protocol. Finally, this chapter explores recorder settings for TCP-based protocols. All reusable functions introduced and explained in this document are contained in the SilkPerformer file telnet.bdh. Script Customization - General Tasks 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 Following is a sampling of TCP/IP traffic recorded by SilkPerformer: WebTcpipSendBin(hWeb0, "\h dd7d311d57ca f0" // } Ó Õ ð "\hf0f14011d74ca f0f0f140ffef", 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 don't 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 SilkPerformer function (see section EBCDIC to ASCII Character Code Conversion for details). Other possible causes for traffic that contains unreadable strings: Reason Traffic uses a character set other than ASCII. Consequence Character mapping functions can easily be implemented in SilkPerformer's BDL language. SilkPerformer Advanced Concepts 161

168 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks Reason Traffic is encrypted with a custom encryption algorithm (i.e., one that doesn't rely on SSL, which would automatically be supported by SilkPerformer). Traffic doesn't contain any strings - only numbers, sent as binaries. Consequence The encryption/decryption routines should be re-implemented in BDL, or made accessible to SilkPerformer via a DLL or a SilkPerformer framework (e.g., Java Framework). In such instances you don't have to worry about strings. Dynamically Receiving Server Responses Full control of client requests is easily achieved, though 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. SilkPerformer's recorder doesn't know in advance about the semantics of the TCP based protocols it records. Hence, all server responses are recorded like this: 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 will be 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 SilkPerformer's 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 SilkPerformer function WebTcpipRecvProto and its sibling, WebTcpipRecvProtoEx, can adequately 162 SilkPerformer Advanced Concepts

169 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks handle such situations. They allow for definition of the position and length of packet-length information in response data. For example, the BDL code line: WebTcpipRecvProto(hWeb, 0, 2, TCP_FLAG_INCLUDE_PROTO, sdata, sizeof(sdata), nreceived); will be used if the length of the response data remains a two-byte sequence in the first two bytes (i.e., position 0) of the server response. See section A Custom TCP/IP Based Protocol for an example taken from an actual load test project. Case II: Termination Byte Sequence In this scenario data packets are terminated by a constant byte sequence. The corresponding SilkPerformer function is WebTcpipRecvUntil. If, for example, the end sequence is defined by the two-byte sequence 0xFF00, the line: WebTcpipRecvUntil(hWeb, sresp, sizeof(sresp), nrecv, "\hff00", 2); will be appropriate. See section The TN3270e Protocol for an example of this type based on the TN3270e protocol. Case III: No Information on Response Packet Size This is the trickiest 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. See section The Telnet Protocol for an example of this type based on the Telnet protocol. Rule-Based Recording An advanced feature introduced in SilkPerformer 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 saving them to the project's Documents folder SilkPerformer Advanced Concepts 163

170 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks (project specific rules) or in SilkPerformer's Include 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 chapter. Examples of recording rule configuration files can be found in sections Recording Rule Configuration Files and Recording Rule Configuration Files Rule-based recording is also well documented in Rule-Based Recording. String Manipulation of Binary Data Request Parameterization Example code contained in a recording of a TCP session: WebTcpipSendBin(hWeb0, "\h f ffff", 14); // O Peter The actual business data sent here - the data that should be parameterized - is that the name "Peter" = 0x won't work: "\h f000000" + sname + "\hffff" won't yield the results you might expect. The problem is caused by the zero (0x00) bytes in this string, which SilkPerformer (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("\h f000000", 7); AppendRequestData(sName); // e.g., "Peter" AppendRequestData("\hFFFF"); SendTcpipRequest(hSend); The function library is included via an include file (*.bdh). It uses two global variables for the request data and request data length. The function AppendRequestData simply 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, consisting of three functions. The most important line, containing the data concatenation, is in bold: Sample const BUFSIZE := 10000; // maximal size for request data var // global variables for Request data contents and length 164 SilkPerformer Advanced Concepts

171 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks 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. SilkPerformer 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); SilkPerformer Advanced Concepts 165

172 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Script Customization - General Tasks There is no binary counterpart yet 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 (e.g., 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 (i.e., they don't contain zero bytes). Sample 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; Session ID's Since many TCP/IP based protocols rely on TCP/IP connections between server and client to remaining open and active during sessions, they don't contain session ID's. Therefore the problems that can arise when customizing load test scripts for stateless protocols such as HTML often don't exist. There are of course exceptions to this rule, so keep watch for session ID's. The TCP support that was added to TrueLog Explorer with SilkPerformer can be helpful in this regard. Finding Information Standard protocols are typically defined in Requests for comments (RFC's). You'll find samples of these at [RFC854], [RFC2355] and others are relevant to the examples included in the following sections of this chapter. 166 SilkPerformer Advanced Concepts

173 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols Telnet, TN3270e, and Custom Protocols The following sections apply the theory discussed in the previous sections to specific real-world examples. The Telnet Protocol The introduction of RFC 854, the Telnet protocol specification, states: The purpose of the TELNET Protocol is to provide a fairly general, bidirectional, eight-bit byte oriented communications facility. Its primary goal is to allow a standard method of interfacing terminal devices and terminal-oriented processes to each other. A Telnet session consists of two main parts: 1 A connection is established, and session details and options are negotiated between client and server. 2 The application launches. From that point forward, generated traffic is user driven. The following Telnet SilkPerformer script comes from a project in which a script was recorded and customized from a Telnet session with VT220 terminal emulation. The client (i.e., 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 recording of the Telnet session: 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, "\hfffa fff0", 11); // ú VT220 ð WebTcpipRecvExact(hWeb0, NULL, 3); WebTcpipSendBin(hWeb0, "\hfffc20", 3); // ü WebTcpipRecvExact(hWeb0, NULL, 60); SilkPerformer Advanced Concepts 167

174 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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. SilkPerformer 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 (Telnet protocol specification), reveals how the conversation was achieved. The first part of the log is translated into TELNET codes in the following table: Red (italic) = Server to Client - Green (bold) = Client to Server FF FD 24 FF FC 24 FF FD 18 FF FB 18 FF FA FF F0 FF FA FF F0 FF FD 20 FF FC 20 IAC DO ENVIRONMENT VARIABLES IAC WON'T ENVIRONMENT VARIABLES IAC DO TERMINAL-TYPE IAC WILL TERMINAL-TYPE IAC SB TERMINAL-TYPE SEND IAC SE IAC SB TERMINAL-TYPE IS "VT220" IAC SE IAC DO TERMINAL-SPEED IAC WON'T TERMINAL-SPEED Each command begins with an "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"); 168 SilkPerformer Advanced Concepts

175 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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, response verification, etc. 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 SilkPerformer Advanced Concepts 169

176 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols } Looking back at the recorded script, you'll find that sending the password - as opposed to sending 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) { [8;19H [;7m+--- 1B 5B 38 3B B 5B 3B 37 6D 2B 2D 2D 2D Hinweis: Kein 2D 2D 2D E A 20 4B E Kunde gefunden- 20 4B 75 6E E E 2D [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. 170 SilkPerformer Advanced Concepts

177 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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 then 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. Sample 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; SilkPerformer Advanced Concepts 171

178 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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 dimension "seconds." The TN3270e Protocol The TN3270e protocol is a method of emulating 3270 terminal and printer devices via Telnet. It is used by terminal emulation software such as NetManage's Rumba and Hummingbird's HostExplorer for direct connections to mainframes. Similar to Telnet, a typical TN3270e session consists of two main parts: 1 A connection is established; session details and options are negotiated. 172 SilkPerformer Advanced Concepts

179 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 2 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, " ", 7230); WebTcpipRecvExact(hWeb0, NULL, 3); WebTcpipSendBin(hWeb0, "\hfffb28", 3); // û( WebTcpipRecvExact(hWeb0, NULL, 7); WebTcpipSendBin(hWeb0, "\hfffa d2d d342d" // ú( IBM "\h45fff0", 19); // E ð WebTcpipRecvExact(hWeb0, NULL, 28); WebTcpipSendBin(hWeb0, "\hfffa fff0", 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: Red (italic) = Server to Client - Green (bold) = Client to Server FF FD 28 FF FB 28 FF FA FF F0 FF FA D 2D D 34 2D 45 FF F0 FF FA D 2D D 34 2D D 55 FF F0 FF FA FF F0 FF FA FF F0 IAC DO TN3270E IAC WILL TN3270E IAC SB TN3270E SEND DEVICE-TYPE IAC SE IAC SB TN3270E DEVICE-TYPE REQUEST "IBM E" IAC SE IAC SB TN3270E DEVICE-TYPE IS "IBM E" CONNECT "T95ITQMU" IAC SE IAC SB TN3270E FUNCTIONS REQUEST (BIND-IMAGE SYSREQ) IAC SE IAC SB TN3270E FUNCTIONS IS (BIND- IMAGE SYSREQ) IAC SE SilkPerformer Advanced Concepts 173

180 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols In summary, server and client agree on a protocol, a device type (IBM 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, "\h dc6c61140c4f311c640f2" // Æ@ò "\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. An EBCDIC code map is included in section EBCDIC to ASCII Character Code Conversion - there, an explanation of conversion between EBCDIC and ASCII using SilkPerformer's script language (BDL) is discussed. Here's an account of the other parts of this message. The first five bytes represent the TN3270e message header (cf. RFC 2355): Field Length Value in our example Data type 1 byte 0x 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). 174 SilkPerformer Advanced Concepts

181 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols A simple customization of the script extract above, using the function library introduced in section Request Parameterization, would look like this: ResetRequestData(); AppendRequestData("\h DC6C61140C4F311C640", 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 SilkPerformer 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 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. SilkPerformer Advanced Concepts 175

182 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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 - required for translating client requests from ASCII to EBCDIC - works in a similar manner. Sample 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; 176 SilkPerformer Advanced Concepts

183 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols // 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. Figure 27 - EBCDIC code map [EBCDIC_UNI] is a reference that presents the specifications of the UTF- EBCDIC - EBCDIC Friendly Unicode (or UCS) Transformation Format. Issues with "Keep Alive" Mechanisms Note The sequence in the load test script file below that 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 SilkPerformer Advanced Concepts 177

184 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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 SilkPerformer 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. IP Spoofing For successful replay of such a script with parallel virtual users, each user must use a unique IP address. Check the option Client IP address multiplexing in SilkPerformer's Active Profile/Internet/Network tab page, and configure enough IP addresses on SilkPerformer agents so that each virtual user can have a unique IP address ("IP Spoofing"). IP addresses can be configured using the IP Address Manager in the System Configuration Manager that ships with SilkPerformer. Recording Rule Configuration Files SilkPerformer's 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", cf. the TN3270e response header above) in the second part. The resulting recording rule XML file looks like this: <?xml version="1.0" encoding="utf-8"?> 178 SilkPerformer Advanced Concepts

185 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols <RecordingRuleSet> <TcpRuleRecvUntil> <Name>Telnet session start</name> <Identify> <TermData>ÿð</TermData> <IgnoreWhiteSpaces>false</IgnoreWhiteSpaces> </Identify> <Conditions> <CompareData> <Data>ÿ</Data> <ApplyTo>Left</ApplyTo> <Offset>0</Offset> </CompareData> </Conditions> </TcpRuleRecvUntil> <TcpRuleRecvUntil> <Name>3270-DATA</Name> <Identify> <TermData>ÿï</TermData> <IgnoreWhiteSpaces>false</IgnoreWhiteSpaces> </Identify> <Conditions> <CompareData> <Data>&#x00;</Data> <ApplyTo>Left</ApplyTo> <Offset>0</Offset> </CompareData> </Conditions> </TcpRuleRecvUntil> </RecordingRuleSet> A Custom TCP/IP Based Protocol 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) some are string type. Here is a typical request-response pair from the recorded traffic: WebTcpipConnect(hWeb0, " ", 3311); WebTcpipSendBin(hWeb0, "\h " // "\h f4b " // OK60... "\h b " // "\h " // 0000, 640); SilkPerformer Advanced Concepts 179

186 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Telnet, TN3270e, and Custom Protocols 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: P OK F 4B U60OKS1 SILK F 4B C 4B Note The first four bytes: 0x They 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 That the client request telegram contains the same information. The first four bytes are 0x , equal to 2* *16 = 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 introduced in section Request Parameterization. The WebTcpipRecvExact function has been replaced by a call to WebTcpipRecvProto Here is the result: ResetRequestData(); AppendRequestData("\h " "\h ", 26); AppendRequestData("OK60 "); AppendRequestData("\h0000", 2); AppendRequestData(sUser + spassword); //... (some more lines not displayed here) MeasureStart("Write Journal"); WebTcpipConnect(hWeb0, " ", 3311); SendTcpipRequest(hWeb0); WebTcpipRecvProto(hWeb0, 0, 4, TCP_FLAG_INCLUDE_PROTO, sresponse, sizeof(sresponse), nreceived); //... (response verification not displayed here) WebTcpipShutdown(hWeb0); 180 SilkPerformer Advanced Concepts

187 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Recorder Settings MeasureStop("Write Journal"); Recording Rule Configuration Files The following recording rule XML file configures SilkPerformer's 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. <?xml version="1.0" encoding="utf-8"?> <RecordingRuleSet> <TcpRuleRecvProto> <Name>My custom TCP protocol</name> <Identify> <LengthOffset>0</LengthOffset> <LengthLen>4</LengthLen> <OptionFlags>ProtoIncluded</OptionFlags> </Identify> </TcpRuleRecvProto> </RecordingRuleSet> Recorder Settings SilkPerformer offers two mechanisms for recording TCP/IP based protocol traffic. The following sections explain how to configure them and how to select an appropriate configuration. "Socksifying" an Application If you know the path of the client application executable that's connecting to the server, you can set up an application profile for the application in Settings/ SilkPerformer Advanced Concepts 181

188 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Recorder Settings System/Recorder/Application Profiles. Here is an example using the application profile for the Windows Telnet client: TCP Proxy Recorder An alternate 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 SilkPerformer and the client application so that traffic is explicitly routed over SilkPerformer's recorder. Assuming that the client connects to MYSERVER on port 5012, you would change these settings to LOCALHOST and port (or any other unused TCP port) in the registry or appropriate configuration file. In SilkPerformer, choose Settings/System/Recorder/Proxies. Add a new proxy, and configure it as 182 SilkPerformer Advanced Concepts

189 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Recorder Settings 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. Choosing Appropriate Recorder Settings 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: SilkPerformer Advanced Concepts 183

190 8 LOAD TESTING LEGACY AND CUSTOM TCP/IP BASED PROTOCOLS Summary Using the TCP proxy mechanism, SilkPerformer 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 via the SilkPerformer 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. Summary You should now be prepared for your own load test projects involving legacy or custom TCP based protocols. This chapter has explored all the major scripting challenges - dynamic server responses, different code tables, string manipulation of binary data, etc. - and has taken a look at two important protocols (Telnet and TN3270e) from a loadtesting perspective. Taken together, the TCP/IP TrueLog Explorer, the extended set of TCP/IP functions, and rule-based recording represent a strong toolset for efficient development of load test scripts for both legacy and custom TCP/IP based protocols. 184 SilkPerformer Advanced Concepts

191 9 Load 9Chapter Testing Microsoft Based Distributed Applications What you will learn This chapter contains the following sections: Section Page Overview 186 Introduction 186 The Sample Application 186 Test Environment 190 Test Goals and Procedures 190 Specification of Test Scenarios 191 First Load Test 192 Applying Optimization 209 Second Load Test 210 Performance Comparison 210 Back-End Test 212 Testing Duwamish Online - A Case Study 213 Glossary 214 SilkPerformer Advanced Concepts 185

192 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Overview Overview This chapter explains how SilkPerformer handles various Microsoft technologies that are frequently used to build e-business applications. Microsoft's sample e-business application, Duwamish Online, is used for all demonstrations. This application allows SilkPerformer's HTTP (S), COM and ODBC capabilities to be demonstrated in a comprehensive, real-world load test scenario. In addition to the better-known front-end Web tests, this chapter explains how you can use SilkPerformer to examine middle-tier and back-end applications to identify performance problems. Introduction In an ongoing effort to meet customers' needs, today's e-business applications have become increasingly complex and involve numerous technologies across multiple tiers. Microsoft technologies, such as Internet Information Server (IIS), Active Server Pages (ASP) and COM, are often applied to enhance the use of Internet portals. Complex application structures result - making it necessary in many cases to monitor and load test middle- and back-end tiers in addition to presentation tiers (front end). Duwamish Online ("Duwamish" for short) is a virtual "real world" application that's useful for demonstrating the capabilities of SilkPerformer in load testing fundamental MS technologies - especially Internet Information Server, COM+ Application Server and MSQL Server. Duwamish Online is a sample online store that sells books, apparel, and related items. It serves as a tutorial application for MSDN Online to demonstrate the use of MS techniques in building complete e-business applications. The version of Duwamish referenced in this chapter simulates an early stage of development in which Duwamish's middle-tier lacks performance optimization, and therefore reveals a middle-tier bottleneck during load testing. The Sample Application Logical Architecture of Duwamish Online Figure 28 shows the basic architecture of Duwamish Online. On the front-end (the presentation layer), Duwamish offers its services by means of an Active Server Pages (ASP) application. The middle-tier implements the bulk of the customer services. It consists of two layers: the workflow layer (WFL), which is used directly (and partially implemented) by the ASP application, and the 186 SilkPerformer Advanced Concepts

193 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS The Sample Application business logic layer (BLL). All data are exchanged between the ASP application and the middle-tier in XML format as parameters of COM functions. Products for sale on Duwamish are stored in a database on the back-end that's managed by Microsoft SQL Server The connection to the database is made in the data access layer (DAL) using Microsoft ActiveX Data Objects (ADO). ADO, in turn, connects the middle-tier and the back-end via an ODBC interface. Beyond the synchronous portion of the middle-tier - which enables catalog browsing, account management, and purchase transactions - Duwamish includes two asynchronous layers: the QWFL (queued workflow layer) and the FWFL (fulfillment/logistic workflow layer). The QWFL performs credit card authentication and payment processing. The FWFL handles order fulfillment through an external logistic service provider. Communication between the synchronous and asynchronous layers is handled by Microsoft Message Queue Server (MSMQ). The Windows 2000 Task Scheduler regularly starts asynchronous tasks to process received requests. Figure 28 - Duwamish logical architecture This figure shows an overview of the logical parts of the Duwamish application. SilkPerformer Advanced Concepts 187

194 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS The Sample Application Physical Architecture of Duwamish Online Figure 28 offers as overview of the logical architecture of Duwamish. Unfortunately, the logical architecture doesn't provide enough information regarding how Duwamish is deployed. However, for load tests of middle-tiers implemented with COM, a thorough understanding of the deployment of the application under test is required. Without such understanding, it's difficult to test COM components (servers) because they are binary units and, therefore, parts of the binary (physical) architecture. There are two other issues that complicate the load testing of COM components: 1 COM function sets aren't fixed. Each component defines its own specific number and function structure. 2 Applications often have numerous components. Both client and server applications may contain several COM components each - and only a small number of those components may be relevant in load testing. This differs from ODBC in which the client contains a single driver DLL (ODBC32.DLL) with a fixed set of functions. A detailed understanding of the physical architecture of Duwamish Online is required for targeting only those COM components and COM interfaces that are relevant to load testing. This keeps test drivers customized and small, despite the fact that Duwamish is a large application. Figure 29 depicts a more detailed view of Duwamish as it's been deployed. The Web server (the front-end) has been installed with the synchronous middle-tier components on one machine (Test Machine 1 in Figure 29); the asynchronous middle-tier components and the database (the back-end) run on a different machine (Test Machine 2 in Figure 29). 188 SilkPerformer Advanced Concepts

195 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS The Sample Application Figure 29 - Duwamish deployment Circles represent processes; rectangles represent machines. The component-dlls include WFL (Workflow Layer), BLL (Business Logic Layer), DAL (Data Access Layer), FWFL (Fulfillment Workflow Layer), and QWFL (Queued Workflow Layer). SilkPerformer enables load tests of servers that support HTTP, COM, and ODBC. For more information regarding deployment options for Duwamish, see Duwamish Online: Web Farm Installation. As you can see from Figure 29, the Duwamish installation deploys four instances of the COM+ application server (dllhost.exe): Business presentation (ASP Script Engine on Test Machine 1): The ASP (Active Server Pages) application runs in a process (in an instance of the COM+ application server) separate from the Web server. This configuration protects the Web server from risks associated with the ASP application crashing. Customer services (Middle-Tier on Test Machine 1): This application provides customer services such as product search and account setup. Order processing (Queued Middle-Tier on Test Machine 2): This application implements all the services that are required for processing orders - including authorizing and billing credit cards for purchases after product delivery. The application performs these tasks asynchronously because they consume a considerable amount of time and don't require immediate feedback. SilkPerformer Advanced Concepts 189

196 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Test Environment Product delivery (Fulfillment on Test Machine 2): This application handles communication with a third-party fulfillment company. Such a company maintains product inventory in their warehouse and ships products to customers. All communication tasks, such as the uploading of order forms and the reporting of order status, are performed asynchronously (no immediate feedback is required). Test Environment In addition to the two machines that host Duwamish, four other machines are required for the installation of the load test environment (see Figure 30). On one machine the entire load test process is controlled and test results are evaluated; this machine runs both SilkPerformer's Controller and the Performance Explorer for server monitoring and results evaluation. Three SilkPerformer agent machines have also been set up for the Web load tests and the load tests of the middle-tier and back-end (DB server). For more information on various setup options for the Duwamish sample application, please see Duwamish Online: Web Farm Installation. Test Goals and Procedures These initial load tests evaluate a version of Duwamish that has intentionally been designed with performance problems - to allow SilkPerformer to detect a bottleneck in the application's middle-tier. Subsequent scalability testing of an improved version of Duwamish reveals that the program performs without error. During the load test attention is concentrated on the synchronous part of the middle-tier (Customer Services, see above and Figure 31) as it must immediately react to user inquiries, many of which don't result in product purchases. The asynchronous part (Order Processing and Product Delivery, see above) is responsible for managing and monitoring product orders. Due to the relatively long period of time required to ship products, these tasks don't require immediate feedback. To identify performance bottlenecks in the middle-tier, the entire application must be put under real load. Only after typical usage scenarios have been specified can accurate load tests identify inferior performance of specific components. 190 SilkPerformer Advanced Concepts

197 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Specification of Test Scenarios Figure 30 - Load Test Environment All test machines are equipped with a single 800MHz processor, 512Mbyte RAM, and 100MBit Ethernet. The machines are connected to a Compaq GBit Ethernet switch. Figure 31 - Test the bottleneck The synchronous part of Duwamish's middle tier (represented by the COM component WFL) contains the bottleneck. Specification of Test Scenarios Finding an accurate test scenario (usage scenario) for a system that isn't yet online can be challenging. Specifications for usage scenarios are comprised of two parts: SilkPerformer Advanced Concepts 191

198 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test 1 Use case distribution: Market research institutes can be helpful in providing statistics regarding typical usage scenarios for comparable online applications. For the sake of this demonstration, consider the following usage distribution (which is based on past experience and comparable application statistics): - 62% Category searchsearch for an Item by Category - 21% Keyword searchsearch for an Item by Keyword - 10% Home PageOpen only the Home Page - 5% Create an accountcreate a User Account - 2% Order an itembuy a product 2 Use case actions: The sequence of actions that make up each use case (for example "Category search" and "Create an account") must be specified. In a test script such actions are represented by, for example, calls to SilkPerformer's Web Page API or COM API. The actions that a use case involves depend on the purpose of each use case and the design of the test object (Duwamish). Action sequences must be carefully defined because they affect the value of load tests. For more information about usage scenarios, see Duwamish Online: Capacity Planning. First Load Test The first load test evaluates the entire application from the Web front-end (see section Front-End Test ). The use of critical system resources is monitored - for example CPU utilization - on all machines on which Duwamish is deployed. Any part of the system that reaches the CPU usage threshold contains a bottleneck. Closer examination of such parts reveals exactly where the bottlenecks occur. In this example, a bottleneck is located in the middle-tier (see section Middle-Tier Test ). Front-End Test To execute accurate load tests that reflect real world Web server usage, it's important to simulate different kinds of users (customers) with different usage profiles. To do this, test scripts that describe varied and randomized user behavior are required. For a realistic usage scenario, users who access Duwamish via different network devices (e.g., T1 and different modems) are simulated using SilkPerformer. 192 SilkPerformer Advanced Concepts

199 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test Creating a Web Load Test Scenario The first step in running a Web load test with SilkPerformer involves creating a new project of type Web business transaction (HTML/HTTP). Neither the standard settings or the application profile need to be changed because the standard Web browser (Internet Explorer) is used to browse Duwamish's online store. The Model Script button is selected in SilkPerformer's workflow bar to begin recording a script that describes the behavior of a typical Duwamish customer. Later, other scripts that model the behavior of other types of customers will be recorded. In the Workflow - Model Script dialog the Record option is selected, Internet Explorer is indicated as the application to be recorded, and the URL that Internet Explorer (IE) is to contact upon start up (see Figure 32) is entered. After clicking OK, Internet Explorer and SilkPerformer's recorder open. Figure 32 - Specifying IE as the client application to be recorded The next step is to record the usage scenarios, as specified in section Specification of Test Scenarios. A separate script is created for each usage scenario; this way the browser cache can't delete generated test scripts. The following steps are performed for each usage scenario: 1 Start the browser. 2 Clear the browser's cache. 3 Clear SilkPerformer's recorder log tab and script tab. SilkPerformer Advanced Concepts 193

200 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test 4 Load the Duwamish home page in the browser and click through the site's pages as required for a particular usage scenario. 5 Stop recording and save the generated script. After recording all usage scenarios in separate test scripts, scripts are merged into a single script that's used to drive the load test. This way each recorded usage scenario becomes a separate SilkPerformer transaction. This process results in a relatively unrealistic load test that carries out user actions in exactly the sequence in which they are recorded. What's required is a script that simulates a group of users with similar behavior, not identical behavior. To achieve this, the generated script must be customized in three ways: 1 Randomizing user input: In the real world, different users buy different products. Therefore, user input (e.g., the products a user searches for or the products a user buys) must be customized. Virtual users select products randomly from sets of available products. For additional information regarding customizing SilkPerformer scripts, see the "Load Testing a Web Application" tutorial. 2 Establishing user groups: In addition to randomizing user input, the test script must be customized in such a way that it reproduces the different usage scenarios specified in section Specification of Test Scenarios. Five different user groups are established, each performing different transactions based on what such user types would likely do in the real world. Note The number of transactions that each user performs during a simulation must also be specified, either in absolute numbers (as with load tests applying the queuing workload model) or in relation to the transactions other users perform (as with load tests applying the steady workload model). However, as only the increasing workload model for front-end tests is used in this example, there's no need to bother with the number of transactions that each user performs. 3 Customizing the connection speed: As mentioned in section Front-End Test, it's unrealistic to assume that all virtual users will connect to the Duwamish Web server with the same connection speed. So, during each user's initial transaction a random modem speed is selected using the WebSetSpeed () BDL function. A randomly selected bandwidth is then passed to the function as a parameter. As a result, the network speed simulation for each user is initialized with a different value. For a better understanding of this 194 SilkPerformer Advanced Concepts

201 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test customization process, please examine the attached sample files <cdrom_drive>:\extras\whitepaper_microsoft Technologies_ ProjectFiles.zip. Now that the test script has been customized, a model that determines the way that SilkPerformer should distribute workload during test runs must be selected. As we have no idea how many concurrent users the installation of Duwamish can handle, SilkPerformer must use the increasing workload model. Increasing workloads help explore the limits of server capacity. Here an increasing workload model that begins with 3 users and increases according to the specified user distribution to a total of 100 users is used (see Figure 33). Although one agent machine would be satisfactory, the virtual users are distributed over three agent machines, as it's expected that Duwamish will be required to handle more users in future test runs. Figure 33 - Setup of an increasing workload Escalating from 3 to 100 Users (62 VUBrowse + 2 VUBuy + 5 VUCreate + 10 VUHome + 21 VUSearch). The total number of users is distributed among the 5 user groups following the user distribution, which is specified in section Specification of Test Scenarios (note the "Max. Vusers" column). The total duration of the increasing phase is 20 minutes (1200 sec), whereas the entire test lasts 30 minutes (1800 sec). SilkPerformer Advanced Concepts 195

202 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test SilkPerformer uses the default profile for all user groups (note the "Profile" column). Therefore, SilkPerformer will consider think times during test runs. Collecting System Data As mentioned in the above scenario, there is a bottleneck in the Duwamish application that must be located. Increasing workloads are well suited to such a task. Performance data regarding the increasing number of transactions must be cross-referenced with performance data regarding the usage of system resources on the machines that host Duwamish. Relevant transaction performance data include actual throughput, response times, transaction errors, and similar data. SilkPerformer collects such data automatically. However, SilkPerformer's Performance Explorer must be configured to collect data regarding the usage of system resources. For the sake of this discussion, the most relevant processes are those of the Web server, the ASP script engine and the COM+ application server that implements the customer service portion of the middle-tier (compare with section Physical Architecture of Duwamish Online ). It's not expected that the database will cause problems, therefore there's no need to advise Performance Explorer to monitor the database server process. Open Performance Explorer and create a new Monitor Report. The system data sources that should be captured during the load test (compare with Figure 34) are: Total CPU usage of the Web server/middle-tier machine CPU usage of the Web server's main process (inetinfo.exe) CPU usage of the Web server's ASP engine (dllhost.exe) CPU usage of the middle-tier process (dllhost.exe) These data sources should be added to the open Monitor Report and Write Monitor Data should be enabled. Performance Explorer will now generate a TSD file with the specified counters. When these preparations are complete, the test can be run. 196 SilkPerformer Advanced Concepts

203 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test Figure 34 - Monitor the server processes CPU utilization Inetinfo - IIS main process; dllhost#1 - ASP Script Engine; dllhost#2 - Duwamish Middle-Tier (synchronous part of Machine 1 in Figure 29 and Figure 31) Analyzing the Results After the load test, all generated time series data are placed in a new Performance Explorer workspace and the data series that represent the CPU usage of the different server processes are compared in a graph (see Figure Figure 35). Analyzing this graph, one can see that the machine hosting the Web server and the middle-tier reaches its peak capacity (CPU usage 100%) at about 60 concurrent users. One can also identify the middle-tier as the bottleneck in the system. The process that hosts the middle-tier objects uses more than 50% of the servers CPU and blocks everything else, including the throughput, once a certain level is reached. Now the middle-tier has been identified as containing a bottleneck. However, the middle-tier performs many tasks. One needs to determine which task in the middle-tier is responsible for the high resource usage. To pinpoint the problem, we need more performance data about each COM function (task) in the middletier. By isolating the problematic task we can expect to gain insight into which optimization will provide the most significant performance gain. To obtain performance data about each middle-tier task, a test that focuses on only the middle-tier needs to be set up. SilkPerformer Advanced Concepts 197

204 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test Figure 35 - CPU Usage of different server processes under increasing load The middle-tier process (the COM+ application server dllhost.exe) utilizes more than 50% of the server's CPU capacity. Middle-Tier Test Testing the middle-tier of Duwamish is more difficult than testing the presentation layer (Web front-end) for two reasons: (1) the middle-tier offers its clients a number of application-specific COM interfaces, rather than a fixed interface as the Web server does, and (2) each action in the Web front-end (e.g., sending a request to the Web server) involves many tasks (functions of COMinterfaces) in the middle-tier. The goal of this test is to get exact response times for each COM function call and identify the functions that consume most of the CPU power. A COM test script (as part of a new COM load test project) that describes the behavior of a middle-tier client is needed. In the case of the Duwamish installation, the client is the COM+ application server that hosts the ASP script engine (see Figure 29 and Figure 31). In other words, during a load test of Duwamish's middle-tier, a replay engine from SilkPerformer replaces a COM+ application server hosting an ASP script engine. To set up an accurate load test scenario for this unusual configuration, some ASP application specifics need to be considered. Structure of an ASP Application In a standard IIS 5.0 configuration, an ASP application is configured to run in a process that's separate from the IIS main process. This process is actually the COM+ application server (dllhost.exe), which hosts the ASP script engine, which in turn interprets ASP applications. This configuration ensures that the IIS main process will keep running and be able to reinitialize the ASP application if the application server crashes. 198 SilkPerformer Advanced Concepts

205 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test When using default parameters, IIS 5.0 spawns up to 25 independent worker threads. So, as many as 25 threads may be responsible for handling incoming custom requests. In addition, IIS 5.0 offers an intelligent mechanism that limits the number of concurrent worker threads to a value that utilizes the CPU as efficiently as possible. When the queue of open requests reaches a specified limit, no further worker threads are created because they would lead to higher CPU load, which in turn would negatively impact the responsiveness of the Web server. The application server that hosts the ASP application deploys the same number of threads as the IIS. For a realistic load test, it's essential to simulate the COM+ application server that hosts the ASP application as accurately as possible. The first step toward this goal is the creation of a COM load test script that simulates a single ASP worker thread. Following that, SilkPerformer's replay engine needs to be set up to run as many threads as the application server hosting the ASP script engine runs. Preparing the Recording Session To create the COM load test script, SilkPerformer's COM recorder captures the traffic that's produced by the ASP script engine under the load generated by a single user. As mentioned above, the ASP script engine is loaded in an instance of the COM+ application server dllhost.exe. Because several instances of the application server can run on one machine, each possibly hosting an ASP script engine, the recorder doesn't know which instance of the application server to monitor. Therefore, the Duwamish ASP application must be reconfigured in such a way that it's loaded into its own distinguished instance of the COM+ application server. That will be the one COM+ application server that the recorder can uniquely hook into. The Duwamish ASP application needs to be separated so that it runs in its dedicated COM+ application server. As this is not a common procedure, the details are outlined below: SilkPerformer Advanced Concepts 199

206 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test 1 Open Internet Information Services (Start/Administrative Tools) and, in the Action menu, open Properties for the Duwamish virtual directory (see Figure 36). Figure 36 - Configuring the Duwamish ASP application Each virtual directory installed in the Internet Information Server can be configured independently. 200 SilkPerformer Advanced Concepts

207 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test 2 On the Virtual Directory tab, change the "Application Protection" property to "High (Isolated)," indicating that the ASP script engine for this application will run in its own instance of the COM+ application server (see Figure 37). Figure 37 - Duwamish ASP properties By changing the isolation level to "High (Isolated)", the ASP application no longer shares a COM+ application server with other ASP applications on the system - it uses its own instance. Once the new properties have been saved, Duwamish appears in the Component Services manager as a new COM+ application. Open the Component Services manager (Start/Administrative Tools) to configure the newly created application as required. In the Component Services manager, SilkPerformer Advanced Concepts 201

208 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test search for the entry "IIS-{Default Web Site//Root/Duwamish}", which is located in the "COM+ Applications" folder (see Figure 38). Figure 38 - Configuring a COM+ application "IIS-{Default Web Site// Root/Duwamish}" is a COM+ application. Each COM+ application installed on the system can be configured using the system's Component Services manager. In the menu bar of the Component Services Control application (see Figure 38), select Action and open Properties. Under the Advanced tab, select Enable 3G support (see Figure 39). This setting is commonly used to give applications additional memory, but the benefit here is that the application will no longer run in the dllhost.exe process, but rather in dllhst3g.exe. This enables the recorder to hook the Duwamish application process in dllhst3g.exe without any interference 202 SilkPerformer Advanced Concepts

209 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test from other applications, because dllhost3g.exe isn't used as a COM+ application server on typical W2k machines. Figure 39 - COM+ properties for Duwamish ASP application By enabling 3GB support, the ASP application of Duwamish "IIS- {Default Web Site//Root/Duwamish}" runs in a unique application server dllhst3g.exe. Once the changes are applied, return to SilkPerformer and create a new application profile to record the ASP application's calls to Duwamish's middletier. Give the application profile a name (e.g., "Duwamish ASP application") and specify the unique COM+ application server dllhst3g.exe as the client application (located in C:\WINNT\System32). Since the middle-tier provides its services as functions of COM interfaces, change the application type to Custom Application and select COM as API (see Figure 40). This instructs SilkPerformer's recorder to monitor each COM SilkPerformer Advanced Concepts 203

210 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test call issued by Duwamish's ASP application. However, in this configuration, the recorder still probably can't generate test scripts. Figure 40 - Creating a profile for a COM application SilkPerformer's recorder needs to capture all of the Duwamish application's COM traffic. To generate test scripts, the recorder needs descriptions of the COM interfaces (types) in the form of COM type libraries. Specifically the recorder needs to be provided with the type library that describes the relevant COM interfaces. For the requirements of this load test, the interfaces of the middle-tier's outermost COM component WFL (recall Figure 31) are most relevant. The corresponding type library is contained as a resource in the component container D5WFL.DLL. Click the Interfaces button to open the Server Interfaces dialog and load all interface descriptions from D5WFL.DLL (see Figure 41). Note "D5" stands for Duwamish Phase 5. Duwamish online is the 5th most powerful version in a series of Duwamish implementations. So for example, WFL in Figure 29 actually means D5WFL. Likewise, the names of all the other components of Duwamish 204 SilkPerformer Advanced Concepts

211 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test online (BLL, DAL, QWFL, FWFL) begin with D5. In the case of Duwamish, all component containers (DLLs) include COMinterface descriptions (type libraries) as resources. Figure 41 - Add the Duwamish workflow type library SilkPerformer's COM recorder needs the type library to correctly interpret the COM traffic. SilkPerformer's replay engine also needs the type library, but only for type checking. Recording the ASP Application Now the COM traffic between the ASP application at the front- end and the workflow components in the middle-tier can be recorded. The recorder only needs to hook the right COM+ application server (dllhost3g.exe). If the application server at the front-end is still running, it must be stopped. Open the IIS service manager again, open the Properties for the Duwamish application, and click the Unload button in the bottom right of the Properties dialog. This shuts down the application server containing the ASP script engine. Following that, start up the COM recorder, open the Web browser and click on the Duwamish Web page. This launches the application server, but this time it's dllhost3g.exe rather than dllhost.exe. Because of the earlier-defined settings, the recorder automatically gets a hold of the application server and begins to generate a test script. SilkPerformer Advanced Concepts 205

212 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test Now the usage scenarios are recorded as specified in section Specification of Test Scenarios. Again, a separate script is created for each usage scenario. This ensures that virtually every call that relates to a certain transaction will be captured. Then follow the steps of a usage scenario (as specified in section Specification of Test Scenarios ), generate and save the resulting script, shutdown the Duwamish ASP application, clear the recorder tabs and start up the ASP application again. With this procedure you get a separate script for each (specified) Duwamish use case. Finally, the different test scripts are merged into a single script with one transaction for each use case. As with the previous Web load test, the new load test script must be customized. This time Customizing user data and Customizing user behavior are customized. 1 Customizing user data: When running HTTP load tests with SilkPerformer, the customization process is relatively simple. HTTP is a simple protocol that allows data transfer by a fixed set of standardized functions. That contrasts with COM, which is a generic protocol that allows data transfer with a set of application specific functions. Session identifiers, for instance, can easily be detected and customized in HTTP test scripts, but not in COM test scripts, as they are modeled as part of application specific interfaces (as in Duwamish). In Duwamish, the middle-tier assigns a unique ID to each user during initial login. This ID also appears in recorded COM scripts. Therefore the script needs to be modified so that each virtual user uses the ID that was assigned by the middle-tier at runtime. Without this, the script won't replay because the hard coded ID will be invalid and the server will reject the requests. Additionally, modifications similar to those that were applied in the HTTP load test script need to be applied and the products that the virtual user buys must be randomized. 2 Customizing user behavior: As with the HTTP load test, the script needs to be modified to simulate the behavior of a real client. In this case, the client isn't a real user sitting in front of a Web browser, but rather an ASP script engine in a COM+ application server. That complicates things because the test scripts won't reflect the intuitive behavior of Web front-end users, but rather the artificial behavior of an ASP script engine. With hundreds of users connected to a server on which just a few concurrent ASP engines are running, each ASP engine handles several user requests in parallel. This means that an ASP engine must first handle a part of user request A, then the same engine must handle a part of user request B. Consequently, each ASP script engine handles all request types. Therefore, different SilkPerformer user groups don't need to be created to simulate the ASP script engines. In this case it's sufficient to establish one user group in 206 SilkPerformer Advanced Concepts

213 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test which all the different transactions are performed. For each transaction type, simply specify the different execution counters according to the distribution specified in section Specification of Test Scenarios. Running the COM Test Despite having recorded and customized the test script, preparation for the load test is not yet complete. The number of IIS worker threads that the COM replay engine should simulate needs to be defined because these worker threads can be seen as the true clients of the middle-tier. However the exact number of IIS worker threads isn't known. Therefore, a test with an increasing workload must be run to determine the number of threads in the COM replay engine that, during a test run, would produce the specified load in the same manner that IIS 5.0 would during normal operation of Duwamish. The increasing load test begins with one virtual user (a single thread in IIS) and steadily increases the number of virtual users (the number of worker threads in IIS) to a maximum of 25. Following this, Performance Explorer is set up to monitor the CPU usage of the middle-tier server so that the CPU usage data can be correlated with data regarding transaction performance. Figure 42 shows that the CPU of the middle-tier is loaded to about 70% with 5 virtual users. This indicates that 5 users will create an adequate amount of load for our second test run. Figure 42 - CPU usage of the middle-tier under increasing load. For the next test, the workload model is changed from increasing to queuing, the maximum amount of concurrent users is set to 5, a total simulation time of 3600sec is specified, and the transactions are run according to the specified distribution plan. With this model, the test run provides an almost realistic workload for the middle-tier during an hour of operation. This test helps determine if the middle-tier can handle the required number of transactions and - more significant to this test - reveals which middle-tier task(s) use the CPU the most. SilkPerformer Advanced Concepts 207

214 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS First Load Test Note To run all virtual users in a single replay engine (like the real client, the presentation layer of Duwamish, where all worker threads run in IIS 5.0 or the application server hosting the ASP script engine, see Figure 31), the SilkPerformer system setting "Virtual users per process" needs to be set to "5." Analyzing the Results Again, the goal here is to pinpoint the most time-consuming middle-tier tasks (COM functions) during a typical usage scenario. These tasks will be candidates for optimization in the next development cycle of Duwamish. So, the most important thing is to compare the response times of the different COM function calls, the number of total calls for the individual functions, and the total call time for all functions of each specific type. The Performance Explorer provides the necessary data (see Table 9-1). Number Response Time in sec COM Function Name of Calls Sum Min Avg Max GetCategories (Late Binding) ,535 0,020 0, ,716 GetDetails (Late Binding) ,269 0,040 0,218 19,748 ProcessOrder (Late Binding) ,608 0,090 9,119 21,010 UpdateSession (Late Binding) ,433 0,020 0,128 3,024 GetSession (Late Binding) ,837 0,020 0,111 17,595 GetSearchResults (Late Binding) ,041 0,030 0,056 0,491 CreateNewAccount (Late Binding) ,296 0,040 0,206 1,633 InsertSession (Late Binding) ,513 0,020 0,135 1,082 LogOnAccount (Late Binding) ,612 0,020 0,129 0,551 GetShippingAddresses (Late Binding) ,293 0,020 0,108 0,511 GetCreditCards (Late Binding) ,584 0,020 0,105 1,012 Table 9-1: COM Function Response Times When running a COM load test, SilkPerformer automatically gathers response times of COM function calls. These response times can be examined using Performance Explorer. 208 SilkPerformer Advanced Concepts

215 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Applying Optimization The "GetCategories" COM function is in first place in terms of total call time during the one hour load test. In second place, with a huge amount of total call time, is the "GetDetails" function. Both of these functions belong to the use case (task) "Category search." Table 9-1 reveals that there are COM function calls that, on average, take more time to be executed. The reason that "GetCategories" and "GetDetails" take the most overall time however is that they are executed much more frequently than are the others. Applying Optimization These test results point out that catalog browsing and retrieval operations create the bottleneck in this system. Each of these operations performs well - they slow down system performance simply because they are called often. So, one can reasonably conclude that an optimization of the browsing and retrieval operations would deliver a huge performance benefit to the system. This is why the developers of Duwamish inserted a cache in their application. The purpose of the cache is to store the XML strings that are returned by the catalog browsing actions. Future requests for the same category don't go to the middletier (see Figure 43) if the cache already contains the required data. In the Duwamish example, as in most every other Web store, data in the catalog doesn't change that often - possibly once a week or less. Therefore, it's useful to cache even dynamically created data and only flush the cache when the product set changes. Figure 44 shows the physical architecture of Duwamish with the newly introduced cache component. Figure 43 - Category search with/without cache With the cache in place, the ASP application queries the middle-tier for a specific category or product only once after the product set is updated. The SilkPerformer Advanced Concepts 209

216 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Second Load Test presentation layer forgoes a roundtrip to the middle-tier when the cache contains the category or product. Figure 44 - Physical architecture of the ASP application with cache The cache component is directly loaded into the process (instance of COM+ application server) of the ASP script engine. This configuration avoids out-of-process round trips. Second Load Test With the cache in place, a second system load test is run from Duwamish's frontend (at the HTTP level) because the impact of the cache on overall system performance needs to be checked. Then the efficiency of the optimized version of Duwamish can be compared with the original version. Because the cache changes the behavior of the client and thereby the behavior of the COM replay engine, the usage scenarios must be recorded in the same way they were recorded in the first Web load test. The recorder is again loaded into the application server that hosts the ASP script engine. But this time it must additionally monitor calls of the cache object. Then the test script is customized and the COM replay engine (simulating the ASP script engine) is configured to load the cache object. The same SilkPerformer setup that was used for the first Web load test can be used for the remainder of this load test. Performance Comparison To detect and interpret deviation, test results should be compared side by side. After the test run, a new Performance Explorer workspace is created and the two TSD files of interest (HTTP load test with and without cache) are added. When creating a new chart, enable the Overlay series checkbox in the charts property dialog (right click in the chart area and, under the Chart tab, select Properties). This way the results of different test runs can be dragged and dropped into a single chart. Performance Explorer assumes that all graphs begin at the same time. As a result, the following chart, which relates transactions per second in 210 SilkPerformer Advanced Concepts

217 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Performance Comparison both configurations with the number of virtual users, is presented (see Figure 45). Figure 45 - Throughput comparison of the Duwamish application with and without cache The amount of concurrent users increases by 5 each minute. One can readily see that the system with the enabled cache component scales to a wider range than the system without the cache. In the chart without the cache, the maximum throughput is reached when about 50 to 60 concurrent users connect to Duwamish, whereas with the enabled cache, the throughput rises along with the number of users. One more load test is run to determine the maximum number of users that Duwamish can handle with the cache in place. Again, a test with increasing load is set up, however this time with a higher number of virtual users in the last stage. Figure 46 shows the result of this load test. The maximum number of transactions per second is reached at about 150 concurrent users. Figure 46 - Throughput with cache Maximum throughput with the cache enabled is reached at about 150 concurrent users. SilkPerformer Advanced Concepts 211

218 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Back-End Test It can be concluded that the cache component considerably improves the system's performance. As soon as the different catalog queries are cached, the ASP engine no longer needs to go to the middle-tier. This puts less strain on the middle-tier components and results in a considerable performance gain for all the middle-tier tasks. Back-End Test Because of the improved performance of Duwamish's middle-tier, it's now conceivable that the back-end (i.e., the database server DBS) could become a bottleneck. Though this isn't the case in this example, in complete load test scenarios, one should perform thorough back-end testing. In the case of Duwamish, the DBS is encapsulated in a COM component called DAL.DLL (Data Access Layer, recall Figure 29). The DAL connects to the DBS via ODBC. With SilkPerformer, there are basically two starting points from which to run load tests against the DBS: 1 Load test at the DAL interface: In this example the performance of the DBS is tested via the COM component DAL, DAL.DLL represents the server and BLL.DLL represents the client. BLL and DAL are both COM components running in the same process: in an instance of the COM+ application server. From the client's (BLL's) point of view, DAL is a typical COM inprocess server. For a load test of the DBS at the data access layer (DAL), a COM load test must be set up with an instance of the COM+ application server as the client process (or dllhost3g.exe to uniquely identify the process the recorder should hook, see section Preparing the Recording Session for details). And SilkPerformer must be parameterized with the server's type library (which is contained in DAL.DLL). In addition to this filter criteria, SilkPerformer's recorder may be forced to focus only on calls of in-process servers - to keep the generated BDL script as small as possible (disable Recorder Settings/ COM/Filter/In-process server). With such a generated script, the load test can proceed as usual. 2 Load test at the ODBC interface: The DB server could just as easily be tested at the ODBC level. To do that the ODBC traffic between the DAL component and the SQL server would be recorded. This could be achieved with SilkPerformer's ODBC support by monitoring the ODBC API calls that the client (in this case the Duwamish DAL) issues. With the resulting script, a subsequent load test could be run against the DBS to identify ODBC statements that don't perform well with this particular test data and usage scenario. 212 SilkPerformer Advanced Concepts

219 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Testing Duwamish Online - A Case Study Testing Duwamish Online - A Case Study This section recounts some of the authors' experiences in implementing the procedures outlined in this chapter: "When we ran the first Web front-end test and increased the number of virtual users, we were confronted with a significant performance problem. What we experienced was a rapid increase of transaction response times, while at the same time the CPU usage on the server decreased considerably (see Figure 47). We were unsure of the cause of this problem: Had we set up the load test correctly? Did we have all the necessary information regarding Duwamish's configuration? Was there a bug in Duwamish? Figure 47 - Results of the first increasing load test We experienced simultaneous increased response time and decreased CPU usage. Was there a locking problem in the system? These are challenging times for testers, especially when they can't contact developers directly. We thoroughly checked our Duwamish configuration and found no obvious errors in the setup. We concluded that the problem must be in the Duwamish system or the Web server itself. As such odd behavior often indicates a locking problem on a server, we wondered if perhaps all worker threads were waiting for the same resources. Indeed, after researching the problem further, we found an article about Contention and Scalability in Duwamish that discusses the same problem we'd encountered. The authors invested a huge amount of time in debugging the Duwamish middle-tier and discovered that the ASP engine in IIS 5.0 does in fact have a locking problem. The ASP function Request.QueryString() (among others) waits for resources it doesn't need and causes performance bottlenecks. This bug has since been reported to the MS development team but, to our knowledge, no fix is yet available. What could we do to bring the test to a positive conclusion? With regard to our testing goal, a positive conclusion would be one that clearly shows the SilkPerformer Advanced Concepts 213

220 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Glossary advantages of the optimized version of Duwamish over the original version. However because of the locking problem, we couldn't test Duwamish at all! Intensive testing showed that the problem only presents itself when more than a specific number (about 5 to 7) of virtual users performs the order transaction simultaneously. The problem is that the URL query string becomes quite long when it proceeds through the order transaction. To avoid the locking problem in which a number of virtual users perform identical order transactions simultaneously, we introduced 5 different user groups in which each group performs only a single specific transaction. In this way, we attained a distribution of different transactions that avoids the risk of having many users perform the same order transaction simultaneously - only 2 out of 100 virtual users order items (perform the shopping transaction). Thus we were able to perform the load tests as described. Though with this slight modification of the user distribution we weren't able to perform an accurate load test. In real-world production conditions, it's possible that the Duwamish application could experience exactly the type of load we've avoided with such an unrealistic workload model. Therefore, one must keep in mind that these test results are not real world test results. Therefore, the correct conclusion of our tests is that the Duwamish system, deployed as described, cannot handle real world traffic because of a bug in the ASP script engine - an important error in the implementation of Duwamish. So, the bottom line is that our tests were successful in every respect, because the end goal of any test should be to find errors!" Glossary ADO ASP BLL DAL FWFL IIS MSMQ QWFL WFL ODBC This section contains a short description of some of the abbreviations used in this document. ActiveX Data Objects Active Server Pages Business Logic Layer Data Access Layer Fulfillment Workflow Layer Internet Information Server Microsoft Message Queue Queued Workflow Layer Workflow Layer Open Database Connectivity 214 SilkPerformer Advanced Concepts

221 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Glossary SilkPerformer Advanced Concepts 215

222 9 LOAD TESTING MICROSOFT BASED DISTRIBUTED APPLICATIONS Glossary 216 SilkPerformer Advanced Concepts

223 10 Load 10 Chapter Testing COM and ADO Based Applications What you will learn This chapter contains the following sections: Section Page Overview 217 Basic Concepts 218 Enhancements in SilkPerformer 220 Recording 223 Replaying 241 Monitoring 243 Tips & Tricks 243 Glossary 247 Overview This paper explains the basic concepts of COM load testing and discusses some of SilkPerformer's new features. This paper builds upon the concepts explored in the Load Testing Microsoft Technologies white paper by detailing recent innovations and examining SilkPerformer's functionality-which includes improved support for ADO (ActiveX Data Objects) interfaces. This paper guides you through a tutorial that explains how to record/replay both normal COM and ADO applications. It also introduces you to TrueLog Explorer's new database interface and offers suggestions for simplifying your work with COM. SilkPerformer Advanced Concepts 217

224 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Basic Concepts Memory Usage of COM/ADO Virtual Users Each virtual user running in its own process requires approximately 4.5 MB system memory. Running more than one user per process results in the following memory consumption: 25 vusers: Approx. 1.1 MB per vuser 50 vusers: Approx. 1.0 MB per vuser Basic Concepts Microsoft's COM/DCOM technology seems to be one of the biggest challenges in load testing. The most significant issue that has come to light since COM support has been available in SilkPerformer is that applications that require load testing aren't designed to be load tested. COM provides numerous features and "open doors" that offer developers much flexibility in working with it. Although SilkPerformer supports most COM functionality, it isn't possible to cover it 100%. What Cannot be Tested There are a number of components that cannot be tested at all and many others that can only be tested after significant preparatory work. ActiveX controls (OCX) ActiveX controls are GUI controls that are based on COM technology; to be more specific, ActiveX controls implement special COM interfaces so that they can be used by any programming or scripting language on the Windows platform while requiring minimal preparatory work. It's possible to record COM traffic generated by client applications on ActiveX components, however it doesn't make sense to load test such GUI components. In the case of ActiveX controls, which require container objects, it's not even possible to execute single user tests, as the virtual users that SilkPerformer executes don't simulate such container objects. So when you record COM traffic by hooking into a GUI application, ensure that you don't add type libraries of OCX controls to application profile settings as these calls will be recorded but won't be of much use due to the issues explained above. 218 SilkPerformer Advanced Concepts

225 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Basic Concepts COM callbacks COM has a callback mechanism that allows COM components (servers) called by client applications or other COM components (clients) to call back callers. Clients need to implement a special callback interface that must be registered on servers before they can call methods on this interface. If you were to record such a client application you would get a script in which the client invokes a method on the server, which in turn calls back to the client. During replay the virtual user process becomes the client application, which needs to provide a callback interface to the server. The problem is that these interfaces aren't implemented and therefore callback interfaces can't be registered on the server. A common scenario for callbacks is a progress status indicator when a client application executes a time-consuming method on a server. The server notifies the client about progress status via the callback interface and the client then forwards the information to the end user by updating a progress bar. In this scenario the server doesn't rely on such a callback interface and so works properly-there is no problem with load testing this server component. The problem occurs when the client implementation of the callback interface executes additional COM calls to the server when it is called; it requires that SilkPerformer do the same thing-otherwise the semantics of the user transaction will be broken. If the implementation of a callback interface is extracted to a COM component and not implemented in a GUI application's client code, then there is also no problem for load testing, as SilkPerformer will record the creation of the COM object and pass the callback interface to the server. The problem is that in most cases, callback interfaces are implemented in GUI code and are not, as good application design would dictate, extracted to external components. Components that aren't designed for load testing COM components that are utilized by client applications running either inprocess or out-of-process on the same machine often aren't designed to be load tested. These components are designed to handle single client instances; if you were to record COM traffic and run a load test, you would bring the component to a state for which it was not designed. D(COM) components running on servers and serving multiple clients are however designed for load testing. Be aware that load testing should only be executed against components that are designed to handle multiple clients SilkPerformer Advanced Concepts 219

226 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Enhancements in SilkPerformer Enhancements in SilkPerformer SilkPerformer introduced major enhancements for the COM framework, particularly for ADO interfaces because ADO is now treated as a database interface, allowing you to use the same features that are available for other database interfaces (ODBC, OCI, etc.), including database TrueLogs and result set handling. Several new API methods have also been introduced to allow for ADO record set fetching and the setting of SQL statements and ADO parameters. Moniker Support Monikers in COM allow you to bind objects that share moniker names. Objects can be either previously instantiated objects, nested objects, or objects generated by a special moniker implementation. Instead of having a Visual Basic application that uses a GetObject method to bind to an object, SilkPerformer provides recording and replay support for the most common COM-moniker functions. Example Basic COM Function Enhancements It's now possible to call a COM method that doesn't take parameters with individual ComCall method calls for the three former calls (ComFunction, ComCall, and ComFree). The SilkPerformer recorder scripts this enhanced ComCall method when you check Enhanced function calls in recording profile settings. Without Enhancement ComFunction(hFunc0, hiface0, "Close"); ComCall(hFunc0); ComFree(hFunc0); With Enhancement ComCall(hIFace0, 0, "Close"); A second enhancement relates to COM property access. COM properties can be accessed with normal function calls using special access modifiers such as get, put and putrefy. Previously, access to a property required four COM API calls in BDL, with the Enhanced property access option selected in recording profile settings, this can now be done using only a single call. The ComGet{Type} and ComSet{Type} methods have been enhanced to recognize these property access modifiers. 220 SilkPerformer Advanced Concepts

227 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Enhancements in SilkPerformer Example Without Enhancement ComFunction(hFunc0, hiface0, "put:value"); ComSetString(hFunc0, "Value", "mark"); ComCall(hFunc0); ComFree(Func0); With Enhancement ComSetString(hIFace0, "put:value", "mark"); ADO Enhancements Extracting SQL statements Checking this option instructs the Recorder to script AdoSetSql rather than ComSetString when setting a SQL statement to a property or function parameter. AdoSetSql consolidates scripted SQL statements to the dclsql sections of your BDL scripts. So if you select this option you will no longer have long SQL statements hard coded in scripts, they will be centralized in dclsql sections. Example Without this option ComSetString(hFunc0, "Source", "SELECT * FROM Person"); With option AdoSetSql(hFunc0, "Source", TMain_SQL001);... dclsql: TMain_SQL001: SELECT * FROM Person; AdoSetSql is scripted for all properties and function parameters of ADO interfaces that the Recorder recognizes as SQL statement prospects. Fetching ADO recordsets By selecting Fetch ADO recordsets the Recorder only scripts one AdoFetch statement when fetching multiple rows. Compare the previous and new scripting approaches for the following Visual Basic Code: While not rs.eof name = rs.fields("name").value age = rs.fields("age").value SilkPerformer Advanced Concepts 221

228 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Enhancements in SilkPerformer rs.movenext Wend Without this option // The following code will be recorded for every record that will iterated by the client application ComGetBoolean(hIFace0, "get:eof"); ComGetInterface(hIFace0, "get:fields", hiface1, "Fields"); ComFunction(hFunc0, hiface1, "get:item"); ComSetString(hFunc0, "Item", "Name"); ComCall(hFunc0); ComGetInterface(hFunc0, "Item", hiface2, "Field"); ComGetString(hIFace2, "get:value", svalue); ComGetInterface(hIFace0, "get:fields", hiface1, "Fields"); ComFunction(hFunc0, hiface1, "get:item"); ComSetString(hFunc0, "Item", "Age"); ComCall(hFunc0); ComGetInterface(hFunc0, "Item", hiface2, "Field"); ComGetString(hIFace2, "get:value", svalue); ComCall(hIFace0, 0, "MoveNext"); With option AdoFetch(hIFace0, ADO_FETCH_ALL, ADO_FETCH_CURRENT, nlength); If the client application doesn't move through the recordset from the first record to the last record, but rather fetches some records then moves to different positions and fetches other records, then the SilkPerformer Recorder will script multiple AdoFetch statements. The Recorder can however merge fetches that fetch successive records. 222 SilkPerformer Advanced Concepts

229 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Example Visual Basic Code Rs.MoveFirst Rs.MoveNext Rs.MoveNext Rs.MoveLast Rs.MovePrevious Rs.MovePrevious Rs.Move 3, adbookmarkcurrent AdoFetches AdoFetch(hIFace0, 3, ADO_START_FIRST, nlength); AdoFetch(hIFace0, -3, ADO_START_LAST, nlength); AdoFetch(hIFace0, 3, ADO_START_CURRENT, nlength, true); Script ADO parameters Parameters are often used to execute ADO commands. ADO parameters must be created and added to the parameters collection of the ADO command interface. There are special API calls in BDL that allow for the definition of the values of parameters and subsequently create those parameters and add them to the collection. This option is required for customizing input values in database TrueLogs as TrueLog Explorer checks for AdoParamSet{Type} methods. To define a parameter it's necessary to first define the value and then create the parameter. For example, the AdoParamSet{Type} calls that precede the AdoParamCreate calls define the values for the following parameter. Example ComGetInterface(hIFace3, "get:parameters", hiface1, "Parameters"); AdoParamSetString("Value", "mark"); AdoParamCreate(hIFace3, "Name", 8, 1, 4, hiface4, "_Parameter"); AdoParamAppend(hIFace1, hiface4); AdoParamSetString defines the value of the parameter. If you have a parameter that takes an array, you can use multiple AdoParamSet{Type} calls to define the individual array elements: Example AdoParamSetString("Value[0]", "mark"); AdoParamSetString("Value[1]", "andi"); Recording Recording COM applications isn't difficult. The biggest challenge is in identifying those COM interfaces that are of interest. As stated in the What SilkPerformer Advanced Concepts 223

230 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Cannot be Tested section, there are a number of interfaces that shouldn't be considered as possible recording interfaces. The interfaces that are of interest here are normal business component interfaces, or in the case of ADO, Microsoft ActiveX Data Objects components (MSADO). Once you have identified the interfaces that are of interest, you need to provide SilkPerformer with the type information for those interfaces. Normally type information is provided in a separate COM type library, a file with the.tlb extension. However this is not the only place where type information can be stored. It's also possible to store it in the COM.dll or.exe. In the case of ADO testing you need to specify the msado15.dll. This.dll can be found in the following directory: \Program Files\Common Files\System\Ado. Recording COM Applications The first step in recording a COM application is creating a new SilkPerformer project of the project type COM, which can be found under the Application Server/Component Models tree node. Figure 48 - Create new COM Project Create a new Application Profile Each application that is to be recorded with SilkPerformer requires an application profile that defines the types of interfaces and technologies that SilkPerformer will need to record on the client side. 224 SilkPerformer Advanced Concepts

231 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording To create a new application profile, open the System Settings dialog (Settings/ System) and click the Recorder icon in the left pane. You will then see a list of preconfigured applications and those that you have configured previously for other projects. Figure 49 - System Settings SilkPerformer Advanced Concepts 225

232 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Create a new application profile by clicking the "Add" button: Figure 50 - Application Profile For the purposes of this paper's tutorial an application profile will be defined for the sample COM application called PersonCOMClient.exe, which can be found in the SilkPerformer subdirectory SampleApps\Com. The working directory will automatically be set to the directory of the.exe program. Choose Custom Application as the application type, then check the COM check box, which tells SilkPerformer that the application should be recorded as a COM application. Click the Interfaces button to specify the type information of the COM objects that are to be tested. Refer to the What Cannot be Tested section to deselect those interfaces that cannot be tested and should therefore not be included in the recording process. 226 SilkPerformer Advanced Concepts

233 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Clicking the Interfaces button brings up the Server Interfaces dialog on which you can add those files (.dll's,.tlbs, etc) that contain the type information for the COM objects used by the client application: Figure 51 - Server Interfaces Our PersonCOMClient application connects to a (D)COM object offered by the PersonCOMServer application. Type information for the (D)COM objects is available in the.exe file itself. Therefore the PersonCOMServer.exe file can be added to the server interfaces by clicking Add and selecting the.exe file that's stored in the sample directory in which the client application is stored. If you expand the type information tree after successfully loading the.exe, you will see all COM interfaces, COM classes, and the COM interfaces that are implemented by those classes. The Class filter option is selected by default. Class filtering means that you can specify that a COM interface be recorded if a COM class implements it. Without class filtering you can only specify if you want to record an interface-regardless of which class implements it. Additional COM filters in PerfComDepend.ini When launching the Recorder to begin recording an application, the interface settings of the application profile are written to a file called extend.ini so that the COM recorder will know which interfaces/classes to look for. The content of the extend.ini file can be extended with custom settings in the PerfComDepend.ini file, which is stored in the SilkPerformer installation directory. This configuration file allows you to define: Settings on the application profile dialog SilkPerformer Advanced Concepts 227

234 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording TypeLibs, Classes and Interfaces Define type libraries, interfaces and classes Filters on the method level You can not only exclude an entire interface, you can also exclude distinct functions of an interface Additional type information that is not available in the type library Mainly used to identify the type of an outgoing pointer or the size of a parameter Note Be sure that a new line follows the last line of your PerfComDepend.ini file. The following sections explain what can be defined, and how. Everything that is achieved by the application profile dialog can be configured manually in the PerfComDepend.ini file. If you want to record a specific type library for all your applications you can define the type library, classes and interfaces that are to be recorded. There are three key words: TYPELIB, INTERFACE and CLASS. "TYPELIB" "=" (FullPathName".exe" FullPathName".dll" FullPathName".tlb") "INTERFACE" "=" <InterfaceName> "CLASS" "=" <ClassName> Keywords need to be listed in a specific order. First there is the type library definition. Than all interfaces that are to be recorded without a special class context are listed. Following that comes the class and the interfaces for that class. Examples: TYPELIB = "MyTypeLib.tlb" INTERFACE = "MyInterface1" INTERFACE = "MyInterface2" CLASS = "MyClass1" INTERFACE = "MyInterface1" CLASS = "MyClass2" INTERFACE = "MyInterface2" Additional Type Information Default PerfComDepend.ini files include additional type information definitions that use the key word RESTRICTED. "RESTRICTED" "=" Function Struct "." Parameter "@" ("size_is" "iid_is" "itf_is" ) ":" Parameter Examples: RESTRICTED = RESTRICTED = RESTRICTED = When do you have to define your own restrictions? 228 SilkPerformer Advanced Concepts

235 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Filters on Methods Example If you are recording a COM interface that passes interfaces with a void** data type, you must tell the Recorder what interface to expect. You can do this by telling the Recorder the parameter that defines the GUID (Global Unique Identifier) of the interface, as in the above example in which the parameter riid defines the interface that is to be passed back in ppvobject of the method CreateInstance of the interface IClassFactory. If you have methods on interfaces that you do not want to record you can specify those methods with the EXCLUDE keyword. This keyword was introduced because recorded ADO scripts were often quite large, containing method calls that were not necessary for replay. As SilkPerformer comes with ADO support, this filtering is no longer necessary for ADO recording, however it may be of use for other interfaces that define methods that are not necessary for replay: EXCLUDE = <InterfaceName> "::" <FunctionName> EXCLUDE = _Recordset::MoveNext EXCLUDE = _Recordset::get:EOF As you can see in the above sample, property access methods must be defined using an accessor prefix (get, put, or putrefy). The exclusion of method calls causes the Recorder to not script appropriate BDL functions for calling methods. You must be careful when using this feature because you may break the semantics of your recorded transaction by excluding COM method calls. However for some interfaces it's possible, as in the case of ADO. Recording the application After closing the System Settings dialog, you can proceed with recording the application. Click the Model Script button on the workflow bar. In the Model SilkPerformer Advanced Concepts 229

236 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Script dialog select the created application profile called COMPerson and click OK. Figure 52 - Model Script When you click OK, SilkPerformer's recorder launches and creates an extend.ini file, as described in a previous section. Following this the Recorder launches the client application defined in the application profile (PersonCOMClient.exe). Once the client application has launched, do the following (Note that these steps are detailed in the COM Tutorial ("Load Testing a COM Application" in the SilkPerformer Tutorial paper): From the Server menu choose Connect Select COM server, machine name localhost, and click OK The COM server application launches Click New to create a new person Enter a name in the dialog Change the properties on the right side (Height, Weight, etc) Finally, search for other persons: enter an asterisk (*) and click GO Browse through the returned names in the list Select Disconnect from the Server menu and close the application Figure 53 - Stop Recording 230 SilkPerformer Advanced Concepts

237 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Click the Stop button on the Recorder and save the generated script to a file. The generated file will then open in SilkPerformer Workbench.. Customizing values Examining the recorded script In the recorded script the Recorder has scripted a user group that loads the type libraries (defined in the application profile) in the TInit transaction. Type information is also required by the COM replay engine to call the COM methods. ComUseTypeLibrary is the BDL-API method used for this action. The TMain transaction includes ComCreateObject methods for those COM objects that the client application has instantiated - in this case it's an instance of PersonCOMServer.PersonManager. The ComQueryInterface method will be scripted when the client application requests a special interface from a COM object. There are two calls to query for the dispatch interface (IDispatch) and the custom interface _PersonManager. Each method that will be called on a COM interface is scripted with a number of functions. The first function is a ComFunction call that creates a function handle for a specific function to call. On this function handle, ComSet{Type} methods can be used to define input parameters for the function call. ComCall then executes the function call with the parameters that have been set on the function handle. After a successful ComCall, the outgoing parameters or return values can be retrieved using ComGet{Type} calls. There is an enhancement for functions that have no input or output parameters. Instead of scripting a ComFunction, ComCall and ComFree to call methods that don't have parameters, you can script one ComCall method, where an additional optional parameter defines the method name that is to be called. If you browse through the script you will find the values you used to create a new person, or to change the properties of a person. You can customize these constant values with random variables, or other variables. A value that should definitely be considered for customization is the name of the person that is to be created. If you don't customize this value, running a load test will result in creating multiple persons with the same name. Customizing scripts is beyond the scope of this paper, though this section will touch on it briefly. To customize the name of the created person, select the first occurrence of the string you have entered and right-click it to open the context menu. Then select Customize Value. Click Next to create a new parameter for the input value. Specify that values be pulled from a multi-column data file. Enter different values for the person's name in the first column (e.g., Mark, Andy, Paul, Simon, etc). Then give the column a more meaningful name (e.g., Personname) by clicking the column header. With the first column selected, click the Next button. SilkPerformer Advanced Concepts 231

238 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Save your changes. Click Next on the following page, accepting the defaults. Notice that the value in the script has been substituted with a variable taken from the multi-column file you created using the wizard. In this way you can add other attributes for the person (such as Height and Weight) and customize other values for the person in the multi-column file. Now find the name of the created person a second time and customize this value also using the same variable you used to create new person entries. To do this select the second occurrence and select Customize Value from the context menu. This time select an existing parameter; choose the parameter that you created earlier and complete the wizard process. Executing a TryScript Run After you have successfully customized the script you should execute a TryScript run. Click the TryScript button on the Workflow Bar, then click Run on the subsequent dialog. One virtual user is executed - performing exactly the same COM operations that the client application performed during recording. The server application logs this activity in its main window, showing you what SilkPerformer is doing in real-time. Recording COM in Web Applications COM is often used in Web applications developed using ASP (Active Server Pages). Recording an ASP application is slightly different than recording a normal client application as there isn't an executable comparable to the PersonCOMClient sample application. ASP applications are hosted in an IIS (Internet Information Server) worker process that handles all HTTP requests, forwarding them to the ASP engine and posting back results to a browser. The client application that must be defined in our application profile is this worker process. There is a different worker process for each version of IIS: Running IIS 5.x The default worker process for ASP applications is inetinfo.exe. This is the main IIS worker process; it handles multiple ASP applications. As you don't want to record all COM traffic triggered by all ASP applications running on a server, you must force IIS to run only the ASP application that you want to record in a separate worker process that can then be used as the client application. IIS provides properties on the Virtual Directories of ASP applications that define the isolation level (Application Protection) of applications. There are three property types: 232 SilkPerformer Advanced Concepts

239 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording LOW (IIS Process) All applications that run on LOW protection are hosted within inetinfo.exe Medium (Pooled) Several applications with MEDIUM protection are hosted within dllhost.exe High (Isolated) Each application with HIGH protection is hosted in its own dllhost.exe The isolation level of virtual directories is defined after applications have been created using the Properties dialog-by clicking Create in the Application Settings section of the dialog. So - after you clicked "Create" in the properties dialog you are able to specify the isolation level. If you specify HIGH protection, it's still possible to have multiple dllhost.exe's runnin on one machine, as other applications running in MEDIUM or HIGH will also be using the hosting application - and the SilkPerformer recorder won't know which one to focus on. To solve this problem, you can specify that our ASP application run in a different hosting application that supports 3GB address space. To define this you must do the following: Select HIGH protection in the Virtual Directory Properties dialog Start Component Services from your Administrative Tools Expand the Component Services tree to include the COM+ applications on your Web server Open the Properties dialog of the Virtual Directory entry On the Advanced tab, select Enable 3GB Support Close the Properties dialog When the Web server is restarted and IIS creates the hosting processes for the virtual directories, your ASP application will be hosted in a process called dllhst3g.exe. Defining the application profile The client application is now dllhst3g.exe. You must define an application profile for this application as was explained for PersonCOMClient.exe. The dllhst3g.exe can be found in the Windows\System32 directory. All subsequent steps for creating a profile are the same. Simply create a new profile, define the dllhst3g.exe as the executable and select those COM type libraries that are of interest to you. SilkPerformer Advanced Concepts 233

240 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Note You will use a browser to access the Web site where you wish to record COM traffic. By default, your browser has a SilkPerformer application profile. To prevent the Recorder from also recording the HTTP traffic of your browser, you must disable your browser's application profile. Simply uncheck the application profile in the System Settings dialog. Recording The SilkPerformer Recorder is only able to record applications that have been launched after the recording process has begun. To record a Web application you must first shut down IIS, start the Recorder, and than start IIS again. The following steps are required: Shut Down IIS Use the iisreset /stop command Start the SilkPerformer Recorder Start the Recorder from the Recorder menu - you don't want the Recorder to start the client application (dllhst3g.exe), as it must be started via IIS Start IIS again Use the iisreset /start command Open your browser and browse to the Web site you wish to record Running IIS 6.x The process model of IIS 6.0-introduced with Windows Server 2003-has changed significantly. All activity is now processed out of the IIS main process in a hosting application called w3wp.exe. IIS 6.0 lets you define application pools. Applications are then assigned to particular pools. Application pools host assigned applications in one or more w3wp.exe containers. It's not possible to specify different hosting processes, as it was with IIS 5.0-at least not with the current process model. However IIS 6.0 allows you to switch back to IIS 5.0 isolation mode-allowing you to define your application with HIGH isolation and specifying 3GB support-making it possible to run your application in a dllhst3g.exe application container. Switching to IIS 5.0 isolation mode Open the Properties dialog of the Web Sites folder in your Internet Service Manager. Click the Service tab and select Run WWW service in IIS 5.0 isolation mode. When you close this dialog IIS will restart automatically. You then must complete the steps described in Running IIS 5.x to record the COM traffic of an ASP application. 234 SilkPerformer Advanced Concepts

241 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Recording ADO Applications ADO (ActiveX Data Objects) is a COM library that allows you to access all database types that offer an OLE-DB Data Provider. A number of OLE-DB providers are installed by MDAC (Microsoft Data Access Components); others are installed with database and client software for databases. Microsoft's intention for ADO is that developers can use a single COM interface for any underlying databases-a concept similar to ODBC. Recording ADO applications is comparable to recording standard COM applications-the only difference is that you must define the type library of ADO in your application profile. The type library or.dll that contains the type information can be found in the following directory: \Program Files\Common Files\System\ADO Defining an application profile The PersonCOMClient sample application is not only capable of connecting to a (D)COM server, it has been enhanced to provide additional functionality by connecting to a database via ADO to manage persons. To record this sample application on the ADO interfaces you must change the application profile that was generated in the Create a new Application Profile section of this chapter: Remove PersonCOMServer.exe from the recording interfaces and add the MSADO15.DLL (\Program Files\Common Files\System\ADO)-thereby telling the Recorder to capture ADO interface traffic. SilkPerformer Advanced Concepts 235

242 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Figure 54 - ADO Interfaces for Application Profile Additional PerfComDepend.ini filters If you have defined any additional COM filters in the PerfComDepend.ini configuration file-as described in Additional COM filters in PerfComDepend.ini -make sure that there are no filters on any of the ADO interfaces. If you have EXCLUDE filters for some of the ADO interface functions it's likely that the new ADO recording support won't work as expected. Recording the application Begin recording the application by choosing Model Script from the Workflow Bar, select the COMPerson application profile and click OK. There is also a tutorial that walks through a complete ADO sample with this client application. You can find the tutorial in the "Load Testing an ADO Application" section in the SilkPerformer Tutorials paper. These are the steps you should follow to record ADO traffic: From the Server menu choose Connect Click Database and select the first entry to connect to a Microsoft Access database that was installed with the sample application. If you wish to connect to a different existing database you must provide an OLE-DB connection string to that database (see the tutorial for further details). If you have selected an empty database rather than the access database, you must select Create Database Tables from the Server menu to create the two tables that are required by the application. Click New to create a new person Enter a name in the subsequent dialog Change properties on the right side of the dialog (Height, Weight, etc) You can store an image for a person by specifying a.gif file and pressing Store Image. Three.gif's accompany the application and are available for upload (man1.gif, man2.gif, and woman.gif). While storing you will be prompted whether or not you wish to use ADO parameters; select Yes (for a detailed description of this application feature, please refer to the tutorial). Enter an asterisk "*" and click GO to search for other persons in the database Select one of the listed persons You can load an image to the selected person by clicking Load Image 236 SilkPerformer Advanced Concepts

243 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording Click Disconnect on the Server menu and close the application Click Stop on the Recorder application and save the generated script to a file. The generated file will then open in the SilkPerformer Workbench Customizing values Examining the recorded script For the most part the script contains only normal COM API calls, as were shown in the example before when recording normal COM interfaces. See Examining the recorded script. The new ADO support introduces some new API functions for ADO recordset handling. Some API method calls begin with the prefix Ado, as in AdoFetch and AdoParamSetShort. Fetching resultsets without the new ADO support results in scripts that are nearly twice as long because moving through recordsets and retrieving values from different fields is done by calling a number of interface methods that are individually recorded and scripted by the Recorder. All fetching is now merged into a single AdoFetch command. ADO parameter handling has also been enhanced with some new API method calls. These new API calls are similar to the API calls of the other database protocols that SilkPerformer supports, allowing TrueLog Explorer to handle all database protocols in a consistent manner. Another helpful feature is that the new ADO functionality makes use of the SQL section of BDL. Each SQL statement that is passed to one of the ADO methods is scripted in the SQL section of scripts, making it easier for QA engineers to see the statements that will be executed. The actual assignment of SQL statements to COM properties or COM parameters is done with the API method AdoSetSql. TrueLog Explorer now offers a common interface for all database protocols. That means that you can customize your values and define your verifications on database resultsets in the same way for each database protocol. This means that there is no need to manually customize scripts; you can now use TrueLog Explorer to achieve for database applications what was previously only possible for Web applications-and all of this is transparent to the user. For a detailed overview of TrueLog Explorer's new database interface, please refer to the TrueLog Explorer User Guide. Now execute a TryScript run to generate a TrueLog from which you can generate script customizations and verifications. After executing a TryScript run-by clicking the TryScript button on SilkPerformer's Workflow Bar and clicking Run-TrueLog Explorer launches, loaded with a database TrueLog that shows different API nodes that indicate SQL-statement executions and resultset fetchings. SilkPerformer Advanced Concepts 237

244 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording To customize the name of the created person, search for the AdoUpdate(AddNew) node and customize the input value via the context menu (as shown below). Figure 55 - Customize Input Value in TrueLog SilkPerformer's Parameter Wizard opens. Create a new parameter based on a multi-column file. Begin by clicking the New File icon. Give the column a meaningful name and complete the remainder of the wizard. Now you must use the selected name for each update statement that will be executed. If you browse through the TrueLog you will see that the client application executes an update statement for each property value change. The primary key for a person is their name. You can tell TrueLog Explorer to customize your script by correlating the returned name after creating the person. This is done on the same API node where the input value is customized. To perform data correlation, choose Find Correlation from the context menu on the output Name column. TrueLog Explorer will then search for occurrences of the value ("mark" in this case) in all subsequent calls. If TrueLog Explorer finds 238 SilkPerformer Advanced Concepts

245 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording the value as an input parameter it will automatically generate a parsing statement to copy the value from the resultset and replace the input value with the parsed variable: Figure 56 - Find Correlation SilkPerformer Advanced Concepts 239

246 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Recording The next dialog shows all occurrences that have been found at a node where the value is used as input parameter. Select all occurrences and click Customize: Figure 57 - Customize after Correlation In the modified script, TrueLog Explorer has now parsed the name from the resultset of the insert statement using the BDL code: sparam1 := RsGetString("1", 1); sparam1 is used as an input parameter for all update statements in the script that used the value "mark". If you browse through the TrueLog nodes you will see that all input parameters that have been customized are now displayed in greenmaking it easier for you to see what has been customized. Now execute another TryScript run to test the customized script. Alternatives to ADO Recording ADO can be used to access all types of databases, including Microsoft Access, SQL Server, Oracle, ODBC Datasources, and more. Although there has been improvement with ADO support in SilkPerformer, it is still recommended that you record on the lower level if possible. This means that if a client application connects to Oracle or to an ODBC data source, you should use Oracle or ODBC recording rather than ADO recording. The reason for this is that you will receive smaller and easier to read/customize scripts, because you won't have the entire COM overhead-they will be pure database scripts. So whenever your application connects to ODBC or Oracle, define your application profile in such a way that it records those database interfaces and not ADO. For all other databases, ADO is the best choice. 240 SilkPerformer Advanced Concepts

247 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Replaying Binary Data Binary data in COM is normally passed as a SAFEARRAY containing Bytes. The COM Recorder has been enhanced to recognize these arrays and now scripts ComSetBinaryFromFile so that it pulls binary data from a file (generated during recording) that includes the binary data that was passed to the COM interface. The script recorded during ADO recording has a constant named BINARY_ FILE0, which is used in the script by ComSetBinaryFromFile or AdoParamSetBinaryFromFile (depending on whether or not you used ADO Parameters to store the image). The Recorder has generated this binary file in a project directory but it has not yet added it to the data file section. Note Currently you must manually add generated binary files to the data file section-otherwise they won't be copied to remote agents during distributed load tests. This workaround will be automated in future versions. Replaying In the previous section's tutorials you learned about replaying recorded scripts. The following sections explain replay issues that have not yet been addressed. Common Replay Issues Incompatible array types Whenever an array is passed to a method, the SilkPerformer recorder records a method for setting SAFEARRAY boundaries, followed by methods for setting the distinct values of the array. During replay, the first element type determines the type of SAFEARRAY. This means that the following code fragment would define a SAFEARRAY of strings: ComFunction(hFunc0, hiface0, "OpenSchema"); ComSetBounds(hFunc0, "Restrictions", 1, 2); ComSetString(hFunc0, "Restrictions[2]", "person"); This special ADO method will return an error because it doesn't expect a string SAFEARRAY. It expects a SAFEARRAY of VARIANT's. The Recorder is not currently able to script the ComSetType method to declare an array as a VARIANT array-this must be done manually. SilkPerformer Advanced Concepts 241

248 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Replaying The final code fragment should look like this: ComFunction(hFunc0, hiface0, "OpenSchema"); ComSetBounds(hFunc0, "Restrictions", 1, 2); ComSetType(hFunc0, "Restrictions", COM_TC_VARIANT); ComSetString(hFunc0, "Restrictions[2]", "person"); The ComSetType method call must appear directly after the ComSetBounds that defines the bounds of the dimensions. How can you determine if a VARIANT array is required? You can check the recorded log file to see what type of SAFEARRAY has been passed to the function. Log information for the above call looks like this: ENTER(0), THREAD 0: _Connection[1610dd8]->OpenSchema ( Schema:SchemaEnum=4 Restrictions:VARIANT={SAFEARRAY= {[0]:VARIANT={EMPTY}, [1]:VARIANT={EMPTY}, [2]:VARIANT={BSTR="person"} }} SchemaID:VARIANT={HRESULT= } ) Errors occurring during recording No Records returned Invalid handling errors There are several reasons why errors may occur during recording. It's possible that an error occurred during recording and that the error wasn't caught by the application and handled there. Check recording logs to see if an error was returned by either the current function or a previous function. If you're testing an ADO application, ensure that you have the same state in the database during your load test as you had during recording. If for example you delete records during recording, those records won't be available for deletion again during the load test-and you'll receive an error during the test. Differences between TryScript runs and Load Tests Just because a TryScript run works correctly doesn't mean that you can't run into problems during load tests. ADO applications in particular are likely to exhibit different behavior between TryScript runs and load tests as there are multiple database connections and multiple SQL operations on the same tables that can cause deadlock situations and other database problems. 242 SilkPerformer Advanced Concepts

249 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Tips & Tricks You will also soon find out if the (D)COM components that run well for one user also run as expected when multiple users connect to them. They will run as expected only if they are thread- and multi-user safe. ADO Replay - Database TrueLogs All supported database interfaces (ODBC, OCI, ADO, etc.) can now generate database TrueLogs, allowing you to customize your scripts within TrueLog Explorer. You can define verifications and parse values-truelog Explorer even helps you correlate input and output values that differ between record and replay. These features all but eliminate the need for manual script customizations. For details regarding the use of database TrueLogs, please refer to the TrueLog Explorer User Guide. Monitoring There aren't any special measures for COM or (D)COM that can be queried with Performance Explorer. So you must manually monitor system statistics such as CPU, disk IO, threads, etc. If you have an out-of-process COM component you should measure the process that hosts the component-for the sample application shown previously, this would be PersonCOMServer.exe. Tips & Tricks Identifying interfaces for recording (the easy approach) The SilkPerformer Recorder can log all COM objects that the client application uses but however aren't currently recorded because they aren't specified in the application profile. This additional logging can be enabled using the recording profile options of your SilkPerformer project: check Show missing type information to enable this feature during recording. SilkPerformer Advanced Concepts 243

250 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Tips & Tricks Figure 58 - Missing Type Information Option If you have changed this setting simply define an application profile for your client application (as described in the Create a new Application Profile and Defining an application profile sections of this paper) without adding any additional type information in the server interfaces dialog. Begin recording your application and go through your testing workflow. When you're done, look at SilkPerformer's recorded log file: Figure 59 - Enlarge Recorder GUI Click the Recorder's Change GUI Size button and select the Log tab. There you will find entries similar to the following: Status: info (COM): no type info available for class "Microsoft StatusBar Control, version 5.0 (SP2)". Status: info (COM): no type info available for class "Microsoft StatusBar Control, version 5.0 (SP2)". Status: info (COM): no type info available for class "PersonCOMServer.PersonManager". 244 SilkPerformer Advanced Concepts

251 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Tips & Tricks You also receive information about COM objects that you aren't interested in recording, such as Microsoft's Status Bar control. As mentioned in What Cannot be Tested, these OCX controls aren't appropriate for testing-simply ignore them. The last element of status information tells you that the application uses a COM object with the ProgId PersonCOMServer.PersonManager. Finding responsible Dll/Exe's You must give the Recorder the type information of the COM object you wish to record. In this case you need to find the type information of PersonCOMServer.PersonManager. ProgId's are stored in the registry. Run regedit and browse the registry. Open the HKEY_CLASSES_ROOT hive and you will find a subkey with the ProgId you're looking for. There is a subkey called CLSID-you'll need this value for further investigating. Figure 60 - Lookup ProgId The CLSID {BA8A8088-FA9F-4558-AF1D E00916} is the unique identifier of the COM object you're looking for. For the implementation.dll or.exe you must look up this value under the CLSID hive of the HKEY_ CLASSES_ROOT. You're looking for the following key: HKEY_CLASSES_ROOT\CLSID\ {BA8A8088-FA9F-4558-AF1D E00916} When you find this key and expand it, you will see a subkey called either LocalServer32 (for out-of-process servers) or InprocServer32 (for in-process servers): Figure 61 - COM DLL/EXE Lookup You now know that the COM object is implemented in this.exe file. You can now go back to your application profile and add this.exe to the recording interfaces. SilkPerformer will either get the type information from the.exe file (if it is stored there) or it will find the type library based on the information in the registry. Looking at the last key you operated on, you will see a TypeLib subkey SilkPerformer Advanced Concepts 245

252 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Tips & Tricks that specifies another CLSID that you can use to look up the TypeLib information. You'll need to search in HKEY_CLASSES_ROOT\TypeLib. If you were to continue searching in the TypeLib key, you would find that the type information is stored in the.exe and not in a separate.tlb file. Identifying interfaces for recording (the difficult approach) There are often situations in which a test engineer needs to test a COM application without having any knowledge of the COM objects that the application uses. The best way to handle this problem is to go to the developers and ask them what the business components of the application are: which interfaces are callbacks that can be excluded and which components are not of interest for testing. Unfortunately it's often the case that developers aren't involved in the testing process and can't or won't give hints as to which interfaces should be recorded. Process Explorer An effective tool called Process Explorer, which investigates the running processes and lists all loaded.dll's and other system resources that an application consumes, can be downloaded from For your purposes here, it's useful for finding out which COM.dll's a client application loads. Follow these steps: Install Process Explorer Start Process Explorer Start your client application Work with your client application to a point where you can be sure that the COM objects of interest have been accessed Within Process Explorer, look for your client application and select it In the Process Explorer toolbar you can switch between showing used handles and loaded.dll's-switch to the.dll view You will see all loaded.dll's/.exe's in the bottom list view Now determine which of these.dll's/.exe's may be COM.dll's/.exe's (see the following section) 246 SilkPerformer Advanced Concepts

253 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Glossary Dependency Walker (depends.exe) Dependency Walker is a tool that ships with Visual Studio (and can be downloaded from Dependency walker allows you to view the functions that.dll's and.exe's export. COM libraries always export at least the following four functions: DllCanUnloadNow DllGetClassObject DllRegisterServer DllUnregisterServer So if you view a.dll or.exe with Dependency Walker and you find these four exported functions, you'll know that it's a COM library that's used by your client application. Whether or not it's a COM library that's worth recording is a judgment you'll have to make (see the following section). Investigating Type Libraries If you have a type library and want to investigate the methods that the different COM interfaces offer to determine which methods may be prospects for exclusion (see Additional COM filters in PerfComDepend.ini ) you can use a tool called OleView. OleView ships with Visual Studio and can be downloaded from oleview-o.asp OleView allows you to investigate which COM objects are offered and which interfaces those COM objects implement. The interfaces themselves can be traced down to the method level, revealing which methods are offered and which parameters are expected. With OleView you may discover additional type information for the Recorder, if there are any void** parameters that return interfaces. Glossary [ADO] [ASP] [ASP.NET] [COM] ActiveX Data Objects. COM library that offers access to databases over an OLE-DB Provider Active Server Pages Next generation of Active Server Pages based on the.net Technology Component Object Model SilkPerformer Advanced Concepts 247

254 10 LOAD TESTING COM AND ADO BASED APPLICATIONS Glossary [DCOM] [HTTP] [IIS] [SOAP] [XML] Distributes Component Object Model. Allows to connect to remote COM objects. Hyper Text Transfer Protocol, used in the World Wide Web as a communication standard for transferring data Internet Information Server, Microsoft's web server software Simple Object Access Protocol extensible Markup Language 248 SilkPerformer Advanced Concepts

255 11 Load 1Chapter Testing Streaming Protocols What you will learn This chapter contains the following sections: Section Page Overview 249 Introduction to Streaming Media 250 Using SilkPerformer's Streaming Feature 251 Measured Data 257 Streaming Function Overview 259 Overview Streaming technology enables users to access multimedia content like sound and video over the Web without downloading files in their entirety, thereby minimizing user frustration while providing opportunities to site operators for more dynamic content. As with any new technology, streaming media can be problematic and unreliable. SilkPerformer offers both the power and functionality to effectively load test Web servers that deliver streaming content. SilkPerformer supports both Real Network and Windows media players. Because SilkPerformer can identify reliability issues in a range of Web-based applications, it's well suited to quantifying reliability issues with streamed media; it can help ensure that visits to sites with streaming content are enjoyable experiences. SilkPerformer Advanced Concepts 249

256 11 LOAD TESTING STREAMING PROTOCOLS Introduction to Streaming Media Introduction to Streaming Media In thinking of streaming media over the Web, one must consider movies, television, Web cams, and Internet radio. With streaming media a user can begin watching a video file or listening to an audio file while the file is still downloading. This enables users to sample files quickly, long before the files are completely downloaded. Internet radio stations use the Web to broadcast news and video clips pertaining to current events in the fields of politics, arts, and entertainment. Media Players Two popular streaming media client tools, or "media players", are Real Player and Windows Media Player. Real Player (or RealOne Player) enables users to locate various music and news channels-users simply specify their preferences. Windows Media Player is installed by default with all Windows operating systems. SilkPerformer's Streaming feature requires at least version 7 of Windows Media Player and at least version 7 of Real Player. The latest versions of Real Player and Windows Media Player can be downloaded from: Note It's not possible to use SilkPerformer's Streaming feature without an installed player. System Requirements Windows Media streaming: - Operating system: Windows 2000 or Windows XP. - Additional required applications: Windows Media Player 7 or higher. For best performance we recommend using Windows Media Player 9. Real Media streaming: - Operating system: Windows NT, Windows 2000 or Windows XP. 250 SilkPerformer Advanced Concepts

257 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature - Additional required applications: Real Player 7 or higher, RealOne Player 2 or higher. Using SilkPerformer's Streaming Feature The easiest way to gain insight into SilkPerformer's Streaming feature is to run a sample load test. This process involves creating a test script, customizing the script to handle a dynamically generated response, and then running the load test against streaming media servers. Finally, resulting measurements must be analyzed. Real media streams are typically identified by URL's like: pnm://video.real.com/gogetg2.ra where pnm (or rtsp) identifies a Real media stream. Windows media streams are typically identified by URL's like: mms://netshow.warnerbros.com/asfroot2/entertaindom/edom_30.asf where mms indicates a Windows media stream. Creating sample scripts for streams involves three basic steps: 1 Initializing SilkPerformer's Real Player or Windows Media Player engine using either RealStreamInit() or MediaStreamInit() in the TInit transaction of your BDL script. 2 Consuming a stream with either RealStreamUrl or MediaStreamUrl. 3 Shutting down the streaming engine in the TEnd transaction with either RealStreamShutdown or MediaStreamShutdown. Example Here is a sample Windows media BDL script: dcltrans transaction TInit begin MediaStreamInit(); end TInit; transaction TMain begin MediaStreamUrl( "mms://netshow.warnerbros.com/asfroot2/ entertaindom/edom_30.asf", "Warner"); end TMain; transaction TShutdown begin MediaStreamShutdown(); SilkPerformer Advanced Concepts 251

258 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature end TShutdown; Note The option "Call End transaction for stopped virtual users" (menu Settings/Active profile...) must be enabled. If this option is disabled streaming functionality may not work properly. Currently, it's not possible to have the recorder automatically generate scripts for streaming media; you must customize your scripts such that they can load test streams, as discussed in the following sections. Real Media Streaming By recording the URL mow/ blairwitch2.jhtml you ll receive the response shown in Figure 1. Figure 62 - Start page Now click the Trailer #2 link, which activates Real Player. Pause recording to see which Real stream has been requested. To do this, examine the recorder's log file, as shown in Figure 2; look for a response to the Trailer #2 link that will invoke Real Player. 252 SilkPerformer Advanced Concepts

259 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature Figure 63 - Recorder Log To quickly find the response that will invoke Real Player, use SilkPerformer's search feature to look for pnm:, which identifies Real media streams. If you generate your script now, you will receive a transaction with the following structure: transaction TMain begin WebPageUrl( " blairwitch2.jhtml", "Blair Witch Webfest 2000"); WebPageLink("watchit_blue3", "Timer", 3); end TMain; Now manually add RealStreamUrl functions to emulate the traffic that Real Player generates. As shown in Figure 2, the Real Player response body contains two URL's. Real Player will establish connections to both locations-you must account for this in your script by adding two lines, as shown below in bold: transaction TMain begin WebPageUrl( " blairwitch2.jhtml", "Blair Witch Webfest 2000"); WebPageLink("watchit_blue3", "Timer", 3); RealStreamUrl( "rtsp://troy-4.real.com/shocase/screen/2000/rv8/booko2.smi"); RealStreamUrl("pnm://video.real.com/gogetg2.ra"); end TMain; SilkPerformer Advanced Concepts 253

260 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature It's inconvenient to hard code the URL's that identify Real streams. An easier approach is to get these URL's at runtime is by parsing them using SilkPerformer's WebParseResponseData function. This is done by adding two additional functions to your transaction, as shown below in bold: transaction TInit begin RealStreamInit(); end TInit; transaction TMain var url1 : string; url2 : string; begin WebPageUrl( " "Blair Witch Webfest 2000"); WebParseResponseData(url1, sizeof(url1), "\n", "\n"); WebParseResponseData(url2, sizeof(url2), "--stop--\n", "\n"); WebPageLink("watchit_blue3", "Timer", 3); /* HttpResponseBody(#580, 108 bytes) { \n rtsp://ticonderoga 4.real.com/showcase/screen/2000/rv8/booko2.smi\n --stop--\n pnm://video.real.com/gogetg2.ra\n }*/ RealStreamUrl(url1, "RealRtsp"); RealStreamUrl(url2, "RealPnm"); end TMain; transaction TEnd begin RealStreamShutdown(); end TEnd; Now your script can be launched as a test. Measured data will be similar to that of a Windows media stream (as shown in the following section). Windows Media Streaming The process for Windows media streams is similar. The only difference is that you check the recorder's log for URL's beginning with mms:. For example, if 254 SilkPerformer Advanced Concepts

261 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature you recorded pages/hipclips/home.jsp and watched a streaming Windows movie clip, you would write the following script: transaction TMedia var mms1 : string; mms2 : string; begin WebPageUrl(" "Entertaindom : Hip Clips"); WebParseResponseData(mms1, sizeof(mms1), "<Entry><Ref href =\"", "\" /> </Entry>"); WebParseResponseData(mms2, sizeof(mms2), "<Ref href =\"", "\"/> </Entry>"); WebPageLink("click to play", "Entertaindom : Hipclips", 5, "mainframe"); // Response to check /* <ASX Version = "3.0">\r\n\r\n <Entry><Ref href ="mms://netshow.warnerbros.com/asfroot2/ entertaindom/edom_30.asf" /> </Entry>\r \n\r\n <Entry><!-- no click her info //-->\r\n <!-recommended for embeded Media Player //-->\r\n <AUTHOR>Warner Bros.</AUTHOR>\r\n <COPYRIGHT>TM & 2000 Warner Bros.</COPYRIGHT>\r\n <Ref href ="mms://netshow.warnerbros.com/ asfroot2/entertaindom/hipclips/september19/exorcis >> t_30.asf"/> </Entry> \r\n\r\n </ASX> */ MediaStreamUrl(mms1, "MovieProlog"); MediaStreamUrl(mms2, "Movie"); end TMedia; When the test is complete you can review the measured data. SilkPerformer provides you with information such as the actual time it takes a virtual user to consume a stream. It also offers information about the quality of streams (e.g., how many packets were lost during stream consumption-the more packets lost, the lower the stream quality). Performance Explorer is used to generate reports that provide the information required for analyzing the performance of streaming servers. This is done by creating a new report and then dragging and dropping all streaming-relevant data into the report. An example report is shown below in Figure 64: SilkPerformer Advanced Concepts 255

262 11 LOAD TESTING STREAMING PROTOCOLS Using SilkPerformer's Streaming Feature Figure 64 - Streaming Measures Report Two measurements will be evaluated in this example, Duration and Packets Received. This test was run for approximately five minutes, with five virtual users. As shown below, it took users an average of 104 seconds to downstream the movie clip. One user was able to downstream the movie within 96 seconds; another user had to wait 112 seconds. Sum Min Avg Max StdDev Duration Packets Received In summary, users received about 2,440 UDP packages. On average, each session held about 488 packages. Interestingly, no packets were lost and there was no stream discontinuity. An overloaded network or server can cause high average download time or high average distance from the average (StdDev). However no such conclusions can be drawn from the results of the sample test illustrated here. To export a report to an HTML file (e.g., to make it available for a presentation), use Performance Explorer's Export feature by selecting Export View from the File menu. 256 SilkPerformer Advanced Concepts

263 11 LOAD TESTING STREAMING PROTOCOLS Measured Data Figure 65 - Media Stream Report Measured Data Analyzing measurement results from Real media load tests enables you to determine if servers and/or networks were overloaded during tests. SilkPerformer enables you to answer important questions, such as: Is the time that it took a virtual user to downstream a video file significantly higher than the sample time of the video? Meaning, if downstreaming a five-minute video took longer than five minutes, the server, the network, or both, were overloaded. To make such an evaluation, compare RealStream_SAMPLETIME with RealStream_ DURATION. How many discontinuities occurred while a virtual user downstreamed a video file? For optimum quality, discontinuities should be avoided completely; a small number of discontinuities may however be acceptable. How many data packets were successfully downstreamed, and how many packets were lost? The higher the rate of successfully received data packets, the better the quality of the media. Real Media Streaming SilkPerformer provides the following measurements for Real Media Streaming: RealStream_DURATION: The time it takes a virtual user to downstream a file from the server (i.e., the actual time it takes the end user to view the video). If this time is significantly higher than the video sample time, the server, the network, or both are overloaded. SilkPerformer Advanced Concepts 257

264 11 LOAD TESTING STREAMING PROTOCOLS Measured Data RealStream_SAMPLETIME: The sample time, in seconds, of a streaming video. The primary goal of performance testing and tuning is to ensure that actual downstreaming time doesn't exceed this measurement. RealStream_PACKETSRECEIVED: Number of data packets that are received during a streaming session. The higher the ratio of successfully received packets to lost packets, the better the quality of media experienced by the end user. RealStream_PACKETSLOST: Number of data packets lost during a session. The higher this number, the poorer the quality of media experienced by the end user. RealStream_COUNTDISCONTINUITY: Number of discontinuities that occur during the downstreaming of a media file. The higher this number, the poorer the quality of media experienced by the end user. RealStream_COUNTBUFFERED: Number of times buffering occurred during a session. Windows Media streaming SilkPerformer provides the following measurements for Windows media streams: MediaStream_DURATION: The time it takes a virtual user to downstream a file from a server (e.g., the actual time it takes for the end user to view a movie). If this time is significantly higher than the video sample time, the server, the network, or both are overloaded. MediaStream_SAMPLETIME: The sample time, in seconds, of a streaming movie. The primary goal of performance testing and tuning is to ensure that actual downstreaming time doesn't exceed this measurement. MediaStream_PACKETSRECEIVED: Number of data packets received during a streaming session. The higher the ratio of successfully received packets to lost packets, the better the quality of media experienced by the end user. MediaStream_PACKETSLOST: Number of data packets lost during a session. The higher this number, the poorer the quality of media experienced by the end user. MediaStream_COUNTDISCONTINUITY: Number of discontinuities that occur during downstreaming of a media file. The higher this number, the poorer the quality of media experienced by the end user. MediaStream_COUNTBUFFERED: Number of times that buffering occurs during a session. 258 SilkPerformer Advanced Concepts

265 11 LOAD TESTING STREAMING PROTOCOLS Streaming Function Overview Streaming Function Overview The SilkPerformer Streaming functions are listed below, accompanied by short descriptions. More detailed information and samples can be found in SilkPerformer Online help. Real Media Streaming RealStreamInit: Initializes the SilkPerformer Real Stream engine. RealStreamUseProxy: This function can be used to set a proxy to be used for streams received with RealStreamUrl calls. RealStreamUrl: Opens a Real media stream for a specified URL and then receives the stream. RealStreamShutdown: Shuts down the SilkPerformer Real Stream engine. Windows Media Streaming MediaStreamInit: Initializes the SilkPerformer Media Stream engine. MediaStreamUseProxy: This function can be used to set a proxy to be used for streams received with MediaStreamUrl calls. MediaStreamEnableProtocols: Selects the protocols that are used to receive streaming Media. MediaStreamUrl: Opens a Windows Media stream for a specified URL and then receives the stream. MediaStreamShutdown: Shuts down the SilkPerformer Media Stream engine. SilkPerformer Advanced Concepts 259

266 11 LOAD TESTING STREAMING PROTOCOLS Streaming Function Overview 260 SilkPerformer Advanced Concepts

267 12 Load 12 Chapter Testing Flash Remoting Applications Introduction What you will learn This chapter explains how to use SilkPerformer to load test Flash Remoting applications. It explains how to use the "Flash Remoting" project type to record and customize scripts for Flash Remoting applications. This chapter contains the following sections: Section Page Configuring SilkPerformer 262 Script Modeling 262 Understanding Recorded Scripts 263 Customizing Scripts 268 SilkPerformer Advanced Concepts 261

268 12 LOAD TESTING FLASH REMOTING APPLICATIONS Configuring SilkPerformer Configuring SilkPerformer Specifying Project Type Create a SilkPerformer project based on the Web Browser/Flash Remoting project type, as shown in Figure 66. Figure 66 - Specifying project type - Flash Remoting Script Modeling Script modeling for Flash Remoting applications is straightforward. Use the Model Script dialog to start the recorder and a web browser, then perform the user interactions for the scenario that is to be recorded. Tip For detailed information on SilkPerformer s AMF3 support, please refer to section Adobe Flex AMF3 Support in the Online Help. 262 SilkPerformer Advanced Concepts

269 12 LOAD TESTING FLASH REMOTING APPLICATIONS Understanding Recorded Scripts Understanding Recorded Scripts Flash Remoting Protocol Flash Remoting uses a binary packet-oriented protocol that is passed with HTTP POST requests. This packet format is called AMF (= action message format). The Flash Remoting 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. Recorded Scripts 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, SilkPerformer 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 treeview in TrueLog Explorer, and can be customized there in the same way that all XML data can be customized. XML Representation of Binary AMF The root node of SilkPerformer's 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). Basic Structure 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: <?xml version='1.0' encoding='utf-8'?> <AmfXml version=\"0\"> SilkPerformer Advanced Concepts 263

270 12 LOAD TESTING FLASH REMOTING APPLICATIONS Understanding Recorded Scripts <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 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 (see Typed Values ). 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 (see Typed Values ). 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. 264 SilkPerformer Advanced Concepts

271 12 LOAD TESTING FLASH REMOTING APPLICATIONS Understanding Recorded Scripts 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 don't have name attributes. This 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 one to efficiently serialize complex data structures, which may even contain cyclic references. 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> SilkPerformer Advanced Concepts 265

272 12 LOAD TESTING FLASH REMOTING APPLICATIONS Understanding Recorded Scripts </Object> <ECMAArray nrelems="0"> <Number name="time"> </number> <String name="eventtype">information</string> <Date name="date"> :13: TZ:-480 [426F73ACED63C000FE20]</ Date> <String name="message">cf_debug_disabled</string> <String name="source">server</string> </ECMAArray> Example request by the PetMarket sample application Example response from the PetMarket 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> <?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> 266 SilkPerformer Advanced Concepts

273 12 LOAD TESTING FLASH REMOTING APPLICATIONS Understanding Recorded Scripts <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> The last two examples shows complete AMF packets from the PetMarket sample application ( flashstore.html). 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 tzoffset denotes the 3 digit number of milliseconds value 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. SilkPerformer Advanced Concepts 267

274 12 LOAD TESTING FLASH REMOTING APPLICATIONS Customizing Scripts When customizing a date value, the hexadecimal representation can either be deleted or left untouched; regardless it will be ignored when the XML representation is converted to binary AMF. Example string representation of a date value :38: TZ:-300 [426F73945F768000FED4] Customizing Scripts Flash Remoting scripts are best customized using Truelog Explorer. Truelog Explorer presents the XML representation of binary AMF requests and response bodies in a tree view structure. The HTTP request body is presented on the "PostData" tab. The HTTP response is presented on the "Rendered" tab of Truelog Explorer. The textual representation of request bodies is shown on the "out-hdr" tab. The textual representation of response bodies is shown on the "inheader" and "Source" tabs. Verification and parsing functions can be inserted visually as with other XML based applications. 268 SilkPerformer Advanced Concepts

275 12 LOAD TESTING FLASH REMOTING APPLICATIONS Customizing Scripts See the Truelog Explorer User Guide, "Working with XML Applications" chapter for more details. SilkPerformer Advanced Concepts 269

276 12 LOAD TESTING FLASH REMOTING APPLICATIONS Customizing Scripts Figure 67 - TrueLog Explorer Post Data view Figure 68 - TrueLog Explorer Rendered view 270 SilkPerformer Advanced Concepts

277 13 Load 13 Chapter Testing Siebel 6 CRM Applications Introduction A Guide to Customizing SilkPerformer BDL Scripts for Siebel 6 (Siebel 2000) Applications. What you will learn This chapter contains the following sections: Section Page Overview 271 Architecture of Siebel 6 CRM Applications 272 Installation and Requirements 274 Key Management with Siebel Applications 278 Formatting Scripts for Siebel Applications 280 Recording and Customizing a Siebel Application 283 References 290 Overview This chapter explains how to use SilkPerformer for load testing Siebel 6 (also known as Siebel 2000, version 6) CRM applications. It covers the testing of Siebel 6 Dedicated Client installations for Oracle and DB2, using SilkPerformer's Oracle OCI and IBM DB2/CLI support. It briefly explains the Siebel architecture and shows how to configure SilkPerformer and Siebel 6 Dedicated Clients. This chapter also provides guidelines for customizing Siebel scripts to run successfully in multi-user load tests using SilkPerformer's Siebel functions, and steps through the customization of a typical Siebel transaction. Ensuring database integrity with SilkPerformer's Siebel functions is also SilkPerformer Advanced Concepts 271

278 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Architecture of Siebel 6 CRM Applications covered. Finally, this chapter provides best practices for customizing Siebel database scripts. This chapter does not explain how to install/configure a Siebel CRM application, use a Siebel CRM application, or optimize the performance of a Siebel CRM application. This chapter is intended for experienced SilkPerformer users with knowledge of databases, SQL and SilkPerformer's database support for Oracle, ODBC, and DB2/CLI. Knowledge of a Siebel CRM application is also preferable. Architecture of Siebel 6 CRM Applications This chapter contains an overview of the Siebel client and how it works. Figure 1 illustrates the architecture of a typical Siebel deployment. Following the figure is a summary of the components that make up the Siebel client and descriptions of each type of client. Figure 69 - Architecture of a typical Siebel 6 CRM application 272 SilkPerformer Advanced Concepts

279 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Architecture of Siebel 6 CRM Applications Siebel Client Types Siebel ebusiness Applications support three types of clients: Siebel Dedicated Clients The most common deployment of a Siebel 6 client is a Siebel Dedicated Client. In Siebel Dedicated Clients, all layers of the Siebel ebusiness Application architecture, except for the database and the file system, reside on the user's personal computer. Figure 1 shows the architecture of a Siebel deployment and demonstrates at a high level how a dedicated client interacts with the Siebel database (area denoted in blue). Siebel Dedicated Clients connect to the Siebel database using the protocol of the database server. For IBM DB2 database servers, DB2/CLI (DB2 Call Level Interface) is used. For Oracle database servers, SQL*Net/OCI (Oracle Call Interface) is used. For SQLServer database servers, ODBC (Open Database Connectivity) is used. SilkPerformer supports Siebel Dedicated Clients for Oracle, DB2, and SQLServer. Though this chapter concentrates on Siebel installations using DB2 and Oracle databases, it is relevant for Siebel installations using SQLServer databases. Siebel Mobile Clients In Siebel Mobile Clients, all layers of the Siebel ebusiness Application architecture reside on the user's computer, and a local database is stored on each mobile machine. Siebel Mobile Clients only connect to the Siebel Enterprise Server to synchronize the mobile databases with the central Siebel database. They use a proprietary TCP/IP based protocol to communicate with the Siebel Enterprise Server. The testing of Siebel Mobile Clients is not covered in this chapter. Siebel Thin Clients The Siebel thin client model differs from the default Siebel Dedicated Client model in several ways. Thin clients do not store data locally. Thin clients connect only to the Gateway Server and not to other servers. The Siebel Server executes all business logic for thin clients. There are two basic types of thin clients: Siebel Thin Client (Java and Windows ActiveX): Siebel Thin clients communicate with the Siebel Enterprise Server using a proprietary TCP/ IP based protocol. SilkPerformer's TCP/IP support can be used to load test Siebel Thin clients, however that process is not covered in this chapter. SilkPerformer Advanced Concepts 273

280 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Installation and Requirements Siebel HTML Thin Client: Siebel HTML Thin Client is a technology used for deploying Siebel.COM Applications where Siebel HTML Thin Clients communicate with the Siebel Web Server using HTTP/HTML. The testing of Siebel HTML Thin Clients is supported by SilkPerformer's Web support. For further information, refer to SilkPerformer's Web support documentation. Installation and Requirements Siebel 6 Dedicated Client software must be installed to record and replay Siebel applications with SilkPerformer. When using multiple SilkPerformer agents, Siebel Dedicated Client software must be installed and running on all SilkPerformer agent machines. Configuring Siebel 6 Client Software / DB2 All Siebel client installations must use identical data sources for each agent. Confirm this using the ODBC Data Source Administrator (accessible from the Administrator Tools menu): Figure 70 - Siebel Data Source Configuration for DB2 Configuring Siebel 6/DB2 for Recording With the default installation of Siebel 6 (through version 6.3) SilkPerformer is not able to record the Siebel client application (Siebel.exe). To enable recording, 274 SilkPerformer Advanced Concepts

281 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Installation and Requirements the default database library used by the client must be changed from sscdd50.dll to sscddcli.dll: Ensure that the library sscddcli.dll is located in the Siebel installation path (e.g., C:\sea\bin\). Determine which configuration file (*.cfg file) is used by the Siebel client application that is to be recorded. To do this, examine the properties of the Start menu shortcut that launches the Siebel application. The entry will look similar to the following: Target: C:\sea\BIN\siebel.exe /c C:\sea\bin\scomm.cfg Open the configuration file (in this case: C:\sea\bin\scomm.cfg) with a text editor. Go to the [Server] section and change the DLL entry from sscdd50.dll to sscddcli.dll. This replaces the old DB2 communication library, which uses embedded SQL, with the new DB2 communication library, which uses DB2/CLI. This change has no impact on the Siebel application's performance or functionality. The old library is used for backward compatibility with DB2 version 5. Sample configuration file:... [Server] Docked ConnectString TableOwner ;;DLL DLL SqlStyle... =TRUE =SIEBEL =SIEBEL =sscdd50.dll =sscddcli.dll =DB2 SilkPerformer Advanced Concepts 275

282 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Installation and Requirements Configuring Siebel 6 Client Software / Oracle All Siebel client installations must use identical database aliases for each agent. Confirm this using the Net8 Easy Config tool, (accessible from the Oracle client software): Figure 71 - Siebel Database Alias Configuration for Oracle The installation of Siebel 6 (through version 6.3) requests the Database Alias and Table Owner in the Database Identification dialog. For that reason, Oracle client software should be installed before Siebel 6 and a Net Service Name should be configured to connect to the machine on which the Siebel database is running. If Oracle client software is not installed before the installation of Siebel 6 Client software, or before an appropriate Database Alias is configured, installation of the Siebel 6 Client may continue, however the client will not be available for use. In such an instance, the Oracle client installation should be done subsequently. Be sure that the Net Service Name and connection parameters of the Database Alias are identical on all machines used as SilkPerformer Agents. Configuring Siebel 6/Oracle for Recording Depending on the different Siebel 6 client versions (through version ), SilkPerformer may not be able to record the Siebel client application (siebel.exe) with the default configuration. While recording Siebel works fine with the default configuration, Siebel requires some adjustments. The default database library used by the client must be changed from sscdo80.dll to sscdo73.dll: 276 SilkPerformer Advanced Concepts

283 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Installation and Requirements Ensure that the library sscdo73.dll is located in the Siebel installation path (e.g., C:\sea\client\bin\). Determine which configuration file (*.cfg file) is used by the Siebel client application that is to be recorded. To do this, examine the properties of the Start menu shortcut that launches the Siebel application. The entry will look similar to the following: Target: C:\sea\client\BIN\siebel.exe /c C:\sea\client\bin\scomm.cfg If there is no configuration file specified there (e.g. with Siebel client version ), then find the.cfg file whose ApplicationTitle entry in the [Siebel] section shows the same string (e.g. Siebel ecommunications) as the window title of the Login dialog box to the Siebel application: [Siebel] RepositoryFile = siebel.srf ApplicationName = Siebel Power Communications ApplicationTitle = Siebel ecommunications ApplicationSplashText = ecommunications ComponentName = Siebel Communications Client Figure 72 - Login dialog box to the Siebel application Open the configuration file (in this case: C:\sea\bin\scomm.cfg) with a text editor. Go to the [Server] section and change the DLL entry from sscdo80.dll to sscdo73.dll. This replaces the default Oracle communication library with an updated version. Sample configuration file: [Server] Docked ConnectString TableOwner ;;DLL DLL SqlStyle... =TRUE =ORA_sunserver =siebel =sscdo80.dll =sscdo73.dll =Oracle SilkPerformer Advanced Concepts 277

284 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Key Management with Siebel Applications Key Management with Siebel Applications Why Database Keys Are Important for Script Customization A recorded SilkPerformer script from a database application such as Siebel 6, which inserts new data into a database, usually will not replay correctly without some modification. Replay may produce errors and undesirable results because scripts will attempt to insert exactly the same data during replay as during recording. Inserting the same data into a database more than once may cause primary key constraint violations in the database, resulting in replay errors. Such errors can easily be identified because they cause tests to halt immediately after errors are detected. In such cases Siebel 6/DB2 generates the following type of error message: Odbc***(ODBC: 5 - ODBC error, (-803) : [IBM][CLI Driver][DB2/NT] SQL0803N One or more values in the INSERT statement, UPDATE statement, or foreign key update caused by a DELETE statement are not valid because the primary key, unique constraint For this reason, scripts that insert data must be customized before they can be replayed successfully. To customize database scripts, it is essential to understand the technique that is used by the application to ensure primary/ foreign key consistency. Siebel Keys (Rowids) Siebel CRM applications use a sophisticated technique to ensure consistent, unique primary keys (primary keys are also referred to as "rowids" in Siebel documentation) for inserted data. Format of Siebel Primary Keys (Rowids): The format for primary keys in Siebel databases is the same for all primary keys. A primary key consists of a prefix and a suffix separated by a "-" character. The prefix is the same for the entire database; by default, a value of 1 is used for the prefix. The suffix is a string that represents a number with base 36. A base 36 number uses the characters "0" to "9" for base 36 digits from 0 to 9 and "A" to "Z" for base 36 digits from 10 to 35. A base 36 value of: A1Z 278 SilkPerformer Advanced Concepts

285 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Key Management with Siebel Applications Correlates to a base 10 value of: + + = + + = Typical Siebel keys include: 1-AF0 1-19UZ 2-ZT Characteristics of Siebel Primary Keys: Key Reservation Algorithm: All primary keys share the same SQL field name "ROW_ID". Siebel applications maintain available primary keys within a single table named "S_ SSA_ID". In addition to being unique within each table, primary key values are also unique to each database. To create a new primary key value, a Siebel client reads the value of the next available primary key in the table "S_SSA_ID" (column "NEXT_SUFFIX") and immediately increments that value by a chosen value, for example 100- thereby reserving the next 100 values for use by the client. For these 100 primary key values the Siebel client does not need to contact the database to retrieve valid primary keys, as they have already been reserved. Unused reserved key values are not returned, which creates "holes" in the key value sequence. Example Siebel Client A: Login Siebel Client A: Reserves a range of rowids (selects table S_SSA_ID and updates table S_SSA_ID with the next available rowid): Reserved rowids: 1-A00 to 1-A2S, next available rowid: 1-A2T Siebel Client A: Inserts row into table using the first reserved rowid value: 1-A00 Siebel Client A: Inserts second row into table using the second reserved rowid value: 1-A01 Siebel Client B: Login Siebel Client B: Reserves a range of rowids: 1-A2T to 1-A3L, next available rowid: 1-A3M SilkPerformer Advanced Concepts 279

286 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Formatting Scripts for Siebel Applications Siebel Client B: Inserts row into table using the first reserved rowid value: 1-A2T Siebel Client A: Inserts third row into table using the third reserved rowid value: 1-A02 Siebel Client B: Inserts second row into table using the second reserved rowid value: 1-A2U Siebel Client A: Logout Siebel Client B: Logout Formatting Scripts for Siebel Applications SilkPerformer Scripts for Siebel 6/DB2 A typical SilkPerformer script for Siebel 6/DB2 appears below: Global Variables benchmark SilkPerformer Recorder use "Kernel.bdh" use "Odbc.bdh" dcluser user VUser transactions TInit : begin; TMain : 1; var c1 : cursor;... c27 : cursor; c28 : cursor; ghdbc1 : number; ghenv1 : number; 280 SilkPerformer Advanced Concepts

287 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Formatting Scripts for Siebel Applications Siebel Dedicated Clients use a database connection (identified by the database handle ghdbc1 in the above example) and numerous database cursors (identified by c1 cnn). Database Login transaction TMain var begin OdbcAlloc(SQL_HANDLE_ENV, ghenv1); OdbcSetEnvAttr(ghEnv1, SQL_ATTR_ODBC_VERSION, SQL_OV_ODBC3); OdbcAlloc(SQL_HANDLE_DBC, ghdbc1, ghenv1); OdbcConnect(ghDbc1, "DSN=SIEBEL;UID=SEA_USER; PWD=mypwd;PATCH2=5,15;DBALIAS=SIEBEL;"); OdbcSetConnectAttr(ghDbc1, SQL_ATTR_TXN_ISOLATION, SQL_TXN_READ_UNCOMMITTED); OdbcSetConnectAttr(ghDbc1, SQL_ATTR_AUTOCOMMIT, SQL_AUTOCOMMIT_ON); OdbcOpen(c1, ghdbc1); /*** TMain_SQL001: SET CURRENT QUERY OPTIMIZATION = 3; ***/ OdbcExecDirect(c1, TMain_SQL001); OdbcSetConnectAttr(ghDbc1, SQL_ATTR_TXN_ISOLATION, SQL_TXN_READ_UNCOMMITTED); The first operation between the Siebel Dedicated Client and the Siebel database is the Login (OdbcConnect/OraLogon). The second parameter of OdbcConnect specifies the data source connect string that is used to connect to the Siebel database. Siebel uses different UIDs (database User ID's) to connect different users to a database. UID and PWD attributes in the data source connect string can be changed to customize user logins. SELECT Statements /*** TMain_SQL002: SELECT T2.PR_POSTN_ID,T1.LAST_UPD,T4.NAME,T1.CREATED_BY, T1.EMP_ID,T2.LAST_NAME,T1.CONFLICT_ID, T1.ROW_ID,T2.FST_NAME,T4.BU_ID,T3.OU_ID,T3.NAME, T4.BASE_CURCY_CD,T1.POSITION_ID,... T2.UPG_COMP_ID,T1.LAST_UPD_BY,T2.JOB_TITLE FROM SIEBEL.S_EMP_POSTN T1 INNER JOIN SIEBEL.S_EMPLOYEE T2 ON T1.EMP_ID = T2.ROW_ID INNER JOIN SIEBEL.S_POSTN T3 ON T1.POSITION_ID = T3. ROW_ID INNER JOIN SIEBEL.S_ORG_INT T4 ON T3.OU_ID = T4.ROW_ID LEFT OUTER JOIN SIEBEL.S_ORG_INT T5 ON T4. BU_ID = T5.ROW_ID LEFT OUTER JOIN SIEBEL.S_POSTN T6 ON T2.PR_POSTN_ID = T6.ROW_ID WHERE (T2.LOGIN =?) FOR FETCH ONLY; ***/ SilkPerformer Advanced Concepts 281

288 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Formatting Scripts for Siebel Applications OdbcPrepare(c1, TMain_SQL002); OdbcDefine(c1, "1", SQL_C_CHAR, 16);... OdbcDefine(c1, "21", SQL_C_CHAR, 76); OdbcBind(c1, ":1", SQL_C_CHAR, 51, SQL_CHAR, 50); OdbcSetString(c1, ":1", "SEA_USER"); OdbcExecute(c1); OdbcFetch(c1, SQL_FETCH_ALL, 1, SQL_FETCH_NEXT); // 1 rows fetched // // // 1 0VT-7T6D :3 Siebel Administ BT Siebel User :3 0VT-7T6D OdbcClose(c1); SELECT statements are the SQL statements most frequently called by Siebel Dedicated Clients. For example, a Siebel transaction might involve connecting to the database, opening the Customer Accounts screen, and adding a new customer consisting of 29 SELECT statements, 4 INSERT statements, and 2 UPDATE statements. SQL Result Sets The SilkPerformer recorder saves data that is returned from the execution of SQL queries during recording as BDL comments, in a tabular format within a BDL script. Such tables are useful for identifying correlations between the output data of SQL queries and input data of subsequent SQL commands. OdbcFetch(c6, SQL_FETCH_ALL, 1, SQL_FETCH_NEXT); // 4 rows fetched // // // : Normal :0 0-4IX5 2 Normal 0-1 // : High :0 0-4IX4 3 High 0-1 // : Urgent :0 0-4IX3 6 Urgent 0-1 // : Urgent with Ale :0 0-4O5O 1 Urgent with Ale 0-1 Maximum column width and number of rows displayed in the result set can be adjusted using profile settings (Menu: Settings > Active Profile - Record - Script - Protocols - Database). Reading Output Parameters Values from result sets can be read using the OdbcGet/OraGet functions. The following statement reads the sixth column of the third row of the above result set, fetched by cursor c6 (0-4IX3): svalue := OdbcGetString(c6, "6", 3); Setting Input Parameters Siebel uses parameter markers (input parameters) to parameterize SQL commands. This makes customization easy, as the data that need to be customized are parameters of the OdbcSet/OraSet functions scripted by SilkPerformer. In the code above, the string "SEA_USER" is bound using the OdbcSetString function to the SQL field T2.LOGIN of SQL statement TMain_ SQL SilkPerformer Advanced Concepts

289 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application Tip To easily identify BDL statements that are relevant for customization, color all OdbcSet/OraSet functions in scripts by adding them to the custom keywords list (Menu: Settings > System - Workbench - Layout - Custom Keywords). Length of Siebel Scripts Siebel BDL scripts can become quite large. For example, a Siebel BDL script that connects to a database, opens a Customer Accounts screen and inserts a new customer may have about 2600 lines of BDL code. SilkPerformer Scripts for Siebel 6/Oracle SilkPerformer scripts for Siebel 6/Oracle are similar to Siebel 6/DB2 scripts. The major difference between them is that instead of BDL ODBC functions, *) BDL ORA functions are used. The functions relevant for customization (OdbcSet/OraSet, OdbcGet/OraGet) have similar parameters. Therefore someone familiar with Siebel 6/DB2 can easily handle Siebel 6/Oracle. *) DB2/CLI and ODBC share the same specification for a callable SQL interface. Therefore SilkPerformer uses the same API functions for IBM DB2/CLI access as it does for ODBC access. Recording and Customizing a Siebel Application As the application logic used to generate consistent rowids is implemented in the Siebel client application, a recorded Siebel script containing the rowid values at the time of the recording is generated. Replaying such scripts may produce errors or lead to inconsistent data in a Siebel database. SilkPerformer provides special Siebel functions that realistically mimic the behavior of a Siebel client application by implementing the Siebel key generation algorithm. Customizing a Siebel script means replacing hard coded rowid values with dynamic, runtime-generated values. The following section covers the process of customizing Siebel scripts. Step 1: Configure Siebel 6/DB2 for Recording See Installation and Requirements for more details. Step 2: Create a SilkPerformer Project Depending on the database system used, create a SilkPerformer project using the application type "Siebel 6/Oracle" or "Siebel 6/DB2". Choosing a Siebel 6 application type automatically configures the SilkPerformer recorder for the Siebel 6 Dedicated Client application (Siebel.exe). SilkPerformer Advanced Concepts 283

290 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application Step 3: Record the Siebel Application Open the recorder and launch the Siebel application from the Start menu. Tip Insert "New Timer Session" for each major step to be recorded (for example, choosing a menu, entering a new value, etc). Figure 73 - SilkPerformer Recorder Using Timer sessions to comment on the recording process assists script customization by identifying, which sections of script belong to each recorded action. For each timer session (each MeasureStart/MeasureStop pair), two entries are made in the Active Script pane of SilkPerformer's Workbenchmaking it easy to navigate to various sections of the script. Commenting recording sessions is more important for recording database applications such as Siebel 6 than it is for recording Web applications. As database scripts often become quite large, it is helpful to have a mechanism for correlating recorded actions with their respective script sections. Additionally, timings are defined for actions that may later be used in load tests. Figure 74 - Active Script pane (double click to navigate to scripts) Tip Write down all data entered during recording sessions. During script customization this helps identify entered data in recorded scripts. 284 SilkPerformer Advanced Concepts

291 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application To ensure consistent scripts, always record full Siebel sessions (from login to logout/exit of the Siebel application). Step 4: Try the Script If data was not modified or entered during the recording session, the recorded script will replay without requiring modification. To make it realistic however, the script should be parameterized. If new data was entered during the recording session, such as creating a new account or adding a new activity to an account, the script will produce errors as it twice attempts to insert the same data. In such an instance customize the key/ rowid management of the script. Step 5: Search for Siebel Rowid Reservations Siebel rowids are maintained in the table "S_SSA_ID" of the Siebel database. Search for occurrences of "S_SSA_ID" to see if Siebel rowids are reserved in a script. Usually a SQL SELECT command is followed by a SQL UPDATE command for table S_SSA_ID within a script. Go to the first occurrence of "S_ SSA_ID". Rowid reservation code in a recorded Siebel 6/DB2 script OdbcOpen(c19, ghdbc1); MeasureStart("---Rowid reservation---"); /*** TMain_SQL020: SELECT T1.LAST_UPD,T1.CREATED_BY,T1.CONFLICT_ ID,T1.CREATED, T1.NEXT_SUFFIX,T1.ROW_ID,T1.NEXT_PREFIX,T1.CORPORATE_ PREFIX, T1.MODIFICATION_NUM,T1.NEXT_FILE_SUFFIX,T1.LAST_UPD_BY FROM SIEBEL.S_SSA_ID T1 FOR FETCH ONLY OPTIMIZE FOR 1 ROW; ***/ OdbcPrepare(c19, TMain_SQL020); OdbcDefine(c19, "1", SQL_C_CHAR, 33); OdbcDefine(c19, "2", SQL_C_CHAR, 16); OdbcDefine(c19, "3", SQL_C_CHAR, 16); OdbcDefine(c19, "4", SQL_C_CHAR, 33); OdbcDefine(c19, "5", SQL_C_CHAR, 16); OdbcDefine(c19, "6", SQL_C_CHAR, 16); OdbcDefine(c19, "7", SQL_C_CHAR, 16); OdbcDefine(c19, "8", SQL_C_CHAR, 16); OdbcDefine(c19, "9", SQL_C_CHAR, 17); OdbcDefine(c19, "10", SQL_C_CHAR, 16); OdbcDefine(c19, "11", SQL_C_CHAR, 16); OdbcExecute(c19); OdbcFetch(c19, 1, 1, SQL_FETCH_NEXT); // 1 rows fetched SilkPerformer Advanced Concepts 285

292 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application // // // : :0 4SL BT OdbcSetConnectAttr(ghDbc1, SQL_ATTR_AUTOCOMMIT, SQL_ AUTOCOMMIT_OFF); OdbcOpen(c20, ghdbc1); OdbcBind(c20, ":1", SQL_C_CHAR, 16, SQL_CHAR, 15); OdbcBind(c20, ":2", SQL_C_CHAR, 16, SQL_CHAR, 15); OdbcBind(c20, ":3", SQL_C_CHAR, 17, SQL_NUMERIC, 16, 0); OdbcBind(c20, ":4", SQL_C_CHAR, 33, SQL_TIMESTAMP, 32, 0); OdbcBind(c20, ":5", SQL_C_CHAR, 16, SQL_CHAR, 15); OdbcBind(c20, ":6", SQL_C_CHAR, 17, SQL_NUMERIC, 16, 0); OdbcSetString(c20, ":1", "1-3BT"); OdbcSetString(c20, ":2", "4VD"); OdbcSetString(c20, ":3", "175"); OdbcSetString(c20, ":4", " :32:56"); OdbcSetString(c20, ":5", "0-11"); OdbcSetString(c20, ":6", "174"); /*** TMain_SQL021: UPDATE SIEBEL.S_SSA_ID SET LAST_UPD_BY =?, NEXT_SUFFIX =?,MODIFICATION_NUM =?,LAST_UPD =? WHERE ROW_ID =? AND MODIFICATION_NUM =? ; ***/ OdbcExecDirect(c20, TMain_SQL021); OdbcClose(c20, SQL_DROP); OdbcCommit(ghDbc1); OdbcSetConnectAttr(ghDbc1, SQL_ATTR_AUTOCOMMIT, SQL_ AUTOCOMMIT_ON); MeasureStop("---Rowid reservation---"); Using the above code section as an example, embed the section beginning after the OdbcOpen call, before the SELECT statement through to the OdbcSetConnectAttr(, SQL_AUTOCOMMIT_ON) call after the UPDATE statement, within a MeasureStart/MeasureStop("---Rowid Reservation---"). This makes it easier to navigate to the rowid reservation section using the Active Script pane. Step 6: Identify Rowid Values Used in the Script The result set table of the "SELECT FROM S_SSA_ID" statement holds the first rowid value (more precisely, the suffix of the first rowid value) that will be used in the application to insert new data. This value is found in the fifth column of the result set table (column: NEXT_SUFFIX). In this example, the value is 4SL. Now search for the next occurrence of this value in the script. The value will be in a script line such as the following: OdbcSetString(c14, ":6", "1-4SL"); 286 SilkPerformer Advanced Concepts

293 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application In this case the complete rowid (prefix + suffix) that will be used to insert data is 1-4SL. To find all subsequent rowids that were used for inserting data, search for a phrase such as "1-4S" in the script. In this example, the following rowid values were found: OdbcSetString(c21, ":1", "1-4SL"); OdbcSetString(c25, ":7", "1-4SN"); OdbcSetString(c25, ":10", "1-4SL"); OdbcSetString(c26, ":3", "1-4SL"); OdbcSetString(c27, ":4", "1-4SO"); OdbcSetString(c27, ":8", "1-4SL"); OdbcSetString(c27, ":4", "1-4SL"); OdbcSetString(c27, ":6", "1-4SM"); OdbcSetString(c27, ":4", "1-4SL"); OdbcSetString(c27, ":22", "1-4SL"); OdbcSetString(c27, ":37", "1-4SL"); OdbcSetString(c27, ":40", "1-4SL"); OdbcSetString(c27, ":2", "1-4SL"); OdbcSetString(c27, ":2", "1-4SL"); The following new rowid values were used in the script: 1-4SL, 1-4SM, 1-4SN, 1-4SO These are the values that must be customized to produce a consistent script that replays without primary key constraint violation errors. Step 7: Replace Static Rowid Reservation Code with SilkPerformer's Siebel Functions SilkPerformer provides special Siebel functions that realistically mimic the behavior of a Siebel client application by implementing the Siebel key generation algorithm. By replacing the static code for the row reservation with SilkPerformer's Siebel functions, dynamic rowid values are generated, replacing the static values found in the script. SilkPerformer's Siebel functions for IBM DB2 are implemented in the include file Siebel6_DB2.bdh. For Oracle, they are implemented in Siebel6_ORA.bdh. Include this file at the beginning of the script: // CUSTOMIZED use "Siebel6_DB2.bdh" For each rowid that is to be customized, create a BDL string variable such as srowid_4sl, srowid_4sm, srowid_4sn, srowid_4so: // CUSTOMIZED var srowid_4sl : string; srowid_4sm : string; srowid_4sn : string; SilkPerformer Advanced Concepts 287

294 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application srowid_4so : string; Replace the code that was embedded between MeasureStart("---Rowid Reservation---") and MeasureStop("---Rowid Reservation---") with the following code (in blue below): OdbcOpen(c19, ghdbc1); // CUSTOMIZED MeasureStart("---Rowid reservation---"); SiebelAllocateRowId_DB2(ghDbc1); srowid_4sl := SiebelNextRowId_DB2(); srowid_4sm := SiebelNextRowId_DB2(); srowid_4sn := SiebelNextRowId_DB2(); srowid_4so := SiebelNextRowId_DB2(); /*** CUSTOMIZED: comment until OdbcSetConnectAttr( SQL_ AUTOCOMMIT_ON); /*** TMain_SQL020: SELECT T1.LAST_UPD,T1.CREATED_BY,T1.CONFLICT_ ID,T1.CREATED, T1.NEXT_SUFFIX,T1.ROW_ID,T1.NEXT_ PREFIX,T1.CORPORATE_PREFIX, T1.MODIFICATION_NUM,T1.NEXT_FILE_SUFFIX,T1.LAST_UPD_ BY FROM SIEBEL.S_SSA_ID T1 FOR FETCH ONLY OPTIMIZE FOR 1 ROW; ***/... /*** TMain_SQL021: UPDATE SIEBEL.S_SSA_ID SET LAST_UPD_BY =?, NEXT_SUFFIX =?,MODIFICATION_NUM =?,LAST_UPD =? WHERE ROW_ID =? AND MODIFICATION_NUM =? ; ***/ OdbcExecDirect(c20, TMain_SQL021); OdbcClose(c20, SQL_DROP); OdbcCommit(ghDbc1); OdbcSetConnectAttr(ghDbc1, SQL_ATTR_AUTOCOMMIT, SQL_ AUTOCOMMIT_ON); CUSTOMIZED ***/ MeasureStop("---Rowid reservation---"); SiebelAllocateRowId_DB2 (use SiebelAllocateRowId_ORA for Oracle) reserves rowids by selecting and updating the Siebel S_SSA_ID table in the 288 SilkPerformer Advanced Concepts

295 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS Recording and Customizing a Siebel Application same way that the Siebel client application does. After calling SiebelAllocateRowId_DB2, get new values for rowids by calling SiebelNextRowId_DB2 (use SiebelNextRowId_ORA for Oracle). Step 8: Replace Static Rowid Values with Dynamic Rowid Variables The last step for customizing rowids is to replace all static occurrences of identified rowids with rowid variables. Using the previous example: Search for "1-4SL" and replace all occurrences with "srowiid_4sl" Search for "1-4SM" and replace all occurrences with "srowiid_4sm" Search for "1-4SN" and replace all occurrences with "srowiid_4sn" Search for "1-4SO" and replace all occurrences with "srowiid_4so" New rowid values are usually only found in Bind functions, such as OdbcSetString for DB2 and OraSetString for Oracle. The replacement looks like this: OdbcSetString(c21, ":1", srowid_4sl); OdbcSetString(c25, ":7", srowid_4sn); OdbcSetString(c25, ":10", srowid_4sl); OdbcSetString(c26, ":3", srowid_4sl); OdbcSetString(c27, ":4", srowid_4so); OdbcSetString(c27, ":8", srowid_4sl); OdbcSetString(c27, ":4", srowid_4sl); OdbcSetString(c27, ":6", srowid_4sm); OdbcSetString(c27, ":4", srowid_4sl); OdbcSetString(c27, ":22", srowid_4sl); OdbcSetString(c27, ":37", srowid_4sl); OdbcSetString(c27, ":40", srowid_4sl); OdbcSetString(c27, ":2", srowid_4sl); OdbcSetString(c27, ":2", srowid_4sl); Step 9: Replace Static Input Data with Customized Data After customizing the rowid handling in the application, customize the user data. This step is rather easy as the data entered during recording can be found as parameters of OdbcSetString functions (OraSetString for Oracle). In the example, a new account with the name "TestAccount" was created. As a simple customization, replace the account name with a randomized account name using a random string pattern. Searching for "TestAccount" returns the following occurrences: OdbcSetString(c27, ":25", "TestAccount"); OdbcSetString(c27, ":1", "TestAccount"); SilkPerformer Advanced Concepts 289

296 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS References Create a variable to be used in the OdbcSetString functions instead of the string constant "TestAccount". var saccountname : string;... OdbcSetString(c27, ":25", saccountname); OdbcSetString(c27, ":1", saccountname); Generate a random variable using the random variable wizard (type RndStr) and assign the random variable raccountname to the variable saccountname at the beginning of the transaction. dclrand raccountname : RndStr(10..30); transaction InsertAccount begin saccountname := raccountname;... Step 10: Test the Script Run a try-script test to check if the customized script works. Check if the Siebel functions work correctly by using the Virtual User output window of the controller, or the Output file of the virtual user (.wrt file). If the functions work correctly, messages such as those listed below will appear. Figure 75 - Virtual User output for Siebel functions References SIEB01 TGUIDE01 IBM01 Siebel ebusiness Applications, Siebel Client Installation and Administration Guide, Siebel 2000, Version 6.2, September 2000, Siebel Systems, Inc., 2207 Bridgepointe Parkway, San Mateo, CA IBM-DB2 Siebel e-business Solution, The Technology Guide Series, Siebel 2000 Database Implementation on OS/390 Using NT Siebel Servers, IBM Redbook, September 2000, IBM Corporation, International Technical 290 SilkPerformer Advanced Concepts

297 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS References Support Organization, Dept. HYJ Mail Station P099, 2455 South Road Poughkeepsie, NY SilkPerformer Advanced Concepts 291

298 13 LOAD TESTING SIEBEL 6 CRM APPLICATIONS References 292 SilkPerformer Advanced Concepts

299 14 Load 14 Chapter Testing Siebel 7 CRM Applications What you will learn This chapter contains the following sections: Section Page Overview 293 Siebel 7 CRM Application Architecture 294 Configuring SilkPerformer 295 Dynamic Information in Siebel 7 Web Client HTTP Traffic 301 Tips, Hints, & Best Practices 312 Summary 313 Overview This chapter explains how to use SilkPerformer to load test Siebel 7 (also known as Siebel 2001, Version 7) CRM applications. It covers the testing of Siebel 7 thin client (Web client) installations that utilize front ends comprised of HTML and applets running within a Web browser (e.g., MS Internet Explorer). This chapter explains how with SilkPerformer's 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. SilkPerformer Advanced Concepts 293

300 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Siebel 7 CRM Application Architecture Also covered are: Best practices for properly preparing recording sessions Basic architecture of Siebel 7 thin client installations This chapter is intended for experienced users who are knowledgeable about load testing Web (HTTP/HTML based) applications with SilkPerformer. Siebel 7 CRM Application Architecture This chapter contains an overview of the Siebel client. Figure 1 illustrates the architecture of a typical Siebel 7 deployment. Overview Figure 76 - Siebel 7 CRM Application Architecture This chapter covers the portion of Figure 76 highlighted in blue - the Web Client (Thin Client). This is the default deployment for Siebel 7 installations. The Web client is a HTTP-, HTML-, Java applet based application that doesn't require a client-side software installation. The load testing of Siebel 7 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 SilkPerformer, though those topics aren't covered in this chapter. 294 SilkPerformer Advanced Concepts

301 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer HTTP Traffic To understand recorded scripts, it's 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 (HTML, pictures, etc). HTTP traffic generated by Java applets consists primarily of POST requests sent to servers. The bodies of HTTP requests have the MIME type "application/xwww-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. And the other shows the corresponding BDL form definition that is generated by the Web Recorder for this HTTP request. Example: HTTP Request Body from a Java Applet SWERPC=1&SWECount=5&SWECmd=InvokeMethod&SWEMethod=GetPrefere nce&sweinputpropset=%400%600%603%600%60getpreference%603%60% 60pCategory%60SWE%3AListAppletLayout%60pPrefName%60%60SWEJSX Info%60false%60 Example: BDL Form Definition for a HTTP Request Body from a Java Applet 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`"; Configuring SilkPerformer Installation The Siebel 7 Web client doesn't require an explicit software installation on the client computer. The client runs within a Web browser (e.g., MS Internet Explorer). SilkPerformer Advanced Concepts 295

302 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer Browsers may however ask for confirmation when Java applets are downloaded and installed. Such an example is shown in Figure 77. Figure 77 - MS Internet Explorer Security Warning Check the "Always trust content from SIEBEL SYSTEMS, INC." checkbox and click Yes. 296 SilkPerformer Advanced Concepts

303 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer To avoid unnecessary security warnings in the future, add the name of the Siebel 7 Web server to the "Trusted Sites" zone of MS Internet Explorer's security settings. Figure 78 - Adding Siebel 7 Web Server to "Trusted Sites" Zone Note Enter the complete address of the server, including " or " Siebel Project Type Create a SilkPerformer project based on the "ERP/CRM, Siebel 7 Web Client" project type, as shown in Figure 79. Otherwise, SilkPerformer's Siebel support SilkPerformer Advanced Concepts 297

304 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer won't be activated, which will lead to HTTP/HTML scripts that require heavy customization before they can be executed successfully. Figure 79 - Specify Project Type - Siebel 7 Web Client Web Recorder By creating a SilkPerformer project, as illustrated in Figure 79, the Web Recorder is prepared to record a Siebel 7 Web client - no additional settings are required. 298 SilkPerformer Advanced Concepts

305 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer However, if the Siebel 7 installation uses load balancing through varying server names, enable the option "Dynamic URL parsing" in the "Advanced Context Management Settings" dialog, as shown in Figure 80. Figure 80 - Profile Settings for Siebel Server with Load Balancing Scripts that use the host name "standardhost" in place of a real host name can be replayed against different servers by simply changing the standardhost profile SilkPerformer Advanced Concepts 299

306 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Configuring SilkPerformer setting. The recorder can generate such scripts if the host name is entered in the profile settings dialog before recording takes place, as shown in Figure 81. Figure 81 - Enter Standardhost Name and Port Before Recording TrueLog Explorer For best results in the "Source Differences" tab of TrueLog Explorer, add the following characters to both the "Compare tags" and "Compare tags HTML" lists within the "Settings / Options" dialog, as shown in Figure 82: Ampersand:& Asterisk:* Reverse single quote:` 300 SilkPerformer Advanced Concepts

307 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic At:@ Figure 82 - Options Dialog Settings for TrueLog Explorer Dynamic Information in Siebel 7 Web Client HTTP Traffic HTTP traffic generated by Siebel 7 Web clients incorporates dynamic information that must be addressed to ensure successful and accurate replay. Error Detection Unfortunately, failure to handle such dynamic data doesn't always generate error messages during script replay. This is because the Siebel 7 Web Server doesn't 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 a 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. SilkPerformer Advanced Concepts 301

308 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Example: Error Condition Response Sent from Server to evel0`0`errmsg`an error happened during restoring the context for requested location`errcode`27631`0`0`notifications`0` SilkPerformer 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: Example: Application Level Error Detection in Recorded Scripts use "WebAPI.bdh" use "Siebel7Web.bdh" //... transaction TInit begin WebSetBrowser(WEB_BROWSER_MSIE55); WebFormDefineEncodeCustom("base=ENCODE_FORM;" " +'@'; -'!()$,'; -'''"); Siebel7WebInit(); end TInit; Session ID's Siebel 7 Web Server uses session ID's to track user sessions. Servers can be configured to send session ID's either in cookies or in URLs (form fields or query strings; this is the default configuration). The example below shows a HTTP response header with a "Set-Cookie" header for a session ID. Session ID's in cookies are handled automatically by SilkPerformer. Example: Siebel Session ID in a Cookie HTTP/ OK Server: Microsoft-IIS/5.0 Date: Tue, 12 Mar :26:01 GMT Content-Language: en Cache-Control: no-cache Content-Type: text/html;charset=windows-1252 Content-Length: 3043 Set-Cookie: _sn=! d.3c8e3a29; Version=1; Path=/sales The example below shows a fragment of a HTML frameset with a frame that incorporates a session ID in a URL. Example: Siebel Session ID in a URL <frameset> <frame name="_sweclient"> 302 SilkPerformer Advanced Concepts

309 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic <frame name="_swe" src=" SWEFrame=top._swe&SWECount=1& _sn=!1.6c0.447b.3ceccd1b &SWECmd=GetCachedFrame"> </frameset> SilkPerformer's Web Recorder generates scripts that accurately handle such session ID's. The next 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's required. In this example, it's required for a form submission. Informational comments enhance readability. Example: Fragments of a Recorded Script with Session ID's 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(" 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"; SilkPerformer Advanced Concepts 303

310 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Timestamps HTTP communication between Java applets and the Siebel Web Server includes timestamps, which are strings that tell the number of milliseconds since Jan 1, Proper replays must include correct timestamps. SilkPerformer's 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. The first example below shows the body of a Java applet HTTP request that incorporates a timestamp. The other 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(). Example: HTTP Request Body with Timestamp Example: Corresponding BDL Form with Timestamp SWEUserName=undisclosed&SWEPassword=undisclosed&SWEForm=SWEE ntryform&sweneedcontext=false&swecount=0&swecmd=executelogin &SWETimeStamp= dclform SWEENTRYFORM002: "SWEUserName" := "undisclosed", // changed "SWEPassword" := "undisclosed", // changed "SWEForm" := "SWEEntryForm", // added "SWENeedContext" := "false", // added "SWECount" := "0", // added "SWECmd" := "ExecuteLogin", // added "SWETimeStamp" := GetTimeStamp(); // added, value: " " 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. SilkPerformer 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 7 Web client Java applets apply a unique encoding type that differs from SilkPerformer's standard encoding types. For this reason, SilkPerformer provides a new encoding type, ENCODE_ CUSTOM, which can be configured with the function WebFormDefineEncodeCustom. 304 SilkPerformer Advanced Concepts

311 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Siebel uses an encoding type that differs from the standard encoding type ENCODE_FORM in the following respects: Characters not escaped:!()$,' Characters SilkPerformer's Web Recorder detects when a 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. The next example shows fragments of a recorded script that utilizes these techniques. Example: Fragments of a Recorded Script that utilizes ENCODE_ CUSTOM 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`"; User Input Generally, it's desirable if user input recorded during recording sessions can be easily identified and changed (e.g., randomized) in recorded scripts. This is especially true for Siebel 7 Web client scripts, because Java applets often send values for all input fields to the server. If a new database record is created (e.g., for a new customer) and the record is subsequently edited or viewed, input (e.g., customer name) may appear multiple times in recorded scripts. SilkPerformer's Web Recorder: SilkPerformer Advanced Concepts 305

312 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic 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. Example: Fragments of a Recorded Script that Includes User Input var gsinputnewname : string init "$NewName$"; gsinputnewsite : string init "_NewSite_"; gsinputihttp_x_com : string init "i. //... 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) ", "s_1_2_37_0" := gsinputihttp_x_com, // value: "i. "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* `"; 306 SilkPerformer Advanced Concepts

313 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Choose input values during recording based on these descriptions so that the Web Recorder will detect them, as shown in Figure 83. Figure 83 - Recording Siebel 7 - Input Value Enclosed in $ Symbols Dynamic Data Siebel HTTP traffic includes a variety of dynamic data that is 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 ID's 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 ID's". Accurate handling of row ID's and other dynamic data is essential for successful replay. Row ID's and other dynamic data can be included in HTML documents (see first example) or in responses to HTTP requests from Java applets (see other example). SilkPerformer Advanced Concepts 307

314 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Dynamic data are always contained in value arrays (lists of values for single rows to be displayed in the Siebel GUI). Example: Value Array in JavaScript Code, within a HTML Document Example: Value Array in an Applet Response <script> row = new top._swescript.jssrecord(); row.id = "1-9Q1"; row.valuearray = ["Foo","Bar"," ","","Active", " "11/26/2002","","USD","11/26/2002", "","","","","N","N","","1-9Q1"]; S_BC1.Rec(row); `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*1 1*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* *6*Active22* 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 308 SilkPerformer Advanced Concepts

315 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic responses. The Recorder uses an appropriate tokenizing function SiebelTokenHtml or SiebelTokenApplet to retrive individual tokens from parsed value arrays. See SilkPerformer Online Help for a detailed description of these tokenizing functions. The next 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's required. In this example, individual tokens of the parsed values occur in various locations in form definitions. Informational comments enhance readability. Example: Script Fragment Utilizing Parsing Functions var gsrowvalarray : string; // = ["Foo","Bar"," ","","Active", // " // "11/26/2002","","USD","11/26/2002", // "","","","","N","N","","1-9Q1"]; gsrowvalarray_001 : string; // 3*Foo3*Bar10* *6*Active // 22* // 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) ", "s_1_2_51_0" := "", "s_1_2_47_0" := SiebelTokenHtml(gsRowValArray, 4), // value: "Active" "s_1_2_45_0" := SiebelTokenHtml(gsRowValArray, 5), //value:" "SWECmd" := "InvokeMethod", "SWERowId" := SiebelTokenHtml(gsRowValArray, 20), // value: "1-9Q1" "SWETS" := GetTimeStamp(); // value: " " SilkPerformer Advanced Concepts 309

316 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic //... 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) ", "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: " "SWECmd" := "InvokeMethod", "SWERowId" := SiebelTokenApplet(gsRowValArray_001, 20), // value: "1-9N9" "SWETS" := GetTimeStamp(); // value: " " Reformatting Functions The Siebel 7 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 (see first example). Example: Phone Number in Server- Response Body Example: Phone Number in Recorded Script, Reformatted by the Siebel Web Client Example: Reformatting Function for Phone Numbers 10* * *0*0*22*main.contact@MyCompany.com5*1-FIH Without modification, the format used in request bodies would also be used in recorded scripts (see second example), making it impossible to replace such values with parsed values. "s_1_1_25_0" := "(987) "; To allow such reformatted strings to be replaced with parsed values, SilkPerformer's 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(" "); 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. 310 SilkPerformer Advanced Concepts

317 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Dynamic Information in Siebel 7 Web Client HTTP Traffic Example: Using a Parsed Value as a Parameter of a Reformatting Function "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 See SilkPerformer Online Help for a detailed description of these functions. Meaningful Timer Names The Recorder extracts meaningful timer names from form fields. This makes it easier for human readers to interpret script, TrueLog and performance reports. The next example includes examples of intuitive timer names: Example: Meaningful Timer Names WebPageForm(" 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: " " SilkPerformer Advanced Concepts 311

318 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Tips, Hints, & Best Practices Tips, Hints, & Best Practices Section Dynamic Information in Siebel 7 Web Client HTTP Traffic of this chapter explained techniques employed by SilkPerformer's Web Recorder to generate working scripts that don't require customization. Due to peculiarities of the Siebel 7 Web client however, there are some pitfalls you may encounter. This chapter explains the common pitfalls, offers hints, and explains best practices for successfully load testing Siebel 7 Web clients. Read-Only Transactions A read-only transaction is a transaction in which new records aren't inserted and data isn't altered. Recorded scripts for read-only transactions run without modification, based on the techniques described in section Dynamic Information in Siebel 7 Web Client HTTP Traffic. Such scripts may however contain parsing functions for value arrays. Parsing functions may, for example, parse the value array of the 3rd 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 would be 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's generally because many tables in Siebel 7 don't allow duplicate records. The circumstances by which Siebel 7 considers records to be duplicates vary between tables. In most 312 SilkPerformer Advanced Concepts

319 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Summary instances, a certain combination of record fields must be different for Siebel 7 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 (see section User Input ). For Try Script runs, it's sufficient to manually change these values directly in scripts. For load 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. Beware 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't later be used during replay sessions once tables have been populated - and vice versa. To avoid such problems, ensure that you don't insert records into empty tables during recording sessions. Also ensure that tables are not emptied before or during load tests. Note that the following scenario is not affected by these constraints: Creating new records in tables that include other records (e.g., accounts). Creating new records in a table associated with the records just created (e.g., 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 won't cause problems. Summary If you follow the recommendations outlined in this chapter, using SilkPerformer to load test Siebel 7 Web client applications will be as easy as load testing standard Web applications. SilkPerformer Advanced Concepts 313

320 14 LOAD TESTING SIEBEL 7 CRM APPLICATIONS Summary 314 SilkPerformer Advanced Concepts

321 15 Load 15 Chapter Testing PeopleSoft 8 What you will learn This chapter contains the following sections: Section Page Overview 315 Configuring SilkPerformer 316 Script Modeling 316 Application Level Errors 326 Parameterization 329 Overview This chapter explains how to use SilkPerformer to load test PeopleSoft 8 applications. It explains how to use the PeopleSoft 8 SilkEssential package to record and customize PeopleSoft 8 scripts for realistic simulation of virtual users. Topics include: Automatic context management Detection and handling of application level errors Optional features via manual script enhancement SilkPerformer Advanced Concepts 315

322 15 LOAD TESTING PEOPLESOFT 8 Configuring SilkPerformer Configuring SilkPerformer Specifying Project Type Create a SilkPerformer project based on the ERP/CRM/PeopleSoft/PeopleSoft 8 project type, as shown in Figure 84. Figure 84 - Specifying project type - PeopleSoft 8 Script Modeling Script modeling for PeopleSoft 8 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 Before recording, make sure that the project has been created based on the PeopleSoft 8 project type, as shown in Figure 84. 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. Don't use your browser's Back button as this is generally problematic for highly statedependent Web applications such as PeopleSoft. 316 SilkPerformer Advanced Concepts

323 15 LOAD TESTING PEOPLESOFT 8 Script Modeling Understanding Recorded Scripts 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 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 applicationlevel 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 "PeopleSoft8Api.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(); SilkPerformer Advanced Concepts 317

324 15 LOAD TESTING PEOPLESOFT 8 Script Modeling //GetLoginInfoPS("LoginPS.csv", gsuserid, gspassword); //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME); //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION); end TInit; 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 WebPageUrlPS WebPageLinkPS WebPageSubmitPS WebPageSubmitBinPS WebPageFormPS WebPageFileUploadPS Wrapped original function WebPageUrl WebPageLink WebPageSubmit WebPageSubmitBin WebPageForm WebPageFileUpload 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 " 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 don't require customization. The SignInPS function parses the sign-out URL to the gssignouturl variable, and the recorded script uses the 318 SilkPerformer Advanced Concepts

325 15 LOAD TESTING PEOPLESOFT 8 Script Modeling variable in the SignOutPS function call. The recorder records the URL of the homepage into a variable for easy customization. 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 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); This process works without any required modification. 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, etc. 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: Recorded script fragment - User interaction within the work area Example: Submitted form WebPageSubmitPS(NULL, MAIN005, "Product Definition", 4); // Form 4 The above example shows a WebPageSubmitPS that 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. MAIN008: "ICType" := "" <USE_HTML_VAL>, // hidden, unchanged, value: "Panel" "ICElementNum" := "" <USE_HTML_VAL>, SilkPerformer Advanced Concepts 319

326 15 LOAD TESTING PEOPLESOFT 8 Script Modeling // 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" Script Customization The PeopleSoft SilkEssential package contains some utility functions that can be accessed via manual script enhancement to get more from recorded scripts. This chapter describes these optional steps. Customizing Think Times SilkPerformer's Recorder 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's called ThinkTimePS. function ThinkTimePS(fTime : float optional; bforcethinktime : boolean optional) To customize the script, use the Replace dialog (select Replace from the Edit menu) to 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), 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 (e.g., stresstest, random thinktime, exponential/uniform distribution, thinktime limited to x seconds, etc). When bforcethinktime is set to true, ThinkTimePS calls the ThinkTime API function with the value of the parameter ftime and the OPT_THINKTIME_ 320 SilkPerformer Advanced Concepts

327 15 LOAD TESTING PEOPLESOFT 8 Script Modeling EXACT option. This results in a thinktime that is exactly as specified, regardless of profile settings and project attributes. Figure 85 - Think time related project attributes There are two project attributes available for customizing the behavior of the ThinkTimePS function. Select Project Attributes from the Project menu 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 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. SilkPerformer Advanced Concepts 321

328 15 LOAD TESTING PEOPLESOFT 8 Script Modeling Customizing Timer Names For easier results analysis, it's 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 orginal 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 Figure 86 shows the project attributes that can be used to specify desired items. Figure 86 - Timer name related project attributes 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. 322 SilkPerformer Advanced Concepts

329 15 LOAD TESTING PEOPLESOFT 8 Script Modeling 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 don't 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. 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 standardhost in the profile settings. 3 Specify a different standardhost in project attributes, as shown in Figure 87. These project attributes will be evaluated in the PeopleSoftInit() function call and will therefore override the recorded WebSetStandardHost function call. SilkPerformer Advanced Concepts 323

330 15 LOAD TESTING PEOPLESOFT 8 Script Modeling Figure 87 - Standardhost related project attributes Enable server-side tracing PeopleSoft 8 offers the option to enable detailed server-side tracing for individual login sessions. 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: 324 SilkPerformer Advanced Concepts

331 15 LOAD TESTING PEOPLESOFT 8 Script Modeling "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. See Figure 88. Figure 88 - Editing tracing options in Tracing.csv Randomizing table row selection PeopleSoft pages often contain tables (e.g., 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. SilkPerformer Advanced Concepts 325

332 15 LOAD TESTING PEOPLESOFT 8 Application Level Errors There are four functions that assist with this: GetMaxRowNr returns the maximum valid row number (e.g., 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. The sample below shows an example that uses the GetRndRowStr function 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>, //... Application Level Errors General PeopleSoft doesn't 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 (e.g., Record has been saved). It doesn't make sense to continue transactions after severe errors occur. 326 SilkPerformer Advanced Concepts

333 15 LOAD TESTING PEOPLESOFT 8 Application Level Errors Benefits Using the PeopleSoft 8 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 that the Truelog On Error option be enabled during load tests to fully benefit from this feature. Customizing Error Messages Lists of specific error messages are contained in the AppErrors.csv and AlertSeverities.csv 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 by following the steps outlined in the following section. 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 wish to catch a set of error messages that have a common substring, it s good practice to enter only one entry where the Error String is the common substring. Example: If you have e.g. 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:. SilkPerformer Advanced Concepts 327

334 15 LOAD TESTING PEOPLESOFT 8 Application Level Errors The AppErrors.csv file can be edited to meet your needs. Figure 89 - Customizing 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 a 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) Enter data into the highlighted fields.&#039;);" > 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). 328 SilkPerformer Advanced Concepts

335 15 LOAD TESTING PEOPLESOFT 8 Parameterization Alert String: The text of the alert string (or fragment thereof). Figure 90 - Customizing alert severities 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. Parameterization The recorder can create variables for certain strings that appear in scripts. This makes script customization and randomization easier. Sign In Data The user names and passwords that are used for sign-in are created as variables at the tops of scripts. 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. SilkPerformer Advanced Concepts 329

336 15 LOAD TESTING PEOPLESOFT 8 Parameterization 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, "pwd" // changed, value: "Admin" := gspassword, // changed, value: "Secret" "Submit" := "" <USE_HTML_VAL> ; // unchanged, value: "Sign In" 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 tops of scripts for these values. This makes randomization of input values easier. 330 SilkPerformer Advanced Concepts

337 15 LOAD TESTING PEOPLESOFT 8 Parameterization Example: Variables created for input values var gsinput_newproduct gsinput_inp_customer //... dclform //... : string init "_New Product_"; : string init "inp.customer"; 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: "" SilkPerformer Advanced Concepts 331

338 15 LOAD TESTING PEOPLESOFT 8 Parameterization 332 SilkPerformer Advanced Concepts

339 16 Load 16 Chapter Testing Oracle Forms What you will learn This chapter contains the following sections: Section Page Overview 333 Basic Concepts 333 Installation and Requirements 336 Record and Replay 337 Oracle Forms TrueLogs 354 Monitoring 359 Root Cause Analysis 363 Tips & Tricks 369 Overview This chapter explains how to use SilkPerformer to run load tests and interpret results for Oracle Forms 6i, Oracle Forms 9i, Oracle Applications 11i, and Oracle Applications 12i. This chapter briefly outlines possible server configurations and discusses how they can be tested. It also provides guidelines for customizing scripts (including verification functions) so that they can be run in distributed multi-user environments. Basic Concepts 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 SilkPerformer Advanced Concepts 333

340 16 LOAD TESTING ORACLE FORMS Basic Concepts 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 new architecture: Figure 91 - Architecture Oracle Forms Client Types The Oracle Forms Web client is a Java applet hosted within a browser. It's possible to use your browser's default Java Virtual Machine (i.e., Internet Explorer's MS JVM or Netscape's JVM). However because there have been some issues with these JVM's, Oracle provides its own JVM, which is called JInitiator. JInitiator is installed automatically when you access an Oracle Forms Web application for the first time. There are different versions of JInitiator; the version numbers reflect the Java Runtime version numbers that are used (e.g., JInitiator uses Java Runtime 1.1.8). You don't necessarily need to use JInitiator, though it's the recommended environment for running Oracle Forms applications. The JVM to be used by the client can be configured on the Oracle Forms server. For information regarding which Oracle Forms versions can be used with which JVM's, see the Oracle Technical Network ( 334 SilkPerformer Advanced Concepts

341 16 LOAD TESTING ORACLE FORMS Basic Concepts Oracle Forms Versions There are different versions of Oracle Forms and, depending on the version you use, SilkPerformer utilizes different approaches to recording. Following is a technical overview of the versions and corresponding architectural changes: Oracle Forms 6 (pre Patch 4) Oracle Forms 6, prior to Patch 4, uses the following architecture for server/client communication: Figure 92 - Server/client communication 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 JInitiator has not yet been installed, this page will redirect your browser to download JInitiator. The applet connects to the Forms-Server Listener process during initialization. This Forms-Server Listener spawns a new process that hosts the Forms-Server Runtime for the client. Thereafter the client applet and the Runtime Engine have a direct connection, via HTTP, HTTPS, or Socket layer. Oracle Forms 6 (Patch 4) Patch 4 of Oracle Forms 6 changes the communication architecture by only having one communication channel between the client and server: SilkPerformer Advanced Concepts 335

342 16 LOAD TESTING ORACLE FORMS Installation and Requirements Figure 93 - Communication channel between client/server As you can see from the above illustration, each message that is sent between the client and the server is processed by the HTTP Listener. This architecture allows you to implement load balancing. Oracle Forms 9 The communication architecture of Oracle Forms 9 hasn't changed. The difference lies on the client side. A new JInitiator that runs on Java Runtime Version 1.3.x can be used, allowing custom applications to develop Java GUI or Java Beans that rely on a newer JDK. A significant change in Oracle Forms 9 impacts the way that SilkPerformer records and replays messages that are sent between the client applet and the Oracle Forms Server. Oracle has introduced a test interface that can be used to retrieve all messages during recording and send those messages to the server during replay. The Difference Between Oracle Forms 6 and 9 The reason that SilkPerformer distinguishes between Oracle Forms 6 and Oracle Forms 9 is the different approaches to recording/replaying that the versions utilize. As mentioned in section Oracle Forms 9, Oracle has introduced a test interface that can be used to work with Oracle Forms 9. When working with Oracle Forms 6 SilkPerformer uses a different approach to intercepting the message flow between client and server. This difference is the reason for having two project types-oracle Forms 6 and Oracle Forms 9. The project type Oracle Forms Applications 11i is basically the same as Oracle Forms 6, as it operates on Oracle Forms 6 technology. Oracle Forms 6 can operate on two different communication channels: HTTP/ HTTPS or Socket layer. 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 application profile (you must first determine which communication channel you're using). For details, see the Tips & Tricks section of this chapter. Installation and Requirements Oracle Forms applications require a Java Runtime installation on the client side. SilkPerformer's record/replay mechanism also requires a Java Runtime installation to test Oracle Forms applications. 336 SilkPerformer Advanced Concepts

343 16 LOAD TESTING ORACLE FORMS Record and Replay Configuring Oracle Forms Client Software Oracle Forms clients run in Web browsers as applets. By default, a Web browser will download and install Oracle's default Java Runtime when loading an Oracle Forms application for the first time. Oracle's Java Runtime for Oracle Forms is also named JInitiator. Using JInitator isn't mandatory. Once a JRE has been installed, SilkPerformer is set up to record Oracle Forms applications. Setting up a Java Runtime for Replay A Java Runtime must be installed on each SilkPerformer agent machine. It is recommended that the latest Java Runtime distributed by Sun be used. The directory containing the Java Runtime must be the same on each SilkPerformer agent machine. As discussed in the Tips & Tricks section of this document, use JDK 1.4 or higher. Configuring Oracle Applications Server Software On your Oracle Applications server, locate the file formsweb.cfg and open it with a text editor. Append the text record=names to this file and save it. Restart the Oracle Applications server. Record and Replay When beginning the testing of an Oracle Forms application, ensure the following: The Oracle Forms client must be running on the recording machine. Check the requirements (see section Installation and Requirements ). Know which version of Oracle Forms you're testing: Oracle Forms 6, Oracle Forms 9, Oracle Applications 11i, or Oracle Applications 12i Begin by creating a new project in SilkPerformer and, from the Outline Project dialog, select the application type that matches your Oracle Forms application version. If you have Oracle Applications 11i, you can either choose the Oracle Forms Applications 11i project type under the ERP/CRM node or you can select Oracle Forms 6i. If you have Oracle Applications 12i, choose the Oracle Forms Applications 12i project type under the ERP/CRM node. SilkPerformer Advanced Concepts 337

344 16 LOAD TESTING ORACLE FORMS Record and Replay Recording 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. When choosing one of the Oracle Forms project types in your application profile settings, a new application profile is created for your project based on the active browser. Here is the System Settings dialog in which the Java Recording API for Oracle Forms 9 is selected: Figure 94 - Application Profile dialog You can't modify the settings for this temporary application profile. If you want to record using different settings (see Problems with Oracle Forms 6 Recording for an example of why this might be necessary) you must change the settings of the Internet Explorer application profile. Oracle Java Recording API The Java Recording API is comprised of two elements: HTTP recording rules Instructions regarding which Java classes implement recording logic 338 SilkPerformer Advanced Concepts

345 16 LOAD TESTING ORACLE FORMS Record and Replay 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. Java Environment Settings As recording and replay of Oracle Forms applications is achieved via a Java implementation, it's necessary to configure your Java environment in SilkPerformer. This can be done either system-wide using the System Settings dialog, or it can be done on a per-project-basis using the Profile settings dialog. In either case you must define the same settings: Version of your Java Runtime Java Home Directory Additional classpaths (you don't need to define these for the recording of Oracle Forms) Advanced settings such as Command Line Options, JITting, and special JVM.dll's (not required for Oracle Forms recording) Figure 95 - System Settings - Java SilkPerformer Advanced Concepts 339

346 16 LOAD TESTING ORACLE FORMS Record and Replay The settings on the System Settings dialog are the default values for all new projects. Within a specific project you can change settings using the Profile settings dialog. Figure 96 - Profile Settings - Java Recording Options Oracle Forms has some recording options that can be defined using the Profile Ssettings dialog: Figure 97 - Profile Settings - Oracle Forms 340 SilkPerformer Advanced Concepts

347 16 LOAD TESTING ORACLE FORMS Record and Replay The tab that's relevant to recording is the Logging tab. Here you can define the Log level and other properties that should be logged for each control in your application. The Log level can be defined as: None: Recording TrueLogs will be generated, though no Oracle Messages will be logged and no detailed information about controls in the recording log file will be written. Error: In addition to the features of the None recording level, errors that occur during recording are logged Normal: In addition to the features of the Error recording level, Oracle Messages are logged to the TrueLog and the recording log file. Debug: In addition to the features of the Normal recording level, detailed information about control messages is logged. This option should be used when you encounter a problem during recording and you must send your recording log files to Customer Care 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 won't 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 aren't used by controls and so will generally be ignored if you define them. Start Recording Begin recording by clicking the Model Script workflow button. Select an Oracle Forms application profile, or the Internet Explorer profile if you've changed SilkPerformer Advanced Concepts 341

348 16 LOAD TESTING ORACLE FORMS Record and Replay some application profile settings. Enter the URL of your Oracle Forms application and click OK. Figure 98 - Workflow - Model Script Your browser will then open. Interact with your Oracle Forms application as a typical user might. Each action will be recorded and an Oracle Forms script will be generated based on the actions. Files Generated During Recording Script Recording Text Log 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. 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 342 SilkPerformer Advanced Concepts

349 16 LOAD TESTING ORACLE FORMS Record and Replay 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# 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 SilkPerformer Advanced Concepts 343

350 16 LOAD TESTING ORACLE FORMS Record and Replay When the log level is set to Debug, log information required for trouble shooting is logged to the log file. If you encounter any problems and need to contact Customer Care, please provide a log file utilizing log level Debug. Record TrueLogs Record TrueLogs contain the same information as replay TrueLogs. This allows you to use Difference View after you've executed your first TryScript (this functionality is covered in the TrueLog section of this chapter). Replay SilkPerformer emulates multiple Oracle Forms clients distributed across multiple SilkPerformer agents. SilkPerformer's Oracle Forms clients are driven by a Java Runtime that is hosted by SilkPerformer during replay. Before launching a test, several runtime options must be modified. General Settings Oracle Forms specific settings are located within SilkPerformer under Settings/ Active Profile/Oracle Forms. The General tab contains connection specific settings. Here is an explanation of the provided settings. Connection mode: Oracle Forms server can be configured to accept several types of connections. Servers can be configured to accept socket connections, HTTP connections, and secure HTTP connections. Note: This profile setting can be overridden using an Oracle Forms specific function called OraFormsSetConnectMode. 344 SilkPerformer Advanced Concepts

351 16 LOAD TESTING ORACLE FORMS Record and Replay Connection Timeout: Specify how long emulated clients should attempt to establish communication with the server before they report an exception. Figure 99 - Profile Settings - Oracle Forms Enable heartbeat with the frequency: An Oracle Forms client can check the connection to the server in intervals. This is useful when the Oracle Forms client isn't communicating with the server for a long period of time (e.g., during a long think time period). Forms version: Oracle Forms servers can only allow certain client releases. Use this setting to specify the Oracle Forms client version. This setting can be overridden with a function called OraFormsSetInt using the parameter OraFormsSetInt("INITIAL_VERSION" nversion). This setting is useful when you're running one load test project against multiple server versions-simply create new profiles and change the version settings. Measures By default, the Oracle Replay engine collects a wide range of performance information during test runs. Based on your goals, the Oracle Forms engine can be configured to collect only a select set of performance metrics. By default, the engine collects and updates the following metrics for each function call: Enable Timers: Measures the time it takes to process the function call. Count round trips: Counts the number of round trips for the function. SilkPerformer Advanced Concepts 345

352 16 LOAD TESTING ORACLE FORMS Record and Replay Count bytes: Counts the number of bytes received and the number of bytes sent. Count messages: Counts the number of messages sent and the number of messages received. The Oracle Forms engine can be configured to enable or disable certain performance metrics for controls. For example, settings can be modified so that the Oracle Forms engine only collects performance metrics for button controls. Figure Profile Settings - Oracle Forms Running the Test Once profile settings have been configured, a test run can be initiated. All SilkPerformer workload models can be used for the Oracle Forms engine, including: Increasing workload Steady state Dynamic All Day Queuing Oracle Forms Client Sessions When executing a recorded Oracle Forms script, a client session begins with the following function call: OraFormsConnect and ends with the end of the transaction. 346 SilkPerformer Advanced Concepts

353 16 LOAD TESTING ORACLE FORMS Record and Replay Example transaction TInit begin WebSetBrowser(WEB_BROWSER_MSIE6); WebModifyHttpHeader("Accept-Language", "en,de-at;q=0.5"); OraFormsInit(" l90servlet", "vangelis", 9000, ORA_FORMS_9I); end TInit; transaction TShutdown begin OraFormsDestroy(); end TShutdown; transaction TMain var begin OraFormsSetString("DEFAULT_LOCAL_TZ", "Europe/Berlin"); OraFormsConnect( "server module=healthyliving.fmx SERVER sso_userid=" "output_dir=c:\\orant\\forms90\\demos\\temp"); // New window activated: MAIN ThinkTime(3.7); OraFormsSetWindow("MAIN"); OraFormsEditSet("EDIT_CONTROL_0", "USER", ORA_EDIT_SEND_ DIRTY); // Supplier Name end TMain; The above session begins with the OraFormsConnect call and ends with the end of the transaction. Therefore each iteration of the transaction can be considered an Oracle Forms client session. Results Once a SilkPerformer test is complete, SilkPerformer's Performance Explorer is used to analyze how the Oracle Forms application performed during the test run. SilkPerformer automatically collects a configurable number of timers and counters for each function call. See Section Measures to see how to specify which performance metrics are collected during test runs. By default, SilkPerformer collects the following counters for each function call: bytes sent bytes received messages received SilkPerformer Advanced Concepts 347

354 16 LOAD TESTING ORACLE FORMS Record and Replay messages sent roundtrips See Figure 101 to see where these counters are found in Performance Explorer. Figure Performance Explorer - Counters In addition to counters, SilkPerformer offers timers, which measure how long it takes a function call to complete its tasks. See Figure 102 to see where these timers are found in Performance Explorer. Figure Performance Explorer - Timers 348 SilkPerformer Advanced Concepts

355 16 LOAD TESTING ORACLE FORMS Record and Replay Reports can be assembled by dragging counters and timers into graphs (see Figure 103). Figure Performance Explorer - counter and timers graph For more information on assembling load test reports, see SilkPerformer's Performance Explorer documentation. Oracle Forms HTTPS Support SilkPerformer enables you to record Oracle Forms applications that use secure connections via HTTPS (Oracle Forms 6 and Oracle Forms 9). Note the following prerequisites: Recording To record an Oracle Forms application over HTTPS you must add the SilkPerformer certificate to your Oracle JInitiator s truststore database. This database is located in your JInitiator s home directory in a subdirectory named \Lib\security\. Open the file certdb.txt with a text editor. This file is located in the directory \Lib\security\ of your JInitiator s home directory. Open the SilkPerformer certificate file IRCAcert.pem with a text editor. This file is located in your SilkPerformer installation directory. Copy the content of the SilkPerformer certificate file and append it to the content of the certdb.txt file. Save and close the certdb.txt file. Remember to start a new browser session before recording your Oracle Forms application. SilkPerformer Advanced Concepts 349

356 16 LOAD TESTING ORACLE FORMS Record and Replay You can now record your application. Replaying Replaying a recorded Oracle Forms script requires no prerequisites. 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 running. 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. After recording your script should resemble the following: Code Example var gsssessionid : string; dclrand dcltrans transaction TInit begin OraFormsInit(" l90servlet", " vangelis ", 9000, ORA_FORMS_9I); //WebSetUserBehavior(WEB_USERBEHAVIOR_FIRST_TIME); //WebSetDocumentCache(true, WEB_CACHE_CHECK_SESSION); end TInit; transaction TShutdown begin 350 SilkPerformer Advanced Concepts

357 16 LOAD TESTING ORACLE FORMS Record and Replay OraFormsDestroy(); end TShutdown; transaction TMain begin WebSetBrowser(WEB_BROWSER_MSIE6); WebModifyHttpHeader("Accept-Language", "de-at"); WebPageUrl(" f90servlet", "iorganizer", FORMS90DEMO_F90SERVLET001); WebSetBrowser(WEB_BROWSER_CUSTOM); WebSetUserAgent("Java "); WebSetHttpVersion("HTTP/1.1"); WebModifyHttpHeader("Accept-Language", NULL, WEB_MODIFY_ OPT_Remove); WebUrl(" jinit.jar", 29.61); WebUrl(" iorganizer.jar", 0.42); WebUrl(" iorganizer.gif", 0.45); WebUrl(" blue.gif", 0.43); WebUrl(" forms/registry/registry.dat", 0.08); WebUrl(" iorg_registry.dat", 6.58); // Connect - with connection properties OraFormsSetInt("INITIAL_VERSION", 90290); 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 module=iorganizer.fmx userid=iorg/iorg@orcl_ SUNSERVER" " sso_userid= usesdi=yes record=names", " forms90demo/f90servlet?config=iorg", " forms90demo/"); OraFormsGetSessionId(gsSSessionID); SilkPerformer Advanced Concepts 351

358 16 LOAD TESTING ORACLE FORMS Record and Replay WebCookieSet(gsSSessionID, " forms90demo/java/"); // --- // New window activated: 10 OraFormsSetWindow("10"); ThinkTime(6.6); end TMain After customization, your script should appear as follows: Code Example var gsssessionid : string; dclfunc function DoConnect begin WebSetBrowser(WEB_BROWSER_MSIE6); WebModifyHttpHeader("Accept-Language", "de-at"); WebPageUrl(" f90servlet", "iorganizer", FORMS90DEMO_F90SERVLET001); WebSetBrowser(WEB_BROWSER_CUSTOM); WebSetUserAgent("Java "); WebSetHttpVersion("HTTP/1.1"); WebModifyHttpHeader("Accept-Language", NULL, WEB_MODIFY_ OPT_Remove); WebUrl(" jinit.jar", 29.61); WebUrl(" iorganizer.jar", 0.42); WebUrl(" iorganizer.gif", 0.45); WebUrl(" blue.gif", 0.43); WebUrl(" forms/registry/registry.dat", 0.08); WebUrl(" iorg_registry.dat", 6.58); // Connect - with connection properties OraFormsSetInt("INITIAL_VERSION", 90290); OraFormsSetPoint("INITIAL_RESOLUTION", 96, 96); OraFormsSetPoint("INITIAL_DISP_SIZE", 1280, 1024); OraFormsSetInt("INITIAL_COLOR_DEPTH", 256); OraFormsSetString("FONT_NAME", "Dialog"); OraFormsSetInt("FONT_SIZE", 900); 352 SilkPerformer Advanced Concepts

359 16 LOAD TESTING ORACLE FORMS Record and Replay 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 module=iorganizer.fmx SUNSERVER" " sso_userid= usesdi=yes record=names", " forms90demo/f90servlet?config=iorg", " forms90demo/"); OraFormsGetSessionId(gsSSessionID); WebCookieSet(gsSSessionID, " forms90demo/java/"); end DoConnect; dcltrans transaction TInit begin OraFormsInit(" l90servlet", " vangelis ", 9000, ORA_FORMS_9I); //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 SilkPerformer Advanced Concepts 353

360 16 LOAD TESTING ORACLE FORMS Oracle Forms TrueLogs 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 won't experience problems with subsequent transactions if an active transaction fails and disconnects from the server. Oracle Forms TrueLogs Note See the Customizing Oracle Applications 12i Scripts for Replay section of the SilkPerformer User Guide for details on customizing session information in Oracle Applications 12i scripts. 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. Structure 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 (e.g., 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. 354 SilkPerformer Advanced Concepts

361 16 LOAD TESTING ORACLE FORMS Oracle Forms TrueLogs 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. Figure TrueLog 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 sub node you will see the state and values of all controls as they existed after the action you selected was fulfilled (e.g., 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 stood after the SilkPerformer Advanced Concepts 355

362 16 LOAD TESTING ORACLE FORMS Oracle Forms TrueLogs reactivation (which in most cases is the same status they had when the window was deactivated). Figure TrueLog Explorer The illustration above shows the controls of a window that has been activated for the first time. Each line represents a control and includes the following information: Change State (first column that is grayed out in the above image) This column is set with a state when a control gains focus or is edited, or a value is changed by the server Id This is the unique control ID. Each control is assigned a unique internal ID. This ID is used in messages that are sent between the server and client to indicate which control is to handle a given message. Name These are the internal programming names for each control. Normally these internal programming names aren't used. With a special option that can be passed to the Oracle Server, the server can be forced to specify these names when controls receive their create messages. It's easier to work with these names than it is to work with ID's only. Type This is the control type. There are different types of controls that can be included on a form and displayed in a TrueLog: TEXT, TAB, BUTTON, TREE, LIST, RADIO, and CHECK Value This is the current value of the control. Depending on the control type this value has different meanings. For a Text control this value is the 356 SilkPerformer Advanced Concepts

363 16 LOAD TESTING ORACLE FORMS Oracle Forms TrueLogs included text. For a Tab control this value is the name of the selected tab page. For a Check/Radio button this value is True or False, depending on whether or not the button is selected. For a List control this value is the selected item in the list. For a Button control this value is the label of the button. This column is unique in that, by right-clicking it, you can add verifications or customize the input value of a control (this is described later in this book). C/S When the value of a control is changed, this column indicates which side (client or server) changed the value. Old This column shows the previous value of the control before either the client or the server changed it to the new value. Some controls are listed in black print, others are grayed out. Those that are grayed out are controls that were created while the window was activated, but are not currently visible. These "not yet visible" controls are only shown in gray on the OraFormsSetWindow node in which they were created. The sub-nodes don't display them until they become visible. These controls will again be shown in gray when the actions on the currently selected node again bring the controls into a invisible state (e.g., when an Exit button is clicked the controls on the form will become invisible or destroyed. Control Change States The first (grayed out; see Figure 105) column of the control list indicates the change state of the control. Each time a control's state changes, this column indicates what has changed. The following states are available: Edit The control is edited by user interaction (e.g., editing a text field changes the state of a radio/check box). Controls with the Edit state can be customized with the input data customization wizard. Simply right-click in the value column of a control and select Customize Value from the context menu. Change The control's value has been changed by either the client or the server. Both the new and old values are displayed, in addition to reference to the side that changed the control's value. Focus The control that receives focus, either via direct clicking or the tab key. SilkPerformer Advanced Concepts 357

364 16 LOAD TESTING ORACLE FORMS Oracle Forms TrueLogs Press If a button has been pressed, this button will have the pressed state Verification and Parsing TrueLog Explorer offers wizards that add verification and parsing functions to your scripts to verify and parse control values-at any time during an application's life cycle. To add a verification or parsing function, right-click in the value column of a control that you wish to verify/parse and select the relevant context menu. For detailed information regarding verification and parsing capabilities, see the TrueLog Explorer User Guide. Input Data Customization 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: OraFormsEditSet Customizes the value of a text control OraFormsRadioSet Specifies whether or not a radio button is to be selected OraFormsCheckboxSet Specifies whether or not a checkbox 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 358 SilkPerformer Advanced Concepts

365 16 LOAD TESTING ORACLE FORMS Monitoring For detailed information regarding the different types of data customization that are available (text, check/radio, list boxes, etc), see the TrueLog Explorer User Guide. Oracle Messages in In/Out Data The In/Out-Data panes of an Oracle Forms node contain the Oracle Forms messages that are sent to the server (Out-Data) and received by the server (In- Data). These messages can be ignored during data customization. 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. Monitoring Monitoring of Oracle Forms application load tests is accomplished using SilkPerformer Performance Explorer. The 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. SilkPerformer Advanced Concepts 359

366 16 LOAD TESTING ORACLE FORMS Monitoring To monitor the database server a set of predefined Oracle database measures can be used: Figure Data Source Wizard For monitoring of the application server, use measures that are provided by the platform upon which the application server runs. Here you can either choose from predefined sets, or use PERFMON, SNMP or REXEC and manually define the measures that are of interest to you. Figure Data Source Wizard Additionally to the default measures for the application server, Performance Explorer offers a BDL Monitor that allows querying performance data from the Oracle Forms Dynamic Monitoring System (DMS). Please read the instructions on for setting up DMS on your Oracle Application Server. 360 SilkPerformer Advanced Concepts

367 16 LOAD TESTING ORACLE FORMS Monitoring In the Data Source Wizard expand "Application Server/Oracle" and select the entry named "Oracle Forms AS". Click Next. In the next step provide the hostname where your Oracle Application Server is running and click Next. This will bring up a dialog where you will have to provide the these settings: URL to DMS Performance site The usual format of the DMS-Site is: Proxy - if you need to connect via an HTTP-Proxy Port of the HTTP-Proxy Username - if you need to authenticate against the Web-Server to access the DMS-Site SilkPerformer Advanced Concepts 361

368 16 LOAD TESTING ORACLE FORMS Monitoring Password for accessing the DMS-Site This monitor is providing the most interesting measures that are provided by the DMS including: Common Apache measures Module information for HTTP, OC4J and PLSQL Database connection statistics Client-side measures are automatically generated by load-test agents and are aggregated into a single result file by the load-test controller. Agents create measures for: Time taken by an action on a control (e.g., 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 roundtrips for an action For detailed information regarding setting up workspace in Performance Explorer and how to use this tool to analyze test results, see the Performance Explorer help system. 362 SilkPerformer Advanced Concepts

369 16 LOAD TESTING ORACLE FORMS Root Cause Analysis Root Cause Analysis Errors that happen during a Try-Script, Baseline or Loadtest-Run can easily be analyzed with the log files that are written during the run - especially with the TrueLog. TrueLog - Analysis The most common error that will occur is: OraForms: 5 - Handler not found This error will be thrown if the control (handler) that is referenced as first parameter of failing OraForms API call cannot be found, e.g.: 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, e.g.: 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 will update 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. Log-File Analysis The log files (recording and replay) contain different information's depending on the Log-Level defined in the profile settings. Whenever you have a problem and need to contact technical support - switch to Log-Level "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-Modus - all client side events will be logged, e.g.: value changed, mouse down, Overview of OraForms-Error Here is an overview of the OraForms errors that can be thrown by the OraForms API calls: SilkPerformer Advanced Concepts 363

370 16 LOAD TESTING ORACLE FORMS Root Cause Analysis ID Message Description 1 Logon Dialog not found OraFormsLogon and OraFormsLogonCancel can throw this error if the Logon dialog is not the current active dialogit 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 "5 - handler not found". 3 Unsupported property Can be thrown by multiple OraForms calls when the calls are querying handlers for special properties that should be set but aren't. 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 "5 - handler not found". 364 SilkPerformer Advanced Concepts

371 16 LOAD TESTING ORACLE FORMS Root Cause Analysis ID Message Description 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 calls 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. Please review the topics above covering Root Cause Analysis.The most often case is that an error was raised on the server, e.g.: 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 has been done during recording. 6 The button to be pressed does not exist OraFormsMessageBoxButton will throw 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 will throw 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 Tabpage not found OraFormsTabSelect will throw this error if there is no tab page with the passed name or passed index. 9 Unrecognized dialog button OraFormsCloseDialog will throw this error if an invalid button number was passed to the method.valid buttons are: ORA_DIALOG_OK and ORA_ DIALOG_CANCEL SilkPerformer Advanced Concepts 365

372 16 LOAD TESTING ORACLE FORMS Root Cause Analysis ID Message Description 10 The function cannot be applied for this handler Several OraForms API calls will throw this error if the method was called on a handler of a type that doesn't allow to execute that kind of function, e.g.: OraFormsTabSelect on a non tab control handler. 11 The lov row does not exist OraFormsLovSelect will throw 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 can throw this error if the list handler referenced in the first parameter doesn't contain a list element with the passed value or index. 13 Handler is of invalid class Several OraForms API calls will throw this error if the method was called on a handler of a type that doesn't allow to execute that kind of function, e.g.: OraFormsTabSelect on a non tab control handler. 14 A value for this property is not set 15 Array index is out of bound All OraFormsGetProp{Type} methods will throw this error if the requested property has not been set on the passed handler. OraFormsGetPropStringArray and OraFormsGetPropByteArray will 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 will throw this error if the defined verification fails! 366 SilkPerformer Advanced Concepts

373 16 LOAD TESTING ORACLE FORMS Root Cause Analysis ID Message Description 17 Received version too old If the server returns the error VERSION_TOO_OLD during the connect phase - this error is been thrown.this means that the version number of the client is too old to work with the version on the server.try to use a different version number for the client by customizing the OraFormsSetInt for the property "INITIAL_VERSION" or by customizing 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 been thrown.this means that the version number of the client is too new to work with the version on the server.try to use a different version number for the client by customizing the OraFormsSetInt for the property "INITIAL_VERSION" or by customizing the version number in the profile settings. 19 Alert dialog Whenever an alert dialog is created - this error will be 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. SilkPerformer Advanced Concepts 367

374 16 LOAD TESTING ORACLE FORMS Root Cause Analysis ID Message Description 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 a error message.therefore - when doing root cause analysis of errors - check for statusbar changes. 21 Runtime Error, see logfile for stack trace If there are internal replay runtime errors - this error will be 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, e.g.: invalid user inputit is likely that a WINSYS_BEEP is followed by other errors like "Handler not found". The reason for this: A recorded session without errors could cause errors during replay if the script has been customized with invalid input values or if a script that should be customized has not been customized, e.g.: using different values each time a test is run.check the chapters above covering Root Cause analysis 23 OraFormsSetConnectMod e overrides the profile's connection setting This is just a warning telling you that the setting in the profile is overruled by the scripted OraFormsSetConnectMode 368 SilkPerformer Advanced Concepts

375 16 LOAD TESTING ORACLE FORMS Tips & Tricks ID Message Description 24 Profile setting INITIAL_ VERSION overridden by function OraFormsSetInt This is just a warning telling you 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 will be created. 26 Handler already destroyed or not created yet It is possible that the client applet sends messages from special handler's (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 will be logged. 27 Tree item was not found All OraFormsTree API calls can throw this error if the referenced tree item was not found in the tree. Tips & Tricks There are several issues that need to be considered when testing Oracle Forms applications with SilkPerformer: Oracle Forms Memory Usage Oracle Forms Replay Engine uses SilkPerformer'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 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 SilkPerformer Advanced Concepts 369

376 16 LOAD TESTING ORACLE FORMS Tips & Tricks 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 Data 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). Use JDK 1.4 or Higher The JDK needs to be configured in your profile settings. You must use JDK 1.4 or higher for the following reasons: Performance Newer versions perform better - allowing you to simulate more users on one machine Stability There might be some stability issues when using JDK 1.2. JDK 1.2 has some deprecated functions which are valid in JDK 1.1.x and JDK >= 1.3. Those deprecated functions might result in unpredicted results during a loadtest. 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 SilkPerformer Recorder process - not by the applet. During replaying - it is used in the virtual user runtime. Virtual Memory Size of JVM A Java Virtual Machine can be configured with a minimum and maximum heap size. 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. Note You must use JDK 1.4 or higher. Java Version Max Heap Size MB MB MB 370 SilkPerformer Advanced Concepts

377 16 LOAD TESTING ORACLE FORMS Tips & Tricks It's likely that you'll run into a memory problem when using version with a default maximum heap size of 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 (e.g., -Xms10m) -Xmxn for defining the maximum heap size (e.g., -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. Disable the Java VM JITter When recording Oracle Forms 6i, on either HTTP or Sockets, it's 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. JITting 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). To do this, launch the JInitiator Control Panel. Add -DJAVA.COMPILER=NONE to the Java Run Time Parameters text field. Click the Apply button. Option #2 Use the check box on the Oracle JInitiator Properties dialog to disable the Just In Time Compiler (only available since version x). To do this, launch the JInitiator Control Panel. Select the Advanced tab. Deselect the Enable Just In Time Compiler checkbox. Click the Apply button. Option #3 Define an environment variable: SET JAVA_COMPILER=NONE SilkPerformer Advanced Concepts 371

378 16 LOAD TESTING ORACLE FORMS Tips & Tricks Note Disable JITting whenever your browser crashes during recording. 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 SilkPerformer's System Settings dialog: Open the System Settings Dialog Figure System Settings - Recorder 372 SilkPerformer Advanced Concepts

379 16 LOAD TESTING ORACLE FORMS Tips & Tricks Edit the SOCKS proxy entry Figure Proxy Settings In the suppressed recording port field, enter the port that your Oracle Forms application uses for communication with the applet. If you fail to suppress the port, SilkPerformer 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. Problems with Oracle Forms 6 Recording When recording an Oracle Forms 6 application using the Oracle Forms 6 project type, SilkPerformer "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 SilkPerformer allows you to specify the transport channel that is of interest to you. SilkPerformer Advanced Concepts 373

380 16 LOAD TESTING ORACLE FORMS Tips & Tricks This setting is defined in your browser's Application Profile dialog. Open the application profile dialog and change the Java API to the protocol that you wish to record. Figure Application Profile Now when you begin recording, don't select the preconfigured Oracle Forms 6i application type; use Internet Explorer as you have already changed its application profile configuration. 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 - SilkPerformer'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. 374 SilkPerformer Advanced Concepts

381 16 LOAD TESTING ORACLE FORMS Tips & Tricks 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: Figure noverify JInitiator settings Java Containers and JavaBeans 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: Open the Windows Control Panel SilkPerformer Advanced Concepts 375

382 16 LOAD TESTING ORACLE FORMS Tips & Tricks Figure Control Panel Double-click System and select the Advanced tab. Click the Environment Variables Button. This launches the dialog on which environment variables are edited. Select the CLASSPATH variable in the System variables section and press the Edit button. Figure Environment Variables Now add the Java archive that contains the Java Bean and apply the settings. Restart the Oracle Forms server. 376 SilkPerformer Advanced Concepts

383 17 Load 17 Chapter Testing SAP GUI What you will learn This chapter contains the following sections: Section Page Overview 377 Basic Concepts 377 Installation and Requirements 384 Recording and Replay 385 TrueLog 393 Preparing for Large Load Tests 398 Monitoring 401 Tips & Tricks 408 Overview This chapter explains how to use SilkPerformer to test SAP systems via the SAP GUI interface. This chapter briefly outlines possible server configurations and discusses how they can be tested. It also provides guidelines for customizing scripts (including verification functions) so that they can be run in distributed multi-user environments. Basic Concepts SAP introduced 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 SilkPerformer Advanced Concepts 377

384 17 LOAD TESTING SAP GUI Basic Concepts execute user actions. SilkPerformer uses this interface to record new scripts and for script execution. SAP GUI Scripting SAP GUI Scripting must be installed on the client. It can be selected during the SAP GUI Client setup process. During recording Figure 1: Installing SAP GUI Scripting Once it has been installed on the client, SAP GUI Scripting must be enabled on both the client and the server. A description of how to enable scripting in SAP can be found in SilkPerformer Online Help, in both the SAP section and the Client-side Requirements section. The SAPLogon process initializes the SAP GUI 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 SAP GUI can be accessed. This COM interface also offers an event mechanism that notifies subscribers of changes in the GUI (e.g., button presses, text edits) and server roundtrips (Start/End Request). SilkPerformer's Recorder is a subscriber of this event interface, so it receives notice of all changes that are made by the user in the SAP GUI user interface. Depending on recording profile settings, SilkPerformer Recorder is either set for low-level scripting of API calls for each change event, or high-level scripting for 378 SilkPerformer Advanced Concepts

385 17 LOAD TESTING SAP GUI Basic Concepts API calls in which certain change events are merged with high-level calls (e.g., SapGuiLogon). Figure 2: Recording Technology During replay When executing a SAP GUI load test, the SAP GUI 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 doesn't make sense to show the UI when executing multiple users on a machine-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 (See TrueLog for further details). Supported Versions SAP GUI Scripting is available since version 620, and on the following SAP server patch levels of older versions: 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 SilkPerformer Advanced Concepts 379

386 17 LOAD TESTING SAP GUI Basic Concepts Software Component Release Package Name Kernel Patch Level SAP_BASIS 610 SAPKB61012 Kernel 6.10 level 360 On the client side, SAP GUI Client 620 is required with a minimum patch level of 44. A detailed description of how to check if the correct versions are installed can be found in SilkPerformer Online Help, in both the SAP section and the Serverside Requirements section. SAP GUI Application Architecture The SAP GUI 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. Figure 4: Application Architecture Top level user objects 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. Depending on whether the new visual design of SAP is used or not, a title and status bar are contained within the main window of each session. The illustration below shows a SAP GUI client with the new visual design that contains all top level objects. The user area contains all controls on the window. 380 SilkPerformer Advanced Concepts

387 17 LOAD TESTING SAP GUI Basic Concepts Figure 6: SapGui Top Level Objects Object IDs Each object within a SAP GUI 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. 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 SilkPerformer Advanced Concepts 381

388 17 LOAD TESTING SAP GUI Basic Concepts 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 (e.g., "lbl" for labels and "txt" for text controls). Following the prefix, controls have a programmatical name (e.g., 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-tab- TDLINE[0,0] /app/con[0]/ses[0]/wnd[0]/tbar[0]/btn[0] Object Properties Each object has properties that can be accessed from a SilkPerformer 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 (e.g., 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. 382 SilkPerformer Advanced Concepts

389 17 LOAD TESTING SAP GUI Basic Concepts 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 (e.g., 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. SilkPerformer 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 SAP GUI_ACTIVEOBJECT as the object identifier. Detailed information about this can be found in Tips & Tricks. Object access with SilkPerformer To make object access easier (see the Object section to see how objects within SAP GUI are identified), SilkPerformer 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. 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, SilkPerformer required 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 whereever 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. SilkPerformer Advanced Concepts 383

390 17 LOAD TESTING SAP GUI Installation and Requirements Installation and Requirements To use SilkPerformer's support for SAP GUI, SAP GUI Scripting must be installed and enabled on the client and the server side. Server-side Requirements SAP servers of version 620 and higher offer SAP GUI Scripting support. Earlier versions require certain patch levels (see Supported Versions for details). After ensuring that you have installed the correct patch, SAP GUI Scripting must be enabled on the server. Here are the steps for enabling scripting on the server: 1 Logon to your SAP server. 2 Start transaction RZ11. 3 Enter the value sapgui/user_scripting in the edit field Param. Name. 4 Hit ENTER or press the Display button. 5 You will see the Current Value of this profile parameter. It must be TRUE. 6 If it is not set to TRUE," click the "Change Value" toolbar button. 7 Enter TRUE in the New Value field of the Change Parameter Value dialog. 8 Click the Save Button. 9 If the Current value has not changed to TRUE, you may need to restart your servers to reflect the change. Client-side Requirements All clients that are either used for recording, replay or monitoring must have a SAP GUI client with SAP GUI Scripting installed. To begin recording, SAP GUI Scripting must be enabled on the machine that is to record a script. This can be done with the following steps: 1 Start your SAPLogon and go to the logon screen of one of your servers. 384 SilkPerformer Advanced Concepts

391 17 LOAD TESTING SAP GUI Recording and Replay 2 Open the Options Dialog. 3 Select the Scripting tab, enable scripting and disable the two suboptions. If the installation status of the Scripting tab doesn't show "Scripting is installed," you must install SAP GUI Scripting by choosing the option in the SAP GUI Client Setup (see SAP GUI Scripting for details). Recording and Replay The following sections explain the workflow for recording, replaying and customizing scripts, as well as result analysis. Recording Recording Settings As with most of the other protocols that are supported by SilkPerformer, SAP scripts can be recorded with SilkPerformer's recorder. See the Record options section of the SilkPerformer System Settings dialog for options regarding recording profile settings. SilkPerformer Advanced Concepts 385

392 17 LOAD TESTING SAP GUI Recording and Replay Common Settings Figure 7: Recording Profile Settings Script logon as single function When enabled, the logon procedure is scripted as a SapGuiLogon API call. When disabled, multiple API calls (e.g., setting username, password, and hitting ENTER) are scripted. Script low level functions Instead of high level API functions (e.g., SapGuiSetText) low level API functions are scripted (e.g., SapGuiInvokeMethod, SapGuiSetProperty). Script timers Most SAP GUI API functions take an optional timer parameter. When this parameter is defined, measures are generated during replay. When this option is enabled the SAP GUI recorder automatically scripts appropriate timer names for each function. Attach to existing SAP session When enabled, the SAP GUI recorder attaches to an existing SAP GUI session without recording the SapGuiOpenConnection statement. Record window title verification When enabled, the SAP GUI recorder scripts the SapGuiSetActiveWindow with the window title so that it can be verified during replay. In addition to the above mentioned recording settings, some common settings that apply to both recording and replay can be changed. 386 SilkPerformer Advanced Concepts

393 17 LOAD TESTING SAP GUI Recording and Replay Figure 8: Common Profile Settings Log level Defines the level of logging. For troubleshooting, "Debug" should be used. Otherwise "Normal" should be used. When running large load tests, logging can be "Disabled" to reduce memory consumption. Capture screenshots When enabled, screenshots are captured for each new window that is activated. This option is only available when "Show SAP GUI during replay" is enabled. Capture screenshots for every action When enabled, screenshots are captured for each user action that causes a SAP server roundtrip. This option is only available when "Capture screenshots" is enabled. Log control information in TrueLog When enabled, control information for each control on the active window is logged to the TrueLog. This allows you to use TrueLog Explorer's customization features. This option should be disabled when running load tests, as it incurs additional resource consumption. Log control information on error When enabled, control information for each control on the active window is logged to the TrueLog when errors occur during replay. This allows you to troubleshoot replay problems by identifying the current SilkPerformer Advanced Concepts 387

394 17 LOAD TESTING SAP GUI Recording and Replay state of all controls on the screen when errors occur. It is recommended that you use this option during load tests rather than the "Log control information in TrueLog" option. Application Profiles SilkPerformer automatically configures application profiles for recording SAP GUI when information about installed SAP GUI clients can be retrieved from the registry. If there is no automatically configured application profile for SAP GUI, you must define one for SAPLOGON.EXE. Create a new profile and select SAP GUI as the protocol: Figure 9: Application Profile Start Recording Begin recording using the Model Script dialog and the selected SAP GUI application profile. To record an existing instance of a SAP GUI client, select the "Attach to existing SAP session recording profile setting" and start the recorder from SilkPerformer's "Record" menu. When you start recording using the Model Script dialog, SAPLOGON is started and you can choose the server to which you wish to connect. When recording an SAP application using the default profile settings (log 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 388 SilkPerformer Advanced Concepts

395 17 LOAD TESTING SAP GUI Recording and Replay 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 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 SapGuiLogonshould be moved to the Tinit transaction when performing large load tests. See "Preparing for Large Load Tests" for more details. When high-level scripting is enabled, the recorder scripts high-level API functions for most of 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 SAP GUI 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 tech support, please 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 "Difference View" after you execute a TryScript. TrueLogs are explained in detail in this paper's TrueLog section. Password for SapGuiLogon Values in password fields cannot be retrieved via the SAP GUI Scripting API. SilkPerformer'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 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. This is 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, SilkPerformer stops script execution when the password parameter is not customized. SilkPerformer Advanced Concepts 389

396 17 LOAD TESTING SAP GUI Recording and Replay Replay Replay Settings SilkPerformer emulates multiple SAP GUI clients distributed across multiple SilkPerformer agents. Before running a TryScript, check replay profile settings. Figure 10: Replay Profile Settings Replay timeout Defines the timeout during replay. If there is no response from the server during the timeout period, an error is thrown. Show SAPGUI during replay When enabled, the SAP GUI client is displayed during replay. This option should only be used for TryScript runs. It should be turned off during load tests. Enable client-side scripting SAP GUI Scripting must be enabled on each client machine via the Options menu of the SAP GUI client application. When running load tests on multiple agents, this setting must be changed manually on each machine before starting the load test. By enabling the "Enable client-side scripting" option however, SilkPerformer changes this setting automatically on each agent before starting load tests. Use new SAP Visual Design 390 SilkPerformer Advanced Concepts

397 17 LOAD TESTING SAP GUI Recording and Replay SAP GUI can be run in two visual modes: "old" and "new." This setting must normally be changed using the SAP Configuration Tool. By enabling/disabling this option, SilkPerformer performs these changes automatically before starting load test. Measures Figure 11: Measure Profile Settings You can either enable all timers for all control types or select those control types that are of interest to you. Timers are only be created for those method calls that have the optional timer parameter specified. Measures are generated for those method calls that force a roundtrip to the SAP server. Note that not all API calls force a roundtrip. The following measures are generated during roundtrips: Round Trips: Before SAP GUI 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 immediately sends a new request to the server. Controls use this technology to load the data they need for visualization. The count of these token switches between SAP GUI and the server is offered with this measure. Flushes: Counts the number of flushes in the automation queue during server communication. SilkPerformer Advanced Concepts 391

398 17 LOAD TESTING SAP GUI Recording and Replay Interpretation Time [s]: Interpretation time begins after data has arrived from the server. It comprises the parsing of the data and distribution to the SAP GUI elements. Response Time [s]: 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 load tests and can also be monitored in Performance Explorer as one of the SilkPerformer Controller/Agent measures. Running the Test Once profile settings have been configured, a test run can be initiated. All SilkPerformer workload models can be used for the SapGui Forms engine, including: Increase workload Steady state Dynamic All Day Queuing Additional Step 1 When executing load tests, SAP GUI is executed in "Invisible Mode." This means that the "Show SAP GUI during replay" setting is automatically disabled. This also means that no screenshots are taken independent of the profile settings for the screenshot feature. Additional Step 2 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 control information for all controls 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 trouble shoot problems, as you can see the full state of the active window. Additional Step 3 When running a large load test the logon sequence should be placed in the Tinit transaction. TMain then starts with the initial screen after logon. You should then ensure that TMain again ends at this screen position. More details can be found in the Preparing for Large Load Tests section. SAP Client Sessions When executing SAP scripts, client sessions begin with the following function call: SapGuiOpenConnection 392 SilkPerformer Advanced Concepts

399 17 LOAD TESTING SAP GUI TrueLog Server Monitoring Results and end when the last SAP session is closed. SapGuiOpenConnection opens a new SAP connection that can have up to 6 SAP sessions. New SAP sessions can be opened with SapGuiCreateSession. An SAP session can be closed by either closing the main SAP session window, clicking the Exit button, or using the session close button. When all sessions are closed the connection is closed automatically. Before beginning a load test, a monitoring template should be created so that server infrastructure can be monitored. For detailed information about SAP monitoring, see Monitoring. Once a SilkPerformer test is complete, Performance Explorer is used to analyze how the SAP Application performed during the test run. SilkPerformer automatically collects a configurable number of timers and counters for each function that forced a roundtrip to the SAP Server. See the Measures section to specify which performance metrics are collected. Collected client side results can be analyzed and compared with those measures that are collected from the server infrastructure. Performance Explorer offers rich functionality to analyze results and customize reports. For a detailed description, please see the Performance Explorer User Guide. TrueLog TrueLog Explorer is a powerful tool that not only offers a convenient means of exploring SAP GUI applications, it also enables you to add verifications for control values and customize input values for controls that are modified during recording. Structure SAP GUI 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 (e.g., text SilkPerformer Advanced Concepts 393

400 17 LOAD TESTING SAP GUI TrueLog control edits, list entry selections) are shown as sub-nodes grouped by a "virtual" SapGuiRoundtrip node. As you can see from the illustration below, each new window context change (SapGuiSetActiveWindow) begins a new top-level node. 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 394 SilkPerformer Advanced Concepts

401 17 LOAD TESTING SAP GUI TrueLog at a certain API node, the changes are reflected in the TrueLog and the controls are displayed in a tree hierarchy. You can either click a control within a screenshot or click a control in the tree view to perform verification/parsing and customization functions. Figure 13: TrueLog Control Tree The "End Request" tab shows the screenshot after the request is returned from the server. The "Start Request" tab shows the screenshot before the request was sent to the server. 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 (e.g., 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. When switching to the "Start Request" tab, the screenshot taken before the request was sent is displayed. This screenshot shows the correct window, as it has not yet been displayed. The Controls tab shows all controls on the window in their hierarchical order. More information on controls can be found in the following section. SilkPerformer Advanced Concepts 395

402 17 LOAD TESTING SAP GUI TrueLog 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. Verifications and Parsing Verifications and parsing are possible with most control types. TrueLog Explorer offers standard verification and parsing wizards for SAP GUI TrueLogs-all you need to do to access a wizard is right-click a control in a screenshot or the control tree. Via a context menu you can then launch the verification and parsing wizards. Figure 14: TrueLog Verification/Parsing Verifications/Parsing on the last node of a window 396 SilkPerformer Advanced Concepts

403 17 LOAD TESTING SAP GUI TrueLog Verification and parsing functions are scripted after the currently selected API node in the tree. As described in the Structure section, 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. 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. Figure 15: TrueLog Explorer's Step-through-TrueLog dialog Controls that can be customized are highlighted in orange. Controls that have already been customized are highlighted in green. SilkPerformer Advanced Concepts 397

404 17 LOAD TESTING SAP GUI Preparing for Large Load Tests Figure 16: TrueLog Customization 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 Preparing for Large Load Tests Here's what you should consider before running large load tests: 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. 398 SilkPerformer Advanced Concepts

405 17 LOAD TESTING SAP GUI Preparing for Large Load Tests 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 SAP GUI is run in visible mode. This behavior can be enabled/disabled via the "Show SAP GUI during replay" 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 TrueLogOnError 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. 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 SAP GUI 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 SilkPerformer Advanced Concepts 399

406 17 LOAD TESTING SAP GUI Preparing for Large Load Tests // 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; 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 usernames that have sequence numbers appended to them (e.g., 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 hits 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 400 SilkPerformer Advanced Concepts

407 17 LOAD TESTING SAP GUI Monitoring By default SapGuiLogon chooses the second option: logging into the system without canceling other sessions of the same user. Changing the option SAP GUI_OPT_LOGON_BEHAVIOR with SapGuiSetOption allows you to customize this behavior: SapGuiSetOption(SAP GUI_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 Monitoring Creating a Monitoring Template Before running a load test, a custom monitoring template should be created for the current project. This can be done in the current profile settings on the replay/ result settings page. SilkPerformer Advanced Concepts 401

408 17 LOAD TESTING SAP GUI Monitoring Figure 18: Defining a Monitoring Template Check "Automatically start monitoring" and select "Use custom monitoring template". The "Create Custom Monitor Template" button then becomes active. Click this button to create a new template. To later edit the template you've created, click the button again (the button is now called "Edit Custom Monitor Template"). Silk Performance Manager then launches with the template so that additional monitors can be defined. Adding a SAPGUI Monitor Click the "Monitor Server" toolbar button to display the "Data Source Wizard". 402 SilkPerformer Advanced Concepts

409 17 LOAD TESTING SAP GUI Monitoring Figure 19: New Monitoring Data Source Select the "Select from predefined Data Sources" radio button and click "Next". Select the following tree entry: "Application Server/SAP/SAP GUI Monitoring". Figure 20: New SAP GUI Monitor Specify a hostname and alias for the SAP server and click Next. SilkPerformer Advanced Concepts 403

410 17 LOAD TESTING SAP GUI Monitoring Figure 21: SAP GUI Monitor - Step 1 As this monitor is a script-based monitor, the following page prompts the user for several project attributes that are required by the monitor in order to connect to the SAP System. The monitor makes use of the ST03N transaction. A detailed description of the steps of this monitor is included in the "SAP GUI Monitor Steps" section. Figure 22: SAP GUI Monitor - Step 2 Here is a description of the required parameters: 404 SilkPerformer Advanced Concepts

411 17 LOAD TESTING SAP GUI Monitoring Parameter Description Username Username with ST03N access rights. This user is used with multiple concurrent logins. Be aware of this as SAP tracks multiple logins. Password Password ClientNum Client (e.g,, 850) Language Language (e.g., EN) ConnectionString Connection (e.g.,/sap_codepage=1100/fullmenu / SAPSERVER /3) Entity An entity from the ST03N transaction (e.g., dialog, RFC, background) TimeFrame ST03N transaction offers average values of the last X minutes. You can specify this time frame in minutes here. The next page allows you to select the measure that should automatically be added to the new monitor graph. No selection is required. Figure 23: SAP GUI Monitor - Step 3 SilkPerformer Advanced Concepts 405

412 17 LOAD TESTING SAP GUI Monitoring Defining a Monitor Report A monitor report can be defined to capture measures during load tests. Measures are logged to a.tsd file that can later be used for analysis. In the toolbar, click the "New Monitor Report" icon. It is recommended that you change the monitor interval to 20 seconds or higher. This can be done via the Monitor Report's Properties dialog. Following that you can drag all server measures of the SAP GUI monitor to the Monitor Report Window. Figure 24: New Monitor Report When starting a load test with automatic monitor-start enabled, all monitor reports automatically begin writing results to a.tsd file, which is stored in the result directory of the load test. SAP GUI Monitor Steps The SAP GUI monitor is a script-based monitor that executes a SAP GUI script so that it can receive all offered measures. The monitor makes use of the ST03N transaction. To receive these measures, the user that is specified in the monitor properties must have access to this transaction. 406 SilkPerformer Advanced Concepts

413 17 LOAD TESTING SAP GUI Monitoring The ST03N transaction looks like this: Figure 25: SAP GUI Monitor Steps The monitor steps are: 1 Login with the provided user credentials 2 Execute ST03N 3 Switch to "Service Engineer" view 4 Double-click the tree item "Detailed Analysis/Last Minutes Load/Total" 5 Specify the defined interval in monitor properties (e.g., last 5 minutes) 6 Click the OK button 7 The row with the defined entity (based on monitor properties) is located in the statistics grid (as shown in the illustration above). 8 If the entity is found, measures are populated with the values in the entity line. 9 These steps are repeated as long as the monitor is executed. As it can take several seconds to perform these steps it is recommended that you increase the default-monitoring interval from 10 to 20 or 30 seconds. SilkPerformer Advanced Concepts 407