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

From EDM2
Jump to: navigation, search

Preface

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.

Chapter 1. Introduction

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.

NDISRRT1.GIF

There are several keys which manipulate RRTTs user interface.

The <F10> 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 <F10> key is a toggle. When the cursor key is in the message area, the <F10> key will move the cursor back up tot he command line.

The <Up> and <Down> 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 <F10>, then the up/down arrow keys scroll through the screen's history and not through the command line history. An <F10> will restore the cursor to the command line and the arrow keys will again scroll through the command history.

The <Left> and <Right> arrow keys move the cursor left and right within the current command line.

The <Insert> 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 <TAB> and <Shift><TAB> keys will move the menu bar tot he next information screen. <TAB> moves the menu to the right while <Shift><TAB> 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.

NDISRRT2.GIF

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.

# use file sizes randomly between 10000 and max
FSIZE RAN 10000
# turn off block delay
BDELAY OFF
# report all activity to a log file
LMODE VERBOSE
# erase any old log information
LMODE RESET
# repeat this test 2 times then stop
TREPEAT 2
# set a destination for testing
DRIVE
# run the test
RUN

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.

NAME DESCRIPTION
BDelay Set the block delay for file transfers
BInter Turn on/off block transfer interleaving
BSize Set the block size for file transfers
DRive Set destination drive for testing
ERror Set number of errors before test abort
FDelay Set the file delay time between transfers
FName Set the transfer file name if user defined
FPattern Set the file contents to a specific pattern
FRepeat Set the file repeat count per test pass
FSize Set the transfer file size
LMode Turn on/off log and set log report mode
LName Change default log file name
MMode Set Monitor Screen report mode
PAusecopy Pause the test prior to comparing a file
PMode Set printer report mode
SEssion Set a unique session number
TRepeat Set the number of test iterations

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.

NAME DESCRIPTION
HELP or ? Display on-line help screens
EXit Exit the application
LComment Write a comment into the log file
LOAD Load a configuration file
QUit Exit the application
REset Reset all the User Options
RUN Run a test
SAve Save the current configuration
SCRIPT Execute a script file from within the UI

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.

NAME DESCRIPTION
S Stop current test
X Exit application
F10 Pause test and toggle to Monitor Screen
TAB Move to next Information Screen

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:

Name This field displays the command name with a brief label denoting its function.
Syntax The Syntax section gives the format of the command and the type of operands allowed. The capitalized portion of the command must be typed while the lower case portion of the command may be left off. For example the command FSize may be abbreviated to FS.

Operands enclosed in square brackets "[]" are option and only one operand in a list enclosed with arrow brackets "<>" may be used.

In many cases if a parameter is left out, the default minimum or maximum is used. Numerical operands may be entered as hexadecimal as well as decimal. If a numeric parameter has a preceding 0x, then it is read as hexadecimal. The default interpretation is decimal. There are a few exceptions to this rule where noted.

Some commands except the qualifying strings INCREMENT or RANDOM, which determine how to interpret the following hexadecimal or decimal values. Many commands accept the RESET, DEFAULT, VERBOSE, TERSE, SILENT, ON, and OFF strings. All of these strings require only that their first three characters be typed. The meaning of each string is explained in each command description.

Description The Description section describes what the command does and how its operands are interpreted. It may also contain a usage suggestion when appropriate.
Example The Example section gives one or more example of the command usage. The ">" preceding each command denotes the command line prompt and is not typed.
Limits DEFAULT: This field indicates the default settings for the command. N/A is used for Not Applicable.

MIN: This field indicates the minimum allowable value for the command. N/A is used for Not Applicable.

MAX: This field indicates the maximum allowable value for the command. N/A is used for Not Applicable.

BDELAY - block delay time

Syntax BDelay [<DEF, INC, OFF, RAN, RES>] ms_time [max_time]
Description BDELAY, displayed on the Transfer Information Screen, sets the delay time used after each individual block of data is transferred. The time is accepted in milliseconds, ranging from 0 to 1000 milliseconds. In addition to accepting a fixed time, this command may be entered with one of the following operand strings: DEF, INC, OFF, RAN or RES.

DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string.

INC (short for INCREMENT) directs RRTT to increase the delay time by a fixed step size for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used.

The OFF string turns the block delay time off which is equivalent to setting the delay time to zero.

RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used.

RES (short for RESET) functions the same as the DEFAULT string and returns the command's parameters back to their original settings.

Example <BD RAN 30 90

Sets the block delay time to be a random value between 30 and 90 milliseconds.

BINTER - turn on/off block interleaving

Syntax BInter <DEF, OFF, ON, RES>
Description Block Interleave, displayed on the Transfer Information Screen, turns on and off drive interleaving during a file transfer. If more than one destination is active and there is more than one block of data to transfer per file, the BInter will transfer one block of data to each destination before proceeding to the next block.
Example >BI ON

Turns on the interleave capability.

Limits DEFAULT: OFF

MIN: N/A

MAX: N/A

BSIZE - block size for file transfers

Syntax BSize [<DEF, INC, RAN, RES>] size [max_size]
Description Block Size, displayed on the Transfer Information Screen, determines the size of the blocks, in bytes, used in transferring a file. Large files are divided into block sizes and then transferred from or to a destination. A block delay after each block transfer may be introduced via the BDELAY User Options. If the file size is small, large block sizes have no effect.

DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string.

INC (short for INCREMENT) directs RRTT to increase the block size by a fixed number of bytes for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value is used.

RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used.

RES (short for RESET) functions the same are the DEFAULT string and returns the command's parameters back to their original settings.

The block sizes used can greatly effect the network performance numbers displayed. For small block sizes the Kbytes/Second performance number will be low.

Example >BS INC 256 0x2000

Sets the block size to increment by decimal 256 for each new file transfer but not to exceed hexadecimal 2000.

Limits DEFAULT: RANDOM 120480 Bytes

MIN: 1 Byte

MAX: 20480 Bytes

DRIVE - set the destination drive list

Syntax DRive [<-,RES>] drive_name [drive_name ...]
Description Drive sets or clears active destination drives. A list of destinations separated by spaces may be entered. If a destination can not be accessed the Monitor Screen will respond with an error and that destination will not be entered onto the list. The Information Screen labeled Dest displays a list of up to 50 unique destinations. Each name may be up to 30 characters long.

To remove a drive from the list a "-" must be supplied before the drive list and separated by spaces. Each active drive on the list is then removed. RES (short for RESET) will clear the entire drive list.

RRTT will not run unless at least one destination is active.

Example >DR - \\server1\root g:\tmp

Removes both the \\server1\root and g:\tmp destinations from drive list.

Limits DEFAULT: no active net names

MIN: 1

MAX: 50

ERROR - error count before test abort

Syntax ERror<DEF,OFF,RES,error_count>
Description Error, displayed on the Loop Information Screen, sets the number of errors allowable prior to terminating a test session. This command is effectively a "break on error" switch. If Error is set to 1, RRTT will stop the session if an error occurs. If Error is set to OFF, RRTT will continue if and error occurs. If Error is set to a value other than 1, RRTT will continue until the appropriate number of errors has occurred.
Example >ER OFF

Continue upon receiving an error.

Limits DEFAULT: 1(break on error)

MIN: OFF

MAX: 999999999

EXIT - exit the RRTT utility

Syntax EXit
Description Exit exits the RRTT utility.
Example >EXIT

Exits the RRTT utility.

Limits DEFAULT: N/A

MIN: N/A

MAX: N/A

FDELAY - file delay time

Syntax FDelay <DEF,OFF,RES,delay_time>
Description File Delay, displayed on the Transfer Information Screen, sets a delay time after each complete file transfer. The value is accepted in floating point seconds. This option can be used to throttle down the RRTT test by placing it in a sleep state after each file transfer. This is not the same as the block delay time which holds off back to back transfers a given block delay time. Here, File Delay simply waits the appropriate number of seconds before transferring another file.

OFF sets the delay to zero. DEF and RES both return FDelay to the default setting. INC, RAN, or ON are not acceptable strings.

