Provided by: gridengine-client_6.2u5-7.3_amd64 bug

NAME

       qhost - show the status of Sun Grid Engine hosts, queues, jobs

SYNTAX

       qhost  [  -cb  ]  [  -F  [resource_name,...]   ]  [  -help  ] [ -h host_list ] [ -j ] [ -l
       resource=val,...  ] [ -u user,...  ] [ -xml ].

DESCRIPTION

       qhost shows the current status of the available Sun Grid Engine hosts, queues and the jobs
       associated  with the queues. Selection options allow you to get information about specific
       hosts, queues, jobs or users.  If multiple selections are done a host is only displayed if
       all  selection criteria for a host are met.  Without any options qhost will display a list
       of all hosts without queue or job information.

OPTIONS

       -F [ resource_name,... ]
              qhost will present a detailed listing of the current resource availability per host
              with  respect  to all resources (if the option argument is omitted) or with respect
              to those resources contained  in  the  resource_name  list.  Please  refer  to  the
              description of the Full Format in section OUTPUT FORMATS below for further detail.

       -cb    This  command  line  switch  can  be  used  since  Sun Grid Engine version 6.2u5 in
              combination with other qhost(1) command line switches. In that case the  output  of
              the corresponding command will contain information concerning the added job to core
              binding feature.

              If this switch is not used then  the  command  behaves  as  in  version  6.2u4  and
              previous versions.

              If this option is used then two additional columns will be shown for each displayed
              host in the output. The first is named NSOC and represents the number of  available
              sockets  on that host. The second additional column is named NCOR and it represents
              the number of cores that are available per socket on the corresponding machine.

       -help  Prints a listing of all options.

       -h host_list
              Prints a list of all hosts contained in host_list.

       -j     Prints all jobs running on the queues hosted by the shown hosts. This switch  calls
              -q implicitly.

       -l resource[=value],...
              Defines  the  resources  to be granted by the hosts which should be included in the
              host list output. Matching is performed on  hosts  based  on  non-mutable  resource
              availability  information  only.   That means load values are always ignored except
              the  so-called  static  load  values   (i.e.   "arch",   "num_proc",   "mem_total",
              "swap_total" and "virtual_total") ones. Also consumable utilization is ignored.  If
              there are multiple -l resource requests they will be concatenated by a logical AND:
              a host needs to match all resources to be displayed.

       -q     Show information about the queues instances hosted by the displayed hosts.

       -u user,...
              Display  information  only on those jobs and queues being associated with the users
              from the given user list.

       -xml   This option can be used with all other options and changes the output to  XML.  The
              used schemas are referenced in the XML output. The output is printed to stdout.

              If  the  -xml  parameter  is  combined  with  -cb  then the XML output will contain
              additional tags containing information about job to core  binding.   You  can  find
              schema     files     with     the     suffix     "_cb"     in     the     directory
              $SGE_ROOT/util/resources/schemas/qhost that describe that changes.

