NDIS Driver Developer's Tool Kit for OS/2 and DOS - Random Redirected Transform Test User's Manual

Purpose of this Manual
This document is the user manual for the Random Redirected Transfer Test Tool (hereafter referred to as RRTT). All of the functions and features available with RRTT are described here in detail.

Prerequisite Knowledge
Although no previous knowledge is required to exercise an RRTT session, the information in this manual is intended for the experienced programmer who is involved in the development of NDIS drivers. The reader should have an understanding of the procedures needed to meaningfully test a network driver.

Overview
RRTT provides a means of verifying a network's file transfer integrity. It resides as a top-level application package capable of transferring files of various size and content to the network nodes of your choice. RRTT is generally used after the TestTool application (also supplied with the NDIS Driver Developer's Tool Kit) has thoroughly demonstrated your development driver's functionality.

RRTT uses a bi-directional copy and compare sequence to verify proper file transfers. As many as 100 unique session may be simultaneously active on one network.

Software Installation
RRTT is a stand alone application requiring no network specific installation.

System Requirements
RRTT can run under either DOS or OS/2*. The minimum hardware configuration is two AT or PS/2 or compatible PCs with at least 640 KB of RAM, either a monochrome or color monitor, a hard drive of at least 10 MB or larger capacity, and a LAN Adapter card. The LAN Adapter card may reside in either one or both of these machines.

Chapter 2. Using RRTT
The RRTT utility uses script files and/or a User Interface to configure and execute file transfer tests. This chapter will, by way of example, describe how to navigate the straight forward User Interface, run a simple test, and change default User Options. Script files will then be explained which can further simplify testing procedures.

User Interface
Part of the User Interface for RRTT is menu driven and part is command driven. At the top of the screen is a Menu Bar, enabling the user to display one or more of the User Options or receive help. Additionally, some status indications are displayed at the right of the Menu Bar. Underneath the Menu Bar is the Information Screen which holds all of RRTTs user option settings. There is a different screen for each entry on the Menu Bar. Below the Information Screen is a Command Line used for entering commands. The bottom half of the screen is a Monitor Screen used for displaying test progress. See Figure 2-1.



There are several keys which manipulate RRTTs user interface.

The  key moves the cursor off the command line and down into the Monitor Screen. Once there, the up and down arrow keys can be used to scroll through the 50 lines of history information. The  key is a toggle. When the cursor key is in the message area, the  key will move the cursor back up tot he command line.

