[ Previous | Next | Contents | Glossary | Search ]
Performance Toolbox Version 1.2 and 2 for AIX: Guide and Reference

Appendix B. Performance Toolbox for AIX Files

Overview of File Placement

Several of the programs in Performance Toolbox for AIX use files, either to customize the programs' behavior or as output or log files. The programs access their files according to an access scheme that allows a user of a host system to override the default information in the files without affecting the defaults available to other users. This appendix gives an overview of the files and their access scheme.

An access scheme is defined as:

Files used by xmperf and Other Data Consumers

The following files share a standard access scheme:

xmperf.cf
The xmperf configuration file.
xmperf.hlp
The xmperf simple help file.
exmon.cf
The exmon configuration file.
exmon.hlp
The exmon simple help file.
azizo.hlp
The azizo simple help file.
Rsi.hosts
The file that defines broadcast options to use.
3dmon.cf
The 3dmon configuration file.
3dplay.hlp
The 3dplay help file, available with Version 2.2 or later .
filter.cf
The filtd configuration file.

When a program needs one of these files, the file is first searched for in the user's home directory. If the file is found there, that file is used.

If the file doesn't exist in the user's home directory, the file is looked for in the directory /etc/perf . Since the /etc directory is always unique for all hosts, even when some hosts are diskless hosts, this allows for defining defaults on a per host basis. Again, if the file is found in this directory, that file is used.

The last place the file is looked for is in /usr/lpp/perfmgr (in case of the filter.cf, the last place the file is looked for is in /usr/lpp/perfagent ). If the file can not be located in any of the directories, the program will be missing important information and may terminate or provide reduced function.

The standard access scheme can be overridden by specifying a full file name on the command line when starting the program. This is the case for the files:

xmperf.cf
The xmperf configuration file.
3dmon.cf
The 3dmon configuration file.
filter.cf
The filtd configuration file.

The xmperf configuration file can be saved from the menus of xmperf. When this happens, the file is normally saved to the user's home directory. Only if the file name has been overridden on the xmperf command line, is the file saved to that same name. This gives users an easy way to modify the default configuration file.

The filtd program produces a log, which alternates between two file names that are identical, apart from one ending in 1 and the other in 2. The file name of the log files are:

The xmperf and azizo programs use a log file to record any error or warning messages and state information. The file is written to $HOME/xmperf.log or $HOME/azizo.log , if possible, otherwise the output is directed to stdout. Each time xmperf and azizo execute, they overwrite any previous copy of their files.

Files used by xmservd

The files xmservd.res and xmservd.cf can exist in two directories. The xmservd daemon first attempts to locate the files in the directory /etc/perf . Because the /etc directory is always unique for all hosts, even when some hosts are diskless hosts, defaults can be defined on a per-host basis. If one or both files are found in this directory, that file is used.

If a file is not found, it is searched for in /usr/lpp/perfagent . If the file can not be located in this directory either, the xmservd continues without any of the actions that can be started from the file.

The xmservd normally produces a log, which alternates between two file names that are identical, apart from one ending in 1 and the other in 2. The file name of the log files are:

Two more files are created by xmservd under certain circumstances:

The xmservd.mib file is created whenever the xmservd daemon was started with the xmservd/SMUX interface active and subsequently sent a SIGINT signal (kill -2).

The xmservd.state file is created when the xmservd daemon is killed or aborts.

Neither of the four output files are created in other places than specified above.

Explaining the xmperf Configuration File

This section explains the format of those lines in the xmperf configuration file that you use to define consoles and instruments. This is described in Defining Consoles . and Defining Skeleton Consoles explains how to convert ordinary console definitions into skeleton console definitions.

The command line option -v is provided to assist you in debugging changes you make to the configuration file. It prints all configuration file lines to the xmperf log file. Lines with errors are followed by a line that begins with *** and explains the error or inconsistency.

Defining Consoles

All console definition lines in the configuration file must have an identifier. This identifier is divided in four parts by periods (full stops). A few examples of lines are shown in the following figure.

monitor.Mini   Monitor.1.width:    
        180
monitor.Mini   Monitor.1.height:           340
monitor.Mini   Monitor.1.x:                1108
monitor.Mini   Monitor.1.y:                580 
monitor.Mini   Monitor.1.background:       black
monitor.Mini   Monitor.1.foreground:       grey70

Example of Definition Lines

The first element of the identifier is a keyword, which must be monitor. Next follows the name of the console you define. All lines with this same name are taken as part of the definition of the console, no matter where they appear in the configuration file. In the example above, the name of the defined console is "Mini Monitor." You'll see that the name may have embedded blanks.

The third part of the identifier is used to identify the instrument within the console. The example above is thus defining part of the first instrument within the console "Mini Monitor."

The fourth part of the identifier describes which property of the instrument is defined. It may be a single keyword, in which case it describes a property for the console itself or for an instrument as a whole. It may be followed by a period and a sequence number, in which case it describes a property for a value in an instrument. In all cases, the fourth element of the identifier must be followed by a colon.

