OpenSS Command Definitions

Table of Contents

• OpenSS Command Definitions
  • Table of Contents
  • Experiment Building Block Commands
    • expAttach
    • expClose
    • expCreate
    • expDetach  
    • expDisable
    • expEnable
    • expFocus
    • expGo
    • expPause
    • expRestore
    • expSave
    • expSetParam
  • Experiment Information Commands
    • expStatus
    • expView
  • Low Level Information Commands
    • list -v breaks
    • list -v expid
    • list -v hosts
    • list -v obj
    • list -v pids
    • list -v metrics
    • list -v params
    • list -v ranks
    • list -v src
    • list -v status
    • list -v threads
    • list -v exptypes
    • list -v views
  • Session Commands
    • clearBreak
    • exit
    • help
    • history
    • log
    • openGui
    • playBack
    • record
    • setBreak
    • wait

Experiment Building Block Commands

expAttach

- Attach applications or collectors to an experiment.
• The attached applications will not execute until an expGo command is issued.
- If there is no <expId_spec> provided, information is attached to the focused experiment.
- If the -v mpi option is selected, all the threads that are part of a running application will be included in the experiment.
- If the -v mpi option is not present, only those threads that are explicitly listed in the <target_list> will be included in the experiment.
- The <target_list> is used to restrict the knowledge of the experiment or data collection to certain portions of an appliaction.
- It is ambiguous to use both the -f and -p options.
• The -f option implies that an executable is to be loaded into the OpenSS tool from a file.
• The use of -p option implies that the OpenSS tool is to attach to a program that is already executing.
- If <target_list> is provided without <expType_list>, those applications are attached to all the <expType>s that are already attached of the experiment.
- If <expType_list> is provided without <target_list>, the specified data collectors are used to instrument all the executable routines that are already attached to the indicated experiment.
- If both <target_list> and <expType_list> are provided, only those portions of the application in the <target_list> are linked to the specified collectors in <expType_list>.
- If neither <target_list> nor <expType_list> is provided, the command does nothing.

expAttach [ -v mpi ] [ <expId_spec> ] [ <target_list> ] [ <expType_list> ]

expClose

- Close/Terminate the experiment specified by <expId_spec>.
• The OpenSS tool is NOT terminated. Use exit to terminate the session.
• All data collectors attached to the experiment are removed from the attached applications.
• All attached applications are removed from the experiment.
• If -v kill is not provided, attached applications will continue executing.
• If -v kill is provided, attached applications will be terminated.
• The database file that was used to save information about the applications and the collected data, is deleted if it is a temporary file, or closed if it is a user defined file. Use expSave for saving information.
- If there is no <expId_spec> provided, the focused experiment will be closed.
- Because important information may accidently be lost, this command should only be issued when the user is certain that more performance measurements are not needed and that the collected data measurements will be saved if there is any chance that the user will want to take another look at the results.
- Use of -v all will cause all defined experiments to be deleted.

expClose [ -v kill ] [ -v all || <expId_spec> ]

expCreate

- Start the process of defining an experiment:
• define a new experiment identifier,
• set the current focus to the new identifier and
• return the experiment identification identifier.
• The experiment will not execute until an expGo command is issued.
- If the -v mpi option is selected, all the threads that are part of a running application will be included in the experiment.
- If the -v mpi option is not present, only those threads that are explicitly listed in the <target_list> will be included in the experiment.
-The <target_list> will associate the specified executable with the experiment being defined.
- The experiment type argument, <expType_list>, can be used to specify the types of data that will be collected during the experiment.
- Missing arguments can be supplied later with the expAttach command.
- An expCreate command with no arguments will still return a new <expId> and will set the focus.

<expId> = expCreate [ -v mpi ] [ <target_list> ] [ <expType_list> ]

expDetach

 

