pbs_submit(3B)

💖 pbs_submit(3B) — like, the submit a PBS batch job manual page, bestie 💖

okay so this is pbs_submit(3B), a page from the PBS manual set, and it's literally the function that yeets a brand-new batch job at the server. no cap, it's iconic. let's get into it 🫶

---

✨ NAME ✨

pbs_submit — submit a pbs batch job

(yeah that's it. that's the whole name section. short and slay.)

---

🎀 SYNOPSIS 🎀

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

char *pbs_submit(int connect, struct attropl *attrib,
char *script, char *destination, char *extend)

look at her. five arguments, one char * return, all vibes. 💅

---

🌸 DESCRIPTION 🌸

okay so what this does: it issues a batch request to submit a new batch job. that's the whole thing, that's the assignment. ✨

A Queue Job batch request gets generated and sent to the server over the connection you specify with connect — and heads up, that's the value that pbs_connect() gave you back. The job gets submitted to the queue specified by destination.

🦋 the attrib situation

The parameter attrib is a list of attropl structures, and pbs_ifl.h defines them like this:

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

The attrib list is terminated by the first entry where next is a null pointer — that's your little "we're done here" signal, periodt. 🎀

The name member points to a string which is the name of the attribute. The value member points to a string which is the value of the attribute. And the attribute names themselves? Those are defined in pbs_ifl.h, and here's the full roster, no skips, no cuts:

• #define ATTR_a "Execution_Time" — Defines the job's execution time.
• #define ATTR_A "Account_Name" — Defines the account string.
• #define ATTR_c "Checkpoint" — Defines the checkpoint interval.
• #define ATTR_e "Error_Path" — Defines the path name for the standard error of the job.
• #define ATTR_g "Group_List" — Defines the list of group names under which the job may execute.
• #define ATTR_h "Hold_Types" — Defines the hold types, the only allowable value string is "u".
• #define ATTR_j "Join_Paths" — Defines whether standard error and standard output are joined (merged).
• #define ATTR_k "Keep_Files" — Defines which output of the job is kept on the execution host.
• #define ATTR_l "Resource_List" — Defines a resource required by the job.
• #define ATTR_m "Mail_Points" — Defines the points at which the server will send mail about the job.
• #define ATTR_M "Mail_Users" — Defines the list of users who would receive mail about the job.
• #define ATTR_N "Job_Name" — Defines the job name.
• #define ATTR_o "Output_Path" — Defines the path name for the standard output of the job.
• #define ATTR_p "Priority" — Defines the priority of the job.
• #define ATTR_r "Rerunable" — Defines the rerunable flag.
• #define ATTR_S "Shell_Path_List" — Defines the path to the shell which will interpret the job script.
• #define ATTR_t "job_array_request" — Requests specific array IDs. Makes this submission a job array submit. 👑
• #define ATTR_u "User_List" — Defines the list of user names under which the job may execute.
• #define ATTR_v "Variable_List" — Defines the list of additional environment variables which are exported to the job.
• #define ATTR_depend "depend" — Defines the inter-job dependencies.
• #define ATTR_stagein "stagein" — Defines the list of files to be staged in prior to job execution.
• #define ATTR_stageout "stageout" — Defines the list of files to be staged out after job execution.

💜 defaults, or: the "we'll handle it" energy

If an attribute isn't named in the attrib array, the default action will be taken. It'll either get assigned the default value or it just won't be passed with the job — which one happens depends entirely on the attribute, so like, it varies. 🙈

And if attrib itself is a null pointer? Then the default action is taken for each attribute. every single one. main character behavior honestly.

🌈 the resource thing

Associated with an attribute of type ATTR_l (that's the letter ell, not a one, bestie, don't come for me) is a resource name indicated by resource in the attrl structure. All other attribute types should have a pointer to a null string for resource. that's it, that's the rule. ⭐

🔥 the op thing

The op member is forced to a value of SET by pbs_submit(). you don't get a say. she decides. 💅

🍓 the other parameters

• script — the path name to the job script. If the path name is relative, it gets expanded to the process's current working directory. And if script is a null pointer, or the path name pointed to is specified as the null string, then no script is passed with the job. (yes, "the path name pointed to is specified as the null string" — that's the real wording, it means an empty string. iykyk.)
• destination — specifies the destination for the job. It's specified as: [queue]. If destination is the null string, or the queue is not specified, the destination will be the default queue at the connected server. 🎀
• extend — reserved for implementation defined extensions. that's it. that's all she wrote. don't touch. 🧚

💖 the return value

The return value is a character string which is the job_identifier assigned to the job by the server. The space for the job_identifier string is allocated by pbs_submit() and should be released via a call to free() by the user when no longer needed.

lowkey important: you have to free() it. she's not gonna do it for you. memory leaks are not the vibe. 😭

---

🦋 SEE ALSO 🦋

• qsub(1B)
• pbs_connect(3B)

both absolute icons, go read them. 💜

---

💀 DIAGNOSTICS 💀

When the batch request generated by pbs_submit() function has been completed successfully by a batch server, the routine returns a pointer to a character string which is the job identifier of the submitted batch job. 🎉

Otherwise? a null pointer is returned and the error code is set in pbs_error. so like, check pbs_error, bestie. always check pbs_error. 🙈

---

and that's the whole page, bestie — this local pbs_submit(3B) page from the PBS manual set. slay, go submit some jobs responsibly. 💅✨