.\"         OpenPBS (Portable Batch System) v2.3 Software License
.\" 
.\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc.
.\" All rights reserved.
.\" 
.\" ---------------------------------------------------------------------------
.\" For a license to use or redistribute the OpenPBS software under conditions
.\" other than those described below, or to purchase support for this software,
.\" please contact Veridian Systems, PBS Products Department ("Licensor") at:
.\" 
.\"    www.OpenPBS.org  +1 650 967-4675                  sales@OpenPBS.org
.\"                        877 902-4PBS (US toll-free)
.\" ---------------------------------------------------------------------------
.\" 
.\" This license covers use of the OpenPBS v2.3 software (the "Software") at
.\" your site or location, and, for certain users, redistribution of the
.\" Software to other sites and locations.  Use and redistribution of
.\" OpenPBS v2.3 in source and binary forms, with or without modification,
.\" are permitted provided that all of the following conditions are met.
.\" After December 31, 2001, only conditions 3-6 must be met:
.\" 
.\" 1. Commercial and/or non-commercial use of the Software is permitted
.\"    provided a current software registration is on file at www.OpenPBS.org.
.\"    If use of this software contributes to a publication, product, or service
.\"    proper attribution must be given; see www.OpenPBS.org/credit.html
.\" 
.\" 2. Redistribution in any form is only permitted for non-commercial,
.\"    non-profit purposes.  There can be no charge for the Software or any
.\"    software incorporating the Software.  Further, there can be no
.\"    expectation of revenue generated as a consequence of redistributing
.\"    the Software.
.\" 
.\" 3. Any Redistribution of source code must retain the above copyright notice
.\"    and the acknowledgment contained in paragraph 6, this list of conditions
.\"    and the disclaimer contained in paragraph 7.
.\" 
.\" 4. Any Redistribution in binary form must reproduce the above copyright
.\"    notice and the acknowledgment contained in paragraph 6, this list of
.\"    conditions and the disclaimer contained in paragraph 7 in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" 5. Redistributions in any form must be accompanied by information on how to
.\"    obtain complete source code for the OpenPBS software and any
.\"    modifications and/or additions to the OpenPBS software.  The source code
.\"    must either be included in the distribution or be available for no more
.\"    than the cost of distribution plus a nominal fee, and all modifications
.\"    and additions to the Software must be freely redistributable by any party
.\"    (including Licensor) without restriction.
.\" 
.\" 6. All advertising materials mentioning features or use of the Software must
.\"    display the following acknowledgment:
.\" 
.\"     "This product includes software developed by NASA Ames Research Center,
.\"     Lawrence Livermore National Laboratory, and Veridian Information
.\"     Solutions, Inc.
.\"     Visit www.OpenPBS.org for OpenPBS software support,
.\"     products, and information."
.\" 
.\" 7. DISCLAIMER OF WARRANTY
.\" 
.\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT
.\" ARE EXPRESSLY DISCLAIMED.
.\" 
.\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE
.\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\" 
.\" This license will be governed by the laws of the Commonwealth of Virginia,
.\" without reference to its choice of law rules.
.if \n(Pb .ig Iq
.TH pbsdsh 1B "" Local PBS
.\"         OpenPBS (Portable Batch System) v2.3 Software License
.\" 
.\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc.
.\" All rights reserved.
.\" 
.\" ---------------------------------------------------------------------------
.\" For a license to use or redistribute the OpenPBS software under conditions
.\" other than those described below, or to purchase support for this software,
.\" please contact Veridian Systems, PBS Products Department ("Licensor") at:
.\" 
.\"    www.OpenPBS.org  +1 650 967-4675                  sales@OpenPBS.org
.\"                        877 902-4PBS (US toll-free)
.\" ---------------------------------------------------------------------------
.\" 
.\" This license covers use of the OpenPBS v2.3 software (the "Software") at
.\" your site or location, and, for certain users, redistribution of the
.\" Software to other sites and locations.  Use and redistribution of
.\" OpenPBS v2.3 in source and binary forms, with or without modification,
.\" are permitted provided that all of the following conditions are met.
.\" After December 31, 2001, only conditions 3-6 must be met:
.\" 
.\" 1. Commercial and/or non-commercial use of the Software is permitted
.\"    provided a current software registration is on file at www.OpenPBS.org.
.\"    If use of this software contributes to a publication, product, or service
.\"    proper attribution must be given; see www.OpenPBS.org/credit.html
.\" 
.\" 2. Redistribution in any form is only permitted for non-commercial,
.\"    non-profit purposes.  There can be no charge for the Software or any
.\"    software incorporating the Software.  Further, there can be no
.\"    expectation of revenue generated as a consequence of redistributing
.\"    the Software.
.\" 
.\" 3. Any Redistribution of source code must retain the above copyright notice
.\"    and the acknowledgment contained in paragraph 6, this list of conditions
.\"    and the disclaimer contained in paragraph 7.
.\" 
.\" 4. Any Redistribution in binary form must reproduce the above copyright
.\"    notice and the acknowledgment contained in paragraph 6, this list of
.\"    conditions and the disclaimer contained in paragraph 7 in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" 5. Redistributions in any form must be accompanied by information on how to
.\"    obtain complete source code for the OpenPBS software and any
.\"    modifications and/or additions to the OpenPBS software.  The source code
.\"    must either be included in the distribution or be available for no more
.\"    than the cost of distribution plus a nominal fee, and all modifications
.\"    and additions to the Software must be freely redistributable by any party
.\"    (including Licensor) without restriction.
.\" 
.\" 6. All advertising materials mentioning features or use of the Software must
.\"    display the following acknowledgment:
.\" 
.\"     "This product includes software developed by NASA Ames Research Center,
.\"     Lawrence Livermore National Laboratory, and Veridian Information
.\"     Solutions, Inc.
.\"     Visit www.OpenPBS.org for OpenPBS software support,
.\"     products, and information."
.\" 
.\" 7. DISCLAIMER OF WARRANTY
.\" 
.\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS
.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT
.\" ARE EXPRESSLY DISCLAIMED.
.\" 
.\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE
.\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
.\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
.\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\" 
.\" This license will be governed by the laws of the Commonwealth of Virginia,
.\" without reference to its choice of law rules.
.\" The following macros defination, Sh and Sx, are used to allow
.\" PBS man pages to be formatted with either -man macros or 
.\" be included in the PBS ERS which is formatted with -ms.
.\" 
.\" The presence of the register Pb defined as non zero will trigger
.\" the use of the Sx alternate form.  Otherwise the standard -man
.\" SH is used.
.\"
.de Sh
.ie \n(Pb .Sx \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
.el .SH \\$1 \\$2 \\$3 \\$4 \\$5 \\$6
..
.\"
.de Sx
.RE
.sp
.B
\\$1 \\$2 \\$3 \\$4 \\$5 \\$6
.br
.RS
.R
..
.\"
.\" end of special PBS man/ERS macros
.\" --
.\" The following macros are style for object names and values.
.de Ar		\" command/function arguments and operands (italic)
.ft 2
.if \\n(.$>0 \&\\$1\f1\\$2
..
.de Av		\" data item values  (Helv)
.if  \n(Pb .ft 6
.if !\n(Pb .ft 3
.ps -1
.if \\n(.$>0 \&\\$1\s+1\f1\\$2
..
.de At		\" attribute and data item names (Helv Bold)
.if  \n(Pb .ft 6
.if !\n(Pb .ft 2
.ps -1
.if \\n(.$>0 \&\\$1\s+1\f1\\$2
..
.de Ty		\" Type-ins and examples (typewritter)
.if  \n(Pb .ft 5
.if !\n(Pb .ft 3
.if \\n(.$>0 \&\\$1\f1\\$2
..
.de Er		\" Error values ( [Helv] )
.if  \n(Pb .ft 6
.if !\n(Pb .ft 3
\&\s-1[\^\\$1\^]\s+1\f1\\$2
..
.de Sc		\" Symbolic constants ( {Helv} )
.if  \n(Pb .ft 6
.if !\n(Pb .ft 3
\&\s-1{\^\\$1\^}\s+1\f1\\$2
..
.de Al		\" Attribute list item, like .IP but set font and size
.if !\n(Pb .ig Ig
.ft 6
.IP "\&\s-1\\$1\s+1\f1"
.Ig
.if  \n(Pb .ig Ig
.ft 2
.IP "\&\\$1\s+1\f1"
.Ig
..
.\" the following pair of macros are used to bracket sections of code
.de Cs
.ft 5
.nf
..
.de Ce
.sp
.fi
.ft 1
..
.if !\n(Pb .ig Ig
.\" define sting Ji as section heading for Job Ids
.ds Ji 2.7.6
.\" define sting Di as section heading for Destination Ids
.ds Di 2.7.3
.\" define sting Si as section heading for Default Server
.ds Si 2.7.4
.Ig
.\" End of macros 
.Iq
.SH NAME
pbsdsh \- distribute task to nodes under pbs
.SH SYNOPSIS
pbsdsh [\-c copies] [\-o] [\-s] [\-u] [\-v] program [args]
.br
pbsdsh [\-n node] [\-o] [\-s] [\-u] [\-v] program [args]
.br
pbsdsh [\-h nodename] [\-o] [\-v] program [args]
.SH DESCRIPTION
Executes (spawns) a normal Unix program on one or more nodes under control of
the Portable Batch System, PBS.  Pbsdsh uses the Task Manager
API, see tm_spawn(3), to distribute the program on the allocated nodes.
.LP
When run without the \-c or the \-n option, pbsdsh will spawn the program
on all nodes allocated to the PBS job.  The spawns take place concurrently \-
all execute at (about) the same time.
.LP
Users will find the
.B PBS_TASKNUM
,
.B PBS_NODENUM
, and the
.B PBS_VNODENUM
environmental variables useful.  They contain the TM task id, the node
identifier, and the cpu (virtual node) identifier.
.SH OPTIONS
.IP "\-c copies"
The program is spawned on the first
.Ar Copies
nodes allocated.  This option is mutual exclusive with \-n.
.IP "\-n node"
The program is spawned on one node which is the 
.Ar node \-th
node allocted.  This option is mutual exclusive with \-c.
.IP "\-h hostname"
The program is spawned on the node specified.
.IP \-o
Capture stdout of the spawned program.  Normally stdout goes to the job's output.
.IP \-s
If this option is given, the program is run in turn on each 
node, one after the other.
.IP \-u
The program is run once on each node (unique).  This ignores the number
of allocated processers on a given node.
.IP \-v
Verbose output about error conditions and task exit status is produced.
.SH OPERANDS
The first operand,
.Ar program ,
is the program to execute.
.LP
Additional operands,
.Ar args ,
are passed as arguments to the program.
.SH STANDARD ERROR
The pbsdsh command will write a diagnostic message to standard error for
each error occurrence.
.SH EXIT STATUS
Upon successful processing of all the operands presented to the command, the
exit status will be a value of zero.
.LP
If the pbsdsh command fails to process any operand, or fails to contact the
MOM daemon on the localhost the command exits with a value greater than zero.
.SH SEE ALSO
qsub(1B), tm_spawn(3B)
\" turn off any extra indent left by the Sh macro
.RE