pbs_selectjob(3B)

NAME
pbs_selectjob - select PBS batch jobs

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

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

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

The attropl struct contains the list of selection criteria.

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 pbs_connect().

The argument, attrib , 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 attrib 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, resource 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 listed in pbs_job_attributes.7B.

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 selected. 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_number.server@server

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 extensions. Finished and Moved Jobs
In order to get information on finished and moved jobs, you must add an 'x' character to the extend parameter. The extend parameter is a character string; set one character to be the 'x' character. For example:
    pbs_selectjob ( ..., ..., extend) ...

To get information on finished and moved jobs only, specify the Finished ('F') and moved ('M') job states. You must also use the extend character string containing the 'x' character.

Subjobs are not considered finished until the parent array job is finished.

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

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.

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