1xpbs(1B) PBS xpbs(1B)
2
6 xpbs - GUI front end to PBS commands
7
9 xpbs [-admin]
10
12 The xpbs command provides a user-friendly point-and-click interface to
13 PBS commands. Please see the sections below for a tour and tutorials.
14 Also, within every dialog box, a Help button can be found for assis‐
15 tance.
16
18 -admin A mode where additional buttons are made available for termi‐
19 nating PBS servers, starting/stopping/disabling/enabling
20 queues, and running/rerunning jobs.
21
23 Running xpbs will initialize the X resource database from various
24 sources in the following order:
25 1. The RESOURCE_MANAGER property on the root window (updated via
27 xrdb) with settings usually defined in the .Xdefaults file
28 2. Preference settings defined by the system administrator in the
30 global xpbsrc file
31 3. User's ~/.xpbsrc file - this file defines various X resources
33 like fonts, colors, list of PBS hosts to query, criteria for
34 listing queues and jobs, and various view states. See PREFER‐
35 ENCES section below for a list of resources that can be set.
36
38 To run xpbs as a regular, non-privileged user, type:
39 setenv DISPLAY <display_host>:0
41 xpbs
42 To run xpbs with the additional purpose of terminating PBS servers,
44 stopping and starting queues, or running/rerunning jobs, then run:
45 xpbs -admin
47 NOTE: Be sure to appropriately set ~/.rhosts file if you're planning to
49 submit jobs to some remote server, and expecting output files to be
50 returned to the local host (where xpbs was run). Usually, adding the
51 PBS hostname running the server to your .rhosts file locally, and
52 adding the name of the local machine to the .rhosts file at remote
53 host, should be sufficient.
54 Also, be sure that the PBS client commands are in the default PATH
56 because xpbs will call these commands.
57
59 This section describes the main parts of the xpbs display. The main
60 window is composed of 5 distinct areas (subwindows) arranged vertically
61 (one on top of another) in the following order:
62 1) Menu
63 2) Hosts
64 3) Queues
65 4) Jobs
66 5) Info
67 Menu. The Menu area is composed of a row of command buttons that signal
69 some action with a click of the left mouse button. The buttons are:
70 Manual Update to update the information on hosts,
72 queues, and jobs.
73 Auto Update same as Manual Update except updating is
75 done automatically every <some specified>
76 number of minutes.
77 Track Job for periodically checking for returned
79 output files of jobs.
80 Preferences for setting certain parameters such as
82 the list of server host(s) to query.
83 Help contains some help information.
85 About tells of the author and who to send com‐
87 ments, bugs, suggestions to.
88 Close for exiting xpbs plus saving the current
90 setup information (if anything had
91 changed) in the user's $HOME/.xpbsrc
92 file. Information saved include the
93 selected host(s), queue(s), job(s), the
94 different jobs listing criteria, the view
95 states (i.e. minimized/maximized) of the
96 Hosts, Queues, Jobs, and INFO regions,
97 and anything in the Preferences section.
98 Hosts. The Hosts area is composed of a leading horizontal HOSTS bar, a
100 listbox, and a set of command buttons. The HOSTS bar contains a mini‐
101 mize/maximize button, identified by a dot or a rectangular image, for
102 displaying or iconizing the Hosts region. The listbox displays informa‐
103 tion about favorite server host(s), and each entry is meant to be
104 selected via a single left mouse button click, shift key + mouse button
105 1 click for contiguous selection, or cntrl key + mouse button 1 click
106 for non-contiguous selection. The command buttons represent actions on
107 selected host(s), and commonly found buttons are:
108 detail for obtaining detailed information about selected
110 server host(s). This functionality can also be
111 achieved by double clicking on an entry in the Hosts
112 listbox.
113 Submit for submitting a job to any of the queues managed by
115 the selected host(s).
116 terminate for terminating PBS servers on selected host(s).
118 (-admin only)
119 The server hosts can be chosen by specifying in the ~/.xpbsrc file (or
121 .Xdefaults) the resource:
122 *serverHosts: hostname1 hostname2 ...
124 Another way of specifying the host is to click on the Preferences but‐
126 ton in the Menu region, and manipulate the server Hosts entry widget
127 from the preferences dialog box.
128 Queues. The Queues area is composed of a leading horizontal QUEUES bar,
131 a listbox, and a set of command buttons. The QUEUES bar lists the hosts
132 that are consulted when listing queues; the bar also contains a mini‐
133 mize/maximize button for displaying or iconizing the Queues region. The
134 listbox displays information about queues managed by the server host(s)
135 selected from the Hosts listbox; each listbox entry is meant to be
136 selected (highlighted) via a single left mouse button click, shift key
137 + mouse button 1 click for contiguous selection, or cntrl key + mouse
138 button 1 click for non-contiguous selection. The command buttons repre‐
139 sent actions for operating on selected queue(s), and commonly found
140 buttons are:
141 detail for obtaining detailed information about selected
143 queue(s). This functionality can also be achieved by
144 double clicking on a Queues listbox entry.
145 stop for stopping the selected queue(s). (-admin only)
147 start for starting the selected queue(s). (-admin only)
149 disable for disabling the selected queue(s). (-admin only)
151 enable for enabling the selected queue(s). (-admin only)
153 Jobs. The Jobs area is composed of a leading horizontal JOBS bar, a
156 listbox, and a set of command buttons. The JOBS bar lists the queues
157 that are consulted when listing jobs; the bar also contains a mini‐
158 mize/maximize button for displaying or iconizing the Jobs region. The
159 listbox displays information about jobs that are found in the queue(s)
160 selected from the Queues listbox; each listbox entry is meant to be
161 selected (highlighted) via a single left mouse button click, shift key
162 + mouse button 1 click for contiguous selection, or cntrl key + mouse
163 button 1 click for non-contiguous selection. The region just above the
164 Jobs listbox shows a collection of command buttons whose labels
165 describe criteria used for filtering the Jobs listbox contents. The
166 list of jobs can be selected according to the owner of jobs (Owners),
167 job state (Job_States), name of the job (Job_Name), type of hold placed
168 on the job (Hold_Types), the account name associated with the job
169 (Account_Name), checkpoint attribute (Checkpoint), time the job is eli‐
170 gible for queueing/execution (Queue_Time), resources requested by the
171 job (Resources), priority attached to the job (Priority), and whether
172 or not the job is rerunnable (Rerunnable). The selection criteria can
173 be modified by clicking on any of the appropriate command buttons to
174 bring up a selection box. The criteria command buttons are accompanied
175 by a Select Jobs button, which when clicked, will update the contents
176 of the Jobs listbox based on the new selection criteria. Please see
177 qselect(1B) for more details on how the jobs are filtered.
178 Finally, to the right of the listbox, the Jobs region is accompanied by
180 the following command buttons, for operating on selected job(s):
181 detail for obtaining detailed information about selected
183 job(s). This functionality can also be achieved by
184 double clicking on a Jobs listbox entry.
185 modify for modifying attributes of the selected job(s).
187 delete for deleting the selected job(s).
189 hold for placing some type of hold on selected job(s).
191 release for releasing held job(s).
193 signal for sending signals to selected job(s) that are run‐
195 ning.
196 msg for writing a message string into the output streams of
198 the selected job(s).
199 move for moving selected job(s) into some specified destina‐
201 tion queue.
202 order for exchanging order of two selected jobs in a queue.
204 run for running selected job(s). (-admin only)
206 rerun for requeueing selected job(s) that are running.
208 (-admin only)
209 Info. The Info Area shows the progress of the commands' executed by
212 xpbs. Look into this box for errors. The INFO bar also contains a mini‐
213 mize/maximize button for displaying or iconizing the Info region.
214
216 Some of the widgets used in xpbs and how they are manipulated are
217 described in the following:
218 1. listbox - can be multi-selectable (a number of entries can be
221 selected/highlighted using a mouse click) or single-selectable (one
222 entry can be highlighted at a time). For a multi-selectable listbox,
223 the following operations are allowed:
224 a. single click with mouse button 1 to select/highlight an entry.
226 b. shift key + mouse button 1 to contiguously select more than one
228 entry.
229 c. cntrl key + mouse button 1 to non-contiguously select more than
231 one entry. NOTE: For systems running Tk < 4.0, the newly
232 selected item is reshuffled to appear next to already selected
233 items.
234 d. click the Select All/Deselect All button to select all entries or
236 deselect all entries at once.
237 e. double clicking an entry usually activates some action that uses
239 the selected entry as a parameter.
240 2. scrollbar - usually appears either vertically or horizontally and
243 contains 5 distinct areas that are mouse clicked to achieve differ‐
244 ent effects:
245 top arrow Causes the view in the associated widget to shift up
247 by one unit (i.e. the object appears to move down one
248 unit in its window). If the button is held down the
249 action will auto-repeat.
250 top gap Causes the view in the associated window to shift up
252 by one less than the number of units in the window
253 (i.e. the portion of the object that used to appear at
254 the very top of the window will now appear at the
255 very bottom). If the button is held down the action
256 will auto-repeat.
257 slider Pressing button 1 in this area has no immediate
259 effect except to cause the slider to appear sunken
260 rather than raised. However, if the mouse is moved
261 with the button down then the slider will be
262 dragged, adjusting the view as the mouse is moved.
263 bottom gap Causes the view in the associated window to shift down
265 by one less than the number of units in the window
266 (i.e. the portion of the object that used to
267 appear at the very bottom of the window will now
268 appear at the very top). If the button is held down
269 the action will auto-repeat.
270 bottom arrow Causes the view in the associated window to shift down
272 by one unit (i.e. the object appears to move up one
273 unit in its window). If the button is held down the
274 action will auto-repeat.
275 3. entry - brought into focus with a click of the left mouse button.
278 To manipulate this widget, simply type in the text value. Use of
279 arrow keys, mouse selection of text for deletion or overwrite, copy‐
280 ing and pasting with sole use of mouse buttons are permitted. This
281 widget is usually accompanied by a scrollbar for horizontally scan‐
282 ning a long text entry string.
283 4. matrix of entry boxes - usually shown as several rows of entry wid‐
286 gets where a number of entries (called fields) can be found per row.
287 The matrix is accompanied by up/down arrow buttons for paging
288 through the rows of data, and each group of fields gets one scroll‐
289 bar for horizontally scanning long entry strings. Moving from field
290 to field can be done using the <Tab>, <Cntrl-f>, or <Cntrl-b> (move
291 backwards) keys.
292 5. spinbox - a combination of an entry widget and a horizontal scroll‐
295 bar. The entry widget will only accept values that fall within a
296 defined list of valid values, and incrementing through the valid
297 values is done by clicking on the up/down arrows.
298 6. button - a rectangular region appearing either raised or pressed
300 that invokes an action when clicked with the left mouse button.
301 When the button appears pressed, then hitting the <RETURN> key will
302 automatically select the button.
303 7. text - an editor like widget. This widget is brought into focus with
305 a click of the left mouse button. To manipulate this widget, simply
306 type in the text. Use of arrow keys, backspace/delete key, mouse
307 selection of text for deletion or overwrite, copying and pasting
308 with sole use of mouse buttons are permitted. This widget is usually
309 accompanied by a scrollbar for vertically scanning a long entry.
310
312 Submitting a PBS job requires only to manipulate the widgets found in
313 the Submit window. The submit dialog box is composed of 4 distinct
314 regions:
315 1) Job Script
317 2) OPTIONS
318 3) OTHER OPTIONS
319 4) Command Buttons
320 The Job Script file region is at the upper left, the OPTIONS region
322 containing various widgets for setting job attributes is scattered all
323 over the dialog box, the OTHER OPTIONS is located just below the Job
324 Script file region, and Command Buttons region is at the bottom.
325 The job script region is composed of a header box, the text box, FILE
327 entry box, and a couple of buttons labeled load and save. If you have
328 a script file containing PBS options and executable lines, then type
329 the name of the file on the FILE entry box, and then click on the load
330 button. The various widgets in the Submit window will get loaded with
331 values found in the script file. The script file text box will only be
332 loaded with executable lines (non-PBS) found in the script. The job
333 script header box has a Prefix entry box that can be modified to spec‐
334 ify the PBS directive to look for when parsing a script file for PBS
335 options. If you don't have a script file, you can start typing the
336 executable lines of the job in the file text box.
337 To submit a job, perform the following steps:
339 1. Select a host from the HOSTS listbox in the main xpbs dis‐
341 play.
342 2. Click on the Submit button located in the Menu bar.
344 3. Specify the script file containing the job execution lines
346 and job property values, or simply type in the execution
347 lines in the FILE textbox.
348 4. Start manipulating the various widgets in the Submit window.
350 Particularly, pay close attention to the Destination listbox.
351 This box lists all the queues found in the host that you
352 selected. A special entry called "@host" refers to the
353 default queue at host. Select appropriately the destination
354 queue of the job. More options can be found by clicking the
355 OTHER OPTIONS buttons.
356 5. At the bottom of the Submit window, click confirm submit.
358 You can also click on interactive to run the job interac‐
359 tively. Running a job interactively will open an xterm win‐
360 dow to your display host containing the session.
361 NOTE: The script FILE entry box is accompanied by a save but‐
363 ton that you click to save the current widget values to the
364 specified file in a form that can later be read by xpbs or by
365 the qsub command.
366
368 Modifying a PBS job requires only to manipulate the widgets found in
369 the Modify window. To modify a job or jobs, do the following steps:
370 1. Select one or more jobs from the JOBS listbox in the main
372 xpbs display.
373 2. Click on the modify button located to the right of the list‐
375 box.
376 3. The Modify window is structured similarly to the Submit win‐
378 dow. Simply manipulate the widgets to specify replacement or
379 additional values of job attributes.
380 4. Click on the confirm modify button located at the bottom of
382 the dialog box.
383
385 Deleting a PBS job requires only to manipulate the widgets found in the
386 Delete window. To delete a job or jobs, do the following steps:
387 1. Select one or more jobs from the JOBS listbox in the main
389 xpbs display.
390 2. Click on the delete button located to the right of the list‐
392 box.
393 3. Manipulate the spinbox widget to set the kill delay signal
395 interval.
396 4. Click on the delete button located at the bottom of the dia‐
398 log box.
399
401 If you want to be informed of returned output files of current jobs,
402 and be able to quickly see the contents of those files, then enable the
403 "track job" feature as follows:
404 1. Submit all the jobs that you want monitored.
406 2. Click on the Track Job button located in the Menu bar to
408 bring up the Track Job dialog box.
409 3. Specify the list of user names, whose jobs are to be mon‐
411 itored for returned output files, in the matrix located
412 at the upper left of the dialog box.
413 4. Manipulate the minutes spinbox, located just below the
415 user names matrix, to specify the interval value when
416 output files will be periodically checked.
417 5. Specify the location of job output files (whether locally
419 or remotely) by clicking on one of the radio buttons
420 located at the upper right of the dialog box. Returned
421 locally means the output files will be returned back to
422 the host where xpbs was run. If the output files are
423 returned to some remote host, then xpbs will execute an
424 RSH <remote_host> test -f <output_files>
425 to test the existence of the files. RSH is whatever you
426 set the remote shell command to in the corresponding
427 entry box.
428 NOTE: Be sure the files are accessible from the host
430 where xpbs was run (i.e. .rhosts appropriately set).
431 6. Click start/reset tracking button located at the bottom
433 of the dialog box to:
434 - cancel any previous tracking
436 - build a new list of jobs to be monitored for returned
438 output files based on currently queued jobs.
439 - start periodic tracking.
441 7. Click on close window button.
443 When an output file for a job being monitored is found, then the Track
445 Job button (the one that originally invoked the Track Job dialog box)
446 will turn into a different color, and the Jobs Found Completed listbox,
447 located in the Track Job dialog box, is then loaded with the corre‐
448 sponding job id(s). Then double click on a job id to see the contents
449 of the output file and the error file. Click stop tracking if you want
450 to cancel tracking.
451
453 Click on the Close button located in the Menu bar to leave xpbs. If
454 anything had changed, it will bring up a dialog box asking for a con‐
455 firmation in regards to saving state information like the view states
456 (minimize/maximize) of the HOSTS, QUEUES, JOBS, and INFO subwindows,
457 and various criteria for listing queues and jobs. The information is
458 saved in ~/.xpbsrc file.
459
461 The resources that can be set in the X resources file, ~/.xpbsrc, are:
462 *serverHosts
464 list of server hosts (space separated) to query by xpbs.
465 *timeoutSecs
467 specify the number of seconds before timing out waiting for a
468 connection to a PBS host.
469 *xtermCmd
471 the xterm command to run driving an interactive PBS session.
472 *labelFont
474 font applied to text appearing in labels.
475 *fixlabelFont
477 font applied to text that label fixed-width widgets such as
478 listbox labels. This must be a fixed-width font.
479 *textFont
481 font applied to a text widget. Keep this as fixed-width font.
482 *backgroundColor
484 the color applied to background of frames, buttons, entries,
485 scrollbar handles.
486 *foregroundColor
488 the color applied to text in any context (under selection,
489 insertion, etc...).
490 *activeColor
492 the color applied to the background of a selection, a selected
493 command button, or a selected scroll bar handle.
494 *disabledColor
496 color applied to a disabled widget.
497 *signalColor
499 color applied to buttons that signal something to the user about
500 a change of state. For example, the color of the Track Job but‐
501 ton when returned output files are detected.
502 *shadingColor
504 a color shading applied to some of the frames to emphasize focus
505 as well as decoration.
506 *selectorColor
508 the color applied to the selector box of a radiobutton or check‐
509 button.
510 *selectHosts
512 list of hosts (space separated) to automatically select/high‐
513 light in the HOSTS listbox.
514 *selectQueues
516 list of queues (space separated) to automatically select/high‐
517 light in the QUEUES listbox.
518 *selectJobs
520 list of jobs (space separated) to automatically select/highlight
521 in the JOBS listbox.
522 *selectOwners
524 list of owners checked when limiting the jobs appearing on the
525 Jobs listbox in the main xpbs window. Specify value as "Owners:
526 <list_of_owners>". See -u option in qselect(1B) for format of
527 <list_of_owners>.
528 *selectStates
530 list of job states to look for (do not space separate) when lim‐
531 iting the jobs appearing on the Jobs listbox in the main xpbs
532 window. Specify value as "Job_States: <states_string>". See -s
533 option in qselect(1B) for format of <states_string>.
534 *selectRes
536 list of resource amounts (space separated) to consult when lim‐
537 iting the jobs appearing on the Jobs listbox in the main xpbs
538 window. Specify value as "Resources: <res_string>". See -l
539 option in qselect(1B) for format of <res_string>.
540 *selectExecTime
542 the Execution Time attribute to consult when limiting the list
543 of jobs appearing on the Jobs listbox in the main xpbs window.
544 Specify value as "Queue_Time: <exec_time>". See -a option in
545 qselect(1B) for format of <exec_time>.
546 *selectAcctName
548 the name of the account that will be checked when limiting the
549 jobs appearing on the Jobs listbox in the main xpbs window.
550 Specify value as "Account_Name: <account_name>". See -A option
551 in qselect(1B) for format of <account_name>.
552 *selectCheckpoint
554 the checkpoint attribute relationship (including the logical
555 operator) to consult when limiting the list of jobs appearing on
556 the Jobs listbox in the main xpbs window. Specify value as
557 "Checkpoint: <checkpoint_arg>". See -c option in qselect(1B)
558 for format of <checkpoint_arg>.
559 *selectHold
561 the hold types string to look for in a job when limiting the
562 jobs appearing on the Jobs listbox in the main xpbs window.
563 Specify value as "Hold_Types: <hold_string>". See -h option in
564 qselect(1B) for format of <hold_string>.
565 *selectPriority
567 the priority relationship (including the logical operator) to
568 consult when limiting the list of jobs appearing on the Jobs
569 listbox in the main xpbs window. Specify value as "Priority:
570 <priority_value>". See -p option in qselect(1B) for format of
571 <priority_value>.
572 *selectRerun
574 the rerunnable attribute to consult when limiting the list of
575 jobs appearing on the Jobs listbox in the main xpbs window.
576 Specify value as "Rerunnable: <rerun_val>". See -r option in
577 qselect(1B) for format of <rerun_val>.
578 *selectJobName
580 name of the job that will be checked when limiting the jobs
581 appearing on the Jobs listbox in the main xpbs window. Specify
582 value as "Job_Name: <jobname>". See -N option in qselect(1B)
583 for format of <jobname>.
584 *iconizeHostsView
586 a boolean value (true or false) indicating whether or not to
587 iconize the HOSTS region.
588 *iconizeQueuesView
590 a boolean value (true or false) indicating whether or not to
591 iconize the QUEUES region.
592 *iconizeJobsView
594 a boolean value (true or false) indicating whether or not to
595 iconize the JOBS region.
596 *iconizeInfoView
598 a boolean value (true or false) indicating whether or not to
599 iconize the INFO region.
600 *jobResourceList
602 a curly-braced list of resource names as according to architec‐
603 ture known to xpbs. The format is as follows:
604 { <arch-type1> resname1 resname2 ... resnameN }
605 { <arch-type2> resname1 resname2 ... resnameN }
606 . . .
607 { <arch-typeN> resname1 resname2 ... resnameN }
608
610 xpbs calls PBS commands as follows:
611 Command Button PBS Command
613 detail (Hosts) qstat -B -f <selected server_host(s)>
615 terminate qterm <selected server_host(s)>
617 detail (Queues) qstat -Q -f <selected queue(s)>
619 stop qstop <selected queue(s)>
621 start qstart <selected queue(s)>
623 enable qenable <selected queue(s)>
625 disable qdisable <selected queue(s)>
627 detail (Jobs) qstat -f <selected job(s)>
629 modify qalter <selected job(s)>
631 delete qdel <selected job(s)>
633 hold qhold <selected job(s)>
635 release qrls <selected job(s)>
637 run qrun <selected job(s)>
639 rerun qrerun <selected job(s)>
641 signal qsig <selected job(s)>
643 msg qmsg <selected job(s)>
645 move qmove <selected job(s)>
647 order qorder <selected job(s)>
649
651 Upon successful processing, the xpbs exit status will be a value of
652 zero.
653 If the xpbs command fails, the command exits with a value greater than
655 zero.
656
658 qalter(1B), qdel(1B), qhold(1B), qmove(1B), qmsg(1B), qrerun(1B),
659 qrls(1B), qselect(1B), qsig(1B), qstat(1B), qorder(1B), qsub(1B), qdis‐
660 able(8B), qenable(8B), qrun(8B), qstart(8B), qstop(8B), qterm(8B).
661Local xpbs(1B)