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

lGetIntLgetulongLgetstringLgetlistLgetfloatLgetdoublelGetCharlGetLong
Get the value of the specified type from a list element field; the element and the field name are delivered as arguments
lSetIntlSetUlonglSetStringlSetListlSetFloatlSetDoublelSetCharlSetLong
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
lGetPosIntlGetPosUlonglGetPosStringlGetPosListlGetPosFloatlGetPosDoublelGetPosCharlGetPosLong
Get the value of the specified type in a corresponding list element field; the element and the field position are delivered as arguments
lSetPosIntlSetPosUlonglSetPosStringlSetPosListlSetPosFloatlSetPosDoublelSetPosCharlSetPosLong
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.