xpbs(1B) PBS xpbs(1B)
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/stop
ping/disabling/enabling queues, and running/rerun
ning 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 adminis
trator 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
various 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 <display_host>:0
xpbs
To run xpbs with the additional purpose of terminating PBS
servers, stopping and starting queues, or running/rerun
ning 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
Local 1
xpbs(1B) PBS xpbs(1B)
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 (subwin
dows) 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 but
tons that signal some action with a click of the left
mouse button. The buttons are:
Manual Update to update the information on
hosts, queues, and jobs.
Auto Update same as Manual Update except
updating is done automati
cally every <some specified>
number of minutes.
Track Job for periodically checking
for returned output files of
jobs.
Preferences for setting certain parame
ters such as the list of
server host(s) to query.
Help contains some help informa
tion.
About tells of the author and who
to send comments, bugs, sug
gestions to.
Close for exiting xpbs plus saving
the current setup informa
tion (if anything had
changed) in the user's
$HOME/.xpbsrc file. Informa
tion saved include the
selected host(s), queue(s),
job(s), the different jobs
listing criteria, the view
states (i.e. minimized/max
imized) of the Hosts,
Local 2
xpbs(1B) PBS xpbs(1B)
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 iconiz
ing 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 selec
tion. 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 function
ality can also be achieved by double
clicking on an entry in the Hosts list
box.
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 horizon
tal 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 list
box entry is meant to be selected (highlighted) via a sin
gle left mouse button click, shift key + mouse button 1
click for contiguous selection, or cntrl key + mouse but
ton 1 click for non-contiguous selection. The command but
tons 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
Local 3
xpbs(1B) PBS xpbs(1B)
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 dis
plays 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 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 accord
ing 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. Please see qse--
lect(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 operat
ing 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.
Local 4
xpbs(1B) PBS xpbs(1B)
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 out
put streams of the selected job(s).
move for moving selected job(s) into some spec
ified 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)
Info. The Info Area shows the progress of the commands'
executed by xpbs. Look into this box for errors. The INFO
bar also contains a minimize/maximize button for display
ing 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 run
ning Tk < 4.0, the newly selected item is reshuffled
to appear next to already selected items.
Local 5
xpbs(1B) PBS xpbs(1B)
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 hori
zontally 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 num
ber 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
Local 6
xpbs(1B) PBS xpbs(1B)
widget is usually accompanied by a scrollbar for hori
zontally 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 <Tab>, <Cntrl-f>,
or <Cntrl-b> (move backwards) keys.
5. spinbox - a combination of an entry widget and a hori
zontal 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 hitting the <RETURN> key will automatically select
the button.
7. 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 wid
get is usually accompanied by a scrollbar for verti
cally scanning a long entry.
SUBMITTING JOBS
Submitting a PBS job requires only to manipulate the wid
gets found in the Submit window. 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
Local 7
xpbs(1B) PBS xpbs(1B)
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.
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 exe
cution 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 atten
tion 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 appropri
ately 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 con
firm 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 cur
rent 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 wid
gets 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.
Local 8
xpbs(1B) PBS xpbs(1B)
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 fol
lows:
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
Local 9
xpbs(1B) PBS xpbs(1B)
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 <remote_host> test -f <output_files>
to test the existence of the files. RSH is
whatever 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
appropriately 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 cur
rently 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 corre
sponding 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
criteria 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
Local 10
xpbs(1B) PBS xpbs(1B)
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
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
Local 11
xpbs(1B) PBS xpbs(1B)
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 win
dow. Specify value as "Owners: <list_of_owners>".
See -u option in qselect(1B) for format of
<list_of_owners>.
*selectStates
list of job states to look for (do not space sepa
rate) when limiting the jobs appearing on the Jobs
listbox in the main xpbs window. Specify value as
"Job_States: <states_string>". See -s option in
qselect(1B) for format of <states_string>.
*selectRes
list of resource amounts (space separated) to con
sult when limiting the jobs appearing on the Jobs
listbox in the main xpbs window. Specify value as
"Resources: <res_string>". See -l option in qse--
lect(1B) for format of <res_string>.
*selectExecTime
the Execution Time attribute to consult when limit
ing the list of jobs appearing on the Jobs listbox
in the main xpbs window. Specify value as
"Queue_Time: <exec_time>". See -a option in qse--
lect(1B) for format of <exec_time>.
*selectAcctName
the name of the account that will be checked when
limiting the jobs appearing on the Jobs listbox in
the main xpbs window. Specify value as
"Account_Name: <account_name>". See -A option in
qselect(1B) for format of <account_name>.
*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:
<checkpoint_arg>". See -c option in qselect(1B)
for format of <checkpoint_arg>.
*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. Specify value as
"Hold_Types: <hold_string>". See -h option in
Local 12
xpbs(1B) PBS xpbs(1B)
qselect(1B) for format of <hold_string>.
*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 win
dow. Specify value as "Priority: <prior
ity_value>". See -p option in qselect(1B) for for
mat of <priority_value>.
*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: <rerun_val>". See -r option in qse--
lect(1B) for format of <rerun_val>.
*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: <job
name>". See -N option in qselect(1B) for format of
<jobname>.
*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:
{ <arch-type1> resname1 resname2 ... resnameN }
{ <arch-type2> resname1 resname2 ... resnameN }
. . .
{ <arch-typeN> resname1 resname2 ... resnameN }
XPBS AND PBS COMMANDS
xpbs calls PBS commands as follows:
Command Button PBS Command
Local 13
xpbs(1B) PBS xpbs(1B)
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)>
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), qre
run(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 14