JSV_SCRIPT_INTERFACE(3)    Grid Engine File Formats    JSV_SCRIPT_INTERFACE(3)



[1mNAME[0m
       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 - Grid Engine Job Submission Verifier Scripting
       Interface

[1mSYNOPSIS[0m
       [1mjsv_clear_params[22m();
       [1mjsv_is_param[22m([4mparam_name[24m);
       [1mjsv_get_param[22m([4mparam_name[24m);
       [1mjsv_set_param[22m([4mparam_name[24m, [4mparam_value[24m);
       [1mjsv_del_param[22m([4mparam_name[24m);
       [1mjsv_sub_is_param[22m([4mparam_name[24m, [4mvariable_name[24m);
       [1mjsv_sub_get_param[22m([4mparam_name[24m, [4mvariable_name[24m);
       [1mjsv_sub_add_param[22m([4mparam_name[24m, [4mvariable_name[24m, [4mvariable_value[24m);
       [1mjsv_sub_del_param[22m([4mparam_name[24m, [4mvariable_name[24m);

       [1mjsv_clear_envs[22m();
       [1mjsv_is_env[22m([4mvariable_name[24m);
       [1mjsv_get_env[22m([4mvariable_name[24m);
       [1mjsv_add_env[22m([4mvariable_name[24m, [4mvariable_value[24m);
       [1mjsv_mod_env[22m([4mvariable_name[24m, [4mvariable_value[24m);
       [1mjsv_del_env[22m([4mvariable_name[24m);

       [1mjsv_accept[22m([4mmessage[24m);
       [1mjsv_correct[22m([4mmessage[24m);
       [1mjsv_reject[22m([4mmessage[24m);
       [1mjsv_reject_wait[22m([4mmessage[24m);

       [1mjsv_show_params[22m();
       [1mjsv_show_envs[22m();
       [1mjsv_log_info[22m([4mmessage[24m);
       [1mjsv_log_warning[22m([4mmessage[24m);
       [1mjsv_log_error[22m([4mmessage[24m);

       [1mjsv_main[22m();
       [1mjsv_send_env[22m();
       [1mjsv_on_start[22m();
       [1mjsv_on_verify[22m();

[1mDESCRIPTION[0m
       The functions documented here implement the server side of the JSV pro-
       tocol as it is described in the man page [4mjsv[24m(1).   These  script  func-
       tions  are  available in Bourne shell, TCL or Perl scripts after sourc-
       ing/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.

   [1mjsv_clear_params()[0m
       This function clears all received job parameters that were stored  dur-
       ing the last job verification process.

   [1mjsv_clear_envs()[0m
       This  function  clears all received job environment variables that were
       stored during the last job verification process.

   [1mjsv_show_params()[0m
       A call of this function reports all known job parameters to  the  coun-
       terpart  of  this script (client or master daemon thread). This parame-
       ters 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.

   [1mjsv_show_envs()[0m
       A  call of this function reports all known job environment variables to
       the counterpart of this script (client or master daemon thread).   They
       will  be  reported  as info messages and appear in the stdout stream of
       the client or in the message file of the master process.

   [1mjsv_is_param()[0m
       This function returns whether or  not  a  specific  job  parameters  is
       available  for  the  job  which is currently being verified. Either the
       string [4mtrue[24m or [4mfalse[24m 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   [4mparam_name[24m.   Corresponding
       [4mqsub[24m/[4mqrsh[24m/[4mqsh[24m/...  switches  next  to  the parameter name are mentioned
       only if they are different from the command line switches.

       Find additional information in [4mqsub[24m(1) man page describing  the  avail-
       ability and value format. Job parameters written in capital letters are
       pseudo parameters. A detailed description for  them  can  be  found  in
       [4mjsv[24m(1)

          [1mparam_name              command line switch/description[0m
          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  [4mtrue[24m if the parameter ([4mparam_name[24m)
       exists in the job currently being verified. If it does not exist  [4mfalse[0m
       will be returned.

   [1mjsv_get_param()[0m
       This   function   returns   the  value  of  a  specific  job  parameter
       ([4mparam_name[24m).

       This value is only available if  the  function  [1mjsv_is_param[22m()  returns
       [4mtrue[24m. Otherwise an empty string is returned.

       Find  a list of allowed parameter names in the section for the function
       [1mjsv_is_param[22m().

   [1mjsv_set_param()[0m
       This function changes the  job  parameter  ([4mparam_name[24m)  to  the  value
       [4mparam_value.[0m

       If  [4mparam_value[24m is an empty string then the corresponding job parameter
       will be deleted similar to the function [1mjsv_del_param[22m().  As  a  result
       the job parameter is not available as if the corresponding command line
       switch was not specified during job submission.

       For boolean parameters that only accept the values [4myes[24m or [4mno[24m it is  not
       allowed to pass an empty string as [4mparam_value.[0m

       Also for the parameters [4mc[24m and [4mm[24m it is not allowed to use empty strings.
       Details can be found in [4mqsub[24m(1).

   [1mjsv_del_param()[0m
       This function deletes the job parameter [4mparam_name[24m.

       Find a list of allowed parameter names in the section for the  function
       [1mjsv_is_param[22m().

   [1mjsv_sub_is_param()[0m
       Some  job parameters are lists that can contain multiple variables with
       an optional value.

       This function returns [4mtrue[24m if a job parameters list contains a variable
       and  [4mfalse[24m otherwise. [4mfalse[24m might also indicate that the parameter list
       itself is not available. Use the function [1mjsv_is_param[22m()  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 ([4mvariable_value[24m) allowed  when
       the   functions    [1mjsv_sub_add_param[22m()    or    it    indicated    that
       [1mjsv_sub_get_param[22m() will return always an empty string. A question mark
       (?) shows that the value is optional.

          [1mparam_name        variable_name              variable_value[0m
          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

   [1mjsv_sub_get_param()[0m
       Some job parameters are lists that can contain multiple variables  with
       an optional value.

       This function returns the value of a variable ([4mvariable_name[24m).  For sub
       list elements that have no value an empty string will be returned.

       Find a list of allowed parameter names ([4mparam_name[24m) and variable  names
       ([4mvariable_name[24m) in the section for the function [1mjsv_sub_is_param[22m().

   [1mjsv_sub_add_param()[0m
       Some  job  parameters are list that can contain multiple variables with
       an optional value.

       This function either adds a new variable with a new value or  it  modi-
       fies the value if the variable is already in the list parameter.  [4mvari-[0m
       [4mable_value[24m is optional. In that case, the variable has no value.

       Find a list of allowed parameter names ([4mparam_name[24m) and variable  names
       ([4mvariable_name[24m) in the section for the function [1mjsv_sub_is_param[22m().

   [1mjsv_sub_del_param()[0m
       Some  job parameters are lists which can contain muliple variables with
       an optional value.

       This function deletes a variable ([4mvariable_name[24m) and if  available  the
       corresponding  value.  If  ([4mvariable_name[24m)  is not available in the job
       parameter then the command will be ignored.

       Find a list of allowed parameter names ([4mparam_name[24m) and variable  names
       ([4mvariable_name[24m ) in the section for the function [1mjsv_sub_is_param[22m().

   [1mjsv_is_env()[0m
       If  the  function  returns [4mtrue[24m, then the job environment variable with
       the name [4mvariable_name[24m exists in the job currently being  verified  and
       [1mjsv_get_env[22m()  can  be used to retrieve the value of that variable.  If
       the function returns [4mfalse[24m, then the job  environment  variable  ([4mvari-[0m
       [4mable_name[24m) does not exist.

   [1mjsv_get_env()[0m
       This  function  returns  the value of a job environment variable ([4mvari-[0m
       [4mable_name[24m).

       This variable has to be passed with the [4mqsub[24m command line switch [4m-v[24m  or
       [4m-V[24m and it has to be enabled that environment variable data is passed to
       JSV scripts. Environment variable data  is  passed  when  the  function
       [1mjsv_send_env[22m() is called in the callback function [1mjsv_on_start[22m().

       If  the  variable does not exist or if environment variable information
       is not available then an empty string will be returned.

   [1mjsv_add_env()[0m
       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 [4mvariable_name[24m and [4mvariable_value[24m become available, as if the
       -v or -V was specified during job submission.

       [4mvariable_value[24m is optional. If there is an empty string passed then the
       variable is defined without value.

       If [4mvariable_name[24m already exists in the set  of  job  environment  vari-
       ables, then the corresponding value will be replaced by [4mvariable_value[24m,
       as if the function [1mjsv_mod_env[22m() was used.  If an emty string is passed
       then the old value will be deleted.

       To  delete  a environment variable the function [1mjsv_del_env[22m() has to be
       used.

   [1mjsv_mod_env()[0m
       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 [4mvariable_name[24m and [4mvariable_value[24m will be available  as
       if the -v or -V was specified during job submission.

       [4mvariable_value[24m is optional. If there is an empty string passed then the
       variable is defined without value.

       If [4mvariable_name[24m does not already exist in the set of  job  environment
       variables,  then  the  corresponding name and value will be added as if
       the function [1mjsv_add_env[22m() was used.

       To delete a environment variable, use the function [1mjsv_del_env[22m().

   [1mjsv_del_env()[0m
       This function removes a job environment variable  ([4mvariable_name[24m)  from
       the  set  of  variables  that  will  be exported to the job, when it is
       started.

       If [4mvariable_name[24m 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 [1mjsv_mod_env[22m() to add
       a new value, call the function [1mjsv_add_env[22m().

   [1mjsv_accept()[0m
       This function can only be used in [1mjsv_on_verify[22m(). After  it  has  been
       called, the function [1mjsv_on_verify[22m() has to return immediately.

       A  call to this function indicates that the job that is currently being
       verified should be accepted as it was initially provided. All job  mod-
       ifications  that might have been applied in [1mjsv_on_verify[22m() before this
       function was called, are then ignored.

       Instead of calling [1mjsv_accept[22m() in [1mjsv_on_verify[22m() also  the  functions
       [1mjsv_correct[22m(),  [1mjsv_reject[22m()  or  [1mjsv_reject_wait[22m()  can be called, but
       only one of these functions can be used at a time.

   [1mjsv_correct()[0m
       This function can only be used in [1mjsv_on_verify[22m(). After  it  has  been
       called, the function [1mjsv_on_verify[22m() 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  parame-
       ter  modifications  that  were previously 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  [1mjsv_correct[22m()  in  [1mjsv_on_verify[22m(), the functions
       [1mjsv_accept[22m(), [1mjsv_reject[22m() or [1mjsv_reject_wait[22m() can be called, but only
       one of these functions can be used.

   [1mjsv_reject()[0m
       This  function  can  only be used in [1mjsv_on_verify[22m(). After it has been
       called the function [1mjsv_on_verify[22m() has to return immediately.

       The job that is currently being verified will be rejected. [4mmessage[24m will
       be  passed to the client application that tried to submit the job. Com-
       mandline clients like [4mqsub[24m will print that message to stdout to  inform
       the user that the submission has failed.

       [1mjsv_reject_wait[22m()  should  be  called if the user may try to submit the
       job again. [1mjsv_reject_wait[22m() indicates that  the  verification  process
       might be successful in the future.

       Instead  of  calling [1mjsv_reject[22m() in [1mjsv_on_verify[22m() also the functions
       [1mjsv_accept()[22m, [1mjsv_correct[22m() or [1mjsv_reject_wait[22m() can  be  also  called,
       but only one of these functions can be used.

   [1mjsv_reject_wait()[0m
       This  function  can  only be used in [1mjsv_on_verify[22m(). After it has been
       called the function [1mjsv_on_verify[22m() has to return immediately.

       The job which is currently verified will be rejected. [4mmessage[24m  will  be
       passed to the client application, that tries to submit the job. Comman-
       dline clients like [4mqsub[24m will print that message to stdout to inform the
       user that the submission has failed.

       This  function should be called if the user who tries to submit the job
       might have a chance to submit the job later. [1mjsv_reject [22mindicates  that
       the verified job will also be rejected in future.

       Instead  of  calling [1mjsv_reject_wait[22m() in [1mjsv_on_verify[22m() the functions
       [1mjsv_accept[22m(), [1mjsv_correct[22m() or [1mjsv_reject[22m() can  be  also  called,  but
       only one of these functions can be used.

   [1mjsv_log_info()[0m
       This  function  sends  an  info  [4mmessage[24m 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.

   [1mjsv_log_warning()[0m
       This function sends a warning [4mmessage[24m 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 warning message to the master daemon message file.

   [1mjsv_log_error()[0m
       This  function  sends  an  error [4mmessage[24m 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.

   [1mjsv_send_env()[0m
       This function can only be used in [1mjsv_on_start[22m(). If it is used  there,
       then  the  job environment information will be available in [1mjsv_on_ver-[0m
       [1mify[22m() for the next job that is scheduled to be verified.

       This  function  must  be  called  for  the  functions  [1mjsv_show_envs()[22m,
       [1mjsv_is_env[22m(),  [1mjsv_get_env[22m(), [1mjsv_add_env[22m() and [1mjsv_mod_env[22m() 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  misin-
       terpreted in the script environment and cause security issues.

   [1mjsv_main()[0m
       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 component.

       During the communication with client and server components, this  func-
       tion  triggers two callback functions for each job that should be veri-
       fied. First [1mjsv_on_start[22m() and later on [1mjsv_on_verify[22m().

       [1mjsv_on_start[22m() can be used to initialize certain things that  might  be
       needed for the verification process. [1mjsv_on_verify[22m() does the verifica-
       tion process itself.

       The function [1mjsv_send_env[22m() can be called in [1mjsv_on_start[22m() so that the
       job environment is available in [1mjsv_on_verify[22m().

       The following function can only be used in [1mjsv_on_verify[22m().  Simple job
       parameters can be accessed/modified with: [1mjsv_is_param[22m,  [1mjsv_get_param[22m,
       [1mjsv_set_param [22mand [1mjsv_del_param[22m.

       List  based  job  parameters  can  be  accessed with: [1mjsv_sub_is_param[22m,
       [1mjsv_sub_get_param[22m, [1mjsv_sub_add_param [22mand [1mjsv_sub_del_param[0m

       If the environment was requested with [1mjsv_send_env[22m() in  [1mjsv_on_start[22m()
       then  the  environment can be accessed/modified with the following com-
       mands:   [1mjsv_is_env[22m,   [1mjsv_get_env[22m,   [1mjsv_add_env[22m,   [1mjsv_mod_env    [22mand
       [1mjsv_del_env[0m

       Jobs  can be accepted/rejected with the following: [1mjsv_accept[22m, [1mjsv_cor-[0m
       [1mrect[22m, [1mjsv_reject [22mand [1mjsv_reject_wait[22m.

       The following functions send messages to the calling component of a JSV
       that  will  either  appear on the stdout stream of the client or in the
       master message file. This is especially useful  when  new  JSV  scripts
       should   be   tested:   jsv_show_params[1m,  [22mjsv_show_envs[1m,  [22mjsv_log_info[1m,[0m
       jsv_log_warning [1mand [22mjsv_log_error

   [1mjsv_on_start()[0m
       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 verifica-
       tion process of a job starts.

       Within this function [1mjsv_send_env [22mcan be called to request job environ-
       ment information for the next job is scheduled to be verified.

       After  this function returns [1mjsv_on_verify[22m() will be called. This func-
       tion does there verification process itself.

   [1mjsv_on_verify()[0m
       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
       [1mjsv_accept[22m(),   [1mjsv_reject[22m(),  [1mjsv_reject_wait[22m()  or  [1mjsv_correct[22m()  is
       called before the function returns.

[1mSEE ALSO[0m
       [4mge_intro[24m(1), [4mjsv[24m(1), [4mqalter[24m(1), [4mqlogin[24m(1), [4mqmake[24m(1),  [4mqrsh[24m(1),  [4mqsh[24m(1),
       [4mqsub[24m(1), [4mqtcsh[24m(1),

[1mCOPYRIGHT[0m
       See [4mge_intro[24m(1) for a full statement of rights and permissions.



GE 6.2u2                 $Date: 2009/02/16 09:33:48 $  JSV_SCRIPT_INTERFACE(3)
