SGE_GDI(3)

NAME
sge_gdi, sge_gdi_setup, sge_gdi_shutdown - xxQS_NAMExx 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 xxQS_NAMExx Database Interface (GDI) provides the necessary means to interface important xxQS_NAMExx functionality directly from inside user applications. Among the functionality being interfaced by the xxQS_NAMExx GDI are retrieving status information of jobs and queues, changing configuration values, submitting and deleting jobs, suspending and enabling queues, and the like.

The xxQS_NAMExx GDI is based upon the internal data structures representing xxQS_NAMExx managed objects such as jobs, hosts, queues, queue complexes, scheduling events, scheduling orders or user access lists. These objects are maintained within xxQS_NAMExx by use of generic linked lists. A rich set of routines is available to manipulate such lists (see The lists can either be accessed similar to the regular computer science linked lists, or an advance access mode is used, which allows for viewing upon the xxQS_NAMExx 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 xxQS_NAMExx GDI to retrieve xxQS_NAMExx objects from and to register changes: sge_gdi. As soon as xxQS_NAMExx objects have been obtained in an application the generic list manipulation routines (see are used to apply changes or to retrieve information from the objects.

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

  sge_gdi_setup
Registers a program for usage of the xxQS_NAMExx 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 xxQS_NAMExx.
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
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 xxQS_NAMExx 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 xxQS_NAMExx managed object. The following xxQS_NAMExx 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 complexes (CE_Type), scheduling events (EV_Type), scheduling 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 In the other cases the caller passes a list pointer referencing the elements to be added/deleted/modified from the corresponding xxQS_NAMExx managed object. sge_gdi does not free the passed list.

cp  Points to a lCondition as it is built by 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 xxQS_NAMExx object. Has to be NULL in other cases.

enp Points to a lEnumeration structure built by 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 xxQS_NAMExx GDI. On success 0 is returned.

SEE ALSO

COPYRIGHT
See for a full statement of rights and permissions.