1 /***********************************************************************/ 2 /* Open Visualization Data Explorer */ 3 /* (C) Copyright IBM Corp. 1989,1999 */ 4 /* ALL RIGHTS RESERVED */ 5 /* This code licensed under the */ 6 /* "IBM PUBLIC LICENSE - Open Visualization Data Explorer" */ 7 /***********************************************************************/ 8 9 10 #if defined(__cplusplus) || defined(c_plusplus) 11 extern "C" { 12 #endif 13 14 #ifndef _DXI_INVALID_H_ 15 #define _DXI_INVALID_H_ 16 17 /* TeX starts here. Do not remove this comment. */ 18 19 /* 20 \section{Invalid Data} 21 22 In order to support the selective elimination of positions and 23 connections from datasets, fields may contain ``invalid positions'' 24 and ``invalid connections'' components. These contain flags in a 25 one-to-one correspondence with the elements of the positions and 26 connections components that denote the current validity of the 27 correspondong element. Elements carrying a {\tt DATA\_INVALID} 28 validity status will not participate in further processing. 29 Note: in the current release of the Data Explorer, invalid data 30 marking is not supported by all modules. 31 32 Data may be invalidated by modifying (creating, if necessary) these 33 invalid positions and invalid connections arrays. If none exists, all 34 elements are assumed to be valid and an invalid array may be created 35 and initialized to {\tt DATA\_VALID} for all elements. Once positions 36 have been invalidated, it is possible to propagate the validity of 37 positions to the connections that are incident on them by calling {\tt 38 DXInvalidateConnections} which will create an invalid connections 39 component, if necessary. Note that the ``invalid connections'' 40 component cannot be assumed to be up-to-date with regard to invalid 41 positions unless this routine is called. 42 43 Invalid positions and connections (and their dependent information) may 44 be actually removed from the data set be calling {\tt DXCull}. This 45 routine removes all invalidated positions and connections and the 46 corresponding elements of components that are dependent on positions 47 and connections, renumbers components that reference positions or 48 connections (inserting a -1 for indices that refer to removed positions 49 or connections) and, finally, removes the invalid positions and 50 connections components. 51 52 The removal of invalid positions and connections may have significantly 53 detrimental effect on the performance of the system as a whole since it 54 may require the conversion or regular positions and connections 55 components to irregular form, thereby increasing the memory usage for 56 these components dramatically. However, the invalid components can 57 then be removed, saving space. {\tt DXCullConditional} is included to 58 weigh these considerations for the calling application. {\tt 59 DXCullConditional} may either return the original structure with invalid 60 components intact, cull the connections component, leaving the invalid 61 positions component intact, or cull both positions and connections. 62 63 */ 64 65 #define DATA_VALID 0 66 #define DATA_INVALID 1 67 68 Object DXInvalidateConnections(Object object); 69 /** 70 \index{DXInvalidateConnections} 71 Propagate the validity of positions within the fields of {\tt object} 72 to the connections. A connection is invalidated if any position on 73 which it is incident is invalid. An ``invalid connections'' component 74 will be created if necessary. Returns the updated object on success, 75 or returns null and sets the error code to indicate an error. 76 **/ 77 78 Object DXInvalidateUnreferencedPositions(Object object); 79 /** 80 \index{DXInvalidateUnreferencedPositions} 81 Determine which positions in the constituent fields of {\tt object} 82 are not referenced by any connections element and invalidate them. An 83 ``invalid positions'' component will be created if necessary. Returns 84 the updated object, or returns null and sets the error code to 85 indicate an error. 86 **/ 87 88 Object DXCull(Object object); 89 /** 90 \index{DXCull} 91 DXRemove any invalidated positions and/or connections from the 92 constituent fields of {\tt object}. DXRemove corresponding elements 93 from components that are dependent on positions or connections. 94 Renumber components that reference either positions and connections, 95 inserting -1 for indices that reference removed positions or 96 connections. DXRemove "invalid positions" and "invalid connections" 97 components. Returns the updated object, or returns null and sets the 98 error code to indicate an error. 99 **/ 100 101 Object DXCullConditional(Object object); 102 /** 103 \index{DXCullConditional} 104 Conditionally cull {\tt object}. Based on effiency criteria, {\tt 105 DXCullConditional} may either leave the original structure with invalid 106 components intact, cull the connections component, leaving the invalid 107 positions component intact, or cull both positions and connections. 108 Components dependent on a culled component are culled. Components 109 that reference culled components are renumbered. Returns the updated 110 object, or returns null and sets the error code to indicate an error. 111 **/ 112 113 #define IC_HASH 1 114 #define IC_DEP_ARRAY 2 115 #define IC_SEGLIST 3 116 #define IC_SORTED_LIST 4 117 #define IC_ALL_MARKED 5 118 #define IC_ALL_UNMARKED 6 119 120 #define IC_ELEMENT_MARKED DATA_INVALID 121 #define IC_ELEMENT_UNMARKED DATA_VALID 122 123 #define IC_MARKS_INDICATE_VALID 0 124 #define IC_MARKS_INDICATE_INVALID 1 125 126 typedef struct invalidComponentHandle 127 { 128 int type; /* current type, eg. dep array or hash */ 129 int myData; /* did I allocate the data pointer? */ 130 int nItems; /* total number of items in component */ 131 int nMarkedItems; /* current number of marked items */ 132 char *iName; /* invalid component name */ 133 HashTable hash; /* hash table pointer */ 134 Pointer data; /* data pointer */ 135 SegList *seglist; /* seg list pointer */ 136 int next; /* next pointer for sequential queries */ 137 Array array; /* original array */ 138 int sense; /* do marks indicate valid? */ 139 140 /* 141 * For iteration 142 */ 143 int *sortList; /* for hashed handles */ 144 int sortListSize; 145 int nextSlot; 146 int nextCand; 147 int nextMark; 148 int nextMarkI; 149 } *InvalidComponentHandle; 150 151 InvalidComponentHandle DXCreateInvalidComponentHandle(Object, Array, char *); 152 Error DXFreeInvalidComponentHandle(InvalidComponentHandle); 153 Error DXSaveInvalidComponent(Field, InvalidComponentHandle); 154 Array DXGetInvalidComponentArray(InvalidComponentHandle); 155 Error DXSetElementInvalid(InvalidComponentHandle, int); 156 Error DXSetElementValid(InvalidComponentHandle, int); 157 Error DXInvertValidity(InvalidComponentHandle); 158 Error DXSetAllValid(InvalidComponentHandle); 159 Error DXSetAllInvalid(InvalidComponentHandle); 160 int DXIsElementInvalid(InvalidComponentHandle, int); 161 int DXIsElementValid(InvalidComponentHandle, int); 162 int DXIsElementValidSequential(InvalidComponentHandle, int); 163 int DXIsElementInvalidSequential(InvalidComponentHandle, int); 164 int DXGetInvalidCount(InvalidComponentHandle); 165 int DXGetValidCount(InvalidComponentHandle); 166 Error DXInitGetNextInvalidElementIndex(InvalidComponentHandle); 167 Error DXInitGetNextValidElementIndex(InvalidComponentHandle); 168 int DXGetNextValidElementIndex(InvalidComponentHandle); 169 int DXGetNextInvalidElementIndex(InvalidComponentHandle); 170 Array DXForceInvalidArrayDependent(Array, Array); 171 172 #endif /* _DXI_INVALID_H_ */ 173 174 #if defined(__cplusplus) || defined(c_plusplus) 175 } 176 #endif 177