users.salleurl.eduusers.salleurl.edu/~marcg/Documentacio/databases/DataBlade_SDK.… · iv DataBlade Developers Kit User’s Guide Chapter 2 INFORMIX-Universal Server Architecture

DataBladeDevelopers Kit

User’s Guide

Version 3.4July 1997Part No. 000-4053

ii DataBlade Developers

Published by INFORMIX Press Informix Software, Inc.4100 Bohannon DriveMenlo Park, CA 94025-1032

Copyright 1981-1997 by Informix Software, Inc., or its subsidiaries, provided that portions may becopyrighted by third parties, as set forth in documentation. All rights reserved.

The following are worldwide trademarks of Informix Software, Inc., or its subsidiaries, registered in theUnited States of America as indicated by “,” and in numerous other countries worldwide:

INFORMIX; Illustra™; DataBlade

All other marks or symbols are registered trademarks or trademarks of their respective owners.

ACKNOWLEDGMENTS

Documentation Team: Informix DataBlade Technical Publications

Contributors: Bernhard Brandmair, Steve Horwitz, Debbi Landshoff, David Marsyla, Michael Olson,Alan Teague, Ken Wolf

To the extent that this software allows the user to store, display, and otherwise manipulate various forms ofdata, including, without limitation, multimedia content such as photographs, movies, music and other binarylarge objects (blobs), use of any single blob may potentially infringe upon numerous different third-partyintellectual and/or proprietary rights. It is the user's responsibility to avoid infringements of any such third-party rights.

RESTRICTED RIGHTS/SPECIAL LICENSE RIGHTS

Software and documentation acquired with US Government funds are provided with rights as follows: (1) iffor civilian agency use, with Restricted Rights as defined in FAR 52.227-19; (2) if for Dept. of Defense use, withrights as restricted by vendor's standard license, unless superseded by negotiated vendor license as prescribedin DFAR 227.7202. Any whole or partial reproduction of software or documentation marked with this legendmust reproduce the legend.

Kit User’s Guide

Table of Contents

Table ofContents

IntroductionAbout This Manual . . . . . . . . . . . . . . . . . . 3

Organization of This Manual . . . . . . . . . . . . . 3Types of Users . . . . . . . . . . . . . . . . . . 4Software Dependencies . . . . . . . . . . . . . . . 4

Documentation Conventions . . . . . . . . . . . . . . 5Typographical Conventions . . . . . . . . . . . . . 5Icon Conventions . . . . . . . . . . . . . . . . . 6Syntax Conventions . . . . . . . . . . . . . . . . 6Screen-Illustration Conventions . . . . . . . . . . . . 7

Additional Documentation . . . . . . . . . . . . . . . 7Related Reading . . . . . . . . . . . . . . . . . 7On-Line Documentation . . . . . . . . . . . . . . 8

Informix DataBlade Developers Program Registry . . . . . . . 9Informix Welcomes Your Comments . . . . . . . . . . . . 9

Chapter 1 DataBlade Module OverviewWhat Is a DataBlade Module? . . . . . . . . . . . . . . 1-3DataBlade Module Components . . . . . . . . . . . . . 1-3

Extended Data Types. . . . . . . . . . . . . . . . 1-4Routines . . . . . . . . . . . . . . . . . . . . 1-6Casts . . . . . . . . . . . . . . . . . . . . . 1-15Interfaces . . . . . . . . . . . . . . . . . . . . 1-15Qualified Data Types . . . . . . . . . . . . . . . . 1-15Tables and Indexes . . . . . . . . . . . . . . . . 1-16Error Codes and Error Messages . . . . . . . . . . . . 1-16Client Code . . . . . . . . . . . . . . . . . . . 1-17

Using a DataBlade Module . . . . . . . . . . . . . . . 1-17From SQL . . . . . . . . . . . . . . . . . . . 1-17From DataBlade API Client Programs . . . . . . . . . . 1-18From Another DataBlade Module . . . . . . . . . . . 1-18

Developing DataBlade Modules . . . . . . . . . . . . . 1-18

iv DataB

Chapter 2 INFORMIX-Universal Server ArchitectureShared Memory . . . . . . . . . . . . . . . . . . 2-4Virtual Processors . . . . . . . . . . . . . . . . . . 2-5

CPU Virtual Processor . . . . . . . . . . . . . . . 2-5Extension Virtual Processor . . . . . . . . . . . . . 2-6Asynchronous I/O Virtual Processor . . . . . . . . . . 2-7Network Virtual Processor . . . . . . . . . . . . . 2-7

Chapter 3 Designing DataBlade ModulesData Model . . . . . . . . . . . . . . . . . . . . 3-4Data Type Design . . . . . . . . . . . . . . . . . . 3-6Query Language Interface . . . . . . . . . . . . . . . 3-7

SQL Query Structure . . . . . . . . . . . . . . . 3-7The Target List . . . . . . . . . . . . . . . . . 3-8The Qualification . . . . . . . . . . . . . . . . . 3-10

Query Processing . . . . . . . . . . . . . . . . . . 3-12Predicate Evaluation . . . . . . . . . . . . . . . 3-12Expensive Routines . . . . . . . . . . . . . . . . 3-13Sorting . . . . . . . . . . . . . . . . . . . . 3-14Grouping . . . . . . . . . . . . . . . . . . . 3-15Casts . . . . . . . . . . . . . . . . . . . . . 3-16Access Path Selection . . . . . . . . . . . . . . . 3-17Planning for Transaction Semantics . . . . . . . . . . 3-19

Interoperability . . . . . . . . . . . . . . . . . . . 3-20Orthogonality . . . . . . . . . . . . . . . . . . 3-21Simple Clean Interfaces . . . . . . . . . . . . . . 3-21Coding Standards . . . . . . . . . . . . . . . . 3-23Performance, Robustness, and Value . . . . . . . . . . 3-24Choosing a Virtual Processor Class . . . . . . . . . . 3-24Writing Thread-Safe Routines . . . . . . . . . . . . 3-25Avoiding System Calls . . . . . . . . . . . . . . . 3-26

Implementation Issues . . . . . . . . . . . . . . . . 3-26Naming DataBlade Module Objects . . . . . . . . . . 3-26Registering Your DataBlade Module . . . . . . . . . . 3-26Using the Registered Object Prefix . . . . . . . . . . . 3-27DataBlade Module Directory Structure . . . . . . . . . 3-28New or Old Code? . . . . . . . . . . . . . . . . 3-29Using the DataBlade Developers Kit Tools . . . . . . . . 3-29Developing Iteratively . . . . . . . . . . . . . . . 3-30Testing and Certifying DataBlade Module Code . . . . . . 3-30Debugging DataBlade Modules . . . . . . . . . . . . 3-30Certifying DataBlade Modules . . . . . . . . . . . . 3-31

Supporting Client Applications . . . . . . . . . . . . . 3-31

lade Developers Kit User’s Guide

Using DataBlade Modules from a Client . . . . . . . . . 3-32Providing Client-Side Libraries . . . . . . . . . . . . 3-32Using the Informix C++ API . . . . . . . . . . . . . 3-33

Chapter 4 Using BladeSmithBladeSmith Overview . . . . . . . . . . . . . . . . . 4-3

BladeSmith Windows. . . . . . . . . . . . . . . . 4-4DataBlade Module Objects . . . . . . . . . . . . . . 4-6

Using BladeSmith . . . . . . . . . . . . . . . . . . 4-12Setting Up a Project Environment . . . . . . . . . . . 4-12Importing DataBlade Module Objects . . . . . . . . . . 4-13Defining New DataBlade Module Objects. . . . . . . . . 4-14Adding Test Data . . . . . . . . . . . . . . . . . 4-14Generating Files . . . . . . . . . . . . . . . . . 4-16Regenerating Files . . . . . . . . . . . . . . . . . 4-20

Chapter 5 Programming DataBlade Module RoutinesDataBlade Module Programming Guidelines . . . . . . . . . 5-3

Use mi_alloc() and mi_free() . . . . . . . . . . . . . 5-3Do Not Use Global or Static Variables . . . . . . . . . . 5-4Avoid Unsafe System and Library Calls . . . . . . . . . 5-4Do Not Use Signals . . . . . . . . . . . . . . . . 5-7Write Thread-Safe Code . . . . . . . . . . . . . . . 5-7

Source Files Generated by BladeSmith . . . . . . . . . . . 5-8Comments in Generated Code. . . . . . . . . . . . . 5-8MI_FPARAM Function Parameter Argument . . . . . . . 5-9Server Connection Handle . . . . . . . . . . . . . . 5-10Tracing and Error Handling . . . . . . . . . . . . . 5-10

Utility Functions Generated by BladeSmith . . . . . . . . . 5-13Code Generated for Opaque Type Support Routines . . . . . . 5-15

Text Input/Output Routines . . . . . . . . . . . . . 5-16Binary Send/Receive Routines . . . . . . . . . . . . 5-20Text File Import/Export Routines . . . . . . . . . . . 5-22Binary File Import/Export Routines. . . . . . . . . . . 5-23Assign/Destroy Routines . . . . . . . . . . . . . . 5-24LOhandles Routine . . . . . . . . . . . . . . . . 5-25Comparison Routines. . . . . . . . . . . . . . . . 5-26Mathematic Routines . . . . . . . . . . . . . . . . 5-29User-Defined Routines and Casts. . . . . . . . . . . . 5-29

Compiling DataBlade Module Code . . . . . . . . . . . . 5-31Compiling with Tracing Support . . . . . . . . . . . . 5-32Compiling with Debug Support . . . . . . . . . . . . 5-33

Table of Contents v

vi DataB

Chapter 6 Testing and Debugging DataBlade ModulesInstalling a Private Server . . . . . . . . . . . . . . . 6-3

Setting Runtime Environment Variables . . . . . . . . . 6-5Starting the Private Server . . . . . . . . . . . . . 6-6

Installing and Registering DataBlade Modules . . . . . . . . 6-6Executing Functional Tests . . . . . . . . . . . . . . . 6-7

Functional Test Overview . . . . . . . . . . . . . . 6-7Contents of the Functional Test Directory . . . . . . . . 6-8Adding Custom Test Files . . . . . . . . . . . . . . 6-10Preparing to Execute Functional Tests . . . . . . . . . 6-11Using the Functional Test Scripts . . . . . . . . . . . 6-11Initializing Reference Files . . . . . . . . . . . . . 6-12

Debugging a DataBlade Module . . . . . . . . . . . . . 6-12Connecting to the Server from a Client . . . . . . . . . 6-13Loading the DataBlade Module . . . . . . . . . . . . 6-13Identifying the Server Process . . . . . . . . . . . . 6-14Starting the Debugger . . . . . . . . . . . . . . . 6-15Setting Breakpoints . . . . . . . . . . . . . . . . 6-15Symbols in Shared Object Files . . . . . . . . . . . . 6-16

Executing DataBlade Modules in Universal Server . . . . . . 6-16Shared Object File Ownership and Permissions . . . . . . 6-16Replacing a Shared Object File . . . . . . . . . . . . 6-17Configuring Virtual Processors for DataBlade Modules . . . 6-17Setting Stack Sizes for User-Defined Routines . . . . . . . 6-18

Chapter 7 Using BladePackBladePack Overview . . . . . . . . . . . . . . . . . 7-3

BladePack On-Line Help . . . . . . . . . . . . . . 7-4BladePack Windows. . . . . . . . . . . . . . . . 7-5

Using BladePack . . . . . . . . . . . . . . . . . . 7-9Understanding Components . . . . . . . . . . . . . 7-10Overriding Screen Display Text . . . . . . . . . . . . 7-11Revising On-Line Help for the Installation . . . . . . . . 7-14

Building the Installation Package . . . . . . . . . . . . 7-15Creating Distribution Media . . . . . . . . . . . . . . 7-17

Chapter 8 Example DataBlade ModulesCircle DataBlade Module . . . . . . . . . . . . . . . 8-4

Pnt Data Type . . . . . . . . . . . . . . . . . . 8-4Circ Data Type. . . . . . . . . . . . . . . . . . 8-5Distance() Function . . . . . . . . . . . . . . . . 8-5Contains() Function . . . . . . . . . . . . . . . . 8-5

lade Developers Kit User’s Guide

PntCompare() Function . . . . . . . . . . . . . . . 8-6PntEqual() Function . . . . . . . . . . . . . . . . 8-6CircCompare() Function . . . . . . . . . . . . . . . 8-6CircEqual() Function . . . . . . . . . . . . . . . . 8-6PntNotEqual() Function . . . . . . . . . . . . . . . 8-7CircNotEqual() Function . . . . . . . . . . . . . . 8-7

Matrix Math DataBlade Module . . . . . . . . . . . . . 8-7Matrix2d Data Type . . . . . . . . . . . . . . . . 8-7Compare() Function . . . . . . . . . . . . . . . . 8-8Equal() Function . . . . . . . . . . . . . . . . . 8-8NotEqual() Function . . . . . . . . . . . . . . . . 8-9Plus() Function . . . . . . . . . . . . . . . . . . 8-9Minus() Function . . . . . . . . . . . . . . . . . 8-9Times() Function . . . . . . . . . . . . . . . . . 8-10Divide() Function . . . . . . . . . . . . . . . . . 8-10

Business DataBlade Module . . . . . . . . . . . . . . . 8-11ExmAmortize() Function . . . . . . . . . . . . . . 8-11ExmFV() Function . . . . . . . . . . . . . . . . . 8-12ExmPV() Function . . . . . . . . . . . . . . . . . 8-12

Parts Explosion DataBlade Module . . . . . . . . . . . . 8-13Explode() Function . . . . . . . . . . . . . . . . 8-13

TopK Terms DataBlade Module . . . . . . . . . . . . . . 8-14TopK() Function . . . . . . . . . . . . . . . . . 8-14

MMX DataBlade Module . . . . . . . . . . . . . . . . 8-14Image Data Type . . . . . . . . . . . . . . . . . 8-15EnlargeImageX2() Function. . . . . . . . . . . . . . 8-15ReduceImageX2() Function . . . . . . . . . . . . . . 8-15ZoomImageXN() Function . . . . . . . . . . . . . . 8-16

Index

Table of Contents vii

Introduction

Introduction

About This Manual . . . . . . . . . . . . . . . . . . . 3Organization of This Manual . . . . . . . . . . . . . . 3Types of Users . . . . . . . . . . . . . . . . . . . 4Software Dependencies . . . . . . . . . . . . . . . . 4

Documentation Conventions . . . . . . . . . . . . . . . 5Typographical Conventions . . . . . . . . . . . . . . 5Icon Conventions . . . . . . . . . . . . . . . . . . 6Syntax Conventions . . . . . . . . . . . . . . . . . 6Screen-Illustration Conventions . . . . . . . . . . . . . 7

Additional Documentation . . . . . . . . . . . . . . . . 7Related Reading . . . . . . . . . . . . . . . . . . 7On-Line Documentation. . . . . . . . . . . . . . . . 8

On-Line Help . . . . . . . . . . . . . . . . . . 8DataBlade Module Development Overview . . . . . . . 8Release Notes and Documentation Notes . . . . . . . . 8

Informix DataBlade Developers Program Registry . . . . . . . . 9

Informix Welcomes Your Comments . . . . . . . . . . . . . 9

2 DataBl
ade Developers Kit User’s Guide

This chapter introduces the DataBlade Developers Kit User’s Guide. Readthis chapter for an overview of the information provided in this manual andfor an understanding of the conventions used throughout.

About This ManualThe DataBlade Developers Kit User’s Guide describes how to develop andpackage DataBlade modules using BladeSmith, BladePack, and theINFORMIX-Universal Server DataBlade API. This section discusses the organi-zation of the manual, the intended audience, and the associated softwareproducts that you must have to develop and use the DataBlade module.

Organization of This ManualThe DataBlade Developers Kit User’s Guide includes the following chapters:

■ This Introduction provides an overview of the contents of the guide,describes documentation conventions used, and lists additionalbooks to supplement the information in the DataBlade Developers KitUser’s Guide.

■ Chapter 1, “DataBlade Module Overview,” describes the compo-nents of a DataBlade module and the process for developing aDataBlade module.

■ Chapter 2, “INFORMIX-Universal Server Architecture,” gives anoverview of the Universal Server database system. This chapterdescribes how DataBlade modules work with Universal Server.

■ Chapter 3, “Designing DataBlade Modules,” discusses DataBlademodule design issues. This chapter helps you to design DataBlademodules that perform well, cooperate with other DataBlademodules, and are robust and maintainable.

Introduction 3

Types of Users

■ Chapter 4, “Using BladeSmith,” provides information about usingBladeSmith to define the objects in your DataBlade module and togenerate code, scripts, and installation files for the module.

■ Chapter 5, “Programming DataBlade Module Routines,” describesthe code that BladeSmith generates and how to compile theDataBlade module for Universal Server.

■ Chapter 6, “Testing and Debugging DataBlade Modules,” describeshow to execute the functional tests generated with BladeSmith andhow to use a debugger with the Universal Server process thatexecutes your DataBlade module functions.

■ Chapter 7, “Using BladePack,” describes how to use BladePack topackage your DataBlade module components together to createinstallation media to distribute your DataBlade module to yourcustomers.

■ Chapter 8, “Example DataBlade Modules,” contains references forthe example DataBlade modules that demonstrate various features,such as opaque types and complex data types. The source code forthe examples is included with the DataBlade Developers Kit in thedbdk\examples subdirectory.

Types of UsersThis guide is for experienced C programmers who are comfortable writinglibraries to support applications. The programmer will develop DataBlademodules to extend Universal Server with support for new data types and thefunctions that operate on them.

Software DependenciesThis manual describes version 3.4 of the DataBlade Developers Kit. Version3.4 requires Universal Server, including the DataBlade API andINFORMIX-ESQL/C libraries included with that server release.

4 DataBlade Developers Kit User’s Guide

Documentation Conventions

Documentation ConventionsThis section describes the conventions that this manual uses. These conven-tions make it easier to gather information from this and other volumes in thedocumentation set. The following conventions are covered:

■ Typographical conventions

■ Icon conventions

■ Function syntax conventions

■ Screen-illustration conventions

Typographical ConventionsThis manual uses the following standard set of conventions to introduce newterms, illustrate screen displays, describe command syntax, and so forth.

Convention Meaning

KEYWORD All keywords appear in uppercase letters in a serif font.

italics Within text, new terms and emphasized words appear in italics.Within syntax diagrams, values that you are to specify appearin italics.

boldface Identifiers (names of classes, objects, constants, events,functions, program variables, forms, labels, and reports),environment variables, database names, filenames, tablenames, column names, icons, menu items, command names,and other similar terms appear in boldface.

monospace Information that the product displays and information that youenter appear in a monospace typeface.

KEYSTROKE Keys that you are to press appear in uppercase letters in a sansserif font.

♦ This symbol indicates the end of product- or platform-specificinformation.

Introduction 5

Icon Conventions

Tip: When you are instructed to “enter” characters or to “execute” a command,immediately press RETURN after the entry. When you are instructed to “type” thetext or to “press” other keys, no RETURN is required.

Icon ConventionsComment icons identify warnings, important notes, or tips. This informationis always displayed in italics.

Syntax ConventionsThis guide uses the following conventions to specify DataBlade modulefunction syntax:

■ Square brackets ( [ ] ) surround optional items.

■ Curly brackets ( { } ) surround items that can be repeated zero ormore times.

■ A vertical line ( | ) separates alternatives.

■ Comma-separated lists of values are indicated by a parameter valuewith a “_commalist” suffix. For example, colorlist=color_commalistmight indicate “colorlist=red, blue, green.”

Icon Description

The warning icon identifies vital instructions, cautions, orcritical information.

The important icon identifies significant information aboutthe feature or operation that is being described.

The tip icon identifies additional details or shortcuts for thefunctionality that is being described.


Screen-Illustration Conventions

■ Function parameters are italicized; arguments that must be specifiedas shown are not italicized.

These function syntax conventions used in context look like this:

myfunction([optionalarg], {repeatablearg}, set | noset,myparam=my_commalist)

DataBlade module functions are used in SQL statements to manipulate thespecialized data types defined by DataBlade modules.

Screen-Illustration ConventionsThe illustrations in this manual represent a generic rendition of variouswindowing environments. The details of dialog boxes, controls, andwindows have been deleted or redesigned to provide this generic look.Therefore, the illustrations in this manual depict the BladeSmith andBladePack screens a little differently than the way they appear on yourscreen.

Additional DocumentationThis section lists resources that contain information that is supplemental tothis guide.

Related ReadingFor information about installing the DataBlade Developers Kit, refer toINFORMIX-Universal Server Client Products Installation Guide for MicrosoftWindows Environments.

For additional information on developing DataBlade modules, consult thefollowing books:

■ Extending INFORMIX-Universal Server: User-Defined Routines

■ Extending INFORMIX-Universal Server: Data Types

■ Informix Guide to SQL: Reference

■ DataBlade API Programmer’s Manual

Introduction 7

On-Line Documentation

■ INFORMIX-ESQL/C Programmer’s Manual

■ INFORMIX-Universal Server Administrator’s Guide

■ BladeManager User’s Guide

On-Line DocumentationThe DataBlade Developers Kit includes on-line help, release notes, anddocumentation notes.

On-Line Help

BladeSmith and BladePack include context-sensitive help that providesoverview and detailed reference information for these programs.

DataBlade Module Development Overview

You can access the DataBlade Module Development Overview from the Blade-Smith Help menu. This document provides an overview of Universal Serverextensibility, DataBlade modules, and the development process. Thedocument requires an HTML browser, such as Netscape Navigator.

Release Notes and Documentation Notes

The following on-line release notes and documentation notes, which you canaccess by clicking their icons in the INFORMIX program group, supplementthe information provided in this manual.

On-Line File Purpose

Documentationnotes file

Describes features that are not covered in the manuals or thathave been modified since publication.

Release notes file Describes feature differences from earlier versions of Informixproducts and how these differences might affect currentproducts. This file also contains information about any knownproblems and their workarounds.


Informix DataBlade Developers Program Registry

Please examine these files because they contain vital information aboutapplication and performance issues.

Informix DataBlade Developers Program RegistryThe Informix DataBlade Developers Program maintains a registry of objectprefixes and error code ranges for all DataBlade modules. The registryensures that object names and error codes are unique so that any combinationof DataBlade modules can coexist in a database. To obtain a unique objectname prefix and a range of error codes for your DataBlade module, contactthe Informix DataBlade Developers Program by sending electronic mail [email protected].

Informix Welcomes Your CommentsPlease tell us what you like or dislike about our manuals. To help us withfuture versions of our manuals, we want to know about any corrections orclarifications that you would find useful. Please include the followinginformation:

■ The name and version of the manual you are using

■ Any comments you have about the manual

■ Your name, address, and phone number

Write to us at the following address:

Informix Software, Inc.Technical Publications300 Lakeside Dr., Suite 2700Oakland, CA 94612

If you prefer to send electronic mail, our address is:

[email protected]

Or, send a facsimile to Technical Publications at:

415-926-6571

Introduction 9

Informix Welcomes Your Comments

We appreciate your feedback.


1Chapter

DataBlade Module Overview

What Is a DataBlade Module? . . . . . . . . . . . . . . . 1-3

DataBlade Module Components . . . . . . . . . . . . . . 1-3Extended Data Types . . . . . . . . . . . . . . . . . 1-4

Collection Data Type . . . . . . . . . . . . . . . 1-5Row Data Type . . . . . . . . . . . . . . . . . 1-5Distinct Data Type . . . . . . . . . . . . . . . . 1-6Opaque Data Type . . . . . . . . . . . . . . . . 1-6

Routines . . . . . . . . . . . . . . . . . . . . . 1-6Format Conversion Routines . . . . . . . . . . . . . 1-7Large Object Support Routines . . . . . . . . . . . . 1-9Comparison Routines . . . . . . . . . . . . . . . 1-11B-tree Indexing Routines . . . . . . . . . . . . . . 1-12R-tree Indexing Routines . . . . . . . . . . . . . . 1-13Mathematic Operator Routines . . . . . . . . . . . . 1-13Concatenation Routine . . . . . . . . . . . . . . . 1-14Hash Routine . . . . . . . . . . . . . . . . . . 1-14

Casts . . . . . . . . . . . . . . . . . . . . . . 1-15Interfaces . . . . . . . . . . . . . . . . . . . . . 1-15Qualified Data Types . . . . . . . . . . . . . . . . . 1-15Tables and Indexes . . . . . . . . . . . . . . . . . 1-16Error Codes and Error Messages . . . . . . . . . . . . . 1-16Client Code . . . . . . . . . . . . . . . . . . . . 1-17

Using a DataBlade Module . . . . . . . . . . . . . . . . 1-17From SQL. . . . . . . . . . . . . . . . . . . . . 1-17From DataBlade API Client Programs . . . . . . . . . . . 1-18From Another DataBlade Module . . . . . . . . . . . . 1-18

Developing DataBlade Modules . . . . . . . . . . . . . . 1-18

1-2 Data
Blade Developers Kit User’s Guide

his chapter describes the components of a DataBlade module andpresents an overview of the DataBlade module development process.

What Is a DataBlade Module?A DataBlade module is a collection of database objects and code that extendINFORMIX-Universal Server by adding new functionality. A DataBlademodule can enable Universal Server to provide the same level of support fornew data types as it provides for built-in data types.

A DataBlade module typically supports a specific application domain, suchas spatial data management or document indexing and retrieval. SeveralDataBlade modules can be used to support a single application. For example,a medical records application that stores information from many differenthospitals might use the Informix Spatial DataBlade module to record andquery hospital locations and a third-party test laboratory DataBlade moduleto index and query results from tests performed on hospital patients.

DataBlade Module ComponentsA DataBlade module can have the following components:

■ Extended data types. New data types added to the server.

■ Routines. C or SPL functions and procedures, callable by thedatabase server, that support opaque data types or clientapplications.

■ Casts. Routines that convert values between data types.

T

DataBlade Module Overview 1-3

Extended Data Types

■ Interfaces. Unique IDs assigned to DataBlade modules or subsets ofthe data types and routines in DataBlade modules. DataBlademodules that depend upon other DataBlade modules’ interfacesdeclare the interfaces they require so that BladeManager can ensurethat all needed DataBlade modules are registered in a database.

■ Qualified data types. Universal Server built-in data types, such asCHARACTER and DECIMAL, that can take additional specifications.Although DataBlade modules do not add qualified data types toUniversal Server, other DataBlade module components canreference qualified data types. Therefore, qualified types are definedin DataBlade modules with the particular specifications required byDataBlade module objects that reference them.

■ Tables and indexes. Database tables and indexes used to supportnew data types or client applications.

■ Error codes and error messages. Message strings and error codesused in DataBlade module routines.

■ Client code. Code that enables clients to access the other compo-nents of the DataBlade module.

The following sections describe each of these DataBlade modulecomponents.

Extended Data TypesThe data types you add to the server when you develop a DataBlade moduleare called extended data types. BladeSmith allows you to define the followingkinds of extended data types:

■ Collection data type

■ Row data type

■ Distinct data type

■ Opaque data type

The following sections describe these data types.

1-4 DataBlade Developers Kit User’s Guide

Extended Data Types

Collection Data Type

A collection data type is a group of elements of the same data type. Theelements can be built-in data types (including CLOBs and BLOBs), qualifieddata types, opaque data types, named row data types, unnamed row datatypes, distinct data types, or other collection data types.

Collection data types include SET, MULTISET, and LIST.

LIST is a collection data type in which the elements are ordered and dupli-cates are allowed. It is created with the LIST constructor.

MULTISET is a collection data type in which elements are not ordered andduplicates are allowed. It is created with the MULTISET constructor.

SET is a collection data type in which elements are not ordered and duplicatesare not allowed. It is created with the SET constructor.

The following table summarizes the properties of the collection data types.

There is no collection data type whose elements are ordered andunduplicated.

Row Data Type

A row data type contains a group of data fields, of the same or different datatypes, that form a template for data records. Row data types can be named orunnamed. A row data type can include any combination of opaque datatypes, distinct data types, built-in data types, other row data types, orcollection data types. A row data type can be stored in a row or column, anda table can be created from a row data type.

Collection Data Type Ordered Multiples Permitted

LIST Yes Yes

MULTISET No Yes

SET No No


Routines

Distinct Data Type

A distinct data type has the same storage representation as an existing opaquedata type or built-in data type, but it is distinguished by its name and cannotbe substituted for the source data type. For example, a new distinct data typeLIRA can be created with the same representation as a MONEY built-in datatype. All routines that operate on LIRA values have server-simulated counter-parts for MONEY values. However, MONEY values and LIRA values cannot beadded, subtracted, or compared with one another without explicitly castingone value to the data type of the other.

Opaque Data Type

An opaque data type is a fundamental data type that stores a single value andcannot be divided into components by the server.

