pbs_statque(3B)

okay so bestie, you've opened the pbs_statque(3B) page and we are about to make queue status make sense. this is the manual page for pbs_statque — obtain status of pbs batch queues — and it's giving "ask the server for the queue receipts" energy. let's go 💅

🎀 NAME 🎀

pbs_statque — obtain status of pbs batch queues

✨ SYNOPSIS ✨

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

struct batch_status *pbs_statque(int connect, char *id,
struct attrl *attrib,
char *extend)

void pbs_statfree(struct batch_status *psj)

🦋 DESCRIPTION 🦋

okay so the whole vibe: you issue a batch request to obtain the status of a batch queue. a Status Queue batch request is generated and sent to the server over the connection specified by connect, which is literally the return value of pbs_connect(). yes bestie, you gotta connect first — that's the whole thing. 🔌

💖 the id parameter

id is the name of a queue, in the form:

queue_name

or the null string. if queue_name is specified, the status of the queue named queue_name at the server will be returned. if id is a null string or null pointer, the status of all queues at the server will be returned. all of them. the whole queue family. 👑

🍓 the attrib parameter

attrib 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 attrib list is terminated by the first entry where next is a null pointer. if attrib is given, then only the attributes in the list are returned by the server. otherwise, all the attributes of a job are returned. (yes, the page says "job" right there — I'm just reporting what it says 😭) when an attrib list is specified, the name member is a pointer to a attribute name as listed in pbs_alter(3) and pbs_submit(3). the resource member is only used if the name member is ATTR_l, otherwise it should be a pointer to a null string. the value member should always be a pointer to a null string. character for character, bestie — no invented options here.

🧚 the extend parameter

extend is reserved for implementation defined extensions. that's it. reserved. implementation defined. don't come for me, I don't know what your server does with it. 🙈

🌈 return value

the return value is a pointer to a list of batch_status structures, which is defined in pbs_ifl.h as:

struct batch_status {
    struct batch_status *next;
    char                *name;
    struct attrl        *attribs;
    char                *text;
}

(no semicolon after the closing brace in the page, and I am not adding one — copy exact means copy exact, bestie. 💀)

it is up the user to free the structure when no longer needed, by calling pbs_statfree(). yes, you. not the library. you. free it. call pbs_statfree().

no cap: that pbs_statfree() call in the synopsis takes struct batch_status *psj, and it is your responsibility to free the structure when you're done with it. 🫶

👑 SEE ALSO 👑

• qstat(1B)
• pbs_connect(3B)

💀 DIAGNOSTICS 💀

when the batch request generated by pbs_statque() function has been completed successfully by a batch server, the routine will return a pointer to the batch_status structure. otherwise, a null pointer is returned and the error code is set in the global integer pbs_errno. so if you get a null pointer, pbs_errno is where the tea is. check it, bestie. 🔥

---

and that's the page! sign-off time: the footer reads Local and pbs_statque(3B) — that's the source/version line, and there's no date on this one, so no cap, that's all she wrote. mwah 💋