.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\" FOR A PARTICULAR PURPOSE.
.\" See the GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH pbs_attach 8B "17 October 2017" Local "PBS Professional"
.SH NAME
.B pbs_attach 
\- attach a session ID to a PBS job


.SH SYNOPSIS
.B Linux
.br
.B pbs_attach 
[-j <job ID>] [-m <port>] -p <PID>
.br
.B pbs_attach 
[-j <job ID>] [-m <port>] [-P] [-s] <cmd> [<arg> ...] 
.br
.B pbs_attach 
--version

.B Windows
.br
.B pbs_attach 
[-c <path to script>] [-j <job ID>] [-m <port>] -p <PID>
.br
.B pbs_attach
[-c <path to script>] [-j <job ID>] [-m <port>] [-P] [-s] 
.RS 11
<cmd> [<arg> ...] 
.RE
.br
.B pbs_attach 
--version

.SH DESCRIPTION
The
.B pbs_attach
command associates the processes in a session with 
a PBS job by attaching the session ID to the job.  This allows PBS MoM
to monitor and control those processes.

MoM uses process IDs to determine session IDs, which are
put into MoM's task list (attached to the job.)  All process IDs in 
a session are then associated with the job.

When a command
.I cmd
is given as an operand, 
the 
.B pbs_attach
process becomes the parent process of 
.I cmd, 
and the session ID of 
.B pbs_attach
is attached to the job.  



.SH OPTIONS
.IP "-c <path to script>" 15
Windows only.  Specified command is invoked using a new command shell.
In order to spawn and attach built-in DOS commands such as set or
echo, it is necessary to open the task using a 
.I cmd 
shell.  The new
command shell, 
.I cmd.exe
, is attached as a task to the PBS job.  The
.B pbs_attach 
command spawns a program using a new command shell when
attaching a batch script, or when invoked with the 
.I -c 
option.
.IP "-j <job ID>" 15
The job ID to which the session ID is to be attached.
If 
.I job ID
is not specified,
a best effort is made to determine the job to which to attach
the session.
.IP "-m <port>" 15
The port at which to contact MOM.  Default: value of PBS_MANAGER_SERVICE_PORT
from pbs.conf
.IP "-p <PID>" 15
Process ID whose session ID is to be attached to the job.  
Default: process ID of pbs_attach.
Cannot be used with the 
.I -P 
or
.I -s
options or the 
.I cmd
operand.

.IP "-P" 15
Attach sessions of both 
.B pbs_attach 
and the parent of 
.B pbs_attach 
to job.  
When used with 
.I -s
option, 
the sessions of the new
.B fork()
ed
.B pbs_attach
and its parent, which is 
.B pbs_attach,
are attached to the job.  Cannot be used with the 
.I -p
or
.I -s
options or the 
.I cmd
operand.

.IP "-s" 15
Starts a new session and attaches it to the job: 
.B pbs_attach
calls 
.B fork(), 
then the child
.B pbs_attach
first calls 
.B setsid() 
and then calls 
.B tm_attach
to attach the new session to the job.  The session ID of the new
.B pbs_attach
is attached to the job.

.IP "--version" 15
The 
.B pbs_attach
command returns its PBS version information and exits.
This option can only be used alone.

.SH OPERANDS
.IP "cmd" 15 
Name of command whose process ID is to be associated with the job.


.SH EXIT STATUS
.IP "0" 15 
Success
.IP "1" 15
Any error following successful command line processing.
A message is printed to standard error.
.LP
If 
.I cmd
is specified, 
.B pbs_attach 
waits for
.I cmd
to exit, then exits with the exit value of
.I cmd.
.LP
If 
.I cmd
is not specified, 
.B pbs_attach
exits after attaching the session ID(s) to the job.


.SH SEE ALSO
The
.B PBS Professional Administrator's Guide
.br
pbs_mom(8B), pbs_tmrsh(8B), setsid(2), tm(3)