After the colon comes the actual value of the property. In the preceding figure, for example, the first line sets the width of the console to 180 pixels while the last line sets the foreground color of instrument number 1 in the console to a color called "grey70."

The keyword in the fourth part of the identifier determines whether the line defines a property for a console, an instrument, or a value. The following three sections describe the keywords that are valid for each of these groups.

The only keyword, which is required to define a console, is the input keyword defining a statistic to be plotted in an instrument of the console. All other keywords have defaults as detailed in the next sections.

Console Keywords

Keywords that define console properties should always be defined using an instrument sequence number equal to the lowest instrument number in the console. It is strongly suggested that this always be sequence number 1. The valid keywords are:

width
Defines the width in pixels of the window that will contain the console. Default is 400 pixels.
height
Defines the height in pixels of the window that will contain the console. Default is 500 pixels.
x
Defines the position of the left side of the console window, measured in pixels from the left side of the display. Default is position zero.
y
Defines the position of the top side of the console window, measured in pixels from the top of the display. Default is position zero.
Instrument Keywords

All keywords that describe instruments must be immediately followed by a colon and never by a sequence number. The valid keywords and related values are:

left
Relative position of the left side of the instrument, given as a percentage of the width of the console window. Must be from 0 to 100 and at least 10 less than "right." Default is 1.
top
Relative position of the top side of the instrument, given as a percentage of the height of the console window. Must be from 0 to 100 and at least 10 less than "bottom." Default is 1.
right
Relative position of the right side of the instrument, given as a percentage of the width of the console window. Must be from 0 to 100 and at least 10 larger than "left." Default is 99.
bottom
Relative position of the bottom side of the instrument, given as a percentage of the height of the console window. Must be from 0 to 100 and at least 10 less than "top." Default is 99.
shift
Number of pixels to shift. Only used for recording graphs. Must be from one more than "space" to 20. Default is 4.
space
Space between bars. Only used for bar graphs. Must be from 0 to one less than "shift." Default is 2.
history
Number of observations to keep in memory. Must be from 50 to 5,000. Default is 500.
interval
Number of milliseconds between observations. Must be from 100 to 15,000. Default is 5000.
background
Background color of instrument. Must be a color defined in the X color file. Default is black.
foreground
Foreground color of instrument. Must be a color defined in the X color file. Default is white.
backtile
Specifies the name of a tile (pixmap) that is used to paint the instrument. The tile name must be one of the following. The number in parentheses after the tile name indicates the number of the tile as shown in the color/tile dialog window of xmperf:
foreground (1)
Instrument is painted with 100% foreground and 0% background color.
background (2)
Instrument is painted with 0% foreground and 100% background color. This is the default tile.
vertical (3)
Instrument is painted with a pattern that mixes foreground and background colors to produce a pattern of vertical lines.
horizontal (4)
Instrument is painted with a pattern that mixes foreground and background colors to produce a pattern of horizontal lines.
slant_right (5)
Instrument is painted with a pattern that mixes foreground and background colors to produce a pattern of lines slanted to the right.
slant_left (6)
Instrument is painted with a pattern that mixes foreground and background colors to produce a pattern of lines slanted to the left.
plaid (7)
Instrument is painted with a pattern resembling the pattern in a plaid.
triangles (8)
Instrument is painted with a pattern composed of triangles.
wallpaper (9)
Instrument is painted with a pattern that resembles wallpaper.
zigzags (10)
Instrument is painted with a zigzag pattern.
fabric (11)
Instrument is painted with a pattern that looks somewhat like woven fabric.
style
Defines the primary style of the instrument. Must be one of the following values:
line
Line graph (default)
area
Area graph
skyline
Skyline graph
bar
Bar graph
level
State bar graph
light
State light graph
pie
Pie chart
meter
Speedometer graph

Actually, only the first three characters of the property name are used, since three characters are enough to make the graph type unique.

stacked
Specifies whether stacking is to be used for values that use the primary style. Specify TRUE if you want stacking to be used; otherwise specify FALSE. Default is false.
Value Keywords

This section describes how to define values for non-skeleton consoles. To see how to define values for skeleton consoles, see Defining Skeleton Consoles. The keywords used to define values must be followed by a period and the sequence number of the value. The value sequence number determines the sequence in which values are plotted, and influences the visual results when stacking is in use.

Plotting for each observation is done so that the lowest sequence number is plotted first. In the case of stacking, this means that the value with the lowest sequence number is plotted relative to zero. The next value is plotted relative to the previously plotted value, and so forth.

The keywords (here all shown with the sequence number 1, but it could be from 1 to 24) are:

input.1
The path name of the value to be plotted. For non-skeleton consoles, this must always be a fully qualified path name (no wildcards). Below are a few examples of the use of this keyword:
monitor.Mini 
Monitor.1.input.4:  IP/NetIF/tr0/ipacket
monitor.Mini Monitor.1.input.20:  Disk/hdisk0/busy
monitor.Maxi Monitor.7.input.18:  hosts/birte/Proc/runque 

The third of the above lines specifies a path name qualified with a host name. Lines with such path names are bound to a specific host. The other two lines do not bind to any specific host. The xmperf program assumes that such lines refer to the host defined through the concept of Localhost as described in The Meaning of Localhost in xmperf.

For process statistics, where the statistic name includes the process ID, a tilde, and the name of the executing program, you can specify either the process ID followed by the tilde, or the name of the executing program. The example below shows how to specify a statistic for the wait pseudo process. The wait pseudo process always has a process ID of 514 on AIX Version 3.2. Both lines point to the same statistic.

monitor.Wait Monitor.1.input.1:  Proc/514~/usercpu 
monitor.Wait Monitor.1.input.2:  Proc/wait/usercpu 

If you specify a name of a program currently executing in more than one process, only the first one encountered will be found.

color.1
The color used to plot the value. Must be a color defined in the X color file. Default is generated from a table of default values for the ValueColor1 through ValueColor24 X resources, depending on the sequence number of the value.
tile.1
Specifies the name of a tile (pixmap) that is used to paint the value if the style of the value is neither line nor skyline and if the style of the instrument is not state light. The tile name must be one of the following. The number in parentheses after the tile name indicates the number of the tile as shown in the color/tile dialog window:
foreground (1)
Value is painted with 100% value color and 0% background color. This is the default tile.
background (2)
Value is painted with 0% value color and 100% background color.
vertical (3)
Value is painted with a pattern that mixes value color and background colors to produce a pattern of vertical lines.
horizontal (4)
Value is painted with a pattern that mixes value color and background colors to produce a pattern of horizontal lines.
slant_right (5)
Value is painted with a pattern that mixes value color and background colors to produce a pattern of lines slanted to the right.
slant_left (6)
Value is painted with a pattern that mixes value color and background colors to produce a pattern of lines slanted to the left.
plaid (7)
Value is painted with a pattern resembling the pattern in a plaid. This pattern is not suited for instruments with low shift values because it requires some space to be recognizable.
triangles (8)
Instrument is painted with a pattern composed of triangles.
wallpaper (9)
Instrument is painted with a pattern that resembles wallpaper.
zigzags (10)
Instrument is painted with a zigzag pattern.
fabric (11)
Instrument is painted with a pattern that looks somewhat like woven fabric.
range.1
The scale (range) used to plot the value. Given as two values separated by a dash. Default is supplied from the SPMI data repository. A couple of examples:
monitor.Mini Monitor.1.range.1:  0-100 monitor.Mini Monitor.1.range.18:  
0-8 
thresh.1
Threshold value. Used only by the state light graph. Default is zero.
descending.1
Type of threshold value. Used only by the state light graph. Specify TRUE if the light must go on when the current value is below the threshold value. If you want the light to go on when the value is above the threshold, specify FALSE or don't specify the keyword. Default is false.
label.1
Defines the user-specified text that is used to label the value in the instrument. Default is no user-specified text (the value path name is used).
style.1
Defines the secondary style for the value defined. Only valid for recording graphs. Must be one of the following values:
line
Line graph
area
Area graph
skyline
Skyline graph
bar
Bar graph

The default is chosen as the same as the graph style of the instrument.

Defining Skeleton Consoles

Skeleton consoles are defined like any other console with two exceptions. Neither the keywords defining the console, nor those defining the instruments, are different. The only difference is in the keyword used to define the values in the instruments of the console. The keyword that's different is the input.1 keyword, which must be changed to all.1 or each.1.

The difference is that the path name of the value must contain exactly one wildcard, and that the path of all the all.1 and each.1 keywords in the console must be the same up to, and including the wildcard.

Whether you use all.1 or each.1 for the keyword depends on what type of skeleton you want. See Skeleton Instruments for an explanation of the two types of skeletons.

The following are three examples of sets of skeleton definitions:

monitor.Single-host Monitor.3.each.1: hosts/*/CPU/kern 
monitor.Single-host Monitor.3.each.2: hosts/*/Syscall/total
  
monitor.Remote Mini Monitor.1.each.4: IP/NetIF/*/ipacket monitor.Remote Mini 
Monitor.1.each.5: IP/NetIF/*/opacket
  
