← Back to branch summary

~ubuntu-branches/ubuntu/utopic/gridengine/utopic

« back to all changes in this revision

Viewing changes to doc/devel/adoc.html

  • Committer: Bazaar Package Importer
  • Author(s): Mark Hymers
  • Date: 2008-06-25 22:36:13 UTC
  • Revision ID: james.westby@ubuntu.com-20080625223613-tvd9xlhuoct9kyhm
Tags: upstream-6.2~beta2
Import upstream version 6.2~beta2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/devel/adoc.html
 
1
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
 
2
<html>
 
3
<head>
 
4
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
 
5
   <meta name="Author" content="Joachim Gabler">
 
6
   <meta name="GENERATOR" content="Mozilla/4.76C-CCK-MCD  [en] (X11; U; SunOS 5.8 sun4u) [Netscape]">
 
7
</head>
 
8
<body>
 
9
 
 
10
<h1>
 
11
Source code documentation using adoc</h1>
 
12
An essential characteristic of high quality source code is a comprehensive
 
13
documentation.
 
14
<p>For the Grid Engine development, we started some time ago to use so
 
15
called Autodoc Headers that are interpreted by the adoc utility.
 
16
<p>Adoc was originally written by Tobias Ferber and published unter the
 
17
GPL.
 
18
<br>It can create ASCII and Texinfo output, Texinfo can be&nbsp; used to
 
19
publish the documentation in a lot of different output formats including
 
20
HTML, PDF, GNU Info, DVI etc.
 
21
<p>It's functionality is a little bit rudimentory and can not really compete
 
22
with tools like doxygen or the javadoc tool, but it has the advantage,
 
23
that it can be used to parse not only C or Java source code, but also any
 
24
scripting languages like tcl, shell etc.&nbsp; using the same syntax.
 
25
<p>The source code of adoc can be found in the directory <tt>source/3rdparty/adoc</tt>.
 
26
<br>We modified it to support 3 levels of chapters/sections instead of
 
27
only 2.
 
28
<br>&nbsp;
 
29
<h2>
 
30
Generating the documentation</h2>
 
31
The documentation can be generated automatically using the aimk script
 
32
(<tt>source/aimk</tt>).
 
33
<br>Calling <tt>aimk -adoc</tt> will
 
34
<ul>
 
35
<li>
 
36
compile the adoc tool</li>
 
37
 
 
38
<li>
 
39
generate 3 texinfo files:</li>
 
40
 
 
41
<ul>
 
42
<li>
 
43
documentation of the library functions (<tt>libs.texi</tt>)</li>
 
44
 
 
45
<li>
 
46
documentation of the core system (<tt>core.texi</tt>)</li>
 
47
 
 
48
<li>
 
49
documentation of the testsuite (<tt>testsuite.texi</tt>)</li>
 
50
</ul>
 
51
</ul>
 
52
The texinfo files can be used to generate a readable documentation in different
 
53
output formats.
 
54
<p>Examples:
 
55
<ul>
 
56
<li>
 
57
Generate HTML-Documentation:</li>
 
58
 
 
59
<br><tt>texi2html libs.texi</tt>
 
60
<br>Writes a file <tt>libs.html</tt> containing the documentation and a
 
61
file <tt>libs_toc.html</tt> containing a table of contents with links to
 
62
<tt>libs.html</tt>
 
63
<li>
 
64
Generate Documentation in PDF Format:</li>
 
65
 
 
66
<br><tt>texi2pdf libs.texi</tt>
 
67
<br>Creates a file <tt>libs.pdf</tt></ul>
 
68
 
 
69
<h2>
 
70
Writing documentation</h2>
 
71
Each function of C, TCL or shell code should have an autodoc header, especially
 
72
these in function libraries.
 
73
<br>The header can be inserted from a template (see<tt><font color="#000000">doc/devel/c-header</font></tt>for
 
74
C-Syntax, <tt><font color="#000000">doc/devel/sh-header</font></tt>for
 
75
TCL and shell syntax) or by using a tcl script defined as editor macro.
 
76
<h3>
 
77
Macro for automated insertion of autodoc headers</h3>
 
78
The&nbsp; distribution contains a small tcl script that may be used to
 
