A.7 Script Variable Rules

Script variables are used to allow command parameters to be changed globally within a script. Variables can be used to control LOOP counts, to define port numbers, to specify the data type for a SEND, and so on.

Each variable has a variable type, depending on its usage as a command parameter—the variable type is not exposed, per se.
Random variables can be used for sleep times or for send and receive buffer sizes only.
Non-zero integer variables can be used for loop count, send size, or buffer size. Variables used for loop count may not be used for any SEND parameter, and vice versa.
Integer variables that allow the keyword DEFAULT are used only for buffer size.
The name of the variable must be unique within a script, and not contain spaces.

The Default Value field lets you specify the initial value for the variable when the script is installed. The value entered should allow the script to behave as expected without modification. The field will accept numbers to 999999999. On some variable types, such as the buffer size on SEND and RECEIVE, you can use other values, such as the term “DEFAULT.” The DEFAULT value depends on the network protocol and the endpoints you are using. AUTO, when entered for the source or destination_port variables, specifies that the TCP stack should dynamically choose available ports to use in the test.

By contrast, changes to the Current Value apply only to a specific network connection or endpoint pair. Use the Default Value field if you want to specify a value that applies to all endpoint pairs.

The type of variable used for the SLEEP command or for send and receive buffer sizes allows only five values: Constant Value, Exponential, Normal, Poisson, and Uniform Distribution. The Constant Value is a single value, but each distribution is entered as a range. All sleep values are in milliseconds (ms). For more information, see “Section A.7.1, Setting Sleep Times,” below. All buffer sizes are in bytes. For more information, see Section A.7.4, Using Random Buffer Sizes for the SEND Command.

A.7.1 Setting Sleep Times

The time parameter value on the SLEEP command lets you emulate delays caused by users or processing time. Before the next script command is executed, the endpoint sleeps for the number of milliseconds specified here. The sleep does not consume CPU cycles; it only simulates a delay, not the CPU or disk overhead that a real application might use.

The location of the SLEEP command in the script is important. If the SLEEP command occurs before the timing loop, the sleep does not affect the data sent and received. This means that timing records do not reflect the impact of the SLEEP command on the test measurements. If the SLEEP command occurs within the timing loop, the results include the effects that the SLEEP command had on the sending and receiving of data.

The Current Value field in the Script Editor Edit Variable dialog box lets you change the amount of time to sleep. By default, scripts have their delay values set to a Constant value of 0, which means that endpoints execute scripts as quickly as possible.

The script variable initial_delay is different from the other sleep variables. The longest allowable time for initial_delay is 90 minutes—that is, 5,400,000 ms. Longer values cause Endpoint 2 to time out, and the connection fails.

A script can sleep for a constant duration, or the sleep time can be randomly distributed using one of four distributions. When choosing a random distribution, be sure to choose upper and lower limits that are far enough apart for the endpoints to create a range of random sleep times. If the limits are too close together, you will not see the effects of random sleeps. For example, a lower limit of 5 ms and an upper limit of 7 ms will not provide enough variance for interesting random sleeps.

Guidelines for how to determine the values for the upper and lower limits depend on the purpose of the specific SLEEP command.

If you are using a SLEEP command for an initial_delay, a lower limit of 0 and an upper limit of 1000 (that is, 1 second) will emulate the random effects of a large network.
If you are using a SLEEP command for a delay_before_responding, tailor the values to the activity that you are emulating. If you are using this parameter to control throughput, use a narrow range between the upper and lower limits and relatively small values. The upper limits should not exceed 100, since large values cause measured throughput to reduce rapidly.

Another use of the delay_before_responding is to emulate the delay time on a server or client-server application. In this case, a reasonable lower limit is 5. You should use high upper limits. For example, if you are emulating a three-tiered application, the upper limit should be several thousand milliseconds.
If you are using a SLEEP command for a transaction_delay, the values should emulate the rate at which transactions are happening based on the number of users. You should determine the typical delay between a user’s transactions and convert the amount of time to milliseconds (ms).

For example, if you are emulating users transferring files, and the average user transfers a file every 20 minutes, there is a typical delay of 20 minutes. 20 minutes is equal to 1200000 ms. Divide this time by the number of users. If you have 10 users, the 1200000-ms delay time is reduced to 120000 ms. This figure determines the upper and lower limits for SLEEP. For the lower limit, reduce this time by 10%. In this example, use a lower limit of 120000. For the upper limit, increase this time by 10%. In this example, use an upper limit of 12000000.
As a general rule, if you are emulating a large number of users, use small values for the upper and lower distributions. If you are emulating a small number of users, you should use large values.