monitor.Uziza Disk Monitor.1.all.21: hosts/uziza/Disk/*/busy

The last line binds the skeleton to a specific host. When this is done, all value definitions in the console must be bound to the same host. If no host binding is done (as in the first two sets above), the concept of Localhost as described in The Meaning of Localhost in xmperf applies.

Note: You can mix skeleton types within a console; just remember that all paths up to the wildcard must be the same, not only in an instrument but for all instruments in a console.

Skeleton instruments of type "all" can, as we have already pointed out several times, only have one value defined. It follows that all values in the instantiated instrument will have the same color, namely as defined for the value in the skeleton instrument. This is rather dull. Worse though, is that it effectively restricts the "all" type skeletons to use the state bar graph type since otherwise you wouldn't be able to tell one value from another.

To cope with this, you can define the color for a value in a skeleton instrument of type "all" as default. This causes xmperf to allocate colors to the values dynamically as values are inserted during instantiation of the skeleton. Below is an example of a full value definition using this feature:

monitor.Processes.1.all.1: hosts/myhost/Proc/*/kerncpu 
monitor.Processes.1.color.1: default 
monitor.Processes.1.range.1: 0-100 
monitor.Processes.1.label.1: cmd  

Defining Default Consoles

When xmperf is started, you can have one or more consoles opened automatically. This is done by adding one line to the configuration file for each console you want to be automatically opened. An example of such a line is shown below:

monitor.Mini Monitor.default

The line states the name of the default console, in this case "Mini Monitor," followed by the keyword default. More than one such line may exist in the configuration file. One console is opened for each such line. The consoles are opened sequentially in the same order as they appear in the configuration file.

The xmperf Resource File

The X Window System resource file for xmperf defines resources you can use to enhance the appearance and behavior of xmperf and is installed as /usr/lib/X11/app-defaults/XMperf .

Resources Defining Appearance

  #  xmperf  options
  #
  *GraphFont: 
       -ibm-block-medium-r-normal--15-1
00-100-100-c-70-iso8859-1
  *background:                              grey70
  *XMMenubar.background:                    #cdb54d
  *XmCascadeButton.background:              #cdb54d
  Console*XMMenubar.background:             pink
  Console*XmCascadeButton.background:       pink
  Console*XMMenubar.foreground:             black
  Console*XmCascadeButton.foreground:       black
  *XMProcMenubar.background:                blue
  *XMProcList*XmCascadeButton.background:   blue
  *XMProcList*XmCascadeButton.foreground:   turquoise
  *XMSkelMenubar.background:                blue
  *XMSkelList*XmCascadeButton.background:   blue
  *XMSkelList*XmCascadeButton.foreground:   turquoise
  *XMHostMenubar.background:                blue
  *XMHostList*XmCascadeButton.background:   blue
  *XMHostList*XmCascadeButton.foreground:   turquoise
  *XMHelpMenubar.background:                ForestGreen
  *XMHelp*XmCascadeButton.background:       ForestGreen
  *XMHelp*XmCascadeButton.foreground:       yellow
  *XMColorWindow.background:                black
  *XMTabWindow.background:                  grey70
  *XMTabWindow.foreground:                  black
  #
  #    Dialog  Colors
  #
  *XMessage.background:    #eaeaad
  *XMessage.foreground:    black
  *XMOptions.background:   medium  aquamarine
  *XMOptions.foreground:   black
  *XMDelete.background:    blue
  *XMDelete.foreground:    yellow
  *XMExit.background:      firebrick
  *XMExit.foreground:      black
  *XMChanged.background:   yellow
  *XMChanged.foreground:   black
  *XMHelp.background:      DarkGreen
  *XMHelp.foreground:      MediumSpringGreen
  *XMStop.background:      pink
  *XMStop.foreground:      black
  *XMMsgbox.background:    DarkGreen
  *XMMsgbox.foreground:    light grey
  #
  #    Light  Colors
  #
  *XMLight.background:     #729fff
  *XMLight.foreground:     black
  #
  #    Digital  Clock  Colors
  #
  *XMSeekTime.foreground:  red
  *XMSeekTime.background:  black
  *XMPlayTime.foreground:  yellow
  *XMPlayTime.background:  black

The sample file first defines the font used for all windows. The resource name to define the font specifically for Performance Toolbox for AIX is GraphFont. If you don't define this resource, xmperf tries to get a font name from the following resources:

If none are defined, a suitable fixed-width font is used.

The next line defines the default color for all widgets with the name XMMenubar, which happens to be the menu bar in the main window and in the console windows when pulldown menus are used. The line defines the background color as a yellowish color.

The third line defines the background color for all widgets of the class XmCascadeButton to be the same yellowish color. This effectively paints all menu lines representing a cascade menu with this color.

The next four lines define the menu bar and cascading menu items as having foreground and background colors different from the defaults in consoles that are created when xmperf runs with pulldown menus. All consoles use the name Console for their top level widget.

Ending this group of resource definitions are four sets of definitions that refer to special widget names. In all cases, resources are set that override menu bar and cascade menu colors for specific windows. The first six letters of each resource name tells which windows it's related to:

XMProc
List of processes, whether used to instantiate skeleton consoles or selected from the Controls menu.
XMSkel
Dialog boxes used to instantiate skeleton consoles except when wildcard is process or remote host.
XMHost
Dialog box used to select from a list of hosts.
XMHelp
Help windows.