- Detach applications from collectors for an experiment.
• The remaining applications will not execute until an expGo command is issued.
• The experiment retains knowledge of both the applications and the collectors and they can be referenced on later commands.
• All previously collected data samples will be retained.
• No new data, of the specified type, will be collected for the specified application.
- If there is no <expId_spec> provided, the focused experiment is used.
- If <target_list> is provided without <expType_list>, all collectors are detached for those applications.
- The use of the "<target_list>" option allows control over the parts of an executable program that will no longer generate performance data.
• The absence of any "-h <hostname>" specification will cause all the hosts in the specifed experiment to stop measuring performance.
• The default cluster contains only localhost and can be specified by using -h localhost.
• Use of the -f option is not supported.
• Use of the -p option will result in only the Threads associated with that Pid to stop measuring performance.
• Use of the -t option will result in only that specific Thread o stop measuring performance.
- If both <target_list> and <expType_list> are provided, only the specified collectores in <expType_list> are detached from just those applications described in <target_list>.
- If <expType_list> is provided without <target_list>, the specified data collectors are detached from all the executable routines that are ttached to the indicated experiment.
- If neither <target_list> nor <expType_list> is provided, the command does nothing.

expDetach [ <expId_spec> ] [ <target_list> ] [ <expType_list> ]

expDisable

- Turn off data collection.
• The experiment remains defined.
• Data collection is "turned off" and no new information is saved.
• Instrumentation is disabled but may not be removed from the application.
• Previously collected data is still available and can be viewed or saved.
• The attached applications will not continue executing until an expGo command is issued.
- See related commands:
• expEnable can be used to restart data collection.
• expSave can be used to save previously collected data.
• expClose can be used to destroy the experiment and free all data space used to save the collected data.
- -v all will result in data collection being stopped for all defined experiments.
- If this command is issued with no arguments, data collection is stopped for the focused experiment.

expDisable [ -v all || <expId_spec> ]

expEnable

- Turn on any instrumentation that was turned off with an expDisable command.
• Existing instrumentation is enabled.
• Data collection is "turned on" and new information will be saved.
• New information will be merged with any previously collected data.
• The attached applications will not continue executing until an expGo command is issued.
- -v all will result in data collection being restarted for all defined experiments.
- If this command is issued with no arguments, data collection for the focused experiment is restarted.

expEnable [ -v all || <expId_spec> ]

expFocus

- Make the given experiment id the current, focused experiment.
- In many commands <expId_spec> is optional. When omitted, the currently "focused" experiment is used.
- If no argument is present on this command, return the focused experiment.
- If the <expId_spec> argument has an experiment id of zero (0), then clear the experiment focus.
• A command that uses an experiment id of zero is illegal and will produce a fatal error.
- This command does not change the execution state of an experiment.

<expId> = expFocus [ <expId_spec> ]

expGo

- Run the experiment and collect performance data.
- If the experiment has already begun execution, this command causes execution to continue from where it was interrupted. - The experiment will continue to run until either
• the application terminates, or
• the application executes a programmed halt, or
• the user issues another exp... command that refers to this experiment Id. or
• the OpenSS tool terminates due to an exit command, an external interrupt, or abnormal, internal event.
- Except when executed in batch mode, the execution of the application and the collection of performance data does not, automatically, prevent other commands from being issued
• A following command that depends on the result of this experiment may not be able to execute and may block further commands from being issued.
• Independent commands may be issued and completed before this experiment completes.
• The status of any experiment can be determined through the listStatus command.
• Depending on the type of data collection that is taking place, it may be possible to view the results before the application completes.
- The absence of the <expId_spec> and -v all will result in only the focused experiment being run.
- The use of <expId_spec> will result in only that experiment being run.
- The use of -v all will result in every defined experiment being run.

expGo [ -v all || <expId_spec> ]

expPause

- Temporarily halt the experiment identified by the input experiment id.

• The experiment will remain suspended until an expGo is issued or until the performance tool is exited, at which time all the instrumentation is removed from the experiment and the program is allowed to continue running.
- If <expId_spec> is not provided, the focused experiment is used.
- If -v all is present, every defined experiment is halted.

expPause [ -v all || <expId_spec> ]

expRestore

- Restore an experiment's definition and previously saved data from a database that was saved with an expSave command.

• A new experiment is created and intitialize with this information.
• This command also sets the focus to the new experiment's Identifier.
• The new experiment will be in the same state as that established with the expDisable command.
• If the original applications are still running, the user can reconnect to them, and reinsert instrumentation into them, through the use of the expEnable command. Doing this will interrupt the executing application and an expGo command will be required before the application continues and new data samples can be collected.
• Previously collected data can be looked at with the expView command without reconnecting to the original applications.
• If an expGo command is issued, new data samples will be placed into the database specified by <file_spec>. A different database can be specified with the expSave command.

