# -*- text -*-
#
# Copyright (c) 2025-2026 Nanook Consulting  All rights reserved.
# $COPYRIGHT$
#
# Additional copyrights may follow
#
# $HEADER$
#
# This is the US/English general help file for PRTE's dash-host.
#
[host]

Host syntax consists of a comma-delimited list of node names, each
entry optionally containing a ":N" extension indicating the number of
slots to assign to that entry:

   --host node01:5,node02

In the absence of the slot extension, one slot will be assigned to the
node. Duplicate entries are aggregated and the number of slots
assigned to that node are summed together.

Note:

  A "slot" is the PRRTE term for an allocatable unit where we can
  launch a process. Thus, the number of slots equates to the maximum
  number of processes PRRTE may start on that node without
  oversubscribing it.

See the "Host specification" HTML documentation for details about the
format and content of hostfiles.
#
[add-host]

PRRTE allows a user to expand an existing DVM prior to launching an
application.  Users can specify a a comma-delimited list of node
names, each entry optionally containing a ":N" extension indicating
the number of slots to assign to that entry:

   --host node01:5,node02

In the absence of the slot extension, one slot will be assigned to the
node. Duplicate entries are aggregated and the number of slots
assigned to that node are summed together.

Note:

  A "slot" is the PRRTE term for an allocatable unit where we can
  launch a process. Thus, the number of slots equates to the maximum
  number of processes PRRTE may start on that node without
  oversubscribing it.

The list can include nodes that are already part of the DVM — in this
case, the number of slots available on those nodes will be set to the
new specification, or adjusted as directed:

   --host node01:5,node02

would direct that node01 be set to 5 slots and node02 will have 1
slot, while

   --host node01:+5,node02

would add 5 slots to the current value for node01, and

   --host node01:-5,node02

would subtract 5 slots from the current value.

Slot adjustments for existing nodes will have no impact on currently
executing jobs, but will be applied to any new spawn requests. Nodes
contained in the add-host specification are available for immediate
use by the accompanying application.

Users desiring to constrain the accompanying application to the newly
added nodes should also include the "--host" command line directive,
giving the same hosts in its argument:

   --add-host node01:+5,node02 --host node01:5,node02

Note that the "--host" argument indicates the number of slots to
assign node01 for this spawn request, and not the number of slots
being added to the node01 allocation.

#
[not-all-mapped-alloc]

At least one of the requested hosts is not included in the current
allocation.

   Missing requested host: %s

Please check your allocation or your request.
#
[dash-host:relative-node-not-found]

A relative host was specified, but was not found. The requested host
was specified with "--host" as:

   Index: %d
   Syntax given: %s

Re-run this command with "--help hosts" for further information.
#
[dash-host:relative-node-out-of-bounds]

A relative host was specified, but the index given is beyond the
number of hosts in the current allocation:

   Index: %d
   #hosts: %d

You could obtain a larger allocation or reduce the relative host
index.

Re-run this command with "--help hosts" for further information.
#
[dash-host:invalid-relative-node-syntax]

A relative host was improperly specified — the value provided was.

   --host: %s

You may have forgotten to preface a node with "N" or "n", or used the
"e" or "E" to indicate empty nodes, or you ended the value with a
colon but forgot to include the number of empty nodes you were
requesting.

Re-run this command with "--help hosts" for further information.
#
[dash-host:not-enough-empty]

The requested number of empty hosts was not available — the system was
short by %d hosts.  Please recheck your allocation.

Re-run this command with "--help hosts" for further information.