Finally, the background color is defined for the window you use to select colors and tiles, and both foreground and background color is set for tabulating windows.

The next group of resources contains definitions of colors for seven distinct uses of dialog windows. The first one (XMessage) sets the colors for the main window used to display messages from xmperf. The next pair of lines (XMOptions) sets colors for all dialog windows used to change the configuration of instruments and consoles. The next three line pairs are used for dialog windows that pop up when you delete something, when you exit the program, and when you are warned that something has changed and you may want to save the changes. The last three pairs of resources define fore- and background colors for help windows, for the dialog box that warns about slow resynchronizing of remote instruments, and for general informational message boxes.

The two lines shown under the group "Light Colors" define the colors to use for the widgets containing state light instruments.

Finally, in the last group of resources, four lines define colors to use in the "digital clocks" used to seek in a recording file and show the playback time, respectively.

The colors used are examples and are chosen to make it easy for you to know what type of dialog window you see. The color difference makes it less likely that you confuse one type of dialog with another.

Resources Defining Default Colors

Whenever a new value is added to an instrument, a default color is assigned to the value based upon the sequence number of the value within the instrument. The default colors are defined through resources. "Figure 3. Supplied xmperf Resource Definitions, Part 2" shows the definition of default colors for values as supplied in the sample resource file.

  #    Default  Value  Colors
  #
  *ValueColor1:   ForestGreen
  *ValueColor2:   Goldenrod
  *ValueColor3:   red
  *ValueColor4:   MediumVioletRed
  *ValueColor5:   LightSteelBlue
  *ValueColor6:   SlateBlue
  *ValueColor7:   green
  *ValueColor8:   yellow
  *ValueColor9:   BlueViolet
  *ValueColor10:  SkyBlue
  *ValueColor11:  pink
  *ValueColor12:  GreenYellow
  *ValueColor13:  SandyBrown
  *ValueColor14:  orange
  *ValueColor15:  plum
  *ValueColor16:  MediumTurquoise
  *ValueColor17:  LimeGreen
  *ValueColor18:  khaki
  *ValueColor19:  coral
  *ValueColor20:  magenta
  *ValueColor21:  cyan
  *ValueColor22:  salmon
  *ValueColor23:  sienna
  *ValueColor24:  blue

Supplied xmperf Resource Definitions, Part 2

Execution Control Resources

The example Supplied xmperf Resource Definitions, Part 3 that follows shows most of the resources that can be used to control the program execution. All resources can be specified as command line options rather than resources, except for:

ScaleLines   
DecimalPlaceLimit
MonoLegends   
TabColumnWidth   
TabWindowLines

If a true or false option is set to true with an X resource, it can not be overridden by a command line option.

  #    Execution  Options
  #
  *LegendAdjust:      false
  *LegendWidth:       14
  *TabColumnWidth:    9
  *TabWindowLines:    20
  *DecimalPlaceLimit: 10
  *GetExceptions:      false
  *MonoLegends:       false
  *PopupMenus:        false
  *DirectDraw:        false
  *Averaging:         100
  *ScaleLines:        front
  *BeVerbose:         false

Supplied xmperf Resource Definitions, Part 3

The following is a list of all execution control resources defined for xmperf:

ConfigFile
Must be followed by a file name of a configuration file (environment) to be used in this execution of xmperf. If this resource is not given, the configuration file name is assumed to be $HOME/xmperf.cf . If this file does not exist, the file is searched for as described in the "Overview of File Placement" .

This resource can alternatively be specified by the command line argument -o.

LegendAdjust
If this resource is set to true, the size of value path names to display in instruments is adjusted to what is required for the longest path name in each instrument. The length may be less than the default fixed length (or the length specified by the -w option if used or the LegendWidth resource) but never longer than that. Note that the use of this option may result in instruments with time scales that are not aligned.

For pie chart graphs, adjustment is always done, regardless of the setting of this resource.

This resource can alternatively be specified by the command line argument -a.

LegendWidth
Must be followed by a number between 8 and 32 to define the number of characters from the value path name to display in instruments. The default number of characters is 12.

This resource can alternatively be specified by the command line argument -w.

TabColumnWidth
Must be followed by a number from 5 through 15 to define the width in characters of each column displayed in a tabulating window. The default width is 9.
TabWindowLines
Must be followed by a number from 2 through 100 to define the number of lines displayed in a tabulating window. The default line count is 20. If more than 25 lines are specified, tabulating windows have a vertical scrollbar to allow you to see all the detail lines in the window.
DecimalPlaceLimit
Defines the limit that determines if a data value is displayed with or without a decimal place in tabulating windows and in the state bar graph type. If the upper range defined for the value is less than or equal to this value, a decimal place is displayed. Otherwise no decimal place is displayed. The default upper range limit is 10.
GetExceptions
If this resource is set to true, xmperf requests all its data suppliers to forward exceptions. If this resource is set to false, data-supplier hosts will not forward exceptions to this invocation of xmperf.