An opaque data type is implemented as a C structure and a set of routineswritten in C that allow the server to support the data type. C routines thatsupport a new opaque data type pass the contents of the structure to theserver to store in the database. The server does not interpret the contents ofthe structure—it stores the memory contents, byte for byte, in the database.The support routines implement operations such as comparing two instancesof a data type, converting an opaque data type to another data type, ordisplaying an instance of the data type. The server calls the support routinesupplied for an operation, passing the C structure or a pointer to it in theparameter list.

RoutinesA DataBlade module can include routines (functions or procedures) writtenin SPL or C. These routines are used by client applications or to support thenew data types that you define. The routines are registered in the server andare called by the server. They execute in a CPU virtual processor (CPU VP) oran extension virtual processor (EXT VP). Routines written in C are compiledinto a shared object file so that the server can load them. The shared object filehas a .bld extension.

If your DataBlade module includes opaque data types, you must provide thesupport routines Universal Server calls to operate on them. Some routines arerequired, while others are optional.


Routines

You can use BladeSmith to define the routines needed to support an opaquedata type. BladeSmith generates C functions for the following categories ofsupport routines:

■ Format conversion

■ Large object support

■ Comparison

■ B-tree indexing

■ R-tree indexing

■ Mathematic operators

■ Concatenation operator

■ Hash support

The following sections describe the opaque data type support routines ineach of these categories. For detailed information about implementing theroutines in C, see Chapter 5, “Programming DataBlade Module Routines.”

Format Conversion Routines

Format conversion routines convert opaque data types between the variousformats used in databases, programs, and external files. The following tabledescribes the formats used to represent an opaque data type.

Format conversion routines convert data type values between their internalserver representation:

Format Description

Server binary C structure on the server machine.

Client binary C structure on the client machine. This is the same as theserver binary format with adjustments for dissimilar serverand client platforms.

Text Formatted string entered by users and displayed to users.

External text Optional format used to represent values in an external textfile. By default, it is the same as the text format.

External binary Format used to represent values in an external binary file.


Routines

■ Text Input/Output routines convert between text and server binaryformats.

■ Binary Send/Receive routines convert between server binary andclient binary formats.

■ Text File Import/Export routines convert between server binary andexternal text formats.

■ Binary File Import/Export routines convert between server binaryand external binary formats.

Text Input/Output Routines

The text representation of an opaque data type is an mi_lvarchar value thatcontains a printable representation of an instance of the data type. The textrepresentation enters values for the data type in SQL statements such asINSERT and displays values in output from SQL statements such as SELECT.

The Text Input routine converts from text format to server binary format. TheText Output routine converts from server binary format to text format.

The Text Input routine takes an mi_lvarchar argument, allocates memory forthe structure, scans the text value, and sets the structure members to thevalues specified in the text value. It returns a pointer to the allocatedstructure.

The Text Output routine receives a pointer to a structure as its argument,allocates memory for an mi_lvarchar buffer, and writes the text represen-tation of the structure in the buffer.

Binary Send/Receive Routines

Binary Send/Receive routines convert instances of opaque data typesbetween server binary format and client binary format. The client and servercan execute on different platforms, with different representations for somedata types. When a client connects with a server, it sends a description of itsdata representation. The server calls the Binary Send routine to convertopaque data type values to the client format before sending them to theclient. The Binary Receive function converts a value arriving from the clientbinary format to the server binary format.


Routines

You do not have to know the specifics about data representation on differingplatforms to convert an instance of a data type. Binary Send/Receive routinescall DataBlade API routines for each member of the structure to convertvalues to the appropriate C data type representation for the destinationplatform.

Text File Import/Export Routines

Text File Import/Export routines enable bulk copy for opaque data types.When you copy data from a file into a database with PLOAD or the DB-AccessLOAD command, the server calls a Text File Import routine to convert theincoming value to the server binary format. When data is copied out of thedatabase into an external file, the server calls a Text File Export routine toconvert the value from server binary format to text file format.

Text File Import/Export routines are needed for opaque data types thatinclude large objects and for any data type that is to be exported to a disk file.On copy-out, the Text File Export routine creates a file on the client, writes thelarge object data to it, and then sends the name of the file as the data value forstorage in the copy file. The Text File Import routine takes the filename, opensit, and loads the large object data. This method stores large object dataindependent from the copy file so that the copy file is smaller and easier toread.

If you do not define Text File Import/Export routines, the server calls the TextInput/Output routines.

Binary File Import/Export Routines

The Binary File Import/Export routines are used to support bulk copy ofbinary data. These routines are the same as the Text File Import/Exportroutines, except that they operate on binary representations of the data type.The routines are called when PLOAD executes.

Large Object Support Routines

When you create an opaque data type that contains one or more large objects,you must provide the following support routines to allow Universal Serverto manage the new data type:

■ Text File Import/Export routines


Routines

■ Binary File Import/Export routines

■ Assign/Destroy routines

■ LOhandles routine

The Text File Import/Export and Binary File Import/Export routines aredescribed under “Format Conversion Routines” on page 1-7. The followingsections describe the Assign/Destroy and LOhandles routines.

Assign/Destroy Routines

You can provide Assign/Destroy routines for an opaque data type thatrequires special processing when an instance is stored in a database orremoved from the database. The Assign routine, if defined, is called before avalue is written to a table. If a Destroy routine is defined for a data type, it iscalled before a value is deleted from a table.

For example, opaque data types that include large objects require specialhandling before they are stored on disk or removed from a table. The servermaintains a reference count for large objects to ensure that an object is notdropped while a row in the database references it. When a reference to a largeobject is inserted into a table, the Assign routine increments the referencecount. When a reference to a large object is deleted from a table, the Destroyroutine decrements the reference count.

Depending on the size of the value, multirepresentational data types can bestored directly in a record or in a large object. The decision is postponed untilthe value is about to be stored in the table. The software that manages thedata type determines whether to create a large object to hold the data, or toleave it directly in the record.

LOhandles Routine

Universal Server calls an LOhandles routine to obtain a list of large objectsused by an opaque data type. The LOhandles routine takes a pointer to aninstance of the data type and returns an array of the large object handles usedby the object.


Routines

Comparison Routines

Universal Server calls comparison routines to determine whether twoinstances of an opaque data type are equivalent. BladeSmith defines threeroutines when you select this category:

■ Compare

■ Equal

■ NotEqual

Compare Routine

The Compare routine compares two instances of an opaque data type andreturns:

■ a negative integer if the first value is less than the second.

■ 0 if the two values are equivalent.

■ a positive integer if the first value is greater than the second.

Other comparison routines, such as the Equal and NotEqual routines, usuallycall the Compare routine.

Some opaque data types represent objects that cannot naturally be comparedfor relative magnitude. In these cases, you can either choose to compare forequality only or choose some property of the object (such as a name) onwhich to base an artificial comparison. If you compare for equality only, theCompare routine must return 0 if the values are equivalent. It can return anyother integer if the values are not equivalent.

Equal Routine

The Equal routine compares two instances of an opaque data type andreturns a Boolean result. For most opaque data types, the Equal routine canreturn true (any non-zero value) if the Compare routine returns 0 for thesame arguments.


Routines

NotEqual Routine

The NotEqual routine compares two instances of an opaque data type andreturns a Boolean result. For most opaque data types, the NotEqual routinecan return true if the Compare routine returns any result except 0 for thesame arguments.

B-tree Indexing Routines

The server can build and maintain B-tree indexes on an opaque data type ifyou provide a Compare routine, as described in “Compare Routine” onpage 1-11.

To search a B-tree index, you must define additional routines. Each of theroutines takes two arguments of the new data type and returns a Booleanresult (that is, MI_TRUE or MI_FALSE) based on the result of comparing thearguments.

All of the following routines can be implemented by calling the Compareroutine for the data type:

■ The LessThan routine returns MI_TRUE if the first argument is lessthan the second. This routine is equivalent to the Compare routinereturning a negative integer.

■ The LessThanOrEqual routine returns MI_TRUE if the first argumentis less than or equal to the second. This routine is equivalent to theCompare routine returning 0 or a negative integer.

■ The Equal routine returns MI_TRUE if the arguments are equivalent.This routine is equivalent to the Compare routine returning 0.

■ The GreaterThanOrEqual routine returns MI_TRUE if the firstargument is greater than or equal to the second. This routine isequivalent to the Compare routine returning 0 or a positive integer.

■ The GreaterThan routine returns MI_TRUE if the first argument isgreater than the second. This routine is equivalent to the Compareroutine returning a positive integer.

Defining these routines for opaque data types allows fast B-tree indexsearches on the new data types. If a query uses the operator bound to one ofthe routines, the optimizer can evaluate strategies that use the index.


Routines

R-tree Indexing Routines

An R-tree index is a tree-based access method for multidimensional spatialdata types. R-tree indexes provide fast access to data such as rectangles andpolygons.

R-tree indexes store bounding boxes for k-dimensional spaces. Parent nodesstore bounding boxes that represent the union of all of the bounding boxesstored in their child nodes. The parent bounding box grows and shrinks aschild nodes are inserted and deleted.

To enable R-tree support for an opaque data type, you create the followingsupport routines in your DataBlade module:

■ The Contains routine compares two opaque data types and returnsMI_TRUE if the first contains the second.

■ The Equal routine compares two opaque data types and returnsMI_TRUE if they are equivalent.

■ The Inter routine compares two opaque data types and returnsMI_TRUE if they intersect.

■ The Overlap routine compares two opaque data types and returnsMI_TRUE if they overlap.

■ The Size routine returns the size of an opaque data type as a double-precision value.

■ The Union routine calculates the union of two opaque data types.

■ The Within routine compares two opaque data types and returnsMI_TRUE if the first is within the second.

When you define these routines for an opaque data type, Universal Servercan use R-tree indexes when processing queries that have Contains(),Equal(), Overlap(), or Within() in their predicates.

Mathematic Operator Routines

You can define mathematic operator routines for an opaque data type toallow the server to manipulate values mathematically. The mathematicoperator routines include the following:

■ The Plus routine, which is bound to the plus operator (+) , returns thesum of two opaque data type values.


Routines

■ The Minus routine, which is bound to the minus operator (-), returnsthe difference between two opaque data type values.

■ The Times routine, which is bound to the multiplication operator (*),returns the product of two opaque data type values.

■ The Division routine, which is bound to the division operator (/),divides one opaque data type value into another and returns thequotient.

■ The Positive routine, which is bound to the unary plus operator (+),returns the positive of a single opaque data type value.

■ The Negate routine, which is bound to the unary minus operator (-),returns the negative of a single opaque data type value.

If you define these routines for an opaque data type, Universal Server canresolve mathematic expressions in the select list or WHERE clause of a query.

Concatenation Routine

The Concatenation routine returns the result of concatenating two opaquedata type values. The Concatenation routine is bound to the concatenationoperator (||).

Hash Routine

The server uses a Hash function to cache routine return values and executedistinct aggregate queries. Most data types are bit-hashable and can use thebuilt-in hashing routine.

Bit-hashable data types have the property that:

if A = B then hash(A) = hash(B)

for any Hash routine hash(). In practice, this means that A and B haveidentical bit representations.

There are some data types for which two equal values have different bitrepresentations. For example, in one’s-complement notation, there are twodistinct representations for 0 (corresponding to +0 and -0). The SQL rules fordata type varchar require that trailing blanks be ignored in equality compar-isons. Thus, two varchar values with different numbers of trailing blanks willhave different bit representations, but they should still be considered equal.


Casts

For data types that are not bit-hashable, you must provide a Hash routine. Ittakes a single argument of the new data type and returns an mi_integervalue. It must obey the property of bit-hashable data types described here.

CastsA cast converts one data type to another data type. The cast support routinetakes an object of the data type to be converted and returns an object of thedestination data type. A cast does not require a support routine if the datadoes not change during the conversion. For example, without changing theinternal representation, a line data type, which is represented by two coordi-nates that define its endpoints, could be cast to a square data type, which isrepresented by two coordinates that define its opposite corners.

InterfacesAn interface is a collection of routines that conforms to a standard and exportsa predictable service. Interfaces allow DataBlade modules to communicate toother DataBlade modules the services they rely upon or provide.

For example, a DataBlade module that does image matching might allowusers to supply captions for images. If a “keyword search” interface wereregistered in the database, the image-matching DataBlade module could usethe keyword search routines to match on the captions.

You can choose the DataBlade module that meets your needs for perfor-mance or other criteria. Uniform interfaces allow DataBlade modules to becombined like building blocks. You can obtain the module desired and besure that it operates with other modules offered by Informix or otherdevelopers.

Qualified Data TypesA qualified data type is a Universal Server built-in data type with additionalspecifications that provide information about the storage size, range ofvalues, or precision of the data type. For example, the DECIMAL data type canbe qualified with precision and scale, which determine the number of signif-icant digits and decimal point placement.


Tables and Indexes

In DataBlade modules, qualified data types are used as components of rowdata types and collection data types, or as arguments or return values ofroutines. You define a qualified data type in a BladeSmith project solely forthe purpose of referencing it in the definition of another object in the project.

Tables and IndexesDataBlade module routines can use data stored in the database. For example,an Input routine can validate the values users enter by looking them up in atable in the database. For large, frequently accessed tables, the DataBlademodule can also define indexes on one or more columns. This can helpqueries over indexed columns to run faster. Indexes consume space andserver resources when modified. Thus, you should define indexes only aftercarefully analyzing the performance of queries on the tables.

BladeSmith allows you to add custom SQL commands to define databaseobjects required by a DataBlade module, such as tables and indexes.

Error Codes and Error MessagesDataBlade module routines running in Universal Server can return informa-tional or error messages. Each message is assigned a code, selected from a setallocated to the DataBlade module by the Informix DataBlade DevelopersProgram registry. See “Naming DataBlade Module Objects” on page 3-26 forinformation about registering error codes.

The text of messages is stored in system tables in the database. Messages areavailable to the client application, and can be written to the server log file ora trace file using DataBlade API routines.

When you create a message in a BladeSmith project, you can designate themessage as an error message, a trace message, or both. BladeManager insertsmessages designated as error messages into the sysmessages system tableand messages designated as trace messages into the systracemessagessystem tables.


Client Code

You can provide the text of a message in multiple languages and codesets byassociating the same error code and a different locale with each version of themessage. BladeSmith generates a separate message file for each locale withmessages in the project. BladeManager loads all available messages into thedatabase when the DataBlade module is registered.

Client CodeIn addition to code that implements and supports the new data types, manyDataBlade modules include some client code. Client code exports a userinterface so that users can query, display, and modify the new data types.

Client code can be included in the DataBlade module or supplied separatelyfrom the DataBlade module. Applications built on DataBlade modulestypically require new client code.

Using a DataBlade ModuleUniversal Server treats new data types, routines, and other objects in theDataBlade module the same as those built into the server. The extensions areavailable via SQL, SPL, the DataBlade API library, and client programs linkedwith any of the Informix client APIs. DataBlade modules can also use theDataBlade API or SQL queries to access data types and routines in otherDataBlade modules.

From SQLUsers can take advantage of DataBlade module extensions in their SQLqueries as if the data types or routines were originally built into the server.Registering a DataBlade module dynamically extends the SQL querylanguage and the query optimizer and executor. The server process looks updata types, routines, operators, and other objects in system tables at runtime.


From DataBlade API Client Programs

From DataBlade API Client ProgramsClient programs use the DataBlade API, the C++ Interface, or ESQL/C toexecute SQL queries that invoke DataBlade module routines.

From Another DataBlade ModuleSPL routines can invoke routines defined in other DataBlade modulesinstalled in the database. DataBlade module routines are called from SQLstatements the same way as routines provided with the server.

Routines written in C use the DataBlade API library to execute C routines ina shared object file provided by another DataBlade module. If the routine isregistered in the server, it can be executed by sending SQL commands withthe DataBlade API mi_exec() function. Alternatively, a C routine can useDataBlade API routines to locate and execute a routine in another DataBlademodule.

Developing DataBlade ModulesDeveloping a DataBlade module involves defining data types and theroutines that operate on them, writing supporting code for the data types andclient applications, testing, debugging, documenting, and packaging themodule.

The DataBlade Developers Kit includes tools to help develop DataBlademodules. The tools automate many development tasks, provide customerswith products that have consistent contents and user interfaces, and helpensure that DataBlade modules can be certified by Informix.

BladeSmith is a tool for organizing a DataBlade module development project.You use BladeSmith to create a project and then define the objects (such asdata types and routines) that belong to the DataBlade module. BladeSmithgenerates C source files, header files, makefiles, functional test files, SQLscripts, messages, and packaging files. Chapter 4, “Using BladeSmith,”describes how to use BladeSmith.


Developing DataBlade Modules

You must edit the source files that BladeSmith generates and then compilethem. Chapter 5, “Programming DataBlade Module Routines,” describes thecontents of the generated source files and suggests ways that you can modifythem.

Chapter 6, “Testing and Debugging DataBlade Modules,” describes how totest and debug DataBlade modules.

BladePack is the tool for creating a final, installable DataBlade module. Itallows you to define the contents of the DataBlade module and then togenerate diskette images or a directory tree that you can use to creatediskettes, CD-ROM, or tape for final distribution. Chapter 7, “UsingBladePack,” describes how to use BladePack to create an installableDataBlade module from your BladeSmith project.

BladeManager, a utility included with Universal Server and the DataBladeDevelopers Kit, is a database administration tool used to register DataBlademodules in databases or to unregister registered DataBlade modules. Blade-Manager supports the DataBlade modules you create with the DataBladeDevelopers Kit. For information about using BladeManager, refer to theBladeManager User’s Guide.

Figure 1-1 shows how the tools included in the DataBlade Developers Kit areused in the DataBlade module development process.

Customers install a DataBlade module into a Universal Server installation.Installing a DataBlade module copies files from the installation media intothe Universal Server installation directory. Some DataBlade modules includeclient files that are copied into directories accessible to client machines.

After a DataBlade module is installed, customers use BladeManager toregister the module in their application databases. BladeManager runs theSQL scripts that define data types, routines, casts, error messages, and otherobjects in application databases. BladeManager can also be used to unregisterDataBlade modules from databases, ensuring that any dependenciesbetween registered DataBlade modules are not compromised.

Customers can also use BladeManager to retrieve client files from theUniversal Server installation onto their workstations. For example, the instal-lation files for a client application program could be included with aDataBlade module so that the files are installed in the Universal Serverdirectory. Clients can then use BladeManager to copy the files from theUniversal Server installation to their workstations.


Developing DataBlade Modules

Figure 1-1DataBlade Module

Development ProcessBladeSmith

BladePack

Generate files

Edit and compile

Project File

CastsErrorsRoutinesData typesInterfacesTest data

Installable DataBlade module

.bld file

SQL scriptsInstallation

files

.h files

.c files

.Makefile

Functionaltests


2Chapter

INFORMIX-Universal ServerArchitecture

Shared Memory . . . . . . . . . . . . . . . . . . . . 2-4

Virtual Processors . . . . . . . . . . . . . . . . . . . 2-5CPU Virtual Processor . . . . . . . . . . . . . . . . 2-5Extension Virtual Processor . . . . . . . . . . . . . . 2-6Asynchronous I/O Virtual Processor . . . . . . . . . . . 2-7Network Virtual Processor . . . . . . . . . . . . . . . 2-7

2-2 Data

NFORMIX-Universal Server is a high-performance, multithreadeddatabase server. With DataBlade modules, you can extend it to support newdata types and routines. This chapter describes the Universal Server archi-tecture and how it supports DataBlade modules.

Universal Server runs on a single machine, which may be a uniprocessor orsymmetric multiprocessor (SMP) computer. The server comprises severaloperating system processes or threads called virtual processors (VPs). Theserver divides tasks into subtasks and then assigns the subtasks to VPs. Onan SMP computer, VPs are distributed among the available CPUs, allowingUniversal Server to benefit from the performance advantages of bothhardware and software parallel processing architectures.

Figure 2-1 illustrates processes in a simple Universal Server installation.

Figure 2-1Process Diagram of

Universal ServerAIOVP

EXTVP

EXTVP

CPUVP

CPUVP

NetVP

SharedMemory

I

INFORMIX-Universal Server Architecture 2-3

Shared Memory

Each square in the diagram represents a virtual processor running as a singleoperating system process or thread. Although only one or two virtualprocessors of each variety appear in the diagram, an installation can havemany more. For example, the diagram shows a single asynchronous I/O(AIO) virtual processor, but a large Universal Server installation might havemore, depending on performance requirements and workload.

Shared MemoryVirtual processors communicate with one another via shared memory. All ofthe processes can read and write all of the shared memory. The sharedmemory region can grow during the lifetime of the server, in response to thememory requirements of queries active at any given time. Any change to thesize or contents of shared memory is visible to all of the virtual processorsthat use it.

The contents of shared memory include:

■ shared buffers, containing data from database tables or indexes.

■ information on queries that are currently active.

■ information on locks held by active queries.

The information stored for active queries includes one or more thread controlblocks. This data structure is a stack that resides entirely in shared memory. Itincludes local variable storage for every active or pending execution frameand the subroutine call and return pointers that link them.

During query processing, the thread control block moves among the variousoperating system processes that appear in Figure 2-1. At any given time, thequery can have multiple threads running, and an individual thread might beexecuting in any of the processes shown. Any operating system runs at mostone thread per processor. When the process has completed the work it needsto do for the thread, it suspends execution of the thread. The thread’s controlblock goes back on a queue to await further processing.


Virtual Processors

All of the operating systems on which Universal Server runs guarantee thatcode addresses from one VP will be identical to those in all the other VPs. OnUNIX, each of the VPs is created by calling the fork() system call from insidea single master VP. The resulting process address spaces are identical at thetime of the call to fork(), and no code is relocated. As a result, threadmigration among VPs does not require address translations when a thread isrescheduled for execution in a new VP.

Local storage in DataBlade module functions is allocated from sharedmemory. As a result, a DataBlade module routine must not consumeexcessive stack space, either through large local variable declarations orthrough excessively long call chains or recursion. Functions are provided32 KB stack memory when they are called. More stack memory can berequested when the function is defined in Universal Server. A function thatoverruns the shared memory region allocated for its stack overwritesadjacent shared memory, with unpredictable and probably undesirableresults.

In addition, any nonstack storage allocated by a thread must be in sharedmemory. Otherwise, the memory will not be visible when the thread movesfrom one VP to another.

The Universal Server dynamic function manager guarantees that a largestack region is available to a thread before it calls a DataBlade modulefunction, so stack exhaustion is generally not a problem. In addition,DataBlade API provides memory management routines that allocate spacefrom shared memory, rather than from process-private memory. If you usethe DataBlade API interfaces, memory visibility is not a problem.

Virtual ProcessorsThe next several sections explain the roles of the Universal Server VPs.

CPU Virtual ProcessorThe CPU virtual processor carries out most of the work of query parsing,planning, optimization, and execution. This VP is the core of the UniversalServer database engine.


Extension Virtual Processor

When a user submits an SQL string to Universal Server, an idle CPU VP threadaccepts the string and parses it. The result of the parsing step is a parse tree.The thread computes a plan from the parse tree by examining the systemcatalogs. It then determines which tables and columns must be fetched. Thethread evaluates different execution plans and selects the one it estimates tobe most efficient.

After parsing and planning, the query can be divided into one or more unitsof execution. A database table can be spread across multiple storage regionsin Universal Server, and the query might need to examine all of these regions,so the planning thread can spawn multiple subthreads to evaluate the query.Each thread operates on at least one storage region.

Once the plan is complete, the planning thread queues as many executionthreads as are necessary to satisfy the query.

Query execution involves examining values to see if they meet user-specifiedcriteria (in the WHERE clause, for example) or doing computations on values(in the target list, for example). The execution threads can run in parallel ondifferent CPU VPs, they can run serially on a single CPU VP, or they can mixthe two execution modes.

Results from each thread are collected by a single master thread, whichcollates the answers and delivers them back to the user.

Extension Virtual ProcessorThe extension VP (EXT VP) performs the same work as a CPU VP, except that,at the expense of server performance, it relaxes restrictions the CPU VPimposes on DataBlade module functions.

Functions running in an EXT VP need not explicitly yield the processor andmay issue direct (blocking) file system calls. Blocking calls suspend the EXTVP, but normal processing of user queries in CPU VPs is not affected.

Code that runs in an EXT VP must still be thread-safe, and it must use theDataBlade API memory allocator for heap storage. Some DataBlade APIroutines can suspend a thread that calls them. When the thread resumes, theserver can move it to a different EXT VP. If this happens, memory that was notallocated from shared memory becomes inaccessible.


Asynchronous I/O Virtual Processor

Asynchronous I/O Virtual ProcessorAn asynchronous I/O virtual processor (AIO VP) implements asynchronousI/O for query threads. Any time a thread executing in a CPU VP requires datafrom disk, the request is handled by the AIO VP.

This service permits threads to issue read or write calls and continueprocessing while waiting for them to complete. If the thread has no otherwork to do, it can suspend and go on an idle queue until the request issatisfied.

Asynchronous I/O is important for Universal Server threads becausesynchronous (blocking) I/O suspends a process that requests it. For example,if a thread issues a blocking I/O call from inside a CPU VP, the entire CPU VPis suspended by the operating system and can do no work while it waits forthe requested data to be read from or written to the disk.

Universal Server requires that all execution threads running in a CPU VPperform nonblocking I/O. The DataBlade API interfaces for file and largeobject access implement nonblocking I/O transparently to the caller. When aDataBlade module function calls mi_read(), the library code issues anasynchronous I/O request and then suspends the thread until the I/Ocompletes. When the request has been satisfied, the thread resumesprocessing and returns to the caller. This is the same general mechanism usedby operating systems to handle blocking I/Os for processes, but sinceUniversal Server handles thread scheduling directly, the virtual processor isfree to continue executing on behalf of another thread.

Network Virtual ProcessorThe network virtual processor (NET VP) handles network communicationswith the client and with other servers. These virtual processors handlecommunications with clients that connect to the server using any of theInformix client APIs. DataBlade module functions do not access NET VPsdirectly.


3Chapter

Designing DataBlade Modules

Data Model . . . . . . . . . . . . . . . . . . . . . 3-4

Data Type Design . . . . . . . . . . . . . . . . . . . 3-6

Query Language Interface . . . . . . . . . . . . . . . . 3-8SQL Query Structure . . . . . . . . . . . . . . . . . 3-8The Target List . . . . . . . . . . . . . . . . . . . 3-9The Qualification . . . . . . . . . . . . . . . . . . 3-11

Query Processing . . . . . . . . . . . . . . . . . . . 3-12Predicate Evaluation . . . . . . . . . . . . . . . . . 3-13Expensive Routines . . . . . . . . . . . . . . . . . 3-13Sorting. . . . . . . . . . . . . . . . . . . . . . 3-14Grouping . . . . . . . . . . . . . . . . . . . . . 3-15Casts . . . . . . . . . . . . . . . . . . . . . . 3-16Access Path Selection. . . . . . . . . . . . . . . . . 3-17

Unordered Processing of Rows . . . . . . . . . . . . 3-18Secondary Access Methods . . . . . . . . . . . . . 3-18

Planning for Transaction Semantics . . . . . . . . . . . . 3-20

Interoperability . . . . . . . . . . . . . . . . . . . . 3-20Orthogonality . . . . . . . . . . . . . . . . . . . 3-21Simple Clean Interfaces . . . . . . . . . . . . . . . . 3-22Coding Standards . . . . . . . . . . . . . . . . . . 3-23Performance, Robustness, and Value . . . . . . . . . . . 3-24Choosing a Virtual Processor Class . . . . . . . . . . . . 3-25Writing Thread-Safe Routines . . . . . . . . . . . . . . 3-25Avoiding System Calls . . . . . . . . . . . . . . . . 3-26

Implementation Issues . . . . . . . . . . . . . . . . . 3-26Naming DataBlade Module Objects . . . . . . . . . . . . 3-27Registering Your DataBlade Module . . . . . . . . . . . 3-27Using the Registered Object Prefix . . . . . . . . . . . . 3-28

3-2 Data

DataBlade Module Directory Structure . . . . . . . . . . . 3-29New or Old Code? . . . . . . . . . . . . . . . . . . 3-29Using the DataBlade Developers Kit Tools . . . . . . . . . 3-30Developing Iteratively . . . . . . . . . . . . . . . . 3-30Testing and Certifying DataBlade Module Code . . . . . . . 3-31Debugging DataBlade Modules . . . . . . . . . . . . . 3-31Certifying DataBlade Modules . . . . . . . . . . . . . 3-31

Supporting Client Applications. . . . . . . . . . . . . . . 3-32Using DataBlade Modules from a Client . . . . . . . . . . 3-32Providing Client-Side Libraries . . . . . . . . . . . . . 3-33Using the Informix C++ API . . . . . . . . . . . . . . 3-33


his chapter provides guidance on designing and developingDataBlade modules to extend INFORMIX-Universal Server.

To ensure that a DataBlade module is valuable to customers andmaintainable by future engineers, you should design with goals of perfor-mance and robustness. This chapter describes many DataBlade moduledesign alternatives and helps you to choose alternatives that will contributeto the best performance, robustness, and customer value for DataBlademodules that you develop.

