Functions Introduced:

The functions in this section enable you to access a set of programming utilities in general use within Creo Parametric. The utilities fill a need that is common in C and Pascal programming—to provide a storage method that provides the advantages of an array, but without its limitations.

When you use an array for storage for a group of items, you have the advantage over a linked list in that the members are contiguous in memory. This enables you to access a given member using its index in the array. However, if you need to make frequent additions to the members in a way that cannot be predicted (a common situation in MCAE applications), you must reallocate the memory for the array each time.

A common compromise is to allocate the memory in blocks large enough to contain several array members, then reallocate the memory only when a block becomes full. You would choose the size of the blocks such that the frequency of reallocation is significantly reduced, while the amount of unused memory in the last block is acceptably small. The difficulty of this solution is that you would normally need a new set of utilities for each item you want to store as an array, and additional static data for each array to keep track of the number of blocks and the number of members.

The “expandable array” utilities provide a set of functions that can be applied to items of any size. The utilities do this by keeping a private header at the start of the array memory to which the “bookkeeping” information (the number and size of its members, and of the blocks) is written. The pointer your application sees is the address of the first block, not the address of the preceding header.

The importance of the expandable array utilities in a Creo TOOLKIT application is not only that you can use them for your own arrays, but that you must use them for arrays of data passed between your application and the internals of Creo Parametric through the Creo TOOLKIT functions.

Note that because the array pointer is not the start of the contiguous memory claimed by the array utility, this pointer is not recognized by the operating system as a valid location for dynamic memory. Therefore, you will cause a fatal error if you try to use the memory management library functions, such as realloc() and free().

The basic type used for referring to expandable arrays is ProArray, declared as a void*.

The function ProArrayAlloc() sets up a new expandable array. Its inputs are as follows:

The function outputs a pointer to the contiguous memory that will contain the array members. You can write to that memory to fill the array using the usual memory functions (such as memcpy() and memset()). If you increase the array size beyond the limit returned by ProArrayMaxCountGet(), this function returns an out-of-memory message.

The maximum memory allocated is 2 MB, except for 64–bit platforms where the maximum is twice that.

The function ProArrayFree() releases the memory for the specified ProArray.

The function ProArraySizeGet() tells you how many members are currently in the specified array.

The ProArraySizeSet() function enables you to change the number of members in the expandable array. This function is equivalent to realloc().

Function ProArrayMaxCountGet(), when given the specified structure size in bytes, returns the maximum number of structure elements a ProArray can support for that structure size.

The function ProArrayObjectAdd() adds a contiguous set of new members to an array, though not necessarily to the end of the array. The function also sets the contents of the new members. If you increase the array size beyond the limit returned by ProArrayMaxCountGet(), this function returns an out-of-memory message.

The function ProArrayObjectRemove() removes a member from the array. The member does not necessarily have to be the last member of the array.

Functions ProArraySizeSet(), ProArrayObjectAdd(), and ProArrayObjectRemove() change the size of the array, and might therefore also change its location.

The Creo TOOLKIT functions use expandable arrays in the following circumstances:

An example of the first type of function is the geometry function ProEdgeVertexdataGet(), which provides a list of the edges and surfaces that meet at a specified solid vertex. When you have finished using the output, you should free the arrays of edges and surfaces (using the function ProArrayFree()).

An example of the second type of function is ProSolidNoteCreate(), which creates a design note in a solid. Because the text lines to add to the note are passed in the form of an expandable array, your application must create and fill the array using the functions ProArrayAlloc() and ProArrayObjectAdd() before you call ProSolidNoteCreate().

An example of the third type of function is ProElementChildrenGet(), which gets the number of feature elements that are the children of the specified compound element. The feature elements form a tree that contains all the necessary information about a particular feature. (This function is therefore used in both feature analysis and feature creation.) Before calling ProElementChildrenGet(), you must call ProArrayAlloc() to create an empty array. You can then use ProArraySizeGet() to find out how many elements were added to the array.

There is a fourth case, which is a variation of the first, in which a Creo TOOLKIT function creates an expandable array as its output the first time it is called in an application, but overwrites the same array on subsequent calls. An example of this is ProSelect(), whose output array of ProSelection structures must not be freed using ProArrayFree(). You must also make sure to copy the contents of the array if you need to use it to make another call to ProSelect().

The conventions are chosen for each function according to its individual needs. For example, ProElementChildrenGet() is typically called in a recursive loop to traverse a tree, so the fourth method of allocation would be inconvenient.

The rules for each Creo TOOLKIT function are documented in the browser.