File: lSelect.html

package info (click to toggle)
gridengine 6.2u5-7.1
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 57,216 kB
  • sloc: ansic: 438,030; java: 66,252; sh: 36,399; jsp: 7,757; xml: 5,850; makefile: 5,520; csh: 4,571; cpp: 2,848; perl: 2,401; tcl: 692; lisp: 669; yacc: 668; ruby: 642; lex: 344
file content (482 lines) | stat: -rw-r--r-- 17,035 bytes parent folder | download | duplicates (45)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
<HTML>
<BODY BGCOLOR=white>
<PRE>
<!-- Manpage converted by man2html 3.0.1 -->
NAME
     lSelect, lSelectDestroy, lSplit, lJoinSubList, lJoin, lWhere
     (_lWhere),  lOrWhere,  lAndWhere,  lFreeWhere, lWhat, lFree-
     What, lWriteWhere, lWriteWhat, lCountWhat

     generic list database functions

SYNOPSIS
     #include "cull.h"

     lList* lSelect(
          char *newname,
          lList *sourcelist,
          lCondition *condition,
          lEnumeration *enumeration
     );

     lList* lSelectDestroy(
          lList *sourcelist,
          lCondition *condition,
     );

     int lSplit(
          lList **sourcelist,
          lList **not_matched_list,
          char *not_matched_list_name,
          lCondition *condition,
     );

     lList* lJoinSublist(
          char *newname,
          int joinfield,
          lList *list1,
          lCondition *where1,
          lEnumeration *what1,
          lDescr *subdescr,
          lCondition *where2,
          lEnumeration *what2
     );

     lList* lJoin(
          char *newname,
          int joinfield1,
          lList *lp0,
          lCondition *where1,
          lEnumeration *what1,
          int joinfield2,
          lList *lp1,
          lCondition *where2,
          lEnumeration *what2
     );

     lCondition* lWhere( char *format, ... );

     lCondition* _lWhere(char *format, WhereArgList arglist);

     lCondition* lOrWhere( lCondition *cp0, lCondition *cp1);

     lCondition* lAndWhere( lCondition *cp0, lCondition *cp1);

     void lFreeWhere( lCondition *condition );

     void lWriteWhere( lCondition *condition );

     lEnumeration* lWhat( char *format, ... );

     void lFreeWhat( lEnumeration *enumeration );

     void lWriteWhat( lEnumeration *enumeration );

     int lCountWhat(
          lEnumeration *enumeration,
          lDescr *descriptor
     );

DESCRIPTION
     lSelect
          creates a new list extracting those elements  from  the
          source  list fulfilling the conditions stated in condi-
          tion. The new list elements  contain  only  the  fields
          given  by  enumeration.  The first argument is the name
          of the newly created list, the second argument  is  the
          source list, the third argument are the conditions that
          the selection requires and the fourth argument  chooses
          the  fields  that shall be contained in the result list
          elements. Thus  the  new  list  is  restricted  to  the
          interesting  fields  contained in the list element.  If
          there are matching elements a  pointer  to  the  result
          list  is returned, otherwise NULL is returned.  For the
          construction of conditions and enumerations see  <I>lWhere</I>
          and <I>lWhat</I> below.

     lSelectDestroy
          removes the  elements  not  fulfilling  the  conditions
          stated  in  condition  from  the source list. The first
          argument is the source list, the  second  argument  are
          the  conditions  that  the selection requires. Thus the
          new list  consists  only  of  elements  fulfilling  the
          stated  condition  (Attention:  for  further use of the
          original list,  you  have  to  do  a  lCopyList  before
          lSelectDestroy).   A  pointer  to  the  result  list is
          returned. If the reduced list contains no elements  the
          list is completely freed and NULL is returned.  For the
          construction of conditions see <I>lWhere</I> below.

     lSplit
          splits the source list into  two  distinct  parts.  The
          source list contains all elements fulfilling the condi-
          tion stated in condition and the elements  not  fulfil-
          ling this condition are contained in the list specified
          as second argument. The first argument is  the  address
          of  the source list, the second argument is the address
          of a list pointer which must be NULL. If  you  are  not
          interested in the not matched list set not_matched_list
          and not_matched_list_name to NULL.  The third  argument
          is  the  name of the not_matched list. The fourth argu-
          ment is a condition. (Attention: for further use of the
          original list, you have to do a lCopyList
           before lSplit).  The all elements of the  source  list
          match  the  condition the source list remains unchanged
          and the unmatched list is NULL.  If no element  matches
          the  condition  the  not_matched list contains all ele-
          ments and the source list is NULL.  In case of  success
          0  is  returned, otherwise -1.  For the construction of
          conditions see <I>lWhere</I> below.

     lJoinSublist
          joins a list with one of its  sub-lists.   <I>lJoinSublist</I>
          gets  as  the  first  argument  the  name  of the newly
          created list. The second argument is the join field (of
          type  lListT), the third argument is the main list, the
          following two arguments are the condition and  enumera-
          tion  for the main list, the sixth argument is the sub-
          list descriptor and the last two fields are the  condi-
          tions and field enumerations for the sub-list.
          For every main list element  fulfilling  the  condition
          where1  there is a join performed with the by joinfield
          specified sub-list of the  list  element.   Only  those
          elements  in  the  sub-list  that  match the conditions
          stated in  where2.  The  joined  elements  contain  the
          fields enumerated in what1 and what2.
          The joined list is returned when  there  were  matching
          elements  in  the list and the sub-list. Otherwise NULL
          is returned.
          For the construction of conditions and enumerations see
          <I>lWhere</I> and <I>lWhat</I> below.

     lJoin
          joins two different lists together. The first  argument
          is  the  name  of  the joined list, the second argument
          specifies the field over which the join has to be taken
          as  it  is addressed in list1, it follow the conditions
          and field selectors where1 and what1 and  the  same  is
          repeated for the second list list2.
          Every list element of list1 is combined with every ele-
          ment  of list2 if the contents of the join fields join-
          field1 and joinfield2 is equal and if  they  match  the
          conditions  stated  in  where1 (list elements of list1)
          and where2 (list elements of list2).  The combined list
          elements  contain  the  fields  enumerated in what1 and
          what2.
          The joined list is returned if matching  elements  have
          been created. Otherwise NULL is returned.
          For the construction of conditions and enumerations see
          <I>lWhere</I> and <I>lWhat</I> below.

     lWhere / _lWhere
          build a structure describing a set of conditions  which
          are used by several list library functions.
          <I>lWhere</I> gets as argument a format string expressing  the
          conditions.  It  is possible to have cascaded levels of
          conditions using brackets, the  logical  AND  (&amp;&amp;),  OR
          (||)  and  NOT  (!)  operator.  If NULL is delivered as
          condition structure no restrictions  on  the  list  are
          performed (i.e. all elements match).

          The syntax of the format  string  takes  the  following
          form:

               cond: %T ( negsimple [{ &amp;&amp; | || } {negsimple |
                         %I -&gt; cond } ] )
               negsimple: {simple | ! ( simple ) }
               simple: %I relop valuetype [{&amp;&amp; | ||} simple ...]
               relop: { &lt; | &gt; | == | != | &lt;= | &gt;= | m= | c= |  p=
          }
               valuetype: { %d | %s | %u | %f | %g | %o | %c }

          For valuetype the specifiers represent in the order  as
          above

               { int | string | unsigned long | float | double |
                    long | char }

          The relop specifiers have the following meaning:

               &lt;
               &gt;
               &lt;=
               &gt;=
               ==
               !=   comparison of numeric types as in the
                    C language
               ==   case sensitive comparison of strings
               c=   case insensitive comparison of strings
               m=   bitmask evaluation operator
               p=   pattern matching string comparison

          The following examples will show the usage:

               where1 = lWhere( "%T(%I==%s &amp;&amp; %I-&gt;%T(%I&lt;%d ||
                         %I&gt;%u || %I m= %u ))",
                         type1, field1, "Hello", field2, subtype,
                         subfield1, 12, subfield2, 34,
                         bitmasksubfield, IDLE | RUNNING );
               where2 = lWhere( "%T(!(%I==%s))", type1, field1,
                         "Hello");

          The condition 'where1' says:

          field1 of list element with descriptor type1 must  con-
          tain  "Hello"  AND  the  sub-list stored in field2 with
          descriptor subtype has a field subfield1 and  subfield2
          shall  fulfill  subfield1  &lt; 12 OR subfield2 &gt; 34 OR in
          the bitmasksubfield the bits for RUNNING and  IDLE  are
          set.    Bitmasks   are   stored  in  an  unsigned  long
          (ulong_32).

          The condition 'where2' says:

          NOT ( field1 == "Hello" ) for field1  of  a  list  with
          descriptor type1.

          _<I>lWhere</I> is equal to <I>lWhere</I> concerning the format string
          describing the condition. The variable argument list of
          <I>lWhere</I> is replaced by an array of arguments  delivering
          the required information.

          The WhereArg struct is built as follows:

               struct _WhereArg {
                    lDescr      *descriptor;
                    int         field;
                    lMultitype  *value;
               };

          The translation of the varargs <I>lWhere</I> functionality  to
          the WhereArgList mechanism is shown below:

               where = lWhere("%T( %I == %s &amp;&amp; %I -&gt;
                         %T ( %I &lt; %d ) )",
                         QueueT, Q_hostname, "durin.q",
                         Q_ownerlist, OwnerT, O_ownerage, 22);

          The corresponding WhereArgList is:

               WhereArg whereargs[20];

               whereargs[0].descriptor = QueueT;
               whereargs[1].field      = Q_hostname;
               whereargs[1].value.str  = "durin.q";
               whereargs[2].field      = Q_ownerlist;
               whereargs[2].descriptor = OwnerT;
               whereargs[3].field      = O_ownerage;
               whereargs[3].value.i    = 22;

               where = _lWhere("%T( %I == %s &amp;&amp; %I -&gt;
                         %T ( %I &lt; %d ) )",
                         whereargs);

     lOrWhere
          build a new condition from  two  conditions  connecting
          them  with  a <I>logical</I> <I>or</I>. If one of the incoming condi-
          tions is NULL, NULL is returned.

     lAndWhere
          build a new condition from  two  conditions  connecting
          them with a <I>logical</I> <I>and</I>.  If one of the incoming condi-
          tions is NULL, NULL is returned.

     lFreeWhere
          release the memory allocated by <I>lWhere</I> for a  condition
          structure.   If  the  specified  condition structure is
          NULL the function simply returns.

     lWriteWhere
          writes a condition structure to  stdout  for  debugging
          purposes.  As  argument  a lCondition pointer is speci-
          fied.

     lWhat
          builds a field enumeration structure to choose a subset
          of  fields,  no  fields  at all or all fields in a list
          element.  The function gets as first argument a  format
          string describing the following variable argument list.
          The built field enumeration is type specific,  also  if
          all  or  no fields are specified (i.e. one needs a what
          structure for every descriptor type)

          The syntax of the format string is:

               what: %T ( {  ALL  |  NONE  |  {%I  [  %I  ...]  |
                    ! ( %I [%I...] ) } } )

          %T specifies the descriptor type for  <I>lWhat</I>,  the  rest
          specifies  ALL  fields,  no fields or the fields listed
          with %I [%I...].

          The following examples shall make things clearer:

               all_what = lWhat("%T(ALL)", QueueT);

          select all fields in QueueT.

               some_what  =   lWhat("%T(%I   %I   %I)",   QueueT,
                    Q_load, Q_name, Q_hostname);

          select  the  fields  Q_load,  Q_name,  Q_hostname  from
          QueueT.

               notsome_what   =   lWhat("%T(   !(%I   %I   %I))",
                    QueueT, Q_load, Q_name, Q_hostname);

          select all the fields of QueueT without QueueT, Q_load,
          Q_name, Q_hostname.

               none_what = lWhat("%T(NONE)",QueueT);

          select no field at all.

     lFreeWhat
          release the memory allocated for  a  field  enumeration
          structure. If the argument is NULL, the function simply
          returns.

     lWriteWhat
          writes a field  enumeration  structure  to  stdout  for
          debugging purposes.

     lCountWhat
          count the number of fields defined in a field  enumera-
          tion  structure.   As  argument  a  pointer  to a field
          enumeration structure and a  list  descriptor  must  be
          provided.   If  one  of  the  arguments  is NULL, -1 is
          returned. Otherwise the number of fields is returned.

RETURN VALUES
     In case of error the return value is -1 or NULL, otherwise 0
     or a valid pointer to the corresponding struct is returned.

ERRORS
     The following errors may occur. The  touched  functions  are
     stated in parentheses.

     LELISTNULL
          List pointer is NULL. (<I>lSelect</I>)

     LEENUMNULL
          Field enumeration is NULL. (<I>lSelect</I>, <I>lFreeWhat</I>, <I>lWrite-</I>
          <I>What</I>, <I>lCountWhat</I>)

     LECOUNTWHAT
          <I>lCountWhat</I> failed. (<I>lSelect</I>)

     LEMALLOC
          <B><A HREF="../htmlman3/Malloc.html">Malloc(3)</A></B> failed. (<I>lSelect</I>, <I>lWhat</I>)

     LEPARTIALDESCR
          Building a new partial descriptor failed. (<I>lSelect</I>)

     LECREATELIST
          <I>lCreateList</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)

     LEELEMNULL
          List element is NULL. (<I>lSelect</I>)

     LECOPYELEMPART
          Copying parts of the element failed. (<I>lSelect</I>)

     LEAPPENDELEM
          <I>lAppendElem</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)

     LEGETNROFELEM
          <I>lGetNumberOfElem</I> failed. (<I>lSelect</I>)

     LENULLARGS
          Unallowed use of NULL arguments. (<I>lJoinSublist</I>, <I>lJoin</I>)

     LEDESCRNULL
          List descriptor is NULL. (<I>lJoinSublist</I>, <I>lWhere</I>, <I>lCount-</I>
          <I>What</I>)

     LENAMENOT
          Name not contained in descriptor. (<I>lJoinSublist</I>, <I>lJoin</I>,
          <I>lWhat</I>)

     LEFALSEFIELD
          Not  a  valid  field  name  specified  in  enumeration.
          (<I>lJoinSublist</I>)

     LEJOINDESCR
          Joining of descriptors failed. (<I>lJoinSublist</I>, <I>lJoin</I>)

     LEJOIN
          <I>lJoin</I> failed. (<I>lJoinSublist</I>)

     LEADDLIST
          <I>lAddList</I> failed. (<I>lJoinSublist</I>)

     LEDIFFDESCR
          List descriptors are unequal. (<I>lJoin</I>)

     LEJOINCOPYELEM
          <I>lJoinCopyElem</I> failed. (<I>lJoin</I>)

     LENOFORMATSTR
          No format string specified. (<I>lWhere</I>, <I>lWhat</I>)

     LEPARSECOND
          Parsing a condition structure failed. (<I>lWhere</I>)

     LECONDNULL
          <I>lCondition</I> pointer is NULL. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)

     LEOPUNKNOWN
          Unknown operator found. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)

     LESYNTAX
          A syntax error occurred. (<I>lWhat</I>)

     LECOUNTDESCR
          Counting  the  number  of  descriptor  fields   failed.
          (<I>lWhat</I>, <I>lCountWhat</I>)

SEE ALSO
     <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>.

COPYRIGHT
     See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and  permis-
     sions.































</PRE>
<HR>
<ADDRESS>
Man(1) output converted with
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
</ADDRESS>
</BODY>
</HTML>