    NAME
         complex - Sun Grid Engine complexes configuration file  for-
         mat

    DESCRIPTION
         Complex reflects the format of the Sun Grid  Engine  complex
         configuration.   The  definition  of complex attributes pro-
         vides all  pertinent  information  concerning  the  resource
         attributes  a user may request for a Sun Grid Engine job via
         the qsub(1) -l option and for the  interpretation  of  these
         parameters within the Sun Grid Engine system.

         The Sun Grid Engine complex object defines all entries which
         are  used  for  configuring  the global, the host, and queue
         object. The system has a set of pre defined  entries,  which
         are  assigned to a host or queue per default.  In a addition
         can the user define new entries and assign them  to  one  or
         multiple   objects.   Each   load  value  has  to  have  its
         corresponding complex entry object, which defines  the  type
         and the relational operator for it.

      defining resource attributes
         The complex configuration should not be  accessed  directly.
         In  order  to  add  or  modify complex entries, the qconf(1)
         options -Mc and -mc should be used instead.  While  the  -Mc
         option takes a complex configuration file as an argument and
         overrides the current configuration, the -mc option bring up
         an editor filled in with the current complex configuration.

         The provided  list  contains  all  definitions  of  resource
         attributes  in  the system. Adding a new entry means to pro-
         vide: name, shortcut, type, relop, requestable,  consumable,
         default, and urgency. The fields are described below. Chang-
         ing one is easily done by updating the field to  change  and
         removing  an  entry by deleting its definition. An attribute
         can only be removed, when it is not referenced in a host  or
         queue  object  anymore.  Also  does the system have a set of
         default resource attributes which are always attached  to  a
         host  or  queue.  They cannot be deleted nor can the type of
         such an attribute be changed.

      working with resource attributes
         Before a user can request a resource attribute it has to  be
         attached to the global, host, or cqueue object. The resource
         attribute exists only for the objects, it got attached to  (
         if it is attached to the global object(qconf -me global), it
         exits system wide, host object: only on that host (qconf -me
         NAME): cqueue object: only on that cqueue (qconf -mq NAME)).

         When the user attached a resource attribute  to  an  object,
         one  also  has  to assign a value to it; the resource limit.
         Another way to get a resource attribute  value  is  done  by
         configuring a load sensor for that attribute.

      Default queue resource attributes
         In its default form it contains a selection of parameters in
         the  queue  configuration  as defined in queue_conf(5).  The
         queue configuration parameters being requestable for  a  job
         by the user in principal are:

              qname
              hostname
              notify
              calendar
              min_cpu_interval
              tmpdir
              seq_no
              s_rt
              h_rt
              s_cpu
              h_cpu
              s_data
              h_data
              s_stack
              h_stack
              s_core
              h_core
              s_rss
              h_rss

      Default host resource attributes
         The standard set of host related attributes consists of  two
         categories. he first category is built by several queue con-
         figuration attributes which are particularly suitable to  be
         managed on a host basis. These attributes are:

              slots
              s_vmem
              h_vmem
              s_fsize
              h_fsize
         (please refer to queue_conf(5) for details).

         Note: Defining these attributes in the host  complex  is  no
         contradiction  to  having  them also in the queue configura-
         tion. It allows maintaining the corresponding resources on a
         host level and at the same time on a queue level. Total vir-
         tual free memory (h_vmem) can be managed  for  a  host,  for
         example,  and a subset of the total amount can be associated
         with a queue on that host.

         The second attribute category in the standard  host  complex
         are  the default load values Every sge_execd(8) periodically
         reports load to sge_qmaster(8).  The  reported  load  values
         are  either the standard Sun Grid Engine load values such as
         the CPU load average (see uptime(1)) or load values  defined
         by  the  Sun Grid Engine administration (see the load_sensor
         parameter in the cluster configuration sge_conf(5)  and  the
         Sun   Grid   Engine   Installation  and  Administration  for
         details).  The characteristics definition for  the  standard
         load  values  is  part  of  the  default host complex, while
         administrator defined load values require extension  of  the
         host     complex.     Please     refer     to    the    file
         <sge_root>/doc/load_parameters.asc for detailed  information
         on the standard set of load values.

      Overriding attributes
         One attribute can be assigned to  the  global  object,  host
         object, and queue object at the same time. On the host level
         it might get its value from the user defined resource  limit
         and  a  load sensor. In case that the attribute is a consum-
         able, we have in addition to the resource limit and its load
         report on host level also the internal usage, which the sys-
         tem keeps track of. The merge is done as follows:

         In general an attribute can be overridden on a lower level
            - global by hosts and queues
            - hosts by queues and load values or resource  limits  on
         the same level.

         We have one limitation for overriding  attributes  based  on
         its relational operator:

         !=, == operators can only be overridden on the  same  level,
         but  not  on  a  lower  level. The user defined value always
         overrides the load value.

         >=, >, <=, < operators can only be overridden, when the  new
         value is more restrictive than the old one.

         In the case of a consumable on host level, which has also  a
         load sensor, the system checks for the current usage, and if
         the internal accounting is more restrictive  than  the  load
         sensor  report, the internal value is kept; if the load sen-
         sor report is more restrictive, that one is kept.

         Note, Sun Grid Engine allows  backslashes  (\)  be  used  to
         escape  newline (\newline) characters. The backslash and the
         newline are replaced with a space (" ") character before any
         interpretation.

    FORMAT
         The principal format of a complex configuration is that of a
         tabulated list. Each line starting with a '#' character is a
         comment line. Each line despite  comment  lines  define  one
         element  of  the complex. A element definition line consists
         of the following 8 column entries per line (in the order  of
         appearance):

      name
         The name of the complex element to be used to  request  this
         attribute  for  a  job  in  the qsub(1) -l option. A complex
         attribute name (see complex_name in sge_types(1)) may appear
         only  once  across all complexes, i.e. the complex attribute
         definition is unique.

      shortcut
         A shortcut for name which may also be used to  request  this
         attribute  for  a job in the qsub(1) -l option. An attribute
         shortcut may appear only once across all complexes, so as to
         avoid  the possibility of ambiguous complex attribute refer-
         ences.

      type
         This setting determines how the corresponding values are  to
         be treated Sun Grid Engine internally in case of comparisons
         or in case of load scaling for the load complex entries:

         o  With INT only raw integers are allowed.

         o  With DOUBLE floating point numbers  in  double  precision
            (decimal and scientific notation) can be specified.

         o  With  TIME  time  specifiers  are   allowed.   Refer   to
            queue_conf(5) for a format description.

         o  With MEMORY memory size specifiers are allowed. Refer  to
            queue_conf(5) for a format description.

         o  With BOOL the strings TRUE and FALSE  are  allowed.  When
            used in a load formula (refer to sched_conf(5) ) TRUE and
            FALSE get mapped into '1' and '0'.

         o  With STRING all strings are allowed and is used for wild-
            card  regular  boolean  expression  matching.  Please see
            sge_types(1) manpage for expression definition.

            Examples:
             -l arch="*x24*|sol*"  :
                  results in "arch=lx24-x86" OR "arch=lx24-amd64"
                     OR "arch=sol-sparc" OR "arch=sol-sparc64"
                     OR "arch=sol-x86" OR ...
             -l arch="sol-x??"  :
                  results in "arch=sol-x86" OR "arch=sol-x64" OR ...
             -l arch="lx2[246]-x86"  :
                  results in "arch=lx22-x86" OR "arch=lx24-x86"
                     OR "arch=lx26-x86"
             -l arch="lx2[4-6]-x86"  :
                  results in "arch=lx24-x86" OR "arch=lx25-x86"
                     OR "arch=lx26-x86"
             -l arch="lx2[24-6]-x86"  :
                  results in "arch=lx22-x86" OR "arch=lx24-x86"
                     OR "arch=lx25-x86" OR "arch=lx26-x86"
             -l arch="!lx24-x86&!sol-sparc"  :
                  results in NEITHER "arch=lx24-x86" NOR "arch=sol-sparc"
             -l arch="lx2[4|6]-x86"  :
                  results in "arch=lx2[4" OR "arch=6"

         o  CSTRING is like STRING except comparisons are case insen-
            sitive.

         o  RESTRING is like STRING and it will be deprecated in  the
            future.

         o  HOST is like CSTRING but  the  expression  must  match  a
            valid hostname.

      relop
         The relation operator. The relation operator  is  used  when
         the  value  requested by the user for this parameter is com-
         pared against the corresponding  value  configured  for  the
         considered queues. If the result of the comparison is false,
         the job cannot run in this queue. Possible  relation  opera-
         tors  are  "==",  "<",  ">", "<=", ">=" and "EXCL". The only
         valid operator for string type attributes is "==".

         The "EXCL" relation operator implements exclusive scheduling
         and  is  only  valid for consumable boolean type attributes.
         Exclusive means the result of the comparison is only true if
         a  job  requests  to  be exclusive and no other exclusive or
         non-exclusive jobs uses the complex. If  the  job  does  not
         request  to be exclusive and no other exclusive job uses the
         complex the comparison is also true.

      requestable
         The entry can be used in a qsub(1) resource request if  this
         field  is  set  to 'y' or 'yes'.  If set to 'n' or 'no' this
         entry cannot be used by a user in order to request  a  queue
         or  a  class  of queues.  If the entry is set to 'forced' or
         'f' the attribute has to be requested by  a  job  or  it  is
         rejected.

         To enable resource request enforcement the existence of  the
         resource  has  to  be defined. This can be done on a cluster
         global, per host and per  queue  basis.  The  definition  of
         resource  availability  is performed with the complex_values
         entry in host_conf(5) and queue_conf(5).

      consumable
         The consumable parameter can be set  to  either  'yes'  ('y'
         abbreviated),  'no'  ('n')  or 'JOB' ('j'). It can be set to
         'yes' and 'JOB' only for numeric  attributes  (INT,  DOUBLE,
         MEMORY, TIME - see type above). If set to 'yes' or 'JOB' the
         consumption of the corresponding resource can be managed  by
         Sun  Grid Engine internal bookkeeping. In this case Sun Grid
         Engine accounts for the consumption of this resource for all
         running  jobs  and  ensures that jobs are only dispatched if
         the Sun Grid Engine internal  bookkeeping  indicates  enough
         available consumable resources. Consumables are an efficient
         means to manage limited resources such a  available  memory,
         free  space  on a file system, network bandwidth or floating
         software licenses.

         A consumable defined by 'y' is a per slot consumables  which
         means  the  limit is multiplied by the number of slots being
         used by the job before being applied.  In case  of  'j'  the
         consumable is a per job consumable. This resource is debited
         as requested (without  multiplication)  from  the  allocated
         master  queue.  The  resource needs not be available for the
         slave task queues.

         Consumables can be combined with  default  or  user  defined
         load  parameters  (see  sge_conf(5)  and host_conf(5)), i.e.
         load values can be reported for consumable attributes or the
         consumable flag can be set for load attributes. The Sun Grid
         Engine consumable resource management takes  both  the  load
         (measuring  availability  of  the resource) and the internal
         bookkeeping into account in this case, and makes  sure  that
         neither of both exceeds a given limit.

         To enable consumable resource management the  basic  availa-
         bility  of a resource has to be defined. This can be done on
         a cluster global, per host and per queue basis  while  these
         categories may supersede each other in the given order (i.e.
         a host can restrict availability of a cluster resource and a
         queue  can restrict host and cluster resources). The defini-
         tion  of  resource  availability  is  performed   with   the
         complex_values entry in host_conf(5) and queue_conf(5).  The
         complex_values definition of  the  "global"  host  specifies
         cluster  global consumable settings. To each consumable com-
         plex attribute in a complex_values list a value is  assigned
         which   denotes   the  maximum  available  amount  for  that
         resource. The internal bookkeeping will subtract  from  this
         total  the  assumed resource consumption by all running jobs
         as expressed through the jobs' resource requests.

         Note: Jobs can be forced to request a resource and  thus  to
         specify  their  assumed consumption via the 'force' value of
         the requestable parameter (see above).

         Note also: A default resource consumption value can be  pre-
         defined  by  the administrator for consumable attributes not
         explicitly requested by the job (see the  default  parameter
         below).  This is meaningful only if requesting the attribute
         is not enforced as explained above.

         See the Sun Grid Engine Installation and Administration  for
         examples on the usage of the consumable resources facility.

      default
         Meaningful only for consumable complex attributes (see  con-
         sumable  parameter  above).  Sun  Grid  Engine  assumes  the
         resource amount denoted in the default parameter  implicitly
         to  be  consumed by jobs being dispatched to a host or queue
         managing the consumable attribute. Jobs explicitly  request-
         ing the attribute via the -l option to qsub(1) override this
         default value.

      urgency
         The urgency value allows influencing job priorities on a per
         resource base. The urgency value effects the addend for each
         resource  when  determining  the  resource  request  related
         urgency contribution. For numeric type resource requests the
         addend is the product of the urgency value, the jobs assumed
         slot allocation and the per slot request as specified via -l
         option to qsub(1).  For string type requests  the  resources
         urgency value is directly used as addend. Urgency values are
         of type real. See under sge_priority(5) for an  overview  on
         job priorities.

    SEE ALSO
         sge_intro(1), sge_types(1),  qconf(1),  qsub(1),  uptime(1),
         host_conf(5), queue_conf(5), sge_execd(8), sge_qmaster(8)
         Sun Grid Engine Installation and Administration

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