<expId> = expRestore <file_spec>

expSave

- Save the experiment information for further analysis.

• For each experiment, information about the executable programs that are instrumented, information about the instrumentation that is used and any performance data that is collected are saved in a database.
• The database is created by the OpenSS tool in a temporary location and will be deleted when an expClose command is issued for the experiment, or when an exit command is issued that terminates the OpenSS tool.
• The entire database can be saved with the expSave command and can be reloaded into the OpenSS tool with the expRestore command.
• The database is in a special format that supports the opertaions that the OpenSS tool must perform.
- Without -v copy
• If the original, temporary database file is still in use, it is copied to the specified file name and the OpenSS tool will use the new file to collect any new information about the experiment. When the experiment completes, this database will be retained.
• If a previous expSave command has caused the experiment's information to be directed to a user defined database
• The contents of the previous database - without any of the data samples - is copied to the new database.
• The previous database is closed.
• The new database is used by the OpenSS tool to collect any new information that is added to or collected for, the experiment.
- With -v copy, the given location receives a copy of the current state of the database.
• The current contents of the database is duplicated and saved to the given location.
• No new information will be added to the given location.
• New information will be added to the original database.
- This command does not change the execution state of the experiment, although it may temporarily suspend execution while the command is being executed.

expSave [ -v copy ] [ <expId_spec> ] <file_spec>

expSetParam

- Change the value an experiment's argument.
- <expParam> will be unique within the experiment.
- The parameter names can be used by other experiments.
- This command does not change the execution state of the experiment, although it may temporarily suspend execution while the command is being executed.

expSetParam [ <expId_spec> ] <expParam> = <expParamValue> [ , <expParam> = <expParamValue> ]+

Experiment Information Commands

expStatus

- Report the current state of user defined experiments.

• The absence of any option will result in information being reported for the focused experiment.
• The use of <expId_spec> will result in information being reported for the specified experiment.
• The use of -v all will result in information being reported for all the known experiments.

expStatus [ -v all || <expId_spec> ]

expView

- Display the performance data that has been collected for an experiment.
- If this command is issued with no <expId_spec>, the focused experiment is used.
- If this command is issued with no <viewType>, the specified experiment is examined and an attempt is made to find a <viewType> with the same name as the <expType> used in the experiment. If there is no matching <viewType>, or if there is more than one <expType> used in the experiment, a generic view is requested that will display all the metrics that were generated for the experiment.
- This command does not change the execution state of the experiment, although the nature of the requested data may require that the experiment complete execution before the information can be provided.
- The use of the "<expMetric_list>" option allows control over the data that is included in the report.
• Only the metrics specified in the list will be included in the report.
• The meterics will be reported in the order that they occur in the list.
• The report will be sorted in descending order of the first metric in the list.
- The use of the "<target_list>" option acts like a filter on the output.
• The absence of any "-h <hostname>" specification will cause all the information available for all hosts in the specifed experiment to be included.
• The default cluster contains only localhost and can be specified by using -h localhost.
• Use of the -f option is not supported.
• Use of the -p option will result in only the Threads associated with that Pid being included for the selected hosts.
• Use of the -t option will result in only that specific Thread being included, if it exists on the selected hosts.

expView [ <expId_spec> ] [ <viewType> ] [ -m <expMetric_list> ] [ <target_list> ]

Low Level Information Commands

listBreaks

- List the breakpoints that have been set by the user.

• The absence of any option will cause all the breakpoints for the focused experiment to be listed.
• The use of <expId_spec> will cause all the breakpoints for the specified experiment to be listed.
• The use of -v all will cause all the known breakpoints, for all of the experiments defined by the user, to be listed.

<ListOf_breakId> = list -v breaks [ <expId_spec> ]
<ListOf_breakId> = list -v breaks , all [ <expId_spec> ]

listExp

- List the experiments that have been defined.

<listOf_expId> = list -v expid

listHosts

- Lists the hosts that define the specified cluster.

