pbs_selectjob(3B)

💖 PBS pbs_selectjob(3B) Manual 💖

Okay bestie, welcome to the pbs_selectjob(3B) page from the PBS manual — this is the job-selection function and it is lowkey iconic. 🫶

---

🌸 NAME 🌸

pbs_selectjob — select pbs batch jobs. That’s the whole assignment: select pbs batch jobs. Slay. 💅

---

✨ SYNOPSIS ✨

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

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

---

🦋 DESCRIPTION 🦋

So you issue a batch request to select jobs that meet certain criteria, and pbs_selectjob() returns an array of job identifiers that met those criteria. No cap, that’s the core vibe. ✨

At first, all batch jobs are selected for which the user is authorized to query status. Then this set may be reduced or filtered by specifying certain attributes of the jobs. It’s giving “start with the whole group chat, then narrow it down.” 💖

A Select Jobs batch request is generated and sent to the server over the connection specified by connect, which is the return value of pbs_connect(). 🎀

The argument attrib is a pointer to an attropl structure, and that structure is defined in pbs_ifl.h as:

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

The attrib list is terminated by the first entry where next is a null pointer. 🛑

The name member points to a string which is the name of the attribute. Not all of the job attributes may be used as a selection criteria. The resource member points to a string which is the name of a resource. This member is only used when name is set to ATTR_l. Otherwise, resource should be a pointer to a null string. The value member points to a string which is the value of the attribute or resource. The attribute names are defined in pbs_ifl.h:

• #define ATTR_a "Execution_Time" — select based on the job’s execution time.
• #define ATTR_A "Account_Name" — select (E) based on the account string.
• #define ATTR_c "Checkpoint" — select based on the checkpoint interval.
• #define ATTR_e "Error_Path" — select (E) based on the name of the standard error file.
• #define ATTR_g "Group_List" — select (E) based on the list of group names under which the job may execute.
• #define ATTR_h "Hold_Types" — select (E) based on the hold types.
• #define ATTR_j "Join_Paths" — select (E) based on the value of the join list.
• #define ATTR_k "Keep_Files" — select (E) based on the value of the keep files list.
• #define ATTR_l "Resource_List" — select based on the value of the resource named in resource.
• #define ATTR_m "Mail_Points" — select (E) based on the setting of the mail points attribute.
• #define ATTR_M "Mail_Users" — select (E) based on the list of user names to which mail will be sent.
• #define ATTR_N "Job_Name" — select (E) based on the job name.
• #define ATTR_o "Output_Path" — select (E) based on the name of the standard output file.
• #define ATTR_p "Rriority" — select based on the priority of the job. (yes, Rriority is literally how it’s spelled in the define 😭)
• #define ATTR_q "destination" — select based on the specified destination. Jobs selected are restricted to those residing in the named queue. If destination is the null string, the default queue at the server is assumed.
• #define ATTR_r "Rerunable" — select (E) based on the rerunable flag.
• #define ATTR_session "session_id" — select based on the session id assigned to running jobs.
• #define ATTR_S "Shell_Path_List" — select (E) based on the execution shell list.
• #define ATTR_u "User_List" — select (E) based on the owner of the jobs.
• #define ATTR_v "Variable_List" — select (E) based on the list of environment variables.
• #define ATTR_ctime "ctime" — select based on the creation time of the job.
• #define ATTR_depend "depend" — select based on the list of job dependencies.
• #define ATTR_mtime "mtime" — select based on the last modification time of the job.
• #define ATTR_qtime "qtime" — select based on the time the job was placed into the current queue.
• #define ATTR_qtype "queue_type" — select (E) based on the type of queue in which the job resides.
• #define ATTR_stagein "stagein" — select based on the list of files to be staged-in.
• #define ATTR_stageout "stageout" — select based on the list of files to be staged-out.
• #define ATTR_state "job_state" — select based on the state of the jobs. State is not a job attribute, but is included here to allow selection.

The op member defines the operator in the logical expression:

value operator current_value

The logical expression must evaluate as true for the job to be selected. The permissible values of op are defined in pbs_ifl.h as:

enum batch_op { ..., EQ, NE, GE, GT, LE, LT, ... };

The attributes marked with (E) in the description above may only be selected with the equal, EQ, or not equal, NE, operators. That’s the rule, bestie — no wildcards in your feelings here. 💀

If attrib itself is a null pointer, then no selection is done on the basis of attributes. 🎀

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

sequence_number.server@server

The array is allocated by pbs_selectjob via malloc(). When the array is no longer needed, the user is responsible for freeing it by a call to free(). Yes, that means you, bestie — clean up after your array. 🧚

The parameter extend is reserved for implementation defined extensions. TORQUE 2.0.0p1 added the #define’d constant string EXECQUEONLY to only retrieve jobs in execution queues. ✨

---

👑 SEE ALSO 👑

qselect(1B), pbs_alterjob(3B), and pbs_connect(3B). Go read the friends too, iykyk. 🫶

---

💀 DIAGNOSTICS 💀

When the batch request generated by pbs_selectjob() has been completed successfully by a batch server, the routine will return a pointer to the array of job identifiers. If no jobs met the criteria, the first pointer in the array will be the null pointer. Empty but valid — it’s giving “no notes.” 💅

If an error occurred, a null pointer is returned and the error is available in the global integer pbs_errno. So if things go sideways, check pbs_errno, okay? 😭

---

💖 Signing off from the Local edition of pbs_selectjob(3B) — no date printed in the footer, so no fake date here, bestie. Stay selected. 🎀✨