pbs_selstat (3) - Linux Manuals

pbs_selstat: obtain status of selected pbs batch jobs

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 which is the return value of pbs_connect().

The parameter, 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 list is terminated by the first entry where is a null pointer.

The 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 member points to a string which is the name of a resource. This member is only used when is set to ATTR_l, otherwise it should be a pointer to a null string. The 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

#define ATTR_m Mail_Points

Select (E) based upon the setting of the mail points attribute.

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

#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 member defines the operator in the logical expression:

The logical expression must evaluate as true for the job to be selected. The permissible values of are defined in pbs_ifl.h as: The attributes marked with (E) in the description above may only be selected with the equal, EQ, or not equal, NE, operators.

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

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

The entry, 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, is reserved for implementation defined extensions. TORQUE 2.0.0p1 added the #define'd constant string EXECQUEONLY to only retrieve jobs in execution queues.

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.