Introduction to External Data
This section describes how to store and retrieve external data. External data is a Creo TOOLKIT application to be stored in the Creo+ database in a way that is invisible to the Creo+ user.
External data provides a way for the Creo TOOLKIT application to store its own private information about a Creo+ 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+, so the Creo TOOLKIT application has complete control over the form and content.
The external data for a particular Creo+ 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:
• Integer
• Double
• Wide string (maximum length = 512 characters)
• Stream (maximum size = 512 kilobytes). A slot of type stream contains a completely unformatted sequence of bytes with unrestricted values. The slot also records the number of bytes in the stream, so no termination rules are assumed. The stream type should be used only when the format is completely controlled by your application in a platform-independent way. For example, if the volume of external data is very large, the stream format might be used to store the data in a more compressed form for greater efficiency.
• section. The section data type is similar to the stream data. It has the following advantages as compared to stream data type:
◦ section data type has no limit on data length.
◦ The name of the slot is used as the name of the section.
Stream and section 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+ 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 section 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.