NAME
	  pbs_statjob -	obtain status of batch jobs

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

	  struct batch_status *pbs_statjob(int connect,	char *id,
	  struct attrl *attrib,	char *extend)

	  void pbs_statfree(struct batch_status	*psj)

     DESCRIPTION
	  Issue	a batch	request	to obtain the status of	a specified
	  batch	job or a set of	jobs at	a destination.

	  A Status Job 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, id, may be either a job identifier or a
	  destination identifier.

	  If id	is a job identifier, it	is the identifier of the job
	  for which status is requested.  It is	specified in the form:
	  sequence_number.server

	  If id	is a destination identifier, it	specifies that status
	  of all jobs at the destination (queue) which the user	is
	  authorized to	see be returned.  If id	is the null pointer or
	  a null string, the status of each job	at the server which
	  the user is authorized to see	is returned.

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

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

	  The attrib list is terminated	by the first entry where next
	  is a null pointer.  If attrib	is given, then only the
	  attributes in	the list are returned by the server.
	  Otherwise, all the attributes	of a job are returned.	When
	  an attrib list is specified, the name	member is a pointer to
	  a attribute name as listed in	pbs_alter(3) and
	  pbs_submit(3).  The resource member is only used if the name
	  member is ATTR_l, otherwise it should	be a pointer to	a null
	  string.  The value member should aways be a pointer to a
	  null string.

	  The parameter, extend, is reserved for implementation
	  defined extensions.

	  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_status structure is defined in pbs_ifl.h
	  as

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

	  It is	up the user to free the	structure when no longer
	  needed, by calling pbs_statfree().

     SEE ALSO
	  qstat(1B) 

     DIAGNOSTICS
	  When the batch request generated by pbs_statjob() function
	  has been completed successfully and the status of each job
	  has been returned by the batch server, the routine will
	  return a pointer to the list of batch_status structures.  If
	  no jobs were available to query or an	error occurred,	a null
	  pointer is returned.	The global integer pbs_errno should be
	  examined to determine	the cause.