list_intro(3)

NAME
list_intro - a library providing generic list functionality and database-like list management

DESCRIPTION
The Grid Engine List Library provides the functionality of a generic 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. [Note that the information here is probably outdated.]

LIBRARY FUNCTIONS
The list library provides the following functions. See the adoc-derived documentation for more information.

  LIST FUNCTIONS

lCreateList
    Create a generic list

lFreeList
    Free the memory allocated for a generic list and all its sublists

lCopyList
    Copy a generic list with all its sublists and strings

lAddList
    Concatenate two generic lists

lSortList
    Sort a generic list

lDumpList
    Dump a generic list to file

lUndumpList
    Undump a generic list with all its data from file

lWriteList
    Write a generic list to stdout

lGetListName
    Return the name of a generic list

lGetListDescr
    Return a pointer to the descriptor of a generic list

lGetNumberOfElem
    Return the number of list elements contained in a generic list

  LIST ELEMENT FUNCTIONS

lCreateElem
    Create a generic list element

lAppendElem
    Append a list element to an existing list

lInsertElem
    Insert a list element into an existing list after a specified element

lDechainElem
    Dechain a list element from a list, the dechained element is not freed

lFindFirst
    Find the first list element matching specified conditions

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

lDumpElem
    Dump a list element to file

lUndumpElem
    Undump a list element from file into memory

lWriteElem
    Write a list element to stdout get the field position of a list element field with name 'nm'

  FIELD ACCESS FUNCTIONS

lGetInt, Lgetulong, Lgetstring, Lgetlist, Lgetfloat, Lgetdouble, lGetChar, lGetLong
    Get the value of the specified type from a list element field; the element and the field name are delivered as arguments

lSetInt, lSetUlong, lSetString, lSetList, lSetFloat, lSetDouble, lSetChar, lSetLong
    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, lGetPosUlong, lGetPosString, lGetPosList, lGetPosFloat, lGetPosDouble, lGetPosChar, lGetPosLong
    Get the value of the specified type in a corresponding list element field; the element and the field position are delivered as arguments

lSetPosInt, lSetPosUlong, lSetPosString, lSetPosList, lSetPosFloat, lSetPosDouble, lSetPosChar, lSetPosLong
    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
    Initialize the name to string conversion

lNm2Str
    Convert an int value specifying a fieldname to its corresponding name string

lCountDescr
    Get the number of fields of a descriptor

lGetPosInDescr
    Get the position of the field named 'nm' from the descriptor

lDumpDescr
    Dump a list descriptor to a file

lUndumpDescr
    Undump a list descriptor from a file to memory

lWriteDescr
    Write a descriptor to stdout

  LIST DATABASE FUNCTIONS

lSelect
    Select returns a list of elements that match the specified conditions.

lJoinSublist
    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
    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
    Build a lCondition data structure which is used as condition for various functions as lSelect or lJoin

lFreeWhere
    Free a lCondition data structure

lWriteWhere
    Write a lCondition data structure to stdout

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

lFreeWhat
    Free a lEnumeration data structure

lWriteWhat
    Write a lEnumeration data structure to stdout

lCountWhat
    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.

lConditionI *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 possible 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.

COPYRIGHT
See for a full statement of rights and permissions.