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