This section describes PSE-related environment variables and run- time command-line options.
PSE-related environment variables are usually defined in a file
(such as .login or .cshrc ) that is
executed whenever you log in. These environment variables define
your general PSE environment. The syntax for using PSE environment
variables is as follows:
setenv variable_name value[,value . . . ]
variable_name=value[,value . . . ] export variable_name
Command-line options can be used to further tailor the PSE environment to meet an application's requirements and if defined, override any corresponding value set by a PSE environment variable. Unrecognized command-line options are passed to the application.
Table 8-1 lists PSE's command- line options and the corresponding environment variables. A detailed description of each option is found in the following sections of this chapter.
| Command-Line Option | Environment Variable | Description |
|---|---|---|
-bind_to_cpu | HPF_BIND_
TO_CPU | Causes peers landing on an SMP machine to bind themselves to a particular CPU, preventing process migration. |
-c protocol-
list | HPF_COMM |
Specifies communications methods to be used for program execution. |
-connections
| Displays a matrix of what communications medium and protocol is used between PSE cluster members. | |
-debug |
Indicates that a debugging session be started for the application. | |
-exclude
member-list | PSE_EXCLUDE
| Defines a set of PSE cluster members to be excluded from application execution. |
-
farm farm-ident | PSE_FARM
| Specifies the PSE cluster on which an application executes. |
-loadserver
member-list | PSE_LOADSERVER
| Indicates the machines that can be queried to provide load information. |
-
local | PSE_LOCAL |
Executes an application developed for PSE in scalar mode on your local machine rather in parallel across the cluster. |
-login
-nologin | PSE_LOGIN |
Specifies whether the local execution environment should be inherited or set by the remote login process. |
-mc_no_errck | Indicates that Memory Channel should not be checked for errors after each message transfer. | |
-
N filespec | Indicates that the names of the PSE cluster members used by an application be placed into a file. | |
-n
| Indicates that the names of
the PSE cluster members used by an application be sent to
stdout . | |
-on
member-list | PSE_ON |
Defines the ordered set of PSE cluster members in the current partition on which you want an application to run. |
-partition identifier |
PSE_PARTITION | Selects the partition in which an application runs. |
-
peers n | PSE_PEERS
| Sets the number of peers for an application that was compiled for a non-specific number of peers. |
-physical
-virtual | PSE_MACHINE
| Specifies physical or virtual mode in case the number of peers exceeds the number of CPUs. |
-pref_comm pref-comm-spec |
PSE_PREF_COMM | Specifies communications medium. |
-
priority n | PSE_PRIORITY
| Sets execution priority for processes your application generates. |
-
pvmhostfile filespec | PSE_
PVMHOSTFILE | Indicates the PVM hostfile to be used to specify the PSE cluster members on which an application executes. |
-stdin
peer-number | PSE_STDIN
| Redirects input from your local machine to one or more peers. |
-timeout
n | HPF_RECV_TIMEOUT |
Defines the receive timeout in seconds. |
-use member-list | PSE_
USE | Defines the unordered set of PSE cluster members in the current partition on which the application can run. |
-verbose |
Display run-time information. | |
PSE_CORE_DIR |
Specifies the directory in which the core dump subdirectories are created. |
HPF_BIND_TO_CPU and -bind_to_cpu cause
any peers that land on an SMP machine to bind themselves to a
particular CPU, preventing process migration, enabling any private
cycle-counter-based profiling methods (and other CPU-specific
activities) to be valid.
The syntax is as follows:
Environment variable (C shell):
% setenv HPF_BIND_TO_CPU string
where string can be TRUE or FALSE.
Command-line option:
% my_program -bind_to_cpu
By default, PSE chooses the appropriate protocol based on the communications medium connecting any two PSE cluster members.
The HPF_COMM environment variable and the
-c command-line option allow you to specify an
ordered, comma-separated preference list for communications
protocol.
The syntax is as follows:
Environment variable (C shell):
% setenv HPF_COMM protocol-list
Command-line option:
% my_program -c protocol-list
The following protocol types are supported:
The -connections command-line option displays a chart
of what medium and protocol is used for communications between any
two PSE cluster members.
The syntax is as follows:
% my_program -connections
Use PSE_CORE_DIR to have core dumps placed in a
subdirectory of the directory you specify.
By default, if an application exits due to an error and a core
dump is produced, each peer generates its own core dump file
(core ) in a subdirectory of the working directory.
PSE creates these subdirectories (one per peer) automatically
and names them core.0 , core.1 , . . . ,
core.n . The core file for each peer is
written to a specific subdirectory so that they do not overwrite
each other.
The directory you specify must already exist. PSE does not create
the directory you specify in PSE_CORE_DIR . If the
directory is not contained within the working directory, you must
specify the path to the directory.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_CORE_DIR directory_name
The -debug option indicates that a debugging session
should be started for the current application.
If -debug is used, the
-c,-bind_to_cpu,-timeout , and -verbose
runtime options should be excluded from the initial command line.
They can be included as arguments to the debugger run command.
The syntax is as follows:
Command-line option:
% my_program -debug
PSE_FARM and -farm specify the PSE
cluster on which an application executes.
This environment variable and command-line option identify the name
of the PSE cluster on which you want to execute an application,
whether you invoke the application from a PSE cluster member or a
non-PSE-cluster member. The PSE cluster name is associated with a
service port number in the /etc/services file.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_FARM clustername
Command-line option:
% my_program -farm clustername
.cshrc or
.login . If the environment variable is not defined,
the command-line option should be specified when executing an
application. If no command-line option is used, psefarm
is used as the default.
PSE_LOADSERVER and -loadserver specify
a comma-separated list of PSE cluster members that can be queried
by the application for system load information. A load server must
be a PSE cluster member, but does not have to be a member of any
partition in the cluster.
By default, applications query the PSE cluster daemon for load information, which forwards the request to an actual load server.
When the machine where the application is invoked is not a
member of the PSE cluster, the environment variable PSE_
LOADSERVER or the command-line must be set.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_LOASERVER member-list
Command-line option:
% my_program -loadserver member-list
PSE_LOCAL and -local allow
applications compiled with no argument or an argument of 1 to the
-wsf option to be run in scalar mode.
The syntax of the PSE_LOCAL is as follows:
Environment variable (C shell):
% setenv PSE_LOCAL string
where string can be TRUE or FALSE
Command-line option:
% my_program -local
PSE_LOGIN , -login and -
nologin indicate whether the default environment local to
each peer is to be used instead of propagating the controlling
process' environment to all peers.
The default is -nologin .
The -login option, or setting PSE_LOGIN
to the string TRUE is equivalent to:
$home
.cshrc
.cshrc
The -nologin (default) option is equivalent to:
cwd of "controlling process"
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_LOCAL string
where string can be TRUE or FALSE.
Command-line option:
% my_program
PSE_PARTITION and -partition select the
partition in which an application runs.
In order to set this variable or use this option, you must know the names and characteristics of the partitions defined. You can display the partition names and characteristics using the lspart(1) command, as follows:
% lspart -farm clustername -all
PSE_PARTITION or -partition must be used
to override the
PSE_DEFAULT_PARTITION specified by the PSE
administrator.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_PARTITION partition-name
Command-line option:
% my_program -partition partiton-name
where partition name is name of a valid PSE partition.
PSE_MACHINE , -physical and
-virtual determine whether the peers used by an
application are physical or virtual processors.
The default is -physical .
The command-line options -virtual and -
physical do not take an argument.
The -virtual option allows the number of PSE peers
to be greater than the number of available CPUs. For example, a
program requiring six peers requires the virtual mode set in order
to execute in a partition containing only 4 CPUs.
Use of virtual processing may degrade PSE performance.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_MACHINE string
where string is "physical" or "virtual".
Command-line option:
% my_program -physical % my_program -virtual
Use PSE_ON or -on to define the PSE
cluster members in the current partition the application must run
on.
The arguments accompanying the -on option should be a
list of PSE cluster members separated by commas. Each member listed
must be configured into the current partition. If you specify a
PSE cluster member that is not part of the current partition, the
application exits with an error message.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_ON member-list
Command-line option:
% my_program -on member-list
where member-list is an ordered list of PSE cluster members.
PSE_PEERS and -peers n set the
number of peer processes used for an application compiled with no
argument to the -wsf option.
If no value is specified for PSE_PEERS or
-peers n, the number of peer processes started
for such applications is equal to the number of available CPUs in
the partition.
In order to start more peer processes than the number of available
CPUs, you must run using the -virtual run-time option.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_PEERS n
Command-line option:
% my_program -peers n
where n is an integer number of peer processes.
PSE_PEERS environment variable and
the -peers n command-line option, see Section 8.4.2.
-virtual run-time option, see
Sections 8.2.5 and 8.5.1.11.
PSE_PRIORITY and -priority set the
priority for the peer processes a controlling process generates.
The system conforms to the POSIX scheme for a range of settings (0-63).
The value of PSE_PRIORITY or the argument n to
-priority must be set carefully. Setting a priority
too high may effectively prevent all other users, including
interactive users, from using the cluster members upon which the
application is executing.
A system variable, PSE_PRIORITY_LIMIT , is
the default maximum setting if no other values are set. If
PSE_PRIORITY_LIMIT is not set, the enforced priority
limit is 19.
The PSE cluster database variable, PSE_DEFAULT_PRIORITY
, allows the PSE administrator to set a default value, which
normally should not exceed 30.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_PRIORITY n
Command-line option:
% my_program -priority n
where n is a valid POSIX scheduling priority.
PSE_PVMHOSTFILE and -pvmhostfile specify
a Parallel Virtual Machine (PVM) hostfile that can be used to
specify the PSE cluster members on which an application executes.
If the file you specify does not reside in the current directory, the path to the specified file must be included.
Using this PSE option has the same effect as defining PSE_
ON or using -on , except that the PSE cluster
members' names are contained in a separate PVM file rather than
directly specified.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_PVMHOSTFILE filespec
Command-line option:
% my_program -pvmhostfile filespec
PSE_STDIN and -stdin redirect input from
your local machine to one or more peers.
By default input is directed to Peer 0. However, if you have an
application that requires input supplied to a peer that is not Peer
0, the -stdin command-line option or the environment
variable should be set to the specified peer number.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_STDIN peer-number
Command-line option:
% my_program -stdin peer-number
where peer-number is the number of a valid peer process or -1 to indicate that input is to be broadcast to all peers.
HPF_RECV_TIMEOUT and -timeout allow you
to specify a timeout period in seconds. This dictates how long an
application waits to receive a message before exiting abnormally.
The default is to wait forever.
The syntax is as follows:
Environment variable (C shell):
% setenv HPF_RECV_TIMEOUT seconds
Command-line option:
% my_program -timeout seconds
The -N option specifies that the names of the PSE
cluster members that an application uses be placed in a file. The
file is created when program execution begins.
The -n option specifies that the names of the
PSE cluster members that an application uses be sent to
stdout .
Use the -n option when you want to know which peers an
application is using but you do not necessarily need the names saved
in a file.
The -verbose option indicates that run-time
information is to be displayed during application execution.
The PSE_EXCLUDE and -exclude option
defines a set of PSE cluster members to be excluded from the peer
selection process.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_EXCLUDE member-list
Command-line option:
% my_program -exclude member-list
where member-list is a list of PSE cluster members separated by commas.
Use PSE_PREF_COMM and -pref_comm to
specify the order of preference for available communications media.
The syntax of the PSE_PREF_COMM definition is as
follows:
Environment variable (C shell):
% setenv PSE_PREF_COMM pref-comm-spec
Command-line option:
% my_program -pref_comm pref-comm-spec
pref-comm-spec is a list containing one or more communication-medium specifiers. The specifiers currently supported are:
The PSE cluster database can also define additional specifiers in the following form:
pref-comm-symbol=subnet.mask
For example:
PSE_PREF_COMM shm, pse_fddi=12.144.32.0
Only the administrator of a PSE database can define additional
specifiers of this form. It is not valid as an environment variable
definition. However, users can view the available specifiers with
lspart , and can select the additional specifiers in
the same way as they can select the pre-defined specifiers. In the
above example, users may select fddi preferentially
over shm by giving the symbol pse_fddi as
an argument to the -pref_comm run-time option:
% myprogram -pref_comm pse_fddi
The order in which the specifiers are listed determines PSE's preference in choosing a communications medium between any two peers. It is generally desirable to put higher-bandwidth media at the beginning of the list, and lower-bandwidth media at the end of the list.
The default setting for PSE_PREF_COMM is:
PSE_PREF_COMM shm,mc,atm,fddi,ethernet
For installations having specialized communications needs, a pref-comm-spec list can also include a definition of the form:
pref-comm-symbol=subnet.mask
For example:
PSE_PREF_COMM shm, pse_fddi=12.144.32.0
This customization method is particularly useful when machines
are interconnected using more than one adapter of the same type
and where the desired adapter for PSE/HPF usage has been defined
to be in a specific subnet. In the above example, users may
select fddi preferentially over shm by
giving the symbol pse_fddi as an argument to the
-pref_comm run-time option:
% myprogram -pref_comm pse_fddi
The PSE_USE and -use option is similar to
PSE_ON in that it defines the PSE cluster members
in the current partition on which the application runs. Unlike
PSE_ON , however, no peer order is implied. In other
words, peer ordering is selected according to load balancing
considerations.
The arguments that accompany the -use option should be
comma separated list of members of a PSE partition.
Each member listed must be configured into the current
PSE_PARTITION or the application exits with an error
message.
The syntax is as follows:
Environment variable (C shell):
% setenv PSE_USE member-list
Command-line option:
% my_program -use member-list
The PSE-related environment variables are used exclusively with the
PSE profiler, pprof .
The profiling process has three phases:
Profiler environment variables are used to set parameters applied during the data output or analysis phases.
pprof profiler, see Chapter 10.
