API Calls for C Programmers: agl Routines

C and C++ programmers can use the following API calls (aglxxxx routines) to incorporate the Array Viewer in their applications:

It is the nature of these APIs that typically you will call them in roughly the same sequence.

First, you call aglAlloc, aglMalloc or aglMallocEx to allocate memory to hold your data. Then you place data into that memory. Note that this produces and populates a one-dimensional array. This will always be the state of your array initially.

If you want your data to be multi-dimensional, you must call aglReshape to recategorize the array as one with the desired number of dimensions and with each dimension of the desired size. Even though aglReshape does not move any data, it does reclassify the array as one having the desired structure.

At any time until you return the array's memory to the system, you can save the array by calling aglSaveAsFile. This API saves the files in the Array Graphic Language (.AGL) format.

From here, displaying the data requires two calls. First, you must call aglStartWatch to alert Array Visualizer that the array has been through the required preliminary steps and is now ready to be displayed. The Array Visualizer places the array in a special class of ready-to-show arrays.

Next, by calling aglShow, the Array Visualizer launches a new instance of the Array Viewer program, with the data in it. At this point, the you see your data and can manipulate the data as desired.

If you want the title bar of the instance of Array Viewer to contain particular information, you can call aglName to place the appropriate text onto the title bar. Make this call any time after the call to aglReshape and before the first call to aglShow.

After the initial call to aglShow, you can make the instance of Array Viewer invisible by calling aglHide and then, if desired, call aglShow again.

One reason to hide and then reshow an instance of Array Viewer is to call aglReshape to alter how the data displays. For example, if the array is 8x3, you could change it to 6x4. Note that the new shape must contain exactly the same number of elements as the previous shape.

When it is time to stop displaying the data, call aglClose to shut down the instance of Array Viewer. Then call aglEndWatch to remove the array from the ready-to-show list.

Finally, call aglFree to return the allocated memory.

You can use aglGetShareName to get a string identifier that identifies the shared memory region associated with an array.

You can also call the CaViewer Class Routines to perform tasks usually done interactively by the user.

Samples of these routines are provided online in folders in  ...\ArrayVisualizer\Samples\C\. For a description of the Array Visualizer Samples, view the file ...\ArrayVisualizer\Samples\Samples.htm in a Web browser. Most Samples include a project workspace file, which allows you to open and build the project in the visual devlopment environment.

Samples are installed on the hard disk when a Complete installation is performed. You can copy Samples folders from the Array Visualizer CD-ROM to your hard disk (remove the read-only file property).