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

FreeBSD Manual Pages

  
 
  

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

NAME
       pbs_selstat - obtain status of selected pbs batch jobs

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

       struct batch_status *pbs_selstat(int connect, struct attropl *sel_list,
       char *extend)

       void pbs_statfree(struct	batch_status *psj)

DESCRIPTION
       Issue  a	batch request to examine the status of jobs which meet certain
       criteria.  pbs_selstat()	returns	a list of batch_status structures  for
       those jobs which	met the	selection criteria.

       This  function  is a combination	of pbs_selectjobs() and	pbs_statjob().
       It is an	extension to the POSIX Batch standard.

       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	Status batch request is	generated and sent to the server  over
       the  connection	specified  by  connect	which  is  the return value of
       pbs_connect().

       The parameter, sel_list,	is a pointer to	an attropl structure which  is
       defined in pbs_ifl.h as:

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

       The sel_list list is terminated by the first entry where	next is	a null
       pointer.

       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 it
       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 attribute
       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
		     file.

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

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

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

	      #define ATTR_p "Priority"
		     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
		     jobs.

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

	      #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  sel_list itself is a	null pointer, then no selection	is done	on the
       basis of	attributes.

       The return value	is a pointer to	a list of batch_status	structures  or
       the  null pointer if no jobs can	be queried for status.	The batch_sta-
       tus structure is	defined	in pbs_ifl.h as

	   struct batch_status {
	       struct batch_status *next;
	       char		   *name;
	       struct attrl	   *attribs;
	       char		   *text;
	   }

       The entry, attribs, is a	pointer	to a list of attrl structures  defined
       in pbs_ifl.h as:

	   struct attrl	{
	       struct attrl *next;
	       char	    *name;
	       char	    *resource;
	       char	    *value;
	   };

       It  is  up the user to free the list of batch_status structures when no
       longer needed, by calling pbs_statfree().

       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.

SEE ALSO
       qselect(1B), pbs_alterjob(3B),  pbs_connect(3B),	 pbs_statjob(3B),  and
       pbs_selectjob(3B).

DIAGNOSTICS
       When  the  batch	 request  generated by pbs_selstat() function has been
       completed successfully by a batch server, the  routine  will  return  a
       pointer	to  the	 list  of batch_status structures.  If no jobs met the
       criteria	or an error occurred, the return will be the null pointer.  If
       an  error  occurred, the	global integer pbs_errno will be set to	a non-
       zero value.

Local							       pbs_selstat(3B)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | DIAGNOSTICS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pbs_selstat&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help