pbs_selectjob(3B)

pbs_selectjob(3B) from PBS Professional is here to teach you how to select PBS batch jobs, and she is serving 💅.

🌸 NAME 🌸

pbs_selectjob — select PBS batch jobs according to specified criteria. yes bestie, that’s literally the whole vibe 🎯

---

✨ SYNOPSIS ✨

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

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

---

💖 DESCRIPTION 💖

okay so pbs_selectjob() sends a batch request to select jobs that meet the criteria you specify, and then returns an array of job IDs that meet those criteria. iconic behavior, honestly 👑

This call generates a Select Jobs (16) batch request and sends it to the server over the connection handle specified by connect.

By default, pbs_selectjob() returns all batch jobs for which the user is authorized to query status. you filter the jobs by specifying values for job attributes and resources. You send a linked list of attributes with associated values and operators. Job attributes are listed in pbs_job_attributes(7B).

It returns a list of jobs that meet all specified criteria. no half-matches, no maybes, periodt ✨

---

🎀 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 attributes to use as selection criteria. Each attribute 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.

• extend — Character string where you can specify limits or extensions of your search.

🧚 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.
• op — Defines the operator in the logical expression:

<existing value> <operator> <specified limit>

Jobs for which the logical expression evaluates to True are selected.

For this command, op can be EQ, NE, GE, GT, LE, LT. get into it 💅

---

🦋 QUERYING STATES 🦋

You can select jobs in more than one state using a single request, by listing all the 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

see? one request, multiple states, main character energy 🌈

---

🌈 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_selectjob ( ..., ..., <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

Subjobs are not considered finished until the parent array job is finished. important lore, 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 ⭐

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 ID in the form:

<sequence number>.<server>@<server>

If no jobs met the criteria, the first pointer in the array is null.

If an error occurred, the routine returns a null pointer, and the error number is available in the global integer pbs_errno. so if something goes sideways, check pbs_errno, okay? 💀

---

💅 CLEANUP REQUIRED 💅

The returned array of character pointers is malloc()'ed by pbs_selectjob(). When the array is no longer needed, you must free it via a call to free(). do not ghost your memory, bestie 😭

---

🍓 SEE ALSO 🍓

qselect(1B), pbs_connect(3B)

---

🎀 and that’s the whole pbs_selectjob(3B) page, bestie — source/version Local, dated 15 November 2019. go select some jobs and slay 💖