279 lines
10 KiB
Groff
279 lines
10 KiB
Groff
.\" 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 Ig
|
|
.TH pbs_selectjob 3B "" Local PBS
|
|
.so ../ers/ers.macros
|
|
.Ig
|
|
.SH NAME
|
|
pbs_selectjob \- select pbs batch jobs
|
|
.SH SYNOPSIS
|
|
#include <pbs_error.h>
|
|
.br
|
|
#include <pbs_ifl.h>
|
|
.sp
|
|
.ft 3
|
|
.nf
|
|
char **pbs_selectjob(\^int\ connect, struct\ attropl\ *attrib, char\ *extend\^)
|
|
.fi
|
|
.ft 1
|
|
.SH DESCRIPTION
|
|
Issue a batch request to select jobs which meet certain criteria.
|
|
\fBpbs_selectjob\fP() returns a array of job identifiers which met the criteria.
|
|
.LP
|
|
Initially all batch jobs are selected for which the user is authorized to
|
|
query status.
|
|
This set may be reduced or filtered by specifying certain attributes
|
|
of the jobs.
|
|
.LP
|
|
A
|
|
.I "Select Jobs"
|
|
batch request is generated and sent to the server over the connection
|
|
specified by
|
|
.Ar connect
|
|
which is the return value of \fBpbs_connect\fP().
|
|
.LP
|
|
The argument,
|
|
.Ar attrib ,
|
|
is a pointer to an
|
|
.I attropl
|
|
structure which is defined in pbs_ifl.h as:
|
|
.sp
|
|
.Ty
|
|
.nf
|
|
struct attropl {
|
|
struct attropl *next;
|
|
char *name;
|
|
char *resource;
|
|
char *value;
|
|
enum batch_op op;
|
|
};
|
|
.fi
|
|
.sp
|
|
.ft 1
|
|
The
|
|
.Ar attrib
|
|
.ft 1
|
|
list is terminated by the first entry where
|
|
.Ty next
|
|
is a null pointer.
|
|
.LP
|
|
The
|
|
.Ty name
|
|
member points to a string which is the name of the attribute.
|
|
Not all of the job attributes may be used as a selection criteria.
|
|
The
|
|
.Ty resource
|
|
member points to a string which is the name of a resource. This
|
|
member is only used when
|
|
.Ty name
|
|
is set to ATTR_l.
|
|
Otherwise, resource should be a pointer to a null string.
|
|
The
|
|
.Ty value
|
|
member points to a string which is the value of the attribute or resource.
|
|
The attribute names are defined in pbs_ifl.h:
|
|
.br
|
|
.RS
|
|
.IP #define\ ATTR_a\ "Execution_Time"
|
|
Select based upon the job's execution time.
|
|
.IP #define\ ATTR_A\ "Account_Name"
|
|
Select (E) based upon the account string.
|
|
.IP #define\ ATTR_c\ "Checkpoint"
|
|
Select based upon the checkpoint interval.
|
|
.IP #define\ ATTR_e\ "Error_Path"
|
|
Select (E) based upon the name of the standard error file.
|
|
.IP #define\ ATTR_g\ "Group_List"
|
|
Select (E) based upon the list of group names under which the job may execute.
|
|
.IP #define\ ATTR_h\ "Hold_Types"
|
|
Select (E) based upon the hold types.
|
|
.IP #define\ ATTR_j\ "Join_Paths"
|
|
Select (E) based upon the value of the join list.
|
|
.IP #define\ ATTR_k\ "Keep_Files"
|
|
Select (E) based upon the value of the keep files list.
|
|
.IP #define\ ATTR_l\ "Resource_List"
|
|
Select based upon the value of the resource named in
|
|
.Ty resource .
|
|
.IP #define\ ATTR_m\ "Mail_Points"
|
|
Select (E) based upon the setting of the mail points attribute.
|
|
.IP #define\ ATTR_M\ "Mail_Users"
|
|
Select (E) based upon the list of user names to which mail will be sent.
|
|
.IP #define\ ATTR_N\ "Job_Name"
|
|
Select (E) based upon the job name.
|
|
.IP #define\ ATTR_o\ "Output_Path"
|
|
Select (E) based upon the name of the standard output file.
|
|
.IP #define\ ATTR_p\ "Rriority"
|
|
Select based upon the priority of the job.
|
|
.IP #define\ ATTR_q\ "destination"
|
|
Select based upon the specified destination.
|
|
Jobs selected are restricted to those residing in the named queue.
|
|
If destination is the null string, the default queue at the server
|
|
is assumed.
|
|
.IP #define\ ATTR_r\ "Rerunable"
|
|
Select (E) based upon the rerunable flag.
|
|
.IP #define\ ATTR_session\ "session_id"
|
|
Select based upon the session id assigned to running jobs.
|
|
.IP #define\ ATTR_S\ "Shell_Path_List"
|
|
Select (E) based upon the execution shell list.
|
|
.IP #define\ ATTR_u\ "User_List"
|
|
Select (E) based upon the owner of the jobs.
|
|
.IP #define\ ATTR_v\ "Variable_List"
|
|
Select (E) based upon the list of environment variables.
|
|
.IP #define\ ATTR_ctime\ "ctime"
|
|
Select based upon the creation time of the job.
|
|
.IP #define\ ATTR_depend\ "depend"
|
|
Select based upon the list of job dependencies.
|
|
.IP #define\ ATTR_mtime\ "mtime"
|
|
Select based upon the last modification time of the job.
|
|
.IP #define\ ATTR_qtime\ "qtime"
|
|
Select based upon the time of the job was placed into the current queue.
|
|
.IP #define\ ATTR_qtype\ "queue_type"
|
|
Select (E) base on the type of queue in which the job resides.
|
|
.IP #define\ ATTR_stagein\ "stagein"
|
|
Select based upon the list of files to be staged-in.
|
|
.IP #define\ ATTR_stageout\ "stageout"
|
|
Select based upon the list of files to be staged-out.
|
|
.IP #define\ ATTR_state\ "job_state"
|
|
Select based upon the state of the jobs. State is not a job attribute,
|
|
but is included here to allow selection.
|
|
.RE
|
|
.LP
|
|
The
|
|
.Ty op
|
|
member defines the operator in the logical expression:
|
|
.br
|
|
.Ty \ \ \ \ value\ operator\ current_value
|
|
.br
|
|
The logical expression must evaluate as true for the job to be selected.
|
|
The permissible values of
|
|
.Ty op
|
|
are defined in pbs_ifl.h as:
|
|
.Ty "enum batch_op { ..., EQ, NE, GE, GT, LE, LT, ... };" .
|
|
The attributes marked with (E) in the description above may only be selected
|
|
with the equal, EQ, or not equal, NE, operators.
|
|
.if !\n(Pb .ig Ig
|
|
.LP
|
|
The full range of batch_op values is
|
|
.Ty "{ SET, UNSET, INCR, DECR, EQ, NE, GE, GT, LE, LT }."
|
|
Only the relational operators are allowed
|
|
in a select call, and others will be rejected by the server.
|
|
.Ig
|
|
.LP
|
|
If
|
|
.Ar attrib
|
|
itself is a null pointer, then no selection is done on
|
|
the basis of attributes.
|
|
.LP
|
|
The return value is a pointer to a null terminated array of character pointers.
|
|
Each character pointer in the array points to a character string which is a
|
|
.IR job_identifier
|
|
in the form:
|
|
.Ty sequence_number.server@server
|
|
.LP
|
|
The array is allocated by pbs_selectjob via \fBmalloc\fP().
|
|
When the array is no longer needed, the user is responsible for freeing it
|
|
by a call to \fBfree\fP().
|
|
.if !\n(Pb .ig Ig
|
|
The space for the array and the job identifier strings is malloc-ed by
|
|
\fBpbs_selectjob\fP() as one allocation.
|
|
The array of pointers starts at the address
|
|
returned by malloc(), so free() will work.
|
|
.Ig
|
|
.LP
|
|
The parameter,
|
|
.Ar extend ,
|
|
is reserved for implementation defined extensions. TORQUE 2.0.0p1 added the
|
|
#define'd constant string EXECQUEONLY to only retrieve jobs in execution
|
|
queues.
|
|
.if !\n(Pb .ig Ig
|
|
It is not
|
|
currently used by this function.
|
|
.Ig
|
|
.SH "SEE ALSO"
|
|
qselect(1B), pbs_alterjob(3B), and pbs_connect(3B)
|
|
.SH DIAGNOSTICS
|
|
When the batch request generated by
|
|
pbs_selectjob()
|
|
function has been completed successfully by a batch server, the routine will
|
|
return a pointer to the array of job identifiers.
|
|
If no jobs met the criteria, the first pointer in the array will be the
|
|
null pointer.
|
|
.LP
|
|
If an error occurred, a null pointer is returned and the error is available
|
|
in the global integer pbs_errno.
|
|
\" turn off any extra indent left by the Sh macro
|
|
.RE
|