Using the PyPBS Package

In this section, we describe the usage of various OpenPBS C API functions through the PyPBS package. We assume that you are familiar with these functions and have read through their man pages (or at least have access to the man pages so you can look them up if this section does not make sense to you). Also, it might be useful to browse through the SWIG documentation to understand how SWIG translates the C functions, variables, and data structures so they are available through the Python module. However, we will also try to illustrate a lot of these features through examples in this section.

Accessing The Module

The PyPBS package provides a module named pbs which can be accessed in Python using an import statement such as:

import pbs

In interactive mode of the Python interpreter, a list of functions and variables available under the pbs module can be listed using the help function after importing the module:

>>> import pbs
>>> help(pbs)

OpenPBS C API Functions

The primary purpose of the PyPBS package is to provide access to the OpenPBS C API functions. All the functions listed in pbs_ifl.h are available with the same name in Python through the pbs module. For example, the pbs_connect() C-function can be called from Python as follows:

import pbs
connection_id = pbs.pbs_connect("pbsserver.mydomain.com")

As in the case of the C-function, the corresponding Python function returns an integer which identifies the connection and is required by almost all other OpenPBS functions. For example, here is the output from an interactive session:

>>> from pbs import pbs_connect, pbs_disconnect
>>> connection_id = pbs_connect ("pbsserver.mydomain.com") 
>>> print connection_id 
1
>>> pbs_disconnect(connection_id)
0

In the above example, we also demonstrate the use of pbs_disconnect() function. As seen here, the calls mirror the corresponding calls from a C program. However, things get a little hairy when functions take pointers to structures and/or return structures. For example, consider the pbs_statnode() function. According to the man page for this function (this is a good time to look it up if you have not read it before) it returns a value of type "pointer to a struct batch_status". This structure is defined as:

           struct batch_status {
               struct batch_status *next;
               char                *name;
               struct attrl        *attribs;
               char                *text;
           }

The corresponding function pbs_statnode() in the pbs module returns an instance of a class which behaves like a batch_status structure. If the pbs_statnode() C function returns a NULL pointer, then the pbs_statnode() Python function returns None. The pbs module follows this rule for all pointer types: if the corresponding C function returns a NULL pointer, it comes in as None through the pbs module.

The data members of the structure can be accessed the same way as any class in Python. For example, the next data member of the batch_status instance named foo can be accessed as foo.next. If the next batch_status is not available foo.next will be None..

One additional comment before we look at a real example. Functions such as pbs_statnode() take arguments which are pointers to various data types including structures. In many cases, in C programs a NULL pointer may be passed to these functions instead of a real instance. While using the pbs module, the equivalent of a NULL pointer is the string "NULL". Whenever, a NULL pointer is needed use the string "NULL" and everything should work as expected.

Now a real example. Here is a complete script which prints the names of all nodes as obtained from the default OpenPBS server and is available as the file examples/pbsnodes.py with the PyPBS source code.

#! /usr/bin/env python
# -*- Mode: python -*-
#
from pbs import *

server_id = pbs_connect( pbs_default() )

node_status = pbs_statnode(server_id, "", "NULL", "NULL")

while node_status:
    print node_status.name
    node_status = node_status.next

pbs_disconnect( server_id )

The examples/ directory under the PyPBS source code contains several real examples which illustrate the use of the PyPBS package.

Global Variables

Preprocessor Macros