This resource can alternatively be specified by the -x command line argument.

MonoLegends
If this resource is set to true, the text describing values in instruments with a primary style of line, skyline, area, bar, state bar, and pie is drawn in the instrument's foreground color. If this resource is set to false, the text is drawn in the value's color.

This resource can not be specified by a command line argument.

PopupMenus
If this resource is set to true, popup menus are used rather than the pulldown menus. As described in "The xmperf User Interface" , the overall menu structure may be based upon pulldown menus (which is the default) or popup menus as activated by setting this resource true. Pulldown menus may be easier to understand for occasional users, while popup menus generally provide a faster but less intuitive interface.

This resource can alternatively be specified by the command line argument -u.

DirectDraw
Normally, xmperf first draws graphical output to a pixmap and then, when all changes are done, moves the pixmap to the display. Generally, with a locally attached color display, performance is better when graphical output is redrawn from pixmaps, which is why this is the default. Also, a flaw in some levels of X Window System can be bypassed when this option is in effect. For monochrome displays and X stations, you may want to set this resource to true, which causes xmperf to draw graphical output directly to the display rather than always redrawing from a pixmap.

This resource can alternatively be specified by the command line argument -z.

Averaging
If this resource is set to a value greater than 25 and smaller than 100, averaging is activated. Averaging causes an "averaging" or "weighting" of all observations for state graphs before they are plotted. The number assigned to the resource is taken as the "weight percentage" to use when averaging the values plotted in state graphs. The formula used to calculate the average is:
val = new * weight/100 + old * 
(100-weight) / 100

where:

val
Is the value used to plot.
new
Is the latest observation value.
old
Is the val calculated for the previous observation.
weight
Is the weight specified by the resource.

If a number outside the valid range is specified, averaging is not activated. This resource can alternatively be specified by the command line argument -p.

The weight is also used to calculate the weighted average line in tabulating windows.

ScaleLines
If this resource has a value of back or front, all recording graphs will have a horizontal, stippled line drawn at the 50% mark and the 100% mark. If the resource value is back, the lines are drawn before the values are plotted so that the actual graph is overlaying the scale lines. If the resource value is front, the lines are superimposed on top of the plotted values and will always be visible.

The default value for this resource is back. If the resource is set to any value but the two valid ones, scale lines are not drawn. The resource does not have corresponding command line arguments.

BeVerbose
If this resource is set true, configuration file lines are printed to the log file as they are processed. Any errors detected for a line are printed immediately below the line. This option is intended as a help to find and correct errors in the configuration file. Use this option if you don't understand why a line in your configuration file does not have the expected effect.

This resource can alternatively be specified by the command line argument -v.

The azizo Resource File

The X Window System resource file for azizo defines resources you can use to enhance the appearance and behavior of azizo and is installed as:

/usr/lib/X11/app-defaults/Azizo.
#    General  azizo  options
#
*GraphFont:        -ibm-block-medium-r-normal--15-100-100-100-c-70-iso8859-1
*background:              grey70
*MetricHeight:            40
*MetricWidth:             600
*MetricLineDouble:        False
*MetricLinePlot:          False
*MainGraphCount:          16
*GraphWindowWidth:        862
*OnlyMetricColorIndex:    6
*FirstMetricColorIndex:   3
*SecondMetricColorIndex:  7
#
#        Major    screen    colors
#
*AZMain.background:                       grey70
*AZMetrics.background:                    grey70
MainGraph*XmDrawingArea.background:       black
MainGraph*XmLabel.background:             black
#
#        Dialog    Colors
#
*XMHelpMenubar.background:                ForestGreen
*XMHelp*XmCascadeButton.background:       ForestGreen
*XMHelp*XmCascadeButton.foreground:       yellow
*XMHelp.background:                       DarkGreen
*XMHelp.foreground:                       MediumSpringGreen
*InfoWindow.background:                   grey70
*AZAction.background:                     grey70
*AZMessage.background:                    grey70
*AZMessage.foreground:                    black
*ExitWindow.background:                   red
*ExitWindow.foreground:                   white
*PromptWindow.background:                 LightSteelBlue
*PromptWindow.foreground:                 black
*QuestionWindow.background:               goldenrod
*QuestionWindow.foreground:               black
*XMMsgbox.background:                     medium aquamarine
*XMMsgbox.foreground:                     black

The sample file first defines the default background color for all windows whenever this color is not overridden by some later resource setting. It then sets the font used for all windows. The resource name to define the font specifically is GraphFont. If you don't define this resource, azizo tries to get a font name from the following resources:

If none are defined, a suitable, fixed-pitch font is used. Other X resources are, in alphabetical order:

AZAction
The name of the widgets used to create action buttons. Use to set background color of the buttons.
AZMain
The name of the base widgets used to create the main window. By referencing the AZMain widget name, you can set the foreground and background color of the main window.
AZMessage
The name of the widget used to create the message window shown below the metrics selection window. Use to set the colors of the message window.
AZMetrics
The name of all widgets used to create the metrics selection window. By referencing the AZMetrics widget name, you can set the foreground and background color of the metrics selection window and the metrics graphs. The color you assign for foreground becomes the default color for drawing the metrics graphs. It can be overridden by other X resources as explained below. To set the background color of the metrics selection window, use *AZMetrics.background as the resource name.
BrightenFactor
Default brighten factor to use in the Print Box. Default is 100; permitted range is 0 - 200.
ExitWindow
Can be used to give the exit dialog box a different color to make it stand out from other dialog boxes.
FirstMetricColorIndex
This resource specifies the index into a table of defined ValueColor1 through ValueColor24 resources. The color selected by the index is used to draw the maximum value line of metrics in the metrics selection window when both maximum and minimum values are drawn. Default is foreground color of the metrics selection window as set by the AZMetrics resource.
GraphWindowWidth
The initial width of main graph windows. This width is the width of the window itself, not the main graph area alone. Default is 862 pixels.
InfoWindow
The name of all widgets used to create information windows. By referencing the InfoWindow widget name, you can set the foreground and background color of all information windows.
HorizontalMargin
The default horizontal margin for the Print Box. Default is 0.5 inch.
MainGraph
The name of all the widgets used to create main graphs is MainGraph. By assigning color values to the X resources defined as MainGraph*XmLabel.background and MainGraph*XmLabel.foreground, the appearance of the metrics label part can be changed. Similarly, the colors used in the graph part can be changed with the resources MainGraph*XmDrawingArea.background and MainGraph*XmDrawingArea.foreground. The supplied X resource file for azizo shows the setting of the background color for both parts of the main graph window.
MainGraphCount
Defines the maximum number of metrics that will be part of the top level main graph after a new recording file has been read in. Defaults to 16 metrics.
MainGraphHeight
Sets the initial height (in pixels) of all main graphs. Default is 300 pixels; permitted range is 50 - 1,000 pixels.
MainGraphWidth
Sets the initial width (in pixels) of all main graphs except the top level main graph. Default is 600 pixels; permitted range is 100 - 1,200 pixels. Note that main graphs are never scaled horizontally. If you increase the width of the main graph window beyond what is required to show the full graph width, empty space appears to the right of the graph. If you reduce the width of the main graph window to less than what is required to display the main graph, then a scrollbar is added to allow horizontal scrolling of the graph area.
MainPlotStyle
Sets the default plotting style for metrics in main graphs. Defaults to "average." Permitted values are: "maximum," "minimum," "both," and "average."
MetricHeight
Sets the height in pixels of individual metrics graphs in the metrics selection window. Default is 40 pixels; permitted range is 10 - 200 pixels.
MetricLegendWidth
Sets the width of the area at the left side of a metrics graph that is used to display the metric path name. Default is 20 characters; permitted range is 8 - 32 characters.
MetricLineDouble
This resource can be set to either true or false. It is ignored if the resource MetricLinePlot is set to false. If both these resources are true, the default way of drawing individual metrics graphs is with two lines: one for the maximum and one for the minimum values. If this resource is set to false while MetricLinePlot is set to true, only the maximum values are drawn.
MetricLinePlot
This resource can be set to either true or false. If this resource and the resource MetricLineDouble are both set to true, the default way of drawing individual metrics graphs is with two lines: one for the maximum and one for the minimum values. If this resource is set to true while MetricLineDouble is set to false, only the maximum values are drawn. If this resource is set to false, individual metrics graphs are drawn in the "Bar, Max-to-Min" style as a series of vertical lines, each one connecting the maximum and minimum value in an interval.
MetricWidth
This resource sets the width of the individual metrics graphs in the metrics selection window. It also sets the width of the graph area of the top level main graph. The default is 600 pixels. Specify in the range 100 through 1,000.
MonoLegends
If this resource is set true, all labels in main graphs are shown in the foreground color of the label part of the main graph. Probably not very useful since it is then not possible to see which line in the graph corresponds to the label.
OnlyMetricColorIndex
This resource is used to select the foreground color of a metrics graph when the style is not "Line, Max & Min." That is, when only one line is drawn in each metrics graph. The resource defines an index into a table of defined ValueColor1 through ValueColor24 resources to use for main graphs. Default is the foreground color of the metrics selection window as set by the AZMetrics resource.
PaperHeight
Default paper height to use in the Print Box. Default is 11 inches.
PaperWidth
Default paper width to use in the Print Box. Default is 8.5 inches.
PrintCommand
The default print command to use for all print operations. Default is lp -d.
PromptWindow
Can be used to give the prompt dialog boxes different foreground and background color to make them stand out from other dialog boxes. Prompt dialogs are those that request you to supply input before an action is performed.
QuestionWindow
Can be used to give the question dialog boxes different foreground and background color to make them stand out from other dialog boxes. Question dialogs are those that ask you to confirm or reject an action.
SecondMetricColorIndex
This resource specifies the index into a table of defined ValueColor1 through ValueColor24 resources. The color selected by the index is used to draw the minimum value line of metrics in the metrics selection window when both maximum and minimum values are drawn. Default is foreground color of the metrics selection window as set by the AZMetrics resource.
VerticalMargin
The default Vertical margin for the Print Box. Default is 0.5 inch.
XMHelp
Used to set the colors of help screens and their menus. See the figure Supplied azizo Resource Definitions for examples.
XMHelpMenubar
Used to set the colors of help screen menu bars. See the figure Supplied azizo Resource Definitions a href="XHDazresf" rel="pagenum"> for an example.
AZIcons
The name of the widgets used to create the image of icons that indicate that a drop action is permitted. Use to set color.
XMMsgbox
The name of the widgets used to create message windows that inform the user of some condition. Use to set colors.

