Home | Previous Page | Next Page

Contents

In This Introduction

About This Manual

Software Dependencies

Assumptions About Your Locale

Demonstration Databases

New Features in Dynamic Server, Version 10.0

Features from Previous Versions

Function Syntax Conventions

DataBlade API Module Code Conventions

Documentation Conventions

Typographical Conventions

Feature, Product, and Platform Markup

Syntax Diagrams

Example Code Conventions

Additional Documentation

IBM Informix Information Center

Installation Guides

Informix Error Messages

IBM Informix Dynamic Server Version 10.0 and CSDK Version 2.90 Documentation Set

Compliance with Industry Standards

IBM Welcomes Your Comments

DataBlade API Overview

Using the DataBlade API

In This Chapter

DataBlade API Module

User-Defined Routine (Server)

Client LIBMI Application

Compatibility of Client and Server DataBlade API Modules

DataBlade API Components

Public Data Types

Regular Public Functions

Advanced Features (Server)

Internationalization of DataBlade API Modules (GLS)

Accessing SQL Data Types

In This Chapter

Type Identifiers

Type Descriptors

Type-Structure Conversion

Data Type Descriptors and Column Type Descriptors

Character Data Types

The mi_char1 and mi_unsigned_char1 Data Types

The mi_char and mi_string Data Types

The mi_lvarchar Data Type

Character Data in a Smart Large Object

Character Processing

Varying-Length Data Type Structures

Using a Varying-Length Structure

Managing Memory for a Varying-Length Structure

Accessing a Varying-Length Structure

Byte Data Types

The mi_bitvarying Data Type

Byte Data in a Smart Large Object

Byte Processing

Boolean Data Types

Boolean Text Representation

Boolean Binary Representation

Pointer Data Types (Server)

Simple Large Objects

The MI_DATUM Data Type

Contents of an MI_DATUM Structure

Address Calculations with MI_DATUM Values

Uses of MI_DATUM Structures

The NULL Constant

NULL-Valued Pointer

Data Manipulation

Using Numeric Data Types

In This Chapter

Integer Text Representation

Integer Binary Representations

Fixed-Point Data

Fixed-Point Text Representations

Fixed-Point Binary Representations

Transferring Fixed-Point Data (Server)

Converting Decimal Data

Performing Operations on Decimal Data

Obtaining Fixed-Point Type Information

Floating-Point Data

Floating-Point Text Representation

Floating-Point Binary Representations

Transferring Floating-Point Data (Server)

Converting Floating-Point Decimal Data

Obtaining Floating-Point Type Information

Formatting Numeric Strings

Using Date and Time Data Types

In This Chapter

Date Text Representation

Date Binary Representation

Transfers of Date Data (Server)

Conversion of Date Representations

Operations on Date Data

Date-Time or Interval Data

Date-Time or Interval Text Representation

Date-Time or Interval Binary Representation

The datetime.h Header File

Retrieval and Insertion of DATETIME and INTERVAL Values

Transfers of Date-Time or Interval Data (Server)

Conversion of Date-Time or Interval Representations

Operations on Date and Time Data

Functions to Obtain Information on Date and Time Data

Using Complex Data Types

In This Chapter

Collection Text Representation

Collection Binary Representation

Creating a Collection

Opening a Collection

Accessing Elements of a Collection

Releasing Collection Resources

The listpos( ) UDR

Row-Type Text Representation

Row-Type Binary Representation

Creating a Row Type

Accessing a Row Type

Copying a Row Structure

Releasing Row Resources

Using Smart Large Objects

In This Chapter

Understanding Smart Large Objects

Parts of a Smart Large Object

Information About a Smart Large Object

Storing a Smart Large Object in a Database

Valid Data Types

Access to a Smart Large Object

Using the Smart-Large-Object Interface

Smart-Large-Object Data Type Structures

Smart-Large-Object Functions

Creating a Smart Large Object

Obtaining the LO-Specification Structure

