Replacement Characters

When placing a tvdsvr command in a Server Launch or Bulk Launch string (see the File > Preferences command within the online Help for more information), you will need to use special replacement characters. When your program needs to launch a remote process, TotalView replaces these command characters with what they represent. Here are the replacement characters:

%A

Expands to the ALPS Application ID (apid), which is a unique identifier for an application started using ALPS aprun on Cray XT, XE, and XK. The token is used to construct server path references copied onto the compute nodes' ramdisk under the /var/spool/alps/apid directory by the ALPS Tool Helper library.

%B

Expands to the bin directory where tvdsvr is installed.

%C

Is replaced by the name of the server launch command being used. On most platforms, this is ssh -x. On Sun SPARC, this command is rsh. If the TVDSVRLAUNCHCMD environment variable exists, TotalView will use its value instead of its platform-specific value.

%D

Is replaced by the absolute path name of the directory to which TotalView will be connected.

%F

Contains the “tracer configuration flags” that need to be sent to tvdsvr processes. These are system-specific startup options that the tvdsvr process needs.

%H

Expands to the host name of the machine upon which TotalView is running. (This replacement character is most often used in bulk server launch commands. However, it can be used in a regular server launch and within a tvdsvr command contained within a temporary file.)

%I

Expands to the pid of the MPI starter process. For example, it can contain mpirun, aprun, etc. It can also be the process to which you manually attach. If no pid is available, %I expands to 0.

%J

Expands to the job ID. For MPICH or poe jobs, is the contents of the totalview_jobid variable contained either in the starter or first process. If that variable does not exist, it is set to zero (“0”). If it is not appropriate for the kind of job being launched, its value is -1.

%K

Expands to the tvdsvr platform suffix string in situations where a different server must be used. On Blue Gene/L and Blue Gene/P, the %K expansion includes _bgl, on Blue Gene/Q it includes _bgq, and on Cray XT3 Catamount (RedStorm) it includes _rs.

When MRNet is being used as the debugger infra-structure, _mrnet is appended to the normal %K expansion. On Cray XT with MRNet enabled the %K token is expanded to _mrnet, while on Blue Gene/L or Blue Gene/P with MRNet enabled the %K token is expanded to _bgl_mrnet. This convention allows MRNet-specific debugger servers to be launched only when MRNet is being used as the debugger infrastructure.

%L

If TotalView is launching one process, this is replaced by the host name and TCP/IP port number (hostname:port) on which TotalView is listening for connections from tvdsvr.

If a bulk launch is being performed, TotalView replaces this with a comma-separated list of the host names and TCP/IP port numbers (hostname:port,hostname:port...) on which TotalView is listening for connections from tvdsvr.

For more information, see Chapter 4, “Setting Up Remote Debugging Sessions” in the TotalView Users Guide.

%M

(Sun) Expands to the command name used for a local server launch.

%N

Is replaced by the number of servers that TotalView will launch. This is only used in a bulk server launch command.

%P

If TotalView is launching one process, this is replaced by the password that it automatically generated.

If a bulk launch is being performed, TotalView replaces this with a comma-separated list of 64-bit passwords.

%R

Is replaced by the host name of the remote machine specified in the File > New Program command. When performing a bulk launch, this is replaced by a comma-separated list of the names of the hosts upon which TotalView will launch tvdsvr processes.

%S

If TotalView is launching one process, it replaces this symbol with the port number on the machine upon which TotalView is running.

If a bulk server launch is being performed, TotalView replaces this with a comma-separated list of port numbers.

%t1 and %t2

Is replaced by files that TotalView creates containing information it generates. This is only available in a bulk launch.

These temporary files have the following structure:

(1) An optional header line containing initialization commands required by your system.

(2) One line for each host being connected to, containing host-specific information.

(3) An optional trailer line containing information needed by your system to terminate the temporary file.

The File > Preferences Bulk Server Page allows you to define templates for the contents of temporary files. These files may use these replacement characters. The %N, %t1, and %t2 replacement characters can only be used within header and trailer lines of temporary files. All other characters can be used in header or trailer lines or within a host line defining the command that initiates a single-process server launch. In header or trailer lines, they behave as defined for a bulk launch within the host line. Otherwise, they behave as defined for a single-server launch.

%U

(Sun) Expands to the local socket ID.

%V

Is replaced by the current TotalView verbosity setting.

%Z

Expands to the job ID. For MPICH or poe jobs, is the contents of the totalview_jobid variable contained either in the starter or first process. If that variable does not exist, it is set to zero (“0”). If it is not appropriate for the kind of job being launched, its value is -1.