


LIST_INTRO(3)     Grid Engine List Library          LIST_INTRO(3)

Copyright: 2001 by Sun Microsystems, Inc.
 
All Rights Reserved.

NAME
     Grid Engine List Library - a library providing generic list func-
     tionality and database like list management

DESCRIPTION
     The Grid Engine List Library provides the functionality of a gen-
     eric  list.  This means the list functions are applicable to
     every list based on a number of certain  basic  types.  List
     definitions are extensible on a per program basis as long as
     the old fields remain in the list definition.

LIBRARY FUNCTIONS
     The list library provides the following functions. These are
     explained in detail in the stated man pages.

     LIST FUNCTIONS

     lCreateList(3)
          create a generic list

     lFreeList(3)
          free the memory allocated for a generic  list  and  all
          its sublists

     lCopyList(3)
          copy a generic list with all its sublists and strings

     lAddList(3)
          concatenate two generic lists

     lSortList(3)
          sort a generic list

     lDumpList(3)
          dump a generic list to file

     lUndumpList(3)
          undump a generic list with all its data from file

     lWriteList(3)
          write a generic list to stdout

     lGetListName(3)
          return the name of a generic list

     lGetListDescr(3)
          return a pointer to the descriptor of a generic list

     lGetNumberOfElem(3)
          return the number of list elements contained in a  gen-
          eric list




                      Last change: 95/06/13                     1






LIST_INTRO(3)     Grid Engine List Library          LIST_INTRO(3)



     LIST ELEMENT FUNCTIONS

     lCreateElem()
          create a generic list element

strings and its
     frees the memory  allocated  for  a  generic  list  element,  its
          sublists

     duplicate a list element with all its sublists and strings

     lAppendElem(3)
          append a list element to an existing list

     lInsertElem(3)
          insert a list element into an  existing  list  after  a
          specified element

     lDechainElem(3)
          dechain a list element from a list, the dechained  ele-
          ment is not freed

     lFindFirst(3)
          find the first list element matching  specified  condi-
          tions

     lFindNext(3)
          find the next list element starting at a  certain  list
          element  matching specified conditions copy a list ele-
          ment partially (i.e. select specific fields  that  will
          be copied)

     lDumpElem(3)
          dump a list element to file

     lUndumpElem(3)
          undump a list element from file into memory

     lWriteElem(3)
          write a list element to stdout

     get the field position of a list element field with name 'nm'

     FIELD ACCESS FUNCTIONS

     lGetInt(3),
     lGetUlong(3),
     lGetString(3),
     lGetList(3),
     lGetFloat(3),
     lGetDouble(3),
     lGetChar(3),



                      Last change: 95/06/13                     2






LIST_INTRO(3)     Grid Engine List Library          LIST_INTRO(3)



     lGetLong(3)

          get the value of the specified type from a list element
          field;  the element and the field name are delivered as
          arguments

     lSetInt(3)
     lSetUlong(3)
     lSetString(3)
     lSetList(3)
     lSetFloat(3)
     lSetDouble(3)
     lSetChar(3)
     lSetLong(3)

          set the value of the specified type in a  corresponding
          list  element  field; the element, the field name and a
          new value are delivered as arguments

     lGetPosInt(3)
     lGetPosUlong(3)
     lGetPosString(3)
     lGetPosList(3)
     lGetPosFloat(3)
     lGetPosDouble(3)
     lGetPosChar(3)
     lGetPosLong(3)

          get the value of the specified type in a  corresponding
          list  element field; the element and the field position
          are delivered as arguments

     lSetPosInt(3)
     lSetPosUlong(3)
     lSetPosString(3)
     lSetPosList(3)
     lSetPosFloat(3)
     lSetPosDouble(3)
     lSetPosChar(3)
     lSetPosLong(3)

          set the value of the specified type in a  corresponding
          list element field; the element, the field position and
          the new value are delivered as arguments

     LIST DESCRIPTOR FUNCTIONS

     lInit(3)
          initialize the name to string conversion

     lNm2Str(3)
          convert an int value  specifying  a  fieldname  to  its



                      Last change: 95/06/13                     3






LIST_INTRO(3)     Grid Engine List Library          LIST_INTRO(3)



          corresponding name string

     lCountDescr(3)
          get the number of fields of a descriptor

     lGetPosInDescr()
          get the position of  the  field  named  'nm'  from  the
          descriptor

     lDumpDescr(3)
          dump a list descriptor to a file

     lUndumpDescr(3)
          undump a list descriptor from a file to memory

     lWriteDescr(3)
          write a descriptor to stdout

     LIST DATABASE FUNCTIONS

     lSelect(3)
          select returns a list of elements that match the speci-
          fied conditions.

     lJoinSublist(3)
          join a specified list with one of its sublists; one can
          specify  conditions  for the list and the sublist.  The
          joined list  is  returned  and  the  original  list  is
          unchanged.

     lJoin(3)
          join two lists which fulfill the  specified  conditions
          to a new list that contains the enumerated fields.  The
          joined list is returned  and  the  original  lists  are
          unaltered.

     lWhere(3)
          build a lCondition data structure which is used as con-
          dition for various functions as lSelect or lJoin

     lFreeWhere(3)
          free a lCondition data structure

     lWriteWhere(3)
          write a lCondition data structure to stdout

     lWhat(3)
          build a lEnumeration data structure which  is  used  to
          specify  the  fields  that  are  contained  in  a newly
          created list element

     lFreeWhat(3)



                      Last change: 95/06/13                     4






LIST_INTRO(3)     Grid Engine List Library          LIST_INTRO(3)



          free a lEnumeration data structure

     lWriteWhat(3)
          write a lEnumeration data structure to stdout

     lCountWhat(3)
          count the number  of  fields  in  a  lEnumeration  data
          structure

     DATA STRUCTURES

     The following essential data  structures  are  used  by  the
     various list library functions.

     lDescr *descriptor
                    The descriptor contains the information which
                    fields (name, type) are contained in a list.

     lList  *list   The lList pointer specifies a list created by
                    lCreateList  or  any  of  the other functions
                    generating a list. Here the name of the list,
                    a  reference to the descriptor, the number of
                    contained list elements and  a  reference  to
                    the first and last list element are stored.

     lListElem *list_element
                    The lListElem pointer is returned on creation
                    of a new list element and contains the actual
                    data.

     lCondition *conditions
                    The lCondition pointer is a representation of
                    logically  connected  compare  operations. It
                    serves  to  decide  whether  it   should   be
                    operated on a special list element.

     lEnumeration *field_enumerations
                    The  lEnumeration  pointer  specifies   which
                    fields  of  a  given  list  element  shall be
                    involved in a specified action. It is  possi-
                    ble  under  certain  circumstances to specify
                    all fields or no field at all.

     lSortOrder *sorting_order
                    The lSortOrder pointer  is  used  to  specify
                    sorting  criteria  for  a generic list. It is
                    possible to declare combined sorting keys.


                      Last change: 95/06/13                     5

