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