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.
Man(1) output converted with
man2html