MAP Reference Manual Version 3.0 Quantitative System Performance, Inc. PREFACE MAP Reference Manual This document describes the modeling facilities available using Version 3.0 of the Modeling and Analysis Package (MAP). The manual is organized into the following chapters: 1. GENERAL MODELING CONCEPTS 2. MAP OVERVIEW 3. MAP EXEC FILES 4. GRAPHS 5. MODELING I/O SUBSYSTEMS 6. MODELING TERMINAL NETWORKS 7. FUNCTION OF SETSYSTEM 8. LIST OF COMMANDS More information on MAP and related software can be found in MAP User's Guide. ---------------------------------------------------------------------- CHAPTER 1 GENERAL MODELING CONCEPTS MAP models of computer systems are constructed of three basic components: customer classes, service centers, and domains. Customer classes represent identifiable components of the computer system workload. Service centers are typically used to represent hardware components where service or queuing delays take place. Domains are used to model memory limitations. MAP provides three types of classes: BATCH, TERMINAL, and TRANSACTION. Batch classes are used to represent batch workloads. The workload intensities of batch classes are given as the average numbers of active jobs. Terminal classes are used to model online users at terminals. The workload intensities are given as the average numbers of online user and the average think times between request submissions. Transaction classes are used to model transaction processing systems. The workload intensities are given as the rates at which new transaction are submitted to the system. MAP provides three kinds of service centers, distinguished by their scheduling disciplines. The default (NORMAL) center type is appropriate for modeling First Come, First Served (FCFS) and round-robin scheduling. DELAY service centers are appropriate for situations in which jobs are delayed entirely due to their service requirements. PRIORITY service centers are used to model priority scheduled hardware devices. Memory limitations are represented in MAP using domains. Each domain has an associated capacity, which is the maximum number of jobs that can be loaded into it at one time. A job must be loaded to obtain service. Domains can be scheduled either FCFS or priority. If there is no limit on the number of jobs of a particular class that can be loaded, that class is not a member of any domain. MAP models composed of the above components are often sufficient to answer the modeling questions posed. However, more sophisticated users might wish to use MAP's Input/Output (I/O) subsystem and memory modeling capabilities. MAP allows the user to describe the I/O subsystem configuration in terms of the number of physical channels, the number of controllers, the number of strings, and the access paths by which Central Processing Units (CPUs) communicate with disks. The MAP commands CHANNEL, CONTROLLER, and STRING establish the respective components of the model, and the commands ONSTRING, ONCONTROLLER, and ONCHANNEL establish the I/O path interconnections and place disks (service centers on the paths. The use of the MODEL and TDEFINE commands allows the user to specify DASD, string, and controller models. Cache controllers are reflected through these general purpose commands and through a small set of other commands specifically for that purpose. MAP uses this information to evaluate the delays incurred in accessing disk devices and, subsequent to the user issuing a SETSYSTEM ON command, alters the loadings of the disk service centers to reflect this contention. Additional sophistication also is available for modeling terminal networks. The LINK command defines a communications line whose speed is given by the LINKSPEED command. The NODE command defines a terminal attachment point which is associated with the current link using the ONLINK command. The ATTACHES command specifies the number of terminals of the current class that the current node attaches to the system. Communication activity is specified by the INMESSAGESIZE, OUTMESSAGESIZE, and MESSAGECOUNT commands, which apply to the current class. The NODEUSE and LINKUSE commands produce performance reports. The advanced memory modeling capabilities are implemented through the use of the MEMSIZE, PAGECOUNT, PAGELOAD, SWAPCOUNT, and SWAPLOAD commands. These allow the user to specify the amount of main memory on the system and to evaluate the use of additional memory to increase multiprogramming levels and to reduce paging and swapping rates. ------------------------------------------------------------------------ CHAPTER 2 MAP OVERVIEW 2.1 INPUT FORMAT MAP commands can be entered in free format fashion in either upper or lower case. Part of a command, a single command, or multiple commands can be entered on a single line. Comments can be entered anywhere that a blank could be reasonably typed, and can be extended over one or more lines. (Comments help annotate MAP runs and MAP EXECs.) Comments are delimited by double braces, as in {{comment line}}, or by single braces, as in {comment line}. The former type of comment is copied to the currently opened output file (including the terminal), while the latter is not. 2.2 FULL SCREEN INTERFACE A full screen interface has been provided. The direct benefits include a greater ease of use and an extensive online help facility. Pleasant side effects include the ability to issue normal TSO or CMS commands from within MAP, making it possible to list MAPEXEC or MAPDAT files and to examine their contents. The full screen interface is documented separately. Refer to the MAP/OBTAIN Full Screen Interface User's Guide for additional information. The user should view the full screen interface as syntactic sugar for the line-oriented MAP commands. Thus, the MAP Reference Manual remains the ultimate authority concerning MAP's 2.3 ABBREVIATIONS Commands and object names can be abbreviated to the shortest unique abbreviation for their context. Thus, CEN CP is equivalent to CENTER CPU, if there is no center (other than CPU) whose name begins with CP. If the name of one center, for instance, is a prefix of the name of some other center, and the shorter name is typed in full, it is assumed that the user means the center whose name matches exactly. Thus, CEN CP sets the center to CP rather than to CPU if both centers exist. It is possible to specify that a name should not be taken as an abbreviation by appending a period (`.') to the name. This can be useful when creating a new object with a name that is an abbreviation of an existing object of that type. For instance, if the CENTER named CPU already exists, the command CENTER CP will set the current center to CPU. In contrast, the command CENTER CP. will create a new center with name CP. Some names cannot be abbreviated. File names (for instance, as used by SAVE, READ, and EXECs) must be typed in full. Similarly, the keywords EACH, EVERY, and CANCEL cannot be abbreviated. 2.4 CONTEXT Most MAP commands serve either to define or alter the MAP model, or to request output performance measures of the current model. For each component type in a MAP model (class, center, domain, string, controller, channel, node, and link) there is at all times a ``current context'' to which commands refer implicitly. The current context for each component type is given by the command with the same name as the component type. For instance, classes, centers, and domains are made current by issuing an appropriate CLASS, CENTER, or DOMAIN command. The purpose of context is to reduce the amount of typing required for command entry. By maintaining an implicit context, the user can enter several commands for the current context without having to specify, for instance, the class, center, or domain affected with each command. For example, in a model with class PRODUCTION current, the commands AVGPL 10 INDOMAIN PROD would set the multiprogramming level of PRODUCTION to 10 and place it in domain PROD. Notice that neither command required the class name (PRODUCTION) as an explicit parameter. It is possible to make the current class, center, or domain either EACH or EVERY. Context EACH causes MAP to prompt for parameters for each entity of the appropriate type. Context EVERY causes the (single) parameter given to be applied to every entity of the appropriate type. For example, suppose that a model contains three classes, named TSO, TSO, and BATCH. If the current class context is EACH, the command ARRIVAL_RATE .7 sets the arrival rate of class TSO to .7, and causes MAP to prompt for the arrival rates of classes TSO and BATCH. If the current class context is EVERY, the same command sets the arrival rate of all three classes to .7 without the need for further input. MAP also allows the user to make arbitrary groups of components the current context. For instance, suppose a model contains a total of ten classes with names TSO, TSO, ..., TSO, BATCH, BATCH, ..., BATCH. The commands CLASS TSO CLASS +TSO CLASS +BATCH set the current class context to {TSO, TSO, BATCH}. The command PLEVEL 4 will now set the priority level of all three classes (and no others) to 4. (Thus, a group defined in this way acts like EVERY with respect to how input is treated.) The first command makes class TSO the current class context. The `+' prefix in the parameters of the second and third commands cause classes TSO and BATCH to be added to the current context, rather than to replace it. Prefix `-' removes objects from the current context. For example, after executing the three commands above the command CLASS -TSO would leave the class context as {TSO, BATCH}. There is a more convenient way to define groups when names share a common prefix. For instance, classes TSO through TSO could be made the current context by the single command CLASS TSO* The appended `*' causes MAP to match all classes whose names begin with `TSO'. The `*' suffix can be combined with prefix operators. For instance, CLASS +BATCH* would cause the context to be all ten classes (and thus semantically equivalent to EVERY). These two commands together have the same effect as CLASS * It is possible to give a name to the current context for a component type when the context forms a group. For instance, CENTER DISK* GDEFINE DASD CENTER makes the current context the group of centers whose names begin with `DISK', e.g., {DISK1, DISK2, DISK3}. The GDEFINE command defines a group whose name is DASD and whose value is given by the current center context. The name of this group, i.e., `DASD', can now be used as a shorthand in subsequent CENTER commands to make the set of centers {DISK1, DISK2, DISK3} the current context. That is, CENTER DASD is valid and means CENTER DISK1 CENTER +DISK2 CENTER +DISK3 Notice that the group represents the specific centers in the current context at the time of the GDEFINE command, rather than the pattern (`DASD*') used to set up that context. Thus, if a new center, DISK4, were created between the GDEFINE command and subsequent use of the name DASD in a CENTER command, DISK4 would not be made part of the current context. Group names may be abbreviated. However, any parameter to the CENTER command (for instance) will be matched against valid center names before any attempt is made to match against center group names. Thus if there is a center named DASDARM the command above will refer to this one center alone rather than the group. (In this case the desired effect can be obtained using `CENTER DASD.'.) Immediately after the execution of a CANCEL command, there is no context for the entity of the type canceled. (For instance, CANCEL CENTER removes the current center from the model and results in there being no current center context.) Commands that require context will cause errors if no context exists when the commands are executed. MAP uses the keyword NONE on output to indicate that no context exists. NONE has no special meaning on input. 2.5 CREATING MODEL COMPONENTS Classes, centers, and domains are created by the CLASS, CENTER, and DOMAIN commands, respectively. Whenever one of these commands refers to an object not currently defined in the MAP model, the object is created with the given name. Thus, CLASS PGROUP1 creates a new class with name PGROUP1 if no class with that name (as a prefix) currently exists. (To define a new center, say, whose name is a prefix of an existing center, append a period (.) to the new name. This indicates that the name has been typed in full, and should not be considered as a possible prefix of some other name.) 2.6 SPECIFYING PARAMETERS Parameters to MAP commands consist primarily of numeric values (real and integer values) and character string names. These names can be any character string of 12 characters or less. (Names longer than 12 characters are truncated.) There are two keywords that cannot be used as names: EACH and EVERY. These have special meanings, as noted in paragraph 2.3. When a command has been issued that causes MAP to prompt (usually because the context of the relevant entity is EACH), typing a null line in response to the prompt causes MAP to proceed to values for the next class (if any) without affecting intervening values. Numeric valued parameters can be specified in any of three ways: a numeric literal (e.g., 2.7), an expression (e.g., (3*2.184) / (17.7+3.8*2.2)), or an operator suffixed value (e.g., 2*). Numeric literals are specified in fixed format, and cannot be given in scientific notation. For example, 127.5 is valid but 1.275E02 is not. Expressions can include parentheses and MAP EXEC variables (see Chapter 3 of this manual), but may not contain embedded blanks. They are evaluated using standard operator precedence rules: parenthetical subexpressions are evaluated first, unary operators (+ and -) have the next highest precedence, multiplication (*) and division (/) come next, and finally addition (+) and subtraction (-). Equal precedence operators are evaluated left to right. For example, the value of 5*6-6/3 is 28, while the value of 5*(6-6)/3 is 0. Unary `@@' is absolute value, that is, that magnitude of the operand is preserved but the sign is made positive. Unary `-' is negation, that is, the sign of the operand is reversed. The result of a unary `-' can therefore be either positive or negative. A unary operator precedes the operand it operates on. For example, `@@(&F1-&F2)/&F2*100' gives the percentage difference between F1 and F2 and forces the result to be positive. A result could be forced to be negative (something that is not normally needed) by negating the absolute value of the result, e.g., `-@@(&F1-&F2)/&F2*100' will be a negative percentage difference. Operator suffixed values serve as modifiers to the current value, rather than as replacements. Thus, ARRIVAL 2* doubles the arrival rate of the current class, rather than setting it to 2 (as ARRIVAL 2 would). The value suffixed can be either a literal value (e.g., 2*) or an expression (e.g., 1+1*). Some MAP commands take integers as parameters. In these cases, any real value given is truncated to an integer. For example, PLEVEL 2+3/4 results in priority level 2 being assigned to the current class. 2.7 VALIDATION VERSUS MODIFICATION ANALYSIS There are two phases of use of a MAP model, validation and modification analysis. In the former the analyst tunes the model so that its performance measures (e.g., utilizations and response times) agree with those measured for the system being modeled. In the latter, a validated model is modified to reflect proposed changes to the computer system, and the model performance measures are used as estimates for system performance. It is essential that MAP be able to distinguish between these two types of usage. The reason is that MAP must know whether or not changes to the model should result in side-effects. For instance, when a DASD device is placed on a string through the ONSTRING command, should the RPS miss times of other devices on the string be increased due to increased contention or not? The answer depends on whether the analyst is in the process of describing the current configuration, in which case the parameters of other devices on the string should not be altered; or whether he is evaluating the introduction of a new device, in which case those parameters must be changed. The distinction between validation and modification analysis is made through the SETSYSTEM command. SETSYSTEM OFF indicates the validation phase. This is the default state. SETSYSTEM ON indicates the beginning of the modification analysis phase. The current value of SETSYSTEM can be determined by issuing a SETSYSTEM command with no parameter. It is the responsibility of the analyst to issue a SETSYSTEM ON command once the model is validated. Failure to do so will cause MAP to incorrectly suppress the side-effects of changes to the model, and will adversely affect the accuracy of the model for performance projection. 2.8 TIME UNITS Unless the user is employing the advanced I/O modeling facilities, there are no enforced time units assumed by MAP. The user must therefore decide upon an appropriate unit and input all values in terms of that unit. Failure to do so will result in unpredictable model behavior. Using seconds as the basic time unit is usually appropriate. In this case, THINK 15 means 15 seconds of think time on average, for example, and LOADING .400 means the loading is 0.4 seconds (400 ms). In the examples in this manual we have assumed seconds as the basic time unit. If a time unit other than seconds is chosen, attention should be paid to the format of the output reports. Unusual time unit selections can result in very large or very low performance measures. Very large values will be too large to fit in the output report, and are replaced by strings of asterisks (for example, `******'). Very small values might have no significant digits displayed. When using the advanced I/O modeling facilities, the IOTIME parameter for each DASD should be given in units of seconds. This is required because the standard MODEL information used by MAP has been provided in terms of seconds. 2.9 MODEL LIMITS The limits on the number of centers, channels, classes, controllers, domains, and strings imposed by an implementation of MAP can be determined by examining the values of the MAP EXEC variables MAXCENTERS, MAXCHANNELS, MAXCLASSES, MAXCONTROLLERS, MAXDOMAINS, and MAXSTRINGS, respectively. A MAP EXEC file, LIMITS, is often available to facilitate this. The EXEC is invoked simply by typing its name. (See chapter 3 for a discussion of MAP EXEC files.) 2.10 SATURATION Model saturation occurs when a greater workload is presented to the model than can be processed. Saturation can occur because of memory or service center limitations. In either case, the utilization of the saturated resource is 100%. When a model saturates, all classes requiring service from the saturated resource have very large response times. These are displayed as a string of asterisks ('******') in output reports. Probably the most frequently encountered saturation effect is exhaustion of the CPU. Since the CPU is often modeled as a PRIORITY scheduled device, the first effect of saturation is on the lowest priority classes. These suffer very large response times before the higher priority classes do. When a resource saturates, the throughput rates of TRANSACTION type classes might not match their arrival rates. MAP will correctly slow down the throughput rates of these classes if a single resource has saturated. When two or more resources are saturated, results are unpredicatable. Models with more than one saturated center are quite uncommon, and the analyst should consider carefully the situation being modeled. 2.11 OUTPUT REPORTS MAP allows the user to control some aspects of output report format, and to direct output to files for later use. The latter function is provided by the OPEN and CLOSE commands, which are explained in chapter 7 of this manual. Basically, OPEN establishes a file to which subsequent output reports will be directed. CLOSE terminates that file, so that reports are again directed to the terminal. Either the absolute performance measures or the relative changes from baseline values may be shown in output reports. For instance the PERF report can display the percent deviation from the measured response times and throughputs (useful in validating a baseline model), or from the response times and throughputs of a baseline model (useful in performing a modification analysis). The DISPLAY command takes RELATIVE or ABSOLUTE as its argument, selecting the display mode for output reports. Baseline values for use with the RELATIVE mode are established in one of two ways. The command BASELINE takes two parameters, a performance measure and a value, and associates this with the current class. For example, if the current class is TSO1 then the command BASELINE RESPONSE 0.52 establishes 0.52 as the baseline response time for class TSO1. BASELINE is intended to be generated by OBTAIN from RMF data. The command SETBASELINE establishes baseline values for all performance measures from the current model. SETBASELINE is intended to be used by the analyst in modification analysis. In models with a large number of classes or centers, the output reports can be very long, and can contain information on a large number of centers not currently of interest. Uninteresting centers and classes can be filtered from the reports using the OUTPUT command (see chapter 7). Basically, this command allows the user to specify for each class (center) whether or not that class (center) is to be included in output reports. The setting for an individual class (center) can be changed as often as desired during a MAP session. (There are also settings for the TERMINALS and MEMORY.) A more powerful report tailoring facility is provided through the EXEC variables CENTERORDER and CLASSORDER. These are arrays that indicate the order in which centers and classes are to appear in reports. The elements of each array represent class or center indices. The indices of classes and centers are the order in which they were created. For instance, if class A is created before class B which is created before class C (starting with an empty model), the index of class A is 1, the index of B is 2, and the index of C is 3. Class and center indices both run from 1 to the number of classes and centers currently defined. The index of the current class or center can be determined using the EXEC variables ICLASS and ICENTER, respectively. Suppose the user wants output reports to list the three classes above in the order C A B. To do so, the first element of CLASSORDER should be set to 3, the second element to 1, the third to 2, and the fourth to 0. (The end of the list in the array is indicated by a 0.) The array elements are set using the SET command. The element affected by a SET CLASSORDER (SET CENTERORDER) command is the one given by the current value of the EXEC variable CLORDNDEX (CEORDNDEX). For instance, SET CLORDNDEX 2 CLASS A SET CLASSORDER &ICLASS sets the second element of CLASSORDER to the index of class A. The values 0, -1, and -2 have special meanings in the order arrays. A value of -2 indicates that a blank line should be inserted at that point for CENTERORDER, and a blank column for CLASSORDER. A value of -1 indicates that a new header line should be printed for both CENTERORDER and CLASSORDER. A value of 0 terminates the list contained in the array. (A number smaller than -2 or larger than the number of classes (centers) also serves as a list terminator, but is not standard usage.) It is possible for any class or center to appear more than once, or not at all, in the order lists. There is no common situation in which the former is desirable. If a class or center does not appear in the order arrays, it will not appear in output reports. However, suppressing class or center output is better performed using the OUTPUT command, as mentioned above. ----------------------------------------------------------------------- CHAPTER 3 MAP EXEC FILES 3.1 INTRODUCTION MAP EXEC files provide a facility whereby users can create new commands from MAP's built-in commands. Basically, MAP EXEC files are files of MAP commands. They are created in either of two ways: using standard editors external to MAP or using the MAP command MAKEXEC. (See appendices D and E in this manual for a description of the files used to contain MAP EXECs.) EXECS are invoked in MAP simply by using their names as commands. When MAP determines that a command issued by a user is not a built-in command, it looks for an EXEC file with filename equal to the command name. If one is found, MAP reads it and executes the commands it contains. (Note that this means that the user can invoke EXEC files with names that are prefixes of MAP built- in commands only by suffixing the name with a period.) Abbreviations for EXEC names are not allowed. The following is a simple example of an EXEC file: Filename: LLOAD Contents: CLASS EVERY CENTER EVERY LIST LOAD This file defines a new command, LLOAD. When the user types LLOAD as a command, MAP reads the three commands that the file with that name contains and executes them just as if they had been typed from the terminal. Thus, LLOAD provides a shortcut for performing what might be a frequently required function. During the execution of EXEC files, all MAP prompts are suppressed. Also, commands that might normally require confirmation before completion of their functions (e.g., EXIT, SAVE, CANCEL) do not ask for confirmation. Processing of an EXEC file is terminated when end of file is reached, when a RETURN instruction is executed, or when an error occurs (unless an ONERROR command has been executed). 3.2 PROFILE EXEC As a convenience in using MAP, the EXEC file named PROFILE is read automatically at the beginning of every MAP session (if such a file exists). This provides a means for initializing MAP to a standard state automatically. A simple PROFILE might be BRIEF 2 READ CURMODEL This PROFILE sets the prompting level to 2 and makes CURMODEL the current model. 3.3 INITDEVS EXEC When MAP is entered, it looks for an EXEC named INITDEVS. If the file exists, it is executed immediately (before execution of any PROFILE MAP EXEC). The purpose of INITDEVS is to establish the initial set of model definitions that comprise the default model types known to MAP. Thus, INITDEVS consists of a number of TDEFINE commands giving model names and associated parameters. The first DASD type TDEFINE issued describes the default DASD device used in cases where a DASD type is required and no type has been explicitly declared for a particular center. This DASD model must have a SPEED parameter listed in the TDEFINE command that creates it. INITDEVS also provides a way for users to alter the standard model definitions, remove standard definitions, and add new models to the standard set. The last thing done by INITDEVS is to attempt to invoke another EXEC, USERDEVS. By putting the customizations that the user desires in USERDEVS (as a sequence of TDEFINE commands), the standard set of models will be altered as desired each time MAP is run, thus providing a tailored set of pre-defined models. The use of the separate EXEC USERDEVS simplifies the process of installing new versions of MAP as compared with editing the INTIDEVS file locally, an alternative way to customize the set of known models. In addition to providing the standard set of model definitions, the INITDEVS file also determines the default DASD device used by MAP when performing advanced I/O modeling (see the SETSYSTEM command). In any MAP run, the first TDEFINE command issued to create a model of DASD type is assumed to indicate the default DASD model to be used when a DASD model is required for a center, but the user has not provided one explicitly. Since the first DASD creating TDEFINE occurs in INITDEVS, that file determines the default. If no INITDEVS EXEC is provided, no models will be known by MAP other than those explicitly established by TDEFINE commands issued by the user or provided in model definition files that have been saved. It is not necessary to have a USERDEVS file; no error will result if the EXEC cannot be found. 3.4 NESTING OF EXECS MAP allows an EXEC file to invoke other EXEC files. This is done by keeping a stack of EXECs. Each time a new EXEC file is requested, it is pushed onto the top of the stack and input is taken from that file. When that file terminates, the file that invoked it resumes processing where it left off. Because this stack has a fixed size (currently four), it is possible that an attempt to invoke an EXEC file can fail because too many files are already invoked (even though all but the most currently invoked files are inactive). There is no code in MAP to prohibit recursive execution of EXEC files (that is, an EXEC invoking itself either directly or indirectly). However, some operating systems do not allow this function. MAP attempts to open the EXEC file each time it is invoked. Multiple opens of a single file might not be allowed on a user's system. 3.5 PASSING PARAMETERS TO EXECS MAP provides two techniques for passing parameters to EXEC files. These allow the construction of parameterized commands. One parameter passing technique is very general purpose, allowing the EXEC to read from the invoking input stream (using EXEC variable TOKEN), issue prompts (using PROMPT), and detect end of line (using EOLN). These techniques are explained in the MAP User's Guide. The other parameter passing technique is simpler, and thus often easier to use. It is based on a set of special EXEC variables that represent parameters that appear in the statement invoking the EXEC. The parameters are named P1, P2, ..., P9. The type of the parameters is character string (i.e., they contain character string values). The value of P1 is the first argument following the command name, the value of P2 the second argument, etc. For instance, VARY C2 2 10 3 invokes EXEC file VARY with parameter P1='C2', P2='2', P3='10', and P4='3'. The initialization of each parameter value is performed the first time either it or a higher numbered parameter is used in the invoked EXEC. Thus, if no reference is made to parameter P4 (or higher), the in the input stream will not be read by VARY. Usually, parameters are used in EXEC files only in conjunction with the & operator. The & operator, used as a prefix to a parameter, causes the value of the named parameter to be substituted for the occurrence of the name of the parameter. For instance, ONLINE &P2 is read by MAP as ONLINE 2 if contained in the VARY EXEC and invoked by the VARY command above. It is important to keep clear the distinction between naming the parameter (e.g., P1) and obtaining the value of the parameter (e.g., &P1). In general, the only place it makes sense to name the parameter is in the SET command (discussed later). It is occasionally necessary to use the character & (as contrasted with the operator &) in a string, for instance, to set the variable P1 to '&WI'. To do so, type && to indicate that a single character ampersand is required, and that the ampersand operator is not desired. Thus, the appropriate command for this operation is SET P1 &&WI This example motivates another feature of the & operator. If the character string expansion of an EXEC variable to which the & operator is applied contains an ampersand operator itself, the expansion is rescanned and the & operators evaluated. This process continues until an expansion with no & operators is generated or until a maximum number of scans has been performed. For example, consider the following command executed immediately after the SET command above: MSGLN &P1 If the workload intensity of the current class is 1.3, this is equivalent to the command MSGLN 1.3 The expansion of &P1 in the original command yields &WI. Since that string contains an & operator, it is reevaluated, yielding 1.3. Since that string does not contain an & operator, evaluation ends and the final string (1.3) is substituted in place of the original &P1. 3.6 OTHER EXEC VARIABLES: LOCAL AND GLOBAL In addition to the parameter variables (which are of type character string), there are also integer and floating point type variables available. These are named I1, I2, ..., I9 and F1, F2, ..., F9, respectively. Unlike the parameter variables, these variables are not initialized by MAP unless specifically requested by the user (using the SET command) While variables F1 through F9 and I1 through I9 contain numeric data, using the & operator allows the user to obtain their character string representations for use in command lines. Thus, ONLINE &I2 is equivalent to typing ONLINE 8 if the current value of I2 is 8. Note that typing ONLINE I2 will cause an error, since MAP will attempt to read the character string I2 as a floating point number. Each EXEC file invocation has its own set of variables P1 through P9, I1 through I9, and F1 through F9. The SET command can be used to alter the values of these variables. For instance, SET F2 10.3 sets variable F2 (of this EXEC) to 10.3. Subsequent occurrences of &F2 would be read as the character string 10.3. It is also possible to explicitly give values to the variables P1 through P9. For instance, SET P1 NEWCLASS sets variable P1 to NEWCLASS. MAP assumes that all variables P1 through Pn-1 have been given values when variable Pn is SET. Thus, if P8 is SET and then followed by the first reference to &P7, unexpected results will be obtained since MAP will assume that P7 has a valid value and will not read a parameter from the command line. In addition to these local variables, there are a number of global variables accessible to all invoked EXEC files. Most of these refer either to parameters of the current model or to the performance measures of that model. These variables allow the user to write EXEC commands that operate conditionally on the performance predicted for the current model, and its parameters. Additionally, the values of the model parameters can be changed by setting the appropriate variable. A list of the variable names and their meanings is given in appendix A. As with local variables, in almost all cases global variables should be used only in conjunction with the & operator. If the user attempts to obtain the value of a variable requiring context, e.g., by typing &WI, and the current context is NONE, EACH, or EVERY, an error message is printed and processing of the EXEC file is terminated. Likewise, if a variable is referenced whose value is the performance of the current model, and the model is not completely defined, so that it cannot be analyzed, an error message is printed and processing of that EXEC file is terminated. There are also global variables accessible to all invoked EXEC files that don't refer to parameters of the current model. These are named CINDEX1, CINDEX2, ..., CINDEX5, CTABLE1, CTABLE2, ..., CTABLE5, INDEPTH, OUTDEPTH, RCHARACTER, RFLOAT, and RINTEGER. CTABLE1, ..., CTABLE5 contain character strings. Each table has an associated index variable, CINDEX1, ..., CINDEX5. These tables can be used as global variables or as local variables. If the CTABLEs are to be used as local variables, the INDEPTH and OUTDEPTH variables allow the user to associate the CTABLE to be used with the current input level (INDEPTH) or output level (OUTDEPTH). RCHARACTER, RFLOAT, and RINTEGER provide the ability to create EXECs that are functions. The values returned by a function EXEC can be returned in these variables. RCHARACTER, RFLOAT, and RINTEGER are character string, real, and integer type variables, respectively. 3.7 CONTROL FLOW In addition to the SET command, there are a number of other commands intended primarily for use in writing EXEC files. The GOTO command causes a branch in flow of control within an EXEC file. For example, GOTO LOOP causes command interpretation to continue with the command following the label LOOP. Labels are created in an EXEC by prefixing the label name with a colon (:), e.g., :LOOP. Labels must begin in the first column of an input line. Here is an example of an EXEC file that prints performance measures of the current model with the population of one class varying from 1 to infinity. The invoking statement is BIGSOLVE TSO and the EXEC file is Filename: BIGSOLVE Contents: CLASS &P1 ONLINE 1 :LOOP PERF ONLINE 1+ GOTO LOOP This example points out the need for conditional control flow. (As written, it is an infinite loop.) This is provided in MAP by the IF command. The format of the IF command is: IF The operators are LT, GT, LE, GE, EQ, NE, CEQ, and CNE. The first six operators require numeric values for comparison, while the last two require character string values. Examples of each are: IF LT &WI 10 LOOP IF CNE &CCLASS TSO LOOP The user can create a command VARY to print performance measures of the current model with the population of one class varying over some range as follows: Filename: VARY Contents: CLASS &P1 ONLINE &P2 :LOOP PERF ONLINE 1+ IF LE &WI &P3 LOOP RETURN (The RETURN instruction in this example is superfluous, since reaching the end of the file would have the same effect.) To print performance measures for the model with class TSO population varying from 3 to 10, the user would type: VARY TSO 3 10 Sometimes the user would like to concatenate two character string values in the EXEC file. This is done by placing an apostrophe between the strings to be concatenated (with no intervening blanks). For instance, suppose that the current model contains 10 classes named IMS1, ..., IMS10, as well as a number of other classes, and the user wants to create a command BUMPUP to increase the IMS workload intensities by 1. BUMPUP would contain the following commands: Filename: BUMPUP Contents: SET I1 1 :LOOP CLASS IMS&I1 SET WI 1+ SET I1 1+ IF LE &I1 10 LOOP 3.8 HANDLING ERRORS The EXEC variable RCODE is a return code set by the execution of each command, and by any attempt to analyze the model (caused either because a command requesting a performance report has been issued, or because the value of an EXEC variable that reflects the performance of the model is required). An RCODE of 0 indicates normal, successful operation. Other values indicate that an error has occurred. Since RCODE is reset by each command executed, if an RCODE resulting from a particular command is to be examined by more than one other command, the RCODE must be saved in an integer variable, and that variable examined. The following example correctly branches to a number of destinations depending on the RCODE of the PERFORMANCE command: PERFORMANCE SET I1 &RCODE IF EQ &I1 0 NORMAL IF EQ &I1 52 UNUSEDTRING IF EQ &I1 89 NOHINK Appendix B contains a list of RCODE values and their meanings. If an error occurs during the processing of an EXEC file, there are two possible responses by MAP. The standard response is to print out the name of the EXEC file, the line number of the command that caused the error, the name of the command causing the error, and an appropriate error message. Execution of that EXEC file is then terminated, and processing continues with the invoking EXEC file (if any). Alternatively, the user can trap errors in the EXEC using the ONERROR command. This command takes a label as a parameter, and MAP causes a branch to the given label if any error occurs processing the EXEC. (See the description of ONERROR for further details.) In either case, the EXEC variable ERRLINE contains the line number of the command that caused the error. 3.9 ARRAY VARIABLES There is a set of array variables, TABLE1 through TABLE10, intended primarily for use by the PLOT command (for printing graphs). Each table has an associated index variable, INDEX1 for TABLE1, INDEX2 for TABLE2, etc. When a reference is made to a table variable, the element indexed by the value of the corresponding index variable is the one referred to. For instance, SET TABLE1 &RESPONSE stores the system response time of the current class in the fifth element of TABLE1 if the current value of INDEX1 is five. 3.10 EFFICIENCY MAP maintains two kinds of internal caches, a cache of open files and a cache of file contents. The open file cache is used to reduce the number of operating system file opens that occur when using nested MAP EXECs. (Note that this cache has nothing to do with either the file stack created by the MAP OPEN command or nested EXEC execution.) For example, assume that the user invokes EXEC ONE, which loops performing some operation on each service center. If the loop in ONE contains an invocation of another EXEC, say TWO, a large number of file system open operations may need to be performed on TWO. To avoid this file system overhead, MAP does not perform an operating system close operation at each termination of TWO. Instead, TWO is left open so that subsequent MAP invocations of it can take place quickly. If the current MAP model contained 100 centers, using the open file cache MAP would perform only one file system open on TWO instead of 100. There is one ``side effect'' of the open file cache. If a MAP EXEC file is edited after it has been invoked in an ongoing MAP session, changes made to the EXEC may not take effect until the MAP session is terminated. (Whether or not the changes take place immediately is somewhat operating system dependent.) The changes may be visible to MAP before then, though. Because the open file cache is of finite size (currently a maximum of ten files are kept open) MAP will occasionally have to flush old files from it to make room for new ones. (A ``least-recently- used'' replacement policy is used.) A file system close operation is performed when a file is flushed. If this occurs, any subsequent invocation of the EXEC results in a new file system open operation, and so the newly modified file is read. The second kind of MAP cache maintains input lines from EXEC files in MAP's currently OPENed file stack. The number of lines cached depends on the depth in the input file stack at which the EXEC is being processed. Those EXECs invoked first have the most lines cached. (The current cache sizes are 100 lines for the first EXEC executed, 30 lines for any EXEC it invokes directly, and 15 lines for each further nested invocation.) MAP is able to execute EXECs much more quickly out of the cache than out of the file. This is especially true of EXECs that perform a large amount of looping. Thus, it is advisable to keep the instructions comprising the major loop of an EXEC together, so that they will fit in the cache. The cache for each file is maintained using FIFO replacement. Each input line is cached as it is read, so that comments and blank lines take up cache space. In some cases, execution speed can be improved by placing multiple commands on a single line to reduce the number of lines required to code the EXEC. Because of the behavior of the cache, there is a slight computational advantage to placing block comments describing an EXEC at the end rather than the beginning of the EXEC. There is one additional efficiency consideration in writing MAP EXECs. There is some redundancy in the MAP instruction set, allowing for two or more ways to produce the same effect. In particular, the SET command can often be used in place of a more special purpose command, as in SET LOADING 2 in place of LOADING 2. This use of SET should be avoided; the special purpose commands can be executed slightly faster by MAP and allow for easier maintenance of the EXEC procedure. 3.11 DEBUGGING EXECS The TRACE and SHOWPANEL commands can be used to aid debugging EXECs. TRACE allows the user to request that MAP print a control flow trace during EXEC execution. SHOWPANEL provides a "breakpoint" capability from within an EXEC. SHOWPANEL suspends the EXEC and the terminal becomes the current input source. The user may then query intermediate model results or global variable values. The EXEC can then be resumed with a RETURN command. -------------------------------------------------------------------------- CHAPTER 4 GRAPHS 4.1 USING MAP WITH OTHER GRAPHICS PACKAGES MAP provides facilities for producing graphs of performance measures as functions of model parameters. There are two distinct ways in which this can be done. One is to create files of raw performance measures during a MAP run. These can be read after the MAP run by some post-processing routine (e.g., an SAS routine) to create graphical output. The other approach is to take advantage of MAP's built-in ability to draw graphs on the terminal. MAP supports the first of these approaches, creating data files for use by post-processing routines, via the OPEN, CLOSE, WRITE, and WRITELN commands. The OPEN command takes a filename as a parameter. It causes subsequent MAP output to be written in the file. The CLOSE command closes the currently opened file. A number of commands cause their output to be sent to the currently opened file (for instance, all the performance report generation commands do so), but the most appropriate commands for use in this situation are WRITE and WRITELN. These write the remaining items on the same input line to the file. WRITELN differs from WRITE in that the former causes a carriage return to be written at the end of the line. WRITE statements merely place their parameters in the output buffer. It is typical to write the values of performance measures of the current model to a file. This is done by writing EXEC variables (see chapter 3). A list of EXEC variables is given in appendix A. The following example writes the workload intensity, response time, and throughput of class TSO on one output line, followed by the utilization of center CPU by class TSO on another output line. Normally, values written on a single output line are separated by a single space. However, the EXEC variable COLUMN can be used to specify the column in which the output value is to begin. The following example inserts an additional two spaces between the first two output values. (This example is written using more WRITEs than necessary to highlight the distinction between WRITE and WRITELN.) CLASS TSO WRITE &WI SET COLUMN 2+ WRITE &RESPONSE WRITELN &THROUGHPUT CENTER CPU WRITELN &UTILIZATION More information on the use of WRITE and WRITELN can be found in Chapter 7 of this manual. The facilities outlined above provide a very general graphing facility. It should be possible to produce data files in whatever format is required by the graphing routines available at the user's installation. Thus, the variety of graphical facilities possible is quite large. A more restrictive but extremely convenient graphing facility is built into MAP. This provides for the plotting of functions of a single parameter (for instance, the plotting of CPU utilization against Information Management System (IMS) arrival rate). MAP supports this facility through the PLOT command and the use of EXEC files. The PLOT command provides low-level plotting facilities. EXEC files are used to provide a more convenient interface to the use of PLOT. They automate the evaluation of the function to be graphed, and the labeling of the graph drawn. Both PLOT and the use of EXECs for graphing are discussed briefly in this chapter. 4.2 THE PLOT COMMAND The PLOT command takes a single integer parameter, the number of an EXEC TABLE variable to be plotted. (TABLE variables are arrays of real numbers.) The table is assumed to contain (X,Y) coordinates of the points to be plotted. Each coordinate requires two entries in the table, the first the X (horizontal axis) value and the second the Y (vertical axis) value. The coordinates are assumed to be stored in successive TABLE elements. The INDEX EXEC variable for the TABLE to be plotted is assumed to indicate the location of the Y value of the last coordinate. Thus, the INDEX must have an even value. The coordinates in the table do not have to be sorted by either X or Y values. The PLOT command reads the values out of the table, and plots a graph of them on the terminal (or in the currently opened output file). MAP automatically chooses scales for the X and Y axes that are appropriate for the data to be plotted, and the axes are labeled with these scales. (An alternative to automatic selection of the Y axis scale is discussed later in this chapter.) As mentioned above, the PLOT command is a low-level facility that allows for a great deal of generality in producing graphs. Convenience in using PLOT is provided by appropriate use of EXEC files. These have two major functions: to automate the process of putting the data to be plotted in a TABLE variable, and to label the graph produced as to what the plotted function represents. Such a MAP EXEC is discussed in the next subparagraph. 4.3 THE GRAPH EXEC As an example, we present an EXEC, called GRAPH, that varies a single model parameter from a specified initial value to a specified final valu by a specified increment, and plots a single model performance measure as a function of this varying parameter. The parameters to GRAPH are: P1: The EXEC variable name of the quantity to be plotted (the Y coordinate values). P2: The EXEC variable name of the model parameter to be varied (the X coordinate values). P3: The initial value for parameter 2. P4: The maximum value for parameter 2. P5: The amount by which parameter 2 should be incremented in producing successive points for the graph. A typical way that GRAPH might be used is: GRAPH RESPONSE WI 1.0 2.5 .25 This graphs the response time of the current class for models in which the workload intensity of that class is successively 1.0, 1.25, 1.50, 1.75, 2.0, 2.25, and 2.50. A simple version of GRAPH is given below. The version of GRAPH on the user's system is probably augmented with error checking code. Filename: GRAPH Contents: SET P5 &P5 {This causes all parameters to be evaluated} SET P6 &&&P2 SET P7 &&&P1 SET INDEX1 0 SET &P2 &P3 :LOOP IF GT &P6 &P4 OUT SET INDEX1 1+ SET TABLE1 &P6 SET INDEX1 1+ SET TABLE1 &P7 {The evaluation of &P7 causes the model to be analyzed} SET I1 &RCODE {Check the return code} IF NE &I1 0 RET {If more than one graph is to be plotted, new commands should be inserted here to use TABLE2, TABLE3, etc.} SET &P2 &P5+ GOTO LOOP :OUT SET &P1 &P5- {Set model parameter equal to its value in final point of graph} :PLOT PLOT 1 WRITELN WRITELN &P1 VS. &P2 FOR CLASS &CCLASS RETURN :RET WRITELN WRITELN AN ERROR HAS OCCURRED. ERROR CODE = &I1 WRITELN SET INDEX1 2- GOTO PLOT This EXEC stores performance measure values in TABLE1, and then plots the table when all points are calculated. If more than one graph was desired, additional code would have to be added to store the appropriate functions in other TABLE variables. When plotting graphs, MAP normally picks a Y axis scale that depends on the function being plotted. Sometimes it is useful to force PLOT to use a particular scale. For instance, in plotting a number of graphs that will later be compared it is helpful to have the Y axis scales the same in all of them. This can be accomplished in MAP using the EXEC variables YMAX and YMIN and the command USESCALE. Normally MAP labels the Y axis so that the maximum and minimum Y values occurring in the function graphed are used as the maximum and minimum Y values on the axis. However, the user can set these values explicitly (using YMAX and YMIN) and instruct MAP to use these explicit values using the USESCALE command Parameter ON to USESCALE indicates that the values of YMAX and YMIN should be used in drawing the graph. Parameter OFF indicates that values should be chosen automatically. It is also possible to have MAP set YMAX and YMIN to the values it uses in plotting a graph by issuing the SETSCALE command. Parameter ON indicates that the next time a PLOT command is issued, MAP should use the maximum and minimum Y values of the plotted function to label the Y axis, and should place those values in YMAX and YMIN. (Note that MAP uses the maximum and minimum function values in plotting the graph even if USESCALE is ON.) SETSCALE is set to OFF automatically when a PLOT is executed. The following example uses SETSCALE, USESCALE, and the EXEC GRAPH to create two graphs with identical Y axis labeling: USESCALE ON SETSCALE ON GRAPH RESPONSE LOAD 2.5 3.5 .1 GRAPH RESPONSE MEMSIZE 8 16 2 ----------------------------------------------------------------------------- CHAPTER 5 MODELING I/O SUBSYSTEMS 5.1 BASIC I/O MODELLING All MAP models contain some representation of the I/O subsystem. The simplest models represent explicitly only the individual DASD devices, and have no explicit representation of I/O path components. Such a model might consist of a single service center representing the CPU and some number of service centers each representing a single DASD. It should be noted that the parameterization of DASD service centers implicitly includes a characterization of the I/O path components. In particular, the LOADING at a DASD center, obtained from measurement of an operating system, contains device busy time attributable to I/O path contention, such as Rotational Positional Sensing (RPS) miss time. The busier the I/O subsystem, the greater the amount of contention, and so the larger the measured device LOADINGs. Because the I/O subsystem is always at least implicitly included in a MAP model, it is appropriate to use these very simple models in some cases. They are most appropriate when the modification analysis portion of the study is not directly concerned with changes to the I/O subsystem itself. If this is the case, a reasonable first order approximation is that the I/O path contention times will not change significantly, and so the current measured contention times (as reflected in the device LOADINGs) are reasonable estimates of contention in the projected systems. The advantage of using this very simple sort of model is the relatively few parameters required to specify it. The user is not faced with the task of supplying the additional information required by more sophisticated models. (Of course, software for creating MAP models, such as OBTAIN, can greatly ease this task.) At the same time, modeling studies that involve modifications judged likely to affect I/O contention require a more sophisticated approach. If the I/O contention changes, the LOADINGs of the DASD devices must change to reflect the increased or decreased I/O times MAP provides this level of sophistication, with its advanced modeling features, described in the remainder of this chapter. 5.2 ADVANCED MODELING: NON-CACHED I/O More sophisticated MAP models of I/O subsystems require refinements of two aspects of the model: the path components connecting the CPU and main memory to the DASD, and the substeps required in an individual I/O operation. In this paragraph, non-cached I/O is discussed. Cached I/O is discussed in paragraph 5.3. MAP provides for explicit representation of three I/O path components: CHANNELs, CONTROLLERs, and STRINGs. In analogy with CENTERs, these components are created by the CHANNEL, CONTROLLER, and STRING commands, respectively, and can be listed using LIST and deleted from the model using CANCEL. Paths between the CPU and I/O devices are described by identifying the string to which each DASD is connected (using ONSTRING), the set of controllers to which each string is connected (using ONCONTROLLER), and the set of channels to which each controller is connected (using ONCHANNEL). A DASD center can be attached to only one string, but each string and each controller can be attached to any number of controllers or channels, respectively. (Warnings are printed for unreasonably large numbers of connections.) All data transfer operations for a disk device must take place over one of the paths connecting it to main memory through a channel. With the possible exception of the string heads, it is assumed that each path component (string, controller, and channel) can be involved in at most one operation at a time. (TDEFINE can be used to define string head models with multiple paths so that more than one disk on the string can be performing data transfer at a time.) MAP provides the evaluation of the contention for these components, and the effect of this contention on performance. The command LIST IO can be used to examine the current I/O subsystem components and their interconnections. The output command PATHREPORT gives the utilizations of the individual path components. A non-cached I/O operation consists of a number of steps. MAP explicitly models four of these: seek, latency, RPS miss, and data transfer. During modification analysis, MAP automatically reevaluates the RPS miss component and adjusts DASD center LOADINGs accordingly. To do so accurately, MAP must be able to determine the time taken by each I/O operation component. The seek, latency, and data transfer times are supplied directly as inputs. Measured RPS miss time is supplied indirectly through specification of time per operation (so that RPS miss can be inferred by subtracting the other components from the total I/O operation time). The I/O operation parameters can be supplied in either of two ways. The first is by specifying the model of the DASD center (using the MODEL command). If no model is given, the default DASD model (the first DASD model defined using the TDEFINE command, usually in the INITDEVS MAP EXEC) is assumed. Associated with each model is a set of default I/O component times, which serve as defaults for DASD centers of that model. Characteristics of models can be examined and altered using the TDEFINE command. Additionally, new models can be defined with this command. The second way to supply these times is to override the default values provided by a DASD's model. In particular, the %SEEK and BLOCKSIZE commands allow the user to specify the percent of accesses requiring seeks and the block size of disk access for each individual DASD. (The CONNECTTIME command can be used in place of the BLOCKSIZE command to provide similar information: the amount of time that the disk is connected to a channel during each operation. Only one of BLOCKSIZE and CONNECTTIME should be used in a single model.) In some cases it will be necessary to override the defaults for the model to correctly determine I/O path component utilizations. Once the I/O path components and interconnections have been specified, and the DASD center parameters have been given, the model can be validated. When this is done, a SETSYSTEM ON command must be given before entering the modification analysis phase of the study. This indicates to MAP that subsequent changes to the model should cause MAP to reevaluate the RPS miss component of I/O time, and to adjust LOADINGs and IOTIMEs appropriately. Typically, once SETSYSTEM has been set ON, it should not be turned OFF. A modeling study using MAP and the advanced I/O modeling facilities should normally proceed as follows: 1. A standard MAP model of the system should be created and parameterized from measurement data. This model consists of service centers representing the CPU and DASD devices and customer classes representing workload components. 2. The I/O subsystem model should be created using the CHANNEL, CONTROLLER, and STRING commands. Service centers representing DASD devices should be given a MODEL (using the MODEL command), a service time per operation (set using the IOTIME command), and a transfer time per operation (using the CONNECTTIME command). 3. The paths between the CPU and DASD should be described by connecting strings to controllers (using ONCONTROLLER) and controllers to channels (using ONCHANNEL). DASDs should be grouped into strings (using ONSTRING). 4. The model should be validated against the current configuration by adjusting the parameters until the outputs of the model agree reasonably with the measurements of the system. 5. A SETSYSTEM ON command should be issued to inform MAP that the current model adequately represents the system. 6. Changes to the computer system should be reflected in the model, and performance reports generated. For instance, the addition of a new workload might be modeled by creating a new job class in the model and issuing a PERFORMANCE command. MAP will automatically incorporate these changes in its evaluation of I/O subsystem performance. Some common situations that might be modeled are: +o Balancing file usage across disks. A MOVE command can move part of the loading at one disk device to another. The two devices can be on the same or different strings. If both devices have defined models, this information is used in computing the new loadings. +o Balancing disks on strings. A disk can be moved from one string to another simply by making the disk current (e.g., CENTER DISK1) and issuing an ONSTRING command (e.g., ONSTRING STRONE). This procedure should be followed whether or not the service center was already on a string. +o Adding a new disk to the model. A new service center should be created and its loadings specified. The IOTIME of the center should be estimated as the sum of seek, latency, and transfer times (possibly by examining measurements of existing disks with behaviors similar to that expected of the new disk); its MODEL given; and an ONSTRING command issued to place it on a string. +o Adding a channel or controller to the system. A new channel or controller should be created and I/O paths using it defined using ONCONTROLLER and ONCHANNEL commands. Output reports can then be requested to indicate the extent to which I/O path contention has been reduced. It is important to remember that MAP ignores the I/O subsystem information until a SETSYSTEM ON command is issued, and that before issuing this command the entire model must be completely defined and validated. 5.3 ADVANCED MODELING: CACHED I/O Modeling cached I/O operations requires additional parameterization of the model. MAP assumes that the caches are maintained by the controllers. Each I/O operation for a cached device can be satisfied by an entry in the controller's cache. This is called a cache hit. If the data is not currently in the cache, the operation is a cache miss. The components of a cached I/O operation depend on whether it is a read or a write, and whether it is a cache hit or a cache miss. For all four possibilities there is a certain amount of controller overhead, spent determining whether the operation is a hit. MAP allows the user to specify the amount of overhead separately for eac of the four possible operations. These parameters, like all others, are specified in the TDEFINE of a controller model. The model can then be associated with a specific controller using the MODEL command. A read hit operation is satisfied directly out of the controller cache, and does not require any DASD service. The time required to service a read hit is given by the RHTIME parameter of the controller model (as specified using TDEFINE). A read miss operation involves a DASD operation to satisfy the request and a staging operation to load the data into the cache. Staging can take place concurrently with the initial I/O operation, or can be a separate (additional) I/O operation. The TDEFINE parameter RMSTAGEIME indicates the time in excess of the initial DASD operation required for staging. A RMSTAGEIME of 0.0 indicates that staging takes place concurrently. Both read misses and read hits involve the same basic operations: some amount of controller overhead plus a disk I/O operation. (In other words, MAP assumes a write-through cache policy.) They differ only in the amount of the overheads. To correctly determine the effective time per I/O operation, MAP needs a characterization of the I/O request stream. In particular, it needs to know the fraction of read operations that results in hits (the RHIT TDEFINE parameter), the fraction of writes that results in hits (the WHIT TDEFINE parameter), and the ratio of the number of reads to the number of writes (the RWATIO TDEFINE parameter). The parameters associated with a controller's model serve as defaults for all DASD that are connected to it (indirectly through their strings). MAP allows a DASD to be connected to two or more controllers that are not associated with the same cache (i.e., have different caching parameters), although strictly speaking this is not possible with current (or anticipated) technology. In this case, though, the parameters of the various caches are averaged. MAP allows the default values associated with the controller cache to be overridden for individual DASD. In particular, the RHIT, WHIT, an RWATIO commands specify values for the current center, and override the defaults. Finally, each individual DASD can be individually selected for caching. The command CACHING takes parameters ON and OFF. ON indicates that the center uses the cache; OFF indicates that it does not. -------------------------------------------------------------------------- CHAPTER 6 MODELING TERMINAL NETWORKS Communication delays can be modelled in MAP using the terminal network facilities. A terminal network consists of LINKs (which connect the terminal network to the processor) and NODEs (which attach terminals to LINKs). Communication lines are defined by the LINK command. The speed of the communication line is defined by the LINKSPEED command. The NODE command defines a terminal attachment point which is associated with the current link using the ONLINK command The ATTACHES command specifies the number of terminals of the current class that the current node attaches to the system. Communication activity is specified by the INMESSAGESIZE, OUTMESSAGESIZE, and MESSAGECOUNT commands, which apply to the current class. The NODEUSE and LINKUSE commands produce performance reports. ------------------------------------------------------------------------ CHAPTER 7 THE FUNCTION OF SETSYSTEM There are two steps involved in modeling a computer system: the creation and validation of the baseline model and the use of the model to investigate the impact of modifications to the system. During the creation process, the user must be free to modify the input parameters to achieve model validation without MAP assuming that these modifications should cause changes to other related parameters as side-effects. For instance, MAP should not change the (measured) RPS miss times of DASDs when the user changes the DASD blocksizes, as the user is most likely simply setting the blocksizes, not modifying them. However, once the model is validated, changes to it should cause MAP to alter related parameters to reflect these changes. The purpose of SETSYSTEM is to distinguish between these two phases. SETSYSTEM OFF corresponds to the model creation and validation phase. SETSYSTEM ON corresponds to the model modification phase. The most important influence of the setting of SETSYSTEM is on those commands dealing with modeling of memory and I/O subsystems. An important part of I/O subsystem performance is amount of path contention that takes place. MAP has the built-in capability to evaluate the amount of path contention if given information about the I/O path connections and the amount of activity directed to each path. The SETSYSTEM command controls a MAP internal flag that determines whether or not MAP should adjust DASD loadings to account for changes in path contention resulting from changes in the MAP model. If SETSYSTEM is off, MAP does not evaluate path contention changes automatically. If SETSYSTEM is on, MAP uses that information. There are two typical ways in which MAP is used. The predominant one is to create a baseline model of an existing system using measurement data from that system obtained by a tool such as SMF or RMF. (This step might be automated using the OBTAIN model generation program. In this case, the measurement information for DASD busy times includes delays due to path contention. That information is exploited by MAP to provide more accurate results. In modeling an existing system, the correct procedure is to fully describe and validate the model (using the measured IOTIMEs that include path contention). All I/O paths should be defined and the DASD placed on them. Only when this model (with SETSYSTEM OFF) validates should SETSYSTEM be turned on. At this point MAP extracts from the IOTIME information the (measured) amount of time due to path contention and stores this value for future use. No changes are made to any device loadings (since the model has not been changed from the baseline). Therefore, no changes occur in any model outputs. However, from this point on, any changes made to the model result in MAP computing new path contention times and adjusting the DASD loadings accordingly. The other way in which a MAP model might be developed is from guesses about the service times in a proposed computer system (i.e., one that does not currently exist and so cannot be measured). In this case, the simplest procedure is to provide IOTIMEs that consist only of seek, latency, and transfer components. MAPs built-in facilities can then be used by setting SETSYSTEM ON and placing the DASD on the I/O paths. As the DASDs are connected, MAP will change the device loadings to account for path contention (since SETSYSTEM is ON). This saves the user the problem of determining path contention times himself or herself. The principal commands used to model changes to memory are MEMSIZE, PAGECOUNT, and SWAPCOUNT. When SETSYSTEM is OFF these commands have no effect other than to set their corresponding values. When SETSYSTEM is ON these commands cause MAP to change other related parameters. In the case of MEMSIZE, the user is queried as to whether the change in memory size is being used to alter multiprogramming levels (with the assumption that the number of page and swap operations per job will not change significantly) or to alter page and swap activity. If the former, MAP adjusts the AVGPL of all classes of type BATCH, and adjusts all domain capacities. If the latter, the user is requested to supply new PAGECOUNT and SWAPCOUNT values, which are used to determine new loadings at the page and swap devices. Issuing PAGECOUNT or SWAPCOUNT commands with SETSYSTEM ON also causes MAP to calculate new page and swap device loadings. ------------------------------------------------------------------------- CHAPTER 8 LIST OF COMMANDS This chapter lists the MAP commands and their effects. Examples of each command are given. These examples might contain multiple MAP commands on a single input line or use command name abbreviations to show these features in the MAP input language. 8.1 ADMIT Command: ADMIT Parameters:FCFS or PRIORITY. Effect: The scheduling policy of the current domain is set to FCFS or priority, as appropriate. If the current domain is EACH, MAP prompts for the policy of each domain. If the current domain context is EVERY, the scheduling disciplines of all domains are set by the single parameter given. (Domain scheduling priorities for each class are set by the DPLEVEL command.) Errors: No current domain. Invalid parameter. Example: DOMAIN NEWMEM ADMIT PRIORITY The current domain is set to NEWMEM. If no such domain existed previously, one is created. The admission policy of NEWMEM is set to priority. 8.2 ARRIVAL RATE Command: ARRIVAL_RATE Parameter:Real valued arrival rate. Effect: If the current class is not EACH, the arrival rate of the current class is set by the parameter. (If the current class is EVERY, the arrival rate of every class with either transaction or undefined type is set to the single parameter value given.) If the current class is EACH, MAP prompts for values for each class with undefined or TRANSACTION type. If the type of a current class is undefined, it is made TRANSACTION. Errors: Current class is not EACH or EVERY and is not TRANSACTION type. No current class. Negative arrival rate. Example: ARR 6+ The arrival rate of current class is incremented by 6. 8.3 ATTACHES Command: ATTACHES Parameters:A real number of terminals. Effect: The current node is indicated as having the specified number of terminals of the current class. The total message traffic of each class is allocated among nodes in proportion to the number of terminals of that class that each node attaches. There is no requirement that the number of terminals of a class attached to nodes equal the total number of terminals of that class when it is a TERMINAL type class. The terminals given in the ATTACHES command are simply weights used to distribute message traffic. Error: Value must be non-negative. Example: CLASS TSO NODE NODE001 ATTACHES 100 NODE001 attaches 100 TSO terminals. If all other nodes combined ATTACH 300 more TSO terminals, 25% of TSO's message traffic will be assumed to flow through NODE001 and the LINK to which it connects. 8.4 AUTHOR Command: AUTHOR Parameters:Two character strings. Effect: This command is intended solely for documentation purposes. It has no functional effect. The two parameters are used to document the creator of a MAP model definition file to be read using the READ command. The parameters are simply read and discarded by MAP. The SAVE command inserts an AUTHOR command in the saved file. Errors: Failure to provide two parameters to this command will cause errors in the interpretation of subsequent commands. Example: AUTHOR MAP V2.0 The author is indicated to be Version 2.0 of MAP. 8.5 AVG_MPL Command: AVG_MPL Parameter:Real-valued average multiprogramming level. Effect: If the current class is not EACH, the multiprogramming level of the current class is set to the parameter value. (If the current class is EVERY, all classes with BATCH or undefined type are set.) If the current class is EACH, MAP prompts for values for each class of undefined or BATCH type. If the type of the current class is undefined, it is made BATCH. Errors: Current class is not EACH or EVERY and is not BATCH type. No current class. Negative average multiprogramming level. Example: CLA PROD AVG 8 The multiprogramming level of PROD is set to 8. 8.6 BASELINE Command: BASELINE Parameters:IORESTIME, MEMWAIT, QLENGTH, RESIDENCE, RESPONSE, THROUGHPUT, or UTILIZATION, followed by measured performance values. Effect: The MAP EXEC variable corresponding to the BASELINE value indicated by the parameter is SET. This command is intended primarily for use by automatic model generation programs. It allows them to insert commands into MAPDAT files that indicate the measured performance values. Use of the DISPLAY RELATIVE command then allows the analyst to determine how much the model deviates from the actual system during the validation step. The data given applies to the current center and class, as appropriate. If either is EACH, a list of input values is required. Error: Example: CLASS TSO BASELINE RESPONSE 0.23 The measured response time of class TSO is indicated to be 0.23 seconds. 8.7 BLOCKSIZE Command: BLOCKSIZE Parameters:Real valued block size. Effect: The parameter represents the number of bytes transferred (in kilobytes) for an average I/O operation performed to the current center. This value overrides the default value for the MODEL of this device (if any). Errors: No current class. A warning is printed if the current center is not a Direct Access Storage Device (DASD) model. Negative or zero blocksize. Example: CENTER TSO001 BLOCKSIZE 8 Center TSO001 transfers 8 kilobytes per operation. Notes: BLOCKSIZE is effective only when the center has been assigned a DASD MODEL and that model has been given a TRANSFERRATE. See MODEL and TDEFINE. Only one of BLOCKSIZE and CONNECTTIME should be specified in a single MAP model. 8.8 BRIEF Command: BRIEF Parameter:A nonnegative integer message level or none. Effect: The integer parameter defines a message level for tailoring of MAP prompting to the experience of the user. Prompts with internal message levels less than the parameter are not printed subsequent to execution of the command. Thus, higher brief settings result in decreased prompting. If no parameter is given with the BRIEF command, MAP responds with the current message level setting. The default setting is 0. Error: Negative argument Examples: BRIEF MAP responds with current setting. BRIEF 1 Turns off level 0 messages, those reporting creation of a new object in the model. 8.9 CACHING Command: CACHING Parameters:ON or OFF. Effect: If ON is specified, the center is assumed to be cached by its associated controllers. If caching is OFF, it is not cached. CACHING ON is required for RHIT, WHIT, and RWATIO to have any effect. Similarly, CACHING ON is required for altering of controller parameters to have any effect. (In both cases, SETSYSTEM ON is also required.) Errors: No current center. Invalid parameter. Example: CENTER PAG017 CACHING ON PAG017 becomes a cached device. 8.10 CANCEL Command: CANCEL Parameters:ALL, CENTER, CHANNEL, CLASS, CONTROLLER, DOMAIN, LINK, NODE, STRING, or none. Effect: If a parameter is given, the currently defined object of that type is removed from the model and the current object of that type is set to NONE. If no parameter is given, or the parameter ALL is given, all objects in the model are canceled, giving a null model. In each case, the action must be confirmed by answering Y or N to the appropriate prompt. Errors: Ambiguous or unknown parameter. Channels and controllers cannot be canceled if currently part of a logical channel. Examples: CAN CLASS Assuming the current class was IMS, MAP would respond with CANCEL CLASS IMS (Y OR N)?. N (No) terminates the command. Y (Yes) results in the removal of the IMS job class from the model. CAN MAP asks for confirmation to cancel the entire model and then acts according to the response. 8.11 CENTER Command: CENTER Parameters:The name of a service center, EACH, EVERY, or none Effect: If no parameter is given, the name of the current center is printed. If EACH or EVERY is given, subsequent commands affecting service centers refer to all currently defined service centers. If a service center name is given, that center is made the current center. If a center with the name given does not currently exist, a new center is created with that name. New centers are initialized so that the loadings of all classes at them are 0.0 and the scheduling disciplines are NORMAL. Errors: An attempt is made to create a new center when the model already contains the maximum number of centers allowable. EACH and EVERY are not allowed when the current model contains no centers. Ambiguous center name. Examples: CEN CP Assuming center CPU was the only center whose name began with CP, it would be made the current center. Subsequent commands affecting service centers refer implicitly to that center (until the next CENTER command). CEN DISK3 If no center had a name beginning with DISK3, MAP would respond that a new service center had been created (with name DISK3). The LOADINGs of all job classes at DISK3 would be set to 0.0. DISK3 would have NORMAL scheduling. 8.12 CHANNEL Command: CHANNEL Parameters:The name of a physical channel, EACH, EVERY, or none. Effect: If no parameter is given, the name of the current channel is printed. If EACH or EVERY is given, subsequent commands affecting channels refer to all currently defined channels. If a channel name is given, that channel is made the current channel. If a channel with the name given does not currently exist, a new channel is created with that name. Errors: An attempt to create a new channel is made when the current model possesses the maximum number of channels allowable. EACH and EVERY are not allowed when the model contains no channels. Ambiguous channel name. Examples: CHANNEL MAP responds by printing the name of the current channel. CHANNEL CHAN1 Assuming that no existing channel had a name beginning with CHAN1, a new channel, CHAN1, would be created. 8.13 CLASS Command: CLASS Parameters:The name of a customer class, EACH, EVERY, or none. Effect: If no parameter is given, the name of the current class is printed. If EACH or EVERY is given, subsequent commands affecting customer classes refer to all classes. If a class name is given, that class is made the current class. If a class with the name given does not currently exist, a new class is created with that name. New classes are initialized to have loadings of 0.0 at all service centers. All other parameters are undefined. Errors: An attempt to create a new class is made when the current model possesses the maximum number of classes allowable. EACH and EVERY are not allowed when the model contains no classes. Ambiguous class name. Examples: CLA MAP responds by printing the name of the current class. CLA TSO The current class is set to TSO. CLA NEWIMS A new class (NEWIMS) is created, with LOADINGs of 0.0 at all service centers. The workload intensity and type of NEWIMS are undefined. 8.14 CLEANIO Command: CLEANIO Parameters:None. Effect: Unused IO path components (STRINGs, CONTROLLERs, and CHANNELs) are removed. The user is prompted for confirmation that these components should be CANCELled. The command should be invoked when there are many superfluous path components in the current model as these components cause warnings to be printed whenever the model is evaluated. Error: None. Example: CLEAN Any path components not on a path between a center and the CPU/memory are removed. 8.15 CLOSE Command: CLOSE Parameters:None. Effect: The currently open output file (see OPEN) is closed and removed from the stack of output files. Thus, the previous most recently opened file becomes the output report destination file. Error: No currently open file. Example: CLOSE The current output file (if any) is closed. 8.16 CONNECTTIME Command: CONNECTTIME Parameter:A real valued connect time. Effect: Connect time is the amount of time the disk is connected to the channel during each I/O operation. The parameter to this command sets the connect time for the current center. Only one of BLOCKSIZE and CONNECTTIME should be used in defining a single model. The LIST command will print information on only one of the two, choosing CONNECTTIME if both commands have been issued. Errors: No current center. Negative connect time. Example: CEN PAG301 CONNECT .003 Center PAG301 is indicated as using the channel an average of 3 ms per operation. Notes: If CONNECTTIME is not used, equivalent information is obtained from the ratio of BLOCKSIZE (as specified for the center in particular or the default taken from the MODEL) to TRANSFERRATE (as taken from the center's MODEL). 8.17 CONTROLLER Command: CONTROLLER Parameters:The name of a controller, EACH, EVERY, or none. Effect: If no parameter is given, the name of the current controller is printed. If EACH or EVERY is given, subsequent commands affecting controllers refer to all currently defined controllers. If a controller name is given, that controller is made the current controller. If a controller with the name given does not currently exist, a new controller is created with that name. Errors: An attempt to create a new controller is made when the current model possesses the maximum number of controllers allowable. EACH and EVERY are not allowed when the model contains no controllers. Ambiguous controller name. Examples: CONTROLLER MAP responds by printing the name of the current controller. CONTROLLER CONTROL1 A new controller, CONTROL1, is created. 8.18 CV2 Command: CV2 Parameters:A real valued coefficient of variation of service time at the current center. Effect: The parameter indicates the ratio of the variance in service time to the square of the mean service time at the current center. The CV2 affects the amount of queueing that will occur in obtaining service from the center. The default CV2 is 1.0. Smaller CV2's result in less queueing, larger CV2's in more. CV2 has an effect only if the scheduling discipline of the current center is NORMAL. Errors: No current center. Parameter value less than 0.0. Examples: CEN DASD1 CV2 0.5 The coefficient of variation of center DASD1 is set to 0.5. 8.19 DISPLAY Command: DISPLAY Parameters:ABSOLUTE or RELATIVE. Effect: This command controls the mode in which performance measures are shown in output reports, and affects how the values of some EXEC varaibles are given. In reports, ABSOLUTE indicates that the values themselves should be shown, while RELATIVE indicates that the percentage change from the saved baseline measures (see SETBASELINE) should be shown. The values of EXEC variables MEMWAITTIME, RESIDENCE, RESPONSE, THROUGHPUT, QLENGTH, UTILIZATION, and WAITTIME are affected similarly. (All other EXEC variables are unaffected.) Error: Invalid parameter. Example: DISPLAY REL RELATIVE display mode is selected. Suppose the current response time is 2.0 seconds and the saved baseline response time is 2.5 seconds. In ABSOLUTE mode the response time would be shown as 2.0 seconds. In RELATIVE mode it will be shown as -20%. 8.20 DOMAIN Command: DOMAIN Parameters:A domain name, EACH, EVERY, or none. Effect: If no parameter is given, the name of the current domain is printed. If EACH or EVERY is given, subsequent commands affecting domains refer implicitly to all domains. If a domain name is given, that domain is made the current domain. If the domain does not currently exist, it is created, with FCFS scheduling and undefined capacity. Errors: The model contains the maximum number of allowable domains when an attempt is made to create a new domain. EACH and EVERY are not allowed when the current model contains no domains. Ambiguous domain name. Examples: DOMAIN DOMAIN1 The current domain is set to DOMAIN1. DOM NEWDOMAIN Assuming it does not already exist, domain NEWDOMAIN is created. There are no classes in the domain; its scheduling discipline is set to FCFS (as the default); and its capacity (limit) is undefined. 8.21 DPLEVEL Command: DPLEVEL Parameter:Integer priority level. Effect: The The domain scheduling priority of the current class is set to the integer argument. If the current class is EACH, MAP prompts for domain priorities for each existing class. If the current class is EVERY, the DPLEVEL of every class is set to the single parameter value given. Priority levels are positive integers, with larger values indicating priority over smaller values (thus, 1 is the lowest possible priority). Errors: No current class. Negative or zero priority level. Examples: CLA EACH DPLEV MAP prompts for the domain scheduling priorities of all classes in the model. CLA TSO DPLEV 4 The domain scheduling priority of TSO jobs is set to 4. 8.22 EXIT Command: EXIT Parameters:None. Effect: Terminate this MAP session. If the model current at the time does not exist as a permanent MAP data file, a warning is printed. The user is requested to confirm his intention to exit the MAP session by typing a Y. Errors: None. Example: EXIT The user is asked to confirm his intention to exit, and upon doing so the MAP session is ended. 8.23 FORMAT Command: FORMAT Parameters:A list of format specifiers terminated with ENDFORMAT. Effect: FORMAT allows the user to control the format of output created using the WRITE and WRITELN commands. FORMAT creates a template that indicates how each token output should be printed. The format specifiers are A n Alphanumeric field of length n. If n is greater than 0, exactly the next n columns of output will be used to print the token, truncating or padding as necessary. If n equals -1 MAP will print the non-blank portion of the current token in exactly the number of columns required. F n m A floating-point field of n columns. The output is printed with m digits to the right of the decimal place if m is greater than 0. If m is -1 MAP will print the number in n columns showing the greatest number of significant digits possible. I n An integer field of width n, if n is greater than 0. If n is less than 0, the field width is chosen equal to the number of digits in the integer. T n Tab to column n. , The previous item is follwed by a comma (instead of the default blank), unless the previous item is the last item in the list. A template is constructed by stringing these format specifiers one after another and terminating the list with ENDFORMAT. If the list of items given with a WRITE or WRITELN command is longer than the format list, the list is repeated starting from the beginning as many times as necessary. There is a distinct FORMAT for each output level, meaning that each EXEC invoked can create its own FORMAT. Error: Improper specifier list. Example: FORMAT T 5 A 10 T 25 F 10 3 ENDFORMAT The template indicates that each output line consists of an alphanumeric field in columns 5 through 14 and a floating-point field in columns 25-34. There will be three digits to the right of the decimal in the floating field. FORMAT I -1 , ENDFORMAT The WRITE may specify any number of integers. Each is printed with no leading blanks, and all but the last is followed by a comma. Thus, WRITE 10 20 30 40 would produce 10,20,30,40 8.24 GDEFINE Command: GDEFINE Parameters: Effect: The group given by the current context is given a name. The group name must not already exist as a group of the specified type. The is one of CLASS, CENTER, DOMAIN, LINK, CHANNEL, CONTROLLER, NODE, STRING, or CANCEL. If CANCEL is given the named group becomes undefined. Because the same name may define groups of more than one type, some ambiguity is possible on a CANCEL request. This is resolved by searching the lists of group names in the order of the group types given above (i.e., from CLASS to STRING). See Section 2.4 of this manual for further information. Errors: The current context does not form a group (contains only a single entity or is NONE, EACH, or EVERY.) Maximum number of groups already defined. Ambiguous group name. Example: DOMAIN TSODOM* GDEFINE TSODOMS DOMAIN A group TSODOMS is created and contains all domains whose name starts with ``TSODOM''. (Notice that these statements would cause an error if there are zero or one domains with matching names.) 8.25 GOTO Command: GOTO Parameter:A label name. Effect: When processing a MAP EXEC file, the next command executed is the one immediately following the label in that file. (Labels are encoded with a leading colon [:] [e.g., :LOOP], and must begin in column 1 of the input.) Errors: If the label does not appear in the EXEC file, an error message is printed and processing of that file is terminated. GOTO is not allowed when entering commands from the terminal. Example: GOTO LOOP Flow of control is transferred to the command immediately following the string :LOOP in the current EXEC file. 8.26 HASUNITS Command: HASUNITS Parameters:Two three-digit hexadecimal unit numbers. Effect: The current string is indicated to contain all devices with unit numbers falling within the range given by the two parameters, inclusive. The first parameter gives the lowest unit number of devices on the string, and the second the highest. The parameters are given as hexadecimal numbers of no more than three digits. When HASUNITS is issued, all centers with unit numbers falling in the indicated range are placed on the current string (as if an ONSTRING command had been issued for those centers). Additionally, future UNIT commands will cause an implicit ONSTRING if the units specified fall in the range given by the HASUNITS command. If the second parameter has a smaller value than the first, the HASUNITS range for the current string (if any) is canceled, and no centers will be placed on this string automatically because of future UNIT commands. Additionally, current centers on the string will be removed, since the user is indicating that the current string contains a null range of unit numbers. Errors: Invalid parameter value. No current string. Specified range overlaps an existing range for some other string. Example: STRING STR1 HASUNITS 120 12F All existing centers with UNITs between 120 and 12F inclusive are placed on string STR1. Additionally, future UNIT commands in the range 120 to 12F will cause the center affected to be placed on string STR1, exactly as if an ONSTRING STR1 command had been issued. 8.27 HELP Command: HELP Parameters:ALL, CENTER, CHANNEL, CLASS, CONTROLLER, DOMAIN, EXECS, FILES, GRAPHS, IO, MEMORY, REPORTS, STRING, or none. Effect: If no parameter is given, a list of valid parameters is printed. Otherwise, a list of command names and their effects is printed. The parameter determines which subset of commands is listed. If the parameter is ALL, all commands are listed. In other cases, only those commands concerned with the named subject type are listed. Errors: None. Invalid or ambiguous parameter. Example: HELP ALL A summary list of MAP commands is printed at the terminal. 8.28 IF Command: IF Parameters: