← Back to branch summary

~ubuntu-branches/ubuntu/utopic/gridengine/utopic

« back to all changes in this revision

Viewing changes to doc/htmlman/htmlman3/lSelect.html

  • Committer: Bazaar Package Importer
  • Author(s): Mark Hymers
  • Date: 2008-06-25 22:36:13 UTC
  • Revision ID: james.westby@ubuntu.com-20080625223613-tvd9xlhuoct9kyhm
Tags: upstream-6.2~beta2
Import upstream version 6.2~beta2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/htmlman/htmlman3/lSelect.html
 
1
<HTML>
 
2
<BODY BGCOLOR=white>
 
3
<PRE>
 
4
<!-- Manpage converted by man2html 3.0.1 -->
 
5
NAME
 
6
     lSelect, lSelectDestroy, lSplit, lJoinSubList, lJoin, lWhere
 
7
     (_lWhere),  lOrWhere,  lAndWhere,  lFreeWhere, lWhat, lFree-
 
8
     What, lWriteWhere, lWriteWhat, lCountWhat
 
9
 
 
10
     generic list database functions
 
11
 
 
12
SYNOPSIS
 
13
     #include "cull.h"
 
14
 
 
15
     lList* lSelect(
 
16
          char *newname,
 
17
          lList *sourcelist,
 
18
          lCondition *condition,
 
19
          lEnumeration *enumeration
 
20
     );
 
21
 
 
22
     lList* lSelectDestroy(
 
23
          lList *sourcelist,
 
24
          lCondition *condition,
 
25
     );
 
26
 
 
27
     int lSplit(
 
28
          lList **sourcelist,
 
29
          lList **not_matched_list,
 
30
          char *not_matched_list_name,
 
31
          lCondition *condition,
 
32
     );
 
33
 
 
34
     lList* lJoinSublist(
 
35
          char *newname,
 
36
          int joinfield,
 
37
          lList *list1,
 
38
          lCondition *where1,
 
39
          lEnumeration *what1,
 
40
          lDescr *subdescr,
 
41
          lCondition *where2,
 
42
          lEnumeration *what2
 
43
     );
 
44
 
 
45
     lList* lJoin(
 
46
          char *newname,
 
47
          int joinfield1,
 
48
          lList *lp0,
 
49
          lCondition *where1,
 
50
          lEnumeration *what1,
 
51
          int joinfield2,
 
52
          lList *lp1,
 
53
          lCondition *where2,
 
54
          lEnumeration *what2
 
55
     );
 
56
 
 
57
     lCondition* lWhere( char *format, ... );
 
58
 
 
59
     lCondition* _lWhere(char *format, WhereArgList arglist);
 
60
 
 
61
     lCondition* lOrWhere( lCondition *cp0, lCondition *cp1);
 
62
 
 
63
     lCondition* lAndWhere( lCondition *cp0, lCondition *cp1);
 
64
 
 
65
     void lFreeWhere( lCondition *condition );
 
66
 
 
67
     void lWriteWhere( lCondition *condition );
 
68
 
 
69
     lEnumeration* lWhat( char *format, ... );
 
70
 
 
71
     void lFreeWhat( lEnumeration *enumeration );
 
72
 
 
73
     void lWriteWhat( lEnumeration *enumeration );
 
74
 
 
75
     int lCountWhat(
 
76
          lEnumeration *enumeration,
 
77
          lDescr *descriptor
 
78
     );
 
79
 
 
80
DESCRIPTION
 
81
     lSelect
 
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.
 
96
 
 
97
     lSelectDestroy
 
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.
 
109
 
 
110
     lSplit
 
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.
 
130
 
 
131
     lJoinSublist
 
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
 
148
          is returned.
 
149
          For the construction of conditions and enumerations see
 
150
          <I>lWhere</I> and <I>lWhat</I> below.
 
151
 
 
152
     lJoin
 
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
 
165
          what2.
 
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.
 
170
 
 
171
     lWhere / _lWhere
 
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  (&amp;&amp;),  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).
 
180
 
 
181
          The syntax of the format  string  takes  the  following
 
182
          form:
 
183
 
 
184
               cond: %T ( negsimple [{ &amp;&amp; | || } {negsimple |
 
185
                         %I -&gt; cond } ] )
 
186
               negsimple: {simple | ! ( simple ) }
 
187
               simple: %I relop valuetype [{&amp;&amp; | ||} simple ...]
 
188
               relop: { &lt; | &gt; | == | != | &lt;= | &gt;= | m= | c= |  p=
 
189
          }
 
190
               valuetype: { %d | %s | %u | %f | %g | %o | %c }
 
191
 
 
192
          For valuetype the specifiers represent in the order  as
 
193
          above
 
194
 
 
195
               { int | string | unsigned long | float | double |
 
196
                    long | char }
 
197
 
 
198
          The relop specifiers have the following meaning:
 
199
 
 
200
               &lt;
 
201
               &gt;
 
202
               &lt;=
 
203
               &gt;=
 
204
               ==
 
205
               !=   comparison of numeric types as in the
 
206
                    C language
 
207
               ==   case sensitive comparison of strings
 
208
               c=   case insensitive comparison of strings
 
209
               m=   bitmask evaluation operator
 
210
               p=   pattern matching string comparison
 
211
 
 
212
          The following examples will show the usage:
 
213
 
 
214
               where1 = lWhere( "%T(%I==%s &amp;&amp; %I-&gt;%T(%I&lt;%d ||
 
215
                         %I&gt;%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,
 
220
                         "Hello");
 
221
 
 
222
          The condition 'where1' says:
 
223
 
 
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  &lt; 12 OR subfield2 &gt; 34 OR in
 
228
          the bitmasksubfield the bits for RUNNING and  IDLE  are
 
229
          set.    Bitmasks   are   stored  in  an  unsigned  long
 
230
          (ulong_32).
 
231
 
 
232
          The condition 'where2' says:
 
233
 
 
234
          NOT ( field1 == "Hello" ) for field1  of  a  list  with
 
235
          descriptor type1.
 
236
 
 
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.
 
241
 
 
242
          The WhereArg struct is built as follows:
 
243
 
 
244
               struct _WhereArg {
 
245
                    lDescr      *descriptor;
 
246
                    int         field;
 
247
                    lMultitype  *value;
 
248
               };
 
249
 
 
250
          The translation of the varargs <I>lWhere</I> functionality  to
 
251
          the WhereArgList mechanism is shown below:
 
252
 
 
253
               where = lWhere("%T( %I == %s &amp;&amp; %I -&gt;
 
254
                         %T ( %I &lt; %d ) )",
 
255
                         QueueT, Q_hostname, "durin.q",
 
256
                         Q_ownerlist, OwnerT, O_ownerage, 22);
 
257
 
 
258
          The corresponding WhereArgList is:
 
259
 
 
260
               WhereArg whereargs[20];
 
261
 
 
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;
 
269
 
 
270
               where = _lWhere("%T( %I == %s &amp;&amp; %I -&gt;
 
271
                         %T ( %I &lt; %d ) )",
 
272
                         whereargs);
 
273
 
 
274
     lOrWhere
 
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.
 
278
 
 
279
     lAndWhere
 
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.
 
283
 
 
284
     lFreeWhere
 
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.
 
288
 
 
289
     lWriteWhere
 
290
          writes a condition structure to  stdout  for  debugging
 
291
          purposes.  As  argument  a lCondition pointer is speci-
 
292
          fied.
 
293
 
 
294
     lWhat
 
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)
 
302
 
 
303
          The syntax of the format string is:
 
304
 
 
305
               what: %T ( {  ALL  |  NONE  |  {%I  [  %I  ...]  |
 
306
                    ! ( %I [%I...] ) } } )
 
307
 
 
308
          %T specifies the descriptor type for  <I>lWhat</I>,  the  rest
 
309
          specifies  ALL  fields,  no fields or the fields listed
 
310
          with %I [%I...].
 
311
 
 
312
          The following examples shall make things clearer:
 
313
 
 
314
               all_what = lWhat("%T(ALL)", QueueT);
 
315
 
 
316
          select all fields in QueueT.
 
317
 
 
318
               some_what  =   lWhat("%T(%I   %I   %I)",   QueueT,
 
319
                    Q_load, Q_name, Q_hostname);
 
320
 
 
321
          select  the  fields  Q_load,  Q_name,  Q_hostname  from
 
322
          QueueT.
 
323
 
 
324
               notsome_what   =   lWhat("%T(   !(%I   %I   %I))",
 
325
                    QueueT, Q_load, Q_name, Q_hostname);
 
326
 
 
327
          select all the fields of QueueT without QueueT, Q_load,
 
328
          Q_name, Q_hostname.
 
329
 
 
330
               none_what = lWhat("%T(NONE)",QueueT);
 
331
 
 
332
          select no field at all.
 
333
 
 
334
     lFreeWhat
 
335
          release the memory allocated for  a  field  enumeration
 
336
          structure. If the argument is NULL, the function simply
 
337
          returns.
 
338
 
 
339
     lWriteWhat
 
340
          writes a field  enumeration  structure  to  stdout  for
 
341
          debugging purposes.
 
342
 
 
343
     lCountWhat
 
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.
 
349
 
 
350
RETURN VALUES
 
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.
 
353
 
 
354
ERRORS
 
355
     The following errors may occur. The  touched  functions  are
 
356
     stated in parentheses.
 
357
 
 
358
     LELISTNULL
 
359
          List pointer is NULL. (<I>lSelect</I>)
 
360
 
 
361
     LEENUMNULL
 
362
          Field enumeration is NULL. (<I>lSelect</I>, <I>lFreeWhat</I>, <I>lWrite-</I>
 
363
          <I>What</I>, <I>lCountWhat</I>)
 
364
 
 
365
     LECOUNTWHAT
 
366
          <I>lCountWhat</I> failed. (<I>lSelect</I>)
 
367
 
 
368
     LEMALLOC
 
369
          <B><A HREF="../htmlman3/Malloc.html">Malloc(3)</A></B> failed. (<I>lSelect</I>, <I>lWhat</I>)
 
370
 
 
371
     LEPARTIALDESCR
 
372
          Building a new partial descriptor failed. (<I>lSelect</I>)
 
373
 
 
374
     LECREATELIST
 
375
          <I>lCreateList</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)
 
376
 
 
377
     LEELEMNULL
 
378
          List element is NULL. (<I>lSelect</I>)
 
379
 
 
380
     LECOPYELEMPART
 
381
          Copying parts of the element failed. (<I>lSelect</I>)
 
382
 
 
383
     LEAPPENDELEM
 
384
          <I>lAppendElem</I> failed. (<I>lSelect</I>, <I>lJoinSublist</I>, <I>lJoin</I>)
 
385
 
 
386
     LEGETNROFELEM
 
387
          <I>lGetNumberOfElem</I> failed. (<I>lSelect</I>)
 
388
 
 
389
     LENULLARGS
 
390
          Unallowed use of NULL arguments. (<I>lJoinSublist</I>, <I>lJoin</I>)
 
391
 
 
392
     LEDESCRNULL
 
393
          List descriptor is NULL. (<I>lJoinSublist</I>, <I>lWhere</I>, <I>lCount-</I>
 
394
          <I>What</I>)
 
395
 
 
396
     LENAMENOT
 
397
          Name not contained in descriptor. (<I>lJoinSublist</I>, <I>lJoin</I>,
 
398
          <I>lWhat</I>)
 
399
 
 
400
     LEFALSEFIELD
 
401
          Not  a  valid  field  name  specified  in  enumeration.
 
402
          (<I>lJoinSublist</I>)
 
403
 
 
404
     LEJOINDESCR
 
405
          Joining of descriptors failed. (<I>lJoinSublist</I>, <I>lJoin</I>)
 
406
 
 
407
     LEJOIN
 
408
          <I>lJoin</I> failed. (<I>lJoinSublist</I>)
 
409
 
 
410
     LEADDLIST
 
411
          <I>lAddList</I> failed. (<I>lJoinSublist</I>)
 
412
 
 
413
     LEDIFFDESCR
 
414
          List descriptors are unequal. (<I>lJoin</I>)
 
415
 
 
416
     LEJOINCOPYELEM
 
417
          <I>lJoinCopyElem</I> failed. (<I>lJoin</I>)
 
418
 
 
419
     LENOFORMATSTR
 
420
          No format string specified. (<I>lWhere</I>, <I>lWhat</I>)
 
421
 
 
422
     LEPARSECOND
 
423
          Parsing a condition structure failed. (<I>lWhere</I>)
 
424
 
 
425
     LECONDNULL
 
426
          <I>lCondition</I> pointer is NULL. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)
 
427
 
 
428
     LEOPUNKNOWN
 
429
          Unknown operator found. (<I>lFreeWhere</I>, <I>lWriteWhere</I>)
 
430
 
 
431
     LESYNTAX
 
432
          A syntax error occurred. (<I>lWhat</I>)
 
433
 
 
434
     LECOUNTDESCR
 
435
          Counting  the  number  of  descriptor  fields   failed.
 
436
          (<I>lWhat</I>, <I>lCountWhat</I>)
 
437
 
 
438
SEE ALSO
 
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>.
 
440
 
 
441
COPYRIGHT
 
442
     See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and  permis-
 
443
     sions.
 
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
</PRE>
 
476
<HR>
 
477
<ADDRESS>
 
478
Man(1) output converted with
 
479
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 
480
</ADDRESS>
 
481
</BODY>
 
482
</HTML>