pbs_module(7B)

NAME
pbs_module - Python interface to PBS and PBS hook environment

DESCRIPTION

The pbs module provides an interface to PBS and the hook environment. The interface is made up of Python objects, which have attributes and methods. You can operate on these objects using Python code. For a description of each object, see the PBS Professional Administrator's Guide.

PBS MODULE OBJECTS

pbs.acl
    Represents a PBS ACL type.

pbs.args
    Represents a space-separated list of PBS arguments to commands like qsub, qdel.

pbs.argv[]
    Represents a list of argument strings to be passed to the program

pbs.BadAttributeValueError
    Raised when setting the attribute value of a pbs.* object to an invalid value.

pbs.BadAttributeValueTypeError
    Raised when setting the attribute value of a pbs.* object to an invalid value type.

pbs.BadResourceValueError
    Raised when setting the resource value of a pbs.* object to an invalid value.

pbs.BadResourceValueTypeError
    Raised when setting the resource value of a pbs.* object to an invalid value type.

pbs.checkpoint
    Represents a job's Checkpoint attribute.

pbs.depend
    Represents a job's depend attribute.

pbs.duration
    Represents a time interval.

pbs.email_list
    Represents the set of users to whom mail may be sent.

pbs.env[]
    Dictionary of environment variables.

pbs.event
    Represents a PBS event.

pbs.EventIncompatibleError
    Raised when referencing a non-existent attribute in pbs.event().

pbs.EXECHOST_PERIODIC
    The exechost_periodic event type.

pbs.EXECHOST_STARTUP
    The exechost_startup event type.

pbs.EXECJOB_ATTACH
    The execjob_attach event type.

pbs.EXECJOB_BEGIN
    The execjob_begin event type.

pbs.EXECJOB_END
    The execjob_end event type.

pbs.EXECJOB_EPILOGUE
    The execjob_epilogue event type.

pbs.EXECJOB_LAUNCH
    The execjob_launch event type.

pbs.EXECJOB_PRETERM
    The execjob_preterm event type.

pbs.EXECJOB_PROLOGUE
    The execjob_prologue event type.

pbs.exec_host
    Represents a job's exec_host attribute.

pbs.exec_vnode
    Represents a job's exec_vnode attribute.

pbs.group_list
    Represents a list of group names.

pbs.hold_types
    Represents a job's Hold_Types attribute.

pbs.hook_config_filename
    Contains path to hook's configuration file.

pbs.job
    Represents a PBS job.

pbs.job_list[]
    Represents a list of pbs.job objects.

pbs.job_sort_formula
    Represents the server's job_sort_formula attribute.

pbs.JOB_STATE_BEGUN
    Represents the job array state of having started.

pbs.JOB_STATE_EXITING
    Represents the job state of exiting.

pbs.JOB_STATE_EXPIRED
    Represents the subjob state of expiring.

pbs.JOB_STATE_FINISHED
    Represents the job state of finished.

pbs.JOB_STATE_HELD
    Represents the job state of held.

pbs.JOB_STATE_MOVED
    Represents the job state of moved.

pbs.JOB_STATE_QUEUED
    Represents the job state of queued.

pbs.JOB_STATE_RUNNING
    Represents the job state of running.

pbs.JOB_STATE_SUSPEND
    Represents the job state of suspended.

pbs.JOB_STATE_SUSPEND_USERACTIVE
    Represents the job state of suspended due to user activity.

pbs.JOB_STATE_TRANSIT
    Represents the job state of transiting.

pbs.JOB_STATE_WAITING
    Represents the job state of waiting.

pbs.join_path
    Represents a job's Join_Path attribute.

pbs.keep_files
    Represents a job's Keep_Files attribute.

pbs.license_count
    Represents a set of licensing-related counters.

pbs.LOG_DEBUG
    Log level 004.

pbs.LOG_ERROR
    Log level 004.

pbs.LOG_WARNING
    Log level 004.

pbs.mail_points
    Represents a job's Mail_Points attribute.

pbs.MODIFYJOB
    The modifyjob event type.

pbs.MOVEJOB
    The movejob event type.

pbs.ND_BUSY
    Represents busy vnode state.

pbs.ND_DEFAULT_EXCL
    Represents default_excl sharing vnode attribute value

pbs.ND_DEFAULT_SHARED
    Represents default_shared sharing vnode attribute value.

pbs.ND_DOWN
    Represents down vnode state

pbs.ND_FORCE_EXCL
    Represents force_excl sharing vnode attribute value.