Choosing Storage Characteristics

Initializing an LO Handle and an LO File Descriptor

Writing Data to a Smart Large Object

Storing an LO Handle

Freeing Resources

Sample Code to Create a New Smart Large Object

Accessing a Smart Large Object

Selecting the LO Handle

Opening a Smart Large Object

Reading Data from a Smart Large Object

Freeing a Smart Large Object

Sample Code to Select an Existing Smart Large Object

Modifying a Smart Large Object

Updating a Smart Large Object

Altering Storage Characteristics

Obtaining Status Information for a Smart Large Object

Obtaining a Valid LO File Descriptor

Initializing an LO-Status Structure

Obtaining Status Information

Freeing an LO-Status Structure

Deleting a Smart Large Object

Managing the Reference Count

Freeing LO File Descriptors

Converting a Smart Large Object to a File or Buffer

Using Operating-System Files

Using User-Defined Buffers

Converting an LO Handle Between Binary and Text

Binary and Text Representations of an LO Handle

DataBlade API Functions for LO-Handle Conversion

Transferring an LO Handle Between Computers (Server)

Using Byte-Range Locking

Passing a NULL Connection (Server)

Database Access

Handling Connections

In This Chapter

Understanding Session Management

Client Connection

UDR Connection (Server)

Connection Descriptor

Initializing a Client Connection

Using Connection Parameters

Using Database Parameters

Using Session Parameters

Setting Connection Parameters for a Client Connection

Establishing a Connection

Establishing a UDR Connection (Server)

Establishing a Client Connection

Associating User Data with a Connection

Initializing the DataBlade API

Closing a Connection

Executing SQL Statements

In This Chapter

Executing SQL Statements

Choosing a DataBlade API Function

Executing Basic SQL Statements

Executing Prepared SQL Statements

Executing Multiple SQL Statements

Processing Statement Results

Executing the mi_get_result( ) Loop

Example: The get_results( ) Function

Retrieving Query Data

Obtaining Row Information

Obtaining Column Information

Retrieving Rows

Obtaining Column Values

Completing Execution

Finishing Execution

Interrupting Execution

Inserting Data into the Database

Assembling an Insert String

Sending the Insert Statement

Processing Insert Results

Using Save Sets

Creating a Save Set

Inserting Rows into a Save Set

Building a Save Set

Freeing a Save Set

Executing User-Defined Routines

In This Chapter

Accessing MI_FPARAM Routine-State Information

Checking Routine Arguments

Accessing Return-Value Information

Saving a User State

Obtaining Other Routine Information

Calling UDRs Within a DataBlade API Module

Invoking a UDR Through an SQL Statement

Calling a UDR Directly (Server)

Named Parameters and UDRs

Calling UDRs with the Fastpath Interface

Obtaining a Function Descriptor

Obtaining Information from a Function Descriptor

Executing the Routine

Using a User-Allocated MI_FPARAM Structure

Releasing Routine Resources

Obtaining Trigger Execution Information and HDR Database Server Status

Trigger Information

HDR Status Information

Handling Exceptions and Events

In This Chapter

DataBlade API Event Types

Event-Handling Mechanisms

Invoking a Callback

Using Default Behavior

Callback Functions

Declaring a Callback Function

Writing a Callback Function

Database Server Exceptions

Understanding Database Server Exceptions

Providing Exception Handling

Returning Error Information to the Caller

Handling Multiple Exceptions

Raising an Exception

State-Transition Events

Understanding State-Transition Events

Providing State-Transition Handling

Client LIBMI Errors

Working with XA-Compliant External Data Sources

3 3

Overview of Integrating XA-Compliant Data Sources in Transactions

3 3

Support for the Two-Phase Commit Protocol

3 3

XA-Compliant Data Sources and Data Source Types

3 3

Infrastructure for Creating Support Routines for XA Routines

3 3

Global Transaction IDs

3 3

System Catalog Tables