Example >FD 1.5

Sets a delay between files of 1.5 seconds.

Limits DEFAULT: OFF

MIN: 0

MAX: 30.0 seconds

FNAME - transfer file file name

Syntax FName <DEF,RES,transfer_file_name>
Description File Name, displayed on the File Information Screen, sets the name of a user created transfer file. If this command is used, all of the internal file attributes used for creating a dummy file are overridden and the named file is used instead. The named file must exist in the current directory for it to be accepted.
Example >FN USER.TST

Directs RRTT to use the file USER.TST for network transfers rather than create its own file.

Limits DEFAULT: RRTTS00.JNK

MIN: N/A

MAX: N/A

FPATTERN - file pattern for transfer files

Syntax FPattern [<DEF,INC,RAN,RES>] value [max_value]
Description File Pattern, displayed on the File Information Screen, controls the contents of an internally generated transfer file. The pattern can be controlled a few different ways.

DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string.

INC (short for INCREMENT) directs RRTT to step by a fixed increment for each ASCII byte. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered it is interpreted as the maximum size to use before repeating the sequence. The first step of an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used.

RAN (short for RANDOM) directs RRTT to use random extended ASCII values between the minimum and maximum supplied on the command line. The first value after the RAN string is the minimum random number. The second value is the maximum value. If the maximum or both values are left blank then the default minimum and maximum values are used.

RES (short for RESET) functions the same as the DEFAULT string and returns the commands parameters back to their original settings.

A fixed input string may also be used extending up to 45 characters long.

Examples >FP 12345abcde

Fills the transfer file with repetitions of this string.

>FP RAN 0x20 0xE0

Fills the file with random bytes ranging in value from 32 to 224 decimal.

Limits DEFAULT: RANDOM 0X00 0XFF

MIN: 0

MAX: 0xFF or 45 character string

FREPEAT - transfer file repeat count

Syntax FRepeat <DEF,RES,count>
Description File Repeat count, displayed on the Loop Information Screen, sets a repeat counter allowing for the same dummy transfer file to be transmitted more than once to a destination without generating a new transfer file. This eliminates the time to create a transfer file.

DEF (short for DEFAULT) and RES (short for RESET) both return the repeat count to its original setting.

File Repeat is no the same as Test Repeat, which causes the entire RRTT test to be repeated a specific number of iterations. File Repeat simply runs copy and compares with the same file the set number of times and then generates a new dummy transfer file.

An FREPEAT value of one means transfer the file once per destination, rather than repeat the file transfer once.

Example >FR 1000

Directs RRTT to use the file 1000 times per destination prior to creating a new transfer file.

Limits DEFAULT: 1 (no repeat)

MIN: 1

MAX: 999999999

FSIZE - file size for dummy transfer file

Syntax FSize [<DEF,INC,RAN,RES>] value [max-value]
Description File Size, displayed on the File Information Screen, sets the size in bytes for the transfer file. As with block size and block delays, RRTT may be directed to create file sizes a number of different ways.

DEF (short for DEFAULT) may be used to return the settings back to their default values. No other values are accepted for this string.

INC (short for INCREMENT) directs RRTT to step the file size by a fixed increment for each new test pass. The first parameter (separated from INC by a space) is interpreted as the step size. If a second value is entered, it is interpreted as the maximum size to use before repeating the sequence. The first step on an INCREMENT sequence is the command's minimum acceptable value. If no maximum is supplied then the maximum acceptable value is used.

RAN (short for RANDOM) directs RRTT to use random numbers between the minimum and maximum supplied on the command line. The first value after the RAN string (separated by a space) is the minimum random number. The second value is the maximum value. If the maximum or both values are used.

RES (short for RESET) functions the same as the DEFAULT string and returns the command's parameters back to their original settings.

A fixed size may be entered, in which case RRTT will alter other test parameters while leaving the file size constant.

Example >FS RAN

Sets the dummy transfer file size to some random number between the default minimum and maximum for each new pass of an RRTT test.

Limits DEFAULT: RANDOM 1 0X20000

