pbs_statjob(3B)

NAME
pbs_statjob - obtain status of PBS 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 query and return the status of a specified batch job, a list of batch jobs, or a set of batch jobs at a queue or server.

A Status Job batch request is generated and sent to the server over the connection specified by connect.

PARAMETERS
The connect parameter is the return value of pbs_connect(). The id parameter can be a job identifier, a list of job identifiers, or a queue or server 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
        or, for an array job,
        sequence_number[].server
    where the first character of the identifier must be a digit. If the identifier is for an array job but the 't' character is not included in the extend parameter, the status of the array job is returned, but not the status of its subjobs. If the 't' character is included, status for each subjob is returned.

    If id is a list of job identifiers, it must be a comma-separated list of job identifiers in a single string. The first character of the string must be a digit. White space outside of a job identifier is ignored. There is no limit to the length of the string except as imposed by available memory. If id is a destination (server or queue) identifier, the status of all jobs at the destination which the user is authorized to see is returned. If id is the null pointer or a null string, the status of each job at the server to which the user is connected is returned.

The attrib parameter is a pointer to a list of attributes. If attrib is specified, then only the attributes in the list are returned by the server. Otherwise, all the attributes of a job are returned. The attrib parameter 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 next member is a pointer to the next entry in the list. The attrib list is terminated by the first entry where next is a null pointer. The name member is a pointer to an attribute name. Attribute names are listed in pbs_ifl.h. The resource member specifies the name of the resource in the job's Resource_List attribute. When attrl describes the job's Resource_List job attribute, the name member is ATTR_l. If attrl is not ATTR_l, resource should be a pointer to a null string. The value member should always be a pointer to a null string.

The extend parameter is used for extensions. This parameter can consist of characters in any order.
    When the extend parameter includes 't', if any array job identifiers are in the set of IDs being queried, the status of each array job is followed by status of each subjob in the array job. When the extend parameter includes 'x', finished and moved jobs and subjobs can be queried, and their status is included. Subjobs are not considered finished until the parent array job is finished.

RETURN VALUES and ERRORS
For a single job, if the job can be queried, the return value is a pointer to a batch_status structure containing the status of the specified job. If the job cannot be queried, a NULL pointer is returned, and pbs_errno is set to an error number. For a list of jobs, if any of the specified jobs can be queried, the return value is a pointer to a batch_status structure containing the status of all the queryable jobs. If none of the jobs can be queried, a NULL pointer is returned, and pbs_errno is set to the error number that indicates the reason that the last job in the list could not be queried. For a queue, if the queue exists, the return value is a pointer to a batch_status structure containing the status of all the queryable jobs in the queue. If the queue does not exist, a NULL pointer is returned, and pbs_errno is set to PBSE_UNKQUE (15018). If the queue exists but contains no queryable jobs, a NULL pointer ia returned and pbs_errno is set to PBSE_NONE (0). When querying a server, the connection to the server is already established by pbs_connect(). If there are jobs at the server, the return value of the query is a pointer to a batch_status structure containing the status of all the queryable jobs at the server. If the server does not contain any queryable jobs, a NULL pointer ia returned and pbs_errno is set to PBSE_NONE (0). 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) and pbs_connect(3B)