Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
pbs_selectjob(3B)		      PBS		     pbs_selectjob(3B)

       pbs_selectjob - select pbs batch	jobs

       #include	<pbs_error.h>
       #include	<pbs_ifl.h>

       char **pbs_selectjob(int	connect, struct	attropl	*attrib, char *extend)

       Issue  a	 batch	request	 to  select  jobs which	meet certain criteria.
       pbs_selectjob() returns a array of job identifiers which	met the	crite-

       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.

       A  Select  Jobs	batch request is generated and sent to the server over
       the connection specified	by  connect  which  is	the  return  value  of

       The argument, attrib, is	a pointer to an	attropl	structure which	is de-
       fined in	pbs_ifl.h as:

	   struct attropl {
	       struct attropl *next;
	       char	      *name;
	       char	      *resource;
	       char	      *value;
	       enum batch_op   op;

       The attrib list is terminated by	the first entry	where next is  a  null

       The  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
       resource	 member	 points	 to  a string which is the name	of a resource.
       This member is only used	when name is set to  ATTR_l.   Otherwise,  re-
       source  should  be a pointer to a null string.  The value member	points
       to a string which is the	value of the attribute or resource.   The  at-
       tribute names are defined in pbs_ifl.h:

	      #define ATTR_a "Execution_Time"
		     Select based upon the job's execution time.

	      #define ATTR_A "Account_Name"
		     Select (E)	based upon the account string.

	      #define ATTR_c "Checkpoint"
		     Select based upon the checkpoint interval.

	      #define ATTR_e "Error_Path"
		     Select  (E)  based	 upon  the  name of the	standard error

	      #define ATTR_g "Group_List"
		     Select (E)	based upon the list of group names under which
		     the job may execute.

	      #define ATTR_h "Hold_Types"
		     Select (E)	based upon the hold types.

	      #define ATTR_j "Join_Paths"
		     Select (E)	based upon the value of	the join list.

	      #define ATTR_k "Keep_Files"
		     Select (E)	based upon the value of	the keep files list.

	      #define ATTR_l "Resource_List"
		     Select  based upon	the value of the resource named	in re-

	      #define ATTR_m "Mail_Points"
		     Select (E)	based upon the setting of the mail points  at-

	      #define ATTR_M "Mail_Users"
		     Select  (E)  based	 upon  the list	of user	names to which
		     mail will be sent.

	      #define ATTR_N "Job_Name"
		     Select (E)	based upon the job name.

	      #define ATTR_o "Output_Path"
		     Select (E)	based upon the name  of	 the  standard	output

	      #define ATTR_p "Rriority"
		     Select based upon the priority of the job.

	      #define ATTR_q "destination"
		     Select  based  upon  the specified	destination.  Jobs se-
		     lected are	restricted to  those  residing	in  the	 named
		     queue.   If  destination  is the null string, the default
		     queue at the server is assumed.

	      #define ATTR_r "Rerunable"
		     Select (E)	based upon the rerunable flag.

	      #define ATTR_session "session_id"
		     Select based upon the  session  id	 assigned  to  running

	      #define ATTR_S "Shell_Path_List"
		     Select (E)	based upon the execution shell list.

	      #define ATTR_u "User_List"
		     Select (E)	based upon the owner of	the jobs.

	      #define ATTR_v "Variable_List"
		     Select (E)	based upon the list of environment variables.

	      #define ATTR_ctime "ctime"
		     Select based upon the creation time of the	job.

	      #define ATTR_depend "depend"
		     Select based upon the list	of job dependencies.

	      #define ATTR_mtime "mtime"
		     Select based upon the last	modification time of the job.

	      #define ATTR_qtime "qtime"
		     Select based upon the time	of the job was placed into the
		     current queue.

	      #define ATTR_qtype "queue_type"
		     Select (E)	base on	the type of queue in which the job re-

	      #define ATTR_stagein "stagein"
		     Select based upon the list	of files to be staged-in.

	      #define ATTR_stageout "stageout"
		     Select based upon the list	of files to be staged-out.

	      #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.

       The op member defines the operator in the logical expression:
	   value operator current_value
       The logical expression must evaluate as true for	 the  job  to  be  se-
       lected.	The permissible	values of op are defined in pbs_ifl.h as: 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 attrib itself	is a null pointer, then	no selection is	 done  on  the
       basis of	attributes.

       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	 job_identifier	 in  the  form:	 sequence_num-

       The array is allocated by pbs_selectjob via malloc().  When  the	 array
       is  no  longer needed, the user is responsible for freeing it by	a call
       to free().

       The parameter, extend, is reserved for  implementation  defined	exten-
       sions.	TORQUE 2.0.0p1 added the #define'd constant string EXECQUEONLY
       to only retrieve	jobs in	execution queues.

       qselect(1B), pbs_alterjob(3B), and pbs_connect(3B)

       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.

       If  an  error  occurred,	 a  null  pointer is returned and the error is
       available in the	global integer pbs_errno.

Local							     pbs_selectjob(3B)


Want to link to this manual page? Use this URL:

home | help