Defining an Opaque Type
To define a new opaque data type to the database server, you must provide the following information in the C or Java™ language.
About this task
- A data structure that serves as the internal storage of the opaque
data type
The internal storage details of the type are hidden, or opaque. Once you define a new opaque data type, the database server can manipulate it without knowledge of the C or Java structure in which it is stored.
- Support functions that allow the database server to interact with
this internal structure.
The support functions tell the database server how to interact with the internal structure of the data type. These support functions must be written in the C or Java programming language.
- Additional user-defined functions that other support functions
or end users can invoke to operate on the opaque type (optional)
Possible support functions include operator functions and cast functions. Before you can use these functions in SQL statements, they must be registered with the appropriate CREATE CAST, CREATE PROCEDURE, or CREATE FUNCTION statement.
| Function | Description | Invoked |
|---|---|---|
| input( ) | Converts the opaque type from its external LVARCHAR representation to its internal representation | When a client application sends a character representation of the opaque type in an INSERT, UPDATE, or LOAD statement |
| output( ) | Converts the opaque type from its internal representation to its external LVARCHAR representation | When the database server sends a character representation of the opaque type as a result of a SELECT or FETCH statement |
| receive( ) | Converts the opaque type from its internal representation on the client computer to its internal representation on the server computer Provides platform-independent results regardless of differences between client and server computer types | When a client application sends an internal representation of the opaque type in an INSERT, UPDATE, or LOAD statement |
| send( ) | Converts the opaque type from its internal representation on the server computer to its internal representation on the client computer Provides platform-independent results regardless of differences between client and database server computer types | When the database server sends an internal representation of the opaque type as a result of a SELECT or FETCH statement |
| db_receive( ) | Converts the opaque type from its internal representation on the local database to the dbsendrecv type for transfer to an external database on the local server | When a local database receives a dbsendrecv type from an external database on the local database server |
| db_send( ) | Converts the opaque type from its internal representation on the local database to the dbsendrecv type for transfer to an external database on the local server | When a local database sends a dbsendrecv type to an external database on the local database server |
| server_receive( ) | Converts the opaque type from its internal representation on the local server computer to the srvsendrecv type for transfer to a remote database server Use any name for this function. | When the local database server receives a srvsendrecv type from a remote database server |
| server_send( ) | Converts the opaque type from its internal representation on the local server computer to the srvsendrecv type for transfer to a remote database server Use any name for this function. | When the local database server sends a srvsendrecv type to a remote database server |
| import( ) | Performs any tasks needed to convert from the external (character) representation of an opaque type to the internal format for a bulk copy | When DB-Access (LOAD) or the High Performance Loader (HPL) initiates a bulk copy from a text file to a databaseWhen DB-Access (LOAD) initiates a bulk copy from a text file to a database |
| export ( ) | Performs any tasks needed to convert from the internal representation of an opaque type to the external (character) format for a bulk copy | When DB-Access (UNLOAD) or the High Performance Loader initiates a bulk copy from a database to a text fileWhen DB-Access (UNLOAD) initiates a bulk copy from a database to a text file |
| importbinary( ) | Performs any tasks needed to convert from the internal representation of an opaque type on the client computer to the internal representation on the server computer for a bulk copy | When DB-Access (LOAD) or the High Performance Loader initiates a bulk copy from a binary file to a database |
| exportbinary( ) | Performs any tasks needed to convert from the internal representation of an opaque type on the server computer to the internal representation on the client computer for a bulk copy | When DB-Access (UNLOAD) or the High Performance Loader initiates a bulk copy from a database to a binary file |
| assign( ) | Performs any processing required before storing the opaque type to disk This support function must be named assign( ). | When the database server executes INSERT, UPDATE, or LOAD, before it stores the opaque type to disk |
| destroy( ) | Performs any processing necessary before removing a row that contains the opaque type This support function must be named destroy( ). | When the database server executes the DELETE or DROP TABLE, before it removes the opaque type from disk |
| lohandles( ) | Returns a list of the LO-pointer structures (pointers to smart large objects) in an opaque type | When the database server must search opaque types for references to smart large objects; when oncheck runs, or an archive is performed |
| compare( ) | Compares two values of the opaque type and returns an integer value to indicate whether the first value is less than, equal to, or greater than the second value | When the database server encounters an ORDER BY, UNIQUE, DISTINCT, or UNION clause in a SELECT statement, or when CREATE INDEX creates a B-tree index |
After you write the necessary support functions for the opaque type, use the CREATE FUNCTION statement to register these support functions in the same database as the opaque type. Certain support functions convert other data types to or from the new opaque type. After you create and register these support functions, use the CREATE CAST statement to associate each function with a particular cast. The cast must be registered in the same database as the support function.
After you have written the necessary C language or Java language source code to define an opaque data type, you then use the CREATE OPAQUE TYPE statement to register the opaque data type in the database.