pbs.ND_FREE
    Represents free vnode state.

pbs.ND_GLOBUS
    PBS no longer supports Globus. The Globus functionality has been removed from PBS. Represents globus vnode ntype.

pbs.ND_IGNORE_EXCL
    Represents ignore_excl sharing vnode attribute value.

pbs.ND_JOBBUSY
    Represents job-busy vnode state.

pbs.ND_JOB_EXCLUSIVE
    Represents job-exclusive vnode state.

pbs.ND_OFFLINE
    Represents offline vnode state.

pbs.ND_PBS
    Represents pbs vnode ntype.

pbs.ND_PROV
    Represents provisioning vnode state.

pbs.ND_RESV_EXCLUSIVE
    Represents resv-exclusive vnode state.

pbs.ND_STALE
    Represents stale vnode state.

pbs.ND_STATE_UNKNOWN
    Represents state-unknown, down vnode state.

pbs.ND_UNRESOLVABLE
    Represents the unresolvable vnode state.

pbs.ND_WAIT_PROV
    Represents wait-provisioning vnode state.

pbs.node_group_key
    Represents the server or queue node_group_key attribute.

pbs.path_list
    Represents a list of pathnames.

pbs.pbs_conf[]
    Dictionary of entries in pbs.conf.

pbs.pid
    Represents the process ID of a process belonging to a job.

pbs.place
    Represents the place job submission specification.

pbs.progname
    Path of job shell or executable.

pbs.QTYPE_EXECUTION
    The execution queue type.

pbs.QTYPE_ROUTE
    The route queue type.

pbs.queue
    Represents a PBS queue.

pbs.QUEUEJOB
    The queuejob event type.

pbs.range
    Represents a range of numbers referring to array indices.

pbs.resv
    Represents a PBS reservation.

pbs.RESVSUB
    The resvsub event type.

pbs.RESV_STATE_BEING_DELETED
    Represents the reservation state RESV_BEING_DELETED.

pbs.RESV_STATE_CONFIRMED
    Represents the reservation state RESV_CONFIRMED.

pbs.RESV_STATE_DEGRADED
    Represents the reservation state RESV_DEGRADED.

pbs.RESV_STATE_DELETED
    Represents the reservation state RESV_DELETED.

pbs.RESV_STATE_DELETING_JOBS
    Represents the reservation state RESV_DELETING_JOBS.

pbs.RESV_STATE_FINISHED
    Represents the reservation state RESV_FINISHED.

pbs.RESV_STATE_NONE
    Represents the reservation state RESV_NONE.

pbs.RESV_STATE_RUNNING
    Represents the reservation state RESV_RUNNING.

pbs.RESV_STATE_TIME_TO_RUN
    Represents the reservation state RESV_TIME_TO_RUN.

pbs.RESV_STATE_UNCONFIRMED
    Represents the reservation state RESV_UNCONFIRMED.

pbs.RESV_STATE_WAIT
    Represents the reservation state RESV_WAIT.

pbs.route_destinations
    Represents a queue's route_destinations attribute.

pbs.RUNJOB
    The runjob event type.

pbs.select
    Represents the select job submission specification.

pbs.server
    Represents the local PBS server.

pbs.size
    Represents a PBS size type.

pbs.software
    Represents a site-dependent software specification resource.

pbs.staging_list
    Represents a list of file stagein or stageout parameters.

pbs.state_count
    Represents a set of job-related state counters.

pbs.SV_STATE_ACTIVE
    Represents the server state "Scheduling".

pbs.SV_STATE_HOT
    Represents the server state "Hot_Start".

pbs.SV_STATE_IDLE
    Represents the server state "Idle".

pbs.SV_STATE_SHUTDEL
    Represents the server state "Terminating, Delayed".

pbs.SV_STATE_SHUTIMM
    Represents the server state "Terminating".

pbs.SV_STATE_SHUTSIG
    Represents the server state "Terminating", when a signal has been caught.

pbs.UnsetAttributeNameError
    Raised when referencing a non-existent name of a pbs.* object.

pbs.UnsetResourceNameError
    Raised when referencing a non-existent name of a pbs.* object.

pbs.user_list
    Represents a list of user names.

pbs.vchunk
    Represents a resource chunk assigned to a job.

pbs.version
    Represents PBS version information.

pbs.vnode
    Represents a PBS vnode.

pbs.vnode_list[]
    Represents a list of PBS vnodes.

SystemExit
    Raised when accepting or rejecting an action.

PBS MODULE GLOBAL METHODS

