clearBreak(*arglist)

• 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.

dumpView()

Helper routine used to dump 2 dimensional views. This will go away once we pump up our usage documentation. Until then this will remain as an example of how to harvest an experiments data.

   try :
       print "In try part"
       ret = openss.expView()

   except openss.error:
       print "In except part"
       ret = None

   if ret is None:
       my_listtype = openss.ModifierList("status")
       print "expView returned None"
       try:
           print "status = ", openss.list(my_listtype)
       except openss.error:
           print "listStatus failed"

   else:
       r_count = len(ret)
       for row_ndx in range(r_count):
           print " "
           row =ret[row_ndx]
           c_count = len(row)
           for rel_ndx in range(c_count):
               print row[rel_ndx]

exit(*arglist)

• 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.
  Example:

     openss.exit()
  

Parameters:

arglist - None

expAttach(*arglist)

• The attached applications will not execute until an expGo command is issued.

If ModifierList object with mpi is selected, all the threads that are part of a running application will be included in the experiment.

If ModifierList object with mpi is not present, only those threads that are explicitly listed in Target will be included in the experiment.

If there is no ExpId provided, information is attached to the focused experiment.

The Target is used to restrict the knowledge of the experiment or data collection to certain portions of an appliaction.

• 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 is provided without ExpTypeList, those applications are attached to all the expTypes that are already attached of the experiment.

If ExpTypeList is provided without Target, the specified data collectors are used to instrument all the executable routines that are already attached to the indicated experiment.

If both Target and ExpTypeList are provided, only those portions of the application in the Target are linked to the specified collectors in ExpTypeList.

If neither Target nor ExpTypeList is provided, the command does nothing.

   my_file = openss.FileList("file_1")
   my_exptype = openss.ExpTypeList("pcsamp")
   my_expid = openss.expCreate()
   openss.expAttach(my_expid,my_file,my_exptype)

Parameters:

arglist - up to 4 optional class objects:

• ModifierList object with mpi
• ExpId object
• Target object lists
  • ClusterList
  • FileList
  • HostList
  • PidList
  • TreadList
  • RankList
• ExpTypeList

expClose(*arglist)

