pbs_tclapi(3B)

💖 pbs_tclapi(3B) 💖

okay so this is the pbs_tclapi page from the PBS Professional manual, and we're diving in, bestie. It's giving vintage API energy, but every detail still matters, fr fr.

🌸 NAME 🌸

pbs_tclapi — PBS TCL Application Programming Interface

🦋 DESCRIPTION 🦋

Deprecated. Not me bringing up the deprecated thing first, but here we are. The pbs_tclapi is a subset of the PBS external API wrapped in a TCL library. This functionality allows the creation of scripts that query the PBS system. Specifically, it permits the user to query the pbs_server about the state of PBS, jobs, queues, and nodes, and communicate with pbs_mom to get information about the status of running jobs, available resources on nodes, etc.

iykyk: deprecated means it's still documented here, but you should definitely clock that vibe check before building your whole personality around it. 💅

✨ USAGE ✨

A set of functions to communicate with the PBS server and resource monitor have been added to those normally available with Tcl. All these calls will set the Tcl variable pbs_errno to a value to indicate if an error occurred. In all cases, the value "0" means no error. If a call to a Resource Monitor function is made, any error value will come from the system supplied errno variable. If the function call communicates with the PBS Server, any error value will come from the error number returned by the server. This is the same TCL interface used by the pbs_tclsh and pbs_wish commands.

• openrm host ?port? — Creates a connection to the PBS Resource Monitor on host using port as the port number or the standard port for the resource monitor if it is not given. A connection handle is returned. If the open is successful, this will be a non-negative integer. If not, an error occurred.
• closerm connection — The parameter connection is a handle to a resource monitor which was previously returned from openrm. This connection is closed. Nothing is returned.
• downrm connection — Sends a command to the connected resource monitor to shutdown. Nothing is returned.
• configrm connection filename — Sends a command to the connected resource monitor to read the configuration file given by filename. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• addreq connection request — A resource request is sent to the connected resource monitor. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• getreq connection — One resource request response from the connected resource monitor is returned. If an error occurred or there are no more responses, an empty string is returned.
• allreq request — A resource request is sent to all connected resource monitors. The number of streams acted upon is returned.
• flushreq — All resource requests previously sent to all connected resource monitors are flushed out to the network. Nothing is returned.
• activereq — The connection number of the next stream with something to read is returned. If there is nothing to read from any of the connections, a negative number is returned.
• fullresp flag — Evaluates flag as a boolean value and sets the response mode used by getreq to full if flag evaluates to "true". The full return from a resource monitor includes the original request followed by an equal sign followed by the response. The default situation is only to return the response following the equal sign. If a script needs to "see" the entire line, this function may be used.
• pbsstatserv — The server is sent a status request for information about the server itself. If the request succeeds, a list with three elements is returned, otherwise an empty string is returned. The first element is the server's name. The second is a list of attributes. The third is the "text" associated with the server (usually blank).
• pbsstatjob — The server is sent a status request for information about the all jobs resident within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each job. Each element is a list with three elements. The first is the job's jobid. The second is a list of attributes. The attribute names which specify resources will have a name of the form "Resource_List:name" where "name" is the resource name. The third is the "text" associated with the job (usually blank).
• pbsstatque — The server is sent a status request for information about all queues resident within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each queue. Each element is a list with three elements. This first is the queue's name. The second is a list of attributes similar to pbsstatjob. The third is the "text" associated with the queue (usually blank).
• pbsstatnode — The server is sent a status request for information about all nodes defined within the server. If the request succeeds, a list is returned, otherwise an empty string is returned. The list contains an entry for each node. Each element is a list with three elements. This first is the node's name. The second is a list of attributes similar to pbsstatjob. The third is the "text" associated with the node (usually blank).
• pbsselstat — The server is sent a status request for information about the all runnable jobs resident within the server. If the request succeeds, a list similar to pbsstatjob is returned, otherwise an empty string is returned.
• pbsrunjob jobid ?location? — Run the job given by jobid at the location given by location. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsasyrunjob jobid ?location? — Run the job given by jobid at the location given by location without waiting for a positive response that the job has actually started. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsrerunjob jobid — Re-runs the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsdeljob jobid — Delete the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsholdjob jobid — Place a hold on the job given by jobid. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsmovejob jobid ?location? — Move the job given by jobid to the location given by location. If location is not given, the default location is used. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsqenable queue — Set the "enabled" attribute for the queue given by queue to true. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsqdisable queue — Set the "enabled" attribute for the queue given by queue to false. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsqstart queue — Set the "started" attribute for the queue given by queue to true. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsqstop queue — Set the "started" attribute for the queue given by queue to false. If this is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsalterjob jobid attribute_list — Alter the attributes for a job specified by jobid. The parameter attribute_list is the list of attributes to be altered. There can be more than one. Each attribute consists of a list of three elements. The first is the name, the second the resource and the third is the new value. If the alter is successful, a "0" is returned, otherwise, "-1" is returned.
• pbsrescquery resource_list — Deprecated. Obtain information about the resources specified by resource_list. This will be a list of strings. If the request succeeds, a list with the same number of elements as resource_list is returned. Each element in this list will be a list with four numbers. The numbers specify available, allocated, reserved, and down in that order.
• pbsconnect ?server? — Make a connection to the named server or the default server if a parameter is not given. Only one connection to a server is allowed at any one time.
• pbsdisconnect — Disconnect from the currently connected server.