79
automatically insert an autodoc header into a source file (see <tt>doc/testsuite/adoc/doc_tool.tcl</tt>).
 
80
<br>It creates an autodoc header and automatically enters data for the
 
81
category and function name, and the autodoc sections <tt>NAME</tt>, <tt>SYNOPSIS</tt>,
 
82
<tt>INPUTS</tt>
 
83
and <tt>RESULT</tt>.
 
84
<p>It can be called as macro from the editor, if the editor has some means
 
85
to include macros and the call of external programs.
 
86
<p>The doc_tool.tcl has a variety of options to parse and modify source
 
87
code for source code documentation purposes.
 
88
<h4>
 
89
Insertion of autodoc headers in the vim editor</h4>
 
90
To install such a macro in the vim editor, edit the .vimrc file in your
 
91
homedirectory and add the following line:
 
92
<p><tt>map ^P :-r !doc_tool mode C output stdout no_warnings func &lt;cword>
 
93
%:p^M</tt>
 
94
<p>To enter the ^P and ^M, in vi press CTRL-V CTRL-p / CTRL-V CTRL-m.
 
95
<p>If you place the cursor on a C function prototype&nbsp; and press F11,
 
96
a new partly filled out autodoc header for the function will be inserted
 
97
into the source file.
 
98
<p>Newer vim versions (beginning with 6.0?) seem to use another syntax
 