The four possible distributions for random sleep time are Uniform, Normal, Poisson, and Exponential. If you choose one of these random distributions, you also must select the upper and lower limits for the random times that are generated.

Uniform

In the following graph, the distribution of sleep times between the upper and lower limit is completely uniform. Any number within the upper and lower limits is as likely to be used for the sleep time as any other number. If you plot the sleep times against the number of occurrences, the graph should be a flat horizontal line.

Normal

In the following graph, the distribution of sleep times between the upper and lower limits is a normal, or bell-curved, distribution. If you plot the sleep times against the number of occurrences, the graph should be a bell curve.

The Marsaglia-Bray algorithm is used to generate the normal distribution. The average value of the distribution is determined from the upper and lower limit. In a normal distribution, most values occur within +/-3 standard deviations with respect to the average. The standard deviation is also calculated from the upper and lower limits, as no value exceeds those limits.

Poisson

In the following graph, the distribution of sleep times between the upper and lower limit is a Poisson distribution. If you plot the sleep times against the number of occurrences, the graph should look like a Poisson distribution. A typical use of a Poisson distribution is to emulate data inter-arrival rates

The incomplete gamma function is used to generate the Poisson distribution. The average value of the distribution is determined from the upper and lower limit. In a Poisson distribution, most values occur within +/-3 standard deviations with respect to the average. The standard deviation is also calculated from the upper and lower limits, as no value will exceed those limits.

This graph is based on an average and standard deviation. This means that 99% of all values on the graph should be within +/-3 times the standard deviation. An endpoint calculates the standard deviation by dividing the difference of the upper and lower limits by three.

Exponential

In the following graph, the distribution of sleep times between the upper and lower limit is an exponential distribution. In other words, if you plot the sleep times against the number of occurrences, the graph’s maximum should be at the upper limit and minimum should be at the lower limit.

The lower limit is where the asymptote occurs. The exponential distribution centers on the average of the upper and lower limit. This should be the average of the distribution. An endpoint uses the average to calculate the distribution and makes sure that no values exceed the upper limit.

A.7.2 Setting the Send Data Rate

You can send data at a specific rate over all supported protocols. The send_data_rate script variable controls the rate the data is sent over the protocol. You may want to specify a specific data rate when generating a constant amount of network traffic or emulating multiple slower links across a single higher speed link. The data rate calculated by the endpoint is based on the amount of data specified. Because this rate does not include protocol and link-layer data lengths, the actual bandwidth consumed in the network is slightly higher than the send_data_rate you specify.

Specify a send_data_rate or select one of the following rates:

28.8 kbps (modem)
33.3 kbps (modem)
56 kbps (modem)
64 kbps (Fractional T1)
128 kbps (Fractional T1/ISDN)
1.544 Mbps (T1)
2.048 Mbps (E1)
8.448 Mbps (E2)
10 Mbps (Ethernet)
44.736 Mbps (T3)
155.52 Mbps (OC-3)
UNLIMITED

You can modify the send_data_rate in the script you want to use. The endpoint sending the data calculates how fast to send it, and then sends it continuously while the timing record is being generated. The total amount of data per timing record is divided by the buffer size to get the amount of data for each SEND.

Here are some tips for achieving a constant send_data_rate:

Send a large amount of data with respect to the buffer size and rate. For example, if you are using a buffer size of 8 KB, setting a send_data_rate of 1 million bytes will give you a more consistent data rate. The faster the rate, the more data you need to send to achieve a constant rate. Be aware that the default buffer size varies based on network protocol and operating system.
When trying to achieve a constant send rate, some scripts are better than others. Scripts that have CONNECTs within a timing record are not good for trying to attain a steady send data rate. Scripts that contain only sends within a timing record are better for achieving a steady send rate.
The timers in different endpoint platforms have different resolution. The resolution affects the accuracy we can achieve with the send data rate. Some experimentation may be necessary to find the best send_data_rate to use for your endpoint platform.
As you increase the rate at which data is sent, you may need to increase the amount of data being sent. The more data sent in the timing record, the more opportunity the endpoint has to smooth out the rate. For example, when sending at 10 Mbps, you may need to send 1 million bytes of data per timing record to achieve a constant rate. The amount of data may need to be increased proportionately as the rate increases. Some experimentation may be necessary.