The chapter discusses the following topics:

■ Data model. The data types and the operations that the DataBlademodule supports on them.

■ Data type design. How to determine whether to use a row data typeor an opaque data type.

■ Query language interface. How database users access the DataBlademodule.

■ Query processing. How DataBlade module operations executeinside Universal Server.

■ Interoperability. How new DataBlade modules work with existingand future DataBlade modules.

■ Implementation issues. How to code, test, debug, and certifyDataBlade modules.

■ Supporting client applications. How to ensure that client applica-tions can easily access DataBlade module data types and routines.

T

Designing DataBlade Modules 3-3

Data Model

Data ModelA data model defines the data types provided by a DataBlade module and theoperations performed on them. The separation of the user interface from thedata model is the most important step in designing a DataBlade module.Consider the data model independently from the applications that use it andthe user interface required by those applications. Concentrate on designing aservice, rather than an application. Build a data model that is reusable bymultiple client applications, rather than one tailored to a particular clientapplication.

For example, consider an application that stores, manipulates, and drawsmaps. The data model for a mapping application consists of spatial datatypes and the operations performed on them. It includes polygons, repre-senting entities like countries and cities, and line segments, representingroads and rivers.

Searching routines are most useful with these data types. For example, aroutine that determines whether two polygons overlap allows the mappingapplication to determine whether a particular city appears in the visibleregion of a map. Other routines could determine whether line segments shareendpoints or intersect so that the mapping application can construct a graphthat represents road or river networks.

This mapping data model allows you to make requests such as, “Find all thepolygons in the map that fall inside the currently visible region, where thecurrently visible region is a given polygon.” The query scans the databaseand returns only the polygons of interest. Thus, you do not need to writeapplication code to decide whether the polygons overlap; you can use theservice provided by the mapping DataBlade module.

One routine that does not belong in the data model is the display logic for thetypes you define. In the mapping example, the rendering of polygons is auser-interface issue, not a data model issue. The data model should onlyinclude abstract operations on the data types required by a user interface.With DataBlade module routines that compute polygon intersections, youcan write a client application that queries the database for polygons ofinterest and draws them on the screen. The client application code does nothave to choose the desired polygons from a larger set retrieved from thedatabase.


Data Model

The data model for a DataBlade module should be simple to understand. TheDataBlade module should provide a rich set of services via a minimal set ofroutines. This fundamental software design concept applies to DataBlademodules in particular, because DataBlade modules are intended for reuse byother developers.

For example, in the mapping DataBlade module, assume that users want tofind overlapping regions on a map. The DataBlade module can provide anumber of different interfaces to support the query. Two examples are:

Overlaps(Polygon, Polygon)

and

Contains(Polygon, Polygon)

The Overlaps() routine returns TRUE if any parts of the two polygonsoverlap. The Contains() routine returns TRUE if the first polygon completelycontains the second. These two routines are simple to understand and easyto remember.

You might consider an additional routine for the mapping DataBlademodule:

Intersects(Polygon, Polygon)

The Intersects() routine returns TRUE only if the boundaries of the twopolygons intersect. Intersects(a,b) is equivalent to the following:

Overlaps(a, b) and not (Contains(a, b) or Contains(b, a))

Intersects() and Overlaps() are confusing when both are supplied. Usershave difficulty remembering which routine computes which value when thesemantics of the routines are too similar. Since Overlaps() and Contains()together can compute intersections, it is probably best to leave Intersects()undefined.

When you construct a data model, separate the routines useful for a singleapplication from the more general service routines. For example, in themapping application, you might provide a routine that would take a polygonas an argument and return another polygon whose border was exactly onepixel outside the original. When drawing the polygon on the screen, you canuse the two polygons together to create a polygon with a thick border.


Data Type Design

However, this routine is not generally useful to other users who operate onspatial data for a mapping application. It is unique to a particular application.It is a poor candidate for inclusion in a DataBlade module. A better place forthis routine would be an application that does the screen rendering, since thatroutine “understands” the desired appearance of thick-bordered polygons.

In summary, the important steps in data modeling are the following:

■ Separate the user interface from the abstract operations on data.

■ Think about data types and routines that operate on them.

■ Keep the design simple.

■ Do not add server routines intended to support a single application.

Data Type DesignA DataBlade module typically provides data types that allow UniversalServer to operate on objects with characteristics shared by other similarobjects. Usually, the individual characteristics of an object can be representedusing data types already supported in the database. You can choose row datatypes or opaque data types to store these kinds of objects.

Row data types are records that contain fields of types known to the DBMS, justas rows are records in tables that contain fields known to the DBMS.

Opaque data types are data structures manipulated with a high-levelprogramming language like C. Universal Server cannot access fields withinthe data structures, so it cannot automatically extract values from opaquedata types.

Use row data types for any type that is just a container and whose constituentvalues users always want to access. For example, you could choose tosupport an Address type in the mapping DataBlade module. Most peoplewant to see and operate directly on the street number and street name,country, and postal code. If you define the type as a row type, UniversalServer automatically provides direct access to each of the fields:

create row type Address(street_number real, street_name varchar(40), city varchar(100), country varchar(40), postal_code varchar(20));


Query Language Interface

If you created the type as a C structure storing all the same information, youwould have to define accessor routines for the street number, name, and soon. The DataBlade module would be more complicated to write and to use,and the query language interface would be more confusing.

Since Address is really just a container type, you should take advantage ofthe container services provided by row types. This allows users to writequeries like

select * from employees where address.city = 'Vienna';

In contrast, the mapping DataBlade module’s Polygon type should beopaque. Users seldom need to examine individual points from a polygon. Ifyou implement the type as a C structure, you get an efficient representationthat you can operate on easily with C code. The query language interfaceremains simple.

When you design data types, ask yourself the following questions:

■ Is the data type just a container for a collection of values that userscan access directly? If so, use a row data type.

■ Is the type naturally indivisible, or do you want to hide its represen-tation from users? If so, use an opaque data type.

■ Is the representation you have chosen easy to use in SQL? Does itmake queries simpler or more complicated?

Query Language InterfaceThe next component in DataBlade module design is the query languageinterface. Since Universal Server is an object-relational database engine, youaccess it by formulating queries in SQL. DataBlade modules extend SQL bydefining new types and new routines that are available to queries. Considerthe syntax that users must master to use a DataBlade module.

SQL Query StructureSQL includes Data Definition Language (DDL) statements and Data Manip-ulation Language (DML) statements.


The Target List

DDL statements, such as CREATE, ALTER, and DROP, are used to modify theschema of a database. DML statements, such as SELECT, INSERT, UPDATE, andDELETE, manipulate data in tables.

Most SQL queries use DML statements. In designing a DataBlade module,you should consider DML statements in the abstract. DML statements are inthe following forms:

select something from some tableswhere some conditions are satisfied

or

update some table set somethingwhere some conditions are satisfied

The italicized components above serve different purposes in the DML query.The some table part is called “the from list” and is not important to considerwhen designing a DataBlade module. The something part is called “the targetlist” and identifies the columns of interest in the query, either for retrieval orupdate. The target list is the target on which the query is operating. The someconditions are satisfied part of the query is called “a qualification” because itidentifies the rows that qualify to participate in the operation.

In the following two sections, the routines that typically appear in the targetlist and qualification are addressed. DataBlade module routines can appearin either the target list or a qualification. However, when developing aDataBlade module, you should consider where you expect a particularroutine to be used most often.

The Target ListThe target list is where simple computation occurs. You should considerproviding DataBlade module routines for common computations on opaquedata types. Performing the computation in the DataBlade module eliminatesthe need to implement the routine in the client application. Using DataBlademodule routines in the target list can also reduce the amount of data trans-ferred from the server to the client, improving system performance.

Consider the following sample query from the mapping example outlinedearlier in this chapter:

create table cities (name text, population integer,boundary Polygon);


The Target List

Polygon is a data type supplied by the mapping DataBlade module.

To retrieve a list of all cities, their populations, and population densities, youcould submit the following query:

select name, population, population / Area(boundary)as density from cities;

In this example, the Area() routine is supplied by the mapping DataBlademodule. Area() returns a floating-point number that is the area of thesupplied polygon. You can invoke the built-in division operator to computedensity from population and area. This query does a simple computation inthe target list, using a mixture of DataBlade module and built-in routines.

This computation can also be done on the client. The client would have toimplement the Area() routine for polygons, and the server would have toship all of the polygons to the client. This would be more expensive thanshipping the results of the division across the network, since polygons can bequite large. Generally, any computation that appears in the target list can alsobe done by the client. Thus, target-list routines should run in the DataBlademodule server routines only if there is an advantage to be gained by doing so.

If there is no advantage to running the routine on the server, you shouldconsider leaving it out of the DataBlade module altogether and allowingclient application developers to implement it in the client. If the serverroutine provides any of the following advantages, it is a good candidate forinclusion in the DataBlade module:

■ It reduces the volume of data transferred to the client.

■ It simplifies application development by sharing code among clientsmore effectively.

■ It benefits from Universal Server parallelism and scalability.

The division operator that appears in the query actually translates into a callto a division routine built into Universal Server. Built-in routines andDataBlade module routines can be combined in queries, as shown by usingdivision with Area() in the previous example. This is also true for routinesfrom different DataBlade modules—DataBlade module routines can bemixed and matched by users to provide interesting services.


The Qualification

Thus, when you design a data model, consider carefully how to leverageexisting types and those provided by other DataBlade modules. In theexample above, you could define a new data type, called AreaType, torepresent the area of geographic objects. However, then you would have toimplement all the math on AreaType values yourself. By using real numbersto represent areas, you can leverage existing math and computationalsupport in the database engine and allow users to mix and match mappingroutines with routines provided outside the mapping DataBlade module.

You could define a routine that computes population density inside themapping DataBlade module. The routine would take two parameters—apolygon and an integer—and do the division itself. However, no realsemantic power is derived from this design. Leaving special-purposeroutines out of the DataBlade module not only keeps the interface simpleenough to understand, but also lets developers define their own expressionsor routines to compute specific values. A simple DataBlade module thatintegrates well with existing data types is always better than a complicatedone with many predefined routines that cannot be used in conjunction withbuilt-in or foreign DataBlade module routines.

If you expect a DataBlade module routine to be used only in the target list,consider leaving it out of the DataBlade module altogether. Put it in theDataBlade module only if there is an advantage to doing so. Be sure yourtypes and routines are simple and easy to understand. Allow users to writetheir own queries that use the DataBlade module routines in special ways,rather than trying to predict all the specialized uses up front.

The QualificationThe qualification restricts the set of rows returned to the user. It is used to filterout records that are not interesting. Only the records that pass the qualifi-cation are evaluated in the target list. Thus, a qualification is a more powerfultool than the target list.

A single expression in a qualification is called a predicate. An qualification cancontain one or more predicates joined by the Boolean operators AND and OR.

If a DataBlade module routine is used in an expression, it filters the recordsreturned to the client. When filtering, Universal Server can operate on thecontents of new data types. This capability is unique to object-relationaldatabase engines and is not available in conventional relational databases.


The Qualification

You should consider whether the routines you define are more likely to beused in the target list or the qualification. Routines more commonly used inthe qualification make better use of Universal Server extensibility becausethey support searches that cannot be done efficiently on conventionalrelational engines.

The following is an example of a DataBlade module routine used in aqualification:

select name, boundary from cities whereOverlaps(boundary, '(1,1), (5,5), (7,7), (8,9)');

In this example, the Overlaps() routine is provided by the mappingDataBlade module and takes two polygon arguments. It returns TRUE if thetwo polygons overlap and FALSE otherwise. The second argument is aconstant string describing a polygon you are interested in. This querysearches the cities table for those cities that overlap the region of interest. Asmall number of rows is returned to the client. The server uses the Overlaps()routine to qualify rows.

The separation between routines used in the target list and those used in thequalification is not absolute. For example, the following query finds thenames and populations of large cities:

select name, population from citieswhere Area(boundary) > 500;

In this example, the Area() routine appears in the qualification. On page 3-9,the Area() routine appeared in the target list.

Some routines are better suited to the qualification than the target list. A goodexample of this distinction is the Overlaps() routine. This routine is morepowerful in the qualification. While it is possible to formulate a query like thefollowing, it is not very common:

select Overlaps(boundary, '(1,1), (5,5), (7,7), (8,9)')from cities;

This query returns a list of yes-or-no answers for each city in the table thatoverlaps the supplied constant polygon. It is more common to use theOverlaps() routine to filter rows than to compute values returned to the user.However, important and useful exceptions to this rule exist, for example:

select a.name, Overlaps(a.boundary, b.boundary)from cities a, cities bwhere b.name = 'Los Angeles';


Query Processing

This query returns a list of all cities in the table and whether they overlapwith Los Angeles.

To help decide which routines to include in the DataBlade module, considerthe following:

■ What questions will users want to ask about the contents of the newdata types in the DataBlade module?

■ What routines allow them to ask those content-based questions?These routines are used in the qualification.

Query ProcessingTo develop a DataBlade module, you should have a general understandingof query processing in Universal Server. Since SQL is the interface betweenthe end user and the DataBlade module, an understanding of SQL queryexecution will help you to build more robust, high-performance DataBlademodules.

You must also understand the execution environment inside UniversalServer—the multithreading model, the collection of processes in whichDataBlade module routines can execute, and concurrent access to databaseobjects, transactions, and so on. This section describes query processing.

Predicate EvaluationAn expression in the qualification of a query is a predicate. In the followingquery:

select name, boundary from citieswhere Overlaps(boundary, '(1,1), (5,5), (7,7), (8,9)');

this expression is a predicate:

Overlaps(boundary, '(1,1), (5,5), (7,7), (8,9)')


Expensive Routines

The database engine evaluates the predicate for every row in the table andreturns to the client the rows that satisfy the predicate. Each predicate in aqualification eliminates rows from the candidate set. Once the server deter-mines that a row does not satisfy a predicate, it stops evaluating the row andmoves on to the next candidate row.

Most predicate evaluation is straightforward—values of interest areextracted from a candidate row and evaluated against the predicate.However, there are some cases where predicates in the qualification behavein a unique way. These cases are described in the following sections.

Expensive RoutinesExpensive routines are routines that either take a long time or require a greatdeal of space to run. Conventional relational database systems do notaccount for expensive routines; any predicate that appears in a query isassumed to be as expensive as any other. For example, comparing twofloating-point numbers is not more difficult than comparing two integers. Forrelational databases, this is the right approach.

However, an object-relational database system must evaluate relativefunction costs. Some routines are very difficult to compute or require a greatdeal of intermediate space. For example, it can take many thousands ofmachine instructions to determine whether two polygons overlap.

Because an object-relational database stops evaluating predicates as soon asit determines that a row does not satisfy the criteria, the database enginechooses an optimum order to evaluate the predicates in a query. If it evaluatesall the expensive predicates first, the query runs slower than if it considersthe inexpensive predicates first.

The strategy for choosing the optimal order to evaluate predicates is complexand beyond the scope of this discussion. However, the database engine mustevaluate the cost of invoking user-defined routines in order to run queriesefficiently.

Therefore, when you define a new routine, you should tell the databaseengine how expensive it is to evaluate. Most DataBlade module routines areat least as complex as a routine that compares floating-point numbers. ForDataBlade module routines that are more expensive, describe the relativeexpense to Universal Server.


Sorting

A good formula for estimating the expense of a routine is:

<lines of code> + (<number of I/Os> * 100)

For example, if a routine has 100 lines of code and performs 5 disk I/Os orSQL queries, the cost is 100 + (5 * 100), or 600.

When estimating the cost of executing a routine, consider the following:

■ Which DataBlade module routines take a long time to run?

■ Which DataBlade module routines consume large amounts ofmemory?

■ How expensive are the DataBlade module routines relative to oneanother?

■ How expensive are the DataBlade module routines relative toexpensive routines defined by other DataBlade modules?

SortingSQL allows you to sort result rows when you express your queries. Sortedresults are useful when you need to see records in some particular order.

The following query sorts a list of cities and their populations in order ofdescending population:

select name, population from cities order by population desc;

If a DataBlade module defines a data type on which sorting is meaningful,then you must supply a comparison routine for the type. This allows the enduser to order query results on that type.

In addition, you can use the results of routines that appear in the target list toorder the results of a query. For example, the following query returns a list ofcities in descending order of population density:

select name, population,population / Area(boundary) as densityfrom citiesorder by density desc;


Grouping

The density expression, on which the query results are sorted, is a complexcalculation. It includes a DataBlade module routine and a division operation.This is another example in which leveraging built-in types for the returnvalue of a DataBlade module routine gives you more power. Since UniversalServer includes support for ordering by integers, the preceding queryrequires no special ordering support from the DataBlade module.

You should ask the following questions:

■ Is there a total ordering on any of the data types that the DataBlademodule defines?

■ What values will end users likely want to sort on?

GroupingSQL allows you to write queries that consider records in groups. This is apowerful facility for summarizing data, particularly in combination withaggregates such as COUNT or SUM. The following query uses grouping andaggregates:

select COUNT(name), population from cities group bypopulation;

This query returns the number of cities that have the same population foreach distinct population value that appears in the table. The GROUP BY clausebreaks the set of result rows into groups with equal populations; then thetarget list is evaluated for each group separately. The COUNT aggregatecounts the number of city names in the group.

If you create a DataBlade module, you should consider whether any of thetypes you define are candidates for grouping. In the mapping DataBlademodule, for example, polygons are a poor candidate; users seldom want tobreak geographic data into bins that contain identical polygons.

Like sort keys in queries, grouping can be done on complex expressions. Forexample, the following query divides cities into groups that are within 10units of the same area, then adds the population for the group:

select Area(boundary) / 10 as dimensions, SUM(population)from cities group by dimensions;

To determine whether your DataBlade module requires support routines forgrouping, ask the following questions:


Casts

■ For each type in the DataBlade module, can the values sensibly bebroken into groups that are equivalent?

■ What is the meaning of each of these groups?

■ Will users want to group values in that way?

■ As a result, which types require support routines for grouping?

CastsThe ability to cast values from one data type to another provides you with apowerful tool for constructing interesting queries. If your DataBlade moduledefines types that are similar or comparable, consider defining casts betweenthe types. You can also supply casts from DataBlade module types to built-intypes and to types defined by other DataBlade modules.

Casting values allows the query processing engine, implicitly or explicitly, tochange the type of a value and use it as an argument to routines that requirethe destination type.

In an inheritance hierarchy, casting can provide another mechanism for typeconversion. In general, subclasses can be implicitly cast to superclass types.However, downward casts (that is, from supertype to subtype) are notautomatically supported, since subclasses typically add instance variablesnot present in the supertype.

Similarly, distinct types can often be cast to their source type. For example, adistinct type called LIRA, based on REAL, might allow casting to REAL, toallow simple math operations on it. However, you probably do not wantREAL to be castable to LIRA, or there would be no need to create the distincttype.

Casts are powerful, but they can confuse users if overused. Implicit casts hidean important fact from users—that a loss during type conversion mightoccur. Explicit casts, which users must explicitly request in their queries, donot have this problem. But the cast invocation can make queries harder toread.

As a result, casts should be used where necessary, but only where necessary.Be sparing in the casts you supply to users, and be sure you understand thecircumstances under which you expect casts to be used.

To determine whether to provide casts, ask the following questions:


Access Path Selection

■ Are any of the types in the DataBlade module comparable? Do theyreally need to be different types? If so, should there be support forexplicit or implicit casts between those types?

■ Will users want to convert between values type and some other type,defined by the DataBlade module or built into the database engine?

■ Which direction should the conversion go? In general, casts shouldonly go one way, unless you intend them to be explicit.

Access Path SelectionDuring query processing, Universal Server takes a nonprocedural query andproduces a procedural plan for satisfying it. Queries are nonproceduralbecause they describe only the records of interest and what operations toperform on them. They do not prescribe an algorithm (procedure) forlocating records on disk or the order in which to process them.

Picking a strategy for reading records from disk is called access path selection.Universal Server considers a collection of possible query plans that canexecute the query correctly. The server estimates the cost of running eachplan and chooses the one with the smallest cost estimate. Cost estimates area combination of the number of expected disk I/Os, the expected number ofrecords that must be processed, and the cost of invoking each of the routinesin the query on candidate rows.

Unordered Processing of Rows

When you design a DataBlade module, you cannot control how queries areexecuted. There is no guarantee that two routines in a query are called in anyparticular order. DataBlade module routines are snap-in modules called atunpredictable points during query processing to compute answers toqueries. DataBlade modules should not hard-code query execution strat-egies. For example, attempting to force an index scan, or a sequential tablescan, reduces the number of choices available to the query optimizer,resulting in poor performance.

To ensure that your DataBlade module does not conflict with the queryprocessing engine, you should ask the following questions:


Access Path Selection

■ Do any routines require values to be delivered in some particularorder? If so, the routine breaks a fundamental rule of relationaldatabase systems and should be changed.

■ Is it important for routines in a query to execute in some particularsequence? Again, the routines should be changed.

Secondary Access Methods

An important consideration in access path selection is the availability ofsecondary access methods. A secondary access method is an index that allowsqueries to be evaluated more efficiently. When you create a table in SQL, youcan choose to create a B-tree index on one or more columns in the table. Thequery processing engine can choose to use the index for some queries. Forexample, if there is an index on the population column of the cities table, thequery processing engine has at least two choices for evaluating the query:

select name from cities where population > 1000000;

The query processing engine can scan the cities table sequentially, examiningeach record in turn and comparing the population to one million, or it can usethe B-tree index to quickly find only those records with populations of morethan one million. When it chooses to use the B-tree index, the engine does notconsider records with smaller populations and does not read them from thedisk.

The B-tree index stores the key value (for example, the population) and apointer to the record in the base table. The base table is the primary store, andthe index is a secondary access method. If you implement a data type thatsupports a new kind of index, you can create a new secondary access methodfor use in query processing.

For example, most text search engines use a textual index to run searchesquickly. These indexes can be built into the DataBlade module. UniversalServer allows users to create those indexes and uses them to evaluate queries.Similarly, spatial data can be indexed in a number of ways, including gridfiles and R-trees.


Planning for Transaction Semantics

You can allow the creation of other indexes on your data types. For example,a DataBlade module that defines a new type on which a total ordering existscan allow users to create B-tree indexes on that type. To do so, you create anoperator class for the type. An operator class is a collection of routines thatallows the type to be used in a given access method. For example, theoperator class for B-trees includes the routines LessThan, LessThanOrEqual,Equal, GreaterThanOrEqual, and GreaterThan. When you define thoseroutines on a new data type, B-trees are available to users of the type.

When you support existing access methods on new types, you help the enduser by providing more tools for tuning query performance in a particularschema. Thus, if you can define an access method or an operator class for anew type, you should do so.

You should consider the following issues:

■ Do any data types in the DataBlade module permit indexing by anew access method? If so, is the benefit to users significant enough tojustify creating the access method for Universal Server?

■ Could you use an existing (that is, built-in or other DataBlademodule) access method for any of the DataBlade module data types?If so, you should define an operator class for each such instance.

Planning for Transaction SemanticsOne important point to bear in mind is that DataBlade module code runs intransactions. A transaction is a single, atomic, independent sequence ofclient/server interactions. For example, inside a transaction, a user cansearch a table for all the cities that overlap Los Angeles. In a separate trans-action, some other user can change the boundaries of Los Angeles, asoutlying areas are incorporated into the city. The two operations areindependent of one another. Each user is isolated from the changes made bythe other until the next transaction begins.

You must define DataBlade module code to be stateless and not to assumethat any particular value persists across user transactions. For example, aDataBlade module that does text matching might have two operations. Oneis to find all the documents that match a particular set of user keywords. Theother is to highlight matching keywords in the documents themselves.


Interoperability

If a user first runs a query to find matching documents, and then runs aseparate query to highlight the matches, the second operation cannot rely onany cached results from the first. The reason for this is that the databasecontents might have changed between calls—some document contents mighthave changed. In addition, because Universal Server is a multiuser system,different users can run the same routines at the same time. There is no way toguarantee that “saved” results belong to a particular query.

It is critical that you design systems that operate correctly in thisenvironment. Ask yourself the following questions:

■ Do any of routines assume that results from previous user actions arestill valid?

■ Do I try to cache results for reuse later?

■ What will happen if two different users run the same routine on thesame table at the same time?

InteroperabilityDataBlade modules support new data types and new operations on existingdata types. Typically, a single DataBlade module provides support for aspecific kind of data or operation.

Users have complicated data management problems that involve manydifferent kinds of data. Universal Server is ideal for managing many differentkinds of data because it allows users to choose the DataBlade modules theyrequire to solve their particular problem. Universal Server extended with acollection of DataBlade modules is a special-purpose query processingengine tuned for the requirements of a particular user.

As more DataBlade modules become available, every DataBlade modulebecomes more valuable because it can be combined with others in differentways, satisfying more user applications.

However, this enhanced query processing environment requires thatDataBlade modules interoperate. If a user cannot arbitrarily combinedifferent DataBlade modules developed by different developers, eachDataBlade module loses some of its value.


Orthogonality

OrthogonalityThe term orthogonality describes a system, such as an object-relationaldatabase, where the various parts work together in a natural, semanticallylogical way. A DataBlade module should provide solutions for the problemsit is intended to solve, and it should rely on Universal Server or otherDataBlade modules to solve problems outside of its domain. Similarly, aDataBlade module should allow other DataBlade modules to use its facilitiesin a natural, semantically logical way.

A mapping DataBlade module, for example, should not implement full-textsearch. Developers who are experts in text search should build DataBlademodules that satisfy this requirement. The mapping DataBlade moduleshould rely on those developers to deliver the required functionality, insteadof implementing it within the DataBlade module.

A simple rule for ensuring orthogonality in DataBlade module developmentis, “Do a small number of things well.”

Consider the data types and operations a DataBlade module provides:

■ Are they easy to understand?

■ Is there exactly one way to express important operations? Thereshould only be one routine that does any particular job.

■ Does the DataBlade module define routines over types that it doesnot create? Would it be better to let another, specialized DataBlademodule define those operations?

Simple Clean InterfacesAll of the services that your DataBlade module implements should be easy toexplain and use. Whenever possible, use generally accepted names forroutines over your new data types. For example, the Overlaps() routine inthe mapping example does precisely what its name indicates. Users knowwhat to expect when they call it, and the name is an important piece ofdocumentation for the routine.


Simple Clean Interfaces

DataBlade module routines should take a small number of arguments andshould not include arguments that make them modal. For example, there area number of different ways to call a routine that computes containment ofspatial values. The mapping DataBlade module could implement:

Containment(polygon, polygon, integer);

This example determines whether the first polygon contains the secondpolygon, or whether the second contains the first. The caller supplies aninteger argument (for example, 1 or 0) to identify which value to compute.This is modal behavior—the mode of the routine changes depending on thethird argument.

Consider a second design for calculating containment:

Contains(polygon, polygon)ContainedBy(polygon, polygon)

This design is an improvement because the routine names clearly explainwhat computation is performed. You should always construct your routinesto be nonmodal, like this second example.

When you design your DataBlade module, keep the number of arguments inits routines small. If a routine takes a large number of arguments, it is morelikely that users will have to consult the documentation to determine howcall it. Make your routine easy to remember and easy to call.

One way to make routines easy to remember is to choose sensible names forthem. For example, the routine name ContainedBy() succinctly describeswhat the routine does.

Since Universal Server supports polymorphism, you can have multipleroutines with the same name that nevertheless take different argument types.A C programmer might be tempted to create functions named:

bigger_int(integer, integer)

and:

bigger_real(real, real)

These functions return the larger of their arguments. However, in SQL theseroutines are better defined as:

bigger(integer, integer)


Coding Standards

and:

bigger(real, real)

Using the naming in the second example allows users to ignore the types ofthe arguments when they call the routine. They simply remember what itdoes and let Universal Server choose which supporting routine to call, basedon the argument types. This makes the DataBlade module simpler to use.

You should consider the following questions about routine naming anddesign:

■ Are any of my routines modal?

■ Can I describe what each type and routine does in two sentences?

■ Do any of my routines take more than three arguments?

■ Have I used polymorphism effectively?

Coding StandardsA collection of standards for DataBlade module development, DataBladeDeveloper Standards and Guidelines, is available from the DataBlade Devel-opers Program. The most important rules govern the naming of DataBlademodule objects, such as types and routines. These name-spaces are shared byall DataBlade modules, so you must follow the naming guidelines toguarantee that there are no problems registering multiple DataBlademodules in a single database.

In addition, the standards for 64-bit clean implementation, safe functioncalling practices, thread-safe development, and platform portability areimportant. Adherence to these standards ensures that DataBlade modulesare portable across platforms.

You should ask the questions:

■ Do I obey all naming standards for DataBlade modules?

■ Is my design 64-bit safe and portable across platforms?

■ Is my design thread-safe?


Performance, Robustness, and Value

