1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
|
<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
jsv_is_param, jsv_get_param, jsv_add_param, jsv_mod_param,
jsv_del_param, jsv_sub_is_param, jsv_sub_get_param,
jsv_sub_add_param, jsv_sub_del_param, jsv_is_env,
jsv_get_env, jsv_add_env, jsv_mod_env, jsv_del_env,
jsv_accept, jsv_correct, jsv_reject, jsv_reject_wait,
jsv_show_params, jsv_show_envs, jsv_log_info,
jsv_log_warning, jsv_log_error, jsv_main - Sun Grid Engine
Job Submission Verifier Scripting Interface
SYNOPSIS
jsv_clear_params();
jsv_is_param(<I>param</I>_<I>name</I>);
jsv_get_param(<I>param</I>_<I>name</I>);
jsv_set_param(<I>param</I>_<I>name</I>, <I>param</I>_<I>value</I>);
jsv_del_param(<I>param</I>_<I>name</I>);
jsv_sub_is_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);
jsv_sub_get_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);
jsv_sub_add_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
jsv_sub_del_param(<I>param</I>_<I>name</I>, <I>variable</I>_<I>name</I>);
jsv_clear_envs();
jsv_is_env(<I>variable</I>_<I>name</I>);
jsv_get_env(<I>variable</I>_<I>name</I>);
jsv_add_env(<I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
jsv_mod_env(<I>variable</I>_<I>name</I>, <I>variable</I>_<I>value</I>);
jsv_del_env(<I>variable</I>_<I>name</I>);
jsv_accept(<I>message</I>);
jsv_correct(<I>message</I>);
jsv_reject(<I>message</I>);
jsv_reject_wait(<I>message</I>);
jsv_show_params();
jsv_show_envs();
jsv_log_info(<I>message</I>);
jsv_log_warning(<I>message</I>);
jsv_log_error(<I>message</I>);
jsv_main();
jsv_send_env();
jsv_on_start();
jsv_on_verify();
DESCRIPTION
The functions documented here implement the server side of
the JSV protocol as it is described in the man page <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>.
These script functions are available in Bourne shell, TCL or
Perl scripts after sourcing/including the files
jsv_inlcude.sh, jsv_include.tcl or JSV.pm. The files and
corresponding JSV script templates are located in the direc-
tory $SGE_ROOT/util/resources/jsv.
jsv_clear_params()
This function clears all received job parameters that were
stored during the last job verification process.
jsv_clear_envs()
This function clears all received job environment variables
that were stored during the last job verification process.
jsv_show_params()
A call of this function reports all known job parameters to
the counterpart of this script (client or master daemon
thread). This parameters will be reported as info messages
and appear either in the stdout stream of the client or in
the message file of the master process.
jsv_show_envs()
A call of this function reports all known job environment
variables to the counterpart of this script (client or mas-
ter daemon thread). They will be reported as info messages
and appear in the stdout stream of the client or in the mes-
sage file of the master process.
jsv_is_param()
This function returns whether or not a specific job parame-
ters is available for the job which is currently being veri-
fied. Either the string <I>true</I> or <I>false</I> will be returned. The
availability/absence of a job parameter does not mean that
the corresponding command line switch was used/not used.
The following values are allowed for <I>param</I>_<I>name</I>. Correspond-
ing <I>qsub</I>/<I>qrsh</I>/<I>qsh</I>/... switches next to the parameter name
are mentioned only if they are different from the command
line switches.
Find additional information in <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B> man page describing
the availability and value format. Job parameters written in
capital letters are pseudo parameters. A detailed descrip-
tion for them can be found in <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>
param_name command line switch/description
a
ac combination of -ac, -sc, -dc
ar
A
b
c
ckpt
cwd
display
dl
e
h
hold_jid
hold_jid_ad
i
l_hard -l or -hard followed by -l
l_soft -soft followed by -l
j
js
m
M
masterq
N
notify
now
N
o
ot
P
pe
q_hard -q or -hard followed by -q
q_soft -soft followed by -q
R
r
shell
S
t
w
wd
CLIENT
CONTEXT
GROUP
VERSION
JOB_ID
SCRIPT
CMDARGS
CMDARG<i> where <i> is a nonnegative number
USER
The function returns the string <I>true</I> if the parameter
(<I>param</I>_<I>name</I>) exists in the job currently being verified. If
it does not exist <I>false</I> will be returned.
jsv_get_param()
This function returns the value of a specific job parameter
(<I>param</I>_<I>name</I>).
This value is only available if the function jsv_is_param()
returns <I>true</I>. Otherwise an empty string is returned.
Find a list of allowed parameter names in the section for
the function jsv_is_param().
jsv_set_param()
This function changes the job parameter (<I>param</I>_<I>name</I>) to the
value <I>param</I>_<I>value</I>.
If <I>param</I>_<I>value</I> is an empty string then the corresponding job
parameter will be deleted similar to the function
jsv_del_param(). As a result the job parameter is not avail-
able as if the corresponding command line switch was not
specified during job submission.
For boolean parameters that only accept the values <I>yes</I> or <I>no</I>
it is not allowed to pass an empty string as <I>param</I>_<I>value</I>.
Also for the parameters <I>c</I> and <I>m</I> it is not allowed to use
empty strings. Details can be found in <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B>.
jsv_del_param()
This function deletes the job parameter <I>param</I>_<I>name</I>.
Find a list of allowed parameter names in the section for
the function jsv_is_param().
jsv_sub_is_param()
Some job parameters are lists that can contain multiple
variables with an optional value.
This function returns <I>true</I> if a job parameters list contains
a variable and <I>false</I> otherwise. <I>false</I> might also indicate
that the parameter list itself is not available. Use the
function jsv_is_param() to check if the parameter list is
not available.
The following parameters are list parameters. The second
columns describes corresponding variable names to be used.
The third column contains a dash (-) if there is no value
(<I>variable</I>_<I>value</I>) allowed when the functions
jsv_sub_add_param() or it indicated that jsv_sub_get_param()
will return always an empty string. A question mark (?)
shows that the value is optional.
param_name variable_name variable_value
ac job context variable name
hold_jid job identifier -
l_hard complex attribute name ?
l_soft complex attribute name ?
M mail address -
masterq cluster queue name or -
queue instance name
q_hard cluster queue name or -
queue instance name
q_soft cluster queue name or -
queue instance name
jsv_sub_get_param()
Some job parameters are lists that can contain multiple
variables with an optional value.
This function returns the value of a variable
(<I>variable</I>_<I>name</I>). For sub list elements that have no value
an empty string will be returned.
Find a list of allowed parameter names (<I>param</I>_<I>name</I>) and
variable names (<I>variable</I>_<I>name</I>) in the section for the func-
tion jsv_sub_is_param().
jsv_sub_add_param()
Some job parameters are list that can contain multiple vari-
ables with an optional value.
This function either adds a new variable with a new value or
it modifies the value if the variable is already in the list
parameter. <I>variable</I>_<I>value</I> is optional. In that case, the
variable has no value.
Find a list of allowed parameter names (<I>param</I>_<I>name</I>) and
variable names (<I>variable</I>_<I>name</I>) in the section for the func-
tion jsv_sub_is_param().
jsv_sub_del_param()
Some job parameters are lists which can contain multiple
variables with an optional value.
This function deletes a variable (<I>variable</I>_<I>name</I>) and if
available the corresponding value. If (<I>variable</I>_<I>name</I>) is not
available in the job parameter then the command will be
ignored.
Find a list of allowed parameter names (<I>param</I>_<I>name</I>) and
variable names (<I>variable</I>_<I>name</I> ) in the section for the func-
tion jsv_sub_is_param().
jsv_is_env()
If the function returns <I>true</I>, then the job environment vari-
able with the name <I>variable</I>_<I>name</I> exists in the job currently
being verified and jsv_get_env() can be used to retrieve the
value of that variable. If the function returns <I>false</I>, then
the job environment variable (<I>variable</I>_<I>name</I>) does not exist.
jsv_get_env()
This function returns the value of a job environment vari-
able (<I>variable</I>_<I>name</I>).
This variable has to be passed with the <I>qsub</I> command line
switch -<I>v</I> or -<I>V</I> and it has to be enabled that environment
variable data is passed to JSV scripts. Environment variable
data is passed when the function jsv_send_env() is called in
the callback function jsv_on_start().
If the variable does not exist or if environment variable
information is not available then an empty string will be
returned.
jsv_add_env()
This function adds an additional environment variable to the
set of variables that will exported to the job, when it is
started. As a result the <I>variable</I>_<I>name</I> and <I>variable</I>_<I>value</I>
become available, as if the -v or -V was specified during
job submission.
<I>variable</I>_<I>value</I> is optional. If there is an empty string
passed then the variable is defined without value.
If <I>variable</I>_<I>name</I> already exists in the set of job environ-
ment variables, then the corresponding value will be
replaced by <I>variable</I>_<I>value</I>, as if the function jsv_mod_env()
was used. If an empty string is passed then the old value
will be deleted.
To delete a environment variable the function jsv_del_env()
has to be used.
jsv_mod_env()
This function modifies an existing environment variable that
is in the set of variables which will exported to the job,
when it is started. As a result, the <I>variable</I>_<I>name</I> and
<I>variable</I>_<I>value</I> will be available as if the -v or -V was
specified during job submission.
<I>variable</I>_<I>value</I> is optional. If there is an empty string
passed then the variable is defined without value.
If <I>variable</I>_<I>name</I> does not already exist in the set of job
environment variables, then the corresponding name and value
will be added as if the function jsv_add_env() was used.
To delete a environment variable, use the function
jsv_del_env().
jsv_del_env()
This function removes a job environment variable
(<I>variable</I>_<I>name</I>) from the set of variables that will be
exported to the job, when it is started.
If <I>variable</I>_<I>name</I> does not already exists in the set of job
environment variables then the command is ignored.
To change the value of a variable use the function
jsv_mod_env() to add a new value, call the function
jsv_add_env().
jsv_accept()
This function can only be used in jsv_on_verify(). After it
has been called, the function jsv_on_verify() has to return
immediately.
A call to this function indicates that the job that is
currently being verified should be accepted as it was ini-
tially provided. All job modifications that might have been
applied in jsv_on_verify() before this function was called,
are then ignored.
Instead of calling jsv_accept() in jsv_on_verify() also the
functions jsv_correct(), jsv_reject() or jsv_reject_wait()
can be called, but only one of these functions can be used
at a time.
jsv_correct()
This function can only be used in jsv_on_verify(). After it
has been called, the function jsv_on_verify() has to return
immediately.
A call to this function indicates that the job that is
currently being verified has to be modified before it can be
accepted. All job parameter modifications that were previ-
ously applied will be committed and the job will be
accepted. "Accept" in that case means that the job will
either be passed to the next JSV instance for modification
or that it is passed to that component in the master daemon
that adds it to the master data store when the last JSV
instance has verified the job.
Instead of calling jsv_correct() in jsv_on_verify(), the
functions jsv_accept(), jsv_reject() or jsv_reject_wait()
can be called, but only one of these functions can be used.
jsv_reject()
This function can only be used in jsv_on_verify(). After it
has been called the function jsv_on_verify() has to return
immediately.
The job that is currently being verified will be rejected.
<I>message</I> will be passed to the client application that tried
to submit the job. Commandline clients like <I>qsub</I> will print
that message to stdout to inform the user that the submis-
sion has failed.
jsv_reject_wait() should be called if the user may try to
submit the job again. jsv_reject_wait() indicates that the
verification process might be successful in the future.
Instead of calling jsv_reject() in jsv_on_verify() also the
functions jsv_accept(), jsv_correct() or jsv_reject_wait()
can be also called, but only one of these functions can be
used.
jsv_reject_wait()
This function can only be used in jsv_on_verify(). After it
has been called the function jsv_on_verify() has to return
immediately.
The job which is currently verified will be rejected. <I>mes-</I>
<I>sage</I> will be passed to the client application, that tries to
submit the job. Commandline clients like <I>qsub</I> will print
that message to stdout to inform the user that the submis-
sion has failed.
This function should be called if the user who tries to sub-
mit the job might have a chance to submit the job later.
jsv_reject indicates that the verified job will also be
rejected in future.
Instead of calling jsv_reject_wait() in jsv_on_verify() the
functions jsv_accept(), jsv_correct() or jsv_reject() can be
also called, but only one of these functions can be used.
jsv_log_info()
This function sends an info <I>message</I> to the client or master
daemon instance that started the JSV script.
For client JSVs, this means that the command line client
will get the information and print it to the stdout stream.
Server JSVs will print that message as an info message to
the master daemon message file.
If <I>message</I> is missing then and empty line will be printed.
jsv_log_warning()
This function sends a warning <I>message</I> to the client or mas-
ter daemon instance that started the JSV script.
For client JSVs, this means that the command line client
will get the information and print it to the stdout stream.
Server JSVs will print that message as an warning message to
the master daemon message file.
If <I>message</I> is missing then and empty line will be printed.
jsv_log_error()
This function sends an error <I>message</I> to the client or master
daemon instance that started the JSV script.
For client JSVs, this means that the command line client
will get the information and print it to the stdout stream.
Server JSVs will print that message as an error message to
the master daemon message file.
If <I>message</I> is missing then and empty line will be printed.
jsv_send_env()
This function can only be used in jsv_on_start(). If it is
used there, then the job environment information will be
available in jsv_on_verify() for the next job that is
scheduled to be verified.
This function must be called for the functions
jsv_show_envs(), jsv_is_env(), jsv_get_env(), jsv_add_env()
and jsv_mod_env() to behave correctly.
Job environments might become very big (10K and more). This
will slow down the executing component (submit client or
master daemon thread). For this reason, job environment
information is not passed to JSV scripts by default.
Please note also that the data in the job environment can't
be verified by Grid Engine and might therefore contain data
which could be misinterpreted in the script environment and
cause security issues.
jsv_main()
This function has to be called an main function in JSV
scripts. It implements the JSV protocol and performs the
communication with client and server components which might
start JSV scripts.
This function does not return immediately. It returns only
when the "QUIT" command is send by the client or server com-
ponent.
During the communication with client and server components,
this function triggers two callback functions for each job
that should be verified. First jsv_on_start() and later on
jsv_on_verify().
jsv_on_start() can be used to initialize certain things that
might be needed for the verification process.
jsv_on_verify() does the verification process itself.
The function jsv_send_env() can be called in jsv_on_start()
so that the job environment is available in jsv_on_verify().
The following function can only be used in jsv_on_verify().
Simple job parameters can be accessed/modified with:
jsv_is_param, jsv_get_param, jsv_set_param and
jsv_del_param.
List based job parameters can be accessed with:
jsv_sub_is_param, jsv_sub_get_param, jsv_sub_add_param and
jsv_sub_del_param
If the environment was requested with jsv_send_env() in
jsv_on_start() then the environment can be accessed/modified
with the following commands: jsv_is_env, jsv_get_env,
jsv_add_env, jsv_mod_env and jsv_del_env
Jobs can be accepted/rejected with the following:
jsv_accept, jsv_correct, jsv_reject and jsv_reject_wait.
The following functions send messages to the calling com-
ponent of a JSV that will either appear on the stdout stream
of the client or in the master message file. This is espe-
cially useful when new JSV scripts should be tested:
jsv_show_params, jsv_show_envs, jsv_log_info,
jsv_log_warning and jsv_log_error
jsv_on_start()
This is a callback function that has to be defined by the
creator of a JSV script. It is called for every job short
time before the verification process of a job starts.
Within this function jsv_send_env can be called to request
job environment information for the next job is scheduled to
be verified.
After this function returns jsv_on_verify() will be called.
This function does there verification process itself.
jsv_on_verify()
This is a callback function that has to be defined by the
creator of a JSV script. It is called for every job and
when it returns a the job will either be accepted or
rejected. Find implementation examples in the directory
$SGE_ROOT/util/resources/jsv.
The logic of this function completely depends on the creator
of this function. The creator has only to take care that one
of the functions jsv_accept(), jsv_reject(),
jsv_reject_wait() or jsv_correct() is called before the
function returns.
EXAMPLES
Find in the table below the returned values for the "*is*"
and "*get*" functions when following job is submitted:
qsub -l mem=1G,mem2=200M ...
function call returned value
----------------------------- -----------------
jsv_is_param(l_hard) "true"
jsv_get_param(l_hard) "mem=1G,mem2=200M"
jsv_sub_is_param(l_hard,mem) "true"
jsv_sub_get_param(l_hard,mem) "1G"
jsv_sub_get_param(l_hard,mem3) "false"
jsv_sub_get_param(l_hard,mem3) ""
SEE ALSO
<B><A HREF="../htmlman1/sge_intro.html?pathrev=V62u5_TAG">sge_intro(1)</A></B>, <B><A HREF="../htmlman1/jsv.html?pathrev=V62u5_TAG">jsv(1)</A></B>, <B><A HREF="../htmlman1/qalter.html?pathrev=V62u5_TAG">qalter(1)</A></B>, <B><A HREF="../htmlman1/qlogin.html?pathrev=V62u5_TAG">qlogin(1)</A></B>, <B><A HREF="../htmlman1/qmake.html?pathrev=V62u5_TAG">qmake(1)</A></B>,
<B><A HREF="../htmlman1/qrsh.html?pathrev=V62u5_TAG">qrsh(1)</A></B>, <B><A HREF="../htmlman1/qsh.html?pathrev=V62u5_TAG">qsh(1)</A></B>, <B><A HREF="../htmlman1/qsub.html?pathrev=V62u5_TAG">qsub(1)</A></B>, <B><A HREF="../htmlman1/qtcsh.html?pathrev=V62u5_TAG">qtcsh(1)</A></B>,
COPYRIGHT
See <B><A HREF="../htmlman1/sge_intro.html?pathrev=V62u5_TAG">sge_intro(1)</A></B> for a full statement of rights and permis-
sions.
</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>
|