Simple Help File Format

Several of the X Window System based programs in the Performance Toolbox for AIX share a common help file layout and have the same help function linked with the executables. These programs are xmperf, exmon, azizo, and 3dplay.

The help function identifies a help screen from a string of characters, called the help ID. Only if a help text with this help ID is present in the help file for the program, can help be given. If no help text is found, a message box will inform the user of this.

When help is requested by a user, the help function is called with a help ID that depends on the way help is requested. The different ways to request help and how the help ID is retrieved for each of those is explained below:

Help requested for xmperf console
The help ID is the name of the console. If the console is an instantiated skeleton console, the help ID is assumed to be the name of the skeleton console, rather than the instance of it.
Help requested for xmperf tools dialog
The help ID is the string of characters that identify the tool as shown in the window frame of the tools dialog window.
Help requested from other dialog box
The help ID is hard-coded for the dialog box. In most cases, the help ID is identical to the text shown in the window frame of the dialog window.
Help requested from menu
The help ID is hard-coded for the menu item.
Help requested from help index
The help ID is the text shown in the selected help index line.
Help requested for azizo action or object
The help ID is hard coded for the action or object.

When a program that uses the simple help file starts, it looks in your home directory for a file with the same name as the program but with a file name extension of .hlp. If found, that file is used. If the file does not exist in your home directory, xmperf attempts to find it as described in Overview of File Placement .

The format of a definition of a help screen is identical for all types of help texts. "Simple Help File Format" is an example of a help text for an xmperf console:

$help: Mini Monitor
This console contains a single state instrument. It is
the default console and is intended to be permanently 
open as a monitor of important activity on the local system.
All values shown in the console are lively to experience
shorter or longer peaks during normal system operation. 

The keyword $help: must appear exactly as shown (including the dollar sign and the colon) and must begin in column one. It must be followed by at least one byte of white space and the help ID.

Following the line that defines the help ID, you specify the help text exactly as you want it to appear in the help screen. When the text is displayed by the help function, the window is sized to match the line length and the number of lines in the help screen, up to 25 lines. If the help window has more than 25 lines, the scroll bar in the help window must be used to scroll the help text up and down.

The help ID (shown as "Mini Monitor" in the figure) identifies the help text and binds it to the situation where it is displayed. If the name matches a console name or tool name as defined in the configuration file, the help text is bound to the console or tool; otherwise the help text is assumed to be a general help text, possibly associated with a help button or a help menu item.

Each of the p rograms that use the help function has a set of hard coded help IDs. These are listed in the following sections:

Predefined help IDs for xmperf

Change Value 
Color Selection 
Erase Recording File
Help on Help
History, number of observations 
Host Selection 
Interval, seconds 
Main Window 
Name of New Console 
Primary Style and Stacking 
Process Controls 
Recording file exists 
Remote Process List 
Select Value 
Shift, pixels per observation 
Slow Resync 
Space between bars 
Wildcard Selection

Predefined help IDs for exmon

Add Hosts 
Command Execution
Delete Hosts 
Delete Log 
Exception Logs 
Exit exmon 
Files Changed
Help on Help 
Read Log

Predefined help IDs for azizo

Changing View Options 
Config Icon 
Configuration Exists 
Configuration File 
Configuration Line 
Delete Configuration 
Exit azizo 
Exit Icon 
Filter Icon 
Help Icon 
Help on Help 
Info Icon 
Information Window 
Local Files Icon 
Main Graph 
Metrics Graph 
Metrics Graph List 
Metric Label in Main Graph
Pit Icon
Print Box 
Print Icon 
Replace Configuration 
Report Box 
Rescaling 
Scale Icon 
Select Recording File 
View Icon 
Writing Configuration 
Writing Filtered Recording 
Zoom-in

Predefined help IDs for 3dplay

Erase Annotation File
Erase Recording File
Help on Help
Select 3dmon Recording File

[ Previous | Next | Contents | Glossary | Search ]