Performance, Robustness, and ValueThe most important criteria for users evaluting a DataBlade module areperformance, robustness, and value. That is, whether a DataBlade modulemakes queries run faster, whether it is robust (it returns the right answers andis reliable), and whether it makes data processing easier. The first two criteriaare easy to measure. The third is less quantifiable, but just as important.

You must consider performance when you design your DataBlade module.Build small, fast routines. If there are tuning parameters that can allow usersto better control the performance they get, think of a sensible way ofsurfacing them to users and explain clearly what they do. Specify perfor-mance goals up front and design tests that will measure the actualperformance of your DataBlade module running in Universal Server.

The next several sections include specific hints for designing fast, reliableDataBlade modules. During each step in the design process, address thefollowing general issues, as well:

■ Why would customers want to use this DataBlade module?

■ Are the DataBlade module operations useful? Will customers investtime in learning how to use the DataBlade module?

■ Is there a specific, identifiable customer for the DataBlade module?What does that customer want to do?

■ What kind of performance do customers expect from the DataBlademodule? How will I verify that the DataBlade module achieves thatperformance?

■ Are there ways that I can allow users to tune performance? If so, haveI designed a simple, sensible interface to tuning parameters?

Choosing a Virtual Processor ClassYou must choose the virtual processor (VP) class in which to run theDataBlade module. DataBlade modules routines can run in the CPU VP or theEXT VP. Generally, DataBlade modules perform best in the CPU VP becausethreads do not have to migrate among operating system processes duringquery execution. However, CPU VP execution requires additionalprogramming. You must make sure your code does no blocking operationsor local resource allocations and that it voluntarily releases the CPU on aregular basis.


Writing Thread-Safe Routines

DataBlade module routines that cannot run in the CPU VP can run in an EXTVP. Running in an EXT VP relaxes some, but not all, of the programmingrequirements. These routines can perform blocking operations, but they stillcannot perform local resource allocations since they might migrate amongthe VPs. Using the EXT VP results in lower performance because queriesnormally execute in the CPU VP, and the query thread must migrate to theEXT VP to evaluate DataBlade module routines. Thus, you should use the EXTVP with caution.

You should consider the following issues:

■ Which VP should the DataBlade module run in? What can I changein my design to allow the DataBlade module to run in the CPU VP?

■ Have I followed the rules for the VP I have chosen?

Writing Thread-Safe RoutinesDataBlade module routines must be thread-safe. The main problems withlibraries that are not thread-safe are global variables and an assumption that,in any particular instance, only one thread of control has access to importantdata structures. Any data stored globally in memory is subject to sharedaccess. There is no mutual exclusion to guarantee nonshared access duringcritical sections.

You should consider the following questions:

■ Are there any global variables in my code? How can I eliminatethem?

■ Are there static local variables in my code? How can I eliminatethem?

■ Do I assume that only one thread is executing at a time? For example,do I make file system calls that create files by some name thatrequires only one instance of my DataBlade module routine to berunning at a time?


Avoiding System Calls

Avoiding System CallsVirtually all system calls can block, causing the operating system to suspendthe process that calls them. Thus, routines that execute in the CPU VP shouldnot make any system calls. In addition, many system calls allocate process-local resources and should not be used in either the CPU VP or the EXT VP. Forexample, the malloc() function allocates memory in the private address spaceof the operating system process, rather than in the shared memory availableto all VPs. If the thread of execution migrates to another VP, it does not haveaccess to memory that was allocated with malloc(). Similarly, the open()function returns a process-local file descriptor and is not thread-safe.

All important system calls have thread-safe analogs in the DataBlade API.You should use the DataBlade API, rather than system calls.

Ask yourself, “Do I make any system calls? If so, how can I eliminate them?”

Implementation IssuesThis chapter addresses DataBlade module design, not implementation.However, the distinction between the two is often blurred, and developersmust make practical trade-offs. You should keep implementation in mindthroughout the design process. The following subsections discuss some ofthe most important implementation issues facing you.

Naming DataBlade Module ObjectsDataBlade module data types, other objects, and code share name andaddress space in Universal Server. Because Universal Server users canregister multiple DataBlade modules in their databases, it is necessary toprevent name conflicts by conforming to the object-naming rules describedin this section.

Registering Your DataBlade ModuleBefore you build your DataBlade module, register the following informationwith the Informix DataBlade Developers Program registry:


Using the Registered Object Prefix

■ A name for your DataBlade module. This is also the BladeSmithproject name.

■ One or more DataBlade module object prefixes. An object prefix is athree-character code with the following format:

❑ The first and second characters are uppercase letters.

❑ The third character is an uppercase letter or digit.

Informix evaluates requests for multiple object prefixes individually.

■ A range of error message codes. Error message codes, which mustconform to the SQL standard for SQLSTATE, have the followingformat:

❑ The first character is the letter U.

❑ The second and third characters are unique alphabeticalcharacters assigned to the DataBlade module.

❑ The fourth and fifth characters are alphanumeric.

Using this format, a DataBlade module can have up to 1,296 errorcodes. If you anticipate no more than 36 error codes, you could usethe three-character object name prefix in the second, third, andfourth positions, and the digits 0 through 9 and letters A through Z inthe fifth position.

Important: To register object prefixes and error code ranges, send a request in emailto [email protected].

Using the Registered Object PrefixUse your registered DataBlade module object prefix to begin the names ofobjects. The following objects are included:

■ User-defined data types

■ User-defined routines

■ Access methods

■ Executable utilities and tools provided with the DataBlade module

■ Tables, views, and other database objects included with yourDataBlade module

You do not have to use the DataBlade module object prefix for the followingobjects:


DataBlade Module Directory Structure

■ Names of routines that operate on data types unique to yourDataBlade module

■ Names of routines that operate on data types provided by otherDataBlade modules that you develop and maintain

■ Names of routines in support libraries linked to the shared object file

Universal Server object names can be up to 18 characters long. However,BladeSmith limits the names of opaque types to 14 characters, reserving 4characters for generated routine names, such as opaque_typeIn(),opaque_typeOut(), opaque_typeSend(), and opaque_typeRecv().

On all platforms, the filename extension for the shared object file is .bld.BladeSmith combines the DataBlade module name with the .bld extension toform the shared object filename used in generated makefiles. The extensionshould always be typed with lowercase letters to avoid problems on case-sensitive platforms.

The name of the C function associated with a user-defined routine shouldbegin with the DataBlade module object prefix in uppercase letters. BecauseSQL is not case-sensitive, however, any combination of uppercase andlowercase letters can be used to reference the routine in Universal Server.

DataBlade Module Directory StructureBladeSmith generates the path to the installation directory for a DataBlademodule by combining the registered DataBlade module name with theversion number. For example, the installation directory for Version 3.4 of theCircle DataBlade module is:

INFORMIXDIR/extend/Circle.3.4

The installation directory must contain the following files, generated byBladeSmith:

■ prepare.sql

■ objects.sql


New or Old Code?

On-line documents and examples included with your DataBlade moduleshould be placed in the installation directory. Platform-specific files,however, should be placed in a subdirectory of the installation directory,named for the platform. The convention for naming these subdirectories isOperatingSystem-Architecture. For example:

INFORMIXDIR/extend/Circle.3.4/WinNT-i386INFORMIXDIR/extend/Circle.3.4/solaris-sparc

New or Old Code?When creating a DataBlade module from an existing product, the firstdecision is whether to adapt an existing library or to write all new code.

In general, simpler projects are more likely to begin with new code. However,many of the most interesting DataBlade modules are developed by otherdevelopers with substantial expertise in a particular domain, such as text orspatial data management, and include large libraries of routines that supportthe data domain.

New code is easier to execute in Universal Server, since it is designed fromthe beginning precisely for that purpose. However, old code can also be madesafe as a DataBlade module. Old code must be modified to use the DataBladeAPI in place of system calls and private resource management.

Consider the following issues when deciding whether to use existing code:

■ Will this project use some existing software, or will it start fresh?

■ If it uses existing code, what changes must be made to allow it to runin Universal Server?

Using the DataBlade Developers Kit ToolsWhether you choose to use existing or new code for a DataBlade module, youmust always produce some new code to support low-level operations on newdata types and to export existing interfaces to SQL. You should use Blade-Smith, provided with the DataBlade Developers Kit, for this purpose.BladeSmith simplifies DataBlade module development dramatically andallows users to register DataBlade modules with BladeManager. In addition,using BladePack provides a common “look and feel” for DataBlade modulepackaging and installation.


Developing Iteratively

Developing IterativelyYou should plan for iterative development of DataBlade modules. Inparticular, new types must always be implemented before the routines thatoperate on them. You should not only plan for a clean separation between thetype implementation and the rest of the DataBlade module, but also have astrategy for iterative development.

You should ask the following questions during the design process:

■ What components will I implement first?

■ Are the components small enough to accomplish quickly?

■ Are they independently testable?

Testing and Certifying DataBlade Module CodeA testing strategy should be built into the development project at the onset.The Informix DataBlade Developers Program provides guidelines and assis-tance for test development and also certifies DataBlade modules. BladeSmithgenerates functional tests for DataBlade module routines. You should testfrom the beginning and plan to have all new DataBlade modules certified. Donot wait until you have finished developing a DataBlade module to begintesting; add test data as you create each object in the DataBlade module.

Debugging DataBlade ModulesSince software development is prone to errors, you should build debuggingsupport into the code from the beginning. Debugging support is useful whenthe DataBlade module is deployed and running at customer sites, but moreimportantly, it simplifies implementation. Code that can be debugged easilyduring prerelease testing will need much less debugging once it has beenreleased.

You should ask the following questions:

■ Have I built tracing into every routine in my DataBlade module?

■ Do I test for problems during execution and use the error system toreport them sensibly to the user?


Certifying DataBlade Modules

■ Are my internal interfaces simple so that I can understand what ishappening when stepping through DataBlade module routines witha debugger?

Certifying DataBlade ModulesYou can take advantage of Informix DataBlade Developers Program certifi-cation, which involves testing and analysis of DataBlade module code toreduce the number and severity of errors in the DataBlade module.

You should consider the following questions:

■ Will I use the certification program?

■ Have I consulted the testing guidelines before beginning implemen-tation, so that I know what features to build into the DataBlademodule to make it more testable?

■ What platform will I develop on?

■ What tools will I use for testing, beyond those mandated by the certi-fication program?

■ Where will I get my test data? Will it exercise all of my DataBlademodule code?

Supporting Client ApplicationsDataBlade modules are snap-in tools that make Universal Server “smarter.”They are invoked from a client application to perform useful data processing.Therefore, although this chapter concentrates on designing DataBlademodules, this section addresses some client application issues.


Using DataBlade Modules from a Client

Using DataBlade Modules from a ClientA DataBlade module registered in a Universal Server database extends theimplementation of SQL. There are new types, routines, access methods, andcasts available from SQL. Most database users do not write their own SQLqueries, but rather run graphical user interfaces to query the databasesystem. Therefore, most DataBlade modules run a discrete set of SQL queriesfrom window applications.

To take advantage of a DataBlade module, you must choose a tool for writingyour application. The most popular tool is ESQL. It allows you to embed SQLqueries, including those that invoke DataBlade module routines, in aprogramming language, such as C. There are also application builders withmore sophisticated built-in data models, such as INFORMIX-New Era.

Providing Client-Side LibrariesAnother strategy you should consider is to provide client-side supportlibraries or object classes that complement the server-side routines that yourDataBlade modules supply. Application developers can use these client-sidesolutions to take advantage of the DataBlade module extensions so that endusers can query, visualize, and manipulate their data. These supporting toolsshould meet the following application developer needs:

■ They must work with existing application developmentframeworks.

■ They should allow applications to be extended dynamically.

■ They must be programmable idiomatically in the popularprogramming languages and object models.


Using the Informix C++ API

Using the Informix C++ APIThe Informix C++ API is a C++ encapsulation of the client-side DataBladeAPI C library. It uses the Microsoft OLE2.0 Common Object Model (COM) toprovide a mechanism for applications to interact with objects representingdatabase values. These objects can expose COM interfaces that define a rangeof behavior for the objects. (COM interfaces are abstract C++ base classes thatsupport the notion of dynamic upcasting and object aggregation anddelegation.) By supporting the Microsoft COM architecture, C++ interfacevalue objects can take full advantage of all of the most popular ActiveX-enabled application development environments available on Windowsplatforms.


4Chapter

Using BladeSmith

BladeSmith Overview . . . . . . . . . . . . . . . . . . 4-3BladeSmith Windows . . . . . . . . . . . . . . . . 4-4DataBlade Module Objects . . . . . . . . . . . . . . . 4-6

Casts . . . . . . . . . . . . . . . . . . . . . 4-6Interfaces . . . . . . . . . . . . . . . . . . . 4-7Errors . . . . . . . . . . . . . . . . . . . . . 4-7Routines . . . . . . . . . . . . . . . . . . . . 4-8Collection Data Type . . . . . . . . . . . . . . . 4-8Distinct Data Type . . . . . . . . . . . . . . . . 4-8Row Data Type . . . . . . . . . . . . . . . . . 4-9Qualified Data Type . . . . . . . . . . . . . . . . 4-9Opaque Data Type . . . . . . . . . . . . . . . . 4-10SQL Files . . . . . . . . . . . . . . . . . . . 4-11Client Files . . . . . . . . . . . . . . . . . . . 4-11

Using BladeSmith . . . . . . . . . . . . . . . . . . . 4-12Setting Up a Project Environment . . . . . . . . . . . . 4-12Importing DataBlade Module Objects . . . . . . . . . . . 4-13

Importing Interfaces. . . . . . . . . . . . . . . . 4-13Importing Data Types . . . . . . . . . . . . . . . 4-13

Defining New DataBlade Module Objects . . . . . . . . . 4-14Adding Test Data . . . . . . . . . . . . . . . . . . 4-14

Test Data for Opaque Types . . . . . . . . . . . . . 4-15Test Data for User-Defined Routines . . . . . . . . . . 4-15Test Data for Casts . . . . . . . . . . . . . . . . 4-16

Generating Files . . . . . . . . . . . . . . . . . . 4-16Setting Generation Options . . . . . . . . . . . . . 4-17Generating SQL Scripts. . . . . . . . . . . . . . . 4-17Generating Source Files . . . . . . . . . . . . . . 4-18Generating Test Files . . . . . . . . . . . . . . . 4-19Generating Installation Package Files . . . . . . . . . . 4-19

Regenerating Files . . . . . . . . . . . . . . . . . . 4-20

4-2 Data

ladeSmith assists with DataBlade module development projects. Itprovides a visual representation of the objects in a DataBlade module,allowing you to add objects and modify properties of objects. AfterDataBlade module objects are defined in a BladeSmith project, BladeSmithgenerates source code files, SQL scripts, functional tests, and installationpackaging files.

Before you begin using BladeSmith, you should complete the design for yourDataBlade module using the concepts discussed in the previous chapters andyour knowledge of the business issues that your DataBlade moduleaddresses. You should write a functional specification to provide anoverview of the features of your DataBlade module and a design specifi-cation to describe in detail how you plan to implement those features. Useyour design specification as a reference when supplying input forBladeSmith.

This chapter describes how to use BladeSmith to define DataBlade moduleobjects and how to generate files. BladeSmith on-line help containsadditional topics and reference information for BladeSmith. Refer to the on-line help for detailed descriptions of the BladeSmith user interface and screenelements.

BladeSmith OverviewBladeSmith allows you to define the following DataBlade module objects:

■ Casts

■ Interfaces

■ Errors

■ Routines

■ Collection data types

B

Using BladeSmith 4-3

BladeSmith Windows

■ Distinct data types

■ Row data types

■ Qualified data types

■ Opaque data types

■ SQL files

■ Client files

BladeSmith uses wizards to collect the information needed to define anobject. The wizards provide helpful explanations about the information youare to enter. After you define the objects in your DataBlade module, you useBladeSmith to generate source code, SQL scripts, test files, and installationfiles.

BladeSmith WindowsThe BladeSmith project window is divided into two panels. The left panel,called the project view, contains a tree representing the hierarchy of the objectsin the project, with folders for files, imported objects, and user-definedobjects. The right panel, called the item view, contains information about theobject selected in the project view.

Figure 4-1 shows a BladeSmith project window.


BladeSmith Windows

In the project view, you can expand or collapse a folder by clicking theexpander button next to the folder. When you select a folder in the projectview, the item view displays the folder’s contents. When you select an objectin the project view, the item view displays information about the object.

Figure 4-1BladeSmith Project Window

BladeSmith - [Currency.IBS]Project Edit View Generate Tools Window Help

Objects in Project: Currency Contents of User Defined Objects

Casts

Interfaces

Errors

Routines

Types

User Defined Objects

CRYPeso->money

Currency.1.0

Files

Imported Objects

Errors

Types

Collection Types

Casts

CRYexchange

CRYload { }

Interfaces

Routines

Opaque Types

Elements

Distinct Types


DataBlade Module Objects

The information displayed in the item view depends on the type of objectselected. The View menu allows you to specify what BladeSmith displays inthe item view. You can choose Small Icons, Large Icons, List, or Details fromthe View menu. When you select the Details view, BladeSmith lists theattributes of the object. Refer to the on-line help for descriptions of theattributes.

Most objects have property sheets, which allow you to view or edit theirattributes. To view the property sheet for an object, select the object in eitherview and then choose Edit➞Properties. You can also choose Edit➞Update tostart the wizard for the selected object.

DataBlade Module ObjectsThe following sections describe the objects that you can define in a Blade-Smith project.

Casts

A cast is a conversion from one data type to another. The cast accepts the“from” data type as its argument and returns the “to” data type. If the “from”and “to” data types do not have the same binary representation, the servercalls a C function to perform the conversion. If the two types have the samebinary representation, a C function might not be needed.

You can specify whether a cast should be called for implicit conversions.Implicit conversions allow the server to use the cast when it is not calledexplicitly in an SQL statement.

For example, if the SUM() function is called with a DOLLAR argument, theserver searches for an implicit cast from DOLLAR to a data type for which theSUM() function is defined. If an implicit cast exists, the server calls theconversion function and then calls the SUM() function without error. If nocast is specified with implicit conversion, the SUM() function call results in anerror message from the server.

In this example, you could create an implicit cast from DOLLAR to DOUBLEPRECISION to permit the server to execute all functions defined for DOUBLEPRECISION on DOLLAR values. However, if you defined a cast from DOLLARto INTEGER, you would not want that cast to be implicit, since the conversionfunction would truncate dollar values, resulting in inaccurate results.



Interfaces

A DataBlade module can access data types and routines provided by anotherDataBlade module. When you use BladeManager to register or unregisterDataBlade modules in databases, BladeManager checks dependenciesbetween modules to ensure that all required interfaces are available. Toenable this checking, you define one or more interfaces for your DataBlademodule.

Errors

DataBlade module functions can print error messages and trace messages.Error messages are printed with the mi_db_error_raise() function. Tracemessages are written to a trace file with the GL_DPRINTF() macro.

Although it is possible to hard-code messages in your functions, definingthem in BladeSmith makes it easier to edit them. Also, BladeSmith generatescode that uses the Informix Global Language Support (GLS) API, so messagesthat you create in BladeSmith can be easily localized.

Errors have the following attributes:

■ A 5-character error code. This is a character string that uniquelyidentifies the error message. Error codes are allocated for yourDataBlade module by the Informix DataBlade Developers Programregistry, ensuring that your error codes do not conflict with built-inerror codes and those of other DataBlade modules.

■ Locale. This is an Informix locale specification for the message. Itenables the server to select a translated error message for a localizeddatabase. The locale is specified using the formatlanguage_country.codeset. Be sure to create messages for all of thelocales where your DataBlade module executes.

The default BladeSmith locale, en_us.1252, is for U.S. English usingcodeset 1252. This is the default locale for Universal Server on UNIXplatforms. ♦The default codeset for Universal Server on Windows NT is 8859. Youshould create U.S. English messages using locale en_us.8859 forWindows NT servers. ♦

UNIX

Windows NT



■ Error, trace, or both. Error messages are added to the syserrorssystem table. Trace messages are added to the systracemsgs systemtable. If you choose Both, the message is added to both system tables.

■ Message. This is a character string that may contain embeddedparameters to be replaced with current values at runtime.

To specify parameters in messages, assign each parameter a unique nameenclosed in percent ( % ) characters. For example, an Input function couldsend the following message when it is unable to translate an input value:

%FUNCNAME%: Unable to decipher input '%INPUT%'.

The DataBlade API Programmer’s Manual contains information about tracingand calling error messages.

Routines

You can define additional public or private routines that support yourDataBlade module. Routines can be server functions, which return values, orprocedures, which do not return values. Routines can be written in C or SPL.

For example, to create a function that operates on a new data type added byyour DataBlade module, define a public C or SPL function that can beexecuted from SQL.

You can also define private C functions called by your DataBlade modulefunctions, but not from SQL statements.

Collection Data Type

A collection data type is an array, or set, of another data type. You can definea collection type of an existing collection. For example, you can define a listof a set of integers. In SQL, this is written as follows:

list(set(integer not null))

Distinct Data Type

A distinct data type has an internal and external representation identical toanother data type, but the server treats it as a different data type. The distinctdata type allows you to create a new data type in a separate applicationdomain, while using existing support routines for the source data type.



Any existing routines on the source data type are automatically registered onthe distinct data type, but the distinct data type cannot be converted to thesource data type automatically. You can define new routines that operate onlyon the distinct data type.

Row Data Type

A row data type is a group of existing data types arranged like a row in atable. The members of a row data type can be any data type that exists in yourproject, including other row data types.

Row data types can inherit from other row data types. A child row data typeinherits its parent’s columns and can be passed to all routines defined for theparent data type. The parent cannot be passed to routines defined for thechild data type. A row data type cannot inherit from itself, since that wouldcause a circular reference.

Qualified Data Type

A qualified data type is a built-in data type with additional specifications thatprovide information about the storage size, range of values, or precision ofthe data type. You must add a qualified data type to a BladeSmith projectbefore you can use it as a component of a row data type or collection datatype.

The effect of creating a qualified data type in a BladeSmith project is to addthe data type and its qualifiers to the list of data types from which you choosethe elements of collection and row data types. No SQL or C source code isgenerated for qualified data types.

For example, to create a collection data type that stores sets of 16-bytecharacter strings, you must first create a char(16) qualified data type. Thenyou can create the collection data type, choosing char(16) as the base datatype and set() as the constructor function. The new data type has thefollowing SQL definition:

set(char(16) not null)



The following table lists the Universal Server data types that takequalifications.

Refer to the Informix Guide to SQL: Reference manual for more informationabout Universal Server data types.

Opaque Data Type

An opaque data type is a C structure. The server does not interpret thecontents of the structure. Instead, it calls C support routines that you provideto manipulate the structure.

BladeSmith generates much of the code for the C support routines. Youcomplete the C code and compile the source into a shared object file using thegenerated makefiles. The compiled shared object file, which has a .bldextension, is installed beneath the Universal Server extend directory with theDataBlade module.

Data Type Qualification

CHARACTER, CHAR (size)

CHARACTER VARYING (size, minimum)

DATETIME largest_qualifier TO smallest_qualifier

DECIMAL, DEC (precision, scale)

INTERVAL largest_qualifier(n) TO smallest_qualifier(n)

MONEY (precision, scale)

NCHAR (size)

NVARCHAR (size, minimum)

SERIAL, SERIAL8 (start value)

VARCHAR (size, minimum)



SQL Files

BladeSmith allows you to add SQL commands to the scripts that describe aDataBlade module and its objects. You can enter SQL commands directly intoa BladeSmith edit window, or you can import an existing disk file into theBladeSmith project. When you import a file, you can choose to copy thecontents of the file at the time you import or to copy the contents of the filewhenever you generate SQL scripts.

You can include SQL commands to create tables, indexes, or SPL proceduresyour DataBlade module requires. If you create any objects for your DataBlademodule, you should add corresponding SQL DROP statements so that theobjects are dropped when your DataBlade module is unregistered. If youimport SQL statements from a text file, separate the CREATE and DROPstatements with a line of 40 dashes ( - ).

You can specify if an SQL command depends upon a DataBlade moduleobject, or if an object depends upon your SQL. These dependencies determinethe sequence of SQL commands in the generated objects.sql script. Blade-Smith generates SQL in the following sequence:

1. SQL commands to create objects that custom SQL commands dependupon

2. Custom SQL commands

3. SQL commands to create objects that depend upon custom SQLcommands

The generated SQL scripts register dependencies when the DataBlademodule is registered in a database.

Client Files

Client files are installed on client workstations after a DataBlade module isinstalled on a server. Client files include graphical user interfaces, documen-tation and help files, and shared object files containing DataBlade moduleroutines executed in the client address space. Client files are installed on theserver in platform-specific directories in the DataBlade module installationdirectory. Clients use BladeManager to download the files to theirworkstations.


Using BladeSmith

Using BladeSmithThis section provides suggestions for using BladeSmith to create a DataBlademodule. After you have designed the DataBlade module, follow thesegeneral steps to implement your design with BladeSmith:

1. Set up a project environment.

2. Import from other DataBlade module projects any objects that yourproject depends upon.

3. Define new DataBlade module objects.

4. Add test data for opaque data types, user-defined routines, andcasts.

5. Generate files.

6. Edit the generated C source file and compile on the server platformsusing the generated makefiles.

You can modify your project file, generate files, and recompile the sourcecode as often as necessary until your development is complete. BladeSmithmerges your previous edits into the newly generated C source file. Whenyour DataBlade module is complete, use BladePack to create installationpackages for each platform you support.

The following sections describe the steps in the BladeSmith developmentprocess. Refer to the BladeSmith on-line help for step-by-step instructions forusing the BladeSmith interface and screen elements.

Setting Up a Project EnvironmentBladeSmith saves DataBlade module object definitions in a project file withan .ibs extension. BladeSmith generates source code, SQL scripts, functionaltests, and installation package files in directories relative to the project file. Bydefault, BladeSmith creates subdirectories src, scripts, functest, and install inthe directory where you save the project file.


Importing DataBlade Module Objects

You should create a new directory for each DataBlade module so that Blade-Smith does not overwrite any other files. Create a new project in BladeSmithand complete the identification and version information requested by thenew project wizard. Then save your project file in the directory you createdso that the project directory is established in the BladeSmith project file.BladeSmith creates the necessary subdirectories when you generate files.

Importing DataBlade Module ObjectsYou can import interfaces and data types from other DataBlade moduleproject files. Any interfaces and data types referenced by your DataBlademodule must appear in the Imported Objects folder in your projecthierarchy. BladeSmith also lists the data types built into Universal Server asimported data types.

After you have imported data types from other projects, BladeSmith addsthem to its list of known data types. You can use the imported data types aselements in new data types and arguments to routines.

Importing Interfaces

If your DataBlade module depends on an interface defined in anotherDataBlade module, import the interface from the project file where it isdefined. For example, your DataBlade module could use a text-searchinginterface defined in another DataBlade module. When registering DataBlademodules, BladeManager checks interface dependencies and warnscustomers if required DataBlade modules are not registered in the database.BladeManager also warns customers before allowing them to unregisterrequired DataBlade modules.

Importing Data Types

If your DataBlade module uses data types from another DataBlade module,you must import them from the project file where they are defined. Once youimport the needed data types, you can reference them in new data types androutines in your DataBlade module.


Defining New DataBlade Module Objects

Defining New DataBlade Module ObjectsUse BladeSmith to add objects to your DataBlade module. You can addobjects in any sequence, except that you must create any extended data typesbefore you can reference them.

To add an object to your project, choose the object from the Insert menu.BladeSmith starts a wizard that collects information about the object and thenadds it to the project hierarchy. Refer to the BladeSmith on-line help for assis-tance in completing the wizard pages.

You can restart the wizard for an object by selecting the object in the projecthierarchy and choosing Edit➞Update. Objects also have properties pagesthat you can use to change specific attributes. Display the properties pagesfor an object by selecting the object and then choosing Edit➞Properties.

Adding Test DataYou can add test data for opaque types, user-defined routines, and casts.Using the test data you enter, BladeSmith generates a functional test for eachC routine associated with an opaque type, user-defined routine, or cast.

After you have entered test data, you generate functional tests. BladeSmithcreates shell scripts and SQL scripts that you can execute to create test tablesin a database, populate them with your test data, and run SQL scripts thatexecute the DataBlade module functions.

BladeSmith only generates functional tests for an object if you enter test datafor it. You must regenerate functional tests whenever you add test data inorder to update the functional test scripts.

Chapter 6, “Testing and Debugging DataBlade Modules,” describes how touse the functional tests that BladeSmith generates.

To enter test data for an object, select the object and choose Edit➞Gather TestData.

The following sections describe the test data you enter in BladeSmith.


Adding Test Data

Test Data for Opaque Types

For opaque types, each test data item includes the following elements:

■ An input value for the data type, in the format specified for the textinput routine.

■ The expected output value for the input value, in the formatspecified for the type’s text output routine.

■ An error code, if the input value is not valid. Leave this entry blankwhen the input value is expected to be correct.

