This chapter describes general requirements for the coding of your user-defined data types.
|
|
|
The code that supports a user-defined data type or SQL function runs as part of the DBMS Server and is available to the entire installation. The DBMS Server, Recovery, and Archiver processes access this code after the code has been properly installed.
Important! A bug in your code—a memory access violation, in particular—can damage the integrity of data or the operating environment of the DBMS Server.
|
|
|
The routines that you write must be written in a language which conforms to the calling and operational conventions of the C language. If you use a language other than C, be sure that the structures you build have the same structure, on a field-by-field basis, as those defined in the header file, IIADD.H. For the location of this header file, see the chapter "Introducing Object Management Extension."
To avoid problems, your code must follow these guidelines:
The code must not make any system calls or perform any other operation, such as generating exceptions or signals, which alter the flow of control within the server.
The code must not perform any operations such as memory allocations or operations such as disk I/O, which cause the process to be suspended.
The code must perform only computations on the data provided by the DBMS Server.
User-defined data types are visible only to the DBMS Server. When a user-defined data type is returned to an Ingres tool such as Query-By-Forms, the DBMS Server must convert your new data type to a standard SQL data type. To specify the external data type, use the dbtoev routine. For more information, see dbtoev in the "Defining the Data Type" chapter.
|
|
|
When you define a new data type, you must also define the coercion routines that support the data type. The following coercion routines are required:
This coercion routine is used by the DBMS Server in variety of instances, for example, during retrieve into and create table as select statements or when changing the length of a data type.
User interface applications do not accept user-defined data types directly. Therefore, you must provide a coercion routine to convert your data type to a standard SQL data type for external representation. This coercion routine must be compatible with the input coercion routine as follows:
The output of this coercion routine must be acceptable as input to the input coercion routine. The output of the input coercion routine must be acceptable as input to this coercion routine.
An example of a coercion routine for converting from an internal to an external representation is shown here:
sprintf(obuffer, "(%11.3f, %11.3f)", point.x,point.y);
This coercion must convert data coming from an SQL insert or update query to internal representation. Data represented as character strings in Embedded SQL is sent to the DBMS Server as the varchar data type. At least one input coercion routine, which converts varchar to your data type, is required. The input coercion routine must be compatible with the external coercion routine as follows:
The output of this coercion routine must be acceptable as input to the output coercion routine. The output of the output coercion routine must be acceptable as input to this coercion routine.
An example of a coercion routine for converting from an external to an internal representation is shown here:
sscanf(inbuffer, "(%F, %F%1s %1s", &point.x, &point.y,
end_paren,junk);
This data type is similar to varchar but is used in different contexts. For example, it is used to display data from various utility programs, such as auditdb.
|
|
|
You must assign an identification number to all data types, functions, and function instances when they are created. The ID numbers for each type of object (data types, functions, and function instances) occupy a number space that is unique for that object type. An object's ID must be unique within the same class of objects, but does not have to be unique across object classes. For example, a new data type cannot have an ID that is the same as another data type, but it can have an ID number that is the same as a new function's ID number.
Note: For upward compatibility, make identification numbers for all objects unique across machines.
Identification numbers are stored in system catalogs in databases. You cannot change an ID number without first removing all references to both the ID and the object it represents from the catalogs. All tables, views, database procedures, grants, permits, integrities, and rules that refer to the object must also be destroyed.
Following are the ranges of values that are reserved for IDs and the corresponding data types:
SQL data types: 1 to 8191
Spatial data types: 8192 to 16383
User-defined data types: 16384 to 32767
|
|
|
When you use the SQL copy statement with user-defined data type, be aware of the following points:
|
|
|
Object Management Extension allows you to create data types that can accommodate objects that exceed the size limits for native data types. These objects are called large objects or peripheral objects. The name peripheral object indicates that these objects are stored outside of the table in which they are declared.
Large objects are stored as a number of segments, each of which is of some simple and small data type. This type is called the underlying data type for the large object. See Structure IIADD_DT_DFN Fields. Operations performed on large objects generally operate on a segment at a time.
Large objects can be up to two gigabytes in size. The code does not attempt to materialize the entire object in memory—rather, large objects are represented in memory using the II_PERIPHERAL data structure. The II_PERIPHERAL structure contains two fields. The first field is the tag and it contains the "style" of the large object. The style can be either real data or coupon. If the tag is seen by the Object Management Extension routines, the value indicates that the large object is a coupon. The coupon status indicates that only the information necessary to find and collect the object is present. At other times during the tag's life, it can contain different values, but these are not seen by the Object Management Extension code. (For example, the tag can have a variety of values that indicate how it is transmitted across the communication link.) The second field contains the length of the object. This field is an eight byte integer, although only four bytes are currently used (per_length1).
Large objects cannot be used as table keys, do not have histograms computed, and cannot be sorted. You must specify these restrictions as data type attributes along with the PERIPHERAL attribute at the time the data type is declared. See the dtd_attributes field in Structure IIADD_DT_DFN Fields.
Because of these restrictions, only a few of the required functions are necessary for peripheral objects. Only the length_check, getempty, tmlen, tmcvt, dbtoev, seglen, value_check, and xform routines must be provided. However, these attributes are independent from the peripheral attribute in the sense that the lack of histogram capability can be specified for non-peripheral objects. If so specified, the histogram routines need not be provided.