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_FIELD_H_
15 #define _DXI_FIELD_H_
16 
17 /* TeX starts here. Do not remove this comment. */
18 
19 /*
20 \section{Field class}
21 \label{fieldsec}
22 
23 This section describes the field data structure.  Each field has some
24 number of named components.  Each component may have a value, which is an
25 {\tt Object}, and some number of attributes, whose values are strings.
26 The defined components and attributes are listed in Chapter ??? of the
27 User's Manual.
28 */
29 
30 Field DXNewField(void);
31 /**
32 \index{DXNewField}
33 Creates a new field object.  Returns the field, or returns null and
34 sets the error code to indicate an error.
35 **/
36 
37 Field DXSetComponentValue(Field f, char *name, Object value);
38 /**
39 \index{DXSetComponentValue}
40 Sets the value of the component of the field {\tt f} specified by {\tt
41 name} to the specified object {\tt value}.  Makes a {\tt DXReference()}
42 to the object {\tt value}.  The {\tt name} may be null, in which case
43 a new component is added that may be accessed only via {\tt
44 DXGetEnumeratedComponentValue()}.  Any attributes set on the previous
45 value of the component are copied to the new value; this may override
46 any attributes set on the new component value before {\tt DXSetComponentValue()}
47 is called.  If this is not the desired behavior, you may either delete
48 the old component first, or set the new component attributes after you set
49 the component value.  Returns {\tt f} on success, or
50 returns null and sets the error code to indicate an error.
51 **/
52 
53 Field DXSetComponentAttribute(Field f, char *name, char *attribute, Object value);
54 /**
55 \index{DXSetComponentAttribute}
56 Sets the value of the specified {\tt attribute} of component {\tt
57 name} to {\tt value}.  Returns {\tt f} on success, or returns null and
58 sets the error code to indicate an error.
59 **/
60 
61 Object DXGetComponentValue(Field f, char *name);
62 /**
63 \index{DXGetComponentValue}
64 Returns the value of component {\tt name} of field {\tt f}, or returns
65 null but does not set the error code if no such component exists.
66 **/
67 
68 Object DXGetComponentAttribute(Field f, char *name, char *attribute);
69 /**
70 \index{DXGetComponentAttribute}
71 Returns the value of the specified {\tt attribute} of component {\tt
72 name}, or returns null but does not set the error code if no such
73 component exists.
74 **/
75 
76 Object DXGetEnumeratedComponentValue(Field f, int n, char **name);
77 Object DXGetEnumeratedComponentAttribute(Field f, int n, char **name, char *attribute);
78 /**
79 \index{DXGetEnumeratedComponentValue}\index{DXGetEnumeratedComponentAttribute}
80 Enumerates a field's components. Call {\tt GetEnumeratedComponent()}
81 with successive values of {\tt n} starting with 0 until null is
82 returned.  Note that the numbering changes as components are added and
83 deleted.  These routines return the name of the component in *name.  The
84 first routine returns the value of the {\tt n}th component, while the
85 second routine returns the value of the specified {\tt attribute} of the
86 {\tt n}th component.  Thus {\tt n} and {\tt attribute} are input
87 parameters and {\tt name} is an output parameter.  Returns the value
88 of the component, or returns null but does not set the error code
89 if {\tt n} is out of range.
90 **/
91 
92 Field DXDeleteComponent(Field f, char *component);
93 /**
94 \index{DXDeleteComponent}
95 Deletes the named component from a field.  Returns {\tt f}, or returns
96 null but does not set the error code if the component does not exist.
97 **/
98 
99 Error DXComponentReq(Array a, Pointer *data, int *n, int nreq, Type t, int dim);
100 Error DXComponentOpt(Array a, Pointer *data, int *n, int nreq, Type t, int dim);
101 Error DXComponentReqLoc(Array a, Pointer *data, int *n, int nreq, Type t, int dim);
102 Error DXComponentOptLoc(Array a, Pointer *data, int *n, int nreq, Type t, int dim);
103 /**
104 \index{DXComponentOpt}\index{DXComponentReq}
105 \index{DXComponentOptLoc}\index{DXComponentReqLoc}
106 These functions combine several common operations in accessing and
107 checking a field component array.  The four routines have identical
108 calling sequences, but differ as follows: First, {\tt DXComponentOpt()}
109 and {\tt DXComponentReq()} return pointers to the global copy of the
110 array data, while {\tt DXComponentOptLoc()} and {\tt DXComponentReqLoc()}
111 return pointers to a local copy of the array data, and should be
112 matched by a {\tt FreeDataLocal()} call.  Second, {\tt DXComponentReq()}
113 and {\tt DXComponentReqLoc()} consider it an error if the component is
114 missing ({\tt a} is null), while {\tt DXComponentOpt()} and {\tt
115 DXComponentOptLoc()} consider the component optional and do not consider
116 a null {\tt a} to be an error.  If {\tt data} is not null, a pointer
117 to a global or local copy of the data is returned in {\tt *data}.  If
118 {\tt n} is not null, the number of items in the array is returned in
119 {\tt *n}.  If {\tt n} is null, the number of array items must be {\tt
120 nreq}.  The type of the array must be {\tt type}.  If {\tt dim} is 0,
121 the array must have rank 0 (scalar).  If {\tt dim} is non-zero, the
122 array must have rank 1 and shape equal to {\tt dim}.  Returns {\tt OK}
123 if no error occurs, or returns {\tt ERROR} and sets the error code in
124 case of error.
125 **/
126 
127 /*
128 \paragraph{Usage notes.}
129 An example of the expected usage of {\tt DXComponentReq()} etc. is
130 as follows:
131 \begin{program}
132     a = DXGetComponentValue(f, "positions");
133     if (!DXComponentReq(a, &points, &npoints, 0, TYPE_FLOAT, 3))
134         return NULL;
135 
136     a = DXGetComponentValue(f, "colors");
137     if (!DXComponentOpt(a, &colors, NULL, npoints, TYPE_FLOAT, 3))
138 	return NULL;
139     if (colors) ...
140 \end{program}
141 The first two statements check and retrieve a required ``positions''
142 component,  while the next two statements check and retrieve an optional
143 ``colors'' component that must have the same number of elements as the
144 ``positions'' component.  Since the second call uses {\tt DXComponentOpt()},
145 the program must then subsequently check if {\tt colors} is null to
146 determine whether the colors were present.
147 */
148 
149 #endif /* _DXI_FIELD_H_ */
150 
151 #if defined(__cplusplus) || defined(c_plusplus)
152 }
153 #endif
154