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.
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 [{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.
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 [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 Parallel Environment for AIX: Operation and Use, Volume 1, Using the Parallel Operating Environment.
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 [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.
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 [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 [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.
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 [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.
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 [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.
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 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:
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.
you can create a new task group, or add tasks to an existing task group.
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.
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 [command_name]
The help subcommand can either list all of the PCT's subcommands, or else return the syntax of a particular subcommand.
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 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.
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 {{[poe] exec absolute_path_to_executable } | {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.
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"
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 information if installing MPI trace probes using the trace add subcommand or profile probes using the profile add subcommand. 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 instrumentation points are listed by this subcommand as a table with headings for task identifier, file identifier, function identifier, point identifier, point type, and callee name.
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.
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 --- ------- ----------- -------- ---------- ------------ 0 54 0 0 0 0 54 0 1 2 printf 0 54 0 2 3 printf 0 54 0 3 2 MPI_Abort 0 54 0 4 3 MPI_Abort 0 54 0 5 1 0 54 1 0 0 0 54 1 1 2 printf 0 54 1 2 3 printf 0 54 1 3 2 printf 0 54 1 4 3 printf 0 54 1 5 2 MPI_Recv 0 54 1 6 3 MPI_Recv 0 54 1 7 2 consume_data 0 54 1 8 3 consume_data 0 54 1 9 2 printf 0 54 1 10 3 printf 0 54 1 11 1 pct>
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...]]
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.
pct> profile show probetypes
pct> profile show probetypes
pct> profile show probetype hwcount
pct> profile show probetype hwcount
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 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
For example, to remove the profile probe set whose index is 3:
pct> profile remove probe 3
profile set path "path_name/output_file_base_name"
The profile set path subcommand specifies the output location and base name for the profile data files generated by profile probes that you install using the profile add subcommand.
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"
profile show {probes | probetypes | probetype probe_type_name | path}
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.
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 [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.
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 "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.
For example, to execute the PCT subcommands contained in the PCT script file myscript.cmd:
pct> run "myscript.cmd"
select {trace | profile}
The select subcommand enables you to select the type of probe data you will be collecting.
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
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.
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/
The show subcommand returns, depending on the form of the subcommand you use, various information about the target application and the PCT.
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.
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.
returns a list of the available instrumentation point types. This enables you to understand the numeric point type returned by the point subcommand.
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.
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.
returns a list of the types of information you can collect using the PCT (for this release, "trace" and "profile"). This information is needed when selecting the type of data you will be collecting using the select subcommand.
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
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
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.
For example:
pct> stdin "now is the time \nfor all good men"
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.
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 [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:
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.
pct> trace show probetypes
pct> trace show probetypes
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
The trace remove subcommand enables you to remove a custom user marker or a trace probe set.
pct> trace show markers
pct> trace show probes
For example, to remove the trace probe whose probe identifier is "2":
pct> trace remove probe 2
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.
If you want to specify more than one event type, use a comma to separate the event type names.
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
The trace show subcommand lists, depending on the clause you specify, either:
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.
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
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 <control>-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