dattach

Brings currently executing processes under TotalView control

Format: 

dattach [ –g gid ] [ –r hname ]
[ –ask_attach_parallel | –no_attach_parallel ]

[ –replay | –no_replay ]

[ –go | –halt ]

[ –c corefile-name ] [ –rank num ]

[ –e ] filename [ pid-list ]

[ –parallel_attach_subset subset-specification ]

Arguments: 

–g gid

Sets the control group for the processes being added to group gid. This group must already exist. (The CLI GROUPS variable contains a list of all groups.)

–r hname

The host on which the process is running. The CLI launches a TotalView Server on the host machine if one is not already running. See the Setting Up Parallel Debugging Sessions chapter of the TotalView User Guide for information on the launch command used to start this server.

Setting a host sets it for all PIDs attached to in this command. If you do not name a host machine, the CLI uses the local host.

–ask_attach_parallel

Specifies that TotalView should ask before attaching to parallel processes of a parallel job. The default is to automatically attach to processes. For additional information, see the Parallel Page in the File > Preferences Dialog Box in ­the online Help.

–no_attach_parallel

Does not attach to any additional parallel processes in a parallel job. For additional information, see the Parallel Page in the File > Preferences Dialog Box in the online Help.

–replay | –no_replay

Enables or disables the ReplayEngine the next time the program is restarted.

–go | –halt

Specifies to explicitly continue or halt target execution after attaching. The default is to leave the target's run state as it was before the attach.

-c corefile-name

Loads the core file corefile-name. If you use this option, you must also specify a file name (filename).

-rank num

Specifies the rank associated with the executable being loaded. While this can be used independently, this option is best used with core files.

–e

Tells the CLI that the next argument is a file name. You need to use this argument if the file name begins with a dash (–) or only uses numeric characters.

filename

The name of the executable. Setting an executable here sets it for all PIDs being attached to in this command. If you do not include this argument, the CLI tries to determine the ­executable file from the process. Some architectures do not allow this to occur.

pid-list

A list of system-level process identifiers (such as a UNIX PID) naming the processes that TotalView controls. All PIDs must reside on the same system, and they are placed in the same control group.

If you need to place the processes in different groups or attach to processes on more than one system, you must use multiple dattach commands.

-parallel_attach_subset subset_specification

Defines a list of MPI ranks to attach to when an MPI job is created or attached to. The list is space-separated; each element can have one of three forms:

rank: specifies that rank only

rank1-rank2: specifies all ranks between rank1 and rank2, inclusive

rank1-rank2:stride: specifies every strideth rank between rank1 and rank2

A rank specification can be either a number or "max" which represents the last rank in the MPI job.

For example:

dattach -parallel_attach_subset {1 2 4-6 7-max:2} mpirun

attaches to ranks 1, 2, 4, 5, 6, 7, 9, 11, 13,....

Description: 

The dattach command attaches to one or more processes, making it possible to continue process execution under TotalView control.

TotalView Individual: You can attach only to processes running on the computer upon which you installed TotalView Individual.

This command returns the TotalView process ID (DPID) as a string. If you specify more than one process in a command, the dattach command returns a list of DPIDs instead of a single value.

TotalView places all processes to which it attaches in one dattach command in the same control group. This lets you place all processes in a multiprocess program executing on the same system in the same control group.

If a program has more than one executable, you must use a separate dattach command for each one.

If you have not loaded filename already, the CLI searches for it. The search includes all directories in the EXECUTABLE_PATH CLI variable.

The process identifiers specified in the pid-list must refer to existing processes in the runtime environment. TotalView attaches to the processes, regardless of their execution states.

Command alias: 

 

Alias	Definition	Description
at	dattach	Brings the process under TotalView control

Examples: 

dattach mysys 10020

Loads debugging information for mysys and brings the process known to the run-time system as PID 10020 under TotalView control.

dattach –e 123 10020

Loads file 123 and brings the process known to the run-time system by PID 10020 under TotalView control.

dattach –g 4 –r Enterprise myfile 10020

Loads myfile that is executing on the host named Enterprise into group 4, and brings the process known to the run-time system by PID 10020 under TotalView control. If a TotalView Server (tvdsvr) is not running on Enterprise, the CLI will start it.

dattach my_file 51172 52006

Loads debugging information for my_file and brings the processes corresponding to PIDs 51172 and 52006 under TotalView control.

set new_pid [dattach –e mainprog 123]

dattach –r otherhost –g $CGROUP($new_pid) –e slave 456

Begins by attaching to mainprog running on the local host; then attaches to slave running on the otherhost host and inserts them both in the same control group.