• The absence of any options will cause all the hosts that have been included in the focused experiment to be listed.
• The <expId_spec> option will cause all the hosts that have been included in the selected experiment to be listed.

<ListOf_hostname> = list -v hosts [ <expId_spec> ]

listObj

- List the objects of the applications that are part of the specified experiment.

• If <expId_spec> is not provided, the focused experiment is used.
- The listing can be restricted with the use of a <target> specification.
- Any component described in the <target> specification must be part of the selected experiment.
- If <target> is not provided, information will be provided for all portions of all applications that are attached to the experiment.

<ListOf_filename> = list -v obj [ <expId_spec> ] [ <target> ]

listPids

- List running processes associated with a specific experiment and, optionally, on a specific machine.
• If no options are supplied, the Pids that are referenced in the focused experiment are listed.
• If the "<expId_spec>" option is supplied, all the Pids that are part of the specified experiment are listed.
- The use of the "<host_list_spec>" option acts like a filter on the output.
• The absence of any "-h <hostname>" specification will cause all pids in the specified experiment to be included.
• The default cluster contains only localhost and can be specified by using -h localhost.

<ListOf_pidname> = list -v pids [ <expId_spec> ] [ <host_list_spec> ]

listMetrics

- Retrieve the metrics that are associated with a particular <viewType> or list of <viewType>s.
• If no options are selected, metrics for only the data collectors that are part of the focused experiment will be listed.
• The use of <expId_spec> will cause the metrics that are associated with the set of data collectors that are part of the specified experiment to be listed.
• The use of -v all will cause all the metrics for all available collectors to be listed.
• The use of the "<expType_list>" option will result in a listing of only those metrics associated with the specific data collectors in the list.

<ListOf_expMetric> = list -v metrics [ <expId_spec> || <expType_list> ]
<ListOf_expMetric> = list -v metrics , all [ <expId_spec> || <expType_list> ]

listParams

- Retrieve the parameters that are associated with a particular <expType> or set of <expType>s.
• If no options are selected, parameters for only the data collectors that are part of the focused experiment will be listed.
• The use of <expId_spec> will cause the parameters that are associated with the set of data collectors that are part of the specified experiment to be listed.
• The use of -v all will cause all the parameters for all available collectors to be listed.
• The use of the "<expType>" option will result in a listing of only those parameters associated with that specific data collector.

<ListOf_expParam> = list -v params [ <expId_spec> || <expType_list> ]
<ListOf_expParam> = list -v params , all [ <expId_spec> || <expType_list> ]

listRanks

- List the mpi ranks associated with a specific experiment, a specific Pid or on a specific machine.
• If no options are supplied, all the Ranks that are referenced in the focused experiment are listed.
• If the "<expId_spec>" option is supplied, all the Ranks that are part of the specified experiment are listed.
- The use of the "<target>" option acts like a filter on the output.
• The absence of any "-h <hostname>" specification will cause all Ranks in the specified experiment to be included.
• The default cluster contains only localhost and can be specified by using -h localhost.
• Use of the -f option is not supported.
• Use of the -p option will result in only the Ranks associated with that Pid being included for the selected hosts.
• Use of the -r option will result in only that specific Rank being included, if it exists on the selected hosts.

<ListOf_rankname> = list -v ranks [ <expId_spec> ] [ <target> ]

listSrc

- List the source filenames of the modules that are part of the specified experiment.
- If <expId_spec> is not provided, the focused experiment is used.
- The listing can be restricted with the use of a <target> specification.
- Any component described in the <target> specification must be part of the selected experiment.
- <file_list_spec> can be used to provide a list of object modules that will be searched for relevant source files.
- If <target> is not provided, information will be provided for all portions of all applications that are attached to the experiment.

<ListOf_filename> = list -v src [ <expId_spec> ] [ <target> ]

listStatus

- List the status of experiments.

• If no option is selected, return the status of the focused experiment.
• The use of <expId_spec> will cause the status of the specified experiment to be returned.
• The use of -v all will cause the status of all the defined experiments to be returned.

<ListOf_statusType> = list -v status [ <expId_spec> ]

listThreads

