NAME
     sge_shepherd - Sun Grid Engine single job controlling agent

SYNOPSIS
     sge_shepherd

DESCRIPTION
     sge_shepherd provides the parent process functionality for a
     single  Sun  Grid  Engine  job.  The parent functionality is
     necessary on UNIX systems to retrieve resource usage  infor-
     mation (see getrusage(2)) after a job has finished. In addi-
     tion, the sge_shepherd forwards signals to the job, such  as
     the  signals  for  suspension, enabling, termination and the
     Sun Grid Engine checkpointing signal  (see  sge_ckpt(1)  for
     details).

     The sge_shepherd receives information about the  job  to  be
     started  from the sge_execd(8).  During the execution of the
     job it actually starts up to 5 child processes. First a pro-
     log  script  is run if this feature is enabled by the prolog
     parameter in the cluster configuration.  (See  sge_conf(5).)
     Next  a parallel environment startup procedure is run if the
     job is a parallel job. (See sge_pe(5) for more information.)
     After  that,  the  job itself is run, followed by a parallel
     environment  shutdown  procedure  for  parallel  jobs,   and
     finally  an epilog script if requested by the epilog parame-
     ter in the cluster  configuration.  The  prolog  and  epilog
     scripts  as  well  as  the  parallel environment startup and
     shutdown procedures are to  be  provided  by  the  Sun  Grid
     Engine  administrator  and  are  intended  for site-specific
     actions to be taken before and after execution of the actual
     user job.

     After the job has finished and the  epilog  script  is  pro-
     cessed,  sge_shepherd  retrieves  resource  usage statistics
     about the job, places them in a job specific subdirectory of
     the  sge_execd(8)  spool  directory  for  reporting  through
     sge_execd(8) and finishes.

     sge_shepherd also places an exit status file  in  the  spool
     directory.  This  exit  status  can  be viewed with qacct -j
     JobId  (see  qacct(1));  it  is  not  the  exit  status   of
     sge_shepherd  itself  but  of one of the methods executed by
     sge_shepherd. This exit status can  have  several  meanings,
     depending  on  in  which  method an error occurred (if any).
     The possible  methods  are:  prolog,  parallel  start,  job,
     parallel  stop,  epilog, suspend, restart, terminate, clean,
     migrate, and checkpoint.

     The following exit values are returned:

     0      All methods: Operation was executed successfully.
     99     Job script, prolog and epilog: When FORBID_RESCHEDULE
            is  not  set  in the configuration (see sge_conf(5)),
            the job gets re-queued.  Otherwise see "Other".

     100    Job script, prolog and epilog:  When  FORBID_APPERROR
            is  not  set  in the configuration (see sge_conf(5)),
            the job gets re-queued.  Otherwise see "Other".

     Other  Job script: This  is  the  exit  status  of  the  job
            itself.  No  action  is  taken  upon this exit status
            because the meaning of this exit status is not known.
            Prolog, epilog and parallel start: The queue  is  set
            to error state and the job is re-queued.
            Parallel stop: The queue is set to error  state,  but
            the  job is not re-queued. It is assumed that the job
            itself ran successfully and only the clean up  script
            failed.
            Suspend,  restart,  terminate,  clean,  and  migrate:
            Always successful.
            Checkpoint: Success, except for kernel checkpointing:
            checkpoint  was  not  successful, did not happen (but
            migration will happen by Sun Grid Engine).

RESTRICTIONS
     sge_shepherd should not be invoked  manually,  but  only  by
     sge_execd(8).

FILES
     sgepasswd  contains  a  list  of  user  names   and    their
     corresponding  encrypted  passwords. If available, the pass-
     word  file  will  be   used   by   sge_shepherd.  To  change
     the  contents of this file please use the sgepasswd command.
     It is not advised to  change that file manually.
     <execd_spool>/job_dir/<job_id>     job specific directory

SEE ALSO
     sge_intro(1), sge_conf(5), sge_execd(8).

COPYRIGHT
     See sge_intro(1) for a full statement of rights and  permis-
     sions.