The  and  arrow keys scroll up and down the command line history. This allows previous commands to be edited and/or repeated. If the cursor is currently in the Monitor Screen (due to an , then the up/down arrow keys scroll through the screen's history and not through the command line history. An  will restore the cursor to the command line and the arrow keys will again scroll through the command history.

The  and  arrow keys move the cursor left and right within the current command line.

The  key toggles whether typing will insert at the cursor point or type over. The default is type over mode. In type over mode, the cursor is a thin underline. In insert mode, the cursor is a full block.

The  and  keys will move the menu bar tot he next information screen.  moves the menu to the right while  moves the menu to the left.

The <Alt> key jumps to one of the Menu Bar items. Each of the menu items has a letter which is highlighted. When the <Alt> key is pressed with one of the highlighted letters, that Information Screen pops up. This method is not available while a test is running.

Information Screens
The Information Screens, selected by the Menu Bar, display all of the various User Options available for configuring an RRTT session. Using the interface keys described above, each of the parameters chosen can be displayed. In addition, a General Information Screen is available for monitoring overall test information while an RRTT test is running.

Help Screen
Help screens are available by entering the ? Or HELP command. A list of all the RRTT commands accompanied by a description of their usage is displayed. The up/down arrows allow for scrolling through the command list. Upon selecting the command of interest, you may type <ENTER> to automatically type that command onto the command line. To exit this help screen without having the command entered into the command line type <ESC>. In either case, RRTT will return to its previously displayed menu.

Testing with RRTT
RRTT has several User Options that can be adjusted by the user. These options come with reasonable default settings and only a few may require your attention. As an introduction to RRTT, the default settings for the User Options are acceptable. To run RRTT requires only that one or more destination drives be selected. You may wish to use your hard drive for initial running as a reality test for RRTT. The DRIVE command followed by a list of drives and/or network nodes can be achieved as follows. >DR C: Any additional names should be separated by at least one space. To activate a test type RUN. At this point RRTT will begin running a copy and compare sequence to each of the destinations chosen. The default settings will cause RRTT to generate a dummy file of random size and contents. The file will be transferred to and received from the root directory of drive C: To observe the test in progress, display the General screen as noted on the menu bar. Test duration, average transfer times, and test iterations are all present with this screen.

The User Interface is altered slightly while a test is running. Figure 2-2 shows the layout when the General Information Screen is displayed.



Figure 2-2: RRTT Test Display

In the particular run shown here, a log file is active and denoted by the L in the upper right hand corner of the interface. The test start time and current time are displayed along with the operating system being run and the session number currently set. The drive chosen is \\server1\root and is shown on the General Information Screen as well as the Monitor Screen. The General screen keeps track of test execution with an average drive performance number in Kbytes per second. These are separate for transmit and receive and are denoted by Xmt Kb/ s and Rcv Kb/s respectively. The total number of bytes sent over the network is displayed for each destination drive along with any errors that have occurred.

During execution the command line is no longer at the user's disposal, instead the current state for the test is displayed. The test iteration count along with the operation under way are reported to this field. There are five tasks that RRTT may be executing during a test session: create, transfer, receive, compare, or report. Create is displayed while RRTT builds the next dummy transfer file. Transfer is displayed while RRTT builds the next dummy file from the destination drive. Receive is displayed while RRTT receives the dummy file from the destination. Compare is displayed each time RRTT compares files. This happens twice per destination, once after a transmit and once after a receive. Report is displayed only briefly while test reports are generated.

The Monitor Screen monitors operations during an RRTT session. Information, such as successful command execution and instantaneous test results, is tracked on this screen. The amount of information displayed may be adjusted by the MMODE command prior to starting a test. Figure 2-2 shows how the Monitor Screen looks in VERBOSE mode. The destination under test, the file size used, the block size used, and the block delay time used are all reported to the Monitor. The success or failure of each copy/compare sequence follows the transfer parameters along with transfer times in Kbytes per second. This sequence repeats for each test iteration.

Once an execution is under way, there are a different set of commands used to control program flow. These options are one letter commands displayed in square brackets on the right of the command line. The two basic commands used during run are <F10> and S.

To pause the RRTT test type <F10>. Upon completion of its current task, RRTT will toggle to the Monitor Screen and allow scrolling through past message lines. Typing a second <F10> will resume the copy and compare sequence.

To stop the test type S, which will return you to the command line interface. Another test may be run using the RUN command or the session may be exited by typing EXIT.

This is all that is required to run RRTT utility. Tailoring RRTTs file transfer parameters and test report modes is available from the command line or from script.

Changing User Options
Each User Option has a unique command string and may be altered by the user. Each option is explained in the help text displayed with the ? Or HELP command For most commands, only the first two letters need to be typed. The same two letters are displayed on the various Information Screens in square brackets along with its current setting. Some of the commands require a range or mode parameter. Here some of the basic commands will be described by example, leaving the more complete explanation for the Command Description Chapter.

The most common User Options to vary are the transfer file contents, the transfer file size, the block transfer size, and the block delay time. These variables control, to a great extent, how a network driver is being exercised. The following four commands demonstrate one way to set their parameters: >      >FPATTERN RAN 0X00 0X60 >FSIZE INC 1 10000 >BSIZE RAN 100 2000 >BDELAY 100 FPATTERN STANDS FOR "file pattern" and changes the contents of the dummy transfer file to be a sequence of random numbers between 0x00 and 0x60. The string RAN is used to direct FPATTERN to use a random range. The Information Screen labeled File displays the current setting. After this command is entered, the values are displayed in square brackets to indicate a range of numbers.

FSIZE stands for "file size" and changes the size of the dummy transfer file. Here, RRTT is directed to increment the file size by one byte but not to exceed 10000 bytes. The file size changes once per pass. In this configuration, after 10000 test iterations, each file size will have been covered and the sequence will start over with a file size of one byte.

BSIZE is the command to alter the "block size" used in transferring a file. This command will set the block size generator to use sizes randomly between 100 bytes and 20000 bytes. Only one size is used per pass. Note that for some test iterations, the block size will be larger than the file size. The block sizes actually used will be the smaller of the two sizes and a true random range for block size will not be accomplished for every pass. It is the user's responsibility to avoid or at least be aware of this type of limit conflict.

BDELAY is the command to alter the "block delay time" used between individual block transfers. In this example, the delay time between each block transfer will be a fixed 100 milliseconds. The corresponding display for block delay time is found, along with block size, on the Transfer Information Screen.

At this point a copy and compare session may be inititiated with the RUN command and the above parameters will be incorporated. To return to the command's default values, use the RESET command, which resets all the User Options including the ones set above.

Changing Report Mode
RRTT is capable of generating reports for the Monitor Screen, a log file, or a printer. There are a few User Options that allow variations on the reports produced. The MMODE (monitor mode), the LMODE (log mode), and PMODE (printer mode) are the commands used. The most common report mode to alter is the log report.

>LMODE SILENT This command will turn the log file on and reduce its output from the default setting of TERSE to SILENT. Only the first three letters of SILENT needed to be entered. In this mode only error encountered will be entered into the log file. A red letter L is registered in the upper right-hand corner of the screen, indicating that a log file is being produced. If a log file already existed, then new information will be appended to it. The Information Screen labelled Report shows the mode settings for the log file.

Using Script Files
Script files give RRTT as much flexibility as needed for performing lengthy top-level network tests. A script file, which is an ASCII text file containing RRTT commands, may be entered while invoking RRTT, in which case no User Interface will appear. Instead, all the commands in the file will be automatically executed.

Along with the interactive commands, there is a special decision command, JUMP, which can perform conditional or unconditional jumps to subsequent commands in the Script File. A Script File may also contain a label to be used in conjunction with the JUMP command. The JUMP command is described in detail in the command description portion of this manual.

Below is an example of an ASCII script file. You can generate this script file by entering these lines into a file using a text editor. To run a script file from RRTTs command line type: >SCRIPT script_file_name This same script file could also be entered on the command line as follows: [C:\]RRTT script-file-name By invoking RRTT with a script file, the user interface is never engaged, and the Monitor Screen prints test progress to standard output.

User Command Lists
The User commands available by RRTT are divided into three categories: Static User Options, Executable User Options, and Run Time User Commands. Each specific command under one of these categories is listed here for a quick reference and described in detail in subsequent chapters.

Static User Options
Static User Options are commands that allow the user to configure the RRTT test as desired. They do not perform any action other than establish a parameter to be used during the next test execution.

The following are the Static User Options. These commands set various values that will be used during an RRTT test.

Executable User Options
The following are the Executable User Options. These commands are not displayed on any of the Information Screens. They perform tasks that require some type of execution.

Run Time User Commands
The following are the Run Time User Commands. These are the set of commands that are used during a test. Each takes effect after RRTT completes its current operation.

Each of these commands is described in detail in the Command Description Chapter of this manual.

Chapter 3. Command Descriptions
This chapter is devoted to detailed descriptions of each User Command, arranged in alphabetical order. These descriptions are given in the following format:

Notices
January, 1996

Issued by:
 * IBM Corporation
 * Personal Software Products
 * 11400 Burnet Road
 * Austin, Texas 78758

Second Edition (January 1996)

First Edition (May 1993)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Copyright Notices
© '''Copyright International Business Machines Corporation 1993. All rights reserved.'''

Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers
References in this products to IBM products, programs or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries in writing to the IBM Director of Commercial relations IBM Corporation Purchase, NY 10577, U.S.A.

Trademarks
The following terms denoted by an asterisk (*) in this publication are trademarks of the IBM Corporation in the United States and/or other countries: IBM                   OS/2