You should enter values to test the opaque type’s boundaries. For example, ifa type does not accept negative input values, you should enter test data withnegative values and specify the error code you expect to receive from the textinput routine.

The data you enter for an opaque type is used to test all of the supportingfunctions defined for the type. BladeSmith generates SQL scripts to test eachsupporting function, including the text input and output routines and anyother routines you specified, such as binary input and output routines andcomparison routines. You should add test data values that thoroughly testeach of these routines.

Test Data for User-Defined Routines

User-defined routines include functions and procedures. The test data foruser-defined routines includes the following items:

■ The input parameters for the test case. Enter the input parameters inthe same format you would type them in a SQL statement. Enclosetext parameters in single quotes.

■ The result expected from the routine, if the input parameters arevalid. If you enter invalid input parameters, leave this field blank.

If the user-defined routine is a procedure, the result field is not available, since proce-dures do not return values.

■ An error code, if the input parameters are invalid. Leave this fieldblank if the input parameters are expected to be valid.


Generating Files

For example, the Circle DataBlade module defines a Contains() function thattakes a Circle value and a Pnt value and returns a Boolean result. To test theContains() function with a Circle value of '(12,12,2)' and a Pnt value of'(12,12)', enter the following input parameters:

'(12,12,2)','(12,12)'

Calling Contains() with these values should return a true result, which youcan enter as t. Since the input parameters are valid, you would leave theError code field blank.

Test Data for Casts

The test data for a cast includes the following items:

■ Input data, in the text input format specified for the source data type.

■ Expected output data, in the text output format specified for thedestination data type.

■ The error code expected if the input data is not valid. If the input datais valid, leave this field blank.

Be sure to enter invalid input values and values that test boundary conditionsfor the data type.

Generating FilesWhen you generate files, BladeSmith creates files that describe the objectsyou defined in your project. The files include SQL scripts that BladeManagerexecutes to register the DataBlade module in databases, SQL scripts thatcreate the DataBlade module objects in user databases, C source files thatcontain code for the C functions defined in your project, functional test files,and setup files that you use with BladePack to create an installation package.

You can generate SQL files, source files, functional test files, and installationfiles at any time. If you change any of the output directories, you shouldregenerate all files. Items on the Generate menu are marked “(needed)” ifchanges in the project file require the files to be regenerated.


Generating Files

Setting Generation Options

Before you generate files with BladeSmith, choose the directories whereBladeSmith will put generated files.

By default, BladeSmith generates files in subdirectories of the directory thatcontains the DataBlade module project file. BladeSmith writes SQL scripts ina subdirectory named scripts, source files in a subdirectory named src,functional test files in a subdirectory named functest, and installation files ina subdirectory named install. BladeSmith creates these subdirectories if theydo not exist.

To change the directories where BladeSmith writes generated files, chooseGenerate➞Options and click the Directories tab. Enter the path for thedirectory you want to use for each category of generated files. The path mustbe relative to the directory that contains the project file.

Generating SQL Scripts

Choose Generate➞SQL Scripts to generate the SQL scripts that BladeM-anager uses to register, update, or unregister DataBlade modules. ClickGenerate UNIX Format Files to generate text lines ending with a linefeedcharacter instead of the default carriage return/linefeed pair.

The following table describes the generated SQL scripts.

BladeSmith generates locale-specific files for objects such as error messagesthat are locale-specific. For example, the files for the default U.S. Englishlocale are prepare.en_us.sql and errors.en_us.1252.

SQL Script Purpose

prepare.sql Contains SQL statements that describe the DataBlademodule to BladeManager.

objects.sql Contains SQL statements that update the sysbldobjectssystem table with information about the DataBlademodule objects that are created in a database.BladeManager uses the information in the table to register,unregister, and upgrade DataBlade modules.


Generating Files

You can add SQL statements to the generated SQL scripts by adding an SQLfile object to your project. See “SQL Files” on page 4-11 for more informationabout adding SQL statements to a DataBlade module.

Warning: Do not edit generated SQL scripts. Use BladeSmith to make changesrequired and then regenerate the scripts.

Generating Source Files

Choose Generate➞Source to generate C source code for objects defined inyour project.

Check Merge with existing files to have BladeSmith merge your previouscode changes into the new C source. BladeSmith displays a dialog boxdescribing any problems it encounters while attempting to merge your edits.

Check Generate UNIX format files to generate text lines ending with alinefeed character instead of the default carriage return/linefeed pair.

Check Generate Intel/MMX support routines to have BladeSmith generatecode to check for an Intel MMX processor.

BladeSmith writes a header file, a C source file, and makefiles for WindowsNT and Solaris. It also generates a .def file containing a list of exportedroutines for the Windows NT dynamic link library.

After you generate source files, edit the .c file to add your code to the functiondeclarations BladeSmith generated. See Chapter 5, “ProgrammingDataBlade Module Routines,” for a description of the contents of thegenerated files and how to modify and compile the generated code.

When BladeSmith finds existing files, it first copies them to backup files. Youcan choose whether BladeSmith creates a file with a .c.base extension whenmerging C source code. This file contains a snapshot of the last generated Csource without any user modifications. You should not edit or delete the.c.base file. BladeSmith uses it the next time you generate source files tolocate changes made since the last merge. If the file is missing, your changescan still be merged into the generated code, but the result could requiresubstantial editing.


Generating Files

Warning: BladeSmith produces warnings when it detects conflicts while mergingchanges. You must resolve the conflicts by hand before you regenerate the code. Tolocate the conflicts, search for blocks delimited with angle brackets ( >>>> and<<<< ). Do not attempt to regenerate the code before you have resolved the mergeconflicts, since the conflicts will be merged into the newly generated code again,making them more difficult to resolve.

Generating Test Files

Check Generate➞Functional Tests to generate test files. Check GenerateUNIX format files to generate functional test files that run on a UNIXcomputer.

When you generate test files, BladeSmith writes a set of files that you can useto test the opaque data types, casts, and user-defined routines defined in theDataBlade module. BladeSmith creates the subdirectories for user-definedtypes, user-defined routines, casts, and test data. Within these subdirectories,BladeSmith creates subdirectories for each of the objects defined in yourproject. These subdirectories contain SQL scripts and shell scripts that youcan use to test the objects you have created.

See Chapter 6, “Testing and Debugging DataBlade Modules,” for infor-mation about executing functional tests.

Generating Installation Package Files

Choose Generate➞Installation Package to generate files for building instal-lation packages. Check Generate UNIX format files to generate text files withUNIX-format line endings.


Regenerating Files

When you generate installation package files, BladeSmith writes a set of filesthat you use with BladePack to generate installation scripts for yourDataBlade module. The following table describes the installation packagefiles that BladeSmith generates.

Important: Do not edit the generated installation package files. Instead, use Blade-Smith to update the installation package files after you have added or removedDataBlade module objects in the project file. To add additional files to your instal-lation package, and to generate installation packages, refer to Chapter 7, “UsingBladePack.”

Regenerating FilesAfter you make changes in a BladeSmith project, you should regenerate files.For example, if you add a new cast to a DataBlade module, you must regen-erate SQL scripts and, if the cast has a support routine, you must alsoregenerate source files. After you make a change that requires you to regen-erate files, BladeSmith displays “(needed)” next to the command in theGenerate menu.

Package File Contents

project_name.bom This is a bill of materials file. It contains an entry for each fileto be installed. The entry includes the path to the source fileand the path where the file will be installed.

project_name.cmp This file lists the main components and subcomponents in theinstallation package.

project_name.str This file defines character strings used in the installation.

project_name.prd This is the main product file that you open with BladePack. Itlists other files that define the installation package. Initially,this file contains entries for the .bom, .cmp, and .str files. Youcan add additional files using BladePack.


Regenerating Files

If BladeSmith finds existing source files, it copies them to backup files in thesame directory before it generates the new files. For C source code, Blade-Smith also allows you to choose whether to merge custom changes fromprevious files into the new files or to generate all new files. If you choose tohave BladeSmith merge previous changes into the newly generated files, itreports any problems encountered in a Generate Code Problem dialog box.For help in resolving merging problems, click the Help button on this dialogbox and read the on-line help.

If BladeSmith does not merge your previous changes into the new sourcefiles, you can copy changes from the backup files into the new generated filesusing a text editor.

BladeSmith does not merge changes to SQL files or installation files. SQL filesare regenerated, replacing the previous files. When you regenerate Instal-lation files, BladeSmith deletes relevant entries in the bill of materials file(.bom) and adds them again. If you use BladePack to add files to the package,your additions are unaffected by regenerating installation files.


5Chapter

Programming DataBladeModule Routines

DataBlade Module Programming Guidelines . . . . . . . . . . 5-3Use mi_alloc() and mi_free() . . . . . . . . . . . . . . 5-3Do Not Use Global or Static Variables . . . . . . . . . . . 5-4Avoid Unsafe System and Library Calls . . . . . . . . . . 5-4Do Not Use Signals . . . . . . . . . . . . . . . . . 5-7Write Thread-Safe Code . . . . . . . . . . . . . . . . 5-7

Source Files Generated by BladeSmith . . . . . . . . . . . . 5-8Comments in Generated Code . . . . . . . . . . . . . 5-8MI_FPARAM Function Parameter Argument . . . . . . . . 5-9Server Connection Handle . . . . . . . . . . . . . . . 5-10Tracing and Error Handling . . . . . . . . . . . . . . 5-10

Adding Tracing and Error Handling . . . . . . . . . . 5-10Standard Error Messages . . . . . . . . . . . . . . 5-12

Utility Functions Generated by BladeSmith . . . . . . . . . . 5-13

Code Generated for Opaque Type Support Routines . . . . . . . 5-15Text Input/Output Routines . . . . . . . . . . . . . . 5-16

Text Input Routine . . . . . . . . . . . . . . . . 5-17Text Output Routine. . . . . . . . . . . . . . . . 5-19

Binary Send/Receive Routines . . . . . . . . . . . . . 5-20Binary Send Routine. . . . . . . . . . . . . . . . 5-20Binary Receive Routine. . . . . . . . . . . . . . . 5-21

Text File Import/Export Routines . . . . . . . . . . . . 5-22Text File Import Routine . . . . . . . . . . . . . . 5-22Text File Export Routine . . . . . . . . . . . . . . 5-23

Binary File Import/Export Routines . . . . . . . . . . . 5-23Binary File Import Routine . . . . . . . . . . . . . 5-24Binary File Export Routine . . . . . . . . . . . . . 5-24

Assign/Destroy Routines . . . . . . . . . . . . . . . 5-24Assign Routine . . . . . . . . . . . . . . . . . 5-25

5-2 Data

Destroy Routine . . . . . . . . . . . . . . . . . 5-25LOhandles Routine . . . . . . . . . . . . . . . . . 5-25Comparison Routines. . . . . . . . . . . . . . . . . 5-26

Compare Routine . . . . . . . . . . . . . . . . . 5-26B-tree Comparison Routines . . . . . . . . . . . . . 5-27R-tree Comparison Routines . . . . . . . . . . . . . 5-28

Mathematic Routines . . . . . . . . . . . . . . . . . 5-29User-Defined Routines and Casts. . . . . . . . . . . . . 5-29

Routines That Return Sets . . . . . . . . . . . . . . 5-30Casts . . . . . . . . . . . . . . . . . . . . . 5-30

Compiling DataBlade Module Code . . . . . . . . . . . . . 5-31Compiling with Tracing Support . . . . . . . . . . . . . 5-32Compiling with Debug Support . . . . . . . . . . . . . 5-33


his chapter contains information to help you edit and compile sourcecode generated by BladeSmith. It includes the following topics:

■ DataBlade module programming guidelines

■ Source files generated by BladeSmith

■ Utility functions generated by BladeSmith

■ Code generated for opaque type support routines

■ Compiling DataBlade module code

DataBlade Module Programming GuidelinesThis section contains guidelines for writing code that executes in UniversalServer virtual processors. DataBlade module code executes in the UniversalServer threaded environment and shares memory with other serverprocesses. Following the guidelines in the section ensures that yourDataBlade module executes safely, efficiently, and without disturbing otherUniversal Server processes.

Use mi_alloc() and mi_free()Use only the DataBlade API memory allocation routines—mi_alloc(),mi_free(), and related routines—to allocate and release memory. Theseroutines allocate space in memory shared by all Universal Server virtualprocessors. If you use the C library malloc() and free() routines, the memoryyou allocate cannot be accessed if the thread migrates from one virtualprocessor to another.

T

Programming DataBlade Module Routines 5-3

Do Not Use Global or Static Variables

Do Not Use Global or Static VariablesBecause Universal Server is multithreaded and DataBlade module functionscan be active in different threads of execution simultaneously, global andstatic memory are not thread-safe. The DataBlade API does not providemutual exclusion for DataBlade module functions. Therefore, DataBlademodule functions must only use stack variables and memory allocated withthe DataBlade API memory allocation routines. Both of these types ofmemory remain accessible when a thread migrates to another virtualprocessor.

The server automatically frees any memory allocated with mi_alloc() whenit is no longer needed.

Most DataBlade module functions execute once and do not need data savedfrom previous executions. However, the server calls some functionsrepeatedly to process a set of data. For example, the server calls a set offunctions to process aggregates such as avg(). It first calls an initializationfunction, which allocates and initializes the memory used to accumulate theaggregate results. It then calls an iteration function for each data value in theset that is to be aggregated. Then it calls two finalization functions: one tocombine intermediate results accumulated for data in multiple partitions andanother to produce the final result.

Iterative functions that must save information over repeated calls can use theMI_FPARAM structure to save a pointer to memory allocated usingmi_dalloc() with the PER_COMMAND duration. The server passes the sameMI_FPARAM structure on each function call for the duration of the query.

Avoid Unsafe System and Library CallsDataBlade modules that run in the CPU VP have the best performancebecause they minimize context switch time and require less copying of dataamong virtual processors. To run in a CPU VP, however, a DataBlade modulemust avoid unsafe system calls.

An unsafe system call is one that blocks, causing the virtual processor to yieldthe processor until the call returns, or one that allocates resources local to thevirtual processor instead of in shared memory.


Avoid Unsafe System and Library Calls

Unfortunately, nearly all operating system calls are unsafe because they canblock. However, the DataBlade API provides alternatives to many systemcalls that can be used in DataBlade module routines.

Many POSIX calls are unsafe because they indirectly call blocking systemcalls. The following table lists POSIX calls that are safe for use in a DataBlademodule that runs in the CPU VP.

Category Safe Calls Notes

character isalpha, isascii, isastream, isatty, iscntrl,isdigit, isgraph, islower, isprint, ispunct,isspace, isupper, isxdigit

string manipulation toascii, tolower, toupper

string parsing getopt, getsubopt Must consider effect of possiblethread switches on staticmemory.

multibyte string mbtowc, wctomb, mblen, mbstowcs,wcstombs

string sprintf, sscanf, strcasecmp, strcat, strchr,strcmp, strcoll, strcpy, strcspn, strdup,strerror, strlen, strncasecmp, strncat,strncmp, strncpy, strpbrk, strrchr, strsignal,strspn, strstr, strtod, strtok, strtok_r, strtol,strtoll, strtoul, strtoull, strxfrm

numeric a64l, abs, atof, atoi, atol, atoll, div, drand48,econvert, ecvt, erand48, fconvert, fcvt,gconvert, gcvt, l64a, labs, ldiv, llabs, lldiv,lltostr, lrand48, mrand48, nrand48,qeconvert, qfconvert, qgconvert, rand,random, seconvert, sfconvert, sgconvert,srand, srand48, srandom, strtoll

The random numbergenerator’s seed is stored instatic memory, so it must bereseeded whenever a threadswitch might have occurred.

time ascftime, asctime, asctime_r, cftime, clock,ctime, ctime_r, difftime, gettimeofday,gmtime, gmtime_r , localtime, localtime_r,mktime, settimeofday, strftime

No time zone changes arepermitted.

date getdate

(1 of 2)


Avoid Unsafe System and Library Calls

sort/search bsearch, qsort, lfind, lsearch

encryption crypt, setkey, encrypt

memorymanagement

memccpy, memchr, memcmp, memcpy,memmove, memset

environment getenv

bit manipulation ffs

byte manipulation swab

structure membermanipulation

offsetof

trigonometricfunctions

acos, acosh, asin, asinh, atan, atan2, atanh,cos, cosh, sin, sinh, tan, tanh

bessel functions j0, j1, jn, y0, y1, yn

root extraction cbrt, sqrt

rounding ceil, floor, rint

IEEE functions copysign, isnan, fabs, fmod, nextafter,remainder

error functions erf, erfc

exponentials andlogarithms

exp, expm1, log, log10, log1p, pow

gamma functions lgamma, lgamma_r signgam is in static memory, socontents are unreliable after athread switch.

euclidean distance hypot

Category Safe Calls Notes

(2 of 2)


Do Not Use Signals

Calls to any other standard library interface or operating system routinemight not be safe to use in a CPU VP. You should use only the routines listedin this table.

Do Not Use SignalsUniversal Server reserves all operating system signals for its own use. NoDataBlade module function should raise, handle, or mask signals.

Write Thread-Safe CodeDataBlade module routines that run in the CPU VP must yield the processorregularly so that other threads can execute. Routines that do not yieldregularly should run in the EXT VP. However, because the CPU VP has lessexecution overhead and provides better performance, you should avoidwriting code that must execute in an EXT VP.

Universal Server is a non-preemptive, multithreaded execution engine. If afunction does not yield regularly, it can diminish overall server throughputby preventing other threads from executing.

To yield the processor, call the mi_yield() DataBlade API function regularly.You should add mi_yield() calls at the beginning or end of lengthy loops andbefore or after an especially expensive computation.

Many DataBlade API calls, including all file and large object I/O calls, callmi_yield() after scheduling an I/O or other expensive operation.

When mi_yield() returns, the thread resumes execution. The thread maymove to another virtual processor before it resumes, so you cannot assumethat the thread remains in the same location even during a single executionof a function.


Source Files Generated by BladeSmith

Source Files Generated by BladeSmithWhen you create user-defined routines and opaque types, BladeSmithgenerates a C source file and a C header file. The files have the same name asyour project file, with .c and .h extensions. By default, BladeSmith writes thesource files in the src subdirectory of the directory that contains the projectfile.

The C header file for a DataBlade module project contains:

■ definitions for error messages used in generated code.

■ function prototypes for utility functions BladeSmith provides.

■ typedefs for opaque type structures defined in the BladeSmithproject.

■ typedef for MI_LO_HANDLES structure returned by LOhandlesroutines.

The C source file BladeSmith generates for a DataBlade module projectcontains:

■ #include directives for standard C header files and DataBlade APIheader files.

■ function definitions for opaque type support routines specified in theDataBlade module project.

■ function declarations for casts defined in the BladeSmith project.

■ function declarations for any user-defined C routines in theBladeSmith project.

■ utility functions called from BladeSmith-generated functions.

Comments in Generated CodeBladeSmith adds comments to the code it generates. Each function beginswith a prologue that describes the purpose of the function, its parameters,and its return value. Comments throughout the code describe variable decla-rations and the results of generated C statements and function calls.


MI_FPARAM Function Parameter Argument

In comments at the beginning and end of each generated function, Blade-Smith stores information it uses when regenerating source code. Theprologue includes a function ID. A comment at the end of the functioncontains a calculated checksum. You should not modify either of thesevalues, since BladeSmith uses them to merge your edits into the regeneratedcode.

BladeSmith adds a Gen_ prefix to all variable names and function names notexplicitly named in the project.

MI_FPARAM Function Parameter ArgumentUniversal Server passes a function parameter to DataBlade modulefunctions. The parameter is a pointer to an MI_FPARAM structure.

Using accessor functions provided by the DataBlade API to access theMI_FPARAM structure, the called function can:

■ get information about the arguments passed to the function, such asdata type and null value indicators.

■ set supplemental information about the value the function returns tothe server, such as its null value indicator.

■ manage iterative calls to the function, for example to return multipledata rows to the server.

■ store state information in private allocated memory to use initerative calls to your function.

BladeSmith includes an MI_FPARAM argument in all functions it generates.You should not access MI_FPARAM structure members directly because thestructure may change between versions of the DataBlade API. Instead, useDataBlade API accessor functions to test and set values in the structure.

In addition to references for each of the accessor functions, the DataBlade APIProgrammer’s Manual includes a chapter that describes the information storedin the MI_FPARAM structure, how to get values form or store values in thestructure, and how to use the structure for creating iterative functions.

See the ExmAmortize() function in the Business example DataBlade modulefor an example of using the MI_FPARAM structure in an iterative function.


Server Connection Handle

Server Connection HandleBladeSmith calls mi_open() at the beginning of many of the functions itgenerates. This call obtains a server connection handle, which is a requiredargument in many DataBlade API calls. For functions running in UniversalServer address space, the connection handle is a dummy, provided to allowclient and server functions to use the same DataBlade API functions.

When mi_open() is called at the beginning of a generated function,mi_close() is called immediately before the function returns, to release thehandle.

Tracing and Error HandlingBladeSmith adds tracing and error handling code throughout the generatedsource code. A generated utility function, Gen_Trace(), processes all tracingand error handling.

Messages in the trace file include the source filename, line number of the callto Gen_Trace(), and the name of the executing function.

The generated header file contains macro definitions that expand toGen_Trace() function calls.

Messages are only written to the trace file when you compile the DataBlade modulewith support for tracing and enable tracing in the database. See “CompilingDataBlade Module Code” on page 5-31 for instructions for enabling tracing.

Adding Tracing and Error Handling

You can use the macros defined in the header file to add tracing and errorhandling calls when you modify the generated source code.


Tracing and Error Handling

The following table describes the tracing and error handling macros definedin the header file.

Important: The Gen_Trace() utility function handles messages that contain theembedded parameters %FUNCTION%, %FILENAME%, and %LINENO%. If youwant to include other parameters in a message, you must call GL_DPRINTF() fortrace messages or mi_db_error_raise() for error messages. See the Gen_Trace()function in the generated source code for an example of calling these routines.

To send a message to the trace file, use the DBDK_TRACE_MSG() macro. Thesyntax for DBDK_TRACE_MSG() is:

DBDK_TRACE_MSG(Caller, ErrNo, ErrLevel)

To send a message to the trace file and raise an error, use theDBDK_TRACE_ERROR() macro. The syntax for DBDK_TRACE_ERROR() is:

DBDK_TRACE_ERROR(Caller, ErrNo, ErrLevel)

Both macros take the same arguments. Both write messages in the trace file iftracing is enabled. DBDK_TRACE_ERROR() also raises an error by callingmi_db_error_raise().

Caller is the name of the C function you are adding the macro to.

ErrNo is the number for an error message in the syserrors system catalog. Youcan use numbers for error messages defined in the BladeSmith project ormessages BladeManager installs with all DataBlade modules. The standarderror messages are listed in “Standard Error Messages” on page 5-12.

Macro Actions

DBDK_TRACE_ERROR() Prints a message in the trace file, if tracing is enabled, andraises an error.

DBDK_TRACE_MSG() Prints a message in the trace file, if tracing is enabled.

DBDK_TRACE_ENTER() If tracing is enabled, prints a message in the trace file uponentering a function.

DBDK_TRACE_EXIT() If tracing is enabled, prints a message in the trace file uponexiting a function.


Tracing and Error Handling

ErrLevel is an integer that determines the tracing level for the message. Whenyou begin tracing in a database, you can specify a threshold. If ErrLevel isbelow the threshold, the message is not printed in the tracing file. This allowsyou to adjust the amount of detail in the tracing file. For example, the ErrLevelfor the “enter function” and “exit function” messages written by theDBDK_TRACE_ENTER() and DBDK_TRACE_EXIT() macros is 20.

Standard Error Messages

BladeSmith uses a standard set of messages in the code that it generates.These messages are shared by all DataBlade modules created with Blade-Smith and cannot be changed. BladeManager adds the error messages to thesyserrors system catalog and the systracemsgs system catalog when aDataBlade module is registered in a database.

The messages have the same text and error numbers in the two system tables,except that messages in the systracemsgs system table include the text“(%FILENAME%, %LINENO%)” after the %FUNCTION% parameter. Thiscauses the source filename and line number to print in the trace file.

The following table lists the standard DataBlade module error messages.

Error Number Message Text

UGEN1 Connection has failed in %FUNCTION%.

UGEN2 Memory allocation has failed in %FUNCTION%.

UGEN3 Error creating large object from client file in %FUNCTION%.

UGEN4 Large object handle is invalid in %FUNCTION%.

UGEN5 Error creating large object from client file in %FUNCTION%.

UGEN6 Error saving large object to client file in %FUNCTION%.

UGEN7 Double-quoted string expected in %FUNCTION%.

UGEN8 Interval format conversion has failed in %FUNCTION%.

UGEN9 Input string is not terminated with double-quote in %FUNCTION%.

UGENA Input string is too long in %FUNCTION%.

(1 of 2)


Utility Functions Generated by BladeSmith

The generated header file defines constants ERRORMSG1 throughERRORMSG17 for these error numbers.

You can define additional messages used in your DataBlade module. Definethem in the BladeSmith project to ensure that they are loaded into thedatabase when your DataBlade module is registered. See “NamingDataBlade Module Objects” on page 3-26 for information about reservingerror codes for your DataBlade module.

Utility Functions Generated by BladeSmithBladeSmith generates support functions that it calls from other generatedcode. These functions include:

■ Gen_sscanf(). This function is called from Input and Import routinesto convert text data to the C structure for an opaque type.

■ Gen_LoadLOFromFile(). When an opaque type includes a largeobject handle, BladeSmith includes this function to retrieve the largeobject data from a disk file.

■ Gen_StoreLOToFile(). When an opaque type includes a large objecthandle, BladeSmith includes this function to write large object datato a disk file.

UGENB Input data format error in %FUNCTION%.

UGENC Output LO file creation has failed in %FUNCTION%.

UGEND Entering function %FUNCTION%.

UGENE Successfully existing function %FUNCTION%.

UGENF The collection could not be created in %FUNCTION%.

UGENG Insertion into the collection has failed in %FUNCTION%.

UGENH Invalid iterator state used in %FUNCTION%.

Error Number Message Text

(2 of 2)


Utility Functions Generated by BladeSmith

■ Gen_nstrwords(). This function counts the number of values in aformatted string. It is called from Input and Import routines toretrieve values from variable-length opaque types.

■ Gen_Trace(). This function processes trace messages and errors. It isgenerally invoked by the macros DBDK_TRACE_ENTER(),DBDK_TRACE_EXIT(), DBDK_TRACE_MSG(), andDBDK_TRACE_ERROR(). This function is described under “Tracingand Error Handling” on page 5-10.

■ Gen_IsMMXMachine(). This function determines whether the serveris running on a computer with an Intel MMX processor. It is onlygenerated if you check Generate Intel/MMX utility functions whenyou generate source code.

Most of the generated utility functions are called by code that BladeSmithgenerates, and you should not have to use them in your code. TheGen_sscanf() utility function, however, might be useful in yourInput/Output routines. And the Gen_IsMMXMachine() function is neededif you use Intel MMX instructions in your code.

The Gen_sscanf() utility function scans one value from an input string andstores it at a given address. It returns a pointer that points just past the valueit scanned from the input string.

Gen_sscanf() takes the following parameters:

Gen_Con The database connection handle

Gen_Caller The name of the calling function

Gen_InData A pointer to the text to be scanned

Gen_InDataLen An integer containing the length of the text (mi_lvarchar stringsare not null-terminated)

Gen_Width An integer containing the maximum data length for text data

Gen_Format A string containing a sscanf() format string for the structuremember to be scanned

Gen_Result A pointer to the member in the structure where Gen_sscanf()stores the scanned value


Code Generated for Opaque Type Support Routines

The generated Input and Import routines call Gen_sscanf() once for eachstructure member. Gen_sscanf() assumes an input string in the current localeand uses the Informix GLS routines to scan the string.

The Gen_IsMMXMachine() function can be used when you include IntelMMX media enhancement technology in your DataBlade module. Thefunction tests the processor in the server computer to determine if it has MMXtechnology support. If MMX technology support is found,Gen_IsMMXMachine() returns 1. If the server machine does not have MMXtechnology support, or if the FORCE_NO_MMX environment variable is set inthe server’s environment, Gen_IsMMXMachine() returns 0.

Call Gen_IsMMXMachine() in an if statement to execute MMX instructionswhen possible and to execute portable C code on computers that do not haveMMX technology support.

Gen_IsMMXMachine() declares a static int flag, MMXType. It first looks forthe FORCE_NO_MMX environment variable, which must be set in theenvironment before the server is started. If FORCE_NO_MMX is found, thefunction sets MMXType to 0 without testing the CPU. If FORCE_NO_MMX isnot found, the function tests the processor and sets the MMXType variable to1 if MMX technology support is found, or 0 if not. Once the value ofMMXType is set, Gen_IsMMXMachine() returns its value immediately, sothat tests are performed just once after the DataBlade module object file isloaded.

Code Generated for Opaque Type Support RoutinesBladeSmith generates code for the following opaque type support routines:

■ Text Input/Output routines

