External Data
This chapter explains using External Data in the VB API.
External Data
This chapter describes how to store and retrieve external data. External data enables a the VB API application to store its own data in a Creo Parametric database in such a way that it is invisible to the Creo Parametric user. This method is different from other means of storage accessible through the Creo Parametric user interface.
Introduction to External Data
External data provides a way for the Creo Parametric application to store its own private information about a Creo Parametric model within the model file. The data is built and interrogated by the 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; the application has complete control over form and content.
The external data for a specific Creo Parametric model is broken down into classes and slots. A class is a named ‘‘bin’’ for your data, and identifies it as yours so no other Creo Parametric API application (or other classes in your own application) will use it by mistake. An application usually needs only one class. The class name should be unique for each application and describe the role of the data in your application.
Each class contains a set of data slots. Each slot is identified by an identifier and optionally, a name. A slot contains a single data item of one of the following types:
The VB API Type
Data
EpfcEXTDATA_INTEGER
integer
EpfcEXTDATA_DOUBLE
double
EpfcEXTDATA_STRING
string
The the VB API interfaces used to access external data in Creo Parametric are:
The VB API Type
Data Type
IpfcExternalDataAccess
This is the top level object and is created when attempting to access external data.
IpfcExternalDataClass
This is a class of external data and is identified by a unique name.
IpfcExternalDataSlot
This is a container for one item of data. Each slot is stored in a class.
IpfcExternalData
This is a compact data structure that contains either an integer, double or string value.
Compatibility with Creo TOOLKIT
the VB API and Creo TOOLKIT share external data in the same manner. the VB API external data is accessible by Creo TOOLKIT and the reverse is also true. However, an error will result if the VB API attempts to access external data previously stored by Creo TOOLKIT as a stream.
Accessing External Data
Methods Introduced:
  • IpfcModel.AccessExternalData()
    		•
  • IpfcModel.TerminateExternalData()
    		•
  • IpfcExternalDataAccess.IsValid()
    		•
    The method IpfcModel.AccessExternalData() prepares Creo Parametric to read external data from the model file. It returns the IpfcExternalDataAccess object that is used to read and write data. This method should be called only once for any given model in session.
    The method IpfcModel.TerminateExternalData() stops Creo Parametric from accessing external data in a model. When you use this method all external data in the model will be removed. Permanent removal will occur when the model is saved.
    Note
    If you need to preserve the external data created in session, you must save the model before calling this function. Otherwise, your data will be lost.
    The method IpfcExternalDataAccess.IsValid() determines if the IpfcExternalDataAccess object can be used to read and write data.
    Storing External Data
    Methods and Properties Introduced:
  • IpfcExternalDataAccess.CreateClass()
    		•
  • IpfcExternalDataClass.CreateSlot()
    		•
  • IpfcExternalDataSlot.Value
    		•
    The first step in storing external data in a new class and slot is to set up a class using the method IpfcExternalDataAccess.CreateClass(), which provides the class name. The method outputs IpfcExternalDataClass, used by the application to reference the class.
    The next step is to use IpfcExternalDataClass.CreateSlot() to create an empty data slot and input a slot name. The method outputs a IpfcExternalDataSlot object to identify the new slot.
    Note
    Slot names cannot begin with a number.
    The property IpfcExternalDataSlot.Value specifies the data type of a slot and writes an item of that type to the slot. The input is a IpfcExternalData object that you can create by calling any one of the methods in the next section.
    Example code
    The sample code in the file pfcExternalDataExamples.vb located at <creo_vbapi_loadpoint>/vbapi_examples demonstrates the usage of external data. It provides utility methods to convert a VB hashtable to a model's external data.
    Initializing Data Objects
    Methods Introduced:
  • CMpfcExternal.CreateIntExternalData()
    		•
  • CMpfcExternal.CreateDoubleExternalData()
    		•
  • CMpfcExternal.CreateStringExternalData()
    		•
    These methods initialize a IpfcExternalData object with the appropriate data inputs.
    Retrieving External Data
    Methods and Properties Introduced:
  • IpfcExternalDataAccess.LoadAll()
    		•
  • IpfcExternalDataAccess.ListClasses()
    		•
  • IpfcExternalDataClass.ListSlots()
    		•
  • IpfcExternalData.discr
    		•
  • IpfcExternalData.IntegerValue
    		•
  • IpfcExternalData.DoubleValue
    		•
  • IpfcExternalData.StringValue
    		•
    For improved performance, external data is not loaded automatically into memory with the model. When the model is in session, call the method IpfcExternalDataAccess.LoadAll() to retrieve all the external data for the specified model from the Creo Parametric model file and put it in the workspace. The method needs to be called only once to retrieve all the data.
    The method IpfcExternalDataAccess.ListClasses() returns a sequence of IpfcExternalDataClasses registered in the model. The method IpfcExternalDataClass.ListSlots() provide a sequence of IpfcExternalDataSlots existing for each class.
    To find out a data type of a IpfcExternalData, call IpfcExternalData.discr and then call one of these properties to get the data, depending on the data type:
    •  IpfcExternalData.IntegerValue
    •  IpfcExternalData.DoubleValue
    •  IpfcExternalData.StringValue
    Example Code
    The sample code in the file pfcExternalDataExamples.vb located at <creo_vbapi_loadpoint>/vbapi_examples demonstrates the usage of external data. It provides utility methods to convert a VB hashtable to a model's external data.
    Exceptions
    Most exceptions thrown by external data methods in the VB API extend IpfcXExternalDataError, which is a subclass of IpfcXToolkitError.
    An additional exception thrown by external data methods is IpfcXBadExternalData. This exception signals an error accessing data. For example, external data access might have been terminated or the model might contain stream data from Creo TOOLKIT.
    The following table lists these exceptions.
    Exception
    Cause
    IpfcXExternalDataInvalidObject
    Generated when a model or class is invalid.
    IpfcXExternalDataClassOrSlotExists
    Generated when creating a class or slot and the proposed class or slot already exists.
    IpfcXExternalDataNamesTooLong
    Generated when a class or slot name is too long.
    IpfcXExternalDataSlotNotFound
    Generated when a specified class or slot does not exist.
    IpfcXExternalDataEmptySlot
    Generated when the slot you are attempting to read is empty.
    IpfcXExternalDataInvalidSlotName
    Generated when a specified slot name is invalid.
    IpfcXBadGetExternalData
    Generated when you try to access an incorrect data type in a IpfcExternalData object.