3 3

Files Containing Necessary Components

3 3

Creating User-Defined XA-Support Routines

3 3

The xa_open( ) function

3 3

The xa_close( ) function

3 3

The xa_start( ) function

3 3

The xa_end( ) function

3 3

The xa_prepare( ) function

3 3

The xa_rollback( ) function

3 3

The xa_commit( ) function

3 3

The xa_recover( ) function

3 3

The xa_forget( ) function

3 3

The xa_complete( ) function

3 3

Dropping an XA Support User-Defined Routine

3 3

Managing XA Data Sources and Data Source Types

3 3

Creating an XA Data Source Type

3 3

Dropping an XA Data Source Type

3 3

Creating an XA Data Source

3 3

Dropping an XA Data Source

3 3

Registering and Unregistering XA-Compliant Data Sources

3 3

Using ax_reg( )

3 3

Using ax_unreg( )

3 3

Using mi_xa_register_xadatasource( )

3 3

Using mi_xa_unregister_xadatasource( )

3 3

Getting the XID Structure

3 3

Getting the Resource Manager ID

3 3

Monitoring Integrated Transactions

Creating User-Defined Routines

Developing a User-Defined Routine

In This Chapter

Designing a UDR

Development Tools

Uses of a C UDR

Insert and Update Operations

Creating UDR Code

Variable Declaration

Session Management

SQL Statement Execution

Routine-State Information

Well-Behaved Routines

Compiling a C UDR

Compiling Options

Creating a Shared-Object File

Registering a C UDR

EXTEND Role Required to Register a C UDR

The External Name

The UDR Language

Routine Modifiers

Parameters and Return Values

Privileges for the UDR

Executing a UDR

Routine Resolution

The Routine Manager

Debugging a UDR

Using a Debugger

Running a Debugging Session

Altering a Routine

Unloading a Shared-Object File

Writing a User-Defined Routine

In This Chapter

Defining Routine Parameters

Obtaining Argument Values

Defining a Return Value

Coding the Routine Body

Using Virtual Processors

Creating a Well-Behaved Routine

Managing Virtual Processors

Controlling the VP Environment

Obtaining VP-Environment Information

Changing the VP Environment

Performing Input and Output

Access to a Stream (Server)

Access to Operating-System Files

Sample File-Access UDR

Accessing the UDR Execution Environment

Accessing the Session Environment

Accessing the Server Environment

Managing Memory

In This Chapter

Understanding Shared Memory

Accessing Shared Memory

Choosing the Memory Duration

Managing Shared Memory

Managing User Memory

Managing Named Memory

Monitoring Shared Memory

Managing Stack Space

Managing Stack Usage

Increasing Stack Space

Creating Special-Purpose UDRs

In This Chapter

Writing an End-User Routine

Writing a Cast Function

Writing an Iterator Function

Initializing the Iterations

Returning One Active-Set Item

Releasing Iteration Resources

Calling an Iterator Function from an SQL Statement

Writing an Aggregate Function

Extending a Built-In Aggregate

Creating a User-Defined Aggregate

Providing UDR-Optimization Functions

Writing Selectivity and Cost Functions

Creating Negator Functions

Creating Commutator Functions

Creating Parallelizable UDRs

Extending Data Types

In This Chapter

Creating an Opaque Data Type

Designing an Opaque Data Type

Writing Opaque-Type Support Functions

Registering an Opaque Data Type

Providing Statistics Data for a Column

Collecting Statistics Data

Using User-Defined Statistics

Optimizing Queries

Selectivity Functions

Appendix A. Writing a Client LIBMI Application

Managing Memory in Client LIBMI Applications

Allocating User Memory

Deallocating User Memory

Accessing Operating-System Files in Client LIBMI Applications

Handling Transactions

Appendix B. Accessibility

Dotted Decimal Syntax Diagrams

Home | [ Top of Page | Previous Page | Next Page | Contents | Index ]