pct Purpose pct - Invokes the Performance Collection Tool (PCT) in either its graphical-user-interface or command-line mode. Format pct [-c [-s script_file]] The pct command starts the PCT in either its graphical-user-interface mode, or, if the -c flag is specified, its command-line mode. Flags -c Specifies that the PCT should be started in command-line mode. Refer to the, "Subcommands of the pct command" section of this manual page for information on the subcommands you can issue once the PCT is running in this mode. -s script_file When running in command-line mode, instructs the PCT to read its commands from the script file specified. When running in graphical-user-interface mode, you cannot use this option. Usage The PCT is a highly scalable performance monitoring tool built on dynamic instrumentation technology -- the Dynamic Probe Class Library (DPCL). Using the PCT, you can collect: * MPI and user event traces for eventual analysis by either: * Jumpshot (a public-domain tool developed at Argonne National Lab). or * the utestats utility provided as part of the PE Benchmarker Toolset. Since the MPI and user trace information will be output as standard AIX(R) trace files, we have also supplied, as part of the PE Benchmarker tool set, several utilities for converting the AIX trace files created by the PCT into a format readable by Jumpshot and the utestats utility. * Hardware and operating system profiles for playback within the Performance Visualization Tool (as invoked by the pvt command). * POWER5(TM) counter architecture enforces coupling of events to counters. Events can only be counted in specific groups. The following PMAPI hardware counter groups are supported: 0, 7, 8, 10, 36, 40, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 78. 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 128, 129, 130, 131, 132, 133, 134, 135, 136. * Users of POWER5 hardware will only be able to select event groups to count, as opposed to individual events. A counter grouping is a set of events that can be simultaneously counted in a set of counters on a POWER5 box. POWER5 contains 6 hardware counters, two of which are dedicated to specific events, and the other four events specific to the grouping. * Communication counts * Profiling data for OpenMP constructs The PCT can be run in either its graphical-user-interface mode, or, if the -c flag is specified, its command-line mode. The PCT's graphical-user-interface is built on top of its command-line interface; in other words, your manipulations of the graphical-user-interface are translated by the tool into pct subcommands. These subcommands are issued, and the information returned is used to update the graphical-user-interface. The pct subcommands that result from your interface interactions are displayed in an information area of the PCT's Main Window. When running in command-line mode, you can optionally have the PCT read its commands from a script file. You can specify the script file using the -s option when issuing the pct command, or you can use the run subcommand. The pct command's subcommands (for controlling the PCT in command-line mode) are listed alphabetically under the, "Subcommands of the pct command" section of this manual page. Examples To start the PCT in graphical-user-interface mode: pct To start the PCT in command-line mode: pct -c To start the PCT in command-line mode, and read commands from the script file myscript.cmd. pct -c -s myscript.cmd Commands: uteconvert(1), pvt(1), slogmerge(1), utemerge(1), utestats(1) Refer to traceTOslog2 documentation at http://www-unix.mcs.anl.gov/perfvis/download/index.htm Subcommands of the pct command block subcommand (of the pct command) block [task task_list | group task_group_name] {file "regular_expression"[,"regular_expression"] | fileid file_identifier[,file_identifier]} "regular_expression_to_match_block" The block subcommand lists, for one or more tasks, the line numbers of blocks where instrumentation can be set in the source files that match the specified regular expression or file identifier. By default, the block subcommand applies to the current task group. The default can be overridden by specifying a task list or task group name. The blocks are listed by this subcommand as a table with column headings for task identifier, file identifier, file name, block identifier, block index, and starting line number. task task_list Specifies the connected POE tasks containing the source file whose blocks you want to list. The tasks in the POE application can be specified by listing individual values separated by commas, by giving a range of tasks using a colon to separate the ends of the range, by giving a range and increment using colons to separate the range and increment values, or by a combination of these specifications. group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the files whose blocks you want to list. The regular expression must be enclosed in quotes. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) you wish to list. "regular_expression_to_match_block_name" Specifies a regular expression enclosed in quotation marks that identifies the block names to list. A block name has the form !block@mmmmmm:nnnnnn, such as init!block@000100:000110 where mmmmmm and nnnnnn are the starting and ending line number for a block. Matching is performed using rules of AIX file name pattern match. An "init*" will match all blocks that have functions starting from 'init' in the given file (or fileid) list. A set of nested blocks may have the same starting line number, the same ending line number, or both. This may occur for a number of reasons. The first is that the application writer may have used a one line macro which expands to source code with nested braces all on one line. Blocks may also have the same starting or ending line number because the compiler did not generate code between individual blocks, and so the starting or ending address is shared by multiple blocks. In cases where blocks have the same starting or ending line number, an additional level of qualification is needed to identify a specific block. In this case, a line number specification will have a sequential number appended to it to identify each unique block. For instance, a block label could look like func!block@000100:000105.1. This form of block label will be used anywhere a block label is accepted. For example, to list the blocks in file calc.c function sum pct> block task 0 file calc.c "sum!*" #include int totals[10]; int nums[10]; void sum(); int main(int argc, char *argv[]) { if (argc == 1) { sum(); } } void sum() { int i; int j; for (i = 0; i < 10; i++) { nums[i] = i; for (j = 0; j < i; j++) { totals[j] = totals[j] + i; } } for (i = 0; i < 10; i++) { if (totals[i] % 2) { printf("Totals[%d] is odd: %d\n", i, totals[i]); } } } --------------------------------------------------------------------------- Tid File Id Block Id File Name Block Name --- ------- -------- --------- ----------------------- 0 1 0 calc.c sum!block@000019:000021 0 1 1 calc.c sum!block@000021:000021 0 1 2 calc.c sum!block@000025:000026 0 1 3 calc.c sum!block@000026:000026 comment subcommand (of the pct command) # [ comment-string ] The comment subcommand is intended for use within script files you write, and is not intended for interactive command-line sessions. Essentially, the # (pound sign) character instructs the PCT to ignore the rest of the line. comment-string Is any comment you want to add to the file. For example, the following PCT script file contains three comment lines to explain the purpose of the script: # This example uses the 'chaotic' application from the DPCL samples. # The script loads a four-way chaotic application, inserts probes, # starts the application, and then waits for the application to complete load poe exec /home/user/chaotic poeargs "-procs 4" select trace trace set path "/scratch/trace_out" trace add mpiid 0 to file "chaotic.f" start wait connect subcommand (of the pct command) connect [{pid process_id | poe pid poe_process_id} | task task_list | group task_group_name] The connect subcommand connects the PCT to an existing application. Using this subcommand, you can connect to a single application process, or the controlling, "home node" process in a POE application. Once you are connected to a controlling POE home node process, you can reissue this subcommand to connect to one or more of the POE application's tasks. pid process_id Specifies the process id of a single application process to connect. poe pid poe_process_id Indicates that you are connecting a POE process, and specifies the process id of the POE home node process (the executing instance of the poe command). Only the controlling POE process is connected. To connect to one or more of the POE application's tasks, reissue the connect subcommand. task task_list Specifies a list of POE tasks to connect. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refer to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. To connect to all tasks in a POE application, you can specify the task group all, which will have been created by the PCT when you connected to the controlling, home node, POE process. Refer to the group subcommand for information on creating task groups. For example, to connect to the application process whose AIX process ID is 12345: pct> connect pid 12345 To connect to the POE "home node" process whose AIX process ID is 12345: pct> connect poe pid 12345 The preceding example connects to just the controlling, home node, process in a POE application. To now connect to all of the tasks in the POE application: pct> connect group all destroy subcommand (of the pct command) destroy [task task_list | group task_group_name] The destroy subcommand terminates execution of one or more connected processes. By default, the tasks in the current task group (as previously defined by the group subcommand) are the ones terminated. You can override this default, however, by specifying a task_list or task_group_name when you issue the destroy subcommand. When working with a POE application, be aware that terminating any process of the application will cause POE to terminate all of the application's processes. This termination of all processes is a function of POE, not of the PCT. For more information, refer to IBM(R) Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment. task task_list Specifies the connected tasks to be terminated. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refer to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. For example, to terminate execution of the tasks in the current task group: pct> destroy To terminate task 8: pct> destroy task 8 To terminate the tasks in task group connected: pct> destroy group connected disconnect subcommand (of the pct command) disconnect [task task_list | group task_group_name] The disconnect subcommand disconnects the PCT from one or more connected processes. Disconnecting from a process removes any performance collection probes from the process. Disconnecting from a process does not terminate the process; the process will continue to run. Once a process is disconnected, the PCT will no longer be able to control execution of, or instrument, the process. By default, the tasks in the current task group (as previously defined by the group subcommand) are the ones that are disconnected. You can override this default, however, by specifying a task list or task group name when you issue the disconnect subcommand. task task_list Specifies the connected POE tasks to be disconnected. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. For example, to disconnect from the tasks in the current task group: pct> disconnect To disconnect from task 8: pct> disconnect task 8 To disconnect from the tasks in task group connected: pct> disconnect group connected exit subcommand (of the pct command) exit [destroy] The exit subcommand exits the PCT. If you loaded the target application, its process(es) will also be terminated. If you merely connected to the target application, the process(es) will continue to run unless you use the destroy clause to explicitly instruct the PCT to kill the connected processes. Since terminating any process of the POE application will cause POE to terminate all of the POE application's processes, the destroy clause effectively terminates the entire POE application. For example, to exit the PCT, but allow all of its connected processes to continue running: pct> exit To exit the PCT and terminate the connected target application processes: pct> exit destroy file subcommand (of the pct command) file [task task_list | group task_group_name] "regular_expression" The file subcommand lists, for one or more tasks, any associated source file names that match a regular expression that you supply. By default, this subcommand applies to the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the file subcommand. The files are listed by this subcommand as a table with column headings for the task identifier, file identifier, file name, and, if available, the path. The file identifiers are determined by sorting the files alphabetically and numbering them starting from 0. The path will be shown only if the file path information was supplied when you compiled a file. task task_list Specifies the connected POE tasks whose source file names you want to list. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. "regular_expression" An AIX regular expression (file name substitution pattern) enclosed in quotation marks that identifies the files to list. The file subcommand will filter the list of file names using this regular expression; only file names that match this regular expression pattern will be listed. For example, to list all the files in the current task group: pct> file "*" Tid File Id File Name Path --- ------- --------- ------------- 0 0 bar.c ../../lib/src 0 1 foo1.c ../../lib/src 0 2 foo2.c ../src pct> To list only the files in task 0 that begin with the letter "f" pct> file task 0 "f*" Tid File Id File Name Path --- ------- --------- ------------- 0 1 foo1.c ../../lib/src 0 2 foo2.c ../src pct> find subcommand (of the pct command) find [task task_list | group task_group_name] function "regular_expression_to_match_function_name" The find subcommand lists all function names that match a regular expression pattern that you supply. This subcommand is intended for situations when you wish to instrument a particular function, but do not know which file contains the function. The function names found are listed by this subcommand as a table with column headings for task identifier, file identifier, file name, and function name. task task_list Specifies the connected POE tasks whose source files you want to search. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. function "regular_expression_to_match_function_name" An AIX regular expression (file name substitution pattern) enclosed in quotation marks that identifies the functions to locate. Matching is performed using rules of AIX file name pattern matching. The find subcommand will filter the list of function names using this regular expression; only function names that match this regular expression pattern will be listed. For example, to list all the functions in task 0 that match the regular expression comp*: pct> find task 0 function "comp*" Tid File Id File Name Function Name --- ------- --------- ------------- 0 23 main.c compute 0 23 main.c compare 0 25 sort.c compare2 pct> function subcommand (of the pct command) function [task task_list | group task_group_name] {file "regular_expression"[,"regular_expression"] | fileid file_identifier[,file_identifier]}... "regular_expression_to_match_function_name" The function subcommand lists, for one or more tasks, the names of the functions contained in a source file that match a regular expression search pattern you supply. The file whose functions are listed can be specified as a file identifier or as a regular expression that matches the file name. The file information can be ascertained by the file subcommand, or, if you are unsure which file the function is located in, the find subcommand. By default, this subcommand applies to the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the function subcommand. The function names are listed by this subcommand as a table with column headings for task identifier, file identifier, function identifier, file name, and function name. The function identifiers are determined by sorting the functions contained in a file alphabetically starting from 0. Each file's functions are numbered sequentially starting from 0. task task_list Specifies the connected POE tasks containing the source files whose functions you want to list. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. file "regular_expression"[,"regular_expression"] Specifies, using one or more regular expression patterns, the file(s) whose functions you want to list. The regular expression patterns must be contained in quotation marks. fileid file_identifier[,file_identifier] Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) whose functions you want to list. "regular_expression_to_match_function_name" A regular expression enclosed in quotation marks that identifies the function names to list. Matching is performed using rules of AIX file name pattern matching. The function subcommand will filter the list of function names using this expression; only function names (for the tasks/file indicated) that match the regular expression will be listed. For example, to list all the functions in the file "bar.c" in task 0: pct> function task 0 file "bar.c" "*" Tid File Id Function Id File Name Function Name --- ------- ----------- --------- ------------- 0 1 0 bar.c func0 0 1 1 bar.c func1 pct> To list all the functions in the file "bar.c" (using the file identifier) in task 0: pct> function task 0 fileid 1 "*" Tid File Id Function Id File Name Function Name --- ------- ----------- --------- ------------- 0 1 0 bar.c func0 0 1 1 bar.c func1 pct> To list, for task 0, all of the functions in files beginning with "b" or "d": pct> function task 0 file "b*", "d*" "*" Tid File Id Function Id File Name Function Name --- ------- ----------- --------- ------------- 0 3 0 bar.c func0 0 3 1 bar.c func1 0 3 2 bar2.c func_xyz 0 4 0 bar2.c calc 0 4 1 bar2.c do_math 0 4 2 bar2.c sum pct> group subcommand (of the pct command) group default task_group_name group add task_group_name task_list group delete task_group_name [task_list] The group subcommand can perform three distinct actions related to task groups: * Using the default action of the group command: group default task_group_name you can set the command context on a particular task group. When you do this, the task group you specify becomes the current task group; certain other subcommands that you issue (such as the file, function, and point subcommands) will, by default, apply only to the tasks in the current task group. * Using the add action of the group subcommand: group add task_group_name task_list you can create a new task group, or add tasks to an existing task group. * Using the delete action of the group subcommand: group delete task_group_name [task_list] you can delete, or delete selected tasks from, a task group. If a task list is specified, these tasks are removed from the task group; otherwise, the entire task group is deleted. In addition to any task groups you create using the group subcommand, note that there are two task groups that are created automatically by the PCT when you issue either the load or connect subcommands. These automatically-created task groups are named all and connected. The all task group contains all tasks in the current application, while the connected task group contains the set of tasks to which the PCT is connected. task_group_name Refers to the name of the task group that, depending on the particular group subcommand action you are executing, you want to: * make the default task group * create or add tasks to * delete or remove tasks from task_list Refers to the list of tasks that, depending on the particular group subcommand action you are executing, you want to either add to, or delete from, the task group. The tasks can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). For example, to create a task group master consisting of task 0, and a task group workers consisting of tasks 1 through 20. pct> group add master 0 pct> group add workers 1:20 To add tasks 21 through 30 to the task group workers: pct> group add workers 21:30 To make the group workers the default task group: pct> group default workers To remove tasks 21 through 30 from the task group workers. pct> group delete workers 21:30 To delete the task group workers: pct> group delete workers help subcommand (of the pct command) help [command_name] The help subcommand can either list all of the PCT's subcommands, or else return the syntax of a particular subcommand. command_name Refers to the name of the PCT subcommand you want help on. For example, to get a listing of all of the PCT's subcommands: pct> help To get the syntax of the load subcommand: pct> help load list subcommand (of the pct command) list {[task task_list | group task_group_name] [file "regular_expression" [,"regular_expression"]... | fileid file_identifier[,file_identifier]...] [line line_number_range]} list next The list subcommand returns the contents of a file. The first time you issue this subcommand, you should specify a file using the file or fileid clause. Doing this will list the entire file's contents. To list only a portion of the file's contents, specify a line number range using the line clause. To minimize typing, the PCT records the number of the last source code line displayed; issuing the list next subcommand will display the next few lines of the source code. By default, this form of the subcommand applies to the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the list subcommand. task task_list Specifies the connected POE tasks containing the source files whose contents you want to list. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. file "regular expression" [,"regular expression"]... Specifies, using one or more regular expressions, the file whose contents you want to list. Only the first file that matches the regular expression(s) will be listed. If this file cannot be located, an error will be returned, regardless of whether a subsequent file match could have been made. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) whose contents you want to list. line line_number_range The line number range of the source code you want to list. Use a colon to separate the ends of the range (for example 1:20). next Displays the next few lines of source code after the range previously returned by the list subcommand. For example, to list lines 1 through 20 of the source file bar.c: pct> list file "bar.c" line 1:20 To then list the next few lines in bar.c: pct> list next load subcommand (of the pct command) load {{[poe] exec executable_name } | {poe [mpmdcmd path_to_poe_commands_file] [poeargs "poe_arguments_string"]} [args "program_arguments_string"] [stdout standard_out_file_name] [stderr standard_error_file_name] [stdin standard_input_file_name] The load subcommand loads a serial or POE application for execution. Once an application is loaded, you can instrument it with probes, or control its execution using the start, suspend, resume, and destroy subcommands. The load subcommand is intended for applications that are not already executing; to connect to applications that are already executing, use the connect subcommand. The poe clause indicates that the application is a POE application; if not specified, the load subcommand assumes you are loading a serial application. The load subcommand loads the application into memory in a "stopped state" with execution suspended at its first executable instruction. You can start execution of the application using the start subcommand. poe Specifies that you are loading a POE program. exec executable_name Specifies the name of the executable file. If you are loading a POE application, you must also include the keyword poe on the command line. mpmdcmd path_to_poe_commands_file Specifies that the POE program you're loading follows the Multiple Program Multiple Data (MPMD) model and indicates the path to the POE commands file listing the executable programs to run. For more information on POE commands files, refer to the manual IBM Parallel Environment for AIX: Operation and Use, Volume 1. poeargs "poe_arguments_string" Specifies command-line arguments that are passed to the poe command to control various aspects of the Parallel Operating Environment. For a complete listing of the POE arguments you can supply, refer to the manual IBM Parallel Environment for AIX: Operation and Use, Volume 1. The POE arguments should be provided as a string delimited by double quotation marks. Embedded quotation marks can be included in the string if each mark is preceded by an escape character (\). Embedded escape characters may also be included if they are preceded by an additional escape character. args "program_arguments_string" Specifies command-line arguments that are passed to the application. Note that these are not POE arguments, which are instead specified by using the poeargs clause. The program arguments should be provided as a string delimited by double quotation marks. Embedded quotation marks can be included in the string if each mark is preceded by an escape character (\). Embedded escape characters may also be included if they are preceded by an additional escape character. stdout standard_out_file_name Redirects the target application's standard output to the file specified. stderr standard_error_file_name Redirects the target application's standard error to the file specified. stdin standard_input_file_name Reads the target application's standard input from a file. For example, the following command loads the serial executable foo and passes it the argument string "a b c": pct> load exec /u/example/bin/foo args "a b c" The following command loads the POE executable parallel_foo and passes it POE arguments: pct> load poe exec /u/example/bin/parallel_foo poeargs \ "-procs 4 -hfile /tmp/host.list" The following command loads an MPMD POE program. The executable files to load are listed in the POE commands file /u/example/bin/foo.cmds: pct> load poe mpmdcmd /u/example/bin/foo.cmds poeargs \ "-procs 3 -hfile /tmp/host.list" openmp add subcommand (of the pct command) openmp add [ task task_list | group task_group_name] {ompname omp_type_name | ompid omp_type_identifier}... to {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]...} [function "regular_expression"[,"regular_expression"]...| funcid function_identifier[,function_identifier...]] The openmp add subcommand adds one or more probes to collect OpenMP related information. You cannot use this subcommand, or any of the openmp subcommands, unless you have specified that you are collecting OpenMP data. To specify that you are collecting OpenMP data, issue the select subcommand with its openmp clause: select openmp If you add multiple openmp probes, be aware that they are considered a single set of probes. When removing openmp probes using the openmp remove subcommand, you will not be able to remove individual probes. Instead, you'll have to remove the entire set of probes. By default, this subcommand will add probe(s) to the tasks in the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the openmp add subcommand. Be aware, however, that the set of tasks cannot include different executables in a MPMD application. For example, if a MPMD application consists of executables a.out and b.out, then this command cannot be applied to a task group that contains both a.out and b.out tasks. task task_list Specifies the connected POE tasks to which you want to add the openmp probes. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of range (12:15 refers to tasks 12,13,14 and 15), by giving a range and increment value using colons to separate the range and increment value (20:26:2 refers to tasks 20,22,24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. ompname omp_type_name Specifies, using a probe type name, a openmp probe type to add. To list the openmp probe type names, use the openmp show subcommand (with the probetypes clause specified): pct> openmp show probetypes ompid omp_type_identifier Specifies, using a probe type identifier, an openmp probe type to add. To list the openmp probe type identifiers, use the openmp show subcommand (with the probetypes clause specified): pct> openmp show probetypes file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions (file name substitution patterns), the file(s) you wish to instrument with openmp probes. The regular expressions must be enclosed in quotation marks. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) you wish to instrument with openmp probes. function "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the functions you wish to instrument with the openmp probes. The regular expression must be enclosed in quotation marks. funcid function_identifier[,function_identifier]... Specifies, using one or more function identifiers as returned by the function subcommand, the functions you wish to instrument with openmp probes. The openmp add subcommand inserts one or more probes to the source. For example: pct> openmp add ompname all to file "foo.c" adds a probe that collects all openMP activities in the file "foo.c". The above command inserts probes to all the functions that contains the OpenMP calls in the file 'foo.c'. The probes include the entry/exit on the function that contains OpenMP calls, the before/after calls to the OpenMP locking functions, the before/after calls to the setup/barrier functions, and the entry/exit on the parallel regions. If there is no OpenMP calls in the file "foo.c", then no probe will be added. The user should use a general purpose profiling tool which we also provide, for the non-OpenMP related activities. For example: pct> # generate probes for functions with OpenMP calls pct> openmp add ompname all to file "foo.c" pct> openmp add ompname all to file "a*" pct> openmp add ompname all to file "foo1.c" function "bar*" The user can query the OpenMP callsites using the openmp callsite subcommand. The probes will not be added to the source block level. Multiple adds on the same function is not allowed. That is, if a function is added by previous probes, a subsequent add of the same function will generate error message and the whole command will fail. pct> openmp add ompname all to file "hello.c" function "foo" pct> openmp add ompname all to file "*" sesmgr: 2554-445 Some functions are profiled in the probe Id 0, duplication is not allowed openmp callsite subcommand (of the pct command) openmp callsite [task task_list | group task_group_name] {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]...} [function "regular_expression"[,"regular_expression"]...| funcid function_identifier[,function_identifier...]] The openmp callsite subcommand returns all the OpenMP related callsites for given file/functions. You cannot use this subcommand, or any of the openmp subcommands, unless you have specified that you are collecting OpenMP data. To specify that you are collecting OpenMP data, issue the select subcommand with its openmp clause: select openmp task task_list Specifies the connected POE tasks to which you want to list openmp runtime call site. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12,13,14 and 15), by giving a range and increment value using colons to separate the range and increment value (20:26:2 refers to tasks 20,22,24,and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions (file name substitution patterns), the file(s) you wish to list OpenMP runtime callsites. The regular expressions must be enclosed in quotation marks. fileid "file_identifier"[,"file_identifier"]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) you wish to list OpenMP runtime callsites function "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the functions you wish to list OpenMP runtime callsites. The regular expression must be enclosed in quotation marks. funcid "function_identifier"[,"function_identifier"]... Specifies, using one or more function identifiers as returned by the function subcommand, the functions you wish to list OpenMP runtime callsites. For example, pct> openmp callsite file "main.f" OmpId FileName Function Name Line/Addr Callee ------------------------------------------------------ 3 main.f deltat 01145 Master_TPO 4 main.f deltat 01146 deltat@OL@A 3 main.f initbuf 00790 InitializeRTE 3 main.f initbuf 00790 WSDoSetup_TPO 4 main.f initbuf 00790 initbuf@OL@8 3 main.f initbuf 00855 WSDoSetup_TPO 4 main.f initbuf 00855 initbuf@OL@9 3 main.f initbuf 00904 Barrier_TPO Note: If the function specified contains '@OL', such as 'compute@OL@3' the returned function name is still the id of the parent function 'compute', not the function name of the 'compute@OL@3' itself. The reason is that when we add probe on the function 'compute', we implicitly instrument the function 'compute@OL'. Normal returns: See example above. Error returns: 2554-403 Multiple programs detected in the command. openmp help subcommand (of the pct command) openmp help [openmp_command_name] The openmp help subcommand can either list all of the openmp subcommands, or return the syntax of a particular openmp subcommand. It provides a brief help message. If no keyword is specified, the help message will be a summary of the various openmp commands. If a keyword is specified, it may be an openmp subcommand, such as add, or a keyword which appears in <> in a help message. If a keyword is specified, then the help text will be explanatory text for that keyword. You cannot use this subcommand, or any of the openmp subcommands, unless you have specified that you are collecting OpenMP data. To specify that you are collecting OpenMP data, issue the select subcommand with its openmp clause where openmp_command_name refers to the name of openmp subcommand you want help on. The keyword can be a command name or the text listed in the angle brackets '< >'. For example: pct> openmp help Command Desc ---------------------------------------------------- OPENMP ADD [ ] TO ... pct> openmp help task_qual Command Desc ----------------------------------------------------------- ---- -> TASK -> GROUP groupname ----Either a task or group clause that specifies what tasks ----to execute the command on. The variables in square brackets '[ ]' are optional. openmp remove probe subcommand (of the pct command) openmp remove probe probe_index The openmp remove subcommand removes the openmp probe set specified by the supplied probe_index. An openmp probe set consists of one or more probes as previously installed by the openmp add subcommand. An installed openmp probe's probe_index can be ascertained by the openmp show probe subcommand. probe probe_index specifies, using a probe index, the openmp probe set to be removed. For example, pct> openmp show probes Probid Command ------------------------------------------- 0 openmp add profname all to file "foo.c" 1 openmp add profname all to file "bar.c" pct> openmp remove probe 1 openmp set path subcommand (of the pct command) openmp set path "path_name/output_file_base_name" The openmp set path subcommand specifies the output path for the data files generated as a result of running the OpenMP profiling tool. "path_name/output_file_base_name" specifies a relative or full path to the desired location for the openmp output files, followed by the output file base name. The base name is needed because the data collected by the PCT will be saved as a file on each host machine where a connected process with probes is running. The file name will consist of the base name you supply followed by a node-specific suffix supplied by the PCT. If a relative path is specified, note that the location will be relative to the directory where you started the PCT. Several openmp set path subcommands can be issued and only the last one is kept for the output. Once the openmp add subcommand is issued, the user can no longer change the path. For example: pct> openmp set path "/home/mydir/xxx" pct> # change mind pct> openmp set path "/tmp/xxx" pct> openmp add profname all to file "foo.c" pct> openmp set path "/tmp/yyy" sesmgr:2554-432 Path cannot be changed after add probe openmp show subcommand (of the pct command) openmp show {probes | probetypes | path} The openmp show subcommand lists, depending on the clause you specify, either the currently installed openmp probes, the list of openmp probe types that you can install, or the openmp file output location. probes Specifies that the openmp show subcommand should list the currently installed openmp probes (including the probe index). The probe index information is needed when removing an openmp probe using the openmp remove subcommand. probetypes Specifies that the openmp show subcommand should list the available probe types you can add using the openmp add subcommand. path Specifies that you want the openmp show subcommand to return the openmp file output location and base name as set by the openmp set path subcommand. For example, to list the installed openmp probes: pct> openmp show probes To list available openmp probe types: pct> openmp show probetypes Omp Id Omp Name Description ----- ------- ----------------- 0 all All probes below 1 lock Locking function 2 critical Critical region 3 setup Setup/barrier 4 parallel Parallel regions 5 query OpenMP query functions point subcommand (of the pct command) point [task task_list | group task_group_name] {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]...} [function "regular_expression"[,"regular_expression"]... | funcid function_identifier[,function_identifier]...] Lists the instrumentation points (at the file or function level) where custom user markers can be added by the trace add subcommand. You only need to identify instrumentation points when installing custom user markers using the trace add subcommand. You do not need the instrumentation point for any other type of data collection. By default, this subcommand will list the instrumentation points for the tasks in the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the point subcommand. The file or fileid clause specifies the file(s) whose instrumentation points you want listed. Using the function clause, you can specify one or more functions whose instrumentation points you want listed. The point identifiers are determined by numbering the points, starting from 0, according to their location in each function. The first instrumentation point in the function is given the identifier 0, the second is given the identifier 1, and so on. Each function's instrumentation points are numbered separately starting from 0. task task_list Specifies the connected POE tasks whose instrumentation points you want to list. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions (file name substitution patterns), the file(s) whose instrumentation points you want to list. The regular expression(s) must be contained in quotation marks. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) whose instrumentation points you want to list. function "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the function(s) whose instrumentation points you want to list. This regular expression must be contained in quotation marks. funcid function_identifier[,function_identifier]... Specifies, using one or more function identifiers as returned by the function subcommand, the function(s) whose instrumentation points you want to list. For example, to list all the instrumentation points in task 0 for the file bar.c: pct> point task 0 file "bar.c" Tid File Id Function Id Point Id Point Type Callee Name Line Number --- ------- ----------- -------- ---------- ------------ ----------- 0 54 0 0 0 61 0 54 0 1 2 printf 61 0 54 0 2 3 printf 61 0 54 0 3 2 MPI_Abort 62 0 54 0 4 3 MPI_Abort 62 0 54 0 5 1 63 0 54 1 0 0 114 0 54 1 1 2 printf 116 0 54 1 2 3 printf 116 0 54 1 3 2 printf 117 0 54 1 4 3 printf 117 0 54 1 5 2 MPI_Recv 120 0 54 1 6 3 MPI_Recv 120 0 54 1 7 2 consume_data 122 0 54 1 8 3 consume_data 122 0 54 1 9 2 printf 126 0 54 1 10 3 printf 126 0 54 1 11 1 130 pct> profile add subcommand (of the pct command) profile add [task task_list | group task_group_name] {{profname profile_type_name | profid profile_type_identifier} [groupid group_identifier | groupname group_name]}... to {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]...} [function "regular_expression"[,"regular_expression"]...| funcid function_identifier[,function_identifier...]] {block block_name[,block_name] | blockid block_ident[,block_ident]} The profile add subcommand adds one or more probes to collect hardware and operating system profile information. You cannot use this subcommand, or any of the profile subcommands, unless you have specified that you are collecting profile data. To specify that you are collecting profile data, issue the select subcommand with its profile clause: select profile If you add multiple profile probes, be aware that they are considered a single set of probes. When removing profile probes using the profile remove subcommand, you will not be able to remove individual probes. Instead, you'll have to remove the entire set of probes. By default, this subcommand will add the probe(s) to the tasks in the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the profile add subcommand. Be aware, however, that the set of tasks cannot include different executables in an MPMD application. For example, if an MPMD application consists of executables a.out and b.out, then this command cannot be applied to a task group that contains both a.out and b.out tasks. task task_list Specifies the connected POE tasks to which you want to add the profile probes. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. profname profile_type_name Specifies, using a probe type name, a profile probe type to add. To list the profile probe type names, use the profile show subcommand (with its probetypes clause specified): pct> profile show probetypes profid profile_type_identifier Specifies, using a probe type identifier, a profile probe type to add. To list the profile probe type identifiers, use the profile show subcommand (with its probetypes clause specified): pct> profile show probetypes groupid group_identifier If you are collecting hardware counter information, a profile group identifier indicating the specific hardware counter information you want to collect. To get a list of the profile groups available for your hardware, use the command: pct> profile show probetype hwcount groupname group_name If you are collecting hardware counter information, a profile group name indicating the specific hardware counter information you want to collect. To get a list of the profile groups available for your hardware, use the command: pct> profile show probetype hwcount file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions (file name substitution patterns), the file(s) you wish to instrument with profile probes. The regular expressions must be enclosed in quotation marks. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the file(s) you wish to instrument with profile probes. function "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the functions you wish to instrument with the profile probes. The regular expression must be enclosed in quotation marks. funcid function_identifier[,function_identifier]... Specifies, using one or more function identifiers as returned by the function subcommand, the functions you wish to instrument with the profile probes. block block_name[,block_name] Specifies one or more block names where profiling probes are to be added. If this parameter is specified, then either the file or fileid parameter must be specified. The combination of file or fileid keywords and block or blockid keywords must resolve to a single file. The source file must be compiled with the -g option, or in the case of a FORTRAN source file, the -g and -qdpcl flags. The block name is specified in the same way as the block_name parameter is specified in the block subcommand. This parameter is mutually exclusive with the function, funcid, and pointid parameters. blockid block_ident[,block_ident] Specifies the block or range of block identifiers as identified by the block command. If this parameter is specified, then the file or fileid parameters must be specified. The combination of file or fileid keywords and block or blockid keywords must resolve to a single file. The source file must be compiled with the -g option, or in the case of a FORTRAN source file, the -g and -qdpcl flags. This parameter is mutually exclusive with the function, funcid, and pointid parameters. If the blockid or block keywords are not specified, then probes will only be inserted at function entry and exit points. Allowing probes to be inserted at all blocks in a function as a default action is likely to cause excessive overhead in tracing that function. For example, to add a profile probe to collect wall clock data for the current task group: pct> profile add profname wclock to fileid 5 funcid 3 To add a profile probe to collect wall clock data and hardware data using counter group 2: pct> profile add profname wclock profname hwcount groupid 2 to fileid 3 profile help subcommand (of the pct command) profile help [profile_command_name] The profile help subcommand can either list all of the PCT's profile subcommands, or else return the syntax of a particular profile subcommand. You cannot use this subcommand, or any of the profile subcommands, unless you have specified that you are collecting profile data. To specify that you are collecting profile data, issue the select subcommand with its profile clause: select profile profile_command_name refers to the name of the PCT profile subcommand you want help on. For example, to get a listing of all of the PCT's profile subcommands: pct> profile help To get the syntax of the profile add subcommand: pct> profile help add profile remove subcommand (of the pct command) profile remove probe probe_index The profile remove subcommand removes the profile probe set specified by the supplied probe_index. A profile probe set consists of one or more probes as previously installed by the profile add subcommand. An installed profile probe's probe_index can be ascertained by the profile show subcommand (with its probes clause) as in: pct> profile show probes probe probe_index Specifies, using a probe index, the profile probe set to be removed. The probe index can be ascertained by issuing the profile show subcommand with its probes clause. For example, to remove the profile probe set whose index is 3: pct> profile remove probe 3 profile set subcommand (of the pct command) profile set {path "path_name/output_file_base_name" | [mode "openmp | pthread"} path Specifies that you want the profile set subcommand to set the profile file output location and base name as set by the profile set path subcommand. "path_name/output_file_base_name" A relative or full path to the desired location for the profile output files, followed by the output file base name. The base name is needed because the data collected by the PCT will be saved as a file on each host machine where a connected process with probes is running. The file name will consist of the base name you supply followed by a node-specific suffix supplied by the PCT. If a relative path is specified, note that the location will be relative to the directory where you started the PCT.pct For example, to specify the relative path profile as the location for profile output files and output as the base name: pct> profile set path "profile/output" mode Specifies that the profile set subcommand sets the current mode, such as openmp or pthread. "openmp" In the openmp mode, the openmp thread id will be recorded in the pvt if the function is running in an OpenMP parallel region. Note this openmp thread id will not map back to the pthread id. In the openmp mode, the original pthread id is still used for the functions outside the parallel region in an OpenMP application. If the application is not an OpenMP application, the openmp mode can still be set. The original pthread id will still be displayed as if the instrumentation is outside the parallel region. Profile set mode may be issued multiple times as long as a profile add subcommand has not been issued. The last issued profile set mode subcommand will determine the mode setting. Once a profile add subcommand has been issued, profile set mode may not be issued again. "pthread" In the pthread mode, the pthread id is recorded even in the parallel region of an OpenMP application. For example, to specify the relative path profile as the location for profile output files and output as the base name: pct> profile set path "profile/output" For example, pct> profile set mode openmp Error Returns: 2554-445 mode can only be changed before the first add command profile show subcommand (of the pct command) profile show {probes | probetypes | probetype probe_type_name | path|mode} The profile show subcommand lists, depending on the clause you specify, either the currently installed profile probes, the list of profile probe types that you can install, the options for a probetype, or the profile file output location. probes Specifies that the profile show subcommand should list the currently installed profile probes (including the probe index). The probe index information is needed when removing a profile probe using the profile remove subcommand. probetypes Specifies that the profile show subcommand should list the available probe types you can add using the profile add subcommand. probetype probe_type_name Specifies that the subcommand should list the options for the specified probe type. Currently, only the hardware counter probe type has options. path Specifies that you want the profile show subcommand to return the profile file output location and base name as set by the profile set path subcommand. mode Specifies that the profile show subcommand returns the current mode, such as openmp or pthread. For example, to list the installed profile probes: pct> profile show probes To list available profile probe types: pct> profile show probetypes Prof Id Prof Name Description ------- --------- ---------------- 0 wclock wall clock 1 rusage resource usage 2 hwcount hardware counter pct> resume subcommand (of the pct command) resume [task task_list | group task_group_name] The resume subcommand resumes execution of one or more processes that have previously been suspended by the suspend subcommand. By default, the tasks in the current task group (as previously defined by the group subcommand) are the ones that have their execution resumed. You can override this default, however, by specifying a task list or task group name when you issue the resume subcommand. task task_list Specifies the connected POE tasks that you want to resume executing. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. For example, to resume execution of all tasks in the current task group: pct> resume To resume execution of tasks 0 through 20: pct> resume task 0:20 To resume execution of the tasks in task group mygroup: pct> resume group mygroup run subcommand (of the pct command) run "pct_script_file" The run subcommand executes a series of PCT commands that are stored in a "PCT script file". A PCT script file is an ASCII file that lists a sequence of PCT subcommands. Each PCT subcommand is placed on a separate line in the PCT script file. Lines beginning with a # (pound sign) character are comments and will not be executed by the PCT. "pct_script_file" Specifies the name of the PCT script file whose subcommands you want to execute. The file name must be enclosed in quotation marks. For example, to execute the PCT subcommands contained in the PCT script file myscript.cmd: pct> run "myscript.cmd" select subcommand (of the pct command) select {trace | profile | openmp | commcount} The select subcommand enables you to select the type of probe data you will be collecting. trace Specifies that you intend to collect MPI or custom user event traces for eventual analysis using Jumpshot or the utestats utility. profile Specifies that you intend to collect hardware and operating system profiles for analysis using the Profile Visualization Tool. openmp Specifies that you intend to profile OpenMP constructs in an OpenMP application. commcount Specifies that you want to use the MPI/LAPI communication profiling tool to record message sizes for MPI and LAPI communications calls. For example, if you will be adding trace probes (using the trace add subcommand) for collecting MPI or custom user event data: pct> select trace If, on the other hand, you will be adding profile probes (using the profile add subcommand) for collecting hardware and operating system profiles: pct> select profile If, on the other hand, you will be using the openmp tool: pct> select openmp pct> Normal returns none Error returns: 2554-052 session loaded with "some_other_tool" already 2554-053 tool name "given_name" is not a valid tool name 2554-054 tool "openmp" failed to load 2554-055 tool "openmp" failed to initialize Given a normal return, openmp tool is now ready to use. All OpenMP related commands need an openmp prefix to separate those commands from the general session manager commands. set subcommand (of the pct command) set sourcepath [relative] "path_list" The set subcommand enables you to set the path used when displaying the contents of a file using the list subcommand. The initial value for the source path is the directory in which the tool was started. relative Specifies that, if relative path information is included as part of the file name supplied to the list subcommand, the relative path should be used together with the directories listed in the pathlist. For example, say one of the source files in the application is named "../../myapp/src/compute.c" and the source path is "/tmp:/usr/tmp:/home/mydir/examples/yourapp". If the relative keyword is used when setting the source path, the PCT searches the following directories when the list /../../myapp/src/compute.c subcommand is issued. /tmp/../../myapp/src/ /usr/tmp/../../myapp/src/ /home/mydir/examples/yourapp/../../myapp/src/ If the relative keyword is not used when setting the source path, however, the following directories are searched: /tmp/ /usr/tmp/ /home/mydir/examples/yourapp/ "path_list" A colon-delimited list that specifies the path the list subcommand will use to search for source files. show subcommand (of the pct command) show { events | group task_group_name | groups | points | ps | sourcepath | tools } The show subcommand returns, depending on the form of the subcommand you use, various information about the target application and the PCT. * Using the form: show events returns a list of the possible events that, if you place the PCT in an event loop using the wait subcommand, can break the PCT out of the loop. Be aware that the wait subcommand is intended only for use within scripts you write, and is not intended for interactive command-line sessions. * Using the form: show group task_group_name returns, for each task in the specified task group, the task identifier, the program name, the name of the host machine on which the task is running, the CPU type, and the task state. * Using the form: show groups returns a list of task groups. This includes any task groups created by default (the task groups all and connected), and any task groups you created using the group subcommand. An ampersand character (@) is displayed to the right of the default task group. * Using the form: show points returns a list of the available instrumentation point types including an additional point type to display the point identifier for source block instrumentation points. This enables you to understand the numeric point type returned by the point subcommand. * Using the form: show ps returns a list of the processes you own on the node where you started the PCT. This information is needed when connecting to an application using the connect subcommand. * Using the form: show sourcepath returns a list of directories searched when displaying the contents of a file using the list subcommand. You can set the source path using the set subcommand. * Using the form: show tools returns a list of the types of information you can collect using the PCT. This information is needed when selecting the type of data you will be collecting using the select subcommand. For example: pct> show tools Selected Name Description -------- ------- ----------- trace MPI and user event traces... profile hardware and operating system profiles... @ openmp OpenMP profiles commcount MPI/LAPI Byte count pct> Normal returns the list of tools available to select. Error returns: none For example, to show the tasks in the current task group: pct> show group To show the tasks in the task group "connected": pct> show group connected To show the processes that you own on the host machine: pct> show ps start subcommand (of the pct command) start The start subcommand starts execution of an application you have loaded using the load subcommand. (The load subcommand loads an application into memory in a "stopped state" with execution suspended at the first executable instruction.) For example, to start execution of the currently-loaded application: pct> start stdin subcommand (of the pct command) stdin [{"string" | eof}] The stdin subcommand sends the supplied string as standard input to the currently loaded application. If no string is supplied, the stdin subcommand will send a newline character to the application. If the eof option is supplied, the stdin subcommand will send an end-of-file character to the application. Be aware that this subcommand is intended only for applications that you have loaded using the load subcommand. If you have instead connected to an application using the connect subcommand, you cannot send standard input text using the stdin subcommand. Also be aware that you can, when loading an application using the load subcommand, indicate that the application should read standard input from a file specified by the stdin option. If the stdin option is used when loading an application with the load subcommand, note that the stdin subcommand cannot be used. "string" Specifies a text string to send to standard input. The string should be enclosed in quotes, and embedded formatting characters (such as \n) are permitted. If no string is supplied, the stdin subcommand will send a newline character to the application. eof sends an end-of-file character to the input stream reading this input data. For example: pct> stdin "now is the time \nfor all good men" suspend subcommand (of the pct command) suspend [task task_list | group task_group_name] The suspend subcommand suspends execution of one or more processes. By default, the tasks in the current task group (as previously defined by the group subcommand) are the ones that are suspended. You can override the default, however, by specifying a task list or task group name when you issue the suspend subcommand. You can resume execution of tasks suspended by this subcommand by issuing the resume subcommand. task task_list Specifies the connected POE tasks that you want to suspend. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. For example, to suspend execution of all tasks in the current task group: pct> suspend To suspend execution of tasks 0 through 20: pct> suspend task 0:20 To suspend execution of the tasks in task group "mygroup": pct> suspend group mygroup trace add subcommand (of the pct command) The syntax of the trace add command to add a probe to control MPI trace collection is: trace add [task task_list | group task_group_name] {mpiid probetype_number_list | mpiname probe_name_list} to {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]... } [function "regular_expression"[,"regular_expression"]... | funcid function_identifier[,function_identifier]...] {block block_name[,block_name] | blockid block_ident[,block_ident]} The syntax of the trace add command to add a user marker or traceon/tradeoff point is: trace add [task task_list | group task_group_name] {simplemarker "marker_name" | {{beginmarker | endmarker} "marker_name"} | {traceon | traceoff}} to {file "regular_expression"[,"regular_expression"]... | fileid file_identifier[,file_identifier]... } {function "regular_expression"[,"regular_expression"]... | funcid function_identifier[,function_identifier]...} pointid point_identifier The trace add subcommand enables you to add the following types of probes to one or more tasks. You can add: * MPI trace probes. If you add multiple MPI trace probes, be aware that they are considered a single set of probes. When removing MPI trace probes using the trace remove subcommand, you will not be able to remove selected probes. Instead, you'll have to remove the entire set of probes. * simple user markers to trace events of interest. * begin user markers and end user markers to trace intervals of interest. * user markers to force tracing on and off. You cannot use this subcommand, or any of the trace subcommands, unless you have specified that you are collecting trace data. To specify that you are collecting trace data, issue the select subcommand with its trace clause: pct> select trace You also need to specify the output location and a "base name" prefix for the trace files. To do this, use the trace set path command. For example: pct> trace set path "/home/timf/tracefiles/mytrace" By default, this subcommand will add the probes to the tasks in the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the trace add subcommand. Be aware, however, that the set of tasks cannot include different executables in an MPMD application. For example, if an MPMD application consists of executables a.out and b.out, then this command cannot be applied to a task group that contains both a.out and b.out tasks. task task_list Specifies the connected POE tasks to which you want to add the trace probes or user markers. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. mpiid probetype_number_list A probe identifier (or a list of comma-separated probe identifiers) indicating the type of MPI data (collective communication, point-to-point communication, one-sided operations, and so on) that you want to collect. To get a list of the probe identifiers, issue the trace show subcommand with its probetypes clause as in: pct> trace show probetypes mpiname probe_name_list A probe name (or a list of comma-separated probe names) indicating the type of MPI data (collective communication, point-to-point communication, one-sided operations, and so on) that you want to collect. To get a list of the probe names, issue the trace show subcommand with its probetypes clause as in: pct> trace show probetypes simplemarker "marker_name" Indicates that the probe is a simple marker being placed in the target application to trace a particular event of interest. A simple marker appears in the trace record as a single point. {beginmarker | endmarker} "marker_name" Specifies that the probe is a user marker that marks either the beginning or ending of a named user state. You need to mark both the beginning and ending of the range with the same "marker_name" (a string that will be used to identify the user state in the trace record). You can only use a particular marker name for one begin marker/end marker pair. The state will appear in the trace record as a region. {traceon | traceoff} Specifies that the probe is a user marker that will either force tracing on or off. This provides a finer degree of trace control than is otherwise available when merely specifying the file and function to trace. file "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions (file name substitution patterns), the file(s) you wish to instrument. The regular expression must be contained in quotation marks. fileid file_identifier[,file_identifier]... Specifies, using one or more file identifiers as returned by the file subcommand, the files you wish to instrument. function "regular_expression"[,"regular_expression"]... Specifies, using one or more regular expressions, the function(s) you want to instrument. funcid function_identifier[,function_identifier]... Specifies, using one or more function identifiers as returned by the function subcommand, the function you want to instrument. pointid point_identifier Specifies, using a point identifier, the instrumentation point at which to add the user markers. block block_name[,block_name] Specifies one or more block names where MPI trace probes are to be added. If this parameter is specified, then either the file or fileid parameter must be specified. The combination of file or fileid keywords and block or blockid keywords must resolve to a single file. The source file must be compiled with the -g option, or in the case of a FORTRAN source file, the -g and -qdpcl flags. The block name is specified in the same way as the block_name parameter is specified in the block subcommand. This parameter is mutually exclusive with the function, funcid, and pointid parameters. blockid block_ident[,block_ident] Specifies the block or range of block identifiers as identified by the block command. If this parameter is specified, then the file or fileid parameters must be specified. The combination of file or fileid keywords and block or blockid keywords must resolve to a single file. The source file must be compiled with the -g option, or in the case of a FORTRAN source file, the -g and -qdpcl flags. This parameter is mutually exclusive with the function, funcid, and pointid parameters If the blockid or block keywords are not specified, then probes will only be inserted at function entry and exit points. Allowing probes to be inserted at all blocks in a function as a default action is likely to cause excessive overhead in tracing that function. For example, to trace all MPI events in the file "bar.c": pct> trace add mpiname all to file "bar.c" To add a begin state marker named "green" to the second point of the first function of file "foo.c": pct> trace add beginmarker "green" to file "foo.c" funcid 0 pointid 1 trace help subcommand (of the pct command) trace help [trace_command_name] The trace help subcommand can either list all of the PCT's trace subcommands, or else return the syntax of a particular trace subcommand. You cannot use this subcommand, or any of the trace subcommands, unless you have specified that you are collecting trace data. To specify that you are collecting trace data, issue the select subcommand with its trace clause: select trace trace_command_name refers to the name of the PCT trace subcommand you want help on. For example, to get a listing of all of the PCT's trace subcommands: pct> trace help To get the syntax of the trace add subcommand: pct> trace help add trace remove subcommand (of the pct command) trace remove {marker marker_id | probe probe_index} The trace remove subcommand enables you to remove a custom user marker or a trace probe set. marker marker_id Specifies the marker identifier of the custom user marker you want to remove. To ascertain the marker identifier, use the trace show subcommand with its markers clause. pct> trace show markers probe probe_index Specifies, using a probe index, the trace probe set you wish to remove. A trace probe set consists of one or more probes previously installed by the trace add subcommand. To ascertain the trace probe set you wish to remove, use the trace show subcommand with its probes clause as in: pct> trace show probes For example, to remove the trace probe whose probe identifier is "2": pct> trace remove probe 2 trace set subcommand (of the pct command) trace set { path "path_name/output_file_base_name" | [bufsize buffer_size] [{event {mpi | process | idle} | {event [mpi,] [process,] [idle]}] [logsize maximum_log_size]} The trace set subcommand enables you to specify various settings for event trace collection. You cannot use this subcommand, or any of the trace subcommands, unless you have specified that you are collecting trace data. To specify that you are collecting trace data, issue the select subcommand with its trace clause: select trace The settings you make with this subcommand will stay in effect until you issue the select subcommand. path "path_name/output_file_base_name" Specifies a relative or full path name to the desired location for trace files followed by the output file base name. The base name is needed because the data collected by the PCT will be stored as a file on each host machine where a connected process with probes is running, The file name will consist of the base name you supply followed by a node specific suffix supplied by the PCT. bufsize buffer_size Specifies the AIX trace buffer size in Kilobytes. This value can be at most 1024, which is also the default value. [{event {mpi | process | idle} | {event [mpi,] [process,] [idle]}] Specifies the type of events (MPI events, process dispatch events, and CPU idle events) that are traced. By default, MPI events and process dispatch events are traced. Tracing process dispatch events and CPU idle events can result in larger trace files, but the additional information can provide useful context for the MPI information collected. If you want to specify more than one event type, use a comma to separate the event type names. logsize maximum_log_size Specifies the maximum trace file size in Megabytes. The default is 20 M. For example, to specify the directory tracefiles/mytrace as the output directory for the trace files: pct> trace set path "tracefiles/mytrace" To specify the buffer size to be 900 K: pct> trace set bufsize 900 To specify the maximum trace file size to be 25 M: pct> trace set logsize 25 To specify that CPU idle events should be collected: pct> trace set event idle To specify that MPI and CPU idle events should be collected: pct> trace set event mpi, idle trace show subcommand (of the pct command) trace show {[task task_list | group task_group_name] {markers | probes} | probetypes | path| options} The trace show subcommand lists, depending on the clause you specify, either: * the currently installed trace probes: trace show [task task_list | group task_group_name] probes * the currently installed user markers: trace show [task task_list | group task_group_name] markers * the list of available probe types you can add using the trace add subcommand: trace show probetypes * the trace file output location and base name (as set by the trace set path subcommand): trace show path * the BufSize, LogSize and Event: trace show options When listing the currently installed trace probes or user markers, the action is performed for the tasks in the current task group (as previously defined by the group subcommand). You can override this default, however, by specifying a task list or task group name when you issue the trace show subcommand. task task_list Specifies the connected POE tasks whose trace probes or user markers you want to list. The tasks in the POE application can be specified by listing individual values separated by commas (1,3,8,9), by giving a range of tasks using a colon to separate the ends of the range (12:15 refers to tasks 12, 13, 14, and 15), by giving a range and increment value using colons to separate the range and increment values (20:26:2 refers to tasks 20, 22, 24, and 26), or by using a combination of these (12:18,22,30). group task_group_name Specifies the name of a task group. Refer to the group subcommand for information on creating task groups. markers Specifies that you want the trace show subcommand to list the currently installed user markers. options Specifies that you want the trace show subcommand to list the current settings for BufSize, LogSize and Event.Specifies. probes Specifies that you want the trace show subcommand to list the currently installed trace probes. probetypes Specifies that you want the trace show subcommand to list the available trace probe types you can add using the trace add subcommand. path Specifies that you want the trace show subcommand to return the trace file output location and base name as set by the trace set path subcommand. For example, to list the trace probes installed in the tasks in the current task group: pct> trace show probes To list the user markers for the tasks in the task group "workers": pct> trace show markers To list the available probe types: pct> trace show probetypes wait subcommand (of the pct command) wait The wait subcommand blocks the PCT's execution so that it can wait for asynchronous system events (such as a task terminating) to occur. When one of these asynchronous events occurs, the PCT resumes execution, and returns the event that occurred. Be aware that this command is intended only for use within scripts you write, and is not intended for interactive command-line sessions. If you use it during an interactive command-line session, the only way to break out of the loop is to press -C which will kill the PCT. To see a list of the possible events that can resume execution of the PCT, issue the subcommand: pct> show events For example, the following example blocks execution of the PCT. Execution of the PCT resumes when the target application terminates. The PCT returns the event name "app_term": pct> wait app_term ------------------------------------------------------------------------