.\" 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_statjob 3B "21 October 2013" Local "PBS Professional"
.SH NAME
pbs_statjob - obtain status of PBS batch jobs
.SH SYNOPSIS
#include <pbs_error.h>
.br
#include <pbs_ifl.h>
.sp
.B struct batch_status *pbs_statjob(\^int\ connect, char\ *id, 
.B struct\ attrl\ *attrib, char *extend)
.sp
.B void pbs_statfree(\^struct batch_status *psj\^)
.SH DESCRIPTION
Issue a batch request to query and return the status of a
specified batch job, a list of batch jobs, or a set of batch jobs at a
queue or server.
.LP
A
.I "Status Job"
batch request is generated and sent to the server over the connection
specified by
.I connect.  

.LP
.SH PARAMETERS
The 
.I connect
parameter is the return value of 
.B pbs_connect().

The 
.I id
parameter can be a job identifier, a list of job identifiers, or a
queue or server identifier.
.LP
.RS 4
If
.I id
is a job identifier, it is the identifier of the job
for which status is requested.  It is specified in the form:
.RS 4
.I "sequence_number.server" 
.br
or, for an array job, 
.br
.I "sequence_number[].server"
.RE
where the first character of the identifier must be a digit.  If the 
identifier is for an array job but the 't' character is not included
in the 
.I extend 
parameter, the status of the array job is returned, but not the status
of its subjobs.  If the 't' character is included, status for each 
subjob is returned.
.LP
If 
.I id
is a list of job identifiers, it must be a comma-separated list of job
identifiers in a single string.  The first character of the string must
be a digit.  White space outside of a job identifier is ignored.  There is 
no limit to the length of the string except as imposed by available memory.

If
.I id
is a destination (server or queue) identifier, the status of all jobs
at the destination which the user is authorized to see is returned.

If
.I id
is the null pointer or a null string, the status of each job at the
server to which the user is connected is returned.
.LP
.RE
The 
.I attrib 
parameter is a pointer to a list of attributes.
If 
.I attrib
is specified, then only the attributes in the list are returned by the server.
Otherwise, all the attributes of a job are returned.
The 
.I attrib
parameter is a pointer to an
.I attrl 
structure which is defined in pbs_ifl.h as:
.sp
.Ty
.nf
    struct attrl {
        struct attrl *next;
        char         *name;
        char         *resource;
        char         *value;
    };
.fi
.sp
.RS 4
The 
.I next
member is a pointer to the next entry in the list.
The
.I attrib
list is terminated by the first entry where
.I next
is a null pointer.  

The
.I name
member is a pointer to an attribute name.  Attribute names are
listed in pbs_ifl.h.

The
.I resource
member specifies the name of the resource in the job's 
.I Resource_List 
attribute.
When 
.I attrl 
describes the job's 
.I Resource_List 
job attribute, the 
.I name 
member is ATTR_l. 
If 
.I attrl 
is not ATTR_l, 
.I resource 
should be a
pointer to a null string.

The
.I value
member should always be a pointer to a null string.
.LP
.RE
The 
.I extend
parameter is used for extensions.  This parameter can consist of
characters in any order.
.RS 4

When the 
.I extend
parameter includes 't', if any array job identifiers are in the set of 
IDs being queried, the
status of each array job is followed by status of each subjob in 
the array job.

When the 
.I extend 
parameter includes 'x', finished and moved jobs and subjobs can be
queried, and their status is included.  Subjobs are not considered
finished until the parent array job is finished.
.RE
.LP

.SH RETURN VALUES and ERRORS
For a single job, if the job can be queried, the return value is a pointer to a
.I batch_status 
structure containing the status of the specified job.
If the job cannot be queried, a NULL pointer is returned, and 
.I pbs_errno 
is set to an error number.

For a list of jobs, if any of the specified jobs can be queried, the
return value is a pointer to a 
.I batch_status 
structure containing the
status of all the queryable jobs.  If none of the jobs can be queried,
a NULL pointer is returned, and 
.I pbs_errno 
is set to the error number
that indicates the reason that the last job in the list could not be 
queried.

For a queue, if the queue exists, the return value is a pointer to a
.I batch_status 
structure containing the status of all the queryable jobs
in the queue.  If the queue does not exist, a NULL pointer is returned, and
.I pbs_errno 
is set to PBSE_UNKQUE (15018).  If the queue exists but contains
no queryable jobs, a NULL pointer ia returned and 
.I pbs_errno 
is set to 
PBSE_NONE (0).

When querying a server, the connection to the server is already
established by
.B pbs_connect().
If there are jobs at the server, the return value of the query is a
pointer to a
.I batch_status 
structure containing the status of all the queryable jobs at the
server.  If the server does not contain any queryable jobs, a NULL
pointer ia returned and 
.I pbs_errno 
is set to PBSE_NONE (0).

The batch_status structure is defined in pbs_ifl.h as
.sp
.Ty
.nf
    struct batch_status {
        struct batch_status *next;
        char                *name;
        struct attrl        *attribs;
        char                *text;
    }
.fi
.LP

It is up the user to free the structure when no longer needed, by calling
\f3pbs_statfree\f1().
.LP


.SH SEE ALSO
qstat(1B) and pbs_connect(3B)