# How to Run PBS Jobs in PTP

## Introduction

The PBS Eclipse plug-in, part of the Parallel Tools Platform (PTP), allows you to launch and monitor applications on local or remote PBS (Portable Batch System) Distributed Resource Managers.

Note: PTP 6.0 does not require the creation of separate Resource Managers and instead, the target configuration is specified on the Run Configuration dialog. This document has not been updated for PTP 6.0, but the Resources tab on the new Run Configuration menu should have approximately the same information as the Resource manager setup dialog described here, but this can vary depending on the target configuration / resource manager.

- For more up-to-date information on launching PTP jobs with PBS and other target system configurations, see Launching jobs with PBS

The PBS Resource Managers use the new configurable (JAXB) framework. (An in-detail explanation of the JAXB Model can be found in the PTP Developer Guide.) What follows here is a guide to the PBS-specific launch tabs. There are no special requirements to run the PBS Resource Managers.

## Preconfigured PBS Resource Manager Types

PTP provides two generic PBS Resource Managers, one which is configured for batch submissions to the scheduler (PBS-Generic-Batch), and one for interactive PBS submissions using a pseudo-terminal (i.e., "qsub -I"; PBS-Generic-Interactive). The settings in these configurations should work on most Torque systems and many PBS Pro setups, though there may be differences in some of the attributes for job submission which may have to be adjusted for depending on your local system.

## Submission Using the PBS Batch Resource Manager

When you select the PBS-Generic-Batch manager, the Run Configuration will have a Resources Tab with three sub-tabs available for use.

- Basic PBS Settings
- Advanced PBS Settings
- Import PBS Script

Each of these is an "independent" environment in the sense that the specific variables set on one are not necessarily included in the others, even though their underlying values are shared across all three tabs; the tab from which you select "Run" is the environment that applies to the job .

Thus if you use the Advanced Tab and set Job_Name to "pbs1", then switch to the Basic tab, you will see Job_Name set to "pbs1" there as well; however, if you launch from Basic, only the variables seen on the Basic tab will be included in the configuration and script for the job; any of the variables on the Advanced Tab not on the Basic Tab will revert to an undefined or default value.

### Basic Settings

Below is a view of the Basic tab. Job_Name and Wallclock Time are validated fields, meaning that values with a specific syntax must be provided (there are defaults); an error message on the top left of the screen will appear in red in case these are incorrect. Hovering over the Name label will display a tooltip, if there is one for that attribute.

At the left bottom of the tab there are three buttons, "View Script", "View Configuration" and "Restore Defaults". The first allows you to inspect what the batch script that is generated from the filled-in values will look like:

Similarly, the second button can be used to see the full configuration underlying this particular tab setting (this is the "environment" for the resource manager, and is useful to check to make sure the values you have set on the tab will be correctly reported to the resource manager):

"Restore Defaults" sets the values of the variables visible in this tab back to their defaults, if they have any. This is different from the "Revert" button on the lower right, which reverts to the previously saved changes. All changes should be saved using the "Apply" button next to it.

### Advanced Settings

The Advanced Tab exposes for configuration all the attributes for job submission as defined in the XML. The viewer allows you to select the ones that are applicable (only these will appear in the configuration). The text box above the table/tree containing the attribute list also displays a string of name=value defintions from the table (here for viewing convenience only). The table has typed values; it provides an appropriate editor (drop-down list, numerical spinner, checkbox, etc.) to fill in the value according to the value's type; doing "tab" after filling in the value effects the change. The check box at the top left "Show Only Checked Items" allows you to filter out unchecked items from the table list.

### Importing a Predefined Batch Script

If you wish to use a custom script that does more than just launch the application selected from your local or remote workspace, this tab is where you do it. The "Browse" button at the top right takes you first to your current workspace, in case you have imported a batch script there from either your local machine or a remote host; however, you can usually navigate from there to other directories in your local file system to search for a script.

The path of the selected script is displayed in the textbox to the left of the browse button, and the contents of the script in the large (scrolling) text area below. The script is not editable there; to edit, you will need to import it like any other file into your workspace. The selection can be cleared or cancelled using the "Clear" button.

The PBS import tab is preconfigured with an optional table viewer for selecting the variables from the environment which you wish to pass to the launch command along with the script.

NOTE:

1. The values should correspond to whatever the script is giving to PBS; if the current values in the environment do not match, they can be changed here. However, these are set for the benefit of the internal consistency of the PTP client, and do not override those hard-coded in script.
2. Unselecting the variable means that its value will not be passed to the resource manager.
3. If the error and output paths are not selected or blank, the default locations will be accessed by the monitor; these, however, require the Job_Name property to be set (and be correct; see further the following paragraph).
4. Setting the destination is for the benefit of monitoring consistency.

#### Reading remote output and error files

The JAXB/PBS manager has the capability of allowing you to stream in to the console the output and error files associated with a batch job when the job has completed. This is done in the XML definition file for the Basic and Advanced tabs by creating a link from the PBS batch attributes defining Output Path and Error Path to special (hidden) variables understood by the resource manager. If you set the PBS attributes, the change will be conveyed through the linked variables. If they are not set, the configuration provides a value corresponding to the default location where PBS would put them.

NOTE: If you are using the Import Script tab, the two paths must be manually adjusted to correspond to whatever you have done inside the script; the default definitions are provided, but these can be adjusted as necessary.

If there are files associated with this job, and the job completes, the "Get Job Error" and "Get Job Output" actions, activated by clicking the row associated with the job in the monitor job table, can be used to issue a streaming command which will write the file contents to the console. If the files do not exist, these actions will be disabled.

## Submission Using the PBS Interactive Resource Manager

The Interactive Resource Manager allows you to submit jobs through a pseudo-terminal. This is done by issuing "qsub -I" (plus any resource limits defined in the tab) upon the first launch, and waiting for the interactive job to start. When the job turns from SUBMITTED to RUNNING (this can be seen both from the reported state in monitor job table views, as well as by the disappearance of the progress bars for the submission), the job will then be streamed to the qsub terminal's standard input, just as it would when you submit from a shell command-line. Subsequent submissions will also be streamed to the same interactive terminal process, for as long as it is running. If the time limit expires, the next submission will resubmit the terminal request (qsub -I).

The Launch Tab for this kind of job closely resembles the Basic batch tab.

The job output will go to the console when the job starts to run, as seen here.

## Preferences

The preference options are mainly aids for the developer or user who wishes to reconfigure or modify the resource manager configuration. Since the PBS Resource Manager is configured from an XML definition file, the file can be cached the first time you add the resource manager (this is the default behavior), or you can set it to reread the file every time you start the Resource Manager. This is useful if you are doing customization (see below) and are configuring from a special XML file you have imported into your workspace. This way, if you make changes, they will automatically be picked up without having to reboot the application or recreate the Resource Manager.

1. From the "Eclipse" menu, select "Preferences"
2. Open Parallel Tools / Resource Managers / Configurable Resource Manager (JAXB)
3. Select "Always reload XML from URL" and click "Apply", then "OK".

The other options are useful if you are writing a new stream tokenizer for a command (which can be tricky); checking all four options usually produces quite a bit of output, so in that case it may be advisable to log the results to a file rather than stdout (at any rate the latter would be available only if PTP were running as an application within the Eclipse IDE platform, which is not the case for those modifying the XML simply from within the PTP package installation workspace).

## Customizing the Configuration

The Resource Manager configuration for PBS can be customized to suit the needs of the systems you habitually work with. Of course, an understanding of the basic structure and content of the XML definition is necessary for this, but often it may simply be a question of changing a few of the provided attribute defaults or definitions or a special command definition.

The way to provide a specialized XML configuration is by placing it in a project named "resourceManagers" in your current workspace. You can import an XML file into your workspace in three different ways:

- Using Import :: General :: File System for files on your local machine;
- Using Import :: Remote Systems :: Remote file system for files on a remote machine;
- Using Import :: Resource Managers :: Resource Manager Definition from Plug-in for the predefined definitions provided with the PTP distribution.

In the first two cases, you must have created the "resourceManagers" project first; the third wizard asks you if you wish to create one if one does not already exist. The following illustrates the last kind of import.

- Open up your Remote C/C++ perspective containing your workspace
- Right click in the Project Explorer and then select "Import :: Import..."

- Choose Resource Managers :: Resource Manager Definition from Plug-in

- Select one of the configurations from the drop-down list, and click "Finish".

The XML file will now appear in the "resourceManagers" directory; double-clicking on it will open an editor in your workspace. The XML editor which has been included in the PTP all-in-one download ("Eclipse for Parallel Application Developers") does syntax highlighting and also provides a design tree-view for examining its structure.

Back to Table of Contents