The above Tcl functions use PBS interface library calls for communication with the server and the PBS resource monitor library to communicate with pbs_mom.

🕰️ datetime ?day? ?time? 🕰️

The number of arguments used determine the type of date to be calculated. With no arguments, the current POSIX date is returned. This is an integer in seconds.

With one argument there are two possible formats. The first is a 12 (or more) character string specifying a complete date in the following format:

YYMMDDhhmmss

All characters must be digits. The year (YY) is given by the first two (or more) characters and is the number of years since 1900. The month (MM) is the number of the month [01-12]. The day (DD) is the day of the month [01-32]. The hour (hh) is the hour of the day [00-23]. The minute (mm) is minutes after the hour [00-59]. The second (ss) is seconds after the minute [00-59]. The POSIX date for the given date/time is returned.

The second option with one argument is a relative time. The format for this is:

HH:MM:SS

With hours (HH), minutes (MM) and seconds (SS) being separated by colons ":". The number returned in this case will be the number of seconds in the interval specified, not an absolute POSIX date.

With two arguments a relative date is calculated. The first argument specifies a day of the week and must be one of the following strings: "Sun", "Mon", "Tue", "Wed", "Thr", "Fri", or "Sat". The second argument is a relative time as given above. The POSIX date calculated will be the day of the week given which follows the current day, and the time given in the second argument. For example, if the current day was Monday, and the two arguments were "Fri" and "04:30:00", the date calculated would be the POSIX date for the Friday following the current Monday, at four-thirty in the morning. If the day specified and the current day are the same, the current day is used, not the day one week later.

🕰️ strftime format time — bestie, it's giving calendar glam ✨

Okay so this one is literally a little messenger between you and the POSIX function strftime(). It calls the POSIX function strftime() for you, and it requires two arguments — no more, no less, she's not flexible like that. 🎀

• The first argument is a format string. The format conventions are the same as those for the POSIX function strftime() — so if you already know those, you already know this, iykyk. 💅
• The second argument is POSIX calendar time, in seconds, as returned by datetime. ⏳

It returns a string based on the format given. So basically you get the ability to extract information about a time, or format it for printing — like, she'll pull the receipts out of a timestamp or dress it up all pretty for the terminal. Both, honestly. Obsessed. 🦋

📝 logmsg tag message — not me writing to the scheduler's diary 🙈

This one calls the internal PBS function log_err(), and the whole vibe is: it will cause a log message to be written to the scheduler's log file. That's the destination, periodt. 🔥

• tag — this specifies a function name or other word used to identify the area where the message is generated. Think of it as the little name tag so you know who is talking in the group chat. 🏷️
• message — the string to be logged. That's it, that's the words. 💌

Ngl, super useful when you're debugging and need the scheduler to spill the tea in her log file. 🌸

🔗 SEE ALSO 🌈

Go give these besties some love too, fr fr:

• pbs_tclsh(8B)
• pbs_wish(8B)
• pbs_mom(8B)
• pbs_server(8B)
• pbs_sched(8B)

And that's the whole page, bestie — you ate that. 💜 This little icon of a manpage is a Local one, dated 4 December 2019, and she answers to the name pbs_tclapi(3B). Go forth and slay your Tcl scripts. 👑✨