IBM Informix User-Defined Routines and Data Types Developer's Guide
Total Page:16
File Type:pdf, Size:1020Kb
Informix Product Family Informix Version 12.10 IBM Informix User-Defined Routines and Data Types Developer's Guide SC27-4536-00 Informix Product Family Informix Version 12.10 IBM Informix User-Defined Routines and Data Types Developer's Guide SC27-4536-00 Note Before using this information and the product it supports, read the information in “Notices” on page B-1. This document contains proprietary information of IBM. It is provided under a license agreement and is protected by copyright law. The information contained in this publication does not include any product warranties, and any statements provided in this publication should not be interpreted as such. When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. © Copyright IBM Corporation 1996, 2013. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Introduction .................................vii About this publication ...............................vii Types of users .................................vii Software dependencies ..............................vii Assumptions about your locale............................vii Demonstration databases .............................viii Example code conventions ..............................viii Additional documentation ..............................ix Compliance with industry standards ...........................ix How to provide documentation feedback .........................ix Chapter 1. Extend the database server......................1-1 Create user-defined routines .............................1-1 Extend built-in data types ..............................1-1 Extend operators .................................1-2 Build opaque data types ...............................1-2 Extend operator classes ...............................1-3 Routine management ................................1-3 Chapter 2. A user-defined routine ........................2-1 User-defined routines ................................2-1 SPL routines ..................................2-1 External-language routines .............................2-1 Information about user-defined routines ........................2-2 Tasks that you can perform with user-defined routines ....................2-2 Extend data type support .............................2-3 Support user-defined data types ...........................2-4 Create an end-user routine.............................2-10 Invoke a user-defined routine............................2-12 Chapter 3. Run a user-defined routine ......................3-1 Invoke a UDR in an SQL statement ...........................3-1 Invoke a UDR with an EXECUTE statement .......................3-1 Invoke a user-defined function in an expression ......................3-2 Invoke a function that is bound to an operator ......................3-2 Named parameters and UDRs ............................3-2 Invoke a UDR in an SPL routine ............................3-3 Execute a user-defined routine .............................3-3 Parse the SQL statement ..............................3-3 Optimize the SQL statement ............................3-3 Execute a UDR across databases of the same database server instance ..............3-3 Execute the routine ...............................3-4 Understanding routine resolution ............................3-7 The routine signature ...............................3-7 Routine overloading ...............................3-8 The routine-resolution process ...........................3-10 Routine resolution with user-defined data types .....................3-13 Null arguments in overloaded routines ........................3-16 Chapter 4. Develop a user-defined routine ....................4-1 Plan the routine..................................4-1 Name the routine ................................4-1 Define routine parameters .............................4-2 Return values .................................4-3 © Copyright IBM Corp. 1996, 2013 iii Name return parameters ..............................4-5 An iterator function ...............................4-6 Adhere to coding standards ............................4-13 Write the routine .................................4-14 Create a user-defined interface for XA data sources ....................4-14 Registering a user-defined routine ...........................4-15 Privileges required to create a routine .........................4-16 Create an SPL routine ..............................4-17 Create an external-language routine .........................4-19 Review information about user-defined routines .....................4-22 A UDR with HDR ................................4-23 Chapter 5. Extend data types ..........................5-1 Understanding the data type system ...........................5-1 Understanding data types ..............................5-2 Built-in data types ................................5-2 Extended data types ...............................5-5 Extend the data type system .............................5-7 Operations ..................................5-8 Casts ....................................5-8 Operator classes ................................5-8 Optimizer information ..............................5-9 Chapter 6. Extend operators and built-in functions ................6-1 Operators and operator functions ............................6-1 Arithmetic operators ...............................6-1 Text operators .................................6-2 Relational operators ...............................6-2 Overload an operator function ............................6-3 Built-in functions .................................6-3 Built-in functions that you can overload ........................6-3 Built-in functions that you cannot overload .......................6-4 Overload a built-in function ............................6-5 Chapter 7. Create user-defined casts ......................7-1 Understanding casts ................................7-1 Built-in casts ..................................7-1 User-defined casts ................................7-1 Casts that you cannot create ............................7-2 Create a user-defined cast ..............................7-2 Choose the kind of user-defined cast..........................7-2 Choose the cast mechanism .............................7-3 Define the direction of the cast............................7-5 Drop a cast ...................................7-6 Chapter 8. Create user-defined aggregates ....................8-1 Extend existing aggregates ..............................8-1 Overload operators for built-in aggregates ........................8-1 Extending a built-in aggregate ............................8-2 Example of extending a built-in aggregate ........................8-2 Create user-defined aggregates.............................8-3 Support functions ................................8-3 Resolve the support functions ............................8-6 Support-function states ..............................8-6 Using C or Java support functions ..........................8-7 Example of a user-defined aggregate..........................8-7 Manage aggregates ................................8-9 Parallel execution of aggregates ...........................8-9 Privileges for user-defined aggregates .........................8-10 Aggregate information in the system catalog.......................8-10 iv IBM Informix User-Defined Routines and Data Types Developer's Guide Aggregate information from the command line ......................8-10 Drop an aggregate ................................8-10 Chapter 9. Create an opaque data type .....................9-1 Opaque data types.................................9-1 The internal structure ...............................9-1 Support functions ................................9-2 Advantages of opaque data types...........................9-3 Creating an opaque data type .............................9-4 Create the internal structure in C ...........................9-4 Creating UDT-to-Java mappings ...........................9-6 Write and register the support functions ........................9-6 Register the opaque data type with the database......................9-6 Grant privileges for an opaque data type ........................9-8 Create SQL-invoked functions ............................9-9 Customize access methods..............................9-12 The generic B-tree ...............................9-13 Other access methods ..............................9-13 Other operations on opaque data types .........................9-14 Access an opaque data type ............................9-14 Drop an opaque data type .............................9-14 Chapter 10. Write support functions ......................10-1 Write support functions...............................10-1 Identify support functions .............................10-1 Choose function parameters ............................10-3 Set privileges for support functions ..........................10-4 Data types for support functions............................10-4 The LVARCHAR data type ............................10-5 The SENDRECV data type.............................10-5 Handle the external representation ...........................10-5 Input support function ..............................10-6 Output support function .............................10-7 Handle the internal representation ...........................10-8 The send and receive