OUTPUT FORMATS

       Depending on the presence or absence of the -q or -F and -j option  three  output  formats
       need to be differentiated.  PP

   Default Format (without -q, -F and -j)
       For each host one line is printed. The output consists of consisting of

       •  the Hostname

       •  the Architecture.

       •  the  Number of processors.

       •  the Load.

       •  the Total Memory.

       •  the Used Memory.

       •  the Total Swapspace.

       •  the Used Swapspace.

       If  the  -q  option is supplied, each host status line also contains extra lines for every
       queue hosted by the host consisting of,

       •  the queue name.

       •  the queue type - one of B(atch), I(nteractive), C(heckpointing), P(arallel), T(ransfer)
          or combinations thereof,

       •  the number of reserved, used and available job slots,

       •  the  state  of the queue - one of u(nknown) if the corresponding sge_execd(8) cannot be
          contacted,  a(larm),  A(larm),  C(alendar   suspended),   s(uspended),   S(ubordinate),
          d(isabled), D(isabled), E(rror) or combinations thereof.

       If   the  state  is  a(alarm)  at  least  one  of  the  load  thresholds  defined  in  the
       load_thresholds list of the queue configuration (see queue_conf(5)) is currently exceeded,
       which prevents from scheduling further jobs to that queue.

       As  opposed  to  this,  the  state  A(larm)  indicates  that  at  least one of the suspend
       thresholds of the queue (see queue_conf(5)) is currently exceeded.  This  will  result  in
       jobs running in that queue being successively suspended until no threshold is violated.

       The  states  s(uspended)  and  d(isabled)  can  be assigned to queues and released via the
       qmod(1) command. Suspending a queue will cause all jobs executing  in  that  queue  to  be
       suspended.

       The  states  D(isabled) and C(alendar suspended) indicate that the queue has been disabled
       or  suspended  automatically  via  the  calendar  facility  of  Sun   Grid   Engine   (see
       calendar_conf(5)),  while  the  S(ubordinate)  state  indicates,  that  the queue has been
       suspend  via  subordination  to  another  queue  (see  queue_conf(5)  for  details).  When
       suspending  a  queue  (regardless  of  the  cause)  all  jobs  executing in that queue are
       suspended too.

       If an E(rror) state is displayed for a queue, sge_execd(8) on  that  host  was  unable  to
       locate  the  sge_shepherd(8) executable on that host in order to start a job. Please check
       the error logfile of that sge_execd(8) for leads on how to  resolve  the  problem.  Please
       enable the queue afterwards via the -c option of the qmod(1) command manually.

       If the -F option was used, resource availability information is printed following the host
       status line. For each resource (as selected in  an  option  argument  to  -F  or  for  all
       resources  if  the  option  argument  was  omitted)  a  single  line is displayed with the
       following format:

       •  a one letter specifier indicating whether the current resource availability  value  was
          dominated by either
          `g' - a cluster global,
          `h' - a host total or

       •  a  second  one  letter  specifier  indicating  the  source  for  the  current  resource
          availability value, being one of
          `l' - a load value reported for the resource,
          `L' - a load value for the resource after administrator defined load scaling  has  been
          applied,
          `c' - availability derived from the consumable resources facility (see complexes(5)),
          `f'  -  a fixed availability definition derived from a non-consumable complex attribute
          or a fixed resource limit.

       •  after a colon the name of the resource on which information is displayed.

       •  after an equal sign the current resource availability value.

       The displayed availability values and the sources from which they derive  are  always  the
       minimum  values  of  all  possible  combinations.  Hence,  for example, a line of the form
       "qf:h_vmem=4G" indicates that a queue currently has  a  maximum  availability  in  virtual
       memory  of  4  Gigabyte,  where  this value is a fixed value (e.g. a resource limit in the
       queue configuration) and it is queue dominated, i.e. the  host  in  total  may  have  more
       virtual  memory  available  than  this, but the queue doesn't allow for more. Contrarily a
       line "hl:h_vmem=4G" would also indicate an  upper  bound  of  4  Gigabyte  virtual  memory
       availability,  but the limit would be derived from a load value currently reported for the
       host. So while the queue might allow for jobs with higher virtual memory requirements, the
       host on which this particular queue resides currently only has 4 Gigabyte available.

       After  the queue status line (in case of -j) a single line is printed for each job running
       currently in this queue. Each job status line contains

       •  the job ID,

       •  the job name,

       •  the job owner name,

       •  the status of the job - one  of  t(ransfering),  r(unning),  R(estarted),  s(uspended),
          S(uspended) or T(hreshold) (see the Reduced Format section for detailed information),

       •  the  start date and time and the function of the job (MASTER or SLAVE - only meaningful
          in case of a parallel job) and

       •  the priority of the jobs.

ENVIRONMENTAL VARIABLES

       SGE_ROOT       Specifies the location of the Sun Grid Engine standard configuration files.

       SGE_CELL       If set, specifies the default Sun Grid Engine cell. To address a  Sun  Grid
                      Engine cell qhost uses (in the order of precedence):

                             The name of the cell specified in the environment variable SGE_CELL,
                             if it is set.

                             The name of the default cell, i.e. default.

       SGE_DEBUG_LEVEL
                      If set, specifies that debug information should be written  to  stderr.  In
                      addition  the  level  of  detail in which debug information is generated is
                      defined.

       SGE_QMASTER_PORT
                      If set, specifies the tcp port  on  which  sge_qmaster(8)  is  expected  to
                      listen  for communication requests.  Most installations will use a services
                      map entry for the service "sge_qmaster" instead to define that port.

FILES

       <sge_root>/<cell>/common/act_qmaster
                       Sun Grid Engine master host file

SEE ALSO

       sge_intro(1), qalter(1), qconf(1), qhold(1), qmod(1),  qstat(1),  qsub(1),  queue_conf(5),
       sge_execd(8), sge_qmaster(8), sge_shepherd(8).

COPYRIGHT

       See sge_intro(1) for a full statement of rights and permissions.