99
in the .vimrc file. Add the following line to your .vimrc file (install
 
100
macro on F9, F11 as in the previous example didn't work for some reason:
 
101
<p><tt>map &lt;unique> &lt;F9> :-r !doc_tool mode C output stdout no_warnings
 
102
func &lt;cword> %:p^M</tt>
 
103
<h3>
 
104
Choosing a function identifier</h3>
 
105
The current structure of the source code documentation provides 3 individual
 
106
files - documentation of libraries, the core system binaries and the testsuite.
 
107
<br>Within each document, we have 3 hiearchical levels of sections - in
 
108
texinfo: chapter, section and subsection.
 
109
<p>The current documentation is structured not to reflext strictly the
 
110
directory structure of the code in the section hierarchy, but the structure
 
111
reflects categories of code within a certain directory based structure.
 
112
<p>Each source file contains functions belonging to exactly one function
 
113
category.
 
114
<p>Example:
 
115
<br>The module qsh has the function category <tt>Interactive/qsh</tt>:
 
116
It is a tool to create an interactive job in Grid Engine, its name is qsh.
 
117
<p>Possible function identifiers then are
 
118
<br><tt>Interactive/qsh/--Interactive</tt>
 
119
<br><tt>Interactive/qsh/add2env()</tt>
 
120
<br><tt>...</tt>
 
121
<p>To enable the doc_tool.tcl to insert adoc headers with the correct function
 
122
categoriy filled in automatically, there exists a file doc/devel/doc_tool.cat
 
123
that maps directories and optionally filenames to function categories.
 
124
One line contains one mapping.
 
125
<p>Example:
 
126
<br><tt>source/clients/qsh Interactive/qsh</tt>
 
127
<br><tt>source/clients/qrsh Interactive/qrsh</tt>
 
128
<br><tt>source/daemons/execd execd</tt>
 
129
<br><tt>source/daemons/execd/load_avg.* execd/load</tt>
 
130
<br><tt>source/daemons/execd/sge_load_sensor.* execd/load</tt>
 
131
<br><tt>...</tt>
 
132
<br>&nbsp;
 
133
<h4>
 
134
Function categories for the library documentation</h4>
 
135
 
 
136
<ul>
 
137
<li>
 
138
Eventclient</li>
 
139
 
 
140
<ul>
 
141
<li>
 
142
Client</li>
 
143
</ul>
 
144
 
 
145
<li>
 
146
commd</li>
 
147
 
 
148
<ul>
 
149
<li>
 
150
commlib</li>
 
151
</ul>
 
152
 
 
153
<li>
 
154
cull</li>
 
155
 
 
156
<ul>
 
157
<li>
 
158
hash - cull specific hash table extensions, based on uti/hash</li>
 
159
 
 
160
<li>
 
161
list</li>
 
162
 
 
163
<li>
 
164
multitype</li>
 
165
</ul>
 
166
 
 
167
<li>
 
168
gdi</li>
 
169
 
 
170
<ul>
 
171
<li>
 
172
feature</li>
 
173
 
 
174
<li>
 
175
job_jatask</li>
 
176
 
 
177
<li>
 
178
queue</li>
 
179
 
 
180
<li>
 
181
range</li>
 
182
 
 
183
<li>
 
184
request</li>
 
185
 
 
186
<li>
 
187
security</li>
 
188
 
 
189
<li>
 
190
setup</li>
 
191
 
 
192
<li>
 
193
sge</li>
 
194
 
 
195
<li>
 
196
suser</li>
 
197
 
 
198
<li>
 
199
usermap</li>
 
200
</ul>
 
201
 
 
202
<li>
 
203
rmon</li>
 
204
 
 
205
<li>
 
206
sched</li>
 
207
 
 
208
<li>
 
209
uti</li>
 
210
 
 
211
<ul>
 
212
<li>
 
213
afsutil</li>
 
214
 
 
215
<li>
 
216
bitop</li>
 
217
 
 
218
<li>
 
219
dstring</li>
 
220
 
 
221
<li>
 
222
hostname</li>
 
223
 
 
224
<li>
 
225
htable - generic hash table implementation</li>
 
226
 
 
227
<li>
 
228
io</li>
 
229
 
 
230
<li>
 
231
language</li>
 
232
 
 
233
<li>
 
234
log</li>
 
235
 
 
236
<li>
 
237
os</li>
 
238
 
 
239
<li>
 
240
prog</li>
 
241
 
 
242
<li>
 
243
signal</li>
 
244
 
 
245
<li>
 
246
spool</li>
 
247
 
 
248
<li>
 
249
stdio</li>
 
250
 
 
251
<li>
 
252
stdlib</li>
 
253
 
 
254
<li>
 
255
string- string parsing functions</li>
 
256
 
 
257
<li>
 
258
time</li>
 
259
 
 
260
<li>
 
261
uidgid</li>
 
262
 
 
263
<li>
 
264
unistd</li>
 
265
</ul>
 
266
</ul>
 
267
 
 
268
<h4>
 
269
Function categories for the core system documentation</h4>
 
270
 
 
271
<ul>
 
272
<li>
 
273
commd</li>
 
274
 
 
275
<li>
 
276
common</li>
 
277
 
 
278
<ul>
 
279
<li>
 
280
General</li>
 
281
 
 
282
<li>
 
283
Clients</li>
 
284
 
 
285
<li>
 
286
Daemons</li>
 
287
</ul>
 
288
 
 
289
<li>
 
290
execd</li>
 
291
 
 
292
<li>
 
293
qacct</li>
 
294
 
 
295
<li>
 
296
qalter</li>
 
297
 
 
298
<li>
 
299
qconf</li>
 
300
 
 
301
<li>
 
302
qdel</li>
 
303
 
 
304
<li>
 
305
qhost</li>
 
306
 
 
307
<li>
 
308
qmaster</li>
 
309
 
 
310
<li>
 
311
qmod</li>
 
312
 
 
313
<li>
 
314
qmod</li>
 
315
 
 
316
<li>
 
317
qstat</li>
 
318
 
 
319
<li>
 
320
qsub</li>
 
321
 
 
322
<li>
 
323
schedd</li>
 
324
 
 
325
<li>
 
326
schadowd</li>
 
327
 
 
328
<li>
 
329
shepherd</li>
 
330
 
 
331
<li>
 
332
Interactive</li>
 
333
 
 
334
<ul>
 
335
<li>
 
336
qsh</li>
 
337
</ul>
 
338
 
 
339
<ul>
 
340
<li>
 
341
qlogin</li>
 
342
 
 
343
<li>
 
344
qmake</li>
 
345
 
 
346
<li>
 
347
qrsh</li>
 
348
 
 
349
<li>
 
350
qtcsh</li>
 
351
</ul>
 
352
 
 
353
<li>
 
354
Eventclient</li>
 
355
 
 
356
<ul>
 
357
<li>
 
358
Server</li>
 
359
</ul>
 
360
</ul>
 
361
 
 
362
<h4>
 
363
Function categories for the testsuite documentation</h4>
 
364
 
 
365
<ul>
 
366
<li>
 
367
checks</li>
 
368
 
 
369
<ul>
 
370
<li>
 
371
install</li>
 
372
 
 
373
<li>
 
374
loadcheck</li>
 
375
 
 
376
<li>
 
377
migration</li>
 
378
 
 
379
<li>
 
380
performance</li>
 
381
 
 
382
<li>
 
383
performance_cluster</li>
 
384
 
 
385
<li>
 
386
performance_scheduler</li>
 
387
 
 
388
<li>
 
389
qalter</li>
 
390
 
 
391
<li>
 
392
qconf</li>
 
393
 
 
394
<li>
 
395
qdel</li>
 
396
 
 
397
<li>
 
398
qmaster_size</li>
 
399
 
 
400
<li>
 
401
qmod</li>
 
402
 
 
403
<li>
 
404
qrsh</li>
 
405
 
 
406
<li>
 
407
qstat</li>
 
408
 
 
409
<li>
 
410
qsub</li>
 
411
 
 
412
<li>
 
413
shadowd_migrate</li>
 
414
</ul>
 
415
 
 
416
<li>
 
417
library</li>
 
418
 
 
419
<ul>
 
420
<li>
 
421
control</li>
 
422
 
 
423
<li>
 
424
file</li>
 
425
 
 
426
<li>
 
427
parser</li>
 
428
 
 
429
<li>
 
430
remote</li>
 
431
 
 
432
<li>
 
433
sge</li>
 
434
</ul>
 
435
 
 
436
<li>
 
437
scripts</li>
 
438
</ul>
 
439
 
 
440
<h3>
 
441
Filling out the autodoc header</h3>
 
442
The following sections of an autodoc header should always be filled out:
 
443
<ul>
 
444
<li>
 
445
<b><tt>NAME</tt></b></li>
 
446
 
 
447
<br>The function name and a short (one line) description
 
448
<li>
 
449
<b><tt>SYNOPSIS</tt></b></li>
 
450
 
 
451
<br>The function prototype, optionally preceeded by an include statement,
 
452
if needed and compiler/linker options, see&nbsp; <a href="#Examples for adoc headers">Examples
 
453
for adoc headers</a>
 
454
<li>
 
455
<b><tt>FUNCTION</tt></b></li>
 
456
 
 
457
<br>A complete function description.
 
458
<li>
 
459
<b><tt>INPUTS</tt></b></li>
 
460
 
 
461
<br>Description of all input parameters
 
462
<li>
 
463
<b><tt>RESULT</tt></b></li>
 
464
 
 
465
<br>Description of the result</ul>
 
466
 
 
467
<p><br>These sections are optional :
 
468
<ul>
 
469
<li>
 
470
<b><tt>EXAMPLE</tt></b></li>
 
471
 
 
472
<br>How to use the function
 
473
<li>
 
474
<b><tt>NOTES</tt></b></li>
 
475
 
 
476
<br>Notes for further development, hints for the usage etc.
 
477
<li>
 
478
<b><tt>BUGS</tt></b></li>
 
479
 
 
480
<br>adoc provides a BUGS section to document known bugs - please do not
 
481
create BUGS sections - use IssueZilla instead.
 
482
<li>
 
483
<b><tt>SEE ALSO</tt></b></li>
 
484
 
 
485
<br>References to other functions, man pages etc.</ul>
 
486
 
 
487
<br>&nbsp;
 
488
<h3>
 
489
Introduction pages for Categories</h3>
 
490
A category usually reflects some hierarchy in the source code tree, often
 
491
an individual binary, and deserves to have an introductory autodoc header
 
492
before the detailed function descriptions.
 
493
<p>Therefor an autodoc header should be written for each category that
 
494
gives a short overview of the category and may refer to other autodoc headers
 
495
giving more details.
 
496
<p>The header of such an introductory page has the form
 
497
<br><tt>/****** chapter/section/--topic *****************</tt>
 
498
<p>The hyphens (-) before the topic influence autodoc's sorting algorithm:
 
499
The introductory page will always be the the first page of a section.
 
500
<br>&nbsp;
 
501
<br>&nbsp;
 
502
<h3>
 
503
Documentation of defines, global variables etc.</h3>
 
504
It is desirable to have documentation also for constants/defines, global
 
505
variables, structures, typedefs etc.
 
506
<p>The following special function identifiers are used for this type of
 
507
documentation:
 
508
<br>-topic-Defines
 
509
<br>-topic-Global_Variables
 
510
<br>-topic-Templates
 
511
<br>-topic-Typedefs
 
512
<br>-topic-Misc
 
513
<p>Again, the hyphen before the identifiers name influence adoc's sorting
 
514
algorithm.
 
515
<br>&nbsp;
 
516
<h2>
 
517
<a NAME="Examples for adoc headers"></a>Examples for adoc headers</h2>
 
518
 
 
519
<h3>
 
520
An introduction header</h3>
 
521
<tt>/****** Interactive/qmake/--qmake ***************************************</tt>
 
522
<br><tt>*</tt>
 
523
<br><tt>*&nbsp; NAME</tt>
 
524
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; qmake -- Scheduled parallel distributed
 
525
make</tt>
 
526
<br><tt>*</tt>
 
527
<br><tt>*&nbsp; SYNOPSIS</tt>
 
528
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; qmake &lt;sge options> -- &lt;gmake options></tt>
 
529
<br><tt>*</tt>
 
530
<br><tt>*&nbsp; FUNCTION</tt>
 
531
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Scheduled, parallel, distributed make.</tt>
 
532
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; qmake is implemented based on GNU make
 
533
3.78.1 using the remote stub</tt>
 
534
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; mechanism of gmake.</tt>
 
535
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; qmake will start a parallel job and run
 
536
make tasks as task in the</tt>
 
537
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; parallel job using the Grid Engine qrsh
 
538
-inherit command.</tt>
 
539
<br><tt>*</tt>
 
540
<br><tt>*&nbsp; INPUTS</tt>
 
541
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; sge options - all options that can be
 
542
specified with qsub command</tt>
 
543
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gmake options&nbsp; - all possible gmake
 
544
options</tt>
 
545
<br><tt>*</tt>
 
546
<br><tt>*&nbsp; RESULT</tt>
 
547
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; returncode from gmake or EXIT_FAILURE,
 
548
if remote mechanism fails.</tt>
 
549
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; On error, an appropriate error description
 
550
is written to stderr.</tt>
 
551
<br><tt>*</tt>
 
552
<br><tt>*&nbsp; EXAMPLE</tt>
 
553
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; qmake -cwd -v PATH -- -j 5</tt>
 
554
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Build sge system: aimk -qmake -parallel
 
555
10</tt>
 
556
<br><tt>*</tt>
 
557
<br><tt>*&nbsp; NOTES</tt>
 
558
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; not yet internationalized</tt>
 
559
<br><tt>*</tt>
 
560
<br><tt>****************************************************************************</tt>
 
561
<br><tt>*/</tt>
 
562
<br>&nbsp;
 
563
<h3>
 
564
A header describing defines</h3>
 
565
<tt>/****** Interactive/qmake/-qmake-Defines ***************************************</tt>
 
566
<br><tt>*</tt>
 
567
<br><tt>*&nbsp; NAME</tt>
 
568
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Defines -- constant and macro definitions</tt>
 
569
<br><tt>*</tt>
 
570
<br><tt>*&nbsp; SYNOPSIS</tt>
 
571
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; #define LOCK_SLEEP_TIME 500</tt>
 
572
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; #define WAIT_SLOT_TIME&nbsp;&nbsp;&nbsp;
 
573
5</tt>
 
574
<br><tt>*</tt>
 
575
<br><tt>*&nbsp; FUNCTION</tt>
 
576
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; LOCK_SLEEP_TIME - Defines how long qmake
 
577
should (u)sleep</tt>
 
578
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
579
after an unsuccessful try to get a lock to the</tt>
 
580
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
581
hostfile</tt>
 
582
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; WAIT_SLOT_TIME&nbsp; - Time to wait,
 
583
if no slot is free in hostfile</tt>
 
584
<br><tt>*</tt>
 
585
<br><tt>****************************************************************************</tt>
 
586
<br><tt>*/</tt>
 
587
<br>&nbsp;
 
588
<h3>
 
589
A function description</h3>
 
590
<tt>/****** Interactive/qmake/remote_exit() ***************************************</tt>
 
591
<br><tt>*</tt>
 
592
<br><tt>*&nbsp; NAME</tt>
 
593
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; remote_exit() -- exit qmake</tt>
 
594
<br><tt>*</tt>
 
595
<br><tt>*&nbsp; SYNOPSIS</tt>
 
596
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; static void remote_exit(int code, const
 
597
char *message,</tt>
 
598
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
599
const char *reason);</tt>
 
600
<br><tt>*</tt>
 
601
<br><tt>*&nbsp; FUNCTION</tt>
 
602
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Outputs the error messages passed as
 
603
parameters to stderr</tt>
 
604
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; and then exits with the error code passed
 
605
as parameter.</tt>
 
606
<br><tt>*</tt>
 
607
<br><tt>*&nbsp; INPUTS</tt>
 
608
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; code&nbsp;&nbsp;&nbsp; - exit code</tt>
 
609
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; message - message to output before exit,
 
610
should describe the</tt>
 
611
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
612
situation when error occurs</tt>
 
613
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; reason&nbsp; - description of the error
 
614
reason, e.g. result from</tt>
 
615
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
616
system call strerror(errno)</tt>
 
617
<br><tt>*</tt>
 
618
<br><tt>*&nbsp; RESULT</tt>
 
619
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; program exits</tt>
 
620
<br><tt>*</tt>
 
621
<br><tt>*&nbsp; EXAMPLE</tt>
 
622
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; #include &lt;stdlib.h></tt>
 
623
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; #include &lt;string.h></tt>
 
624
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; #include &lt;errno.h></tt>
 
625
<br><tt>*</tt>
 
626
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; ...</tt>
 
627
<br><tt>*</tt>
 
628
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; if(write(filehandle, buffer, size) !=
 
629
size) {</tt>
 
630
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; remote_exit(EXIT_FAILURE,
 
631
"writing to file failed", strerror(errno));</tt>
 
632
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; }*</tt>
 
633
<br><tt>****************************************************************************</tt>
 
634
<br><tt>*/</tt>
 
635
<br>&nbsp;
 
636
<h3>
 
637
Description of a Cull object/class</h3>
 
638
<tt>/****** gdi/range/--RN_Type ***************************************************</tt>
 
639
<br><tt>*&nbsp; NAME</tt>
 
640
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; RN_Type - CULL range element</tt>
 
641
<br><tt>*</tt>
 
642
<br><tt>*&nbsp; ELEMENTS</tt>
 
643
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; SGE_ULONG(RN_min)</tt>
 
644
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; minimum or start value
 
645
of an id range (e.g. 1)</tt>
 
646
<br><tt>*</tt>
 
647
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; SGE_ULONG(RN_max)</tt>
 
648
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; maximum or end value
 
649
of an id range (e.g. 9)</tt>
 
650
<br><tt>*</tt>
 
651
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; SGE_ULONG(RN_step)</tt>
 
652
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; stepsize (e.g. 2)</tt>
 
653
<br><tt>*</tt>
 
654
<br><tt>*&nbsp; FUNCTION</tt>
 
655
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; CULL element holding values which define
 
656
a id range</tt>
 
657
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; (e.g. 1-9:2 => 1, 3, 5, 7, 9).</tt>
 
658
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Lists of this CULL element are hold within
 
659
a CULL job element</tt>
 
660
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; (JB_Type) to hold job array task ids.</tt>
 
661
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Several functions may be used to access/modify/delete
 
662
range</tt>
 
663
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; elements and range lists. You may find
 
664
them in the 'SEE ALSO'</tt>
 
665
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; section. It is highly advised to use
 
666
these access functions</tt>
 
667
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; because they assure and require a defined
 
668
structure of</tt>
 
669
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; elements and lists.</tt>
 
670
<br><tt>*</tt>
 
671
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; Range elements and lists stored in other
 
672
CULL elements fullfill</tt>
 
673
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; following conditions:</tt>
 
674
<br><tt>*</tt>
 
675
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - min &lt;= max</tt>
 
676
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - step >= 1</tt>
 
677
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - real range elements
 
678
(e.g. 1-9:2 instead of 1-10:2)</tt>
 
679
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - min-ids within range
 
680
elements part of the same</tt>
 
681
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; list are
 
682
in ascending order: min_id(n) &lt; min_id(n+1)</tt>
 
683
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (e.g. NOT
 
684
11-20:1; 1-9:2)</tt>
 
685
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; - ids within range
 
686
elements part of the same</tt>
 
687
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; list are
 
688
non-overlapping: max_id(n) &lt; min_id(n+1)</tt>
 
689
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; (e.g. 1-9:2;
 
690
11-20:1; 25-28:3)</tt>
 
691
<br><tt>*</tt>
 
692
<br><tt>*&nbsp; SEE ALSO</tt>
 
693
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/RN_Type</tt>
 
694
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_calculate_union_set()</tt>
 
695
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_calculate_difference_set()</tt>
 
696
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_calculate_intersection_set()</tt>
 
697
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_compress()</tt>
 
698
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_get_first_id()</tt>
 
699
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_get_last_id()</tt>
 
700
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_get_number_of_ids()</tt>
 
701
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_initialize()</tt>
 
702
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_insert_id()</tt>
 
703
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_is_id_within()</tt>
 
704
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_move_first_n_ids()</tt>
 
705
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_print_to_string()</tt>
 
706
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_list_remove_id()</tt>
 
707
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_correct_end()</tt>
 
708
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_get_all_ids()</tt>
 
709
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_get_number_of_ids()</tt>
 
710
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_is_overlapping()</tt>
 
711
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_is_id_within()</tt>
 
712
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_set_all_ids()</tt>
 
713
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/range/range_sort_uniq_compress()</tt>
 
714
<br><tt>*&nbsp;&nbsp;&nbsp;&nbsp; gdi/job/JB_Type</tt>
 
715
<br><tt>******************************************************************************/</tt>
 
716
<h3>
 
717
Documentation of a TCL function</h3>
 
718
#<tt>****** library/control/ps_grep() ******</tt>
 
719
<br><tt>#</tt>
 
720
<br><tt>#&nbsp; NAME</tt>
 
721
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; ps_grep -- call get_ps_info and return
 
722
only expected ps information</tt>
 
723
<br><tt>#</tt>
 
724
<br><tt>#&nbsp; SYNOPSIS</tt>
 
725
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; ps_grep { forwhat { host "local" } {
 
726
variable ps_info } }</tt>
 
727
<br><tt>#</tt>
 
728
<br><tt>#&nbsp; FUNCTION</tt>
 
729
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; This procedure will call the get_ps_info
 
730
procedure. It will parse the</tt>
 
731
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; get_ps_info result for the given strings
 
732
and return only those process</tt>
 
733
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; ids which match.</tt>
 
734
<br><tt>#</tt>
 
735
<br><tt>#&nbsp; INPUTS</tt>
 
736
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; forwhat&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 
737
- search string (e.g. binary name)</tt>
 
738
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; { host "local" }&nbsp;&nbsp;&nbsp;&nbsp;
 
739
- host on which the ps command should be called</tt>
 
740
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; { variable ps_info } - variable name
 
741
to store the result (default ps_info)</tt>
 
742
<br><tt>#</tt>
 
743
<br><tt>#&nbsp; RESULT</tt>
 
744
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; returns a list of indexes where the search
 
745
string matches the ps output.</tt>
 
746
<br><tt>#</tt>
 
747
<br><tt>#&nbsp; EXAMPLE</tt>
 
748
<br><tt>#</tt>
 
749
<br><tt>#&nbsp;&nbsp; set myprocs [ ps_grep "execd" "fangorn" ]</tt>
 
750
<br><tt>#</tt>
 
751
<br><tt>#&nbsp;&nbsp; puts "execd's on fangorn index list: $myprocs"</tt>
 
752
<br><tt>#</tt>
 
753
<br><tt>#&nbsp;&nbsp; foreach elem $myprocs {</tt>
 
754
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; puts $ps_info(string,$elem)</tt>
 
755
<br><tt>#&nbsp;&nbsp; }</tt>
 
756
<br><tt>#</tt>
 
757
<br><tt>#&nbsp;&nbsp; output of example:</tt>
 
758
<br><tt>#</tt>
 
759
<br><tt>#&nbsp;&nbsp; execd's on fangorn index list: 34 39 50 59 61</tt>
 
760
<br><tt>#&nbsp;&nbsp; 2530&nbsp;&nbsp; 140&nbsp;&nbsp;&nbsp;&nbsp; 1&nbsp;&nbsp;
 
761
259 S Sep12&nbsp; 1916 00:00:14 /sge_s/glinux/sge_execd</tt>
 
762
<br><tt>#&nbsp;&nbsp; 7700&nbsp;&nbsp; 142&nbsp;&nbsp;&nbsp;&nbsp; 1&nbsp;&nbsp;
 
763
339 S Sep13&nbsp; 2024 00:03:49 /vol2/bin/glinux/sge_execd</tt>
 
764
<br><tt>#&nbsp;&nbsp; 19159&nbsp;&nbsp;&nbsp;&nbsp; 0&nbsp;&nbsp;&nbsp;&nbsp;
 
765
1&nbsp;&nbsp;&nbsp;&nbsp; 0 S Sep14&nbsp; 1772 00:31:09 /vol/bin/glinux/sgeee_execd</tt>
 
766
<br><tt>#&nbsp;&nbsp; 24148&nbsp;&nbsp;&nbsp;&nbsp; 0&nbsp;&nbsp;&nbsp;&nbsp;
 
767
1&nbsp;&nbsp;&nbsp;&nbsp; 0 S Sep14&nbsp; 2088 00:06:23 bin/glinux/sge_execd</tt>
 
768
<br><tt>#&nbsp;&nbsp; 15085&nbsp;&nbsp;&nbsp;&nbsp; 0&nbsp;&nbsp;&nbsp;&nbsp;
 
769
1&nbsp;&nbsp;&nbsp;&nbsp; 0 S Sep14&nbsp; 1904 00:27:04 /vol2/glinux/sgeee_execd</tt>
 
770
<br><tt>#</tt>
 
771
<br><tt>#&nbsp; NOTES</tt>
 
772
<br><tt>#&nbsp;&nbsp; look at get_ps_info procedure for more information!</tt>
 
773
<br><tt>#</tt>
 
774
<br><tt>#&nbsp; SEE ALSO</tt>
 
775
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; library/control/get_ps_info()</tt>
 
776
<br><tt>#*******************************</tt>
 
777
<h3>
 
778
Documentation of a shell script</h3>
 
779
<tt>#****** utilities/preemption/high_prolog.sh ***************************************</tt>
 
780
<br><tt>#</tt>
 
781
<br><tt>#&nbsp; NAME</tt>
 
782
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; high_prolog.sh -- prolog for high priority
 
783
queues</tt>
 
784
<br><tt>#</tt>
 
785
<br><tt>#&nbsp; SYNOPSIS</tt>
 
786
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; high_prolog.sh</tt>
 
787
<br><tt>#</tt>
 
788
<br><tt>#&nbsp; FUNCTION</tt>
 
789
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; If the number of slots occupied in queues
 
790
belonging to the preemption</tt>
 
791
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; mechanism exceeds the number of slots
 
792
reserved, an appropriate number</tt>
 
793
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; of low priority jobs/tasks are suspended.</tt>
 
794
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; The jobid's of the jobs suspended are
 
795
written to a job context variable</tt>
 
796
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; "suspended" separated by a colon (:).</tt>
 
797
<br><tt>#</tt>
 
798
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; If the number of slots occupied is equal
 
799
or exceeds the number of</tt>
 
800
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; reserved slots, the low priority queues
 
801
are disabled.</tt>
 
802
<br><tt>#</tt>
 
803
<br><tt>#&nbsp; SEE ALSO</tt>
 
804
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; utilities/preemption/--Preemption</tt>
 
805
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; utilities/preemption/high_epilog.sh</tt>
 
806
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; utilities/preemption/low_prolog.sh</tt>
 
807
<br><tt>#&nbsp;&nbsp;&nbsp;&nbsp; utilities/preemption/low_epilog.sh</tt>
 
808
<br><tt>#</tt>
 
809
<br><tt>#***************************************************************************</tt>
 
810
<br>&nbsp;
 
811
</body>
 
812
</html>