IBM Visualization Data Explorer SC38-0497-06 Programmer's Reference Version 3 Release 1 Modification 4 IBM IBM Visualization Data Explorer SC38-0497-06 Programmer's Reference Version 3 Release 1 Modification 4 +--- Note! ----------------------------------------------------------+ | | | Before using this information and the product it supports, be sure | | to read the general information under "Notices" on page xvii. | | | +--------------------------------------------------------------------+ Seventh Edition (September 1997) This edition applies to IBM Visualization Data Explorer Version 3.1.4, to IBM Visualization Data Explorer SMP Version 3.1.4, and to all subsequent releases and modifications thereof until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. Order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address given below. A form for readers' comments appears at the back of this publication. If the form has been removed, address your comments to: IBM Corporation Thomas J. Watson Research Center/Hawthorne Data Explorer Development P.O. Box 704 Yorktown Heights, NY 10598-0704 USA If you send information to IBM, you grant IBM a nonexclusive right to use or distribute that information, in any way it believes appropriate, without incurring any obligation to you. (C) Copyright International Business Machines Corporation 1991-1997. All rights reserved. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. CONTENTS ________ Figures . . . . . . . . . . . . . . . . . . . . . xiii Tables . . . . . . . . . . . . . . . . . . . . . . xv Notices . . . . . . . . . . . . . . . . . . . . . xvii Products, Programs, and Services . . . . . . . . xviii Trademarks and Service Marks . . . . . . . . . . xviii Copyright notices . . . . . . . . . . . . . . . . . xix About This Book . . . . . . . . . . . . . . . . . xxvii Summary of Topics . . . . . . . . . . . . . . . xxviii Typographic Conventions . . . . . . . . . . . . . xxix Related Publications and Sources . . . . . . . . . xxx IBM Publications . . . . . . . . . . . . . . . . xxx Non-IBM Publications . . . . . . . . . . . . . . xxx Other sources of information . . . . . . . . . xxxi Chapter 1. Overview . . . . . . . . . . . . . . . . 1 1.1 Writing Modules for use in the Data Explorer VPE or Scripting Language . . . . . . . . . . . . . . . 2 1.2 Writing a Stand-alone Program Using the Data Explorer Data Model . . . . . . . . . . . . . . . . 3 1.3 Writing a Stand-alone Program Using Data Explorer Modules . . . . . . . . . . . . . . . . . . . . . . 3 1.4 Controlling the Data Explorer Executive or User Interface from a Separate Program . . . . . . . . . 4 Chapter 2. Writing a Simple Module . . . . . . . . . 5 2.1 Getting Started Writing a Module . . . . . . . . 6 2.2 Adding the Hello Module . . . . . . . . . . . . 7 Hello Module with Error Checking . . . . . . . . 13 Chapter 3. Module Builder . . . . . . . . . . . . 17 3.1 Overview . . . . . . . . . . . . . . . . . . . 18 3.2 Creating a Module with the Module Builder: A Summary . . . . . . . . . . . . . . . . . . . . . 19 3.3 Using the Module Builder: A Quick Walk Through 20 3.4 Module Builder: Menu Bar . . . . . . . . . . . 24 File Options . . . . . . . . . . . . . . . . . . 24 Edit Options . . . . . . . . . . . . . . . . . . 24 Build Options . . . . . . . . . . . . . . . . . . 24 Help Options . . . . . . . . . . . . . . . . . . 25 3.5 Module Builder: Overall Module Description . . 25 3.6 Module Builder: Individual Parameter Information Section . . . . . . . . . . . . . . . . . . . . . 27 3.7 Worker Routine . . . . . . . . . . . . . . . . 30 Positions Specification . . . . . . . . . . . . . 30 Connections Specification . . . . . . . . . . . . 31 (C) Copyright IBM Corp. 1991-1997 iii Input Data . . . . . . . . . . . . . . . . . . . 31 Output Data . . . . . . . . . . . . . . . . . . . 31 Implementing Default Input Parameters . . . . . . 32 Worker Routine Examples . . . . . . . . . . . . . 32 Chapter 4. What you need to know about Data Explorer to write a Module . . . . . . . . . . . . . . . . 37 4.1 Data Explorer Data Model . . . . . . . . . . . 38 4.2 Memory Management . . . . . . . . . . . . . . 40 Allocating and Freeing Memory . . . . . . . . . . 40 Reference Counts . . . . . . . . . . . . . . . . 40 4.3 Data Explorer Execution Model . . . . . . . . 41 Chapter 5. Working with Data . . . . . . . . . . . 43 5.1 Add Module Example--Add a Number to Every Data Value . . . . . . . . . . . . . . . . . . . . . . 44 5.2 Add2 Module Example--Add Two Data Fields . . . 46 5.3 Add2Invalid Module Example--Manipulate Invalid Data . . . . . . . . . . . . . . . . . . . . . . . 47 Chapter 6. Working with Positions . . . . . . . . 51 6.1 MakeX Module Example--Create New Positions . . 52 6.2 MakeXEfficient Module Example--Create New Positions . . . . . . . . . . . . . . . . . . . . 55 Chapter 7. Working with Connections . . . . . . . 59 7.1 AverageCell Module Example--Average the Data Values of All Neighbors . . . . . . . . . . . . . 60 Chapter 8. Importing Data . . . . . . . . . . . . 65 8.1 Writing a Filter . . . . . . . . . . . . . . . 66 8.2 Writing an Import Module . . . . . . . . . . . 69 Chapter 9. Using the Pick Structure . . . . . . . 73 9.1 The Pick Structure . . . . . . . . . . . . . . 74 9.2 ShowPick Module Example--Using Color to Show a Picked Object . . . . . . . . . . . . . . . . . . 75 Chapter 10. Writing Modules for a Parallel Environment . . . . . . . . . . . . . . . . . . . 85 10.1 A Parallel Version of the Add Module . . . . 86 10.2 A Parallel Version of the AverageCell Module 90 Chapter 11. Making a Module Work . . . . . . . . . 97 11.1 Module Description Files . . . . . . . . . . 98 Examples of Module Description Files . . . . . . 103 11.2 Asynchronous Modules . . . . . . . . . . . . 104 11.3 Inboard, Outboard, and Runtime-loadable Modules . . . . . . . . . . . . . . . . . . . . . 105 11.4 Compiling, Linking, and Debugging an Inboard Module . . . . . . . . . . . . . . . . . . . . . . 106 11.5 Compiling, Linking, and Debugging an Outboard Module . . . . . . . . . . . . . . . . . . . . . . 107 Special Considerations for Outboard Modules . . . 109 iv IBM Visualization Data Explorer: Programmer's Reference Asynchronous Outboard Module: An Example . . . . 111 11.6 Compiling, Linking, and Debugging a Runtime-loadable Module . . . . . . . . . . . . . 114 11.7 Memory Leaks . . . . . . . . . . . . . . . . 115 Chapter 12. Working with Data Model Objects . . . 117 12.1 Field Class . . . . . . . . . . . . . . . . . 120 12.2 Group Class . . . . . . . . . . . . . . . . . 122 Generic Operations . . . . . . . . . . . . . . . 122 Series Groups . . . . . . . . . . . . . . . . . . 123 MultiGrid Groups . . . . . . . . . . . . . . . . 124 Composite Fields . . . . . . . . . . . . . . . . 124 Parts . . . . . . . . . . . . . . . . . . . . . . 125 12.3 Array Class . . . . . . . . . . . . . . . . . 125 Generic Operations . . . . . . . . . . . . . . . 126 Irregular Arrays . . . . . . . . . . . . . . . . 127 String List Routines . . . . . . . . . . . . . . 128 Array Handling . . . . . . . . . . . . . . . . . 128 Creating Positions and Connections Grids . . . . 129 Regular Arrays . . . . . . . . . . . . . . . . . 130 Path Arrays . . . . . . . . . . . . . . . . . . . 131 Product Arrays . . . . . . . . . . . . . . . . . 131 Mesh Arrays . . . . . . . . . . . . . . . . . . . 132 Constant Arrays . . . . . . . . . . . . . . . . . 132 12.4 String Class . . . . . . . . . . . . . . . . 133 12.5 Private Class . . . . . . . . . . . . . . . . 133 12.6 Printing Objects . . . . . . . . . . . . . . 134 12.7 Field Construction . . . . . . . . . . . . . 134 Points and Dependent Data . . . . . . . . . . . . 134 Connections . . . . . . . . . . . . . . . . . . . 135 Standard Components . . . . . . . . . . . . . . . 135 12.8 Extracting Module Parameters . . . . . . . . 137 12.9 Creating Simple Data Explorer Objects . . . . 138 12.10 Component Manipulation . . . . . . . . . . . 139 12.11 Data Import and Export . . . . . . . . . . . 139 Data Explorer Format Files . . . . . . . . . . . 139 netCDF Data . . . . . . . . . . . . . . . . . . . 140 Chapter 13. System Services . . . . . . . . . . . 141 13.1 Error Handling and Messages . . . . . . . . . 142 13.2 Timing . . . . . . . . . . . . . . . . . . . 145 13.3 Memory Allocation . . . . . . . . . . . . . . 145 13.4 Object Class . . . . . . . . . . . . . . . . 146 Type Definitions . . . . . . . . . . . . . . . . 146 Classes and Subclasses . . . . . . . . . . . . . 148 Object Routines . . . . . . . . . . . . . . . . . 148 Setting Data Types . . . . . . . . . . . . . . . 150 13.5 Cache . . . . . . . . . . . . . . . . . . . . 151 13.6 Pending Commands . . . . . . . . . . . . . . 153 13.7 Looping Support . . . . . . . . . . . . . . . 153 13.8 Parallelism . . . . . . . . . . . . . . . . . 154 13.9 Basic Data Types . . . . . . . . . . . . . . 155 Points and Vectors . . . . . . . . . . . . . . . 155 Contents v Lines, Triangles, Quadrilaterals, Tetrahedra, and Cubes . . . . . . . . . . . . . . . . . . . . . 155 Colors . . . . . . . . . . . . . . . . . . . . . 156 Angles . . . . . . . . . . . . . . . . . . . . . 157 Transformation Matrices . . . . . . . . . . . . . 157 Basic Operations . . . . . . . . . . . . . . . . 158 13.10 Module Access . . . . . . . . . . . . . . . 159 13.11 Asynchronous Services . . . . . . . . . . . 161 Chapter 14. Data Processing . . . . . . . . . . . 163 14.1 Data Partitioning . . . . . . . . . . . . . . 164 14.2 Interpolation and Mapping . . . . . . . . . . 164 14.3 Invalid Data . . . . . . . . . . . . . . . . 166 Examples . . . . . . . . . . . . . . . . . . . . 169 14.4 Growing and Shrinking Partitioned Data . . . 171 14.5 Hashing . . . . . . . . . . . . . . . . . . . 173 Examples . . . . . . . . . . . . . . . . . . . . 175 14.6 Pick-Assistance Routines . . . . . . . . . . 178 Example . . . . . . . . . . . . . . . . . . . . . 178 Chapter 15. Geometric Objects . . . . . . . . . . 181 15.1 Text . . . . . . . . . . . . . . . . . . . . 182 15.2 Clipping . . . . . . . . . . . . . . . . . . 182 15.3 Path Operations . . . . . . . . . . . . . . . 183 Chapter 16. Rendering . . . . . . . . . . . . . . 185 16.1 Transformation . . . . . . . . . . . . . . . 186 16.2 Surface Shading . . . . . . . . . . . . . . . 187 16.3 Tiling . . . . . . . . . . . . . . . . . . . 189 Rendering Model . . . . . . . . . . . . . . . . . 190 Tiling Options . . . . . . . . . . . . . . . . . 190 16.4 Xform Class . . . . . . . . . . . . . . . . . 191 16.5 Screen Class . . . . . . . . . . . . . . . . 191 16.6 Clipped Class . . . . . . . . . . . . . . . . 192 16.7 Camera Class . . . . . . . . . . . . . . . . 193 16.8 Light Class . . . . . . . . . . . . . . . . . 194 16.9 Image Fields . . . . . . . . . . . . . . . . 194 Chapter 17. DXLink Developer's Toolkit . . . . . . 197 17.1 Introduction . . . . . . . . . . . . . . . . 198 17.2 Example 1: sealevel.c . . . . . . . . . . . . 199 17.3 Example 2: maptoplane.c . . . . . . . . . . . 201 17.4 Example 3: xapp.c . . . . . . . . . . . . . . 204 17.5 Initialization and Exit . . . . . . . . . . . 209 17.6 Messaging System . . . . . . . . . . . . . . 211 Sending Messages to the Server . . . . . . . . . 211 Receiving Messages from the Server . . . . . . . 212 Messaging Routines . . . . . . . . . . . . . . . 213 17.7 Execution Control . . . . . . . . . . . . . . 214 17.8 Program Control . . . . . . . . . . . . . . . 216 Loading programs and macros . . . . . . . . . . . 216 Setting Variables . . . . . . . . . . . . . . . . 217 Retrieving Values Sent From Data Explorer . . . . 220 17.9 Window Control . . . . . . . . . . . . . . . 221 vi IBM Visualization Data Explorer: Programmer's Reference Appendix A. Data Explorer Libraries . . . . . . . 223 A.1 libDXlite.a . . . . . . . . . . . . . . . . . 223 A.2 libDXcallm.a . . . . . . . . . . . . . . . . . 223 A.3 libDXL.a . . . . . . . . . . . . . . . . . . . 224 Appendix B. Data Explorer Data Model Library: DXlite Routines . . . . . . . . . . . . . . . . . 225 Appendix C. Data Explorer Library Routines . . . . 227 DXAbortTaskGroup . . . . . . . . . . . . . . . . 233 DXAdd, DXCross, DXDiv, DXDot, DXLength, DXMax, DXMin, DXMul, DXNeg, DXNormalize, DXSub . . . . 234 DXAddArrayData . . . . . . . . . . . . . . . . . 235 DXAddFaceNormal, DXAddFaceNormals . . . . . . . . 236 DXAddLine, ...Triangle, ...Quad, ...Tetrahedron, ...Lines, ...Triangles, ...Quads, ...Tetrahedra 237 DXAddMessage, DXMessageReturn, DXMessageGoto . . 239 DXAddPoint, ...Color, ...FrontColor, ...BackColor, ...Opacity, ...Normal, DXAddPoints, ...Colors, ...FrontColors, ...BackColors, ...Opacities, ...Normals . . . . . . . . . . . . . . . . . . . 239 DXAddTask . . . . . . . . . . . . . . . . . . . . 241 DXAllocate, DXAllocateZero, DXAllocateLocal, DXAllocateLocalZero, DXAllocateLocalOnly, DXAllocateLocalOnlyZero . . . . . . . . . . . . 242 DXAllocateArray . . . . . . . . . . . . . . . . . 243 DXApplyTransform . . . . . . . . . . . . . . . . 244 DXArrayConvert, DXArrayConvertV . . . . . . . . . 245 DXBeginLongMessage, DXEndLongMessage . . . . . . 247 DXBoundingBox . . . . . . . . . . . . . . . . . . 247 DXCallModule, DXModSet..., DXSetModule... . . . . 249 DXChangedComponentValues, DXChangedComponentStructure . . . . . . . . . . 251 DXCheckRIH . . . . . . . . . . . . . . . . . . . 252 DXClipBox . . . . . . . . . . . . . . . . . . . . 253 DXClipPlane . . . . . . . . . . . . . . . . . . . 254 DXColorNameToRGB . . . . . . . . . . . . . . . . 254 DXCompareModuleId . . . . . . . . . . . . . . . . 255 DXComponentReq, DXComponentOpt, DXComponentReqLoc, DXComponentOptLoc . . . . . . . . . . . . . . . 256 DXConcatenate, DXInvert, DXTranspose, DXAdjointTranspose, DXDeterminant, DXApply . . . 257 DXCopy . . . . . . . . . . . . . . . . . . . . . 258 DXCopyAttributes . . . . . . . . . . . . . . . . 259 DXCopyModuleId . . . . . . . . . . . . . . . . . 260 DXCreateArrayHandle . . . . . . . . . . . . . . . 260 DXCreateHash . . . . . . . . . . . . . . . . . . 261 DXCreateInvalidComponentHandle . . . . . . . . . 263 DXCreateTaskGroup . . . . . . . . . . . . . . . . 264 DXCull . . . . . . . . . . . . . . . . . . . . . 265 DXDebug, DXEnableDebug, DXQueryDebug . . . . . . 266 DXDelete . . . . . . . . . . . . . . . . . . . . 267 DXDeleteComponent . . . . . . . . . . . . . . . . 268 DXDeleteHashElement . . . . . . . . . . . . . . . 269 Contents vii DXDestroyHash . . . . . . . . . . . . . . . . . . 269 DXDisplayX, DXDisplayX8, DXDisplayX12, DXDisplayX24 . . . . . . . . . . . . . . . . . . 270 DXEmptyField . . . . . . . . . . . . . . . . . . 272 DXEndField . . . . . . . . . . . . . . . . . . . 272 DXEndObject . . . . . . . . . . . . . . . . . . . 275 DXExecuteTaskGroup . . . . . . . . . . . . . . . 275 DXExists . . . . . . . . . . . . . . . . . . . . 276 DXExportDX . . . . . . . . . . . . . . . . . . . 277 DXExtract . . . . . . . . . . . . . . . . . . . . 278 DXExtractFloat . . . . . . . . . . . . . . . . . 278 DXExtractInteger . . . . . . . . . . . . . . . . 279 DXExtractNthString . . . . . . . . . . . . . . . 279 DXExtractParameter . . . . . . . . . . . . . . . 280 DXExtractString . . . . . . . . . . . . . . . . . 282 DXFree . . . . . . . . . . . . . . . . . . . . . 283 DXFreeArrayDataLocal . . . . . . . . . . . . . . 283 DXFreeArrayHandle . . . . . . . . . . . . . . . . 284 DXFreeInvalidComponentHandle . . . . . . . . . . 284 DXFreeModuleId . . . . . . . . . . . . . . . . . 285 DXGeometricText . . . . . . . . . . . . . . . . . 286 DXGetArrayClass . . . . . . . . . . . . . . . . . 286 DXGetArrayData . . . . . . . . . . . . . . . . . 287 DXGetArrayDataLocal . . . . . . . . . . . . . . . 288 DXGetArrayEntry, DXGetArrayEntries . . . . . . . 289 DXGetArrayInfo . . . . . . . . . . . . . . . . . 289 DXGetAttribute . . . . . . . . . . . . . . . . . 290 DXGetCacheEntry, DXGetCacheEntryV . . . . . . . . 291 DXGetCameraMatrix, DXGetCameraRotation, DXGetCameraMatrixWithFuzz . . . . . . . . . . . 292 DXGetClippedInfo . . . . . . . . . . . . . . . . 293 DXGetComponentAttribute . . . . . . . . . . . . . 294 DXGetComponentValue . . . . . . . . . . . . . . . 295 DXGetConnections . . . . . . . . . . . . . . . . 295 DXGetConstantArrayData . . . . . . . . . . . . . 296 DXGetEnumeratedAttribute . . . . . . . . . . . . 297 DXGetEnumeratedComponentAttribute . . . . . . . . 297 DXGetEnumeratedComponentValue . . . . . . . . . . 298 DXGetEnumeratedMember . . . . . . . . . . . . . . 299 DXGetError . . . . . . . . . . . . . . . . . . . 300 DXGetErrorExit . . . . . . . . . . . . . . . . . 300 DXGetErrorMessage . . . . . . . . . . . . . . . . 301 DXGetFloatAttribute . . . . . . . . . . . . . . . 302 DXGetFont . . . . . . . . . . . . . . . . . . . . 303 DXGetGroupClass . . . . . . . . . . . . . . . . . 303 DXGetImageSize, DXGetImageBounds . . . . . . . . 305 DXGetIntegerAttribute . . . . . . . . . . . . . . 305 DXGetInvalidComponentArray . . . . . . . . . . . 307 DXGetInvalidCount . . . . . . . . . . . . . . . . 307 DXGetItemSize . . . . . . . . . . . . . . . . . . 308 DXGetMember . . . . . . . . . . . . . . . . . . . 308 DXGetMemberCount . . . . . . . . . . . . . . . . 309 DXGetMeshArrayInfo . . . . . . . . . . . . . . . 309 DXGetMeshOffsets . . . . . . . . . . . . . . . . 310 viii IBM Visualization Data Explorer: Programmer's Reference DXGetModuleId . . . . . . . . . . . . . . . . . . 311 DXGetNextHashElement . . . . . . . . . . . . . . 312 DXGetNextInvalidElementIndex . . . . . . . . . . 312 DXGetNextValidElementIndex . . . . . . . . . . . 313 DXGetObjectClass . . . . . . . . . . . . . . . . 313 DXGetObjectTag, DXSetObjectTag . . . . . . . . . 314 DXGetPart . . . . . . . . . . . . . . . . . . . . 315 DXGetPartClass . . . . . . . . . . . . . . . . . 315 DXGetPathArrayInfo . . . . . . . . . . . . . . . 316 DXGetPathOffset . . . . . . . . . . . . . . . . . 317 DXGetPickPoint . . . . . . . . . . . . . . . . . 318 DXGetPixels . . . . . . . . . . . . . . . . . . . 318 DXGetPrivateData . . . . . . . . . . . . . . . . 319 DXGetProductArrayInfo . . . . . . . . . . . . . . 320 DXGetRegularArrayInfo . . . . . . . . . . . . . . 320 DXGetScreenInfo . . . . . . . . . . . . . . . . . 321 DXGetSeriesMember . . . . . . . . . . . . . . . . 323 DXGetString . . . . . . . . . . . . . . . . . . . 323 DXGetStringAttribute . . . . . . . . . . . . . . 324 DXGetTime . . . . . . . . . . . . . . . . . . . . 325 DXGetType . . . . . . . . . . . . . . . . . . . . 326 DXGetValidCount . . . . . . . . . . . . . . . . . 327 DXGetXformInfo . . . . . . . . . . . . . . . . . 327 DXGrow, DXGrowV . . . . . . . . . . . . . . . . . 329 DXImportCDF . . . . . . . . . . . . . . . . . . . 330 DXImportCM . . . . . . . . . . . . . . . . . . . 330 DXImportDX . . . . . . . . . . . . . . . . . . . 331 DXImportHDF . . . . . . . . . . . . . . . . . . . 332 DXImportNetCDF . . . . . . . . . . . . . . . . . 332 DXInitGetNextHashElement . . . . . . . . . . . . 333 DXInitModules . . . . . . . . . . . . . . . . . . 334 DXInitGetNextInvalidElementIndex, DXInitGetNextValidElementIndex . . . . . . . . . 334 DXInsert . . . . . . . . . . . . . . . . . . . . 335 DXInsertHashElement . . . . . . . . . . . . . . . 335 DXInterpolate . . . . . . . . . . . . . . . . . . 336 DXInvalidateConnections . . . . . . . . . . . . . 337 DXInvalidateDupBoundary . . . . . . . . . . . . . 338 DXInvalidateUnreferencedPositions . . . . . . . . 338 DXInvertValidity . . . . . . . . . . . . . . . . 339 DXIsElementValid, DXIsElementInvalid . . . . . . 339 DXIsElementValidSequential, DXIsElementInvalidSequential . . . . . . . . . . 340 DXIterateArray . . . . . . . . . . . . . . . . . 342 DXLn, DXTri, DXQuad, DXTetra . . . . . . . . . . 343 DXLocalizeInterpolator . . . . . . . . . . . . . 344 DXLoopDone . . . . . . . . . . . . . . . . . . . 344 DXLoopFirst . . . . . . . . . . . . . . . . . . . 345 DXMakeFloat . . . . . . . . . . . . . . . . . . . 346 DXMakeGridConnections, DXMakeGridConnectionsV . . 346 DXMakeGridPositions, DXMakeGridPositionsV . . . . 347 DXMakeImage . . . . . . . . . . . . . . . . . . . 348 DXMakeInteger . . . . . . . . . . . . . . . . . . 349 DXMakeString . . . . . . . . . . . . . . . . . . 349 Contents ix DXMakeStringList, DXMakeStringListV . . . . . . . 350 DXMap . . . . . . . . . . . . . . . . . . . . . . 350 DXMapArray . . . . . . . . . . . . . . . . . . . 351 DXMapCheck . . . . . . . . . . . . . . . . . . . 352 DXMarkTime, DXMarkTimeLocal . . . . . . . . . . . 353 DXMessage . . . . . . . . . . . . . . . . . . . . 354 DXNeighbors . . . . . . . . . . . . . . . . . . . 355 DXNewAmbientLight . . . . . . . . . . . . . . . . 355 DXNewArray, DXNewArrayV . . . . . . . . . . . . . 356 DXNewCamera . . . . . . . . . . . . . . . . . . . 357 DXNewClipped . . . . . . . . . . . . . . . . . . 359 DXNewCompositeField . . . . . . . . . . . . . . . 360 DXNewConstantArray, DXNewConstantArrayV . . . . . 361 DXNewDistantLight . . . . . . . . . . . . . . . . 362 DXNewField . . . . . . . . . . . . . . . . . . . 362 DXNewGroup . . . . . . . . . . . . . . . . . . . 364 DXNewInterpolator . . . . . . . . . . . . . . . . 365 DXNewMeshArray, DXNewMeshArrayV . . . . . . . . . 366 DXNewMultiGrid . . . . . . . . . . . . . . . . . 367 DXNewPathArray . . . . . . . . . . . . . . . . . 367 DXNewPrivate . . . . . . . . . . . . . . . . . . 368 DXNewProductArray, DXNewProductArrayV . . . . . . 369 DXNewRegularArray . . . . . . . . . . . . . . . . 370 DXNewScreen . . . . . . . . . . . . . . . . . . . 372 DXNewSeries . . . . . . . . . . . . . . . . . . . 374 DXNewString . . . . . . . . . . . . . . . . . . . 374 DXNewXform . . . . . . . . . . . . . . . . . . . 375 DXOutputRGB . . . . . . . . . . . . . . . . . . . 377 DXPartition . . . . . . . . . . . . . . . . . . . 378 DXPrint, DXPrintV . . . . . . . . . . . . . . . . 378 DXPrintAlloc . . . . . . . . . . . . . . . . . . 379 DXPrintTimes . . . . . . . . . . . . . . . . . . 381 DXProcessorId . . . . . . . . . . . . . . . . . . 382 DXProcessors . . . . . . . . . . . . . . . . . . 383 DXProcessParts . . . . . . . . . . . . . . . . . 383 DXPt, DXVec . . . . . . . . . . . . . . . . . . . 385 DXQueryAmbientLight . . . . . . . . . . . . . . . 386 DXQueryArrayCommon, DXQueryArrayCommonV . . . . . 386 DXQueryArrayConvert, DXQueryArrayConvertV . . . . 388 DXQueryConstantArray . . . . . . . . . . . . . . 389 DXQueryDistantLight . . . . . . . . . . . . . . . 390 DXQueryGridConnections . . . . . . . . . . . . . 391 DXQueryGridPositions . . . . . . . . . . . . . . 391 DXQueryHashElement . . . . . . . . . . . . . . . 392 DXQueryOriginalSizes, DXQueryOriginalMeshExtents 393 DXQueryParameter . . . . . . . . . . . . . . . . 394 DXQueryPickCount . . . . . . . . . . . . . . . . 395 DXQueryPickPath . . . . . . . . . . . . . . . . . 397 DXQueryPokeCount . . . . . . . . . . . . . . . . 397 DXReadyToRun . . . . . . . . . . . . . . . . . . 399 DXReAllocate . . . . . . . . . . . . . . . . . . 400 DXReference . . . . . . . . . . . . . . . . . . . 400 DXRegisterInputHandler . . . . . . . . . . . . . 401 DXRemove . . . . . . . . . . . . . . . . . . . . 402 x IBM Visualization Data Explorer: Programmer's Reference DXRename . . . . . . . . . . . . . . . . . . . . 402 DXRender . . . . . . . . . . . . . . . . . . . . 403 DXReplace . . . . . . . . . . . . . . . . . . . . 404 DXResetError . . . . . . . . . . . . . . . . . . 405 DXRGB . . . . . . . . . . . . . . . . . . . . . . 405 DXRibbon . . . . . . . . . . . . . . . . . . . . 406 DXRotateX, DXRotateY, DXRotateZ, DXScale, DXTranslate, DXMat . . . . . . . . . . . . . . . 407 DXSaveInvalidComponent . . . . . . . . . . . . . 409 DXScalarConvert . . . . . . . . . . . . . . . . . 409 DXSetAllInvalid . . . . . . . . . . . . . . . . . 410 DXSetAllValid . . . . . . . . . . . . . . . . . . 410 DXSetAttribute, DXDeleteAttribute . . . . . . . . 411 DXSetBackgroundColor, DXGetBackgroundColor . . . 412 DXSetCacheEntry, DXSetCacheEntryV . . . . . . . . 412 DXSetClippedObjects . . . . . . . . . . . . . . . 415 DXSetComponentAttribute . . . . . . . . . . . . . 415 DXSetComponentValue . . . . . . . . . . . . . . . 416 DXSetConnections . . . . . . . . . . . . . . . . 417 DXSetElementInvalid . . . . . . . . . . . . . . . 417 DXSetElementValid . . . . . . . . . . . . . . . . 418 DXSetEnumeratedMember . . . . . . . . . . . . . . 418 DXSetError, DXErrorReturn, DXErrorGoto . . . . . 419 DXSetErrorExit . . . . . . . . . . . . . . . . . 420 DXSetFloatAttribute . . . . . . . . . . . . . . . 422 DXSetGroupType, DXSetGroupTypeV . . . . . . . . . 422 DXSetIntegerAttribute . . . . . . . . . . . . . . 423 DXSetMember . . . . . . . . . . . . . . . . . . . 425 DXSetMeshOffsets . . . . . . . . . . . . . . . . 425 DXSetOrthographic, DXGetOrthographic . . . . . . 426 DXSetPart . . . . . . . . . . . . . . . . . . . . 427 DXSetPathOffset . . . . . . . . . . . . . . . . . 428 DXSetPendingCmd . . . . . . . . . . . . . . . . . 429 DXSetPerspective, DXGetPerspective . . . . . . . 430 DXSetResolution, DXGetCameraResolution . . . . . 431 DXSetScreenObject . . . . . . . . . . . . . . . . 432 DXSetSeriesMember . . . . . . . . . . . . . . . . 433 DXSetStringAttribute . . . . . . . . . . . . . . 434 DXSetView, DXGetView . . . . . . . . . . . . . . 434 DXSetXformObject . . . . . . . . . . . . . . . . 435 DXShrink . . . . . . . . . . . . . . . . . . . . 436 DXStatistics . . . . . . . . . . . . . . . . . . 437 DXSwap . . . . . . . . . . . . . . . . . . . . . 437 DXTraceTime . . . . . . . . . . . . . . . . . . . 439 DXTraversePickPath . . . . . . . . . . . . . . . 439 DXTrim . . . . . . . . . . . . . . . . . . . . . 440 DXTube . . . . . . . . . . . . . . . . . . . . . 440 DXTypeCheck, DXTypeCheckV . . . . . . . . . . . . 441 DXTypeSize, DXCategorySize . . . . . . . . . . . 442 DXUnreference . . . . . . . . . . . . . . . . . . 444 DXUnsetGroupType . . . . . . . . . . . . . . . . 444 DXValidPositionsBoundaryBox . . . . . . . . . . . 446 DXWarning . . . . . . . . . . . . . . . . . . . . 448 Contents xi Glossary . . . . . . . . . . . . . . . . . . . . . 449 Index . . . . . . . . . . . . . . . . . . . . . . . 457 xii IBM Visualization Data Explorer: Programmer's Reference FIGURES _______ 1. Data Explorer architecture . . . . . . . . . . . 2 2. The Hello Module in a Visual Program . . . . . 12 3. The Hello Module with a String Interactor in a Visual Program . . . . . . . . . . . . . . . . 12 4. Module Builder Dialog Box . . . . . . . . . . 20 5. Worker Routine: Example1_worker . . . . . . . 32 6. Worker Routine. Example2_worker . . . . . . . 33 7. Worker Routine. Example3_worker . . . . . . . 34 8. Parts of a Group . . . . . . . . . . . . . . . 125 9. Order of Vertices in Connection Elements . . . 157 10. Transformation of Coordinates . . . . . . . . 186 11. Types of Connections and Positions . . . . . . 190 12. sealevel.net . . . . . . . . . . . . . . . . . 199 13. maptoplane.net . . . . . . . . . . . . . . . . 201 14. Data Explorer architecture . . . . . . . . . . 224 (C) Copyright IBM Corp. 1991-1997 xiii xiv IBM Visualization Data Explorer: Programmer's Reference TABLES ______ 1. Data Explorer Objects . . . . . . . . . . . . 118 2. Summary of Type Conversions . . . . . . . . . 245 3. Summary of Category Conversions . . . . . . . 246 4. Set Attributes . . . . . . . . . . . . . . . . 273 5. Format Keyword Description . . . . . . . . . . 277 6. Summary of Type Conversions . . . . . . . . . 387 7. Summary of Category Conversions . . . . . . . 388 (C) Copyright IBM Corp. 1991-1997 xv xvi IBM Visualization Data Explorer: Programmer's Reference NOTICES _______ Products, Programs, and Services . . . . . . . . xviii Trademarks and Service Marks . . . . . . . . . . xviii Copyright notices . . . . . . . . . . . . . . . . . xix (C) Copyright IBM Corp. 1991-1997 xvii PRODUCTS, PROGRAMS, AND SERVICES ________________________________ References in this publication to IBM(*) products, programs, or services do not imply that IBM intends to make these available in all countries in which it operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights may be used instead. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give the user any license to those patents. License inquiries should be sent, in writing, to: International Business Machines Corporation IBM Director of Licensing 500 Columbus Avenue Thornwood, New York 10594 USA TRADEMARKS AND SERVICE MARKS ____________________________ The following terms, marked by an asterisk (*) at their first occurrence in this publication, are trademarks or registered trademarks of the IBM Corporation in the United States and/or other countries. AIX IBM IBM Power Visualization System RISC System/6000 Visualization Data Explorer The following terms, marked by a double asterisk (**) at their first occurrence in this publication, are trademarks of other companies. AViiON Data General Corporation DEC Digital Equipment Corporation DGC Data General Corporation Graphics Interchange Format (GIF) CompuServe, Inc. Hewlett-Packard Hewlett-Packard Company xviii IBM Visualization Data Explorer: Programmer's Reference HP Hewlett-Packard Company iFOR/LS Apollo Computer, Inc. Motif Open Software Foundation NetLS Apollo Computer, Inc. Network Licensing Software Apollo Computer, Inc. OpenWindows Sun Microsystems, Inc. OSF Open Software Foundation, Inc. PostScript Adobe Systems, Inc. X Window System Massachusetts Institute of Technology COPYRIGHT NOTICES _________________ IBM Visualization Data Explorer contains software copyrighted as follows: o E. I. du Pont de Nemours and Company (C) Copyright 1997 E. I. du Pont de Nemours and Company Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of E. I. du Pont de Nemours and Company not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. E. I. du Pont de Nemours and Company makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. E. I. du Pont de Nemours and Company disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall E. I. du Pont de Nemours and Company be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. o National Space Science Data Center (C) Copyright 1990-1994 NASA/GSFC Notices xix National Space Science Data Center NASA/Goddard Space Flight Center Greenbelt, Maryland 20771 USA (NSI/DECnet -- NSSDCA::CDFSUPPORT) (Internet -- CDFSUPPORT@NSSDCA.GSFC.NASA.GOV) o University Corporation for Atmospheric Research/Unidata (C) Copyright 1993, University Corporation for Atmospheric Research Permission to use, copy, modify, and distribute this software and its documentation for any purpose without fee is hereby granted, provided that the above copyright notice appear in all copies, that both that copyright notice and this permission notice appear in supporting documentation, and that the name of UCAR/Unidata not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. UCAR makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. It is provided with no support and without obligation on the part of UCAR Unidata, to assist in its use, correction, modification, or enhancement. o NCSA NCSA HDF version 3.2r4 March 1, 1993 NCSA HDF Version 3.2 source code and documentation are in the public domain. Specifically, we give to the public domain all rights for future licensing of the source code, all resale rights, and all publishing rights. We ask, but do not require, that the following message be included in all derived works: Portions developed at the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign, in collaboration with the Information Technology Institute of Singapore. THE UNIVERSITY OF ILLINOIS GIVES NO WARRANTY, EXPRESSED OR IMPLIED, FOR THE SOFTWARE AND/OR DOCUMENTATION PROVIDED, INCLUDING, WITHOUT LIMITATION, WARRANTY OF MERCHANTABILITY AND WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE o Gradient Technologies, Inc. and Hewlett-Packard Co. xx IBM Visualization Data Explorer: Programmer's Reference (C) Copyright Gradient Technologies, Inc. 1991,1992,1993 (C) Copyright Hewlett-Packard Co. 1988,1990 June, 1993 UNIX is a registered trademark of UNIX Systems Laboratories, Inc. Gradient is a registered trademark of Gradient Technologies, Inc. NetLS and Network Licensing System are trademarks of Apollo Computer, Inc., a subsidiary of Hewlett-Packard Co. o Sam Leffler and Silicon Graphics (C) Copyright 1988-1996 Sam Leffler (C) Copyright 1991-1996 Silicon Graphics, Inc. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in all copies of the software and related documentation, and (ii) the names of Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Sam Leffler and Silicon Graphics. THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. o Compuserve Incorporated The Graphics Interchange Format (C) is the copyright property of Compuserve Incorporated. GIF(SM) is a Service Mark property of Compuserve Incorporated. o Integrated Computer Solutions, Inc. Motif Shrinkwrap License Notices xxi READ THIS LICENSE AGREEMENT CAREFULLY BEFORE USING THE PROGRAM TAPE, THE SOFTWARE (THE "PROGRAM"), OR THE ACCOMPANYING USER DOCUMENTATION (THE "DOCUMENTATION"). THIS AGREEMENT REPRESENTS THE ENTIRE AGREEMENT CONCERNING THE PROGRAM AND DOCUMENTATION POSAL, REPRESENTATION, OR UNDERSTANDING BETWEEN THE PARTIES WITH RESPECT TO ITS SUBJECT MATTER. BY BREAKING THE SEAL ON THE TAPE, YOU ARE ACCEPTING AND AGREEING TO THE TERMS OF THIS AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND NY THE TERMS OF THIS AGREEMENT, YOU SHOULD PROMPTLY RETURN THE CONTENTS, WITH THE TAPE SEAL UNBROKEN; YOUR MONEY WILL BE REFUNDED. 1. License: ISC remains the exclusive owner of the Program and the Documentation. ICS grant to Customer a nonexclusive, nontransferable (except as provided herein) license to use, modify, have modified, and prepare and have prepared derivative works of the Program as necessary to use it. 2. Customer Rights: Customer may use, modify and have modified and prepare and have prepared derivative works of the Program in object code form as is necessary to use the Program. Customer may make copies of the Program up to the number authorized by ICS in writing, in advance. There shall be no fee for Statically linked copies of the Motif libraries. Statically linked copies are object code copies integrated within a single application program and executable only with that single application. Run Time copies require payment of ICS' then applicable fee. Run Time copies are copies which include any portion of a linkable object file (".o" file), library file (".a" file), the window manager (mwm manager), the U.I.L. compiler, a shared library, or any tool or mechanism that enables generation of any portion of such components; other copies will require payment of ICS' applicable fees. TRANSFERS TO THIRD PARTIES OF COPIES OF THE LICENSED PROGRAMS, OR OF APPLICATIONS PROGRAMS INCORPORATING THE PROGRAM (OR ANY PORTION THEREOF), REQUIRE ICS' RESELLER AGREEMENT. Customer may not lease or lend the Program to any party. Customer shall not attempt to reverse engineer, disassemble or decompile the program. 3. Limited Warranty: (a) ICS warrants that for thirty (30) days from the delivery to Customer, each copy of the Program, when installed and used in accordance with the Documentation, will conform in all material respects to the description of the Program's operations in the Documentation. (b) Customer's exclusive remedy and ICS' sole liability under this warranty shall be for ICS to attempt, through xxii IBM Visualization Data Explorer: Programmer's Reference reasonable efforts, to correct any material failure of the Program to perform as warranted, if such failure is reported to ICS within the warranty period and Customer, at ICS' request, provides ICS with sufficient information (which may include access to Customer's computer system for use of Customer's copies of the Program by ICS personnel) to reproduce the defect in question; provided, that if ICS is unable to correct any such failure within a reasonable time, ICS may, at its sole option, refund to the Customer the license fee paid for the Product. (c) ICS need not treat minor discrepancies in the Documentation as errors in the Program, and may instead furnish correction to the Program. (d) ICS does not warrant that the operation of the Program will be uninterrupted or error-free, or that all errors will be corrected. (e) THE FOREGOING WARRANTY IS IN LIEU OF, AND ICS DISCLAIMS, ALL OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT WILL ICS BE LIABLE FOR ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING WITHOUT LIMITATION LOST PROFITS, ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM OR DOCUMENTATION. 4. Term and Termination: The term of this agreement shall be indefinite; however, this Agreement may be terminated by ICS in the event of a material default by Customer which is not cured within thirty (30) days after the receipt of notice of such breech by ICS. Customer may terminate this Agreement at any time by destruction of the Program, the Documentation, and all other copies of either of them. Upon termination, Customer shall immediately cease use of, and return immediately to ICS, all existing copies of the Program and Documentation, and cease all use thereof. All provisions hereof regarding liability and limits thereon shall survive the termination of this the Agreement. 5. U.S. GOVERNMENT LICENSES. If the Product is provided to the U.S. Government, the Government acknowledges receipt of notice that the Product and Documentation were developed at private expense and that no part of either of them is in the public domain. The Government acknowledges ICS' representation that the Product is "Restricted Computer Software" as defined in clause 52.227-19 of the Federal Acquisition Regulations (the "FAR" and is "Commercial Computer Software" as defined in Subpart 227.471 of the Department of Defense Federal Acquisition Regulation Supplement (the "DFARS"). The Government agrees that (i) if the software is Notices xxiii supplied to the Department of Defense, the software is classified as "Commercial Computer Software" . and that the Government is acquiring only "Restricted Rights" in the software and its documentation as that term is defined in Clause 252.227-7013(c)(1) of the DFARS and (ii) if the software is supplied to any unit or agency of the Government other than the Department of Defense, then notwithstanding any other lease or license agreement that may pertain to, or accompany the delivery of, the computer software and accompanying documentation, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Clause 52.227-19(c)(2) of the FAR. All copies of the software and the documentation sold to or for use by the Government shall contain any and all notices and legends necessary or appropriate to assure that the Government acquires only limited right in any such documentation and restricted rights in any such software. 6. Governing Law: This license shall be governed by and construed in accordance with the laws of the Commonwealth of Massachusetts as a contract made and performed therein. o OMRON Corporation, NTT Software Corporation, and MIT (C) Copyright 1990, 1991 by OMRON Corporation, NTT Software Corporation, and Nippon Telegraph and Telephone Corporation (C) Copyright 1991 by the Massachusetts Institute of Technology Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of OMRON, NTT Software, NTT, and M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. OMRON, NTT Software, NTT, and M.I.T. make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. OMRON, NTT SOFTWARE, NTT, AND M.I.T. DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL OMRON, NTT SOFTWARE, NTT, OR M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER xxiv IBM Visualization Data Explorer: Programmer's Reference TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Notices xxv xxvi IBM Visualization Data Explorer: Programmer's Reference ABOUT THIS BOOK _______________ Summary of Topics . . . . . . . . . . . . . . . xxviii Typographic Conventions . . . . . . . . . . . . . xxix Related Publications and Sources . . . . . . . . . xxx IBM Publications . . . . . . . . . . . . . . . . xxx Non-IBM Publications . . . . . . . . . . . . . . xxx Other sources of information . . . . . . . . . xxxi (C) Copyright IBM Corp. 1991-1997 xxvii This reference is intended for programmers who: 1. want to write their own modules for use with Data Explorer, or 2. want to write applications which incorporate Data Explorer modules or use the Data Explorer data model, or 3. want to write applications which directly control the Data Explorer executive or user interface. Programmers using this reference should be familiar with Data Explorer (in particular, its data model). In addition to covering various aspects of creating and implementing modules, this reference describes in detail the use of the Module Builder--a utility that simplifies the task of writing a module. SUMMARY OF TOPICS _________________ o Chapter 1, "Overview" on page 1 briefly discusses the various ways the Data Explorer libraries can be used and points you to the appropriate sections, depending on what task you want to accomplish and how you want to use Data Explorer. o Chapter 2, "Writing a Simple Module" on page 5 presents a simple example to outline the basic procedure for creating and implementing a module. It also summarizes the data and execution models of Data Explorer. o Chapter 3, "Module Builder" on page 17, details the basic features of the Module Builder user interface. o Chapter 5, "Working with Data" on page 43 shows how to write modules which are concerned only with "data" component of an object. A simple module which adds two fields together is described. o Chapter 6, "Working with Positions" on page 51 shows how to write modules which operate on the "positions" component of an object. A simple "glyph" type module which places a mark at each position in a field is described. o Chapter 7, "Working with Connections" on page 59 shows how to write modules which operate using the "connections" component of an object. A simple module which averages data over the nearby neighbors in a field is described. o Chapter 8, "Importing Data" on page 65 shows how to write an import filter. o Chapter 9, "Using the Pick Structure" on page 73 shows how to write a module which uses the structure output by the Pick tool to perform specific operations on objects "picked" using the mouse in the Image window. xxviii IBM Visualization Data Explorer: Programmer's Reference o Chapter 10, "Writing Modules for a Parallel Environment" on page 85, explains how to write a module for execution on parallel processors. o Chapter 11, "Making a Module Work" on page 97, deals with the main aspects of implementing a new module: module description files, compilation and linking, and debugging. o Chapter 12, "Working with Data Model Objects" on page 117, details the programming interface of the Data Explorer data model. o Chapter 13, "System Services" on page 141, Chapter 14, "Data Processing" on page 163, and Chapter 15, "Geometric Objects" on page 181 summarize the Data Explorer routines available for: - System services (e.g, error handling and storage allocation) - Data processing (e.g, partitioning and hashing) - Creating geometric objects. o Chapter 16, "Rendering" on page 185, deals with several advanced aspects of rendering an image: transformations, shading, and tiling. o Chapter 17, "DXLink Developer's Toolkit" on page 197, describes the main features of this aid to application programming for Data Explorer. o Appendix B, "Data Explorer Data Model Library: DXlite Routines" on page 225, lists the subset of Data Explorer routines for creating, querying, and modifying Data Explorer Objects. o Appendix C, "Data Explorer Library Routines" on page 227, lists and describes all the Data Explorer interface routines. o "Glossary" on page 449, a glossary of Data Explorer terms, follows the appendices. TYPOGRAPHIC CONVENTIONS _______________________ "Boldface" Identifies commands, keywords, files, directories, messages from the system, and other items whose names are defined by the system. Italic Identifies parameters with names or values to be supplied by the user. "Monospace" Identifies examples of specific data values and text similar to what you might see displayed or might type at a keyboard or that you might write in a program. About This Book xxix RELATED PUBLICATIONS AND SOURCES ________________________________ IBM PUBLICATIONS o IBM Visualization Data Explorer User's Guide, SC38-0496 Details the main features of Data Explorer, including the data model, data import, the user interface, the Image window, and the visual program editor. and the scripting language. Of particular interest to programmers: chapters on the data model and the scripting language. o IBM Visualization Data Explorer User's Reference, SC38-0486 Contains detailed descriptions of Data Explorer's tools. Note: Consult this reference if you are creating visual programs or scripts. o IBM Visualization Data Explorer Programmer's Reference, SC38-0497 Contains detailed descriptions of the Data Explorer library routines. Note: Consult this reference if you are writing your own modules for Data Explorer. NON-IBM PUBLICATIONS The following treat various aspects of computer graphics and visualization: Adobe Systems Incorporated, PostScript Language Reference Manual, 2nd Ed., Addison-Wesley Publishing Company, Massachusetts, 1990. Aldus Corporation and Microsoft Corporation, Tag Image File Format Specification, Revision 5.0, Aldus Corporation, Washington, 1988. Arvo, Jim, ed., Graphics Gems II, Academic Press, Inc., Boston, Massachusetts, 1991. Foley, J.D., van Dam, A., Feiner, S.K., Hughes, J.F., Computer Graphics: Principles and Practice, xxx IBM Visualization Data Explorer: Programmer's Reference Addison-Wesley Publishing Company; Massachusetts, 1990. Friedhoff, Richard M., and Benzon, William, Visualization: The Second Computer Revolution, New York, Harry N. Abrams, Inc., 1989. Glassner, Andrew, ed., Graphics Gems, Academic Press, Inc., Boston, Massachusetts, 1990. Hill, F.S., Jr., Computer Graphics. Macmillan Publishing Company, New York, 1990. Kirk, David, ed., Graphics Gems III, Academic Press, Inc., Boston, Massachusetts, 1992. Robin, Harry, The Scientific Image: from cave to computer, Harry N. Abrams, Inc., New York, 1992. Rogers, David F., Procedural Elements for Computer Graphics, McGraw-Hill Book Company, New York, 1985. Rogers, David F. and Adams, J.Alan, Mathematical Elements for Computer Graphics, 2nd Ed., New York, McGraw-Hill Book Company, 1990. SIGGRAPH Conference Proceedings, Association for Computing Machinery, Inc.: A Publication of ACM SIGGRAPH, New York, various years. Tufte, Edward, The Visual Display of Quantitative Information, Graphics Press, Cheshire, Connecticut, 1983. OTHER SOURCES OF INFORMATION For additional ideas, consult the "DX Repository," available through anonymous FTP ("ftp.tc.cornell.edu." in directory "pub/Data.Explorer"), and gopher ("ftp.tc.cornell.edu." port 70). This public software resource includes information and visual programs contributed by Data Explorer users from around the world. We encourage you to contribute your innovations and ideas to the Repository, in the form of new modules, macros, visual programs, and tips and tricks you discover as you learn and master Data Explorer. On the Internet, the newsgroup "comp.graphics.apps.data-explorer" is used by customers around the word to share information and ask questions. This newsgroup is also followed by Data Explorer developers. About This Book xxxi If you have access to the World Wide Web, you can find the Data Explorer home page at "http://www.almaden.ibm.com/dx/". xxxii IBM Visualization Data Explorer: Programmer's Reference CHAPTER 1. OVERVIEW ____________________ 1.1 Writing Modules for use in the Data Explorer VPE or Scripting Language . . . . . . . . . . . . . . . 2 1.2 Writing a Stand-alone Program Using the Data Explorer Data Model . . . . . . . . . . . . . . . . 3 1.3 Writing a Stand-alone Program Using Data Explorer Modules . . . . . . . . . . . . . . . . . . . . . . 3 1.4 Controlling the Data Explorer Executive or User Interface from a Separate Program . . . . . . . . . 4 (C) Copyright IBM Corp. 1991-1997 1 The Data Explorer libraries allow you to extend Data Explorer's functionality in a variety of ways. Depending on the task you want to accomplish, the way you use the libraries will vary. Figure 1 shows the Data Explorer architecture. Figure 1. Data Explorer architecture The Data Explorer User Interface and Data Explorer Executive are the two programs you use when you create and execute visual programs. Underlying the Data Explorer Executive is a collection of modules, which in turn use the Data Explorer data model to manipulate all of the objects in a program (data sets, isosurfaces, images, etc.). The Data Explorer architecture is described in more detail in Chapter 1, "Overview" on page 1 in IBM Visualization Data Explorer User's Guide. 1.1 WRITING MODULES FOR USE IN THE DATA EXPLORER VPE OR SCRIPTING LANGUAGE ___________________________________________________________________________ If you want to write a module to use in the Data Explorer Visual Program Editor, or in the scripting language, you will probably use the libDXlite.a library. This library contains all of the Data Explorer data model routines which allow you to query, manipulate, and create data model objects. Much of this reference book concerns this common use of the Data Explorer library routines. You should be familiar with the material in Chapter 12, "Working with Data Model Objects" on page 117, which discusses how to use the Data Explorer data model routines. You may also want to incorporate one or more of the existing Data Explorer modules into your own module, or use some of the high level data processing functions, such as interpolation. In this case you would need to use the libDXcallm.a library. DXCallModule is discussed in 13.10, "Module Access" on page 159. Chapter 2 through Chapter 11 show you a number of examples of modules, including import filters and various data manipulation modules. These examples are supported by ".c" files and makefiles in "/usr/lpp/dx/samples/program_guide". If you wish to incorporate routines from the libDXcallm.a library, simply change the makefiles to link to this library instead of to libDXlite.a. All of the routines in libDXcallm.a are described in Appendix C, "Data Explorer Library Routines" on page 227, while the subset of routines available in libDXlite.a is listed in Appendix B, "Data Explorer Data Model Library: DXlite Routines" on page 225. When you write a module for use in Data Explorer, the Data Explorer Executive is still the process which "owns main". Your module is simply 2 IBM Visualization Data Explorer: Programmer's Reference incorporated into Data Explorer. Your module can be directly built in to the Data Explorer Executive (inboard module), run as a separate process (outboard module), or loaded into the Data Explorer executive at runtime (runtime-loadable module). Each of these is discussed in Chapter 11, "Making a Module Work" on page 97. Using runtime-loadable modules is in general the preferred option. 1.2 WRITING A STAND-ALONE PROGRAM USING THE DATA EXPLORER DATA MODEL _____________________________________________________________________ You may also want to write a stand-alone program which uses the Data Explorer data model. For example, you may want to write a data filter which processes data, writing it out to a file in Data Explorer format using DXExportDX. In this case, your stand-alone program "owns main" and simply links in Data Explorer data model routines, which are listed in Appendix B, "Data Explorer Data Model Library: DXlite Routines" on page 225, and discussed in Chapter 12, "Working with Data Model Objects" on page 117. Graphically, this is represented by the lower "User Program" in Figure 1 on page 2, which embeds Data Explorer data model routines into the user's program. 1.3 WRITING A STAND-ALONE PROGRAM USING DATA EXPLORER MODULES ______________________________________________________________ You may want to write a stand-alone program which directly uses Data Explorer modules. You would link to the libDXcallm.a library, and use DXCallModule to call individual Data Explorer. In this case, as with the previous one, your stand-alone program "owns main". Note that you can do complete visualization programs in this way, from Import to Isosurface to Display from within your own program. However, you will not be getting the functionality of the Data Explorer Executive in this case, including cache management, and control of execution order. You will, in addition, be responsible for deleting objects when you are finished using them. Note that with the SuperviseWindow and SuperviseState modules (see "SuperviseWindow" on page 431 and "SuperviseState" on page 425 in IBM Visualization Data Explorer User's Reference), direct manipulation within the Image window is available without the Image tool, so that a program using DXCallModule can provide direct interaction with objects. Examples of stand-alone programs including ".c" files and makefiles which use the CallModule library can be found in "/usr/lpp/dx/samples/callmodule". Graphically, this is represented by the lower "User Program" in Figure 1 on Chapter 1. Overview 3 page 2, which embeds Data Explorer module routines into the user's program. 1.4 CONTROLLING THE DATA EXPLORER EXECUTIVE OR USER INTERFACE FROM A SEPARATE ______________________________________________________________________________ PROGRAM _______ You may want to write a program which controls the Data Explorer Executive. For example, you could write your own user interface, providing a custom "look and feel", and send Data Explorer script language commands to the Data Explorer executive. In this case you would get all of the functionality provided by the executive (cache management, control of execution order, and object management). You could also directly control the Data Explorer User Interface from a separate program, loading and executing visual programs. For example, you may wish to fire up Data Explorer with a "canned" visualization program once a simulation is complete, with parameters within the visual program preset to particular values. Graphically, both of these are represented by the upper "User Program" in Figure 1 on page 2, which controls the Data Explorer Executive or User Interface from the user's program. The libDXL.a library (DXLink) provides this functionality, and is discussed in Chapter 17, "DXLink Developer's Toolkit" on page 197. Examples of DXLink programs can be found in "/usr/lpp/dx/samples/dxlink." With the functionality provided by SuperviseWindow and SuperviseState (see "SuperviseWindow" on page 431 and "SuperviseState" on page 425 in IBM Visualization Data Explorer User's Reference), your program does not need the Image tool (which is provided only within the Data Explorer User Interface) in order to provide direct user interaction in the image window. Thus a custom GUI communicating only with the Data Explorer Executive can implement all of the user-interaction provided by the Data Explorer User Interface. Examples of custom direct interactors can be found in "/usr/lpp/dx/samples/supervise"; while these examples are demonstrated using the Data Explorer User Interface, there is no necessity that they do so, as all of the modules used in these examples (SuperviseWindow, SuperviseState, and Display, in particular) are available directly from the Data Explorer Executive. 4 IBM Visualization Data Explorer: Programmer's Reference CHAPTER 2. WRITING A SIMPLE MODULE ___________________________________ 2.1 Getting Started Writing a Module . . . . . . . . 6 2.2 Adding the Hello Module . . . . . . . . . . . . 7 Hello Module with Error Checking . . . . . . . . 13 (C) Copyright IBM Corp. 1991-1997 5 This chapter discusses the basics of writing a simple module for Data Explorer. Subsequent chapters cover some typical types of modules you might want to write. Although Data Explorer modules support a broad range of data and connections types, your module need support only those types it can be expected to encounter. Moreover, it is not necessary to manipulate all the components of a Data Explorer Field. The programming examples in later chapters illustrate modules that manipulate particular components (e.g., "data"). Before writing a module, you should have a general understanding of the Data Explorer data model and be familiar with the way data is carried in Fields, Groups, and components (see 4.1, "Data Explorer Data Model" on page 38). For a detailed treatment of the data model, see Chapter 3, "Understanding the Data Model" on page 19 in IBM Visualization Data Explorer User's Guide. In this manual, Chapter 12, "Working with Data Model Objects" on page 117, summarizes the routines that implement the model. Two other important topics are briefly reviewed in subsequent sections: 1. managing the memory allocated to and used by visual programs and their constituent modules (see 4.2, "Memory Management" on page 40) and 2. the Data Explorer execution model (see 4.3, "Data Explorer Execution Model" on page 41). 2.1 GETTING STARTED WRITING A MODULE _____________________________________ To build a module, you must: 1. Define the module's function and its interface (i.e., its inputs and outputs). 2. Create a module description file containing this information. 3. Write the module. 4. Compile and link the module. Once you have completed these four steps, you can run a version of Data Explorer that incorporates the module. The Module Builder is a point-and-click interface that facilitates much of this work by creating the files necessary for a module: o a module description file o a C-code framework (or template) file o a makefile. 6 IBM Visualization Data Explorer: Programmer's Reference All you need do is add your own application code to the framework file. (See Chapter 3, "Module Builder" on page 17.) A module can be added to Data Explorer in one of three forms: inboard, outboard, or runtime-loadable. An inboard module is linked directly into a new Data Explorer executive. An outboard module is a separate executable linked to the Data Explorer routine library and controlled by the executive. It can later be compiled and linked as an inboard module for greater efficiency. A runtime-loadable module can be loaded when Data Explorer is started or while it is running. It is more portable than the inboard module version of the same function and more efficient than the outboard version. See 11.3, "Inboard, Outboard, and Runtime-loadable Modules" on page 105. 2.2 ADDING THE HELLO MODULE ____________________________ The procedure in this example follows the 4-step sequence outlined above. (1) Define the module's function, inputs, and outputs The Hello module appends an input string to "hello." The resulting combination is the module's output. If the input string is "NULL", the default output is ""hello world."" (2) Create a module description file Data Explorer's graphical user interface and executive access the module description file to determine the names of the modules and their inputs and outputs. Note: This type of file is commonly referred to as an "mdf" file (because of its file extension) and is created automatically from user input to the Module Builder, as described in Chapter 3, "Module Builder" on page 17. However, for very simple modules like the one in this example, it is usually easier and quicker to create the file with a text editor. Parameter names are a part of the module interface that can be seen by the user. In the graphical user interface, parameter names appear in the configuration dialog box and also serve as default names for interactors. In the scripting language, module parameters can be specified by name. Chapter 2. Writing a Simple Module 7 A new module cannot have the name of an existing Data Explorer module (see IBM Visualization Data Explorer User's Reference for a complete list). You should also be aware of the following requirements: o A Data Explorer module name must be a single alphanumeric string and its first character must be a letter. (Standard Data Explorer module names capitalize the first character of each "word" in a name, as in Attribute and AutoAxes. You may observe this convention or not, as you wish, for the modules you create.) o The module must be assigned to a tool category--in a "CATEGORY" statement in the module description file. The category can be any of those listed in the Category palette of the VPE window or a new one that you create by naming it in the statement. In the following example, the mdf file consists of five statements: MODULE Hello CATEGORY Greetings DESCRIPTION Prefixes "hello" to the input string INPUT value; string; "world"; input string OUTPUT greeting; string; prefixed string "MODULE" Specifies the module name as Hello. "CATEGORY" Assigns the module to a new, user-specified category (Greetings). "DESCRIPTION" Describes Hello's purpose: to affix "hello" to the input string. "INPUT" Assigns the name "value" to the input parameter; specifies its parameter type as "string"; specifies its default value as "world"; and describes it as an input string. "OUTPUT" Assigns the name "greeting" to the output parameter; specifies its parameter type as "string"; and describes it as a prefixed string. For details, see 11.1, "Module Description Files" on page 98. 8 IBM Visualization Data Explorer: Programmer's Reference (3) Write the module Having defined the module in a description file, you can now implement the module with a C-language function like the one shown here. 01 #include 02 03 04 Error m_Hello(Object *in, Object *out) 05 { 06 char message[30], *greeting; 07 08 if (!in[0]) 09 sprintf(message, "hello world"); 10 else { 11 DXExtractString(in[0], &greeting); 12 sprintf(message, "%s %s", "hello", greeting); 13 } 14 15 out[0] = DXNewString(message); 16 return OK; 17 } The "dx.h" file "included" in line 01 contains the definitions of all the Data Explorer library routines. The name of the function that implements a module must consist of the module name (specified in the "MODULE" statement of the description file) prefixed by "m_". In this case, the function name is "m_Hello". When Data Explorer invokes a module, it passes the module two pointers: the first to an array containing the inputs, the second to an array containing the outputs. (See 4.3, "Data Explorer Execution Model" on page 41 for details of parameter passing.) Because the input parameter of this module is passed to "m_Hello" as an array of pointers, "in[0]" is the "value" parameter. If no argument is specified for "value", "in[0]" is "NULL", and the default output ("hello world") is placed in "message". If you do specify an argument, a library routine ("DXExtractString") extracts it from "in[0]", and "greeting" becomes a pointer to that string. In line 12, "greeting" is appended to "hello," creating "message". Once "message" has been created, the "DXNewString" library routine creates a String Object for the output "out[0]". Note: The output of any Data Explorer module must be a Data Explorer Object (such as an Array, Field, or Group). Chapter 2. Writing a Simple Module 9 See Table 1 on page 118 for a complete list of Data Explorer Objects. (4) Compiling and Linking Hello... ...AS AN INBOARD MODULE: Copy the following files to the directory you want to work in: "/usr/lpp/dx/samples/program_guide/Makefile_workstation"" /usr/lpp/dx/samples/program_guide/hello.c"" /usr/lpp/dx/samples/program_guide/hello.mdf" Now rename the makefile to "Makefile" (the name of the default makefile) and enter: "make hello". This command creates an executable that contains the Hello module. To invoke this executable (from the directory to which the files were copied), enter: dx -edit -mdf ./hello.mdf -exec ./dxexec. This command starts Data Explorer (the "hello.mdf" file tells the graphical user interface about Hello and its inputs and outputs). You can now run any visual program that uses the Hello module. One such program is "hello.net" in the directory "/usr/lpp/dx/samples/program_guide". ...AS AN OUTBOARD MODULE: Copy the following files to the directory you want to work in: "/usr/lpp/dx/samples/program_guide/Makefile_workstation"" /usr/lpp/dx/samples/program_guide/hello.c"" /usr/lpp/dx/samples/program_guide/hello_outboard.mdf" Now rename the makefile to "Makefile" (the name of the default makefile) and enter: "make hello_outboard". This command creates the executable "hello_outboard". To invoke the executable (from the directory to which the files were copied), enter: dx -edit -mdf ./hello_outboard.mdf This command starts Data Explorer (the "hello_outboard.mdf" file tells the graphical user interface about Hello and its inputs and outputs). You can now run any visual program that uses the Hello module. One such program is "hello.net" in the directory "/usr/lpp/dx/samples/program_guide". 10 IBM Visualization Data Explorer: Programmer's Reference Note: The mdf file of the outboard module contains one additional statement, "OUTBOARD", which specifies the executable ("hello_outboard"; see 11.1, "Module Description Files" on page 98). This statement may also specify the name of a host on which to run the executable. MODULE Hello CATEGORY Greetings DESCRIPTION Prefixes "hello" to the input string OUTBOARD hello_outboard INPUT value; string; "world"; input string OUTPUT greeting; string; prefixed string ...AS A RUNTIME-LOADABLE MODULE: Copy the following files to the directory you want to work in: "/usr/lpp/dx/samples/program_guide/Makefile_workstation"" /usr/lpp/dx/samples/program_guide/hello.c"" /usr/lpp/dx/samples/program_guide/hello_loadable.mdf" Now rename the makefile to "Makefile" (the name of the default makefile) and enter: "make hello_loadable". This command creates the executable "hello_loadable". Note: Runtime-loadable modules are not available for SunOS 4.1 or Data General AViiON. To invoke the executable (from the directory to which the files were copied), enter: dx -edit -mdf ./hello_loadable.mdf This command starts Data Explorer (the "hello_loadable.mdf" file tells the graphical user interface about Hello and its inputs and outputs). You can now run any visual program that uses the Hello module. One such program is "hello.net" in the directory "/usr/lpp/dx/samples/program_guide". Note: The mdf file of the runtime-loadable module contains one additional statement, "LOADABLE", which specifies the executable ("hello_loadable"; see 11.1, "Module Description Files" on page 98). MODULE Hello CATEGORY Greetings DESCRIPTION Prefixes "hello" to the input string LOADABLE hello_loadable INPUT value; string; "world"; input string OUTPUT greeting; string; prefixed string Chapter 2. Writing a Simple Module 11 Including Hello in a Visual Program In this example (Figure 2), the Hello module is not given an input value and therefore uses its default string ("hello world") as output. The Echo module sends the string to Data Explorer's Message window. +-------------------------------------------------------+ | | | | +-------------------------------------------------------+ Figure 2. The Hello Module in a Visual Program. The protrusion of the upper tab indicates that the Hello module is using default input. When input is supplied through a connecting "arc," as it is to the Echo module, the input tab folds in. A visual program that produces the string "hello, how are you?" can be created by: o Using the visual program in Figure 2 and entering the string ", how are you?" as the argument of the "value" input parameter of the Hello module's configuration dialog box, or o Creating a visual program (Figure 3) in which a string interactor stand-in provides the input (previously entered in the interactor by the user). +-------------------------------------------------------+ | | | | +-------------------------------------------------------+ Figure 3. The Hello Module with a String Interactor in a Visual Program. Note that both input tabs are folded in (compare Figure 2). Using Hello in a Script In the following example, no input to Hello is provided, so the module produces its default output: a = Hello(); Echo(a); In the next three examples, the user provides input to the Hello module. All three produce the output "hello, how are you?" Example 1 12 IBM Visualization Data Explorer: Programmer's Reference b = Hello(", how are you?"); Echo(b); Example 2 b = Hello(value = ", how are you?"); Echo(b); Example 3 a = ", how are you?"; b = Hello(a); Echo(b); HELLO MODULE WITH ERROR CHECKING The definition of the Hello module (see 2.2, "Adding the Hello Module" on page 7) contains no error checking code. This omission, of course, is not a recommended practice. In the following version, the Data Explorer routine "DXSetError" reports errors to the user. 01 #include 02 03 04 m_HelloErrorChecking(Object *in, Object *out) 05 { 06 char message[30], *greeting, longmessage=NULL; 07 08 if (!in[0]) { 09 sprintf(message, "hello world"); 10 out[0] = DXNewString(message); 11 } 12 else { 13 if (!DXExtractString(in[0], &greeting)) { 14 DXSetError(ERROR_BAD_PARAMETER, "value must be a string"); 15 goto error; 16 } 17 if (strlen(greeting)<=(28-strlen("hello")) { 18 sprintf(message, "%s %s", "hello", greeting); 19 out[0] = DXNewString(message); 20 } Chapter 2. Writing a Simple Module 13 21 else { 22 longmessage = DXAllocate((strlen("hello")+strlen(greeting)+2) * sizeof(char)); 23 if (!longmessage) 24 goto error; 25 sprintf(longmessage, "%s %s", "hello", greeting); 26 out[0] = DXNewString(longmessage); 27 DXFree((Pointer)longmessage); 28 } 29 } 30 return OK; 31 32 error: 33 DXFree((Pointer)longmessage); 34 return ERROR; 35 } In this example, the return from "DXExtractString" (line 13) is checked. If the routine returns "ERROR", the error message "value must be a string" is generated and Hello returns "ERROR". The combined length of the user-supplied parameter string and "hello" is checked against the length of the buffer. If it exceeds the length, a new buffer is allocated for the output message (and freed before returning). Because "longmessage" is initialized to "NULL", it can safely be freed on error, even if it has not yet been allocated. Note: The "m_"module function should return an error code according to the Data Explorer library standard: "ERROR" for error and "OK" for successful completion. Thus the module entry point would typically be declared by: Error m_module(Object *in, Object *out); To create a version of Data Explorer that includes the HelloErrorChecking module, copy the following files to the directory you want to work in: "/usr/lpp/dx/samples/program_guide/Makefile_workstation"" /usr/lpp/dx/samples/program_guide/hello_errorchecking.c"" /usr/lpp/dx/samples/program_guide/helloerr.mdf" Now rename the makefile to "Makefile" (the name of the default makefile) and enter: "make helloerr". This command creates an executable that contains the HelloErrorChecking module. To invoke this executable (from the directory to which the files were copied), enter: 14 IBM Visualization Data Explorer: Programmer's Reference dx -edit -mdf ./helloerr.mdf -exec ./dxexec. This command starts Data Explorer (the "helloerr.mdf" file tells the graphical user interface about HelloErrorChecking and its inputs and outputs). You can now run any visual program that uses the HelloErrorChecking module. One such program is "hello_errorchecking.net" in the "/usr/lpp/dx/samples/program_guide" directory. Chapter 2. Writing a Simple Module 15 16 IBM Visualization Data Explorer: Programmer's Reference CHAPTER 3. MODULE BUILDER __________________________ 3.1 Overview . . . . . . . . . . . . . . . . . . . 18 3.2 Creating a Module with the Module Builder: A Summary . . . . . . . . . . . . . . . . . . . . . 19 3.3 Using the Module Builder: A Quick Walk Through 20 3.4 Module Builder: Menu Bar . . . . . . . . . . . 24 File Options . . . . . . . . . . . . . . . . . . 24 Edit Options . . . . . . . . . . . . . . . . . . 24 Build Options . . . . . . . . . . . . . . . . . . 24 Help Options . . . . . . . . . . . . . . . . . . 25 3.5 Module Builder: Overall Module Description . . 25 3.6 Module Builder: Individual Parameter Information Section . . . . . . . . . . . . . . . . . . . . . 27 3.7 Worker Routine . . . . . . . . . . . . . . . . 30 Positions Specification . . . . . . . . . . . . . 30 Connections Specification . . . . . . . . . . . . 31 Input Data . . . . . . . . . . . . . . . . . . . 31 Output Data . . . . . . . . . . . . . . . . . . . 31 Implementing Default Input Parameters . . . . . . 32 Worker Routine Examples . . . . . . . . . . . . . 32 (C) Copyright IBM Corp. 1991-1997 17 The Module Builder is a point-and-click interface for creating a module from user-supplied information. The next several sections describe the general structure of modules built with the Module Builder; its dialog box; and examples of the "worker routine"--the interface between a module and the user-supplied application code. 3.1 OVERVIEW _____________ From specifications supplied by the user, the Module Builder generates three files: 1. a module description file (with the extension ".mdf"); 2. a C-code framework file that implements the structure of the module; and 3. a makefile. The C-code framework file itself consists of three major routines: o The first routine checks input parameters and creates output Objects. It is named by prefixing "m_" to the module name (e.g., the entry point for a module named Example is "m_Example"). o The second routine traverses hierarchically defined data Objects. When this routine ("Traverse") encounters a Data Explorer Field Object, it calls the third routine. o The third routine ("doLeaf") creates a "worker routine" as an interface to the user's application-specific code: it extracts the input arguments, sets up the outputs, and calls the user-supplied code. (See 3.7, "Worker Routine" on page 30 and "Worker Routine Examples" on page 32.). The worker routine appears at the end of the C-code framework file. To complete a customized module, the user need only: add the application-specific code to the worker routine (after the line "User's code goes here" at the end of the C-code framework file) by: using an "include" file, or adding the application code directly to the framework file. Using an include file is recommended because (1) if you rerun the module builder, it will overwrite the ".c" file, and (2) it makes replacing your own code easy. 18 IBM Visualization Data Explorer: Programmer's Reference Notes: 1. The Module Builder is designed to accommodate the most common form of customized module, in which the output Object is a copy of the input, but the data component is modified. 2. Other inputs can be constant parameters or other hierarchically defined data Objects (note that the hierarchy of the data Objects must match exactly). 3.2 CREATING A MODULE WITH THE MODULE BUILDER: A SUMMARY _________________________________________________________ To begin a Module Builder session, enter: "dx -builder". The dialog box (Figure 4 on page 20) consists of a menu bar and two major sections: o A "Overall Module Description" section for defining the module, and o An "Individual Parameter" section for defining the individual input and output parameters. When all the necessary information has been entered, save it. For new modules, use the "Save as..." option in the "File" pull-down menu (or "Save", if the specified module name is already known to the system). The saved file has the name of the module and the extension ".mb". You can now use the options in the "Build" pull-down menu to create a module description file (".mdf"), a C-code module framework (".c"), a makefile (".make"), or all three together. You can incorporate your own application code in the C-code framework file and reference additional files in the makefile. Compile the program as follows: "make -f filename.make" This command creates a customized version of the Data Explorer executive that can use the new module. To run this version in your working directory, enter the following command: For an inboard module: dx -edit -mdf filename.mdf -exec dxexec For an outboard or runtime-loadable module: dx -edit -mdf filename.mdf Chapter 3. Module Builder 19 To create a version of the Data Explorer executive with more than one customized module, you must: 1. concatenate in a single mdf file the module descriptions you want to use; 2. create a makefile that references the combined mdf file as well as all the individual ".c" framework files. 3. compile the program as above. You can now run the new version with the new mdf file. 3.3 USING THE MODULE BUILDER: A QUICK WALK THROUGH ___________________________________________________ In this example, you will use the Module Builder to create a simple module that adds a single number to each data value of a set. Note: This function is supplied with Data Explorer as part of the "Compute" module and is used here only for purposes of illustration. 1. Start the Module Builder with the command "dx -builder". The Module Builder dialog box appears. 2. Fill in the "Overall Module Description" section as follows: "Name" Type in a name for the module (for this example, use "Add.") "Category" Select a category for the new module, either by clicking on one of the entries in the "Existing" pull-down menu or by typing in a menu name or a name of your choosing. "Description" Type in a short description of the module. This description will appear in the module's configuration dialog box (in the VPE window). "Number of inputs" Use the stepper buttons to set the value to "2." The two inputs of the new module Figure 4. Module Builder Dialog Box. In the "Individual Parameter Information" section, the "Input or Output?" button specifies the kind of parameter being defined, and the associated "Number" setting specifies its ordinal ranking (i.e., first, second, etc.). Use the "Number" stepper buttons to proceed from one parameter description to the next. 20 IBM Visualization Data Explorer: Programmer's Reference will be a data Field and the number to be added to each data value. "Number of outputs" The module generates a single output. Use the stepper buttons to set the value to "1" if that is not already the value. The output is the new Field (i.e., the data value plus the added value). "Outboard" Activate the "outboard" toggle button and type in "Add" in the "Executable Name" field. (Leave the other toggle buttons and fields as they are.) Note: In this example, the new ("outboard") module is an independent process. In contrast, an "inboard" module is compiled and incorporated as part of the Data Explorer executable; and a runtime-loadable module is compiled independently and loaded into Data Explorer at run time. 3. Fill in the "Individual Parameter Information" section as follows: "Input Number < 1 >" The first input is the data field. a. Set the button in the top-left corner of the "Individual Parameter Information" section to "Input" if that is not already the setting. b. Use the stepper buttons to set "Number" to "1" if that is not already the value. c. Enter a name for this parameter in the "Name" field (e.g., "data"). d. Enter a short description in the "Description" field. e. Confirm that the "Required" toggle button for the first input is activated. f. Confirm that the "field object" toggle button (below "Object Type") is activated. g. On the right-hand side of the "Individual Parameter Information" section, select "float" ("floating point") and "Scalar" for "Data type" and "Data shape" respectively. Chapter 3. Module Builder 21 h. Set "Positions" and "Connections" to "Not required" (information about these components is not needed). i. For this example, since the dependency of the data on positions or connections in the output Object will be the same as it was in the input Object, select "Positions or Connections". "Input Number < 2 >" The second input is the value to be added to each data value. a. Confirm that the button in the top-left corner of the "Individual Parameter Information" section is set to "Input". b. Use the stepper buttons to set "Number" to "2". c. Enter a name for this parameter in the "Name" field (e.g., "value"). d. Enter a short description in the "Description" field. e. Confirm that the "Required" toggle button is deactivated. f. Specify a default value, such as "0." g. If the default value is meant to be descriptive, activate the "Descriptive" toggle button. h. Under "Object Type", activate the "simple parameter" toggle button. i. Now activate the "Scalar" toggle button (below "Type" on the right-hand side). "Output Number < 1 >" Now describe the output of the module. a. Change "Input" to "Output" (top-left corner of the "Individual Parameter Information" section). The "Number" setting changes to "1" automatically. b. Enter a name for this parameter in the "Name" field (e.g., "result"). c. Enter a short description in the "Description" field. d. Confirm that the "field object" toggle button (below "Object Type") is activated. e. Confirm that "Data type" and "Data Shape" are set to "float" and "Scalar" respectively. 22 IBM Visualization Data Explorer: Programmer's Reference f. Confirm that "Dependency" is set to "Positions or connections". You can now create the necessary files: a. Click on "Build" in the dialog box menu bar and select "Create All" in the pull-down menu. The Module Builder creates three files for the Add module: "Add.c", "Add.mdf", and "Add.make". b. To insert the necessary user-specific code in "Add.c", use an editor. Look for the phrase "User's code goes here" at the bottom of the file, and type in the following: int i; float value; if (value_knt==0) value = 0; else value = value_data[0]; for (i=0; i= 0 && ((i % (c_counts[1]-1)) != 0)) { output_data[neighbor]+=input_data[i]; itemcounts[neighbor]++; } Chapter 7. Working with Connections 61 neighbor = i+1; if (neighbor < input_knt &&(((i+1)%(c_counts[1]-1)) != 0)) { output_data[neighbor]+=input_data[i]; itemcounts[neighbor]++; } /* now do neighbors in the slowest-varying dimension */ neighbor = i - (c_counts[1]-1); if (neighbor >= 0) { output_data[neighbor]+=input_data[i]; itemcounts[neighbor]++; } neighbor = i + (c_counts[1]-1); if (neighbor < input_knt) { output_data[neighbor]+=input_data[i]; itemcounts[neighbor]++; } } /* now divide by the number of items added for that cell */ for (i=0; i< input_knt; i++) output_data[i] = output_data[i]/itemcounts[i]; DXFree((Pointer)itemcounts); return OK; error: DXFree((Pointer)itemcounts); return ERROR; } The file "/usr/lpp/dx/samples/program_guide/averagecell.c" contains a completed version of this program. (7) To create a version of Data Explorer that includes the AverageCell module, enter the command: make -f averagecell.make dxexec (You have now created an executable that contains the AverageCell module.) (8) To invoke this version, enter: dx -edit -mdf ./averagecell.mdf -exec ./dxexec This command starts Data Explorer (the "averagecell.mdf" file tells the graphical user interface about AverageCell and its inputs and outputs). The executable dxexec invoked here is the one created in Step 6. (9) With this version of Data Explorer you can now run any visual program that uses the AverageCell module. One 62 IBM Visualization Data Explorer: Programmer's Reference such program is "/usr/lpp/dx/samples/program_guide/averagecell.net" Chapter 7. Working with Connections 63 64 IBM Visualization Data Explorer: Programmer's Reference CHAPTER 8. IMPORTING DATA __________________________ 8.1 Writing a Filter . . . . . . . . . . . . . . . 66 8.2 Writing an Import Module . . . . . . . . . . . 69 (C) Copyright IBM Corp. 1991-1997 65 If you want to import data that is not in a format supported by Data Explorer, you have three options: o Write an import filter to convert the data to Data Explorer or General Array importer format on disk. o Write an import filter to convert the data to Data Explorer or General Array header format on standard output, and use the external filter option of Import to import the data. (See "Import" on page 212 in IBM Visualization Data Explorer User's Reference.) o Write your own import module to read the data and create a Data Explorer Object as its output (e.g., a Field Object). Notes: 1. The following examples illustrate the conversion of data from Hierarchical Data Format (HDF) to Data Explorer file format. Understanding the examples does not require any familiarity with HDF. 2. HDF libraries are not distributed with Data Explorer and no makefiles are provided for the programs used. If you have the HDF libraries, you can use the same compilation and linking procedures as you do for other programs requiring those libraries. 3. The Import module will import HDF data. The example in 8.2, "Writing an Import Module" on page 69 is for illustration only. 8.1 WRITING A FILTER _____________________ The filters used to create a Data Explorer format file on disk and on standard output are essentially the same. Assume a single data set of scalar data stored in an HDF file. All HDF files are gridded. The dimensionality and size of the grid are to be determined from queries to the data set. The following C program requires the HDF file name as an argument. It is found in "/usr/lpp/dx/samples/program_guide/simpleimportfilter.c" . 01 02 03 #include "df.h" is a necessary include file for HDF library routines. 66 IBM Visualization Data Explorer: Programmer's Reference 04 #include 05 06 #define MAXRANK 3 07 08 main(argc, argv) 09 char *argv[]; 10 { 11 FILE *in; 12 char filename[80]; 13 int dims, counts[MAXRANK], numelements, i, j; 14 float deltas[MAXRANK*MAXRANK], origins[MAXRANK], *databuf=NULL; 15 Check that the user has supplied the name of the file to be opened. 16 if (argc < 2) { 17 fprintf(stderr,"Usage: simpleimportfilter \n"); 18 return 0; 19 } 20 21 strcpy(filename, argv[1]); 22 } The HDF library routine "DFishdf" checks the file for accessibility and for the correct (HDF) format. If the file is not accessible or is not an HDF file, the routine generates an error message. 23 if (DFishdf(filename) != 0) { 24 fprintf(stderr, 25 "file \"%s\" is not accessible, or is not an hdf file\n", 26 filename); 27 return 0; 28 } Initialize the HDF library. 29 DFSDrestart(); The HDF library routine "DFSDgetdims" returns the dimensionality of the grid (1D, 2D, etc.) in "dims". The number of positions in each dimension is returned in the Array "counts". 30 DFSDgetdims(filename, &dims, counts, MAXRANK); Determine the number of elements in the data Array. 31 numelements=1; 32 for (i=0; i " df.h " is a necessary include file for HDF library routines. Chapter 8. Importing Data 69 02 #include 03 04 #define MAXRANK 3 05 06 Error m_SimpleImport(Object *in, Object *out) 07 { 08 Array a=NULL; 09 Field f=NULL; 10 char *filename; 11 int dims, counts[MAXRANK], numelements, i, j; 12 float deltas[MAXRANK*MAXRANK], origins[MAXRANK], *data; Extract the file name from "in[0]", and check that it is a string. 13 if (!in[0]) { 14 DXSetError(ERROR_BAD_PARAMETER,"missing filename"); 15 goto error; 16 } 17 else if (!DXExtractString(in[0], &filename)) { 18 DXSetError(ERROR_BAD_PARAMETER, "filename must be a string"); 19 goto error; 20 } The HDF library routine "DFishdf" checks the file for accessibility and for the correct (HDF) format. If the file is not accessible or is not an HDF file, the routine generates an error message. 21 if (DFishdf(filename) != 0) { 22 DXSetError(ERROR_BAD_PARAMETER, 23 "file \"%s\" is not accessible, or is not an hdf file", 24 filename); 25 goto error; 26 } 27 Initialize the HDF library. 28 DFSDrestart(); The HDF library routine "DFSDgetdims" returns the dimensionality of the grid (1D, 2D, etc.) in "dims". The number of positions in each dimension is returned in the Array "counts". 29 DFSDgetdims(filename, &dims, counts, MAXRANK); Make a new Array (scalar). 30 a = DXNewArray(TYPE_FLOAT, CATEGORY_REAL, 0); 31 if (!a) 32 goto error; 70 IBM Visualization Data Explorer: Programmer's Reference Determine the number of elements in the data Array. 33 numelements=1; 34 for (i=0; i 02 #include "pick.h" 03 04 static Error DoPick(Object, Object, RGBColor, int, int, int, int); 05 static Error SetColor(Object, RGBColor); 06 07 Error m_ShowPick(Object *in, Object *out) 08 { 09 Object o = NULL, pickfield; 10 char *colorstring; 11 int colorwhich, poke, pick, depth; 12 RGBColor color; Copy the structure of "in[0]", the object in which picking took place. 13 if (!in[0]) { 14 DXSetError(ERROR_BAD_PARAMETER, "missing input"); 15 goto error; 16 } 17 o = (Object)DXCopy(in[0], COPY_STRUCTURE); 18 if (!o) 19 goto error; First, set all the colors to white, to initialize. (The SetColor routine is defined below.) 20 if (!SetColor(o, DXRGB(1.0, 1.0, 1.0))) 21 goto error; "in[1]" is the pick Field. If the pick Field is "NULL" or an empty Field, just return the copy of the object. 22 if (!in[1] || DXEmptyField(in[1])) { 23 out[0] = o; 24 return OK; 25 } 26 pickfield = in[1]; Get the color that will be used for picked Objects, which is "in[2]". 27 if (in[2]) { 28 if (!DXExtractString((Object)in[2], &colorstring)) { 29 DXSetError(ERROR_BAD_PARAMETER,"color must be a string"); 30 goto error; 31 } Convert the color name to an RGB vector. 76 IBM Visualization Data Explorer: Programmer's Reference 32 33 if (!DXColorNameToRGB(colorstring, &color)) 34 goto error; 35 } 36 else { If "in[2]" is not specified, then the default color is red. 37 color = DXRGB(1.0, 0.0, 0.0); 38 } Determine if we are to color just the picked element, just the vertex closest to the picked point, or the entire Field. The default is to color just the picked element. 39 if (!in[3]) { 40 colorwhich = 0; 41 } 42 else { 43 if (!DXExtractInteger(in[3], &colorwhich)) { 44 DXSetError(ERROR_BAD_PARAMETER,"colorwhich flag must be 0, 1, or 2"); 45 goto error; 46 } 47 if ((colorwhich < 0)&&(colorwhich > 2)) { 48 DXSetError(ERROR_BAD_PARAMETER,"colorwhich flag must be 0, 1, or 2"); 49 goto error; 50 } 51 } Determine if we are to select a particular poke, or all of them. The default is to select all of them. 52 53 if (!in[4]) { 54 poke = -1; 55 } 56 else { 57 if (!DXExtractInteger(in[4], &poke)) { 58 DXSetError(ERROR_BAD_PARAMETER,"poke must be a nonnegative integer"); 59 goto error; 60 } 61 if (poke < 0) { 62 DXSetError(ERROR_BAD_PARAMETER,"poke must be a nonnegative integer"); 63 goto error; 64 } 65 } Determine if we are to select a particular pick, or all of them. The default is to select all of them. Chapter 9. Using the Pick Structure 77 66 if (!in[5]) { 67 pick = -1; 68 } 69 else { 70 if (!DXExtractInteger(in[5], &pick)) { 71 DXSetError(ERROR_BAD_PARAMETER,"pick must be a nonnegative integer"); 72 goto error; 73 } 74 if (pick < 0) { 75 DXSetError(ERROR_BAD_PARAMETER,"pick must be a nonnegative integer"); 76 goto error; 77 } 78 } Determine if we are to select a depth. The default is to select the deepest level. 79 if (!in[6]) { 80 depth = -1; 81 } 82 else { 83 if (!DXExtractInteger(in[6], &depth)) { 84 DXSetError(ERROR_BAD_PARAMETER,"depth must be a nonnegative integer"); 85 goto error; 86 } 87 if (depth < 0) { 88 DXSetError(ERROR_BAD_PARAMETER,"depth must be a nonnegative integer"); 89 goto error; 90 } 91 } Traverse the picked object, using the pick structure, passing the given parameters. 92 if (!DoPick(o, pickfield, color, colorwhich, poke, pick, depth)) 93 goto error; Delete the "opacities" component. 94 if (DXExists(o, "opacities")) 95 DXRemove(o,"opacities"); Successful return. 96 out[0] = o; 97 return OK; Return on error. 98 error: 99 DXDelete(o); 100 return ERROR; 101 } 78 IBM Visualization Data Explorer: Programmer's Reference The "DoPick()" routine traverses the picked object. 102 static 103 Error 104 DoPick(Object o, Object pickfield, RGBColor color, int colorwhich, 105 int pokes, int picks, int depth) 106 { 107 int pokecount, pickcount, poke, pick, i, pathlength; 108 int vertexid, elementid, *path, numitems, index; 109 Object current; 110 Matrix matrix; 111 Array a, newcolors=NULL, oldcolors; 112 char *depatt; 113 RGBColor *newcolors_ptr, oldcolor; 114 int pokemin, pokemax; 115 int pickmin, pickmax; 116 int thisdepth; "pickfield" is expected to be a Field. 117 if (!(DXGetObjectClass(pickfield)==CLASS_FIELD)) { 118 DXSetError(ERROR_INVALID_DATA,"pickfield must be a field"); 119 goto error; 120 } Find out the number of pokes. 121 DXQueryPokeCount(pickfield, &pokecount); The user has chosen to mark all pokes. 122 if (pokes < 0) { 123 pokemin = 0, pokemax = pokecount-1; 124 } The user has specified a poke larger than the number present. 125 else if (pokes > pokecount-1) { 126 DXSetError(ERROR_BAD_PARAMETER, 127 "only %d pokes are present", pokecount); 128 return ERROR; 129 } Consider only the specified poke. 130 else 131 pokemin = pokemax = pokes; For each poke... 132 for (poke=pokemin; poke<=pokemax; poke++) { Find out how many picks there are in this poke. Chapter 9. Using the Pick Structure 79 133 if (!DXQueryPickCount(pickfield, poke, &pickcount)) 134 goto error; Issue warning if this particular poke does not contain as many picks as the user has specified. 135 if (picks > pickcount-1) { 136 DXWarning("poke %d contains only %d picks", poke, pickcount); 137 } 138 139 else { 140 if (picks < 0) { 141 pickmin = 0, pickmax = pickcount-1; 142 } 143 else { 144 pickmin = pickmax = picks; 145 } For each pick... 146 147 for (pick=pickmin; pick<=pickmax; pick++) { For the given "pickfield", the current poke number, and the current pick number, get the traversal path "path", the length of the traversal path "pathlength", and the IDs of the picked element and the picked vertex. 148 DXQueryPickPath(pickfield, poke, pick, &pathlength, &path, 149 &elementid, &vertexid); Initialize "current" to the picked object, and "matrix" to the identity matrix. 150 current = o; 151 matrix = Identity; 152 if (depth != -1 && pathlength > depth) 153 thisdepth = depth; 154 else 155 thisdepth = pathlength; Iterate through the pick path. 156 for (i=0; i= numitems) { 189 DXSetError(ERROR_INVALID_DATA, 190 "pick structure does not correspond to picked object"); 191 goto error; 192 } Get the original colors component. 193 oldcolors = DXGetComponentValue((Field)current, "colors"); Chapter 9. Using the Pick Structure 81 If it is a constant Array, we need to expand it so that we can set just one element or vertex to the given color. 194 if (DXQueryConstantArray(oldcolors, NULL, &oldcolor)) { Create a new colors Array and allocate space to it. 195 newcolors = DXNewArray(TYPE_FLOAT,CATEGORY_REAL, 1, 3); 196 if (!DXAddArrayData(newcolors, 0, numitems, NULL)) 197 goto error; Start by setting all colors to the original constant color. 198 newcolors_ptr = (RGBColor *)DXGetArrayData(newcolors); 199 for (i=0; i 02 03 static Error DoAdd(Object o, float x); 04 05 m_AddParallel(Object *in, Object *out) 06 ¤ 07 Object o = NULL; 08 float x; Copy the structure of "in[0]". 09 if (!in[0]) 10 DXErrorGoto(ERROR_BAD_PARAMETER, "missing object"); 11 o = DXCopy(in[0], COPY_STRUCTURE); 12 if (!o) 13 goto error; Extract floating-point parameter from "in[1]" (default 0). 14 if (!in[1]) 15 x = 0; 16 else if (!DXExtractFloat(in[1], &x)) 17 DXErrorGoto(ERROR_BAD_PARAMETER, "bad addend"); Create the task Group, call "DoAdd()" for recursive traversal, and then execute the task Group. 18 DXCreateTaskGroup(); 19 if (!DoAdd(o, x)) { 20 DXAbortTaskGroup() 21 goto error; 22 } 23 if (!DXExecuteTaskGroup()) 24 goto error; A successful return or return on error. 25 out[0] = o; 26 return OK; 27 28 error: 29 DXDelete(o); 30 return ERROR; 31 ‡ 32 33 The argument block for passing parameters to the task routine: Chapter 10. Writing Modules for a Parallel Environment 87 34 struct arg ¤ 35 Field field; 36 float x; 37 ‡ The following task routine does the actual work of processing a Field. "DXAddTask" instructs the executive to call this routine once for each Field. The executive will pass to "task" the argument block pointer that was specified when "DXAddTask" itself was called. 01 02 static Error 03 task(Pointer p) 04 ¤ 05 struct arg *arg = (struct arg *)p; 06 Field field; 07 float x, *from, *to; 08 int i, n; 09 Array a; Extract the arguments. 10 field = arg->field; 11 x = arg->x; Extract, typecheck, and get the data from the "data" component. 12 a = (Array) DXGetComponentValue(field, "data"); 13 if (!a) 14 DXErrorReturn(ERROR_MISSING_DATA, "field has no data"); 15 if (!DXTypeCheck(a, TYPE_FLOAT, CATEGORY_REAL, 0)) 16 DXErrorReturn(ERROR_BAD_TYPE, "data is not floating point"); 17 from = (float *) DXGetArrayData(a); Create a new Array, allocate space to it, and put it in the Field. 18 DXGetArrayInfo(a, &n, NULL, NULL, NULL, NULL); 19 a = DXNewArray(TYPE_FLOAT, CATEGORY_REAL, 0); 20 if (!DXAddArrayData(a, 0, n, NULL)) 21 return ERROR; 22 to = (float *) DXGetArrayData(a); 23 DXSetComponentValue(field, "data", (Object)a); The following loop adds "x" to obtain the result. 24 for (i=0; i 02 03 static Error DoAverageCell(Object); 04 05 06 07 Error m_AverageCellParallel(Object *in, Object *out) 08 { 09 Object o=NULL; 10 11 if (!in[0]) { 12 DXSetError(ERROR_BAD_PARAMETER,"missing input"); 13 goto error; 14 } 15 16 o = DXCopy(in[0], COPY_STRUCTURE); "Grow" the Fields so that averaging can be performed across partition boundaries. Since it is not necessary to grow a Field beyond the original boundaries of the data, and since only the "data" component is affected, grow the partition by one cell. (The original components--"positions," "data," etc.--are copied into components named "original positions," "original data," and so on.) 17 if (!DXGrow(o, 1, GROW_NONE, "data", NULL)) 18 goto error; Create the task Group. 19 if (!DXCreateTaskGroup()) 20 goto error; The add tasks will be added in "DoAverageCell()". 21 if (!DoAverageCell(o)) { 22 DXAbortTaskGroup(); 23 goto error; 24 } 25 26 if (!DXExecuteTaskGroup()) 27 goto error; Do not call "DXShrink" to shrink the grown Field until you have recursively removed any "original data" component(s), assuming that you want to save the newly created one(s). Otherwise the new "data" component(s) will be replaced by the (unprocessed) "original data" components(s). Now you can call "DXShrink". Chapter 10. Writing Modules for a Parallel Environment 91 28 if (DXExists(o, "original data")) 29 DXRemove(o,"original data"); 30 if (!DXShrink(o)) 31 goto error; 32 33 out[0] = o; 34 return OK; 35 error: 36 DXDelete((Object)o); 37 return ERROR; 38 } 39 40 struct arg { 41 Field field; 42 }; 43 44 static Error AddCellTask(Pointer p) 45 { 46 struct arg *arg = (struct arg *)p; 47 int i, j, numitems, shape, *neighbors_ptr, sum, neighbor; 48 int dim, counts[3]; 49 char *attribute; 50 float *data_ptr, *newdata_ptr, dataaverage; 51 Array connections, data, newdata=NULL, neighbors; 52 Field field; 53 54 field = arg->field; 55 Get the connections component; determine the number of connections and their element type. 56 57 connections = (Array)DXGetComponentValue(field,"connections"); 58 if (!connections) { 59 DXSetError(ERROR_MISSING_DATA,"input has no connections"); 60 goto error; 61 } 62 if (!DXGetArrayInfo(connections, &numitems, NULL, NULL, NULL, NULL)) { 63 goto error; 64 } 65 if (!(attribute= 66 (char *)DXGetString((String)DXGetComponentAttribute(field, 67 "connections", 68 "element type")))) { 69 DXSetError(ERROR_MISSING_DATA, 70 "missing connection element type attribute"); 71 goto error; 72 } 73 74 Get the data component, and get the data dependency attribute. 92 IBM Visualization Data Explorer: Programmer's Reference 75 data = (Array)DXGetComponentValue(field,"data"); 76 if (!data) { 77 DXSetError(ERROR_MISSING_DATA,"input has no data"); 78 goto error; 79 } 80 if (!(attribute= 81 (char *)DXGetString((String)DXGetComponentAttribute(field, 82 "data", 83 "dep")))) { 84 DXSetError(ERROR_MISSING_DATA, 85 "missing data dependency attribute"); 86 goto error; 87 } 88 In this example, the data must be dependent on the connections. 89 if (strcmp(attribute,"connections")) { 90 DXSetError(ERROR_INVALID_DATA, 91 "data must be dependent on connections"); 92 goto error; 93 } 94 For this example, the data must be floating-point scalar. 95 if (!DXTypeCheck(data, TYPE_FLOAT, CATEGORY_REAL, 0, NULL)) { 96 DXSetError(ERROR_INVALID_DATA, "data must be floating point scalar"); 97 goto error; 98 } Get a pointer to the data. 99 data_ptr = (float *)DXGetArrayData(data); 100 Make a new data component, allocate space in it, and get a pointer to it. 101 newdata = DXNewArray(TYPE_FLOAT,CATEGORY_REAL, 0); 102 if (!DXAddArrayData(newdata, 0, numitems, NULL)) 103 goto error; 104 newdata_ptr = (float *)DXGetArrayData(newdata); 105 If the data is ungridded, use the neighbors component. If it is gridded, use a different method. 106 if (!DXQueryGridConnections(connections, &dim, counts)) { 107 Now the program needs the neighbors of the connections. Note that neighbors can be obtained only for ungridded Chapter 10. Writing Modules for a Parallel Environment 93 data: for gridded data there are more efficient ways to determine neighbors. 108 neighbors = DXNeighbors(field); 109 if (!neighbors) 110 goto error; 111 neighbors_ptr = (int *)DXGetArrayData(neighbors); 112 if (!DXGetArrayInfo(neighbors, NULL, NULL, NULL, NULL, &shape)) 113 goto error; 114 115 116 for (i=0; i 0) { 142 neighbor = i-1; 143 dataaverage = dataaverage + data_ptr[neighbor]; 144 sum++; 145 } 94 IBM Visualization Data Explorer: Programmer's Reference 146 if ((i % (counts[1]-1)) < (counts[1] - 2)) { 147 neighbor = i+1; 148 dataaverage = dataaverage + data_ptr[neighbor]; 149 sum++; 150 } 151 neighbor = i-(counts[1]-1); 152 if (neighbor>=0 && neighbor=0 && neighbor