■ Binary Send/Receive routines

■ Text File Import/Export routines

■ Binary File Import/Export routines

■ Assign/Destroy routines

■ LOhandles routine

■ Comparison routines, including B-tree and R-tree indexing supportroutines



■ Mathematic routines

■ User-defined routines and casts

Refer to “Routines” on page 1-6 for an overview of these routines. Thefollowing sections describe the code BladeSmith generates for each routineand modifications you might need to make to the generated code.

Text Input/Output RoutinesText Input/Output routines convert between the textual representation of anopaque type and the internal format (the C structure). BladeSmith generatescomplete C functions for these routines.

The generated code assumes a default text representation, a string containingall members of the structure, delimited with spaces. Strings are enclosed inquotation marks ("). Large objects are represented as external filenamesenclosed in quotation marks. The Input routine calls the sscanf() C libraryfunction for other data types, so valid character representations for thesetypes are those that sscanf() recognizes.

For example, the Circle DataBlade module defines a Pnt data type with twomi_double_precision members, x and y. The Circ.h header file contains thefollowing structure definition:

typedef struct{

mi_double_precision x;mi_double_precision y;

}Pnt;

The default text representation for the Pnt data type is:

'x y'

where x and y are character strings that sscanf() can convert to double-precision values. For example, the following statement inserts a Pnt valueinto a table, using the default text representation:

insert into mytable (col1) values ('12.3 66.9');



Text Input Routine

The Text Input routine has two parameters: an mi_lvarchar pointer, whichpoints to the text that is to be converted, and an MI_FPARAM pointer, whichis not used by the generated code.

The Text Input routine returns a pointer to a filled-in C structure for the Pntdata type. The contents of this structure are written to the database table. Theroutine allocates memory for the opaque type it returns:

/* Allocate memory room to build the UDT in. */Gen_RetVal = (Pnt *)mi_alloc( sizeof( Pnt ) );if( Gen_RetVal == 0 ){

/*** Memory allocation has failed so issue** the following message and quit.**** "Memory allocation has failed in PntInput."*/mi_db_error_raise( Gen_Con, MI_SQL, ERRORMESG2,

"FUNCTION%s", "PntInput", (char *)NULL);

The server frees the allocated memory.

Next, the routine scans the text string, obtaining a value for one structuremember at a time:

/* Get the data value for Gen_OutData->x. */Gen_InData = Gen_sscanf( Gen_Con, "PntInput", Gen_InData,

mi_get_varlen( Gen_param1 ), 0,"%lf %n",(char *)&Gen_OutData->x);

/* Get the data value for Gen_OutData->y. */Gen_InData = Gen_sscanf( Gen_Con, "PntInput", Gen_InData,

mi_get_varlen( Gen_param1 ), 0,"%lf %n",(char *)&Gen_OutData->y);

This code calls the Gen_sscanf() utility function, which BladeSmith adds toeach generated C source file. The next section describes the Gen_sscanf()function.



Finally, the Text Input routine returns a pointer to the completed C structure:

/* Return the UDT value. */return Gen_RetVal;

You must modify the generated Text Input routine code if you want to use aninput text format different from the default format or if the C structurecontains data types that BladeSmith cannot scan with Gen_sscanf().

If you want a different input text format than the default that BladeSmithassumes, replace the generated code with your own. For example, you couldchoose to delimit values with commas instead of spaces. Your code might beable to call the Gen_sscanf() function, or you might need to write your ownscanning function.

In the Circle DataBlade module, the text representation of the Pnt data typehas been changed from the default format:

'x y'

to this format:

'(x, y)'

To support the new format, Gen_sscanf() calls in the PntInput() function aremodified to include the parentheses and comma in the format string:

/* Get the data value for Gen_OutData->x. */Gen_InData = Gen_sscanf( Gen_Con, "PntInput", Gen_InData,

mi_get_varlen( Gen_param1 ), 0,"(%lf, %n",(char *)&Gen_OutData->x);

/* Get the data value for Gen_OutData->y. */Gen_InData = Gen_sscanf( Gen_Con, "PntInput", Gen_InData,

mi_get_varlen( Gen_param1 ), 0,"%lf %n)",(char *)&Gen_OutData->y);



Text Output Routine

The Text Output routine takes a pointer to the opaque type structure and anMI_FPARAM pointer, and returns a text representation of the data type in anmi_lvarchar value. Again, BladeSmith assumes that the text representation isa string containing character representations of all of the structure membersdelimited with spaces. The function encloses strings and filenames for largeobjects in quotation marks.

If you change the Text Input function to support a different text format thanthe default, you should also change the Text Output function. The stringreturned by the Text Output function should be a valid string for the TextInput function.

The generated Text Output code computes the maximum length of the stringit returns and calls mi_new_var() to allocate an mi_lvarchar variable,Gen_RetVal. The server frees the allocated memory later.

The function calls the C standard library function sprintf() once for eachstructure member to write the value and a space in the data area pointed toby the Gen_OutData variable. Following are the sprintf() calls from thegenerated PntOutput() routine in the Circle DataBlade module:

/* Format the value for Gen_InData->x.*/sprintf( Gen_OutData, "%lf ", Gen_InData->x );Gen_OutData += strlen( Gen_OutData );

/* Format the value for Gen_InData->y.*/sprintf( Gen_OutData, "%lf ", Gen_InData->y );Gen_OutData += strlen( Gen_OutData );

Between calls to sprintf(), the function resets Gen_OutData to point to theend of the string.



You can modify the code BladeSmith generates for the Text Output routine tochange the text representation of the opaque type or to optimize the code.The text representation must match the representation used for the Text Inputfunction. For example, to support the new text representation for the Pnt datatype, the parentheses and comma are added to the sprintf() calls in thePntOutput() routine:

/* Format the value for Gen_InData->x.*/sprintf( Gen_OutData, "(%lf,", Gen_InData->x );Gen_OutData += strlen( Gen_OutData );

/* Format the value for Gen_InData->y.*/sprintf( Gen_OutData, "%lf) ", Gen_InData->y );Gen_OutData += strlen( Gen_OutData );

Binary Send/Receive RoutinesThe Binary Send/Receive routines translate opaque types sent to andreceived from clients. The routines are needed to adjust data types fordiffering byte order and alignment requirements between the client andserver computers. The routines call the mi_put and mi_get DataBlade APIfunctions to transform individual members of the opaque type structure.

Binary Send Routine

The server calls the Binary Send routine with a pointer to an mi_sendrecvtype, which contains the opaque type structure, and an MI_FPARAM pointer.It allocates an mi_sendrecv variable to hold another opaque data structure.It fills in the members of the new structure with values from the inputstructure, adjusted for the client machine architecture.



The routine calls mi_put DataBlade API routines to store the client represen-tation of the data type in the structure to be returned to the server. Thefollowing code, taken from the Circle DataBlade module CircSend() routine,calls mi_put_double_precision() to store values from an input Circ data type(addressed by Gen_InData) to an output Circ data type (addressed byGen_OutData):

/* Prepare the value for Gen_OutData->center.x. */mi_put_double_precision( (mi_unsigned_char1

*)&Gen_OutData->center.x, &Gen_InData->center.x );

/* Prepare the value for Gen_OutData->center.y. */mi_put_double_precision( (mi_unsigned_char1

*)&Gen_OutData->center.y, &Gen_InData->center.y );

/* Prepare the value for Gen_OutData->radius. */mi_put_double_precision( (mi_unsigned_char1

*)&Gen_OutData->radius, &Gen_InData->radius );

Binary Receive Routine

The server calls the Binary Receive routine with an mi_sendrecv pointer andan MI_FPARAM pointer. The mi_sendrecv pointer contains the address of theopaque structure. The routine returns a pointer to an opaque structure, forwhich it allocates memory. The server frees this memory later.


Text File Import/Export Routines

The Binary Receive routine calls mi_get DataBlade API routines to retrievevalues for each structure member from the input received from the client. Thefollowing code, from the Circle DataBlade module CircReceive() routine,calls mi_get_double_precision() to retrieve three double-precision valuesand store them in the Circ stucture:

/* Copy the attribute value(s) from the transmissionparcel. */

/* Prepare the value for Gen_InData->center.x. */mi_get_double_precision( (mi_unsigned_char1

*)&Gen_InData->center.x, &Gen_OutData->center.x );

/* Prepare the value for Gen_InData->center.y. */mi_get_double_precision( (mi_unsigned_char1

*)&Gen_InData->center.y, &Gen_OutData->center.y );

/* Prepare the value for Gen_InData->radius. */mi_get_double_precision( (mi_unsigned_char1

*)&Gen_InData->radius, &Gen_OutData->radius );

Text File Import/Export RoutinesUniversal Server calls Text File Import/Export routines when using bulkcopy to transfer opaque type values between a database and an external file.

Text File Import Routine

The server calls the Text File Import routine with a pointer to an mi_impexptype containing the input text, which it retrieves from an external file, and anMI_FPARAM pointer.

The Text File Import routine converts the text to an instance of the opaquetype and returns a pointer to it.

The Text File Import routine allocates memory for the opaque structure thatit returns and then calls Gen_sscanf() for each member of the structure,storing the scanned values in the allocated memory. If the data type containsa large object handle data type (MI_LO_HANDLE), the input contains thelarge object filename in quotation marks. The Text File Import routine callsGen_LoadLOFromFile() to retrieve the large object data from the external file.


Binary File Import/Export Routines

The default format for imported text is the same as for the Input routine—astring containing each structure member, delimited with spaces. You canmodify the format strings in the Gen_sscanf() calls if you use a different textrepresentation for your data type.

Text File Export Routine

The server calls the Text File Export routine with a pointer to an instance ofthe opaque type and an MI_FPARAM pointer, which is not used by thegenerated code. The Text File Export routine converts the opaque type valueto a text value stored in an mi_lvarchar variable that it allocates. Thegenerated code works the same way as the Text File Output routine.

The routine computes the maximum length of the text value it can return bysumming the maximum lengths for each structure member. Then it callsmi_new_var() to allocate an mi_impexp variable large enough to hold thelargest possible text value.

To create the output text, the routine calls sprintf() once for each member ofthe opaque type structure, concatenating a text representation of the value tothe string in the mi_impexp variable. Each value is followed by a space.

The default Text File Export routine is the same text representation as theInput and Import functions. This format allows database users to entervalues for the opaque type and recognize values returned by the server. Forbulk copy operations, however, a user-readable format is not necessary. Youmight want to use a different text representation for bulk copy to conservespace in the external file or to match the representation required by someanother application that uses the export file. When you modify the text repre-sentation that the Text File Export routine uses for copy-out operations, youshould usually make similar modifications in the Text File Import routine.

Binary File Import/Export RoutinesUniversal Server calls Binary File Import/Export routines during bulk copyto transfer opaque type values in binary format between external files and adatabase.

If you define Binary File Import/Export routines, BladeSmith generates codethat calls DataBlade API mi_put and mi_get routines to build a binary imageof the opaque type C structure in the client format.


Assign/Destroy Routines

Binary File Import Routine

Universal Server calls the Binary File Import routine with an mi_bitvaryingpointer containing the binary representation of an opaque type value, readfrom an external file. The routine also receives an MI_FPARAM pointer, whichis not used by the code that BladeSmith generates for this routine.

The Binary File Import routine translates the binary data in themi_bitvarying structure into an instance of the opaque type and returns apointer to the C structure. The BladeSmith-generated code allocates memoryfor the return structure and then calls DataBlade API mi_get routines toretrieve a value for each member of the structure. If the opaque type includeslarge objects, the routine calls Gen_LoadLOFromFile() to read the largeobject data from a file.

Binary File Export Routine

Universal Server calls the Binary File Export routine with a pointer to anmi_lvarchar value, which contains an instance of the opaque type, and anMI_FPARAM pointer. The routine translates the opaque type value into abinary image and returns it in an mi_bitvarying variable. Universal Serverwrites the returned binary value into external files.

The Binary File Export routine calls mi_new_var() to allocate anmi_bitvarying variable and then calls an mi_put routine for each element ofthe opaque structure to store the value. If the opaque type includes largeobjects, the generated code calls Gen_StoreLOToFile() to save the largeobject data in an external file.

Assign/Destroy RoutinesUniversal Server calls an Assign routine when storing an opaque type ondisk. It calls a Destroy routine when removing an opaque type from disk.These two routines allow you to perform special processing associated withthe creation and destruction of opaque types. For example, if your opaquetype includes large objects, you should create Assign/Destroy routines tomanage the large object references.

Important: If Text Input/Output routines are used, Assign/Destroy routines must bepresent to prevent runtime errors from the database server.


LOhandles Routine

BladeSmith generates Assign and Destroy routines that manage large objectreference counts. For other types of special processing, you must add code tothe generated code.

Assign Routine

Universal Server calls the Assign routine with a pointer to an instance of anopaque type and a pointer to an MI_FPARAM structure. The routine returns apointer to the opaque type to the server. Usually, the pointer returned by theAssign routine is the same one Universal Server passed to it. If the Assignroutine alters the input opaque type in any way and returns a pointer to it,the server stores the modified value in the database.

The generated Assign routine code manages large object reference counts. Itcalls mi_lo_validate() to determine if a valid large object exists andmi_lo_increfcount() to increment the reference count for the large object.

Destroy Routine

Universal Server calls the Destroy routine before removing an opaque typefrom the database. It passes the Destroy routine a pointer to the opaque typevalue that is about to be removed from the database, and an MI_FPARAMpointer. The routine has no return value.

The Destroy routine calls mi_lo_validate() for each large object. For validlarge objects, it calls mi_lo_decrefcount() to decrement the reference countfor the large object.

LOhandles RoutineUniversal Server calls the LOhandles routine to retrieve a list of large objecthandles used by an opaque type. The LOhandles routine receives a pointer tothe opaque type and a pointer to an MI_FPARAM structure.


Comparison Routines

The LOhandles routine returns a pointer to an mi_bitvarying variablecontaining an MI_LO_HANDLES structure. BladeSmith definesMI_LO_HANDLES in the generated header file; it is not part of theDataBlade API. The structure holds a list of MI_LO_HANDLE structures. It hasthe following definition:

/* This data structure returned by LOhandles. */typedef struct{

mi_integernlos;/* Number of large object handles. */MI_LO_HANDLElos[1];/* Valid large object handles. */

} MI_LO_HANDLES;

The LOhandles routine calls mi_lo_validate() for each large object in theopaque type structure, accumulating a count of valid large objects. If thereare no valid large objects in the opaque type, the routine returns 0 to its caller.

If the opaque type contains valid large objects, the routine:

■ allocates an mi_bitvarying variable to hold the MI_LO_HANDLESstructure.

■ copies valid large object handles into the los array in theMI_LO_HANDLES structure.

■ sets the MI_LO_HANDLES nlos member to the number of largeobjects in the array.

■ returns a pointer to the MI_LO_HANDLES structure.

Comparison RoutinesUniversal Server calls DataBlade module comparison routines to comparetwo opaque type values. For example, database users can compare opaquevalues in SQL statements. If you want to support B-tree indexes on an opaquetype, you must provide an additional set of comparison routines.

Compare Routine

The Compare routine compares two opaque type values and returns:

■ -1 if the first value is less then second value.

■ +1 if the first value is greater than the second value.


Comparison Routines

■ 0 if the two values are equivalent.

BladeSmith generates a complete Compare function for an opaque type. Thegenerated code compares each member of the opaque type C structure, in theorder defined in the structure. When the routine encounters two values thatare not equal, it returns -1 if the first is less than second, or +1 if the first isgreater than the second.

For types such as mi_boolean, which cannot be compared for relativemagnitude, the routine returns +1 if the values differ. If all structure membersare equal, it returns 0.

The algorithm used to generate the Compare function cannot evaluate thesemantic content of an opaque type. Therefore, for many opaque types, thegenerated code should be replaced with more appropriate code.

For example, the Matrix Math DataBlade module defines a variable-lengthMatrix2d data type in Matrix.h:

typedef struct{

mi_integer noOfRows;mi_integer noOfCols;mi_double_precision data[1];

}Matrix2d;

The Compare function generated for the Matrix2D type first comparesnoOfRows, then noOfCols, and then each element of the array of double-precision values beginning at the address of the data structure member.

B-tree Comparison Routines

Universal Server calls additional comparison routines when constructingB-tree indexes for opaque data types:

■ Equal

■ LessThan

■ LessThanOrEqual

■ GreaterThanOrEqual

■ GreaterThan


Comparison Routines

■ NotEqual

For these routines, BladeSmith generates code that calls the Comparefunction described in the previous section. For example, the Equal routinegenerated for the Matrix2d type calls the Matrix2dcompare() function:

/* Call Compare to perform the comparison. */return (mi_boolean)(0 == Matrix2dCompare( Gen_param1,

Gen_param2, Gen_fparam ));

You do not have to modify these generated routines.

R-tree Comparison Routines

If you choose to support R-tree indexes for spatial data types, BladeSmithgenerates the following routines:

■ Equal() returns MI_TRUE if two opaque values are equivalent.

■ Overlap() returns MI_TRUE if two opaque values overlap.

■ Contains() returns MI_TRUE if the second opaque value is containedwithin the first opaque value.

■ Within() returns MI_TRUE if the first opaque value is containedwithin the second opaque value.

■ Union() returns a pointer to a new opaque value that is the union ofits two arguments.

■ Size() returns a double-precision value that is the calculated size ofthe opaque value.

■ Inter() returns MI_TRUE if two opaque values intersect.

Spatial data types are usually represented by opaque data types that storecoordinates in k-dimensional space. An R-tree index is organized on thespatial relationships of the values. A parent node in the index stores a valuethat represents the union of all of the values in its child nodes.


Mathematic Routines

Mathematic RoutinesIf you choose to support mathematic functions for an opaque type, Blade-Smith generates the following routines:

■ Plus

■ Minus

■ Times

■ Divide

■ Concat

■ Positive

■ Negate

■ Hash

The Plus, Minus, Times, Divide, and Concat routines take two pointers to theopaque types that are to be operated upon and an MI_FPARAM pointer. ThePositive, Negate, and Hash routines take one pointer to an opaque type andan MI_FPARAM pointer. All of the routines return pointers to an opaque typestructure that is the result of the operation.

BladeSmith does not generate code to perform these arithmetic operations. Itsets the return value to 0 in the generated code. You should call mi_alloc() toallocate memory for the return structure, perform the necessary calculationsto obtain a result, and return a pointer to the result structure. The server freesthe allocated memory when it has finished processing the result.

User-Defined Routines and CastsIf a BladeSmith project contains user-defined routines or casts, BladeSmithgenerates functions for them. It declares the function, its return type, andparameters. In the body of the function, it declares a local variable,Gen_RetVal, of the correct return data type.

Although these functions compile without error, you must add code to themso that they perform the function you intend for them.


User-Defined Routines and Casts

Routines That Return Sets

If you create a user-defined routine that returns a set, BladeSmith adds codeto process the set. Universal Server calls this type of routine repeatedly toprocess all of the return values, using an MI_FPARAM structure to controliteration over the set. The generated code includes a C switch statement withcases to process the set. The switch statement uses the MI_FP_REQUEST()macro to obtain the request flag from the MI_FPARAM structure. UniversalServer sets this flag to one of the following values before calling the routine:

■ SET_INIT: This is the initial call to the routine. The routine shouldallocate and initialize memory for state information.

■ SET_RETONE: The routine is called with this request flag once foreach value in the set.

❑ For each value in the set, the routine places the address of thenext value in the set in the Gen_RetVal variable and returnsGen_RetVal.

❑ When there are no more values to return, the routine uses theMI_FP_SETISDONE() macro to signal Universal Server that all ofthe set values have been returned:MI_FP_SETISDONE(Gen_fparam, MI_TRUE);

On this call, the routine returns a NULL pointer.

■ SET_END: Universal Server sets this request flag after all values in theset have been returned. The routine should clean up, freeingallocated memory and releasing any other resources it has obtained.

For an example of a routine that returns sets, see the LoanAmortization()function in the Business.c example file. See “ExmAmortize() Function” onpage 8-11 for a description of the SQL interface to the LoanAmortization()function.

Casts

Cast routines convert an opaque type to another data type. The generatedfunction takes a pointer to the “from” data type and returns a pointer to the“to” data type. You must add code to perform the conversion and store theresult in the Gen_RetVal variable.


Compiling DataBlade Module Code

Compiling DataBlade Module CodeBladeSmith generates makefiles for UNIX and Windows platforms. Thegenerated makefiles compile the generated C source, producing a sharedobject file in a platform-specific subdirectory of the source code directory.

Important: DataBlade module code requires header files and libraries in theUniversal Server installation tree. The resulting object file is compatible only withthe Universal Server release available during compilation.

The makefile requires the INFORMIXHOME environment variable to be set tothe Universal Server installation directory. The BINDIR variable in themakefile determines where the shared object file is written.

BladeSmith creates server, all, and clean targets in the makefile. The servertarget builds the shared object file. The clean target deletes the shared objectfile. The default all target is equivalent to the server target.

On UNIX platforms, you use the generic UNIX.mak makefile. It includesadditional definitions from platform-specific makefiles. Specify the UNIXplatform by setting the TARGET variable to the path and filename of theinclude file for your platform. Platform-specific files are found in thedirectory $INFORMIXDIR/incl/dbdk. The environment variableMAKEINC_DIR must be set to the location of the Informix make.rules file:

setenv MAKEINC_DIR $INFORMIXDIR/incl/dbdk

To compile and link shared objects on a Sun Solaris 2.5 computer, using theSparc compiler, execute the following command:

make -f UNIX.mak TARGET=$INFORMIXDIR/incl/dbdk/makeinc1.sol

On UNIX, a DataBlade module dynamically links with functions in theDataBlade module .bld file and with functions in other Informix libraries. Atlink time, the UNIX linker lists many of these functions as unresolved. This isproper behavior. ♦

On Windows platforms, the makefile is a Visual C++ project file. Your PATHvariable must include the directories $INFORMIXDIR\incl\public and$INFORMIXDIR\incl\esql. The LIB variable must include$INFORMIXDIR\lib.

UNIX

Windows


Compiling with Tracing Support

For Windows NT, BladeSmith creates two makefiles. The WinNT.mak file isa generic Windows makefile. The datablade_name.mak file is a MicrosoftVisual C++ 4.2 project makefile.

If you use the Microsoft Visual C++ Developer Studio on Windows NT,$INFORMIXDIR/incl/public must precede all other Informix include direc-tories. Choose Tools➞Options➞Directories to relocate the directory.

The DataBlade module .bld file generated on Windows NT must be set read-only. If you use the WinNT.mak make file, this is done for you. If you useMicrosoft Visual C++, you must set the file to read-only yourself aftercompiling the DataBlade module. ♦

Compiling with Tracing SupportBy default, DataBlade modules are compiled with tracing support.

To disable tracing, add the following definition to the make command:

-DTRACE_DEBUG_module=0

Replace module with the name of your DataBlade module. Disabling tracingsupport disables calls to the generated Gen_Trace() routine except those thatraise errors.

If you compile with tracing, you must still enable tracing for the DataBlademodule after you register it in a database. To enable tracing in the database,you create a trace class by inserting a record into the systraceclasses systemcatalog for the DataBlade module.

The following example creates a trace class for the Business DataBlademodule:

insert into informix.systraceclasses(name)values('Business');

You can set a filename for the trace file, or use the default filename, which isthe session id with a .trc extension in the /tmp directory. Use onstat -g sesto get the session id.

To set the name of the trace file in your own code, use the mi_tracefile_set()function:

mi_tracefile_set( "/path/tracefile.trc" );


Compiling with Debug Support

To insure that tracing text actually appears in the output trace file,SERVER_LOCALE, CLIENT_LOCALE, and DB_LOCALE must be set to theappropriate locale in the environment.

The DataBlade API Programmer’s Manual contains a complete discussion oftracing features.

Compiling with Debug SupportTo debug your DataBlade module while it executes in a server process, youmust build the shared object file with debugging symbols. You can eithermodify the makefile and add the required compiler flags to the CFLAGSvariable, or you can set the COPTS variable on the make command line.

On Solaris, the following command builds shared object files with debuggingsymbols:

make -f UNIX.mak COPTS="-g -xs" \TARGET=$INFORMIXDIR/incl/dbdk/Sol2.5_SC.mak

On Windows NT, use Visual C++ to build a debug version of the DataBlademodule.


6Chapter

Testing and DebuggingDataBlade Modules

Installing a Private Server . . . . . . . . . . . . . . . . 6-3Setting Runtime Environment Variables . . . . . . . . . . 6-5Starting the Private Server . . . . . . . . . . . . . . . 6-6

Installing and Registering DataBlade Modules . . . . . . . . . 6-6

Executing Functional Tests . . . . . . . . . . . . . . . . 6-7Functional Test Overview . . . . . . . . . . . . . . . 6-7Contents of the Functional Test Directory . . . . . . . . . . 6-8Adding Custom Test Files . . . . . . . . . . . . . . . 6-10Preparing to Execute Functional Tests . . . . . . . . . . . 6-11Using the Functional Test Scripts. . . . . . . . . . . . . 6-11Initializing Reference Files . . . . . . . . . . . . . . . 6-12

Debugging a DataBlade Module . . . . . . . . . . . . . . 6-12Connecting to the Server from a Client. . . . . . . . . . . 6-13Loading the DataBlade Module . . . . . . . . . . . . . 6-13Identifying the Server Process . . . . . . . . . . . . . . 6-14Starting the Debugger . . . . . . . . . . . . . . . . 6-15Setting Breakpoints . . . . . . . . . . . . . . . . . 6-15Symbols in Shared Object Files . . . . . . . . . . . . . 6-16

Executing DataBlade Modules in Universal Server . . . . . . . . 6-16Shared Object File Ownership and Permissions. . . . . . . . 6-16Replacing a Shared Object File . . . . . . . . . . . . . 6-17Configuring Virtual Processors for DataBlade Modules . . . . . 6-17Setting Stack Sizes for User-Defined Routines . . . . . . . . 6-18

6-2 Data

his chapter provides instructions for executing functional testsgenerated with BladeSmith and for debugging DataBlade module functionsrunning in INFORMIX-Universal Server. The debugging instructions in thischapter support the Sun debugger utility.

To debug DataBlade modules in Universal Server on a UNIX platform, youmust create a separate, private Universal Server installation. This is necessarybecause you must execute the debugger and Universal Server with the sameuser ID.

See the on-line documentation notes for instructions on debugging aDataBlade module in Universal Server running on Windows NT. ♦

This chapter contains the following topics:

■ Installing a private server

■ Installing and registering DataBlade modules

■ Executing functional tests

■ Debugging a DataBlade module

■ Executing DataBlade modules in Universal Server

Installing a Private ServerA Universal Server installation on a UNIX system normally runs with thesuperuser ID. To attach a debugger to a virtual processor, however, you mustrun Universal Server and the debugger with the same user ID. To accomplishthis, you can create a separate Universal Server installation running underyour own user ID.

Windows

T

Testing and Debugging DataBlade Modules 6-3

Installing a Private Server

Because the private server does not run setuid, it has some restrictions:

■ Your chunks must be owned by you and a group to which youbelong.

■ Your private server cannot be accessed by any other users.

■ You cannot mix commands from the production installationdirectory and your private installation directory.

Follow these steps to create a private server installation:

1. Log into the computer with the user ID you want to use when yourun the private server and the debugger.

2. Create a directory for your private server installation.

3. Ask the system administrator to add an entry to /etc/services so thatthe private server has a port number to use.

4. Ask the system adminstrator to create the /INFORMIXTMPdirectory with permissions 1777.

5. Ask the system administrator to check that the following systemlimits are set sufficiently high for you to run Universal Server:

■ Maximum memory per user

■ File descriptor limits

■ Shared memory segment limits

Refer to the Universal Server on-line release notes for any machine-specific parameters that might require tuning.

6. Set the INFORMIXDIR environment variable to the installationdirectory of the production Universal Server installation:

setenv INFORMIXDIR path

7. Change to the Universal Server installation directory:cd $INFORMIXDIR

8. Execute installonline with the -c or -l option to make a private copyof the Universal Server installation in the directory you created for it:

■ To copy all files to the private installation, use the -c option:installonline -c target_directory

■ To use links wherever possible, use the -l option:installonline -l target_directory


Setting Runtime Environment Variables

9. Configure the new Universal Server following the instructions in theINFORMIX-Universal Server Administrator’s Guide.

Setting Runtime Environment VariablesTo run the private server, check that the following environment variables areset properly:

■ INFORMIXDIR

■ PATH

■ LD_LIBRARY_PATH

■ ONCONFIG

■ INFORMIXSERVER

The INFORMIXDIR environment variable contains the full pathname of thedirectory where your private server is installed.

The PATH environment variable must include the directory where theUniversal Server executable files are stored.

The LD_LIBRARY_PATH variable must include the directory $INFOR-MIXDIR/lib. Alternatively, you can ask the system administrator to createlinks in /usr/lib for the shared objects Universal Server requires:

■ $INFORMIXDIR/lib/iasfs09a.so

■ $INFORMIXDIR/lib/iasft09a.so

■ $INFORMIXDIR/lib/ismdd09a.so

The ONCONFIG environment variable specifies the name of the activeONCONFIG configuration file. If the ONCONFIG environment variable is notpresent, the server uses configuration values from the file$INFORMIXDIR/etc/onconfig.

The INFORMIXSERVER environment variable specifies the name of thedefault database server. It is set to the same value you assigned to theDBSERVERNAME configuration parameter in the ONCONFIG configu-ration file. The INFORMIXSERVER environment variable must be set for theserver to build the sysmaster tables.


Starting the Private Server

Starting the Private ServerTo start your private server, first make sure your environment variables areset as described in “Setting Runtime Environment Variables.”

The first time you start the server, execute the following command:

$INFORMIXDIR/bin/oninit -iy

Warning: The -i flag initializes the database, overwriting its existing contents. Usethe -i flag only the first time you start the server.

This command initializes the root dbspace. You must run this command atleast once.

After the root dbspace is initialized, you can start your private server with thefollowing command:

$INFORMIXDIR/bin/oninit

Shut down the server with the following command:

onmode -yak

Installing and Registering DataBlade ModulesInstalling a DataBlade module places the module’s files in a subdirectory ofthe INFORMIXDIR/extend directory. Registering a DataBlade module addsthe module to a database.

See “Replacing a Shared Object File” on page 6-17 for important informationabout updating an existing DataBlade module shared object file.

Important: To debug a DataBlade module, the shared object file must be compiledwith the -g compiler option so that debugging symbols are available to the debugger.See “Compiling DataBlade Module Code” on page 5-31 for information aboutcompiling with debugging support.

For DataBlade modules that you create with the DataBlade Developers Kit,you can copy the directory tree that BladePack generates into the module’ssubdirectory under INFORMIXDIR/extend. Then you use BladeManager toregister the DataBlade module in your test database. Refer to theBladeManager User’s Guide for instructions on running BladeManager.


Executing Functional Tests

To install and register other DataBlade modules, such as the DataBlademodules included with INFORMIX-Universal Server, refer to the instructionsthat accompany them.

Executing Functional TestsWhen you generate functional tests, BladeSmith creates a set of files thatinclude shell scripts and SQL scripts for testing opaque data types, user-defined routines, and casts. By default, these files are created in the functestsubdirectory of the directory containing the BladeSmith project file.

This section includes the following topics:

■ An overview of the functional test environment

■ A description of the files in the functional test directory tree

■ How to add custom tests and initialization scripts to the test suite

■ Preparing to execute functional tests

■ How to execute the shell scripts

■ How to initialize reference files

Functional tests are generated only for the DataBlade module objects forwhich you enter test data in your BladeSmith project. See Chapter 4, “UsingBladeSmith,” for information about entering test data.

Functional Test OverviewFunctional tests include SQL scripts and shell scripts that execute the SQLscripts and determine the results. The shell scripts build test tables in adatabase, run the SQL test scripts, and then drop the test tables from thedatabase.

You can create custom shell scripts to run additional tests or initializationscripts. The generated scripts include calls to your custom scripts.

Shell scripts execute SQL scripts using DB-Access. The results from the SQLstatements are saved in .log files. When you first run functional tests, youmust inspect the .log files and, if the results are as expected, copy them to .reqfiles. You can use the shell scripts to copy .log files to .req files.


Contents of the Functional Test Directory

When you execute functional tests after saving .req files, the shell script usesdiff to compare the .log files to the .req files. If the .log and .req files match,the script prints a “test passed” message. If the files do not match, the scriptprints a “test failed” message. When a .req file does not yet exist, the scriptprints a “status unknown” message.

Contents of the Functional Test DirectoryThe functional test directory includes the following subdirectories:

■ The data directory contains .dat files for each opaque type, user-defined routine, and cast for which you entered test data. The nameof the data file is objectname.dat, where objectname is either the nameof the opaque type or the name of the C function associated with auser-defined routine or cast.

■ The opaque directory contains a subdirectory for each opaque typefor which you have entered test data. The subdirectory containsfunctional tests for the support routines defined for the opaque type.

■ The udr directory contains a subdirectory containing functionaltests3for each user-defined routine for which you entered test data.

■ The cast directory contains a subdirectory containing functional testsfor each cast for which you have entered test data.

The top-level test directory contains a master shell script, main.sh, forexecuting all of the functional tests generated for the DataBlade module.Each subdirectory in the udr, opaque, and cast directories also contains amain.sh script to execute only the functional tests in that subdirectory.

The subdirectories in the udr, opaque, and cast directories contain variousSQL scripts. Each subdirectory has a setup.sql script and a cleanup.sql script.The setup.sql script creates test tables and initializes them with test data. Thecleanup.sql script drops all of the test tables from the database.

BladeSmith creates SQL test scripts for the object that is being tested:

■ For user-defined routines, including functions and procedures,BladeSmith creates a call_pos.sql script and, if negative tests exist, acall_neg.sql script.

■ For casts, it creates a cast.sql script in the cast’s test directory.


Contents of the Functional Test Directory

■ For opaque types, BladeSmith generates SQL scripts to test thesupport routines defined for the type.

The following table lists scripts that may be created for opaque types. A scriptis only generated when the support routines it tests are defined.

Script Names Support Routines Tested

textio_pos.sql Tests Text Input/Output routines for an opaque type.This script uses only valid test data.

textio_neg.sql Tests Text Input/Output routines for an opaque type,using test data with invalid input data.

binio.sql Tests Binary File Input/Output routines using the validinput data for the opaque type.

textexp.sql Tests Text File Import/Export routines for opaque typesusing the UNLOAD and LOAD SQL statements.

binexp.sql Tests Binary File Import/Export routines for an opaquetype using nested calls to the Binary File Import/Exportroutines. The result of the nested calls should be equiv-alent to the text input format for the type.

notify.sql Tests the Assign/Destroy routines by inserting anddeleting values in a new test table.

compare.sql Tests the Compare routine for an opaque type.

equal.sql Tests the Equal routine for an opaque type.

notequal.sql Tests the Not Equal routine for an opaque type.

btree.sql

lessthan.sql

lessthanorequal.sql

greaterthan.sql

greaterthanorequal.sql

Test B-tree support routines for an opaque type.

(1 of 2)


Adding Custom Test Files

Adding Custom Test FilesYou can add additional tests or initialization scripts to your test suite byadding your own scripts in the subdirectories of the functest directory andediting the sample user.sh shell script that BladeSmith generates. Forexample, you could add SQL scripts to create a test database, create specialtest tables in it, and execute custom tests against those tables.

rtree.sql

equal.sql

overlap.sql

contains.sql

within.sql

union.sql

size.sql

inter.sql

Test R-tree support routines for an opaque type.

plus.sql

minus.sql

times.sql

divide.sql

Test standard math operators for an opaque type.

positive.sql

negative.sql

Test the Positive and Negate routines for an opaque type.

concat.sql Tests the concatenation operator by calling the Concate-nation routine for an opaque data type with two instancesof the type.

hash.sql Tests the Hash support routine with a SELECT...GROUP BYSQL query.

Script Names Support Routines Tested

(2 of 2)


Preparing to Execute Functional Tests

Preparing to Execute Functional TestsFunctional tests execute on a UNIX system with a Universal Server instal-lation. Therefore, you must either copy the entire test directory tree to theUNIX machine or share the directory with the UNIX computer through anetwork.

Create a test database and register the DataBlade module you are testing inthe database.

The TESTDB environment variable must be set to the name of the testdatabase.

Using the Functional Test ScriptsUse the main.sh script to execute functional scripts. The main.sh script is aBourne shell script that accepts one command line parameter, as described inthe following table.

Command Description

main.sh build Runs user.sh with a “build” target.

Runs the setup.sql script.

main.sh clean Deletes .log files.

Runs user.sh with a “clean” target.

Executes clean.sql in the database.

main.sh run Uses DB-Access to run each SQL script generated by Blade-Smith, saving the output in a .log file.

If a .req file exists, calls diff to determine the test result. Itprints a message telling whether the test passed or failed.

After all BladeSmith-generated tests are run, executesuser.sh with a “run” target.

main.sh save Copies all .log files to .req files, overwriting existing .reqfiles.

main.sh all Performs the “build,” “run,” and “clean” actions. You canuse this shortcut after the .req files have been saved.


Initializing Reference Files

You can execute a command in all test directories by executing the main.shcommand in the top-level test directory. Or you can execute tests for a specificDataBlade module object by executing main.sh in that object’s test directory.

Initializing Reference FilesThe first time you run tests, you should execute the “build” and “run”targets:

main.sh buildmain.sh run

These two steps prepare the database and run the test scripts, generating .logfiles. The results of all tests will be “unknown (no reference file).”

Check the results in each .log file to determine if the test returned the correctresult. The expected result (which was entered with the test data inBladeSmith) is shown in a comment.

If the results are incorrect, you might need to fix the DataBlade module Ccode. In other cases, the test data could be incorrect.

When the tests return correct results, you can create reference files byexecuting the “save” target:

main.sh save

After reference files have been saved, you can use the “all” shortcut target tobuild and run the tests and clean up the database and test directory.

Debugging a DataBlade ModuleTo debug your DataBlade module, use a debugger that can attach to theactive server process and access the symbol tables of dynamically loadedshared object files. On Solaris, the debugger utility meets these criteria.


Connecting to the Server from a Client

To attach to the server process

1. Connect to the server from a client application, such asDB-Access.

2. Load the DataBlade module into a virtual processor by executingany function defined in the DataBlade module.

3. Identify the server process for the virtual processor executing theDataBlade module code.

4. Start the debugger on the server process.

The following sections describe these steps.

Connecting to the Server from a ClientTo connect to a Universal Server system, choose a client tool that allows youto submit ad hoc queries. On Windows NT, you can use INFORMIX-SQLEditor. On UNIX, you can use DB-Access.

For example, from UNIX, execute the following command:

dbaccess database

where database is a database in which you registered the DataBlade moduleyou want to debug.

Loading the DataBlade ModuleBefore you can attach to the server process with the debugger, you need toload your DataBlade module’s shared object file into the server addressspace. With the shared object file loaded, you can set breakpoints on themodule’s entry points and examine local storage provided by the module’sfunctions.


Identifying the Server Process

To load the DataBlade module into the server address space, execute one ofits functions. One technique is to define a routine in the DataBlade modulethat you use to load the DataBlade module. The routine can be as simple asthis:

mi_integer mod_load_bld(){

return 0;}

To prevent name conflicts, substitute the object prefix assigned to yourDataBlade module in place of mod.

You can then load the DataBlade module shared object file by executing thefollowing command in your client application:

select mod_load_bld()from informix.systables where tabid=1;

Identifying the Server ProcessFind the CPU or EXT virtual process that your DataBlade module is loadedinto by executing the onstat command, as follows:

onstat -g glo

The last section of the output of this onstat command is similar to thefollowing example.

Find the CPU or EXT virtual processor you want to debug and record itsprocess ID for the next step.

Individual virtual processors: vp pid class usercpu syscpu total 1 3544 cpu 3.75 0.96 4.71 2 3545 adm 0.05 0.03 0.08 3 3546 lio 0.04 0.07 0.11 4 3547 pio 0.05 0.03 0.08 5 3548 aio 0.04 0.04 0.08 6 3549 msc 0.39 0.19 0.58 7 3550 aio 0.09 0.10 0.19 8 3551 aio 0.03 0.07 0.10 9 3552 aio 0.02 0.07 0.09 10 3553 aio 0.04 0.04 0.08 11 3554 aio 0.03 0.05 0.08 tot 4.53 1.65 6.18

Figure 6-1onstat Command Output


Starting the Debugger

Starting the DebuggerTo start the debugger, enter the following command at the shell prompt:

debugger - process_id

where process_id is the PID of the CPU or EXT virtual process.

This command starts the debugger on the server virtual processor processwithout starting a new instance of the virtual processor.

Before you can begin debugging, you must enter the following commands todisable signal handlers in the debugger:

ignore SIGUSR1ignore SIGUSR2

You can set breakpoints, examine the stack, resume execution, or carry outany other normal debugger command. See the on-line debugger manualpage for more information about available debugger commands.

Setting BreakpointsYou can set breakpoints in any function with an entry point known todebugger. This includes internal server functions and your DataBlademodule functions.

Universal Server software is compiled with debugging support turned off, solocal storage and line number information is not available for server routines.However, once you compile the DataBlade module for debugging, you cansee line number information and local storage for your functions.

The Universal Server routine that calls your DataBlade module functions iscalled udr_execute(). You can set a breakpoint in this routine as follows:

stop in udr_executecont

When you enter a command in the client that calls one of your DataBlademodule functions, the debugger stops in the udr_execute() routine. Then youcan step through your function. Since your DataBlade module is compiledwith debugging support, you can view your functions’ local variables andstack.


Symbols in Shared Object Files

Symbols in Shared Object FilesUndefined symbols in a shared object file are resolved with the mainUniversal Server module when the file is loaded. If a symbol is missing, theload fails on the first execution of the user-defined routine, and a message iswritten in the log file.

Symbols defined in two different shared object files are distinct entities anddo not resolve against each other.

A symbol defined in a shared object file and the Universal Server mainmodule behaves in one of two ways:

■ If the symbol referenced in the shared object file is in the same sourcefile that references it, the debugger accesses the symbol in the sharedobject file, as expected.

■ If the shared object file includes more than one source file and thereis a cross-file symbol reference, the symbol is resolved to theUniversal Server main module.

Most platforms provide compiler flags that eliminate this problem byresolving all shared object dependencies and generating warnings foranything defined only in the server.

Executing DataBlade Modules in Universal ServerThis section contains information about using DataBlade module sharedobject files with Universal Server.

Shared Object File Ownership and PermissionsShared object files must be owned by the user ID that runs Universal Server.In a production installation, Universal Server runs as user informix andshared object files are owned by user informix.

Shared object files must not be writable by anyone except the owner. Sharedobject file permissions should be set to 755 or 775. If a shared object file iswriteable by “all,” you will get a -9793 error when you try to execute a routinein the shared object file, and a message will be written in the log file.


Replacing a Shared Object File

Replacing a Shared Object FileIf you overwrite a shared object file while it is loaded in the server, the servermay crash when the module is accessed or unloaded. To unload a modulewithout restarting Universal Server, you must drop all routines in themodule, using the SQL DROP command.

When all routines in the module have been dropped and all instances of theroutines have finished executing, the module is removed from the servermemory map. A message is recorded in the log file when the module isunloaded. After the module is unloaded, you can replace the shared objectfile and re-create its user-defined routines in the database.

Configuring Virtual Processors for DataBlade ModulesYou can increase the number of Universal Server virtual processors by settingvariables in the ONCONFIG file. For example:

NUMCPUVPS 2 # Number of user (CPU) VPsSINGLE_CPU_VP 0 # If non-zero, limit number

New VP classes are included in the NUMCPUVPS count.

Tip: Debugging is more difficult when you have more than one CPU because threadscan migrate between processes. The Universal Server communication mechanismuses the SIGUSR1 signal. When debugging, you must avoid SIGUSR1 to preventserver processes from hanging.

You can create new virtual processor classes in the ONCONFIG file as follows:

VPCLASS dbgclass # New VP class for testingSINGLE_CPU_VP 0 # Limit number

User-defined routines created with the CLASS = 'dbgclass' clause areexecuted in the dbgclass virtual process. The class name is not case-sensitive.It appears in the onstat -g glo output as a new process.

In BladeSmith, you assign a routine to a virtual processor class by specifyingthat the routine is poorly behaved, and then typing the class name in theGroup field.

If you create a new virtual processor class, set SINGLE_CPU_VP to 0 in theONCONFIG file.


Setting Stack Sizes for User-Defined Routines

Setting Stack Sizes for User-Defined RoutinesWhen you specify a stack size for a user-defined routine, the server allocatesthe specified amount of memory for every execution iteration of the routine.If a routine does not need a stack larger than 32 KB, it is best not to specify astack size.


7Chapter

Using BladePack

BladePack Overview . . . . . . . . . . . . . . . . . . 7-3BladePack On-Line Help . . . . . . . . . . . . . . . 7-4BladePack Windows . . . . . . . . . . . . . . . . . 7-5

Project View . . . . . . . . . . . . . . . . . . 7-6Item View . . . . . . . . . . . . . . . . . . . 7-9

Using BladePack. . . . . . . . . . . . . . . . . . . . 7-9Understanding Components . . . . . . . . . . . . . . 7-10Overriding Screen Display Text . . . . . . . . . . . . . 7-11Revising On-Line Help for the Installation . . . . . . . . . 7-14

Building the Installation Package . . . . . . . . . . . . . . 7-15

Creating Distribution Media . . . . . . . . . . . . . . . 7-17

7-2 Data

ladePack creates installation packages for DataBlade modules andother software products. BladePack provides a visual representation of aninstallation package, allowing you to add files to the installation package andto customize the installation in a variety of ways. When the installationpackage is defined and any customizations are completed, BladePack createsthe installation package in a build area.

This chapter describes BladePack, the process for creating an installationpackage, and features available for installation packages. BladePack on-linehelp contains additional topics and reference information. Refer to the on-line help for detailed descriptions of the BladePack user interface and screenelements.

BladePack OverviewBladePack produces installation packages for installing products on UNIXand Microsoft Windows platforms. BladePack can create a simple directorytree containing files to be installed, or an installation that includes an inter-active user interface.

On UNIX platforms, an interactive installation includes install and uninstallshell scripts. On Windows, an interactive installation includes Setup andUninstall programs created with InstallShield.

Important: You must have an InstallShield license to create an InstallShield instal-lation for Windows NT or Windows 95. Specify the directory where InstallShield isinstalled during the DataBlade Developers Kit installation or, after installation,modify the IShieldDir environment variable.

B

Using BladePack 7-3

BladePack On-Line Help

The files in an installation package can be divided into separate components,subcomponents, and sub-subcomponents. You must define at least onecomponent for an installation package. You can designate the components toinclude in typical and compact installations. You can also allow users tocustomize their installation by choosing the components they want to install.

For example, in addition to the required shared object file and SQL scripts, aDataBlade module could include example files and on-line help files. You canplace these additional files into separate components that are included in atypical installation, but excluded from a compact installation.

BladePack organizes information into projects. Each project is controlled bya product file (project_name.prd), which contains entries for the componentfile (project_name.cmp), bill of materials file (project_name.bom), and string file(project_name.str).

Tip: If you are packaging a DataBlade module created using BladeSmith, the Blade-Smith Generate Installation Package command creates BladePack project files foryou. Additions and changes you make with BladePack are reflected in the files.

When you build an installation package, you can include several BladePackprojects. For example, you can include DataBlade modules that facilitatesimilar financial calculations into a single installation package.

If you include standard items in each of your installations, you can create aseparate project for these items and include this project in every installation.For example, you can put registry changes required by all DataBlademodules in a standard project file. You should include these changes in acomponent that is always installed.

BladePack On-Line HelpBladePack on-line help provides overview and detailed reference infor-mation for BladePack.

The “About BladePack” section contains topics that provide an overview ofBladePack and installation packages.

The “BladePack Interface” section describes BladePack menus, project viewpages, item view pages, dialog boxes, and the Build Installation wizard.


BladePack Windows

The “BladePack Procedures” section contains instructions for working withprojects, establishing the content of the installation package, organizingcomponents, and setting up the installation package interface.

BladePack WindowsThe BladePack project window is divided into two panes. The left pane iscalled the project view because it displays the overall structure of the instal-lation package. It contains tabbed views of the contents of the installationpackage arranged in hierarchical trees.

The right pane, called the item view, contains detailed information about theobject selected in the project view. You use the project view to add objects tothe installation package and to organize the structure of the installationpackage. You use the item view to enter details about objects in the instal-lation package. Figure 7-1 shows a BladePack window.

Using BladePack 7-5

BladePack Windows

Project View

The project view has three tabbed pages: Content, Structure, andInstallation.

Each page in the project view presents a hierarchical tree of the contents ofthe package. You can click the expander button next to a folder to viewobjects within the folder, or collapse the contents of an expanded folder. Youcan also double-click folders to expand or collapse the view.

Figure 7-1BladePack Project Window

BladePack - [Circle.prd]File Edit View Project Window Help

File:

Directories to DeleteINI File Changes

Circle.bldprep.sqlregister.sqlunregister.sql

Files To Install

Directories to Install

extend

Circle.3.2extend/Circle.3.2

Solaris/sparc

Same

Update:

Date

Shared Locked Neither

Version Neither

Project Contents

Install dir:

Component:

File Details File Comments Project Details

OS:

Circle.3.2

Files to Delete

File IconContent Structure Installation

Registry Changes

../scripts/unregister.sql


BladePack Windows

Content Page

When you click the Content tab in the project view, BladePack displays filesand directories to install, and files and directories to remove. It also displaysinitialization file changes and registry changes for Windows installations.

The Files to Install, Files to Delete, Directories to Install, and Directories toDelete folders are organized as trees that match the directories on the targetcomputer for the installation.

The INI File Changes folder contains entries you want to add to Windowsinitialization files. A folder in the INI File Changes folder identifies an initial-ization file. Folders within these folders represent sections within theinitialization file. Finally, entries within the initialization file section foldersrepresent variables.

The Registry Changes folder contains entries for the Windows registry.Folders within the Registry Changes folder represent the standard registrykeys:

■ HKEY_USERS

■ HKEY_LOCAL MACHINE

■ HKEY_CLASSES_ROOT

You add new folders to these folders to represent subkeys. Within subkeys,you define value entries, consisting of variable names and the values to assignthem. When your DataBlade module is installed on the target computer, theinstallation program adds your keys and value entries to the registry. Referto your Windows documentation for information about the registry.

Structure Page

The Structure page displays the component organization of the installationpackage. An installation package can have components, subcomponents, andsub-subcomponents. You can create a component, subcomponent or sub-subcomponent and then drag files and directories into it.

Using BladePack 7-7

BladePack Windows

Organizing the installation package into components makes it possible toselect portions of the DataBlade module. For example, if your DataBlademodule includes examples, you can create a component of the DataBlademodule called Examples and then create subcomponents for each example.Then customers can choose which examples to install with the DataBlademodule.

However, you can also ship your DataBlade module as a single componentthat contains all of the files. You do not have to organize your installationpackage into subcomponents and sub-subcomponents.

Installation Page

The Installation page displays information that can be customized for theinstallation package.

The Routines folder contains custom dialog boxes, functions, and executableprograms for InstallShield installations on Windows platforms andexecutable programs to run from within interactive installations on Windowsor UNIX platforms. You control when routines execute by placing them in theInit, Before Copy, After Copy, or Exit subfolders. Within the subfolders, youcan drag and drop items to rearrange the execution sequence.

Tip: To add dialog boxes and functions to your installation package, create themusing Microsoft Visual C++ and then add them to a dynamic link library (DLL). Forexamples, see the directory $INFORMIXDIR\dbdk\setup\example.

The Strings folder contains character strings that appear in the dialog boxesand wizards of the InstallShield installation. The folder contains defaultstrings for a standard DataBlade module installation. You can customize thestrings for your installation.

The PC Disk 1 folder contains files that you want to place unpacked on thefirst diskette of an InstallShield installation. This folder does not apply toUNIX DataBlade modules.

The Support folder contains files for dialogs, functions, and programs.

Item View

The right panel displays one or more tabbed pages, depending on the objectyou select in the project view.


Using BladePack

If you select a folder in the project view, the first tab in the item view containsa list of the folder’s contents.

If you select an object, such as a file, in the project view, the first tab in the itemview displays details about the object. The information displayed and thenames of the tabs depend on the type of object you are viewing. A second tabdisplays any comments that you associate with the object.

A Project Details tab always appears in the item view. When you click thistab, BladePack displays information about the project, including the locationof the project file and the date the project was created. You can entercomments to describe the project.

Much of the information in the item view is editable. For example, if you adda component, you type its name in the name field that appears in the itemview. Editable fields have a white background. Fields that cannot be editedhave a gray background.

Using BladePackTo build an installation package with BladePack

1. Collect the product files into a working directory.

2. Start BladePack.

3. Open a project file:

■ For DataBlade modules created using BladeSmith, open the .prdfile created with BladeSmith.

■ For other products, choose File➞New to create a new BladePackproject.

4. Choose Edit➞Add➞Structure➞Component to define a component.If you want to support a selective installation, which allows users tochoose components to install, define additional components orsubcomponents.

5. Add files or directories you want to include in the product instal-lation, such as example files and on-line help files.

Using BladePack 7-9

Understanding Components

6. For Windows installation packages, you can perform any of thefollowing optional customizations:

■ Define modifications to initialization (.ini) files.

■ Define modifications to the Windows registry.

■ Add custom InstallShield dialogs, programs, or functions to callfrom the installation.

■ Customize text strings displayed in the InstallShield Setupwizard.

■ Edit and recompile on-line help for the installation package.

7. If needed, specify programs to execute from within the installation.

8. Build the installation package.

9. Transfer files from the build area to installation media.

Understanding ComponentsBladePack allows you to organize your product installation package intothree layers: component, subcomponent, and sub-subcomponent. To see thecomponent hierarchy for your product, click the Structure tab in the projectview.

Organizing an installation package into a component structure allows you todefine Typical, Compact, and Custom installations. You specify whether eachcomponent is included in the Typical and Compact installations, andwhether it is initially selected when users choose the Custom installation.

During a Custom installation, users can choose to install any components orsubcomponents that you have not marked Hidden. When you mark acomponent Custom, the component is initially selected. The user can chooseto include or exclude any components from the installation.

Tip: If you do not want to offer the choices of Typical, Compact, and Custom instal-lations, mark all components Hidden.

In most cases, the component level is sufficient to create Typical, Compact,and Custom installation options. For example, suppose you have created thefollowing components (and no subcomponents) in your installation package,and marked them as shown:

■ DataBlade module. Typical, Compact, Custom.


Overriding Screen Display Text

■ Help. Typical.

■ Examples. Typical.

■ Debugging Support. Custom.

In this scheme, users install the DataBlade module, help files, and examplesif they choose the Typical installation. If they choose the Compact instal-lation, they install the DataBlade module only. If they choose the Custominstallation, the DataBlade module and Debugging Support are preselected.They can choose to add Help and Examples.

Overriding Screen Display TextBladePack provides default text strings for the InstallShield installationwizard screens for Windows. You can override certain of these text strings.For example, in the Select Installation Type wizard, you can change the textthat appears next to the words Typical, Compact, and Custom to provide yourown definitions for these three types of installations. When you save aBladePack project, BladePack saves any new string definitions in the appro-priate string files.

In the Main Screen folder, you can change the text that appears in the upperleft corner of the background screen. The InstallShield wizard screens, withthe default text provided by BladePack, are shown in the following figures.

Using BladePack 7-11


If all components are marked Hidden, the Typical, Compact, and Customoption buttons in Figure 7-2 are not displayed.

Figure 7-2Installation Options

The instructionsat the top of thepage and the textto the right of thewords Typical,Compact, andCustom can beedited withBladePack.

Installation Options

Choose the installation type.

< Back Next > Cancel

Destination Directoryc:\informix Browse...

Typical

Compact

Custom

Program will be installed with the most commonoptions. Recommended for most users.

Program will be installed with the minimum requiredoptions.

You may choose the options you want to install.Recommended for advanced users.

Figure 7-3Select Installation

Components

The instructionsat the top of thepage can beedited withBladePack.

Select Installation Components

Click to the left of a name to check or uncheck that item. Check any


items you want to install. Uncheck any items you do not want toinstall.Components: Sub Components:

✔ Circ.1.0 69 K✔ doc 69 K

test 1067 K

Descriptiononline documentation

Space Required: 69 K Space Available: 115441 K



Figure 7-4Select Folder for

InformixApplications

The instructionsat the top of thepage and thedefault programfolder can beedited withBladePack.

Select Folder For Informix Applications

Select a program folder for the Informix application icons.

< Back Next >

Program Folder:

Existing Folders:

Cancel

INFORMIX

Administrative Tools

INFORMIXMain

Adobe AcrobatApplicationsFrameMakerGames

Startup

Figure 7-5Ready to Install

Files


Ready To Install Files

Before you begin installing files on your system, review the settings

Circ.1.0testdocCirc.1.0


below. To begin installing, click NEXT.

Destination Path:

c:\informix

Selected Components (Typical Install):


Revising On-Line Help for the Installation

Revising On-Line Help for the InstallationWhen you create an interactive installation for Windows, a Setup.hlp on-linehelp file is included to accompany the Setup program. You can replace thestandard on-line help file with your own. The DataBlade Developers Kitincludes source files you can use to create a custom on-line help file for yourinstallation package:

Figure 7-6Setup Complete


Setup Complete

Setup is complete. Click Finish to exit the installation.

< Back Finish

Figure 7-7Setup Complete,Reboot Required

The text in thetitle bar, theinstructions atthe top of thepage, and theinstructions atthe bottom of thepage can beedited withBladePack.

Setup Complete, Reboot Required

Setup encountered some files on your system that were lockedand could not be copied. Setup will automatically copy theselocked files the next time you restart Windows. You can restartWindows now or restart it later.

Remove any disks from their drives and click on Finish tocomplete the installation.

< Back Finish

Yes, I want to restart my computer now.No, I will restart my computer later.


Building the Installation Package

■ Setup.hpj, the help project file

■ Setup.rtf, the help text source file

These files are in the $INFORMIXDIR\dbdk\setup\WinNT\i386 directory.To customize on-line help for your installation package, edit the Setup.rtf fileand use the project file to create a new Setup.hlp file in the same directory.

Building the Installation PackageWhen the content and organization of your installation package arecomplete, you can build and test it.

When you choose Project➞Build Installation, the Build Installation wizardcollects the following information:

■ Installation type: interactive or file tree

■ Platform for which to build the installation package

■ The target directory in which to build the installation

■ List of BladePack .prd files to include in the installation package

BladePack creates a directory structure in the target directory and copies filesinto the tree. When you build an interative installation package for Windows,BladePack calls InstallShield to process the files and create CD-ROM anddiskette images. If you build an interactive installation for a UNIX platform,BladePack includes install and uninstall shell scripts.

When you build a file tree installation, BladePack creates the file treespecified in the project in the target directory. A file tree build is useful fordebugging the BladePack project.


Building the Installation Package

After you successfully build an interactive installation, the target directorycontains the subdirectories described in the following table.

Directory Description

tree The root of a directory tree containing files to be included inthe installation package. The tree directory can be used todebug problems in the installation package. The contents ofthis directory are not distributed with your installationpackage.

cdrom Contains an image of the installation package that can betransferred to distribution media. DataBlade module devel-opers must rename this directory to the name of theDataBlade module.

For Windows platforms, this directory contains Setup.exeand other files that support an InstallShield installation.

For UNIX platforms, this directory contains an install shellscript and other files that the install script uses duringinstallation.

disk1, disk2...diskn Contain files needed for an InstallShield installation, withfiles split to fit on 1.4 MB diskettes. The disk1 directorycontains Setup.exe and the files required to begin a disketteinstallation.

support Contains copies of files to support the installation, such asproject files, .dll files, and bitmap images. Its contents arenot distributed with your installation package.

folder_tree Contains a directory tree containing the contents of all of thedirectories to be included in the installation package. Thecontents of this directory are not distributed with yourinstallation package.


Creating Distribution Media

Creating Distribution MediaThe product you distribute should conform to the Informix DataBlademodule installation standard. This ensures that customers can installDataBlade modules and other Informix products using common instructions.BladePack creates an interactive installation that ensures a consistent userinterface.

To install a product from diskettes on a Windows platform, the installerexecutes the Setup.exe program on the first diskette. You create diskettes bycopying the contents of the disk1 ... diskn directories to formatted 1.4 MBdiskettes.

All other types of media are created using the cdrom directory in the buildarea.

Important: Rename the cdrom directory to the name of your product before you copythe directory to media or the release area. For example, for the Circle DataBlademodule, rename the cdrom directory to circle. (Do not include the version numberin the directory name.)

Copy the renamed directory and its contents to the media or into the archivefile. This makes it possible to distribute multiple products with their owninstallations on a CD-ROM or tape.

For example, to install the Circle DataBlade module from CD-ROM, theinstaller mounts the CD-ROM, changes to the circle subdirectory, andexecutes Setup (Windows platforms) or install (UNIX platforms).

To install the Circle DataBlade module from a file named circle3.3.tar,retrieved through a local network or the Internet, the installer extracts the fileinto a temporary directory, changes to the circle subdirectory, and executesinstall. When the installation has finished, the circle subdirectory can beremoved.


8Chapter

Example DataBlade Modules

Circle DataBlade Module. . . . . . . . . . . . . . . . . 8-4Pnt Data Type . . . . . . . . . . . . . . . . . . . 8-4Circ Data Type . . . . . . . . . . . . . . . . . . . 8-5Distance() Function . . . . . . . . . . . . . . . . . 8-5Contains() Function . . . . . . . . . . . . . . . . . 8-5PntCompare() Function . . . . . . . . . . . . . . . . 8-6PntEqual() Function . . . . . . . . . . . . . . . . . 8-6CircCompare() Function. . . . . . . . . . . . . . . . 8-6CircEqual() Function . . . . . . . . . . . . . . . . . 8-6PntNotEqual() Function . . . . . . . . . . . . . . . . 8-7CircNotEqual() Function . . . . . . . . . . . . . . . 8-7

Matrix Math DataBlade Module . . . . . . . . . . . . . . 8-7Matrix2d Data Type . . . . . . . . . . . . . . . . . 8-7Compare() Function . . . . . . . . . . . . . . . . . 8-8Equal() Function . . . . . . . . . . . . . . . . . . 8-8NotEqual() Function . . . . . . . . . . . . . . . . . 8-9Plus() Function . . . . . . . . . . . . . . . . . . . 8-9Minus() Function . . . . . . . . . . . . . . . . . . 8-9Times() Function . . . . . . . . . . . . . . . . . . 8-10Divide() Function . . . . . . . . . . . . . . . . . . 8-10

Business DataBlade Module. . . . . . . . . . . . . . . . 8-11ExmAmortize() Function . . . . . . . . . . . . . . . 8-11ExmFV() Function . . . . . . . . . . . . . . . . . . 8-12ExmPV() Function . . . . . . . . . . . . . . . . . . 8-12

Parts Explosion DataBlade Module . . . . . . . . . . . . . 8-13Explode() Function . . . . . . . . . . . . . . . . . 8-13

TopK Terms DataBlade Module . . . . . . . . . . . . . . 8-14TopK() Function . . . . . . . . . . . . . . . . . . 8-14

8-2 Data

MMX DataBlade Module . . . . . . . . . . . . . . . . . 8-14Image Data Type . . . . . . . . . . . . . . . . . . 8-15EnlargeImageX2() Function. . . . . . . . . . . . . . . 8-15ReduceImageX2() Function . . . . . . . . . . . . . . . 8-15ZoomImageXN() Function . . . . . . . . . . . . . . . 8-16


his chapter contains reference information for the exampleDataBlade modules included with the DataBlade Developers Kit. Eachreference describes the data types and functions provided by the DataBlademodule.

The DataBlade modules are simple examples designed to demonstrate howto use various techniques to extend the database system. Each moduleconcentrates on one or two of the techniques described in this guide:

■ The Circle DataBlade module shows how to implement opaquetypes. It defines the Pnt and Circle data types and routines thatoperate on them, such as Text Input/Output routines.

■ The Matrix Math DataBlade module demonstrates how toimplement a two-dimensional matrix data type and provides tworoutines that operate on the data type.

■ The Business DataBlade module demonstrates how to writefunctions that return sets of row types.

■ The Parts Explosion DataBlade module demonstrates how to executequeries in, and return rows from, a DataBlade module function.

■ The TopK Terms DataBlade module demonstrates how to write aniterator function. The TopK() function takes a set as an argument andreturns a set.

■ The MMX DataBlade module demonstrates how to include IntelMMX technology in a DataBlade module. The module shows how towrite DataBlade module routines that can run on computers with orwithout Intel MMX technology. The example uses large objects tostore bitmap images and includes large object support routines.

T

Example DataBlade Modules 8-3

Circle DataBlade Module

For usage examples and implementation details for these DataBlademodules, see the on-line code for the DataBlade modules. The on-line files arelocated in the dbdk\examples directory. The on-line files include a Blade-Smith project file, source files, installation package files, generated andcustom functional tests, and SQL scripts. The generated source files have beenedited to complete the DataBlade modules.

Instructions for compiling the DataBlade modules are in the Readme.txt file.Each example has a test directory containing scripts to test the DataBlademodule features. See Chapter 6, “Testing and Debugging DataBladeModules,” for information about using the functional tests.

Circle DataBlade ModuleThe Circle DataBlade module defines two opaque types, representing two-dimensional points and circles. The DataBlade module provides a functionfor calculating the distance between two points and a function for testingwhether a circle contains a given point.

Pnt Data TypeThe Pnt data type consists of two double precision values, the x-coordinateand y-coordinate of a point.

The input and output text representations of the type are:

'(x,y)'

Associated Functions

The following functions take a Pnt argument:

Distance(Pnt, Pnt) returns double precisionContains(Circ, Pnt) returns BooleanPntCompare(Pnt, Pnt) returns integerPntEqual(Pnt, Pnt) returns BooleanPntNotEqual(Pnt, Pnt) returns Boolean


Circ Data Type

Circ Data TypeThe Circ data type consists of one Pnt value and one double precision valuethat represent the center of a circle and its radius.

The input and output text representations of the Circ type are both:

'(x,y,r)'

where x and y are coordinates of the center of the circle and r is the radius ofthe circle.


The following functions take a Circ argument:

Contains(Circ, Pnt) returns BooleanCircEqual(Circ, Circ) returns BooleanCircNotEqual(Circ, Circ) returns BooleanCircCompare(Circ, Circ) returns integer

Distance() FunctionThe Distance() function computes the distance between two points.

Syntax

Distance(Pnt, Pnt) returns double precision

Contains() FunctionThe Contains() function returns TRUE if a circle contains a given point, FALSEotherwise.

Syntax

Contains(Circ, Pnt) returns Boolean


PntCompare() Function

PntCompare() FunctionThe PntCompare() function compares two Pnt values and returns a nonzerovalue if the points differ or 0 if the points are the same.

Syntax

PntCompare(Pnt, Pnt) returns integer

PntEqual() FunctionThe PntEqual() function returns TRUE if two Pnt values are equal, FALSEotherwise.

Syntax

PntEqual(Pnt, Pnt) returns Boolean

CircCompare() FunctionThe CircCompare() function compares two Circ values and returns anonzero value if the circles differ or 0 if they are the same.

Syntax

CircCompare(Circ, Circ) returns integer

CircEqual() FunctionThe CircEqual() function returns TRUE if two Circ values are equal, FALSEotherwise.

Syntax

CircEqual(Circ, Circ) returns Boolean


PntNotEqual() Function

PntNotEqual() FunctionThe PntNotEqual() function returns TRUE if two Pnt entities are not equal,FALSE otherwise.

Syntax

PntNotEqual(Pnt, Pnt) returns Boolean

CircNotEqual() FunctionThe CircNotEqual() function returns TRUE if two Circ values are not equal,FALSE otherwise.

Syntax

CircNotEqual(Circ, Circ) returns Boolean

Matrix Math DataBlade ModuleThe Matrix Math DataBlade module provides the capability of storing andretrieving two-dimensional matrixes to and from the database. In addition, itprovides some arithmetic operations between matrixes of compatibledimensions.

Matrix2d Data TypeThis data type is a two-dimensional rectangular matrix that stores floating-point numbers.


Compare() Function

Type Representation

The input and output representations of the two-dimensional matrix type arethe same. The representation is enclosed within a set of parentheses. Withinthese outer parentheses, each row is enclosed within parentheses anddelimited from other rows by an optional comma. Within each row, thefloating-point numbers are separated by commas.


Compare(Matrix2d, Matrix2d) returns integerEqual(Matrix2d, Matrix2d) returns BooleanNotEqual(Matrix2d, Matrix2d) returns BooleanPlus(Matrix2d, Matrix2d) returns Matrix2dMinus(Matrix2d, Matrix2d) returns Matrix2dTimes(Matrix2d, Matrix2d) returns Matrix2dDivide(Matrix2d, Matrix2d) returns Matrix2d

Compare() FunctionThe Compare() function compares two matrixes. It returns a nonzero value ifthe matrixes differ or 0 if they are equivalent.

Syntax

Compare(Matrix2d, Matrix2d) returns integer

Equal() FunctionThe Equal() function compares two matrixes. It returns TRUE if they are equalor FALSE if they are not equal.

Syntax

Equal(Matrix2d, Matrix2d) returns Boolean


NotEqual() Function

NotEqual() FunctionThe NotEqual() function compares two matrixes. It returns TRUE if they arenot equal or FALSE if they are equal.

Syntax

NotEqual(Matrix2d, Matrix2d) returns Boolean

Plus() FunctionThe Plus() function performs a matrix add operation on the two matrixes thatare passed to it as arguments and returns the resulting matrix. A matrix addis defined as the sum of the corresponding elements of the two matrixes. Ifthe matrixes passed to this function have different dimensions, this functionresults in a database exception. For two matrixes M1 and M2, each havingdimensions m x n, the resultant matrix M1 + M2 is calculated as follows:

M1 + M2[1,1] = M1[1,1] + M2[1,1]M1 + M2[1,2] = M1[1,2] + M2[1,2]...M1 + M2[m,n] = M1[m,n] + M2[m,n]

Syntax

Plus(Matrix2d, Matrix2d) returns Matrix2d

Minus() FunctionThe Minus() function performs a matrix subtraction operation on the twomatrixes that are passed to it as arguments and returns the resulting matrix.A matrix subtraction is defined as the difference of the correspondingelements of the two matrixes. If the matrixes passed to this function havedifferent dimensions, this function results in a database exception. For twomatrixes M1 and M2, each having dimensions m x n, the resultant matrixM1 - M2 is calculated as follows:

M1 - M2[1,1] = M1[1,1] - M2[1,1]M1 - M2[1,2] = M1[1,2] - M2[1,2]...M1 - M2[m,n] = M1[m,n] - M2[m,n]


Times() Function

Syntax

Minus(Matrix2d, Matrix2d) returns Matrix2d

Times() FunctionThe Times() function performs a matrix multiplication operation on the twomatrixes that are passed to it as arguments and returns the resultant matrix.A matrix M1 that has the dimensions m x n can be multiplied only by anothermatrix M2 having dimensions n x m. The resultant matrix M1 * M2 hasdimensions m x m and is calculated as follows:

M1*M2[1,1] = (M1[1,1]*M2[1,1] + M1[1,2]*M2[2,1] + ... + M1[1,n]*M2[n,1])M1*M2[1,2] = (M1[1,1]*M2[1,2] + M1[1,2]*M2[2,2] + ... + M1[1,n]*M2[n,2]) ...M1*M2[i,j] = (M1[i,1]*M2[1,j] + M1[i,2]*M2[2,j] + ... + M1[i,n]*M2[n,j]) ...M1*M2[m,m] = (M1[m,1]*M2[1,m] + M1[m,2]*M2[2,m] + ... + M1[m,n]*M2[n,m])

Syntax

Times(Matrix2d, Matrix2d) returns Matrix2d

Divide() FunctionThe Divide() function performs a matrix division operation on the twomatrixes that are passed to it as arguments and returns the resultant matrix.A matrix M1 that has the dimensions m x n can only be divided by anothermatrix M2 having dimensions n x m. The resultant matrix M1 / M2 hasdimensions m x m and is calculated as follows:

M1/M2[1,1] = (M1[1,1]/M2[1,1] + M1[1,2]/M2[2,1] + ... + M1[1,n]/M2[n,1])M1/M2[1,2] = (M1[1,1]/M2[1,2] + M1[1,2]/M2[2,2] + ... + M1[1,n]/M2[n,2]) ...M1/M2[i,j] = (M1[i,1]/M2[1,j] + M1[i,2]/M2[2,j] + ... + M1[i,n]/M2[n,j]) ...M1/M2[m,m] = (M1[m,1]/M2[1,m] + M1[m,2]/M2[2,m] + ... + M1[m,n]/M2[n,m])

Syntax

Divide(Matrix2d, Matrix2d) returns Matrix2d


Business DataBlade Module

Business DataBlade Module The Business DataBlade module consists of the following functions:

■ ExmAmortize(). Applies compound interest to loans that are to bepaid off in installments.

■ ExmFV(). Calculates the value of payments after a given time whencompounded at a given interest rate.

■ ExmPV(). Calculates the value today of future payments discountedat the appropriate discount rate.

ExmAmortize() FunctionInput to the ExmAmortize() function is the amount of the loan, its interestrate, and its life span. Output is a schedule of payments and its components.

Syntax

ExmAmortize(real LoanAmount,integer Timespan,real Interestrate)

LoanAmount is the amount borrowed.

Timespan is the loan period.

Interestrate is the interest rate the lender charges per period.

The ExmAmortize() function returns a set of row values. The row consists ofthe following:

■ Period number

■ Beginning amount

■ Payment in period

■ Interest component of payment

■ Principal component of payment

■ Remaining principal balance after this period


ExmFV() Function

ExmFV() FunctionThe ExmFV() function returns the future value given the present value, timespan, and interest rate.

Syntax

ExmFV(real Amount,integer Numyears,real Interestrate) returns real

Amount is the number for which the future value is being estimated.

Numyears is the number of years after which the future value is beingestimated.

Interestrate is the assumed interest rate for estimating the future value.

Amount, Numyears, and Interestrate values cannot be negative.

ExmPV() FunctionThe ExmPV() function returns present value given the future value, timespan, and interest rate.

Syntax

ExmPV(real Amount,integer Numyears,real Interestrate) returns real

Amount is the number for which the present value is being estimated.

Numyears is the number of years after which the future value is given.

Interestrate is the assumed interest rate for estimating the present value.

Amount, Numyears, and Interestrate values cannot be negative.


Parts Explosion DataBlade Module

Parts Explosion DataBlade ModuleThe Parts Explosion DataBlade module provides a simple solution to a partsexplosion problem, in which the idea is to find all dependent child objects fora given parent object. For example, you could find all parts that must beordered to build the engine of a particular model of automobile.

The assumption for this module is that all objects (parts) are stored in onetable. This table has at least two columns:

■ A key column, unique for every object in the table

■ A pointer column describing the “is part of” relationship to otherobjects in the table

This implementation requires that both the key column and the pointercolumn be of type integer.

Typically, the table also has a description of the object, its price, and so on.This parts explosion solution is limited in that it assumes that an object canbe the child of only one parent.

This example DataBlade module demonstrates the use of SQL statementswithin a DataBlade module, how to return a set of results, and the use of theMI_FPARAM structure to return multiple rows. The results of the partsexplosion are stored in a linked list in memory allocated by the functionbefore they are returned to the caller.

Explode() FunctionThe Explode() function returns a set of object keys of type integer that list alldependent child objects for a given parent object key.

Syntax

Explode(integer parent_key,lvarchar table_name,lvarchar key_col_name,lvarchar ptr_col_name) returns set(integer)


TopK Terms DataBlade Module

parent_key is the key of the parent object for which all dependent child objectsshould be looked up.

table_name is the name of the table containing the parent/child objectinformation.

key_col_name is the name of the object key column in the table.

ptr_col_name is the name of the object pointer column ("is part of") in thegiven table.

TopK Terms DataBlade ModuleThe TopK Terms DataBlade module provides a function that finds the top kinteger terms from a set of integers.

TopK() FunctionThe TopK() function accepts a set of integers and a value k and returns thelargest k terms from the input set. The value of k must be greater than zero.

Syntax

TopK(set(integer) intset,integer k) returns set(integer)

intset is the set of integers.

k is the number of integers to return.

MMX DataBlade ModuleThe MMX DataBlade module provides an Image data type to store Windowsbitmap images and functions to enlarge and reduce them. On computerswith Intel MMX processors, these functions use MMX instructions to rescalethe images.


Image Data Type

Image Data TypeThe Image data type stores a Windows bitmap image (.bmp) in the database.The image must be RGB-encoded and square, with dimensions that are amultiple of 64.

Type Representation

The text representation for the Image data type is a space-delimited stringcontaining the name of an external file containing the image data and adescription of the image.

Both strings are enclosed in double quotation marks. For example:

('"image_file_name" "description"')


EnlargeImageX2(Image) returns ImageReduceImageX2(Image) returns ImageZoomImageXN(Image, integer) returns Image

EnlargeImageX2() FunctionThe EnlargeImageX2() function expands an image to twice its original size.The input image must be 64 or 128 pixels square.

Syntax

EnlargeImageX2(Image) returns Image

ReduceImageX2() FunctionThe ReduceImageX2() function reduces an image to half its original size. Theinput image must be 64 or 128 pixels square.

Syntax

ReduceImageX2(Image) returns Image


ZoomImageXN() Function

ZoomImageXN() FunctionThe ZoomImageXN() function expands a portion of an image to twice its size.The size of the resulting image is the same as the original image, which mustbe an RGB-encoded BMP bitmap, 64 or 128 pixels square.

Syntax

ZoomImageXN(Image, integer) returns Image


Index

Index

AAccess methods

for new data types 3-19R-trees 3-18

Access path 3-17Aggregates 3-15AIO virtual processor 2-4, 2-7Assign/Destroy routines

code generated for 5-24 to 5-25overview 1-10

Asynchronous I/O virtualprocessor (AIO VP) 2-4, 2-7

BBinary File Import/Export

routines 1-9, 5-23 to 5-24Binary Send/Receive routines 1-8,

5-20 to 5-22Bit-hashable data types 1-14BladeManager overview 1-19BladePack 7-3 to 7-16

components 7-10windows 7-5

BladeSmithoverview of 1-18viewing property sheets 4-6

.bld file. See Shared object file.Blocking system calls

in DataBlade moduleroutines 2-6, 5-4

.bom file, bill of materials 4-20Business DataBlade module 8-11

CC routines in DataBlade

modules 1-6C source file, merging changes

into 4-21Calling routines 1-18Cast

code generated for 5-29defining with BladeSmith 4-6designing 3-16and inheritance 3-16overview of 1-13

Certifying DataBlade modules 3-31Circ opaque type 8-5CircCompare() function 8-6CircEqual() function 8-6CircleMath DataBlade module 8-4Client applications 3-31Client code 1-17Client format, converting with

Binary Send routine 1-8Client-side libraries

for DataBlade module 3-32.cmp file, components file 4-20Coding standards 3-23Collection type

defining in BladeSmith 4-8overview of 1-5

Comparison routines 1-11, 5-26Compiling

for debugging 5-33using generated makefiles 5-31

Contains() function 8-5Cost of executing query 3-17CPU virtual processor (CPU

VP) 2-5

DData model 3-4DataBlade API, memory

management routines 2-5DataBlade Developers Program

DataBlade moduleregistration 3-26

error code allocation Intro-9, 4-7DataBlade module

accessing 1-17certification 3-31data model 3-4debugging 3-30, 6-6defined 1-3dependency on other DataBlade

modules 1-19designing 3-3 to 3-33directory structure 3-28examples of 1-3, 8-3 to 8-15interoperating with other

DataBlade modules 3-20loading into server address

space 6-13objects, defining with

BladeSmith 4-6query langage interface to 3-7registering with DataBlade

Developers Program 3-26thread-safe calls in 3-25, 5-4

Debuggingcompiling shared object file

for 5-33environment variables for 6-5planning for 3-30starting 6-15steps for 6-7

.def file, for Windows NT.DLL 4-18

Directories, DataBlade moduleinstallation 3-28

Distance() function 8-5Distinct type 1-6, 4-8Distribution media, creating 7-17Dynamically linkable library

(DLL) 4-18

EEnlargeImageX2() function 8-15Environment variables for

debugging 6-5Error code allocation Intro-9, 4-7Error message

allocation of error codes 3-27and SQLSTATE standard 3-27defining with BladeSmith 4-7in generated C source code 5-10internationalization of 4-7parameters in 4-8

ESQL/C, for clientapplications 3-32

Example DataBlade modulesreference 8-3 to 8-15source code Intro-4

Expensive routines 3-13Explode() function 8-13Extended data types 1-4Extension virtual processor (EXT

VP) 2-6

Ffork() function 2-5Formats for representing opaque

types 1-7Functions 1-3

GGenerated files

C code, described 5-8installation package files 4-19objects.sql script 4-17options for 4-17prepare.sql script 3-28, 4-17

Gen_IsMMXMachine()function 5-15

Gen_LoadLOFromFile() utilityfunction 5-13

Gen_sscanf() utility function 5-13,5-17

Gen_StoreLOToFile() utilityfunction 5-13

Global variables in DataBlademodule routines 3-25

GreaterThanOrEqual routine 1-12Grouping 3-15

HHash routine 1-14Help. See On-line help.

IImage data type 8-15Informix

DataBlade DevelopersProgram Intro-9, 3-27

Inheritance, row data type 4-9Installation

customizing screen displaytext 7-11

directory, contents of 3-28package files 4-19

Intel MMX 4-18, 5-14Interface

DataBlade module object 4-7design principles 3-21

Internationalization, errormessages 4-7

Interoperability 3-20Iterative development 3-30

LLarge objects

bulk copy support routines 1-9LOhandles routine 5-25reference count for 1-10

LessThanOrEqual routine 1-12Locale-specific SQL scripts 4-17LOhandles routine. See Large

objects.

Mmake command 5-33Makefile 5-31malloc() function 3-26


Mathematic routines, codegenerated for 5-28

Matrix Math DataBlade module 8-7Matrix2d data type 8-7Media 7-17Memory, allocating in generated

code 5-17Merging source code changes 4-21mi_close() function 5-10MI_LO_HANDLES typedef 5-8mi_new_var() function 5-19mi_open() funtion 5-10mi_read() function 2-7MMX DataBlade module 8-14MMX See Intel MMX.Modality, of DataBlade module

routines 3-22Multirepresentational types,

Assign/Destroy routinesfor 1-10

Multithreaded server 2-4, 3-12

NName space, shared by DataBlade

module objects 3-23Network virtual processor (NET

VP) 2-7NotEqual() function 8-7

OObject names, rules for 3-28Object prefix 3-27objects.sql generated script 4-17On-line help

BladePack 7-4BladeSmith 4-14, 4-21customizing for an installation

package 7-14Opaque type

Assign/Destroy routines 1-10Binary Send/Receive routines 1-8bit-hashable 1-14compared with row type 3-6external representation of 5-16formats for representing 1-7name length 3-28

Text File Import/Exportroutines 1-9

typedef in header file 5-8open() function 3-26Operator class for access method

implementation 3-19Orthogonality 3-21

PParallel processing architecture 2-3Parameters in error messages 4-8Parts Explosion DataBlade

module 8-13Performance, designing DataBlade

module for 3-24Platform naming convention 3-29Platform portability

Binary Send/ Receiveroutines 1-8

coding standards for 3-23data type representation 1-9

Plus() function 8-9Pnt user-defined data type 5-16, 8-4PntCompare() function 8-6PntEqual() function 8-6PntInput() function 5-18PntNotEqual() function 8-7Polymorphism 3-22.prd file, product file 4-20Predicate evaluation 3-12prepare.sql generated script 4-17Property sheet, for BladeSmith

object 4-6

QQualification, in SQL

statement 3-10Qualified type 1-15, 4-9Query language interface

and DataBlade moduledesign 3-7

Query optimizerand access path selection 3-17strategies using B-trees for user-

defined types 1-12Query processing

and thread control blocks 2-4and virtual processors 2-5

RReduceImageX2() function 8-15Routines 1-3

defining with BladeSmith 4-8supporting opaque

types 1-6 to 1-15Row type

defining in BladeSmith 4-9overview of 1-5

R-tree access method 1-13, 3-18

SServer binary format,

converting 1-8Setup.rtf, location of 7-15Shared memory 2-4Shared object file 1-6

compiling with debuggingsupport 5-33

loading into server addressspace 6-13

naming 3-28Sorting 3-14SPL 1-3SQL

target list in a DML statement 3-8user-defined routines in a

WHERE clause 3-10SQL scripts

adding custom SQL to generatedscripts 4-18

generating 4-17SQLSTATE, and error

messages 3-27Stack space

used by DataBlade moduleroutines 2-5

.str file, strings file 4-20Symetric multiprocessor (SMP)

computer 2-3sysbldobjects system table 4-17syserrors system table 5-12

Index 3

System calls in DataBlade moduleroutines 3-26

TTables in DataBlade modules 1-16Testing DataBlade modules 3-30Text File Import/Export

routines 1-9, 5-22 to 5-23Text Input/Output routines 1-8,

5-16 to 5-20Thread control block 2-4Thread-safe DataBlade module

routines 3-25Times() function 8-10TopK Terms DataBlade

module 8-14TopK() function 8-14Tracing in DataBlade module

routines 3-30Transactions and DataBlade

module design 3-19

UUniversal Server

architecture 2-3 to 2-7dynamic function manager 2-5predicate evaluation 3-12query processing 3-12 to 3-20shared memory 2-4virtual processors 2-3

User interface, separating from datamodel 3-4

User-defined routinecode generated for 5-29implemented in server or

client 3-9in DataBlade module design 3-12used in SQL statements 3-8

Vvarchar data type, trailing blanks

in 1-14Virtual processors 2-3, 2-5 to 2-7

and thread migration 2-5

choosing for DataBlademodule 3-24

CPU VP restrictions 2-6

Wwritten 1-6


Documents

users.salleurl.eduusers.salleurl.edu/~marcg/Documentacio/databases/DataBlade_SDK.… · iv DataBlade Developers Kit User’s Guide Chapter 2 INFORMIX-Universal Server Architecture