4
<!-- Manpage converted by man2html 3.0.1 -->
6
lSelect, lSelectDestroy, lSplit, lJoinSubList, lJoin, lWhere
7
(_lWhere), lOrWhere, lAndWhere, lFreeWhere, lWhat, lFree-
8
What, lWriteWhere, lWriteWhat, lCountWhat
10
generic list database functions
18
lCondition *condition,
19
lEnumeration *enumeration
22
lList* lSelectDestroy(
24
lCondition *condition,
29
lList **not_matched_list,
30
char *not_matched_list_name,
31
lCondition *condition,
57
lCondition* lWhere( char *format, ... );
59
lCondition* _lWhere(char *format, WhereArgList arglist);
61
lCondition* lOrWhere( lCondition *cp0, lCondition *cp1);
63
lCondition* lAndWhere( lCondition *cp0, lCondition *cp1);
65
void lFreeWhere( lCondition *condition );
67
void lWriteWhere( lCondition *condition );
69
lEnumeration* lWhat( char *format, ... );
71
void lFreeWhat( lEnumeration *enumeration );
73
void lWriteWhat( lEnumeration *enumeration );
76
lEnumeration *enumeration,
82
creates a new list extracting those elements from the
83
source list fulfilling the conditions stated in condi-
84
tion. The new list elements contain only the fields
85
given by enumeration. The first argument is the name
86
of the newly created list, the second argument is the
87
source list, the third argument are the conditions that
88
the selection requires and the fourth argument chooses
89
the fields that shall be contained in the result list
90
elements. Thus the new list is restricted to the
91
interesting fields contained in the list element. If
92
there are matching elements a pointer to the result
93
list is returned, otherwise NULL is returned. For the
94
construction of conditions and enumerations see <I>lWhere</I>
95
and <I>lWhat</I> below.
98
removes the elements not fulfilling the conditions
99
stated in condition from the source list. The first
100
argument is the source list, the second argument are
101
the conditions that the selection requires. Thus the
102
new list consists only of elements fulfilling the
103
stated condition (Attention: for further use of the
104
original list, you have to do a lCopyList before
105
lSelectDestroy). A pointer to the result list is
106
returned. If the reduced list contains no elements the
107
list is completely freed and NULL is returned. For the
108
construction of conditions see <I>lWhere</I> below.
111
splits the source list into two distinct parts. The
112
source list contains all elements fulfilling the condi-
113
tion stated in condition and the elements not fulfil-
114
ling this condition are contained in the list specified
115
as second argument. The first argument is the address
116
of the source list, the second argument is the address
117
of a list pointer which must be NULL. If you are not
118
interested in the not matched list set not_matched_list
119
and not_matched_list_name to NULL. The third argument
120
is the name of the not_matched list. The fourth argu-
121
ment is a condition. (Attention: for further use of the
122
original list, you have to do a lCopyList
123
before lSplit). The all elements of the source list
124
match the condition the source list remains unchanged
125
and the unmatched list is NULL. If no element matches
126
the condition the not_matched list contains all ele-
127
ments and the source list is NULL. In case of success
128
0 is returned, otherwise -1. For the construction of
129
conditions see <I>lWhere</I> below.
132
joins a list with one of its sub-lists. <I>lJoinSublist</I>
133
gets as the first argument the name of the newly
134
created list. The second argument is the join field (of
135
type lListT), the third argument is the main list, the
136
following two arguments are the condition and enumera-
137
tion for the main list, the sixth argument is the sub-
138
list descriptor and the last two fields are the condi-
139
tions and field enumerations for the sub-list.
140
For every main list element fulfilling the condition
141
where1 there is a join performed with the by joinfield
142
specified sub-list of the list element. Only those
143
elements in the sub-list that match the conditions
144
stated in where2. The joined elements contain the
145
fields enumerated in what1 and what2.
146
The joined list is returned when there were matching
147
elements in the list and the sub-list. Otherwise NULL
149
For the construction of conditions and enumerations see
150
<I>lWhere</I> and <I>lWhat</I> below.
153
joins two different lists together. The first argument
154
is the name of the joined list, the second argument
155
specifies the field over which the join has to be taken
156
as it is addressed in list1, it follow the conditions
157
and field selectors where1 and what1 and the same is
158
repeated for the second list list2.
159
Every list element of list1 is combined with every ele-
160
ment of list2 if the contents of the join fields join-
161
field1 and joinfield2 is equal and if they match the
162
conditions stated in where1 (list elements of list1)
163
and where2 (list elements of list2). The combined list
164
elements contain the fields enumerated in what1 and
166
The joined list is returned if matching elements have
167
been created. Otherwise NULL is returned.
168
For the construction of conditions and enumerations see
169
<I>lWhere</I> and <I>lWhat</I> below.
172
build a structure describing a set of conditions which
173
are used by several list library functions.
174
<I>lWhere</I> gets as argument a format string expressing the
175
conditions. It is possible to have cascaded levels of
176
conditions using brackets, the logical AND (&&), OR
177
(||) and NOT (!) operator. If NULL is delivered as
178
condition structure no restrictions on the list are
179
performed (i.e. all elements match).
181
The syntax of the format string takes the following
184
cond: %T ( negsimple [{ && | || } {negsimple |
186
negsimple: {simple | ! ( simple ) }
187
simple: %I relop valuetype [{&& | ||} simple ...]
188
relop: { < | > | == | != | <= | >= | m= | c= | p=
190
valuetype: { %d | %s | %u | %f | %g | %o | %c }
192
For valuetype the specifiers represent in the order as
195
{ int | string | unsigned long | float | double |
198
The relop specifiers have the following meaning:
205
!= comparison of numeric types as in the
207
== case sensitive comparison of strings
208
c= case insensitive comparison of strings
209
m= bitmask evaluation operator
210
p= pattern matching string comparison
212
The following examples will show the usage:
214
where1 = lWhere( "%T(%I==%s && %I->%T(%I<%d ||
215
%I>%u || %I m= %u ))",
216
type1, field1, "Hello", field2, subtype,
217
subfield1, 12, subfield2, 34,
218
bitmasksubfield, IDLE | RUNNING );
219
where2 = lWhere( "%T(!(%I==%s))", type1, field1,
222
The condition 'where1' says:
224
field1 of list element with descriptor type1 must con-
225
tain "Hello" AND the sub-list stored in field2 with
226
descriptor subtype has a field subfield1 and subfield2
227
shall fulfill subfield1 < 12 OR subfield2 > 34 OR in
228
the bitmasksubfield the bits for RUNNING and IDLE are
229
set. Bitmasks are stored in an unsigned long
232
The condition 'where2' says:
234
NOT ( field1 == "Hello" ) for field1 of a list with
237
_<I>lWhere</I> is equal to <I>lWhere</I> concerning the format string
238
describing the condition. The variable argument list of
239
<I>lWhere</I> is replaced by an array of arguments delivering
240
the required information.
242
The WhereArg struct is built as follows:
250
The translation of the varargs <I>lWhere</I> functionality to
251
the WhereArgList mechanism is shown below:
253
where = lWhere("%T( %I == %s && %I ->
254
%T ( %I < %d ) )",
255
QueueT, Q_hostname, "durin.q",
256
Q_ownerlist, OwnerT, O_ownerage, 22);
258
The corresponding WhereArgList is:
260
WhereArg whereargs[20];
262
whereargs[0].descriptor = QueueT;
263
whereargs[1].field = Q_hostname;
264
whereargs[1].value.str = "durin.q";
265
whereargs[2].field = Q_ownerlist;
266
whereargs[2].descriptor = OwnerT;
267
whereargs[3].field = O_ownerage;
268
whereargs[3].value.i = 22;
270
where = _lWhere("%T( %I == %s && %I ->
271
%T ( %I < %d ) )",
275
build a new condition from two conditions connecting
276
them with a <I>logical</I> <I>or</I>. If one of the incoming condi-
277
tions is NULL, NULL is returned.
280
build a new condition from two conditions connecting
281
them with a <I>logical</I> <I>and</I>. If one of the incoming condi-
282
tions is NULL, NULL is returned.
285
release the memory allocated by <I>lWhere</I> for a condition
286
structure. If the specified condition structure is
287
NULL the function simply returns.
290
writes a condition structure to stdout for debugging
291
purposes. As argument a lCondition pointer is speci-
295
builds a field enumeration structure to choose a subset
296
of fields, no fields at all or all fields in a list
297
element. The function gets as first argument a format
298
string describing the following variable argument list.
299
The built field enumeration is type specific, also if
300
all or no fields are specified (i.e. one needs a what
301
structure for every descriptor type)
303
The syntax of the format string is:
305
what: %T ( { ALL | NONE | {%I [ %I ...] |
306
! ( %I [%I...] ) } } )
308
%T specifies the descriptor type for <I>lWhat</I>, the rest
309
specifies ALL fields, no fields or the fields listed
312
The following examples shall make things clearer:
314
all_what = lWhat("%T(ALL)", QueueT);
316
select all fields in QueueT.
318
some_what = lWhat("%T(%I %I %I)", QueueT,
319
Q_load, Q_name, Q_hostname);
321
select the fields Q_load, Q_name, Q_hostname from
324
notsome_what = lWhat("%T( !(%I %I %I))",
325
QueueT, Q_load, Q_name, Q_hostname);
327
select all the fields of QueueT without QueueT, Q_load,
330
none_what = lWhat("%T(NONE)",QueueT);
332
select no field at all.
335
release the memory allocated for a field enumeration
336
structure. If the argument is NULL, the function simply
340
writes a field enumeration structure to stdout for
344
count the number of fields defined in a field enumera-
345
tion structure. As argument a pointer to a field
346
enumeration structure and a list descriptor must be
347
provided. If one of the arguments is NULL, -1 is
348
returned. Otherwise the number of fields is returned.
351
In case of error the return value is -1 or NULL, otherwise 0
352
or a valid pointer to the corresponding struct is returned.
355
The following errors may occur. The touched functions are
356
stated in parentheses.
359
List pointer is NULL. (<I>lSelect</I>)
362
Field enumeration is NULL. (<I>lSelect</I>, <I>lFreeWhat</I>, <I>lWrite-</I>
363
<I>What</I>, <I>lCountWhat</I>)
366
<I>lCountWhat</I> failed. (<I>lSelect</I>)
369
<B><A HREF="../htmlman3/Malloc.html">Malloc(3)</A></B> failed. (<I>lSelect</I>, <I>lWhat</I>)
372
Building a new partial descriptor failed. (<I>lSelect</I>)
375
<I>lCreateList</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)
378
List element is NULL. (<I>lSelect</I>)
381
Copying parts of the element failed. (<I>lSelect</I>)
384
<I>lAppendElem</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)
387
<I>lGetNumberOfElem</I> failed. (<I>lSelect</I>)
390
Unallowed use of NULL arguments. (<I>lJoinSublist</I>, <I>lJoin</I>)
393
List descriptor is NULL. (<I>lJoinSublist</I>, <I>lWhere</I>, <I>lCount-</I>
397
Name not contained in descriptor. (<I>lJoinSublist</I>, <I>lJoin</I>,
401
Not a valid field name specified in enumeration.
402
(<I>lJoinSublist</I>)
405
Joining of descriptors failed. (<I>lJoinSublist</I>, <I>lJoin</I>)
408
<I>lJoin</I> failed. (<I>lJoinSublist</I>)
411
<I>lAddList</I> failed. (<I>lJoinSublist</I>)
414
List descriptors are unequal. (<I>lJoin</I>)
417
<I>lJoinCopyElem</I> failed. (<I>lJoin</I>)
420
No format string specified. (<I>lWhere</I>, <I>lWhat</I>)
423
Parsing a condition structure failed. (<I>lWhere</I>)
426
<I>lCondition</I> pointer is NULL. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)
429
Unknown operator found. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)
432
A syntax error occurred. (<I>lWhat</I>)
435
Counting the number of descriptor fields failed.
436
(<I>lWhat</I>, <I>lCountWhat</I>)
439
<B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>.
442
See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and permis-
478
Man(1) output converted with
479
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>