A.7.3 Choosing the Datatype for the SEND Command

The third parameter of the SEND command lets you choose the contents of the data. When editing this variable, choose one of the available values, a list of compression files (with the extension .cmp) that emulate various types and amounts of data.

Not every datatype listed in the table below is shipped with AppManager, but a ZIP file containing all the available .cmp files can be downloaded free from the NetIQ Web site: www.netiq.com/support/pe/pe.asp.

The following table summarizes the available .cmp files and datatype values:

send_datatype	Description
ZEROS	The data contains all hex zeros. This is the simplest data for the endpoints to generate. Data consisting of all zeros is easy to compress, by even the most primitive compression techniques.
NOCOMPRESS	Each byte of data is randomly selected from among the 256 possible hexadecimal values. Since there is usually no pattern to the sequence of characters, buffers full of NOCOMPRESS data are difficult to compress effectively. Data is generated once during test setup; this does not increase CPU usage at the endpoints.
Named .cmp files	Choose one of the predefined data files listed in the rows below. These files represent typical types of computer data, from the Calgary Corpus (see http://links.uwaterloo.ca/calgary.corpus.html for more information)
bib.cmp	text file (bibliography)
book1.cmp	text file (book 1)
book2.cmp	text file (book 2)
geo.cmp	binary file (geophysical data)
lena.cmp	binary graphic file (GIF format)
news.cmp	text file (newsgroup text)
paper1.cmp	text file (paper 1)
paper2.cmp	text file (paper 2)
pic.cmp	binary file (CCITT fax test)
progc.cmp	text file (C program source)
progl.cmp	text file (LISP program source)
progp.cmp	text file (Pascal program source)
trans.cmp	text file (terminal session)
user01.cmp through user10.cmp	User-defined data files. Data is read from the file CMPFILES\USERxx.CMP, which you put at the endpoint computers. You may put anything you choose in these files. Up to 10 user files can be created to contain any data desired. Files with the same name must contain the same data on each endpoint where they are used if data validation is used.

A.7.4 Using Random Buffer Sizes for the SEND Command

Some applications do not send data packets of a fixed size. For example, streaming applications may not buffer smaller packets and send them out in larger chunks, but instead send data as quickly as it becomes available. The ability to choose a random buffer size lets you emulate bursty traffic and some widely used commercial applications, such as stock-ticker applications and video conference applications.

Use the NetIQ Script Editor (with Application Scanner) to select random buffer sizes for the SEND command in an application. The changes apply to the buffer_size parameter on the SEND and RECEIVE verbs of an application script. When you are using a connectionless protocol—UDP or RTP—the buffer size determines the payload size of datagrams sent over the network. For connection-oriented protocols, you should plan to disable the Nagle algorithm for testing with random buffer sizes; otherwise, Nagle determines that data will be gathered into maximum segment-sized (MSS) chunks before it is sent.

The RECEIVE command that corresponds to the SEND command in a particular script cannot be edited to use a random buffer size. In most cases, it is the same size as the SEND buffer_size. The table below summarizes the behavior of the RECEIVE command, depending on the SEND buffer_size you select: either Constant, DEFAULT, or Random distribution.

SEND buffer_size Parameter	RECEIVE buffer_size Parameter
	Constant	DEFAULT	Random
Constant	The effective RECEIVE buffer size is the same as the RECEIVE command's Constant value	The effective RECEIVE buffer size is the same as the SEND default buffer size	The effective RECEIVE buffer size is the upper limit of the RECEIVE command's random variable; it is not randomly generated
DEFAULT	The effective RECEIVE buffer size is the same as the RECEIVE command's Constant value	The effective RECEIVE buffer size is the same as the RECEIVE default buffer size	The effective RECEIVE buffer size is the upper limit of the RECEIVE command's random variable; it is not randomly generated
Random	The effective RECEIVE buffer size is the same as the RECEIVE command's Constant value	The effective RECEIVE buffer size is the upper limit of the SEND default buffer size; it is not randomly generated	The effective RECEIVE buffer size is the upper limit of the RECEIVE command's random variable; it is not randomly generated