MIN: 1 Byte

MAX: 131072 Bytes

HELP - display on-line help screens

Syntax HElp
Description Pops up a detailed help list. On the left is a list of all the RRTT commands available. On the right is a detailed description of the command currently highlighted on the left. The up and down arrow keys will navigate up and down the left-hand list commands. Typing the <ENTER> or <RETURN> key will exit the help screen with the current command selection already typed into the command line. Typing the <ESC> key will exit the help screen without saving the currently selected command. The menu displayed prior to executing HELP will be restored.

The first few screens of the HELP command explain how to interpret the syntax fields of the command descriptions. The JUMP command is not included in the help screens and is only applicable when running script files.

Typing ? is identified to typing the HELP command.

Example >HELP

Displays the on-line help screen atop the Information Screen.

Limits DEFAULT: N/A

MIN: N/A

MAX: N/A

JUMP - jump to a script file label

Syntax JUMP [[!]<condition_code>] [<label>]
Description JUMP will alter the otherwise sequential flow of a script file by either skipping over the next script entry or moving the script file's pointer to a label. A condition code may be used to dictate whether the jump should be taken. A '1' flag is available for inverting the meaning of the condition code. If used, no white space may exist between the "!" and the condition code. If the condition code is not present, the jump is always taken. A label in a script is a command line starting with a colon followed immediately by a label. White space is not allowed in labels. If the label is not present on the command line, the JUMP merely skips the next non-blank script line. This command is valid only when RRTT is reading command input from a script file.

The presently supported condition code for the JUMP command is DRIVE_ERROR. It must be typed in all upper case letters. If any of the active destinations sustained an error during the last RRTT execution then the DRIVE_ERROR condition code will cause the script file to make the jump. If the !DRIVE_ERROR condition code is used, the jump is taken if no errors occurred. If identical labels exist in a script file, a JUMP command will start execution at the first occurrence of these identical labels. Labels are not case sensitive.

Examples JUMP

Skips the execution of the next command.

JUMP !DRIVE_ERROR

Skips the execution of the next command if no errors occurred during the last RUN.

JUMP DRIVE_ERROR ExitScript

Continues execution of the script file from after the label :ExitScript if an error occurred during the last RUN.

:ExitScript

Label in a script file. Ignored during execution and searched for by the JUMP command.

Limits DEFAULT: N/A

MIN: N/A

MAX: N/A

LCOMMENT - write user comment into log file

Syntax LComment text_string
Description Log Comment writes a string into the active log file. The string may be up to 45 characters long. If no log file is active, no action is taken. A comment may be useful for deciphering a test report. Note that when the log file made has been set to VERBOSE the actual command LCOMMENT text_string will also be entered into the log file preceded by the text_string. When the log mode is TERSE or SILENT only the text_string will be entered.
Example >LC start of test number 5

Writes "start of test number 5" into the active log file.

Limits DEFAULT: N/A

MIN: N/A

MAX: N/A

LMODE - sets the log mode for test reporting

Syntax LMode <DEF,OFF,ON,RES,SIL,TER,VER,file_name>
Description The Log Mode command, displayed on the Report Information Screen, performs tasks to control the log file. Depending on the parameters given, LMODE will turn on/off the log file, rename and turn on a new log file, change the reporting mode of a log file, or erase an old log file.

DEF (short for DEFAULT) will return the log mode back to its original state, turn off an active log, and reset the log name to the default name.

The OFF parameter turns off an active log.

The ON parameter turns on a log file with the name displayed on the Report Information Screen. All new logging is appended to the log file.

The RES (short for RESET) will erase the contents of the existing log file and start a fresh log using the name displayed on the Report Information Screen.

SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) altar the amount of information collected during an RRTT session. SILENT only records test error information collected during an RRTT session. SILENT only records test error information and test completion summaries into the log file. TERSE records all the SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the logger to record all test activity along with all command line activity. Only one switch may be used at a time, and each will turn on the log file if there isn't one already active.

When a log file is active, a red letter L is displayed in the upper right-hand corner of the screen. If there is no L then log information is not being captured.

