External data provides a way for the Creo TOOLKIT application to store its own private information about a Creo Parametric model within the model file. The data is built and interrogated by the Creo TOOLKIT application as a workspace data structure. It is saved to the model file when the model is saved, and retrieved when the model is retrieved. The external data is otherwise ignored by Creo Parametric, so the Creo TOOLKIT application has complete control over the form and content.

The external data for a particular Creo Parametric model is broken down into classes and slots. A class is a named “bin” for your data, and simply identifies it as yours so no other Creo TOOLKIT application (or other classes in your own application) will use it by mistake. A Creo TOOLKIT application usually needs only one class. The class name should be unique for each model, and describe the role of the data in your application.

Each class contains a list of data slots. Each slot is identified by either a name or an identifier, and contains a single data item of one of the following types:

Stream and chapter slots could also be used as a shortcut way to store, for instance, an entire C structure, or an array of C structures, without any formatting. However, if you are supporting more than one platform with your Creo TOOLKIT application, remember that the mapping of a C structure may differ between platforms.

If external data is stored during a Creo Parametric session on one platform and retrieved on another, the values of integer, double, and wide string slots will be preserved correctly, regardless of any differences in the coding of those data types by the two C compilers. Stream and chapter slots will be preserved with exactly the same byte values and sequence that was saved, regardless of byte-swap conventions on the two platforms.

External data is stored in the workspace and is accessible only through the functions provided for that purpose. Two objects are used to reference the data contents: ProExtdataClass and ProExtdataSlot. These are both declared as DHandles—visible data structures. The declarations are as follows:

     typedef struct pro_extdata_class
     {
       ProMdl   p_model;
       ProName  class_name;
     } ProExtdataClass;
     
     typedef struct pro_extdata_slot
     {
       ProExtdataClass *p_class;
       ProName         slot_name;
       int             slot_id;
     } ProExtdataSlot;

Each slot has two ways to be identified: a name, which is defined by the application when the slot is created, or an identifier, which is allocated automatically. You can choose which kind of identifier to use for each slot. The Creo TOOLKIT functions for external data do not use the usual return type ProError. Instead, they use an enumerated type called ProExtdataErr that contains error statuses that are more specific to the needs of those functions. All the declarations relevant to external data are in the header file ProExtdata.h.

Functions Introduced:

The first step in manipulating external data for a model in a Creo Parametric session is to call the initialize function ProExtdataInit() for that model.

Next, set up a class using the function ProExtdataClassRegister(). The inputs are the ProMdl object and the class name, in the form of a wide string. The function outputs a ProExtdataClass used thereafter by the application to reference the class.

You can delete a class that is no longer needed using the function ProExtdataClassUnregister().

The function ProExtdataSlotCreate() creates an empty data slot. The inputs are the ProExtdataClass object and the slot name, in the form of a wide string. The function outputs a ProExtdataSlot object to identify the new slot. You can use NULL as the value of the slot name argument, in which case the function allocates a unique integer identifier for the slot (which becomes the value of the field slot_id in the ProExtdataSlot structure).

The function ProExtdataSlotWrite() specifies the slot data type and writes an item of that type to the slot. The inputs are:

A slot of type stream has a maximum size of 512 kilobytes. If this size is exceeded, ProExtdataSlotWrite() returns the status PROEXTDATA_TK_STREAM_TOO_LARGE. For data of size larger than 512 kilobytes, use the slot of type chapter.

You can delete an unused slot using the function ProExtdataSlotDelete().

If the user and application no longer need external data in session, call ProExtdataTerm() to clean the external data from memory.

Functions Introduced:

For improved performance, external data is not loaded automatically into memory with the model. When the model is in session, call the function ProExtdataLoadAll() to retrieve all the external data for the specified model from the Creo Parametric model file and put it in the workspace. The function needs to be called only once to retrieve all the data.

Note that the function ProExtdataLoadAll() provides better performance than ProExtdataClassNamesList(), ProExtdataSlotNamesList(), and ProExtdataSlotRead() because these functions load only specific information (class names, slot names, and slot files, respectively), which can be slow.

The ProExtdataClassNamesList() function provides an array of the names of all the external data classes registered in a specified model.

The function ProExtdataSlotIdsList() provides an array of the integer identifiers of all the slots in a specified class. The input is a ProExtdataClass structure that must be set up manually or programmatically. The function ProExtdataSlotNamesList() provides an array of the names of the slots in the specified class. The function allocates a term in the array for each slot, even if you did not assigned a name to the slot.

The function ProExtdataSlotRead() reads the data type and data from a specified slot. Its input is a ProExtdataSlot structure that must be set up manually. There is also an input argument to show whether the slot is identified by name or by integer. The function outputs the data type, the number of bytes (if the data type is stream or chapter), and a pointer to the data itself.

The ProExtdataSlotRead() function allocates memory for the data it outputs. To free this memory, call ProExtdataFree().