pbs.acl("[+|-]<entity>][,...]")
    Creates an object representing a PBS ACL, using the given string parameter. Instantiation of these objects requires a formatted input string.

pbs.args("<args>")
    where <args> are space-separated arguments to a command such as qsub or qdel. Creates an object representing the arguments to the command. Example:
    pbs.args("-Wsuppress_email=N -r y")

    Instantiation of these objects requires a formatted input string.

pbs.checkpoint("<checkpoint_string>")
    where <checkpoint_string> must be one of "n", "s", "c", "c=mmm", "w", or "w=mmm" Creates an object representing the job's Checkpoint attribute, using the given string. Instantiation of these objects requires a formatted input string.

pbs.depend("<depend_string>")
    <depend_string> must be of format "<type>:<jobid>[,<jobid>...]", or "on:<count>", and where <type> is one of "after", "afterok", "afterany", "before", "beforeok", and "beforenotok". Creates a PBS dependency specification object representing the job's depend attribute, using the given <depend_string>. Instantiation of these objects requires a formatted input string.

pbs.duration("[[hours:]minutes:]seconds[.milliseconds]")
    Creates a time specification duration instance, returning the equivalent number of seconds from the given time string. Represents an interval or elapsed time in number of seconds. Duration objects can be specified using either a time or an integer. See the "pbs.duration(<integer>)" creation method.

pbs.duration(<integer>)
    Creates an integer duration instance using the specified number of seconds. A pbs.duration instance can be operated on by any of the Python int functions. When performing arithmetic operations on a pbs.duration type, ensure the resulting value is a pbs.duration() type, before assigning to a job member that expects such a type.

pbs.email_list("<email_address1>[,<email_address2>...]")
    Creates an object representing a mail list. Instantiation of these objects requires a formatted input string.

pbs.exec_host("host/N[*C][+...]")
    Create an object representing the exec_host job attribute, using the given host and resource specification. Instantiation of these objects requires a formatted input string.

pbs.exec_vnode("<vchunk>[+<vchunk>...]")
    <vchunk> is (<vnodename:ncpus=N:mem=M>) Creates an object representing the exec_vnode job attribute, using the given vnode and resource specification. When the qrun -H command is used, or when the scheduler runs a job, the pbs.job.exec_vnode object contains the vnode specification for the job. Instantiation of these objects requires a formatted input string.
    Example:
    pbs.exec_vnode("(vnodeA:ncpus=N:mem=X)+(nodeB:ncpus=P:mem=Y+nodeC:mem=Z)")
    This object is managed and accessed via the str() or repr() functions.
    Example:
    Python> ev = pbs.server().job("10").exec_vnode
    Python> str(ev)
    "(vnodeA:ncpus=2:mem=200m)+(vnodeB:ncpus=5:mem=1g)"

pbs.get_hook_config_file()
    Returns the path to the hook's configuration file, or None if there is no configuration file. For example:
    configfilepath = pbs.get_hook_config_file()

pbs.get_local_nodename()
    This returns a Python str whose value is the name of the local natural vnode. If you want to refer to the vnode object representing the current host, you can pass this vnode name as the key to pbs.event().vnode_list[]. For example:
    Vn = pbs.event().vnode_list[pbs.get_local_nodename()]

