Chapter 9 Manipulating Experiments
This chapter describes the utilities which are available for use with the Collector and Performance Analyzer.
This chapter covers the following topics:
Manipulating Experiments
Experiments are stored in a directory that is created by the Collector. To manipulate experiments, you can use the usual UNIX® commands cp, mv and rm and apply them to the directory. You cannot do so for experiments from releases earlier than Forte Developer 7 (SunTM ONE Studio 7, Enterprise Edition for Solaris). Three utilities which behave like the UNIX commands have been provided to copy, move and delete experiments. These utilities are er_cp(1), er_mv(1) and er_rm(1), and are described below.
The data in the experiment includes archive files for each of the load objects used by your program. These archive files contain the absolute path of the load object and the date on which it was last modified. This information is not changed when you move or copy an experiment.
Copying Experiments With the er_cp Utility
Two forms of the er_cp command exist:
er_cp [-V] experiment1 experiment2 er_cp [-V] experiment-list directory |
The first form of the er_cp command copies experiment1 to experiment2. If experiment2 exists, er_cp exits with an error message. The second form copies a blank-separated list of experiments to a directory. If the directory already contains an experiment with the same name as one of the experiments being copied the er_mv utility exits with an error message. The -V option prints the version of the er_cp utility. This command does not copy experiments created with software releases earlier than the Forte Developer 7 release.
Moving Experiments With the er_mv Utility
Two forms of the er_mv command exist:
er_mv [-V] experiment1 experiment2 er_mv [-V] experiment-list directory |
The first form of the er_mv command moves experiment1 to experiment2. If experiment2 exists the er_mv utility exits with an error message. The second form moves a blank-separated list of experiments to a directory. If the directory already contains an experiment with the same name as one of the experiments being moved, the er_mv utility exits with an error message. The -V option prints the version of the er_mv utility. This command does not move experiments created with software releases earlier than the Forte Developer 7 release.
Deleting Experiments With the er_rm Utility
Removes a list of experiments or experiment groups. When experiment groups are removed, each experiment in the group is removed then the group file is removed.
The syntax of the er_rm command is as follows:
er_rm [-f] [-V] experiment-list |
The -f option suppresses error messages and ensures successful completion, whether or not the experiments are found. The -V option prints the version of the er_rm utility. This command removes experiments created with software releases earlier than the Forte Developer 7 release.
Other Utilities
Some other utilities should not need to be used in normal circumstances. They are documented here for completeness, with a description of the circumstances in which it might be necessary to use them.
The er_archive Utility
The syntax of the er_archive command is as follows.
er_archive [–nqAF] experiment er_archive -V |
The er_archive utility is automatically run when an experiment completes normally, or when the Performance Analyzer or er_print utility is started on an experiment. It reads the list of shared objects referenced in the experiment, and constructs an archive file for each. Each output file is named with a suffix of .archive, and contains function and module mappings for the shared object.
If the target program terminates abnormally, the er_archive utility might not be run by the Collector. If you want to examine the experiment from an abnormally-terminated run on a different machine from the one on which it was recorded, you must run the er_archive utility on the experiment, on the machine on which the data was recorded. To ensure that the load objects are available on the machine to which the experiment is copied, use the -A option.
An archive file is generated for all shared objects referred to in the experiment. These archives contain the addresses, sizes and names of each object file and each function in the load object, as well as the absolute path of the load object and a time stamp for its last modification.
If the shared object cannot be found when the er_archive utility is run, or if it has a time stamp differing from that recorded in the experiment, or if the er_archive utility is run on a different machine from that on which the experiment was recorded, the archive file contains a warning. Warnings are also written to stderr whenever the er_archive utility is run manually (without the -q flag).
The following sections describe the options accepted by the er_archive utility.
-n
Archive the named experiment only, not any of its descendants.
–q
Do not write any warnings to stderr. Warnings are incorporated into the archive file, and shown in the Performance Analyzer or output from the er_print utility.
–A
Request writing of all load objects into the experiment. This argument can be used to generate experiments that are more readily copied to a machine other than the one on which the experiment was recorded.
–F
Force writing or rewriting of archive files. This argument can be used to run er_archive by hand, to rewrite files that had warnings.
–V
Write version number information for the er_archive utility and exit.
The er_export Utility
The syntax of the er_export command is as follows.
er_export [–V] experiment |
The er_export utility converts the raw data in an experiment into ASCII text. The format and the content of the file are subject to change, and should not be relied on for any use. This utility is intended to be used only when the Performance Analyzer cannot read an experiment; the output allows the tool developers to understand the raw data and analyze the failure. The–V option prints version number information.
- © 2010, Oracle Corporation and/or its affiliates