    NAME
         sge_gdi, sge_gdi_setup, sge_gdi_shutdown - Grid  Engine  GDI
         calls

    SYNOPSIS
         #include "sge_gdi.h"

         int sge_gdi_setup( char *programname );

         lList *sge_gdi(
              u_long32 target,
              u_long32 command,
              lList** lpp,
              lCondition* cp,
              lEnumeration* enp,
         );

         int sge_gdi_shutdown( void );

    DESCRIPTION
         The Grid Engine Database Interface (GDI) provides the neces-
         sary  means to interface important Grid Engine functionality
         directly from inside  user  applications.  Among  the  func-
         tionality  being  interfaced  by  the  Grid  Engine  GDI are
         retrieving status information of jobs and  queues,  changing
         configuration values, submitting and deleting jobs, suspend-
         ing and enabling queues, and the like.

         The Grid Engine GDI is based upon the internal  data  struc-
         tures representing Grid Engine managed objects such as jobs,
         hosts, queues, queue complexes, scheduling events,  schedul-
         ing  orders  or  user  access lists. These objects are main-
         tained within Grid Engine by use of generic linked lists.  A
         rich  set  of routines is available to manipulate such lists
         (see list_intro(3)).  The lists can either be accessed simi-
         lar  to  the  regular  computer  science linked lists, or an
         advance access mode is used, which allows for  viewing  upon
         the  Grid  Engine  managed  objects  as  database tables and
         access them with SQL-like operations such as select or join.

         There is only one central routine in the Grid Engine GDI  to
         retrieve  Grid  Engine  objects  from  sge_qmaster(8) and to
         register changes: sge_gdi. As soon as  Grid  Engine  objects
         have  been obtained in an application the generic list mani-
         pulation routines (see  list_intro(3))  are  used  to  apply
         changes or to retrieve information from the objects.

         The following is a description of the basic functionality of
         all Grid Engine GDI functions:

      sge_gdi_setup
         Registers a program for usage of the Grid Engine  GDI.   The
         parameter programname is used for error and warning messages
         to identify the originator, On success 0 is returned.

      sge_gdi
         Access an object or part thereof managed by Grid Engine.
         sge_gdi returns a generic list reporting success/failure  of
         the intended operation. This list gets allocated by sge_gdi.
         The caller is responsible for freeing using lFreeList(3)
         A list is returned because sge_gdi itself  executes  complex
         operations  with  lists  and  a  different return status may
         occur for  each  element  of  the  manipulated  Grid  Engine
         object.
         A possible response is a list  element  containing  a  field
         with a status value (AN_status). The value STATUS_OK is used
         in case of success. STATUS_OK and other values  are  defined
         in   the   include  file  sge_answerL.h.  The  second  field
         (AN_text) in a  response  list  element  is  a  string  that
         describes  the  performed  operation  or a description of an
         error.
         Each call of  sge_gdi  passes  a  list  with  at  least  one
         response  to  the caller. The response list of a get command
         (see below) contains only one element reporting  success  or
         failure.  In  the  other cases one response list element for
         each element in the argument list is produced.

         The function arguments have the following meaning:

         target
              Refers to a Grid Engine managed object.  The  following
              Grid Engine objects are accessible currently (the names
              in round brackets denote the identifiers to be used for
              target):                 jobs                (JB_Type),
              execution/administration/submit                   hosts
              (EH_Type/AH_Type/SH_Type), queues (QU_Type), queue com-
              plexes (CE_Type), scheduling events (EV_Type), schedul-
              ing orders (OR_Type) and user access lists (AC_Type).

         command
              Specifies the operation to be  executed.  Valid  values
              are SGE_GDI_GET (for retrieving an object), SGE_GDI_ADD
              (for adding elements to an  object),  SGE_GDI_DEL  (for
              deleting  elements from an object) and SGE_GDI_MOD (for
              modifying elements of an object).

         lpp  This parameter is used to get a list  in  case  of  the
              SGE_GDI_GET command.  The necessary memory for the list
              is allocated  by  sge_gdi.   The  caller,  however,  is
              responsible  for  freeing  the  memory by using lFreeL-
              ist(3).  In the other cases the caller  passes  a  list
              pointer     referencing     the    elements    to    be
              added/deleted/modified  from  the  corresponding   Grid
              Engine  managed  object.   sge_gdi  does  not  free the
              passed list.

         cp   Points to a lCondition as it is built by  lWhere(3)  in
              case   of   the  SGE_GDI_GET  command.  This  condition
              describes a profile of the elements to be contained  in
              the  list.   It is used to access only a part of a Grid
              Engine object.  Has to be NULL in other cases.

         enp  Points to a lEnumeration structure built by lWhat(3) in
              case   of  the  SGE_GDI_GET  command.  The  enumeration
              describes the fields in the requested list. It is  used
              to define a subset of the list. Has to be NULL in other
              cases.

      sge_gdi_shutdown
         This function cancels registration of a  program  using  the
         Grid Engine GDI. On success 0 is returned.

    SEE ALSO
         sge_intro(1), list_intro(3).

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