• 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 ModifierList("kill") is not provided, attached applications will continue executing.
• If ModifierList("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 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 ModifierList("all") will cause all defined experiments to be deleted.

   my_expid = openss.expCreate()
   all_mod = openss.ModifierList("all")
   kill_mod = openss.ModifierList("kill")

   openss.expclose(all_mod,my_expid)
       -or-
   openss.expclose(all_mod,kill_mod)
       -or-
   openss.expclose(all_mod)
       -or-
   openss.expclose()

Parameters:

arglist - up to 2 optional class objects:

• ModifierList object with kill
• ExpId object or ModifierList object with all

expCreate(*arglist)

• Start the process of defining an experiment:
  • Define a new experiment identifier.
  • Set the current focus to the new identifier.
  • Return the experiment identification identifier.
  • The experiment will not execute until an expGo command is issued.
• If ModifierList object with mpi is selected, all the threads that are part of a running application will be included in the experiment.
• If ModifierList object with mpi is not present, only those threads that are explicitly listed in Target will be included in the experiment.
• The Target will associate the specified executable with the experiment being defined.
• The experiment type argument, ExpTypeList, 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.
• The return type is an ExpId object which can be used directly by other commands.

ExpId = expCreate(arglist)

   my_file = openss.FileList("file_1")
   my_exptype = openss.ExpTypeList("usertime")
   my_expid = openss.expCreate(my_file,my_exptype)

Parameters:

arglist - up to 3 optional class objects:

• ModifierList object with mpi
• Target object lists
  • ClusterList
  • FileList
  • HostList
  • PidList
  • TreadList
  • RankList
• ExpTypeList

expDetach(*arglist)

• 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 provided, the focused experiment is used.
• If Target is provided without ExpTypeList, all collectors are detached for those applications.
• The use of Target" allows control over the parts of an executable program that will no longer generate performance data.
  • The absence of any HostList 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 FileList is not supported.
  • Use of PidList will result in only the Threads associated with that Pid to stop measuring performance.
  • Use of TreadList will result in only that specific Thread to stop measuring performance.
• If both Target and ExpTypeList are provided, only the specified collectores in ExpTypeList are detached from just those applications described in Target.
• If ExpTypeList is provided without Target, the specified data collectors are detached from all the executable routines that are ttached to the indicated experiment.
• If neither Target nor ExpTypeList is provided, the command does nothing.

   my_file = openss.FileList("file_1")
   my_exptype = openss.ExpTypeList("pcsamp")
   my_expid = openss.expCreate()
   openss.expAttach(my_expid,my_file,my_exptype)
   openss.expDetach(my_expid,my_exptype)

Parameters:

arglist - up to 3 optional class objects:

• ExpId object
• Target object lists
  • ClusterList
  • HostList
  • PidList
  • TreadList
  • RankList
• ExpTypeList

expDisable(*arglist)

• 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.
• ModifierList("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.

   # Disable the currently focused experiment
   openss.expDisable()

   # Disable all active experiments
   my_modifier = openss.ModifierList("all")
   openss.expDisable(my_modifier)

   # Disable a specified experiment (7)
   my_exp = openss.ExpId(7)
   openss.expDisable(my_exp)

Parameters:

arglist - 1 of 2 optional class objects:

• ModifierList("all")
• ExpId

expEnable(*arglist)

• 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.
• ModifierList("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.

   # Enable the currently focused experiment
   openss.expEnable()

   # Enable all experiments
   my_modifier = openss.ModifierList("all")
   openss.expEnable(my_modifier)

   # Enable a specified experiment (7)
   my_exp = openss.ExpId(7)
   openss.expEnable(my_exp)

Parameters:

arglist - 1 of 2 optional class objects:

• ModifierList("all")
• ExpId

expFocus(*arglist)

• Make the given experiment id the current, focused experiment.
• In many commands ExpId 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 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.
• The return type is an ExpId object which can be used directly by other commands.

ExpId = expCreate(arglist)

   # Get the Id of the currently focused experiment
   cur_id = openss.expEnable()

   # Change the focus to experiment #7
   my_exp = openss.ExpId(7)
   cur_id = openss.expEnable(my_exp)

Parameters:

arglist - 1 optional class object:

• ExpId

expGo(*arglist)

• 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. Current available status strings are:
    • "Unknown": An unknown status was returned.
    • "Paused": The process is in a "paused" state.
    • "Running": The process is still running.
    • "Terminated": The process has finished running.
    • "Error": Something went wrong.
  • 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 and ModifierList("all") will result in only the focused experiment being run.
• The use of ExpId will result in only that experiment being run.
• The use of ModifierList("all") will result in every defined experiment being run.

   # Run the currently focused experiment
   openss.expGo()

   # Run all experiments
   my_modifier = openss.ModifierList("all")
   openss.expGo(my_modifier)

   # Run a specified experiment (7)
   my_exp = openss.ExpId(7)
   openss.expGo(my_exp)

Parameters:

arglist - 1 of 2 optional class objects:

• ModifierList("all")
• ExpId

expPause(*arglist)

• 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 is not provided, the focused experiment is used.

• If ModifierList("all") is present, every defined experiment is halted.

  expPause [ ModifierList("all") || ExpId ]

   # Halt the currently focused experiment
   openss.expPause()

   # Halt all experiments
   my_modifier = openss.ModifierList("all")
   openss.expPause(my_modifier)

   # Halt a specified experiment (7)
   my_exp = openss.ExpId(7)
   openss.expPause(my_exp)

Parameters:

arglist - 1 of 2 optional class objects:

• ModifierList("all")
• ExpId

expRestore(*arglist)

• 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 FileList. A different database can be specified with the expSave command.
• The return type is an ExpId object which can be used directly by other commands.

ExpId = expRestore(arglist)

   # Restore an experiment previously save as "stored_data.db".
   my_file = openss.FileList("stored_data.db")
   my_exp = openss.expRestore(my_file)

Parameters:

arglist - 1 class object:

• FileList

expSave(*arglist)

• 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 ModifierList("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 ModifierList("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.

   # Store the currently focused experiment
   my_file = openss.FileList("stored_data.db")
   openss.expSave(my_file)

   # Copy the currently focused experiment
   my_file = openss.FileList("stored_data.db")
   my_modifier = openss.ModifierList("copy")
   openss.expSave(my_modifier,my_file)

   # Store a specified experiment (7) to file
   my_file = openss.FileList("stored_data.db")
   my_exp = openss.ExpId(7)
   openss.expSave(my_exp,my_file)

Parameters:

arglist - From 1 to 3 class objects:

• ModifierList("copy") (optional)
• ExpId (optional)
• FileList (required)

expSetParam(*arglist)

• Change the value an experiment's argument.
• A parameter's setting 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.

   # Create a hardware counting experiment
   my_expid = openss.expCreate("hwc")

   my_param_list = openss.ParamList()
   # Set which counter event we want
   my_param_list += ("event","PAPI_HW_INT")
   # Set the sampling rate
   my_param_list += ("sampling_rate",2000)
   # Set the paramerter list to the experiment
   openss.expSetParam(my_expid,my_param_list)
   # Attach the test program to the experiment
   my_prog = openss.FileList("bosco.exe")
   openss.expAttach(my_expid,my_prog)
   # Run the experiment
   openss.expGo()

Parameters:

arglist - From 1 to 2 class objects:

• ExpId (optional)
• ParamList (required)

expView(*arglist)

• Display the performance data that has been collected for an experiment.
• If this command is issued with no ExpId, 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 MetricList 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 option acts like a filter on the output.
  • The absence of any HostList 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 FileList is not supported.
  • Use of PidList will result in only the Threads associated with that Pid being included for the selected hosts.
  • Use of TreadList will result in only that specific Thread being included, if it exists on the selected hosts.
  expView [ ExpId ] [ <viewType> ] [ -m <expMetric_list> ] [ Target ]

   my_file = openss.FileList("bosco")
   my_viewtype = openss.ViewTypeList("pcsamp")
   my_metric_list = openss.MetricList()
   my_metric_list += ("pcsamp","inclusive")

   ret = openss.expView(my_expid,my_viewtype,my_metric_list)

Parameters:

arglist - up to 4 optional class objects:

• ExpId (optional)
• ViewType (optional)
• MetricList (optional)
• Target object lists (optional)
  • ClusterList
  • FileList
  • HostList
  • PidList
  • TreadList
  • RankList

list(*arglist)

• List command for experiment status inquiries.

  Syntax:

     # Both <output> and <list args> change for 
     # each <list modifier>
     <output> = list(<list modifiers>,<list args>)
  

• One must include one of the following <list modifiers>:
  • "breaks" !! NOT SUPPORTED YET !!
    • 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 will cause all the breakpoints for the specified experiment to be listed.
      • The use of ModifierList("all") will cause all the known breakpoints, for all of the experiments defined by the user, to be listed.
    • <list args>: 1 of 2 optional class objects
      • ModifierList("all") (optional)
      • ExpId (optional)

    • <output>:

      Example1:

         # List breaks set in the currently focused experiment
         my_modifier = openss.ModifierList("breaks")
         int_list = openss.list(my_modifier)
      

      Example2:

         # List breaks set in all active experiments
         my_modifier = openss.ModifierList(["breaks","all"])
         int_list = openss.list(my_modifier)
      

      Example3:

         # List breaks set in a specified experiment
         my_modifier = openss.ModifierList("breaks")
         :
         :
         my_exp = openss.expCreate()
         int_list = openss.list(my_modifier)
      

  • "expid"
    • List the experiments that have been defined.
    • <list args>:
      • None

    • <output>:

      Example:

         # List of I{ExpId} of active experiments.
         my_modifier = openss.ModifierList("expid")
         expid_list = openss.list()
      

  • "hosts"
    • 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 option will cause all the hosts that have been included in the selected experiment to be listed.
    • <list args>: 1 optional class object:
      • ExpId (optional)
      Example1:

         # List hosts for currently focused experiment
         my_modifier = openss.ModifierList("hosts")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List hosts for a specified experiment
         my_modifier = openss.ModifierList("hosts")
         my_exp = openss.expCreate()
         :
         :
         string_list = openss.list(my_modifier,my_exp)
      

  • "metrics"
    • Retrieve the metrics that are associated with a ViewTypeList object.
      • 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 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 ModifierList("all") will cause all the metrics for all available collectors to be listed.
      • The use of the "<viewType_list>" option will result in a listing of only those metrics associated with the specific data collectors in the list.
    • <list args>: 1 of 3 optional class objects
      • ModifierList("all") (optional)
      • ExpId (optional)
      • ExpTypeList (optional)
    • <output>:
      • <ListOf_expMetric>
      Example1:

         # List view type metrics for currently focused experiment
         my_modifier = openss.ModifierList("metrics")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List view type metrics for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("metrics")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         string_list = openss.list(my_modifier,my_exp,my_host)
      

  • "obj"
    • List the objects of the applications that are part of the specified experiment.
      • If ExpId 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.
    • The return type is a list of string objects.
    • <list args>: Up to 2 optional class objects:
      • ExpId object (optional)
      • Target object lists (optional)
        • ClusterList
        • HostList
        • PidList
        • TreadList
        • RankList
    • <output>:
      • <ListOf_filename>
      Example1:

         # List the a.out and dsos for currently focused experiment
         my_modifier = openss.ModifierList("obj")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List a.out and dsos for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("obj")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         string_list = openss.list(my_modifier,my_exp,my_host)
      

  • "params"
    • Retrieve the parameters that are associated with a particular <viewType> or set of <viewType>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 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 ModifierList("all") will cause all the parameters for all available collectors to be listed.
      • The use of the "<viewType>" option will result in a listing of only those parameters associated with that specific data collector.
    • <list args>: Up to 3 optional class objects:
      • ModifierList("all") (optional)
      • ExpId (optional)
      • ExpTypeList (optional)
    • <output>:
      • <ListOf_expParam>
      Example1:

         # List collector parameters set in the currently 
         # focused experiment
         my_modifier = openss.ModifierList("params")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List parameters available in all available collectors
         my_modifier = openss.ModifierList(["params","all"])
         string_list = openss.list(my_modifier)
      

      Example3:

         # List collector parameters set in a specified experiment
         my_modifier = openss.ModifierList("params")
         :
         :
         my_exp = openss.expCreate()
         string_list = openss.list(my_modifier)
      

  • "pids"
    • 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" option is supplied, all the Pids that are part of the specified experiment are listed.
    • The use of the HostList option acts like a filter on the output.
      • The absence of any HostList specification will cause all pids in the specified experiment to be included.
      • The default cluster contains only localhost and can be specified by using HostList.
    • <list args>: Up to 2 optional class objects:
      • ExpId (optional)
      • <HostList> (optional)
    • <output>:
      • <ListOf_pidname>
      Example1:

         # List the process ids for currently focused experiment
         my_modifier = openss.ModifierList("pids")
         pid_list = openss.list(my_modifier)
      

      Example2:

         # List process ids for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("pids")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         pid_list = openss.list(my_modifier,my_exp,my_host)
      

  • "ranks" !! NOT SUPPORTED YET !!
    • 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" 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 HostList specification will cause all Ranks in the specified experiment to be included.
      • The default cluster contains only localhost and can be specified by using HostList.
      • Use of FileList is not supported.
      • Use of PidList will result in only the Ranks associated with that Pid being included for the selected hosts.
      • Use of RankList will result in only that specific Rank being included, if it exists on the selected hosts.
    • <list args>:
      • ExpId object (optional)
      • Target object lists (optional)
        • ClusterList
        • HostList
        • PidList
        • TreadList
        • RankList
    • <output>:
      • <ListOf_rankname>
      Example1:

         # List the mpi ranks for currently focused experiment
         my_modifier = openss.ModifierList("ranks")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List mpi ranks for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("ranks")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         string_list = openss.list(my_modifier,my_exp,my_host)
      

  • "src"
    • List the source filenames of the modules that are part of the specified experiment.
    • If ExpId 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.
    • FileList 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.
    • <list args>:
      • ExpId object (optional)
      • Target object lists (optional)
        • ClusterList
        • HostList
        • PidList
        • TreadList
        • RankList
    • <output>:
      • <listOf_filename>
      Example1:

         # List the source files for currently focused experiment
         my_modifier = openss.ModifierList("src")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List a.source files for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("src")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         string_list = openss.list(my_modifier,my_exp,my_host)
      

  • "status"
    • List the status of experiments.
      • If no option is selected, return the status of the focused experiment.
      • The use of ExpId will cause the status of the specified experiment to be returned.
      • The use of ModifierList("all") will cause the status of all the defined experiments to be returned.
      • The return value is a list of strings representing the status of the current focused experiment process. Current available status strings are:
        • "Unknown": An unknown status was returned.
        • "Paused": The process is in a "paused" state.
        • "Running": The process is still running.
        • "Terminated": The process has finished running.
        • "Error": Something went wrong.
    • <list args>: up to 1 of 2 optional class objects.
      • ModifierList("all") (optional)
      • ExpId (optional)
    • <output>:
      • <ListOf_statusType>
      Example1:

         # List status for the currently focused experiment
         my_modifier = openss.ModifierList("status")
         string_list = openss.list(my_modifier)
      

      Example2:

         # List status for all active experiments
         my_modifier = openss.ModifierList(["status","all"])
         string_list = openss.list(my_modifier)
      

      Example3:

         # List status for a specified experiment
         my_modifier = openss.ModifierList("status")
         :
         :
         my_exp = openss.expCreate()
         string_list = openss.list(my_modifier)
      

      Example4:: See example for waitForGo().
  • "threads" !! NOT SUPPORTED YET !!
    • 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" 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 HostList specification will cause all Threads in the specified experiment to be included.
      • The default cluster contains only localhost and can be specified by using HostList.
      • Use of FileList is not supported.
      • Use of PidList will result in only the Threads associated with that Pid being included for the selected hosts.
      • Use of TreadList will result in only that specific Thread being included, if it exists on the selected hosts.
    • <list args>:
      • ExpId object (optional)
      • Target object lists (optional)
        • ClusterList
        • HostList
        • PidList
        • TreadList
        • RankList
    • <output>:
      • <ListOf_threadname>
      Example1:

         # List the threads for currently focused experiment
         my_modifier = openss.ModifierList("threads")
         thread_list = openss.list(my_modifier)
      

      Example2:

         # List a.threads for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("threads")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         thread_list = openss.list(my_modifier,my_exp,my_host)
      

  • "exptypes"
    • 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 will cause the utilities that are attached to the specified experiment to be listed.
      • The use of ModifierList("all") will cause all the possible performance measurement utilities that can be used in experiments to be listed.
    • The return type is a list of string objects representing experiment type.
    • <list args>: Up to 1 of 2 optional class objects.
      • ModifierList("all") (optional)
      • ExpId (optional)
    • <output>:
      • <ListOf_expType>
      Example1:

         # List experiment types attached to the currently 
         # focused experiment.
         string_list = openss.list(ModifierList("types"))
      

      Example2:

         # List all experiment types possible for the currently 
         # focused experiment.
         string_list = openss.list(ModifierList(["types","all"]))
      

  • "views"
    • Retrieve the views that are available for an ExpTypeList.
      • 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 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 ModifierList("all") will cause all the the reports for all available collectors to be listed.
      • The use of the ExpTypeList option will result in a listing of only those reports associated with the specific data collectors in the list.
    • <list args>: up to 1 of 3 optional class objects.
      • ModifierList("all") (optional)
      • ExpId (optional)
      • ExpTypeList (optional)
    • <output>:
      • ViewTypeList
      Example1:

         # Get views available for currently focused experiment
         my_modifier = openss.ModifierList("views")
         view_list = openss.list(my_modifier)
      

      Example2:

         # Get views available for a specified experiment
         # and for a specific host.
         my_modifier = openss.ModifierList("views")
         my_host = openss.HostList("bosco.milk.com")
         my_exp = openss.expCreate()
         :
         :
         view_list = openss.list(my_modifier,my_exp,my_host)
      

setBreak(*arglist)

• Enter a breakpoint, which will halt the application when reached.
• If ExpId 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.

wait(*arglist)

• 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.

   # Use the following for all the wait() examples:
   my_file = openss.FileList("foo")
   my_exptype = openss.ExpTypeList("pcsamp")
   my_expid = openss.expCreate(my_file,my_exptype)
   my_mod = openss.ModifierList("terminate")

   # 
   openss.expGo()
   openss.wait()

   # 
   openss.expGo()
   openss.wait(my_mod)

   # 
   openss.expGo()
   openss.wait(my_mod,my_expid)

   # 
   openss.expGo()
   openss.wait(my_expid)

Parameters:

arglist - up to 2 optional class objects:

• ExpId object (optional)
• ModifierList("terminate") (optional)

waitForGo()

Helper routine to wait until expGo really has finished.

Since expGo is asynctric in nature, we need to run this routine to see when it is done if we want to make sure it is really done before continuing on.

This was created before the wait() command was implemented and is retained as an example of how to poll for experiment status using the list() command.

   modifier = openss.ModifierList("status")
   while 1:
       # Pause for 10 seconds
       os.system("sleep 10")

       status = openss.list(modifier)
       stat_count = len(status)
       for ndx in range(stat_count):
           if status[ndx] == 'Terminated':
               return
           if status[ndx] == 'Error':
               raise error,"expGo failed for some reason"
               return