pbs_selstat(3B)

💖 pbs_selstat(3B) — get status of selected PBS batch jobs ✨

okay bestie, this is the pbs_selstat(3B) page from the PBS Professional manual, and it's lowkey the "give me the jobs that match these criteria" bestie. no cap, it's useful. let's go 🫶

🌸 NAME 🌸

pbs_selstat — get status of selected PBS batch jobs

✨ SYNOPSIS ✨

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

struct batch_status *
pbs_selstat(int connect, struct attropl *criteria_list,
            struct attrl *output_attribs, char *extend)

🎀 DESCRIPTION 🎀

okay so pbs_selstat issues a batch request to get the status of jobs that meet the specified criteria. it generates a Select Status (51) batch request and sends it to the server over the connection specified by connect.

it returns a list of batch_status structures for jobs that meet the selection criteria. iconic.

this function is a combination of pbs_selectjob() and pbs_statjob(). the way it's literally two icons in a trench coat.

by default this gives status for all jobs for which you are authorized to query status. you can filter the results by specifying selection criteria. slay.

🦋 ARGUMENTS 🦋

• connect — return value of pbs_connect(). specifies the connection handle over which to send the batch request to the server.
• criteria_list — pointer to a list of selection criteria, which are attributes and resources with required values. if this list is null, you are not filtering your results via selection criteria. each attribute or resource is described in an attropl structure, defined in pbs_ifl.h as:

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

if criteria_list itself is null, you are not using attributes or resources as selection criteria. both null facts stay, bestie.

• output_attribs — pointer to a list of attributes to return. if this list is null, all attributes are returned. each attribute is described in an attrl structure, defined in pbs_ifl.h as:

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

• extend — character string where you can specify limits or extensions of your selection.

🧚 Members of attropl Structure 🧚

• next — points to the next attribute in the list. a null pointer terminates the list.
• name — points to a string containing the name of the attribute.
• resource — points to a string containing the name of a resource. used only when the specified attribute contains resource information. otherwise, resource should be a null pointer.
• value — points to a string containing the value of the attribute or resource. for parameterized limit attributes, this string contains all parameters for the attribute.
• op — specifies the test to be applied to the attribute or resource. the operators are EQ, NE, GE, GT, LE, LT.

🍓 Members of attrl Structure 🍓

• name — points to a string containing the name of the attribute.
• resource — points to a string containing the name of a resource. used only when the specified attribute contains resource information. otherwise, resource should be a null pointer.
• value — points to a string containing the value of the attribute or resource. should always be null.
• next — points to the next attribute in the list. a null pointer terminates the list.

🌈 QUERYING STATES 🌈

you can select jobs in more than one state using a single request, by listing all states you want returned. for example, to get jobs in Held and Waiting states:

Fill in criteria_list->name with "job_state"
Fill in criteria_list->value with "HW" for Held and Waiting

🔥 EXTENDING YOUR QUERY 🔥

you can use the following characters in the extend parameter:

• T, t — extends query to include subjobs. job arrays are not included.
• x — extends query to include finished and moved jobs.

💜 Querying Finished and Moved Jobs 💜

to get information on finished or moved jobs, as well as current jobs, add an 'x' character to the extend parameter (set one character to be the 'x' character). for example:

pbs_selstat ( ..., ..., <extend characters>) ...

to get information on finished jobs only:

Add the "x" character to the extend parameter
Fill in criteria_list->name with "ATTR_state"
Fill in criteria_list->value with "FM" for Finished and Moved

for example:

criteria_list->name = ATTR_state;
criteria_list->value = "FM";
criteria_list->op = EQ;
pbs_selstat ( ..., criteria_list, ..., extend) ...

subjobs are not considered finished until the parent array job is finished. important bestie!

🦋 Querying Job Arrays and Subjobs 🦋

to query only job arrays (not jobs or subjobs):

Fill in criteria_list->name with "array"
Fill in criteria_list->value with "True"

to query only job arrays and subjobs (not jobs):

Fill in criteria_list->name with "array"
Fill in criteria_list->value with "True"
Add the "T" or "t" character to the extend parameter

to query only jobs and subjobs (not job arrays), add the "T" or "t" character to the extend parameter.

👑 RETURN VALUE 👑

returns a pointer to a list of batch_status structures for jobs that meet the selection criteria. if no jobs meet the criteria or can be queried for status, returns the null pointer.

if an error occurred, the routine returns a null pointer, and the error number is available in the global integer pbs_errno.

🎀 The batch_status Structure 🎀

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;
}

💅 CLEANUP 💅

you must free the list of batch_status structures when no longer needed, by calling pbs_statfree().

🌟 SEE ALSO 🌟

• qselect(1B)
• qstat(1B)
• pbs_connect(3B)
• pbs_selectjob(3B)
• pbs_statjob(3B)

---

that's the whole page, bestie — source/version Local, dated 15 November 2019, for pbs_selstat(3B) in the PBS Professional manual. bye and slay 💖✨