xpbs Manual Page
NAME
xpbs - GUI front end to PBS commands
SYNOPSIS
xpbs [-admin]
DESCRIPTION
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.
OPTIONS
-admin A mode where additional buttons are made available
for terminating PBS servers,
starting/stopping/disabling/enabling queues, and
running/rerunning jobs.
GETTING STARTED
Running xpbs will initialize the X resource database from
various sources in the following order:
1. The RESOURCE_MANAGER property on the root window
(updated via xrdb) with settings usually defined in the
.Xdefaults file
2. Preference settings defined by the system administrator
in the global xpbsrc file
3. 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 vari-
ous view states. See PREFERENCES section below for a
list of resources that can be set.
RUNNING XPBS
To run xpbs as a regular, non-privileged user, type:
setenv DISPLAY :0
xpbs
To run xpbs with the additional purpose of terminating PBS
servers, stopping and starting queues, or running/rerunning
jobs, then run:
xpbs -admin
NOTE: Be sure to appropriately set ~/.rhosts file if you're
planning to submit jobs to some remote server, and expecting
output files to be returned to the local host (where xpbs
was run). Usually, adding the PBS hostname running the
server to your .rhosts file locally, and adding the name of
the local machine to the .rhosts file at remote host, should
be sufficient.
Also, be sure that the PBS client commands are in the
default PATH because xpbs will call these commands.
THE XPBS DISPLAY
This section describes the main parts of the xpbs display.
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
Menu. The Menu area is composed of a row of command buttons
that signal some action with a click of the left mouse but-
ton. The buttons are:
Manual Update to update the information on
hosts, queues, and jobs.
Auto Update same as Manual Update except
updating is done automatically
every number of
minutes.
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.
Help contains some help information.
About tells of the author and who to
send comments, bugs, suggestions
to.
Close for exiting xpbs plus saving the
current setup information (if
anything had changed) in the
user's $HOME/.xpbsrc file.
Information saved include the
selected host(s), queue(s),
job(s), the different jobs list-
ing criteria, the view states
(i.e. minimized/maximized) of
the Hosts, Queues, Jobs, and
INFO regions, and anything in
the Preferences section.
Hosts. 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 iconizing
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 cntrl 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.
Submit for submitting a job to any of the queues
managed by the selected host(s).
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.
Queues. 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 cntrl 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.
stop for stopping the selected queue(s). (-admin
only)
start for starting the selected queue(s). (-admin
only)
disable for disabling the selected queue(s). (-admin
only)
enable for enabling the selected queue(s). (-admin
only)
Jobs. 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 informa-
tion 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 cntrl 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 criteria
used for filtering the Jobs listbox contents. The list of
jobs can be selected according to the owner of jobs (Own-
ers), 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. Please see
qselect(1B) for more details on how the jobs are filtered.
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 list-
box 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 run-
ning. (-admin only)
Info. The Info Area shows the progress of the commands' exe-
cuted by xpbs. Look into this box for errors. The INFO bar
also contains a minimize/maximize button for displaying or
iconizing the Info region.
WIDGETS USED IN XPBS
Some of the widgets used in xpbs and how they are manipu-
lated are described in the following:
1. 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:
a. single click with mouse button 1 to select/highlight
an entry.
b. shift key + mouse button 1 to contiguously select more
than one entry.
c. cntrl 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.
d. click the Select All/Deselect All button to select all
entries or deselect all entries at once.
e. double clicking an entry usually activates some action
that uses the selected entry as a parameter.
2. scrollbar - usually appears either vertically or horizon-
tally 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 win-
dow). 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.
3.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 usu-
ally accompanied by a scrollbar for horizontally scanning
a long text entry string.
4. 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 , , or
(move backwards) keys.
5. spinbox - a combination of an entry widget and a horizon-
tal 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.
6. 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 hit-
ting the key will automatically select the but-
ton.
7. text - an editor like widget. This widget is brought into
focus with a click of the left mouse button. To manipu-
late 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 JOBS
Submitting a PBS job requires only to manipulate the widgets
found in the Submit window. The submit dialog box is com-
posed 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 vari-
ous 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 execut-
able lines of the job in the file text box.
To submit a job, perform the following steps:
1. Select a host from the HOSTS listbox in the main
xpbs display.
2. Click on the Submit button located in the Menu bar.
3. Specify the script file containing the job execution
lines and job property values, or simply type in the
execution lines in the FILE textbox.
4. 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.
5. 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 con-
taining 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 ATTRIBUTES OF JOBS
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:
1. Select one or more jobs from the JOBS listbox in the
main xpbs display.
2. Click on the modify button located to the right of
the listbox.
3. The Modify window is structured similarly to the
Submit window. Simply manipulate the widgets to
specify replacement or additional values of job
attributes.
4. Click on the confirm modify button located at the
bottom of the dialog box.
DELETING JOBS
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:
1. Select one or more jobs from the JOBS listbox in the
main xpbs display.
2. Click on the delete button located to the right of
the listbox.
3. Manipulate the spinbox widget to set the kill delay
signal interval.
4. Click on the delete button located at the bottom of
the dialog box.
TRACKING RETURNED OUTPUT FILES
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:
1. Submit all the jobs that you want monitored.
2. Click on the Track Job button located in the Menu
bar to bring up the Track Job dialog box.
3. 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.
4. Manipulate the minutes spinbox, located just below
the user names matrix, to specify the interval
value when output files will be periodically
checked.
5. 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. Returned locally means the output
files will be returned back to the host where xpbs
was run. If the output files are returned to some
remote host, then xpbs will execute an
RSH test -f
to test the existence of the files. RSH is what-
ever you set the remote shell command to in the
corresponding entry box.
NOTE: Be sure the files are accessible from the
host where xpbs was run (i.e. .rhosts appropri-
ately set).
6. Click start/reset 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.
7. 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 double 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.
LEAVING XPBS
Click on the Close button located in the Menu bar to leave
xpbs. If anything had changed, 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, JOBS, and INFO subwindows, and various cri-
teria for listing queues and jobs. The information is saved
in ~/.xpbsrc file.
PREFERENCES
The resources that can be set in the X resources file,
~/.xpbsrc, are:
*serverHosts
list of server hosts (space separated) to query by
xpbs.
*timeoutSecs
specify the number of seconds before timing out waiting
for a connection to a PBS host.
*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 selec-
tion, insertion, etc...).
*activeColor
the color applied to the background of a selection, a
selected command button, or a selected scroll bar han-
dle.
*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 checked when limiting the jobs appearing
on the Jobs listbox in the main xpbs window. Specify
value as "Owners: ". See -u option in
qselect(1B) for format of .
*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. Specify value as "Job_States:
". See -s option in qselect(1B) for
format of .
*selectRes
list of resource amounts (space separated) to consult
when limiting the jobs appearing on the Jobs listbox in
the main xpbs window. Specify value as "Resources:
". See -l option in qselect(1B) for format
of .
*selectExecTime
the Execution Time attribute to consult when limiting
the list of jobs appearing on the Jobs listbox in the
main xpbs window. Specify value as "Queue_Time:
". See -a option in qselect(1B) for format
of .
*selectAcctName
the name of the account that will be checked when lim-
iting the jobs appearing on the Jobs listbox in the
main xpbs window. Specify value as "Account_Name:
". See -A option in qselect(1B) for for-
mat of .
*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. Specify value as "Checkpoint:
". See -c option in qselect(1B) for
format of .
*selectHold
the hold types string to look for in a job when limit-
ing the jobs appearing on the Jobs listbox in the main
xpbs window. Specify value as "Hold_Types:
". See -h option in qselect(1B) for for-
mat of .
*selectPriority
the priority relationship (including the logical opera-
tor) to consult when limiting the list of jobs appear-
ing on the Jobs listbox in the main xpbs window.
Specify value as "Priority: ". See -p
option in qselect(1B) for format of .
*selectRerun
the rerunnable attribute to consult when limiting the
list of jobs appearing on the Jobs listbox in the main
xpbs window. Specify value as "Rerunnable:
". See -r option in qselect(1B) for format
of .
*selectJobName
name of the job that will be checked when limiting the
jobs appearing on the Jobs listbox in the main xpbs
window. Specify value as "Job_Name: ". See
-N option in qselect(1B) for format of .
*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.
*iconizeInfoView
a boolean value (true or false) indicating whether or
not to iconize the INFO region.
*jobResourceList
a curly-braced list of resource names as according to
architecture known to xpbs. The format is as follows:
{ resname1 resname2 ... resnameN }
{ resname1 resname2 ... resnameN }
. . .
{ resname1 resname2 ... resnameN }
XPBS AND PBS COMMANDS
xpbs calls PBS commands as follows:
Command Button PBS Command
detail (Hosts) qstat -B -f
terminate qterm
detail (Queues) qstat -Q -f
stop qstop
start qstart
enable qenable
disable qdisable
detail (Jobs) qstat -f
modify qalter
delete qdel
hold qhold
release qrls
run qrun
rerun qrerun
signal qsig
msg qmsg
move qmove
order qorder
EXIT STATUS
Upon successful processing, the xpbs exit status will be a
value of zero.
If the xpbs command fails, the command exits with a value
greater than zero.
SEE ALSO
qalter(1B), qdel(1B), qhold(1B), qmove(1B), qmsg(1B)
qrerun(1B), qrls(1B), qselect(1B), qsig(1B), qstat(1B),
qorder(1B), qsub(1B), qdisable(8B), qenable(8B), qrun(8B),
qstart(8B), qstop(8B), qterm(8B).
Local Last change: 15