Example >LMODE VERBOSE
>LMODE RESET

Sets the logger to record all activity and start with a fresh log file.

Limits DEFAULT: TERSE

MIN: N/A

MAX: N/A

LNAME - log name

Syntax LName <DEF,RES, file_name>
Description Log Name, displayed on the Report Information Screen, is a Static User Option used to change the log file name. The name may be any valid file name and extension.

DEF and RES (short for DEFAULT and RESET respectively) will return the log file name to the default name.

The command LMODE file_name can also be used to change the log file name making the change takes place immediately. LNAME file_name does not turn the log on or off, it only changes the log on or off, it only changes the log file name. The name change, using LNAME, takes effect the next time a log file is opened.

Example >LN USER.LOG

Redefines the log file name to USER.LOG.

Limits DEFAULT: RRTT.LOG

MIN: N/A

MAX: N/A

LOAD - load a configuration file

Syntax LOAD [file_name]
Description LOAD scans a configuration or script file for RRTT User Options. This allows for test configurations stored with the SAVE command or created with a test editor to be automatically loaded into RRTT. If the file_name is a script file, then all non-static commands are ignored. If the file_name is left off, the default file name is used. LOAD does not abbreviate.
Example >LOAD TEST8.CFG

Executes the configuration file TEST8.CFG

Limits DEFAULT: RRTT.CFG

MIN: N/A

MAX: N/A

MMODE - set the monitor screen mode for reporting

Syntax MMode <DEF,RES,SIL,TER,VER>
Description The Monitor Mode command, displayed on the Report Information Screen, controls the amount of information reported to the Monitor Screen during an RRTT test.

DEF and RES (short for DEFAULT and RESET respectively) will return the monitor mode back to its original state.

SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) alter the amount of information displayed on the Monitor Screen during an RRTT session. SILENT only reports test error information. TERSE records all that SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the Monitor to record all test activity. The command line activity is always reported to the Monitor Screen. Only one switch may be used at a time.

Example >MMODE SILENT

Do not monitor the RRTT test with the Monitor Screen.

Limits DEFAULT: VERBOSE

MIN: N/A

MAX: N/A

PAUSECOPY - pause after file copy

Syntax PAusecopy<ON,OFF>
Description Pause on Copy, displayed on the Transfer Information Screen, causes RRTT to pause after each file copy and prior to performing a file compare. The user may, if they wish, manually introduce file errors (outside the application). Doing so will verify proper error reporting. Typing any character will resume the test. This is a 'reality check' and is not intended for network testing.
Example >PA ON

Wait for a keyboard hit before comparing files.

Limits DEFAULT: OFF

MIN: N/A

MAX: N/A

PMODE - set the printer mode for test reporting

Syntax PMode <DEF,OFF,ON,RES,SIL,TER,VER>
Description The Printer Mode command, displayed on the Report Information Screen, controls the amount of information captured on the printer.

DEF (short for DEFAULT) will return the printer mode back to its original state.

The OFF parameter turns off the active printer.

The ON parameter turns on the printer with the mode displayed on the Report Information Screen.

The RES (short for RESET) will open then close the printer port. This is similar to turning the printer On the OFF.

SIL, TER, VER (short for SILENT, TERSE, and VERBOSE respectively) alter the amount of information collected during an RRTT session. SILENT records only test error information and test completion summaries to the printer. TERSE records all that SILENT does plus RRTT drive report information for each test iteration. The VERBOSE switch causes the printer to record all test activity. Only one switch may be used at a time and each will turn on the printer if it isn't already active.

When the printer log is active, a red letter P is displayed in the upper right-hand corner of the screen. If there is no P then log information is not being captured on the printer.

Example >PM SIL

Activate the printer to record error information.

Limits DEFAULT: SILENT

MIN: N/A

MAX: N/A

QUIT - exit the RRTT utility

Syntax QUit
Description QUIT exits the RRTT utility and is identical to EXIT.
Example >QUIT

Exit RRTT

Limits DEFAULT: N/A

MIN: N/A

MAX: N/A

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