pbs_statjob(3B)

✨ NAME ✨

pbs_statjob — get status of PBS batch jobs.

okay so bestie, welcome to pbs_statjob(3B) from PBS Professional 💅 this is the page for the function that gets PBS batch job status, and we are going to walk through it together, no cap.

---

🌸 SYNOPSIS 🌸

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

struct batch_status *
pbs_statjob(int connect, char *ID, struct attrl *output_attribs,
            char *extend)

---

💅 DESCRIPTION 💅

Issues a batch request to get the status of a specified batch job, a list of batch jobs, or the batch jobs at a queue or server. iconic behavior honestly.

It generates a Status Job (19) batch request and sends it to the server over the connection specified by connect.

You can query status of jobs, job arrays, subjobs, and ranges of subjobs. yes bestie, all the flavors 🍓

Queries all specified jobs that the user is authorized to query. periodt.

---

🎀 ARGUMENTS 🎀

• connect — Return value of pbs_connect(). Specifies connection handle over which to send the batch request to the server.
• ID — Job ID, list of job IDs, queue, server, or null.

If ID is a null pointer or points to a null string, gets status of jobs at the connected server.

Format for a job: <sequence number>.<server name>

Format for a job array: <sequence number>[].<server name>

Format for a subjob: <sequence number>[<index>].<server name>

Format for a range of subjobs: <sequence number>[<index start>-<index end>].<server name>

Format for a list of jobs: comma-separated list of job IDs in a single string. White space is ignored. No limit on length: <job ID>,<job ID>,<job ID>, ...

Format for a queue: <queue name>@<server name>

Format for a server: <server name>

• 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 search. Order of characters is not important.

👑 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.
• next — Points to next attribute in list. A null pointer terminates the list.

---

🦋 QUERYING JOB ARRAYS AND SUBJOBS 🦋

You can query status of job arrays and their subjobs, or just the parent job arrays only. choose your fighter 💅

To query status of job arrays and their subjobs, include the job array IDs in the ID argument, and include the "t" character in the extend argument. The function returns the status of each parent job array followed by status of each subjob in that job array.

To query status of one or more parent job arrays only, but not their subjobs, include their job IDs in the ID argument, but do not include anything in the extend argument.

---

🌈 QUERYING THE JOBS AT A QUEUE OR SERVER 🌈

To query status of all jobs at a queue, give the queue name in the ID argument.

To query status of all jobs at a server, give the server name in the ID argument. If you give a null ID argument, the function queries the default server.

---

🔥 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 status for 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_statjob ( ..., ..., <extend characters>) ...

Subjobs are not considered finished until the parent array job is finished. that's the rule, bestie 🫶

---

💖 RETURN VALUES 💖

For a single job, if the job can be queried, returns a pointer to a batch_status structure containing the status of the specified job. If the job cannot be queried, returns a NULL pointer, and pbs_errno is set to an error number indicating the reason the job could not be queried.

For a list of jobs, if any of the specified jobs can be queried, returns a pointer to a batch_status structure containing the status of all the queryable jobs. If none of the jobs can be queried, returns a NULL pointer, 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, returns a pointer to a batch_status structure containing the status of all the queryable jobs in the queue. If the queue does not exist, returns a NULL pointer, and pbs_errno is set to PBSE_UNKQUE (15018). If the queue exists but contains no queryable jobs, returns a NULL pointer, 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, returns 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, returns a NULL pointer, and pbs_errno is set to PBSE_NONE (0).

🧚 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(). do not leave that list hanging, bestie 😭

---

🌟 SEE ALSO 🌟

qstat(1B), pbs_connect(3B), pbs_statfree(3B)

---

okay that's the whole vibe — this page is from Local, dated 15 November 2019, and it's giving pbs_statjob(3B) in PBS Professional. bye bestie 💖✨