- List the Threads associated with a specific experiment, a specific Pid or on a specific machine.
• If no options are supplied, the Threads that are referenced in the focused experiment are listed.
• If the "<expId_spec>" option is supplied, all the Threads that are part of the specified experiment are listed.
- The use of the "<target>" option acts like a filter on the output.
• The absence of any "-h <hostname>" specification will cause all Threads in the specified experiment to be included.
• The default cluster contains only localhost and can be specified by using -h localhost.
• Use of the -f option is not supported.
• Use of the -p option will result in only the Threads associated with that Pid being included for the selected hosts.
• Use of the -t option will result in only that specific Thread being included, if it exists on the selected hosts.

<ListOf_threadname> = list -v threads [ <expId_spec> ] [ <target> ]

listTypes

- List the available performance measurement utilities that can be used to collect data in an experiment.

• If no option is selected, list the utilities that are attached to the focused experiment.
• The use of <expId_spec> will cause the utilities that are attached to the specified experiment to be listed.
• The use of -v all will cause all the possible performance measurement utilities that can be used in experiments to be listed.

<ListOf_expType> = list -v exptypes [ <expId_spec> ]
<ListOf_expType> = list -v exptypes , all [ <expId_spec> ]

listViews

- Retrieve the views that are available for a particular <expType> or list of <expType>s.
• If no options are selected, the reports for only the data collectors that are part of the focused experiment will be listed.
• The use of <expId_spec> will cause the the reports that are associated with the set of data collectors that are part of the specified experiment to be listed.
• The use of -v all will cause all the the reports for all available collectors to be listed.
• The use of the "<expType_list>" option will result in a listing of only those reports associated with the specific data collectors in the list.

<ListOf_viewType> = list -v views [<expId_spec> || <expType_list> ]
<ListOf_viewType> = list -v views , all [ <expId_spec> || <expType_list> ]

Session Commands

clearBreak

- Remove a breakpoint.
- This command does not change the execution state of an experiment, although it may be temporarily suspended during execution of the command.

clearBreak <breakId>

exit

- Terminate all experiments and the session.
• Suspend execution of all executables
• Suspend data collection.
• Remove instrumentation from all applications.
• Release all applications from control of the OpenSS tool
• Allow all applications to continue executing.
• Close all database files.
• Delete all temporary database files.
• Close the GUI and Command windows.
• Terminate execution of the OpenSS tool.


exit

help

- Request information about a topic.
- The detail of information can be controlled with the optional <verbosity_spec>.

<string> = help [ <verbosity_list_spec> ] [ <string> ]

history

- Print a list of previously executed commands.
- If the optional integer is provided, the command will list that number of previous commands.
- If no integer is provided, the command will list a default number of previous commands.

<string> = history [ <int> ]

log

- Begin echoing executed commands and their results to a file.
- Stop echoing if no file is specified on a log command.
- This is primarly intended to be an internal debug aid for the OpenSS tool developer since the generated files can quickly become huge.

log [ <file_spec> ]

openGui

- Open the Graphical User Interface, if it is not already open.

openGui

playBack

- Read and execute commands from a file.

playBack <file_spec>

record

- Begin echoing executed commands to a file.
• Recording is preformed relative to the input source that issues this command.
• This design causes commands issued by the GUI to be recorded seperately from commands issued by the Command window.
- Commands read from a file specified on a succeeding playBack command will not be echoed.
- Stop echoing if no file is specified on a record command.
- Stop echoing if the end of the input file containing the original record command is encountered.

record [ <file_spec> ]

setBreak

- Enter a breakpoint, which will halt the application when reached.
- If <expId_spec> is not provided, the focused experiment is used.
- The break location is specified through the combination of the <target> and <address_description> arguments.
- The break location must be a location in the specified experiment.
- If <target> is not provided, the <address_description> must be valid on every host and executable attached to the experiment.

<breakId> = setBreak [ <expId_spec> ] [ <target> ] <address_description>

wait

- This command will cause openss to wait for an event before processing any more commands.
- If -v terminate is not provided, the wait will be until every preceding command is completed.
- With -v terminate , the wait will be until the specified experiment, or the focused experiment has completed execution, either normally or in error.

wait [ -v terminate ] [ <expId_spec> ]