pbs.get_pbs_conf()
    This method returns a dictionary of values which represent entries in the pbs.conf file. The method reads the file on the host where a hook runs, so pre-execution event hooks get the entries on the server host, and execution event hooks get the entries on the execution host where the hook runs. The method reads /etc/pbs.conf on the host where pbs_python runs. Example:
    pbs_conf = pbs.get_pbs_conf()
    pbs.logmsg(pbs.LOG_DEBUG, "pbs home is " % (pbs_conf['PBS_HOME]))

    If you HUP pbs_mom (Linux/UNIX), pbs.get_pbs_conf returns the reloaded contents of the pbs.conf file.

pbs.group_list("<group_name>[@<host>][,<group_name>[@<host>]...]")
    Creates an object representing a PBS group list. To use a group list object:
    pbs.job.group_list = pbs.group_list(....)
    Instantiation of these objects requires a formatted input string.

pbs.hold_types("<hold_type_str>")
    where <hold_type_str> is one of "u", "o", "s", or "n". Creates an object representing the Hold_Types job attribute. Instantiation of these objects requires a formatted input string.

pbs.job_sort_formula("<formula_string>")
    where <formula_string> is a string containing a math formula. Creates an object representing the job_sort_formula server attribute. Instantiation of these objects requires a formatted input string.

pbs.join_path({"oe"|"eo"|"n"})
    Creates an object representing the Join_Path job attribute. Instantiation of these objects requires a formatted input string.

pbs.keep_files("<keep_files_str>")
    where <keep_files_str> is one of "o", "e", "oe", "eo". Creates an object representing the Keep_Files job attribute. Instantiation of these objects requires a formatted input string.

pbs.license_count("Avail_Global:<W>Avail_Local:<X>Used:<Y>High_Use:<Z>")
    Instantiates an object representing a license_count attribute. Instantiation of these objects requires a formatted input string.

pbs.logjobmsg(job_ID,message)
    where job_ID must be an existing or previously existing job ID and where message is an arbitrary string. This puts a custom string in the PBS Server log. The tracejob command can be used to print out the job-related messages logged by a hook script. Messages are logged at log event class pbs.LOG_DEBUG.

pbs.logmsg(log_event_class,message)
    where message is an arbitrary string, and where log_event_class can be one of the message log event class constants:
    pbs.LOG_WARNING
    pbs.LOG_ERROR
    pbs.LOG_DEBUG
    This puts a custom string in the daemon log.

pbs.mail_points("<mail_points_string>")
    where <mail_points_string> is "a", "b", and/or "e", or "n". Creates an object representing a Mail_Points attribute. Instantiation of these objects requires a formatted input string.

pbs.node_group_key("<resource>")
    Creates an object representing the resource to be used for node grouping, using the specified resource.

pbs.path_list("<path>[@<host>][,<path>@<host>...]")
    Creates an object representing a PBS pathname list. To use a path list object:
    pbs.job.Shell_Path_List = pbs.path_list(....)
    Instantiation of these objects requires a formatted input string.

pbs.env()
    Creates an empty environment variable list. For example, to create an empty environment variable list:
    pbs.event().env = pbs.pbs_env()

pbs.place("[arrangement]:[sharing]:[group]")
    arrangement can be "pack", "scatter", "free", "vscatter"
    sharing can be "shared", "excl", "exclhost"
    group can be of the form "group=<resource>"
    [arrangement], [sharing], and [group] can be given in any order or combination.
    Creates a place object representing the job's place specification. Instantiation of these objects requires a formatted input string.
    Example:
    pl = pbs.place("pack:excl")
    s = repr(pl) (or s = `pl`)
    letter = pl[0] (assigns 'p' to letter)
    s = s + ":group=host" (append to string) br pl = pbs.place(s) (update original pl)

pbs.range("<start>-<stop>:<step>")
    Creates a PBS object representing a range of values.
    Example:
    pbs.range("1-30:3")
    Instantiation of these objects requires a formatted input string.

pbs.reboot([<command>])
    This stops hook execution, so that remaining lines in the hook script are not executed, and starts the tasks that would normally begin after the hook is finished, such as flagging the current host to be rebooted. The MoM logs show the following:
    <hook name> requested for host to be rebooted

    We recommend that before calling pbs.reboot(), you set any vnodes managed by this MoM offline, and requeue the current job, if this hook is not an exechost_periodic hook. For example:
    for v in pbs.event().vnode_list.keys():
    pbs.event().vnode_list[v].state = pbs.ND_OFFLINE
    pbs.event().vnode_list[v].comment = "MoM host rebooting"
    pbs.event().job.rerun()
    pbs.reboot()

    The effect of the call to pbs.reboot() is not instantaneous. The reboot happens after the hook executes, and after any of the other actions such as pbs.event().job.rerun(), pbs.event().delete(), and pbs.event().vnode_list[] take effect. A hook with its user attribute set to pbsuser cannot successfully invoke pbs.reboot(), even if the owner is a PBS Manager or Operator. If this is attempted, the host is not rebooted, and the following message appears at log event class PBSEVENT_DEBUG2 in the MoM logs:
    <hook_name>; Not allowed to issue reboot if run as user.

    The <command> is an optional argument. It is a Python str which is executed instead of the reboot command that is the default for the system. For example:
    pbs.reboot("/usr/local/bin/my_reboot -s 10 -c 'going down in 10'")

    The specified <command> is executed in a shell on Linux/UNIX or via cmd on Windows.

pbs.route_destinations("<queue_spec>[,<queue_spec>,...]")
    where <queue_spec> is queue_name[@server_host[:port]]
    Creates an object that represents a route_destinations routing queue attribute. Instantiation of these objects requires a formatted input string.

pbs.select("[N:]res=val[:res=val][+[N:]res=val[:res=val]...]")
    Creates a select object representing the job's select specification. Instantiation of these objects requires a formatted input string. Example:
    sel = pbs.select("2:ncpus=1:mem=5gb+3:ncpus=2:mem=5gb")
    s = repr(sel) (or s = `sel`)
    letter = s[3] (assigns 'c' to letter)
    s = s + "+5:scratch=10gb" (append to string)
    sel = pbs.select(s) (reset the value of sel)

pbs.size(<integer>)
    Creates a PBS size object using the given integer value, storing the value as the number of bytes. Size objects can be specified using either an integer or a string. See the "pbs.size("<integer><suffix>")" creation method.

pbs.size("<integer><suffix>")
    Creates a PBS size object out of the given string specification. See the PBS Professional Reference Guide for suffix information. The size of a word is the word size on the execution host. Size objects can be specified using either an integer or a string. To operate on pbs.size instances, use the "+" and "-" operators. To compare pbs.size instances, use the "==", "!=", ">", "<", ">=", and "<=" operators. Example: the sizes are normalized to the smaller of the 2 suffixes. In this case, "10gb" becomes "10240mb" and is added to "10mb":
    sz = pbs.size("10gb")
    sz = sz + 10mb
    10250mb
    Example: the following returns True because sz is greater than 100 bytes:
    if sz > 100:
    gt100 = True

pbs.software("<software_info_string>")
    Creates an object representing a site-dependent software resource. Instantiation of these objects requires a formatted input string.

pbs.staging_list("<filespec>[,<filespec>,...]")
    where <filespec> is <execution_path>@<storage_host>:<storage_path> Creates an object representing a job file staging parameters list. To use a staging list object:
    pbs.job.stagein = pbs.staging_list(....)
    Instantiation of these objects requires a formatted input string.

pbs.state_count("Transit:<U>Queued:<V>Held:<W>Running:<X>Exiting:<Y>Begun:<Z>)
    Instantiates an object representing a state_count attribute. Instantiation of these objects requires a formatted input string.

pbs.user_list("<user>[@<host>][,<user>@<host>...]")
    Creates an object representing a PBS user list. To use a user list object:
    pbs.job.User_List = pbs.user_list(....)
    Instantiation of these objects requires a formatted input string.

pbs.version("<pbs_version_string>")
    Creates an object representing the PBS version string. Instantiation of these objects requires a formatted input string.

ATTRIBUTES AND RESOURCES
Hooks can read Server, Queue, or reservation resources. Hooks can read vnode or job attributes and resources. Hooks can modify

    The resources requested by a job
    The resources used by a job
    The attributes of a job
    The resource arguments to pbs_rsub
    Vnode attributes and resources
    The shell or program to be executed in a job
    The arguments to the shell or program to be executed in a job
    The environment of the job

Custom and built-in PBS resources are represented in Python dictionaries, where the resource names are the dictionary keys. Built-in resources are listed in pbs_resources(7B). You reference a resource through a vnode, the Server, the event that triggered the hook, or the current job, for example:

    pbs.server().resources_available["< resource name>"]
    pbs.event().job.Resource_List["< resource name>"]
    pbs.event().vnode_list[<vnode name>].resources_available["< resource name >"]

The resource name must be in quotes. Example: Get the number of CPUs:

    ncpus = Resource_List["ncpus"]

An instance R of a job resource can be set as follows:

    R["<resource name>"] = <resource value>

For example:

    pbs.event().job().Resource_List["mem"] = 8gb

EXCEPTIONS

pbs.BadAttributeValueError
    Raised when setting the attribute value of a pbs.* object to an invalid value.

pbs.BadAttributeValueTypeError
    Raised when setting the attribute value of a pbs.* object to an invalid value type.

pbs.BadResourceValueError
    Raised when setting the resource value of a pbs.* object to an invalid value.

pbs.BadResourceValueTypeError
    Raised when setting the resource value of a pbs.* object to an invalid value type.

pbs.EventIncompatibleError
    Raised when referencing a non-existent attribute in pbs.event().

pbs.UnsetAttributeNameError
    Raised when referencing a non-existent name of an attribute.

pbs.UnsetResourceNameError
    Raised when referencing a non-existent name of a resource.

SystemExit
    Raised when accepting or rejecting an action.

If a hook encounters an unhandled exception:

    PBS rejects the corresponding action, and an error message is printed to stderr.
    A message is printed to the daemon log.

SEE ALSO
The PBS Professional Administrator's Guide,
pbs_hook_attributes(7B), pbs_resources(7B), qmgr(1B)