pbs_python(1B)

NAME
pbs_python - Python interpreter for debugging a hook script from the command line

SYNOPSIS
pbs_python --hook [-e <log event mask>] [-i <event input file>]
    [-L <log dir>] [-l <log file>] [-o <hook execution record>]
    [-r <resourcedef file>] [-s <site data file>] [<Python script>]
pbs_python <standard Python options> pbs_python --version

DESCRIPTION
The PBS Python interpreter, pbs_python, is a wrapper for Python. You can use the pbs_python wrapper that is shipped with PBS to debug hooks. Either:
    Use the --hook option to pbs_python to run pbs_python as a wrapper to Python, employing the pbs_python options. With the --hook option, you cannot use the standard Python options. The rest of this man page covers how to use pbs_python with the --hook option. Do not use the --hook option, so pbs_python runs the Python interpreter, with the standard Python options, and without access to the pbs_python options.
Debugging Hooks
You can get each hook to write out debugging files, and then modify the files and use them as debugging input to pbs_python. Alternatively, you can write them yourself. Debugging files can contain information about the event, about the site, and about what the hook changed. You can use these as inputs to a hook when debugging. For a complete description of using pbs_python with debugging files, see "Debugging Hooks" in the PBS Professional Hooks Guide.

Options to pbs_python

--hook
    This option is a switch. When you use this option, you can use the PBS Python module (via "import pbs"), and the other options described here are available. When you use this option, you cannot use the standard Python options. This option is useful for debugging. When you do not use this option, you cannot use the other options listed here, but you can use the standard Python options.

-e <log event mask>
    Sets the mask that determines which event types are logged by pbs_python. To see only debug messages, set the value to 0xd80. To see all messages, set the value to 0xffff.
    The pbs_python interpreter uses the same set of mask values that are used for the $logevent <mask> entry in the pbs_mom configuration file. See the pbs_mom.8B man page. Available only when --hook option is used.

-i <event input file>
    Text file containing data to populate pbs.event() objects. Each line specifies an attribute value or a resource value. Syntax of each input line is one of the following:
    <object name>.<attribute name>=<attribute value>
    <object name>.<resource list>[<resource name>]=<resource value>

    Where
    <object name> is a PBS object name which can refer to its sub-objects. Examples: "pbs.event()", "pbs.event().job", "pbs.event().vnode_list["<vnode name>"]".

    Example input file:
    pbs.event().hook_name=proto
    pbs.event().hook_type=site
    pbs.event().type=queuejob
    pbs.event().requestor=user1
    pbs.event().requestor_host=host1
    pbs.event().hook_alarm=40
    pbs.event().job.id=72
    pbs.event().job.Job_Name=job1
    pbs.event().job.Resource_List[ncpus]=5
    pbs.event().job.Resource_List[mem]=6mb
    pbs.event().vnode_list["host1"].resources_available["ncpus"] = 5
    pbs.event().vnode_list["host1"].resources_available["mem"] = 300gb

    Available only when --hook option is used.

-L <log dir>
    Directory holding the log file where pbs.logmsg() and pbs.logjobmsg() write their output. Default is current working directory where pbs_python is executed. Available only when --hook option is used.

-l <log file>
    Log file where pbs.logmsg() and pbs.logjobmsg() write their output. Default file name is current date in yyyymmdd format. Available only when --hook option is used.

-o <hook execution record>
    The hook execution record contains the changes made after executing the hook script, such as the attributes and resources set in any pbs.event() jobs and reservations, whether an action was accepted or rejected, and any pbs.reject() messages.
    Example hook execution record:
    pbs.event().job.Job_Name=job2
    pbs.event().job.Resource_List[file]=60gb
    pbs.event().job.Resource_List[ncpus]=5
    pbs.event().job.Resource_List[mem]=20gb
    pbs.event().job.Account_Name=account2
    pbs.event().reject=True
    pbs.event().reject_msg=No way!

    Without this option, output goes to stdout.

    Available only when --hook option is used.

-r <resourcedef file>
    File/path name containing a resource definition specifying a custom resource whose Python type is pbs.resource.
    Format:
    <resource name> type=<typename> [flag=<value>]
    This file has the same format as the PBS_HOME/server_priv/resourcedef file. Available only when --hook option is used.

-s <site data file>
    The site data file can contain any relevant information about the server, queues, vnodes, and jobs at the server. This file can be written by a hook or by the administrator.
    When the hook writes it, this file contains the values that populate the server, queues, vnodes, reservations, and jobs, with all attributes and resources for which there are values.
    The site data file is named hook_<event type>_<hook name>_<random integer>.data. Available only when --hook option is used.

--version
    The pbs_python command prints its version information and exits. This option can only be used alone.

ARGUMENTS

<Python script>
    The hook script to execute. We recommend importing the PBS Python module at the start of the script:
    import pbs

    If you do not specify Python script, you can perform interactive debugging. If you type the following:
    pbs_python --hook -i hook.input

    The interpreter displays a prompt:
    >>

    You can type your Python lines at the prompt:
    >>import pbs
    >> e=pbs.event().job
    >> print e.id
    <job ID>