The assign and destroy routines

The Assign() function performs tasks before saving an opaque data type to disk. The C name for each opaque data type is OpaqueAssign(). The Destroy() procedure performs tasks before saving an opaque data type to disk. The C name for each opaque data type is OpaqueDestroy().

BladeSmith generates complete C code for Assign() and Destroy() routines that manage large object reference counts. For other types of special processing, you must add code to the generated code.
Important: If you use text input and output functions for smart large objects, you must define Assign() and Destroy() routines to prevent runtime errors from the database server.

The generated code

The HCL OneDB™ database server calls the Assign() function with a pointer to an instance of an opaque type and a pointer to an MI_FPARAM structure that is not used by the generated code. The function returns a pointer to the opaque type to the database server. Usually, the pointer returned by the Assign() function is the same one the HCL OneDB database server passed to it. If the Assign() function alters the input opaque type in any way and returns a pointer to it, the database server stores the modified value in the database.

The HCL OneDB database server calls the Destroy() procedure before removing an opaque type from the database. It passes the Destroy() procedure a pointer to the opaque type value that is about to be removed from the database and an unused MI_FPARAM pointer. The procedure returns no value.

Customize the code

If your opaque data type does not contain a smart large object, you must add code to perform the required task.

Smart large object considerations

If your opaque data type contains a smart large object, then the generated Assign() function manages smart large object reference counts. It calls mi_lo_validate() to determine if a valid large object exists and mi_lo_increfcount() to increment the reference count for the large object.

The Destroy() procedure calls mi_lo_validate() for each large object. For valid large objects, it calls mi_lo_decrefcount() to decrement the reference count for the large object.

Examples

The following example DataBlade® modules use Assign() and Destroy() routines for smart large object processing:
  • Strings DataBlade module
  • MMXImage DataBlade module

The MultiRep DataBlade module uses the Assign() function to determine whether to put the multi-representational opaque type in the database table or in a smart large object, depending on its size. The Destroy() procedure removes the reference counts to smart large objects, but has not effect on in-row data.

The Creating Distinct Types and Casts exercise in the tutorial uses the Assign() function for the FTemp (representing Fahrenheit degrees) and CTemp (representing Celsius degrees) distinct data types to prevent a user from entering a temperature value below absolute zero.