1JSV_SCRIPT_INTERFACE(3) Grid Engine File Formats JSV_SCRIPT_INTERFACE(3)
2
6 jsv_is_param, jsv_get_param, jsv_add_param, jsv_mod_param,
7 jsv_del_param, jsv_sub_is_param, jsv_sub_get_param, jsv_sub_add_param,
8 jsv_sub_del_param, jsv_is_env, jsv_get_env, jsv_add_env, jsv_mod_env,
9 jsv_del_env, jsv_accept, jsv_correct, jsv_reject, jsv_reject_wait,
10 jsv_show_params, jsv_show_envs, jsv_log_info, jsv_log_warning,
11 jsv_log_error, jsv_main - Grid Engine Job Submission Verifier Scripting
12 Interface
13
15 jsv_clear_params();
16 jsv_is_param(param_name);
17 jsv_get_param(param_name);
18 jsv_set_param(param_name, param_value);
19 jsv_del_param(param_name);
20 jsv_sub_is_param(param_name, variable_name);
21 jsv_sub_get_param(param_name, variable_name);
22 jsv_sub_add_param(param_name, variable_name, variable_value);
23 jsv_sub_del_param(param_name, variable_name);
24 jsv_clear_envs();
26 jsv_is_env(variable_name);
27 jsv_get_env(variable_name);
28 jsv_add_env(variable_name, variable_value);
29 jsv_mod_env(variable_name, variable_value);
30 jsv_del_env(variable_name);
31 jsv_accept(message);
33 jsv_correct(message);
34 jsv_reject(message);
35 jsv_reject_wait(message);
36 jsv_show_params();
38 jsv_show_envs();
39 jsv_log_info(message);
40 jsv_log_warning(message);
41 jsv_log_error(message);
42 jsv_main();
44 jsv_send_env();
45 jsv_on_start();
46 jsv_on_verify();
47
49 The functions documented here implement the server side of the JSV pro‐
50 tocol as it is described in the man page jsv(1). These script func‐
51 tions are available in Bourne shell, TCL or Perl scripts after sourc‐
52 ing/including the files jsv_inlcude.sh, jsv_include.tcl or JSV.pm. The
53 files and corresponding JSV script templates are located in the direc‐
54 tory $SGE_ROOT/util/resources/jsv.
55 jsv_clear_params()
57 This function clears all received job parameters that were stored dur‐
58 ing the last job verification process.
59 jsv_clear_envs()
61 This function clears all received job environment variables that were
62 stored during the last job verification process.
63 jsv_show_params()
65 A call of this function reports all known job parameters to the coun‐
66 terpart of this script (client or master daemon thread). This parame‐
67 ters will be reported as info messages and appear either in the stdout
68 stream of the client or in the message file of the master process.
69 jsv_show_envs()
71 A call of this function reports all known job environment variables to
72 the counterpart of this script (client or master daemon thread). They
73 will be reported as info messages and appear in the stdout stream of
74 the client or in the message file of the master process.
75 jsv_is_param()
77 This function returns whether or not a specific job parameters is
78 available for the job which is currently being verified. Either the
79 string true or false will be returned. The availability/absence of a
80 job parameter does not mean that the corresponding command line switch
81 was used/not used.
82 The following values are allowed for param_name. Corresponding
84 qsub/qrsh/qsh/... switches next to the parameter name are mentioned
85 only if they are different from the command line switches.
86 Find additional information in qsub(1) man page describing the avail‐
88 ability and value format. Job parameters written in capital letters are
89 pseudo parameters. A detailed description for them can be found in
90 jsv(1)
91 param_name command line switch/description
93 a
94 ac combination of -ac, -sc, -dc
95 ar
96 A
97 b
98 c
99 ckpt
100 cwd
101 display
102 dl
103 e
104 h
105 hold_jid
106 hold_jid_ad
107 i
108 l_hard -l or -hard followed by -l
109 l_soft -soft followed by -l
110 j
111 js
112 m
113 M
114 masterq
115 N
116 notify
117 now
118 N
119 o
120 ot
121 P
122 pe
123 q_hard -q or -hard followed by -q
124 q_soft -soft followed by -q
125 R
126 r
127 shell
128 S
129 t
130 w
131 wd
132 CLIENT
133 CONTEXT
134 GROUP
135 VERSION
136 JOB_ID
137 SCRIPT
138 CMDARGS
139 CMDARG<i> where <i> is a nonnegative number
140 USER
141 The function returns the string true if the parameter (param_name)
143 exists in the job currently being verified. If it does not exist false
144 will be returned.
145 jsv_get_param()
147 This function returns the value of a specific job parameter
148 (param_name).
149 This value is only available if the function jsv_is_param() returns
151 true. Otherwise an empty string is returned.
152 Find a list of allowed parameter names in the section for the function
154 jsv_is_param().
155 jsv_set_param()
157 This function changes the job parameter (param_name) to the value
158 param_value.
159 If param_value is an empty string then the corresponding job parameter
161 will be deleted similar to the function jsv_del_param(). As a result
162 the job parameter is not available as if the corresponding command line
163 switch was not specified during job submission.
164 For boolean parameters that only accept the values yes or no it is not
166 allowed to pass an empty string as param_value.
167 Also for the parameters c and m it is not allowed to use empty strings.
169 Details can be found in qsub(1).
170 jsv_del_param()
172 This function deletes the job parameter param_name.
173 Find a list of allowed parameter names in the section for the function
175 jsv_is_param().
176 jsv_sub_is_param()
178 Some job parameters are lists that can contain multiple variables with
179 an optional value.
180 This function returns true if a job parameters list contains a variable
182 and false otherwise. false might also indicate that the parameter list
183 itself is not available. Use the function jsv_is_param() to check if
184 the parameter list is not available.
185 The following parameters are list parameters. The second columns
187 describes corresponding variable names to be used. The third column
188 contains a dash (-) if there is no value (variable_value) allowed when
189 the functions jsv_sub_add_param() or it indicated that
190 jsv_sub_get_param() will return always an empty string. A question mark
191 (?) shows that the value is optional.
192 param_name variable_name variable_value
194 ac job context variable name
195 hold_jid job identifier -
196 l_hard complex attribute name ?
197 l_soft complex attribute name ?
198 M mail address -
199 masterq cluster queue name or -
200 queue instance name
201 q_hard cluster queue name or -
202 queue instance name
203 q_soft cluster queue name or -
204 queue instance name
205 jsv_sub_get_param()
207 Some job parameters are lists that can contain multiple variables with
208 an optional value.
209 This function returns the value of a variable (variable_name). For sub
211 list elements that have no value an empty string will be returned.
212 Find a list of allowed parameter names (param_name) and variable names
214 (variable_name) in the section for the function jsv_sub_is_param().
215 jsv_sub_add_param()
217 Some job parameters are list that can contain multiple variables with
218 an optional value.
219 This function either adds a new variable with a new value or it modi‐
221 fies the value if the variable is already in the list parameter. vari‐
222 able_value is optional. In that case, the variable has no value.
223 Find a list of allowed parameter names (param_name) and variable names
225 (variable_name) in the section for the function jsv_sub_is_param().
226 jsv_sub_del_param()
228 Some job parameters are lists which can contain multiple variables with
229 an optional value.
230 This function deletes a variable (variable_name) and if available the
232 corresponding value. If (variable_name) is not available in the job
233 parameter then the command will be ignored.
234 Find a list of allowed parameter names (param_name) and variable names
236 (variable_name ) in the section for the function jsv_sub_is_param().
237 jsv_is_env()
239 If the function returns true, then the job environment variable with
240 the name variable_name exists in the job currently being verified and
241 jsv_get_env() can be used to retrieve the value of that variable. If
242 the function returns false, then the job environment variable (vari‐
243 able_name) does not exist.
244 jsv_get_env()
246 This function returns the value of a job environment variable (vari‐
247 able_name).
248 This variable has to be passed with the qsub command line switch -v or
250 -V and it has to be enabled that environment variable data is passed to
251 JSV scripts. Environment variable data is passed when the function
252 jsv_send_env() is called in the callback function jsv_on_start().
253 If the variable does not exist or if environment variable information
255 is not available then an empty string will be returned.
256 jsv_add_env()
258 This function adds an additional environment variable to the set of
259 variables that will exported to the job, when it is started. As a
260 result the variable_name and variable_value become available, as if the
261 -v or -V was specified during job submission.
262 variable_value is optional. If there is an empty string passed then the
264 variable is defined without value.
265 If variable_name already exists in the set of job environment vari‐
267 ables, then the corresponding value will be replaced by variable_value,
268 as if the function jsv_mod_env() was used. If an empty string is
269 passed then the old value will be deleted.
270 To delete a environment variable the function jsv_del_env() has to be
272 used.
273 jsv_mod_env()
275 This function modifies an existing environment variable that is in the
276 set of variables which will exported to the job, when it is started.
277 As a result, the variable_name and variable_value will be available as
278 if the -v or -V was specified during job submission.
279 variable_value is optional. If there is an empty string passed then the
281 variable is defined without value.
282 If variable_name does not already exist in the set of job environment
284 variables, then the corresponding name and value will be added as if
285 the function jsv_add_env() was used.
286 To delete a environment variable, use the function jsv_del_env().
288 jsv_del_env()
290 This function removes a job environment variable (variable_name) from
291 the set of variables that will be exported to the job, when it is
292 started.
293 If variable_name does not already exists in the set of job environment
295 variables then the command is ignored.
296 To change the value of a variable use the function jsv_mod_env() to add
298 a new value, call the function jsv_add_env().
299 jsv_accept()
301 This function can only be used in jsv_on_verify(). After it has been
302 called, the function jsv_on_verify() has to return immediately.
303 A call to this function indicates that the job that is currently being
305 verified should be accepted as it was initially provided. All job mod‐
306 ifications that might have been applied in jsv_on_verify() before this
307 function was called, are then ignored.
308 Instead of calling jsv_accept() in jsv_on_verify() also the functions
310 jsv_correct(), jsv_reject() or jsv_reject_wait() can be called, but
311 only one of these functions can be used at a time.
312 jsv_correct()
314 This function can only be used in jsv_on_verify(). After it has been
315 called, the function jsv_on_verify() has to return immediately.
316 A call to this function indicates that the job that is currently being
318 verified has to be modified before it can be accepted. All job parame‐
319 ter modifications that were previously applied will be committed and
320 the job will be accepted. "Accept" in that case means that the job will
321 either be passed to the next JSV instance for modification or that it
322 is passed to that component in the master daemon that adds it to the
323 master data store when the last JSV instance has verified the job.
324 Instead of calling jsv_correct() in jsv_on_verify(), the functions
326 jsv_accept(), jsv_reject() or jsv_reject_wait() can be called, but only
327 one of these functions can be used.
328 jsv_reject()
330 This function can only be used in jsv_on_verify(). After it has been
331 called the function jsv_on_verify() has to return immediately.
332 The job that is currently being verified will be rejected. message will
334 be passed to the client application that tried to submit the job. Com‐
335 mandline clients like qsub will print that message to stdout to inform
336 the user that the submission has failed.
337 jsv_reject_wait() should be called if the user may try to submit the
339 job again. jsv_reject_wait() indicates that the verification process
340 might be successful in the future.
341 Instead of calling jsv_reject() in jsv_on_verify() also the functions
343 jsv_accept(), jsv_correct() or jsv_reject_wait() can be also called,
344 but only one of these functions can be used.
345 jsv_reject_wait()
347 This function can only be used in jsv_on_verify(). After it has been
348 called the function jsv_on_verify() has to return immediately.
349 The job which is currently verified will be rejected. message will be
351 passed to the client application, that tries to submit the job. Comman‐
352 dline clients like qsub will print that message to stdout to inform the
353 user that the submission has failed.
354 This function should be called if the user who tries to submit the job
356 might have a chance to submit the job later. jsv_reject indicates that
357 the verified job will also be rejected in future.
358 Instead of calling jsv_reject_wait() in jsv_on_verify() the functions
360 jsv_accept(), jsv_correct() or jsv_reject() can be also called, but
361 only one of these functions can be used.
362 jsv_log_info()
364 This function sends an info message to the client or master daemon
365 instance that started the JSV script.
366 For client JSVs, this means that the command line client will get the
368 information and print it to the stdout stream. Server JSVs will print
369 that message as an info message to the master daemon message file.
370 If message is missing then and empty line will be printed.
372 jsv_log_warning()
374 This function sends a warning message to the client or master daemon
375 instance that started the JSV script.
376 For client JSVs, this means that the command line client will get the
378 information and print it to the stdout stream. Server JSVs will print
379 that message as an warning message to the master daemon message file.
380 If message is missing then and empty line will be printed.
382 jsv_log_error()
384 This function sends an error message to the client or master daemon
385 instance that started the JSV script.
386 For client JSVs, this means that the command line client will get the
388 information and print it to the stdout stream. Server JSVs will print
389 that message as an error message to the master daemon message file.
390 If message is missing then and empty line will be printed.
392 jsv_send_env()
394 This function can only be used in jsv_on_start(). If it is used there,
395 then the job environment information will be available in jsv_on_ver‐
396 ify() for the next job that is scheduled to be verified.
397 This function must be called for the functions jsv_show_envs(),
399 jsv_is_env(), jsv_get_env(), jsv_add_env() and jsv_mod_env() to behave
400 correctly.
401 Job environments might become very big (10K and more). This will slow
403 down the executing component (submit client or master daemon thread).
404 For this reason, job environment information is not passed to JSV
405 scripts by default.
406 Please note also that the data in the job environment can't be verified
408 by Grid Engine and might therefore contain data which could be misin‐
409 terpreted in the script environment and cause security issues.
410 jsv_main()
412 This function has to be called an main function in JSV scripts. It
413 implements the JSV protocol and performs the communication with client
414 and server components which might start JSV scripts.
415 This function does not return immediately. It returns only when the
417 "QUIT" command is send by the client or server component.
418 During the communication with client and server components, this func‐
420 tion triggers two callback functions for each job that should be veri‐
421 fied. First jsv_on_start() and later on jsv_on_verify().
422 jsv_on_start() can be used to initialize certain things that might be
424 needed for the verification process. jsv_on_verify() does the verifica‐
425 tion process itself.
426 The function jsv_send_env() can be called in jsv_on_start() so that the
428 job environment is available in jsv_on_verify().
429 The following function can only be used in jsv_on_verify(). Simple job
431 parameters can be accessed/modified with: jsv_is_param, jsv_get_param,
432 jsv_set_param and jsv_del_param.
433 List based job parameters can be accessed with: jsv_sub_is_param,
435 jsv_sub_get_param, jsv_sub_add_param and jsv_sub_del_param
436 If the environment was requested with jsv_send_env() in jsv_on_start()
438 then the environment can be accessed/modified with the following com‐
439 mands: jsv_is_env, jsv_get_env, jsv_add_env, jsv_mod_env and
440 jsv_del_env
441 Jobs can be accepted/rejected with the following: jsv_accept, jsv_cor‐
443 rect, jsv_reject and jsv_reject_wait.
444 The following functions send messages to the calling component of a JSV
446 that will either appear on the stdout stream of the client or in the
447 master message file. This is especially useful when new JSV scripts
448 should be tested: jsv_show_params, jsv_show_envs, jsv_log_info,
449 jsv_log_warning and jsv_log_error
450 jsv_on_start()
452 This is a callback function that has to be defined by the creator of a
453 JSV script. It is called for every job short time before the verifica‐
454 tion process of a job starts.
455 Within this function jsv_send_env can be called to request job environ‐
457 ment information for the next job is scheduled to be verified.
458 After this function returns jsv_on_verify() will be called. This func‐
460 tion does there verification process itself.
461 jsv_on_verify()
463 This is a callback function that has to be defined by the creator of a
464 JSV script. It is called for every job and when it returns a the job
465 will either be accepted or rejected. Find implementation examples in
466 the directory $SGE_ROOT/util/resources/jsv.
467 The logic of this function completely depends on the creator of this
469 function. The creator has only to take care that one of the functions
470 jsv_accept(), jsv_reject(), jsv_reject_wait() or jsv_correct() is
471 called before the function returns.
472
474 Find in the table below the returned values for the "*is*" and "*get*"
475 functions when following job is submitted:
476 qsub -l mem=1G,mem2=200M ...
478 function call returned value
480 ----------------------------- -----------------
481 jsv_is_param(l_hard) "true"
482 jsv_get_param(l_hard) "mem=1G,mem2=200M"
483 jsv_sub_is_param(l_hard,mem) "true"
484 jsv_sub_get_param(l_hard,mem) "1G"
485 jsv_sub_get_param(l_hard,mem3) "false"
486 jsv_sub_get_param(l_hard,mem3) ""
487
490 ge_intro(1), jsv(1), qalter(1), qlogin(1), qmake(1), qrsh(1), qsh(1),
491 qsub(1), qtcsh(1),
492
494 See ge_intro(1) for a full statement of rights and permissions.
495GE 6.2u5 $Date: 2009/05/28 16:56:19 $ JSV_SCRIPT_INTERFACE(3)