xpbs - Graphical
Interface to PBS
The xpbs command provides
a user-friendly point-and-click interface to PBS commands. Please see the
sections below for a tour and tutorials. Also, within every dialog box, a
Help button can be found for assistance.
Running xpbs will initially
load preference settings defined by the system administrator in the global
.xpbsrc file. And then it checks the user's ~/.xpbsrc file. This file defines
various X resources like fonts, colors, list of PBS hosts to query, criteria
for listing queues and jobs, and various view states. See Preferences section below for a list of resources that
can be set.
To run xpbs as a regular,
non-privileged user:
setenv DISPLAY <display_host>:0
xpbs
This section describes the main
parts of the xpbs display:
xpbs Main Window
|
Click
here to view a full-size image.
The main window is
composed of 5 distinct areas (subwindows) arranged vertically (one on top
of another) in the following order:
1) Menu
2) Hosts
3) Queues
4) Jobs
5) Info
The Menu area
is composed of a row of command buttons that signal some action with a click
of the left mouse button. The buttons are:
- Update Data Manually - to
update the information on hosts, queues, and jobs.
- Update Data
Auto - same as "Update" except updating is done automatically every <some
specified> number of minutes.
- Submit - for
submitting a job to any of the queues managed by the selected host(s).
- Track Job -
for periodically checking for returned output files of jobs.
- Preferences
- for setting certain parameters such as the list of server host(s) to query.
- Close - for
exiting xpbs plus saving the current setup information
in the user's $HOME/.xpbsrc file. Information saved include the selected
host(s), queue(s), job(s), the different jobs listing criteria, and the
view states (i.e. minimized/maximized) of the Hosts, Queues, and Jobs regions.
- Help - contains
some help information.
The Hosts area is composed
of a leading horizontal HOSTS bar, a listbox, and a set of command buttons.
The HOSTS bar contains a minimize/maximize button, identified by a dot or
a rectangular image, for displaying or getting rid of the Hosts region. The
listbox displays information about favorite server host(s), and each entry
is meant to be selected via a single left mouse button click, shift key
+ mouse button 1 click for contiguous selection, or ctrl key + mouse button
1 click for non-contiguous selection. The command buttons represent actions
on selected host(s), and commonly found buttons are:
- detail - for obtaining detailed
information about selected server host(s). This functionality can also be
achieved by double clicking on an entry in the Hosts listbox.
- terminate -
for terminating PBS servers on selected host(s). (-admin only)
The server hosts
can be chosen by specifying in the ~/.xpbsrc file (or .Xdefaults) the resource:
*serverHosts: hostname1 hostname2 ...
Another way of specifying
the host is to click on the Preferences button in the Menu region, and manipulate
the server Hosts entry widget from the preferences dialog box.
The Queues
area is composed of a leading horizontal QUEUES bar, a listbox, and a set
of command buttons. The QUEUES bar lists the hosts that are consulted when
listing queues; the bar also contains a minimize/maximize button for displaying
or iconizing the Queues region. The listbox displays information about queues
managed by the server host(s) selected from the Hosts listbox; each listbox
entry is meant to be selected (highlighted) via a single left mouse button
click, shift key + mouse button 1 click for contiguous selection, or ctrl
key + mouse button 1 click for non-contiguous selection. The command buttons
represent actions for operating on selected queue(s), and commonly found
buttons are:
- detail - for obtaining detailed
information about selected queue(s). This functionality can also be achieved
by double clicking on a Queues listbox entry.
The Jobs area
is composed of a leading horizontal JOBS bar, a listbox, and a set of command
buttons. The JOBS bar lists the queues that are consulted when listing jobs;
the bar also contains a minimize/maximize button for displaying or iconizing
the Jobs region. The listbox displays information about jobs that are found
in the queue(s) selected from the Queues listbox; each listbox entry is
meant to be selected (highlighted) via a single left mouse button click,
shift key + mouse button 1 click for contiguous selection, or ctrl key +
mouse button 1 click for non-contiguous selection. The region just above
the Jobs listbox shows a collection of command buttons whose labels describe
a corresponding criteria used for filtering the Jobs listbox contents. The
list of jobs can be selected according to the owner of jobs (Owners), job
state (Job_States), name of the job (Job_Name), type of hold placed on the
job (Hold_Types), the account name associated with the job (Account_Name),
checkpoint attribute (Checkpoint), time the job is eligible for queueing/execution
(Queue_Time), resources requested by the job (Resources), priority attached
to the job (Priority), and whether or not the job is rerunnable (Rerunnable).
The selection criteria can be modified by clicking on any of the appropriate
command buttons to bring up a selection box. The criteria command buttons
are accompanied by a "Select Jobs" button, which when clicked, will update
the contents of the Jobs listbox based on the new selection criteria.
Finally, to the
right of the listbox, the Jobs region is accompanied by the following command
buttons, for operating on selected job(s):
- detail - for obtaining detailed
information about selected job(s). This functionality can also be achieved
by double clicking on a Jobs listbox entry.
- modify - for
modifying attributes of the selected job(s).
- delete - for
deleting the selected job(s).
- hold - for placing
some type of hold on selected job(s).
- release - for
releasing held job(s).
- signal - for
sending signals to selected job(s) that are running.
- msg - for writing
a message string into the output streams of the selected job(s).
- move - for moving
selected job(s) into some specified destination queue.
- order - for
exchanging order of two selected jobs in a queue.
- run - for running
selected job(s). (-admin only)
- rerun - for
requeueing selected job(s) that are running. (-admin only)
The Info Area
shows the progress of the commands' executed by xpbs. Look into this
box for errors.
Some of the widgets used in xpbs
and how they are manipulated are described in the following:
- listbox - can be multi-selectable
(a number of entries can be selected/highlighted using a mouse click) or
single-selectable (one entry can be highlighted at a time). For a multi-selectable
listbox, the following operations are allowed:
- single click with mouse button
1 to select/highlight an entry.
- shift key
+ mouse button 1 to contiguously select more than one entry.
- ctrl key
+ mouse button 1 to non-contiguously select more than one entry. NOTE: For
systems running Tk < 4.0, the newly selected item is reshuffled to appear
next to already selected items.
- click the
"Select All/Deselect All" button to select all entries or deselect all entries
at once.
- double clicking
an entry usually activates some action that uses the selected entry as a
parameter.
- scrollbar
- usually appears either vertically or horizontally and contains 5 distinct
areas that are mouse clicked to achieve different effects:
- top arrow - Causes the view
in the associated widget to shift up by one unit (i.e. the object appears
to move down one unit in its window). If the button is held down the action
will auto-repeat.
- top gap
- Causes the view in the associated window to shift up by one less than
the number of units in the window (i.e. the portion of the object that used
to appear at the very top of the window will now appear at the very bottom).
If the button is held down the action will auto-repeat.
- slider -
Pressing button 1 in this area has no immediate effect except to cause the
slider to appear sunken rather than raised. However, if the mouse is moved
with the button down then the slider will be dragged, adjusting the view as
the mouse is moved.
- bottom gap
- Causes the view in the associated window to shift down by one less than
the number of units in the window (i.e. the portion of the object that used
to appear at the very bottom of the window will now appear at the very top).
If the button is held down the action will auto-repeat.
- bottom arrow
- Causes the view in the associated window to shift down by one unit (i.e.
the object appears to move up one unit in its window). If the button is held
down the action will auto-repeat.
- entry
- brought into focus with a click of the left mouse button. To manipulate
this widget, simply type in the text value. Use of arrow keys, mouse selection
of text for deletion or overwrite, copying and pasting with sole use of
mouse buttons are permitted. This widget is usually accompanied by a scrollbar
for horizontally scanning a long text entry string.
- matrix of
entry boxes - usually shown as several rows of entry widgets where a
number of entries (called fields) can be found per row. The matrix is accompanied
by up/down arrow buttons for paging through the rows of data, and each group
of fields gets one scrollbar for horizontally scanning long entry strings.
Moving from field to field can be done using the <Tab>, <Ctrl-f>,
or <Ctrl-b> (move backwards) keys.
- spinbox
- a combination of an entry widget and a horizontal scrollbar. The entry
widget will only accept values that fall within a defined list of valid values,
and incrementing through the valid values is done by clicking on the up/down
arrows.
- button
- a rectangular region appearing either raised or pressed that invokes an
action when clicked with the left mouse button. When the button appears pressed,
then hitting the <RETURN> key will automatically select the button.
- text -
an editor like widget. This widget is brought into focus with a click of the
left mouse button. To manipulate this widget, simply type in the text. Use
of arrow keys, backspace/delete key, mouse selection of text for deletion
or overwrite, copying and pasting with sole use of mouse buttons are permitted.
This widget is usually accompanied by a scrollbar for vertically scanning
a long entry.
Submitting a PBS
job requires only to manipulate the widgets found in the Submit window.
xpbs Main Window
|
Click
here to view a full-size image.
To submit a job, do
the following steps:
- Select a host from the HOSTS
listbox in the main xpbs display.
- Click on the
"Submit" button located in the Menu bar.
- The submit dialog
box is composed of 4 distinct regions:
(1) Job Script
(2) OPTIONS
(3) OTHER OPTIONS
(4) Command Buttons
The Job Script
file region is at the upper left, the OPTIONS region containing various
widgets for setting job attributes is scattered all over the dialog box,
the OTHER OPTIONS is located just below the Job Script file region, and
Command Buttons region is at the bottom.
The job script
region is composed of a header box, the text box, FILE entry box, and a
couple of buttons labeled "load" and "save". If you have a script file containing
PBS options and executable lines, then type the name of the file on the
FILE entry box, and then click on the "load" button. The various widgets
in the Submit window will get loaded with values found in the script file.
The script file text box will only be loaded with executable lines (non-PBS)
found in the script. The job script header box has a "Prefix" entry box
that can be modified to specify the PBS directive to look for when parsing
a script file for PBS options.
If you don't
have a script file, you can start typing the executable lines of the job
in the file text box.
- Start manipulating
the various widgets in the Submit window. Particularly, pay close attention
to the Destination listbox. This box lists all the queues found in the host
that you selected. A special entry called "@host" refers to the default queue
at host. Select appropriately the destination queue of the job. More options
can be found by clicking the OTHER OPTIONS buttons.
- At the bottom
of the Submit window, click "confirm submit". You can also click on "interactive"
to run the job interactively. Running a job interactively will open an xterm
window to your display host containing the session.
NOTE: The script
FILE entry box is accompanied by a "save" button that you click to save
the current widget values to the specified file in a form that can later
be read by xpbs or by the qsub command.
Modifying a PBS job requires
only to manipulate the widgets found in the Modify window. To modify a job
or jobs, do the following steps:
- Select one or more jobs from
the JOBS listbox in the main xpbs display.
- Click on the
"modify" button located to the right of the listbox.
- The Modify window
is structured similarly to the Submit window. Simply manipulate the widgets
to specify replacement or additional values of job attributes.
- Click on the
"confirm modify" button located at the bottom of the dialog box.
Deleting a PBS job requires only
to manipulate the widgets found in the Delete window. To delete a job or
jobs, do the following steps:
- Select one or more jobs from
the JOBS listbox in the main xpbs display.
- Click on the
"delete" button located to the right of the listbox.
- Manipulate the
spinbox widget to set the kill delay signal interval.
- Click on the
"delete" button located at the bottom of the dialog box.
If you want to be informed of
returned output files of current jobs, and be able to quickly see the contents
of those files, then enable the "track job" feature as follows:
- Submit all the jobs that you
want monitored.
- Click on the
"Track Job" button located in the Menu bar to bring up the Track Job dialog
box.
- Specify the list
of user names, whose jobs are to be monitored for returned output files,
in the matrix located at the upper left of the dialog box.
- Manipulate the
minutes spinbox, located just below the user names matrix, to specify the
interval value when output files will be periodically checked.
- Specify the location
of job output files (whether locally or remotely) by clicking on one of the
radio buttons located at the upper right of the dialog box. If the output
files are returned to some remote host, then xpbs will execute an
"RSH <remote_host> test -f <output_files>" to test the existence
of the files.
NOTE: Be sure
the files are accessible from the host where xpbs was run (i.e. .rhosts
appropriately set).
- Click "start
tracking" button located at the bottom of the dialog box to:
- cancel any previous tracking
- build a new list of jobs to be monitored for returned
output files based on currently queued jobs.
- start periodic tracking.
- Click on "close
window" button.
When an output file
for a job being monitored is found, then the "Track Job" button (the one
that originally invoked the Track Job dialog box) will turn into a different
color, and the "Jobs Found Completed" listbox, located in the Track Job dialog
box, is then loaded with the corresponding job id(s). Then click on a job
id to see the contents of the output file and the error file. Click "stop
tracking" if you want to cancel tracking.
Click on the Close button located
in the Menu bar to leave xpbs. It will bring up a dialog box asking
for a confirmation in regards to saving state information like the view
states (minimize/maximize) of the HOSTS, QUEUES, and JOBS subwindows, and
various criteria for listing queues and jobs. The information is saved in
~/.xpbsrc file.
The resources that can be set
in the X resources file, ~/.xpbsrc, are:
*serverHosts
list of server hosts (space separated) to query by
xpbs.
*xtermCmd
the xterm command to run driving an interactive PBS
session.
*labelFont
font applied to text appearing in labels.
*fixlabelFont
font applied to text that label fixed-width widgets
such as listbox labels. This must be a fixed-width
font.
*textFont
font applied to a text widget. Keep this as fixed-width
font.
*backgroundColor
the color applied to background of frames, buttons,
entries, scrollbar handles.
*foregroundColor
the color applied to text in any context (under
selection, insertion, etc...).
*activeColor
the color applied to the background of a selection, a
selected command button, or a selected scroll bar
handle.
*disabledColor
color applied to a disabled widget.
*signalColor
color applied to buttons that signal something to the
user about a change of state. For example, the color of
the "Track Job" button when returned output files are
detected.
*shadingColor
a color shading applied to some of the frames to
emphasize focus as well as decoration.
*selectorColor
the color applied to the selector box of a radiobutton
or checkbutton.
*selectHosts
list of hosts (space separated) to automatically
select/highlight in the HOSTS listbox.
*selectQueues
list of queues (space separated) to automatically
select/highlight in the QUEUES listbox.
*selectJobs
list of jobs (space separated) to automatically
select/highlight in the JOBS listbox.
*selectOwners
list of owners (space separated) checked when limiting
the jobs appearing on the Jobs listbox in the main xpbs
window. See -j option in qselect(1B) for format.
*selectStates
list of job states to look for (do not space separate)
when limiting the jobs appearing on the Jobs listbox in
the main xpbs window. See -s option in qselect(1B) for
format.
*selectRes
list of resource amounts (space separated) to consult
when limiting the jobs appearing on the Jobs listbox in
the main xpbs window. See -l option in qselect(1B) for
format.
*selectExecTime
the Execution Time attribute to consult when limiting
the list of jobs appearing on the Jobs listbox in the
main xpbs window. See -a option in qselect(1B) for
format.
*selectAcctName
the name of the account that will be checked when
limiting the jobs appearing on the Jobs listbox in the
main xpbs window. See -A option in qselect(1B) for
format.
*selectCheckpoint
the checkpoint attribute relationship (including the
logical operator) to consult when limiting the list of
jobs appearing on the Jobs listbox in the main xpbs
window. See -c option in qselect(1B) for format.
*selectHold
the hold types string to look for in a job when
limiting the jobs appearing on the Jobs listbox in the
main xpbs window. See -h option in qselect(1B) for
format.
*selectPriority
the priority relationship (including the logical
operator) to consult when limiting the list of jobs
appearing on the Jobs listbox in the main xpbs window.
See -p option in qselect(1B) for format.
*selectRerun
the rerunnable attribute to consult when limiting the
list of jobs appearing on the Jobs listbox in the main
xpbs window. See -r option in qselect(1B) for format.
*selectJobName
name of the job that will be checked when limiting the
jobs appearing on the Jobs listbox in the main xpbs
window. See -N option in qselect(1B) for format.
*iconizeHostsView
a boolean value (true or false) indicating whether or
not to iconize the HOSTS region.
*iconizeQueuesView
a boolean value (true or false) indicating whether or
not to iconize the QUEUES region.
*iconizeJobsView
a boolean value (true or false) indicating whether or
not to iconize the JOBS region.
xpbs calls PBS commands
as follows:
Command Button PBS Command
-------------- -----------
detail (Hosts) qstat -B -f <selected server_host(s)>
terminate qterm <selected server_host(s)>
detail (Queues) qstat -Q -f <selected queue(s)>
stop qstop <selected queue(s)>
start qstart <selected queue(s)>
enable qenable <selected queue(s)>
disable qdisable <selected queue(s)>
detail (Jobs) qstat -f <selected job(s)>
modify qalter <selected job(s)>
delete qdel <selected job(s)>
hold qhold <selected job(s)>
release qrls <selected job(s)>
run qrun <selected job(s)>
rerun qrerun <selected job(s)>
signal qsig <selected job(s)>
msg qmsg <selected job(s)>
move qmove <selected job(s)>
order qorder <selected job(s)>
|
){kind=link}
){kind=link}