Introducing Object Management Extension

This chapter introduces Object Management Extension and outlines the general tasks you must perform to add data types and functions to Ingres.

What Is Object Management Extension?

Object Management Extension is an option that enables you to add data types and SQL functions to the DBMS Server.

You can use a user-defined data type in any context in which you can use a standard Ingres data type, including with Ingres Star. You can use user-defined SQL functions in queries to manipulate both user-defined data types and standard SQL data types. To support your new data types and functions, you can add new capabilities to existing SQL comparison and arithmetic operators.

Structure and Symbol Definitions

You must write all the code that defines and manipulates your new data types. The header file, IIADD.H, which you can include in your C program, contains the structure and symbol definitions that the DBMS Server requires. IIADD.H is located in the following directories:

Windows: %II_SYSTEM%\ingres\files\iiadd.h

UNIX: $II_SYSTEM/ingres/files/iiadd.h

VMS: II_SYSTEM:[INGRES.FILES]IIADD.H

Demonstration Data Types

Object Management Extension includes two demonstration data types:

• ord_pair

  This demo creates an ordered pair data type, which consists of a simple pair of x and y coordinates. The code is located in the following files:

  Windows: %II_SYSTEM%\ingres\demo\udadts\op.c

  UNIX: $II_SYSTEM/ingres/demo/udadts/op.c

  VMS: II_SYSTEM:[INGRES.DEMO.UDADTS]OP.C

• int_list

  This demo creates a data type consisting of a variable-length list of 4-byte integers. The code is located in the following files:

  Windows: %II_SYSTEM%\ingres\demo\udadts\intlist.c

  UNIX: $II_SYSTEM/ingres/demo/udadts/intlist.c

  VMS: II_SYSTEM:[INGRES.DEMO.UDADTS]INTLIST.C

How You Add Data Types and Functions

To add data types and functions you must:

• Write the code that tells the DBMS Server what the new data type or function is and how to manipulate it
• Install the code in a test installation and debug the code
• Install the code in the target installation

Required Contents of the Code

You must write the code that the DBMS Server uses to manipulate a new data type or SQL function. This code consists of

• Data type or function definition
• Function instance definitions
• Required coercion routines

Data Type Definitions

A data type definition consists of:

• Name of the data type
• Internal data type identifier (a 2-byte integer)
• Data type status flags
• An underlying data type (if necessary)
• Routines required by the DBMS Server to manipulate the data type

Function Definitions

A function definition specifies the names of the functions that are used to invoke operations. The definition of a function consists of:

• Function name
• Function identifier (a 2-byte integer)
• Type of operation invoked by the function

Function Instance Definitions

A function instance definition defines the use of a function or operator in a particular context. Because the same function can be used differently with different data types, each instance of use must be defined. For example, different function instances exist for the + operator: one to add integers, one to concatenate text, one to add money, and so on.

When you are defining a new data type, you must also define a function instance for each function or operator that you use with the new data type. If, for example, you want to add two values of the new data type, you must first define a function instance for the + operator used with the new data types. When you define a new SQL function, you must define a function instance for its use with each data type with which it is used.

The definition of a function instance is composed of:

• Function instance identifier (a 2-byte integer)
• Function instance complement identifier (if this instance is a comparison)
• Operator or function identifier for which this is an instance
• Operator type
• Function instance status flags
• Number of arguments and their data types
• Workspace length
• Data type of the result
• Length of the result
• Address of the routine that performs the instance

Note: Object Management Extension does not allow you to redefine the use of the standard operators with existing SQL data types and functions. If you try to do this, you do not receive an error, but the code is ignored.

Coercion Routines

You must provide the data type coercion routines that support your new data type. For a list and discussion of the required coercion routines, see the chapter "User-Defined Data Types and the DBMS Server Environment."

Installation and Testing of the New Code

After you have written all of the routines necessary to define and manipulate the new data types and functions, you must create the routine IIudadt_register.

Windows: After IIudadt_register is created, you must rebuild the OIUDTNT.DLL. The IIudadt_register function serves as the entry point to the OIUDTNT Dynamic Linked Library that gives the DBMS Server access to the new data types and functions.

UNIX: After IIudadt_register is created, you must relink the images to give the DBMS Server access to the new data types and functions.

VMS: IIudadt_register serves as the entry point to the shared image that the various components of the DBMS Server use to access the new data types and functions.

For information about these steps in the procedure, see the chapter "Passing Definitions to the DBMS Server" and the chapter "Installing and Testing Data Types."

Install your new code in a test installation and test it thoroughly before moving it to the target installation.

Object Management Extension Restrictions

The following restrictions apply to Object Management Extension:

• You can add a maximum of 128 new data types.
• You cannot export user-defined data types from the DBMS Server.

For this reason, the Ingres user interfaces (such as Query-By-Forms or Report-By-Forms) cannot manipulate user-defined data types in their "natural" state. You must choose a standard SQL data type to represent the new data types for the user interface programs and write the necessary coercion routines.

Note: The copy statement allows the byte representation of the data to be exported. However, copy handles this data as char. To avoid errors caused by network character translation, avoid moving the data to a different machine using Ingres Net.