Storing External Data
Functions Introduced:
The first step in manipulating external data for a model in a 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).
Consider this information about slots:
• Slot names cannot begin with a number.
• If you do not specify a slot name or pass
NULL for the input argument
slot_name in
ProExtdataSlotCreate()), the slot name will be internally managed to be unique to avoid overwriting the slot data.
• If the slot data type is
PRO_CHAPTER_TYPE, the following is true: If you pass a valid string value for the input argument
slot_name in
ProExtdataSlotCreate()), then the slot is created under Global workspace and not in the individual Class workspaces. Hence, you should pass a unique slot name that is not used anywhere across all the classes. For example, you can append the class name to the slot name to make it unique.
• Although class and slot names are individually restricted to a length of
PRO_NAME_SIZE, they must also have a combined length shorter than
PRO_NAME_SIZE—2. If you try to use combined names longer than
PRO_NAME_SIZE—2, the function
ProExtdataSlotCreate() returns the error
PROEXTDATA_TK_NAMES_TOO_LONG.
The function
ProExtdataSlotWrite() specifies the slot data type and writes an item of that type to the slot. The inputs are:
• The slot object ProExtdataSlot
• A flag showing whether the slot is identified by name or integer
• The data type of the slot
• The number of bytes in the data. Specify this argument only when the data type is stream or section.
• A pointer to the data (cast to void*)
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 section.
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.
|
Note:
|
ProExtdataTerm() does not affect the contents of any file on the disk. It only removes all external data from the memory. Changes made to external data during the current session are not stored in the file until you save the model. If you call ProExtdataTerm() after making changes to the model, all external data changes (such as newly created slots, changed slot value, and deleted slot) made since the last ProMdlSave() are lost.
|