DB2 IBM Informix


Version 10.0

IBM Informix Dynamic Server Administrator’s Guide

G251-2267-02
 DB2 IBM Informix
®


Version 10.0

IBM Informix Dynamic Server Administrator’s Guide

G251-2267-02
 Note:
Before using this information and the product it supports, read the information in “Notices” on page B-1.

Third Edition (December 2005)

This document contains proprietary information of IBM. It is provided under a license agreement and is protected
by copyright law. The information contained in this publication does not include any product warranties, and any
statements provided in this manual should not be interpreted as such.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any
way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1996, 2005. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
In This Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Types of Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Software Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Assumptions About Your Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Demonstration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
New Features in Dynamic Server, Version 10.0 . . . . . . . . . . . . . . . . . . . . . . . xix
Database Server Security and Usability Enhancements . . . . . . . . . . . . . . . . . . . . xix
New Features in Previous Versions of Dynamic Server . . . . . . . . . . . . . . . . . . . . . xxi
Features in Dynamic Server, Version 9.4. . . . . . . . . . . . . . . . . . . . . . . . . xxi
Features in Dynamic Server, Version 9.3 . . . . . . . . . . . . . . . . . . . . . . . . xxii
Features in Dynamic Server, Version 9.21 . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Organizational Changes to This Manual In Version 9.2 . . . . . . . . . . . . . . . . . . . xxiii
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Feature, Product, and Platform Markup . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Example Code Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
IBM Informix Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Installation Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Online Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Informix Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
IBM Informix Dynamic Server Version 10.0 and CSDK Version 2.90 Documentation Set . . . . . . . . . xxxi
Compliance with Industry Standards . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
IBM Welcomes Your Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii

Part 1. The Database Server

Chapter 1. Installing and Configuring the Database Server . . . . . . . . . . . . . 1-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Planning for the Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Considering Your Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Considering Your Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Configuring the Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Configuring Windows Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Modifying UNIX Kernel Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Allocating Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Using Large Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Creating Chunk Files on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Providing NTFS Partitions in Windows . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Setting Permissions, Ownership, and Group . . . . . . . . . . . . . . . . . . . . . . . 1-6
Creating Standard Device Names (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Setting Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Setting GLS Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Setting Environment Variables on UNIX . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Setting Environment Variables on Windows . . . . . . . . . . . . . . . . . . . . . . . 1-9
Configuring Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
The sqlhosts File on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
The sqlhosts Registry on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Configuring Connectivity Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . 1-10

© Copyright IBM Corp. 1996, 2005 iii

Configuring the Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Preparing the ONCONFIG Configuration File . . . . . . . . . . . . . . . . . . . . . . 1-11
Using Server Setup in ISA to Customize Your Configuration . . . . . . . . . . . . . . . . . 1-12
Using IBM Informix Server Administrator to Update the ONCONFIG File . . . . . . . . . . . . . 1-12
Using the Instance Manager to Create a New Database Server Instance (Windows) . . . . . . . . . . 1-12
Using the Instance Manager to Rename a Database Server Instance (Windows) . . . . . . . . . . . 1-13
Configuring Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Starting and Administering the Database Server . . . . . . . . . . . . . . . . . . . . . . 1-13
Starting the Database Server and Initializing Disk Space . . . . . . . . . . . . . . . . . . . 1-14
Preparing for Automatic Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Preparing to Connect to Applications . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Creating Storage Spaces and Chunks . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Supporting Large Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Setting Up Your Backup System and Storage. . . . . . . . . . . . . . . . . . . . . . . 1-17
Performing Routine Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Changing Database Server Modes . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Backing Up Data and Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Monitoring Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Checking for Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Performing Additional Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Using Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing Database-Logging Status . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Shared Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Parallel Database Query . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Using Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using Distributed Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Monitoring Database Server Activity . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Event Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
IBM Informix Server Administrator (ISA) . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Message Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
oncheck Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
onperf Tool (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
onstat Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
System Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
UNIX Operating-System Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Windows Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Windows Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Windows Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24

Chapter 2. Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 2-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Database Server Identification Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Disk-Space Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Mirror of Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Other Space-Management Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Logging Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Physical Log Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Rollback and Recovery Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Backup and Restore Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Message-Log Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Shared-Memory Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Shared-Memory Size Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Shared-Memory Space Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5

iv IBM Informix Dynamic Server Administrator’s Guide

 Shared-Memory Buffer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
SQL Statement Cache Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Decision-Support Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Database Server Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Virtual Processor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Time Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Restore Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
High-Availability Data-Replication Parameters . . . . . . . . . . . . . . . . . . . . . . . 2-8
Event-Alarm Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Dump Parameters (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Directives Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Security-Related Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Specialized Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Auditing Parameters (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Optical Media Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
UNIX Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Monitoring Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

Chapter 3. Client/Server Communications . . . . . . . . . . . . . . . . . . . . 3-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Client/Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Network Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-2
Network Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Windows Network Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-3
Database Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
Multiplexed Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-4
Connections That the Database Server Supports . . . . . . . . . . . . . . . . . . . . . . .3-5
Local Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Shared-Memory Connections (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . .3-6
Stream-Pipe Connections (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Named-Pipe Connections (Windows) . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Local-Loopback Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-7
Communication Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Connectivity Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Network-Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . .3-8
Network Security Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
The sqlhosts File and the SQLHOSTS Registry Key . . . . . . . . . . . . . . . . . . . . 3-13
The sqlhosts Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Connectivity Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Alternatives for TCP/IP Connections . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Dynamic Server Support for IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . 3-28
ONCONFIG Parameters for Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
DBSERVERNAME Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . . 3-29
DBSERVERALIASES Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . 3-30
NETTYPE Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Environment Variables for Network Connections . . . . . . . . . . . . . . . . . . . . . . 3-31
Examples of Client/Server Configurations . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Using a Shared-Memory Connection (UNIX) . . . . . . . . . . . . . . . . . . . . . . . 3-31
Using a Local-Loopback Connection . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Using a Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
Using Multiple Connection Types . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Accessing Multiple Database Servers . . . . . . . . . . . . . . . . . . . . . . . . . 3-35
Using IBM Informix MaxConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35

Chapter 4. Initializing the Database Server . . . . . . . . . . . . . . . . . . . . 4-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Types of Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Initializing Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Contents v
 Initialization Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Process Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Create Shared-Memory Portions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Initialize or Restart Shared-Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Initialize Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start All Required Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Make Necessary Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start a Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Document Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Create the oncfg_servername.servernum File . . . . . . . . . . . . . . . . . . . . . . . 4-6
Drop Temporary Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Set Forced Residency If Specified . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Return Control to User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Create sysmaster Database and Prepare SMI Tables . . . . . . . . . . . . . . . . . . . . . 4-6
Create the sysutils Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Monitor Maximum Number of User Connections . . . . . . . . . . . . . . . . . . . . . 4-7
Database Server Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Changing Database Server Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Users Permitted to Change Modes . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
ISA Options for Changing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
ON-Monitor Options for Changing Modes (UNIX) . . . . . . . . . . . . . . . . . . . . . 4-10
Command-Line Options for Changing Modes . . . . . . . . . . . . . . . . . . . . . . 4-10

Chapter 5. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Server Utility Security Before Starting on UNIX and Linux . . . . . . . . . . . . . . . . . . . 5-2
Disabling Security Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Securing an Insecure Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Warning and Error Messages for Utility Security Checks . . . . . . . . . . . . . . . . . . . 5-3
INFORMIXDIR Directory Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Users and Group Membership for Running Dynamic Server Utilities . . . . . . . . . . . . . . . 5-5
Setting Up Security for Local Connections to a Host . . . . . . . . . . . . . . . . . . . . . 5-5
Auditing Database Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
3 Setting Permission to Create Databases . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Default Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
3 Limiting Denial-of-Service Flood Attacks . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Using the LISTEN_TIMEOUT and MAX_INCOMPLETE_CONNECTIONS Parameters . . . . . . . . . 5-8
Using the onmode -wm and onmode -wf Options to Change Parameter Values . . . . . . . . . . . 5-8
Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Overview of Encryption and Encryption Options . . . . . . . . . . . . . . . . . . . . . 5-8
Using Communication Support Modules (CSMs) for Password and Data Transmission Encryption . . . . . 5-9
Using Column-Level Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Authentication Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Pluggable Authentication Modules for Systems Running on UNIX or Linux . . . . . . . . . . . . 5-23
LDAP Authentication Support on Windows . . . . . . . . . . . . . . . . . . . . . . . 5-25
Application Development for Authentication Modules . . . . . . . . . . . . . . . . . . . 5-27
Distributed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Client APIs and Authentication Support Modules . . . . . . . . . . . . . . . . . . . . . 5-30
Compatibility Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30
Enterprise Replication and High-Availability Data Replication Connection Security Option . . . . . . . . 5-31
Security for External Routines (UDRs) . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32
4 Security for Loading External Modules . . . . . . . . . . . . . . . . . . . . . . . . . 5-32
3 Enabling non-DBAs to View SQL Statements a Session Is Executing . . . . . . . . . . . . . . . . 5-33

Part 2. Disk, Memory, and Process Management

Chapter 6. Virtual Processors and Threads . . . . . . . . . . . . . . . . . . . . 6-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

vi IBM Informix Dynamic Server Administrator’s Guide

Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Types of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Advantages of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
How Virtual Processors Service Threads . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Context Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Virtual-Processor Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
CPU Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
User-Defined Classes of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . 6-15
Java Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Disk I/O Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Network Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
Communications Support Module Virtual Processor . . . . . . . . . . . . . . . . . . . . 6-25
Encrypt Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Optical Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Audit Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Miscellaneous Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

Chapter 7. Managing Virtual Processors . . . . . . . . . . . . . . . . . . . . . 7-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Setting Virtual-Processor Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 7-1
Setting Virtual-Processor Parameters with a Text Editor . . . . . . . . . . . . . . . . . . . 7-1
Setting Virtual-Processor Parameters with ISA . . . . . . . . . . . . . . . . . . . . . . 7-2
Setting Virtual-Processor Parameters with ON-Monitor . . . . . . . . . . . . . . . . . . . 7-3
Starting and Stopping Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Adding Virtual Processors in Online Mode . . . . . . . . . . . . . . . . . . . . . . . 7-3
Dropping CPU and User-Defined Virtual Processors . . . . . . . . . . . . . . . . . . . . 7-4
Monitoring Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Monitoring Virtual Processors with Command-Line Utilities . . . . . . . . . . . . . . . . . . 7-5
Monitoring Virtual Processors with SMI Tables . . . . . . . . . . . . . . . . . . . . . . 7-6

Chapter 8. Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared-Memory Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared-Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Shared-Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Action to Take If SHMTOTAL Is Exceeded . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Processes That Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
How a Client Attaches to the Communications Portion (UNIX) . . . . . . . . . . . . . . . . . 8-6
How Utilities Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . 8-6
How Virtual Processors Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . 8-7
Resident Shared-Memory Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Resident Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Shared-Memory Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Shared-Memory Buffer Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Logical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Physical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
High-Availability Data-Replication Buffer . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Lock Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Management of the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . 8-14
Components of the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . 8-15
Data-Distribution Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Communications Portion of Shared Memory (UNIX) . . . . . . . . . . . . . . . . . . . . . 8-20
Virtual-Extension Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . 8-20

Contents vii
Concurrency Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Shared-Memory Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Shared-Memory Buffer Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Database Server Thread Access to Shared Buffers . . . . . . . . . . . . . . . . . . . . . . 8-21
FIFO/LRU Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Configuring the Database Server to Read Ahead . . . . . . . . . . . . . . . . . . . . . 8-25
Database Server Thread Access to Buffer Pages . . . . . . . . . . . . . . . . . . . . . . 8-25
Flushing Data to Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing Buffer-Pool Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing Before-Images First . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing the Physical-Log Buffer. . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Synchronizing Buffer Flushing . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Describing Flushing Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Flushing the Logical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Buffering Large-Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Writing Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Accessing Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Memory Use on 64-Bit Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32

Chapter 9. Managing Shared Memory . . . . . . . . . . . . . . . . . . . . . . 9-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Setting Operating-System Shared-Memory Configuration Parameters . . . . . . . . . . . . . . . . 9-2
Maximum Shared-Memory Segment Size . . . . . . . . . . . . . . . . . . . . . . . . 9-2

Semaphores (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-3
Setting Database Server Shared-Memory Configuration Parameters . . . . . . . . . . . . . . . .
9-3
Setting Parameters for Resident Shared Memory . . . . . . . . . . . . . . . . . . . . . .
9-4
Setting Parameters for Virtual Shared Memory . . . . . . . . . . . . . . . . . . . . . .
9-4
Setting Parameters for Shared-Memory Performance . . . . . . . . . . . . . . . . . . . .
9-5
Setting Shared-Memory Parameters with a Text Editor . . . . . . . . . . . . . . . . . . . .
9-5
Setting Shared-Memory Parameters with ISA . . . . . . . . . . . . . . . . . . . . . . .
9-5
Setting Shared-Memory Parameters with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . .
9-6
Setting SQL Statement Cache Parameters . . . . . . . . . . . . . . . . . . . . . . . . .
9-6
Setting Up Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-7
Turning Residency On or Off for Resident Shared Memory . . . . . . . . . . . . . . . . . . .
9-7
Turning Residency On or Off in Online Mode . . . . . . . . . . . . . . . . . . . . . .
9-7
Turning Residency On or Off When Restarting the Database Server . . . . . . . . . . . . . . .
9-7
Adding a Segment to the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . .
9-7
Monitoring Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-8
Monitoring Shared-Memory Segments . . . . . . . . . . . . . . . . . . . . . . . . .
9-8
Monitoring the Shared-Memory Profile and Latches . . . . . . . . . . . . . . . . . . . .
9-8
Monitoring Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-9
Monitoring Buffer-Pool Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11

Chapter 10. Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Physical and Logical Units of Storage . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
Disk Allocation for Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
Offsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Blobpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-6
Sbpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7
Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-8
Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-9
Control of Where Data Is Stored . . . . . . . . . . . . . . . . . . . . . . . . . . .10-9
Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Temporary Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13

viii IBM Informix Dynamic Server Administrator’s Guide

 Advantages of Using Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Sbspaces and Enterprise Replication . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Metadata, User Data, and Reserved Area . . . . . . . . . . . . . . . . . . . . . . . 10-13
Control of Where Data Is Stored . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Storage Characteristics of Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
Levels of Inheritance for Sbspace Characteristics . . . . . . . . . . . . . . . . . . . . . 10-17
More Information About Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Temporary Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19
Comparison of Temporary and Standard Sbspaces . . . . . . . . . . . . . . . . . . . . 10-20
Temporary Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
Extspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Table Types for Dynamic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
Standard Permanent Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
RAW Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Temp Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Properties of Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Maximum Number of Tblspaces in a Table . . . . . . . . . . . . . . . . . . . . . . . 10-28
Table and Index Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Extent Interleaving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Table Fragmentation and Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Amount of Disk Space Needed to Store Data . . . . . . . . . . . . . . . . . . . . . . . 10-31
Size of the Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Amount of Space That Databases Require . . . . . . . . . . . . . . . . . . . . . . . 10-33
Disk-Layout Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Dbspace and Chunk Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Table-Location Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Sample Disk Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
Sample Layout When Performance Is Highest Priority . . . . . . . . . . . . . . . . . . . 10-36
Sample Layout When Availability Is Highest Priority . . . . . . . . . . . . . . . . . . . 10-36
Logical-Volume Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37

Chapter 11. Managing Disk Space . . . . . . . . . . . . . . . . . . . . . . . 11-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-2
Allocating Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3
Specifying an Offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-3
Allocating Cooked File Spaces on UNIX . . . . . . . . . . . . . . . . . . . . . . . .11-4
Allocating Raw Disk Space on UNIX . . . . . . . . . . . . . . . . . . . . . . . . .11-5
Creating Symbolic Links to Raw Devices (UNIX) . . . . . . . . . . . . . . . . . . . . .11-5
Allocating NTFS File Space on Windows . . . . . . . . . . . . . . . . . . . . . . . .11-6
Allocating Raw Disk Space on Windows . . . . . . . . . . . . . . . . . . . . . . . .11-6
Specifying Names for Storage Spaces and Chunks . . . . . . . . . . . . . . . . . . . . . .11-7
Specifying the Maximum Size of Chunks . . . . . . . . . . . . . . . . . . . . . . . .11-7
Specifying the Maximum Number of Chunks and Storage Spaces . . . . . . . . . . . . . . . .11-8
Backing Up After You Change the Physical Schema . . . . . . . . . . . . . . . . . . . .11-8
Managing Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11-8
Creating a Dbspace that Uses the Default Page Size . . . . . . . . . . . . . . . . . . . .11-8
Creating a Dbspace with a Non-Default Page Size . . . . . . . . . . . . . . . . . . . . 11-11
Creating a Temporary Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
What to Do If You Run Out of Disk Space . . . . . . . . . . . . . . . . . . . . . . . 11-16
Adding a Chunk to a Dbspace or Blobspace . . . . . . . . . . . . . . . . . . . . . . 11-16
Renaming Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
Managing Dbspace Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18
Managing Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20
Creating a Blobspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20
Preparing Blobspaces to Store TEXT and BYTE Data . . . . . . . . . . . . . . . . . . . . 11-21
Determining Blobpage Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
Managing Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22

Contents ix
 Creating an Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Sizing Sbspace Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Adding a Chunk to an Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Altering Storage Characteristics of Smart Large Objects . . . . . . . . . . . . . . . . . . . 11-24
Creating a Temporary Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
Dropping a Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
Verifying Whether a Chunk Is Empty . . . . . . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from a Dbspace with onspaces . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from a Blobspace . . . . . . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from an Sbspace with onspaces . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
Preparing to Drop a Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
Dropping a Mirrored Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . 11-28
Dropping a Storage Space with onspaces . . . . . . . . . . . . . . . . . . . . . . . 11-28
Dropping a Dbspace or Blobspace with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 11-28
Backing Up After Dropping a Storage Space . . . . . . . . . . . . . . . . . . . . . . 11-28
Managing Extspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Creating an Extspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Dropping an Extspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Skipping Inaccessible Fragments . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Using the DATASKIP Configuration Parameter . . . . . . . . . . . . . . . . . . . . . 11-30
Using the Dataskip Feature of onspaces . . . . . . . . . . . . . . . . . . . . . . . . 11-30
Using onstat to Check Dataskip Status . . . . . . . . . . . . . . . . . . . . . . . . 11-30
Using the SQL Statement SET DATASKIP . . . . . . . . . . . . . . . . . . . . . . . 11-30
Effect of the Dataskip Feature on Transactions . . . . . . . . . . . . . . . . . . . . . . 11-31
Determining When to Use Dataskip . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
Monitoring Fragmentation Use . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
Displaying Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Monitoring Disk Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Monitoring Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
Monitoring Tblspaces and Extents . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Monitoring Simple Large Objects in a Blobspace . . . . . . . . . . . . . . . . . . . . . 11-37
Monitoring Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-39
Loading Data Into a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-44

Part 3. Logging and Log Administration

Chapter 12. Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Database Server Processes That Require Logging . . . . . . . . . . . . . . . . . . . . . . 12-1
Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Logging of SQL Statements and Database Server Activity . . . . . . . . . . . . . . . . . . . 12-3
Activity That is Always Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Activity Logged for Databases with Transaction Logging . . . . . . . . . . . . . . . . . . 12-4
Activity That is Not Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Database-Logging Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Unbuffered Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Buffered Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
ANSI-Compliant Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
No Database Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Databases with Different Log-Buffering Status . . . . . . . . . . . . . . . . . . . . . . 12-6
Database Logging in an X/Open DTP Environment . . . . . . . . . . . . . . . . . . . . 12-7
Settings or Changes for Logging Status or Mode . . . . . . . . . . . . . . . . . . . . . . 12-7

Chapter 13. Managing the Database-Logging Mode . . . . . . . . . . . . . . . . 13-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Changing the Database-Logging Mode. . . . . . . . . . . . . . . . . . . . . . . . . . 13-2

x IBM Informix Dynamic Server Administrator’s Guide

Modifying the Database-Logging Mode with ondblog . . . . . . . . . . . . . . . . . . . . 13-2
Changing the Buffering Mode with ondblog . . . . . . . . . . . . . . . . . . . . . . . 13-2
Canceling a Logging Mode Change with ondblog . . . . . . . . . . . . . . . . . . . . . 13-3
Ending Logging with ondblog . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Making a Database ANSI Compliant with ondblog . . . . . . . . . . . . . . . . . . . . 13-3
Changing the Logging Mode of an ANSI-Compliant Database . . . . . . . . . . . . . . . . . 13-3
Modifying the Database Logging Mode with ontape . . . . . . . . . . . . . . . . . . . . . 13-3
Turning On Transaction Logging with ontape . . . . . . . . . . . . . . . . . . . . . . 13-3
Ending Logging with ontape . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Changing Buffering Mode with ontape . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Making a Database ANSI Compliant with ontape . . . . . . . . . . . . . . . . . . . . . 13-4
Modifying Database Logging Mode with ISA . . . . . . . . . . . . . . . . . . . . . . . 13-4
Modifying Database Logging Mode with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . 13-5
Modifying the Table-Logging Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Altering a Table to Turn Off Logging . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Altering a Table to Turn On Logging . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring the Logging Mode of a Database . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring the Logging Mode with SMI Tables . . . . . . . . . . . . . . . . . . . . . . 13-6
Monitoring the Logging Mode with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . 13-6
Monitoring the Logging Mode with ISA . . . . . . . . . . . . . . . . . . . . . . . . 13-6

Chapter 14. Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
What Is the Logical Log? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Location of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Identification of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Status Flags of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Size of the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Number of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Dynamic Log Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Freeing of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Action If the Next Logical-Log File Is Not Free . . . . . . . . . . . . . . . . . . . . . . 14-5
Action if the Next Log File Contains the Last Checkpoint . . . . . . . . . . . . . . . . . . 14-6
Logging Blobspaces and Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . . 14-6
Switching Log Files to Activate Blobspaces . . . . . . . . . . . . . . . . . . . . . . . 14-6
Backing Up Log Files to Free Blobpages . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Backing Up Blobspaces After Inserting or Deleting TEXT and BYTE Data . . . . . . . . . . . . . 14-7
Logging Sbspaces and Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Using Sbspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Using Smart-Large-Object Log Records . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Preventing Long Transactions When Logging Smart-Large-Object Data . . . . . . . . . . . . . . 14-9
Logging Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Dbspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Blobspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10

Chapter 15. Managing Logical-Log Files . . . . . . . . . . . . . . . . . . . . 15-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Estimating the Size and Number of Log Files . . . . . . . . . . . . . . . . . . . . . . . 15-2
Estimating the Log Size When Logging Smart Large Objects . . . . . . . . . . . . . . . . . 15-3
Estimating the Number of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . 15-3
Backing Up Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Backing Up Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Backing Up Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Switching to the Next Logical-Log File. . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Freeing a Logical-Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Deleting a Log File with Status D . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Freeing a Log File with Status U . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Freeing a Log File with Status U-B or F . . . . . . . . . . . . . . . . . . . . . . . . 15-5

Contents xi
 Freeing a Log File with Status U-C or U-C-L. . . . . . . . . . . . . . . . . . . . . . . 15-6
Freeing a Log File with Status U-B-L . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
Monitoring Logging Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
Monitoring the Logical Log for Fullness . . . . . . . . . . . . . . . . . . . . . . . . 15-6
Monitoring Temporary Logical Logs . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Monitoring Log-Backup Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Allocating Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Adding Logs Dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Adding Logical-Log Files Manually . . . . . . . . . . . . . . . . . . . . . . . . . 15-10
Dropping Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-11
Changing the Size of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . 15-12
Moving a Logical-Log File to Another Dbspace . . . . . . . . . . . . . . . . . . . . . . 15-12
Changing Logging Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . 15-13
Using ON-Monitor to Change LOGFILES (UNIX). . . . . . . . . . . . . . . . . . . . . 15-14
Displaying Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-14
Monitoring Events for Dynamically Added Logs . . . . . . . . . . . . . . . . . . . . . . 15-14
Setting High-Watermarks for Rolling Back Long Transactions . . . . . . . . . . . . . . . . . . 15-15
Long-Transaction High-Watermark (LTXHWM) . . . . . . . . . . . . . . . . . . . . . 15-16
Exclusive Access, Long-Transaction High-Watermark (LTXEHWM) . . . . . . . . . . . . . . . 15-16
Adjusting the Size of Log Files to Prevent Long Transactions . . . . . . . . . . . . . . . . . 15-16
Recovering from a Long Transaction Hang . . . . . . . . . . . . . . . . . . . . . . . 15-16

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery . . . . . . . . . . 16-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-2
Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-2
Physical Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-2
Fast Recovery Use of Physically-Logged Pages . . . . . . . . . . . . . . . . . . . . . .16-2
Backup Use of Physically-Logged Pages . . . . . . . . . . . . . . . . . . . . . . . .16-3
Database Server Activity That Is Physically Logged . . . . . . . . . . . . . . . . . . . .16-3
Size and Location of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . .16-4
Specifying the Location of the Physical Log . . . . . . . . . . . . . . . . . . . . . . .16-4
Estimating the Size of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . .16-4
Configuring the Size of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . .16-5
Details of Physical Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-6
Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-7
Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-7
Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16-7
Events That Initiate a Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . .16-9
Events That Initiate a Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . .16-9
Sequence of Events in a Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . .16-9
Backup and Restore Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Need for Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Situations When Fast Recovery Is Initiated . . . . . . . . . . . . . . . . . . . . . . . 16-11
Details of Fast Recovery After A Full Checkpoint . . . . . . . . . . . . . . . . . . . . . 16-12
Details of Fast Recovery After A Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . 16-14
Alternative Fast Restart Recovery Options for Fuzzy Operations . . . . . . . . . . . . . . . . 16-17

Chapter 17. Managing the Physical Log . . . . . . . . . . . . . . . . . . . . . 17-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Changing the Physical-Log Location and Size . . . . . . . . . . . . . . . . . . . . . . . 17-1
Preparing to Make the Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Checking For Adequate Contiguous Space . . . . . . . . . . . . . . . . . . . . . . . 17-2
Using a Text Editor to Change Physical-Log Location or Size . . . . . . . . . . . . . . . . . 17-2
Using onparams to Change Physical-Log Location or Size . . . . . . . . . . . . . . . . . . 17-2
Using ON-Monitor to Change Physical-Log Location or Size (UNIX). . . . . . . . . . . . . . . 17-3
Monitoring Physical and Logical-Logging Activity . . . . . . . . . . . . . . . . . . . . . . 17-3
Monitoring Checkpoint Information . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4

xii IBM Informix Dynamic Server Administrator’s Guide

 Forcing a Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
Forcing a Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6

Part 4. Fault Tolerance

Chapter 18. Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Benefits of Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Costs of Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Consequences of Not Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Data to Mirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Alternatives to Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Mirroring Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Creation of a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Mirror Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Actions During Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Result of Stopping Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6
Structure of a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6

Chapter 19. Using Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Preparing to Mirror Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Enabling the MIRROR Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . 19-2
Changing the MIRROR Parameter with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 19-2
Allocating Disk Space for Mirrored Data . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Linking Chunks (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Relinking a Chunk to a Device After a Disk Failure . . . . . . . . . . . . . . . . . . . . 19-3
Using Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Mirroring the Root Dbspace During Initialization . . . . . . . . . . . . . . . . . . . . . 19-4
Changing the Mirror Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Managing Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Starting Mirroring for Unmirrored Storage Spaces . . . . . . . . . . . . . . . . . . . . . 19-4
Starting Mirroring for New Storage Spaces . . . . . . . . . . . . . . . . . . . . . . . 19-5
Adding Mirror Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Taking Down a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Recovering a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Ending Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) . . . 20-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
High-Availability Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
HDR Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Type of Data Replicated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Advantages of Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
How HDR Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
How Data Initially Replicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
Reproduction of Updates to the Primary Database Server . . . . . . . . . . . . . . . . . . 20-6
Threads That Handle HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9
Checkpoints Between Database Servers . . . . . . . . . . . . . . . . . . . . . . . . 20-10
How Data Synchronization Is Tracked . . . . . . . . . . . . . . . . . . . . . . . . 20-10
HDR Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
HDR Failures Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Detection of HDR Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11
Actions When an HDR Failure Is Detected . . . . . . . . . . . . . . . . . . . . . . . 20-11
Considerations After HDR Failure . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11
Redirection and Connectivity for Data-Replication Clients . . . . . . . . . . . . . . . . . . . 20-14
Designing Clients for Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . 20-14

Contents xiii
 Directing Clients Automatically with DBPATH . . . . . . . . . . . . . . . . . . . . . 20-14
Directing Clients with the Connectivity Information . . . . . . . . . . . . . . . . . . . . 20-15
Directing Clients with INFORMIXSERVER . . . . . . . . . . . . . . . . . . . . . . . 20-18
Handling Redirection Within an Application . . . . . . . . . . . . . . . . . . . . . . 20-19
Comparing Different Redirection Mechanisms . . . . . . . . . . . . . . . . . . . . . . 20-20
Designing HDR Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20
Setting Lock Mode to Wait for Access to Primary Database Server . . . . . . . . . . . . . . . 20-20
Designing Clients to Use the Secondary Database Server . . . . . . . . . . . . . . . . . . 20-21

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Planning for HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Configuring a System for HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Meeting Hardware and Operating-System Requirements . . . . . . . . . . . . . . . . . . . 21-2
Meeting Database and Data Requirements . . . . . . . . . . . . . . . . . . . . . . . 21-3
Meeting Database Server Configuration Requirements . . . . . . . . . . . . . . . . . . . 21-3
Configuring HDR Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5
Starting HDR for the First Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6
Decreasing Setup Time Through an Alternate Backup Method . . . . . . . . . . . . . . . . . 21-9
Performing Basic Administration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Changing Database Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . 21-9
Backing Up Storage Spaces and Logical-Log Files . . . . . . . . . . . . . . . . . . . . . 21-9
Changing the Logging Mode of Databases . . . . . . . . . . . . . . . . . . . . . . . 21-10
Adding and Dropping Chunks and Storage Spaces . . . . . . . . . . . . . . . . . . . . 21-10
Renaming Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Saving Chunk Status on the Secondary Database Server . . . . . . . . . . . . . . . . . . 21-11
Using and Changing Mirroring of Chunks . . . . . . . . . . . . . . . . . . . . . . . 21-11
Managing the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing Virtual Processors. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Replicating an Index to the Secondary Database Server . . . . . . . . . . . . . . . . . . . 21-12
Changing the Database Server Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 21-13
Changing the Database Server Type . . . . . . . . . . . . . . . . . . . . . . . . . . 21-14
Monitoring HDR Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Using Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Restoring Data After Media Failure Occurs . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Restoring After a Media Failure on the Primary Database Server . . . . . . . . . . . . . . . 21-16
Restoring After a Media Failure on the Secondary Database Server . . . . . . . . . . . . . . . 21-17
Replicating An Index to the Secondary Server . . . . . . . . . . . . . . . . . . . . . . . 21-18
Restarting HDR After a Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-18
Restarting After Critical Data Is Damaged . . . . . . . . . . . . . . . . . . . . . . . 21-18
Restarting If Critical Data Is Not Damaged . . . . . . . . . . . . . . . . . . . . . . . 21-20

Chapter 22. Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . 22-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Performing Periodic Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Verifying Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Monitoring for Data Inconsistency . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Retaining Consistent Level-0 Backups . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Dealing with Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Finding Symptoms of Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Fixing Index Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Fixing I/O Errors on a Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Collecting Diagnostic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-6
Disabling I/O Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7
Monitoring the Database Server for Disabling I/O Errors . . . . . . . . . . . . . . . . . . . 22-8
Using the Message Log to Monitor Disabling I/O Errors . . . . . . . . . . . . . . . . . . 22-8

xiv IBM Informix Dynamic Server Administrator’s Guide

 Using Event Alarms to Monitor Disabling I/O Errors . . . . . . . . . . . . . . . . . . . . 22-8
Using No Bad-Sector Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9

Part 5. Distributed Data

Chapter 23. Multiphase Commit Protocols . . . . . . . . . . . . . . . . . . . . 23-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Transaction Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Using the TP/XA Library With a Transaction Manager . . . . . . . . . . . . . . . . . . . 23-2
Using Microsoft Transaction Server (MTS/XA) . . . . . . . . . . . . . . . . . . . . . . 23-2
3 Using Dynamic Server Transaction Support for XA-Compliant, External Data Sources . . . . . . . . . 23-3
Using Loosely-Coupled and Tightly-Coupled Modes . . . . . . . . . . . . . . . . . . . . 23-4
Two-Phase Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
When the Two-Phase Commit Protocol Is Used . . . . . . . . . . . . . . . . . . . . . . 23-5
Two-Phase Commit Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Phases of the Two-Phase Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . 23-6
How the Two-Phase Commit Protocol Handles Failures . . . . . . . . . . . . . . . . . . . 23-7
Presumed-End Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Independent Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Situations That Initiate Independent Action . . . . . . . . . . . . . . . . . . . . . . . 23-8
Possible Results of Independent Action . . . . . . . . . . . . . . . . . . . . . . . . 23-9
The Heuristic Rollback Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
The Heuristic End-Transaction Scenario . . . . . . . . . . . . . . . . . . . . . . . . 23-12
Monitoring a Global Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14
Two-Phase Commit Protocol Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15
Two-Phase Commit and Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . 23-15
Logical-Log Records When the Transaction Commits . . . . . . . . . . . . . . . . . . . 23-15
Logical-Log Records Written During a Heuristic Rollback . . . . . . . . . . . . . . . . . . 23-17
Logical-Log Records Written After a Heuristic End Transaction . . . . . . . . . . . . . . . . 23-18
Configuration Parameters Used in Two-Phase Commits . . . . . . . . . . . . . . . . . . . 23-19
Function of the DEADLOCK_TIMEOUT Parameter . . . . . . . . . . . . . . . . . . . . 23-20
Function of the TXTIMEOUT Parameter . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Heterogeneous Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Gateways That Can Participate in a Heterogeneous Commit Transaction . . . . . . . . . . . . . 23-21
Enabling and Disabling of Heterogeneous Commit . . . . . . . . . . . . . . . . . . . . 23-21
How Heterogeneous Commit Works . . . . . . . . . . . . . . . . . . . . . . . . . 23-22
Implications of a Failed Heterogeneous Commit . . . . . . . . . . . . . . . . . . . . . 23-23

Chapter 24. Recovering Manually from Failed Two-Phase Commit . . . . . . . . . 24-1

In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1
Determining If Manual Recovery Is Required . . . . . . . . . . . . . . . . . . . . . . . 24-1
Determining If a Transaction Was Implemented Inconsistently . . . . . . . . . . . . . . . . . 24-1
Determining If the Distributed Database Contains Inconsistent Data . . . . . . . . . . . . . . . 24-2
Deciding If Action Is Needed to Correct the Situation. . . . . . . . . . . . . . . . . . . . 24-4
Example of Manual Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5

Part 6. Appendixes

Appendix. Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1

Contents xv
xvi IBM Informix Dynamic Server Administrator’s Guide
Introduction
In This Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Types of Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Software Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Assumptions About Your Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Demonstration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
New Features in Dynamic Server, Version 10.0 . . . . . . . . . . . . . . . . . . . . . . . xix
Database Server Security and Usability Enhancements . . . . . . . . . . . . . . . . . . . . xix
New Features in Previous Versions of Dynamic Server . . . . . . . . . . . . . . . . . . . . . xxi
Features in Dynamic Server, Version 9.4. . . . . . . . . . . . . . . . . . . . . . . . . xxi
Database Server Usability Enhancements . . . . . . . . . . . . . . . . . . . . . . . xxi
Security Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Features in Dynamic Server, Version 9.3 . . . . . . . . . . . . . . . . . . . . . . . . xxii
Performance Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
SQL Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Other Significant Changes in Version 9.3 . . . . . . . . . . . . . . . . . . . . . . . xxiii
Features in Dynamic Server, Version 9.21 . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Organizational Changes to This Manual In Version 9.2 . . . . . . . . . . . . . . . . . . . xxiii
Documentation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Feature, Product, and Platform Markup . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
How to Read a Command-Line Syntax Diagram . . . . . . . . . . . . . . . . . . . . xxvi
Keywords and Punctuation . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Identifiers and Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Example Code Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
Additional Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
IBM Informix Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Installation Guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Online Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviii
Locating Online Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Online Notes Filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Informix Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Online Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx
Printed Manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi
IBM Informix Dynamic Server Version 10.0 and CSDK Version 2.90 Documentation Set . . . . . . . . . xxxi
Compliance with Industry Standards . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii
IBM Welcomes Your Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiii

In This Introduction
This introduction provides an overview of the information in this manual and
describes the conventions it uses.

About This Manual

This manual describes concepts and procedures for configuring, administering, and
using IBM Informix Dynamic Server or IBM Informix Dynamic Server with
J/Foundation.

© Copyright IBM Corp. 1996, 2005 xvii

 A companion volume, the IBM Informix Dynamic Server Administrator's Reference,
contains reference material for using Informix database servers. If you need to tune
the performance of your database server and SQL queries, see your IBM Informix
Dynamic Server Performance Guide.

This section discusses the organization of the manual, the intended audience, and
the associated software products that you must have to use the database server.

Types of Users
This manual is written for the following users:
v Database users
v Database administrators
v Database server administrators
v Performance engineers
v Programmers in the following categories
– Application developers
– DataBlade module developers
– Authors of user-defined routines

This manual is written with the assumption that you have the following
background:
v A working knowledge of your computer, your operating system, and the utilities
that your operating system provides
v Some experience working with relational databases or exposure to database
concepts
v Some experience with computer programming
v Some experience with database server administration, operating-system
administration, or network administration

If you have limited experience with relational databases, SQL, or your operating
system, see the IBM Informix Dynamic Server Getting Started Guide for your database
server for a list of supplementary titles.

Software Dependencies
This manual is written with the assumption that you are using IBM Informix
Dynamic Server Version 10.0 as your database server.

Assumptions About Your Locale

IBM Informix products can support many languages, cultures, and code sets. All
the information related to character set, collation, and representation of numeric
data, currency, date, and time is brought together in a single environment, called a
Global Language Support (GLS) locale.

The examples in this manual are written with the assumption that you are using
the default locale, en_us.8859-1. This locale supports U.S. English format
conventions for date, time, and currency. In addition, this locale supports the ISO
8859-1 code set, which includes the ASCII code set plus many 8-bit characters such
as é, è, and ñ.

xviii IBM Informix Dynamic Server Administrator’s Guide

 If you plan to use nondefault characters in your data or your SQL identifiers, or if
you want to conform to the nondefault collation rules of character data, you need
to specify the appropriate nondefault locale.

For instructions on how to specify a nondefault locale, additional syntax, and other
considerations related to GLS locales, see the IBM Informix GLS User's Guide.

Demonstration Database
The DB–Access utility, which is provided with your Informix database server
products, includes one or more of the following demonstration databases:
v The stores_demo database illustrates a relational schema with information about
a fictitious wholesale sporting-goods distributor. Many examples in IBM
Informix manuals are based on the stores_demo database.
v The superstores_demo database illustrates an object-relational schema. The
superstores_demo database contains examples of extended data types, type and
table inheritance, and user-defined routines.

For information about how to create and populate the demonstration databases,
see the IBM Informix DB–Access User's Guide. For descriptions of the databases and
their contents, see the IBM Informix Guide to SQL: Reference.

The scripts that you use to install the demonstration databases reside in the
$INFORMIXDIR/bin directory on UNIX and in the %INFORMIXDIR%\bin
directory on Windows.

New Features in Dynamic Server, Version 10.0

The following table provides information about the new features for IBM Informix
Dynamic Server, Version 10.0, which this manual covers. For a description of all
new features, see the IBM Informix Getting Started Guide.

Database Server Security and Usability Enhancements

Version 10.0 includes new features that enhance the functionality of the database
server and make it easier to use.

New Features Reference

A new Security chapter that contains information on new Chapter 5, “Security”
security-related features. In addition, information on
Communication Support Modules (CSMs) was moved from
Chapter 3 to Chapter 5, the new Security chapter.

Chapters 5 through 23 that existed in previous versions of

the guide have been renumbered to 6 through 24.
3 A new configuration parameter used to give specified users “Setting Permission to Create Databases” on page 5-6
3 permission to create databases and thus prevent other users
3 from creating databases
3 If this parameter is not set, any user can create a database.
3 New AES ciphers to use when encrypting network data “Configuring Network Data Encryption” on page 5-12
Functionality for most server utilities on UNIX or Linux to “Server Utility Security Before Starting on UNIX and
check for a secure environment before contacting the Linux” on page 5-2
database server (or, starting the database server when using
the oninit utility)

Introduction xix
 New Features Reference
A new default role that you can assign to individual users “User Roles” on page 5-6
or to the PUBLIC group for a particular database. The
default role is automatically applied when a user establishes
a connection with the database.
3 New configuration parameters that you can use on UNIX, “Limiting Denial-of-Service Flood Attacks” on page 5-7
3 Linux, and Windows platforms to reduce the incomplete
3 connection timeout period and restrict the number of
3 incomplete requests for connections, thus reducing the risk
3 of a hostile, denial-of-service (DOS) flood attack
Options for implementing column-level encryption, as well “Encryption” on page 5-8
as password and data-transmission encryption
A configuration parameter that a database server security “Security for External Routines (UDRs)” on page 5-32
administrator can use to restrict the users who can register
an external routine
A new event-alarm parameter to use if you want the “Event-Alarm Parameters” on page 2-9
event-alarm program to operate for all events that are
logged in the MSGPATH, not just noteworthy events
Rename-dbspace functionality “Renaming Dbspaces” on page 11-17
Single-user mode, a new database server mode to use when “Database Server Operating Modes” on page 4-7 and
performing maintenance tasks involving the execution of “Changing Database Server Operating Modes” on page
SQL and DDL statements 4-8
The DRAUTO configuration parameter to use to automate “Actions When an HDR Failure Is Detected” on page
switching High-Availability Data Replication database 20-11, “Actions to Take If the Primary Database Server
servers if the primary server fails Fails” on page 20-12, “Changing the Database Server
Mode” on page 21-13, “Critical Media Failure on the
Primary Database Server” on page 21-18, and “The
Secondary Database Server Is Changed to a Standard
Database Server Automatically” on page 21-21
External back up and restore functionality to use when “Starting HDR for the First Time” on page 21-6
setting up HDR
Two configuration parameters that enable the database “Alternative Fast Restart Recovery Options for Fuzzy
server to perform physical logging on fuzzy checkpoints Operations” on page 16-17
during the roll-forward phase of recovery, thus reducing the
time required for recovery
The DS_NONPDQ_QUERY_MEM configuration parameter “Size of the Virtual Portion of Shared Memory” on
to use to increase the amount of sort memory that is page 8-14 and the IBM Informix Dynamic Server
available for a query that is not a Parallel Database Query Performance Guide
(PDQ)
Functionality for either manually or automatically “Replicating An Index to the Secondary Server” on
replicating a High-Availability Data Replication (HDR) page 21-18
index to the secondary server when an index on the
secondary server becomes corrupt
Functionality for creating multiple partitions of a table or “Managing Dbspace Partitions” on page 11-18
index within a single dbspace for fragmented tables that use
expression-based or round-robin distribution schemes
New configuration parameters and onspaces options for “Specifying the First and Next Extent Sizes for the
specifying the first and next extent sizes for the tblspace tblspace tblspace” on page 11-10
tblspace in the dbspace

xx IBM Informix Dynamic Server Administrator’s Guide

 New Features Reference
Functionality for specifying the page size for a standard or “Creating a Dbspace with a Non-Default Page Size” on
temporary dbspace when you create the dbspace and the page 11-11
BUFFERPOOL configuration parameter to use for defining a
buffer pool

Information that was specified with the BUFFERS, LRUS,

LRU_MAX_DIRTY, and LRU_MIN_DIRTY configuration
parameters prior to Version 10.0 should now be specified
using the BUFFERPOOL configuration parameter.
Functionality for changing the name of a database server “Using the Instance Manager to Rename a Database
instance Server Instance (Windows)” on page 1-13
3 Transaction support for XA-compliant, external data sources “Using Dynamic Server Transaction Support for
XA-Compliant, External Data Sources” on page 23-3
3 A configuration parameter that allows you to remove the “Enabling non-DBAs to View SQL Statements a Session
3 restriction that only DBA users can execute certain onstat Is Executing” on page 5-33
3 commands
4 IPv6 support, including automatic discovery of whether or “Dynamic Server Support for IPv6 Addresses” on page
4 not a platform supports IPv6 3-28
4 Functionality for specifying a comma-separated list of valid “Security for Loading External Modules” on page 5-32
4 directory prefix locations from which the database server
4 can load external modules

Important: HDR is available with the standard version of Dynamic Server. HDR
does not work with the IBM Informix Dynamic Server Express Edition.

New Features in Previous Versions of Dynamic Server

Features in Dynamic Server, Version 9.4

The following table provides information about the new features for IBM Informix
Dynamic Server, Version 9.4, which this manual covers. For a description of all
new features, see the IBM Informix Dynamic Server Getting Started Guide.

Database Server Usability Enhancements

Version 9.4 includes new features that make the database server easier to install,
use, and manage.

New Features Reference

The ability to clean buffers faster because of acceptance of “Number of Pages Added to the MLRU Queues” on
decimals in the LRU configuration parameters. page 8-24.
The ability to send email and pagermail notifications of “Event-Alarm Parameters” on page 2-9.
alarm events and degree of severity.
“Appendix C: Event Alarms” in the Administrator’s
Reference

Introduction xxi
New Features Reference
The ability to use chunks and extents to a maximum size of “Using Large Chunks” on page 1-5.
4 terabytes.
“Creating Storage Spaces and Chunks” on page 1-16.

“Supporting Large Chunks” on page 1-16.

“Chunks” on page 10-3.

“Sample Layout When Performance Is Highest

Priority” on page 10-36.

“Sample Disk Layouts” on page 10-35.

The ability to use a maximum of 32,766 allowable chunks. “Specifying the Maximum Number of Chunks and
Storage Spaces” on page 11-8.
The ability of HDR to replicate extended types “Type of Data Replicated” on page 20-3.

Security Enhancements
Version 9.4 adds the encryption communication support module (ENCCSM), which
enables you to encrypt data transmissions over the network. This option provides
complete data encryption with the OpenSSL library, with many configurable
options.

New Features Reference

Encryption of data transmissions over the network “Using Communication Support Modules (CSMs) for
Password and Data Transmission Encryption” on page
5-9

This product includes software developed by the OpenSSL Project for use in the
OpenSSL Toolkit ([Link]

Features in Dynamic Server, Version 9.3

The following features were introduced in IBM Informix Dynamic Server, Version
9.3.

Performance Enhancements
Version 9.3 includes many new features that help you monitor and improve the
performance of your database.

New Features Reference

The onstat -g stm option “Monitoring Transactions” on page 13-5
Dynamic addition of logical logs Chapter 14, “Logical Log,” on page 14-1

Chapter 15, “Managing Logical-Log Files,” on page 15-1

SQL Enhancements
Version 9.3 includes several new SQL statements that ease migration from
non-Informix databases to Dynamic Server, Version 9.4.

New Features Reference

Configurable default lock modes “Lock Table” on page 8-13

xxii IBM Informix Dynamic Server Administrator’s Guide

 Other Significant Changes in Version 9.3
The following lists other significant Version 9.3 changes to this guide.

Changes to the Manual Reference

IBM Informix Server Administrator (ISA) has many new ISA online help
features.
Use the VPCLASS configuration parameter instead of the Chapter 7, “Managing Virtual Processors,” on page 7-1
AFF_NPROCS, AFF_SPROC, NOAGE, NUMAIOVPS, and
NUMCPUVPS configuration parameters.

Features in Dynamic Server, Version 9.21

These features were introduced in IBM Informix Dynamic Server, Version 9.21.

Features Reference
Nonlogging (RAW) tables “Table Types for Dynamic Server” on page 10-23
onpladm utility “Loading Data Into a Table” on page 11-44
SQL statement cache enhancements: “Setting SQL Statement Cache Parameters” on page 9-6
v new configuration parameters
v new onstat -g ssc options
v new onmode -W options for changing SQL statement
cache parameters

Organizational Changes to This Manual In Version 9.2

This guide was reorganized as follows:
v The information on configuring the database server and overview of
administration tasks is in Chapter 1, “Installing and Configuring the Database
Server,” on page 1-1.
v The information on multiple residency and high availability on Windows has
been moved to the IBM Informix Installation Guide.
v The information on managing database server operating modes and initializing
the database server is in Chapter 4, “Initializing the Database Server,” on page
4-1.
v The information on the physical log and checkpoints is in Chapter 16, “Physical
Logging, Checkpoints, and Fast Recovery,” on page 16-1.

Documentation Conventions
This section describes the conventions that this manual uses. These conventions
make it easier to gather information from this and other volumes in the
documentation set.

The following conventions are discussed:

v Typographical conventions
v Other conventions
v Syntax diagrams
v Command-line conventions
v Example code conventions

Introduction xxiii
 Typographical Conventions
This manual uses the following conventions to introduce new terms, illustrate
screen displays, describe command syntax, and so forth.

Convention Meaning
KEYWORD Keywords of SQL, SPL, and some other programming languages appear
in uppercase letters in a serif font.
italics Within text, new terms and emphasized words appear in italics. Within
syntax and code examples, variable values that you are to specify
appear in italics.
boldface Names of program entities (such as classes, events, and tables),
environment variables, file and pathnames, and interface elements (such
as icons, menu items, and buttons) appear in boldface.
monospace Information that the product displays and information that you enter
appear in a monospace typeface.
KEYSTROKE Keys that you are to press appear in uppercase letters in a sans serif
font.
> This symbol indicates a menu item. For example, “Choose Tools >
Options” means choose the Options item from the Tools menu.

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”
the text or to “press” other keys, no RETURN is required.

Feature, Product, and Platform Markup

Feature, product, and platform markup identifies paragraphs that contain
feature-specific, product-specific, or platform-specific information. Some examples
of this markup follow:

Dynamic Server

Identifies information that is specific to IBM Informix Dynamic Server

End of Dynamic Server

Windows Only

Identifies information that is specific to the Windows environment

End of Windows Only

This markup can apply to one or more paragraphs within a section. When an
entire section applies to a particular product or platform, this is noted as part of
the heading text, for example:
Table Sorting (Linux)

Syntax Diagrams
This guide uses syntax diagrams built with the following components to describe
the syntax for statements and all commands other than system-level commands.

Syntax diagrams depicting SQL and command-line statements have changed in the
following ways:

xxiv IBM Informix Dynamic Server Administrator’s Guide

 v The symbols at the beginning and end of statements are double arrows.
v The symbols at the beginning and end of syntax segment diagrams are vertical
lines.
v How many times a loop can be repeated is explained in a diagram footnote,
whose marker appears above the path that is describes.
v Syntax statements that are longer than one line continue on the next line.
v Product or condition-specific paths are explained in diagram footnotes, whose
markers appear above the path that they describe.
v Cross-references to the descriptions of other syntax segments appear as diagram
footnotes, whose markers immediately follow the name of the segment that they
reference.

The following table describes syntax diagram components.

Component represented in PDF Component represented in HTML Meaning

>>---------------------- Statement begins.

-----------------------> Statement continues on next

line.

>----------------------- Statement continues from

previous line.
----------------------->< Statement ends.

--------SELECT---------- Required item.

--+-----------------+--- Optional item.

’------LOCAL------’

---+-----ALL-------+--- Required item with choice.

+--DISTINCT-----+ One and only one item must
’---UNIQUE------’ be present.

---+------------------+--- Optional items with choice

+--FOR UPDATE-----+ are shown below the main
’--FOR READ ONLY--’ line, one of which you might
specify.
.---NEXT---------. The values below the main
----+----------------+--- line are optional, one of
+---PRIOR--------+ which you might specify. If
’---PREVIOUS-----’ you do not specify an item,
the value above the line will
be used as the default.
.-------,-----------. Optional items. Several items
V | are allowed; a comma must
---+-----------------+--- precede each repetition.
+---index_name---+
’---table_name---’

>>-| Table Reference |->< Reference to a syntax

segment.

Introduction xxv
Component represented in PDF Component represented in HTML Meaning
Table Reference Syntax segment.
|--+-----view--------+--|
+------table------+
’----synonym------’

How to Read a Command-Line Syntax Diagram

The following command-line syntax diagram uses some of the elements listed in
the table in the previous section.

Creating a No-Conversion Job

onpladm create job job -n -d device -D database

-p project

-t table



(1)
Setting the Run Mode
-S server -T target

Notes:
1 See page Z-1

The second line in this diagram has a segment named “Setting the Run Mode,”
which according to the diagram footnote, is on page Z-1. If this was an actual
cross-reference, you would find this segment in on the first page of Appendix Z.
Instead, this segment is shown in the following segment diagram. Notice that the
diagram uses segment start and end components.

Setting the Run Mode:

l
c
-f
d u n N
p
a

To see how to construct a command correctly, start at the top left of the main
diagram. Follow the diagram to the right, including the elements that you want.
The elements in this diagram are case sensitive because the illustrates utility
syntax. Other types of syntax, such as SQL, are not case sensitive.

The Creating a No-Conversion Job diagram illustrates the following steps:

xxvi IBM Informix Dynamic Server Administrator’s Guide

 1. Type onpladm create job and then the name of the job.
2. Optionally, type -p and then the name of the project.
3. Type the following required elements:
v -n
v -d and the name of the device
v -D and the name of the database
v -t and the name of the table
4. Optionally, you can choose one or more of the following elements and repeat
them an arbitrary number of times:
v -S and the server name
v -T and the target server name
v The run mode. To set the run mode, follow the Setting the Run Mode
segment diagram to type -f, optionally type d, p, or a, and then optionally
type l or u.
5. Follow the diagram to the terminator.

Your diagram is complete.

Keywords and Punctuation

Keywords are words reserved for statements and all commands except
system-level commands. When a keyword appears in a syntax diagram, it is
shown in uppercase letters. When you use a keyword in a command, you can
write it in uppercase or lowercase letters, but you must spell the keyword exactly
as it appears in the syntax diagram.

You must also use any punctuation in your statements and commands exactly as
shown in the syntax diagrams.

Identifiers and Names

Variables serve as placeholders for identifiers and names in the syntax diagrams
and examples. You can replace a variable with an arbitrary name, identifier, or
literal, depending on the context. Variables are also used to represent complex
syntax elements that are expanded in additional syntax diagrams. When a variable
appears in a syntax diagram, an example, or text, it is shown in lowercase italic.

The following syntax diagram uses variables to illustrate the general form of a
simple SELECT statement.

SELECT column_name FROM table_name


When you write a SELECT statement of this form, you replace the variables
column_name and table_name with the name of a specific column and table.

Example Code Conventions

Examples of SQL code occur throughout this manual. Except as noted, the code is
not specific to any single IBM Informix application development tool.

If only SQL statements are listed in the example, they are not delimited by
semicolons. For instance, you might see the code in the following example:
CONNECT TO stores_demo
...

Introduction xxvii
 DELETE FROM customer
WHERE customer_num = 121
...

COMMIT WORK
DISCONNECT CURRENT

To use this SQL code for a specific product, you must apply the syntax rules for
that product. For example, if you are using DB–Access, you must delimit multiple
statements with semicolons. If you are using an SQL API, you must use EXEC SQL
at the start of each statement and a semicolon (or other appropriate delimiter) at
the end of the statement.

Tip: Ellipsis points in a code example indicate that more code would be added in
a full application, but it is not necessary to show it to describe the concept
being discussed.

For detailed directions on using SQL statements for a particular application

development tool or SQL API, see the manual for your product.

Additional Documentation
For additional information, refer to the following types of documentation:
v Installation guides
v Online notes
v Informix error messages
v Manuals
v Online help

IBM Informix Information Center

The Informix Dynamic Server Information Center integrates the entire IBM
Informix Dynamic Server 10.0 and IBM Informix Client SDK (CSDK) 2.90
documentation sets in both HTML and PDF formats. The Information Center
provides full text search, a master index, logical categories, easy navigation, and
links to troubleshooting and support files.

The IBM Informix Information Center site is located at

[Link]

Installation Guides
Installation guides are located in the /doc directory of the product CD or in the
/doc directory of the product‘s compressed file if you downloaded it from the IBM
Web site. Alternatively, you can obtain installation guides from the IBM Informix
Online Documentation site at
[Link] or the IBM Informix
Information Center at
[Link]

Online Notes
The following sections describe the online files that supplement the information in
this manual. Please examine these files before you begin using your IBM Informix
product. They contain vital information about application and performance issues.

xxviii IBM Informix Dynamic Server Administrator’s Guide

Online File Description Format
TOC Notes The TOC (Table of Contents) notes file provides HTML
a comprehensive directory of hyperlinks to the
release notes, the fixed and known defects file,
and all the documentation notes files for
individual manual titles.
Documentation Notes The documentation notes file for each manual HTML, text
contains important information and corrections
that supplement the information in the manual
or information that was modified since
publication.
Release Notes The release notes file describes feature HTML, text
differences from earlier versions of IBM
Informix products and how these differences
might affect current products. For some
products, this file also contains information
about any known problems and their
workarounds.
Machine Notes (Non-Windows platforms only) The machine text
notes file describes any platform-specific actions
that you must take to configure and use IBM
Informix products on your computer.
Fixed and Known This text file lists issues that have been text
Defects File identified with the current version. It also lists
customer-reported defects that have been fixed
in both the current version and in previous
versions.

Locating Online Notes

Online notes are available from the IBM Informix Online Documentation site at
[Link] and in the IBM
Informix Information Center at
[Link] Additionally you
can locate these files before or after installation as described below.

Before Installation

All online notes are located in the /doc directory of the product CD. The easiest
way to access the documentation notes, the release notes, and the fixed and known
defects file is through the hyperlinks from the TOC notes file.

The machine notes file and the fixed and known defects file are only provided in
text format.

After Installation

On UNIX platforms in the default locale, the documentation notes, release notes,
and machine notes files appear under the $INFORMIXDIR/release/en_us/0333
directory.

Dynamic Server

On Windows the documentation and release notes files appear in the Informix
folder. To display this folder, choose Start > Programs > IBM product name
version > Documentation Notes or Release Notes from the taskbar.

Introduction xxix
 Machine notes do not apply to Windows platforms.
End of Dynamic Server

Online Notes Filenames

Online notes have the following file formats:

Online File File Format Examples

TOC Notes prod_os_toc_version.html ids_win_toc_10.[Link]
Documentation Notes prod_bookname_docnotes_version.html/txt ids_hpl_docnotes_10.[Link]
Release Notes prod_os_relnotes_version.html/txt ids_unix_relnotes_10.[Link]
Machine Notes prod_machine_notes_version.txt ids_machine_notes_10.[Link]
Fixed and Known prod_defects_version.txt ids_defects_10.[Link]
Defects File client_defects_2.[Link]

ids_win_fixed_and_known ids_win_fixed_and_known
_defects_version.txt _defects_10.[Link]

Informix Error Messages

This file is a comprehensive index of error messages and their corrective actions for
the Informix products and version numbers.

On UNIX platforms, use the finderr command to read the error messages and their
corrective actions.

Dynamic Server

On Windows, use the Informix Error Messages utility to read error messages and
their corrective actions. To display this utility, choose Start > Programs > IBM
product name version > Informix Error Messages from the taskbar.
End of Dynamic Server

You can also access these files from the IBM Informix Online Documentation site at
[Link] or in the IBM
Informix Information Center at
[Link]

Manuals
Online Manuals
A CD that contains your manuals in electronic format is provided with your IBM
Informix products. You can install the documentation or access it directly from the
CD. For information about how to install, read, and print online manuals, see the
installation insert that accompanies your CD. You can also obtain the same online
manuals from the IBM Informix Online Documentation site at
[Link] or in the IBM
Informix Information Center at
[Link]

xxx IBM Informix Dynamic Server Administrator’s Guide

 Printed Manuals
To order hardcopy manuals, contact your sales representative or visit the IBM
Publications Center Web site at
[Link]

Online Help
IBM Informix online help, provided with each graphical user interface (GUI),
displays information about those interfaces and the functions that they perform.
Use the help facilities that each GUI provides to display the online help.

Accessibility
IBM is committed to making our documentation accessible to persons with
disabilities. Our books are available in HTML format so that they can be accessed
with assistive technology such as screen reader software. The syntax diagrams in
our manuals are available in dotted decimal format, which is an accessible format
that is available only if you are using a screen reader. For more information about
the dotted decimal format, see the Accessibility appendix.

IBM Informix Dynamic Server Version 10.0 and CSDK Version 2.90
Documentation Set
The following tables list the manuals that are part of the IBM Informix Dynamic
Server, Version 10.0 and the CSDK Version 2.90, documentation set. PDF and
HTML versions of these manuals are available at
[Link] or in the IBM
Informix Information Center at
[Link] You can order
hardcopy versions of these manuals from the IBM Publications Center at
[Link]
Table 1. Database Server Manuals
Manual Subject
Administrator’s Guide Understanding, configuring, and administering your database server.
Administrator’s Reference Reference material for Informix Dynamic Server, such as the syntax of database
server utilities onmode and onstat, and descriptions of configuration parameters,
the sysmaster tables, and logical-log records.
Backup and Restore Guide The concepts and methods you need to understand when you use the ON-Bar
and ontape utilities to back up and restore data.
Built-In DataBlade Modules Using the following DataBlade modules that are included with Dynamic Server:
User’s Guide v MQ DataBlade module, to allow IBM Informix database applications to
communicate with other MQSeries applications.
v Large Object Locator, a foundation DataBlade module that can be used by other
modules that create or store large-object data.
DB-Access User’s Guide Using the DB-Access utility to access, modify, and retrieve data from Informix
databases.
DataBlade API The DataBlade API functions and the subset of ESQL/C functions that the
Function Reference DataBlade API supports. You can use the DataBlade API to develop client LIBMI
applications and C user-defined routines that access data in Informix databases.
DataBlade API The DataBlade API, which is the C-language application-programming interface
Programmer’s Guide provided with Dynamic Server. You use the DataBlade API to develop client and
server applications that access data stored in Informix databases.

Introduction xxxi
Table 1. Database Server Manuals (continued)
Manual Subject
Database Design and Designing, implementing, and managing your Informix databases.
Implementation Guide
Enterprise Replication Guide How to design, implement, and manage an Enterprise Replication system to
replicate data between multiple database servers.
Error Messages file Causes and solutions for numbered error messages you might receive when you
work with IBM Informix products.
Getting Started Guide Describes the products bundled with IBM Informix Dynamic Server and
interoperability with other IBM products. Summarizes important features of
Dynamic Server and the new features for each version.
Guide to SQL: Reference Information about Informix databases, data types, system catalog tables,
environment variables, and the stores_demo demonstration database.
Guide to SQL: Syntax Detailed descriptions of the syntax for all Informix SQL and SPL statements.
Guide to SQL: Tutorial A tutorial on SQL, as implemented by Informix products, that describes the basic
ideas and terms that are used when you work with a relational database.
High-Performance Loader Accessing and using the High-Performance Loader (HPL), to load and unload
User’s Guide large quantities of data to and from Informix databases.
Installation Guide for Instructions for installing IBM Informix Dynamic Server on Windows.
Microsoft Windows
Installation Guide for Instructions for installing IBM Informix Dynamic Server on UNIX and Linux.
UNIX and Linux
J/Foundation Developer’s Writing user-defined routines (UDRs) in the Java programming language for
Guide Informix Dynamic Server with J/Foundation.
Migration Guide Conversion to and reversion from the latest versions of Informix database servers.
Migration between different Informix database servers.
Optical Subsystem Guide The Optical Subsystem, a utility that supports the storage of BYTE and TEXT data
on optical disk.
Performance Guide Configuring and operating IBM Informix Dynamic Server to achieve optimum
performance.
R-Tree Index User’s Guide Creating R-tree indexes on appropriate data types, creating new operator classes
that use the R-tree access method, and managing databases that use the R-tree
secondary access method.
SNMP Subagent Guide The IBM Informix subagent that allows a Simple Network Management Protocol
(SNMP) network manager to monitor the status of Informix servers.
Storage Manager Informix Storage Manager (ISM), which manages storage devices and media for
Administrator’s Guide your Informix database server.
Trusted Facility Guide The secure-auditing capabilities of Dynamic Server, including the creation and
maintenance of audit logs.
User-Defined Routines and How to define new data types and enable user-defined routines (UDRs) to extend
Data Types Developer’s Guide IBM Informix Dynamic Server.
Virtual-Index Interface Creating a secondary access method (index) with the Virtual-Index Interface (VII)
Programmer’s Guide to extend the built-in indexing schemes of IBM Informix Dynamic Server.
Typically used with a DataBlade module.
Virtual-Table Interface Creating a primary access method with the Virtual-Table Interface (VTI) so that
Programmer’s Guide users have a single SQL interface to Informix tables and to data that does not
conform to the storage scheme of Informix Dynamic Server.

xxxii IBM Informix Dynamic Server Administrator’s Guide

Table 2. Client/Connectivity Manuals
Manual Subject
Client Products Installation Installing IBM Informix Client Software Developer’s Kit (Client SDK) and IBM
Guide Informix Connect on computers that use UNIX, Linux, and Windows.
Embedded SQLJ User’s Guide Using IBM Informix Embedded SQLJ to embed SQL statements in Java programs.
ESQL/C Programmer’s Manual The IBM Informix implementation of embedded SQL for C.
GLS User’s Guide The Global Language Support (GLS) feature, which allows IBM Informix APIs and
database servers to handle different languages, cultural conventions, and code
sets.
JDBC Driver Programmer’s Installing and using Informix JDBC Driver to connect to an Informix database
Guide from within a Java application or applet.
.NET Provider Reference Guide Using Informix .NET Provider to enable .NET client applications to access and
manipulate data in Informix databases.
ODBC Driver Programmer’s Using the Informix ODBC Driver API to access an Informix database and interact
Manual with the Informix database server.
OLE DB Provider Installing and configuring Informix OLE DB Provider to enable client applications,
Programmer’s Guide such as ActiveX Data Object (ADO) applications and Web pages, to access data on
an Informix server.
Object Interface for C++ The architecture of the C++ object interface and a complete class reference.
Programmer’s Guide

Table 3. DataBlade Developer’s Kit Manuals

Manual Subject
DataBlade Developer’s Kit Developing and packaging DataBlade modules using BladeSmith and BladePack.
User’s Guide
DataBlade Module Basic orientation for developing DataBlade modules. Includes an example
Development Overview illustrating the development of a DataBlade module.
DataBlade Module Installation Installing DataBlade modules and using BladeManager to manage DataBlade
and Registration Guide modules in Informix databases.

Compliance with Industry Standards

The American National Standards Institute (ANSI) and the International
Organization of Standardization (ISO) have jointly established a set of industry
standards for the Structured Query Language (SQL). IBM Informix SQL-based
products are fully compliant with SQL-92 Entry Level (published as ANSI
X3.135-1992), which is identical to ISO 9075:1992. In addition, many features of
IBM Informix database servers comply with the SQL-92 Intermediate and Full
Level and X/Open SQL Common Applications Environment (CAE) standards.

IBM Welcomes Your Comments

We want to know about any corrections or clarifications that you would find
useful in our manuals, which will help us improve future versions. Include the
following information:
v The name and version of the manual that you are using
v Section and page number
v Your suggestions about the manual

Send your comments to us at the following email address:

Introduction xxxiii
 docinf@[Link]

This email address is reserved for reporting errors and omissions in our
documentation. For immediate help with a technical problem, contact IBM
Technical Support. For instructions, see the IBM Informix Technical Support
website at [Link]
[Link]/software/data/informix/support/[Link].

We appreciate your suggestions.

xxxiv IBM Informix Dynamic Server Administrator’s Guide

Part 1. The Database Server

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
Chapter 1. Installing and Configuring the Database Server
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2
Planning for the Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Considering Your Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Considering Your Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3
Configuring the Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Configuring Windows Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Maximum Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Modifying UNIX Kernel Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
Allocating Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Using Large Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Creating Chunk Files on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Raw or Unbuffered Disk Access . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
Cooked Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Providing NTFS Partitions in Windows . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Setting Permissions, Ownership, and Group . . . . . . . . . . . . . . . . . . . . . . . 1-6
Creating Standard Device Names (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Setting Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Setting GLS Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Setting Environment Variables on UNIX . . . . . . . . . . . . . . . . . . . . . . . . 1-8
Setting Environment Variables on Windows . . . . . . . . . . . . . . . . . . . . . . . 1-9
Configuring Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
The sqlhosts File on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Network-Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Network-Security Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
The sqlhosts Registry on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Configuring Connectivity Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Configuring the Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Preparing the ONCONFIG Configuration File . . . . . . . . . . . . . . . . . . . . . . 1-11
Creating an ONCONFIG File on UNIX . . . . . . . . . . . . . . . . . . . . . . . 1-11
Creating an ONCONFIG File on Windows . . . . . . . . . . . . . . . . . . . . . . 1-11
Using Server Setup in ISA to Customize Your Configuration . . . . . . . . . . . . . . . . . 1-12
Using IBM Informix Server Administrator to Update the ONCONFIG File . . . . . . . . . . . . . 1-12
Using the Instance Manager to Create a New Database Server Instance (Windows) . . . . . . . . . . 1-12
Using the Instance Manager to Rename a Database Server Instance (Windows) . . . . . . . . . . . 1-13
Configuring Java Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-13
Starting and Administering the Database Server . . . . . . . . . . . . . . . . . . . . . . 1-13
Starting the Database Server and Initializing Disk Space . . . . . . . . . . . . . . . . . . . 1-14
On UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
On Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Initialize Only When Starting a New Database Server . . . . . . . . . . . . . . . . . . 1-14
Preparing for Automatic Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Preparing for Automatic Startup on Windows . . . . . . . . . . . . . . . . . . . . . 1-14
Preparing the UNIX Startup and Shutdown Scripts . . . . . . . . . . . . . . . . . . . 1-14
Preparing to Connect to Applications . . . . . . . . . . . . . . . . . . . . . . . . . 1-15
Creating Storage Spaces and Chunks . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Supporting Large Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Setting Up Your Backup System and Storage. . . . . . . . . . . . . . . . . . . . . . . 1-17
Setting Up ontape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Setting up Your Storage Manager and ON-Bar . . . . . . . . . . . . . . . . . . . . . 1-17
Performing Routine Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Changing Database Server Modes . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Backing Up Data and Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . 1-17
Monitoring Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Checking for Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Performing Additional Administrative Tasks . . . . . . . . . . . . . . . . . . . . . . . . 1-18

© Copyright IBM Corp. 1996, 2005 1-1

 Using Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing Database-Logging Status . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Managing the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Shared Memory. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Managing Parallel Database Query . . . . . . . . . . . . . . . . . . . . . . . . . . 1-19
Using Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
High-Availability Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Enterprise Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using Auditing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using Distributed Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using Global Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Using a Transaction Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Monitoring Database Server Activity . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Event Alarms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
IBM Informix Server Administrator (ISA) . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Message Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21
Specifying the Destination for Message-Log Messages . . . . . . . . . . . . . . . . . . 1-22
Monitoring the Message Log . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
oncheck Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
onperf Tool (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22
onstat Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
System Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
UNIX Operating-System Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-23
Windows Event Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Windows Performance Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24
Windows Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24

In This Chapter
When you install Version 10.0 of the IBM Informix Dynamic Server, you should
follow the installation instructions to ensure the permissions of all key files and
directories are set appropriately. The install instructions are in the IBM Informix
Dynamic Server Installation Guide for UNIX and Linux and the IBM Informix Dynamic
Server Installation Guide for Microsoft Windows.

After you install a new version of the database server, you must configure it.

Configuration refers to setting specific parameters that customize the database

server for your data-processing environment: quantity of data, number of tables,
types of data, hardware, number of users, and security needs.

The following list identifies the basic configuration requirements that are described
in this chapter:
v Planning for the database server
v Configuring the operating system
v Allocating disk space
v Setting environment variables
v Configuring connectivity information
v Preparing the ONCONFIG configuration file
v Using Server Setup to customize configuration
v Starting and administering the database server
v Monitoring database server activity

1-2 IBM Informix Dynamic Server Administrator’s Guide

 When you start a database server on a UNIX or Linux computer, server utilities
check to determine if your environment is secure. For more information, see
“Server Utility Security Before Starting on UNIX and Linux” on page 5-2.

Planning for the Database Server

Configuring a database management system requires many decisions, such as
where to store the data, how to access the data, and how to protect the data. How
you install and configure Dynamic Server can greatly affect the performance of
database operations.

You can customize the database server so that it functions optimally in your
particular data-processing environment. For example, using a database server to
serve 1000 users who execute frequent, short transactions is very different from
using a database server to serve a few users making long and complicated
searches.

When you are planning for your database server, consider your priorities and your
environment.

Considering Your Priorities

As you prepare the initial configuration and plan your backup strategy, keep in
mind the characteristics of your database server:
v Do applications on other computers use this database server instance?
v What is the maximum number of users that you can expect?
v To what extent do you want to control the environment of the users?
v Are you limited by resources for space, CPU, or availability of operators?
v Do you need the database server to run unsupervised?
v Does the database server usually handle many short transactions or fewer long
transactions?
v Which new database server features or related products do you plan to use?

Considering Your Environment

Before you start the initial configuration of your database server, collect as much of
the following information as possible. You might need the assistance of your
system administrator to obtain this information:
v The host names and IP addresses of the other computers on your network
v Does your UNIX platform support the Network Information Service (NIS)?
v The disk-controller configuration
How many disk drives are available? Are some of the disk drives faster than
others? How many disk controllers are available? What is the disk-controller
configuration?
v What are the requirements, features, and limitations of your storage manager
and backup devices?
For more information, see the IBM Informix Storage Manager Administrator's Guide
or your storage-manager documentation.
v Do you need to upgrade the hardware and operating system? Is your operating
system 32-bit or 64-bit?
v Operating-system shared memory and other resources
How much shared memory is available? How much of it can you use for the
database server?

Chapter 1. Installing and Configuring the Database Server 1-3

 UNIX only: The machine notes file indicates which parameters are applicable for
each UNIX platform.

Configuring the Operating System

Before you can start configuring the database server, you must configure the
operating system appropriately. You might need the assistance of the system
administrator for this task.

The 32-bit version of Dynamic Server runs on a 64-bit or 32-bit operating system.
The 64-bit version of Dynamic Server must run on a 64-bit operating system. For
more information, see “Memory Use on 64-Bit Platforms” on page 8-32.

Configuring Windows Memory

On Windows, you must create NTFS partitions and configure memory. Also see
“Providing NTFS Partitions in Windows” on page 1-6.

Insufficient memory for the database server can result in excessive

buffer-management activity. When you set the Virtual Memory values in the
System application on the Control Panel, ensure that you have enough paging
space for the total amount of physical memory.

Maximum Address Space

On Windows, the maximum address space per computer system is:
v 1.7 gigabytes if the [Link] file is not modified to 3 gigabytes.
v 2.7 gigabytes if the [Link] file is modified to 3 gigabytes.

You can use the /userva=xxxx switch for more precise tuning of user and kernel
virtual memory space. Use this switch with the 3-gigabyte switch in the [Link]
file to tune the user-mode space to a value that is between 2 and 3 gigabytes, with
the difference (3,072 less xxxx) given back to the kernel mode. Note that xxxx is a
value expressed in megabytes.

The following sample [Link] file shows how to use the new switch to tune a
computer to allocate 2,900 megabytes of user-mode virtual memory and 1,196
megabytes of kernel-mode virtual memory. This increases the available kernel
space by 172 megabytes.
[Boot Loader]
Timeout=30
Default=multi(0)disk(0)rdisk(0)partition(2)\WINNT
[Operating Systems]
multi(0)disk(0)rdisk(0)partition(2)\WINNT="Microsoft Windows Server 2003"
/fastdetect /3GB /Userva=2900

Modifying UNIX Kernel Parameters

The machine notes file contains recommended values for configuring
operating-system resources. Use these recommended values when you configure
the operating system.

If the recommended values for the database server differ significantly from your
current environment, consider modifying your operating-system configuration. For
more information, see your IBM Informix Dynamic Server Performance Guide.

On some operating systems, you can specify the amount of shared memory
allocated to the database server. The amount of available memory influences the

1-4 IBM Informix Dynamic Server Administrator’s Guide

 values that you can choose for the shared-memory parameters in your
configuration file. In general, increasing the space available for shared memory
enhances performance. You might also need to specify the number of locks and
semaphores.

For background information on the role of the UNIX kernel parameters, see
Chapter 9, “Managing Shared Memory,” on page 9-1.

Allocating Disk Space

Configure your disks to obtain optimum performance with data marts and data
warehouses. Disk I/O is the longest portion of the response time for an SQL
operation. The database server offers parallel access to multiple disks on a
computer. Before you allocate the disk space, study the information about disk
space in your operating-system administration guide and see “Disk Allocation for
Chunks” on page 10-3.

Using Large Chunks

The size of chunks for dbspaces is 4 terabytes for a 2-kilobyte page. Chunks can
reside anywhere in a 64-bit address space.

To activate the creation of large chunks, you must use the onmode utility. The
onmode utility uses a -BC flag to control the availability of large chunks, chunks
greater than 2 gigabytes.

When the database server is first migrated to a new version of Dynamic Server,
large chunks are not allowed. Run onmode -BC 1 to allow large chunks to be
created.

If necessary to convert older versions of Dynamic Server to the large chunk format,
execute onmode -BC 2.

If the root chunk is a large chunk at the time the server starts, the onmode -BC 1
step is skipped and -BC 2 mode starts automatically.

Creating Chunk Files on UNIX

On UNIX, you can store data in chunks that use either unbuffered (raw) disks or
operating-system files, also known as buffered or cooked files.

Raw or Unbuffered Disk Access

UNIX provides unbuffered disk access using character-special devices (also known
as raw disk devices). To create raw disk devices on UNIX, follow the instructions
provided with your operating system.

The database server uses raw disk access to improve the speed and reliability of
disk I/O operations. Raw disk access bypasses the file-buffering mechanism that
the operating system provides. The database server itself manages the data
transfers between disk and memory. The database server optimizes table access by
guaranteeing that rows are stored contiguously.

Important: While you should use raw disk devices on UNIX to achieve better
performance, recent advances in I/O caching for cooked writes can
provide similar if not better performance. To determine the best device
performance, perform benchmark testing on the system with both
types of devices for the dbspace and table layout.

Chapter 1. Installing and Configuring the Database Server 1-5

 To allocate disks for the database server:
1. Configure a raw disk device for each disk.
2. Create standard device names or filenames.
3. Set permissions, ownership, and group for each raw disk device.

Cooked Files
If optimum performance is unimportant, you can configure the database server to
store data in cooked files. Cooked files are easier to set up than raw disk devices.

Providing NTFS Partitions in Windows

On Windows, install the database server on a New Technology File System (NTFS)
or File Allocation Table (FAT) partition. However, you must store all dbspaces,
blobspaces, and sbspaces in NTFS files or on a physical drive or logical disk
partition. You should use NTFS files to simplify disk administration. For more
information about NTFS files, see your Windows documentation and “Disk Access
on Windows” on page 10-3.

If all of your partitions are FAT partitions, you need to convert at least one
partition to NTFS. You can use the Windows convert utility, as the following
example shows:
convert /fs:ntfs

Setting Permissions, Ownership, and Group

Files or raw disk devices that the database server uses must have the appropriate
ownership and permissions.

UNIX Only

On UNIX, the owner and group must be informix, and the permissions must be
set to read and write for both the user and the group (but not for others).

If you want users other than informix or root to execute ON–Bar commands,
create a bargroup group. Only members of bargroup can execute ON–Bar
commands. The bargroup group is not created automatically during database
server installation. For instructions on creating a group, see the IBM Informix
Dynamic Server Installation Guide for UNIX and Linux or your UNIX documentation.
End of UNIX Only

Windows Only

On Windows, files must be owned by a member of the Informix-Admin group.

The Informix-Admin group is created automatically when you install the database
server.
End of Windows Only

Creating Standard Device Names (UNIX)

You should use symbolic links to assign abbreviated standard device names for
each raw disk device. If you have symbolic links, you can replace a disk that has
failed with a new disk by assigning the symbolic name to the new disk.

To create a link between the character-special device name and another filename,
use the UNIX link command (usually ln).

1-6 IBM Informix Dynamic Server Administrator’s Guide

 Execute the UNIX command ls -l on your device directory to verify that both the
devices and the links exist. The following example shows links to raw disk devices.
If your operating system does not support symbolic links, you can use hard links.
ls -l
crw-rw--- /dev/rxy0h
crw-rw--- /dev/rxy0a
lrwxrwxrwx /dev/my_root@->/dev/rxy0h
lrwxrwxrwx /dev/raw_dev2@->/dev/rxy0a

Setting Environment Variables

To start, stop, or access a database server, each user must set the appropriate
environment variables. Some environment variables are required; others are
optional.

To set the required environment variables:

1. Set INFORMIXDIR to the directory where you installed the IBM Informix
products.
2. Set the PATH environment variable to include $INFORMIXDIR/bin (UNIX) or
%INFORMIXDIR%\bin (Windows).
3. Set INFORMIXSERVER to the name of the database server.

Tip: Set the environment variables in the appropriate startup file for your shell file
or Windows.

The IBM Informix Guide to SQL: Reference contains a complete list of environment
variables. For information on how setting environment variables can affect
performance, see your IBM Informix Dynamic Server Performance Guide.

Table 1-1 shows the environment variables that you must set before you access the
database server or perform most administrative tasks.
Table 1-1. Required Environment Variables
Environment Variable Description
CLASSPATH If you are using J/Foundation, specifies the location of jvphome/[Link] file so that
Java Development Kit (JDK) can compile the Java source files.
INFORMIXDIR Specifies the directory where you installed your IBM Informix database server.
INFORMIXSERVER Specifies the name of the default database server. It has the value specified for the
DBSERVERNAME or DBSERVERALIASES configuration parameter.
JVPHOME If you are using J/Foundation, specifies the directory where you installed the IBM
Informix JDBC Driver.
ONCONFIG Specifies the name of the active ONCONFIG file. All users who use database server
utilities such as onstat must set the ONCONFIG environment variable. Users running
client applications do not need to set the ONCONFIG environment variable.

If the ONCONFIG environment variable is not present, the database server uses
configuration values from the onconfig file:

On UNIX: $INFORMIXDIR/etc/onconfig

On Windows: %INFORMIXDIR%\etc\[Link]

Chapter 1. Installing and Configuring the Database Server 1-7

Table 1-1. Required Environment Variables (continued)
Environment Variable Description
PATH Specifies the location of executable files.

On UNIX: $INFORMIXDIR/bin

On Windows: %INFORMIXDIR%\bin
TERM Enables DB–Access to recognize and communicate with the terminal that you are using.
This environment variable is not required for initialization or start up, but it must be set
before you can run an application.
TERMCAP Specifies whether DB–Access should use the information in the termcap file or the
TERMINFO terminfo directory. If required for your system, you might need assistance from the UNIX
INFORMIXTERM system administrator to set these variables because they are highly system dependent.

Setting GLS Environment Variables

The following environment variables let you work with the Global Language
Support (GLS) feature. Set these environment variables if you want to use a
language other than the default, U.S. English:
v CLIENT_LOCALE
v DB_LOCALE
v SERVER_LOCALE
v DBLANG
v C8BITLEVEL
v ESQLMF
v GLS8BITFSYS
v GL_DATE
v GL_DATETIME

For more information, see the IBM Informix GLS User's Guide.

Setting Environment Variables on UNIX

Set UNIX environment variables in one of the following ways:
v At the system prompt on the command line
When you set an environment variable at the system prompt, you must reassign
it the next time you log in to the system.
v In an environment-configuration file such as $INFORMIXDIR/etc/[Link] or
.informix
An environment-configuration file is a common or private file where you can set
environment variables for each database server user. Use of an
environment-configuration file reduces the number of environment variables that
you must set at the command line or in a shell file.
v In your .profile or .login file
When you set an environment variable in your .login, .cshrc, or .profile file, it is
assigned automatically every time you log in to the system. For information
about these files, see your operating-system manuals.

To override environment variables that have been automatically set, use a private
environment-variable file, ~/.informix, or assign new values to environment
variables individually. For information about the .informix and [Link] files,
see the IBM Informix Dynamic Server Administrator's Reference.

1-8 IBM Informix Dynamic Server Administrator’s Guide

 To check the validity of environment variables, use the chkenv utility.

Figure 1-1 shows a sample setup file that contains environment variables for the
miami database server. LD_LIBRARY_PATH is set to the location of the database
server and ESQL/C library files.

setenv INFORMIXDIR /ix/informix93

setenv INFORMIXSQLHOSTS /ix/[Link]
setenv ONCONFIG [Link]
setenv INFORMIXSERVER miami

# setup to use J/Foundation

setenv JVPHOME /ix/informix93/extend/krakatoa
setenv CLASSPATH $JVPHOME/[Link]:$JVPHOME/[Link]:/usr/java/lib/[Link]

# Include jar paths for Java; include /usr/ccs/bin for C compiler:

setenv PATH $INFORMIXDIR/bin:$INFORMIXDIR/extend/krakatoa/[Link]:
$INFORMIXDIR/extend/krakatoa/[Link]:/usr/ccs/bin:$PATH

setenv LD_LIBRARY_PATH $INFORMIXDIR/lib:$INFORMIXDIR/lib/esql:/usr/lib

Figure 1-1. Sample Setup File

Setting Environment Variables on Windows

On Windows, the installation procedure prepares a file, [Link], that sets the
environment variables to their correct values. The [Link] file is stored in the
%INFORMIXDIR% directory. You must execute [Link] before you can use
any of the command-line utilities.

You can set environment variables or override environment variables that have
been automatically set in the following places:
v On Windows, System > Environment > User Variables
v In a command-prompt session
v %INFORMIXDIR%\[Link] batch file
Use this batch file to configure command-prompt utilities.

For more information, see the IBM Informix Guide to SQL: Reference and “Creating
an ONCONFIG File on Windows” on page 1-11.

Configuring Connectivity
The connectivity information allows a client application to connect to any IBM
Informix database server on the network. The connectivity data for a particular
database server includes the database server name, the type of connection that a
client can use to connect to it, the host name of the computer or node on which the
database server runs, and the service name by which it is known.

You must prepare the connectivity information even if the client application and
the database server are on the same computer or node.

You do not need to specify all possible network connections in the sqlhosts file or
registry before you start the database server. But to make a new connection
available, you must take the database server offline and then bring it back to
online mode once again.

For detailed information about configuring connectivity, see Chapter 3,

“Client/Server Communications,” on page 3-1.

Chapter 1. Installing and Configuring the Database Server 1-9

 When you configure connectivity on UNIX, also consider setting the
LISTEN_TIMEOUT and MAX_INCOMPLETE_CONNECTIONS configuration
parameters. These parameters enable you to reduce the risk of a hostile
denial-of-service (DOS) attack by making it more difficult to overwhelm the
Listener VP that handles connections. For more information, see “Limiting
Denial-of-Service Flood Attacks” on page 5-7

The sqlhosts File on UNIX

On UNIX, the sqlhosts file contains connectivity information. The default location
of this file is $INFORMIXDIR/etc/sqlhosts. If you store the information in another
location, you must set the INFORMIXSQLHOSTS environment variable. For more
information, see “The sqlhosts File and the SQLHOSTS Registry Key” on page
3-13.

If you set up several database servers to use distributed queries, use one of the
following ways to store the sqlhosts information for all the databases:
v In one sqlhosts file, pointed to by INFORMIXSQLHOSTS
v In separate sqlhosts files in each database server directory

Use a text editor or ISA to edit the sqlhosts file. For more information, see
“Configuring Connectivity Using ISA” on page 1-10.

Network-Configuration Files
In addition to the sqlhosts files, TCP/IP connections require entries in the
/etc/hosts and /etc/services files. For IPX/SPX connections, the names of the
auxiliary files depend on the hardware vendor.

Network-Security Files
IBM Informix database servers follow UNIX security requirements for making
connections. Thus, the UNIX system administrator might need to make
modifications to the /etc/passwd, etc/hosts, ~/.rhosts, and other related files.

The network-configuration and network-security files are described in

operating-system manuals.

The sqlhosts Registry on Windows

On Windows, the HKEY_LOCAL_MACHINE registry contains the sqlhosts
information. The database server installation procedure prepares the registry
information. You should not edit the HKEY_LOCAL_MACHINE registry.

Use setnet32 to manage sqlhosts information. For information about setnet32, see
the installation information in your client documentation. However, setnet32 does
not allow you to assign a database server to a database server group.

Configuring Connectivity Using ISA

Use IBM Informix Server Administrator (ISA) to configure connectivity information
for IBM Informix database servers and database server groups for Enterprise
Replication. ISA allows you to edit the sqlhosts file on UNIX or the sqlhosts
registry on Windows. For more information, see the ISA onscreen instructions or
online help.

In ISA, select Configuration > SQLHOSTS.

1-10 IBM Informix Dynamic Server Administrator’s Guide

Configuring the Database Server
The configuration parameters are stored in the ONCONFIG file. The product
installation script sets the defaults for most of the configuration parameters.

For information about the configuration parameters and how to monitor them, see
Chapter 2, “Configuration Parameters,” on page 2-1 and the chapter on
configuration parameters in the IBM Informix Dynamic Server Administrator's
Reference. For information on the order of files that the database server checks for
configuration values, see “Process Configuration File” on page 4-3.

Preparing the ONCONFIG Configuration File

The [Link] template file in the etc subdirectory of INFORMIXDIR contains
initial values for many of the configuration parameters. Copy this template and
tailor it to your specific configuration.

The template files contain initial values for many of the configuration parameters.
You can use a text editor or ISA to change the configuration parameters in your
ONCONFIG file.

Important: Do not modify or delete the template files. The database server
provides these files as templates and not as functional configuration
files.

Note: If you omit parameters in your copy of the ONCONFIG file, the database
server uses values in the [Link] file for the missing parameters when
the server starts.

Creating an ONCONFIG File on UNIX

A new instance of the database server is created and initialized when you install
the IBM Informix software for the first time. The installation script automatically
creates the [Link] file for you.

To prepare the ONCONFIG file using a text editor:

1. Copy and rename the $INFORMIXDIR/etc/[Link] file and store it in the
etc subdirectory. (Skip this step if you are using ISA.)
2. Use a text editor or ISA to edit the ONCONFIG configuration file.
3. Set the ONCONFIG environment variable to the name of your new
ONCONFIG file.
4. Initialize the database server if it is a new instance.
Otherwise, shut down and restart the database server.

Creating an ONCONFIG File on Windows

On Windows, a new instance of the database server is created and initialized when
you install the IBM Informix software for the first time. You can also use the
Instance Manager ([Link]) to create a new database server instance. The
Instance Manager automatically creates an ONCONFIG file.

To prepare the ONCONFIG file using the Instance Manager:

1. Use the Instance Manager to create a new database server instance.
For details, see “Using the Instance Manager to Create a New Database Server
Instance (Windows)” on page 1-12.
2. Use a text editor or ISA to edit the ONCONFIG configuration file.

Chapter 1. Installing and Configuring the Database Server 1-11

 3. Set your ONCONFIG environment variable to the name of your new
ONCONFIG file.
4. Shut down and restart the database server for the configuration changes to take
effect.
a. From the Service control application window, select the Dynamic Server
service and click the Stop button.
b. Click the Start button.

To use [Link] to change the ONCONFIG environment variable:

1. Change the ONCONFIG environment variable for your session in the
%INFORMIXDIR%\[Link] file.
2. Execute [Link] for the changes to take effect.

Using Server Setup in ISA to Customize Your Configuration

Use Server Setup in ISA to configure your production database server and
optionally, J/Foundation and database storage. For more information, see the ISA
online help and onscreen instructions.

To use Server Setup to customize your configuration:

1. Start your Web browser and open the Web page for ISA:
[Link]
port_number/
If you did not install or start ISA, see your IBM Informix Installation Guide for
directions.
2. Log in with the username and password that you provided during installation.
3. On the main page, select the database server name.
4. From the ISA server view page, click Server Setup.

Using IBM Informix Server Administrator to Update the

ONCONFIG File
Use ISA to edit configuration parameters and set environment variables for all
database servers. ISA automatically creates the ONCONFIG file (no need to copy
[Link]).

To use IBM Informix Server Administrator to update the ONCONFIG file:

1. In ISA, display the setup file and edit the environment variables.
2. Select the database server name.
3. In ISA, display the ONCONFIG file and modify specific configuration
parameters.
ISA automatically updates your ONCONFIG file.
4. Shut down and restart the database server for the changes to take effect.

Using the Instance Manager to Create a New Database Server

Instance (Windows)
You can use the Instance Manager to create a new instance of the database server.
The Instance Manager automatically creates an ONCONFIG file for you. For more
information about the Instance Manager and scheduling priority, see IBM Informix
Dynamic Server Installation Guide for Microsoft Windows.

To use the Instance Manager:

1-12 IBM Informix Dynamic Server Administrator’s Guide

 1. Select Server Instance Manager from the Dynamic Server menu.
2. Click Create New to create a new instance of the database server and follow
the instructions in the wizard.
3. To improve database server performance, choose a scheduling priority for the
oninit process in the Instance Manager. The default scheduling priority for
Windows is Normal.
4. Click Delete Server to delete a database server instance.

Using the Instance Manager to Rename a Database Server

Instance (Windows)
You can also use the Instance Manager rename option, to change the name for a
database server instance.

To rename a database server instance:

1. Shut down the database server instance that you want to rename.
2. Select Server Instance Manager from the Dynamic Server menu.
The Instance Manager displays a list of available instances.
3. Select the instance to rename and click Rename Server.
4. In the dialog box that appears, enter your password and specify the new
database server name.

After you rename the server instance, you can start the instance.

If an administrator changed the name of ONCONFIG file or the MSGLOG file to a

file with a custom name before the server instance was renamed, you must
manually edit the file to change the name.

Configuring Java Support

IBM Informix Dynamic Server with J/Foundation allows you to develop and run
Java UDRs. Configure the database server without Java and then modify it to add
Java support. Configuring the database server to support Java requires several
additional steps:

To configure the database server to support Java user-defined routines:

1. Create an sbspace to hold the Java JAR files.
2. Create the JVP properties file.
3. Add (or modify) the Java configuration parameters in the ONCONFIG file.
4. Set environment variables.

For the setup instructions, see J/Foundation Developer's Guide.

Starting and Administering the Database Server

After you install and configure the database server, you need to perform one or
more of the following:
v Preparing to connect to applications.
v Starting the database server and initialize disk space.
v Creating storage spaces.
v Setting up your backup and restore system.
v Performing administrative tasks.

Chapter 1. Installing and Configuring the Database Server 1-13

 Starting the Database Server and Initializing Disk Space
On UNIX
To bring the database server to online mode, enter oninit.

If starting a new database server, use the oninit command with the -i flag to
initialize the disk space and bring the database server online.

On Windows
On Windows, the database server runs as a service. Use the Service control
application to bring the database server to online mode. To initialize the database
server, click the Dynamic Server service and enter -iy in the Startup Parameters
box.

Another way to initialize the database server on Windows is to use the following
command where dbservername is the database server name:
starts dbservername -iy

Initialize Only When Starting a New Database Server

Warning: When you initialize disk space, all of the existing data in the database
server is destroyed. Initialize disk space only when you are starting a
new database server.

For a description of the initialization types and associated commands, see

Chapter 4, “Initializing the Database Server,” on page 4-1.

Preparing for Automatic Startup

Prepare the operating-system registry or scripts to automatically start and stop the
database server.

Preparing for Automatic Startup on Windows

Change the Informix password in the Service control application when you change
the Informix password on Windows.

To start the database server automatically when Windows starts:

1. From the Service control application window, select the Dynamic Server service
and click the Startup button.
2. Select Automatic in the Status Type dialog box.
3. In the Log On As dialog box, select This Account and verify that informix is
in the text box.

Preparing the UNIX Startup and Shutdown Scripts

You can modify the UNIX startup script to initialize the database server
automatically when your computer enters multiuser mode. You can also modify
your UNIX shutdown script to shut down the database server in a controlled
manner whenever UNIX shuts down.

To prepare the UNIX startup script, add UNIX and database server utility
commands to the UNIX startup script so that the script performs the following
steps.

ISA provides a sample UNIX script for startup and shutdown that you can
customize in $INFORMIXDIR/etc/[Link].

1-14 IBM Informix Dynamic Server Administrator’s Guide

 To prepare the UNIX startup script:
1. Set the INFORMIXDIR environment variable to the full pathname of the
directory in which the database server is installed.
2. Set the PATH environment variable to include the $INFORMIXDIR/bin
directory.
3. Set the ONCONFIG environment variable to the desired configuration file.
4. Set the INFORMIXSERVER environment variable so that the sysmaster
database can be updated (or created, if needed).
5. Execute oninit, which starts the database server and leaves it in online mode.
If you plan to initialize multiple versions of the database server (multiple
residency), you must reset ONCONFIG and INFORMIXSERVER and
re-execute oninit for each instance of the database server.
6. If you are using IBM Informix Storage Manager (ISM) for managing database
server backups, you must start the ISM server on each node.
For information about how to start the ISM server, see your IBM Informix
Installation Guide.

If different versions of the database server are installed in different directories, you
must reset INFORMIXDIR and repeat the preceding steps for each different
version.

To shut down the database server in a controlled manner whenever UNIX shuts
down, add UNIX and database server utility commands to the UNIX shutdown
script so that the script performs the following steps.

To prepare the UNIX shutdown scrip:

1. Set the INFORMIXDIR environment variable to the full pathname of the
directory in which the database server is installed.
2. Set the PATH environment variable to include the $INFORMIXDIR/bin
directory.
3. Set the ONCONFIG environment variable to the desired configuration file.
4. Execute onmode -ky, which initiates an immediate shutdown and takes the
database server offline.
If you are running multiple versions of the database server (multiple
residency), you must reset ONCONFIG and re-execute onmode -ky for each
instance.

If different versions of the database server are installed in different directories, you
must reset INFORMIXDIR and repeat the preceding steps for each version.

In the UNIX shutdown script, the database server shutdown commands should
execute after all client applications have completed their transactions and exited.

Preparing to Connect to Applications

When the database server is online, you can connect client applications and begin
to create databases. Before you can access information in a database, the client
application must connect to the database server environment. To connect to and
disconnect from a database server, you can issue SQL statements from the
following client programs:
v DB–Access
v SQL Editor

Chapter 1. Installing and Configuring the Database Server 1-15

 v IBM Informix ESQL/C
v IBM Informix ODBC Driver
v IBM Informix JDBC Driver

For information about creating databases, see IBM Informix Database Design and
Implementation Guide and IBM Informix Guide to SQL: Tutorial. For information about
how to use client applications, see the IBM Informix DB–Access User's Guide, IBM
Informix ESQL/C Programmer's Manual, IBM Informix ODBC Driver Programmer's
Manual, or IBM Informix JDBC Driver Programmer's Guide.

Creating Storage Spaces and Chunks

You are responsible for planning and implementing the storage configuration. The
way you distribute the data on disks affects the performance of the database
server. A chunk is the same as a logical volume, logical unit, or regular file that has
been assigned to the database server. The maximum size of an individual chunk is
4 terabytes. The number of allowable chunks is 32,766. A logical storage space is
composed of one or more chunks.

Tip: To take advantage of the large limit of 4 terabytes per chunk, assign a single
chunk per disk drive. This way of distributing data increases performance.

After the database server is initialized, you can create storage spaces such as
dbspaces, blobspaces, or sbspaces. Use the onspaces utility or ISA to create storage
spaces and chunks.

You must create an sbspace if you are using the following functions:
v J/Foundation (to hold Java JAR files)
v Enterprise Replication (to hold spooled row data)
v Smart large objects (BLOB and CLOB data types)
v Multirepresentational data types (such as DataBlades or HTML data types)

For a description of storage spaces and other physical units such as tblspaces and
extents, see Chapter 10, “Data Storage,” on page 10-1. For a discussion of the
allocation and management of storage spaces, see “Disk-Space Parameters” on
page 2-2 and Chapter 11, “Managing Disk Space,” on page 11-1.

For more information, see the IBM Informix Dynamic Server Enterprise Replication
Guide and J/Foundation Developer's Guide.

Supporting Large Chunks

If you just converted from a version of Dynamic Server that is prior to Version 9.4,
chunks that are greater than 2 gigabytes are not yet enabled. To support large
chunks and large offsets to the maximum size of 4 terabytes and more than 2047
chunks, run onmode -BC 1.

You can test your data in the onmode -BC 1 mode. When you are satisfied that
your data has converted correctly, then you can run onmode -BC 2 and thereby
put the server in large -chunk-only mode.

After running onmode -BC 2, reversion is no longer supported. After support for
large chunks is enabled, it cannot be disabled.

1-16 IBM Informix Dynamic Server Administrator’s Guide

 Setting Up Your Backup System and Storage
To back up and restore your data, choose either the ON–Bar or ontape utility. For
more information on setting up and using ON–Bar or ontape, see “Backup and
Restore Parameters” on page 2-4 and the IBM Informix Backup and Restore Guide.

Setting Up ontape
If you use ontape as your backup tool, you must set up storage devices (tape
drives) before you can back up and restore data. The ontape utility does not
require a storage manager.

Setting up Your Storage Manager and ON-Bar

If you use ON–Bar as your backup tool, you must set up a storage manager and
storage devices before you can back up and restore data.

ON–Bar is packaged with IBM Informix Storage Manager (ISM). The storage
manager is an application that manages the storage devices and media that contain
backups. The storage manager handles all media labeling, mount requests, and
storage volumes. ISM can back up data to as many as four storage devices at a
time. ISM stores data on simple tape drives, optical disk devices, and file systems.
However, you can purchase a third-party storage manager if you want to use more
sophisticated storage devices, backups to more than four storage devices at a time,
or backups over a network.

When you plan your storage-space and logical-log backup schedule, make sure
that the storage devices and backup operators are available to perform backups.
For information about configuring and managing storage devices and media, see
the IBM Informix Storage Manager Administrator's Guide or to your third-party
storage-manager documentation.

Performing Routine Administrative Tasks

Depending on the needs of your organization, you might be responsible for
performing the periodic tasks described in the following paragraphs. Not all of
these tasks are appropriate for every installation. For example, if your database
server is available 24 hours a day, 7 days a week, you might not bring the database
server to offline mode, so database server operating mode changes would not be a
routine task.

Changing Database Server Modes

The database server administrator is responsible for starting up and shutting down
the database server by changing the mode. “Database Server Operating Modes” on
page 4-7 explains how to change database server modes.

Backing Up Data and Logical-Log Files

To ensure that you can recover your databases in the event of a failure, make
frequent backups of your storage spaces and logical logs. You also can verify
ON–Bar backups with the archecker utility.

How often you back up the storage spaces depends on how frequently the data is
updated and how critical it is. A backup schedule might include a complete
(level-0) backup once a week, incremental (level-1) backups daily, and level-2
backups hourly. You also need to perform a level-0 backup after performing
administrative tasks such as adding a dbspace, deleting a logical-log file, or
enabling mirroring.

Chapter 1. Installing and Configuring the Database Server 1-17

 Back up each logical-log file as soon as it fills. You can back up these files
manually or automatically. For information on using ON–Bar and ontape, see the
IBM Informix Backup and Restore Guide.

Monitoring Activity
The IBM Informix database server design lets you monitor every aspect of the
database server. “Monitoring Database Server Activity” on page 1-21 provides
descriptions of the available information, instructions for obtaining information,
and suggestions for its use.

Checking for Consistency

You should perform occasional checks for data consistency. For a description of
these tasks, see Chapter 22, “Consistency Checking,” on page 22-1.

Performing Additional Administrative Tasks

This section covers various administrative tasks that you would perform on a
production database server.

Using Mirroring
When you use disk mirroring, the database server writes data to two locations.
Mirroring eliminates data loss due to storage device failures. If mirrored data
becomes unavailable for any reason, the mirror of the data is available immediately
and transparently to users. For information on mirroring, see Chapter 18,
“Mirroring,” on page 18-1. For instructions on tasks related to mirroring, see
Chapter 19, “Using Mirroring,” on page 19-1.

Important: You should mirror critical dbspaces that contain logical-log files, the
physical log, and the root dbspace.

Managing Database-Logging Status

You can specify whether each database uses transaction logging by default,
whether the default logging mode for databases is buffered or unbuffered, and
whether the logging mode is ANSI compliant.

You can create the following table types in a logging database:

v STANDARD
v TEMP
v RAW

For more information, see “Temporary Tables” on page 10-26 and Chapter 12,
“Logging,” on page 12-1. For information on how to change logging options, see
Chapter 13, “Managing the Database-Logging Mode,” on page 13-1.

Managing the Logical Log

The database server contains several files called logical logs that record data
transactions and administrative information such as checkpoint records and
additions and deletions of chunks.

Typical logical-log administration tasks include backing up logical-log files, adding,

freeing, and resizing logical-log files, and specifying high-watermarks.

1-18 IBM Informix Dynamic Server Administrator’s Guide

 The database server dynamically allocates logical-log files while online to prevent
long transactions from hanging the database server.

For more information, see “Logging Parameters” on page 2-3 and Chapter 14,
“Logical Log,” on page 14-1. For instructions on creating and modifying the
logical-log configuration, see Chapter 15, “Managing Logical-Log Files,” on page
15-1. For information on backing up the logical log, see the IBM Informix Backup
and Restore Guide.

Managing the Physical Log

You can change the size and location of the physical log. For more information
about the physical log, see “Physical Log Parameters” on page 2-4. Chapter 16,
“Physical Logging, Checkpoints, and Fast Recovery,” on page 16-1, and Chapter 17,
“Managing the Physical Log,” on page 17-1.

When the database server starts up, it checks whether the physical log is empty,
because that implies that it shut down in a controlled fashion. If the physical log is
not empty, the database server automatically performs an operation called fast
recovery. Fast recovery automatically restores databases to a state of physical and
logical consistency after a system failure that might have left one or more
transactions uncommitted.

Managing Shared Memory

Managing shared memory includes the following tasks:
v Changing the size or number of buffers (by changing the size of the logical-log
or physical-log buffer, or changing the number of buffers in the shared-memory
buffer pool)
v Changing shared-memory parameter values, if necessary
v Changing forced residency (on or off, temporarily or for this session)
v Tuning checkpoint intervals
v Adding segments to the virtual portion of shared memory
v Using the SQL statement cache to reduce memory usage and preparation time
for queries

For information on how the database server uses shared memory, see Chapter 8,
“Shared Memory,” on page 8-1. For additional information, see “Shared-Memory
Parameters” on page 2-5 and Chapter 9, “Managing Shared Memory,” on page 9-1.

Managing Virtual Processors

The configuration and management of virtual processors (VPs) has a direct impact
on the performance of a database server. The optimal number and mix of VPs for
your database server depends on your hardware and on the types of applications
that your database server supports.

For an explanation of virtual processors, see Chapter 6, “Virtual Processors and

Threads,” on page 6-1. For additional information, see “Virtual Processor
Parameters” on page 2-7 and Chapter 7, “Managing Virtual Processors,” on page
7-1.

Managing Parallel Database Query

You can control the resources that the database uses to perform decision-support
queries in parallel. You need to balance the requirements of decision-support

Chapter 1. Installing and Configuring the Database Server 1-19

 queries against those of online transaction processing (OLTP) queries. The
resources that you need to consider include shared memory, threads, temporary
table space, and scan bandwidth. For information on parallel database query
(PDQ) and how fragmentation affects the performance of PDQ, see your IBM
Informix Dynamic Server Performance Guide. For information on the configuration
parameters, see “Decision-Support Parameters” on page 2-6.

Using Data Replication

Data replication refers to the process of representing database objects at more than
one distinct site. Dynamic Server supports two methods of data replication:
High-Availability Data Replication (HDR) and IBM Informix Enterprise Replication (ER).
You can combine HDR and Enterprise Replication on the same database server. For
more information, see the IBM Informix Dynamic Server Enterprise Replication Guide.

High-Availability Data Replication

HDR supports synchronous replication of an entire database to another database
server, providing a hot standby in case of a catastrophic computer failure. For
more information, see “High-Availability Data-Replication Parameters” on page
2-8. Chapter 20, “High-Availability Data Replication (Enterprise/Workgroup
Editions),” on page 20-1, and Chapter 21, “Using High-Availability Data
Replication (Enterprise/Workgroup Editions),” on page 21-1.

Enterprise Replication
Enterprise Replication supports asynchronous data replication over geographically
distributed database servers and allows you to replicate both entire databases and
subsets of databases and tables. Enterprise Replication offers limited support of
user-defined data types. For detailed information on Enterprise Replication, see the
IBM Informix Dynamic Server Enterprise Replication Guide.

Using Auditing
If you intend to use database server auditing, you need to specify where audit
records are stored, how to handle error conditions, and so on. You also might want
to change how users are audited if you suspect that they are abusing their access
privileges. For information on tasks related to auditing, see “Auditing Parameters
(UNIX)” on page 2-10 and the IBM Informix Trusted Facility Guide.

Using Distributed Queries

The database server allows users to query and update more than one database
across multiple database servers. This type of query is called a distributed query.
The database servers can reside on a single host computer, on the same network,
or on a gateway.

For more information on distributed queries, see the IBM Informix Database Design
and Implementation Guide and IBM Informix Guide to SQL: Tutorial.

Using Global Transactions

A global transaction is a transaction that involves more than one database server.
IBM Informix database servers support two types of global transactions:
v TP/XA with a transaction manager
v Two-phase commit

Informix uses a two-phase commit protocol to ensure that distributed queries are
uniformly committed or rolled back across multiple database servers. For more
information, see Chapter 23, “Multiphase Commit Protocols,” on page 23-1.

1-20 IBM Informix Dynamic Server Administrator’s Guide

 Using a Transaction Manager
Transaction managers manage terminals and data recovery. The TP/XA library
enables communication between a third-party transaction manager and IBM
Informix databases in an X/Open environment. For more information, see the IBM
Informix TP/XA Programmer's Manual and “Transaction Managers” on page 23-2.

Monitoring Database Server Activity

You can gather information about database server activity from the following
sources.

Source of Information UNIX Windows

Event alarms X X
IBM Informix Server Administrator (ISA) X X
Message log X X
ON–Monitor X
oncheck utility X X
onperf utility X
onstat utility X X
SMI tables X X
System console X X
Windows Event Viewer X
Windows Performance Monitor X

The following sections explain each of these sources.

Event Alarms
To report situations that require your immediate attention, the database server uses
the event-alarm feature. To use the event-alarm feature, set the ALARMPROGRAM
configuration parameter to the full pathname of an executable file that performs
the necessary administrative actions.

For more information, see the appendix on event alarms and the chapter on
configuration parameters in the IBM Informix Dynamic Server Administrator's
Reference.

IBM Informix Server Administrator (ISA)

ISA is a browser-based tool that provides system administration for the entire
range of IBM Informix database servers. ISA provides access to almost all IBM
Informix database server command-line functions.

For more information on ISA, see the IBM Informix Dynamic Server Administrator's
Reference and the ISA online help.

Message Log
The database server message log is an operating-system file. The messages
contained in the database server message log do not usually require immediate
action. To report situations that require your immediate attention, the database
server uses the event-alarm feature. See “Event Alarms” on page 1-21. You can
view the message log in ISA.

Chapter 1. Installing and Configuring the Database Server 1-21

 Specifying the Destination for Message-Log Messages
To specify the message-log pathname, set the MSGPATH configuration parameter.
The changes to MSGPATH take effect after you shut down and restart the database
server. For more information about MSGPATH, see the chapter on configuration
parameters in the IBM Informix Dynamic Server Administrator's Reference.

Monitoring the Message Log

You should monitor the message log once or twice a day to ensure that processing
is proceeding normally and that events are being logged as expected. Use the
onstat -m command to obtain the name of the message log and the 20 most recent
entries. Use a text editor to read the complete message log. Use an
operating-system command (such as the UNIX command tail -f) to see the
messages as they occur.

Monitor the message-log size, because the database server appends new entries to
this file. Edit the log as needed, or back it up to tape and delete it.

If the database server experiences a failure, the message log serves as an audit trail
for retracing the events that develop later into an unanticipated problem. Often the
database server provides the exact nature of the problem and the suggested
corrective action in the message log.

You can read the database server message log for a minute-by-minute account of
database server processing in order to catch events before a problem develops.
However, you do not need to perform this kind of monitoring.

For more information, see the chapter on the messages in the IBM Informix
Dynamic Server Administrator's Reference. Also, see IBM Informix Error Messages.

ON-Monitor (UNIX)
ON–Monitor provides a simple way to monitor many aspects of the database
server. Most of the monitoring functions are available under the Status menu. For
more information, see the section about ON–Monitor in the IBM Informix Dynamic
Server Administrator's Reference.

oncheck Utility
The oncheck utility displays information about the database disk configuration
and usage, such as the number of pages used for a table, the contents of the
reserved pages, and the number of extents in a table. For more information about
oncheck, see the IBM Informix Dynamic Server Administrator's Reference.

onperf Tool (UNIX)

The database server includes a graphical monitoring tool called onperf. This tool
can monitor most of the metrics that onstat provides. It provides the following
advantages over onstat:
v It displays the values of the metrics graphically in real time.
v It lets you choose which metrics to monitor.
v It saves recent-history metrics data to a buffer in memory. This data is available
if you want to analyze a recent trend.
v It can save performance data to a file.

For more information about the onperf tool, see your IBM Informix Dynamic Server
Performance Guide.

1-22 IBM Informix Dynamic Server Administrator’s Guide

onstat Utility
The onstat utility provides a way to monitor database server shared memory from
the command line. The onstat utility reads data from shared memory and reports
statistics that are accurate for the instant during which the command executes.
That is, onstat provides information that changes dynamically during processing,
including changes in buffers, locks, indexes, and users.

SMI Tables
The system-monitoring interface (SMI) tables are special tables managed by the
database server that contain dynamic information about the state of the database
server. You can use SELECT statements on them to determine almost anything you
might want to know about your database server. For a description of the SMI
tables, see the chapter about the sysmaster database in the IBM Informix Dynamic
Server Administrator's Reference.

System Console
The database server sends messages that are useful to the database server
administrator by way of the system console. To specify the destination pathname of
console messages, set the CONSOLE configuration parameter. For more
information about CONSOLE, see the chapter about configuration parameters in
the IBM Informix Dynamic Server Administrator's Reference.

The changes to CONSOLE take effect after you shut down and restart the database
server.

Windows Only

A database server system administrator can log in to the console from any node to
perform system management and monitoring tasks.
End of Windows Only

UNIX Operating-System Tools

The database server relies on the operating system of the host computer to provide
access to system resources such as the CPU, memory, and various unbuffered disk
I/O interfaces and files. Each operating system has its own set of utilities for
reporting how system resources are used. Different operating-systems might have
monitoring utilities with the same name but different options and informational
displays.

The following table shows typical UNIX operating-system resource-monitor

utilities. For information on how to monitor your operating-system resources,
consult your system administration guide.

UNIX Utility Description

vmstat Displays virtual-memory statistics
iostat Displays I/O utilization statistics
sar Displays a variety of resource statistics
ps Displays active process information
cron Captures the status of system resources by a system scheduler that runs
a command or program at regular intervals. You also can use other
scheduling tools that are available with your operating system.

Chapter 1. Installing and Configuring the Database Server 1-23

 Windows Event Viewer
The Event Viewer shows informational, warning, and error messages for the
operating system, other applications, and the database server.

To display database server messages on Windows:

1. Choose Administrative Tools > Event Viewer.
2. Choose Log > Security.
3. Double-click any event for a more detailed message.

Windows Performance Monitor

The Windows Performance Monitor ([Link]) monitors resources such as
processor, memory, cache, threads, and processes. The Performance Monitor also
provides charts, alerts, report capabilities, and the ability to save information to log
files for later analysis.

To display the Performance Monitor on Windows, choose Administrative Tools >

Performance Monitor.

Windows Utilities
The following Informix utilities simplify administration of the database server on
Windows.

Windows Utility Description and Usage

[Link] Changes the logon password for all services which log on as user informix. You can change
the password interactively or on the command line using the -y option. This utility saves
having to manually change the password for each service whenever you change the
informix password.

If you are logged on locally and run ixpasswd, it changes the password for services that
log on as the local informix user. If you are logged on domain and run ixpasswd, it changes
the password for services that log on as domain\informix.

Usage: ixpasswd [-y new_password]

[Link] Launches a command-line window that runs as the specified user. The user is a local user
unless you specify a domain name. If you do not specify a user name, the default user is
informix. You no longer need to log off as the current user and log on as informix to
perform DBA tasks that need to be run as informix.

The ixsu utility requires Advanced User Rights:

v Act as part of the operating system
v Increase quotas
v Replace a process-level token

To configure Advanced User Rights on Windows NT, select User Manager > Policies >
User Rights and check the Advanced User Rights option. If you change the Advanced User
Rights for the current user, you need to log off and log back on for the new rights to take
effect.

Usage: ixsu [[domain\]username]

The ixsu utility is equivalent to the Windows 2000 runas command. To use runas to run a
command shell as another user:

Usage: runas /user:username cmd

1-24 IBM Informix Dynamic Server Administrator’s Guide

Windows Utility Description and Usage
[Link] Changes the registry entries for Dynamic Server from the old hostname to the new
hostname. Run ntchname after you change the hostname. This utility does not change user
environment variables.

After you execute ntchname, edit the %INFORMIXDIR%\%INFORMIXSERVER%.cmd

file and change the INFORMIXSQLHOSTS entry to the new hostname.

Usage: ntchname old_name new_name

Chapter 1. Installing and Configuring the Database Server 1-25

1-26 IBM Informix Dynamic Server Administrator’s Guide
Chapter 2. Configuration Parameters
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Database Server Identification Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-1
Disk-Space Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Mirror of Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2
Other Space-Management Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Logging Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3
Physical Log Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Rollback and Recovery Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Backup and Restore Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Message-Log Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4
Shared-Memory Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Shared-Memory Size Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Shared-Memory Space Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-5
Shared-Memory Buffer Control . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
SQL Statement Cache Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Decision-Support Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6
Database Server Process Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Virtual Processor Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7
Time Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
Restore Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-8
High-Availability Data-Replication Parameters . . . . . . . . . . . . . . . . . . . . . . . 2-8
Event-Alarm Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Dump Parameters (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Directives Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9
Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Security-Related Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Specialized Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Auditing Parameters (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-10
Optical Media Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
UNIX Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11
Monitoring Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

In This Chapter
This chapter provides an overview of the ONCONFIG configuration parameters
that the database server uses and describes different ways of monitoring
configuration information. The chapter can help you decide which parameters are
most crucial for your particular environment and which parameters you can defer
until you are tuning the performance of your database server. For details on each
parameter, see the chapter on configuration parameters in the IBM Informix
Dynamic Server Administrator's Reference.

Database Server Identification Parameters

Use the SERVERNUM and DBSERVERNAME parameters to provide unique
identification for each instance of the database server.

© Copyright IBM Corp. 1996, 2005 2-1

Configuration Parameter Description
DBSERVERALIASES Specifies an alternate name or names for an instance of the database server. The
maximum number of aliases is 32.

For information about using DBSERVERALIASES to create multiple listen endpoints to

which clients can connect, see “Specifying Listen and Poll Threads for the Client/Server
Connection” on page 6-22.

Warning: Do not change the DBSERVERNAME configuration parameter without

restarting the database server.
DBSERVERNAME Specifies the unique name of an instance of the database server. Use the
DBSERVERNAME for your INFORMIXSERVER environment variable and in the
sqlhosts information.
SERVERNUM Specifies a unique integer for the database server instance. The database server uses
SERVERNUM to determine the shared-memory segment addresses.

Disk-Space Parameters
The disk-space parameters control how the database server manages storage space.

Root Dbspace
The first storage space that you allocate is called the root database space, or root
dbspace. It stores all the basic information that describes your database server. Use
the following parameters to describe the root dbspace.

Configuration Parameter Description

ROOTNAME Specifies the name of the root dbspace. You can choose any descriptive name for
ROOTNAME, but it is usually called rootdbs. For more information, see “Root
Dbspace” on page 10-11.
ROOTOFFSET Specifies an offset. For information about when to set ROOTOFFSET, see “Specifying an
Offset” on page 11-3.
ROOTPATH Specifies the pathname of the storage allocated to the root dbspace. For information on
how to choose and allocate the storage, see “Allocating Disk Space” on page 11-3.
ROOTSIZE Specifies the amount of space allocated to the root dbspace. For information on how to
choose an appropriate size for the root dbspace, see “Size of the Root Dbspace” on page
10-31.
TBLTBLFIRST Specifies the first extent size of tblspace tblspace in kilobytes.
TBLTBLNEXT Specifies the next extent size of tblspace tblspace in kilobytes

Mirror of Root Dbspace

Mirroring allows fast recovery from a disk failure while the database server
remains in online mode. When mirroring is active, the same data is stored on two
disks simultaneously. If one disk fails, the data is still available on the other disk.
Use the following parameters to describe mirroring of the root dbspace.

Configuration Parameter Description

MIRROR Defines whether mirroring is enabled or disabled. For more information, see Chapter 19,
“Using Mirroring,” on page 19-1.
MIRRORPATH Specifies the full pathname of the chunk that mirrors the initial chunk of the root
dbspace.

2-2 IBM Informix Dynamic Server Administrator’s Guide

Configuration Parameter Description
MIRROROFFSET Specifies the offset into the device that serves as the mirror for the initial root dbspace
chunk. For more information, see “Specifying an Offset” on page 11-3.

Other Space-Management Parameters

Use the following parameters to specify how the database server should manage
particular types of disk space.

Configuration Parameter Description

DBSPACETEMP Specifies a list of dbspaces that the database server can use for the storage of temporary
tables. For more information, see “Creating a Temporary Dbspace” on page 11-15.
FILLFACTOR Specifies how much to fill index pages when indexes are created. For more information,
see your IBM Informix Dynamic Server Performance Guide.
ONDBSPACEDOWN Defines how the database server treats a disabled dbspace that is not a critical dbspace.
SBSPACENAME Specifies the name of the default sbspace. For more information, see “Control of Where
Data Is Stored” on page 10-9..
SBSPACETEMP Specifies the name of the default temporary sbspace. For more information, see
“Temporary Sbspaces” on page 10-19..
SYSSBSPACENAME Specifies the name of the sbspace in which the database server stores statistics that the
UPDATE STATISTICS statement collects for certain user-defined data types.

Logging Parameters
Use the logging parameters to control the logical and physical logs.

Logical Log
The logical log contains a record of changes made to a database server instance.
The logical-log records are used to roll back transactions, recover from system
failures, and so on. The following parameters describe logical logging.

Configuration Parameter Description

DYNAMIC_LOGS Determines whether the database server allocates new logical-log files automatically. For
more information, see Chapter 14, “Logical Log,” on page 14-1.
LOGBUFF Determines the amount of shared memory reserved for the buffers that hold the
logical-log records until they are flushed to disk. For information on how to tune the
logical-log buffer, see “Logical-Log Buffer” on page 8-11.
LOGFILES Specifies the number of logical-log files used to store logical-log records until they are
backed up on disk. For more information, see “Estimating the Size and Number of Log
Files” on page 15-2.
LOGSIZE Specifies the size of each logical-log file.
LTXHWM Specifies the percentage of the available logical-log space that, when filled, triggers the
database server to check for a long transaction. For more information, see “Setting
High-Watermarks for Rolling Back Long Transactions” on page 15-15.
LTXEHWM Specifies the point at which the long transaction being rolled back is given exclusive
access to the logical log.

Chapter 2. Configuration Parameters 2-3

 Physical Log Parameters
The physical log contains images of all pages (units or storage) changed since the
last checkpoint. The physical log combines with the logical log to allow fast
recovery from a system failure. Use the following parameters to describe the
physical log.

Configuration Parameter Description

PHYSBUFF Determines the amount of shared memory reserved for the buffers that serve as
temporary storage space for pages about to be modified.
PHYSDBS Specifies the name of the dbspace in which the physical log resides.
PHYSFILE Specifies the size of the physical log.

Rollback and Recovery Parameters

Information on using the following parameters, which affect rollback and recovery,
is in the IBM Informix Dynamic Server Performance Guide. Also see Chapter 16,
“Physical Logging, Checkpoints, and Fast Recovery,” on page 16-1.

Configuration Parameter Description

FAST_RESTART_CKPT Enables the flushing of dirty-pages table (DPT) records to the physical log on fuzzy
_FUZZYLOG checkpoints at checkpoint during the roll-forward phase of recovery. Like
FAST_RESTART_PHYSLOG, this parameter reduces recovery time.
FAST_RESTART_ Enables the database server to perform physical logging on fuzzy pages while the
PHYSLOG server is running normally. Like FAST_RESTART_CKPT_FUZZYLOG, this parameter
reduces recovery time.

Backup and Restore Parameters

Use ON–Bar or ontape to create storage-space and logical-log backups of database
server data. To verify storage-space backups, use ON–Bar. For more information on
ON–Bar and ontape, see the IBM Informix Backup and Restore Guide.

If you use the ontape utility, use the following parameters to describe your tape
devices. To use a tape to its full physical capacity, set TAPESIZE and LTAPESIZE to
0 to read/write to the end of the medium.

Configuration Parameter Description

TAPEDEV Specifies tape devices.
TAPEBLK Specifies the block size of the tape device.
TAPESIZE Specifies the maximum amount of data that should be written to each tape.
LTAPEDEV Specifies tape devices.
LTAPEBLK Specifies the block size of the tape device.
LTAPESIZE Specifies the maximum amount of data that should be written to each tape.

Message-Log Parameters
The message files provide information about how the database server is
functioning.

2-4 IBM Informix Dynamic Server Administrator’s Guide

Configuration Parameter Description
CONSOLE (UNIX) Specifies the pathname for console messages. For additional information, see “System
Console” on page 1-23.
MSGPATH Specifies the pathname of the database server message-log file. For more information,
see “Message Log” on page 1-21.

Shared-Memory Parameters
The shared-memory parameters affect database server performance.

Shared-Memory Size Allocation

Use the following parameters to control how and where the database server
allocates shared memory.

Configuration Parameter Description

EXTSHMADD Specifies the size of an added extension segment.
SHMADD Specifies the increment of memory that is added when the database server requests
more memory.
SHMBASE Specifies the shared-memory base address and is computer dependent. The value
depends on the platform and whether the processor is 32-bit or 64-bit. For information
on which SHMBASE value to use, see the machine notes.
SHMTOTAL Specifies the maximum amount of memory that the database server is allowed to use.
SHMVIRTSIZE Specifies the size of the first piece of memory that the database server attaches.

For more information on these parameters, see Chapter 8, “Shared Memory,” on

page 8-1.

For platform-specific information on these database server shared-memory

configuration parameters, see your machine notes file on UNIX or your release
notes file on Windows.

Shared-Memory Space Allocation

Use the following parameters to control how space is allocated in shared memory.

Configuration Parameter Description

BUFFERPOOL Specifies information about the buffer pool that must be defined for each different
page size that a dbspace uses. See “Creating a Dbspace with a Non-Default Page
Size” on page 11-11.

Information that was specified with the BUFFERS, LRUS, LRU_MAX_DIRTY, and
LRU_MIN_DIRTY configuration parameters prior to Version 10.0 is now specified
using the BUFFERPOOL configuration parameter.
CKPTINTVL Specifies the maximum time interval allowed to elapse before a checkpoint. For
more information, see Chapter 16, “Physical Logging, Checkpoints, and Fast
Recovery,” on page 16-1.
DD_HASHMAX Specifies the maximum number of entries for each hash bucket in the
data-dictionary cache. For more information about setting DD_HASHMAX, see your
IBM Informix Performance Guide.
DD_HASHSIZE Specifies the number of hash buckets in the data-dictionary cache. For more
information about setting DD_HASHSIZE, see your IBM Informix Performance Guide.

Chapter 2. Configuration Parameters 2-5

Configuration Parameter Description
DEF_TABLE_ Sets the lock mode to page or row for new tables. For more information, see the
LOCKMODE IBM Informix Guide to SQL: Tutorial.
LOCKS Specifies the initial number of locks available to database server user processes
during transaction processing. For more information, see Chapter 9, “Managing
Shared Memory,” on page 9-1 and your IBM Informix Dynamic Server Performance
Guide.
PC_POOLSIZE Specifies the number of UDRs (both SPL routines and external routines) that can be
stored in the UDR cache. For more information about setting PC_POOLSIZE, see
your IBM Informix Dynamic Server Performance Guide.
PC_HASHSIZE Specifies the number of hash buckets for the UDR cache. For more information
about setting PC_HASHSIZE, see your IBM Informix Dynamic Server Performance
Guide.
RESIDENT Specifies whether shared-memory residency is enforced. For more information, see
Chapter 9, “Managing Shared Memory,” on page 9-1 and your IBM Informix
Dynamic Server Performance Guide.
STACKSIZE Specifies the stack size for database server user threads. For a discussion of the use
of stacks, see “Stacks” on page 8-18.

Shared-Memory Buffer Control

Use the following parameters to control the shared-memory buffer pool.

Configuration Parameter Description

CLEANERS Controls the number of threads used to flush pages to disk and return the pages to
the shared-memory pool. See “Flushing Data to Disk” on page 8-26.
RA_PAGES and Control the number of disk pages that the database server reads ahead during
RA_THRESHOLD sequential scans. See “Configuring the Database Server to Read Ahead” on page
8-25.

SQL Statement Cache Usage

Use the following parameters to configure the SQL statement cache. For more
information, see “Setting SQL Statement Cache Parameters” on page 9-6.

Configuration Parameter Description

STMT_CACHE Turns on, enables, or disables the SQL statement cache in memory. If turned on,
specifies whether the SQL statement cache can hold a parsed and optimized SQL
statement.
STMT_CACHE_SIZE Specifies the size of the SQL statement cache.
STMT_CACHE_HITS Specifies the number of hits (references) to a statement before it is fully inserted into
the SQL statement cache.
STMT_CACHE_NOLIMIT Controls whether to insert statements into the SQL statement cache after its size is
greater than the STMT_CACHE_SIZE value.
STMT_CACHE_NUMPOOL Defines the number of memory pools for the SQL statement cache.

Decision-Support Parameters
When you configure virtual shared memory on your system, you must decide
what portion to reserve for decision-support queries. Decision-support queries use
large amounts of the virtual portion of shared memory to perform joins and sort
operations.
2-6 IBM Informix Dynamic Server Administrator’s Guide
 Use the following parameters to control how decision-support queries are
processed and to control the amount of memory that the database server allocates
to decision-support queries. For more information about tuning these configuration
parameters, see your IBM Informix Dynamic Server Performance Guide.

Configuration Parameter Description

DATASKIP Controls whether the database server skips an unavailable table fragment.
DS_MAX_QUERIES Specifies the maximum number of queries that can run concurrently.
DS_MAX_SCANS Limits the number of Parallel Database Query (PDQ) scan threads that the
database server can execute concurrently.
DS_TOTAL_MEMORY Specifies the amount of memory available for PDQ queries.

Set the DS_TOTAL_MEMORY configuration parameter to any value not greater

than the quantity (SHMVIRTSIZE - 10 megabytes).
DS_NONPDQ_QUERY_MEM Enables you to increase the amount of memory that is available for a query that is
not a PDQ query.
MAX_PDQPRIORTY Limits the amount of resources that a query can use.
OPTCOMPIND Advises the optimizer on an appropriate join strategy for your applications.

Database Server Process Parameters

Configuration parameters for database server processes describe the type of
processors on your computer and specify the behavior of virtual processes.

Virtual Processor Parameters

Use the following parameters to specify the type of processors in your
environment and to allocate the virtual processors.

You need to set the following parameters to specific values, depending upon the
number of processors on your platform:
v MULTIPROCESSOR
v SINGLE_CPU_VP
v VPCLASS

For guidelines on setting these parameters, see “Setting Virtual-Processor

Configuration Parameters” on page 7-1.

Configuration Parameter Description

MULTIPROCESSOR Specifies the appropriate type of locking.
NETTYPE Provides tuning options for each communications protocol.
SINGLE_CPU_VP Specifies that the database server is using only one processor and allow the database
server to optimize for that situation.
VPCLASS Specifies a class of virtual processors, the number of virtual processors that the database
server should start, the maximum number allowed, the processor affinity, and the
priority aging. You should use the VPCLASS parameter instead of NOAGE,
NUMCPUVPS, NUMAIOVPS, AFF_NPROCS, or AFF_SPROCS. For more information,
see “Specifying VPCLASS” on page 7-2.

Chapter 2. Configuration Parameters 2-7

 Time Intervals
Use the following parameters to control the time intervals that the database server
uses while processing transactions.

Configuration Parameter Description

DEADLOCK_TIMEOUT Specifies the amount of time that the database server waits for a shared-memory
resource during a distributed transaction.
HETERO_COMMIT Specifies whether the database server uses heterogeneous commit transactions.
TXTIMEOUT Specifies how long a participant waits to receive a commit instruction during a
two-phase commit.
USEOSTIME Controls the granularity of time reported by the database server.

Restore Parameters
Use the following parameters to control the number of threads that the database
server allocates to offline and online logical recovery. For more information, see
your IBM Informix Dynamic Server Performance Guide.

Configuration Parameter Description

OFF_RECVRY_THREADS Specifies the number of recovery threads used during a cold restore.
ON_RECVRY_THREADS Specifies the number of recovery threads used during fast recovery and a warm
restore.

High-Availability Data-Replication Parameters

Use the High-Availability Data-replication (HDR) parameters to control the
behavior of a pair of HDR servers. For more information, see Chapter 20,
“High-Availability Data Replication (Enterprise/Workgroup Editions),” on page
20-1.

Configuration Parameter Description

DRIDXAUTO Specifies whether the primary High-Availability Data Replication (HDR) server
automatically starts index replication if the secondary HDR server detects a corrupted
index.
DRAUTO Defines how a secondary database server reacts to an HDR failure.
DRINTERVAL Specifies the maximum time interval in seconds between flushing of the
data-replication buffer.
DRLOSTFOUND Specifies the pathname to a file that contains transactions committed on the primary
database server but not committed on the secondary database server when the
primary database server experiences a failure.
DRTIMEOUT Specifies how long in seconds a database server in a data-replication pair waits for a
transfer acknowledgment from the other database server in the pair.

2-8 IBM Informix Dynamic Server Administrator’s Guide

Event-Alarm Parameters
The database server can execute a program that operates either whenever certain
noteworthy event alarms occur or every time any event alarm occurs. Noteworthy
event alarms include failure of a database, table, index, chunk or dbspace taken
offline, internal subsystem failure, start-up failure, and detection of long
transaction. You can receive notification of an event alarm through email or
pagermail.

Use the following parameters to specify:

v Whether the event-alarm program operates for all or only certain events alarms
v What actions to take when alarm events occur

Configuration Parameter Description

ALRM_ALL_EVENTS Specifies whether ALARMPROGRAM runs for all events that are logged in the
MSGPATH or only specified noteworthy events.
ALARMPROGRAM Specifies the location of a file that is executed when an event alarm occurs.

You can set the ALARMPROGRAM parameter to back up logs automatically as they
fill. For more information, see the IBM Informix Backup and Restore Guide.

For more information, see your Administrator’s Reference.

Dump Parameters (UNIX)

Use the following parameters to control the types and location of core dumps that
are performed if the database server fails. For more information, see “Monitoring
for Data Inconsistency” on page 22-3.

Configuration Parameter Description

DUMPCNT Specifies the number of assertion failures for which a single thread dumps shared
memory.
DUMPCORE Controls whether assertion failures cause a virtual processor to dump core memory.
DUMPDIR Specifies a directory where the database server places dumps of shared memory, gcore
files, or messages from a failed assertion.
DUMPGCORE If your operating system supports the gcore utility, an assertion failure causes the
database server to call gcore.
DUMPSHMEM Specifies that shared memory should be dumped on an assertion failure.

Directives Parameters
You can use the following configuration parameters to turn on or off directives that
the database server encounters.

Configuration Parameter Description

DIRECTIVES Determines whether the optimizer follows all directives. The default value is 1,
indicating the optimizer follows all directives. For more information, see the IBM
Informix Dynamic Server Performance Guide.
EXT_DIRECTIVES Enables an external directive. For more information, see the IBM Informix Dynamic
Server Administrator's Reference or the IBM Informix Dynamic Server Performance Guide.

Chapter 2. Configuration Parameters 2-9

Connection Parameters
Use the following parameters to configure connectivity use to reduce the
incomplete connection timeout period and restrict the number of incomplete
requests for connections, thus reducing the risk of a hostile, denial-of-service (DOS)
flood attack. For more information, see “Limiting Denial-of-Service Flood Attacks”
on page 5-7.

Configuration Parameter Description

LISTEN_TIMEOUT Sets the incomplete connection timeout period. The default value is 10 seconds.
MAX_INCOMPLETE_ Restricts the number of incomplete requests for connections. The default value is 1024.
CONNECTIONS

Security-Related Parameters
The following security-related parameters are discussed more fully in Chapter 5,
“Security.”

Configuration Parameter Description

DBCREATE_PERMISSION Gives permission to a specified user to create databases, thus restricting other users
from creating databases.
DB_LIBRARY_PATH Enables a database server administrator (DBSA) to specify a comma-separated list of
valid directory prefix locations from which the database server can load external
modules.
IFX_EXTEND_ROLE Enables a DBSA to prevent unauthorized users from registering DataBlade
user-defined routines (UDRs).
SECURITY_ Enables a DBSA to set up security checking for local connections with the same host.
LOCALCONNECTION
UNSECURE_ONSTAT Removes the restriction that only allows DBA users to execute onstat -ses, onstat -stm,
onstat -ssc, and onstat -sql commands.

Specialized Parameters
Some parameters appear in the configuration file only when you use specialized
features of the database server.

Auditing Parameters (UNIX)

Use the auditing parameters only when you use the database server auditing
features. The IBM Informix Trusted Facility Guide describes these parameters.

Configuration Parameter Description

ADTERR Specifies how the database server behaves when it encounters an error while it writes
an audit record.
ADTMODE Controls whether the database server or the operating system manages auditing of
user actions.
ADTPATH Specifies the directory in which the database server can save audit files.
ADTSIZE Specifies the maximum size of an audit file.

2-10 IBM Informix Dynamic Server Administrator’s Guide

 Optical Media Parameters
Use the following configuration parameters when you use the Optical Subsystem.
For more information about these parameters, see the IBM Informix Optical
Subsystem Guide.

Configuration Parameter Description

OPCACHEMAX Specifies the size of the memory cache.
STAGEBLOB Specifies the name of the blobspace for storing simple large objects that are destined
for optical disk.

IBM Informix Storage Manager allows you to back up information to optical

media, but it does not allow the database server to access directly the data that is
stored on the disks.

UNIX Parameters
Some UNIX platforms have additional configuration parameters. For a description
of these specialized parameters and instructions on using them, see your machine
notes.

Monitoring Configuration Information

One of the tasks of the database server administrator is to keep records of the
configuration. Table 2-1 describes methods of obtaining configuration information.
Table 2-1. Monitoring Configuration Information
Command Description
onstat -c Displays a copy of the ONCONFIG file. For more information, see “Configuring the Database
Server” on page 1-11. Changes to the ONCONFIG file take effect when you shut down and
restart the database server, also called reinitializing shared memory. If you change a configuration
parameter but do not shut down and restart the database server, the effective configuration
differs from what the onstat -c option displays. The values of the configuration parameters are
stored in the file indicated by the ONCONFIG environment variable or, if you have not set the
ONCONFIG environment variable, in $INFORMIXDIR/etc/onconfig on UNIX or
%INFORMIXDIR%\etc\[Link] on Windows.
oncheck -pr Lists the reserved page. The database server also stores current configuration information in the
PAGE_CONFIG reserved page. If you change the configuration parameters from the command
line and run oncheck -pr without shutting down and restarting the database server, the
configuration values that oncheck displays do not match the current values in the reserved
pages. The oncheck utility returns a warning message.
ON–Monitor Select Status > Configuration to create a copy of the current configuration and store it in the
(UNIX) directory and file that you specify. If you specify only a filename, the database server stores the
file in the current working directory. Changes to the configuration parameters take effect when
you shut down and restart the database server.
ISA Displays or updates the configuration parameters.

Figure 2-1 shows sample output from the oncheck -pr command.

Chapter 2. Configuration Parameters 2-11

 ...

Validating Informix database server reserved pages - PAGE_CONFIG

ROOTNAME rootdbs
ROOTPATH /home/dyn_srv/root_chunk
ROOTOFFSET 0
ROOTSIZE 8000
MIRROR 0
MIRRORPATH
MIRROROFFSET 0
PHYSDBS rootdbs
PHYSFILE 1000
LOGFILES 5
LOGSIZE 500
MSGPATH /home/dyn_srv/[Link]
CONSOLE /dev/ttyp5
... ...

Figure 2-1. PAGE_CONFIG Reserved Page

2-12 IBM Informix Dynamic Server Administrator’s Guide

Chapter 3. Client/Server Communications
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Client/Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Network Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2
Network Programming Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Windows Network Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3
Database Server Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Multiplexed Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4
Connections That the Database Server Supports . . . . . . . . . . . . . . . . . . . . . . . 3-5
Local Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Shared-Memory Connections (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . 3-6
Stream-Pipe Connections (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Named-Pipe Connections (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Local-Loopback Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7
Communication Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Connectivity Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Network-Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
TCP/IP Connectivity Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-8
Multiple TCP/IP Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10
IPX/SPX Connectivity Files (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
Network Security Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
The [Link] File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-11
The netrc Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-12
The sqlhosts File and the SQLHOSTS Registry Key . . . . . . . . . . . . . . . . . . . . 3-13
The sqlhosts File (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13
Tools for Updating SQLHOSTS Information . . . . . . . . . . . . . . . . . . . . . . 3-13
The SQLHOSTS Registry Key (Windows) . . . . . . . . . . . . . . . . . . . . . . . 3-14
The sqlhosts Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15
Connectivity Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Database Server Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
The Connection Type Field . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-16
Host Name Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-18
Service Name Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-19
Options Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-20
Group Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Database Server Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Alternatives for TCP/IP Connections . . . . . . . . . . . . . . . . . . . . . . . . . 3-25
IP Addresses for TCP/IP Connections . . . . . . . . . . . . . . . . . . . . . . . . 3-25
Wildcard Addressing for TCP/IP Connections . . . . . . . . . . . . . . . . . . . . . 3-26
Port Numbers for TCP/IP Connections . . . . . . . . . . . . . . . . . . . . . . . 3-28
Dynamic Server Support for IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . 3-28
ONCONFIG Parameters for Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . 3-29
DBSERVERNAME Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . . 3-29
DBSERVERALIASES Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . 3-30
NETTYPE Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 3-30
Environment Variables for Network Connections . . . . . . . . . . . . . . . . . . . . . . 3-31
Examples of Client/Server Configurations . . . . . . . . . . . . . . . . . . . . . . . . 3-31
Using a Shared-Memory Connection (UNIX) . . . . . . . . . . . . . . . . . . . . . . . 3-31
Using a Local-Loopback Connection . . . . . . . . . . . . . . . . . . . . . . . . . 3-32
Using a Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-33
The sqlhosts File Entry for IPX/SPX (UNIX) . . . . . . . . . . . . . . . . . . . . . . 3-33
Using Multiple Connection Types . . . . . . . . . . . . . . . . . . . . . . . . . . 3-34
Accessing Multiple Database Servers . . . . . . . . . . . . . . . . . . . . . . . . . 3-35

© Copyright IBM Corp. 1996, 2005 3-1

Using IBM Informix MaxConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-35

In This Chapter
This chapter explains the concepts and terms that you need to understand in order
to configure client/server communications. The chapter consists of the following
parts:
v Description of client/server architecture
v Database server connection types
v Communication services
v Connectivity files
v ONCONFIG connectivity parameters
v Connectivity environment variables
v Examples of client/server configurations

Client/Server Architecture
IBM Informix products conform to a software design model called client/server. The
client/server model allows you to place an application or client on one computer
and the database server on another computer, but they can also reside on the same
computer. Client applications issue requests for services and data from the
database server. The database server responds by providing the services and data
that the client requested.

You use a network protocol together with a network programming interface to connect
and transfer data between the client and the database server. The following
sections define these terms in detail.

Network Protocol
A network protocol is a set of rules that govern how data is transferred between
applications and, in this context, between a client and a database server. These
rules specify, among other things, what format data takes when it is sent across the
network. An example of a network protocol is TCP/IP.

The rules of a protocol are implemented in a network-protocol driver. A

network-protocol driver contains the code that formats the data when it is sent
from client to database server and from database server to client.

Clients and database servers gain access to a network driver by way of a network
programming interface. A network programming interface contains system calls or
library routines that provide access to network-communications facilities. An
example of a network programming interface for UNIX is TLI (Transport Layer
Interface). An example of a network programming interface for Windows is
WINSOCK (sockets programming interface).

The power of a network protocol lies in its ability to enable client/server

communication even though the client and database server reside on different
computers with different architectures and operating systems.

You can configure the database server to support more than one protocol, but
consider this option only if some clients use TCP/IP and some use IPX/SPX.

To determine the supported protocols for your operating system, see “Database
Server Connection” on page 3-4.

3-2 IBM Informix Dynamic Server Administrator’s Guide

 To specify which protocol the database server uses, set the nettype field in the
sqlhosts file on UNIX. On Windows, set the PROTOCOL field in the SQLHOSTS
registry key. For more information, see “The sqlhosts File and the SQLHOSTS
Registry Key” on page 3-13.

Network Programming Interface

A network programming interface is an application programming interface (API)
that contains a set of communications routines or system calls. An application can
call these routines to communicate with another application that resides on the
same or on different computers. In the context of this discussion, the client and the
database server are the applications that call the routines in the TLI or sockets API.
Clients and database servers both use network programming interfaces to send
and receive the data according to a communications protocol.

Both client and database server environments must be configured with the same
protocol if client/server communication is to succeed. However, some network
protocols can be accessed through more than one network programming interface.
For example, TCP/IP can be accessed through either TLI or sockets, depending on
which programming interface is available on the operating-system platform.
Therefore, a client using TCP/IP through TLI on one computer can communicate
with a database server using TCP/IP with sockets on another computer, or vice
versa. For an example, see “Using a Network Connection” on page 3-33.

Windows Network Domain

Windows network technology enables you to create network domains. A domain is
a group of connected Windows computers that share user account information and
a security policy. A domain controller manages the user account information for all
domain members.

The domain controller facilitates network administration. By managing one account

list for all domain members, the domain controller relieves the network
administrator of the requirement to synchronize the account lists on each of the
domain computers. In other words, the network administrator who creates or
changes a user account needs to update only the account list on the domain
controller rather than the account lists on each of the computers in the domain.

To log in to a Windows database server, a user on another Windows computer

must belong to either the same domain or a trusted domain. A trusted domain is
one that has established a trust relationship with another domain. In a trust
relationship, user accounts are located only in the trusted domain, but users can
log on to the trusted domain.

A user who attempts to log in to a Windows computer that is a member of a

domain can do so either by using a local login and profile or a domain login and
profile. However, if the user is listed as a trusted user or the computer from which
the user attempts to log in is listed as a trusted host, the user can be granted login
access without a profile.

Important: A client application can connect to an Informix database server only if

there is an account for the user ID in the Windows domain in which
the database server runs. This rule also applies to trusted domains.

For more information on domains, consult your Windows operating system

manuals.

Chapter 3. Client/Server Communications 3-3

 Important: The Informix trusted client mechanism is unrelated to the trust
relationship that you can establish between Windows domains.
Therefore, even if a client connects from a trusted Windows domain,
the user must have an account in the domain on which the database
server is running. For more information on how the database server
authenticates clients, see “Communication Support Services” on page
3-8 and “Network Security Files” on page 3-11.

Database Server Connection

A connection is a logical association between two applications; in this context,
between a client application and a database server. A connection must be
established between client and database server before data transfer can take place.
In addition, the connection must be maintained for the duration of the transfer of
data.

Tip: The Informix internal communications facility is called Association Services

Facility (ASF). If you see an error message that refers to ASF, you have a
problem with your connections.

A client application establishes a connection to a database server with either the

CONNECT or DATABASE SQL statement. For example, to connect to the database
server my_server, an application might contain the following form of the
CONNECT statement:
CONNECT TO ’@my_server’

For more information on the CONNECT and DATABASE statements, see the IBM
Informix Guide to SQL: Syntax.

Multiplexed Connection
Some applications connect multiple times to the same database server on behalf of
one user. A multiplexed connection uses a single network connection between the
database server and a client to handle multiple database connections from the client.
Client applications can establish multiple connections to a database server to access
more than one database on behalf of a single user. If the connections are not
multiplexed, each database connection establishes a separate network connection to
the database server. Each additional network connection consumes additional
computer memory and CPU time, even for connections that are not active.
Multiplexed connections enable the database server to create multiple database
connections without consuming the additional computer resources that are
required for additional network connections.

To configure the database server to support mulitplexed connections, you must

include in the ONCONFIG file a special NETTYPE parameter that has a value of
sqlmux, as in the following example:
NETTYPE sqlmux

To configure the automatic use of multiplexed connections by clients, the entry in

the sqlhosts file or registry that the client uses for the database server connection
must specify the value of m=1 in the options field, as in the following example:
menlo ontlitcp valley jfk1 m=1

You do not need to make any changes to the sqlhosts file or registry that the
database server uses. The client program does not need to make any special SQL
calls to enable connections multiplexing. Connection multiplexing is enabled

3-4 IBM Informix Dynamic Server Administrator’s Guide

 automatically when the ONCONFIG file and the sqlhosts file or SQLHOSTS
registry key are configured appropriately. For information on the NETTYPE
configuration parameter, see the chapter on configuration parameters in the IBM
Informix Dynamic Server Administrator's Reference. For more information on the
sqlhosts file or registry, see “The sqlhosts File and the SQLHOSTS Registry Key”
on page 3-13.

The following limitations apply to multiplexed connections:

v Multithreaded client connections are not supported.
v Shared-memory connections are not supported.
v Connections to subordinate database servers (for distributed queries or data
replication, for example) are not multiplexed.
v The ESQL/C sqlbreak() function is not supported.
v You can activate database server support for multiplexed connections only when
the database server starts.

If any of these conditions exist when an application attempts to establish a

connection, the database server establishes a standard connection. The database
server does not return an SQL error.

Connections That the Database Server Supports

The database server supports the following types of connections to communicate
between client applications and a database server.

Connection Type Windows UNIX Local Network

Sockets X X X X
TLI (TCP/IP) X X X
TLI (IPX/SPX) X X X
Shared memory X X
Stream pipe X X
Named pipe X X

Note: When configuring connectivity, consider setting the IFX_LISTEN_TIMEOUT

and MAX_INCOMPLETE_CONNECTION configuration parameters. These
parameters enable you to reduce the risk of a hostile denial-of-service (DOS)
attack by making it more difficult to overwhelm the Listener VP that
handles connections. For more information, see “Limiting Denial-of-Service
Flood Attacks” on page 5-7.

UNIX Only

On many UNIX platforms, the database server supports multiple network

programming interfaces. The machine notes shows the interface/protocol
combinations that the database server supports for your operating system:
Machine Specific Notes:
=======================

1. The following interface/protocol combinations(s) are

supported for this platform:

Berkeley sockets using TCP/IP

Chapter 3. Client/Server Communications 3-5

 End of UNIX Only

To set up a client connection:

1. Specify connectivity and connection configuration parameters in your
ONCONFIG file.
2. Set up appropriate entries in the connectivity files on your platform.
3. Specify connectivity environment variables in your UNIX start-up scripts or the
local and domainwide Windows registries.
4. Define a dbserver group for your database server in the sqlhosts file or
registry.

The following sections describe database server connection types in more detail.
For detailed information about implementing the connections described in the
following sections, see the following topics:
v “Connectivity Files” on page 3-8
v “The sqlhosts Information” on page 3-15
v “ONCONFIG Parameters for Connectivity” on page 3-29
v “Environment Variables for Network Connections” on page 3-31

Local Connections
A local connection is a connection between a client and the database server on the
same computer. The following sections describe these types of local connections.

Shared-Memory Connections (UNIX)

A shared-memory connection uses an area of shared-memory as the channel through
which the client and database server communicate with each other. Figure 3-1
illustrates a shared-memory connection.

Shared
Database server
memory

Client
application

Computer

Figure 3-1. A Shared-Memory Connection

Shared memory provides fast access to a database server, but it poses some
security risks. Errant or malicious applications could destroy or view message
buffers of their own or of other local users. Shared-memory communication is also
vulnerable to programming errors if the client application performs explicit
memory addressing or overindexes data arrays. Such errors do not affect the
database server if you use network communication or stream pipes. For an
example of a shared-memory connection, see “Using a Shared-Memory Connection
(UNIX)” on page 3-31.

3-6 IBM Informix Dynamic Server Administrator’s Guide

 A client cannot have more than one shared-memory connection to a database
server.

For information about the portion of shared memory that the database server uses
for client/server communications, see “Communications Portion of Shared
Memory (UNIX)” on page 8-20. For additional information, you can also see “How
a Client Attaches to the Communications Portion (UNIX)” on page 8-6.

Stream-Pipe Connections (UNIX)

A stream pipe is a UNIX interprocess communication (IPC) facility that allows
processes on the same computer to communicate with each other. You can use
stream-pipe connections any time that the client and the database server are on the
same computer. For more information, see “Network Protocol Entry” on page 3-17
and “Shared-Memory and Stream-Pipe Communication (UNIX)” on page 3-18.

Stream-pipe connections have the following advantages:

v Unlike shared-memory connections, stream pipes do not pose the security risk of
being overwritten or read by other programs that explicitly access the same
portion of shared memory.
v Unlike shared-memory connections, stream-pipe connections allow distributed
transactions between database servers that are on the same computer.

Stream-pipe connections have the following disadvantages:

v Stream-pipe connections might be slower than shared-memory connections on
some computers.
v Stream pipes are not available on all platforms.
v When you use shared memory or stream pipes for client/server
communications, the hostname entry is ignored.

Named-Pipe Connections (Windows)

Named pipes are application programming interfaces (APIs) for bidirectional
interprocess communication (IPC) on Windows. Named-pipe connections provide a
high-level interface to network software by making transport-layer operations
transparent. Named pipes store data in memory and retrieve it when requested, in
a way that is similar to reading from and writing to a file system.

Named pipes are supported for local connections to the database server.

Local-Loopback Connections
A network connection between a client application and a database server on the
same computer is called a local-loopback connection. The networking facilities used
are the same as if the client application and the database server were on different
computers. You can make a local-loopback connection provided your computer is
equipped to process network transactions. Local-loopback connections are not as
fast as shared-memory connections, but they do not pose the security risks of
shared memory.

In a local-loopback connection, data appears to pass from the client application,

out to the network, and then back in again to the database server. In fact, although
the database server uses the network programming interface (TLI or sockets), the
internal connection processes send the information directly between the client and
the database server and do not put the information out on the network.

Chapter 3. Client/Server Communications 3-7

 For an example of a local-loopback connection, see “Using a Local-Loopback
Connection” on page 3-32.

Communication Support Services

Communication support services include connectivity-related services such as the
following security services:
v Authentication is the process of verifying the identity of a user or an application.
The most common form of authentication is to require the user to enter a name
and password to obtain access to a computer or an application.
v Message integrity ensures that communication messages are intact and unaltered
when they arrive at their destination.
v Message confidentiality protects messages, usually by encryption and
decryption, from viewing by unauthorized users during transmission.

Communication support services can also include other processing such as data
compression or traffic-based accounting.

The database server provides a default method of authentication, which is

described in “Network Security Files” on page 3-11. The database server uses the
default authentication policy when you do not specify a communications support
module.

The database server provides extra security-related communication support

services through plug-in software modules called Communication Support
Modules (CSM). For details, see “Using Communication Support Modules (CSMs)
for Password and Data Transmission Encryption” on page 5-9.

Connectivity Files
The connectivity files contain the information that enables client/server
communication. These files also enable a database server to communicate with
another database server. The connectivity configuration files can be divided into
three groups:
v Network-configuration files
v Network security files
v The sqlhosts file or SQLHOSTS registry

Network-Configuration Files
This section identifies and explains the use of network-configuration files on
TCP/IP and IPX/SPX networks.

TCP/IP Connectivity Files

When you configure the database server to use the TCP/IP network protocol, you
use information from the hosts and services network-configuration files to prepare
the sqlhosts information.

The network administrator maintains these files. When you add a host or a
software service such as a database server, you need to inform the network
administrator so that person can make sure the information in these files is
accurate.

3-8 IBM Informix Dynamic Server Administrator’s Guide

The hosts file needs a single entry for each network-controller card that connects a
computer running an Informix client/server product on the network. Each line in
the file contains the following information:
v Internet address (or ethernet card IP address)
v Host name
v Host aliases (optional)

Although the length of the host name is not limited in the hosts file, Informix
limits the host name to 256 bytes. Table 3-4 on page 3-25 includes a sample hosts
file.

The services file contains an entry for each service available through TCP/IP. Each
entry is a single line that contains the following information:
v Service name
IBM Informix products use this name to determine the port number and
protocol for making client/server connections. The service name can have up to
128 bytes.
v Port number and protocol
The port number is the computer port, and the protocol for TCP/IP is tcp.
The operating system imposes restrictions on the port number. User informix
must use a port number equal to or greater than 1024. Only root users are
allowed to use a port number less than 1024.
v Aliases (optional)

The service name and port number are arbitrary. However, they must be unique
within the context of the file and must be identical on all computers that are
running IBM Informix client/server products. The aliases field is optional. For
example, a services file might include the following entry for a database server:
server2 1526/tcp

This entry makes server2 known as the service name for TCP port 1526. A database
server can then use this port to service connection requests. Figure 3-4 on page 3-19
includes a sample services file.

Important: For database servers that communicate with other database servers,
you must define a TCP/IP connection in DBSERVERNAME or
DBSERVERALIAS even when both instances reside on the same
machine.

For information about the hosts and services files, see your operating system
documentation.

TCP/IP Connectivity Files on UNIX: On UNIX, the hosts and services files are in
the /etc directory. The files must be present on each computer that runs an IBM
Informix client/server product, or on the NIS server if your network uses Network
Information Service (NIS).

Warning: On systems that use NIS, the /etc/hosts and /etc/services files are
maintained on the NIS server. The /etc/hosts and /etc/services files that
reside on your local computer might not be used and might not be up to
date. To view the contents of the NIS files, enter the following
commands on the command line:
ypcat hosts
ypcat services

Chapter 3. Client/Server Communications 3-9

 TCP/IP Connectivity Files on Windows: You use information from the hosts and
services network-configuration files to prepare the SQLHOSTS registry key for the
TCP/IP network protocol. These files are in the following locations:
v %WINDIR%\system32\drivers\etc\hosts
v %WINDIR%\system32\drivers\etc\services

Alternately, you can configure TCP/IP to use the Domain Name Service (DNS) for
host name resolutions. For information about these files, see your operating-system
documentation.

The Dynamic Host Configuration Product (DHCP) dynamically assigns IP

addresses from a pool of addresses instead of using IP addresses that are explicitly
assigned to each workstation. If your system uses DHCP, you must also have
installed Windows Internet Name Service (WINS). DCHP is transparent to the
database server.

What Happens Between a Client and Server When a TCP/IP Connection Is

Opened: When a TCP/IP connection is opened, the following information is read
on the client side:
v INFORMIXSERVER
v hosts file information (INFORMIXSQLHOSTS, $INFORMIXDIR/etc/sqlhosts, the
registry entry on Windows NT) and services file information
v Other environment variables
v Resource files

The following information is read on the server side:

v DBSERVERNAME
v DBSERVERALIAS
v Server environment variables and configuration parameters, including any
NETTYPE configuration parameter setting that manage TCP/IP connections
For more information about the NETTYPE configuration parameter, see
“NETTYPE Configuration Parameter” on page 3-30 and the IBM Informix
Dynamic Server Administrator's Reference.

Multiple TCP/IP Ports

To take advantage of multiple ethernet cards, take the following actions:
v Make an entry in the services file for each port the database server will use, as
in the following example:
soc1 21/tcp
soc2 22/tcp
Each port of a single IP address must be unique. Separate ethernet cards can use
unique or shared port numbers. You might want to use the same port number
on ethernet cards connecting to the same database server. (In this scenario, the
service name is the same.)
v Put one entry per ethernet card in the hosts file with a separate IP address, as in
the following example:
[Link] svc8
[Link] svc81
v In the ONCONFIG configuration file, enter DBSERVERNAME for one of the
ethernet cards and DBSERVERALIASES for the other ethernet card. The
following lines show sample entries in the ONCONFIG file:
DBSERVERNAME chicago1
DBSERVERALIASES chicago2

3-10 IBM Informix Dynamic Server Administrator’s Guide

 v In the sqlhosts file on UNIX or the SQLHOSTS registry key on Windows, make
one entry for each ethernet card. That is, make an entry for the
DBSERVERNAME and another entry for the DBSERVERALIAS.
chicago1 onsoctcp svc8 soc1
chicago2 onsoctcp svc81 soc2

After this configuration is in place, the application communicates through the

ethernet card assigned to the dbservername that the INFORMIXSERVER
environment variable provides.

IPX/SPX Connectivity Files (UNIX)

To configure the database server to use the IPX/SPX protocol on a UNIX network,
you must purchase IPX/SPX software and install it on the database server
computer. Your choice of IPX/SPX software depends on the operating system that
you are using. For some operating systems, the IPX/SPX software is bundled with
software products based on NetWare for UNIX or Portable NetWare. In addition,
for each of the UNIX vendors that distributes IPX/SPX software, you might find a
different set of configuration files.

For advice on how to set configuration files for these software products, consult
the manuals that accompany your IPX/SPX software.

Network Security Files

IBM Informix products follow standard security procedures that are governed by
information contained in the network security files. For a client application to
connect to a database server on a remote computer, the user of the client
application must have a valid user ID on the remote computer.

The [Link] File

The [Link] file lists the remote hosts and users that are trusted by the
computer on which the database server resides. Trusted users, and users who log
in from trusted hosts, can access the computer without supplying a password. The
operating system uses the [Link] file to determine whether a user should be
allowed access to the computer without specifying a password. Informix requires a
[Link] file for its default authentication policy.

If a client application supplies an invalid account name and password, the

database server rejects the connection even if the [Link] file contains an entry
for the client computer. You should use the [Link] file only for client
applications that do not supply a user account or password. On UNIX, the
[Link] file is in the /etc directory. On Windows, the [Link] file is in the
\%WINDIR%\system32\drivers\etc directory. If you do not have a [Link]
file, you must create one.

On some networks, the host name that a remote host uses to connect to a
particular computer might not be the same as the host name that the computer
uses to refer to itself. For example, the network host name might contain the fully
qualified domain name (FQDN), as in the following example:
fully_qualified_domain_name.[Link]

By contrast, the computer might refer to itself with the local host name, as the
following example shows:
viking

Chapter 3. Client/Server Communications 3-11

 If this situation occurs, make sure that you specify both host name formats in the
[Link] file.

To determine whether a client is trusted, execute the following statement on the

client computer:
rlogin hostname

If you log in successfully without receiving a password prompt, the client is a

trusted computer.

As an alternative, an individual user can list hosts from which he or she can
connect as a trusted user in the .rhosts file. This file resides in the user’s home
directory on the computer on which the database server resides.

Windows Only

On Windows, a home directory is not automatically assigned when the Windows

administrator creates a user identity. The administrator can add a home directory
to a user’s profile with the User Manager application.
End of Windows Only

The netrc Information

The netrc information is optional information that specifies identity data. A user
who does not have authorization to access the database server or is not on a
computer that is trusted by the database server can use this file to supply a name
and password that are trusted. A user who has a different user account and
password on a remote computer can also provide this information.

On UNIX, the netrc information resides in the .netrc file in the user’s home
directory. Use any standard text editor to prepare the .netrc file. Windows
maintains the netrc information in the registry keys. Use the Host Information tab
of setnet32 to edit the netrc information.

If you do not explicitly provide the user password in an application for a remote
server (that is, through the USER clause of the CONNECT statement or the user
name and password prompts in DB–Access), the client application looks for the
user name and password in the netrc information. If the user has explicitly
specified the password in the application, or if the database server is not remote,
the netrc information is not consulted.

The database server uses the netrc information regardless of whether it uses the
default authentication policy or a communications support module.

For information about the specific content of this file, see your operating system
documentation.

Windows Only

On Windows, a home directory is not automatically assigned when the Windows

administrator creates a user identity. The administrator can add a home directory
to a user’s profile with the User Manager application.
End of Windows Only

3-12 IBM Informix Dynamic Server Administrator’s Guide

 User Impersonation: For certain client queries or operations, the database server
must impersonate the client to run a process or program on behalf of the client. In
order to impersonate the client, the database server must receive a password for
each client connection. Clients can provide a user ID and password through the
CONNECT statement or netrc information.

The following examples show how you can provide a password to impersonate a
client.
File or Statement Example
netrc information machine trngpc3 login bruce password im4golf
CONNECT statement CONNECT TO ol_trngpc3 USER bruce USING
″im4golf″

The sqlhosts File and the SQLHOSTS Registry Key

Informix client/server connectivity information, the sqlhosts information, contains
information that enables a client application to find and connect to any Informix
database server on the network.

For a detailed description of the sqlhosts information, see “The sqlhosts

Information” on page 3-15.

The sqlhosts File (UNIX)

On UNIX, the sqlhosts file resides, by default, in the $INFORMIXDIR/etc
directory. As an alternative, you can set the INFORMIXSQLHOSTS environment
variable to the full pathname and filename of a file that contains the sqlhosts file
information. Each computer that hosts a database server or a client must have an
sqlhosts file.

Each entry (each line) in the sqlhosts file contains the sqlhosts information for one
database server. Use white space (spaces, tabs, or both) to separate the fields. Do not
include any spaces or tabs within a field. To put comments in the sqlhosts file, start
a line with the comment character (#). You can also leave lines completely blank
for readability. Additional syntax rules for each of the fields are provided in the
following sections, which describe the entries in the sqlhosts file. Use any standard
text editor to enter information in the sqlhosts file.

Table 3-1 shows a sample sqlhosts file.

Table 3-1. Sample sqlhosts File
dbservername nettype hostname servicename options
menlo onipcshm valley menlo
newyork ontlitcp hill dynsrvr2 s=2,b=5120
sales ontlispx knight sales k=0,r=0
payroll onsoctcp dewar py1
asia group – – e=asia.3
asia.1 ontlitcp node6 svc8 g=asia
asia.2 onsoctcp node0 svc1 g=asia

Tools for Updating SQLHOSTS Information

To manage the SQLHOSTS information, use one of the following tools:
v Text editor

Chapter 3. Client/Server Communications 3-13

 v IBM Informix Server Administrator (ISA)
v setnet32

Tip: Use ISA to manage the SQLHOSTS connectivity information. Although

setnet32 allows you to set up database servers (nettype, hostname,
servicename, and options), it does not allow you to set up database server
groups.

The SQLHOSTS Registry Key (Windows)

When you install the database server, the setup program creates the following key
in the Windows registry:
HKEY_LOCAL_MACHINE\SOFTWARE\INFORMIX\SQLHOSTS

This branch of the HKEY_LOCAL_MACHINE subtree stores the sqlhosts

information. Each key on the SQLHOSTS branch is the name of a database server.
When you click the database server name, the registry displays the values of the
HOST, OPTIONS, PROTOCOL, and SERVICE fields for that particular database
server.

Each computer that hosts a database server or a client must include the
connectivity information either in the sqlhosts registry key or in a central registry.
When the client application runs on the same computer as the database server,
they share a single sqlhosts registry key.

Location of the SQLHOSTS Registry Key: When you install the database server,
the installation program asks where you want to store the SQLHOSTS registry key.
You can specify one of the following two options:
v The local computer where you are installing the database server
v Another computer in the network that serves as a central, shared repository of
sqlhosts information for multiple database servers in the network

Using a shared SQLHOSTS registry key relieves you of the necessity to maintain
the same sqlhosts information on multiple computers. However, the hosts and
services files on each computer must contain information about all computers that
have database servers.

If you specify a shared sqlhosts registry key, you must set the
INFORMIXSQLHOSTS environment variable on your local computer to the name
of the Windows computer that stores the registry. The database server first looks
for the sqlhosts registry key on the INFORMIXSQLHOSTS computer. If the
database server does not find an sqlhosts registry key on the
INFORMIXSQLHOSTS computer, or if INFORMIXSQLHOSTS is not set, the
database server looks for an sqlhosts registry key on the local computer.

You must comply with Windows network-access conventions and file permissions
to ensure that the local computer has access to the shared sqlhosts registry key. For
information about network-access conventions and file permissions, see your
Windows documentation.

Figure 3-2 illustrates the location and contents of the SQLHOSTS registry key for
the database server payroll.

3-14 IBM Informix Dynamic Server Administrator’s Guide

 HKEY_LOCAL_MACHINE on Local Machine

HARDWARE HOST:REG_SZ:dewar
OPTIONS:REG_SZ:
SAM
PROTOCOL:REG_SZ:onsoctcp
SECURITY SERVICE:REG_SZ:py1
SOFTWARE
Classes
Description
INFORMIX
ESQL/C
OnLine
SQLHOSTS
payroll
Microsoft

Figure 3-2. sqlhosts Information in the Windows Registry

The sqlhosts Information

The sqlhosts information in the sqlhosts file on UNIX or the SQLHOSTS registry
key on Windows contains connectivity information for each database server. The
sqlhosts information also contains definitions for groups. The database server
looks up the connectivity information when you start the database server, when a
client application connects to a database server, or when a database server connects
to another database server.

The connectivity information for each database server includes four fields of
required information and one optional field. The group information contains
information in only three of its fields.

The five fields of connectivity information form one line in the UNIX sqlhosts file.
On Windows, the database server name is assigned to a key in the SQLHOSTS
registry key, and the other fields are values of that key. The following table
summarizes the fields used for the sqlhosts information.

Description of Description of
UNIX Windows Connectivity Group
Field Name Field Name Information Information
dbservername Database server name key or Database server name Database server group name
database server group key
nettype PROTOCOL Connection type The word group
hostname HOST Host computer for the No information.
database server Use a hyphen as a
placeholder in this field.
servicename SERVICE Alias for the port number No information.
Use a hyphen as a
placeholder in this field.
options OPTIONS Options that describe or limit Group options
the connection

Chapter 3. Client/Server Communications 3-15

 UNIX Only

If you install IBM Informix Enterprise Gateway with DRDA in the same directory
as the database server, your sqlhosts file also contains entries for the Gateway and
non-Informix database servers. However, this manual covers only the entries for
the database server. For information about other entries in the sqlhosts file, see the
IBM Informix Enterprise Gateway with DRDA User Manual.
End of UNIX Only

Connectivity Information
The next section describes the connectivity information that is in each field of the
sqlhosts file or SQLHOSTS registry key.

Database Server Name

The database server name field (dbservername) gives the name of the database
server for which the connectivity information is being specified. Each database
server across all of your associated networks must have a unique database server
name. The dbservername field must match the name of a database server in the
network, as specified by the DBSERVERNAME and DBSERVERALIASES
configuration parameters in the ONCONFIG configuration file. For more
information about these configuration parameters, see “ONCONFIG Parameters for
Connectivity” on page 3-29.

The dbservername field can include any printable character other than an
uppercase character, a field delimiter, a new line character, or a comment character.
This field is limited to 128 bytes.

UNIX Only

If the sqlhosts file has multiple entries with the same dbservername, only the first
one is used.
End of UNIX Only

The Connection Type Field

The connection-type field (nettype on UNIX or PROTOCOL on Windows)
describes the type of connection that should be made between the database server
and the client application or another database server. The field is a series of eight
letters composed of three subfields, as Figure 3-3 shows.

d d i i i p p p

Database Interface type Network protocol

server product or IPC mechanism

Figure 3-3. Format of the Connection-Type Field

The following sections describe the subfields of the connection-type field.

Database Server Product: The first two letters of the connection-type field
represent the database server product.

3-16 IBM Informix Dynamic Server Administrator’s Guide

Product
Subfield Product
on or ol The database server
dr (UNIX) IBM Informix Enterprise Gateway with DRDA
For information about DRDA, see the IBM Informix Enterprise
Gateway with DRDA User Manual.

Interface Type: The middle three letters of the connection-type field represent the
network programming interface that enables communications. For more
information, see “Network Programming Interface” on page 3-3.
Interface
Subfield Type of Interface
ipc IPC (interprocess communications)
soc Sockets
tli TLI (transport layer interface)

Interprocess communications (IPC) are used only for communications between two
processes running on the same computer.

Network Protocol Entry: The final three letters of the connection-type field
represent the network protocol or specific IPC mechanism.
Protocol
Subfield Type of Protocol
imc TCP/IP network protocol used with IBM Informix MaxConnect
nmp Named-pipe communication
shm Shared-memory communication
spx IPX/SPX network protocol
str Stream-pipe communication
tcp TCP/IP network protocol

IPC connections use shared memory or stream pipes. The database server supports
two network protocols: TCP/IP and IPX/SPX.

Table 3-2 summarizes the possible connection-type values for database server
connections. For more information on MaxConnect protocols, see “Using IBM
Informix MaxConnect” on page 3-35.

Chapter 3. Client/Server Communications 3-17

Table 3-2. Summary of nettype Values
nettype PROTOCOL
Value Value Connection
(UNIX) (Windows) Description Type
onipcshm Shared-memory communication IPC
onipcstr Stream-pipe communication IPC
onipcnmp Named-pipe communication IPC
ontlitcp TLI with TCP/IP protocol Network
onsoctcp onsoctcp Sockets with TCP/IP protocol Network
ontlispx TLI with IPX/SPX protocol Network
onsocimc Sockets with TCP/IP protocol for communication Network
with MaxConnect
ontliimc TLI with TCP/IP protocol for communication Network
with MaxConnect
sqlmux sqlmux Single network connection with multiple Network
database connections.

For information on the connection types for your platform, see “Connections That
the Database Server Supports” on page 3-5.

Host Name Field

The host name field (hostname on UNIX or host on Windows) contains the name
of the computer where the database server resides. The name field can include any
printable character other than a field delimiter, a new line character, or a comment
character. The host name field is limited to 256 bytes.

The following sections explain how client applications derive the values used in
the host name field.

Network Communication with TCP/IP: When you use the TCP/IP network
protocol, the host name field is a key to the hosts file, which provides the network
address of the computer. The name that you use in the host name field must
correspond to the name in the hosts file. In most cases, the host name in the hosts
file is the same as the name of the computer. For information about the hosts file,
see “TCP/IP Connectivity Files” on page 3-8.

In some situations, you might want to use the actual Internet IP address in the
host name field. For information about using the IP address, see “IP Addresses for
TCP/IP Connections” on page 3-25.

Shared-Memory and Stream-Pipe Communication (UNIX): When you use shared

memory or stream pipes for client/server communications, the hostname field
must contain the actual host name of the computer on which the database server
resides.

Network Communication with IPX/SPX (UNIX): When you use the IPX/SPX
network protocol, the hostname field must contain the name of the NetWare file
server. The name of the NetWare file server is usually the UNIX hostname of the
computer. However, this is not always the case. You might need to ask the
NetWare administrator for the correct NetWare file server names.

3-18 IBM Informix Dynamic Server Administrator’s Guide

Tip: NetWare installation and administration utilities might display the NetWare
file server name in capital letters; for example, VALLEY. In the sqlhosts file,
you can enter the name in either uppercase or lowercase letters.

Service Name Field

The interpretation of the service name field (servicename or service) depends on
the type of connection that the connection-type field (nettype or PROTOCOL)
specifies. The service name field can include any printable character other than a
field delimiter, a new line character, or a comment character. The service name
field is limited to 128 bytes.

Network Communication with TCP/IP: When you use the TCP/IP connection
protocol, the service name field must correspond to a service name entry in the
services file. The port number in the services file tells the network software how to
find the database server on the specified host. It does not matter what service
name you choose, as long as you agree on a name with the network administrator.

Figure 3-4 shows the relationship between the sqlhosts file or registry and the
hosts file, as well as the relationship of sqlhosts to the services file.

sqlhosts entry to connect by TCP/IP

dbservername nettype hostname servicename options
sales onsoctcp knight sales_ol

hosts file
IP address hostname alias
[Link] knight

services file
service name port#/protocol
sales_ol 1543/tcp

Figure 3-4. Relationship of sqlhosts File or Registry to hosts and services Files

In some cases, you might use the actual TCP listen-port number in the service
name field. For information about using the port number, see “Port Numbers for
TCP/IP Connections” on page 3-28.

Named-Pipe Communication (Windows): When the PROTOCOL field specifies a

named-pipe connection (onipcnmp), the SERVICE entry can be any short group of
letters that is unique in the environment of the host computer where the database
server resides.

Shared-Memory and Stream-Pipe Communication (UNIX): When the nettype

field specifies a shared-memory connection (onipcshm) or a stream-pipe connection
(onipcstr), the database server uses the value in the servicename entry internally
to create a file that supports the connection. For both onipcshm and onipcstr
connections, the servicename can be any short group of letters that is unique in the
environment of the host computer where the database server resides.

Recommendation: Use the dbservername as the servicename for stream-pipe

connections.

Chapter 3. Client/Server Communications 3-19

 Network Communication with IPX/SPX (UNIX): A service on an IPX/SPX
network is simply a program that is prepared to do work for you, such as the
database server. For an IPX/SPX connection, the value in the servicename field can
be an arbitrary string, but it must be unique among the names of services available
on the IPX/SPX network. It is convenient to use the dbservername in the
servicename field.

Options Field
The options field includes entries for the following features.

Option Name Option Letter Reference

Buffer size b page 3-21
Connection redirection c page 3-21
End of group e page 3-22
Group g page 3-22
Identifier i page 3-24
Keep-alive k page 3-24
Security s (database server) page 3-24
r (client)
Communication support module csm “Using Communication Support
Modules (CSMs) for Password
and Data Transmission
Encryption” on page 5-9

When you change the values in the options field, those changes affect the next
connection that a client application makes. You do not need to stop and restart the
client application to allow the changes to take effect. However, a database server
reads its own connectivity information only during initialization or database-server
restart. If you change the options for the database server, you must restart the
database server to allow the changes to take effect.

Syntax Rules for the Options Field: Each item in the options field has the
following format:
letter=value

You can combine several items in the options field, and you can include them in
any order. The maximum length of the options field is 256 bytes.

You can use either a comma or white space as the separator between options. You
cannot use white space within an option.

The database server evaluates the options field as a series of columns. A comma or
white space in the options field represents an end of a column. Client and
database server applications check each column to determine whether the option is
supported. If an option is not supported, you are not notified. It is merely ignored.

3-20 IBM Informix Dynamic Server Administrator’s Guide

The following examples show both valid and invalid syntax.

Syntax Valid Comments

k=0,s=3,b=5120 Yes Syntax is correct.
s=3,k=0 b=5120 Yes Syntax is equivalent to the preceding entry. (White space is
used of instead of a comma.)
k=s=0 No You cannot combine entries.

Buffer-Size Option: Use the buffer-size option (b=value) to specify in bytes the
size of the communications buffer space. The buffer-size option applies only to
connections that use the TCP/IP network protocol. Other types of connections
ignore the buffer-size setting. You can use this option when the default size is not
efficient for a particular application. The default buffer size for the database server
using TCP/IP is 4096 bytes.

Adjusting the buffer size allows you to use system and network resources more
efficiently; however, if the buffer size is set too high, the user receives a
connection-reject error because no memory can be allocated. For example, if you
set b=64000 on a system that has 1000 users, the system might require 64
megabytes of memory for the communications buffers. This setting might exhaust
the memory resources of the computer.

On many operating systems, the maximum buffer size supported for TCP/IP is 16
kilobytes. To determine the maximum allowable buffer size, see the documentation
for your operating system or contact the technical-support services for the vendor
of your platform.

If your network includes several different types of computers, be particularly

careful when you change the size of the communications buffer.

Tip: Use the default size for the communications buffer. If you choose to set the
buffer size to a different value, set the client-side communications buffer and
the database server-side communications buffer to the same size.

Connection-Redirection Option: You can define a group of database servers, or

aliases in the sqlhosts file on the client and have the client connections to the
dbserver group try each of the group members with fail-over. The
connection-redirection option (c=value) indicates the order in which the connection
software chooses database servers, aliases, or coservers within a group.

Use the connection-redirection option in the following situations:

v To balance the load across multiple database server instances
v To use High-Availability Data Replication (HDR) to transfer over to a backup
database server if a failure should occur

The following table shows the possible settings for the connection-redirection
option.
Setting Result
c=0 By default, a client application connects to the first database server
instance listed in the dbserver group in the sqlhosts file. If the
client cannot connect to the first instance, it attempts to connect to
the second instance and so on.

Chapter 3. Client/Server Communications 3-21

 c=1 The client application chooses a random starting point from which
to connect to a list of dbserver group members.

Important: The connection-redirection option is valid only in a

dbserver group. For more information on the g option
to specify dbserver groups, see “Group Option” on
page 3-22.

Communication Support Module Option: Use the Communication Support

Module (CSM) option to describe the CSM for each database server that uses a
CSM. If you do not specify the CSM option, the database server uses the default
authentication policy for that database server. You can specify the same CSM
option setting for every database server described in the sqlhosts file or registry, or
you can specify a different CSM option or no CSM options for each sqlhosts entry.

The format of the CSM option is illustrated in the following example:

csm=(csmname,csm-connection-options)

The value of csmname must match a csmname entry in the [Link] file. The
connection-options parameter overrides the default csm-connection options specified
in the [Link] file.

The following example specifies that the ENCCSM communication support module
will be used for the connection:
csm=(ENCCSM)

For information on Communication Support Modules, see “Using Communication

Support Modules (CSMs) for Password and Data Transmission Encryption” on
page 5-9. For information on the [Link] file entry, see “CSM Configuration
File” on page 5-10.

End-of-Group Option: Use the end-of-group option (e=dbservername) to specify

the ending database server name of a database server group. If you specify this
option in an entry other than a database server group, the option is ignored.

If no end-of-group option is specified for a group, the group members are assumed
to be contiguous. The end of group is determined when an entry is reached that
does not belong to the group, or at the end of file, whichever comes first. For an
example of the end-of-group option, see Table 3-3 on page 3-23.

Group Option: When you define database server groups in the sqlhosts file or
registry, you can use multiple related entries as one logical entity to establish or
change client/server connections.

To create a database server group:

1. Specify the name of the database server group to which the sqlhosts entry
belongs (up to 18 bytes) in the DBSERVERNAME field.
The database server group name can be the same as the initial
DBSERVERNAME for the database server.
2. Place the keyword group in the connection type field.
3. The host name and service name fields are not used. Use dash (-) characters as
null-field indicators for the unused fields. If you do not use options, you can
omit the null-field indicators.
The options for a database server group entry are as follows:

3-22 IBM Informix Dynamic Server Administrator’s Guide

 v c = connection redirection
v e = end of group
v g = group option
v i = identifier option

To use database server groups for Enterprise Replication:

Use the i and g options in Enterprise Replication. All database servers

participating in replication must be a member of a database server group. Each
database server in the enterprise must have a unique identifier, which is the server
group. Make sure that the sqlhosts file is set up properly on each database server
participating in replication.

For more information, see preparing the replication environment in the IBM
Informix Dynamic Server Enterprise Replication Guide.

To use database server groups for High-Availability Data Replication:

Use the c, e, and g options in High-Availability Data Replication (HDR). HDR

requires two identical systems. For more information, see “Directing Clients with
the Connectivity Information” on page 20-15.

Important: Database server groups cannot be nested inside other database server
groups, and database server group members cannot belong to more
than one group.

The example in Table 3-3 shows the following two groups: asia and peru. Group
asia includes the following members:
v asia.1
v asia.2
v asia.3

Because group asia uses the end-of-group option (e=asia.3), the database server
searches for group members until it reaches asia.3, so the group includes usa.2.
Because group peru does not use the end-of-group option, the database server
continues to include all members until it reaches the end of file.

Table 3-3 shows examples of database server groups in the sqlhosts file.
Table 3-3. Database Server Groups in sqlhosts File or Registry
dbservername nettype hostname servicename options
asia group – – e=asia.3
asia.1 ontlitcp node6 svc8 g=asia
asia.2 onsoctcp node0 svc1 g=asia
usa.2 ontlispx node9 sv2
asia.3 onsoctcp node1 svc9 g=asia
peru group – –
peru.1 ontlitcp node4 svc4
peru.2 ontlitcp node5 svc5 g=peru
peru.3 ontlitcp node7 svc6
usa.1 onsoctcp [Link] sales_ol k=1, s=0

Chapter 3. Client/Server Communications 3-23

 You can use the name of a database server group instead of the database server
name in the following environment variables, or in the SQL CONNECT command:
v INFORMIXSERVER
The value of INFORMIXSERVER for a client application can be the name of a
database server group. However, you cannot use a database server group name
as the value of INFORMIXSERVER for a database server or database server
utility.
v DBPATH
DBPATH can contain the names of database server groups as dbservernames.

Identifier Option: The identifier option (i=number) assigns an identifying number

to a database server group. The identifier must be a positive numeric integer and
must be unique within your network environment.

For more information on the use of the identifier option, see the IBM Informix
Dynamic Server Enterprise Replication Guide.

Keep-Alive Option: The keep-alive option is a network option that TCP/IP uses.
It does not affect other types of connections. If you do not include the keep-alive
option in the options field, the keep-alive feature is enabled by default. To set the
keep-alive option on the database server side only, the client side only, or on both
sides, specify k=1 in the fifth column of the sqlhosts file. For most cases, you
should enable the keep-alive option.

The letter k identifies keep-alive entries in the options field, as follows:

k=0 Disable the keep-alive feature
k=1 Enable the keep-alive feature

When a connected client and server are not exchanging data and the keep-alive
option is enabled, the network service checks the connection periodically. If the
receiving end of the connection does not respond within the time specified by the
parameters of your operating system, the network service immediately detects the
broken connection and frees resources.

When the keep-alive option is disabled, the network service does not check
periodically whether the connection is still active. If the opposite end of the
connection terminates unexpectedly without any notification, as when a PC
reboots, for example, the network service might never detect that the connection is
broken.

Security Options: The security options let you control operating-system

security-file lookups. The letter s identifies database server-side settings, and the
letter r identifies client-side settings. You can set both options in the options field.
A client ignores s settings, and the database server ignores r settings.

The following table shows the possible security option settings.

Setting Result
r=0 Disables netrc lookup from the client side (no password can be
supplied).
r=1 Enables netrc lookup from the client side (default setting for the
client side).

3-24 IBM Informix Dynamic Server Administrator’s Guide

 s=0 Disables both [Link] and rhosts lookup from the database
server side (only incoming connections with passwords are
accepted).
s=1 Enables only the [Link] lookup from the database server side.
s=2 Enables only the rhosts lookup from the database server side.
s=3 Enables both [Link] and rhosts lookup on the database server
side (default setting for the database server side).

The security options let you control the way that a client (user) gains access to a
database server. By default, an Informix database server uses the following
information on the client computer to determine whether the client host computer
is trusted:
v [Link]
v rhosts information

With the security options, you can specifically enable or disable the use of either or
both files.

For example, if you want to prevent end users from specifying trusted hosts in
rhosts, you can set s=1 in the options field of the sqlhosts file or SQLHOSTS
registry key for the database server to disable the rhosts lookup.

Important: Do not disable the [Link] lookup in database servers that are
used in distributed database operations. That is, if you expect to use
the database server in distributed processing, do not set s=0 or s=2.

Group Information
The following section describes the fields of the sqlhosts file or registry for groups.

Database Server Group

A database server group allows you to treat multiple related database server
entries as one logical entity to establish or change client/server connections. You
can also use dbserver groups to simplify the redirection of connections to database
servers. For more information on database server groups, see “Group Option” on
page 3-22.

Alternatives for TCP/IP Connections

The following sections describe some ways to bypass port and IP address lookups
for TCP/IP connections.

IP Addresses for TCP/IP Connections

For TCP/IP connections (both TLI and sockets), you can use the actual IP address
in the hostname field instead of the host name or alias found in the hosts file. The
IP address is composed of four integers between 0 and 255, separated by periods.
Table 3-4 on page 3-25 shows sample IP addresses and hosts from a hosts file.
Table 3-4. A Sample hosts File
IP Address Host Name Host Alias
[Link] smoke
[Link] odyssey
[Link] knight sales

Chapter 3. Client/Server Communications 3-25

 Using the IP address for knight from Table 3-4, the following two sqlhosts entries
are equivalent:
sales ontlitcp [Link] sales_ol
sales ontlitcp knight sales_ol

Using an IP address might speed up connection time in some circumstances.

However, because computers are usually known by their host name, using IP
addresses in the host name field makes it less convenient to identify the computer
with which an entry is associated.

UNIX Only

You can find the IP address in the net address field of the hosts file, or you can
use the UNIX arp or ypmatch command.
End of UNIX Only

Windows Only

You can configure Windows to use either of the following mechanisms to resolve
Internet Domain Addresses ([Link]) to Internet Protocol
addresses ([Link]):
v Windows Internet Name Service
v Domain Name Server

End of Windows Only

Wildcard Addressing for TCP/IP Connections

You can use wildcard addressing in the host name field when both of the following
conditions are met:
v You are using TCP/IP connections.
v The computer where the database server resides has multiple network-interface
cards (for example, three ethernet cards).

If the preceding conditions are met, you can use an asterisk (*) as a wildcard in the
host name field that the database server uses. When you enter a wildcard in the
host name field, the database server can accept connections at any valid IP address
on its host computer.

Each IP address is associated with a unique host name. When a computer has
multiple network-interface cards (NICs), as in Figure 3-5 on page 3-27, the hosts
file must have an entry for each interface card. For example, the hosts file for the
texas computer might include these entries.

NIC Internet IP Address Host Name

Card 1 [Link] texas1
Card 2 [Link] texas2

You can use the wildcard (*) alone or as a prefix for a host name or IP address, as
shown in Table 3-5 on page 3-27.

If the client application and database server share connectivity information (the
sqlhosts file or the SQLHOSTS registry key), you can specify both the wildcard

3-26 IBM Informix Dynamic Server Administrator’s Guide

and a host name or IP address in the host name field (for example, *texas1 or
*[Link]). The client application ignores the wildcard and uses the host name
(or IP address) to make the connection, and the database server uses the wildcard
to accept a connection from any IP address.

The wildcard format allows the listen thread of the database server to wait for a
client connection using the same service port number on each of the valid
network-interface cards. However, waiting for connections at multiple IP addresses
might require slightly more CPU time than waiting for connections with a specific
host name or IP address.

Figure 3-5 shows a database server on a computer (texas) that has two
network-interface cards. The two client sites use different network cards to
communicate with the database server.

iowa

Client

texas

texas_srvr

kansas

Client

Network
programming
interfaces

Figure 3-5. Using Multiple Network-Interface Cards

Table 3-5 shows the connectivity information for the texas_srvr database server.
Table 3-5. Possible Connectivity Entries for the texas_srvr Database Server
database server name connection type host name service name
texas_srvr ontlitcp *texas1 pd1_on
texas_srvr ontlitcp *[Link] pd1_on
texas_srvr ontlitcp *texas2 pd1_on
texas_srvr ontlitcp *[Link] pd1_on
texas_srvr ontlitcp * pd1_on

Important: You can include only one of these entries.

Chapter 3. Client/Server Communications 3-27

 If the connectivity information corresponds to any of the preceding lines, the
texas_srvr database server can accept client connections from either of the network
cards. The database server finds the wildcard in the host name field and ignores
the explicit host name.

Tip: For clarity and ease of maintenance, you should include a host name when
you use the wildcard in the host name field (that is, use *host instead of
simply *).

The connectivity information used by a client application must contain an explicit

host name or IP address. The client applications on iowa can use any of the
following host names: texas1, *texas1, [Link], or *[Link]. If there is
a wildcard (*) in the host name field, the client application ignores it.

The client application on kansas can use any of the following host names: texas2,
*texas2, [Link], or *[Link].

Port Numbers for TCP/IP Connections

For the TCP/IP network protocol, you can use the actual TCP listen port number
in the service name field. The TCP port number is in the port# field of the services
file.

For example, if the port number for the sales database server in the services file is
1543/tcp, you can write an entry in the sqlhosts file as follows:

servername nettype hostname servicename

sales ontlitcp knight 1543

Using the actual port number might save time when you make a connection in
some circumstances. However, as with the IP address in the host name field, using
the actual port number might make administration of the connectivity information
less convenient.

Dynamic Server Support for IPv6 Addresses

Dynamic Server recognizes Internet Protocol Version 6 (IPv6) addresses, which are
128-bits long, on many platforms.

On all platforms, Dynamic Server supports Internet Protocol Version 4 (IPv4)

addresses, which are 32-bits long.

4 IBM Informix Dynamic Server Version 10.00.UC4 and CSDK 2.90.UC4 initially
4 check to determine whether IPv6 is supported in the underlying operating system.
4 If IPv6 is supported, the IPv6 address is used. If the underlying operating system
4 does not support IPv6, the IPv4 address is used. Dynamic Server and CSDK
4 retrieve the IP address from the name service.

You can treat Dynamic Server that runs on a host with both IPv4 and IPv6
addresses the same way you treat a server running on a multi-homed host. You
can configure Dynamic Server on a host with both IPv4 and IPv6 addresses in
either of the following ways:
v Create aliases (using the DBSERVERALIASES configuration parameter) and
assign an IPv6 address to one of them and an IPv4 address to the other.

3-28 IBM Informix Dynamic Server Administrator’s Guide

 v Instruct the Dynamic Server to listen on all the IP addresses configured on the
host by using a wild-carded hostname in the SQLHOSTS file.
For example:
olserver1 oltlitcp *myhost olservice1

Note the asterisk in front of the hostname. This is the same naming scheme that
currently exists for the servers in a multi-homed host. Starting with Dynamic
Server Version 10.0, the hostname entry in the SQLHOSTS file maps to an IPv6
address if the host has a configured IPv6 address. If the host does not have a
configured IPv6 address, the hostname entry maps to an IPv4 address. The
hostname with a preceding asterisk maps to a wildcard address.

ONCONFIG Parameters for Connectivity

When you restart the database server, the restart procedure uses parameter values
from the ONCONFIG configuration file. The following ONCONFIG parameters are
related to connectivity:
v DBSERVERNAME
v DBSERVERALIASES
v NETTYPE

The next sections explain these configuration parameters.

DBSERVERNAME Configuration Parameter

The DBSERVERNAME configuration parameter specifies a name, called the
dbservername, for the database server. For example, to assign the value
nyc_research to dbservername, use the following line in the ONCONFIG
configuration file:
DBSERVERNAME nyc_research

When a client application connects to a database server, it must specify a

dbservername. The sqlhosts information that is associated with the specified
dbservername describes the type of connection that should be made.

Client applications specify the name of the database server in one of the following
places:
v In the INFORMIXSERVER environment variable
v In SQL statements such as CONNECT, DATABASE, CREATE TABLE, and
ALTER TABLE, which let you specify a database environment
v In the DBPATH environment variable

Windows Only

In Windows, the DBSERVERNAME cannot be changed in the configuration file,

because the registry stores information about the database server instance under
the DBSERVERNAME.
End of Windows Only

The DBSERVERNAME must specify either the dbservername or one of the

dbserveraliases. The name must begin with a lowercase letter and can contain
other lowercase letters, digits, and underscores. The name should not include
uppercase characters, a field delimiter (space or tab), or a new line character. Other

Chapter 3. Client/Server Communications 3-29

 characters from the basic ASCII code set are not necessarily reliable. For example, a
hyphen or minus sign can create problems and a colon might not work reliably.
The @ character is reserved to separate the database from the server (as in
dbase@server).

DBSERVERALIASES Configuration Parameter

The DBSERVERALIASES parameter lets you assign additional dbservernames to
the same database server. The maximum number of aliases is 32. Figure 3-6 shows
entries in an ONCONFIG configuration file that assign three dbservernames to the
same database server instance.

DBSERVERNAME sockets_srvr
DBSERVERALIASES ipx_srvr,shm_srvr

Figure 3-6. Example of DBSERVERNAME and DBSERVERALIASES Parameters

The sqlhosts entries associated with the dbservernames from Figure 3-6 could
include those shown in Figure 3-7. Because each dbservername has a
corresponding entry in the sqlhosts file or SQLHOSTS registry key, you can
associate multiple connection types with one database server.

shm_srvr onipcshm my_host my_shm

sockets_srvr onsoctcp my_host port1
ipx_srvr ontlispx nw_file_server ipx_srvr

Figure 3-7. Three Entries in the sqlhosts File for One Database Server in UNIX format

Using the sqlhosts file shown in Figure 3-7, a client application uses the following
statement to connect to the database server using shared-memory communication:
CONNECT TO ’@shm_srvr’

A client application can initiate a TCP/IP sockets connection to the same database
server using the following statement:
CONNECT TO ’@sockets_srvr’

DBSERVERALIASES must begin with a lowercase letter and can contain other
lowercase letters, digits, and underscores. DBSERVERALIASES should not include
uppercase characters, a field delimiter (space or tab), or a new line character. Other
characters from the basic ASCII code set are not necessarily reliable. For example, a
hyphen or minus sign can create problems and a colon might not work reliably.
The @ character is reserved to separate the database from the server (as in
dbase@server).

In the examples above, the @shm_srvr statement connects to an unidentified

database at that server; alternatively, you could connect to dbase1@shm_srvr.

NETTYPE Configuration Parameter

The NETTYPE configuration parameter lets you adjust the number and type of
virtual processors the database server uses for communication. Each type of
network connection (ipcshm, ipcstr, ipcnmp, soctcp, tlitcp, and tlispx) can have a
separate NETTYPE entry in the configuration file.

Recommendation: Although the NETTYPE parameter is not a required parameter,

you should set NETTYPE if you use two or more connection types. After the
database server has been running for some time, you can use the NETTYPE
configuration parameter to tune the database server for better performance.

3-30 IBM Informix Dynamic Server Administrator’s Guide

 For more information about NETTYPE, see “Network Virtual Processors” on page
6-20. For information about the NETTYPE configuration parameter, see the IBM
Informix Dynamic Server Administrator's Reference.

Environment Variables for Network Connections

The INFORMIXCONTIME (connect time) and INFORMIXCONRETRY (connect
retry) environment variables are client environment variables that affect the
behavior of the client when it is trying to connect to a database server. Use these
environment variables to minimize connection errors caused by busy network
traffic.

If the client application explicitly attaches to shared-memory segments, you might

need to set INFORMIXSHMBASE (shared-memory base). For more information,
see “How a Client Attaches to the Communications Portion (UNIX)” on page 8-6.

The INFORMIXSERVER environment variable allows you to specify a default

dbservername to which your clients will connect.

For more information on environment variables, see the IBM Informix Guide to SQL:
Reference.

Examples of Client/Server Configurations

The next several sections of this chapter show the correct entries in the sqlhosts
file or SQLHOSTS registry key for several client/server connections. The following
examples are included:
v Using a shared-memory connection
v Using a local-loopback connection
v Using a network connection
v Using multiple connection types
v Accessing multiple database servers

Important: In the following examples, you can assume that the

network-configuration files hosts and services have been correctly
prepared even if they are not explicitly mentioned.

Using a Shared-Memory Connection (UNIX)

Figure 3-8 shows a shared-memory connection on the computer named river.

river

river_shm
Shared
Database server
memory

Client

Figure 3-8. A Shared-Memory Connection

Chapter 3. Client/Server Communications 3-31

 The ONCONFIG configuration file for this installation includes the following line:
DBSERVERNAME river_shm

The table below shows a sample entry in the sqlhosts file or SQLHOSTS registry
key for the connection shown above in Figure 3-8.
Table 3-6. sqlhosts entry
dbservername nettype hostname servicename
river_shm onipcshm river rivershm

The client application connects to this database server using the following
statement:
CONNECT TO ’@river_shm’

Because this is a shared-memory connection, no entries in network configuration

files are required. For a shared-memory connection, you can choose arbitrary
values for the hostname and servicename fields of the sqlhosts file or SQLHOSTS
registry key.

For more information about shared-memory connections, see “How a Client

Attaches to the Communications Portion (UNIX)” on page 8-6.

Using a Local-Loopback Connection

Figure 3-9 shows a local-loopback connection that uses sockets and TCP/IP. The
name of the host computer is river.

river

TCP/IP network
river_soc programming
interface
Client Database server
SOC - TCP

Figure 3-9. Local-Loopback Connection

The following table shows the correct entry for the sqlhosts file or SQLHOSTS
registry key for the connection shown above in Figure 3-9.
Table 3-7. sqlhosts entry
dbservername nettype hostname servicename
river_soc onsoctcp river riverol

If the network connection uses TLI instead of sockets, only the nettype entry in
this example changes. In that case, the nettype entry is ontlitcp instead of
onsoctcp.

The ONCONFIG file includes the following line:

DBSERVERNAME river_soc

3-32 IBM Informix Dynamic Server Administrator’s Guide

 This example assumes that an entry for river is in the hosts file and an entry for
riverol is in the services file.

Using a Network Connection

Figure 3-10 shows a configuration in which the client application resides on host
river and the database server resides on host valley.

river
sqlhosts entry on river
dbservername nettype hostname servicename options
Client
valley_ds onsoctcp valley valleyol

SOC - TCP

TLI - TCP
sqlhosts entry on valley

valley_ds dbservername nettype hostname servicename options

valley_ds ontlitcp valley valleyol
Database server

valley

Figure 3-10. A Network Configuration

An entry for the valley_ds database server is in the sqlhosts files or registries on
both computers. Each entry in the sqlhosts file or SQLHOSTS registry key on the
computer where the database server resides has a corresponding entry on the
computer where the client application resides.

UNIX Only

Both computers are on the same TCP/IP network, but the host river uses sockets
for its network programming interface, while the host valley uses TLI for its
network programming interface. The nettype field must reflect the type of network
programming interface used by the computer on which sqlhosts resides. In this
example, the nettype field for the valley_ds database server on host river is
onsoctcp, and the nettype field for the valley_ds database server on host valley is
ontlitcp.
End of UNIX Only

The sqlhosts File Entry for IPX/SPX (UNIX)

IPX/SPX software frequently provides TLI. Table 3-8 shows the entries in the
sqlhosts file on both computers when the configuration in Figure 3-10 on page 3-33
uses IPX/SPX instead of TCP/IP.
Table 3-8. sqlhosts entry
dbservername nettype hostname servicename
valley_us ontlispx valley_nw valley_us

Chapter 3. Client/Server Communications 3-33

 In this case, the hostname field contains the name of the NetWare file server. The
servicename field contains a name that is unique on the IPX/SPX network and is
the same as the dbservername.

Using Multiple Connection Types

A single instance of the database server can provide more than one type of
connection. Figure 3-11 illustrates such a configuration. The database server is on
host river. Client A connects to the database server with a shared-memory
connection because shared memory is fast. Client B must use a network connection
because the client and server are on different computers.

When you want the database server to accept more than one type of connection,
you must take the following actions:
v Put DBSERVERNAME and DBSERVERALIASES entries in the ONCONFIG
configuration file.
v Put an entry in the sqlhosts file or SQLHOSTS registry key for each database
server/connection type pair.

For the configuration in Figure 3-11, the database server has two dbservernames:
river_net and river_shm. The ONCONFIG configuration file includes the following
entries:
DBSERVERNAME river_net
DBSERVERALIASES river_shm

river

Client A sqlhosts entries on river

Shared
memory
river_shm onipcshm river riverA
river_net onsoctcp river riveron

Database server A

SOC - TCP
valley TLI - TCP
sqlhosts entries on valley

Client B river_net ontlitcp river riveron

Figure 3-11. A UNIX Configuration That Uses Multiple Connection Types

The dbservername used by a client application determines the type of connection

that is used. In Figure 3-11 above, Client A uses the following statement to connect
to the database server:
CONNECT TO ’@river_shm’

3-34 IBM Informix Dynamic Server Administrator’s Guide

 In the sqlhosts file or SQLHOSTS registry key, the nettype associated with the
name river_shm specifies a shared-memory connection, so this connection is a
shared-memory connection.

Client B uses the following statement to connect to the database server:

CONNECT TO ’@river_net’

In the sqlhosts file or registry, the nettype value associated with river_net specifies
a network (TCP/IP) connection, so client B uses a network connection.

Accessing Multiple Database Servers

Figure 3-12 shows a configuration with two database servers on host river. When
more than one database server is active on one computer, it is known as multiple
residency. (For more information about multiple residency, see your IBM Informix
Installation Guide.)

river
Shared memory riverA_shm
Database server A

Client
SOC - TCP riverB_soc
Database server B

sqlhosts entries on river

dbservername nettype hostname servicename options
riverA_shm onipcshm river riverA
riverB_soc onsoctcp river riveron

Figure 3-12. Multiple Database Servers on UNIX

For the configuration in Figure 3-12, you must prepare two ONCONFIG
configuration files, one for database server A and the other for database server B.
The sqlhosts file or SQLHOSTS registry key includes the connectivity information
for both database servers.

The ONCONFIG configuration file for database server A includes the following
line:
DBSERVERNAME riverA_shm

The ONCONFIG configuration file for database server B includes the following
line:
DBSERVERNAME riverB_soc

Using IBM Informix MaxConnect

IBM Informix MaxConnect is a networking product for Informix database server
environments on UNIX. MaxConnect manages large numbers (from several
hundred to tens of thousands) of client/server connections. MaxConnect
multiplexes connections so that the ratio of client connections to database
connections can be 200:1 or higher. MaxConnect increases system scalability to

Chapter 3. Client/Server Communications 3-35

 many thousands of connections and saves system resources, reducing response
times and CPU requirements. MaxConnect is best for OLTP data transfers and not
recommended for large multimedia data transfers.

Install MaxConnect separately from your Informix database server and client
applications. For maximum performance benefit, install MaxConnect either on a
separate computer to which Informix clients connect or on the client application
server. You can install MaxConnect in the following configurations:
v On a dedicated server to which Informix clients connect
v On the client application server
v On the database server computer

Two protocols for multiplexing connections, ontliimc and onsocimc, are available
for MaxConnect users. You can use the ontliimc and onsocimc protocols in the
following two configurations:
v To connect MaxConnect to the database server.
In this configuration, the client connections are multiplexed and use packet
aggregation.
v To connect the client applications directly to the database server without going
through MaxConnect.
In this configuration, the client does not get the benefits of connection
multiplexing or packet aggregation. Choose this configuration when the client
application is transferring simple- or smart-large-object data, because a direct
connection to the database server is best.

For more information on how to configure MaxConnect and monitor it with the
onstat -g imc and imcadmin commands, see the IBM Informix MaxConnect User's
Guide.

Important: MaxConnect and the IBM Informix MaxConnect User's Guide ship
separately from the Informix database server.

3-36 IBM Informix Dynamic Server Administrator’s Guide

Chapter 4. Initializing the Database Server
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Types of Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Initializing Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Initialization Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Process Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3
Create Shared-Memory Portions . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Initialize or Restart Shared-Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Initialize Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start All Required Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Make Necessary Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Start a Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Document Configuration Changes . . . . . . . . . . . . . . . . . . . . . . . . . . 4-5
Create the oncfg_servername.servernum File . . . . . . . . . . . . . . . . . . . . . . . 4-6
Drop Temporary Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Set Forced Residency If Specified . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Return Control to User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
Create sysmaster Database and Prepare SMI Tables . . . . . . . . . . . . . . . . . . . . . 4-6
Create the sysutils Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Monitor Maximum Number of User Connections . . . . . . . . . . . . . . . . . . . . . 4-7
Database Server Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Changing Database Server Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Users Permitted to Change Modes . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
ISA Options for Changing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
ON-Monitor Options for Changing Modes (UNIX) . . . . . . . . . . . . . . . . . . . . . 4-10
Command-Line Options for Changing Modes . . . . . . . . . . . . . . . . . . . . . . 4-10
From Offline to Quiescent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
From Offline to Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-10
From Offline to Single-User . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
From Quiescent to Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Gracefully from Online to Quiescent . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Immediately from Online to Quiescent. . . . . . . . . . . . . . . . . . . . . . . . 4-12
From Quiescent or Online to Single-User . . . . . . . . . . . . . . . . . . . . . . . 4-12
From Single-User to Online . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
From Single-User to Quiescent . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
From Any Mode Immediately to Offline . . . . . . . . . . . . . . . . . . . . . . . 4-13

In This Chapter
This chapter tells how to initialize the database server, describes the activities that
take place during initialization, describes database server operating modes, and
provides information on changing operating modes.

Types of Initialization
Initialization of the database server refers to two related activities: shared-memory
initialization and disk-space initialization.

Shared-memory initialization or bringing up or starting the server establishes the

contents of database server shared memory, as follows: internal tables, buffers, and
the shared-memory communication area. Shared memory is initialized every time
the database server starts up. You use the oninit utility from the command line to
initialize database server shared memory and bring the database server online.

© Copyright IBM Corp. 1996, 2005 4-1

 Shared-memory initialization also occurs when you restart the database server.

One key difference distinguishes shared-memory initialization from disk-space

initialization:
v Shared-memory initialization has no effect on disk-space allocation or layout. No
data is destroyed.

Disk-space initialization uses the values stored in the configuration file to create the
initial chunk of the root dbspace on disk. When you initialize disk space, the
database server automatically initializes shared memory as part of the process.
Disk space is initialized the first time the database server starts up. It is only
initialized thereafter during a cold restore or at the request of the database server
administrator.

Warning: When you initialize disk space, you overwrite whatever is on that disk
space. If you reinitialize disk space for an existing database server, all
the data in the earlier database server becomes inaccessible and, in
effect, is destroyed.

Initializing Disk Space

The database server must be in offline mode when you begin initialization.

If you are starting a database server for the first time or you want to remove all
dbspaces and their associated data, use the following methods to initialize the disk
space and to bring the database server into online mode.

Operating System Action to Bring Database Server into Online Mode

UNIX You must be logged in as informix or root to initialize the database
server. Execute oninit -iy.
Windows You must be a member of the Administrators or Power Users
group to initialize the database server.
v The database server runs as a service. In the Services control
application, choose the database server service and type -iy in the
Startup parameters field. Then click Start.
v On the command line, use the starts dbservername -iy command.

Warning: When you execute these commands, all existing data in the database
server disk space is destroyed. Use the -i flag only when you are starting
a new instance of the database server.

You can use the oninit -s option to initialize shared memory and leave the
database server in quiescent mode.

Windows Only

When you install the database server and choose to initialize a new instance of the
database server, or when you use the instance manager program to create a new
instance of the database server, the database server is initialized for you.

Recommendation: Do not use the oninit -iy command to initialize the database
server unless you are diagnosing a problem.
End of Windows Only

4-2 IBM Informix Dynamic Server Administrator’s Guide

 For more information about oninit, see the IBM Informix Dynamic Server
Administrator's Reference.

For information on using these utilities to initialize the database server and change
the database server mode, see “Starting the Database Server and Initializing Disk
Space” on page 1-14.

Initialization Steps
Disk-space initialization always includes the initialization of shared memory.
However, some activities that normally take place during shared-memory
initialization, such as recording configuration changes, are not required during disk
initialization because those activities are not relevant with a newly initialized disk.

Table 4-1 shows the main tasks completed during the two types of initialization.
The following sections discuss each step.
Table 4-1. Initialization Steps
Shared-Memory Initialization Disk Initialization
Process configuration file. Process configuration file.
Create shared-memory segments. Create shared-memory segments.
Initialize shared-memory structures. Initialize shared-memory structures.
Initialize disk space.
Start all required virtual processors. Start all required virtual processors.
Make necessary conversions.
Initiate fast recovery.
Initiate a checkpoint. Initiate a checkpoint.
Document configuration changes.
Update oncfg_servername.servernum file. Update oncfg_servername.servernum file.
Change to quiescent mode. Change to quiescent mode.
Drop temporary tblspaces (optional).
Set forced residency, if requested. Set forced residency, if specified.
Change to online mode and return control to user. Change to online mode and return control to user.
If the SMI tables are not current, update the tables. Create sysmaster database that contains the SMI tables.
Create the sysutils database.
Monitor maximum number of user connections at each Monitor maximum number of user connections at each
checkpoint. checkpoint.

Process Configuration File

The database server uses configuration parameters to allocate shared-memory
segments during initialization and restart. If you modify a shared-memory
configuration parameter, you must shut down and restart the database server for
the change to take effect.

The ONCONFIG, onconfig, and [Link] files are stored in

$INFORMIXDIR/etc on UNIX and %INFORMIXDIR%\etc on Windows. During
initialization, the database server looks for configuration values in the following
files, in this order:

Chapter 4. Initializing the Database Server 4-3

 1. If the ONCONFIG environment variable is set, the database server reads
values from the ONCONFIG file.
If the ONCONFIG environment variable is set, but the database server cannot
access the specified file, it returns an error message.
2. If the ONCONFIG environment variable is not set, the database server reads
the configuration values from the ONCONFIG file.
3. If you omit a configuration parameter in your onconfig file, the database server
reads the configuration values from the $INFORMIXDIR/etc/[Link] file.

You should always set the ONCONFIG environment variable before you initialize
or restart the database server. The default configuration files are intended as
templates and not as functional configurations. However, the server will not
initialize if onconfig_std is missing. For more information about the configuration
file, see “Configuring the Database Server” on page 1-11.

The restart process compares the values in the current configuration file with the
previous values, if any, that are stored in the root dbspace reserved page,
PAGE_CONFIG. When differences exist, the database server uses the values from
the current ONCONFIG configuration file when the database server is restarted.

Create Shared-Memory Portions

The database server uses the configuration values to calculate the required size of
the database server resident shared memory. In addition, the database server
computes additional configuration requirements from internal values. Space
requirements for overhead are calculated and stored.

To create shared memory, the database server acquires the shared-memory space
from the operating system for three different types of memory:
v Resident portion, used for data buffers and internal tables
v Virtual portion, used for most system and user-session memory requirements

UNIX Only

v IPC communication portion, used for IPC communication

The database server allocates this portion of shared memory only if you
configure an IPC shared-memory connection.
End of UNIX Only

Next, the database server attaches shared-memory segments to its virtual address
space and initializes shared-memory structures. For more information about
shared-memory structures, see “Virtual Portion of Shared Memory” on page 8-13.

After initialization is complete and the database server is running, it can create
additional shared-memory segments as needed. The database server creates
segments in increments of the page size.

Initialize or Restart Shared-Memory

After the database server attaches to shared memory, it clears the shared-memory
space of uninitialized data. Next the database server lays out the shared-memory
header information and initializes data in the shared-memory structures. The
database server lays out the space needed for the logical-log buffer, initializes the
structures, and links together the three individual buffers that form the logical-log

4-4 IBM Informix Dynamic Server Administrator’s Guide

 buffer. For more information about these structures, see the onstat utility section in
the IBM Informix Dynamic Server Administrator's Reference.

After the database server remaps the shared-memory space, it registers the new
starting addresses and sizes of each structure in the new shared-memory header.

During shared-memory initialization, disk structures and disk layout are not
affected. The database server reads essential address information, such as the
locations of the logical and physical logs, from disk and uses this information to
update pointers in shared memory.

Initialize Disk Space

This procedure is performed only during disk-space initialization, not when the
database server is restarted. After shared-memory structures are initialized, the
database server begins initializing the disk. The database server initializes all the
reserved pages that it maintains in the root dbspace on disk and writes
PAGE_PZERO control information to the disk.

Start All Required Virtual Processors

The database server starts all the virtual processors that it needs. The parameters
in the ONCONFIG file influence what processors are started. For example, the
NETTYPE parameter can influence the number and type of processors started for
making connections. For more information about virtual processors, see “Virtual
Processors” on page 6-2.

Make Necessary Conversions

The database server checks its internal files. If the files are from an earlier version,
it updates these files to the current format. For information about database
conversion, see the IBM Informix Migration Guide.

Start Fast Recovery

The database server checks if fast recovery is needed and, if so, starts it. For more
information about fast recovery, see “Fast Recovery” on page 16-11.

Fast recovery is not performed during disk-space initialization because there is not
yet anything to recover.

Start a Checkpoint
After fast recovery executes, the database server starts a full checkpoint. As part of
the checkpoint procedure, the database server writes a checkpoint-complete
message in the message log. For more information about checkpoints, see
“Checkpoints” on page 16-7.

The database server now moves to quiescent mode or online mode, depending on
how you started the initialization or database-server restart process.

Document Configuration Changes

The database server compares the current values stored in the configuration file
with the values previously stored in the root dbspace reserved page
PAGE_CONFIG. When differences exist, the database server notes both values (old
and new) in a message to the message log.

This task is not performed during disk-space initialization or restart.

Chapter 4. Initializing the Database Server 4-5

 Create the oncfg_servername.servernum File
The database server creates the oncfg_servername.servernum file and updates it
every time that you add or delete a dbspace, blobspace, logical-log file, or chunk.
You do not need to manipulate this file in any way, but you can see it listed in
your $INFORMIXDIR/etc directory on UNIX or in your %INFORMIXDIR%\etc
directory on Windows. The database server uses this file during a full-system
restore.

For more information about the oncfg_servername.servernum file, see the section
on files that the database server uses in the IBM Informix Dynamic Server
Administrator's Reference.

Drop Temporary Tblspaces

The database server searches through all dbspaces for temporary tblspaces. (If you
use the -p option of oninit to initialize the database server, the database server
skips this step.) These temporary tblspaces, if any, are tblspaces left by user
processes that died prematurely and were unable to perform proper cleanup. The
database server deletes any temporary tblspaces and reclaims the disk space. For
more information about temporary tblspaces, see “Temporary Tables” on page
10-26.

This task is performed when the database server is restarted; it is not performed
during disk-space initialization.

Set Forced Residency If Specified

If the value of the RESIDENT configuration parameter is -1 or a number greater
than 0, the database server tries to enforce residency of shared memory. If the host
computer system does not support forced residency, the initialization procedure
continues. Residency is not enforced, and the database server sends an error
message to the message log. For more information about the RESIDENT
configuration parameter, see the IBM Informix Dynamic Server Administrator's
Reference.

Return Control to User

The database server writes the IBM Informix Dynamic Server initialized -
complete disk initialized message in the message log only if initialization, not
database-server restart, occurred. The database server also dynamically allocates a
virtual shared-memory segment.

At this point, control returns to the user. Any error messages generated by the
initialization procedure are displayed in the following locations:
v The command line
v The database server message log file, specified by the MSGPATH configuration
parameter
For more information about the MSGPATH parameter, see the IBM Informix
Dynamic Server Administrator's Reference.
v Summary section of IBM Informix Server Administrator (ISA)

Create sysmaster Database and Prepare SMI Tables

Even though the database server has returned control to the user, it has not
finished its work. The database server now checks the system-monitoring interface
(SMI) tables. If the SMI tables are not current, the database server updates the

4-6 IBM Informix Dynamic Server Administrator’s Guide

 tables. If the SMI tables are not present, as is the case when the disk is initialized,
the database server creates the tables. After the database server builds the SMI
tables, it puts the message sysmaster database built successfully in the message
log. The database server also re-creates the sysmaster database during conversion
and reversion. For more information about SMI tables, see the chapter on the
sysmaster database in the IBM Informix Dynamic Server Administrator's Reference.

If you shut down the database server before it finishes building the SMI tables, the
process of building the tables stops. This condition does not damage the database
server. The database server simply builds the SMI tables the next time that you
bring the database server online. However, if you do not allow the SMI tables to
finish building, you cannot run any queries against those tables, and you cannot
use ON–Bar for backups.

After the SMI tables have been created, the database server is ready for use. The
database server runs until you stop it or, possibly, until a malfunction.

Recommendation: Do not try to stop the database server by stopping a virtual

processor or ending another database server process. For more information, see
“Starting and Stopping Virtual Processors” on page 7-3.

Create the sysutils Database

The database server drops and re-creates the sysutils database during disk
initialization, conversion, or reversion. ON–Bar stores backup and restore
information in the sysutils database. Wait until the message sysutils database
built successfully displays in the message log. For more information, see the
IBM Informix Backup and Restore Guide.

Monitor Maximum Number of User Connections

At each checkpoint, the database server prints the maximum number of user
connections in the message log: maximum server connections number. You can
monitor the number of users who have connected to the database server since the
last restart or disk initialization.

The number displayed is reset when the customer reinitializes the database server.

Database Server Operating Modes

You can determine the current database server mode by executing the onstat utility
from the command line. The onstat header displays the mode.

Table 4-2 shows the principal modes of operation of the database server.

Chapter 4. Initializing the Database Server 4-7

Table 4-2. Operating Modes
Operating Mode Description Users Allowed Access
Offline mode The database server is not running. Shared Only the administrator (user informix) can
memory is not allocated. change from this mode to another mode.
Quiescent mode Database-server processes are running and Only the administrator (user informix) can
shared-memory resources are allocated. access the database server.

Administrators use this mode to perform Other users can view database-server status
maintenance functions that do not require information, but they cannot access the
the execution of SQL and DDL statements. database server.
Single-User mode This mode is an intermediary mode Only the administrator (user informix) can
between Quiescent mode and Online mode. access the database server.

Administrators use this mode to perform Other users can view database-server status
any maintenance task, including tasks information, but they cannot access the
requiring the execution of SQL and DDL database server.
statements. Administrators can also
perform all other functions available in
Online mode.
Online mode This is the normal operating mode of the Any authorized user can connect with the
database server. database server and perform all database
activities.

User informix or user root can use the

command-line utilities to change many
database server ONCONFIG parameter
values.

In addition, the database server can also be in one of the following modes:
v Read-only mode is used by the secondary database server in an HDR pair. An
application can query a database server that is in read-only mode, but the
application cannot write to a read-only database.
v Recovery mode is transitory. It occurs when the database server performs fast
recovery or recovers from a system archive or system restore. Recovery occurs
during the change from offline to quiescent mode.
v Shutdown mode is transitory. It occurs when the database server is moving from
online to quiescent mode or from online (or quiescent) to offline mode. Current
users access the system, but no new users are allowed access.
After shutdown mode is initiated, it cannot be cancelled.

Changing Database Server Operating Modes

This section describes how to change from one database server operating mode to
another with the oninit and onmode utilities and with ISA.

Windows Only

In Windows, the database server runs as a service. Windows provides a service

control application (also called the Services tool) to start, stop, and pause a service.
The service control application is located in the Control Panel program group. The
service name for the database server includes the database server name (the value
of DBSERVERNAME in the ONCONFIG file). For example, the Dynamic Server
service for the newyork database server is as follows:
IBM Informix Database Server - newyork

4-8 IBM Informix Dynamic Server Administrator’s Guide

 To change mode with the Services tool, start the tool and select the database server
service. Then choose the appropriate button in the Services window. The tables
shown later in this chapter explain which button you select for each mode.

To start and stop the database server, you can use other Windows tools, such as
the NET command and the Server Manager tool. For more information about these
methods, consult your Windows operating-system documentation.

End of Windows Only

Tip: After you change the mode of your database server, execute the onstat
command to verify the current server status.

Users Permitted to Change Modes

UNIX Only

Only users who are logged in as root or informix can change the operating mode
of the database server.
End of UNIX Only

Windows Only

Table 4-2 on page 4-8 shows which users can change the operating mode of the
database server in Windows. If you use ISA, you can log in to the operating
system as any user but you must log in to Apache as user informix. The Apache
server runs as a member of the Informix-Admin group.
Table 4-3. Changing Operating Modes in Windows
Changing Operating Mode Administrators Group Informix-Admin Group
command-line utilities X
such as starts
ISA X
Services control panel X

End of Windows Only

ISA Options for Changing Modes

You can use ISA to change the database server mode. For more information, see
the ISA online help.

Chapter 4. Initializing the Database Server 4-9

 Action ISA Option
Initialize the database server. Mode > Online (Initialize Disks)
or Quiescent (Initialize Disks)
Change from offline or single-user to quiescent. Mode > Quiescent
Change from any mode to single-user. Mode > Single-User
Change from offline, quiescent, or single-user to Mode > Online
online.
Change gracefully from online to quiescent. Mode > Quiescent (Graceful)
Change immediately from online to quiescent. Mode > Quiescent (Immediate)
Shut down the database server. Mode > Offline

ON-Monitor Options for Changing Modes (UNIX)

You can use ON–Monitor to change the database server mode on UNIX. For more
information, see the section on ON–Monitor in the IBM Informix Dynamic Server
Administrator's Reference.

Action Menu Option

Initialize the database server. Parameters > Initialize
Change from offline to quiescent. Mode > Startup
Change from offline or quiescent to online. Mode > Online
Change gracefully from online to quiescent. Mode > Graceful Shutdown
Change immediately from online to quiescent. Mode > Immediate Shutdown
Change to single-user mode. Mode > Single User
Shut down the database server. Mode > Take Offline

Command-Line Options for Changing Modes

This section contains commands for changing modes and information about how
mode changes effect user sessions. Table 4-2 on page 4-8 contains descriptions of
each mode and shows which users can access the database server when the server
is in each mode.

From Offline to Quiescent

When the database server changes from offline mode to quiescent mode, the
database server initializes shared memory. Only administrators can access the
database server to perform maintenance functions that do not involve the
execution of SQL and DDL statements.
Operating System Action
UNIX
v Execute oninit -s.
Windows
v On the command line, use the starts
dbservername -s command.

From Offline to Online

When you move the database server from offline to online mode, the database
server initializes shared memory and is available for all user sessions.

4-10 IBM Informix Dynamic Server Administrator’s Guide

Operating System Action
UNIX
v Execute oninit.
Windows
v With the Services tool, select the database server
service and click Start.
v On the command line, use the starts
dbservername command.

From Offline to Single-User

When you move the database server from off-line to single-user mode, you move
the server into a mode that only administrators can use to perform database server
functions and maintenance functions, including those involving the execution of
SQL and DDL statements.
Operating System Action
UNIX or Windows
v Execute oninit -j.

From Quiescent to Online

When you take the database server from quiescent mode to online mode, all
sessions gain access.

If you have already taken the database server from online mode to quiescent mode
and you are now returning the database server to online mode, any users who
were interrupted in earlier processing must reselect their database and redeclare
their cursors.
Operating System Action
UNIX or Windows
v Execute onmode -m.
Windows only
v With the Services tool, choose the database
server service and click Continue.

Gracefully from Online to Quiescent

Take the database server gracefully from online mode to quiescent mode to restrict
access to the database server without interrupting current processing.

After you perform this task, the database server sets a flag that prevents new
sessions from gaining access to the database server. Current sessions are allowed to
finish processing.

After you initiate the mode change, it cannot be cancelled. During the mode
change from online to quiescent, the database server is considered to be in
Shutdown mode.
Operating System Action
UNIX or Windows
v Execute onmode -s or onmode -sy.
Windows only

Chapter 4. Initializing the Database Server 4-11

 v With the Services tool, choose the database
server service and click Pause.

Immediately from Online to Quiescent

Take the database server immediately from online mode to quiescent mode to
restrict access to the database server as soon as possible. Work in progress can be
lost.

A prompt asks for confirmation of the immediate shutdown. If you confirm, the
database server sends a disconnect signal to all sessions that are attached to shared
memory. If a session does not receive the disconnect signal or is not able to comply
automatically within 10 seconds, the database server terminates the session.

The database server users receive either error message -459 indicating that the
database server was shut down or error message -457 indicating that their session
was unexpectedly terminated.

The database server cleans up all sessions that the database server terminated.
Active transactions are rolled back.
Operating System Action
UNIX or Windows
v Execute onmode -u or onmode -uy.
The -y option eliminates the need to confirm the
prompt.

From Quiescent or Online to Single-User

When you move the database server from quiescent or online to single-user mode,
you move the server into a mode that only administrators can use.

If you begin in online mode, the database server automatically disconnects any
users who are connected with any user ID that is not user informix and the users
receive an error message. If a connection is terminated during a transaction, the
database server rolls back the transaction.

Change to single-user mode when you want to execute SQL and DLL commands
when no other users are connected.
Operating System Action
UNIX or Windows
v Execute onmode -j.

From Single-User to Online

When you move the database server from single-user to online mode, all users can
access the database server.
Operating System Action
UNIX or Windows
v Execute onmode -m.

From Single-User to Quiescent

When you move the database server from single-user to quiescent mode, you
move the server into a mode that only administrators can use to perform
maintenance functions that do not involve the execution of SQL and DDL
statements.

4-12 IBM Informix Dynamic Server Administrator’s Guide

Operating System Action
UNIX or Windows
v Execute onmode -s.

From Any Mode Immediately to Offline

You can take the database server immediately from any mode to offline mode.
After you take the database server to offline mode, restart the database server in
quiescent, single-user, or online mode. When you restart the database server, it
performs a fast recovery to ensure that the data is logically consistent.

A prompt asks for confirmation to go offline. If you confirm, the database server
initiates a checkpoint request and sends a disconnect signal to all sessions that are
attached to shared memory. If a session does not receive the disconnect signal or is
not able to comply automatically within 10 seconds, the database server terminates
this session.

The database server users receive either error message -459 indicating that the
database server was shut down or error message -457 indicating that their session
was unexpectedly terminated.

After you take the database server to offline mode, restart the database server in
quiescent, single-user, or online mode. When you restart the database server, it
performs a fast recovery to ensure that the data is logically consistent.

The database server cleans up all sessions that were terminated by the database
server. Active transactions are rolled back.
Operating System Action
UNIX or Windows
v Execute onmode -k or onmode -ky. The -y
option eliminates the automatic prompt that
confirms an immediate shutdown.
Windows only
v With the Services tool, choose the database
server service and click Stop.

Chapter 4. Initializing the Database Server 4-13

4-14 IBM Informix Dynamic Server Administrator’s Guide
 Chapter 5. Security
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Server Utility Security Before Starting on UNIX and Linux . . . . . . . . . . . . . . . . . . . 5-2
Disabling Security Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Securing an Insecure Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Warning and Error Messages for Utility Security Checks . . . . . . . . . . . . . . . . . . . 5-3
INFORMIXDIR Directory Permissions . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Users and Group Membership for Running Dynamic Server Utilities . . . . . . . . . . . . . . . 5-5
Setting Up Security for Local Connections to a Host . . . . . . . . . . . . . . . . . . . . . 5-5
Auditing Database Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
3 Setting Permission to Create Databases . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
User Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Default Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
3 Limiting Denial-of-Service Flood Attacks . . . . . . . . . . . . . . . . . . . . . . . . . 5-7
Using the LISTEN_TIMEOUT and MAX_INCOMPLETE_CONNECTIONS Parameters . . . . . . . . . 5-8
Using the onmode -wm and onmode -wf Options to Change Parameter Values . . . . . . . . . . . 5-8
Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Overview of Encryption and Encryption Options . . . . . . . . . . . . . . . . . . . . . 5-8
Using Communication Support Modules (CSMs) for Password and Data Transmission Encryption . . . . . 5-9
CSM Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10
Configuring Password Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Configuring Network Data Encryption . . . . . . . . . . . . . . . . . . . . . . . 5-12
Using Column-Level Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-19
Storage Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Encrypting Column Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-21
Example Showing How to Determine the Size of an Encrypted Column . . . . . . . . . . . . 5-21
Example Showing How to Encrypt a Column . . . . . . . . . . . . . . . . . . . . . 5-22
Example Showing How to Query Encrypted Data . . . . . . . . . . . . . . . . . . . . 5-23
Authentication Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-23
Pluggable Authentication Modules for Systems Running on UNIX or Linux . . . . . . . . . . . . 5-23
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
The Name of the PAM Service . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Authentication Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Required Stack Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-24
Implicit Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
Configuring a Database Server to Use PAM . . . . . . . . . . . . . . . . . . . . . . 5-25
Enterprise Replication and High-Availability Data Replication . . . . . . . . . . . . . . . . 5-25
Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25
Distributed Transactions with PAM, Client APIs, and Compatibility Issues . . . . . . . . . . . . 5-25
LDAP Authentication Support on Windows . . . . . . . . . . . . . . . . . . . . . . . 5-25
Installing and Customizing the LDAP Authentication Support Module . . . . . . . . . . . . . 5-26
Configuring the LDAP Module . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Configuring Dynamic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-26
Authentication Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Implicit Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Enterprise Replication and High-Availability Data Replication . . . . . . . . . . . . . . . . 5-27
Application Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-27
Distributed Transactions with LDAP Support Modules, Client APIs, and Compatibility Issues . . . . . 5-27
Application Development for Authentication Modules . . . . . . . . . . . . . . . . . . . 5-27
Distributed Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-29
Client APIs and Authentication Support Modules . . . . . . . . . . . . . . . . . . . . . 5-30
Compatibility Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30
Enterprise Replication and High-Availability Data Replication Connection Security Option . . . . . . . . 5-31
Security for External Routines (UDRs) . . . . . . . . . . . . . . . . . . . . . . . . . . 5-32
4 Security for Loading External Modules . . . . . . . . . . . . . . . . . . . . . . . . . 5-32

© Copyright IBM Corp. 1996, 2005 5-1

3 Enabling non-DBAs to View SQL Statements a Session Is Executing . . . . . . . . . . . . . . . . 5-33

In This Chapter
This chapter contains information on these database server security features:
v A server utilities check for a secure environment before Dynamic Server starts on
UNIX or Linux
v A default role that you can assign to individual users or to the PUBLIC group
for a particular database
v Configuration parameters that you can use to reduce the incomplete connection
timeout period and restrict the number of incomplete requests for connections,
thus reducing the risk of a hostile, denial-of-service (DOS) flood attack
v Password, data-transmission, and column-level encryption options
v The Pluggable Authentication Module (PAM) for Dynamic Server systems
running on UNIX or Linux
v The Lightweight Directory Access Protocol (LDAP) Authentication Support for
Dynamic Server systems running on Windows
v The Enterprise Replication and High-Availability Data Replication connection
security option
v A security option that you can use to prevent unauthorized users from
registering external routines

Server Utility Security Before Starting on UNIX and Linux

When you install a new version of your database server, you should follow the
installation instructions to ensure that the permissions of all key files and
directories are set appropriately.

To provide increased security, key server utilities check to determine if your

environment is secure. Before the database server starts, the following settings
must be unchanged from the settings established during installation:
v The permissions on $INFORMIXDIR and some directories under it.
For each directory, the database server checks that the directory exists, that it is
owned by user informix and the correct group (as shown in “INFORMIXDIR
Directory Permissions” on page 5-4), and that directory permissions do not
include write permissions for the group or other users.
v The permissions on the ONCONFIG file.
The file must belong to the Database Server Administrator (DBSA) group. If the
DBSA group is informix (the default group), the ONCONFIG file should be
owned by user informix; otherwise, the ownership is not restricted. The file
must not have write permissions for others.
v The permissions on the sqlhosts file.
Under the default configuration, the sqlhosts file is located in the
$INFORMIXDIR/etc directory. The owner should be user informix, the group
should be either the informix group or the DBSA group, and the file must not
have public write permissions. If the file is specified through an
INFORMIXSQLHOSTS environment variable, the owner and group are not
checked; however, public write permissions are not permitted.
v Filename lengths.
The length of both the filenames $INFORMIXDIR/etc/[Link] and
$INFORMIXDIR/etc/$ONCONFIG must be less than 256 characters.

5-2 IBM Informix Dynamic Server Administrator’s Guide

 If the tests for any of these conditions fail, the utilities exit with an error message.

Warning: The database server does not read configuration files if they are publicly
writable, unless the INFORMIXDIR environment variable is designated
as secure in the /etc/informix directory. See information on “Disabling
Security Checking” and “Securing an Insecure Environment.”

Disabling Security Checking

Although it is strongly recommended that you never disable security checking,
you can partially disable the security checking for a database server residing in a
specific $INFORMIXDIR directory. To disable security checking, as the user root,
run the INFORMIXDIR/etc/informixdir-is-insecure script. After this script runs
successfully, the warning messages still appear when the utilities are run, but the
programs continue.

Note: You can specify the value of INFORMIXDIR on the command line as an
argument to the script. Thus, you do not need to set INFORMIXDIR in the
root user environment.

The informixdir-is-insecure script creates a /etc/informix directory (if necessary)

that is owned by root and has 555 permissions. In this directory, the script creates
a file named [Link] that has 444 permissions. The xx portion of the
filename is the major version number and yyy portion is the fixpack number: for
example, server-10.00.UC1. This file lists the $INFORMIXDIR values for which
security checking is disabled.

Note: The format of the contents of the [Link] files might change in
future releases.

If you choose to disable the security checking even though it is recommended that
you never do so, you should use the ibmifmx_security.sh script to limit the
number of SUID and SGID programs on your system.

Securing an Insecure Environment

If the database server reports that your environment is no longer secure and the
programs exit, user root can reset the relevant directory permissions so that they
are secure again by running the $INFORMIXDIR/etc/make-informixdir-secure
script.

Although user informix has permission to run the script, the script cannot fix the
problems unless the directory is owned by user informix. However, the error
messages indicate what still needs to be fixed. The script also shows files and
directories under $INFORMIXDIR that belong to an unexpected owner or group or
have public write permission.

Warning and Error Messages for Utility Security Checks

If the security check that a server utility performs at startup detects a problem, the
security check returns an error message. These messages are returned when the
message file and internationalization support are not available; therefore, the error
messages do not have error numbers and are not translated.

For the following problems, one of the following messages displays and the utility
continues:

Chapter 5. Security 5-3

 v INFORMIXDIR or ONCONFIG is too long. Maximum length for
$INFORMIXDIR/etc/$ONCONFIG is 255 characters.
v INFORMIXSQLHOSTS is too long. Maximum length is 255 characters.
v ONCONFIG not set; TBCONFIG set. TBCONFIG will not be supported in
future.

For the following problems, the utility exits and displays one of the following
messages:
v User informix not found.
v Group informix not found.
v Could not access logical-file filename.
v Logical-file filename is not owned by user with id UID.
v Logical-file filename not owned by group with id GID.
v Logical-file filename has insecure mode mode.
v Could not access logical-file filename.

The following table defines the variables used in the messages above.

Variable Explanation
filename A name of the file or directory
logical-file Either ONCONFIG, INFORMIXSQLHOSTS, INFORMIXDIR, or
INFORMIXDIR/xxx (where xxx is one of a number of subdirectories
under $INFORMIXDIR).

For example, if INFORMIXDIR is set to /usr/informix, the message might

read: INFORMIXSQLHOSTS /usr/informix/etc/sqlhosts is not owned by
the user with id 1234.
mode An octal permissions value
UID A number
GID A number

INFORMIXDIR Directory Permissions

The following table lists $INFORMIXDIR directories and their respective owners,
groups, and permissions.

Subdirectory Owner Group Permissions

. ($INFORMIXDIR) informix informix 755
bin informix informix 755
lib informix informix 755
gls informix informix 755
msg informix informix 755
etc informix DBSA 775
aaodir informix AAO 775
dbssodir informix DBSSO 775

See the IBM Informix Trusted Facility Guide for more information about database
server administrator (DBSA), audit analysis officer (AAO), and database system
security officer (DBSSO) groups.

5-4 IBM Informix Dynamic Server Administrator’s Guide

 Users and Group Membership for Running Dynamic Server
Utilities
The following Dynamic Server utilities are SUID root and SGID informix:
v onaudit
v onbar_d
v ondblog
v onedcu
v oninit
v onmode
v ON-Monitor
v onshowaudit
v onsmsync
v onsnmp
v onsrvapd
v ontape
v snmpdm

The following Dynamic Server utilities are SGID informix:

v oncheck
v onedpdu
v onload
v onlog
v onparams
v onpload
v onspaces
v onstat
v onunload
v xtree

Setting Up Security for Local Connections to a Host

The SECURITY_LOCALCONNECTION configuration parameter enables a
database server administrator (DBSA) to set up security checking for local
connections with the same host. The table below shows the settings of the
SECURITY_LOCALCONNECTION configuration parameter that you can use.
Table 5-1. SECURITY_LOCALCONNECTION Configuration Parameter Setting
Setting Explanation
0 No security checking occurs.
1 Dynamic Server compares the user ID of the owner trying to connect with
the connection user ID. If these do not match, Dynamic Server rejects the
connection.
2 Dynamic Server performs the same checking that is performed when
SECURITY_LOCALCONNECTION is set to 1. In addition, Dynamic
Server gets the peer port number from the network API and verifies that
the connection is coming from the client program.

If you set SECURITY_LOCALCONNECTION to 2, you must have

SOCTCP or IPCSTR network protocols.

Chapter 5. Security 5-5

 If SECURITY_LOCALCONNECTION is set to 1 or 2, Dynamic Server establishes a
connection only if the connection meets the requirements of the security check.

Auditing Database Events

You can audit database events by tracking activities that users perform on
particular objects at distinct times. You can use this information to monitor
database activity for suspicious use, detect unauthorized access attempts, assess
potential security damage, unscrupulous users, and provide evidence of database
server abuse.

For detailed information on auditing, see the IBM Informix Trusted Facility Guide.

3 Setting Permission to Create Databases

3 Use the DBCREATE_PERMISSION configuration parameter to give specified users
3 permission to create databases and thus prevent other users from creating
3 databases. If this parameter is not set, any user can create a database.

3 The informix user always has permission to create databases. To restrict the ability
3 to create databases to the informix user, add the following line to the ONCONFIG
3 file:
3 DBCREATE_PERMISSION informix

3 You can include multiple instances of DBCREATE_PERMISSION in the

3 ONCONFIG file to give additional users permission to create databases. For
3 example, to grant permission to a user named watsonjay, add this line to the
3 ONCONFIG file:
3 DBCREATE_PERMISSION watsonjay
3
User Roles
A role is a work-task classification, such as payroll or payroll manager. Each
defined role has privileges on the database object granted to the role. You use the
CREATE ROLE statement to define a role.

After you create a role, you use the GRANT statement to grant privileges to one or
more users associated with the role name. The CREATE ROLE and GRANT ROLE
statements enable you to create one set of privileges for a role and then grant the
role to many users, instead of granting the same set of privileges to each user in a
group.

When a role is granted to a user, the role grantor or the role grantee (user) must
use the SET ROLE statement to activate the role. Only then does the user have the
privileges of the role.

For more information on creating and using roles, see the see the IBM Informix
Guide to SQL: Syntax.

Default Roles
An administrator can define a default role to assign to individual users or to the
PUBLIC group for a particular database. The default role is automatically applied

5-6 IBM Informix Dynamic Server Administrator’s Guide

 when a user establishes a connection with the database. This enables a user to
connect to a database without issuing a SET ROLE statement.

Each user has whatever privileges are granted to the user individually, as well as
the privileges of the default role. A user can switch from the current individual
role to the default role using the SET ROLE DEFAULT statement.

If different default roles are assigned to a user and to PUBLIC, the default role of
the user takes precedence. If a default role is not assigned to a user, the user only
has individually granted and public privileges.

To define and grant privileges for a default role:

1. Choose an existing role in the current database to use as a default role or create
the role that you want to use as a default role. Use the CREATE ROLE rolename
statement to create a new role in the current database.
2. Use the GRANT statement to grant privileges to the role.
3. Grant the role to a user and set the role as the default user or PUBLIC role,
using the syntax GRANT DEFAULT ROLE rolename TO username or GRANT DEFAULT
ROLE rolename TO PUBLIC.

Use the REVOKE DEFAULT ROLE statement to disassociate a default role from a
user.

A user must use the SET ROLE DEFAULT statement to change any other current
role to the default role.

See the IBM Informix Guide to SQL: Syntax for more information on using these
statements.

3 Limiting Denial-of-Service Flood Attacks

3 To limit denial-of-service (DOS) attacks on UNIX, Linux, and Windows platforms,
3 Dynamic Server has multiple listener threads (listen_authenticate). These threads
3 authenticate client requests, while the main listener thread only accepts the
3 incoming requests and forks new threads for authentication. (Prior to Dynamic
3 Server Version 10.00.xc3, this feature was only supported on UNIX and Linux
3 platforms.)

You can use the MAX_INCOMPLETE_CONNECTIONS configuration parameter to

configure the number of the threads authenticating at any point in time.

You can use the LISTEN_TIMEOUT configuration parameter to configure the

timeout value for incomplete connections.

DOS attacks can occur when you use external mechanisms such as Telnet to
connect to the port reserved for a database server. For example, if you use Telnet to
connect to the port reserved for a database server service, but do not send data,
and a separate session attempts to connect to the server through an application
such as DB-Access, the listener thread is blocked while waiting for information
from the Telnet session and the listener thread cannot accept the connection to the
application used in the second session. If during the waiting period, an attacker
launches a distributed DOS (DDOS) attack in a loop, you can receive a flood attack
on the connection leading to poor connection performance.

Chapter 5. Security 5-7

 Using the LISTEN_TIMEOUT and
MAX_INCOMPLETE_CONNECTIONS Parameters
To reduce the risk of a hostile, DOS flood attack, you can customize the following
configuration parameters:
v LISTEN_TIMEOUT. Sets the incomplete connection timeout period. The default
incomplete connection timeout period is 10 seconds.
v MAX_INCOMPLETE_CONNECTIONS. Restricts the number of incomplete
requests for connections. The default maximum number of incomplete
connections is 1024.

If you do not set the LISTEN_TIMEOUT and

MAX_INCOMPLETE_CONNECTIONS configuration parameters and a flood of
unauthorized attacks occurs, the Listener VP might become insecure and it might
not be able to listen to a valid request in a timely manner.

If you set the LISTEN_TIMEOUT and MAX_INCOMPLETE_CONNECTIONS

configuration parameters and someone tries to break into the system and reaches
the maximum limit specified, the following information in the online message log
tells you that the system is under attack:
%d incomplete connection at this time.
System is under attack through invalid clients
on the listener port.

Depending on the machine capability of holding the threads (in number), you can
configure MAX_INCOMPLETE_CONNECTIONS to a higher value and depending
on the network traffic, you can set LISTEN_TIMEOUT to a lower value to reduce
the chance that the attack can reach the maximum limit.

Using the onmode -wm and onmode -wf Options to Change

Parameter Values
When the database server is in online mode, you can use the onmode -wm and
onmode -wf options to change to change the values of the LISTEN_TIMEOUT and
MAX_INCOMPLETE_CONNECTIONS configuration parameters.

To specify a new value for either configuration parameter for the current session,
use this syntax:

onmode -wm configuration_parameter=value

To change the value of either configuration parameter in the ONCONFIG file, use
this syntax:

onmode -wf configuration_parameter=value

Encryption
Dynamic Server provides the means for encrypting passwords, data that is being
transmitted, and data in specified columns.

Overview of Encryption and Encryption Options

Encryption is the process of transforming data into an unintelligible form to prevent
the unauthorized use of the data. To read an encrypted file, you must have access

5-8 IBM Informix Dynamic Server Administrator’s Guide

 to a secret key or password that enables you to decrypt it. Unencrypted data is
called plain text; encrypted data is called cipher text. A cipher is an
encryption-decryption algorithm.

The Data Encryption Standard (DES) is a cryptographic algorithm designed to

encrypt and decrypt data using 8-byte blocks and a 64-bit key.

The Triple DES (DES3) is a variation of DES in which three 64-bit keys are used for
a 192-bit key. DES3 works by first encrypting the plain text using the first 64-bits of
the key. Then the cipher text is decrypted using the next part of the key. Finally the
resulting cipher text is re-encrypted using the last part of the key.

The Advanced Encryption Standard (AES) is a replacement algorithm that is used

by the United States government.

Two encryption modes are:

v Block Mode, a method of encryption in which the message is broken into blocks
and the encryption occurs on each block as a unit. Since each block is at least 8
bytes large, block mode provides the ability for 64-bit arithmetic in the
encryption algorithm.
v Stream Mode, a method of encryption in which each individual byte is encrypted.
It is generally considered to be a weak form of encryption.

A blowfish is a block cipher that operates on 64-bit (8-byte) blocks of data. It uses a
variable size key, but typically, 128-bit (16-byte) keys are considered to be good for
strong encryption. Blowfish can be used in the same modes as DES.

The Dynamic Server options that you can use for encryption are shown in the table
below.

Encryption Option When and Why You Use This Option

Password encryption Use to encrypt passwords.

For more information, see “Using Communication Support Modules

(CSMs) for Password and Data Transmission Encryption”
Data-transmission Use to encrypt data transmitted over the network. This includes
encryption data transmitted between the database server and client systems.

For more information, see “Using Communication Support Modules

(CSMs) for Password and Data Transmission Encryption”
Column-level Use to set encryption passwords for columns containing sensitive
encryption data, such as credit card numbers. If you set column-level
encryption passwords, data in the columns is stored in an encrypted
format. Only users who can provide a secret password can view,
copy, or modify encrypted data.

For more information, see “Using Column-Level Encryption” on

page 5-19

Using Communication Support Modules (CSMs) for Password

and Data Transmission Encryption
You can use communication support modules (CSMs) to enable two different kinds
of encryption:
v The simple password CSM (SPWDCSM) provides password encryption.

Chapter 5. Security 5-9

 This encryption protects a password when it must be sent between the client
and the database server for authentication. SPWDCSM is available on all
platforms.
v The encryption CSM (ENCCSM) enables you to encrypt data transmissions,
including distributed queries, over the network.
This option provides complete data encryption with the openSSL library, with
many configurable options. A message authentication code (MAC) is transmitted
as part of the encrypted data transmission to ensure data integrity. A MAC is an
encrypted message digest.
The encryption algorithms use openSSL 0.9.6 as the code base.

Important: CSMs have the following restrictions:

v You cannot use both kinds of CSM simultaneously. For example, if
you are using the SPWDCSM and decide to encrypt your network
data, you must remove the entries for the SPWDCSM in your
[Link] and sqlhosts files.
v You cannot use either simple password CSM or encryption CSM
over a multiplexed connection.
v Enterprise Replication and High-Availability Data Replication (HDR)
support encryption, but cannot use a connection configured with a
CSM.
To use network encryption with Enterprise Replication, set the
encryption configuration parameters (for more information, see the
IBM Informix Dynamic Server Enterprise Replication Guide).
v Encrypted connections and unencrypted connections cannot be
combined on the same port.

To use encryption, you must do the following:

1. Add a line to the [Link] configuration file.
The [Link] file must contain an entry for each Communications Support
Module (of the same kind) that you are using. See “CSM Configuration File”
below for more information on the [Link] file.
2. Add an entry to the options column of the sqlhosts file or registry.
For information on specifying the CSM in the sqlhosts file or registry, see
“Communication Support Module Option” on page 3-22.

CSM Configuration File

You must have a [Link] file if you use a communication support module
(CSM). An entry in the file is a single line and is limited to 1024 characters. After
you describe the CSM in the [Link] file, you can enable it in the options
parameter of the sqlhosts file, as described in “Communication Support Module
Option” on page 3-22.

The [Link] file resides in the $INFORMIXDIR/etc directory by default. The

default directory for the [Link] file is INFORMIXDIR/etc. If you want to store
the file somewhere else, you can override the default location by setting the
INFORMIXCONCSMCFG environment variable to the full pathname of the new
location. For information on setting the environment variable
INFORMIXCONCSMCFG, see the IBM Informix Guide to SQL: Reference.

Entries in the [Link] file must conform to the following restrictions:

v The following characters are not allowed to be part of library pathnames:
– = (equal sign)
5-10 IBM Informix Dynamic Server Administrator’s Guide
 – ″ (double quote)
– , (comma)
v White spaces cannot be used unless the white spaces are part of a pathname.

Configuring Password Encryption

For password encryption, you must specify password encryption libraries and
connection options. To configure password encryption, use the following syntax to
add a line to the [Link] file.

csmname ( “ client = clientlib , server = serverlib “ ,

csmlib

“ “ , “ “ )

global_options conn_options

Option Description
client=clientlib Specifies the full path and name of the shared library
that is the CSM on the client computer.

Client computers use this CSM to communicate with the

database server. The library provided by Dynamic Server
is $INFORMIXDIR\lib\client\csm\[Link]
conn_options The conn_options option has the following options:
Setting Result
p=1 The password is mandatory for
authentication.
p=0 The password is not mandatory. If the
client provides it, the password is
encrypted and used for authentication.

An unknown option placed in conn_options results in a

context initialization error.

You can put a null value in the conn_options field, for

example: "". For Client SDK before Version 2.3, if the
conn_options field is null, the default behavior is p=1. For
Client SDK, Version 2.3 and later, if the conn_options field
is null, the default behavior is p=0.
csmlib The full path and name of the shared library that is the
CSM if the CSM is shared by both the database server
and the client computers.

The library provided by Dynamic Server is

$INFORMIXDIR\lib\csm\[Link].
csmname The name that you assign to the communications support
module

For example, a name could be SPWDCSM.

global_options This option is not currently used.

Chapter 5. Security 5-11

 Option Description
server=serverlib Specifies the full path and name of the shared library
that is the CSM on the database server.

The library provided by Dynamic Server is usually

installed in the following directories:
v UNIX: $INFORMIXDIR/lib/csm/[Link]
v Windows: %INFORMIXDIR%/bin/[Link]

SMI Tables and [Link] Setting: If you want to build the SMI tables when
you bring up the database server (oninit -i), do not specify the p=1 option in the
database server CSM entry in the [Link] file. The oninit process does not have
a password for the informix or root user ID. If you specify the p=1 option in the
[Link] file for the database server, you receive the following error message:
-5013 CSM: cannot obtain credential:
authentication error.

To specify that the password is mandatory for the database server CSM when
the SMI tables are not yet built:
1. Do not specify the p=1 option in the [Link] entry.
2. Bring up the database server with the oninit -i command to build the SMI
tables.
3. Bring down the database server.
4. Specify the p=1 option in the database server CSM entry in the [Link] file.
5. Start the database server again with the oninit command.

Example [Link] Entries for Password Encryption: The following two

examples illustrate the two alternatives for parameters you must enter in the
[Link] file to define the Simple Password Communication Support Module:
SPWDCSM
("client=/usr/informix/lib/client/csm/[Link],
server=/usr/informix/lib/csm/
[Link]", "", "")

SPWDCSM("/usr/informix/lib/csm/
[Link]", "", "")

The following example shows the conn_options field set to 0, so no password is

necessary:
SPWDCSM("/work/informix/csm/[Link]","","p=0")

Configuring Network Data Encryption

For network data encryption, you must specify the network encryption libraries
and the encryption options. You can specify the following types of encryption
options:
3 v DES and AES ciphers to use during encryption
v Modes to use during encryption
v Message authentication code (MAC) key files
v MAC levels
v Switch frequency for ciphers and keys
Each of these options are described later in this section.

5-12 IBM Informix Dynamic Server Administrator’s Guide

You can specify encryption options using encryption parameters in a separate file,
or using encryption tags in the [Link] file. To configure network encryption,
use the following syntax to add one or more lines to the [Link] file.

csmname ( “ client = clientlib , server = serverlib “ ,

csmlib

“ “ )

config = encrypt_config
(1) (2) (3)
Cipher Tag Mac Tag Switch Tag

Notes:
1 See “The Cipher Tag” on page 5-17.
2 See “The Mac Tag” on page 5-18.
3 See “The Switch Tag” on page 5-19.

Option Description
client=clientlib The full path and name of the shared library that is the
CSM on the client computer.

Client computers use this CSM to communicate with the

database server. The library provided by Dynamic Server
is $INFORMIXDIR/lib/client/csm/[Link].
config=encrypt_config The full path and filename of the file in which the
encryption parameters are defined. If the file does not
exist, then the default values are used. No error is
returned.

For more information on using encryption parameters,

see “Using Encryption Parameters” on page 5-15.
csmlib The full path and name of the shared library that is the
CSM if the CSM is shared by both the database server
and the client computers.

The library provided by Dynamic Server is

$INFORMIXDIR/lib/csm/[Link].
csmname The name that you assign to the communications support
module.

For example, a name could be SPWDCSM.

server=serverlib The full path and name of the shared library that is the
CSM on the database server. The library provided by
Dynamic Server is usually installed in the following
directories:
v UNIX: $INFORMIXDIR/lib/csm/[Link]
v Windows: %INFORMIXDIR%\bin\[Link]

Ciphers and Modes: You must specify which ciphers and mode to use during
encryption. The cipher and mode that is used is randomly chosen among the
ciphers that are common between the two servers. Make sure that all servers and
client computers that participate in encrypted communication have ciphers and
modes in common. Encryption is more secure if you include more ciphers and
modes that the database server can switch between. For information on how to
switch between ciphers, see “Switch Frequency” on page 5-15.

Chapter 5. Security 5-13

 Important: It is strongly recommended that you do not specify specific ciphers.
For security reasons, all ciphers should be allowed. If a cipher is
discovered to have a weakness, you can exclude it.

Use the allbut option to list ciphers and modes to exclude. Enclose the allbut list
in angled brackets (<>). The list can include unique, abbreviated entries. For
example, bf can represent bf1, bf2, and bf3. However, if the abbreviation is the
name of an actual cipher, then only that cipher is eliminated. Therefore, des
eliminates only the DES cipher, but de eliminates des, ede, and desx.

The following des, ede, and desx ciphers are supported.

Cipher Explanation Blowfish Cipher Explanation

des DES bf1 Blowfish
(64-bit key) (64-bit key)
ede Triple DES bf2 Blowfish
(128-bit key)
desx Extended DES bf3 Blowfish
(128-bit key) (192-bit key)

Warning: The cipher desx can only be used in cbc mode.

3 The following AES-encryption ciphers are supported.

33 Cipher Explanation
3 aes AES (128-bit key)
3 aes128 AES (128-bit key)
3 aes192 AES (192-bit key)
3 aes256 AES (256-bit key)
3

3 The following modes are supported.

Mode Explanation
ecb Electronic Code Book
cbc Cipher Block Chaining
cfb Cipher Feedback
ofb Output Feedback

Because ecb mode is considered weak; it is only included if specifically requested.

It is not included in the all or the allbut list.

MAC Key Files: The MAC key files contain encryption keys that are used to
encrypt messages. All database servers and client computers that participate in
encryption should have MAC key files in common. For information on how to
switch between MAC keys, see “Switch Frequency” on page 5-15.

The default MAC key file is the built-in file provided by Dynamic Server. This file
provides limited message verification (some validation of the received message and
determination that it appears to have come from an IBM Informix Dynamic Server
client or server). A site-generated MAC key file performs the strongest verification.
You can generate key files with the GenMacKey utility.

5-14 IBM Informix Dynamic Server Administrator’s Guide

Each of the MAC key files is prioritized and negotiated at connect time. The
prioritization for the MAC key files is based on their creation time by the
GenMacKey utility. The built-in key file has the lowest priority.

Tip: If there are no MAC key files present, the built-in MAC key is used by
default. However, by using a MAC key file, the default built-in MAC key is
disabled.

To generate a new MAC key file:

1. Execute the following command from the command line:
GenMacKey –o filename
The filename is the path and filename of the new MAC key file.
2. Update the central server’s configuration to include the location of the new
MAC key file in one of the following ways:
v Using encryption tags: Edit the relevant line in the [Link] file to add a
path and filename to the mac tag. For instructions, see “The Mac Tag” on
page 5-18.
v Using encryption parameters: Edit the encryption parameters file to alter the
value of the ENCCSM_MACFILES parameter. For instructions, see
“ENCCSM_MACFILES” on page 5-17.
3. If necessary, remove old MAC key file entries from the configuration.
4. Distribute the new MAC key file among all appropriate computers.

MAC Levels: MAC levels determine the type of MAC key generation.

The supported generation levels are:

v high. Uses SHA1 MAC generation on all messages.
v medium. Uses SHA1 MAC generation for all messages greater than 20 bytes
long and XOR folding on smaller messages.
v low. Uses XOR folding on all messages.
v off. Does not use MAC generation.

The level is prioritized to the highest value. For example, if one database server
has a level of high and medium enabled and the other database server has only
low enabled, then the connection attempt will fail. The off entry should only be
used between servers when it is guaranteed that there is a secure network
connection.

Make sure that all servers and client computers that participated in encrypted
communication have MAC levels in common.

Switch Frequency: The switch frequency defines when ciphers and or secret keys
are renegotiated. The longer that the secret key and encryption cipher remain in
use, the more likely that the encryption rules might be broken by an attacker. To
avoid this, cryptologists recommend periodically changing the secret key and
cipher on long-term connections. The default time that this renegotiation occurs is
once an hour. By using switch options, you can set the time in minutes when the
renegotiation occurs.

Using Encryption Parameters: You can configure encryption options by setting

encryption parameters in a file. In the encryption parameters file, each option has
the following form:
parameter_name value

Chapter 5. Security 5-15

 Use the following parameters to set encryption options:
v ENCCSM_CIPHERS: Ciphers to be used
v ENCCSM_MAC: MAC levels
v ENCCSM_MACFILES: MAC file locations
v ENCCSM_SWITCH: Cipher and key change frequency
Each of these parameters is described later in this section.

The following restrictions apply to the parameter values:

v Each entry should be of the form parameter_name value separated by white
spaces.
v No white spaces are allowed within a value.
v Each parameter should have one entry in the configuration file. If multiple
entries exist, only first entry is considered.
v Default values are used if a parameter does not exist in the configuration file.
v Characters after a comment character (#) are ignored; however, the pathname
value is not ignored.

ENCCSM_CIPHERS:
syntax ENCCSM_CIPHERS
all|allbut:<list of ciphers and
modes>|cipher:mode{,cipher:mode ...}
v all
Specifies to include all available ciphers and modes, except ECB mode. For
example: ENCCSM_CIPHERS all
v allbut:<list of ciphers and modes>
Specifies to include all ciphers and modes except the ones in the list. Separate
ciphers or modes with a comma. For example: ENCCSM_CIPHERS
allbut:<cbc,bf>
v cipher:mode
Specifies the ciphers and modes. Separate cipher-mode pairs with a comma. For
example: ENCCSM_CIPHERS des3:cbc,des3:ofb

default value allbut:<ecb>

The ENCCSM_CIPHERS parameter specifies the ciphers and modes to use during
encryption. For more information on ciphers and mode, see “Ciphers and Modes”
on page 5-13.

ENCCSM_MAC:
default value medium
range of values One or more of the following options, separated by commas:
v off does not use MAC generation.
v low uses XOR folding on all messages.
v medium uses SHA1 MAC generation for all messages greater than
20 bytes long and XOR folding on smaller messages.
v high uses SHA1 MAC generation on all messages.
For example: ENCCSM_MAC medium,high

5-16 IBM Informix Dynamic Server Administrator’s Guide

The ENCCSM_MAC parameter specifies the MAC level to use. For more
information on MAC levels, see “MAC Levels” on page 5-15.

ENCCSM_MACFILES:
default value builtin
units pathnames, up to 1536 bytes in length
range of values One or more full path and filenames separated by commas, and
the optional builtin keyword. For example: ENCCSM_MACFILES
/usr/local/bin/[Link],/usr/local/bin/[Link],builtin

The ENCCSM_MACFILES parameter specifies the MAC key files to use. For more
information, see “MAC Key Files” on page 5-14.

ENCCSM_SWITCH:
syntax ENCCSM_SWITCH
cipher_switch_time,key_switch_time
v cipher_switch_time specifies the minutes between cipher
renegotiation
v key_switch_time specifies the minutes between secret key
renegotiation
default value 60,60
units minutes
range of values positive integers

The ENCCSM_SWITCH parameter defines the number of minutes between cipher

and key renegotiation. For more information, see “Switch Frequency” on page 5-15.

Example of Encryption Parameter File: The following example shows an encryption

parameter file:
ENCCSM_CIPHERS all
ENCCSM_SWITCH 120,60
ENCCSM_MAC medium
ENCCSM_MACFILE /usr/informix/etc/[Link]

The following example illustrates a line in the [Link] file to specify encryption
with a parameter file:
ENCCSM("usr/informix/lib/cms/[Link]",
"config=/usr/lib/[Link]")

Using Encryption Tags: You can use encryption tags to specify encryption options
in the [Link] file.

The Cipher Tag: The cipher tag can include the cipher options shown in the
following syntax diagram.

cipher [ all ]

,

allbut: <  cipher >

,

 cipher:mode

Chapter 5. Security 5-17

 Cipher Option Description
all Specifies to include all available ciphers and all
available modes, except ECB mode. There is no value
list. For example:
cipher[all],...
allbut:<list of ciphers to exclude> Specifies to include all ciphers except the ones in the
list.

For more information, see “Ciphers and Modes” on

page 5-13.

For example:
cipher[allbut:<ecb,des>],...

cipher[allbut:<cbc,bf>]
cipher:mode Specifies one or more cipher and mode. For example:
cipher[des:cbc,des:ofb]

The default value for the cipher field is:

cipher[allbut:<ecb>]

For more information on ciphers and modes, see “Ciphers and Modes” on page
5-13.

The Mac Tag: The mac tag defines the MAC key files and the level of MAC
generation to be used during the MAC generation.

The mac tag can include the MAC options shown in the following syntax diagram.

mac [

levels: < high >
medium
low
off

files: < path , builtin > ]


builtin

Mac Option Description

levels Specifies a comma-separated list of MAC generation levels
that the connection supports.

For more information, see “MAC Levels” on page 5-15.

files Specifies a comma-separated list of the full path names of
MAC key files.

For more information, see “MAC Key Files” on page 5-14.

For example:
mac[levels:<high,low>,files:
</usr/local/bin/[Link],
/usr/local/bin/[Link],builtin>]

5-18 IBM Informix Dynamic Server Administrator’s Guide

 The Switch Tag: The switch tag defines the frequency at which ciphers and or
secret keys are renegotiated.

The switch tag can include the switch options shown in the following syntax
diagram.

switch [ ]

cipher: minutes
key: minutes
cipher: minutes , key: minutes

Switch Option Description

cipher:minutes Specifies the time in minutes between cipher
renegotiation.
key:minutes Specifies the time in minutes between secret key
renegotiation.

For example:
switch[cipher:120,key:20]

For more information on switching ciphers and modes, see “Switch Frequency” on
page 5-15.

Examples Using Encryption Tags: The following two examples illustrate alternatives
for tags you enter in the [Link] file to define the encryption CSM. For
example:
ENCCSM(“$INFORMIXDIR/lib/csm/[Link]”,
“cipher[allbut:<ecb,bf>]”)

This configuration string states to use all available ciphers except for any of the
blowfish ciphers, and to not use any cipher in ECB mode.

Another example:
ENCCSM(“/$INFORMIXDIR/lib/csm/[Link]”,
“cipher[des:cbc,ede:ofb,desx:cbc],switch[cipher:120,key:15]”)

This configuration string states to use the DES/CBC-mode, EDE/OFB-mode, and

DESX/CBC-mode ciphers for this connection and also to switch the cipher being
used every 120 minutes and renegotiate the secret key every 15 minutes.

Using Column-Level Encryption

Use the built-in ENCRYPT_AES() and ENCRYPT_TDES() encryption functions to
encrypt data in columns containing the following character data types or smart
large object data types:
v CHAR
v NCHAR
v VARCHAR
v NVARCHAR
v LVARCHAR
v BLOB
v CLOB

Chapter 5. Security 5-19

 After encrypting sensitive data, such as credit card numbers, only users who can
provide a secret password can decrypt the data.

You can also use the SET ENCRYPTION PASSWORD statement to set an
encryption password for a session. If you do this, only users who can provide a
secret password can view, copy, or modify encrypted data.

The built-in ENCRYPT_AES(), ENCRYPT_TDES(), DECRYPT_CHAR(), and

DECRYPT_BINARY() encryption and decryption functions can use the session-level
password if the password is not explicitly specified in the encryption or decryption
function. If you use the SET ENCRYPTION PASSWORD statement, you do not
need to provide the same password in every encryption or decryption function.

When you set an encryption password for a session, you can also specify a
password hint. If you specify a hint, you can store the hint with the encrypted
password or in another location. The password must be a minimum of 6 bytes and
can be a maximum of 128 bytes. The password used for decryption must match
the password used for encryption.

When you set encryption passwords for column data, you can specify these types
of encryption:
v Column Level Encryption. All values in a specific column of a database table
are encrypted with the same password (word or phrase), the same encryption
algorithm, and the same cipher mode. For column-level encryption, you can
store the hint outside the encrypted column, rather than repeating it in every
row.

Tip: If encryption functions are not used, end users could enter unencrypted
data into columns that are meant to contain encrypted data. To ensure that
data entered into a field is always encrypted, use views and ″instead-of″
triggers.
v Cell-Level Encryption (also called Row-Column and Set-Column Level Encryption).
Within a column of encrypted data, many different passwords, encryption
algorithms, or modes are used. This type of encryption might be necessary to
protect personal data.

Passwords and hints that you declare with SET ENCRYPTION PASSWORD are not
stored as plain text in any table of the system catalog. To prevent other users from
accessing the plain text of encrypted data or of a password, you must avoid
actions that might compromise the secrecy of a password:
v Unless your database is accessible only by a secure network, you must enable
the Encryption Communication Support Module (ENCCSM) to protect data
transmission between the database server and any client system.
v Do not create a functional index using the DECRYPT_CHAR() function. This
would store plain-text data in the database, defeating the purpose of encryption.
v Do not store passwords in a trigger or in a user-defined routine (UDR) that
exposes the password to the public. Use the session password before you
activate the trigger, invoke the UDR, or pass any password as a parameter to a
UDR.

When you set a password, Dynamic Server transfers the password and any hint to
a 128-bit key that is used to encrypt the password and hint. Passwords and hints
are not stored as clear text. The key is a time-based random value per instance.
The database server starts the key when the server starts; the key is destroyed
when the database server shuts down.

5-20 IBM Informix Dynamic Server Administrator’s Guide

Dynamic Server includes an Encrypt Virtual Processor. If the encrypt option of the
VPCLASS parameter is not defined in the ONCONFIG configuration file, the
database server starts one Encrypt VP the first time that any encryption or
decryption functions defined for column-level encryption are called. You can define
multiple Encrypt VPs if necessary to decrease the time needed to start the database
server. For more information, see “Encrypt Virtual Processors” on page 6-26 and
the configuration parameters chapter in the IBM Informix Dynamic Server
Administrator's Reference.

When the database server is in online mode, you can use the onmode -p command
to add or drop Encrypt VPs. For example, to add four more Encrypt VPs, use:
onmode -p 4 encrypt

To drop three Encrypt VPs, use:

onmode -p -3 encrypt

For more information, see the onmode utility chapter in the IBM Informix Dynamic
Server Administrator's Reference.

Storage Considerations
An encrypted value uses more storage space than the corresponding plain text
value. This occurs because all of the information needed to decrypt the value,
except the encryption key, is stored with the value. Therefore, embedding zero
bytes in the encrypted result is not recommended.

Encrypting Column Data

Before you set the encryption password and encrypt data, you must be sure the
encrypted data can fit in the column.

To encrypt a column:
1. Calculate the size of the encrypted column. If necessary, modify the column.
For examples of two methods for calculating the size of an encrypted column,
see “Example Showing How to Determine the Size of an Encrypted Column.”
2. Insert information on the encryption password into your code. Use the SET
ENCRYPTION PASSWORD SQL statement to specify either a password or a
password and a hint. Use the ENCRYPT_AES() or the ENCRYPT_TDES()
function to define encrypted data.
For an example of how to insert a password into your code and use the
ENCRYPT function, see “Example Showing How to Encrypt a Column” on
page 5-22.

Use the DECRYPT_BINARY(), and DECRYPT_CHAR() functions to query

encrypted data. For an example of querying encrypted data, see “Example
Showing How to Query Encrypted Data” on page 5-23.

See the IBM Informix Guide to SQL: Syntax for more informations about:
v The SET ENCRYPTION PASSWORD statement and the syntax to use to specify
the password and the hint
v The ENCRYPT and DECRYPT functions

Example Showing How to Determine the Size of an Encrypted

Column
The following example shows how the size of a Credit Card column is calculated:

Chapter 5. Security 5-21

 DATA SIZE 16 bytes
ENCRYPTED DATA SIZE = (DATA SIZE + blocksize8) / blocksize8 *
blocksize8 = 24 bytes (integer operation)
OR ENCRYPTED DATA SIZE = (DATA SIZE - DATA SIZE% blocksize8 +
blocksize8 ) = 24 bytes
(For ENCRYPT_TDES, round up to (N + 1) * 8 bytes, for example
13 bytes round up to 16 bytes, 16 bytes to 24 bytes)
HEADER SIZE = 11 bytes (for Base64 encoding)
IV SIZE = 8 bytes (fixed size)
HINT SIZE = 32 bytes (maximum size)
ENCRYPED HINT SIZE = 40 bytes (maximum size)

BASE64 SIZE = ((INPUT DATA SIZE + 2) / 3) * 4

(integer operation)
OR BASE64 SIZE = ((INPUT DATA SIZE + 2) -
(INPUT DATA SIZE + 2) % 3) / 3 * 4

TOTAL SIZE = HEADER SIZE

+ BASE64(IV SIZE + ENCRYPTED DATA SIZE + ENCRYPTED HINT)
= 11 + BASE64(8 + 24 + 40)
= 11 + (72 + 2) / 3 * 4
= 11 + 96 = 107

In the previous example, Initialization Vector (IV) is a pseudo-random series of

bytes that is used to initiate encryption when using some cipher modes. IV size is
the number of random series of bytes; for Dynamic Server, this is 8 bytes.

If the hint is not stored in the column, the total size in the previous example is 55
bytes.

Tip: Another way to determine the encrypted column size is to calculate as

follows:
SELECT LENGTH(ENCRYPT_TDES
("1234567890123456",
"password", "long....hint"))
FROM "informix".systables WHERE tabid = 1

Without the hint, you can calculate as follows:

SELECT LENGTH(ENCRYPT_TDES("1234567890123456",
"password", ""))
FROM "informix".systables
WHERE tabid = 1

Important: If the column size is smaller than the returned data size from
ENCRYPT/DECRYPT functions, the encrypted data is truncated when
it is inserted and it is not possible to decrypt the data (because the
header will indicate that the length should be longer than the data
received).

Example Showing How to Encrypt a Column

The following example shows how to use the encryption password in a column
that contains a social security number:
create table emp
( name char(40),
salary money,
ssn lvarchar(67)
);
set encryption password "one two three 123";
insert into emp values ("Alice", 50000, encrypt_aes
(’123-456-7890’));

5-22 IBM Informix Dynamic Server Administrator’s Guide

 insert into emp values ("Bob", 65000, encrypt_aes
(’213-656-0890’));
select name, salary, decrypt_char(ssn, "one two three 123")
from emp where name = ’Bob’;

Example Showing How to Query Encrypted Data

The following example shows how to use the decrypt function to query encrypted
data:
select name, decrypt_char(ssn, "one two three 123") from emp;
or
set encryption password "one two three 123";
select name, salary, decrypt_char(ssn) from emp where name = ’Bob’;

Authentication Modules
Depending on your platform, you can use one of the following authentication
modules:
v Pluggable Authentication Module (PAM) for Dynamic Server systems running
on UNIX or Linux. These modules enable you to implement different
authentication modules for different applications. For more information, see
“Pluggable Authentication Modules for Systems Running on UNIX or Linux”
below.
v Lightweight Directory Access Protocol (LDAP) Authentication Support for
Windows. Use the LDAP Authentication Support module when you want to use
an LDAP server to authenticate users. For more information, see “LDAP
Authentication Support on Windows” on page 5-25.

Pluggable Authentication Modules for Systems Running on

UNIX or Linux
A Pluggable Authentication Module (PAM) is a well-defined framework for
supporting different authentication modules originally developed by Sun
Microsystems.

PAM enables system administrators to implement different authentication

mechanisms for different applications. For example, the needs of a system like the
UNIX login program might be different from an application that accesses sensitive
information from a database. PAM allows for many such scenarios in a single
machine, because the authentication services are attached at the application level.

In addition to enabling an application to select the authentication as needed, PAM

permits module stacking. Many modules can be stacked one after another, thus
enabling the application to be authenticated in multiple ways, before granting
access. PAM provides a set of APIs to support authentication, account
Management, session Management and password management.

The system administrator can enable or disable the use of PAM. By default, the
database server uses the traditional Informix authentication mechanism (which is
based on the BSD rhosts mechanism) in order to avoid forcing major changes on
users.

To use PAM with Dynamic Server:

v Your Informix database server must be on an operating system platform that
supports PAM.
v Your client applications must be written using a sufficiently recent version of
Client SDK.

Chapter 5. Security 5-23

 v You must have the appropriate PAM service configured in the operating system.
v You must know whether the PAM service will simply accept the given password
or whether it will use a challenge-response protocol (for example, a RADIUS
authentication server).
v If your PAM service will use a challenge-response protocol, you must modify
your applications to handle the challenge and response. The application must be
aware that the PAM module can raise multiple challenges.
v You must ensure that Enterprise Replication and High-Availability Data
Replication are not affected by PAM authentication.
v You must modify the server entry in the sqlhosts file for both the client
application and the database server (if they are on separate machines or in
separate locations on a single machine).

These changes are discussed in more detail below.

Supported Platforms
PAM is supported on Solaris and Linux, in both 32- and 64-bit modes.

On HP-UX and AIX, PAM is supported in 32-bit mode only.

The Name of the PAM Service

The PAM service name identifies the PAM module. This PAM module typically
resides in /usr/lib/security and its parameters are listed in the file /etc/[Link].

In Linux, /etc/[Link] can be replaced with a directory called /etc/pam.d, where

there is a file for each PAM service. If /etc/pam.d exists, /etc/[Link] will be
ignored by Linux. See the system documentation for the details of this
configuration file.

Authentication Mode
The PAM module determines whether a simple password is sufficient or other
challenges are required. The PAM implementation in Dynamic Server takes
advantage of the fact that for explicit connections, a password is sent to the server
by the client. This password can be used to satisfy PAM in cases where a simple
password is used. If the authentication mode involves responding to challenges,
the applications must be prepared to respond to them. The application must be
aware that the PAM module might raise multiple challenges.

Required Stack Size

The PAM feature loads OS or third-party PAM modules (shared libraries) into the
informix user thread. The stack size requirements of these PAM modules cannot be
predicted. For instance, on Linux some modules need more than 128K of stack
space. Use the PAM_STACKSIZE configuration parameter to customize the stack
size for PAM modules. The default value of PAM_STACKSIZE is 32 KB.

For example, set PAM_STACKSIZE in the ONCONFIG file as follows:

PAM_STACKSIZE 64 # Stack size needed for the PAM modules
(K Bytes)

On Linux, the default value is 128 KB plus the value of the STACKSIZE
configuration parameter.

5-24 IBM Informix Dynamic Server Administrator’s Guide

 Implicit Connections
PAM is a challenge oriented system, in that the authentication response (the
password) is supplied in response to a PAM message. In implicit connections to
the database server, there is no password.

Therefore, implicit connections can work under PAM only in challenge mode.
Implicit connections in password mode will result in failure.

Configuring a Database Server to Use PAM

To configure a server to use PAM, the system administrator must know:
v The name of the PAM module.
v Whether the PAM module will raise a challenge in addition to accepting a
simple username and password combination.

The following example shows an sqlhosts entry with illustrative names:

Authentication mode: challenge
ifxserver2 oltlitcp servermc portnum2 options
where options are "s=4, pam_serv=(pam_pass), pamauth=(challenge)"
PAM service: pam_password (Needs only a password)
Authentication mode: password
ifxserver2 oltlitcp servermc portnum2 options
where options are "s=4, pam_serv=(pam_pass), pamauth=(password)"

Enterprise Replication and High-Availability Data Replication

Enterprise Replication and High-Availability Data Replication (HDR) cannot
respond to challenges, if the authentication scheme calls for it. For this reason,
Enterprise Replication and HDR must not be configured in the port using PAM.
For information on the facility to dedicate ports to Enterprise Replication and
HDR, see “Enterprise Replication and High-Availability Data Replication
Connection Security Option” on page 5-31.

Application Development
The process for preparing an application to respond to challenges raised by PAM is
the same process to use when responding to challenges raised by LDAP
Authentication Support modules. For more information, see “Application
Development for Authentication Modules” on page 5-27.

Distributed Transactions with PAM, Client APIs, and

Compatibility Issues
Distributed transactions, APIs that support PAM, and compatibility issues with
other IBM Informix products and tools are the same for both PAM and LDAP
Authentication Support modules. For more information, see “Distributed
Transactions” on page 5-29, “Client APIs and Authentication Support Modules” on
page 5-30, and “Compatibility Issues” on page 5-30.

LDAP Authentication Support on Windows

LDAP Authentication on Windows is set up and configured like the Pluggable
Authentication Module (PAM) that is used on UNIX and Linux. Use the LDAP
Authentication Support module when you want to use an LDAP server to
authenticate your system users. The module contains source code that you can
modify for your specific LDAP Authentication Support module.

The authentication module is a DLL that usually resides in the

%INFORMIXDIR%\dbssodir\lib\security directory. The parameters of the
module are listed in the %INFORMIXDIR%\dbssodir\[Link] file. The source

Chapter 5. Security 5-25

 code for a fully functional LDAP Authentication Module and samples of the
required configuration files are included in the
%INFORMIXDIR%\demo\authentication directory.

The LDAP Authentication Module provides single-module authentication only. The

module does not support features such as module stacking. The system
administrator can enable or disable the authentication.

Installing and Customizing the LDAP Authentication Support

Module
Before you can use the Dynamic Server LDAP Authentication Module to create
your authentication module, you must have an LDAP server and the LDAP
client-side system. Examples of LDAP systems are IBM Directory Server and
openLDAP.

Your LDAP client-side system typically includes LDAP libraries and header files.
These libraries and header files are required to compile the LDAP module.

To customize the module:

1. Customize the pam_ldap.c file that is included with Dynamic Server.
2. Compile the pam_ldap.c file into a DLL and place it in a secure directory.
Recommendation: Place the pam_ldap.c file in the
%INFORMIXDIR%\dbssodir\lib directory.

Your installation also includes a template of a configuration file, pam_ldap_tmpl,

for the LDAP module. This configuration file contains site specific information. You
should store site-specific information in this configuration file, because the file
enables a single LDAP module to work in different settings.

Configuring the LDAP Module

Use the template of a PAM configuration file to configure your LDAP module.

To configure your LDAP module:

1. Copy the template file to %INFORMIXDIR%\dbssodir\etc and name it
[Link].
2. Customize the file to accommodate your local security settings. See the
template file, pam.conf_tmpl, for details about how to customize the file.

Configuring Dynamic Server

To configure a server to use an LDAP Authentication Support module, edit the
sqlhosts file. The system administrator must know:
v The name of the module.
v Whether the module will raise a challenge in addition to accepting a simple
username and password combination.

The following example shows an sqlhosts entry with descriptive names:

PAM service: pam_chal

Authentication mode: challenge

ifxserver1 oltlitcp servermc portnum1
s=4, pam_serv=(pam_chal), pamauth=(challenge)

PAM service: pam_password (Needs only a password)

5-26 IBM Informix Dynamic Server Administrator’s Guide

 Authentication mode: password
ifxserver2 oltlitcp servermc portnum2
s=4, pam_serv=(pam_pass), pamauth=(password)

Authentication Mode
The LDAP Authentication Support module determines whether a simple password
is sufficient or other challenges are required. Implementation of the module in
Dynamic Server takes advantage of the fact that for explicit connections, a
password is sent to the server by the client. This password can be used to satisfy
the LDAP Authentication Support module in cases where a simple password is
used. If the authentication mode involves responding to single or multiple
challenges, the applications must be able to respond to the challenges.

Implicit Connections
The LDAP Authentication Support module is a challenge oriented system, in that
the authentication response (the password) is supplied in response to an LDAP
Authentication Support module message. In implicit connections to the database
server, there is no password.

Implicit connections can work under the LDAP Authentication Support module
only in challenge mode. Implicit connections in password mode result in failure.

Enterprise Replication and High-Availability Data Replication

Enterprise Replication and High-Availability Data Replication (HDR) cannot
respond to challenges, if the authentication scheme calls for it. For this reason,
Enterprise Replication and HDR must not be configured on the port that uses the
LDAP Authentication Support module. For information on the facility to dedicate
ports to Enterprise Replication and HDR, see “Enterprise Replication and
High-Availability Data Replication Connection Security Option” on page 5-31.

Application Development
The process for preparing an application to respond to challenges raised by LDAP
Authentication Support modules is the same process to use when responding to
challenges raised by PAM modules. For more information, see “Application
Development for Authentication Modules.”

Distributed Transactions with LDAP Support Modules, Client

APIs, and Compatibility Issues
Distributed transactions, APIs that support LDAP Authentication Support modules,
and compatibility issues with other IBM Informix products and tools are the same
for both PAM and LDAP Authentication Support modules. For more information,
see “Distributed Transactions” on page 5-29, “Client APIs and Authentication
Support Modules” on page 5-30, and “Compatibility Issues” on page 5-30.

Application Development for Authentication Modules

The authentication method depends on the PAM or LDAP Authentication Support
module installed. The method can involve challenge and response. When the PAM
or LDAP Authentication Support module raises a challenge, these processes occur:
1. The database server forwards the challenge to the client.
2. The application must respond to the challenge using a callback function that is
provided by the IBM Informix CSDK and the IBM Informix JDBC driver.
3. If the server to which the client is connecting is set up for challenge, the
application must register a callback function with CSDK or JDBC.
4. When CSDK or JDBC receive a challenge from the server, the challenge is
forwarded to the application by the callback function.

Chapter 5. Security 5-27

 5. The application must respond to the challenge.
6. CSDK or JDBC forwards the response to the database server.

The application must be prepared to respond to multiple challenges and cannot

assume the number of challenges or the challenges themselves.

The callback function should look like the following function:

mint ifx_pam_callback(mint (*callbackfunc_ptr)(char *challenge,
char *response, mint msg_style))
char *challenge
the character buffer in which the challenge is given by the server. The size
of this is fixed at 512, defined by PAM_MAX_MSG_SIZE in the
pam_appl.h file.
char *response
the character buffer in which the response is provided by the user. The size
of this is fixed at 512, defined by PAM_MAX_RESP_SIZE in the
pam_appl.h file.
int msg_style
contains a number that indicates the type of the message given by the
server. Based on the type of the response, the application can take
appropriate action in the callback function.

The client application must register the callback function before making the first
connection. If the callback function is not registered when the first connection is
made to the database server, and the server responds, then ESQL/C returns error
-1809.

The example below shows a very simple program that first registers a callback
function and then unregister it.
#include <stdio.h>
#include <security/pam_appl.h>

static int user_callback(char *challenge, char *response,

int msg_style);

int main(void)
{
EXEC SQL char passwd[]="password";
int retval = 0;

/* first register the callback */

retval = ifx_pam_callback(user_callback);

if (retval == -1)
{
printf("Error in registering callback\n");
return (-1);
}
else
{
EXEC SQL database test; /* successful connection */
/* Note that this is an implicit connection. So, the
* application should be ready to respond to challenges.*/
printf ("sqlcode on pam connect = %d\n", SQLCODE);
}

retval = ifx_pam_callback(NULL); /* unregister the callback

* function */

5-28 IBM Informix Dynamic Server Administrator’s Guide

 if (retval == -1)
{
printf("Error in registering callback\n");
return (-1);
}
else
{
/* This connection throw error -1809, since the callback
* function was unregistered statement */
EXEC SQL database test;
printf ("sqlcode on connect = %d\n", SQLCODE);
}
return 0;
}

static int user_callback(char *challenge, char *response,

int msg_style)
{
switch (msg_style)
{
/* If the msg_style is PAM_PROMPT_ECHO_OFF, the
* application should not echo the user’s response. */
case PAM_PROMPT_ECHO_OFF:
case PAM_PROMPT_ECHO_ON :
printf("%s: %d:", challenge, msg_style);
scanf("%.*s", PAM_MAX_RESP_SIZE, response);
break;

case PAM_ERROR_MSG:
case PAM_TEXT_INFO:
default:
printf("%s: %d\n", challenge, msg_style);
break;
}
return 0;
}

Distributed Transactions
Distributed connections cannot respond to challenges, because when a distributed
connection can be made cannot be predicted. Authentication on the remote servers
must be done within the database. A new database, called sysusers, can be used to
administer remote connections.

If PAM or an LDAP Authentication Support Module is enabled in the remote

servers, the system administrator needs to enter authorized users in the sysauth
table in the sysusers database for each remote server.

Database: sysusers

Table: sysauth

The sysauth table in the sysusers database has the following structure:

Column Structure
Username char(32)
Groupname char(32)
Servers char(128)
Hosts char(128)

Chapter 5. Security 5-29

 The table can contain multiple rows for a single user to authenticate for multiple
servers and hosts.

The following example enables the server to accept distributed transactions from
user user1, belonging to group group1, from database server server1, and from
host [Link]:
insert into sysauth values ("user1", "group1", "server1",
"[Link]");

Client APIs and Authentication Support Modules

The following IBM Informix client APIs support PAM and LDAP Authentication
Support modules:
v ESQL/C
v ODBC
v JDBC

The other APIs do not support PAM and LDAP Authentication Support modules.
To use them against a version of Dynamic Server that has an enabled
authentication module, connect to a DBSERVERALIAS that does not have the PAM
parameters in the sqlhosts file.

The following client APIs, tools and applications do not support PAM or LDAP
Authentication Support modules:
v LibC++
v Libdmi
v OLEDB
v VB Applications using ODBC
v Ilogin, dbping and ODBC Test connection
v ISA

Compatibility Issues
Not all IBM Informix products and tools support PAM or LDAP authentication:
v IBM Informix-4GL does not directly support PAM or LDAP authentication
because it has no mechanism for identifying callback functions. However, if IBM
Informix-4GL uses the correct version of CSDK, you can write C code that can
be called from IBM Informix-4GL to handle the challenge and response protocol.
To implement PAM, migrate to the new CSDK version, modify your applications
to register a callback that can handle challenges and responses, and recompile
your application.
v Products such as Informix SQL will not handle the challenge and response
protocol.
v The DB-Access, dbexport, dbimport, dbload, and dbschema utilities support
PAM. If they receive a challenge, they pass the challenge to the user and wait for
a response. This is repeated for each challenge that the PAM module raises.
v The onmode, onstat, and oncheck server administration utilities do not use
PAM. However, because these utilities operate on all Dynamic Server ports, the
utilities can function with a PAM-enabled port.
v Other server utilities do not support PAM.

5-30 IBM Informix Dynamic Server Administrator’s Guide

 If you are using any tools that do not support PAM or LDAP authentication
modules, then make connections to a DBSERVERALIAS that does not have the
PAM parameters in the SQLHOSTS file.

Enterprise Replication and High-Availability Data Replication

Connection Security Option
You can increase security for Enterprise Replication and High-Availability Data
Replication (HDR) connections with a new configuration option in the
INFORMIXSQLHOSTS file.

Add s=6 to the options (fifth) field in the INFORMIXSQLHOSTS files to indicate
that the corresponding port accepts only Enterprise Replication or HDR connection
requests. Any other type of connection request will be rejected with error number
-25539, invalid connection type.

Here is an outline of a INFORMIXSQLHOSTS file entry:

dbservername nettype hostname servicename s=6

For example:
ifxer1 oltlitcp mc001 er_port s=6,Other_ER_Parameters

When you set s=6, the Enterprise Replication (ER) or HDR connection requests are
authenticated using a new mechanism. The system administrator should create a
file [Link] file in the $INFORMIXDIR/etc directory and add the names of the
participating Enterprise Replication and HDR nodes (host names, as would be
found in the third column of the INFORMIXSQLHOSTS file) in that file, one per
line. The format of the file is similar to the UNIX /etc/[Link] file. The file
should be owned by user informix, belong to group informix, and the permissions
should be restricted so that at most user informix can modify the file (using octal
permissions, one of the values 644, 640, 444, or 440 is appropriate).

If the configuration is such that the replicating servers are on the same machine,
then the $INFORMIXDIR/etc/[Link] file is not needed.

The following restrictions apply to this security option:

v For Enterprise Replication or HDR-only ports, s=6 should be the only security
option present. No other security option (s=0,1,2,3,4) should be used when s=6 is
used.
v This option is specific to the database server environment for Enterprise
Replication and HDR, so it should not be used in the client environment. Clients
will return an error if this option is set in SQLHOSTS file and the client attempts
to use the associated server name.

Recommendation: Dedicate the database server name or a database server alias for
administering the secure connectivity. For example, if you are using HDR, execute
the onmode -d primary secondary_servername command with INFORMIXSERVER
set to the secure database server or alias name. Then execute the ontape or onbar
restore commands (for example, ontape -p) that are part of HDR initialization
using a different, non-secure INFORMIXSERVER setting. Likewise, use a different,
non-secure INFORMIXSERVER for other client applications, such as DB-Access.

For information on HDR, see Chapter 20, “High-Availability Data Replication

(Enterprise/Workgroup Editions),” on page 20-1. For information on Enterprise
Replication, see IBM Informix Dynamic Server Enterprise Replication Guide.

Chapter 5. Security 5-31

 Security for External Routines (UDRs)
External routines with shared libraries that are outside the database server can be
security risks. External routines include user-defined routines (UDRs) and the
routines in DataBlade modules. A database server administrator (DBSA), the user
informix by default, can implement security measures that establish which users
can register external routines. This prevents unauthorized users from registering
the external routines.

Use the IFX_EXTEND_ROLE configuration parameter to restrict the ability of users

to register external routines.

The default value of the IFX_EXTEND_ROLE configuration parameter is 1 (on). (In

versions 10.00.UC1 to 10.00.UC3 of Dynamic Server), the default was 0 (off).)

When the IFX_EXTEND_ROLE configuration parameter is set to on:

v You can grant a user privileges to create or drop a UDR that has the EXTERNAL
clause.
v The EXTEND role is operational and you can grant a user privileges to create or
drop an external routine that has the EXTERNAL clause.
When you grant the EXTEND role to a specific user, the sysroleauth system
catalog table is updated to reflect the new built-in role.

After you set the IFX_EXTEND_ROLE configuration parameter to On, a DBSA can
use the following syntax to grant and revoke privileges to and from specific users.
v GRANT extend To username
v REVOKE extend From username

If you do not want to restrict UDR access, set the IFX_EXTEND_ROLE

configuration parameter to0 ( Off). When the IFX_EXTEND_ROLE parameter is set
to Off, the EXTEND role is not operational and any user can register external
routines.

The DB-Import Utility, in particular, is affected when the IFX_EXTEND_ROLE

configuration parameter is set to 1 (on) because a user who uses DB-Import to
create a new database has not been given an extend role on that database.

For more information, see the IBM Informix Guide to SQL: Syntax.

4 Security for Loading External Modules

4 Use the DB_LIBRARY_PATH configuration parameter to specify a
4 comma-separated list of valid directory prefix locations from which the database
4 server can load external modules, such as DataBlade modules.
4 DB_LIBRARY_PATH takes effect when the database server is restarted after the
4 parameter has been set.

4 The DB_LIBRARY_PATH configuration parameter allows you to control the

4 location from which shared objects can be loaded, and it allows you to enforce
4 policies and standards on the formats of the EXTERNAL NAME clause of the
4 CREATE FUNCTION, CREATE PROCEDURE, and CREATE ROUTINE statements.

5-32 IBM Informix Dynamic Server Administrator’s Guide

4 If the DB_LIBRARY_PATH configuration parameter is not set or is not present in
4 the ONCONFIG file, security checks for loading external modules are not
4 performed.

4 You should include in the DB_LIBRARY_PATH settings every file system in which
4 your security policy authorizes DataBlades and UDRs to reside. DataBlades
4 provided with Dynamic Server are stored under the $INFORMIXDIR/extend
4 directory. For extensibility to work properly when security is turned on, the string
4 ″$INFORMIXDIR/extend″ must be part of DB_LIBRARY_PATH.

4 For more information on the DB_LIBRARY_PATH configuration parameter, see the

4 IBM Informix Dynamic Server Administrator's Reference. Also see the IBM Informix
4 Guide to SQL: Syntax for information on using DB_LIBRARY_PATH with
4 IFX_EXTEND_ROLE.

3 Enabling non-DBAs to View SQL Statements a Session Is Executing

3 The onstat commands that show the SQL statement text that a session is executing
3 are normally restricted to DBA users. You can set the UNSECURE_ONSTAT
3 configuration parameter to 1 to remove this restriction. Removing this restriction
3 enables other users to execute onstat -ses, onstat -stm, onstat -ssc, and onstat -sql
3 commands.

3 The UNSECURE_ONSTAT configuration parameter takes effect when the database

3 server is shut down and restarted.

Chapter 5. Security 5-33

5-34 IBM Informix Dynamic Server Administrator’s Guide
Part 2. Disk, Memory, and Process Management

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
Chapter 6. Virtual Processors and Threads
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2
Types of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3
Advantages of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5
Sharing Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Saving Memory and Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Processing in Parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-6
Adding and Dropping Virtual Processors in Online Mode . . . . . . . . . . . . . . . . . 6-7
Binding Virtual Processors to CPUs . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
How Virtual Processors Service Threads . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Control Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Context Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-8
Stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-9
Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Ready Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10
Sleep Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Wait Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Virtual-Processor Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
CPU Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12
Determining the Number of CPU Virtual Processors Needed . . . . . . . . . . . . . . . . 6-12
Running on a Multiprocessor Computer . . . . . . . . . . . . . . . . . . . . . . . 6-13
Running on a Single-Processor Computer . . . . . . . . . . . . . . . . . . . . . . . 6-13
Adding and Dropping CPU Virtual Processors in Online Mode . . . . . . . . . . . . . . . 6-14
Preventing Priority Aging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
Using Processor Affinity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-14
User-Defined Classes of Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . 6-15
Determining the Number of User-Defined Virtual Processors Needed . . . . . . . . . . . . . 6-15
Using User-Defined Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . 6-15
Specifying a User-Defined Virtual Processor . . . . . . . . . . . . . . . . . . . . . . 6-16
Assigning a UDR to a User-Defined Virtual-Processor Class . . . . . . . . . . . . . . . . 6-16
Adding and Dropping User-Defined Virtual Processors in Online Mode . . . . . . . . . . . . 6-17
Java Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
Disk I/O Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17
I/O Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Logical-Log I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-18
Physical-Log I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
Asynchronous I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19
Network Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20
Specifying Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . 6-21
Running Poll Threads on CPU or Network Virtual Processors . . . . . . . . . . . . . . . . 6-21
Specifying the Number of Networking Virtual Processors . . . . . . . . . . . . . . . . . 6-22
Specifying Listen and Poll Threads for the Client/Server Connection . . . . . . . . . . . . . 6-22
Starting Multiple Listen Threads . . . . . . . . . . . . . . . . . . . . . . . . . . 6-24
Communications Support Module Virtual Processor . . . . . . . . . . . . . . . . . . . . 6-25
Encrypt Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Optical Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26
Audit Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

© Copyright IBM Corp. 1996, 2005 6-1

 Miscellaneous Virtual Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

In This Chapter
This chapter explains how the database server uses virtual processors and threads
within virtual processors to improve performance. It explains the types of virtual
processors and how threads run within the virtual processors.

Virtual Processors
Database server processes are called virtual processors because the way they
function is similar to the way that a CPU functions in a computer. Just as a CPU
runs multiple operating-system processes to service multiple users, a database
server virtual processor runs multiple threads to service multiple SQL client
applications.

A virtual processor is a process that the operating system schedules for processing.

Figure 6-1 illustrates the relationship of client applications to virtual processors. A

small number of virtual processors serve a much larger number of client
applications or queries.

Client applications

Client Client Client

Client Client Client Client

Virtual processors

CPU 1 CPU 2 CPU 3 CPU 4

Figure 6-1. Virtual Processors

Threads
A thread is a task for a virtual processor in the same way that the virtual processor
is a task for the CPU. The virtual processor is a task that the operating system
schedules for execution on the CPU; a database server thread is a task that the
virtual processor schedules internally for processing. Threads are sometimes called
lightweight processes because they are like processes, but they make fewer demands
on the operating system.

6-2 IBM Informix Dynamic Server Administrator’s Guide

 Database server virtual processors are multithreaded because they run multiple
concurrent threads.

The nature of threads is as follows.

Operating System Description of Thread
UNIX A thread is a task that the virtual processor
schedules internally for processing.
Windows A thread is a task that the virtual processor
schedules internally for processing. Because the
virtual processor is implemented as a Windows
thread, database server threads run within
Windows threads.

Important: Throughout this chapter, all references to “thread” refer to the threads
created, scheduled, and destroyed by the database server. All references
to “Windows threads” refer to the threads created, scheduled, and
destroyed by Windows.

A virtual processor runs threads on behalf of SQL client applications (session

threads) and also to satisfy internal requirements (internal threads). In most cases,
for each connection by a client application, the database server runs one session
thread. The database server runs internal threads to accomplish, among other
things, database I/O, logging I/O, page cleaning, and administrative tasks. For
cases in which the database server runs multiple session threads for a single client,
refer to “Processing in Parallel” on page 6-6.

A user thread is a database server thread that services requests from client
applications. User threads include session threads, called sqlexec threads, which
are the primary threads that the database server runs to service client applications.

User threads also include a thread to service requests from the onmode utility,
threads for recovery, B-tree scanner threads, and page-cleaner threads.

To display active user threads, use onstat -u. For more information on monitoring
sessions and threads, refer to your IBM Informix Dynamic Server Performance Guide.

Types of Virtual Processors

Table 6-1 shows the classes of virtual processors and the types of processing that
they do. Each class of virtual processor is dedicated to processing certain types of
threads.

The number of virtual processors of each class that you configure depends on the
availability of physical processors (CPUs), hardware memory, and the database
applications in use.
Table 6-1. Virtual-Processor Classes
Virtual-
Processor
Class Category Purpose
CPU Central processing Runs all session threads and some system threads. Runs thread for
kernel asynchronous I/O (KAIO) where available. Can run a single poll
thread, depending on configuration.
PIO Disk I/O Writes to the physical-log file (internal class) if it is in cooked disk space.

Chapter 6. Virtual Processors and Threads 6-3

Table 6-1. Virtual-Processor Classes (continued)
Virtual-
Processor
Class Category Purpose
LIO Disk I/O Writes to the logical-log files (internal class) if they are in cooked disk
space.
AIO Disk I/O Performs nonlogging disk I/O. If KAIO is used, AIO virtual processors
perform I/O to cooked disk spaces.
SHM Network Performs shared memory communication.
TLI Network Uses the Transport Layer Interface (TLI) to perform network
communication.
SOC Network Uses sockets to perform network communication.
OPT Optical Performs I/O to optical disk.
(UNIX)
ADM Administrative Performs administrative functions.
ADT Auditing Performs auditing functions.
MSC Miscellaneous Services requests for system calls that require a very large stack.
CSM Communications Performs communications support service operations.
Support Module
Encrypt Encryption Used by the database server when encryption or decryption functions are
called.
classname User defined Runs user-defined routines in a thread-safe manner so that if the routine
fails, the database server is unaffected. Specified with the VPCLASS
configuration parameter. You must specify classname.
Java VP (JVP) Java UDR Executes Java UDRs. Contains the Java Virtual Machine (JVM).

Figure 6-2 illustrates the major components and the extensibility of the database
server.

6-4 IBM Informix Dynamic Server Administrator’s Guide

 Client Client Client

Client applications

Client Client Client Client

Threads Virtual processors

AIO AIO User defined

User defined
CPU
Database server CPU
CPU CPU

DataBlade API
DataBlade

DataBlade

DataBlade

DataBlade

Date & Time

Text
Audio DataBlade
Graphics

Numbers Spatial Documents

Video

Figure 6-2. Database Server

Advantages of Virtual Processors

Compared to a database server process that services a single client application, the
dynamic, multithreaded nature of a database server virtual processor provides the
following advantages:
v Virtual processors can share processing.
v Virtual processors save memory and resources.
v Virtual processors can perform parallel processing.
v You can start additional virtual processors and terminate active CPU virtual
processors while the database server is running.
v You can bind virtual processors to CPUs.

The following sections describe these advantages.

Chapter 6. Virtual Processors and Threads 6-5

 Sharing Processing
Virtual processors in the same class have identical code and share access to both
data and processing queues in memory. Any virtual processor in a class can run
any thread that belongs to that class.

Generally, the database server tries to keep a thread running on the same virtual
processor because moving it to a different virtual processor can require some data
from the memory of the processor to be transferred on the bus. When a thread is
waiting to run, however, the database server can migrate the thread to another
virtual processor because the benefit of balancing the processing load outweighs
the amount of overhead incurred in transferring the data.

Shared processing within a class of virtual processors occurs automatically and is

transparent to the database user.

Saving Memory and Resources

The database server is able to service a large number of clients with a small
number of server processes compared to architectures that have one client process
to one server process. It does so by running a thread, rather than a process, for
each client.

Multithreading permits more efficient use of the operating-system resources

because threads share the resources allocated to the virtual processor. All threads
that a virtual processor runs have the same access to the virtual-processor memory,
communication ports, and files. The virtual processor coordinates access to
resources by the threads. Individual processes, on the other hand, each have a
distinct set of resources, and when multiple processes require access to the same
resources, the operating system must coordinate the access.

Generally, a virtual processor can switch from one thread to another faster than the
operating system can switch from one process to another. When the operating
system switches between processes, it must stop one process from running on the
processor, save its current processing state (or context), and start another process.
Both processes must enter and exit the operating-system kernel, and the contents
of portions of physical memory might need to be replaced. Threads, on the other
hand, share the same virtual memory and file descriptors. When a virtual
processor switches from one thread to another, the switch is simply from one path
of execution to another. The virtual processor, which is a process, continues to run
on the CPU without interruption. For a description of how a virtual processor
switches from one thread to another, refer to “Context Switching” on page 6-8.

Processing in Parallel
In the following cases, virtual processors of the CPU class can run multiple session
threads, working in parallel, for a single client:
v Index building
v Sorting
v Recovery
v Scanning
v Joining
v Aggregation
v Grouping
v User-defined-routine (UDR) execution

6-6 IBM Informix Dynamic Server Administrator’s Guide

For more information on parallel UDR execution, refer to IBM Informix User-Defined
Routines and Data Types Developer's Guide.

Figure 6-3 illustrates parallel processing. When a client initiates index building,
sorting, or logical recovery, the database server spawns multiple threads to work
on the task in parallel, using as much of the computer resources as possible. While
one thread is waiting for I/O, another can be working.

Indexing
Client sorting
recovery

Virtual processors

CPU 1 CPU 2 CPU 3 CPU 4

Figure 6-3. Parallel Processing

Adding and Dropping Virtual Processors in Online Mode

You can add virtual processors to meet increasing demands for service while the
database server is running. For example, if the virtual processors of a class become
compute bound or I/O bound (meaning that CPU work or I/O requests are
accumulating faster than the current number of virtual processors can process
them), you can start additional virtual processors for that class to distribute the
processing load further.

You can add virtual processors for any of the classes while the database server is
running. For more information, see “Adding Virtual Processors in Online Mode”
on page 7-3.

Windows Only

In Windows, you cannot drop a virtual processor of any class.

End of Windows Only

While the database server is running, you can drop virtual processors of the CPU
or a user-defined class. For more information, see “Setting Virtual-Processor
Configuration Parameters” on page 7-1.

Binding Virtual Processors to CPUs

Some multiprocessor systems allow you to bind a process to a particular CPU. This
feature is called processor affinity.

On multiprocessor computers for which the database server supports processor

affinity, you can bind CPU virtual processors to specific CPUs in the computer.
When you bind a CPU virtual processor to a CPU, the virtual processor runs
exclusively on that CPU. This operation improves the performance of the virtual
processor because it reduces the amount of switching between processes that the
operating system must do. Binding CPU virtual processors to specific CPUs also

Chapter 6. Virtual Processors and Threads 6-7

 enables you to isolate database work on specific processors on the computer,
leaving the remaining processors free for other work. Only CPU virtual processors
can be bound to CPUs.

For information on how to assign CPU virtual processors to hardware processors,

refer to “Using Processor Affinity” on page 6-14.

How Virtual Processors Service Threads

At a given time, a virtual processor can run only one thread. A virtual processor
services multiple threads concurrently by switching between them. A virtual
processor runs a thread until it yields. When a thread yields, the virtual processor
switches to the next thread that is ready to run. The virtual processor continues
this process, eventually returning to the original thread when that thread is ready
to continue. Some threads complete their work, and the virtual processor starts
new threads to process new work. Because a virtual processor continually switches
between threads, it can keep the CPU processing continually. The speed at which
processing occurs produces the appearance that the virtual processor processes
multiple tasks simultaneously and, in effect, it does.

Running multiple concurrent threads requires scheduling and synchronization to

prevent one thread from interfering with the work of another. Virtual processors
use the following structures and methods to coordinate concurrent processing by
multiple threads:
v Control structures
v Context switching
v Stacks
v Queues
v Mutexes

This section describes how virtual processors use these structures and methods.

Control Structures
When a client connects to the database server, the database server creates a session
structure, which is called a session control block, to hold information about the
connection and the user. A session begins when a client connects to the database
server, and it ends when the connection terminates.

Next, the database server creates a thread structure, which is called a thread-control
block (TCB) for the session, and initiates a primary thread (sqlexec) to process the
client request. When a thread yields—that is, when it pauses and allows another
thread to run—the virtual processor saves information about the state of the thread
in the thread-control block. This information includes the content of the process
system registers, the program counter (address of the next instruction to execute),
and the stack pointer. This information constitutes the context of the thread.

In most cases, the database server runs one primary thread per session. In cases
where it performs parallel processing, however, it creates multiple session threads
for a single client, and, likewise, multiple corresponding thread-control blocks.

Context Switching
A virtual processor switches from running one thread to running another one by
context switching. The database server does not preempt a running thread, as the

6-8 IBM Informix Dynamic Server Administrator’s Guide

 operating system does to a process, when a fixed amount of time (time-slice)
expires. Instead, a thread yields at one of the following points:
v A predetermined point in the code
v When the thread can no longer execute until some condition is met

When the amount of processing required to complete a task would cause other
threads to wait for an undue length of time, a thread yields at a predetermined
point. The code for such long-running tasks includes calls to the yield function at
strategic points in the processing. When a thread performs one of these tasks, it
yields when it encounters a yield function call. Other threads in the ready queue
then get a chance to run. When the original thread next gets a turn, it resumes
executing code at the point immediately after the call to the yield function.
Predetermined calls to the yield function allow the database server to interrupt
threads at points that are most advantageous for performance.

A thread also yields when it can no longer continue its task until some condition
occurs. For example, a thread yields when it is waiting for disk I/O to complete,
when it is waiting for data from the client, or when it is waiting for a lock or other
resource.

When a thread yields, the virtual processor saves its context in the thread-control
block. Then the virtual processor selects a new thread to run from a queue of
ready threads, loads the context of the new thread from its thread-control block,
and begins executing at the new address in the program counter. Figure 6-4
illustrates how a virtual processor accomplishes a context switch.

Thread-control blocks

t0 prgm ctr t1 prgm ctr

registers registers

stack ptr stack ptr

etc. etc.

Save Restore
Time
Virtual processor

Thread t0 Context switch Thread t1

Figure 6-4. Context Switch: How a Virtual Processor Switches from One Thread to Another

Stacks
The database server allocates an area in the virtual portion of shared memory to
store nonshared data for the functions that a thread executes. This area is called
the stack. For information on how to set the size of the stack, refer to “Stacks” on
page 8-18.

Chapter 6. Virtual Processors and Threads 6-9

 The stack enables a virtual processor to protect the nonshared data of a thread
from being overwritten by other threads that concurrently execute the same code.
For example, if several client applications concurrently perform SELECT
statements, the session threads for each client execute many of the same functions
in the code. If a thread did not have a private stack, one thread could overwrite
local data that belongs to another thread within a function.

When a virtual processor switches to a new thread, it loads a stack pointer for that
thread from a field in the thread-control block. The stack pointer stores the
beginning address of the stack. The virtual processor can then specify offsets to the
beginning address to access data within the stack. Figure 6-5 illustrates how a
virtual processor uses the stack to segregate nonshared data for session threads.

Threads t0 t1 t2 t3

Thread-control blocks
t3 prgm ctr
t2 prgm ctr Stack Stack Stack Stack
t1 prgm ctr
t0 prgm ctr
registers
stack ptr

etc.
Virtual processor

Figure 6-5. Virtual Processors Segregate Nonshared Data for Each User

Queues
The database server uses three types of queues to schedule the processing of
multiple, concurrently running threads:
v Ready queues
v Sleep queues
v Wait queues

Virtual processors of the same class share queues. This fact, in part, enables a
thread to migrate from one virtual processor in a class to another when necessary.

Ready Queues
Ready queues hold threads that are ready to run when the current (running)
thread yields. When a thread yields, the virtual processor picks the next thread
with the appropriate priority from the ready queue. Within the queue, the virtual
processor processes threads that have the same priority on a first-in-first-out (FIFO)
basis.

On a multiprocessor computer, if you notice that threads are accumulating in the

ready queue for a class of virtual processors (indicating that work is accumulating
faster than the virtual processor can process it), you can start additional virtual
processors of that class to distribute the processing load. For information on how
to monitor the ready queues, refer to “Monitoring Virtual Processors” on page 7-5.
For information on how to add virtual processors while the database server is in
online mode, refer to “Adding Virtual Processors in Online Mode” on page 7-3.

6-10 IBM Informix Dynamic Server Administrator’s Guide

Sleep Queues
Sleep queues hold the contexts of threads that have no work to do at a particular
time. A thread is put to sleep either for a specified period of time or forever.

The administration class (ADM) of virtual processors runs the system timer and
special utility threads. Virtual processors in this class are created and run
automatically. No configuration parameters impact this class of virtual processors.

The ADM virtual processor wakes up threads that have slept for the specified time.
A thread that runs in the ADM virtual processor checks on sleeping threads at
one-second intervals. If a sleeping thread has slept for its specified time, the ADM
virtual processor moves it into the appropriate ready queue. A thread that is
sleeping for a specified time can also be explicitly awakened by another thread.

A thread that is sleeping forever is awakened when it has more work to do. For
example, when a thread that is running on a CPU virtual processor needs to access
a disk, it issues an I/O request, places itself in a sleep queue for the CPU virtual
processor, and yields. When the I/O thread notifies the CPU virtual processor that
the I/O is complete, the CPU virtual processor schedules the original thread to
continue processing by moving it from the sleep queue to a ready queue.
Figure 6-6 illustrates how the database server threads are queued to perform
database I/O.

Ready queue Threads t5

CPU
and t3, ready
Virtual processors to continue
VPt1 t5
Processing processing
I/O request for AIO VPt2 t3 when thread t1
thread t2 yields

Ready queue
I/O requests Sleep queue Partially
for threads t4 t4 executed
and t6 t2 threads, t2, t4,
t6 and t6, waiting
t4 for completion
of their disk I/O
t6 requests

Figure 6-6. How Database Server Threads Are Queued to Perform Database I/O

Wait Queues
Wait queues hold threads that need to wait for a particular event before they can
continue to run. For example, wait queues coordinate access to shared data by
threads. When a user thread tries to acquire the logical-log latch but finds that the
latch is held by another user, the thread that was denied access puts itself in the
logical-log wait queue. When the thread that owns the lock is ready to release the
latch, it checks for waiting threads, and, if threads are waiting, it wakes up the
next thread in the wait queue.

Chapter 6. Virtual Processors and Threads 6-11

 Mutexes
A mutex (mutually exclusive), also referred to as a latch, is a latching mechanism
that the database server uses to synchronize access by multiple threads to shared
resources. Mutexes are similar to semaphores, which some operating systems use
to regulate access to shared data by multiple processes. However, mutexes permit a
greater degree of parallelism than semaphores.

A mutex is a variable that is associated with a shared resource such as a buffer. A

thread must acquire the mutex for a resource before it can access the resource.
Other threads are excluded from accessing the resource until the owner releases it.
A thread acquires a mutex, after a mutex becomes available, by setting it to an
in-use state. The synchronization that mutexes provide ensures that only one
thread at a time writes to an area of shared memory.

For information on monitoring mutexes, refer to “Monitoring the Shared-Memory

Profile and Latches” on page 9-8.

Virtual-Processor Classes
A virtual processor of a given class can run only threads of that class. This section
describes the types of threads, or the types of processing, that each class of virtual
processor performs. It also explains how to determine the number of virtual
processors that you need to run for each class.

CPU Virtual Processors

The CPU virtual processor runs all session threads (the threads that process
requests from SQL client applications) and some internal threads. Internal threads
perform services that are internal to the database server. For example, a thread that
listens for connection requests from client applications is an internal thread.

Determining the Number of CPU Virtual Processors Needed

The right number of CPU virtual processors is the number at which they are all
kept busy but not so busy that they cannot keep pace with incoming requests. You
should not allocate more CPU virtual processors than the number of hardware
processors in the computer.

To evaluate the performance of the CPU virtual processors while the database
server is running, repeat the following command at regular intervals over a set
period of time:
onstat -g glo

If the accumulated usercpu and syscpu times, taken together, approach 100 percent
of the actual elapsed time for the period of the test, add another CPU virtual
processor if you have a CPU available to run it.

For information on deciding how many CPU virtual processors you need, see
“Running Poll Threads on CPU or Network Virtual Processors” on page 6-21.

The VPCLASS parameter allows you to specify all of the following information:
v The number of virtual processors to start initially for a class
v The maximum number of virtual processors to run for the class
v Processor affinity for CPU class virtual processors
v Disabling of priority aging, if applicable

6-12 IBM Informix Dynamic Server Administrator’s Guide

Important: You should use the VPCLASS parameter instead of the AFF_SPROC,
AFFNPROCS, NOAGE, NUMCPUVPS, and NUMAIOVPS parameters.
The VPCLASS parameter cannot be used in combination with these
parameters. If the ONCONFIG file contains a NUMCPUVPS parameter,
for example, you receive an error message if the file also contains a
VPCLASS cpu parameter. For information about the VPCLASS
configuration parameter, refer to the IBM Informix Administrator's
Reference.

In addition to considering the number of CPUs in the computer and the number of
users who will connect to the database server, also consider the fact that
user-defined routines and DataBlade modules, which are collections of
user-defined routines, run on either CPU virtual processors or user-defined virtual
processors. For information on how you assign a user-defined routine to a virtual
processor, refer to “Assigning a UDR to a User-Defined Virtual-Processor Class” on
page 6-16.

Running on a Multiprocessor Computer

If you are running multiple CPU virtual processors on a multiprocessor computer,
set the MULTIPROCESSOR parameter in the ONCONFIG file to 1. When you set
MULTIPROCESSOR to 1, the database server performs locking in a manner that is
appropriate for a multiprocessor computer. For information on setting
multiprocessor mode, refer to the chapter on configuration parameters in the IBM
Informix Dynamic Server Administrator's Reference.

Running on a Single-Processor Computer

If you are running the database server on a single-processor computer, set the
MULTIPROCESSOR configuration parameter to 0. To run the database server with
only one CPU virtual processor, set the SINGLE_CPU_VP parameter to 1.

Setting MULTIPROCESSOR to 0 enables the database server to bypass the locking

that is required for multiple processes on a multiprocessor computer. For
information on the MULTIPROCESSOR configuration parameter, refer to the IBM
Informix Dynamic Server Administrator's Reference.

Setting SINGLE_CPU_VP to 1 allows the database server to bypass some of the

mutex calls that it normally makes when it runs multiple CPU virtual processors.
For information on setting the SINGLE_CPU_VP parameter, refer to the IBM
Informix Dynamic Server Administrator's Reference.

Important: Setting VPCLASS num to 1 and SINGLE_CPU_VP to 0 does not reduce

the number of mutex calls, even though the database server starts only
one CPU virtual processor. You must set SINGLE_CPU_VP to 1 to
reduce the amount of latching that is performed when you run a single
CPU virtual processor.

Setting the SINGLE_CPU_VP parameter to 1 imposes two important restrictions on

the database server, as follows:
v Only one CPU virtual processor is allowed.
You cannot add CPU virtual processors while the database server is in online
mode.
v No user-defined classes are allowed. (However, users can still define routines
that run directly on the CPU VP.)

Chapter 6. Virtual Processors and Threads 6-13

 For more information, see “Adding Virtual Processors in Online Mode” on page
7-3.

Adding and Dropping CPU Virtual Processors in Online Mode

You can add or drop CPU class virtual processors while the database server is
online. For instructions on how to do this, see “Adding Virtual Processors in
Online Mode” on page 7-3 and “Dropping CPU and User-Defined Virtual
Processors” on page 7-4.

Preventing Priority Aging

Some operating systems lower the priority of long-running processes as they
accumulate processing time. This feature of the operating system is called priority
aging. Priority aging can cause the performance of database server processes to
decline over time. In some cases, however, the operating system allows you to
disable this feature and keep long-running processes running at a high priority.

To determine if priority aging is available on your computer, check the machine

notes file, that comes with your installation and is described in the Introduction to
this guide.

If your operating system allows you to disable priority aging, You can disable it by
specifying noage for the priority entry in the VPCLASS configuration parameter.
For more information, refer to the IBM Informix Dynamic Server Administrator's
Reference.

Using Processor Affinity

The database server supports automatic binding of CPU virtual processors to
processors on multiprocessor computers that support processor affinity. Your
database server distribution includes a machine notes file that contains information
on whether your database server version supports this feature. When you assign a
CPU virtual processor to a specific CPU, the virtual processor runs only on that
CPU, but other processes also can run on that CPU.

Use the VPCLASS configuration parameter with the aff option to implement
processor affinity on multiprocessor computers that support it.

Figure 6-7 illustrates the concept of processor affinity.

CPU virtual processors

Virtual processor

Virtual processor Virtual processor

Starting CPU = 1

CPU 0 CPU 1 CPU 2 CPU 3

Number of virtual processors = 3

Figure 6-7. Processor Affinity

6-14 IBM Informix Dynamic Server Administrator’s Guide

 UNIX Only

To see if processor affinity is supported on your UNIX platform, refer to the

machine notes file.
End of UNIX Only

Setting Processor Affinity with the VPCLASS Parameter: To set processor

affinity with the VPCLASS parameter, specify the range of CPUs to which you are
assigning the virtual processors. The database server assigns CPU virtual
processors to CPUs in round-robin fashion, starting with the first processor
number that aff specifies. If you specify more CPU virtual processors than there are
processors, the database server starts over again at the beginning. In the following
example, the affinity entry assigns a virtual processor to CPUs 1, 2, and 3. Three
virtual processors (specified in num) are available:
VPCLASS CPU,num=3,aff=1-3

In the following example, the database server assigns two virtual processors to
CPUs 5 and 6, and one virtual processor to CPU 7:
VPCLASS CPU,num=3,aff=5-7

For more information, see VPCLASS in the chapter on configuration parameters in

the IBM Informix Dynamic Server Administrator's Reference.

User-Defined Classes of Virtual Processors

You can define special classes of virtual processors to run user-defined routines or
to run a DataBlade module. User-defined routines are typically written to support
user-defined data types. If you do not want a user-defined routine to run in the
CPU class, which is the default, you can assign it to a user-defined class of virtual
processors (VPs). User-defined classes of virtual processors are also called extension
virtual processors.

This section provides the following information about user-defined virtual

processors:
v When to execute a C-language UDR in a user-defined VP instead of in the CPU
VP
v How to assign a C-language UDR to a particular user-defined VP class
v How to add and drop user-defined VPs when the database server is in online
mode

Determining the Number of User-Defined Virtual Processors

Needed
You can specify as many user-defined virtual processors as your operating system
will allow. If you run many UDRs or parallel PDQ queries with UDRs, you should
configure more user-defined virtual processors.

Using User-Defined Virtual Processors

User-defined classes of virtual processors protects the database server from
ill-behaved user-defined routines. An ill-behaved user-defined routine has at least
one of the following characteristics:
v Does not yield control to other threads
v Makes blocking operating-system calls
v Modifies the global VP state

Chapter 6. Virtual Processors and Threads 6-15

 A well-behaved C-language UDR has none of these characteristics. Execute only
well-behaved C-language UDRs in a CPU VP.

Warning: Execution of an ill-behaved routine in a CPU VP can cause serious

interference with the operation of the database server, possibly causing it
to fail or behave erratically. In addition, the routine itself might not
produce correct results.

To ensure safe execution, assign any ill-behaved user-defined routines to a

user-defined class of virtual processors. User-defined VPs remove the following
programming restrictions on the CPU VP class:
v The need to yield the processor regularly
v The need to eliminate blocking I/O calls

Functions that run in a user-defined virtual-processor class need not yield the
processor, and they might issue direct file-system calls that block further
processing by the virtual processor until the I/O is complete.

The normal processing of user queries is not affected by ill-behaved traits of a

C-language UDR because these UDRs do not execute in CPU virtual processors.
For a more detailed discussion of ill-behaved routines, refer to the IBM Informix
DataBlade API Programmer's Guide.

Specifying a User-Defined Virtual Processor

The VPCLASS parameter with the vpclass option defines a user-defined VP class.
You also can specify a nonyielding user-defined virtual processor. For more
information, see “Specifying VPCLASS” on page 7-2 and the configuration
parameters chapter of the IBM Informix Dynamic Server Administrator's Reference.

Assigning a UDR to a User-Defined Virtual-Processor Class

The SQL CREATE FUNCTION statement registers a user-defined routine. For
example, the following CREATE FUNCTION statement registers the user-defined
routine, GreaterThanEqual(), and specifies that calls to this routine should be
executed by the user-defined VP class named UDR:
CREATE FUNCTION GreaterThanEqual(ScottishName, ScottishName)
RETURNS boolean
WITH (CLASS = UDR )
EXTERNAL NAME ‘/usr/lib/objects/[Link]’
LANGUAGE C

To execute this function, the ONCONFIG file must include a VPCLASS parameter
that defines the UDR class. If not, calls to the GreaterThanEqual function will fail.

Tip: The CLASS routine modifier can specify any name for the VP class. This class
name need not exist when you register the UDR. However, when you try to
run a UDR that specifies a user-defined VP class for its execution, this class
must exist and have virtual processors assigned to it.

To configure the UDR class, include a line similar to the following one in the
ONCONFIG file. This line configures the UDR class with two virtual processors
and with no priority aging.
VPCLASS UDR ,num=2,noage

The preceding line defines the UDR VP class as a yielding VP class; that is, this VP
class allows the C-language UDR to yield to other threads that need access to the

6-16 IBM Informix Dynamic Server Administrator’s Guide

 UDR VP class. For more information on how to use the VPCLASS configuration
parameter, see the IBM Informix Dynamic Server Administrator's Reference.

For more information on the CREATE FUNCTION statement, refer to the IBM
Informix Guide to SQL: Syntax.

Adding and Dropping User-Defined Virtual Processors in Online

Mode
You can add or drop virtual processors in a user-defined class while the database
server is online. For instructions on how to do this, refer to “Adding Virtual
Processors in Online Mode” on page 7-3 and “Dropping CPU and User-Defined
Virtual Processors” on page 7-4.

Java Virtual Processors

Java UDRs and Java applications execute on specialized virtual processors, called
Java virtual processors (JVPs). A JVP embeds a Java virtual machine (JVM) in its
code. A JVP has the same capabilities as a CPU VP in that it can process complete
SQL queries.

You can specify as many JVPs as your operating system will allow. If you run
many Java UDRs or parallel PDQ queries with Java UDRs, you should configure
more JVPs. For more information about UDRs written in Java, refer to J/Foundation
Developer's Guide.

Use the VPCLASS configuration parameter with the jvp keyword to configure
JVPs. For more information, see the configuration parameters chapter in the IBM
Informix Dynamic Server Administrator's Reference.

Disk I/O Virtual Processors

The following classes of virtual processors perform disk I/O:
v PIO (physical-log I/O)
v LIO (logical-log I/O)
v AIO (asynchronous I/O)
v CPU (kernel-asynchronous I/O)

The PIO class performs all I/O to the physical-log file, and the LIO class performs
all I/O to the logical-log files, unless those files reside in raw disk space and the
database server has implemented KAIO.

On operating systems that do not support KAIO, the database server uses the AIO
class of virtual processors to perform database I/O that is not related to physical
or logical logging.

The database server uses the CPU class to perform KAIO when it is available on a
platform. If the database server implements KAIO, a KAIO thread performs all I/O

Chapter 6. Virtual Processors and Threads 6-17

 to raw disk space, including I/O to the physical and logical logs.

UNIX Only

To find out if your UNIX platform supports KAIO, refer to the machine notes file.
End of UNIX Only

Windows Only

Windows supports KAIO.

End of Windows Only

For more information about nonlogging I/O, refer to “Asynchronous I/O” on page
6-19.

I/O Priorities
In general, the database server prioritizes disk I/O by assigning different types of
I/O to different classes of virtual processors and by assigning priorities to the
nonlogging I/O queues. Prioritizing ensures that a high-priority log I/O, for
example, is never queued behind a write to a temporary file, which has a low
priority. The database server prioritizes the different types of disk I/O that it
performs, as Table 6-2 shows.
Table 6-2. How Database Server Prioritizes Disk I/O
Priority Type of I/O VP Class
1st Logical-log I/O CPU or LIO
2nd Physical-log I/O CPU or PIO
3rd Database I/O CPU or AIO
3rd Page-cleaning I/O CPU or AIO
3rd Read-ahead I/O CPU or AIO

Logical-Log I/O
The LIO class of virtual processors performs I/O to the logical-log files in the
following cases:
v KAIO is not implemented.
v The logical-log files are in cooked disk space.

Only when KAIO is implemented and the logical-log files are in raw disk space
does the database server use a KAIO thread in the CPU virtual processor to
perform I/O to the logical log.

The logical-log files store the data that enables the database server to roll back
transactions and recover from system failures. I/O to the logical-log files is the
highest priority disk I/O that the database server performs.

If the logical-log files are in a dbspace that is not mirrored, the database server
runs only one LIO virtual processor. If the logical-log files are in a dbspace that is
mirrored, the database server runs two LIO virtual processors. This class of virtual
processors has no parameters associated with it.

6-18 IBM Informix Dynamic Server Administrator’s Guide

Physical-Log I/O
The PIO class of virtual processors performs I/O to the physical-log file in the
following cases:
v KAIO is not implemented.
v The physical-log file is stored in buffered-file chunks.

Only when KAIO is implemented and the physical-log file is in raw disk space
does the database server use a KAIO thread in the CPU virtual processor to
perform I/O to the physical log. The physical-log file stores before-images of
dbspace pages that have changed since the last checkpoint. (For more information
on checkpoints, refer to “Checkpoints” on page 16-7.) At the start of recovery, prior
to processing transactions from the logical log, the database server uses the
physical-log file to restore before-images to dbspace pages that have changed since
the last checkpoint. I/O to the physical-log file is the second-highest priority I/O
after I/O to the logical-log files.

If the physical-log file is in a dbspace that is not mirrored, the database server runs
only one PIO virtual processor. If the physical-log file is in a dbspace that is
mirrored, the database server runs two PIO virtual processors. This class of virtual
processors has no parameters associated with it.

Asynchronous I/O
The database server performs database I/O asynchronously, meaning that I/O is
queued and performed independently of the thread that requests the I/O.
Performing I/O asynchronously allows the thread that makes the request to
continue working while the I/O is being performed.

The database server performs all database I/O asynchronously, using one of the
following facilities:
v AIO virtual processors
v KAIO on platforms that support it

Database I/O includes I/O for SQL statements, read-ahead, page cleaning, and
checkpoints, as well as other I/O.

Kernel-Asynchronous I/O: The database server uses KAIO when the following
conditions exist:
v The computer and operating system support it.
v A performance gain is realized.
v The I/O is to raw disk space.

The database server implements KAIO by running a KAIO thread on the CPU
virtual processor. The KAIO thread performs I/O by making system calls to the
operating system, which performs the I/O independently of the virtual processor.
The KAIO thread can produce better performance for disk I/O than the AIO
virtual processor can, because it does not require a switch between the CPU and
AIO virtual processors.

UNIX Only

Informix implements KAIO when it ports the database server to a platform that
supports this feature. The database server administrator does not configure KAIO.

Chapter 6. Virtual Processors and Threads 6-19

 To see if KAIO is supported on your platform, see the machine notes file.
End of UNIX Only

AIO Virtual Processors: If the platform does not support KAIO or if the I/O is to
buffered-file chunks, the database server performs database I/O through the AIO
class of virtual processors. All AIO virtual processors service all I/O requests
equally within their class.

The database server assigns each disk chunk a queue, sometimes known as a gfd
queue, based on the filename of the chunk. The database server orders I/O requests
within a queue according to an algorithm that minimizes disk-head movement.
The AIO virtual processors service queues that have work pending in round-robin
fashion.

All other non-chunk I/O is queued in the AIO queue.

Use the VPCLASS parameter with the aio keyword to specify the number of AIO
virtual processors that the database server starts initially. For information about
VPCLASS, refer to the chapter on configuration parameters in the IBM Informix
Dynamic Server Administrator's Reference.

You can start additional AIO virtual processors while the database server is in
online mode. For more information, refer to “Adding Virtual Processors in Online
Mode” on page 7-3.

You cannot drop AIO virtual processors while the database server is in online
mode.

Number of AIO Virtual Processors Needed: The goal in allocating AIO virtual
processors is to allocate enough of them so that the lengths of the I/O request
queues are kept short; that is, the queues have as few I/O requests in them as
possible. When the gfd queues are consistently short, it indicates that I/O to the
disk devices is being processed as fast as the requests occur. The onstat -g ioq
command allows you to monitor the length of the gfd queues for the AIO virtual
processors. For more information, refer to “Monitoring Virtual Processors” on page
7-5.

If the database server implements KAIO on your platform, and all of your
dbspaces are composed of raw disk space, one AIO virtual processor might be
sufficient.

If the database server implements KAIO, but you are using some buffered files for
chunks, allocate two AIO virtual processors per active dbspace that is composed of
buffered file chunks. If KAIO is not implemented on your platform, allocate two
AIO virtual processors for each disk that the database server accesses frequently.

Allocate enough AIO virtual processors to accommodate the peak number of I/O
requests. Generally, it is not detrimental to allocate too many AIO virtual
processors.

Network Virtual Processors

As explained in Chapter 3, “Client/Server Communications,” on page 3-1, a client
can connect to the database server in the following ways:
v Through a network connection

6-20 IBM Informix Dynamic Server Administrator’s Guide

v Through a pipe

UNIX Only

v Through shared memory

End of UNIX Only

The network connection can be made by a client on a remote computer or by a

client on the local computer mimicking a connection from a remote computer
(called a local-loopback connection).

Specifying Network Connections

In general, the DBSERVERNAME and DBSERVERALIASES parameters define
dbservernames that have corresponding entries in the sqlhosts file or registry. Each
dbservername parameter in sqlhosts has a nettype entry that specifies an
interface/protocol combination. The database server runs one or more poll threads
for each unique nettype entry. For a description of the nettype field, refer to “The
Connection Type Field” on page 3-16.

The NETTYPE configuration parameter provides optional configuration

information for an interface/protocol combination. It allows you to allocate more
than one poll thread for an interface/protocol combination and also designate the
virtual-processor class (CPU or NET) on which the poll threads run. For a
complete description of this configuration parameter, refer to the IBM Informix
Dynamic Server Administrator's Reference.

Running Poll Threads on CPU or Network Virtual Processors

Poll threads can run either on CPU virtual processors or on network virtual
processors. In general, and particularly on a single-processor computer, poll
threads run more efficiently on CPU virtual processors. This might not be true,
however, on a multiprocessor computer with a large number of remote clients.

The NETTYPE parameter has an optional entry, called vp class, that allows you to
specify either CPU or NET, for CPU or network virtual-processor classes,
respectively.

If you do not specify a virtual processor class for the interface/protocol

combination (poll threads) associated with the DBSERVERNAME variable, the class
defaults to CPU. The database server assumes that the interface/protocol
combination associated with DBSERVERNAME is the primary interface/protocol
combination and that it should be the most efficient.

For other interface/protocol combinations, if no vp class is specified, the default is

NET.

While the database server is in online mode, you cannot drop a CPU virtual
processor that is running a poll thread.

Note: You should carefully distinguish between poll threads for network
connections and poll threads for shared memory connections, which should
run one per CPU virtual processor. TCP connections should only be in
network virtual processors, and you should only have the minimum needed
to maintain responsiveness. Shared memory connections should only be in
CPU virtual processors and should run in every CPU virtual processor.

Chapter 6. Virtual Processors and Threads 6-21

 Specifying the Number of Networking Virtual Processors
Each poll thread requires a separate virtual processor, so you indirectly specify the
number of networking virtual processors when you specify the number of poll
threads for an interface/protocol combination and specify that they are to be run
by the NET class. If you specify CPU for the vp class, you must allocate a
sufficient number of CPU virtual processors to run the poll threads. If the database
server does not have a CPU virtual processor to run a CPU poll thread, it starts a
network virtual processor of the specified class to run it.

For most systems, one poll thread and consequently one virtual processor per
network interface/protocol combination is sufficient. For systems with 200 or more
network users, running additional network virtual processors might improve
throughput. In this case, you need to experiment to determine the optimal number
of virtual processors for each interface/protocol combination.

Specifying Listen and Poll Threads for the Client/Server

Connection
When you start the database server, the oninit process starts an internal thread,
called a listen thread, for each dbservername that you specify with the
DBSERVERNAME and DBSERVERALIASES parameters in the ONCONFIG file. To
specify a listen port for each of these dbservername entries, assign it a unique
combination of hostname and service name entries in sqlhosts. For example, the
sqlhosts file or registry entry shown in Table 6-3 causes the database server
soc_ol1 to start a listen thread for port1 on the host, or network address, myhost.
Table 6-3. A Listen Thread for Each Listen Port
dbservername nettype hostname service name
soc_ol1 onsoctcp myhost port1

The listen thread opens the port and requests one of the poll threads for the
specified interface/protocol combination to monitor the port for client requests.
The poll thread runs either in the CPU virtual processor or in the network virtual
processor for the connection that is being used. For information on the number of
poll threads, refer to “Specifying the Number of Networking Virtual Processors” on
page 6-22.

For information on how to specify whether the poll threads for an

interface/protocol combination run in CPU or network virtual processors, refer to
“Running Poll Threads on CPU or Network Virtual Processors” on page 6-21 and
to the NETTYPE configuration parameter in the IBM Informix Administrator's
Reference.

When a poll thread receives a connection request from a client, it passes the
request to the listen thread for the port. The listen thread authenticates the user,
establishes the connection to the database server, and starts an sqlexec thread, the
session thread that performs the primary processing for the client. Figure 6-8
illustrates the roles of the listen and poll threads in establishing a connection with
a client application.

6-22 IBM Informix Dynamic Server Administrator’s Guide

 Request
Client
connection

Receive Poll Receive Listen

connect thread connect thread Start
request request sqlexec
thread

Accept client
Pass request to connection
listen thread Key

Database server Thread

Data
process

Figure 6-8. The Roles of the Poll and the Listen Threads in Connecting to a Client

A poll thread waits for requests from the client and places them in shared memory
to be processed by the sqlexec thread. For network connections, the poll thread
places the message in a queue in the shared-memory global pool. The poll thread
then wakes up the sqlexec thread of the client to process the request. Whenever
possible, the sqlexec thread writes directly back to the client without the help of
the poll thread. In general, the poll thread reads data from the client, and the
sqlexec thread sends data to the client.

UNIX Only

For a shared-memory connection, the poll thread places the message in the
communications portion of shared memory.
End of UNIX Only

Figure 6-9 illustrates the basic tasks that the poll thread and the sqlexec thread
perform in communicating with a client application.

Chapter 6. Virtual Processors and Threads 6-23

 Process
Client

Read data

Send
data
to client

Pass request
and data
Poll to sqlexec sqlexec Process
thread thread
Read data
from client

Wait for client

request
Key

Database server
Application Thread Data
process process

Figure 6-9. The Roles of the Poll and sqlexec Threads in Communicating with the Client
Application

Starting Multiple Listen Threads

If the database server cannot service connection requests satisfactorily for a given
interface/protocol combination with a single port and corresponding listen thread,
you can improve service for connection requests in the following two ways:
v Add listen threads for additional ports.
v Add another network-interface card.

Adding Listen Threads: As stated previously, the database server starts a listen
thread for each dbservername that you specify with the DBSERVERNAME and
DBSERVERALIASES configuration parameters.

To add listen threads for additional ports, you must first use the
DBSERVERALIASES parameter to specify dbservernames for each of the ports. For
example, the DBSERVERALIASES parameter in Figure 6-10 defines two additional
dbservernames, soc_ol2 and soc_ol3, for the database server instance identified as
soc_ol1.

6-24 IBM Informix Dynamic Server Administrator’s Guide

 DBSERVERNAME soc_ol1
DBSERVERALIASES soc_ol2,soc_ol3

Figure 6-10. Defining Multiple dbservernames for Multiple Connections of the Same Type

After you define additional dbservernames for the database server, you must
specify an interface/protocol combination and port for each of them in the
sqlhosts file or registry. Each port is identified by a unique combination of
hostname and servicename entries. For example, the sqlhosts entries shown in
Table 6-4 cause the database server to start three listen threads for the onsoctcp
interface/protocol combination, one for each of the ports defined.
Table 6-4. sqlhosts Entries to Listen to Multiple Ports for a Single Interface/Protocol
Combination
dbservername nettype hostname service name
soc_ol1 onsoctcp myhost port1
soc_ol2 onsoctcp myhost port2
soc_ol3 onsoctcp myhost port3

If you include a NETTYPE parameter for an interface/protocol combination, it

applies to all the connections for that interface/protocol combination. In other
words, if a NETTYPE parameter exists for onsoctcp in Table 6-4, it applies to all of
the connections shown. In this example, the database server runs one poll thread
for the onsoctcp interface/protocol combination unless the NETTYPE parameter
specifies more. For more information about entries in the sqlhosts file or registry,
refer to “Connectivity Files” on page 3-8.

Adding a Network-Interface Card: If the network-interface card for the host

computer cannot service connection requests satisfactorily, or if you want to
connect the database server to more than one network, you can add a
network-interface card.

To support multiple network-interface cards, you must assign each card a unique
hostname (network address) in sqlhosts. For example, using the same
dbservernames shown in Figure 6-10, the sqlhosts file or registry entries shown in
Table 6-5 on page 6-25 cause the database server to start three listen threads for the
same interface/protocol combination (as did the entries in Table 6-4). In this case,
however, two of the threads are listening to ports on one interface card (myhost1),
and the third thread is listening to a port on the second interface card (myhost2).
Table 6-5. Example of sqlhosts Entries to Support Two Network-Interface Cards for the
onsoctcp Interface/Protocol Combination
dbservername nettype hostname service name
soc_ol1 onsoctcp myhost1 port1
soc_ol2 onsoctcp myhost1 port2
soc_ol3 onsoctcp myhost2 port1

Communications Support Module Virtual Processor

The communications support module (CSM) class of virtual processors performs
communications support service and communications support module functions.

The database server starts the same number of CSM virtual processors as the
number of CPU virtual processors that it starts.

Chapter 6. Virtual Processors and Threads 6-25

 For more information on the communications support service, refer to Chapter 3,
“Client/Server Communications,” on page 3-1.

Encrypt Virtual Processors

If the encrypt option of the VPCLASS parameter is not defined in the ONCONFIG
configuration file, the database server starts one ENCRYPT VP the first time that
any encryption or decryption functions defined for column-level encryption are
called. You can define multiple ENCRYPT VPs if necessary to decrease the time
needed to start the database server.

Use the VPCLASS configuration parameter with the encrypt keyword to configure
encryption VPs. For example, to add five ENCRYPT VPs, add information in the
ONCONFIG file as follows:
VPCLASS encrypt,num=5

You can modify the same information using the onmode utility, as follows:
onmode -p 5 encrypt

For more information, see the configuration parameters and the onmode utility
chapter in the IBM Informix Dynamic Server Administrator's Reference. For more
information on column-level encryption, see “Using Column-Level Encryption” on
page 5-19.

Optical Virtual Processor

The optical class (OPT) of virtual processors is used only with the Optical
Subsystem. The Optical Subsystem starts one virtual processor in the optical class
if the STAGEBLOB configuration parameter is present. For more information on
the Optical Subsystem, see the IBM Informix Optical Subsystem Guide.

Audit Virtual Processor

The database server starts one virtual processor in the audit class (ADT) when you
turn on audit mode by setting the ADTMODE parameter in the ONCONFIG file to
1. For more information about database server auditing, refer to your IBM Informix
Trusted Facility Guide.

Miscellaneous Virtual Processor

The miscellaneous virtual processor services requests for system calls that might
require a very large stack, such as fetching information about the current user or
the host-system name. Only one thread runs on this virtual processor; it executes
with a stack of 128 kilobytes.

6-26 IBM Informix Dynamic Server Administrator’s Guide

Chapter 7. Managing Virtual Processors
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Setting Virtual-Processor Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 7-1
Setting Virtual-Processor Parameters with a Text Editor . . . . . . . . . . . . . . . . . . . 7-1
Specifying VPCLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Disabling Priority Aging (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Setting Virtual-Processor Parameters with ISA . . . . . . . . . . . . . . . . . . . . . . 7-2
Setting Virtual-Processor Parameters with ON-Monitor . . . . . . . . . . . . . . . . . . . 7-3
Starting and Stopping Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
Adding Virtual Processors in Online Mode . . . . . . . . . . . . . . . . . . . . . . . 7-3
Adding Virtual Processors in Online Mode with onmode . . . . . . . . . . . . . . . . . . 7-3
Adding Virtual Processors in Online Mode with ON-Monitor (UNIX) . . . . . . . . . . . . . . 7-4
Adding Network Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . 7-4
Dropping CPU and User-Defined Virtual Processors . . . . . . . . . . . . . . . . . . . . 7-4
Monitoring Virtual Processors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
Monitoring Virtual Processors with Command-Line Utilities . . . . . . . . . . . . . . . . . . 7-5
onstat -g ath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
onstat -g glo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
onstat -g ioq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-5
onstat -g rea . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-6
Monitoring Virtual Processors with SMI Tables . . . . . . . . . . . . . . . . . . . . . . 7-6

In This Chapter
This chapter describes how to set the configuration parameters that affect database
server virtual processors, and how to start and stop virtual processors.

For descriptions of the virtual-processor classes and for advice on how many
virtual processors you should specify for each class, refer to Chapter 6, “Virtual
Processors and Threads,” on page 6-1

Setting Virtual-Processor Configuration Parameters

As user root or informix, use the following tools to set the configuration
parameters for the database server virtual processors:
v A text editor
v IBM Informix Server Administrator (ISA)

UNIX Only

v ON–Monitor
End of UNIX Only

To implement any changes that you make to configuration parameters, you must
shut down and restart the database server. For more information, refer to “Setting
Up Shared Memory” on page 9-7.

Setting Virtual-Processor Parameters with a Text Editor

You can use a text editor program to set ONCONFIG parameters at any time. Use
the editor to locate the parameter that you want to change, enter the new value,
and rewrite the file to disk.

© Copyright IBM Corp. 1996, 2005 7-1

 Table 7-1 lists the ONCONFIG parameters that are used to configure virtual
processors. For more information on how these parameters affect virtual
processors, refer to “Virtual-Processor Classes” on page 6-12.
Table 7-1. Configuration Parameters for Configuring Virtual Processors
Parameter Subparameters Purpose
MULTIPROCESSOR Specifies that you are running on a multiprocessor
computer
NETTYPE Specifies parameters for network protocol threads (and
virtual processors)
SINGLE_CPU_VP Specifies that you are running a single CPU virtual
processor
VPCLASS adm adt cpu kio lio msc opt Specifies a class of virtual processors
lio shm soc str tli
VPCLASS num=num_VPs Specifies the number of virtual processors of the specified
class that the database server should start
VPCLASS max=max_VPs Specifies the maximum number of virtual processors
allowed for a class
VPCLASS noage Specifies the disabling of the aging priority
VPCLASS aff=processor_number Specifies assignment to CPUs if processor affinity is
aff=start_range - available
end_range
VPCLASS user_defined Specifies user-defined virtual processor
VPCLASS jvp Specifies Java virtual processor (JVP)
VPCLASS noyield Specifies non-yielding virtual processor

Specifying VPCLASS
You should use the VPCLASS parameter instead of the NUMCPUVPS,
NUMAIOVPS, NOAGE, AFF_SPROC, and AFF_NPROCS parameters. You can
specify a VPCLASS name of up to 128 bytes. The VPCLASS name must begin with
a letter or underscore, and must contain letters, digits, underscores, or $ characters.

You specify user-defined classes of virtual processors and Java virtual processors in
the VPCLASS configuration parameter. For more information on the VPCLASS
configuration parameter, including the defaults and value ranges, see the IBM
Informix Dynamic Server Administrator's Reference, “User-Defined Classes of Virtual
Processors” on page 6-15, and “Java Virtual Processors” on page 6-17.

Disabling Priority Aging (UNIX)

Use the VPCLASS parameter with the noage option to disable process priority
aging on platforms that allow this feature.

For recommended values for these database server parameters on UNIX, refer to
your machine notes file.

Setting Virtual-Processor Parameters with ISA

You can use ISA to display information about virtual processor classes, and
monitor, add, or remove virtual-processor classes. For more information, see the
ISA online help.

7-2 IBM Informix Dynamic Server Administrator’s Guide

 Setting Virtual-Processor Parameters with ON-Monitor
To set the virtual-processor configuration parameters with ON–Monitor, select the
Parameters > perFormance option.

To specify network virtual processors, enter the number of virtual processors and
then enter one of the following interface/protocol combinations: ipcshm, ipcstr,
tlitcp, tlispx, or soctcp.

Starting and Stopping Virtual Processors

When you start the database server, the oninit utility starts the number and types
of virtual processors that you have specified directly and indirectly. You configure
virtual processors primarily through ONCONFIG parameters and, for network
virtual processors, through parameters in the sqlhosts file or registry. For
descriptions of the virtual-processor classes, refer to “Virtual-Processor Classes” on
page 6-12.

The database server allows you to start a maximum of 1000 virtual processors.

After the database server is in online mode, you can start additional virtual
processors to improve performance, if necessary. For more information, refer to
Adding Virtual Processors in Online Mode below.

While the database server is in online mode, you can drop virtual processors of the
CPU and user-defined classes. For more information, refer to “Dropping CPU and
User-Defined Virtual Processors” on page 7-4.

To terminate the database server and thereby terminate all virtual processors, use
the onmode -k command. For more information on using onmode -k, see the IBM
Informix Dynamic Server Administrator's Reference.

Adding Virtual Processors in Online Mode

While the database server is in online mode, you can start additional virtual
processors for the following classes: CPU, AIO, PIO, LIO, SHM, STR, TLI, SOC,
JVP, and user-defined. The database server automatically starts one virtual
processor each in the LIO and PIO classes unless mirroring is used, in which case
it starts two.

You can start these additional virtual processors with one of the following
methods:
v The -p option of the onmode utility
v ISA

You can also start additional virtual processors for user-defined classes to run
user-defined routines. For more information about user-defined virtual processors,
refer to “Assigning a UDR to a User-Defined Virtual-Processor Class” on page 6-16.

Adding Virtual Processors in Online Mode with onmode

Use the -p option of the onmode command to add virtual processors while the
database server is in online mode. Specify the number of virtual processors that
you want to add with a positive number. As an option, you can precede the
number of virtual processors with a plus sign (+). Following the number, specify
the virtual processor class in lowercase letters. For example, either of the following
commands starts four additional virtual processors in the AIO class:

Chapter 7. Managing Virtual Processors 7-3

 onmode -p 4 aio

onmode -p +4 aio

The onmode utility starts the additional virtual processors immediately.

You can add virtual processors to only one class at a time. To add virtual
processors for another class, you must run onmode again.

Adding Virtual Processors in Online Mode with ON-Monitor

(UNIX)
To use ON–Monitor to add virtual processors while the database server is online,
select the Modes > Add-Proc option. You can add virtual processors in the
following classes: CPU, AIO, LIO, PIO, and NET.

To specify network virtual processors, first enter the number of virtual processors
and then enter one of the following interface/protocol combinations: ipcshm,
ipcstr, tlitcp, tlispx, or soctcp.

You cannot use ON–Monitor to start additional virtual processors for a

user-defined class. For more information, refer to “Adding Virtual Processors in
Online Mode with onmode” on page 7-3.

Adding Network Virtual Processors

When you add network virtual processors, you are adding poll threads, each of
which requires its own virtual processor to run. If you attempt to add poll threads
for a protocol while the database server is in online mode, and you have specified
in the NETTYPE parameter that the poll threads run in the CPU class, the database
server does not start the new poll threads if no CPU virtual processors are
available to run them.

In the following example, the poll threads handle a total of 240 connections:

NETTYPE ipcshm,4,60,CPU # Configure poll thread(s) for nettype

Dropping CPU and User-Defined Virtual Processors

While the database server is in online mode, you can use the -p option of the
onmode utility to drop, or terminate, virtual processors of the CPU and
user-defined classes.

To drop CPU virtual processors:

Following the onmode command, specify a negative number that is the number of
virtual processors that you want to drop, and then specify the CPU class in
lowercase letters. For example, the following command drops two CPU virtual
processors:
% onmode -p -2 cpu

If you attempt to drop a CPU virtual processor that is running a poll thread, you
receive the following message:
onmode: failed when trying to change the number of cpu virtual processor by -number.

For more information, refer to “Running Poll Threads on CPU or Network Virtual
Processors” on page 6-21.

To drop user-defined virtual processors:

7-4 IBM Informix Dynamic Server Administrator’s Guide

 Following the onmode command, specify a negative number that is the number of
virtual processors that you want to drop, and then specify the user-defined class in
lowercase letters. For example, the following command drops two virtual
processors of the class usr:
onmode -p -2 usr

Windows Only

In Windows, you can have only one user-defined virtual processor class at a time.
Omit the number parameter in the onmode -p vpclass command.
End of Windows Only

For information on how to create a user-defined class of virtual processors and

assign user-defined routines to it, refer to “User-Defined Classes of Virtual
Processors” on page 6-15.

Monitoring Virtual Processors

Monitor the virtual processors to determine if the number of virtual processors
configured for the database server is optimal for the current level of activity. For
more information on these onstat -g options, see the chapter on the effect of
configuration on CPU utilization in the IBM Informix Dynamic Server Performance
Guide.

For examples of output for the onstat -g commands, see information on the onstat
utility in the IBM Informix Administrator's Reference.

Monitoring Virtual Processors with Command-Line Utilities

You can use the following onstat -g options to monitor virtual processors:
v ath
v glo
v ioq
v rea

onstat -g ath
The onstat -g ath command displays information on system threads and the
virtual-processor classes.

onstat -g glo
Use the onstat -g glo command to display information about each virtual processor
that is currently running, as well as cumulative statistics for each virtual processor
class. For an example of onstat -g glo output, see information on the onstat utility
in the IBM Informix Administrator's Reference.

onstat -g ioq
Use the onstat -g ioq option to determine whether you need to allocate additional
virtual processors. The command onstat -g ioq displays the length and other
statistics about I/O queues.

If the length of the I/O queue is growing, I/O requests are accumulating faster
than the AIO virtual processors can process them. If the length of the I/O queue
continues to show that I/O requests are accumulating, consider adding AIO virtual
processors.

Chapter 7. Managing Virtual Processors 7-5

 For an example of onstat -g ioq output, see information in the IBM Informix
Administrator's Reference.

onstat -g rea
Use the onstat -g rea option to monitor the number of threads in the ready queue.
If the number of threads in the ready queue is growing for a class of virtual
processors (for example, the CPU class), you might need to add more virtual
processors to your configuration.

For an example of onstat -g rea output, see information in the IBM Informix
Administrator's Reference.

Monitoring Virtual Processors with SMI Tables

Query the sysvpprof table to obtain information on the virtual processors that are
currently running. This table contains the following columns.
Column Description
vpid Virtual-processor ID number
class Virtual-processor class
usercpu Minutes of user CPU consumed
syscpu Minutes of system CPU consumed

7-6 IBM Informix Dynamic Server Administrator’s Guide

Chapter 8. Shared Memory
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared-Memory Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Shared-Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-3
Shared-Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Action to Take If SHMTOTAL Is Exceeded . . . . . . . . . . . . . . . . . . . . . . . . 8-5
Processes That Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
How a Client Attaches to the Communications Portion (UNIX) . . . . . . . . . . . . . . . . . 8-6
How Utilities Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . 8-6
How Virtual Processors Attach to Shared Memory . . . . . . . . . . . . . . . . . . . . . 8-7
Obtaining Key Values for Shared-Memory Segments . . . . . . . . . . . . . . . . . . . 8-7
Specifying Where to Attach the First Shared-Memory Segment . . . . . . . . . . . . . . . . 8-7
Attaching Additional Shared-Memory Segments . . . . . . . . . . . . . . . . . . . . . 8-8
Defining the Shared-Memory Lower-Boundary Address . . . . . . . . . . . . . . . . . . 8-8
Resident Shared-Memory Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9
Resident Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Shared-Memory Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Shared-Memory Buffer Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10
Buffer Overflow to the Virtual Portion . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Logical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Physical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12
High-Availability Data-Replication Buffer . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Lock Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-13
Management of the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . 8-14
Size of the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . 8-14
Components of the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . 8-15
Shared-Memory Internal Tables . . . . . . . . . . . . . . . . . . . . . . . . . . 8-15
Big Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
Session Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Thread Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Data-Distribution Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Dictionary Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
SQL Statement Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Sorting Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
SPL Routine and the UDR Cache . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Global Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Communications Portion of Shared Memory (UNIX) . . . . . . . . . . . . . . . . . . . . . 8-20
Virtual-Extension Portion of Shared Memory . . . . . . . . . . . . . . . . . . . . . . . 8-20
Concurrency Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Shared-Memory Mutexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Shared-Memory Buffer Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Types of Buffer Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Database Server Thread Access to Shared Buffers . . . . . . . . . . . . . . . . . . . . . . 8-21
FIFO/LRU Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Components of LRU Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
Pages in Least-Recently Used Order . . . . . . . . . . . . . . . . . . . . . . . . 8-22
LRU Queues and Buffer-Pool Management . . . . . . . . . . . . . . . . . . . . . . 8-22
Number of LRU Queues to Configure . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Number of Cleaners to Allocate . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Number of Pages Added to the MLRU Queues . . . . . . . . . . . . . . . . . . . . . 8-24
End of MLRU Cleaning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-24
Configuring the Database Server to Read Ahead . . . . . . . . . . . . . . . . . . . . . 8-25
Database Server Thread Access to Buffer Pages . . . . . . . . . . . . . . . . . . . . . . 8-25

© Copyright IBM Corp. 1996, 2005 8-1

Flushing Data to Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing Buffer-Pool Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing Before-Images First . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Flushing the Physical-Log Buffer. . . . . . . . . . . . . . . . . . . . . . . . . . . 8-26
Synchronizing Buffer Flushing . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Describing Flushing Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Foreground Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
LRU Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Chunk Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Flushing the Logical-Log Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
After a Transaction Is Prepared or Terminated in a Database with Unbuffered Logging . . . . . . . 8-29
When a Session That Uses Nonlogging Databases or Unbuffered Logging Terminates . . . . . . . . 8-29
When a Checkpoint Occurs . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
When a Page Is Modified That Does Not Require a Before-Image in the Physical-Log File . . . . . . 8-29
Buffering Large-Object Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Writing Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Blobpages and Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Creation of Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . 8-30
Creation of Blobpage Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-30
Accessing Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Memory Use on 64-Bit Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32

In This Chapter
This chapter describes the content of database server shared memory, the factors
that determine the sizes of shared-memory areas, and how data moves into and
out of shared memory. For information on how to change the database server
configuration parameters that determine shared memory allocations, refer to
Chapter 9, “Managing Shared Memory,” on page 9-1.

Shared Memory
Shared memory is an operating-system feature that allows the database server
threads and processes to share data by sharing access to pools of memory. The
database server uses shared memory for the following purposes:
v To reduce memory usage and disk I/O
v To perform high-speed communication between processes

Shared memory enables the database server to reduce overall memory usage
because the participating processes, in this case, virtual processors, do not need to
maintain private copies of the data that is in shared memory.

Shared memory reduces disk I/O, because buffers, which are managed as a
common pool, are flushed on a database server-wide basis instead of a per-process
basis. Furthermore, a virtual processor can often avoid reading data from disk
because the data is already in shared memory as a result of an earlier read
operation. The reduction in disk I/O reduces execution time.

Shared memory provides the fastest method of interprocess communication,

because it processes read and write messages at the speed of memory transfers.

Shared-Memory Use
The database server uses shared memory for the following purposes:
v To enable virtual processors and utilities to share data

8-2 IBM Informix Dynamic Server Administrator’s Guide

 v To provide a fast communications channel for local client applications that use
IPC communication

Figure 8-1 illustrates the shared-memory scheme.

Virtual processor A Virtual processor B

memory space memory space

Unallocated space Unallocated space

Shared-memory
segments

Private data Private data

Program text Program text

Client
Client

Client
Client

Data Client applications (UNIX)

Figure 8-1. How the Database Server Uses Shared Memory

Shared-Memory Allocation
The database server creates the following portions of shared memory:
v The resident portion
v The virtual portion

UNIX Only

v The IPC communications or message portion

If the sqlhosts file specifies shared-memory communications, the database server
allocates memory for the communications portion.
End of UNIX Only
v The virtual-extension portion

The database server adds operating-system segments as needed to the virtual and
virtual-extension portions of shared memory.

For more information on shared-memory settings for your platform, see the
machine notes. Figure 8-2 on page 8-4 shows the contents of each portion of shared
memory.

Chapter 8. Shared Memory 8-3

 All database server virtual processors have access to the same shared-memory
segments. Each virtual processor manages its work by maintaining its own set of
pointers to shared-memory resources such as buffers, locks, and latches. Virtual
processors attach to shared memory when you take the database server from
offline mode to quiescent, single-user, or online. The database server uses locks
and latches to manage concurrent access to shared-memory resources by multiple
threads.

Shared memory header Buffer-header table LRU queues

Lock table Physical-log buffer Logical-log buffer

Resident portion
Buffer pool

Chunk table Mirrored-chunk table

Dbspace table Page-cleaner table

Tblspace table Transaction table User table

Session structures Thread structures Dictionary cache

UDR cache SQL statement cache Sorting pool

Thread stacks Thread heaps

Virtual portion
Big buffers

Global pool

Unallocated memory

Client/server IPC messages IPC communications

portion (UNIX only)

Thread heaps Virtual-extension segments

for DataBlade modules and
user-defined routines

Figure 8-2. Contents of Database Server Shared Memory

Shared-Memory Size
Each portion of the database server shared memory consists of one or more
operating-system segments of memory, each one divided into a series of blocks
that are 4 kilobytes in size and managed by a bitmap.

The header-line output by the onstat utility contains the size of the database server
shared memory, expressed in kilobytes. You can also use onstat -g seg to monitor

8-4 IBM Informix Dynamic Server Administrator’s Guide

 how much memory the database server allocates for each portion of shared
memory. For information on how to use onstat, see the IBM Informix Dynamic
Server Administrator's Reference.

You can set the SHMTOTAL parameter in the ONCONFIG file to limit the amount
of memory overhead that the database server can place on your computer or node.
The SHMTOTAL parameter specifies the total amount of shared memory that the
database server can use for all memory allocations. However, certain operations
might fail if the database server needs more memory than the amount set in
SHMTOTAL. If this condition occurs, the database server displays the following
message in the message log:
size of resident + virtual segments x + y > z
total allowed by configuration parameter SHMTOTAL

In addition, the database server returns an error message to the application that
initiated the offending operation. For example, if the database server needs more
memory than you specify in SHMTOTAL while it tries to perform an operation
such as an index build or a hash join, it returns an error message to the application
that is similar to one of the following:
-567 Cannot write sorted rows.
-116 ISAM error: cannot allocate memory.

After the database server sends these messages, it rolls back any partial results
performed by the offending query.

Internal operations, such as page-cleaner or checkpoint activity, can also cause the
database server to exceed the SHMTOTAL ceiling. When this situation occurs, the
database server sends a message to the message log. For example, suppose that the
database server attempts and fails to allocate additional memory for page-cleaner
activity. As a consequence, the database server sends a message to the message log
that is similar to the following:
17:19:13 Assert Failed: WARNING! No memory available for page cleaners
17:19:13 Who: Thread(11, flush_sub(0), 9a8444, 1)
17:19:13 Results: Database server may be unable to complete a checkpoint
17:19:13 Action: Make more virtual memory available to database server
17:19:13 See Also: /tmp/af.c4

After the database server informs you about the failure to allocate additional
memory, it rolls back the transactions that caused it to exceed the SHMTOTAL
limit. Immediately after the rollback, operations no longer fail from lack of
memory, and the database server continues to process transactions as usual.

Action to Take If SHMTOTAL Is Exceeded

When the database server needs more memory than SHMTOTAL allows, a
transient condition occurs, perhaps caused by a burst of activity that exceeds the
normal processing load. Only the operation that caused the database server to run
out of memory temporarily should fail. Other operations continue to be processed
in a normal fashion.

If messages indicate on a regular basis that the database server needs more
memory than SHMTOTAL allows, you have not configured the database server
correctly. Lowering DS_TOTAL_MEMORY or the buffers value in the
BUFFERPOOL configuration parameter is one possible solution; increasing the
value of SHMTOTAL is another.

Chapter 8. Shared Memory 8-5

Processes That Attach to Shared Memory
The following processes attach to the database server shared memory:

UNIX Only

v Client-application processes that communicate with the database server through

the shared-memory communications portion (ipcshm)

End of UNIX Only

v Database server virtual processors
v Database server utilities

The following sections describe how each type of process attaches to the database
server shared memory.

How a Client Attaches to the Communications Portion (UNIX)

Client-application processes that communicate with the database server through
shared memory (nettype ipcshm) attach transparently to the communications
portion of shared memory. System-library functions that are automatically
compiled into the application enable it to attach to the communications portion of
shared memory. For information on specifying a shared-memory connection, see
Chapter 3, “Client/Server Communications,” on page 3-1, and “Network Virtual
Processors” on page 6-20.

If the INFORMIXSHMBASE environment variable is not set, the client application

attaches to the communications portion at an address that is platform specific. If
the client application attaches to other shared-memory segments (not database
server shared memory), the user can set the INFORMIXSHMBASE environment
variable to specify the address at which to attach the database server
shared-memory communications segments. When you specify the address at which
to address the shared-memory communications segments, you can prevent the
database server from colliding with the other shared-memory segments that your
application uses. For information on how to set the INFORMIXSHMBASE
environment variable, refer to the IBM Informix Guide to SQL: Reference.

How Utilities Attach to Shared Memory

Database server utilities such as onstat, onmode, and ontape attach to shared
memory through one of the following files.
Operating System File
UNIX $INFORMIXDIR/etc/.[Link]
Windows %INFORMIXDIR%\etc\.[Link]

The variable servername is the value of the DBSERVERNAME parameter in the

ONCONFIG file. The utilities obtain the servername portion of the filename from
the INFORMIXSERVER environment variable.

The oninit process reads the ONCONFIG file and creates the file .[Link]
when it starts the database server. The file is removed when the database server
terminates.

8-6 IBM Informix Dynamic Server Administrator’s Guide

How Virtual Processors Attach to Shared Memory
The database server virtual processors attach to shared memory during setup.
During this process, the database server must satisfy the following two
requirements:
v Ensure that all virtual processors can locate and access the same shared-memory
segments
v Ensure that the shared-memory segments reside in physical memory locations
that are different than the shared-memory segments assigned to other instances
of the database server, if any, on the same computer

The database server uses two configuration parameters, SERVERNUM and

SHMBASE, to meet these requirements.

When a virtual processor attaches to shared memory, it performs the following

major steps:
v Accesses the SERVERNUM parameter from the ONCONFIG file
v Uses SERVERNUM to calculate a shared-memory key value
v Requests a shared-memory segment using the shared-memory key value
The operating system returns the shared-memory identifier for the first
shared-memory segment.
v Directs the operating system to attach the first shared-memory segment to its
process space at SHMBASE
v Attaches additional shared-memory segments, if required, to be contiguous with
the first segment

The following sections describe how the database server uses the values of the
SERVERNUM and SHMBASE configuration parameters in the process of attaching
shared-memory segments.

Obtaining Key Values for Shared-Memory Segments

The values of the SERVERNUM configuration parameter and shmkey, an internally
calculated number, determine the unique key value for each shared-memory
segment.

To see the key values for shared-memory segments, run the onstat -g seg
command. For more information, see the sections on SHMADD and the buffer pool
in your IBM Informix Dynamic Server Performance Guide.

When a virtual processor requests that the operating system attach the first
shared-memory segment, it supplies the unique key value to identify the segment.
In return, the operating system passes back a shared-memory segment identifier
associated with the key value. Using this identifier, the virtual processor requests
that the operating system attach the segment of shared memory to the
virtual-processor address space.

Specifying Where to Attach the First Shared-Memory Segment

The SHMBASE parameter in the ONCONFIG file specifies the virtual address
where each virtual processor attaches the first, or base, shared-memory segment.
Each virtual processor attaches to the first shared-memory segment at the same
virtual address. This situation enables all virtual processors within the same
database server instance to reference the same locations in shared memory without
needing to calculate shared-memory addresses. All shared-memory addresses for
an instance of the database server are relative to SHMBASE.

Chapter 8. Shared Memory 8-7

 Warning: Do not change the value of SHMBASE.

The value of SHMBASE is sensitive for the following reasons:

v The specific value of SHMBASE depends on the platform and whether the
processor is a 32-bit or 64-bit processor. The value of SHMBASE is not an
arbitrary number and is intended to keep the shared-memory segments safe
when the virtual processor dynamically acquires additional memory space.
v Different operating systems accommodate additional memory at different virtual
addresses. Some architectures extend the highest virtual address of the
virtual-processor data segment to accommodate the next segment. In this case,
the data segment might grow into the shared-memory segment.

UNIX Only

v Some versions of UNIX require the user to specify a SHMBASE parameter of

virtual address zero. The zero address informs the UNIX kernel that the kernel
should pick the best address at which to attach the shared-memory segments.
However, not all UNIX architectures support this option. Moreover, on some
systems, the selection that the kernel makes might not be the best selection.
End of UNIX Only

For information on SHMBASE, see your Dynamic Server machine notes.

Attaching Additional Shared-Memory Segments

Each virtual processor must attach to the total amount of shared memory that the
database server has acquired. After a virtual processor attaches each
shared-memory segment, it calculates how much shared memory it has attached
and how much remains. The database server facilitates this process by writing a
shared-memory header to the first shared-memory segment. Sixteen bytes into the
header, a virtual processor can obtain the following data:
v The total size of shared memory for this database server
v The size of each shared-memory segment

To attach additional shared-memory segments, a virtual processor requests them

from the operating system in much the same way that it requested the first
segment. For the additional segments, however, the virtual processor adds 1 to the
previous value of shmkey. The virtual processor directs the operating system to
attach the segment at the address that results from the following calculation:
SHMBASE + (seg_size x number of attached segments)

The virtual processor repeats this process until it has acquired the total amount of
shared memory.

Given the initial key value of (SERVERNUM * 65536) + shmkey, the database server
can request up to 65,536 shared-memory segments before it could request a
shared-memory key value used by another database server instance on the same
computer.

Defining the Shared-Memory Lower-Boundary Address

If your operating system uses a parameter to define the lower boundary address
for shared memory, and the parameter is set incorrectly, it can prevent the
shared-memory segments from being attached contiguously.

8-8 IBM Informix Dynamic Server Administrator’s Guide

 Figure 8-3 illustrates the problem. If the lower-boundary address is less than the
ending address of the previous segment plus the size of the current segment, the
operating system attaches the current segment at a point beyond the end of the
previous segment. This action creates a gap between the two segments. Because
shared memory must be attached to a virtual processor so that it looks like
contiguous memory, this gap creates problems. The database server receives errors
when this situation occurs.

To correct the problem, check the operating-system kernel parameter that specifies
the lower-boundary address or reconfigure the kernel to allow larger
shared-memory segments.

Operating-system memory
Virtual processor

SHMBASE
Shared-memory
segment
The next segment of shared
memory should attach here.
Gap

When lower boundary is too large,

Shared-memory the next segment attaches here.
segment

Figure 8-3. Shared-Memory Lower-Boundary Address Overview

Resident Shared-Memory Segments

The operating system, as it switches between the processes running on the system,
normally swaps the contents of portions of memory to disk. When a portion of
memory is designated as resident, however, it is not swapped to disk. Keeping
frequently accessed data resident in memory improves performance because it
reduces the number of disk I/O operations that would otherwise be required to
access that data.

The database server requests that the operating system keep the virtual portions in
physical memory when the following two conditions exist:
v The operating system supports shared-memory residency.
v The RESIDENT parameter in the ONCONFIG file is set to -1 or a value that is
greater than 0.

Warning: You must consider the use of shared memory by all applications when
you consider whether to set the RESIDENT parameter to -1. Locking all

Chapter 8. Shared Memory 8-9

 shared memory for the use of the Informix database server can
adversely affect the performance of other applications, if any, on the
same computer.

For more information on the RESIDENT configuration parameter, refer to the IBM
Informix Dynamic Server Administrator's Reference.

Resident Portion of Shared Memory

The resident portion of the database server shared memory stores the following
data structures that do not change in size while the database server is running:
v Shared-memory header
v Buffer pool
v Logical-log buffer
v Physical-log buffer
v Lock table

Shared-Memory Header
The shared-memory header contains a description of all other structures in shared
memory, including internal tables and the buffer pool.

The shared-memory header also contains pointers to the locations of these

structures. When a virtual processor first attaches to shared memory, it reads
address information in the shared-memory header for directions to all other
structures.

The size of the shared-memory header is about 200 kilobytes, but the size varies
depending on the computer platform. You cannot tune the size of the header.

Shared-Memory Buffer Pool

The buffer pool in the resident portion of shared memory contains buffers that
store dbspace pages read from disk. The pool of buffers comprises the largest
allocation of the resident portion of shared memory.

Figure 8-4 illustrates the shared-memory header and the buffer pool.

Shared-memory Buffer table

header
Hash table

Buffer pool

Figure 8-4. Shared-Memory Buffer Pool

You use the BUFFERPOOL configuration parameter to specify information about a

buffer pool, including the number of buffers in the buffer pool. To allocate the
8-10 IBM Informix Dynamic Server Administrator’s Guide
 proper number of buffers, start with at least four buffers per user. For more than
500 users, the minimum requirement is 2000 buffers. Too few buffers can severely
impact performance, so you must monitor the database server and tune the value
of buffers to determine an acceptable value. For more information on tuning the
number of buffers, see the IBM Informix Dynamic Server Performance Guide.

If a buffer pool for a non-default page size does not exist, the database server will
automatically create a large-page buffer.

If you are creating a dbspace with a non-default page size, the dbspace must have
a corresponding buffer pool. For example, if you create a dbspace with a page size
of 6 kilobytes, you must create a buffer pool with a size of 6 kilobytes.

For more information on setting the BUFFERPOOL configuration parameter, see

the IBM Informix Dynamic Server Administrator's Reference.

The status of the buffers is tracked through the buffer table. Within shared
memory, buffers are organized into FIFO/LRU buffer queues. Buffer acquisition is
managed through the use of latches, called mutexes, and lock-access information.

For a description of how LRU queues work, refer to “FIFO/LRU Queues” on page
8-21. For a description of mutexes, refer to “Mutexes” on page 6-12.

Buffer Overflow to the Virtual Portion

Because the maximum number of buffers in 64-bit addressing can be as large as
231-1, the resident portion of shared memory might not be able to hold all of the
buffers in a large buffer pool. In this case, the virtual portion of database server
shared memory might hold some of the buffers.

Buffer Size
Each buffer is the size of one database server page.

In general, the database server performs I/O in full-page units, the size of a buffer.
The exceptions are I/O performed from big buffers, from blobspace buffers, or
from lightweight I/O buffers. (See “Big Buffers” on page 8-17 and “Creation of
Blobpage Buffers” on page 8-30.) For information about when to use private
buffers, see information about lightweight I/O operations in the IBM Informix
Dynamic Server Performance Guide.

The onstat -b command displays information about the buffers. For information on
onstat, see the IBM Informix Dynamic Server Administrator's Reference.

Logical-Log Buffer
The database server uses the logical log to store a record of changes to the
database server data since the last dbspace backup. The logical log stores records
that represent logical units of work for the database server. The logical log contains
the following five types of log records, in addition to many others:
v SQL data definition statements for all databases
v SQL data manipulation statements for databases that were created with logging
v Record of a change to the logging status of a database
v Record of a full or fuzzy checkpoint
v Record of a change to the configuration

Chapter 8. Shared Memory 8-11

 The database server uses only one of the logical-log buffers at a time. This buffer is
the current logical-log buffer. Before the database server flushes the current
logical-log buffer to disk, it makes the second logical-log buffer the current one so
that it can continue writing while the first buffer is flushed. If the second
logical-log buffer fills before the first one finishes flushing, the third logical-log
buffer becomes the current one. This process is illustrated in Figure 8-5.

Logical-log buffers
Writes performed by
Current user thread
logical-log buffer
(now filling)
Current
logical-log
Logical-log file
buffer (ready to
accept data)
Free
logical-log
file
Logical-log
buffer
(flushing) Free
logical-log
file

Figure 8-5. The Logical-Log Buffer and Its Relation to the Logical-Log Files on Disk

For a description of how the database server flushes the logical-log buffer, refer to
“Flushing the Logical-Log Buffer” on page 8-28.

The LOGBUFF parameter in the ONCONFIG file specifies the size of the
logical-log buffers. Small buffers can create problems if you store records larger
than the size of the buffers (for example, TEXT or BYTE data in dbspaces). For the
possible values that you can assign to this configuration parameter, refer to the
IBM Informix Dynamic Server Administrator's Reference.

For information on the impact of TEXT and BYTE data on shared memory buffers,
refer to “Buffering Large-Object Data” on page 8-29.

Physical-Log Buffer
The database server uses the physical-log buffer to hold before-images of some of
the modified dbspace pages. The before-images in the physical log and the
logical-log records enable the database server to restore consistency to its databases
after a system failure.

The physical-log buffer is actually two buffers. Double buffering permits the
database server processes to write to the active physical-log buffer while the other
buffer is being flushed to the physical log on disk. For a description of how the
database server flushes the physical-log buffer, refer to “Flushing the Physical-Log
Buffer” on page 8-26. For information on monitoring the physical-log file, refer to
“Monitoring Physical and Logical-Logging Activity” on page 17-3.

The PHYSBUFF parameter in the ONCONFIG file specifies the size of the
physical-log buffers. A write to the physical-log buffer writes exactly one page. If
the specified size of the physical-log buffer is not evenly divisible by the page size,
the database server rounds the size down to the nearest value that is evenly
divisible by the page size. Although some operations require the buffer to be
flushed sooner, in general the database server flushes the buffer to the physical-log
8-12 IBM Informix Dynamic Server Administrator’s Guide
 file on disk when the buffer fills. Thus, the size of the buffer determines how
frequently the database server needs to flush it to disk. For more information on
this configuration parameter, refer to the IBM Informix Dynamic Server
Administrator's Reference.

High-Availability Data-Replication Buffer

High-Availability Data Replication (HDR) requires two instances of the database
server, a primary instance and a secondary instance, running on two computers. If
you implement HDR for your database server, the database server holds logical-log
records in the HDR buffers before it sends them to the secondary database server.
An HDR buffer is always the same size as the logical-log buffer. For information
on the size of the logical-log buffer, refer to the preceding section, “Logical-Log
Buffer” on page 8-11. For more information on how the HDR buffer is used, refer
to “How HDR Works” on page 20-6.

Lock Table
A lock is created when a user thread writes an entry in the lock table. The lock
table is the pool of available locks. Each lock is 44 bytes. A single transaction can
own multiple locks. For an explanation of locking and the SQL statements
associated with locking, see the IBM Informix Guide to SQL: Tutorial.

The following information, which is stored in the lock table, describes the lock:
v The address of the transaction that owns the lock
v The type of lock (exclusive, update, shared, byte, or intent)
v The page and rowid that is locked
v The tblspace where the lock is placed
v Information about the bytes locked (byte-range locks for smart large objects):
– Smart-large-object ID
– Offset into the smart large object where the locked bytes begin
– The number of bytes locked, starting at the offset

To specify the initial size of the lock table, set the LOCKS configuration parameter.

If the number of locks allocated by sessions exceeds the value of LOCKS, the
database server doubles the size of the lock table, up to 15 times. The maximum
value of LOCKS is 8,000,000. Use the DEF_TABLE_LOCKMODE configuration
parameter to set the lock mode to page or row for new tables.

For more information on using and monitoring locks, see the chapter on locking in
your IBM Informix Dynamic Server Performance Guide and the IBM Informix Guide to
SQL: Tutorial. For more information on using LOCKS to specify the number of
locks for a session, see the chapter on configuration parameters in the IBM Informix
Dynamic Server Administrator's Reference and the chapter on configuration effects on
memory utilization in your IBM Informix Dynamic Server Performance Guide.

Virtual Portion of Shared Memory

The virtual portion of shared memory is expandable by the database server and
can be paged out to disk by the operating system. As the database server executes,
it automatically attaches additional operating-system segments, as needed, to the
virtual portion.

Chapter 8. Shared Memory 8-13

 Management of the Virtual Portion of Shared Memory
The database server uses memory pools to track memory allocations that are similar
in type and size. Keeping related memory allocations in a pool helps to reduce
memory fragmentation. It also enables the database server to free a large allocation
of memory at one time, as opposed to freeing each piece that makes up the pool.

All sessions have one or more memory pools. When the database server needs
memory, it looks first in the specified pool. If insufficient memory is available in a
pool to satisfy a request, the database server adds memory from the system pool. If
the database server cannot find enough memory in the system pool, it dynamically
allocates more segments to the virtual portion.

The database server allocates virtual shared memory for each of its subsystems
(session pools, stacks, heaps, control blocks, system catalog, SPL routine caches,
SQL statement cache, sort pools, and message buffers) from pools that track free
space through a linked list. When the database server allocates a portion of
memory, it first searches the pool free-list for a fragment of sufficient size. If it finds
none, it brings new blocks into the pool from the virtual portion. When memory is
freed, it goes back to the pool as a free fragment and remains there until the pool
is destroyed. When the database server starts a session for a client application, for
example, it allocates memory for the session pool. When the session terminates, the
database server returns the allocated memory as free fragments.

Size of the Virtual Portion of Shared Memory

To specify the initial size of the virtual shared-memory portion, set the
SHMVIRTSIZE parameter in the ONCONFIG file. To specify the size of segments
that are added later to the virtual shared memory, set the SHMADD or
EXTSHMADD configuration parameter.

To specify the amount of memory available for PDQ queries, set the
DS_TOTAL_MEMORY parameter.

If you want to increase the amount of memory that is available for a query that is
not a PDQ query and the PDQ priority is set to 0 (zero), you can change the
amount using any of the following options:
v The DS_NONPDQ_QUERY_MEM configuration parameter
v The onmode -wm or onmode -wf commands
v The Non PDQ Query Memory option on the ON-Monitor pdQ menu.

For example, if you use the onmode utility, specify a value as shown in the
following example:
onmode -wf DS_NONPDQ_QUERY_MEM=500

The minimum value for DS_NONPDQ_QUERY_MEM is 128 kilobytes. The

maximum supported value is 25 percent of the value of DS_TOTAL_MEMORY.

For more information on the SHMVIRTSIZE, SHMADD, EXTSHMADD,

DS_TOTAL_MEMORY, DS_TOTAL_SIZE, and DS_NONPDQ_QUERY_MEM
configuration parameters, see the IBM Informix Dynamic Server Performance Guide
and the IBM Informix Dynamic Server Administrator's Reference. Also see “Adding a
Segment to the Virtual Portion of Shared Memory” on page 9-7.

8-14 IBM Informix Dynamic Server Administrator’s Guide

Components of the Virtual Portion of Shared Memory
The virtual portion of shared memory stores the following data:
v Internal tables
v Big buffers
v Session data
v Thread data (stacks and heaps)
v Data-distribution cache
v Dictionary cache
v SPL routine cache
v SQL statement cache
v Sorting pool
v Global pool

Shared-Memory Internal Tables

The database server shared memory contains seven internal tables that track
shared-memory resources. The shared-memory internal tables are as follows:
v Buffer table
v Chunk table
v Dbspace table
v Page-cleaner table
v Tblspace table
v Transaction table
v User table

Buffer Table: The buffer table tracks the addresses and status of the individual
buffers in the shared-memory pool. When a buffer is used, it contains an image of
a data or index page from disk. For more information on the purpose and content
of a disk page, refer to “Pages” on page 10-5.

Each buffer in the buffer table contains the following control information, which is
needed for buffer management:
v Buffer status
Buffer status is described as empty, unmodified, or modified. An unmodified
buffer contains data, but the data can be overwritten. A modified (dirty) buffer
contains data that must be written to disk before it can be overwritten.
v Current lock-access level
Buffers receive lock-access levels depending on the type of operation that the
user thread is executing. The database server supports two buffer lock-access
levels: shared and exclusive.
v Threads waiting for the buffer
Each buffer header maintains a list of the threads that are waiting for the buffer
and the lock-access level that each waiting thread requires.

Each database server buffer has one entry in the buffer table.

For information on the database server buffers, refer to “Resident Portion of Shared
Memory” on page 8-10. For information on how to monitor the buffers, refer to
“Monitoring Buffers” on page 9-9.

Chapter 8. Shared Memory 8-15

 The database server determines the number of entries in the buffer-table hash
table, based on the number of allocated buffers. The maximum number of hash
values is the largest power of 2 that is less than the value of buffers, which is
specified in one of the BUFFERPOOL configuration parameter fields.

Chunk Table: The chunk table tracks all chunks in the database server. If
mirroring has been enabled, a corresponding mirror chunk table is also created
when shared memory is set up. The mirror chunk table tracks all mirror chunks.

The chunk table in shared memory contains information that enables the database
server to locate chunks on disk. This information includes the number of the initial
chunk and the number of the next chunk in the dbspace. Flags also describe chunk
status: mirror or primary; offline, online, or recovery mode; and whether this
chunk is part of a blobspace. For information on monitoring chunks, refer to
“Monitoring Chunks” on page 11-33.

The maximum number of entries in the chunk table might be limited by the
maximum number of file descriptors that your operating system allows per
process. You can usually specify the number of file descriptors per process with an
operating-system kernel-configuration parameter. For details, consult your
operating-system manuals.

Dbspace Table: The dbspace table tracks storage spaces in the database server.
The dbspace-table information includes the following information about each
dbspace:
v Dbspace number
v Dbspace name and owner
v Dbspace mirror status (mirrored or not)
v Date and time that the dbspace was created

If the storage space is a blobspace, flags indicate the media where the blobspace is
located: magnetic, removable, or optical media. If the storage space is an sbspace, it
contains internal tables that track metadata for smart large objects and large
contiguous blocks of pages containing user data.

For information on monitoring dbspaces, refer to “Monitoring Disk Usage” on

page 11-32.

Page-Cleaner Table: The page-cleaner table tracks the state and location of each
of the page-cleaner threads. The number of page-cleaner threads is specified by the
CLEANERS configuration parameter in the ONCONFIG file. For advice on how
many page-cleaner threads to specify, refer to the chapter on configuration
parameters in the IBM Informix Dynamic Server Administrator's Reference.

The page-cleaner table always contains 128 entries, regardless of the number of
page-cleaner threads specified by the CLEANERS parameter in the ONCONFIG
file.

For information on monitoring the activity of page-cleaner threads, see information

on the onstat -F option in the IBM Informix Dynamic Server Administrator's Reference.

Tblspace Table: The tblspace table tracks all active tblspaces in a database server
instance. An active tblspace is one that is currently in use by a database session.
Each active table accounts for one entry in the tblspace table. Active tblspaces
include database tables, temporary tables, and internal control tables, such as

8-16 IBM Informix Dynamic Server Administrator’s Guide

system catalog tables. Each tblspace table entry includes header information about
the tblspace, the tblspace name, and pointers to the tblspace tblspace in dbspaces
on disk. (The shared-memory active tblspace table is different from the tblspace
tblspace.) For information on monitoring tblspaces, refer to “Monitoring Tblspaces
and Extents” on page 11-36.

The database server manages one tblspace table for each dbspace.

Transaction Table: The transaction table tracks all transactions in the database
server.

Tracking information derived from the transaction table appears in the onstat -x
display. For an example of the output that onstat -x displays, refer to monitoring
transactions in your IBM Informix Dynamic Server Performance Guide.

The database server automatically increases the number of entries in the

transaction table, up to a maximum of 32,767, based on the number of current
transactions.

For more information on transactions and the SQL statements that you use with
transactions, refer to the IBM Informix Guide to SQL: Tutorial, the IBM Informix Guide
to SQL: Reference, and the IBM Informix Guide to SQL: Syntax.

UNIX Only

The transaction table also specifically supports the X/Open environment. Support
for the X/Open environment requires TP/XA. For a description of a transaction in
this environment, refer to the IBM Informix TP/XA Programmer's Manual.
End of UNIX Only

User Table: The user table tracks all user threads and system threads. Each client
session has one primary thread and zero-to-many secondary threads, depending on
the level of parallelism specified. System threads include one to monitor and
control checkpoints, one to process onmode commands, the B-tree scanner threads,
and page-cleaner threads.

The database server increases the number of entries in the user table as needed.
You can monitor user threads with the onstat -u command.

Big Buffers
A big buffer is a single buffer that is made up of several pages. The actual number
of pages is platform dependent. The database server allocates big buffers to
improve performance on large reads and writes.

The database server uses a big buffer whenever it writes to disk multiple pages
that are physically contiguous. For example, the database server tries to use a big
buffer to perform a series of sequential reads (light scans) or to read into shared
memory simple large objects that are stored in a dbspace.

Users do not have control over the big buffers. If the database server uses light
scans, it allocates big buffers from shared memory.

For information on monitoring big buffers with the onstat command, refer to the
chapter on configuration effects on I/O activity in your IBM Informix Dynamic
Server Performance Guide.

Chapter 8. Shared Memory 8-17

 Session Data
When a client application requests a connection to the database server, the
database server begins a session with the client and creates a data structure for the
session in shared memory called the session-control block. The session-control block
stores the session ID, the user ID, the process ID of the client, the name of the host
computer, and various status flags.

The database server allocates memory for session data as needed.

Thread Data
When a client connects to the database server, in addition to starting a session, the
database server starts a primary session thread and creates a thread-control block for
it in shared memory.

The database server also starts internal threads on its own behalf and creates
thread-control blocks for them. When the database server switches from running
one thread to running another one (a context switch), it saves information about
the thread— such as the register contents, program counter (address of the next
instruction), and global pointers—in the thread-control block. For more information
on the thread-control block and how it is used, refer to “Context Switching” on
page 6-8.

The database server allocates memory for thread-control blocks as needed.

Stacks: Each thread in the database server has its own stack area in the virtual
portion of shared memory. For a description of how threads use stacks, refer to
“Stacks” on page 6-9. For information on how to monitor the size of the stack for a
session, refer to monitoring sessions and threads section in your IBM Informix
Dynamic Server Performance Guide.

The size of the stack space for user threads is specified by the STACKSIZE
parameter in the ONCONFIG file. The default size of the stack is 32 kilobytes. You
can change the size of the stack for all user threads, if necessary, by changing the
value of STACKSIZE. For information and a warning on setting the size of the
stack, refer to STACKSIZE in the chapter on configuration parameters in the IBM
Informix Dynamic Server Administrator's Reference.

To alter the size of the stack for the primary thread of a specific session, set the
INFORMIXSTACKSIZE environment variable. The value of
INFORMIXSTACKSIZEoverrides the value of STACKSIZE for a particular user.
For information on how to override the stack size for a particular user, refer to the
description of the INFORMIXSTACKSIZE environment variable in the IBM
Informix Guide to SQL: Reference.

To more safely alter the size of stack space, use the INFORMIXSTACKSIZE
environment variable rather than alter the configuration parameter STACKSIZE.
The INFORMIXSTACKSIZE environment variable affects the stack space for only
one user, and it is less likely to affect new client applications that initially were not
measured.

Heaps: Each thread has a heap to hold data structures that it creates while it is
running. A heap is dynamically allocated when the thread is created. The size of
the thread heap is not configurable.

8-18 IBM Informix Dynamic Server Administrator’s Guide

Data-Distribution Cache
The database server uses distribution statistics generated by the UPDATE
STATISTICS statement in the MEDIUM or HIGH mode to determine the query
plan with the lowest cost. When the database server accesses the distribution
statistics for a specific column the first time, it reads the distribution statistics from
the sysdistrib system catalog table on disk and stores the statistics in the
data-distribution cache. These statistics can then be read for the optimization of
subsequent queries that access the column.

Performance improves if these statistics are efficiently stored and accessed from the
data-distribution cache. You can configure the size of the data-distribution cache
with the DS_HASHSIZE and DS_POOLSIZE configuration parameters. For
information about changing the default size of the data-distribution cache, refer to
the chapter on queries and the query optimizer in your IBM Informix Dynamic
Server Performance Guide.

Dictionary Cache
When a session executes an SQL statement that requires access to a system catalog
table, the database server reads data from the system catalog tables. The database
server stores the catalog data for each queried table in structures that it can access
more efficiently during subsequent queries on that table. These structures are
created in the virtual portion of shared memory for use by all sessions. These
structures constitute the dictionary cache.

You can configure the size of the dictionary cache with the DD_HASHSIZE and
DD_HASHMAX configuration parameters. For more information about these
parameters, refer to the chapter on configuration effects on memory in your IBM
Informix Dynamic Server Performance Guide.

SQL Statement Cache

The SQL statement cache reduces memory usage and preparation time for queries.
The database server uses the SQL statement cache to store parsed and optimized
SQL statements that a user executes. When users execute a statement stored in the
SQL statement cache, the database server does not parse and optimize the
statement again, so performance improves.

For more information, see “Setting SQL Statement Cache Parameters” on page 9-6.
For details on how these parameters affect the performance of the SQL statement
cache, refer to the IBM Informix Dynamic Server Performance Guide.

Sorting Memory
The following database operations can use large amounts of the virtual portion of
shared memory to sort data:
v Decision-support queries that involve joins, groups, aggregates and sort
operations
v Index builds
v UPDATE STATISTICS statement in SQL

The amount of virtual shared memory that the database server allocates for a sort
depends on the number of rows to be sorted and the size of the row, along with
other factors.

For information on parallel sorts, refer to your IBM Informix Dynamic Server
Performance Guide.

Chapter 8. Shared Memory 8-19

 SPL Routine and the UDR Cache
The database server converts an SPL routine to executable format and stores the
routine in the UDR cache, where it can be accessed by any session.

When a session needs to access an SPL routine or other user-defined routine for
the first time, the database server reads the definition from the system catalog
tables and stores the definition in the UDR cache.

You can configure the size of the UDR cache with the PC_HASHSIZE and
PC_POOLSIZE configuration parameters. For information about changing the
default size of the UDR cache, refer to the chapter on queries and the query
optimizer in your IBM Informix Dynamic Server Performance Guide.

Global Pool
The global pool stores structures that are global to the database server. For
example, the global pool contains the message queues where poll threads for
network communications deposit messages from clients. The sqlexec threads pick
up the messages from the global pool and process them.

For more information, see the sections on network buffer pools and virtual portion
of shared memory in your IBM Informix Dynamic Server Performance Guide.

Communications Portion of Shared Memory (UNIX)

The database server allocates memory for the IPC communication portion of
shared memory if you configure at least one of your connections as an IPC
shared-memory connection. The database server performs this allocation when you
set up shared memory. The communications portion contains the message buffers
for local client applications that use shared memory to communicate with the
database server.

The size of the communications portion of shared memory equals approximately

12 kilobytes multiplied by the expected number of connections needed for
shared-memory communications (nettype ipcshm). If nettype ipcshm is not present,
the expected number of connections defaults to 50. For information about how a
client attaches to the communications portion of shared memory, refer to “How a
Client Attaches to the Communications Portion (UNIX)” on page 8-6.

Virtual-Extension Portion of Shared Memory

The virtual-extension portion of shared memory contains additional virtual
segments and virtual-extension segments. Virtual-extension segments contain
thread heaps for DataBlade modules and user-defined routines that run in
user-defined virtual processors.

The SHMADD, EXTSHMADD, and SHMTOTAL configuration parameters apply to

the virtual-extension portion of shared memory, just as they do to the other
portions of shared memory.

Concurrency Control
The database server threads that run on the same virtual processor and on separate
virtual processors share access to resources in shared memory. When a thread
writes to shared memory, it uses mechanisms called mutexes and locks to prevent
other threads from simultaneously writing to the same area. A mutex gives a

8-20 IBM Informix Dynamic Server Administrator’s Guide

 thread the right to access a shared-memory resource. A lock prevents other threads
from writing to a buffer until the thread that placed the lock is finished with the
buffer and releases the lock.

Shared-Memory Mutexes
The database server uses mutexes to coordinate threads as they attempt to modify
data in shared memory. Every modifiable shared-memory resource is associated
with a mutex. Before a thread can modify a shared-memory resource, it must first
acquire the mutex associated with that resource. After the thread acquires the
mutex, it can modify the resource. When the modification is complete, the thread
releases the mutex.

If a thread tries to obtain a mutex and finds that it is held by another thread, the
incoming thread must wait for the mutex to be released.

For example, two threads can attempt to access the same slot in the chunk table,
but only one can acquire the mutex associated with the chunk table. Only the
thread that holds the mutex can write its entry in the chunk table. The second
thread must wait for the mutex to be released and then acquire it.

For information on monitoring mutexes (which are also referred to as latches), refer
to “Monitoring the Shared-Memory Profile and Latches” on page 9-8.

Shared-Memory Buffer Locks

A primary benefit of shared memory is the ability of database server threads to
share access to disk pages stored in the shared-memory buffer pool. The database
server maintains thread isolation while it achieves this increased concurrency
through a strategy for locking the data buffers.

Types of Buffer Locks

The database server uses two types of locks to manage access to shared-memory
buffers:
v Share locks
v Exclusive locks

Each of these lock types enforces the required level of thread isolation during
execution.

Share Lock: A buffer is in share mode, or has a share lock, if multiple threads
have access to the buffer to read the data but none intends to modify the data.

Exclusive Lock: A buffer is in exclusive mode, or has an exclusive lock, if a

thread demands exclusive access to the buffer. All other thread requests that access
the buffer are placed in the wait queue. When the executing thread is ready to
release the exclusive lock, it wakes the next thread in the wait queue.

Database Server Thread Access to Shared Buffers

Database server threads access shared buffers through a system of queues, using
mutexes and locks to synchronize access and protect data.

FIFO/LRU Queues
A buffer holds data for the purpose of caching. The database server uses the
least-recently used (LRU) queues to replace the cached data. Dynamic Server also

Chapter 8. Shared Memory 8-21

 has a first-in first-out (FIFO) queue. When you set the number of LRU queues, you
are actually setting the number of FIFO/LRU queues.

Use the BUFFERPOOL configuration parameter to specify information about the

buffer pool, including information about the number of LRU queues to create
when database server shared memory is set up and values for lru_min_dirty and
lru_max_dirty, which control how frequently the shared-memory buffers are
flushed to disk.

Note: Information that was specified with the BUFFERS, LRUS,

LRU_MAX_DIRTY, and LRU_MIN_DIRTY configuration parameters prior to
Version 10.0 is now specified using the BUFFERPOOL configuration
parameter.

Components of LRU Queue

Each LRU queue is composed of a pair of linked lists, as follows:
v FLRU (free least-recently used) list, which tracks free or unmodified pages in the
queue
v MLRU (modified least-recently used) list, which tracks modified pages in the
queue

The free or unmodified page list is referred to as the FLRU queue of the queue
pair, and the modified page list is referred to as the MLRU queue. The two
separate lists eliminate the need to search a queue for a free or unmodified page.
Figure 8-6 illustrates the structure of the LRU queues.

Least-recently used <--> most-recently used

FLRU 1
LRU queue
(composed of two
MLRU 1 queues)

Pointer to a Pointer to an Pointer to an

modified page unmodified page empty page

Figure 8-6. LRU Queue

Pages in Least-Recently Used Order

When the database server processes a request to read a page from disk, it must
decide which page to replace in memory. Rather than select a page randomly, the
database server assumes that recently referenced pages are more likely to be
referenced in the future than pages that it has not referenced for some time. Thus,
rather than replacing a recently accessed page, the database server replaces a
least-recently accessed page. By maintaining pages in least-recently to
most-recently used order, the database server can easily locate the least-recently
used pages in memory.

LRU Queues and Buffer-Pool Management

Before processing begins, all page buffers are empty, and every buffer is
represented by an entry in one of the FLRU queues. The buffers are evenly
distributed among the FLRU queues. To calculate the number of buffers in each
queue, divide the total number of buffers by the number of LRU queues. The
number of buffers and LRU queues are specified in the BUFFERPOOL
configuration parameter.

8-22 IBM Informix Dynamic Server Administrator’s Guide

When a user thread needs to acquire a buffer, the database server randomly selects
one of the FLRU queues and uses the oldest or least-recently used entry in the list.
If the least-recently used page can be latched, that page is removed from the
queue.

If the FLRU queue is locked, and the end page cannot be latched, the database
server randomly selects another FLRU queue.

If a user thread is searching for a specific page in shared memory, it obtains the
LRU-queue location of the page from the control information stored in the buffer
table.

After an executing thread finishes its work, it releases the buffer. If the page has
been modified, the buffer is placed at the most-recently used end of an MLRU
queue. If the page was read but not modified, the buffer is returned to the FLRU
queue at its most-recently used end. For information on how to monitor LRU
queues, refer to “Monitoring Buffer-Pool Activity” on page 9-11.

Number of LRU Queues to Configure

Multiple LRU queues have two purposes:
v They reduce user-thread contention for the queues.
v They allow multiple cleaners to flush pages from LRU queues and maintain the
percentage of dirty pages at an acceptable level.

Initial values for the LRUS are recommended based on the number of CPUs that
are available on your computer. If your computer is a uniprocessor, start by setting
the lrus value in the BUFFERPOOL configuration parameter to 4. If your computer
is a multiprocessor, use the following formula:
LRUS = max(4, (NUMCPUVPS))

After you provide an initial value for lrus in the BUFFERPOOL configuration
parameter, monitor your LRU queues with onstat -R. If you find that the
percentage of dirty LRU queues consistently exceeds the value specified for
lru_max_dirty, increase the value specified for lrus to add more LRU queues.

For example, suppose you set lru_max_dirty to 70 and find that your LRU queues
are consistently 75 percent dirty. Consider increasing the value of the lrus. If you
increase the number of LRU queues, you shorten the length of the queues, thereby
reducing the work of the page cleaners. However, you must allocate a sufficient
number of page cleaners with the CLEANERS configuration parameter, as
discussed in the following section.

Note: Information that was specified with the BUFFERS, LRUS,

LRU_MAX_DIRTY, and LRU_MIN_DIRTY configuration parameters prior to
Version 10.0 is now specified using the BUFFERPOOL configuration
parameter.

Number of Cleaners to Allocate

In general, you should configure one cleaner for each disk that your applications
update frequently. However, you should also consider the length of your LRU
queues and frequency of checkpoints, as explained in the following paragraphs.

In addition to insufficient LRU queues, another factor that influences whether page
cleaners keep up with the number of pages that require cleaning is whether you
have enough page-cleaner threads allocated. The percent of dirty pages might

Chapter 8. Shared Memory 8-23

 exceed the BUFFERPOOL value specified for lru_max_dirty in some queues
because no page cleaners are available to clean the queues. After a while, the page
cleaners might be too far behind to catch up, and the buffer pool becomes dirtier
than the percent that you specified in lru_max_dirty.

For example, suppose that the CLEANERS parameter is set to 8, and you increase
the number of LRU queues from 8 to 12. You can expect little in the way of a
performance gain because the 8 cleaners must now share the work of cleaning an
additional 4 queues. If you increase the number of CLEANERS to 12, each of the
now-shortened queues can be more efficiently cleaned by a single cleaner.

Setting CLEANERS too low can cause performance to suffer whenever a

checkpoint occurs because page cleaners must flush all modified pages to disk
during checkpoints. If you do not configure a sufficient number of page cleaners,
checkpoints take longer, causing overall performance to suffer.

For more information, see “Flushing Buffer-Pool Buffers” on page 8-26.

Number of Pages Added to the MLRU Queues

Periodically, the page-cleaner threads flush the modified buffers in an MLRU
queue to disk. To specify the point at which cleaning begins, use the
BUFFERPOOL configuration parameter to specify a value for lru_max_dirty.

By specifying when page cleaning begins, the lru_max_dirty value limits the
number of page buffers that can be appended to an MLRU queue. The initial
setting of lru_max_dirty is 60.00, so page cleaning begins when 60 percent of the
buffers managed by a queue are modified.

In practice, page cleaning begins under several conditions, only one of which is
when an MLRU queue reaches the value of lru_max_dirty. For more information
on how the database server performs buffer-pool flushing, refer to “Flushing Data
to Disk” on page 8-26.

Figure 8-7 shows how the value of lru_max_dirty is applied to an LRU queue to
specify when page cleaning begins and thereby limit the number of buffers in an
MLRU queue.

Buffers specified as 8000

lrus specified as 8
lru_max_dirty specified as 60 percent

Page cleaning begins when the number of buffers in the MLRU

queue is equal to lru_max_dirty.

Buffers per lru queue = (8000/8) = 1000

Max buffers in MLRU queue and point at which page cleaning

begins: 1000 x 0.60 = 600

Figure 8-7. How the lru_max_dirty Value Initiates Page Cleaning to Limit the Size of the
MLRU Queue

End of MLRU Cleaning

You can also specify the point at which MLRU cleaning can end. The
lru_min_dirty value in the BUFFERPOOL configuration parameter specifies the
acceptable percentage of buffers in an MLRU queue. For example, if lru_min_dirty
is set to 50.00, page cleaning is not required when 50 percent of the buffers in an

8-24 IBM Informix Dynamic Server Administrator’s Guide

 LRU queue are modified. In practice, page cleaning can continue beyond this
point, as directed by the page-cleaner threads.

Figure 8-8 shows how the value of lru_min_dirty is applied to the LRU queue to
specify the acceptable percent of buffers in an MLRU queue and the point at which
page cleaning ends.

Buffers specified as 8000

lrus specified as 8
lru_min_dirty specified as 50 percent

The acceptable number of buffers in the MLRU queue and

the point at which page cleaning can end is equal
to lru_min_dirty.

Buffers per LRU queue = (8000/8) = 1000

Acceptable number of buffers in MLRU queue and the point

at which page cleaning can end: 1000 x .50 = 500

Figure 8-8. How the lru_min_dirty Value Specifies the Point at Which Page Cleaning Can
End

You can use decimals for the lru_max_dirty and the lru_min_dirty values. For
example, if you set lru_max_dirty to 1.0333 and lru_min_dirty to 1.0, this triggers
the LRU to write at 3,100 dirty buffers and to stop at 3,000 dirty buffers.

For more information on how the database server flushes the buffer pool, refer to
“Flushing Data to Disk” on page 8-26.

Configuring the Database Server to Read Ahead

For sequential table or index scans, you can configure the database server to read
several pages ahead while the current pages are being processed. A read-ahead
enables applications to run faster because they spend less time waiting for disk
I/O.

The database server performs a read-ahead whenever it detects the need for it
during sequential data or index reads.

The RA_PAGES parameter in the ONCONFIG file specifies the number of pages to
read from disk or the index when the database server performs a read-ahead.

The RA_THRESHOLD parameter specifies the number of unprocessed pages in

memory that cause the database server to perform another read-ahead. For
example, if RA_PAGES is 10, and RA_THRESHOLD is 4, the database server reads
ahead 10 pages when 4 pages remain to be processed in the buffer.

For more information on using the onstat -p command to monitor the database
server use of read-ahead, see “Monitoring the Shared-Memory Profile and Latches”
on page 9-8. For an example of onstat -p output, see the IBM Informix
Administrator's Reference.

Database Server Thread Access to Buffer Pages

The database server uses shared-lock buffering to allow more than one database
server thread to access the same buffer concurrently in shared memory. The
database server uses two categories of buffer locks to provide this concurrency
without a loss in thread isolation. The two categories of lock access are share and
exclusive. (For more information, refer to “Types of Buffer Locks” on page 8-21.)

Chapter 8. Shared Memory 8-25

Flushing Data to Disk
Writing a buffer to disk is called buffer flushing. When a user thread modifies data
in a buffer, it marks the buffer as dirty. When the database server flushes the buffer
to disk, it subsequently marks the buffer as not dirty and allows the data in the
buffer to be overwritten.

The database server flushes the following buffers:

v Buffer pool (covered in this section)
v Physical-log buffer
See “Flushing the Physical-Log Buffer” on page 8-26.
v Logical-log buffer
See “Flushing the Logical-Log Buffer” on page 8-28.

Page-cleaner threads manage buffer flushing. The database server always runs at
least one page-cleaner thread. If the database server is configured for more than
one page-cleaner thread, the LRU queues are divided among the page cleaners for
more efficient flushing. For information on specifying how many page-cleaner
threads the database server runs, refer to the CLEANERS configuration parameter
in the IBM Informix Dynamic Server Administrator's Reference.

Flushing the physical-log buffer, the modified shared-memory page buffers, and
the logical-log buffer must be synchronized with page-cleaner activity according to
specific rules designed to maintain data consistency.

Flushing Buffer-Pool Buffers

Flushing of the buffers is initiated by any one of the following three conditions:
v The number of buffers in an MLRU queue reaches the number specified by the
lru_max_dirty value in the BUFFERPOOL configuration parameter.
v The page-cleaner threads cannot keep up. In other words, a user thread needs to
acquire a buffer, but no unmodified buffers are available.
v The database server needs to execute a checkpoint. (See “Checkpoints” on page
16-7.)

Flushing Before-Images First

The overriding rule of buffer flushing is that the before-images of modified pages
are flushed to disk before the modified pages themselves.

In practice, the physical-log buffer is flushed first and then the buffers that contain
modified pages. Therefore, even when a shared-memory buffer page needs to be
flushed because a user thread is trying to acquire a buffer but none is available (a
foreground write), the buffer pages cannot be flushed until the before-image of the
page has been written to disk.

Flushing the Physical-Log Buffer

The database server temporarily stores before-images of some of the modified disk
pages in the physical-log buffer. If the before-image has been written to the
physical-log buffer but not to the physical log on disk, the physical-log buffer must
be flushed to disk before the modified page can be flushed to disk. This action is
required for the fast-recovery feature.

8-26 IBM Informix Dynamic Server Administrator’s Guide

 Both the physical-log buffer and the physical log contribute toward maintaining
the physical and logical consistency of the data. For information on physical
logging, checkpoints, and fast recovery, refer to Chapter 16, “Physical Logging,
Checkpoints, and Fast Recovery,” on page 16-1.

The following events cause the current physical-log buffer to flush:

v The current physical-log buffer becomes full.
v A modified page in shared memory must be flushed, but the before-image is still
in the current physical-log buffer.
v A full or fuzzy checkpoint occurs.

The contents of the physical-log buffer must always be flushed to disk before any
data buffers. This rule is required for the fast-recovery feature.

The database server uses only one of the two physical-log buffers at a time. This
buffer is the current physical-log buffer. Before the database server flushes the
current physical-log buffer to disk, it makes the other buffer the current buffer so
that it can continue writing while the first buffer is being flushed.

Synchronizing Buffer Flushing

When shared memory is first set up, all buffers are empty. As processing occurs,
data pages are read from disk into the buffers, and user threads begin to modify
these pages.

Describing Flushing Activity

To provide you with information about the specific condition that prompted
buffer-flushing activity, the database server defines three types of writes and
counts how often each write occurs:
v Foreground write
v LRU write
v Chunk write

To display the write counts that the database server maintains, use onstat -F as
described in the IBM Informix Dynamic Server Administrator's Reference.

If you implement mirroring for the database server, data is always written to the
primary chunk first. The write is then repeated on the mirror chunk. Writes to a
mirror chunk are included in the counts. For more information on monitoring the
types of writes that the database server performs, refer to “Monitoring Buffer-Pool
Activity” on page 9-11.

Foreground Write
Whenever an sqlexec thread writes a buffer to disk, it is termed a foreground write.
A foreground write occurs when an sqlexec thread searches through the LRU
queues on behalf of a user but cannot locate an empty or unmodified buffer. To
make space, the sqlexec thread flushes pages, one at a time, to hold the data to be
read from disk. (For more information, refer to “FIFO/LRU Queues” on page 8-21.)

If the sqlexec thread must perform buffer flushing just to acquire a shared-memory
buffer, performance can suffer. Foreground writes should be avoided. To display a
count of the number of foreground writes, run onstat -F. If you find that
foreground writes are occurring on a regular basis, tune the value of the
page-cleaning parameters. Either increase the number of page cleaners or decrease
the BUFFERPOOL lru_max_dirty value.
Chapter 8. Shared Memory 8-27
 LRU Write
Unlike foreground writes, LRU writes are performed by page cleaners rather than
by sqlexec threads. The database server performs LRU writes as background
writes that typically occur when the percentage of dirty buffers exceeds the percent
you that specified for lru_max_dirty in the BUFFERPOOL configuration parameter.

In addition, a foreground write can trigger an LRU write. When a foreground write
occurs, the sqlexec thread that performed the write alerts a page-cleaner to wake
up and clean the LRU for which it performed the foreground write.

In a properly tuned system, page cleaners ensure that enough unmodified buffer
pages are available for storing pages to be read from disk. Thus, sqlexec threads
that perform a query do not need to flush a page to disk before they read in the
disk pages required by the query. This condition can result in significant
performance gains for queries that do not make use of foreground writes.

LRU writes are preferred over foreground writes because page-cleaner threads
perform buffer writes much more efficiently than sqlexec threads do. To monitor
both types of writes, use onstat -F.

Chunk Write
Chunk writes are commonly performed by page-cleaner threads during a checkpoint
or, possibly, when every page in the shared-memory buffer pool is modified.
Chunk writes, which are performed as sorted writes, are the most efficient writes
available to the database server.

During a chunk write, each page-cleaner thread is assigned to one or more chunks.
Each page-cleaner thread reads through the buffer headers and creates an array of
pointers to pages that are associated with its specific chunk. (The page cleaners
have access to this information because the chunk number is contained within the
physical page number address, which is part of the page header.) This sorting
minimizes head movement (disk seek time) on the disk and enables the
page-cleaner threads to use the big buffers during the write, if possible.

In addition, because user threads must wait for the checkpoint to complete, the
page-cleaner threads are not competing with a large number of threads for CPU
time. As a result, the page-cleaner threads can finish their work with less context
switching.

Flushing the Logical-Log Buffer

The database server uses the shared-memory logical-log buffer as temporary
storage for records that describe modifications to database server pages. From the
logical-log buffer, these records of changes are written to the current logical-log file
on disk and eventually to the logical-log backup media. For a description of logical
logging, refer to Chapter 14, “Logical Log,” on page 14-1.

Five events cause the current logical-log buffer to flush:

v The current logical-log buffer becomes full.
v A transaction is prepared or committed in a database with unbuffered logging.
v A nonlogging database session terminates.
v A checkpoint occurs.
v A page is modified that does not require a before-image in the physical log.

The following sections discuss each of these events in detail.

8-28 IBM Informix Dynamic Server Administrator’s Guide

 After a Transaction Is Prepared or Terminated in a Database with
Unbuffered Logging
The following log records cause flushing of the logical-log buffers in a database
with unbuffered logging:
v COMMIT
v PREPARE
v XPREPARE
v ENDTRANS

For a comparison of buffered versus unbuffered logging, refer to the SET LOG
statement in the IBM Informix Guide to SQL: Syntax.

When a Session That Uses Nonlogging Databases or Unbuffered

Logging Terminates
Even for nonlogging databases, the database server logs certain activities that alter
the database schema, such as the creation of tables or extents. When the database
server terminates sessions that use unbuffered logging or nonlogging databases,
the logical-log buffer is flushed to make sure that any logging activity is recorded.

When a Checkpoint Occurs

For a detailed description of the events that occur during a checkpoint, refer to
“Checkpoints” on page 16-7.

When a Page Is Modified That Does Not Require a Before-Image

in the Physical-Log File
When a page is modified that does not require a before-image in the physical log,
the logical-log buffer must be flushed before that page is flushed to disk.

Buffering Large-Object Data

Simple large objects (TEXT or BYTE data) can be stored in either dbspaces or
blobspaces. Smart large objects (CLOB or BLOB data) are stored only in sbspaces.
The database server uses different methods to access each type of storage space.
The following sections describe buffering methods for each.

Writing Simple Large Objects

The database server writes simple large objects to disk pages in a dbspace in the
same way that it writes any other data type. For more information, refer to
“Flushing Data to Disk” on page 8-26.

You can also assign simple large objects to a blobspace. The database server writes
simple large objects to a blobspace differently from the way that it writes other
data to a shared-memory buffer and then flushes it to disk. For a description of
blobspaces, refer to the chapter on disk structure and storage in the IBM Informix
Dynamic Server Administrator's Reference.

Blobpages and Shared Memory

Blobspace blobpages store large amounts of data. Consequently, the database
server does not create or access blobpages by way of the shared-memory buffer
pool, and it does not write blobspace blobpages to either the logical or physical
logs.

If blobspace data passed through the shared-memory pool, it might dilute the
effectiveness of the pool by driving out index pages and data pages. Instead,
blobpage data is written directly to disk when it is created.
Chapter 8. Shared Memory 8-29
 To reduce logical-log and physical-log traffic, the database server writes blobpages
from magnetic media to dbspace backup tapes and logical-log backup tapes in a
different way than it writes dbspace pages. For a description of how blobspaces are
logged, refer to “Logging Blobspaces and Simple Large Objects” on page 14-6.

Blobpages stored on optical media are not written to dbspace and logical-log
backup tapes due to the high reliability of optical media.

Creation of Simple Large Objects

When simple-large-object data is written to disk, the row to which it belongs might
not exist yet. During an insert, for example, the simple large object is transferred
before the rest of the row data. After the simple large object is stored, the data row
is created with a 56-byte descriptor that points to its location. For a description of
how simple large objects are stored physically, refer to the structure of a dbspace
blobpage in the disk storage and structure chapter of the IBM Informix Dynamic
Server Administrator's Reference.

Creation of Blobpage Buffers

To receive simple large object data from the application process, the database
server creates a pair of blobspace buffers, one for reading and one for writing, each
the size of one blobspace blobpage. Each user has only one set of blobspace buffers
and, therefore, can access only one simple large object at a time.

Simple large object data is transferred from the client-application process to the
database server in 1-kilobyte segments. The database server begins filling the
blobspace buffers with the 1-kilobyte pieces and attempts to buffer two blobpages
at a time. The database server buffers two blobpages so that it can determine when
to add a forwarding pointer from one page to the next. When it fills the first buffer
and discovers that more data remains to transfer, it adds a forward pointer to the
next page before it writes the page to disk. When no more data remains to transfer,
the database server writes the last page to disk without a forward pointer.

When the thread begins writing the first blobspace buffer to disk, it attempts to
perform the I/O based on the user-defined blobpage size. For example, if the
blobpage size is 32 kilobytes, the database server attempts to read or write the data
in 32,768-byte increments. If the underlying hardware (such as the disk controller)
cannot transfer this amount of data in a single operation, the operating-system
kernel loops internally (in kernel mode) until the transfer is complete.

The blobspace buffers remain until the thread that created them is finished. When
the simple large object is written to disk, the database server deallocates the pair of
blobspace buffers. Figure 8-9 illustrates the process of writing a simple large object
to a blobspace.

8-30 IBM Informix Dynamic Server Administrator’s Guide

 Database server shared memory Database server disk space

Client

Blobspace
Virtual processor Temporary blobpage
buffers

Figure 8-9. Writing Simple Large Object to a Blobspace

Blobspace blobpages are allocated and tracked with the free-map page. Links that
connect the blobpages and pointers to the next blobpage segments are created as
needed.

A record of the operation (insert, update, or delete) is written to the logical-log

buffer.

Accessing Smart Large Objects

The database server accesses smart large objects through the shared-memory
buffers, in the same way that it accesses data that is stored in a dbspace. However,
the user-data portion of a smart large object is buffered at a lower priority than
normal buffer pages to prevent flushing data of higher value out of the buffer
pool. Buffering permits faster access to smart large objects that are accessed
frequently.

A smart large object is stored in an sbspace. You cannot store simple large objects
in an sbspace, and you cannot store smart large objects in a blobspace. An sbspace
consists of a user-data area and a metadata area. The user-data area contains the
smart-large-object data. The metadata area contains information about the content
of the sbspace. For more information on sbspaces, refer to “Sbspaces” on page
10-13.

Because smart large objects pass through the shared-memory buffer pool and can
be logged, you must consider them when you allocate buffers. Use the
BUFFERPOOL configuration parameter to allocate shared-memory buffers. As a
general rule, try to have enough buffers to hold two smart-large-object pages for
each concurrently open smart large object. (The additional page is available for
read-ahead purposes.) For more information about tuning buffers for smart large
objects, refer to your IBM Informix Dynamic Server Performance Guide.

Use the LOGBUFF configuration parameter to specify the size of the logical-log
buffer. For information about setting each of the following configuration
parameters, refer to the IBM Informix Dynamic Server Administrator's Reference:
v BUFFERPOOL
v LOGBUFF

The user-data area of smart large objects that are logged does not pass through the
physical log, so the PHYSBUFF parameter need not be adjusted for smart large
objects.

For more information on the structure of an sbspace, refer to sbspace structure in

the disk structures and storage chapter of the IBM Informix Dynamic Server

Chapter 8. Shared Memory 8-31

 Administrator's Reference. For information on creating an sbspace, see information
on the onspaces utility in the IBM Informix Dynamic Server Administrator's Reference.

Memory Use on 64-Bit Platforms

With 64-bit addressing, you can have larger buffer pools to reduce the amount of
I/O operations to obtain data from disks. Because 64-bit platforms allow for larger
memory-address space, the maximum values for the following memory-related
configuration parameters are larger on 64-bit platforms:
v BUFFERPOOL
v CLEANERS
v DS_MAX_QUERIES
v DS_TOTAL_MEMORY
v LOCKS
v LRUS
v SHMADD
v SHMVIRTSIZE

The machine notes for each 64-bit platform lists the maximum values for these
configuration parameters and platform-specific parameters such as SHMMAX. For
more information about the configuration parameters, see the IBM Informix
Dynamic Server Administrator's Reference and the chapter on shared memory in the
IBM Informix Dynamic Server Performance Guide.

8-32 IBM Informix Dynamic Server Administrator’s Guide

Chapter 9. Managing Shared Memory
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1
Setting Operating-System Shared-Memory Configuration Parameters . . . . . . . . . . . . . . . . 9-2
Maximum Shared-Memory Segment Size . . . . . . . . . . . . . . . . . . . . . . . . 9-2
Using More Than Two Gigabytes of Memory (Windows) . . . . . . . . . . . . . . . . . . 9-2
Maximum Number of Shared-Memory Identifiers (UNIX) . . . . . . . . . . . . . . . . . 9-3

Semaphores (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Setting Database Server Shared-Memory Configuration Parameters . . . . . . . . . . . . . . . . 9-3
Setting Parameters for Resident Shared Memory . . . . . . . . . . . . . . . . . . . . . . 9-4
Setting Parameters for Virtual Shared Memory . . . . . . . . . . . . . . . . . . . . . . 9-4
Setting Parameters for Shared-Memory Performance . . . . . . . . . . . . . . . . . . . . 9-5
Setting Shared-Memory Parameters with a Text Editor . . . . . . . . . . . . . . . . . . . . 9-5
Setting Shared-Memory Parameters with ISA . . . . . . . . . . . . . . . . . . . . . . . 9-5
Setting Shared-Memory Parameters with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 9-6
Setting SQL Statement Cache Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 9-6
Setting Up Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7
Turning Residency On or Off for Resident Shared Memory . . . . . . . . . . . . . . . . . . . 9-7
Turning Residency On or Off in Online Mode . . . . . . . . . . . . . . . . . . . . . . 9-7
Turning Residency On or Off When Restarting the Database Server . . . . . . . . . . . . . . . 9-7
Adding a Segment to the Virtual Portion of Shared Memory . . . . . . . . . . . . . . . . . . . 9-7
Monitoring Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Monitoring Shared-Memory Segments . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Monitoring the Shared-Memory Profile and Latches . . . . . . . . . . . . . . . . . . . . 9-8
Using Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-8
Using IBM Informix Server Administrator . . . . . . . . . . . . . . . . . . . . . . . 9-8
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Monitoring Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Using Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10
Monitoring Buffer-Pool Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Using Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . 9-11
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12

In This Chapter
This chapter tells you how to perform the following tasks, which concern
managing shared memory:
v Setting the shared-memory configuration parameters
v Setting up shared memory
v Turning residency on or off for the resident portion of the database server
shared memory
v Adding a segment to the virtual portion of shared memory
v Monitoring shared memory

This chapter does not cover the DS_TOTAL_MEMORY configuration parameter.

This parameter places a ceiling on the allocation of memory for decision-support
queries. For information on this parameter, refer to your IBM Informix Dynamic
Server Performance Guide.

© Copyright IBM Corp. 1996, 2005 9-1

Setting Operating-System Shared-Memory Configuration Parameters
Several operating-system configuration parameters can affect the use of shared
memory by the database server. Parameter names are not provided because names
vary among platforms, and not all parameters exist on all platforms. The following
list describes these parameters by function:
v Maximum operating-system shared-memory segment size, expressed in bytes or
kilobytes
v Minimum shared-memory segment size, expressed in bytes
v Maximum number of shared-memory identifiers
v Lower-boundary address for shared memory
v Maximum number of attached shared-memory segments per process
v Maximum amount of systemwide shared memory

UNIX Only
v Maximum number of semaphore identifiers
v Maximum number of semaphores
v Maximum number of semaphores per identifier

On UNIX, the machine notes file contains recommended values that you use to
configure operating-system resources. Use these recommended values when you
configure the operating system. For information on how to set these
operating-system parameters, consult your operating-system manuals.

For specific information about your operating-system environment, refer to the

machine notes file that is provided with the database server.
End of UNIX Only

Maximum Shared-Memory Segment Size

When the database server creates the required shared-memory segments, it
attempts to acquire as large an operating-system segment as possible. The first
segment size that the database server tries to acquire is the size of the portion that
it is allocating (resident, virtual, or communications), rounded up to the nearest
multiple of 8 kilobytes.

The database server receives an error from the operating system if the requested
segment size exceeds the maximum size allowed. If the database server receives an
error, it divides the requested size by two and tries again. Attempts at acquisition
continue until the largest segment size that is a multiple of 8 kilobytes can be
created. Then the database server creates as many additional segments as it
requires.

Using More Than Two Gigabytes of Memory (Windows)

The database server can access shared-memory segments larger than two gigabytes
on Windows. However, you must enable this feature with an entry in the Windows
boot file.

To add the entry, edit the [Link] file (located in the top level, or root directory).
You can either add a new boot option or use the currently existing boot option. To
enable support for more than two gigabytes, add the following text to the end of
the boot line:
/3GB

9-2 IBM Informix Dynamic Server Administrator’s Guide

 The following example has support for more than two gigabytes enabled:
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT
Workstation Version 4.00"
/3GB

The maximum size of the shared-memory segment depends on the operating

system, but it is approximately 3 gigabytes for Windows without additional
drivers.

Maximum Number of Shared-Memory Identifiers (UNIX)

Shared-memory identifiers affect the database server operation when a virtual
processor attempts to attach to shared memory. The operating system identifies
each shared-memory segment with a shared-memory identifier. For most operating
systems, virtual processors receive identifiers on a first-come, first-served basis, up
to the limit that is defined for the operating system as a whole. For more
information about shared-memory identifiers, refer to “How Virtual Processors
Attach to Shared Memory” on page 8-7.

You might be able to calculate the maximum amount of shared memory that the
operating system can allocate by multiplying the number of shared-memory
identifiers by the maximum shared-memory segment size.

Semaphores (UNIX)
The database server operation requires one UNIX semaphore for each virtual
processor, one for each user who connects to the database server through shared
memory (ipcshm protocol), six for database server utilities, and sixteen for other
purposes.

Setting Database Server Shared-Memory Configuration Parameters

Shared-memory configuration parameters fall into the following categories based
on their purposes:
v Parameters that affect the resident portion of shared memory
v Parameters that affect the virtual portion of shared memory
v Parameters that affect performance

You can set shared-memory configuration parameters in the following ways:

v Using a text editor

Chapter 9. Managing Shared Memory 9-3

 v IBM Informix Server Administrator (ISA)

UNIX Only

v Using ON–Monitor
End of UNIX Only

On UNIX, you must be root or user informix to use either method. On Windows,
you must be a user in the Informix Admin group.

Setting Parameters for Resident Shared Memory

Table 9-1 lists the parameters in the ONCONFIG file that specify the configuration
of the buffer pool and the internal tables in the resident portion of shared memory.
Before any changes that you make to the configuration parameters take effect, you
must shut down and restart the database server. For a description of the
configuration parameters, refer to the IBM Informix Dynamic Server Administrator's
Reference.
Table 9-1. Configuring the Resident Portion of Shared Memory
Configuration Parameter Purpose
BUFFERPOOL Specifies information about the buffer pool that must be defined for each different
page size that a dbspace uses.
LOCKS Specifies the initial number of locks for database objects; for example, rows, key
values, pages, and tables
LOGBUFF Specifies the size of the logical-log buffers
PHYSBUFF Specifies the size of the physical-log buffers
RESIDENT Specifies residency for the resident portion of the database server shared memory
SERVERNUM Specifies a unique identification number for the database server on the local host
computer
SHMTOTAL Specifies the total amount of memory to be used by the database server

Setting Parameters for Virtual Shared Memory

Table 9-2 lists the ONCONFIG parameters that you use to configure the virtual
portion of shared memory. For more information, see the chapter on configuration
effects on memory in your IBM Informix Dynamic Server Performance Guide.

9-4 IBM Informix Dynamic Server Administrator’s Guide

Table 9-2. Configuring the Virtual Portion of Shared Memory
Configuration Parameter Purpose
DS_HASHSIZE Number of hash buckets for lists in the data-distribution cache.
DS_POOLSIZE Maximum number of entries in the data-distribution cache.
PC_HASHSIZE Specifies the number of hash buckets for the UDR cache and other caches that the
database server uses. For more information about setting PC_HASHSIZE, refer to
your IBM Informix Dynamic Server Performance Guide.
PC_POOLSIZE Specifies the number of UDRs (SPL routines and external routines) that can be
stored in the UDR cache. In addition, this parameter specifies the size of other
database server caches, such as the typename cache and the opclass cache. For more
information about setting PC_POOLSIZE, refer to your IBM Informix Dynamic Server
Performance Guide.
SHMADD Specifies the size of dynamically added shared-memory segments
EXTSHMADD Specifies the size of an added extension segment
SHMTOTAL Specifies the total amount of memory to be used by the database server
SHMVIRTSIZE Specifies the initial size of the virtual portion of shared memory
STACKSIZE Specifies the stack size for the database server user threads

Setting Parameters for Shared-Memory Performance

Table 9-3 lists the ONCONFIG parameters that set shared-memory performance
options. For more information, see the chapter on configuration parameters in the
IBM Informix Dynamic Server Administrator's Reference.
Table 9-3. Setting Shared-Memory Performance Options
Configuration Parameter Purpose
CKPTINTVL Specifies the maximum number of seconds that can elapse before the database
server checks if a checkpoint is needed
CLEANERS Specifies the number of page-cleaner threads that the database server is to run
RA_PAGES Specifies the number of disk pages that the database server should attempt to read
ahead when it performs sequential scans of data or index records
RA_THRESHOLD Specifies the number of unprocessed memory pages that, after they are read, cause
the database server to read ahead on disk

Setting Shared-Memory Parameters with a Text Editor

You can use a text editor to set the configuration parameters for resident and
virtual shared memory, and shared-memory performance. Locate the parameter in
the ONCONFIG file, enter the new value or values, and rewrite the file to disk.
Before the changes take effect, however, you must shut down and restart the
database server.

Setting Shared-Memory Parameters with ISA

Use ISA to monitor and set the following shared-memory parameters. For more
information, see the ISA online help:
v Execute utility commands such as onmode and onstat.
v Edit ONCONFIG parameters.
v Monitor segments
v Monitor pools
v Monitor resident memory
Chapter 9. Managing Shared Memory 9-5
 v Monitor nonresident memory
v Monitor data dictionary cache

Setting Shared-Memory Parameters with ON-Monitor (UNIX)

To set the configuration parameters for the resident and virtual portions of shared
memory with ON–Monitor, select the Parameters > Shared-Memory option.

To determine the page size for your system, choose the Parameters >
Shared-memory option in ON–Monitor. The database server page size is the last
entry on the page.

Important: The configuration parameters SHMADD, EXTSHMADD, and

SHMTOTAL affect both the resident and virtual portions of shared
memory.

To set the configuration parameters for the following shared-memory performance

options with ON–Monitor, select the Parameters > perFormance option:
v CKPTINTVL
v RA_PAGES
v RA_THRESHOLD

Setting SQL Statement Cache Parameters

Table 9-4 shows the different ways that you can configure the SQL statement cache.
Table 9-4. Configuring the SQL Statement Cache
Configuration Parameter Purpose onmode Command
STMT_CACHE Turns on, enables, or disables the SQL statement onmode -e mode
cache in memory. If turned on, specifies whether
the SQL statement cache can hold a parsed and
optimized SQL statement.
STMT_CACHE_HITS Specifies the number of hits (references) to a onmode -W
statement before it is fully inserted into the SQL STMT_CACHE_HITS
statement cache.
STMT_CACHE_NOLIMIT Controls whether to insert statements into the onmode -W
SQL statement cache after its size is greater than STMT_CACHE_NOLIMIT
the STMT_CACHE_SIZE value.
STMT_CACHE_NUMPOOL Defines the number of memory pools for the None
SQL statement cache.
STMT_CACHE_SIZE Specifies the size of the SQL statement cache. onmode -W
STMT_CACHE_SIZE

Use the following onstat options to monitor the SQL statement cache:
v onstat -g ssc (same as onstat -g cac stmt)
v onstat -g ssc all
v onstat -g ssc pool

For more information on these configuration parameters, onstat -g options, and

onmode commands, see the IBM Informix Dynamic Server Administrator's Reference.

For more information on using the SQL statement cache, monitoring it with the
onstat -g options, and tuning the configuration parameters, see improving query

9-6 IBM Informix Dynamic Server Administrator’s Guide

 performance in the IBM Informix Dynamic Server Performance Guide. For details on
qualifying and identical statements, see the IBM Informix Guide to SQL: Syntax.

Setting Up Shared Memory

To set up shared memory, take the database server offline and then online. For
information on how to take the database server from online mode to offline, refer
to “From Any Mode Immediately to Offline” on page 4-13.

Turning Residency On or Off for Resident Shared Memory

You can turn residency on or off for the resident portion of shared memory in
either of the following two ways:
v Use the onmode utility to reverse the state of shared-memory residency
immediately while the database server is in online mode.
v Change the RESIDENT parameter in the ONCONFIG file to turn
shared-memory residency on or off for the next time that you set up the
database server shared memory.

For a description of the resident portion of shared memory, refer to “Resident

Portion of Shared Memory” on page 8-10.

Turning Residency On or Off in Online Mode

To turn residency on or off while the database server is in online mode, use the
onmode utility.

To turn on residency immediately for the resident portion of shared memory,

execute the following command:
% onmode -r

To turn off residency immediately for the resident portion of shared memory,
execute the following command:
% onmode -n

These commands do not change the value of the RESIDENT parameter in the
ONCONFIG file. That is, this change is not permanent, and residency reverts to
the state specified by the RESIDENT parameter the next time that you set up
shared memory. On UNIX, you must be root or user informix to turn residency on
or off. On Windows, you must be a user in the Informix Admin group to turn
residency on or off.

Turning Residency On or Off When Restarting the Database

Server
You can use a text editor to turn residency on or off. To change the current state of
residency, use a text editor to locate the RESIDENT parameter. Set RESIDENT to 1
to turn residency on or to 0 to turn residency off, and rewrite the file to disk.
Before the changes take effect, you must shut down and restart the database server.

Adding a Segment to the Virtual Portion of Shared Memory

The -a option of the onmode utility allows you to add a segment of specified size
to virtual shared memory.

Chapter 9. Managing Shared Memory 9-7

 You do not normally need to add segments to virtual shared memory because the
database server automatically adds segments as needed.

The option to add a segment with the onmode utility is useful if the number of
operating-system segments is limited, and the initial segment size is so low,
relative to the amount that is required, that the operating-system limit of
shared-memory segments is nearly exceeded.

Monitoring Shared Memory

This section describes how to monitor shared-memory segments, the
shared-memory profile, and the use of specific shared-memory resources (buffers,
latches, and locks).

You can use the onstat -o utility to capture a static snapshot of database server
shared memory for later analysis and comparison.

Monitoring Shared-Memory Segments

Monitor the shared-memory segments to determine the number and size of the
segments that the database server creates. The database server allocates
shared-memory segments dynamically, so these numbers can change. If the
database server is allocating too many shared-memory segments, you can increase
the SHMVIRTSIZE configuration parameter. For more information, see the chapter
on configuration parameters in the IBM Informix Dynamic Server Administrator's
Reference.

The onstat -g seg command lists information for each shared-memory segment,
including the address and size of the segment, and the amount of memory that is
free or in use. For an example of onstat -g seg output, see information on the
onstat utility in the IBM Informix Administrator's Reference.

Monitoring the Shared-Memory Profile and Latches

Monitor the database server profile to analyze performance and the use of
shared-memory resources. The Profile screen maintains cumulative statistics on
shared-memory use. To reset these statistics to zero, use the onstat -z option. For a
description of all the fields that onstat displays, see information on the onstat
utility in the IBM Informix Dynamic Server Administrator's Reference.

You can obtain statistics on latch use and information on specific latches. These
statistics provide a measure of the system activity.

Using Command-Line Utilities

You can use the following command-line utilities to monitor shared memory and
latches:
v onstat -s
v onstat -p

onstat -s: Use onstat -s command to obtain latch information.

onstat -p: Execute onstat -p to display statistics on database server activity and
waiting latches (in the lchwaits field). For an example of onstat -p output, see
information on the onstat utility in the IBM Informix Administrator's Reference.

Using IBM Informix Server Administrator

You can use ISA to obtain information about latches, spin locks, and profiles.

9-8 IBM Informix Dynamic Server Administrator’s Guide

 Using ON-Monitor (UNIX)
Select Status > Profile. The screen displays shared-memory statistics, as well as the
current operating mode, the boot time, the current time, and latches.

Using SMI Tables

Query the sysprofile table to obtain shared-memory statistics. This table contains
all of the statistics available in onstat -p output except the ovbuff, usercpu, and
syscpu statistics.

Monitoring Buffers
You can obtain both statistics on buffer use and information on specific buffers.
The statistical information includes the percentage of data writes that are cached to
buffers and the number of times that threads had to wait to obtain a buffer. The
percentage of writes cached is an important measure of performance. (For
information on how to use this statistic to tune the database server, see your IBM
Informix Dynamic Server Performance Guide.)

The number of waits for buffers gives a measure of system concurrency.

Information on specific buffers includes a listing of all the buffers in shared

memory that are held by a thread. This information allows you to track the status
of a particular buffer. For example, you can determine if another thread is waiting
for the buffer.

Using Command-Line Utilities

You can use the following command-line utilities to monitor buffers:
v onstat -p
v onstat -B
v onstat -b
v onstat -X
v onstat -R

onstat -p: Execute onstat -p to obtain statistics about cached reads and writes. The
following caching statistics appear in four fields on the top row of the output
display:
v The number of reads from shared-memory buffers (bufreads)
v The percentage of reads cached (%cached)
v The number of writes to shared memory (bufwrits)
v The percentage of writes cached (%cached)
v Information on generic pages (nonstandard pages in the buffer pool)

In the output, the number of reads or writes can appear as a negative number if
the number of occurrences exceeds 232 (depends on the platform).

The onstat -p option also displays a statistic (bufwaits) that indicates the number
of times that sessions had to wait for a buffer.

For an example of onstat -p output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

onstat -B: Execute onstat -B to obtain information on all buffers currently in use,
including:
v The address of every regular shared-memory buffer

Chapter 9. Managing Shared Memory 9-9

 v The address of the thread that currently holds the buffer
v The address of the first thread that is waiting for each buffer
v Information on buffer pools

For an example of onstat -B output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

onstat -b: Execute onstat -b to obtain the following information about each buffer:
v Address of each buffer currently held by a thread
v Page numbers for the page held in the buffer
v Type of page held in the buffer (for example, data page, tblspace page, and so
on)
v Type of lock placed on the buffer (exclusive or shared)
v Address of the thread that is currently holding the buffer
v Address of the first thread that is waiting for each buffer
v Information on buffer pools

You can compare the addresses of the user threads to the addresses that appear in
the onstat -u display to obtain the session ID number.

For more information on the fields that onstat displays, see information on the
onstat utility in the IBM Informix Dynamic Server Administrator's Reference

onstat -X: Execute onstat -X to obtain the same information as for onstat -b, along
with the complete list of all threads that are waiting for buffers, not just the first
waiting thread.

onstat -R: Use onstat -R to display information about buffer pools, including
information about buffers.

Using ON-Monitor (UNIX)

To access the fields mentioned on page 9-9 for onstat -p (bufreads, %cached,
bufwrits %cached), select the Status > Profile option.

Here is an example of cached read and write statistics in the Profile option of the
ON-Monitor Status menu:
...

Disk Reads Buff. Reads %Cached Disk Writes Buff. Writes %Cached
177 330 46.36 4 0 0.00
...

Using SMI Tables

Query the sysprofile table to obtain statistics on cached reads and writes and total
buffer waits. The following rows are relevant.
Row Description
dskreads Number of reads from disk
bufreads Number of reads from buffers
dskwrites Number of writes to disk
bufwrites Number of writes to buffers
buffwts Number of times that any thread had to wait for a buffer

9-10 IBM Informix Dynamic Server Administrator’s Guide

Monitoring Buffer-Pool Activity
You can obtain statistics that relate to buffer availability as well as information on
the buffers in each LRU queue.

The statistical information includes the number of times that the database server
attempted to exceed the maximum number of buffers and the number of writes to
disk (categorized by the event that caused the buffers to flush). These statistics
help you determine if the number of buffers is appropriate. For information on
tuning database server buffers, see your IBM Informix Dynamic Server Performance
Guide.

Information on the buffers in each LRU queue consists of the length of the queue
and the percentage of the buffers in the queue that have been modified.

Using Command-Line Utilities

You can use the onstat utility to obtain information on buffer-pool activity. You
also can execute onstat options from ISA.

For more information about the onstat options, see information on the onstat
utility in the IBM Informix Dynamic Server Administrator's Reference.

onstat -p: The onstat -p output contains a statistic (ovbuff) that indicates the
number of times the database server attempted to exceed the maximum number of
shared buffers specified by buffers value in the BUFFERPOOL configuration
parameter.

onstat -F: Execute onstat -F to obtain a count by write type of the writes
performed. (For an explanation of the different write types, see “Describing
Flushing Activity” on page 8-27.

The onstat -F command displays totals for the following write types:
v Foreground write
v LRU write
v Chunk write

The onstat -F command also lists the following information about the page
cleaners:
v Page-cleaner number
v Page-cleaner shared-memory address
v Current state of the page cleaner
v LRU queue to which the page cleaner was assigned

For an example of onstat -F output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

onstat -R: Execute onstat -R to obtain information about the number of buffers in
each LRU queue and the number and percentage of the buffers that are modified
or free.

For an example of onstat -R output, see information on the onstat utility in the
IBM Informix Administrator's Reference

Chapter 9. Managing Shared Memory 9-11

 Using SMI Tables
Query the sysprofile table to obtain the statistics on write types that are held in
the following rows.
Row Description
fgwrites Number of foreground writes
lruwrites Number of LRU writes
chunkwrites Number of chunk writes

9-12 IBM Informix Dynamic Server Administrator’s Guide

Chapter 10. Data Storage
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Physical and Logical Units of Storage . . . . . . . . . . . . . . . . . . . . . . . . . .10-2
Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
Disk Allocation for Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
Disk Access on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-3
Unbuffered or Buffered Disk Access on UNIX . . . . . . . . . . . . . . . . . . . . .10-4
Offsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-5
Blobpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-6
Sbpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-7
Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-8
Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10-9
Control of Where Data Is Stored . . . . . . . . . . . . . . . . . . . . . . . . . . .10-9
Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Temporary Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11
Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-12
Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Advantages of Using Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Sbspaces and Enterprise Replication . . . . . . . . . . . . . . . . . . . . . . . . . 10-13
Metadata, User Data, and Reserved Area . . . . . . . . . . . . . . . . . . . . . . . 10-13
Control of Where Data Is Stored . . . . . . . . . . . . . . . . . . . . . . . . . . 10-14
Storage Characteristics of Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . 10-15
Extent Sizes for Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
Average Smart-Large-Object Size . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
Buffering Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-16
Last-Access Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Lock Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-17
Levels of Inheritance for Sbspace Characteristics . . . . . . . . . . . . . . . . . . . . . 10-17
More Information About Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . 10-18
Temporary Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-19
Comparison of Temporary and Standard Sbspaces . . . . . . . . . . . . . . . . . . . . 10-20
Temporary Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 10-20
Extspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-22
Table Types for Dynamic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-23
Standard Permanent Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
RAW Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Temp Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-24
Properties of Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Loading of Data Into a Table . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Fast Recovery of Table Types . . . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Backup and Restore of RAW Tables . . . . . . . . . . . . . . . . . . . . . . . . 10-25
Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Temporary Tables That You Create. . . . . . . . . . . . . . . . . . . . . . . . . 10-26
Temporary Tables That the Database Server Creates . . . . . . . . . . . . . . . . . . . 10-27
Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Maximum Number of Tblspaces in a Table . . . . . . . . . . . . . . . . . . . . . . . 10-28
Table and Index Tblspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-28
Extent Interleaving . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-29
Table Fragmentation and Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . 10-30
Amount of Disk Space Needed to Store Data . . . . . . . . . . . . . . . . . . . . . . . 10-31
Size of the Root Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-31
Physical and Logical Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32

© Copyright IBM Corp. 1996, 2005 10-1

 Temporary Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-32
Critical Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Extra Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Amount of Space That Databases Require . . . . . . . . . . . . . . . . . . . . . . . 10-33
Disk-Layout Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Dbspace and Chunk Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . 10-33
Table-Location Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-34
Sample Disk Layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-35
Sample Layout When Performance Is Highest Priority . . . . . . . . . . . . . . . . . . . 10-36
Sample Layout When Availability Is Highest Priority . . . . . . . . . . . . . . . . . . . 10-36
Logical-Volume Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-37

In This Chapter
This chapter defines terms and explains the concepts that you must understand to
perform the tasks described in Chapter 11, “Managing Disk Space,” on page 11-1.
This chapter covers the following topics:
v Definitions of the physical and logical units that the database server uses to
store data on disk
v Instructions on how to calculate the amount of disk space that you need to store
your data
v Guidelines on how to lay out your disk space and where to place your
databases and tables

See the current Dynamic Server release notes for any supplementary information
on the maximum values related to the storage units discussed in this chapter.

Physical and Logical Units of Storage

The database server uses the physical units of storage to allocate disk space. Unlike
the logical units of storage whose size fluctuates, each of the physical units has a
fixed or assigned size that is determined by the disk architecture. The database
server uses the following physical units to manage disk space:
v Chunk
v Page
v Extent
v Blobpage
v Sbpage

The database server stores data in the following logical units:

v Dbspace
v Temporary dbspace
v Blobspace
v Sbspace
v Temporary sbspace
v Extspace
v Database
v Table
v Tblspace
v Partition

10-2 IBM Informix Dynamic Server Administrator’s Guide

 The database server maintains the following storage structures to ensure physical
and logical consistency of data:
v Logical log
v Physical log
v Reserved pages

The following sections describe the various data-storage units that the database
server supports and the relationships between those units. For information about
reserved pages, see the disk structures and storage chapter in the IBM Informix
Dynamic Server Administrator's Reference.

Chunks
A chunk is the largest unit of physical disk dedicated to database server data
storage. Chunks provide administrators with a significantly large unit for
allocating disk space. The maximum size of an individual chunk is 4 terabytes. The
number of allowable chunks is 32,766. You must run onmode -BC to enable the
maximum size of a chunk and the maximum number allowable. If onmode -BC is
not run, then the maximum chunk size is 2 gigabytes.

The database server administrator adds one or more chunks to the following
storage spaces when they approach full capacity:
v Dbspace (see page 10-9)
v Blobspace (see page 10-12)
v Sbspace (see page 10-13)

For information on chunk names, size, and number, see “Specifying Names for
Storage Spaces and Chunks” on page 11-7 and “Specifying the Maximum Size of
Chunks” on page 11-7.

The database server also uses chunks for mirroring. A primary chunk is a chunk
from which the database server copies data to a mirror chunk. If the primary chunk
fails, the database server brings the mirror chunk online automatically. For more
information, see Chapter 18, “Mirroring,” on page 18-1.

Disk Allocation for Chunks

The database server can use regular operating-system files or raw disk devices to
store data. On UNIX, you should use raw disk devices to store data whenever
performance is important. On Windows, using NTFS files to store data is
recommended for ease of administration.

An Informix storage space can reside on an NFS-mounted file system using regular
operating-system files.

Disk Access on Windows

On Windows, both raw disks and NTFS use kernel asynchronous I/O (KAIO). The
Windows file system manager adds additional overhead to disk I/O, so using raw
disks provides slight performance advantages. Because NTFS files are a more
standard method of storing data, you should use NTFS files instead of raw disks.
Consider using raw disks if your database server requires a large amount of disk
access.

Raw Disk Space on Windows: On Windows, raw disk space can be either a
physical drive without a drive letter or a logical disk partition that has been

Chapter 10. Data Storage 10-3

 assigned a drive letter using the Disk Administrator. The space can either be
formatted or unformatted. If it contains data, the data will be overwritten after the
space has been allocated to the database server. For more information, see
“Allocating Raw Disk Space on Windows” on page 11-6.

NTFS Files: You must use NTFS files, not FAT files, for disk space on Windows.
For more information, see “Allocating NTFS File Space on Windows” on page 11-6.

Unbuffered or Buffered Disk Access on UNIX

You can allocate disk space in two ways:
v Use files that are buffered through the operating system. These files are often
called cooked files.
v Use unbuffered disk access, also called raw disk space.

When dbspaces reside on raw disk devices (also called character-special devices), the
database server uses unbuffered disk access. Performance is much better when you
use raw disk devices than cooked files because the database server has direct I/O
access to the devices. A raw disk directly transfers data between the database
server memory and disk without also copying data.

To create a raw device, configure a block device (hard disk) with a raw interface.
The storage space that the device provides is called raw disk space. A chunk of raw
disk space is physically contiguous.

The name of the chunk is the name of the character-special file in the /dev
directory. In many operating systems, you can distinguish the character-special file
from the block-special file by the first letter in the filename (typically r). For
example, /dev/rsd0f is the character-special device that corresponds to the
/dev/sd0f block-special device.

For more information, see “Allocating Raw Disk Space on UNIX” on page 11-5.

A cooked file is a regular file that the operating system manages. Cooked file chunks
and raw disk chunks are equally reliable. Unlike raw disk space, the logically
contiguous blocks of a cooked file might not be physically contiguous.

You can more easily allocate cooked files than raw disk space. To allocate a cooked
file, you need only create the file on any existing partition. The name of the chunk
is the complete pathname of the file. These steps are described in detail in
“Allocating Cooked File Spaces on UNIX” on page 11-4.

In a learning environment, where performance is not critical, or for static data,

cooked files can be convenient. If you must use cooked UNIX files, store the least
frequently accessed data in those files. Store the files in a file system with minimal
activity.

For cooked file chunks, the operating system processes all chunk I/O from its own
buffer pool and ensures that all writes to chunks are physically written to the disk.

Important: While you should use raw disk devices on UNIX to achieve better
performance, recent advances in I/O caching for cooked writes can
provide similar if not better performance. To determine the best device
performance, perform benchmark testing on the system with both
types of devices for the dbspace and table layout.

10-4 IBM Informix Dynamic Server Administrator’s Guide

 When using raw disks, you do not need to take any special action to create chunks
and files that are larger than two gigabytes. If you want to create large chunks in
cooked files, or if you want to use the various database export and import utilities
with large files, you must ensure that the files systems that will hold the large files
are properly configured.

Offsets
The system administrator might divide a physical disk into partitions, which are
different parts of a disk that have separate pathnames. Although you should use
an entire disk partition when you allocate a chunk on a raw disk device, you can
subdivide partitions or cooked files into smaller chunks using offsets. For more
information, see “Disk-Layout Guidelines” on page 10-33.

Tip: With a 4-terabyte limit to the size of a chunk, you can avoid partitioning a
disk by assigning a single chunk per disk drive.

An offset allows you to indicate the location of a given chunk on the disk partition,
file, or device. For example, suppose that you create a 1000-kilobyte chunk that
you want to divide into two chunks of 500 kilobytes each. You can use an offset of
zero kilobytes to mark the beginning of the first chunk and an offset of 500
kilobytes to mark the beginning of the second chunk.

You can specify an offset whenever you create, add, or drop a chunk from a
dbspace, blobspace, or sbspace.

You might also need to specify an offset to prevent the database server from
overwriting partition information. “Allocating Raw Disk Space on UNIX” on page
11-5 explains when and how to specify an offset.

Pages
A page is the physical unit of disk storage that the database server uses to read
from and write to Informix databases. Figure 10-1 illustrates the concept of a page,
represented by a darkened sector of a disk platter.

Figure 10-1. A Page on Disk

On most UNIX platforms, the page size is 2 kilobytes. On Windows, the page size
is 4 kilobytes. Because your hardware determines the size of your page, you cannot
alter this value.

A chunk contains a certain number of pages, as Figure 10-2 illustrates. A page is

always entirely contained within a chunk; that is, a page cannot cross chunk
boundaries.

Chapter 10. Data Storage 10-5

 Chunk

Page

Figure 10-2. A Chunk, Logically Separated into a Series of Pages

For information on how the database server structures data within a page, see the
chapter on disk structures and storage in the IBM Informix Dynamic Server
Administrator's Reference

Blobpages
A blobpage is the unit of disk-space allocation that the database server uses to
store simple large objects (TEXT or BYTE data) within a blobspace. For a
description of blobspaces, refer to “Blobspaces” on page 10-12.

You specify blobpage size as a multiple of the database server page size. Because
the database server allocates blobpages as contiguous spaces, it is more efficient to
store simple large objects in blobpages that are as close to the size of the data as
possible. Figure 10-3 illustrates the concept of a blobpage, represented as a multiple
(three) of a data page.

Figure 10-3. A Blobpage on Disk

For information about how Dynamic Server structures data stored in a blobpage,
see structure of a blobspace blobpage in the disk structures and storage chapter of
the IBM Informix Dynamic Server Administrator's Reference.

Just as with pages in a chunk, a certain number of blobpages compose a chunk in

a blobspace, as Figure 10-4 illustrates. A blobpage is always entirely contained in a
chunk and cannot cross chunk boundaries.

10-6 IBM Informix Dynamic Server Administrator’s Guide

 Chunk
Blobpage (defined when
blobspace was created)

Figure 10-4. A Chunk in a Blobspace, Logically Separated into a Series of Blobpages

Instead of storing simple-large-object data in a blobspace, you can choose to store

it in a dbspace. However, for a simple large object larger than two pages,
performance improves when you store it in a blobspace. Simple large objects stored
in a dbspace can share a page, but simple large objects stored in a blobspace do
not share pages.

For information on how to determine the size of a blobpage, refer to “Determining

Blobpage Size” on page 11-21.

Sbpages
An sbpage is the type of page that the database server uses to store smart large
objects within a sbspace. For a description of sbspaces, refer to “Sbspaces” on page
10-13. Unlike blobpages, sbpages are not configurable. An sbpage is the same size
as the database server page, which is usually 2 kilobytes on UNIX and 4 kilobytes
on Windows.

The unit of allocation in an sbspace is an extent, whereas the unit of allocation in a

blobspace is a blobpage. Just as with pages in a chunk, a certain number of smart
large object extents compose a chunk in an sbspace, as Figure 10-5 illustrates. An
extent is always entirely contained in a chunk and cannot cross chunk boundaries.

Chunk
Smart-large-object extent
(size calculated by
database server)

Figure 10-5. A Chunk in an Sbspace, Logically Separated into a Series of Extents

Chapter 10. Data Storage 10-7

 Smart large objects cannot be stored in a dbspace or blobspace. For more
information, see “Sbspaces” on page 10-13, and sbspace structure in the disk
structures and storage chapter of the IBM Informix Dynamic Server Administrator's
Reference.

The database server calculates the extent size for a smart large object from a set of
heuristics, such as the number of bytes in a write operation. For more information,
see “Extent Sizes for Sbspaces” on page 10-16.

Extents
When you create a table, the database server allocates a fixed amount of space to
contain the data to be stored in that table. When this space fills, the database
server must allocate space for additional storage. The physical unit of storage that
the database server uses to allocate both the initial and subsequent storage space is
called an extent. Figure 10-6 illustrates the concept of an extent.

Chunk

Page

Extent

Figure 10-6. An Extent That Consists of Six Contiguous Pages on a Raw Disk Device

An extent consists of a collection of contiguous pages that store data for a given
table. (See “Tables” on page 10-22.) Every permanent database table has two extent
sizes associated with it. The initial-extent size is the number of kilobytes allocated
to the table when it is first created. The next-extent size is the number of kilobytes
allocated to the table when the initial extent (and any subsequent extents) becomes
full. For permanent tables and user-defined temporary tables, the next-extent size
begins to double after 16 extents have been added. For system-created temporary
tables, the next-extent size begins to double after 4 extents have been added.

To specify the initial-extent size and next-extent size, use the CREATE TABLE and
ALTER TABLE statements. For more information, see the IBM Informix Guide to
SQL: Syntax and disk structures in the IBM Informix Dynamic Server Administrator's
Reference.

When you create a table with a column for CLOB or BLOB data types, you also
define extents for an sbspace. For more information, refer to “Storage
Characteristics of Sbspaces” on page 10-15.

Figure 10-7 shows how the database server allocates six pages for an extent:
v An extent is always entirely contained in a chunk; an extent cannot cross chunk
boundaries.

10-8 IBM Informix Dynamic Server Administrator’s Guide

 v If the database server cannot find the contiguous disk space that is specified for
the next-extent size, it searches the next chunk in the dbspace for contiguous
space.

Figure 10-7. Process of Extent Allocation

Dbspaces
A dbspace is a logical unit that can contain between 1 and 32,767 chunks. Place
databases, tables, logical-log files, and the physical log in dbspaces.

Control of Where Data Is Stored

A key responsibility of the database server administrator is to control where the
database server stores data. By storing high-use access tables or critical dbspaces
(root dbspace, physical log, and logical log) on your fastest disk drive, you can
improve performance. By storing critical data on separate physical devices, you
ensure that when one of the disks holding noncritical data fails, the failure affects
only the availability of data on that disk.

As Figure 10-8 shows, to control the placement of databases or tables, you can use
the IN dbspace option of the CREATE DATABASE or CREATE TABLE statements.
(For more information, see “Tables” on page 10-22.)

Chapter 10. Data Storage 10-9

 Dbspace on UNIX
% onspaces -c -d stores_space -p /dev/rsd0f -o 0 -s 10000

CREATE TABLE stores_demo IN stores_space

/dev/rsd0f

Figure 10-8. Controlling Table Placement with the CREATE TABLE... IN Statement

Before you create a database or table in a dbspace, you must first create the
dbspace. For more information on how to create a dbspace, see “Creating a
Dbspace that Uses the Default Page Size” on page 11-8.

A dbspace includes one or more chunks, as Figure 10-9 shows. You can add more
chunks at any time. It is a high-priority task of a database server administrator to
monitor dbspace chunks for fullness and to anticipate the need to allocate more
chunks to a dbspace. (See “Monitoring Disk Usage” on page 11-32.) When a
dbspace contains more than one chunk, you cannot specify the chunk in which the
data resides.

Logical units of storage Physical units of storage

Chunks
Database
System catalog
Dbspace 1 Chunk 1

Table 1
Dbspace 2 Chunk 2

Table 2
Dbspace 3 Chunk 3

Chunk 4

Figure 10-9. Dbspaces That Link Logical and Physical Units of Storage

The database server uses the dbspace to store databases and tables. (See “Tables”
on page 10-22.)

When you create a standard or temporary dbspace, you can specify the page size
for the dbspace. You cannot specify a page size for blobspaces, sbspaces, or
external spaces. If you do not specify a page size, the size of the root dbspace is
the default page size. For more information, see “Creating a Dbspace with a
Non-Default Page Size” on page 11-11.

10-10 IBM Informix Dynamic Server Administrator’s Guide

 When you create a standard dbspace, you can specify the first and next extent
sizes for the tblspace tblspace in the dbspace. Do this if you want to reduce the
number of tblspace tblspace extents and reduce the frequency of situations when
you need to place the tblspace tblspace extents in non-primary chunks. For more
information, see “Specifying the First and Next Extent Sizes for the tblspace
tblspace” on page 11-10.

You can mirror every chunk in a mirrored dbspace. As soon as the database server
allocates a mirror chunk, it flags all space in that mirror chunk as full. See
“Monitoring Disk Usage” on page 11-32.

For information on using ISA or onspaces to perform the following tasks, see
Chapter 11, “Managing Disk Space,” on page 11-1.
v Creating a dbspace
v Adding a chunk to a dbspace
v Renaming a dbspace
v Dropping a chunk
v Dropping a dbspace, blobspace, or sbspace

Root Dbspace
The root dbspace is the initial dbspace that the database server creates. The root
dbspace is special because it contains reserved pages and internal tables that
describe and track all physical and logical units of storage. (For more information
on these topics, see “Tables” on page 10-22 and the disk structures and storage
chapter in the IBM Informix Dynamic Server Administrator's Reference.) The initial
chunk of the root dbspace and its mirror are the only chunks created during
disk-space setup. You can add other chunks to the root dbspace after disk-space
setup.

The following disk-configuration parameters in the ONCONFIG configuration file

refer to the first (initial) chunk of the root dbspace:
v ROOTPATH
v ROOTOFFSET
v ROOTNAME
v MIRRORPATH
v MIRROROFFSET
v TBLTBLFIRST
v TBLTBLNEXT

The root dbspace is also the default dbspace location for any database created with
the CREATE DATABASE statement.

The root dbspace is the default location for all temporary tables created by the
database server to perform requested data management.

See “Size of the Root Dbspace” on page 10-31 for information on how much space
to allocate for the root dbspace. You can also add extra chunks to the root dbspace
after you set up database server disk space.

Temporary Dbspaces
A temporary dbspace is a dbspace reserved exclusively for the storage of
temporary tables. You cannot mirror a temporary dbspace.

Chapter 10. Data Storage 10-11

 The database server never drops a temporary dbspace unless it is explicitly
directed to do so. A temporary dbspace is temporary only in the sense that the
database server does not preserve any of the dbspace contents when the database
server shuts down abnormally.

Whenever you set up the database server, all temporary dbspaces are set up. The
database server clears any tables that might remain since the last time that the
database server shut down.

The database server does not perform logical or physical logging for temporary
dbspaces. Because temporary dbspaces are not physically logged, fewer
checkpoints and I/O operations occur, which improves performance.

The database server logs table creation, the allocation of extents, and the dropping
of the table for a temporary table in a standard dbspace. In contrast, the database
server does not log tables stored in temporary dbspaces. Logical-log suppression in
temporary dbspaces reduces the number of log records to roll forward during
logical recovery as well, thus improving the performance during critical down
time.

Using temporary dbspaces to store temporary tables also reduces the size of your
storage-space backup, because the database server does not back up temporary
dbspaces.

If you have more than one temporary dbspace and execute a SELECT statement
into a temporary table, the results of the query are inserted in round robin order.

For detailed instructions on how to create a temporary dbspace, see “Creating a

Temporary Dbspace” on page 11-15.

Important: When the database server is running as a secondary database server in

an HDR pair, it requires a temporary dbspace to store any internal
temporary tables generated by read-only queries.

Blobspaces
A blobspace is a logical storage unit composed of one or more chunks that store
only TEXT and BYTE data. A blobspace stores TEXT and BYTE data in the most
efficient way possible. You can store TEXT and BYTE columns associated with
distinct tables (see “Tables” on page 10-22) in the same blobspace.

The database server writes data stored in a blobspace directly to disk. This data
does not pass through resident shared memory. If it did, the volume of data could
occupy so many of the buffer-pool pages that other data and index pages would be
forced out. For the same reason, the database server does not write TEXT or BYTE
objects that are assigned to a blobspace to either the logical or physical log. The
database server logs blobspace objects by writing them directly from disk to the
logical-log backup tapes when you back up the logical logs. Blobspace objects
never pass through the logical-log files.

When you create a blobspace, you assign to it one or more chunks. You can add
more chunks at any time. One of the tasks of a database server administrator is to
monitor the chunks for fullness and anticipate the need to allocate more chunks to
a blobspace. For instructions on how to monitor chunks for fullness, see
“Monitoring Simple Large Objects in a Blobspace” on page 11-37. For instructions

10-12 IBM Informix Dynamic Server Administrator’s Guide

 on how to create a blobspace, add chunks to a blobspace, or drop a chunk from a
blobspace, see Chapter 11, “Managing Disk Space,” on page 11-1.

For information about the structure of a blobspace, see the chapter on disk
structures and storage in the IBM Informix Dynamic Server Administrator's Reference.

Sbspaces
An sbspace is a logical storage unit composed of one or more chunks that store
smart large objects. Smart large objects consist of CLOB (character large object) and
BLOB (binary large object) data types. User-defined data types can also use
sbspaces. For more information about data types, refer to the IBM Informix Guide to
SQL: Reference.

Advantages of Using Sbspaces

Sbspaces have the following advantages over blobspaces:
v They have read, write, and seek properties similar to a standard UNIX file.
Programmers can use functions similar to UNIX and Windows functions to read,
write, and seek smart large objects. Dynamic Server provides this
smart-large-object interface in the DataBlade API and the ESQL/C programming
interface.
v They are recoverable.
You can log all write operations on data stored in sbspaces. You can commit or
rollback changes if a failure occurs during a transaction.
v They obey transaction isolation modes.
You can lock smart large objects at different levels of granularity, and the lock
durations obey the rules for transaction isolation levels. For more information on
locking and concurrency, refer to your IBM Informix Dynamic Server Performance
Guide.
v Smart large objects within table rows do not need to be retrieved in one
statement.
An application can store or retrieve smart large objects in pieces using either the
DataBlade API or the ESQL/C programming interface. For more information on
the DataBlade API functions, refer to the IBM Informix DataBlade API Function
Reference. For more information on the ESQL/C functions, refer to the IBM
Informix ESQL/C Programmer's Manual.

Sbspaces and Enterprise Replication

Before you define a replication server for Enterprise Replication, you must create
an sbspace. Enterprise Replication spools the replicated data to smart large objects.
Specify the sbspace name in the CDR_QDATA_SBSPACE configuration parameter.
Enterprise Replication uses the default log mode with which the sbspace was
created for spooling the row data. The CDR_QDATA_SBSPACE configuration
parameter accepts multiple sbspaces, up to a maximum of 32 sbspaces. Enterprise
Replication can support a combination of logging and non-logging sbspaces for
storing spooled row data. For more information, see the IBM Informix Dynamic
Server Enterprise Replication Guide.

Metadata, User Data, and Reserved Area

As with blobspaces and dbspaces, when you create a sbspace, you assign to it one
or more chunks. However, the first chunk of an sbspace always has three areas:
v Metadata area

Chapter 10. Data Storage 10-13

 Metadata identifies key aspects of the sbspace and each smart large object stored
in the sbspace, and enables the database server to manipulate and recover smart
large objects stored within.
v User-data area
User data is the smart large object data stored in the sbspace by user
applications. The chunk has up to two user-data areas.
v Reserved area
The database server allocates space from the reserved area to either the metadata
or user-data area when more space is needed. The chunk has up to two reserved
areas.

For information on correctly allocating metadata and user data for sbspaces, see
“Sizing Sbspace Metadata” on page 11-23 and the IBM Informix Dynamic Server
Performance Guide.

When you add a chunk to an sbspace, you can specify whether it contains a
metadata area and user-data area or whether to reserve the chunk exclusively for
user data. You can add more chunks at any time. If you are updating smart large
objects, I/O to the user data is much faster on raw disks than cooked chunk files.
For instructions on how to create a sbspace, add chunks to a sbspace, or drop a
chunk from a sbspace, see Chapter 11, “Managing Disk Space,” on page 11-1.

Important: Sbspace metadata is always logged, regardless of the logging setting of

the database.

Control of Where Data Is Stored

You specify the data type of a column when you create the table. For smart large
objects, you specify CLOB, BLOB, or user-defined data types. As Figure 10-10
shows, to control the placement of smart large objects, you can use the IN sbspace
option in the PUT clause of the CREATE TABLE statement.

sbspace on UNIX
% onspaces -c -S s9_sbspc -g 4 -p./s9_sbspc -o 0 -s 2000

CREATE TABLE catalog

(...advert_descr CLOB, ...)
...PUT advert_descr IN s9_sbspc

s9_sbspc

Figure 10-10. Controlling Smart-Large-Object Placement

Before you specify an sbspace in a PUT clause, you must first create the sbspace.
For more information on how to create an sbspace with the onspaces -c -S
command, see “Adding a Chunk to a Dbspace or Blobspace” on page 11-16. For
more information on how to specify smart large object characteristics in the PUT
clause, refer to the CREATE TABLE statement in the IBM Informix Guide to SQL:
Syntax.

If you do not specify the PUT clause, the database server stores the smart large
objects in the default sbspace that you specify in the SBSPACENAME configuration

10-14 IBM Informix Dynamic Server Administrator’s Guide

 parameter. For more information on SBSPACENAME, refer to the configuration
parameter chapter of the IBM Informix Dynamic Server Administrator's Reference.

An sbspace includes one or more chunks, as Figure 10-11 shows. When an sbspace
contains more than one chunk, you cannot specify the chunk in which the data
resides.

You can add more chunks at any time. It is a high-priority task of a database
server administrator to monitor sbspace chunks for fullness and to anticipate the
need to allocate more chunks to a sbspace. For more information on monitoring
sbspaces, refer to your IBM Informix Dynamic Server Performance Guide.

Logical units of storage Physical units of storage

Chunks
Table
Dbspace 1 Chunk 1
Column Data Type
1 SERIAL
2 SMALLINT
3 INTEGER

n CLOB Sbspace 1 Chunk 1

Chunk 2

Figure 10-11. Sbspaces That Link Logical and Physical Units of Storage

The database server uses sbspaces to store table columns that contain smart large
objects. The database server uses dbspaces to store the rest of the table columns.

You can mirror an sbspace to speed recovery in event of a media failure. For more
information, refer to “Mirroring” on page 18-1.

For information on using onspaces to perform the following tasks, see Chapter 11,
“Managing Disk Space,” on page 11-1.
v Creating an sbspace
v Adding a chunk to an sbspace
v Altering storage characteristics of smart large objects
v Creating a temporary sbspace
v Dropping an sbspace

Storage Characteristics of Sbspaces

As the database server administrator, you can use the system default values for
these storage characteristics, or you can specify them in the -Df tags when you
create the sbspace with onspaces -c. Later on, you can change these sbspace

Chapter 10. Data Storage 10-15

 characteristics with the onspaces -ch option. The administrator or programmer can
override these default values for storage characteristics and attributes for
individual tables.

Extent Sizes for Sbspaces

Similar to extents in a table, an extent in an sbspace consists of a collection of
contiguous pages that store smart large object data.

The unit of allocation in an sbspace is an extent. The database server calculates the
extent size for a smart large object from a set of heuristics, such as the number of
bytes in a write operation. For example, if an operation asks to write 30 kilobytes,
the database server tries to allocate an extent the size of 30 kilobytes.

Important: For most applications, you should use the values that the database
server calculates for the extent size.

If you know the size of the smart large object, you can use one of the following
functions to set the extent size. The database server allocates the entire smart large
object as one extent (if an extent of that size is available in the chunk):
v The DataBlade API mi_lo_specset_estbytes() function
For more information on the DataBlade API functions for smart large objects,
refer to the IBM Informix DataBlade API Function Reference.
v The ESQL/C ifx_lo_specset_estbytes function
For more information on the ESQL/C functions for smart large objects, refer to
the IBM Informix ESQL/C Programmer's Manual.

For information about tuning extent sizes, see smart large objects in the chapter on
configuration effects on I/O utilization in your IBM Informix Dynamic Server
Performance Guide.

Average Smart-Large-Object Size

Smart large objects usually vary in length. You can provide an average size of your
smart large objects to calculate space for an sbspace. You specify this average size
with the AVG_LO_SIZE tag of the onspaces -c -Df option.

To specify the size and location of the metadata area, specify the -Ms and -Mo
flags in the onspaces command. If you do not use the -Ms flag, the database server
uses the value of AVG_LO_SIZE to estimate the amount of space to allocate for the
metadata area. For more information, refer to “Sizing Sbspace Metadata” on page
11-23.

Buffering Mode
When you create an sbspace, the default buffering mode is on, which means to use
the buffer pool in the resident portion of shared memory.

As the database administrator, you can specify the buffering mode with the
BUFFERING tag of the onspaces -c -Df option. The default is “buffering=ON”,
which means to use the buffer pool. If you turn off buffering, the database server
uses private buffers in the virtual portion of shared memory.

Important: In general, if read and write operations to the smart large objects are
less than 8 kilobytes, do not specify a buffering mode when you create
the sbspace. If you are reading or writing short blocks of data, such as
2 kilobytes or 4 kilobytes, leave the default of “buffering=ON” to
obtain better performance.

10-16 IBM Informix Dynamic Server Administrator’s Guide

 For information about when to use private buffers, see the section on light-weight
I/O operations in the chapter on configuration effects on I/O utilization in your
IBM Informix Dynamic Server Performance Guide.

Last-Access Time
When you create an sbspace, you can specify whether or not the database server
should keep the last time that the smart large object was read or updated with the
ACCESSTIME tag of the onspaces -c -Df option. The default is
“ACCESSTIME=OFF”. The database server keeps this last-access time in the
metadata area.

For more information on how programmers use this last-access time, refer to the
IBM Informix DataBlade API Programmer's Guide and IBM Informix ESQL/C
Programmer's Manual.

Lock Mode
When you create an sbspace, you can specify whether or not the database server
should lock the whole smart large object or a range of bytes within a smart large
object with the LOCK_MODE tag of the onspaces -c -Df option. The default is
“LOCK_MODE=BLOB”, which means to lock the entire smart large object. For
more information, refer to the locking chapter in your IBM Informix Dynamic Server
Performance Guide.

Logging
When you create an sbspace, you can specify whether or not to turn on logging for
the smart large objects. The default is no logging. For more information, refer to
“Logging Sbspaces and Smart Large Objects” on page 14-7.

Important: When you use logging databases, turn logging on for the sbspaces. If a
failure occurs that requires log recovery, you can keep the smart large
objects consistent with the rest of the database.

You specify the logging status with the LOGGING tag of the onspaces -c -Df
option. The default is “LOGGING=off”. You can change the logging status with the
onspaces -ch -Df option. You can override this logging status with the PUT clause
in the SQL statements CREATE TABLE or ALTER TABLE. For more information
about these SQL statements, refer to the IBM Informix Guide to SQL: Syntax.

The programmer can override this logging status with functions that the DataBlade
API and ESQL/C provide. For more information on the DataBlade API functions
for smart large objects, refer to the IBM Informix DataBlade API Function Reference.
For more information on the ESQL/C functions for smart large objects, refer to the
IBM Informix ESQL/C Programmer's Manual.

When you turn on logging for an sbspace, the smart large objects pass through the
resident portion of shared memory. Although applications can retrieve pieces of a
smart large object, you still need to consider the larger size of data that might pass
through the buffer pool and logical-log buffers. For more information, refer to
“Accessing Smart Large Objects” on page 8-31.

Levels of Inheritance for Sbspace Characteristics

The four levels of inheritance for sbspace characteristics are system, sbspace,
column, and smart large objects. You can use the system default values for sbspace
attributes, or override them for specific sbspaces, columns in a table, or smart large

Chapter 10. Data Storage 10-17

 objects. Figure 10-12 shows the storage-characteristics hierarchy for a smart large
object.

Database server storage characteristics

(system defaults)

System-specified
storage characteristics
Sbspace storage characteristics
when the sbspace is created with the onspaces utility or
when you change the sbspace with onspaces -ch)

Column-level storage characteristics

(assigned when the table is created with the CREATE TABLE
statement or when you change the table with the ALTER TABLE

User-specified storage characteristics

(assigned when the smart large object is created with a DataBlade API
mi_lo_create function or ESQL/C ifx_lo_create function)

Figure 10-12. Storage-Characteristics Hierarchy

Figure 10-12 shows that you can override the system default in the following ways:
v Use the -Df tags of the onspaces -c -S command to override the system default
for a specific sbspace.
You can later change these sbspace attributes for the sbspace with the onspaces
-ch option. For more information on valid ranges for the -Df tags, refer to the
onspaces section in the IBM Informix Dynamic Server Administrator's Reference.
v You override the system default for a specific column when you specify these
attributes in the PUT clause of the CREATE TABLE or ALTER TABLE
statements.
For more information on these SQL statements, refer to the IBM Informix Guide to
SQL: Syntax.
v The programmer can override the default values for sbspace attributes for
specific smart large objects with functions that the DataBlade API and ESQL/C
programming interface provide.

More Information About Sbspaces

Table 10-1 lists sources of information about various tasks related to using and
managing sbspaces.
Table 10-1. Finding Information for Sbspace Tasks
Task Reference
Setting memory configuration parameters for smart Chapter 9, “Managing Shared Memory,” on page 9-1
large objects
Understanding sbpages “Sbpages” on page 10-7
Specifying I/O characteristics for an sbspace onspaces option in “Storage Characteristics of Sbspaces” on
page 10-15

10-18 IBM Informix Dynamic Server Administrator’s Guide

Table 10-1. Finding Information for Sbspace Tasks (continued)
Task Reference
Allocating space for an sbspace “Creating an Sbspace” on page 11-22
Adding a chunk to an sbspace “Adding a Chunk to an Sbspace” on page 11-23
Defining or altering storage characteristics for a “Altering Storage Characteristics of Smart Large Objects” on
smart large object page 11-24

PUT clause of CREATE TABLE or ALTER TABLE statement in

IBM Informix Guide to SQL: Syntax
Monitoring sbspaces “Monitoring Sbspaces” on page 11-39
Chapter on table performance considerations in IBM Informix
Dynamic Server Performance Guide
Setting up logging for an sbspace “Logging Sbspaces and Smart Large Objects” on page 14-7
Backing up an sbspace “Backing Up Sbspaces” on page 15-4
Checking consistency of an sbspace “Validating Metadata” on page 22-3
Understanding an sbspace structure Chapter on disk structures in the IBM Informix Administrator's
Reference
Using onspaces for sbspaces Chapter on utilities in the IBM Informix Administrator's
Reference
Creating a table with CLOB or BLOB data types IBM Informix Guide to SQL: Syntax
Accessing smart large objects in an application IBM Informix DataBlade API Programmer's GuideIBM Informix
ESQL/C Programmer's Manual
Calculating the metadata area size Chapter on table performance in IBM Informix Dynamic Server
Performance Guide
Improving metadata I/O

Changing storage characteristics

Understanding smart-large-object locking Chapter on locking in IBM Informix Dynamic Server Performance
Guide
Configuring sbspaces for temporary smart large Chapter on configuration effects on I/O activity in IBM
objects Informix Dynamic Server Performance Guide

Temporary Sbspaces
Use a temporary sbspace to store temporary smart large objects without metadata
logging and user-data logging. If you store temporary smart large objects in a
standard sbspace, the metadata is logged. Temporary sbspaces are similar to
temporary dbspaces. To create a temporary sbspace, use the onspaces -c -S
command with the -t option. For more information, see “Creating a Temporary
Sbspace” on page 11-25.

You can store temporary large objects in a standard sbspace or temporary sbspace.
v If you specify a temporary sbspace in the SBSPACETEMP parameter, you can
store temporary smart large objects there.
v If you specify a standard sbspace in the SBSPACENAME parameter, you can
store temporary and permanent smart large objects there.
v If you specify a temporary sbspace name in the CREATE TEMP TABLE
statement, you can store temporary smart large objects there.
v If you specify a permanent sbspace name in the CREATE TABLE statement, you
can store temporary smart large objects there.

Chapter 10. Data Storage 10-19

 v If you omit the SBSPACETEMP and SBSPACENAME parameters and create a
smart large object, error message -12053 might display.
v If you specify a temporary sbspace in the SBSPACENAME parameter, you
cannot store a permanent smart large object in that sbspace. You can store
temporary smart large objects in that sbspace.

Comparison of Temporary and Standard Sbspaces

Table 10-2 compares standard and temporary sbspaces.
Table 10-2. Temporary and Standard Sbspaces
Characteristics Standard Sbspace Temporary Sbspace
Stores smart large objects Yes No
Stores temporary smart large Yes Yes
objects
Logs metadata Metadata is always logged Metadata is not logged
Logs user data User data is not logged for temporary User data is not logged
smart large objects but is logged for
permanent smart large objects if Creation and deletion of space, and
LOGGING=ON addition of chunks is logged
Fast recovery Yes No (the sbspace is emptied when the
database server restarts) To set up shared
memory without cleaning up temporary
smart large objects, specify oninit -p. If
you keep the temporary large objects, their
state is indeterminate.
Backup and restore Yes No
Add and drop chunks Yes Yes
Configuration parameter SBSPACENAME SBSPACETEMP

Temporary Smart Large Objects

Use temporary smart large objects to store text or image data (CLOB or BLOB) that
do not require restoring from a backup or log replay in fast recovery. Temporary
smart large objects last for the user session and are much faster to update than
smart large objects.

You create a temporary smart large object in the same way as a permanent smart
large object, except you set the LO_CREATE_TEMP flag in the ifx_lo_specset_flags
or mi_lo_specset_flags function. Use mi_lo_copy or ifx_lo_copy to create a
permanent smart large object from a temporary smart large object. For details on
creating temporary smart large objects, see the IBM Informix DataBlade API
Programmer's Guide.

Important: Store pointers to temporary large objects in temporary tables only. If

you store them in standard tables and reboot the database server, it
results in an error that says that the large object does not exist.

10-20 IBM Informix Dynamic Server Administrator’s Guide

 Table 10-3 compares standard and temporary smart large objects.
Table 10-3. Temporary and Standard Smart Large Objects
Characteristics Smart Large Object Temporary Smart Large Object
Creation flags LO_CREATE_LOG or LO_CREATE_TEMP
LO_CREATE_NOLOG
Rollback Yes No
Logging Yes, if turned on No
Duration Permanent (until user deletes it) Deleted at end of user session or
transaction
Table type stored in Permanent or temporary table Temporary tables

Extspaces
An extspace is a logical name associated with an arbitrary string that signifies the
location of external data. The resource that the extspace references depends on a
user-defined access method for accessing its contents.

For example, a database user might require access to binary files encoded in a
proprietary format. First, a developer creates an access method, which is a set of
routines that access the data. These routines are responsible for all interaction
between the database server and the external file. A DBA then adds an extspace
that has the file as its target to the database. After the DBA creates a table in the
extspace, the users can access the data in the proprietary files via SQL statements.
To locate those files, use the extspace information.

An extspace need not be a filename. For example, it can be a network location. The
routines that access the data can use information found in the string associated
with the extspace in any manner.

For more information on user-defined access methods, see the IBM Informix
Virtual-Table Interface Programmer's Guide. For more information on creating
functions and primary access methods, see the IBM Informix Guide to SQL: Syntax.

Databases
A database is a logical storage unit that contains tables and indexes. (See “Tables”
on page 10-22.) Each database also contains a system catalog that tracks
information about many of the elements in the database, including tables, indexes,
SPL routines, and integrity constraints.

A database resides in the dbspace specified by the CREATE DATABASE statement.

When you do not explicitly name a dbspace in the CREATE DATABASE statement,
the database resides in the root dbspace. When you do specify a dbspace in the
CREATE DATABASE statement, this dbspace is the location for the following
tables:
v Database system catalog tables
v Any table that belongs to the database

Figure 10-13 shows the tables contained in the stores_demo database.

Chapter 10. Data Storage 10-21

 stores_demo database

customer orders items stock catalog

table table table table table

cust_calls call_type manufact state

table table table table

system catalog zip_ix

index
systables sysviews
table table

Figure 10-13. The stores_demo Database

The size limits that apply to databases are related to their location in a dbspace. To
be certain that all tables in a database are created on a specific physical device,
assign only one chunk to the device, and create a dbspace that contains only that
chunk. Place your database in that dbspace. When you place a database in a chunk
assigned to a specific physical device, the database size is limited to the size of that
chunk.

For instructions on how to list the databases that you create, see “Displaying
Databases” on page 11-32.

Tables
In relational database systems, a table is a row of column headings together with
zero or more rows of data values. The row of column headings identifies one or
more columns and a data type for each column.

When you create a table, the database server allocates disk space for the table in a
block of pages called an extent. (See “Extents” on page 10-8.) You can specify the
size of both the first and any subsequent extents.

You can place the table in a specific dbspace by naming the dbspace when they
create the table (usually with the IN dbspace option of CREATE TABLE). When you
do not specify the dbspace, the database server places the table in the dbspace
where the database resides.

You can also:

v Fragment a table over more than one dbspace. However, you cannot put
fragments into different page-size dbspaces. All fragments might need to be the
same page size.
You must define a distribution scheme for the table that specifies which table
rows are located in which dbspaces.
v Create multiple partitions of a fragmented table within a single dbspace if the
fragmented tables uses an expression-based or round-robin distribution scheme.

10-22 IBM Informix Dynamic Server Administrator’s Guide

 A table or table fragment resides completely in the dbspace in which it was
created. The database server administrator can use this fact to limit the growth of a
table by placing a table in a dbspace and then refusing to add a chunk to the
dbspace when it becomes full.

For more information about distribution schemes, see the IBM Informix Database
Design and Implementation Guide. For information on how to fragment tables and
indexes over multiple disks to improve performance, concurrency, data availability,
and backups, refer to your IBM Informix Dynamic Server Performance Guide.

A table, composed of extents, can span multiple chunks, as Figure 10-14 shows.

Chunk 1 Chunk 2

Extent 1 Extent 2

Two extents, both allocated

to the same table

Figure 10-14. Table That Spans More Than One Chunk

Simple large objects reside in blobpages in either the dbspace with the data pages
of the table or in a separate blobspace. When you use the Optical Subsystem, you
can also store simple large objects in an optical storage subsystem.

For advice on where to store your tables, see “Disk-Layout Guidelines” on page
10-33 and your IBM Informix Dynamic Server Performance Guide.

Table Types for Dynamic Server

You can create logging or nonlogging tables in a logging database on Dynamic
Server. The two table types are STANDARD (logging tables) and RAW (nonlogging
tables). The default standard table is like a table created in earlier versions without
a special keyword specified. You can create either a STANDARD or RAW table and
change tables from one type to another.

In a nonlogging database, both STANDARD tables and RAW tables are

nonlogging. In a nonlogging database, the only difference between STANDARD
and RAW tables is that RAW tables do not allow indexes and referential
constraints.

Table 10-4 lists the properties of the types of tables available with Dynamic Server.
The flag values are the hexadecimal values for each table type in the flags column
of systables.

Chapter 10. Data Storage 10-23

 Table 10-4. Table Types for Dynamic Server
Characteristic STANDARD RAW TEMP
Permanent Yes Yes No
Logged Yes No Yes
Indexes Yes No Yes
Rollback Yes No Yes
Recoverable Yes Yes, if not updated No
Restorable Yes Yes, if not updated No
Loadable Yes Yes Yes
Enterprise Replication Yes No No
Flag Value None 0x10 None

Standard Permanent Tables

A STANDARD table is the same as a table in a logged database that the database
server creates. STANDARD tables do not use light appends. All operations are
logged, record by record, so STANDARD tables can be recovered and rolled back.
You can back up and restore STANDARD tables. Logging enables updates since
the last physical backup to be applied when you perform a warm restore or
point-in-time restore. Enterprise Replication is allowed on STANDARD tables.

A STANDARD table is the default type on both logging and nonlogging databases.
STANDARD tables are logged if stored in a logging database but are not logged if
stored in a nonlogging database.

RAW Tables
RAW tables are nonlogging permanent tables and are similar to tables in a
nonlogging database. RAW tables use light appends, which add rows quickly to the
end of each table fragments. Updates, inserts, and deletes in a RAW table are
supported but not logged. RAW tables do not support indexes, referential
constraints, or rollback. You can restore a RAW table from the last physical backup
if it has not been updated since that backup. Fast recovery rolls back incomplete
transactions on STANDARD tables but not on RAW tables. A RAW table has the
same attributes whether stored in a logging or nonlogging database.

RAW tables are intended for the initial loading and validation of data. To load
RAW tables, you can use any loading utility, including dbexport or the
High-Performance Loader (HPL) in express mode. If an error or failure occurs
while loading a RAW table, the resulting data is whatever was on the disk at the
time of the failure.

Recommendation: Do not use RAW tables within a transaction. After you have
loaded the data, use the ALTER TABLE statement to change the table to type
STANDARD and perform a level-0 backup before you use the table in a
transaction.

Warning: Do not use Enterprise Replication on RAW or TEMP tables.

Temp Tables
Temp tables are temporary, logged tables that are dropped when the user session
closes, the database server shuts down, or on reboot after a failure. Temp tables

10-24 IBM Informix Dynamic Server Administrator’s Guide

 support indexes, constraints, and rollback. You cannot recover, back up, or restore
temp tables. Temp tables support bulk operations such as light appends, which
add rows quickly to the end of each table fragment. For more information about
light appends, refer to your IBM Informix Dynamic Server Performance Guide.

For more information, see “Temporary Tables” on page 10-26.

Properties of Table Types

This section discusses loading tables, fast recovery, and backup and restore of table
types.

Loading of Data Into a Table

Dynamic Server creates STANDARD tables that use logging by default. Data
warehousing applications can have huge tables that take a long time to load.
Nonlogging tables are faster to load than logging tables. You can use the CREATE
RAW TABLE statement to create a RAW table or use the ALTER TABLE statement
to change a STANDARD table to RAW before loading the table. After you load the
table, run UPDATE STATISTICS on it.

For more information about how to improve the performance of loading very large
tables, see your IBM Informix Dynamic Server Performance Guide. For more
information on using ALTER TABLE to change a table from logging to nonlogging,
see the IBM Informix Guide to SQL: Syntax.

Fast Recovery of Table Types

Table 10-5 shows fast recovery scenarios for the table types available with Dynamic
Server.
Table 10-5. Fast Recovery of Table Types
Table Type Fast Recovery Behavior
Standard Fast recovery is successful. All committed log records are rolled forward, and
all incomplete transactions are rolled back.
RAW If a checkpoint completed since the raw table was modified last, all the data is
recoverable.

Inserts, updates, and deletions that occurred after the last checkpoint are lost.

Incomplete transactions in a RAW table are not rolled back.

Backup and Restore of RAW Tables

Table 10-6 discusses backup scenarios for the table types available on Dynamic
Server.
Table 10-6. Backing Up Tables on Dynamic Server
Table Type Backup Allowed?
Standard Yes.
Temp No.
RAW Yes. If you update a RAW table, you must back it up so that you can restore
all the data in it. Backing up only the logical logs is not enough.

Important: After you load a RAW table or change a RAW table to type
STANDARD, you must perform a level-0 backup.

Chapter 10. Data Storage 10-25

 Table 10-7 shows restore scenarios for these table types.
Table 10-7. Restoring Tables on Dynamic Server
Table Type Restore Allowed?
Standard Yes. Warm restore, cold restore, and point-in-time restore work.
Temp No.
RAW When you restore a RAW table, it contains only data that was on disk at the
time of the last backup. Because RAW tables are not logged, any changes that
occurred since the last backup are not restored.

Temporary Tables
The database server needs to provide disk space for temporary tables of the
following two kinds:
v Temporary tables that you create with an SQL statement, such as CREATE
TEMP TABLE... or SELECT .... INTO SCRATCH
v Temporary tables that the database server creates as it processes a query

Make sure that your database server has configured enough temporary space for
both user-created and database server-created temporary tables. Some uses of the
database server might require as much temporary storage space as permanent
storage space, or more.

By default, the database server stores temporary tables in the root dbspace. If you
decide not to store your temporary tables in the root dbspace, use the
DBSPACETEMP environment variable or the DBSPACETEMP configuration
parameter to specify a list of dbspaces for temporary tables.

Temporary Tables That You Create

You can create temporary tables with any of the following SQL statements:
v TEMP TABLE option of the CREATE TABLE statement
v INTO TEMP clause of the SELECT statement, such as SELECT * FROM customer
INTO TEMP cust_temp

Only the session that creates a temporary table can use the table. When the session
exits, the table is dropped automatically.

When you create a temporary table, the database server uses the following criteria:
v If the query used to populate the TEMP table produces no rows, the database
server creates an empty, unfragmented table.
v If the rows that the query produces do not exceed 8 kilobytes, the temporary
table resides in only one dbspace.
v If the rows exceed 8 kilobytes, the database server creates multiple fragments
and uses a round-robin fragmentation scheme to populate them unless you
specify a fragmentation method and location for the table.

If you use the CREATE TEMP and SELECT...INTO TEMP SQL statements and
DBSPACETEMP has been set:
v LOGGING dbspaces in the list are used to create the tables that specify or imply
the WITH LOG clause.
v NON-LOGGING temporary dbspaces in the list are used to create the tables that
specify the WITH NO LOG clause.

10-26 IBM Informix Dynamic Server Administrator’s Guide

When CREATE TEMP and SELECT...INTO TEMP SQL statements are used and
DBSPACETEMP has not been set or does not contain the correct type of dbspace,
Dynamic Server uses the dbspace of the database to store the temporary table. See
the IBM Informix Guide to SQL: Syntax for more information.

Where User-Created Temporary Tables are Stored: If your application lets you
specify the location of a temporary table, you can specify either logging spaces or
nonlogging spaces that you create exclusively for temporary tables. SCRATCH
tables are not logged and must be created in temporary spaces.

For information about creating temporary dbspaces and dbslices, refer to the
onspaces section in t.

If you do not specify the location of a temporary table, the database server stores
the temporary table in one of the spaces that you specify as an argument to the
DBSPACETEMP configuration parameter or environment variable. The database
server keeps track of the name of the last dbspace that it used for a temporary
table. When the database server receives another request for temporary storage
space, it uses the next available dbspace to spread I/O evenly across the temporary
storage space.

For information about where the database stores temporary tables when you do
not list any spaces as an argument to DBSPACETEMP, see the DBSPACETEMP
section in the IBM Informix Administrator's Reference.

When you use an application to create a temporary table, you can use the
temporary table until the application exits or performs one of the following
actions:
v Closes the database in which the table was created and opens a database in a
different database server
v Closes the database in which the table was created
v Explicitly drops the temporary table

Temporary Tables That the Database Server Creates

The database server sometimes creates temporary tables while running queries
against the database or backing it up. The database server might create a
temporary table in any of the following circumstances:
v Statements that include a GROUP BY or ORDER BY clause
v Statements that use aggregate functions with the UNIQUE or DISTINCT
keywords
v SELECT statements that use auto-index or hash joins
v Complex CREATE VIEW statements
v DECLARE statements that create a scroll cursor
v Statements that contain correlated subqueries
v Statements that contain subqueries that occur within an IN or ANY clause
v CREATE INDEX statements

When the process that initiated the creation of the table is complete, the database
server deletes the temporary tables that it creates.

Chapter 10. Data Storage 10-27

 If the database server shuts down without removing temporary tables, it performs
temporary table cleanup the next time shared-memory is set up. To initialize
shared memory without temporary table cleanup, execute oninit with the -p
option.

Important: In addition to temporary tables, the database server uses temporary

disk space to store the before images of data that are overwritten while
backups are occurring and overflow from query processing that occurs
in memory. Make sure that you have configured enough temporary
space for all uses.

Where Database Server-Created Temporary Tables are Stored: When the

database server creates a temporary table, it stores the temporary table in one of
the dbspaces that you specify in the DBSPACETEMP configuration parameter or
the DBSPACETEMP environment variable. The environment variable supersedes
the configuration parameter.

When you do not specify any temporary dbspaces in DBSPACETEMP, or the

temporary dbspaces that you specify have insufficient space, the database server
creates the table in a standard dbspace according to the following rules:
v If you created the temporary table with CREATE TEMP TABLE, the database
server stores this table in the dbspace that contains the database to which the
table belongs.
v If you created the temporary table with the INTO TEMP option of the SELECT
statement, the database server stores this table in the root dbspace.

For more information, see “Creating a Temporary Dbspace” on page 11-15.

Tblspaces
Database server administrators sometimes need to track disk use by a particular
table. A tblspace contains all the disk space allocated to a given table or table
fragment (if the table is fragmented). A separate tblspace contains the disk space
allocated for the associated index.

A tblspace, for example, does not correspond to any particular part of a chunk or
even to any particular chunk. The indexes and data that make up a tblspace might
be scattered throughout your chunks. The tblspace, however, represents a
convenient accounting entity for space across chunks devoted to a particular table.
(See “Tables” on page 10-22.)

Maximum Number of Tblspaces in a Table

You can specify a maximum of 2**20 (or 1,048,576) tblspaces in a table.

Table and Index Tblspaces

The table tblspace contains the following types of pages:
v Pages allocated to data
v Pages allocated to indexes
v Pages used to store TEXT or BYTE data in the dbspace (but not pages used to
store TEXT or BYTE data in a blobspace)
v Bitmap pages that track page use within the table extents

The index tblspace contains the following types of pages:

10-28 IBM Informix Dynamic Server Administrator’s Guide

 v Pages allocated to indexes
v Bitmap pages that track page use within the index extents

Figure 10-15 illustrates the tblspaces for three tables that form part of the
stores_demo database. Only one table (or table fragment) exists per tblspace. An
index resides in a separate tblspace from the associated table. Blobpages represent
TEXT or BYTE data stored in a dbspace.

stores_demo Database
customer catalog orders
data tblspace data tblspace data tblspace
Data Data Data Data Data Data Data Data Data
page page page page page page page page page
Data Data Data Data Data Data Data Data Data
page page page page page page page page page
Data Data Data Data Data Data Data Data Data
page page page page page page page page page
Bitmap Blob- Blob- Blob- Index Index Bitmap
page page page page page page page
Blob- Blob- Bitmap Index
page page page page

customer catalog orders

index tblspace index tblspace index tblspace

Index Index Bitmap Index Index Index Index Index Index

page page page page page page page page page
Index Index Bitmap Bitmap
page page page page

Figure 10-15. Sample Tblspaces in the stores_demo Database

Extent Interleaving
The database server allocates the pages that belong to a tblspace as extents.
Although the pages within an extent are contiguous, extents might be scattered
throughout the dbspace where the table resides (even on different chunks).

Figure 10-16 depicts this situation with two noncontiguous extents that belong to
the tblspace for table_1 and a third extent that belongs to the tblspace for table_2.
A table_2 extent is positioned between the first table_1 extent and the second
table_1 extent. When this situation occurs, the extents are interleaved. Because
sequential access searches across table_1 require the disk head to seek across the
table_2 extent, performance is worse than if the table_1 extents were contiguous.
For instructions on how to avoid and eliminate interleaving extents, see your IBM
Informix Dynamic Server Performance Guide.

Chapter 10. Data Storage 10-29

 Page

Table_1 Extent Table_2 Extent Table_1 Extent

Figure 10-16. Three Extents That Belong to Two Different Tblspaces in a Single Dbspace

Table Fragmentation and Data Storage

The fragmentation feature gives you additional control over where the database
stores data. You are not limited to specifying the locations of individual tables and
indexes. You can also specify the location of table and index fragments, which are
different parts of a table or index that reside on different storage spaces. You can
fragment the following storage spaces:
v Dbspaces
v Sbspaces

Usually you fragment a table when you initially create it. The CREATE TABLE
statement takes one of the following forms:
CREATE TABLE tablename ... FRAGMENT BY ROUND ROBIN IN dbspace1,
dbspace2, dbspace3;

CREATE TABLE tablename ...FRAGMENT BY EXPRESSION

<Expression 1> in dbspace1,
<Expression 2> in dbspace2,
<Expression 3> in dbspace3;

The FRAGMENT BY ROUND ROBIN and FRAGMENT BY EXPRESSION

keywords refer to two different distribution schemes. Both statements associate
fragments with dbspaces.

When you fragment a table, you can also create multiple partitions of the table
within the same dbspace, as shown in this example:
CREATE TABLE tb1(a int)
FRAGMENT BY EXPRESSION
PARTITION part1 (a >=0 AND a < 5) in dbs1,
PARTITION part2 (a >=5 AND a < 10) in dbs1
...
;

Figure 10-17 illustrates the role of fragments in specifying the location of data.

10-30 IBM Informix Dynamic Server Administrator’s Guide

 Logical units of storage Physical units of storage
Chunks
Database
System catalog

Dbspace 1 Chunk 1

Table 1

Dbspace 2 Chunk 2

Table 2

Fragment 1
Dbspace 3 Chunk 3

Fragment 2

Fragment 3

Figure 10-17. Dbspaces That Link Logical Units (Including Table Fragments) and Physical
Units of Storage

For information on spaces and partitions, see Chapter 11, “Managing Disk Space,”
on page 11-1.

For more information about fragmentation, refer to the IBM Informix Database
Design and Implementation Guide and the IBM Informix Dynamic Server Performance
Guide.

Amount of Disk Space Needed to Store Data

To determine how much disk space you need, follow these steps:

To determine how much disk space you need:

1. Calculate the size requirements of the root dbspace.
2. Estimate the total amount of disk space to allocate to all the database server
databases, including space for overhead and growth.

The following sections explain these steps.

Size of the Root Dbspace

To calculate the size of the root dbspace, take the following storage structures into
account:
v The physical log (200 kilobytes minimum)
v The logical-log files (200 kilobytes minimum)
v Temporary tables
v Data

Chapter 10. Data Storage 10-31

 v System databases (sysmaster, sysutils, syscdr, sysuuid) and system catalogs (the
size varies between versions)
v Reserved pages (~24 kilobytes)
v Tablespace tablespace (100 to 200 kilobytes minimum)
v Extra space

This estimate is the initial root dbspace size before you initialize the database
server. The initial size of the root dbspace depends on whether you plan to store
the physical log, logical logs, and temporary tables in the root dbspace or in
another dbspace. The root dbspace must be large enough for the minimum size
configuration during disk initialization.

Recommendation: Set up the system with a small log size (for example, three
1000-kilobyte log files, or 3000 kilobytes for the total log size). After setup is
complete, create new dbspaces, move and resize the logical-log files, and drop the
original logs in the root dbspace. Then move the physical log to another dbspace.
This procedure minimizes the impact of the logs in the root dbspace because:
v A large amount of space is not left unused in the root dbspace after you move
the logs (if your root dbspace does not grow).
v The logs do not contend for space and I/O on the same disk as the root dbspace
(if your root dbspace does grow).

For details on how to move the logs, see “Moving a Logical-Log File to Another
Dbspace” on page 15-12 and “Changing the Physical-Log Location and Size” on
page 17-1.

You can add chunks and drop empty chunks in the root dbspace. Start with a
small root dbspace and expand it as your system grows. However, you cannot start
with a large initial root chunk and shrink it.

Physical and Logical Logs

The value stored in the ONCONFIG parameter PHYSFILE defines the size of your
physical log. Advice on sizing your physical log is contained in “Size and Location
of the Physical Log” on page 16-4.

To calculate the size of the logical-log files, multiply the value of the ONCONFIG
parameter LOGSIZE by the number of logical-log files. For advice on sizing your
logical log, see “Estimating the Size and Number of Log Files” on page 15-2.

Temporary Tables
Analyze end-user applications to estimate the amount of disk space that the
database server might require for temporary tables. Try to estimate how many of
these statements are to run concurrently. The space occupied by the rows and
columns that are returned provides a good basis for estimating the amount of
space required.

The largest temporary table that the database server creates during a warm restore
is equal to the size of your logical log. You calculate the size of your logical log by
adding the sizes of all logical-log files.

You must also analyze end-user applications to estimate the amount of disk space
that the database server might require for explicit temporary tables.

For more information, including a list of statements that require temporary space,
see “Temporary Tables” on page 10-26.

10-32 IBM Informix Dynamic Server Administrator’s Guide

 Critical Data
Recommendation: Do not store databases and tables in the root dbspace. Mirror
the root dbspace and other dbspaces that contain critical data such as the physical
log and logical logs. Estimate the amount of disk space, if any, that you need to
allocate for tables stored in the root dbspace.

Extra Space
Allow extra space in the root dbspace for the system databases to grow, for the
extended reserved pages, and ample free space. The number of extended reserved
pages depends on the number of primary chunks, mirror chunks, logical-log files,
and storage spaces in the database server.

Amount of Space That Databases Require

The amount of additional disk space required for the database server data storage
depends on the needs of your end users, plus overhead and growth. Every
application that your end users run has different storage requirements. The
following list suggests some of the steps that you can take to calculate the amount
of disk space to allocate (beyond the root dbspace):
v Decide how many databases and tables you need to store. Calculate the amount
of space required for each one.
v Calculate a growth rate for each table and assign some amount of disk space to
each table to accommodate growth.
v Decide which databases and tables you want to mirror.

For instructions about calculating the size of your tables, refer to your IBM Informix
Dynamic Server Performance Guide.

Disk-Layout Guidelines
The following are typical goals for efficient disk layout:
v Limiting disk-head movement
v Reducing disk contention
v Balancing the load
v Maximizing availability

You must make some trade-offs among these goals when you design your disk
layout. For example, separating the system catalog tables, the logical log, and the
physical log can help reduce contention for these resources. However, this action
can also increase the chances that you have to perform a system restore. For
detailed disk-layout guidelines, see the IBM Informix Dynamic Server Performance
Guide.

Dbspace and Chunk Guidelines

This section lists some general strategies for disk layout that do not require any
information about the characteristics of a particular database:
v Associate disk partitions with chunks and allocate at least one additional chunk
for the root dbspace.
A disk that is already partitioned might require the use of offsets. For details, see
“Allocating Raw Disk Space on UNIX” on page 11-5.

Tip: With the 4-terabyte maximum size of a chunk, you can avoid partitioning
by assigning a chunk per disk drive.

Chapter 10. Data Storage 10-33

 v Mirror critical dbspaces: the root dbspace, the dbspaces that contain the physical
log and the logical-log files. Also mirror high-use databases and tables.
You specify mirroring at the dbspace level. Mirroring is either on or off for all
chunks belonging to a dbspace. Locate the primary and the mirrored dbspaces
on different disks. Ideally, different controllers handle the different disks.
v Spread temporary tables and sort files across multiple disks.
To define several dbspaces for temporary tables and sort files, use onspaces -t.
When you place these dbspaces on different disks and list them in the
DBSPACETEMP configuration parameter, you can spread the I/O associated
with temporary tables and sort files across multiple disks. For information on
using the DBSPACETEMP configuration parameter or environment variable, see
the chapter on configuration parameters in the IBM Informix Administrator's
Reference.
v Keep the physical log in the root dbspace but move the logical logs from the
root dbspace. However, if you plan to store the system catalogs in the root
dbspace, move the physical log to another dbspace.
For advice on where to store your logs, see “Specifying the Location of the
Physical Log” on page 16-4 and “Location of Logical-Log Files” on page 14-2.
Also see “Moving a Logical-Log File to Another Dbspace” on page 15-12 and
“Changing the Physical-Log Location and Size” on page 17-1.
v To improve backup and restore performance:
– Cluster system catalogs with the data that they track.
– If you use ON–Bar to perform parallel backups to a high-speed tape drive,
store the databases in several small dbspaces.
For additional performance recommendations, see the IBM Informix Backup
and Restore Guide.

Table-Location Guidelines
This section lists some strategies for optimizing the disk layout, given certain
characteristics about the tables in a database. You can implement many of these
strategies with a higher degree of control using table fragmentation:
v Isolate high-use tables on a separate disk.
To isolate a high-use table on its own disk device, assign the device to a chunk,
and assign the same chunk to a dbspace. Finally, place the frequently used table
in the dbspace just created using the IN dbspace option of CREATE TABLE.
To display the level of I/O operations against each chunk, run the onstat -g iof
option.
v Fragment high-use tables over multiple disks.
v Group related tables in a dbspace.
If a device that contains a dbspace fails, all tables in that dbspace are
inaccessible. However, tables in other dbspaces remain accessible. Although you
must perform a cold restore if a dbspace that contains critical information fails,
you need only perform a warm restore if a noncritical dbspace fails.
v Place high-use tables on the middle partition of a disk.
v Optimize table extent sizes.

For more information, see the chapter on table performance considerations in your
IBM Informix Performance Guide. For information on onstat options, see the IBM
Informix Administrator's Reference.

10-34 IBM Informix Dynamic Server Administrator’s Guide

Sample Disk Layouts
When setting out to organize disk space, the database server administrator usually
has one or more of the following objectives in mind:
v High performance
v High availability
v Ease and frequency of backup and restore

Meeting any one of these objectives has trade-offs. For example, configuring your
system for high performance usually results in taking risks regarding the
availability of data. The sections that follow present an example in which the
database server administrator must make disk-layout choices given limited disk
resources. These sections describe two different disk-layout solutions. The first
solution represents a performance optimization, and the second solution represents
an availability-and-restore optimization.

The setting for the sample disk layouts is a fictitious sporting goods database that
uses the structure (but not the volume) of the stores_demo database. In this
example, the database server is configured to handle approximately 350 users and
3 gigabytes of data. The disk space resources are shown in the following table.

Disk Drive Size of Drive High Performance

Disk 1 2.5 gigabytes No
Disk 2 3 gigabytes Yes
Disk 3 2 gigabytes Yes
Disk 4 1.5 gigabytes No

The database includes two large tables: cust_calls and items. Assume that both of
these tables contain more than 1,000,000 rows. The cust_calls table represents a
record of all customer calls made to the distributor. The items table contains a line
item of every order that the distributor ever shipped.

The database includes two high-use tables: items and orders. Both of these tables
are subject to constant access from users around the country.

The remaining tables are low-volume tables that the database server uses to look
up data such as postal code or manufacturer.

Table Name Maximum Size Access Rate

cust_calls 2.5 gigabytes Low
items 0.5 gigabytes High
orders 50 megabytes High
customers 50 megabytes Low
stock 50 megabytes Low
catalog 50 megabytes Low
manufact 50 megabytes Low
state 50 megabytes Low
call_type 50 megabytes Low

Chapter 10. Data Storage 10-35

 Sample Layout When Performance Is Highest Priority
Figure 10-18 on page 10-36 shows a disk layout optimized for performance. This
disk layout uses the following strategies to improve performance:
v Migration of the logical log from the rootdbs dbspace to a dbspace on a separate
disk
This strategy separates the logical log and the physical log and reduces
contention for the root dbspace.
v Location of the two tables that undergo the highest use in dbspaces on separate
disks
Neither of these disks stores the logical log or the physical log. Ideally you could
store each of the items and orders tables on a separate high-performance disk.
However, in the present scenario, this strategy is not possible because one of the
high-performance disks is needed to store the very large cust_calls table (the
other two disks are too small for this task).

Disks
Database rootdbs

phys_log_space
Disk 1
(2.5 gigabyte)

cust_calls
cust_calls_space

log_log_space
Disk 2
(3 gigabyte, high
items performance)

items_space

stock catalog manufact

look_up2

state call_type customer Disk 3

look_up3 (2 gigabyte, high
performance)

orders
orders_space
Disk 4
(1.5 gigabyte)

Figure 10-18. Disk Layout Optimized for Performance

Sample Layout When Availability Is Highest Priority

The weakness of the previous disk layout is that if either Disk 1 or Disk 2 fails, the
whole database server goes down until you restore the dbspaces on these disks
from backups. In other words, the disk layout is poor with respect to availability.

10-36 IBM Informix Dynamic Server Administrator’s Guide

 An alternative disk layout that optimizes for availability and involves mirroring is
shown in Figure 10-19 on page 10-37. This layout mirrors all the critical data spaces
(the system catalog tables, the physical log, and the logical log) to a separate disk.
Ideally you could separate the logical log and physical log (as in the previous
layout) and mirror each disk to its own mirror disk. However, in this scenario, the
required number of disks does not exist; therefore, the logical log and the physical
log both reside in the root dbspace.

Database Disks
stock catalog manufact
look_up1

Disk 1
rootdbs (2.5 gigabyte)

phys_log_space

log_log_space
state call_type customer
Disk 4
look_up2 (1.5 gigabyte)

cust_calls

cust_calls_space

orders
orders_space
Disk 2
(3 gigabyte, high
performance)
items

items_space

Disk 3
(2 gigabyte, high
performance)

Figure 10-19. Disk Layout Optimized for Availability

Logical-Volume Manager
A logical-volume manager (LVM) is a utility that allows you to manage your disk
space through user-defined logical volumes.

Many computer manufacturers ship their computers with a proprietary LVM. You
can use the database server to store and retrieve data on disks that are managed
by most proprietary LVMs. Logical-volume managers provide some advantages
and some disadvantages, as discussed in the remainder of this section.

Most LVMs can manage multiple gigabytes of disk space. The database server
chunks are limited to a size of 4 terabytes, and this size can be attained only when

Chapter 10. Data Storage 10-37

 the chunk being allocated has an offset of zero. Consequently, you should limit the
size of any volumes to be allocated as chunks to a size of 4 terabytes.

Because LVMs allow you to partition a disk drive into multiple volumes, you can
control where data is placed on a given disk. You can improve performance by
defining a volume that consists of the middle-most cylinders of a disk drive and
placing high-use tables in that volume. (Technically, you do not place a table
directly in a volume. You must first allocate a chunk as a volume, then assign the
chunk to a dbspace, and finally place the table in the dbspace. For more
information, see “Control of Where Data Is Stored” on page 10-9.)

Tip: If you choose to use large disk drives, you can assign a chunk to one drive
and eliminate the need to partition the disk.

You can also improve performance by using a logical volume manager to define a
volume that spreads across multiple disks and then placing a table in that volume.

Many logical volume managers also allow a degree of flexibility that standard
operating-system format utilities do not. One such feature is the ability to
reposition logical volumes after you define them. Thus getting the layout of your
disk space right the first time is not so critical as with operating-system format
utilities.

LVMs often provide operating-system-level mirroring facilities. For more

information, see “Alternatives to Mirroring” on page 18-3.

10-38 IBM Informix Dynamic Server Administrator’s Guide

Chapter 11. Managing Disk Space
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2
Allocating Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Specifying an Offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3
Specifying an Offset for the Initial Chunk of Root Dbspace . . . . . . . . . . . . . . . . . 11-4
Specifying an Offset for Additional Chunks . . . . . . . . . . . . . . . . . . . . . . 11-4
Using Offsets to Create Multiple Chunks . . . . . . . . . . . . . . . . . . . . . . . 11-4
Allocating Cooked File Spaces on UNIX . . . . . . . . . . . . . . . . . . . . . . . . 11-4
Allocating Raw Disk Space on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . 11-5
Creating Symbolic Links to Raw Devices (UNIX) . . . . . . . . . . . . . . . . . . . . . 11-5
Allocating NTFS File Space on Windows . . . . . . . . . . . . . . . . . . . . . . . . 11-6
Allocating Raw Disk Space on Windows . . . . . . . . . . . . . . . . . . . . . . . . 11-6
Specifying Names for Storage Spaces and Chunks . . . . . . . . . . . . . . . . . . . . . . 11-7
Specifying the Maximum Size of Chunks . . . . . . . . . . . . . . . . . . . . . . . . 11-7
Specifying the Maximum Number of Chunks and Storage Spaces . . . . . . . . . . . . . . . . 11-8
Backing Up After You Change the Physical Schema . . . . . . . . . . . . . . . . . . . . 11-8
Managing Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-8
Creating a Dbspace that Uses the Default Page Size . . . . . . . . . . . . . . . . . . . . 11-8
Specifying the First and Next Extent Sizes for the tblspace tblspace . . . . . . . . . . . . . 11-10
Creating a Dbspace with a Non-Default Page Size . . . . . . . . . . . . . . . . . . . . 11-11
Creating a Buffer Pool for the Non-Default Page Size . . . . . . . . . . . . . . . . . . 11-12
Defining the Page Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
Creating a Temporary Dbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-15
What to Do If You Run Out of Disk Space . . . . . . . . . . . . . . . . . . . . . . . 11-16
Adding a Chunk to a Dbspace or Blobspace . . . . . . . . . . . . . . . . . . . . . . 11-16
Adding a Chunk with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . 11-17
Renaming Dbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-17
Additional Actions You might Need to Take After Renaming a Dbspace . . . . . . . . . . . . 11-18
Managing Dbspace Partitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-18
Managing Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20
Creating a Blobspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-20
Preparing Blobspaces to Store TEXT and BYTE Data . . . . . . . . . . . . . . . . . . . . 11-21
Determining Blobpage Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-21
Determining Database Server Page Size . . . . . . . . . . . . . . . . . . . . . . . 11-21
Obtaining Blobspace Storage Statistics . . . . . . . . . . . . . . . . . . . . . . . 11-22
Managing Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Creating an Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-22
Sizing Sbspace Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Adding a Chunk to an Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-23
Altering Storage Characteristics of Smart Large Objects . . . . . . . . . . . . . . . . . . . 11-24
Creating a Temporary Sbspace . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
Dropping a Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-25
Verifying Whether a Chunk Is Empty . . . . . . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from a Dbspace with onspaces . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from a Blobspace . . . . . . . . . . . . . . . . . . . . . . . . . 11-26
Dropping a Chunk from an Sbspace with onspaces . . . . . . . . . . . . . . . . . . . . 11-26
Using the -f (Force) Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
Deleting Smart Large Objects Without any Pointers . . . . . . . . . . . . . . . . . . . 11-27
Dropping a Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
Preparing to Drop a Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . . 11-27
Dropping a Mirrored Storage Space . . . . . . . . . . . . . . . . . . . . . . . . . 11-28
Dropping a Storage Space with onspaces . . . . . . . . . . . . . . . . . . . . . . . 11-28
Dropping a Dbspace or Blobspace with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 11-28
Backing Up After Dropping a Storage Space . . . . . . . . . . . . . . . . . . . . . . 11-28
Managing Extspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Creating an Extspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29

© Copyright IBM Corp. 1996, 2005 11-1

 Dropping an Extspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Skipping Inaccessible Fragments . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-29
Using the DATASKIP Configuration Parameter . . . . . . . . . . . . . . . . . . . . . 11-30
Using the Dataskip Feature of onspaces . . . . . . . . . . . . . . . . . . . . . . . . 11-30
Using onstat to Check Dataskip Status . . . . . . . . . . . . . . . . . . . . . . . . 11-30
Using the SQL Statement SET DATASKIP . . . . . . . . . . . . . . . . . . . . . . . 11-30
Effect of the Dataskip Feature on Transactions . . . . . . . . . . . . . . . . . . . . . . 11-31
Determining When to Use Dataskip . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
Determining When to Skip Selected Fragments . . . . . . . . . . . . . . . . . . . . 11-31
Determining When to Skip All Fragments . . . . . . . . . . . . . . . . . . . . . . 11-31
Monitoring Fragmentation Use . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-31
Displaying Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Monitoring Disk Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-32
Monitoring Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
onstat -d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
onstat -d update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
onstat -D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-33
onstat -g iof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-34
oncheck -pr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-34
oncheck -pe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-34
Using IBM Informix Server Administrator . . . . . . . . . . . . . . . . . . . . . . 11-35
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-35
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Monitoring Tblspaces and Extents . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-36
Monitoring Simple Large Objects in a Blobspace . . . . . . . . . . . . . . . . . . . . . 11-37
onstat -O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-37
Determining Blobpage Fullness with oncheck -pB. . . . . . . . . . . . . . . . . . . . 11-38
Monitoring Blobspace Usage with oncheck -pe . . . . . . . . . . . . . . . . . . . . 11-38
Monitoring Simple Large Objects in a Dbspace with oncheck -pT . . . . . . . . . . . . . . 11-38
Monitoring Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-39
Using onstat -d . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-40
Using oncheck -ce and oncheck -pe . . . . . . . . . . . . . . . . . . . . . . . . 11-41
Using oncheck -cs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-42
Using oncheck -ps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-42
Monitoring the Metadata and User-Data Areas . . . . . . . . . . . . . . . . . . . . 11-43
Using onstat -g smb c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-44
Loading Data Into a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-44

In This Chapter
This chapter provides the instructions on managing effectively the disk spaces and
data that the database server controls. It assumes you are familiar with the terms
and concepts contained in Chapter 10, “Data Storage,” on page 10-1.

You can use the following utilities to manage storage spaces:

v onspaces
v ISA

This chapter covers the following topics:

v Allocating disk space
v Specifying chunk names, and the maximum size and number of chunks and
storage spaces
v Backing up after you change the physical schema
v Creating and dropping dbspaces, blobspaces, and sbspaces

11-2 IBM Informix Dynamic Server Administrator’s Guide

 v Renaming dbspaces
v Managing dbspace Partitions
v Adding, and dropping chunks from dbspaces, blobspaces, and sbspaces
v Creating and dropping extspaces
v Skipping inaccessible fragments
v Monitoring disk space usage
v Monitoring simple-large-object data and smart-large-object data

Your IBM Informix Dynamic Server Performance Guide also contains information
about managing disk space. In particular, it describes how to eliminate interleaved
extents, how to reclaim space in an empty extent, and how to improve disk I/O.

Allocating Disk Space

This section explains how to allocate disk space for the database server. Read the
following sections before you allocate disk space:
v “Unbuffered or Buffered Disk Access on UNIX” on page 10-4
v “Amount of Disk Space Needed to Store Data” on page 10-31
v “Disk-Layout Guidelines” on page 10-33

Before you can create a storage space or chunk, or mirror an existing storage space,
you must allocate disk space for the chunk file. You can allocate either an empty
file or a portion of raw disk for database server disk space.

UNIX Only

On UNIX, if you allocate raw disk space, you should use the UNIX ln command to
create a link between the character-special device name and another filename. For
more information on this topic, see “Creating Symbolic Links to Raw Devices
(UNIX)” on page 11-5.

Using a UNIX file and its inherent operating-system interface for database server
disk space also is referred to as using cooked space.
End of UNIX Only

Windows Only

On Windows, you should use NTFS files for database server disk space. For more
information on this recommendation, see “Unbuffered or Buffered Disk Access on
UNIX” on page 10-4.
End of Windows Only

You can balance chunks over disks and controllers. Placing multiple chunks on a
single disk can improve throughput.

Specifying an Offset
When you allocate a chunk of disk space to the database server, specify an offset
for one of the following two purposes:
v To prevent the database server from overwriting the partition information
v To define multiple chunks on a partition, disk device, or cooked file

Chapter 11. Managing Disk Space 11-3

 The maximum value for the offset is 4 terabytes.

Many computer systems and some disk-drive manufacturers keep information for
a physical disk drive on the drive itself. This information is sometimes referred to
as a volume table of contents (VTOC) or disk label. The VTOC is commonly stored
on the first track of the drive. A table of alternate sectors and bad-sector mappings
(also called a revectoring table) might also be stored on the first track.

If you plan to allocate partitions at the start of a disk, you might need to use
offsets to prevent the database server from overwriting critical information
required by the operating system. For the exact offset required, refer to your
disk-drive manuals.

Warning: If you are running two or more instances of the database server, be
extremely careful not to define chunks that overlap. Overlapping chunks
can cause the database server to overwrite data in one chunk with
unrelated data from an overlapping chunk. This overwrite effectively
destroys overlapping data.

Specifying an Offset for the Initial Chunk of Root Dbspace

For the initial chunk of root dbspace and its mirror, if it has one, specify the offsets
with the ROOTOFFSET and MIRROROFFSET parameters, respectively. For more
information, see the chapter on configuration parameters in the IBM Informix
Administrator's Reference.

Specifying an Offset for Additional Chunks

To specify an offset for additional chunks of database server space, you must
supply the offset as a parameter when you assign the space to the database server.
For more information, see “Creating a Dbspace that Uses the Default Page Size” on
page 11-8.

Using Offsets to Create Multiple Chunks

You can create multiple chunks from a disk partition, disk device, or file, by
specifying offsets and assigning chunks that are smaller than the total space
available. The offset specifies the beginning location of a chunk. The database
server determines the location of the last byte of the chunk by adding the size of
the chunk to the offset.

For the first chunk, assign any initial offset, if necessary, and specify the size as an
amount that is less than the total size of the allocated disk space. For each
additional chunk, specify the offset to include the sizes of all previously assigned
chunks, plus the initial offset, and assign a size that is less than or equal to the
amount of space remaining in the allocation.

Allocating Cooked File Spaces on UNIX

The following procedure shows an example of allocating a cooked file
usr/data/my_chunk for disk space on UNIX.

To allocate cooked file space:

1. Log in as user informix:
su informix
2. Change directories to the directory where the cooked space will reside:
cd /usr/data
3. Create your chunk by concatenating null to the filename that the database
server will use for disk space:

11-4 IBM Informix Dynamic Server Administrator’s Guide

 cat /dev/null > my_chunk
4. Set the file permissions to 660 (rw-rw----):
chmod 660 my_chunk
5. You must set both group and owner of the file to informix:
ls -l my_chunk -rw-rw----
1 informix informix
0 Oct 12 13:43 my_chunk
6. Use onspaces to create the storage space or chunk.

For information on how to create a storage space using the file you have allocated,
refer to “Creating a Dbspace that Uses the Default Page Size” on page 11-8,
“Creating a Blobspace” on page 11-20, and “Creating an Sbspace” on page 11-22.

Allocating Raw Disk Space on UNIX

To allocate raw space, you must have a disk partition available that is dedicated to
raw space. To create raw disk space, you can either repartition your disks or
unmount an existing file system. Back up any files before you unmount the device.

To allocate raw disk space:

1. Create and install a raw device.
For specific instructions on how to allocate raw disk space on UNIX, see your
operating-system documentation and “Unbuffered or Buffered Disk Access on
UNIX” on page 10-4.
2. Change the ownership and permissions of the character-special devices to
informix.
The filename of the character-special device usually begins with the letter r. For
the procedure, see steps 4 and 5 in “Allocating Cooked File Spaces on UNIX”
on page 11-4.
3. Verify that the operating-system permissions on the character-special devices
are crw-rw----.
4. Create a symbolic link between the character-special device name and another
filename with the UNIX link command, ln -s. For details, see “Creating
Symbolic Links to Raw Devices (UNIX)” on page 11-5.

Warning: After you create the raw device that the database server uses for disk
space, do not create file systems on the same raw device that you
allocate for the database server disk space. Also, do not use the same
raw device as swap space that you allocate for the database server disk
space.

Creating Symbolic Links to Raw Devices (UNIX)

Use symbolic links to assign standard device names and to point to the device. To
create a link between the character-special device name and another filename, use
the UNIX link command (usually ln). To verify that both the devices and the links
exist, execute the UNIX command ls -l (ls -lg on BSD) on your device directory.
The following example shows links to raw devices. If your operating system does
not support symbolic links, hard links also work.
ln -s /dev/rxy0h /dev/my_root # orig_device link to symbolic_name
ln -s /dev/rxy0a /dev/raw_dev2
ls -l
crw-rw--- /dev/rxy0h
crw-rw--- /dev/rxy0a
lrwxrwxrwx /dev/my_root@->/dev/rxy0h
lrwxrwxrwx /dev/raw_dev2@->/dev/rxy0a

Chapter 11. Managing Disk Space 11-5

 Why use symbolic links? If you create chunks on a raw device and that device
fails, you cannot restore from a backup until you replace the raw device and use
the same pathname. All chunks that were accessible at the time of the last backup
must be accessible when you perform the restore.

Symbolic links simplify recovery from disk failure and enable you to replace
quickly the disk where the chunk is located. You can replace a failed device with
another device, link the new device pathname to the same filename that you
previously created for the failed device, and restore the data. You do not need to
wait for the original device to be repaired.

Allocating NTFS File Space on Windows

On Windows, the database server uses NTFS files by default. The NTFS file system
allows you to use standard filenames for unbuffered files.

To allocate NTFS file space for database server disk space or mirrored space, the
first step is to create a null (zero bytes) file.

To allocate NTFS file space for a dbspace, blobspace, or sbspace:

1. Log in as a member of the Informix-Admin group.
2. Open an MS-DOS command shell.
3. Change to the directory where you want to allocate the space, as in the
following example:
c:> cd \usr\data
4. Create a null file with the following command:
c:> copy nul my_chunk
5. If you want to verify that the file has been created, use the dir command to do
so.

After you have allocated the file space, you can create the dbspace or other storage
space as you normally would, using onspaces. For information on how to create a
dbspace or a blobspace, refer to “Creating a Dbspace that Uses the Default Page
Size” on page 11-8 and “Creating a Blobspace” on page 11-20.

Allocating Raw Disk Space on Windows

You can configure raw disk space on Windows as a logical drive or physical drive.
To find the drive letter or disk number, run the Disk Administrator. If the drives
need to be striped (multiple physical disks combined into one logical disk), only
logical drive specification would work.

You must be a member of the Informix-Admin group when you create a storage
space or add a chunk. The raw disk space can be formatted or unformatted disk
space.

To specify a logical drive:

1. Assign a drive letter to the disk partition.
2. Specify the following value for ROOTDBS in the ONCONFIG file:
\\.\drive_letter
3. To create a storage space or add a chunk, specify the logical drive partition.
This example adds a chunk of 5000 kilobytes on the e: drive, at an offset of
5200 kilobytes, to dbspace dpspc3.
onspaces -a dbspc3 \\.\e: -o 5200 -s 5000

11-6 IBM Informix Dynamic Server Administrator’s Guide

 To specify a physical drive:
1. If the disk partition has not been assigned a drive letter, specify the following
value for ROOTDBS in the ONCONFIG file:
\\.\PhysicalDrive<number>
2. To create a storage space or add a chunk, specify the physical drive partition.
This example adds a chunk of 5000 kilobytes on PhysicalDrive0, at an offset of
5200 kilobytes, to dbspace dpspc3.
onspaces -a dbspc3 \\.\PhysicalDrive0 : -o 5200 -s 5000

Warning: If you allocate a formatted drive or disk partition as raw disk space and
it contains data, the database server overwrites the data when it begins
to use the disk space. You must ensure that any data on raw disk space
is expendable before you allocate the disk space to the database server.

Specifying Names for Storage Spaces and Chunks

Chunk names follow the same rules as storage-space names. Specify an explicit
pathname for a storage space or chunk as follows:

UNIX Only

v If you are using raw disks on UNIX, you should use a linked pathname. (See
“Creating Symbolic Links to Raw Devices (UNIX)” on page 11-5.)
End of UNIX Only

Windows Only

v If you are using raw disks on Windows, the pathname takes the following form,
where x specifies the disk drive or partition:
\\.\x:

End of Windows Only

v If you are using a file for database server disk space, the pathname is the
complete path and filename.

Use these naming rules when you create storage spaces or add a chunk. The
filename must have the following characteristics:
v Be unique and not exceed 128 bytes
v Begin with a letter or underscore
v Contain only letters, digits, underscores, or $ characters

The name is case insensitive unless you use quotes around it. By default, the
database server converts uppercase characters in the name to lowercase. If you
want to use uppercase in names, put quotes around them and set the
DELIMIDENT environment variable to ON.

Specifying the Maximum Size of Chunks

On most platforms, the maximum chunk size is 4 terabytes, but on other
platforms, the maximum chunk size is 8 terabytes. To determine which chunk size
your platform supports refer to your machine notes file. If you do not run onmode
-BC, then the maximum chunk size is 2 GB.

Chapter 11. Managing Disk Space 11-7

 Specifying the Maximum Number of Chunks and Storage
Spaces
You can specify a maximum of 32,766 chunks for a storage space, and a maximum
of 32,766 storage spaces on the database server system. The storage spaces can be
any combination of dbspaces, blobspaces, and sbspaces.

Considering all limits that can apply to the size of an instance of the database
server, the maximum size of an instance is approximately 8 petabytes.

You must run onmode -BC to enable the maximum number of chunks and storage
spaces.

Backing Up After You Change the Physical Schema

You must perform a level-0 backup of the root dbspace and the modified storage
spaces to ensure that you can restore the data when you:
v Add or drop mirroring
v Drop a logical-log file
v Change the size or location of the physical log
v Change your storage-manager configuration
v Add, move, or drop a dbspace, blobspace, or sbspace
v Add, move, or drop a chunk to a dbspace, blobspace, or sbspace

Important: When you add a new logical log, you no longer need to perform a
level-0 backup of the root dbspace and modified dbspace to use the
new logical log. However, you should perform the level-0 backup to
prevent level-1 and level-2 backups from failing.

You must perform a level-0 backup of the modified storage spaces to ensure that
you can restore the unlogged data before you switch to a logging table type:
v When you convert a nonlogging database to a logging database
v When you convert a RAW table to standard

Managing Dbspaces
This section contains information on creating standard and temporary dbspaces
with and without the default page size, specifying the first and next extent sizes
for the tblspace tblspace in a dbspace when you create the dbspace, and adding a
chunk to a dbspace or blobspace.

Creating a Dbspace that Uses the Default Page Size

This section explains how to use onspaces to create a standard dbspace and a
temporary dbspace. For information on creating a dbspace with a non-default page
size, see “Creating a Dbspace with a Non-Default Page Size” on page 11-11.

For information on using ISA to create a dbspace, see the ISA online help.

Any newly added dbspace (and its mirror, if one exists) is available immediately. If
you are using mirroring, you can mirror the dbspace when you create it. Mirroring
takes effect immediately.

To create a standard dbspace using onspaces:

1. On UNIX, you must be logged in as user informix or root to create a dbspace.

11-8 IBM Informix Dynamic Server Administrator’s Guide

 On Windows, users in the Informix-Admin group can create a dbspace.
2. Ensure that the database server is in online, single-user, or quiescent mode.
3. Allocate disk space for the dbspace, as described in “Allocating Disk Space” on
page 11-3.
4. To create a dbspace, use the onspaces -c -d options.
Kilobytes is the default unit for the -s size and -o offset options. To convert
kilobytes to megabytes, multiply the unit by 1024 (for example, 10 MB = 10 *
1024 KB).
See “Creating a Dbspace with a Non-Default Page Size” on page 11-11 for
information on additional onspaces options if you are creating a dbspace with
a non-default page size.
5. If you do not want to specify the first and next extent sizes for the tblspace
tblspace in a dbspace, go to step 6.
If you want to specify the first and next extent sizes for the tblspace tblspace in
a dbspace, see additional information in “Specifying the First and Next Extent
Sizes for the tblspace tblspace” on page 11-10.
6. After you create the dbspace, you must perform a level-0 backup of the root
dbspace and the new dbspace.

The following example shows how to create a 10-megabyte mirrored dbspace,

dbspce1, with an offset of 5000 kilobytes for both the primary and mirror chunks,
using raw disk space on UNIX:
onspaces -c -d dbspce1 -p /dev/raw_dev1 -o 5000 -s 10240 -m /dev/raw_dev2 5000

The following example shows how to create a 5-megabyte dbspace, dbspc3, with
an offset of 200 kilobytes, from raw disk space (drive e:) on Windows:
onspaces -c -d dbspc3 \\.\e: -o 200 -s 5120

For more information on creating a dbspace with onspaces, see “Dbspaces” on

page 10-9. and information on the onspaces utility in the IBM Informix
Administrator's Reference.

To create a dbspace with ON-Monitor (UNIX):

1. Select the Dbspaces > Create option.
2. Enter the name of the new dbspace in the field Dbspace Name.
3. If you want to create a mirror for the initial dbspace chunk, enter Y in the
Mirror field.
Otherwise, enter N.
4. If the dbspace that you are creating is a temporary dbspace, enter Y in the
Temp field.
Otherwise, enter N.
5. If you are specifying a page size for a standard dbspace, enter the size in
kilobytes in the Page Size field. The size must be a multiple of the page size of
the root dbspace. For more information on specifying page sizes, see “Creating
a Dbspace with a Non-Default Page Size” on page 11-11.
All tables, indexes, and other objects within the dbspace will use pages of the
specified size.
6. Enter the full pathname for the initial primary chunk of the dbspace in the Full
Pathname field of the primary-chunk section.
7. Specify an offset in the Offset field.
8. Enter the size of the chunk, in kilobytes, in the Size field.

Chapter 11. Managing Disk Space 11-9

 9. If you are mirroring this dbspace, enter the mirrored-chunk full pathname, size,
and optional offset in the mirrored-chunk section of the screen.

For more information, refer to the ON–Monitor chapter in the IBM Informix
Administrator's Reference.

Specifying the First and Next Extent Sizes for the tblspace
tblspace
Specify first and next extent sizes if you want to reduce the number of tblspace
tblspace extents and reduce the frequency of situations when you need to place
the tblspace tblspace extents in non-primary chunks. (A primary chunk is the initial
chunk in a dbspace.)

You can choose to specify the first extent size, the next extent size, both the first
and the next extent size, or neither extent size. If you do not specify first or next
extent sizes for the tblspace tblspace, Dynamic Server uses the existing default
extent sizes.

You can use the TBLTBLFIRST and TBLTBLNEXT configuration parameters to

specify the first and next extent sizes for the tblspace tblspace in the root dbspace
that is created when the server is initialized.

You can use the onspaces utility to specify the first and next extent sizes for the
tblspace tblspace in non-root dbspaces.

You can only specify the first and next extent sizes when you create dbspace. You
cannot alter the specification of the first and next extent sizes after the creation of
the dbspace. In addition, you cannot specify extent sizes for temporary dbspaces,
sbspaces, blobspaces, or external spaces. You cannot alter the specification of the
first and next extents sizes after the creation of the dbspace.

To specify the first and next extent sizes:

1. Determine the total number of pages needed in the tblspace tblspace. The
number of pages is equal to the sum of the number of tables, detached indexes,
and table fragments likely to reside in the dbspace plus one page for the
tblspace tblspace.
2. Calculate the number of kilobytes needed for the number of pages. This
number will depend on the number of kilobytes to a page on the system.
3. Determine the space management needs on your system by considering the
importance of having all of the extents for the tblspace tblspace allocated
during dbspace creation and whether the extents should be allocated
contiguously. The more important these issues are, the larger the first extent
size should be. If you are less concerned with having non-contiguous extents,
possibly in secondary chunks, then the first and next extent sizes can be
smaller.
4. Specify the extent size as follows:
v If the space requirement is for the root dbspace, specify the first extent size
in the TBLTBLFIRST configuration parameter and the next extent size in the
TBLTBLNEXT configuration parameter. Then initialize the database server
instance.
v If the space requirement is for a non-root dbspace, indicate the first and next
extent sizes on the command line using the onspaces utility to create the
dbspace.

11-10 IBM Informix Dynamic Server Administrator’s Guide

 Extent sizes must be in kilobytes and must be multiples of the page size. When
you specify first and next extent sizes, follow these guidelines:

Type of Extent Minimum Size Maximum Size

First extent in a non-root The equivalent of 50 pages, The size of the initial chunk,
dbspace specified in kilobytes. This is minus the space needed for
the system default. any system objects such as
For example, for a the reserved pages, the
two-kilobyte page system, database tblspace, and the
the minimum length is 100. physical and logical logs.
First extent in a root dbspace The equivalent of 250 pages The size of the initial chunk,
specified in kilobytes. This is minus the space needed for
the system default. any system objects such as
the reserved pages, the
database tblspace, and the
physical and logical logs.
Next Extent Four times the disk-page size The maximum chunk size
on the system. The default is minus three pages.
50 pages on any type of
dbspace.

You use the following onspaces utility -ef and -en options to specify the first and
next extent sizes for the tblspace tblspace in non-root dbspaces:
v First extent size: -ef size_in_kbytes
v Next extent size: -en size_in_kbytes

For example, you can specify:

onspaces -c -d dbspace1 -p /usr/data/dbspace1 -o 0 -s 1000000 -e 2000 -n 1000

You can use Oncheck -pt and oncheck -pT to show the first and next extent sizes
of a tblspace tblspace.

If HDR is being used and a dbspace is created on the primary database server, the
first and next extent sizes are passed to the secondary database server via the
ADDCHK log record.

For more information on the onspaces utility, oncheck commands, and specifying
the first and next extent sizes for the tblspace tblspace, see the IBM Informix
Administrator's Reference.

Creating a Dbspace with a Non-Default Page Size

You can specify a page size for a standard or temporary dbspace if you want a
longer key length than is available for the default page size. The root dbspace is
the default page size. If you want to specify a page size, the size must be an
integral multiple of the default page size, and cannot be greater than 16 kilobytes.

For systems with sufficient storage, the performance advantages of a larger page
size include:
v Reduced depth of b-tree indexes, even for smaller index keys.
v Decreased checkpoint time, which typically occurs with larger page sizes.

Additional performance advantages occur because you can:

Chapter 11. Managing Disk Space 11-11

 v Group on the same page long rows that currently span multiple pages of the
default page size.
v Define a different page size for temporary tables, so the temporary tables have a
separate buffer pool.

You can use the BUFFERPOOL configuration parameter to create a buffer pool that
corresponds to the page size of the dbspace. (You might want to do this to
implement a form of ″private buffer pool.″)

A table can be in one dbspace and the index for that table can be in another
dbspace. The page size for these partitions can be different.

If you want to specify the page size for the dbspace, perform these tasks:
1. Use the onmode -BC command to enable the large chunk mode if this mode is
not enabled. By default, when Dynamic Server Version 10.0 is first initialized or
restarted, Dynamic Server starts with the large chunk mode enabled. For
information on the onmode utility in the IBM Informix Dynamic Server
Administrator's Reference.
2. Create a buffer pool that corresponds to the page size of the dbspace. You can
use the onparams utility or the BUFFERPOOL configuration parameter. You
should do this before you create the dbspace.
If you create a dbspace with a page size that does not have a corresponding
buffer pool, Dynamic Server automatically creates a buffer pool using the
default parameters defined in the ONCONFIG configuration file.
You cannot have multiple buffer pools with the same page size.
For more information, see “Creating a Dbspace with a Non-Default Page Size”
on page 11-11.
3. Define the page size of the dbspace when you create the dbspace. You can use
the onspaces utility or ON-Monitor. For more information, see “Defining the
Page Size” on page 11-15.

For example, if you create a dbspace with a page size of 6 kilobytes, you must
create a buffer pool with a size of 6 kilobytes. If you do not specify a page size for
the new buffer pool, Dynamic Server uses the operating system default page size
(4 kilobytes on Windows and 2 kilobytes on most UNIX platforms) as the default
page size for the buffer pool.

Note: If you use non-default page sizes, you might need to increase the size of
your physical log. If you perform many updates to non-default pages you
might need a 150 to 200 percent increase of the physical log size. Some
experimentation might be needed to tune the physical log. You can adjust
the size of the physical log as necessary according to how frequently the
filling of the physical log triggers checkpoints.

Creating a Buffer Pool for the Non-Default Page Size

When you create a buffer pool, you can use the BUFFERPOOL configuration
parameter or the onparams utility to define information about the buffer pool
including its size, the number of LRUS in the buffer pool, the number of buffers in
the buffer pool, and lru_min_dirty and lru_max_dirty values.

You specify this information using the BUFFERPOOL configuration parameter.

The BUFFERPOOL configuration parameter consists of two lines in the

[Link] file.

11-12 IBM Informix Dynamic Server Administrator’s Guide

 On UNIX machines, the lines are:
BUFFERPOOL default,lrus=8,buffers=5000,lru_min_dirty=50,lru_max_dirty=60
BUFFERPOOL size=2K,buffers=5000,lrus=8,lru_min_dirty=50,lru_max_dirty=60

On Windows machines, the lines are:

BUFFERPOOL default,lrus=8,buffers=2000,lru_min_dirty=50,lru_max_dirty=60
BUFFERPOOL size=4K,buffers=2000,lrus=8,lru_min_dirty=50,lru_max_dirty=60

The top line specifies the default values that are used if you create a dbspace with
a page size that does not have a corresponding buffer pool that was created when
the database server started. The line below the default line specifies the database
server default values for the buffer pool. These values are based on the default
page size of the database server.

When you add a dbspace with a different page size with the onspaces utility or
when you add a new buffer pool with the onparams utility, a new line is added to
the BUFFERPOOL configuration parameter in the ONCONFIG file. The page size
for each buffer pool must be a multiple of the default page size for your operating
system. The following example shows a third BUFFERPOOL line that was added
to the ONCONFIG file:
BUFFERPOOL default,lrus=8,buffers=5000,lru_min_dirty=50,lru_max_dirty=60
BUFFERPOOL size=2K,buffers=5000,lrus=8,lru_min_dirty=50,lru_max_dirty=60
BUFFERPOOL size=6K,buffers=3000,lrus=8,lru_min_dirty=50,lru_max_dirty=60

The fields in the BUFFERPOOL lines are not case sensitive, so you can specify lrus
or Lrus or LRUS). These fields can appear in any order.

If you do not specify a page size for a new buffer pool, Dynamic Server uses the
operating system default page size (4 kilobytes on Windows and 2 kilobytes on
most UNIX platforms) as the default page size for the buffer pool.

If the value of buffers is zero (0) or if the value of buffers is missing in the
BUFFERPOOL configuration parameter, Dynamic Server will not create the buffer
pool of the specified page size.

Note: Information that was specified with the BUFFERS, LRUS,

LRU_MAX_DIRTY, and LRU_MIN_DIRTY configuration parameters prior to
Version 10.0 is now specified using the BUFFERPOOL configuration
parameter. Information you enter using the BUFFERPOOL configuration
parameter supersedes any information previously specified with the
deprecated parameters. For more information on the deprecated parameters,
see the appendix that contains information on discontinued configuration
parameters that is in IBM Informix Dynamic Server Administrator's Reference.

The table below provides an explanation of the values that you specify using the
BUFFERPOOL configuration parameter or the onparams utility.

Field Explanation Range of Values

size Specifies the number of kilobytes, followed by the The size can vary from 2K or 4K to 16
suffix K, in a page. K. 2K is the default.

Chapter 11. Managing Disk Space 11-13

Field Explanation Range of Values
buffers Specifies the number of buffers for the page size. For 32-bit platform on UNIX
v with page size equal to 2048 bytes:
This is the maximum number of shared-memory
100 through 1,843,200 buffers
buffers that the database server user threads have
(1843200 = 1800 * 1024
available for disk I/O on behalf of client
applications. The number of buffers that the v with page size equal to 4096 bytes:
database server requires depends on the 100 through 921,600 buffers
applications. (921,600 = ((1800 * 1024)/4096) *
2048 )
For example, if the database server accesses 15
percent of the application data 90 percent of the For 32-bit platform on Windows:
time, you need to allocate enough buffers to hold 100 through 524,288 buffers
that 15 percent. Increasing the number of buffers (524,288 = 512 * 1024)
can improve system performance.
For 64-bit platforms:
The percentage of physical memory that you need 100 through 231-1 buffers
for buffer space depends on the amount of memory (For the actual value for your 64-bit
available on your computer and the amount of platform, see your release notes. The
memory used for other applications. For systems maximum number of buffers on Solaris
with a large amount of available physical memory is 536,870,912.)
(4 gigabytes or more), buffer space can be as much
as 90 percent of physical memory. For systems with
smaller amounts of available physical memory,
buffer space can range from 20 to 25 percent of
physical memory.

You should calculate all other shared-memory

parameters after you set buffer space (buffers
*system_page_size).
lrus Specifies the number of LRU (least-recently-used) 1 through 128
queues in the shared-memory buffer pool for the
page size. You can tune the value of LRUS, in
combination with the lru_min_dirty and
lru_max_dirty values, to control how frequently the
shared-memory buffers are flushed to disk.

Setting LRUS too high might result in excessive

page-cleaner activity.
lru_min_dirty Specifies the percentage of modified pages in the 0 through 100 (fractional values are
LRU queues at which page cleaning is no longer allowed)
mandatory. Page cleaners might continue cleaning
beyond this point under some circumstances. If a
parameter is specified out of the range of values,
then the default of 50.00 percent is set.
lru_max_dirty Specifies the percentage of modified pages in the 0 through 100 (fractional values are
LRU queues at which the queue is cleaned. If a allowed)
parameter is specified out of the range of values,
then the default of 60.00 percent is set.

If the database server is in online, quiescent, or single user mode, you can also use
the onparams utility to add a new buffer pool of a different size. When you use
the onparams utility, the information you specify is automatically transferred to the
ONCONFIG file and new values are specified using the BUFFERPOOL keyword.
You cannot change the values by editing the [Link] file.

When you use the onparams utility, you specify information as follows:

11-14 IBM Informix Dynamic Server Administrator’s Guide

 onparams -b -g <size of buffer page in Kbytes> -n <number of buffers>
-r <number of LRUs> -x <max dirty (fractional value allowed)>
-m <minimum dirty (fractional value allowed)>

For example:
onparams -b -g 6 -n 3000 -r 2 -x 2.0 -m 1.0

This adds 3000 buffers of size 6K bytes each with 2 LRUS and lru_max_dirty set at
2 percent and lru_min_dirty set at 1 percent.

For more information on the onparams utility, see the IBM Informix Dynamic Server
Administrator's Reference.

Recommendation: Set the PHYSBUFF configuration parameter to a multiple of

your largest page size. For example, if your largest page size is 16 kilobytes, you
can set the PHYSBUFF parameter to 32.

The LG_ADDBPOOL log record and the sysbufpool system catalog table contain
information on each buffer pool.

Buffer pools that are added while the database server is running go into virtual
memory, not into resident memory. Only those buffer pool entries that are specified
in the ONCONFIG file at startup go into resident memory, depending on the
availability of the memory you are using.

Resizing an Existing Buffer Pool: If you need to resize an existing buffer pool,
you must bring down the database server. Then change the buffer pool size in the
ONCONFIG file.

Deleting an Existing Buffer Pool: If you need to delete an existing buffer pool,
you must bring down the database server. Then, in the ONCONFIG file, delete the
buffer pool.

Defining the Page Size

Use the onspaces -k option to set the page size in kilobytes, as follows:
onspaces -c -d DBspace [-t] [-k pagesize] -p path -o offset -s size [-m path offset]

The root dbspace is the default page size.

If you specify a page size, the page size must be a multiple of the default page
size, but not greater than 16 kilobytes.

If you are using ON-Monitor to create a dbspace, be sure to enter the page size in
kilobytes in the Page Size field.

For more information about using the ON-Monitor and onspaces utilities, see the
IBM Informix Dynamic Server Administrator's Reference.

Creating a Temporary Dbspace

To specify where to allocate the temporary files, create temporary dbspaces.

To define temporary dbspaces:

1. Use the onspaces utility with the -c -d -t options.
For more information, refer to “Creating a Dbspace that Uses the Default Page
Size” on page 11-8.

Chapter 11. Managing Disk Space 11-15

 2. Use the DBSPACETEMP environment variables or the DBSPACETEMP
configuration parameter to specify the dbspaces that the database server can
use for temporary storage.
The DBSPACETEMP configuration parameter can contain dbspaces with a
non-default page size. However, all of the dbspaces in the DBSPACETEMP list
must have the same page size.
For further information on DBSPACETEMP, refer to the chapter on
configuration parameters in the IBM Informix Administrator's Reference.
3. If you create more than one temporary dbspace, the dbspaces should reside on
separate disks to optimize the I/O.

If you are creating a temporary dbspace, you must make the database server aware
of the existence of the newly created temporary dbspace by setting the
DBSPACETEMP configuration variable, the DBSPACETEMP environment variable,
or both. The database server does not begin to use the temporary dbspace until
you take both of the following steps:
v Set the DBSPACETEMP configuration parameter, the DBSPACETEMP
environment variable, or both.
v Restart the database server.

The following example shows how to create 5-megabyte temporary dbspace named
temp_space with an offset of 5000 kilobytes:
onspaces -c -t -d temp_space -p /dev/raw_dev1 -o 5000 -s 5120

For more information, see “Temporary Dbspaces” on page 10-11.

What to Do If You Run Out of Disk Space

When the initial chunk of the dbspace that you are creating is a cooked file on
UNIX or an NTFS file on Windows, the database server verifies that the disk space
is sufficient for the initial chunk. If the size of the chunk is greater than the
available space on the disk, a message is displayed and no dbspace is created.
However, the cooked file that the database server created for the initial chunk is
not removed. Its size represents the space left on your file system before you
created the dbspace. Remove this file to reclaim the space.

Adding a Chunk to a Dbspace or Blobspace

You add a chunk when a dbspace, blobspace, or sbspace is becoming full or it
needs more disk space. Use onspaces or ISA to add a chunk. For information on
using ISA to add a chunk, see the ISA online help.

Important: The newly added chunk (and its associated mirror, if one exists) is
available immediately. If you are adding a chunk to a mirrored storage
space, you must also add a mirror chunk.

To add a chunk using onspaces:

1. On UNIX, you must be logged in as user informix or root to add a chunk.
On Windows, users in the Informix-Admin group can add a chunk.
2. Ensure that the database server is in online, single-user, or quiescent mode, or
the cleanup phase of fast-recovery mode.
3. Allocate disk space for the chunk, as described in “Allocating Disk Space” on
page 11-3.
4. To add a chunk, use the -a option of onspaces.

11-16 IBM Informix Dynamic Server Administrator’s Guide

 If the storage space is mirrored, you must specify the pathname of both a
primary chunk and mirror chunk.
If you specify an incorrect pathname, offset, or size, the database server does
not create the chunk and displays an error message. Also see “What to Do If
You Run Out of Disk Space” on page 11-16.
5. After you create the chunk, you must perform a level-0 backup of the root
dbspace and the dbspace, blobspace, or sbspace that contains the chunk.

The following example adds a 10-megabyte mirror chunk to blobsp3. An offset of

200 kilobytes for both the primary and mirror chunk is specified. If you are not
adding a mirror chunk, you can omit the -m option.
onspaces -a blobsp3 -p /dev/raw_dev1 -o 200 -s 10240 -m /dev/raw_dev2 200

The next example adds a 5-megabyte chunk of raw disk space, at an offset of 5200
kilobytes, to dbspace dbspc3.
onspaces -a dbspc3 \\.\e: -o 5200 -s 5120

For reference information on adding a chunk to a dbspace with onspaces, see

information on the onspaces utility in the IBM Informix Administrator's Reference.

Adding a Chunk with ON-Monitor (UNIX)

To add a chunk to a dbspace, follow these instructions:
1. Choose Add Chunk > Dbspaces option.
2. Use RETURN or the arrow keys to select the blobspace or dbspace that will
receive the new chunk and press CTRL-B or F3.
3. The next screen indicates whether the blobspace or dbspace is mirrored. If it is,
enter Y in the Mirror field.
4. If the dbspace to which you are adding the chunk is a temporary dbspace,
enter Y in the Temp field.
5. If you indicated that the dbspace or blobspace is mirrored, you must specify
both a primary chunk and mirror chunk.
Enter the complete pathname for the new primary chunk in the Full Pathname
field of the primary-chunk section.
6. Specify an offset in the Offset field.
7. Enter the size of the chunk, in kilobytes, in the Size field.
8. If you are mirroring this chunk, enter the complete pathname, size, and
optional offset in the mirror-chunk section of the screen.

Renaming Dbspaces
You can use the onspaces utility to rename a dbspace if you are user informix or
have DBA privileges and the database server is in quiescent mode (and not any
other mode).

To rename a dbspace use the following onspaces utility command:

onspaces -ren old_dbspace_name-n new_dbspace_name

You can rename standard dbspaces and all other spaces, including blobspaces,
smart blobspaces, temporary spaces, and external spaces. However, you cannot
rename any critical dbspace, such as a root dbspace or a dbspace that contains
physical logs.

You can rename a dbspace and an sbspace:

Chapter 11. Managing Disk Space 11-17

 v When Enterprise Replication is enabled
v On a High-Availability Data Replication (HDR) primary database server

You cannot rename a dbspace and an sbspace on an HDR secondary database

server or when the HDR secondary database server is part of the Enterprise
Replication configuration

The rename dbspace operation only changes the dbspace name; it does not
reorganize data.

The rename dbspace command updates the dbspace name in all places where that
name is stored. This includes reserved pages on disk, system catalogs, the
ONCONFIG configuration file, and in-memory data structures.

Warning: After renaming a dbspace, perform a level-0 archive of the renamed

dbspace and the root dbspace. For information, see the IBM Informix
Backup and Restore Guide.

Additional Actions You might Need to Take After Renaming a

Dbspace
If you rename a dbspace, you must rewrite and recompile any stored procedure
code that references the old dbspace name. For example, if you have a stored
procedures that contains the ALTER FRAGMENT keywords and a reference to the
dbspace name, you must rewrite and recompile that stored procedure.

If you rename dbspaces that are specified in the DATASKIP configuration

parameter, you must manually update the DATASKIP configuration parameter
after renaming the dbspace.

Managing Dbspace Partitions

For fragmented tables that use expression-based or round-robin distribution
schemes, you can create multiple partitions, which are collections of pages for a
table or index, within a single dbspace.

Suppose you are creating a fragmented table using an expression-based

distribution scheme in which each expression specifies the datasets that are placed
in particular fragments. You might decide to separate the data in the table with
data from one month in one dbspace and data from the next 11 months in 11 other
dbspaces. However, if you want to use only one dbspace for all the yearly data,
you can create partitions so the data for each month is stored in a separate
partition in one dbspace.

If you create a fragmented table with partitions, each row in the sysfragments
system catalog contains a partition name in the Partition column. If you create a
fragmented table without partitions, the name of the dbspace appears in the
Partition column. The Flags column in the sysfragments catalog tells you if the
fragmentation scheme has partitions.

You can create tables and indexes with partitions, and you can create, drop, and
alter partition fragments using the PARTITION keyword and the partition name.

To create a fragmented table with partitions, use SQL syntax as shown in the
following example:

11-18 IBM Informix Dynamic Server Administrator’s Guide

CREATE TABLE tb1(a int)
FRAGMENT BY EXPRESSION
PARTITION part1 (a >=0 AND a < 5) IN dbspace1,
PARTITION part2 (a >=5 AND a < 10) IN dbspace1
...
;

If you created a table or index fragment containing partitions, you must use syntax
containing the partition name when you use the ALTER FRAGMENT statement, as
shown in the following examples.
ALTER FRAGMENT ON TABLE tb1 INIT FRAGMENT BY EXPRESSION
PARTITION part_1 (a >=0 AND a < 5) IN dbspace1,
PARTITION part_2 (a >=5 AND a < 10) IN dbspace1;
ALTER FRAGMENT ON INDEX ind1 INIT FRAGMENT BY EXPRESSION
PARTITION part_1 (a >=0 AND a < 5) IN dbspace1,
PARTITION part_2 (a >=5 AND a < 10) IN dbspace1;

You can use the PARTITION BY EXPRESSION clause instead of the FRAGMENT
BY EXPRESSION clause in CREATE TABLE, CREATE INDEX, and ALTER
FRAGMENT ON INDEX statements as shown in this example:
ALTER FRAGMENT ON INDEX idx1 INIT PARTITION BY EXPRESSION
PARTITION part1 (a <= 10) IN idxdbspc1,
PARTITION part2 (a <= 20) IN idxdbspc1,
PARTITION part3 (a <= 30) IN idxdbspc1;

Use ALTER FRAGMENT syntax to change fragmented tables and indexes that do
not have partitions into tables and indexes that have partitions. For example, the
syntax below shows how you might The syntax below shows how you might
convert a fragmented table with multiple dbspaces into one using partitions.
CREATE TABLE t1 (c1 int) FRAGMENT BY EXPRESSION
(c1=10) IN dbs1,
(c1=20) IN dbs2;
ALTER FRAGMENT ON TABLE t1 MODIFY dbs2 TO PARTITION part_3 (c1=20)
IN dbs1

The syntax below shows how you might convert a fragmented index into an index
that contains partitions:
CREATE TABLE t1 (c1 int) FRAGMENT BY EXPRESSION
(c1=10) IN dbs1, (c1=20) IN dbs2, (c1=30) IN dbs3
CREATE INDEX ind1 ON t1 (c1) FRAGMENT BY EXPRESSION
(c1=10) IN dbs1, (c1=20) IN dbs2, (c1=30) IN dbs3
ALTER FRAGMENT ON INDEX ind1 INIT FRAGMENT BY EXPRESSION
PARTITION part_1 (c1=10) IN dbs1, PARTITION part_2 (c1=20) IN dbs1,
PARTITION part_3 (c1=30) IN dbs1,

See the IBM Informix Dynamic Server Performance Guide for more information on
fragmentation, including fragmentation guidelines, procedures for fragmenting
indexes, procedures for creating attached and detached indexes with partitions,
and examples of SQL statements used to create attached and detached indexes
containing partitions.

See the IBM Informix Guide to SQL: Syntax for more syntax details, including
information on partitions in GRANT FRAGMENT, REVOKE FRAGMENT
statements and details for using the DROP, DETACH and MODIFY clauses of the
ALTER FRAGMENT statement.

Chapter 11. Managing Disk Space 11-19

Managing Blobspaces
This section discusses how to create a blobspace and determine the blobpage size.
The database server stores TEXT and BYTE data in dbspaces or blobspaces, but
blobspaces are more efficient. For information on adding a chunk, see “Adding a
Chunk to a Dbspace or Blobspace” on page 11-16.

Creating a Blobspace
You can use onspaces, ISA, or ON–Monitor to create a blobspace. Specify a
blobspace name of up to 128 bytes. The name must be unique and must begin with
a letter or underscore. You can use letters, digits, underscores, and $ characters in
the name.

Important: You can mirror the blobspace when you create it if mirroring is
enabled for the database server. Mirroring takes effect immediately.

Before you create a blobspace:

1. Allocate disk space for the blobspace, as described in “Allocating Disk Space”
on page 11-3.
2. Determine what blobpage size is optimal for your environment.
For instructions, see “Determining Blobpage Size” on page 11-21.

To create a blobspace using onspaces:

1. To create a blobspace on UNIX, you must be logged in as user informix or
root.
To create a blobspace on Windows, you must be a member of the
Informix-Admin group.
2. Ensure that the database server is in online, single-user, or quiescent mode, or
the cleanup phase of fast-recovery mode.
3. To add a blobspace, use the onspaces -c -b options.
a. Specify an explicit pathname for the blobspace. If the blobspace is mirrored,
you must specify the pathname and size of both the primary chunk and
mirror chunk.
b. Use the -o option to specify an offset for the blobspace.
c. Use the -s option to specify the size of the blobspace chunk, in kilobytes.
d. Use the -g option to specify the blobpage size in terms of the number of
disk pages per blobpages.
See “Determining Blobpage Size” on page 11-21. For example, if your
database server instance has a disk-page size of 2 kilobytes, and you want
your blobpages to have a size of 10 kilobytes, enter 5 in this field.
If you specify an incorrect pathname, offset, or size, the database server does
not create the blobspace and displays an error message. Also see “What to Do
If You Run Out of Disk Space” on page 11-16.
4. After you create the blobspace, you must perform a level-0 backup of the root
dbspace and the new blobspace.

The following shows how to create a 10-megabyte mirrored blobspace, blobsp3,

with a blobpage size of 10 kilobytes, where the database server page size is 2
kilobytes. An offset of 200 kilobytes for the primary and mirror chunks is specified.
The blobspace is created from raw disk space on UNIX.
onspaces -c -b blobsp3 -g 5 -p /dev/raw_dev1 -o 200 -s 10240 -m /dev/raw_dev2 200

11-20 IBM Informix Dynamic Server Administrator’s Guide

 For reference information on creating a blobspace with onspaces, see information
on the onspaces utility in the IBM Informix Administrator's Reference.

To create a blobspace with ON-Monitor (UNIX):

1. Select the Dbspaces > BLOBSpace option.
2. Enter the name of the new blobspace in the BLOBSpace Name field.
3. If you want to create a mirror for the initial blobspace chunk, enter Y in the
Mirror field.
Otherwise, enter N.
4. Specify the blobpage size in terms of the number of disk pages per blobpage in
the BLOBPage Size field.
See “Determining Database Server Page Size” on page 11-21. For example, if
your database server instance has a disk-page size of 2 kilobytes, and you want
your blobpages to have a size of 10 kilobytes, enter 5 in this field.
5. Enter the complete pathname for the initial primary chunk of the blobspace in
the Full Pathname field of the primary-chunk section.
6. Specify an offset in the Offset field.
7. Enter the size of the chunk, in kilobytes, in the Size field.
8. If you are mirroring this blobspace, enter the full pathname, size, and optional
offset in the mirror-chunk section of the screen.

Preparing Blobspaces to Store TEXT and BYTE Data

A newly created blobspace is not immediately available for storage of TEXT or
BYTE data. Blobspace logging and recovery require that the statement that creates
a blobspace and the statements that insert TEXT and BYTE data into that blobspace
appear in separate logical-log files. This requirement is true for all blobspaces,
regardless of the logging status of the database. To accommodate this requirement,
switch to the next logical-log file after you create a blobspace. (For instructions, see
“Backing Up Log Files to Free Blobpages” on page 14-7.)

Determining Blobpage Size

When you create a blobspace, use the size of the most frequently occurring simple
large object as the size of the blobpage. In other words, choose a blobpage size that
wastes the least amount of space. For information on calculating an optimal
blobpage size, see blobpage size considerations in the chapter on effect of
configuration on I/O activity in the IBM Informix Dynamic Server Performance Guide.

If a table has more than one TEXT or BYTE column, and the objects are not close
in size, store each column in a different blobspace, each with an appropriately
sized blobpage. See “Tables” on page 10-22.

Determining Database Server Page Size

When you specify blobpage size, you specify it in terms of the database server
pages. You can use one of the following methods to determine the database server
page size for your system:
v Run the onstat -b utility to display the system page size, given as buffer size on
the last line of the output.
v To view the contents of the PAGE_PZERO reserved page, run the oncheck -pr
utility.
v UNIX only: In ON–Monitor, select either the Parameters > Shared-Memory or
Parameters > Initialize option to display the system page size.

Chapter 11. Managing Disk Space 11-21

 Obtaining Blobspace Storage Statistics
To help you determine the optimal blobpage size for each blobspace, use the
following database server utility commands:
v oncheck -pe
v oncheck -pB

The oncheck -pe command provides background information about the objects
stored in a blobspace:
v Complete ownership information (displayed as database:[Link]) for each table
that has data stored in the blobspace chunk
v The total number of pages used by each table to store its associated TEXT and
BYTE data
v The total free and total overhead pages in the blobspace

The oncheck -pB command lists the following statistics for each table or database:
v The number of blobpages used by the table or database in each blobspace
v The average fullness of the blobpages used by each simple large object stored as
part of the table or database

For more information, see “Monitoring Blobspace Usage with oncheck -pe” on
page 11-38, “Determining Blobpage Fullness with oncheck -pB” on page 11-38, and
optimizing blobspace blobpage size in the chapter on table performance
considerations in the IBM Informix Dynamic Server Performance Guide.

Managing Sbspaces
This section describes how to create a standard or temporary sbspace, monitor the
metadata and user-data areas, add a chunk to an sbspace, and alter storage
characteristics of smart large objects.

Creating an Sbspace
Use the onspaces utility or ISA to create an sbspace.

To create an sbspace using onspaces:

1. To create an sbspace on UNIX, you must be logged in as user informix or root.
To create an sbspace on Windows, you must be a member of the
Informix-Admin group.
2. Ensure that the database server is online, single-user, or quiescent mode, or in
the cleanup phase of fast-recovery mode.
3. Use the onspaces -c -S options to create the sbspace.
a. Use the -p option to specify the pathname, the -o option to specify the
offset, and the -s option to specify the sbspace size.
b. If you wish to mirror the sbspace, use the -m option to specify the mirror
path and offset.
c. If you want to use the default storage characteristics for the sbspace, omit
the -Df option.
If you want to specify different storage characteristics, use the -Df option.
For more information, refer to “Storage Characteristics of Sbspaces” on page
10-15.
d. The first chunk in an sbspace must have a metadata area.

11-22 IBM Informix Dynamic Server Administrator’s Guide

 You can specify a metadata area for an sbspace or let the database server
calculate the size of the metadata area. For more information, see “Sizing
Sbspace Metadata” on page 11-23.
4. After you create the sbspace, you must perform a level-0 backup of the root
dbspace and the new sbspace.
5. To start storing smart large objects in this sbspace, specify the space name in
the SBSPACENAME configuration parameter.
6. Use onstat -d, onstat -g smb s, and oncheck -cs, -cS, -ps, or -pS to display
information about the sbspace.
For more information, see “Monitoring Sbspaces” on page 11-39.

This shows how to create a 20-megabyte mirrored sbspace, sbsp4. Offsets of 500
kilobytes for the primary and 500 kilobytes for the mirror chunks are specified, as
well as a metadata size of 150 kilobytes with a 200 kilobyte offset. The
AVG_LO_SIZE -Df tag specifies an expected average smart-large-object size of 32
kilobytes.
onspaces -c -S sbsp4 -p /dev/rawdev1 -o 500 -s 20480 -m /dev/rawdev2 500
-Ms 150 -Mo 200 -Df "AVG_LO_SIZE=32"

For information about creating an sbspace and default options for smart large
objects, see information on the onspaces utility in the IBM Informix Administrator's
Reference. For information on creating smart large objects, see the IBM Informix
DataBlade API Programmer's Guide and IBM Informix ESQL/C Programmer's Manual.

To create an sbspace using ISA:

1. Create the sbspace using
2. ISA. For more information, see the ISA online help.
3. Back up the new sbspace and the root dbspace.

Sizing Sbspace Metadata

The first chunk of an sbspace must have a metadata area. When you add smart
large objects and chunks to the sbspace, the metadata area grows. In addition, the
database server reserves 40 percent of the user area to be used in case the
metadata area runs out of space.

It is important to size the metadata area for an sbspace correctly to ensure that the
sbspace does not run out of metadata space. You can either:
v Let the database server calculate the size of the metadata area for the new
sbspace chunk.
v Specify the size of the metadata area explicitly.

For instructions on estimating the size of the sbspace and metadata area, see table
performance considerations in the IBM Informix Dynamic Server Performance Guide.
Also see “Monitoring the Metadata and User-Data Areas” on page 11-43.

Adding a Chunk to an Sbspace

Use the onspaces utility or ISA to add a chunk to an sbspace or temporary
sbspace. You can specify a metadata area for a chunk, let the database server
calculate the metadata area, or use the chunk for user data only.

To add a chunk to an sbspace using onspaces:

1. Ensure that the database server is online, single-user, or quiescent mode, or in
the cleanup phase of fast-recovery mode.
Chapter 11. Managing Disk Space 11-23
 2. Use the onspaces -a option to create the sbspace chunk.
a. Use the -p option to specify the pathname, the -o option to specify the
offset, and the -s option to specify the chunk size.
b. If you want to mirror the chunk, use the -m option to specify the mirror
path and offset.
c. To specify the size and offset of the metadata space, use the -Mo and -Ms
options.
The database server allocates the specified amount of metadata area on the
new chunk.
d. To allow the database server to calculate the size of the metadata for the
new chunk, omit the -Mo and -Ms options.
The database server divides the estimated average size of the smart large
objects by the size of the user data area.
e. To use the chunk for user data only, specify the -U option.
If you use the -U option, the database server does not allocate metadata
space in this chunk. Instead, the sbspace uses the metadata area in one of
the other chunks.
3. After you add a chunk to the sbspace, the database server writes the
CHRESERV and CHKADJUP log records.
4. Perform a level-0 backup of the root dbspace and the sbspace.
5. Use onstat -d and oncheck -pe to monitor the amount of free space in the
sbspace chunk.
For more information, see “Monitoring Sbspaces” on page 11-39.

This example adds a 10-megabyte mirror chunk to sbsp4. An offset of 200

kilobytes for both the primary and mirror chunk is specified. If you are not adding
a mirror chunk, you can omit the -m option. The -U option specifies that the new
chunk will contain user data exclusively.
onspaces -a sbsp4 -p /dev/rawdev1 -o 200 -s 10240 -m /dev/rawdev2 200 -U

For more information, see “Adding a Chunk to a Dbspace or Blobspace” on page

11-16, and information on the onspaces utility in the IBM Informix Administrator's
Reference.

Altering Storage Characteristics of Smart Large Objects

Use the onspaces -ch command to change the following default storage
characteristics for the sbspace:
v Extent sizes
v Average smart-large-object size
v Buffering mode
v Last-access time
v Lock mode
v Logging

For more information, refer to “Storage Characteristics of Sbspaces” on page 10-15

and managing sbspaces in the chapter on table performance considerations in your
IBM Informix Dynamic Server Performance Guide.

11-24 IBM Informix Dynamic Server Administrator’s Guide

 Creating a Temporary Sbspace
For background information and the rules for determining where temporary smart
large objects are stored, see “Temporary Sbspaces” on page 10-19. You can store
temporary smart large objects in a standard or temporary sbspace. You can add or
drop chunks in a temporary sbspace.

To create a temporary sbspace with a temporary smart large object:

1. Allocate space for the temporary sbspace. For details, see “Allocating Disk
Space” on page 11-3.
For information on SBSPACETEMP, see the configuration parameters chapter in
the IBM Informix Administrator's Reference.
2. Create the temporary sbspace as the following example shows:
onspaces -c -S tempsbsp -t -p ./tempsbsp -o 0 -s 1000
You can specify any of the following onspaces options:
a. Specify a metadata area and offset (-Ms and -Mo).
b. Specify storage characteristics (-Df).
You cannot turn on logging for a temporary sbspace.
3. Set the SBSPACETEMP configuration parameter to the name of the default
temporary sbspace storage area.
Restart the database server.
4. Use onstat -d to display the temporary sbspace.
For an information on and an example of onstat -d output, see information on
the onstat utility in the IBM Informix Administrator's Reference.
5. Specify the LO_CREATE_TEMP flag when you create a temporary smart large
object.
Using DataBlade API:
mi_lo_specset_flags(lo_spec,LO_CREATE_TEMP);
Using ESQL/C:
ifx_lo_specset_flags(lo_spec,LO_CREATE_TEMP);

For information on creating smart large objects, see the IBM Informix DataBlade API
Programmer's Guide and IBM Informix ESQL/C Programmer's Manual.

Dropping a Chunk
Use onspaces or ISA to drop a chunk from a dbspace.

Before you drop a chunk, ensure that the database server is in the correct mode,
using the following table as a guideline.

Database Server in
Database Server in Single-User or Database Server in
Chunk Type Online Mode Quiescent Mode Offline Mode
Dbspace chunk Yes Yes No
Temporary dbspace chunk Yes Yes No
Blobspace chunk No Yes No
Sbspace or temporary Yes Yes No
sbspace chunk

Chapter 11. Managing Disk Space 11-25

 Verifying Whether a Chunk Is Empty
To drop a chunk successfully from a dbspace with either of these utilities, the
chunk must not contain any data. All pages other than overhead pages must be
freed.

If any pages remain allocated to nonoverhead entities, the utility returns the
following error:
Chunk is not empty.

In addition, when a dbspace consists of two or more chunks and the additional
chunks do not contain user data, the additional chunks cannot be deleted if the
chunks contain a tblspace tblspace.

If you receive the ″Chunk is not empty″ message, you must determine which table
or other entity still occupies space in the chunk by executing oncheck -pe to list
contents of the extent.

Usually, the pages can be removed when you drop the table that owns them. Then
reenter the utility command.

Dropping a Chunk from a Dbspace with onspaces

The following example drops a chunk from dbsp3 on UNIX. An offset of 300
kilobytes is specified.
onspaces -d dbsp3 -p /dev/raw_dev1 -o 300

You cannot drop the initial chunk of a dbspace with the syntax in the previous
example. Instead, you must drop the dbspace. Use the fchunk column of onstat -d
to determine which is the initial chunk of a dbspace. For more information about
onstat, see information on the onspaces utility in the IBM Informix Administrator's
Reference.

For information about dropping a chunk from a dbspace with onspaces, see the
IBM Informix Administrator's Reference.

Dropping a Chunk from a Blobspace

The procedure for dropping a chunk from a blobspace is identical to the procedure
for dropping a chunk from a dbspace described in “Dropping a Chunk from a
Dbspace with onspaces” on page 11-26 except that the database server must be in
quiescent or single-user mode. Other than this condition, you need only substitute
the name of your blobspace wherever a reference to a dbspace occurs.

Dropping a Chunk from an Sbspace with onspaces

The following example drops a chunk from sbsp3 on UNIX. An offset of 300
kilobytes is specified. The database server must be in online single-user, or
quiescent mode when you drop a chunk from an sbspace or temporary sbspace.
onspaces -d sbsp3 -p /dev/raw_dev1 -o 300

You cannot drop the initial chunk of an sbspace with the syntax in the previous
example. Instead, you must drop the sbspace. Use the fchunk column of onstat -d
to determine which chunk is the initial chunk of an sbspace.

11-26 IBM Informix Dynamic Server Administrator’s Guide

 Using the -f (Force) Option
You can use the -f option of onspaces to drop an sbspace chunk without metadata
allocated in it. If the chunk contains metadata for the sbspace, you must drop the
entire sbspace. Use the Chunks section of onstat -d to determine which sbspace
chunks contain metadata.
onspaces -d sbsp3 -f

Warning: If you force the drop of an sbspace, you might introduce consistency
problems between tables and sbspaces.

Deleting Smart Large Objects Without any Pointers

Each smart large object has a reference count, the number of pointers to the smart
large object. When the reference count is greater than 0, the database server
assumes that the smart large object is in use and does not delete it.

Rarely, a smart large object with a reference count of 0 remains. You can use the
onspaces -cl command to delete all smart large objects that have a reference count
of 0, if it is not open by any application.

For information on using onspaces -cl, see information on the onspaces utility in
the IBM Informix Administrator's Reference.

Dropping a Storage Space

Use onspaces, ISA, or ON–Monitor to drop a dbspace, temporary dbspace,
blobspace, sbspace, temporary sbspace, or extspace.

On UNIX, you must be logged in as root or informix to drop a storage space. On

Windows, you must be a member of the Informix-Admin group to drop a storage
space.

You can drop a storage space only when the database server is in online,
single-user, or quiescent mode.

Preparing to Drop a Storage Space

Before you drop a dbspace, you must first drop all databases and tables that you
previously created in that dbspace. You cannot drop the root dbspace.

Before you drop a blobspace, you must drop all tables that have a TEXT or BYTE
column that references the blobspace.

Execute oncheck -pe to verify that no tables or log files reside in the dbspace or
blobspace.

Before you drop an sbspace, you must drop all tables that have a CLOB or BLOB
column that reference objects that are stored in the sbspace. For sbspaces, you need
not delete columns that point to an sbspace, but these columns must be null; that
is, all smart large objects must be deallocated from the sbspace.

Tip: If you drop tables on dbspaces where light appends are occurring, the light
appends might be slower than you expect. The symptom of this problem is
physical logging activity. If light appends are slower than you expect, make
sure that no tables are dropped in the dbspace either before or during the
light appends. If you have dropped tables, force a checkpoint with onmode -c
before you perform the light append.

Chapter 11. Managing Disk Space 11-27

 Dropping a Mirrored Storage Space
If you drop a storage space that is mirrored, the mirror spaces are also dropped.

If you want to drop only a storage-space mirror, turn off mirroring. (See “Ending
Mirroring” on page 19-7.) This action drops the dbspace, blobspace, or sbspace
mirrors and frees the chunks for other uses.

Dropping a Storage Space with onspaces

To drop a storage space with onspaces, use the -d option as illustrated in the
following examples.

This example drops a dbspace called dbspce5 and its mirrors.

onspaces -d dbspce5

This example drops a dbspace called blobsp3 and its mirrors.

onspaces -d blobsp3

Use the -d option with the -f option if you want to drop an sbspace that contains
data. If you omit the -f option, you cannot drop an sbspace that contains data. This
example drops an sbspace called sbspc4 and its mirrors.
onspaces -d sbspc4 -f

Warning: If you use the -f option, the tables in the database server might have
dead pointers to the deleted smart large objects.

For information on dropping a storage space with onspaces, see information on the
onspaces utility in the IBM Informix Administrator's Reference.

Dropping a Dbspace or Blobspace with ON-Monitor (UNIX)

To drop a dbspace or blobspace with ON–Monitor, follow these instructions:
1. Select the Dbspaces > Drop option.
2. Use RETURN or arrow keys to scroll to the dbspace or blobspace that you want
to drop.
3. Press CTRL-B or F3.

You are asked to confirm that you want to drop the dbspace or blobspace.

Backing Up After Dropping a Storage Space

If you create a storage space with the same name as the deleted storage space,
perform another level-0 backup to ensure that future restores do not confuse the
new storage space with the old one. For more information, see the IBM Informix
Backup and Restore Guide.

Warning: After you drop a dbspace, blobspace, or sbspace, the newly freed chunks
are available for reassignment to other dbspaces, blobspaces, or sbspaces.
However, before you reassign the newly freed chunks, you must
perform a level-0 backup of the root dbspace and the modified storage
space. If you do not perform this backup, and you subsequently need to
perform a restore, the restore might fail because the backup reserved
pages are not up-to-date.

11-28 IBM Informix Dynamic Server Administrator’s Guide

Managing Extspaces
An extspace does not require allocation of disk space. You create and drop
extspaces using the onspaces utility. For more information about extspaces, refer to
“Extspaces” on page 10-21.

Creating an Extspace
You create an extspace with the onspaces utility. But you should first have a valid
data source and a valid access method with which to access that data source.
Although you can create an extspace without a valid access method or a valid data
source, any attempts to retrieve data from the extspace will generate an error. For
information on access methods, see the IBM Informix Virtual-Table Interface
Programmer's Guide.

To create an extspace with onspaces, use the -c option as illustrated in the

following example. The following example shows how to create an extspace,
pass_space, that is associated with the UNIX password file.
onspaces -c -x pass_space -l /etc/passwd

Specify an extspace name of up to 128 bytes. The name must be unique and begin
with a letter or underscore. You can use letters, digits, underscores, and $
characters in the name.

Important: The preceding example assumes that you have coded a routine that
provides functions for correctly accessing the file passwd and that the
file itself exists. After you have created the extspace, you must use the
appropriate commands to allow access to the data in the file passwd.
For more information on user-defined access methods, see the IBM
Informix Virtual-Table Interface Programmer's Guide.

For reference information on creating an extspace with onspaces, see information

on the onspaces utility in the IBM Informix Administrator's Reference.

Dropping an Extspace
To drop an extspace with onspaces, use the -d option as illustrated in the following
examples. An extspace cannot be dropped if it is associated with an existing table
or index.

This example drops an extspace called pass_space.

onspaces -d pass_space

Skipping Inaccessible Fragments

One benefit that fragmentation provides is the ability to skip table fragments that
are unavailable during an I/O operation. For example, a query can proceed even
when a fragment is located on a chunk that is currently down as a result of a disk
failure. When this situation occurs, a disk failure affects only a portion of the data
in the fragmented table. By contrast, tables that are not fragmented can become
completely inaccessible if they are located on a disk that fails.

This functionality is controlled as follows:

v By the database server administrator with the DATASKIP configuration
parameter
v By individual applications with the SET DATASKIP statement

Chapter 11. Managing Disk Space 11-29

 Using the DATASKIP Configuration Parameter
You can set the DATASKIP parameter to OFF, ALL, or ON dbspace_list. OFF means
that the database server does not skip any fragments. If a fragment is unavailable,
the query returns an error. ALL indicates that any unavailable fragment is skipped.
ON dbspace_list instructs the database server to skip any fragments that are located
in the specified dbspaces.

Using the Dataskip Feature of onspaces

Use the dataskip feature of the onspaces utility to specify the dbspaces that are to
be skipped when they are unavailable. For example, the following command sets
the DATASKIP parameter so that the database server skips the fragments in
dbspace1 and dbspace3, but not in dbspace2:
onspaces -f ON dbspace1 dbspace3

For the complete syntax of this onspaces option, see information on the onspaces
utility in the IBM Informix Administrator's Reference.

Using onstat to Check Dataskip Status

Use the onstat utility to list the dbspaces currently affected by the dataskip feature.
The -f option lists both the dbspaces that were set with the DATASKIP
configuration parameter and the -f option of the onspaces utility.

When you execute onstat -f, you receive a message that tells you whether the
DATASKIP configuration parameter is set to on for all dbspaces, off for all
dbspaces, or on for specific dbspaces.

Using the SQL Statement SET DATASKIP

An application can use the SQL statement SET DATASKIP to control whether a
fragment should be skipped if it is unavailable. Applications should include this
statement only in limited circumstances, because it causes queries to return
different results, depending on the availability of the underlying fragments. Like
the configuration parameter DATASKIP, the SET DATASKIP statement accepts a
list of dbspaces that indicate to the database server which fragments to skip. For
example, suppose that an application programmer included the following
statement at the beginning of an application:
SET DATASKIP ON dbspace1, dbspace5

This statement causes the database server to skip dbspace1 or dbspace5 whenever
both of these conditions are met:
v The application attempts to access one of the dbspaces.
v The database server finds that one of the dbspaces is unavailable.

If the database server finds that both dbspace1 and dbspace5 are unavailable, it
skips both dbspaces.

The DEFAULT setting for the SET DATASKIP statement allows a database server
administrator to control the dataskip feature. Suppose that an application
developer includes the following statement in an application:
SET DATASKIP DEFAULT

When a query is executed subsequent to this SQL statement, the database server
checks the value of the configuration parameter DATASKIP. Encouraging end users
to use this setting allows the database server administrator to specify which

11-30 IBM Informix Dynamic Server Administrator’s Guide

 dbspaces are to be skipped as soon as the database server administrator becomes
aware that one or more dbspaces are unavailable.

Effect of the Dataskip Feature on Transactions

If you turn the dataskip feature on, a SELECT statement always executes. In
addition, an INSERT statement always succeeds if the table is fragmented by
round-robin and at least one fragment is online. However, the database server does
not complete operations that write to the database if a possibility exists that such
operations might compromise the integrity of the database. The following
operations fail:
v All UPDATE and DELETE operations where the database server cannot
eliminate the down fragments
If the database server can eliminate the down fragments, the update or delete is
successful, but this outcome is independent of the DATASKIP setting.
v An INSERT operation for a table fragmented according to an expression-based
distribution scheme where the appropriate fragment is down
v Any operation that involves referential constraint checking if the constraint
involves data in a down fragment
For example, if an application deletes a row that has child rows, the child rows
must also be available for deletion.
v Any operation that affects an index value (for example, updates to a column that
is indexed) where the index in question is located in a down chunk

Determining When to Use Dataskip

Use this feature sparingly and with caution because the results are always suspect.
Consider using it in the following situations:
v You can accept the compromised integrity of transactions.
v You can determine that the integrity of the transaction is not compromised.

The latter task can be difficult and time consuming.

Determining When to Skip Selected Fragments

In certain circumstances, you might want the database server to skip some
fragments, but not others. This usually occurs in the following situations:
v Fragments can be skipped because they do not contribute significantly to a
query result.
v Certain fragments are down, and you decide that skipping these fragments and
returning a limited amount of data is preferable to canceling a query.

When you want to skip fragments, use the ON dbspace-list setting to specify a list
of dbspaces with the fragments that the database server should skip.

Determining When to Skip All Fragments

Setting the DATASKIP configuration parameter to ALL causes the database server
to skip all unavailable fragments. Use this option with caution. If a dbspace
becomes unavailable, all queries initiated by applications that do not issue a SET
DATASKIP OFF statement before they execute could be subject to errors.

Monitoring Fragmentation Use

The database administrator might find the following aspects of fragmentation
useful to monitor:
v Data distribution over fragments

Chapter 11. Managing Disk Space 11-31

 v I/O request balancing over fragments
v The status of chunks that contain fragments

The administrator can monitor the distribution of data over table fragments. If the
goal of fragmentation is improved single-user response time, it is important for
data to be distributed evenly over the fragments. To monitor fragmentation disk
use, you must monitor database server tblspaces, because the unit of disk storage
for a fragment is a tblspace. (For information on how to monitor the data
distribution for a fragmented table, see “Monitoring Tblspaces and Extents” on
page 11-36.)

The administrator must monitor I/O request queues for data that is contained in
fragments. When I/O queues become unbalanced, the administrator should work
with the DBA to tune the fragmentation strategy. (For a discussion of how to
monitor chunk use, including the I/O queues for each chunk, see “Monitoring
Chunks” on page 11-33.)

The administrator must monitor fragments for availability and take appropriate
steps when a dbspace that contains one or more fragments fails. For how to
determine if a chunk is down, see “Monitoring Chunks” on page 11-33.

Displaying Databases
You can display databases that you create with the following tools:
v SMI tables
v ISA
v ON–Monitor

Using SMI Tables

Query the sysdatabases table to display a row for each database managed by the
database server. For a description of the columns in this table, see the sysdatabases
information in the chapter about the sysmaster database in the IBM Informix
Administrator's Reference.

Using ISA
To query sysdatabases using ISA, follow these steps:
1. Choose SQL > Query.
2. Select the sysmaster data in the Database list.
3. Enter the following command and click Submit:
select * from sysdatabases;

Using ON-Monitor (UNIX)

To use ON–Monitor to find the current status of each database, select the Status >
Databases option. ON–Monitor can only display up to 100 databases. If you have
more than 100 databases on your database server, use the SMI tables to display the
full list, as described in the previous section.

Monitoring Disk Usage

This section describes methods of tracking the disk space used by various database
server storage units.

11-32 IBM Informix Dynamic Server Administrator’s Guide

 For background information about internal database server storage units
mentioned in this section, see the chapter about disk structures and storage in the
IBM Informix Administrator's Reference.

Monitoring Chunks
You can monitor chunks for the following information:
v Chunk size
v Number of free pages
v Tables within the chunk

This information allows you to track the disk space used by chunks, monitor
chunk I/O activity, and check for fragmentation.

onstat -d
The onstat -d utility lists all dbspaces, blobspaces, and sbspaces and the following
information for the chunks within those spaces.
v The address of the chunk
v The chunk number and associated dbspace number
v The offset into the device (in pages)
v The size of the chunk (in pages)
v The number of free pages in the chunk
v The pathname of the physical device

If you issue the onstat -d command on an instance with blobspace chunks, the
number of free pages shown is out of date. The tilde (~) that precedes the free
value indicates that this number is approximate. The onstat -d command does not
register a blobpage as available until the logical log in which a deletion occurred is
backed up and the blobpage is freed. Therefore, if you delete 25 simple large
objects and immediately execute onstat -d, the newly freed space does not appear
in the onstat output.

To obtain an accurate number of free blobpages in a blobspace chunk, issue the

onstat -d update command. For details, see “onstat -d update” on page 11-33.

In onstat -d update output, the flags column in the chunk section provides the
following information:
v Whether the chunk is the primary chunk or the mirror chunk
v Whether the chunk is online, is down, is being recovered, or is a new chunk

For an example of onstat -d output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

Important: You must perform a level-0 backup of the root dbspace and the
modified dbspace before mirroring can become active and after turning
off mirroring.

onstat -d update
The onstat -d update option displays the same information as onstat -d and an
accurate number of free blobpages for each blobspace chunk.

onstat -D
The onstat -D option displays the same information as onstat -d, plus the number
of pages read from the chunk (in the page Rd field).

Chapter 11. Managing Disk Space 11-33

 onstat -g iof
The onstat -g iof option displays the number of reads from each chunk and the
number of writes to each chunk. If one chunk has a disproportionate amount of
I/O activity against it, this chunk might be a system bottleneck. This option is
useful for monitoring the distribution of I/O requests against the different
fragments of a fragmented table.

For an example of onstat -g iof output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

oncheck -pr
The database server stores chunk information in the reserved pages
PAGE_1PCHUNK and PAGE_2PCHUNK.

To list the contents of the reserve pages, execute oncheck -pr. Figure 11-1 shows
sample output for oncheck -pr. This output is essentially the same as the onstat -d
output; however, if the chunk information has changed since the last checkpoint,
these changes do not appear in the oncheck -pr output.

Validating PAGE_1DBSP & PAGE_2DBSP...

Using dbspace page PAGE_2DBSP.

DBspace number 1
DBspace name rootdbs
Flags 0x20001 No mirror chunks
Number of chunks 2
First chunk 1
Date/Time created 07/28/2000 14:46:55
Partition table page number 14
Logical Log Unique Id 0
Logical Log Position 0
Oldest Logical Log Unique Id 0
Last Logical Log Unique Id 0
Dbspace archive status No archives have occurred
.
.
Validating PAGE_1PCHUNK & PAGE_2PCHUNK...
Using primary chunk page PAGE_2PCHUNK.

Chunk number 1
Flags 0x40 Chunk is online
Chunk path /home/server/root_chunk
Chunk offset 0 (p)
Chunk size 75000 (p)
Number of free pages 40502
DBSpace number 1
.
.
.

Figure 11-1. oncheck -pr Output Showing Dbspace and Chunk Information

oncheck -pe
To obtain the physical layout of information in the chunk, execute oncheck -pe.
The dbspaces, blobspaces, and sbspaces are listed. Figure 11-2 on page 11-35 shows
sample output for oncheck -pe.

The following information is displayed:

v The name, owner, and creation date of the dbspace
v The size in pages of the chunk, the number of pages used, and the number of
pages free

11-34 IBM Informix Dynamic Server Administrator’s Guide

v A listing of all the tables in the chunk, with the initial page number and the
length of the table in pages

The tables within a chunk are listed sequentially. This output is useful for
determining chunk fragmentation. If the database server is unable to allocate an
extent in a chunk despite an adequate number of free pages, the chunk might be
badly fragmented.

DBSpace Usage Report: rootdbs Owner: informix Created: 08/08/2000

Chunk Pathname Size Used Free

1 /home/server/root_chunk 75000 19420 55580

Description Offset Size

------------------------------------------- --------------------
RESERVED PAGES 0 12
CHUNK FREELIST PAGE 12 1
rootdbs:’informix’.TBLSpace 13 250
PHYSICAL LOG 263 1000
FREE 1263 1500
LOGICAL LOG: Log file 2 2763 1500
LOGICAL LOG: Log file 3 4263 1500
...
sysmaster:’informix’.sysdatabases 10263 4
sysmaster:’informix’.systables 10267 8
...

Chunk Pathname Size Used Free

2 /home/server/dbspace1 5000 53 4947

Description Offset Size

------------------------------------------- --------------------
RESERVED PAGES 0 2
CHUNK FREELIST PAGE 2 1
dbspace1:’informix’.TBLSpace 3 50
FREE 53 4947

Figure 11-2. oncheck -pe Output

Using IBM Informix Server Administrator

You can perform the following tasks using ISA commands:
v Check reserved pages.
v Check storage spaces.
v Add dbspaces, temporary dbspaces, blobspaces, temporary sbspaces, and
sbspaces.
v Display and add chunks to a storage space.
v Check the dataskip status.
v Display and add external spaces.
v Display the number of pages in your database, percentage of allocated space,
and used space.
v Override ONDBSPACEDOWN.

Using ON-Monitor (UNIX)

You can perform the following tasks using ON–Monitor commands.
ON_Monitor Command Description
Status > Spaces Displays status information about storage spaces
and chunks
Dbspaces > Create Creates a dbspace
Dbspaces > BLOBSpace Creates a blobspace

Chapter 11. Managing Disk Space 11-35

 Dbspaces > Mirror Adds or drops mirroring for a storage space
Dbspaces > Info Displays information about storage spaces
Dbspaces > Add Chunk Adds a chunk to a storage space
Dbspaces > dataSkip Starts or stops dataskip
Dbspaces > Chunk Adds a chunk to a dbspace or blobspace
Dbspaces > Drop Drops a dbspace or blobspace
Dbspaces > Status Changes the mirror status of a chunk

Using SMI Tables

Query the syschunks table to obtain the status of a chunk. The following columns
are relevant.
Column Description
chknum Number of the chunk within the dbspace
dbsnum Number of the dbspace
chksize Total size of the chunk in pages
nfree Number of pages that are free
is_offline Whether the chunk is down
is_recovering Whether the chunk is recovering
mis_offline Whether the mirror chunk is down
mis_recovering Whether the mirror chunk is being recovered

The syschkio table contains the following columns.

Column Description
pagesread Number of pages read from the chunk
pageswritten Number of pages written to the chunk

Monitoring Tblspaces and Extents

Monitor tblspaces and extents to determine disk usage by database, table, or table
fragment. Monitoring disk usage by table is particularly important when you are
using table fragmentation, and you want to ensure that table data and table index
data are distributed appropriately over the fragments.

Execute oncheck -pt to obtain extent information. The oncheck -pT option returns
all the information from the oncheck -pt option as well as the additional
information about page and index usage.

Using SMI Tables

Query the systabnames table to obtain information about each tblspace. The
systabnames table has columns that indicate the corresponding table, database,
and table owner for each tblspace.

Query the sysextents table to obtain information about each extent. The sysextents
table has columns that indicate the database and the table that the extent belongs
to, as well as the physical address and size of the extent.

11-36 IBM Informix Dynamic Server Administrator’s Guide

Monitoring Simple Large Objects in a Blobspace
Monitor blobspaces to determine the available space and whether the blobpage
size is optimal.

onstat -O
The onstat -O option displays information about the staging-area blobspace and
the Optical Subsystem memory cache. The totals shown in the display accumulate
from session to session. The database server resets the totals to 0 only when you
execute onstat -z.

For an example of onstat -O output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

The first section of the display describes the following system-cache totals
information.
Column Description
size Size specified in the OPCACHEMAX configuration parameter
alloc Number of 1-kilobyte pieces that the database server allocated to
the cache
avail Portion of alloc (in kilobytes) not used
number Number of simple large objects that the database server
successfully put into the cache without overflowing
kbytes Number of kilobytes of the simple large objects that the database
server put into the cache without overflowing
number Number of simple large objects that the database server wrote to
the staging-area blobspace
kbytes Number of kilobytes of simple large objects that the database
server wrote to the staging-area blobspace

Although the size output indicates the amount of memory that is specified in the
configuration parameter OPCACHEMAX, the database server does not allocate
memory to OPCACHEMAX until necessary. Therefore, the alloc output reflects
only the number of 1-kilobyte pieces of the largest simple large object that has
been processed. When the values in the alloc and avail output are equal, the cache
is empty.

The second section of the display describes the following user-cache totals
information.
Column Description
SID Session ID for the user
user User ID of the client
size Size specified in the INFORMIXOPCACHE environment variable,
if set
If you do not set the INFORMIXOPCACHE environment variable,
the database server uses the size that you specify in the
configuration parameter OPCACHEMAX.
number Number of simple large objects that the database server put into
cache without overflowing

Chapter 11. Managing Disk Space 11-37

 kbytes Number of kilobytes of simple large objects that the database
server put into the cache without overflowing
number Number of simple large objects that the database server wrote to
the staging-area blobspace
kbytes Size of the simple large objects (in kilobytes) that the database
server wrote to the staging-area blobspace

Determining Blobpage Fullness with oncheck -pB

The oncheck -pB command displays statistics that describe the average fullness of
blobpages. If you find that the statistics for a significant number of simple large
objects show a low percentage of fullness, the database server might benefit from
changing the size of the blobpage in the blobspace.

Execute oncheck -pB with either a database name or a table name as a parameter.
The following example retrieves storage information for all simple large objects
stored in the table [Link] in the stores_demo database:
oncheck -pB stores_demo:[Link]

For detailed information about interpreting the oncheck -pB output, see optimizing
blobspace blobpage size in the chapter on table performance considerations in the
IBM Informix Dynamic Server Performance Guide.

Monitoring Blobspace Usage with oncheck -pe

The oncheck -pe command provides information about blobspace usage:
v Names of the tables that store TEXT and BYTE data, by chunk
v Number of disk pages (not blobpages) used, by table
v Number of free disk pages remaining, by chunk
v Number of overhead pages used, by chunk

Figure 11-3 shows sample oncheck -pe output.

BLOBSpace Usage Report: fstblob Owner:informix Created: 03/01/99

Chunk: 3 /home/server/blob_chunk Size Used Free
4000 304 3696
Disk usage for Chunk 3 Total Pages
------------------------------------------------------
OVERHEAD 8
stores_demo:[Link] 296
FREE 3696

Figure 11-3. oncheck -pe Output That Shows Blobspace Use

Monitoring Simple Large Objects in a Dbspace with oncheck -pT

Use oncheck -pT to monitor dbspaces to determine the number of dbspace pages
that TEXT and BYTE data use.

This command takes a database name or a table name as a parameter. For each
table in the database, or for the specified table, the database server displays a
general tblspace report.

Following the general report is a detailed breakdown of page use in the extent, by
page type. See the Type column for information on TEXT and BYTE data.

11-38 IBM Informix Dynamic Server Administrator’s Guide

 The database server can store more than one simple large object on the same
blobpage. Therefore, you can count the number of pages that store TEXT or BYTE
data in the tblspace, but you cannot estimate the number of simple large objects in
the table.

Figure 11-4 shows sample output.

TBLSpace Usage Report for mydemo:[Link]

Type Pages Empty Semi-Full Full Very-Full

---------------- ---------- ---------- ---------- ---------- ----------
Free 7
Bit-Map 1
Index 2
Data (Home) 9
Data (Remainder) 0 0 0 0 0
Tblspace BLOBs 5 0 0 1 4
----------
Total Pages 24

Unused Space Summary

Unused data bytes in Home pages 3564

Unused data bytes in Remainder pages 0
Unused bytes in Tblspace Blob pages 1430

Index Usage Report for index 111_16 on mydemo:[Link]

Average Average
Level Total No. Keys Free Bytes
----- -------- -------- ----------
1 1 74 1058
----- -------- -------- ----------
Total 1 74 1058

Index Usage Report for index 111_18 on mydemo:[Link]

Average Average
Level Total No. Keys Free Bytes
----- -------- -------- ----------
1 1 74 984
----- -------- -------- ----------
Total 1 74 984

Figure 11-4. Sample output from oncheck -pT with TEXT or BYTE data

Monitoring Sbspaces
One of the most important areas to monitor in an sbspace is the metadata page
use. When you create an sbspace, you specify the size of the metadata area. Also,
any time that you add a chunk to the sbspace, you can specify that metadata space
be added to the chunk.

If you attempt to insert a new smart large object, but no metadata space is
available, you receive an error. The administrator should monitor metadata space
availability to prevent this situation from occurring.

Use the following commands to monitor sbspaces.

Chapter 11. Managing Disk Space 11-39

Command Description
onstat -g smb s Displays the storage attributes for all sbspaces in the system:
v sbspace name, flags, owner
v logging status
v average smart-large-object size
v first extent size, next extent size, and minimum extent size
v maximum I/O access time
v lock mode
onstat -g smb c Displays for each sbspace chunk the following:
v chunk number and sbspace name
v chunk size and pathname
v total user data pages and free user data pages
v location and number of pages in each user-data and metadata areas

See “Using onstat -g smb c” on page 11-44.

oncheck -ce Displays the following information about sbspace use:
oncheck -pe v Names of the tables that store smart-large-object data, by chunk
v Number of disk pages (not sbpages) used, by table
v Number of free user-data pages that remain, by chunk
v Number of reserved user-data pages that remain, by chunk
v Number of metadata pages used, by chunk

The output provides the following totals:

v Total number of used pages for all user-data areas and metadata area. The system adds 53
pages for the reserved area to the totals for the user-data area and metadata area.
v Number of free pages that remain in the metadata area
v Number of free pages that remain in all user-data areas

See “Using oncheck -ce and oncheck -pe” on page 11-41 and “Monitoring the Metadata and
User-Data Areas” on page 11-43.
onstat -d Displays the following information about the chunks in each sbspace:
v Number of free sbpages in each sbspace chunk, in the metadata area, and in the user-data
areas
v Total number of sbpages in each sbspace chunk, in the metadata area, and in the user-data
areas

See “Using onstat -d,” following.

oncheck -cs Validates and displays information about the metadata areas for sbspaces. See “Using oncheck
oncheck -ps -cs” on page 11-42 and “Using oncheck -ps” on page 11-42.
oncheck -cS Displays information about smart-large-object extents and user-data areas for sbspaces.
oncheck -pS Displays information about smart-large-object extents, user-data areas, and metadata areas for
sbspaces. For more information on oncheck -cS and -pS, see managing sbspaces in the chapter
on table performance considerations in your IBM Informix Dynamic Server Performance Guide.

Using onstat -d
Use the onstat -d option to display the following information about the chunks in
each sbspace:
v Number of free sbpages in each sbspace chunk, in the metadata area, and in the
user-data area
v Total number of sbpages in each sbspace chunk, in the metadata area, and in the
user-data area

11-40 IBM Informix Dynamic Server Administrator’s Guide

For an example of onstat -d output, see information on the onstat utility in the
IBM Informix Administrator's Reference.

To find out the total amount of used space, execute the oncheck -pe command. For
more information, see “Using oncheck -ce and oncheck -pe” on page 11-41.

The onstat -d option does not register an sbpage as available until the logical log
in which a deletion occurred is backed up and the sbpage is freed. Therefore, if
you delete 25 smart large objects and immediately execute onstat -d, the newly
freed space does not appear in the onstat output.

Using oncheck -ce and oncheck -pe

Execute oncheck -ce to display the size of each sbspace chunk, the total amount of
used space, and the amount of free space in the user-data area. The oncheck -pe
option displays the same information as oncheck -ce plus a detailed listing of
chunk use. First the dbspaces are listed and then the sbspaces. The -pe output
provides the following information about sbspace use:
v Names of the tables that store smart-large-object data, by chunk
v Number of disk pages (not sbpages) used, by table
v Number of free user-data pages that remain, by chunk
v Number of metadata pages used, by chunk

The output provides the following totals:

v Total number of used pages for the user-data area, metadata area, and reserved
area
The system adds an extra 53 pages for the reserved area to the totals for the
user-data area and metadata area.
v Number of free pages that remain in the metadata area
v Number of free pages that remain in the user-data area

Tip: The oncheck -pe option provides information about sbspace use in terms of
database server pages, not sbpages.

Figure 11-5 shows sample output. In this example, the sbspace s9_sbspc has a total
of 214 used pages, 60 free pages in the metadata area, and 726 free pages in the
user-data area.

Chapter 11. Managing Disk Space 11-41

 Chunk Pathname Size Used Free
2 /ix/ids9.2/./s9_sbspc 1000 940 60

Description Offset Size

-------------------------------------------------- -------- --------
RESERVED PAGES 0 2
CHUNK FREELIST PAGE 2 1
s9_sbspc:’informix’.TBLSpace 3 50
SBLOBSpace LO [2,2,1] 53 8
SBLOBSpace LO [2,2,2] 61 1
...
SBLOBSpace LO [2,2,79] 168 1
SBLOBSpace FREE USER DATA 169 305
s9_sbspc:’informix’.sbspace_desc 474 4
s9_sbspc:’informix’.chunk_adjunc 478 4
s9_sbspc:’informix’.LO_hdr_partn 482 8
s9_sbspc:’informix’.LO_ud_free 490 5
s9_sbspc:’informix’.LO_hdr_partn 495 24
FREE 519 60
SBLOBSpace FREE USER DATA 579 421

Total Used: 214

Total SBLOBSpace FREE META DATA: 60
Total SBLOBSpace FREE USER DATA: 726

Figure 11-5. oncheck -pe Output That Shows Sbspace Use

Using oncheck -cs

The oncheck -cs and the oncheck -Cs options validate the metadata area of an
sbspace. Figure 11-6 shows an example of the -cs output for s9_sbspc. If you do
not specify an sbspace name on the command line, oncheck checks and displays
the metadata for all sbspaces.

Use the oncheck -cs output to see how much space is left in the metadata area. If
it is full, allocate another chunk with adequate space for the metadata area. To find
the number of used pages in the metadata area, total the numbers in the Used
column. To find the number of free pages in the metadata area, total the numbers
in the Free column.

For example, based on the field values displayed in Figure 11-6, the total number
of used pages in the metadata area for s9_sbspc is 33 two-kilobyte pages (or 66
kilobytes). The metadata area contains a total of 62 free pages (or 124 kilobytes).

Validating space ’s9_sbspc’ ...

SBLOBspace Metadata Partition Partnum Used Free

s9_sbspc:’informix’.TBLSpace 0x200001 6 44
s9_sbspc:’informix’.sbspace_desc 0x200002 2 2
s9_sbspc:’informix’.chunk_adjunc 0x200003 2 2
s9_sbspc:’informix’.LO_hdr_partn 0x200004 21 11
s9_sbspc:’informix’.LO_ud_free 0x200005 2 3

Figure 11-6. oncheck -cs Output

Using oncheck -ps

The oncheck -ps option validates and displays information about the metadata
areas in sbspace partitions. Figure 11-7 on page 11-43 shows an example of the -ps
output for s9_sbspc. If you do not specify an sbspace name on the command line,
oncheck validates and displays tblspace information for all storage spaces.

To monitor the amount of free metadata space, run the following command:
oncheck -ps spacename

11-42 IBM Informix Dynamic Server Administrator’s Guide

The -ps output includes information about the locking granularity, partnum,
number of pages allocated and used, extent size, and number of rows in the
metadata area. Use the oncheck -ps output to see how much space is left in the
metadata area. If it is full, allocate another chunk with adequate space for the
metadata area.

If you run oncheck -ps for the dbspace that contains the tables where the smart
large objects are stored, you can find the number of rows in the table.

Validating space ’s9_sbspc’ ...

TBLSpace Report for

TBLspace Flags 2801 Page Locking
TBLspace use 4 bit bit-maps
Permanent System TBLspace

Partition partnum 0x200001

Number of rows 92
Number of special columns 0
Number of keys 0
Number of extents 1
Current serial value 1
First extent size 50
Next extent size 50
Number of pages allocated 50
Number of pages used 6
Number of data pages 0
Number of rows 0
Partition lockid 2097153
Optical Cluster Partnum -1
Current SERIAL8 value 1
Current REFID value 1
Created Thu Jun 25 14:14:33 1999

Figure 11-7. oncheck -ps Output

Monitoring the Metadata and User-Data Areas

The database server reserves 40 percent of the user-data area as a reserved area. The
database server uses this reserved space for either the metadata or user data. The
metadata area gets used up as smart large objects are added to that sbspace. When
the database server runs out of metadata or user-data space, it moves a block of
the reserved space to the corresponding area.

When all of the reserve area is used up, the database server cannot move space to
the metadata area, even if the user-data area contains free space.
1. As you add smart large objects to the sbspace, use oncheck -pe or onstat -g
smb c to monitor the space in the metadata area, user-data area, and reserved
area. For an example, see “Using oncheck -ce and oncheck -pe” on page 11-41.
2. Use the message log to monitor metadata stealing.
The database server prints messages about the number of pages allocated from
the reserved area to the metadata area.
3. Add another chunk to the sbspace before the sbspace runs out of space in the
metadata and reserved areas.
For more information, see “Adding a Chunk to an Sbspace” on page 11-23.
4. The database server writes the FREE_RE and CHKADJUP log records when it
moves space from the reserve area to the metadata or user-data area.

For more information, see “Sizing Sbspace Metadata” on page 11-23.

Chapter 11. Managing Disk Space 11-43

 Using onstat -g smb c
Use the onstat -g smb c option to monitor the amount of free space in each
sbspace chunk, and the size in pages of the user-data, metadata, and reserved
areas.

The output of this command shows the number of used pages (usr pgs) and free
pages (free pg) in an sbspace chunk. The metadata area Md area includes
information that shows the starting page offset and the number of pages.

Loading Data Into a Table

You can load data into an existing table in the following ways.

Method to Load Data TEXT or BYTE Data CLOB or BLOB Data Reference
DB–Access LOAD statement Yes Yes LOAD statement in the IBM
Informix Guide to SQL: Syntax
dbload utility Yes Yes IBM Informix Migration Guide
dbimport utility Yes Yes IBM Informix Migration Guide
ESQL/C programs Yes Yes IBM Informix ESQL/C Programmer's
Manual
onload utility No No IBM Informix Migration Guide
onpladm utility Yes, deluxe mode Yes, deluxe mode IBM Informix Server
Administrator
High-Performance Loader (HPL) Yes, deluxe mode Yes, deluxe mode IBM Informix High-Performance
Loader User's Guide

Important: The database server does not contain any mechanisms for compressing
TEXT and BYTE data after the data has been loaded into a database.

11-44 IBM Informix Dynamic Server Administrator’s Guide

Part 3. Logging and Log Administration

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
Chapter 12. Logging
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Database Server Processes That Require Logging . . . . . . . . . . . . . . . . . . . . . . 12-1
Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Logging of SQL Statements and Database Server Activity . . . . . . . . . . . . . . . . . . . 12-3
Activity That is Always Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Activity Logged for Databases with Transaction Logging . . . . . . . . . . . . . . . . . . 12-4
Activity That is Not Logged . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Database-Logging Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Unbuffered Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Buffered Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
ANSI-Compliant Transaction Logging . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
No Database Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Databases with Different Log-Buffering Status . . . . . . . . . . . . . . . . . . . . . . 12-6
Database Logging in an X/Open DTP Environment . . . . . . . . . . . . . . . . . . . . 12-7
Settings or Changes for Logging Status or Mode . . . . . . . . . . . . . . . . . . . . . . 12-7

In This Chapter
This chapter describes logging of Informix databases and addresses the following
questions:
v Which database server processes require logging?
v What is transaction logging?
v What database server activity is logged?
v What is the database-logging status?
v Who can set or change the database logging status?

All the databases managed by a single database server instance store their log
records in the same logical log, regardless of whether they use transaction logging.
Most database users might be concerned with whether transaction logging is
buffered or whether a table uses logging.

If you want to change the database-logging status, see “Settings or Changes for
Logging Status or Mode” on page 12-7.

Database Server Processes That Require Logging

As Dynamic Server operates, processing transactions, tracking data storage, and
ensuring data consistency, Dynamic Server automatically generates logical-log
records for some of the actions that it takes. Most of the time the database server
makes no further use of the logical-log records. However, when the database server
needs to roll back a transaction, to execute a fast recovery after a system failure,
for example, the logical-log records are critical. The logical-log records are at the
heart of the data-recovery mechanisms.

The database server stores the logical-log records in a logical log. The logical log is
made up of logical-log files that the database server manages on disk until they
have been safely transferred offline (backed up). The database server administrator
keeps the backed up logical-log files until they are needed during a data restore, or
until the administrator decides that the records are no longer needed for a restore.
See Chapter 14, “Logical Log,” on page 14-1 for more information on logical logs.

© Copyright IBM Corp. 1996, 2005 12-1

 The logical-log records themselves are variable length. This arrangement increases
the number of logical-log records that can be written to a page in the logical-log
buffer. However, the database server often flushes the logical-log buffer before the
page is full. For more information on the format of logical-log records, see the
chapter on interpreting logical-log records in the IBM Informix Administrator's
Reference.

The database server uses logical-log records when it performs various functions
that recover data and ensure data consistency, as follows:
v Transaction rollback. If a database is using transaction logging and a transaction
must be rolled back, the database server uses the logical-log records to reverse
the changes made during the transaction. For more information, see “Transaction
Logging” on page 12-3.
v Fast recovery. If the database server shuts down in an uncontrolled manner, the
database server uses the logical-log records to recover all transactions that
occurred since the oldest update not yet flushed to disk and to roll back any
uncommitted transactions. (When all the data in shared memory and on disk are
the same, they are physically consistent.) The database server uses the logical-log
records in fast recovery when it returns the entire database server to a state of
logical consistency up to the point of the most recent logical-log record. (For
more information, see “Details of Fast Recovery After A Full Checkpoint” on
page 16-12.)
v Data restoration. The database server uses the most recent storage-space and
logical-log backups to re-create the database server system up to the point of the
most recently backed-up logical-log record. The logical restore applies all the log
records since the last storage-space backup.
v Deferred checking. If a transaction uses the SET CONSTRAINTS statement to
set checking to DEFERRED, the database server does not check the constraints
until the transaction is committed. If a constraint error occurs while the
transaction is being committed, the database server uses logical-log records to
roll back the transaction. For more information, see SET Database Object Mode
in the IBM Informix Guide to SQL: Syntax.
v Cascading deletes. Cascading deletes on referential constraints use logical-log
records to ensure that a transaction can be rolled back if a parent row is deleted
and the system fails before the children rows are deleted. For information on
table inheritance, see the IBM Informix Database Design and Implementation Guide.
For information on primary key and foreign key constraints, see the IBM
Informix Guide to SQL: Tutorial.
v Distributed transactions. Each database server involved in a distributed
transaction keeps logical-log records of the transaction. This process ensures data
integrity and consistency, even if a failure occurs on one of the database servers
that is performing the transaction. For more information, see “Two-Phase
Commit and Logical-Log Records” on page 23-15.
v High-Availability Data Replication (HDR). High-Availability Data Replication
uses logical-log records to maintain consistent data on two different database
servers so that one of the database servers can be used quickly as a backup
database server if the other fails. For more details, see “How HDR Works” on
page 20-6.
v Enterprise Replication. You must use database logging with Enterprise
Replication because it replicates the data from the logical-log records. For more
information, see the IBM Informix Dynamic Server Enterprise Replication Guide.

12-2 IBM Informix Dynamic Server Administrator’s Guide

Transaction Logging
A database or table is said to have or use transaction logging when SQL data
manipulation statements in a database generate logical-log records.

The database-logging status indicates whether a database uses transaction logging.

The log-buffering mode indicates whether a database uses buffered or unbuffered
logging, or ANSI-compliant logging. For more information, see “Database-Logging
Status” on page 12-5 and Chapter 13, “Managing the Database-Logging Mode,” on
page 13-1.

When you create a database, you specify whether it uses transaction logging and, if
it does, what log-buffering mechanism it uses. After the database is created, you
can turn off database logging or change to buffered logging, for example. Even if
you turn off transaction logging for all databases, the database server always logs
some events. For more information, see “Activity That is Always Logged” on page
12-3 and “Database Logging in an X/Open DTP Environment” on page 12-7.

You can use logging or nonlogging tables within a database. The user who creates
the table specifies the type of table. Even if you use nonlogging tables, the
database server always logs some events. For more information, see “Table Types
for Dynamic Server” on page 10-23.

Logging of SQL Statements and Database Server Activity

Three types of logged activity are possible in the database server:
v Activity that is always logged
v Activity that is logged only for databases that use transaction logging
v Activity that is never logged

Activity That is Always Logged

Some database operations always generate logical-log records, even if you turn off
transaction logging or use nonlogging tables.

The following operations are always logged for permanent tables:

v Certain SQL statements, including SQL data definition statements
v Storage-space backups
v Checkpoints
v Administrative changes to the database server configuration such as adding a
chunk or dbspace
v Allocation of new extents to tables
v A change to the logging status of a database
v Smart-large-object operations:
– Creating
– Deleting
– Allocating and deallocating extents
– Truncating
– Combining and splitting chunk free list pages
– Changing the LO header and the LO reference count
v Sbspace metadata
v Blobspaces

Chapter 12. Logging 12-3

 The table below lists statements that generate operations that are logged.

ALTER ACCESS_METHOD CREATE ROUTINE DROP SEQUENCE

ALTER FRAGMENT CREATE ROUTINE FROM DROP SYNONYM
ALTER FUNCTION CREATE ROW TYPE DROP TABLE
ALTER INDEX CREATE SCHEMA DROP TRIGGER
ALTER PROCEDURE CREATE SEQUENCE DROP TYPE
ALTER ROUTINE CREATE SYNONYM DROP VIEW
ALTER SEQUENCE CREATE TABLE CREATE XADATASOURCE
ALTER TABLE CREATE Temporary TABLE DROP XADATASOURCE TYPE
CLOSE DATABASE CREATE TRIGGER GRANT
CREATE ACCESS_METHOD CREATE VIEW RENAME COLUMN
CREATE AGGREGATE CREATE XADATASOURCE RENAME DATABASE
CREATE CAST CREATE XADATASOURCE TYPE RENAME INDEX
CREATE DATABASE DROP ACCESS_METHOD RENAME SEQUENCE
CREATE DISTINCT TYPE DROP AGGREGATE RENAME TABLE
CREATE EXTERNAL TABLE DROP CAST REVOKE
CREATE FUNCTION DROP DATABASE REVOKE FRAGMENT
CREATE FUNCTION FROM DROP FUNCTION
CREATE INDEX DROP INDEX
CREATE OPAQUE TYPE DROP OPCLASS
CREATE OPCLASS DROP PROCEDURE
CREATE PROCEDURE DROP ROLE
CREATE PROCEDURE FROM DROP ROUTINE
CREATE ROLE DROP ROW TYPE

Activity Logged for Databases with Transaction Logging

If a database uses transaction logging, the following SQL statements generate one
or more log records. If these statements are rolled back, the rollback also generates
log records.

DELETE LOAD UNLOAD

FLUSH PUT UPDATE
INSERT SELECT INTO TEMP

The following SQL statements generate log records in special situations.

SQL Statement Log Record That the Statement Generates

BEGIN WORK Returns an error unless the database uses transaction logging. A log record is produced
if the transaction does some other logging work.
COMMIT WORK Returns an error unless the database uses transaction logging. A log record is produced
if the transaction does some other logging work.
EXECUTE Whether this statement generates a log record depends on the command being
executed.
EXECUTE FUNCTION Whether this statement generates a log record depends on the function being executed.
EXECUTE IMMEDIATE Whether this statement generates a log record depends on the command being
executed.
EXECUTE PROCEDURE Whether this statement generates a log record depends on the procedure being
executed.

Activity That is Not Logged

The following SQL statements do not produce log records, regardless of the
database logging mode.

12-4 IBM Informix Dynamic Server Administrator’s Guide

ALLOCATE COLLECTION DEALLOCATE ROW LOCK TABLE
ALLOCATE DESCRIPTOR DECLARE OPEN
ALLOCATE ROW DESCRIBE OUTPUT
CLOSE DISCONNECT PREPARE
CONNECT FETCH SELECT
DATABASE FREE SET
DEALLOCATE COLLECTION GET DESCRIPTOR UNLOCK TABLE
DEALLOCATE DESCRIPTOR GET DIAGNOSTICS WHENEVER
DEALLOCATE ROW INFO

For temporary tables in temporary dbspaces, nothing is logged, not even the SQL
statements listed in “Activity That is Always Logged” on page 12-3. If you include
temporary (nonlogging) dbspaces in DBSPACETEMP, the database server places
nonlogging tables in these temporary dbspaces first. For more information, see
“Temporary Tables” on page 10-32.

Database-Logging Status
You must use transaction logging with a database to take advantage of any of the
features listed in “Database Server Processes That Require Logging” on page 12-1.

Every database that the database server manages has a logging status. The logging
status indicates whether the database uses transaction logging and, if so, which
log-buffering mechanism the database employs. To find out the transaction-logging
status of a database, use the database server utilities, as explained in “Monitoring
the Logging Mode of a Database” on page 13-5. The database-logging status
indicates any of the following types of logging:
v Unbuffered transaction logging
v Buffered transaction logging
v ANSI-compliant transaction logging
v No logging

All logical-log records pass through the logical-log buffer in shared memory before
the database server writes them to the logical log on disk. However, the point at
which the database server flushes the logical-log buffer is different for buffered
transaction logging and unbuffered transaction logging. For more information, see
Figure 8-1 on page 8-3 and “Flushing the Logical-Log Buffer” on page 8-28.

Unbuffered Transaction Logging

If transactions are made against a database that uses unbuffered logging, the
records in the logical-log buffer are guaranteed to be written to disk during
commit processing. When control returns to the application after the COMMIT
statement (and before the PREPARE statement for distributed transactions), the
logical-log records are on the disk. The database server flushes the records as soon
as any transaction in the buffer is committed (that is, a commit record is written to
the logical-log buffer).

When the database server flushes the buffer, only the used pages are written to
disk. Used pages include pages that are only partially full, however, so some space
is wasted. For this reason, the logical-log files on disk fill up faster than if all the
databases on the same database server use buffered logging.
Chapter 12. Logging 12-5
 Unbuffered logging is the best choice for most databases because it guarantees that
all committed transactions can be recovered. In the event of a failure, only
uncommitted transactions at the time of the failure are lost. However, with
unbuffered logging, the database server flushes the logical-log buffer to disk more
frequently, and the buffer contains many more partially full pages, so it fills the
logical log faster than buffered logging does.

Buffered Transaction Logging

If transactions are made against a database that uses buffered logging, the records
are held (buffered) in the logical-log buffer for as long as possible. They are not
flushed from the logical-log buffer in shared memory to the logical log on disk
until one of the following situations occurs:
v The buffer is full.
v A commit on a database with unbuffered logging flushes the buffer.
v A checkpoint occurs.
v The connection is closed.

If you use buffered logging and a failure occurs, you cannot expect the database
server to recover the transactions that were in the logical-log buffer when the
failure occurred. Thus, you could lose some committed transactions. In return for
this risk, performance during alterations improves slightly. Buffered logging is best
for databases that are updated frequently (when the speed of updating is
important), as long as you can re-create the updates in the event of failure. You can
tune the size of the logical-log buffer to find an acceptable balance for your system
between performance and the risk of losing transactions to system failure.

ANSI-Compliant Transaction Logging

The ANSI-compliant database logging status indicates that the database owner
created this database using the MODE ANSI keywords. ANSI-compliant databases
always use unbuffered transaction logging, enforcing the ANSI rules for transaction
processing. You cannot change the buffering status of ANSI-compliant databases.

No Database Logging
If you turn off logging for a database, transactions are not logged, but other
operations are logged. For more information, see “Activity That is Always Logged”
on page 12-3. Usually, you would turn off logging for a database when you are
loading data, or just executing queries.

If you are satisfied with your recovery source, you can decide not to use
transaction logging for a database to reduce the amount of database server
processing. For example, if you are loading many rows into a database from a
recoverable source such as tape or an ASCII file, you might not need transaction
logging, and the loading would proceed faster without it. However, if other users
are active in the database, you would not have logical-log records of their
transactions until you reinitiate logging, which must wait for a level-0 backup.

Databases with Different Log-Buffering Status

All databases on a database server use the same logical log and the same
logical-log buffers. Therefore, transactions against databases with different
log-buffering statuses can write to the same logical-log buffer. In that case, if
transactions exist against databases with buffered logging and against databases
with unbuffered logging, the database server flushes the buffer either when it is full
or when transactions against the databases with unbuffered logging complete.

12-6 IBM Informix Dynamic Server Administrator’s Guide

 Database Logging in an X/Open DTP Environment
Databases in the X/Open distributed transaction processing (DTP) environment
must use unbuffered logging. Unbuffered logging ensures that the database server
logical logs are always in a consistent state and can be synchronized with the
transaction manager. If a database created with buffered logging is opened in an
X/Open DTP environment, the database status automatically changes to
unbuffered logging. The database server supports both ANSI-compliant and
non-ANSI databases. For more information, see “Transaction Managers” on page
23-2.

Settings or Changes for Logging Status or Mode

The user who creates a database with the CREATE DATABASE statement
establishes the logging status or buffering mode for that database. For more
information on the CREATE DATABASE statement, see the IBM Informix Guide to
SQL: Syntax.

If the CREATE DATABASE statement does not specify a logging status, the
database is created without logging.

Only the database server administrator can change logging status. Chapter 13,
“Managing the Database-Logging Mode,” on page 13-1, describes this topic.
Ordinary end users cannot change database-logging status.

If a database does not use logging, you do not need to consider whether buffered
or unbuffered logging is more appropriate. If you specify logging but do not
specify the buffering mode for a database, the default is unbuffered logging.

End users can switch from unbuffered to buffered (but not ANSI-compliant)
logging and from buffered to unbuffered logging for the duration of a session. The
SET LOG statement performs this change within an application. For more
information on the SET LOG statement, see the IBM Informix Guide to SQL: Syntax.

Chapter 12. Logging 12-7

12-8 IBM Informix Dynamic Server Administrator’s Guide
Chapter 13. Managing the Database-Logging Mode
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Changing the Database-Logging Mode. . . . . . . . . . . . . . . . . . . . . . . . . . 13-2
Modifying the Database-Logging Mode with ondblog . . . . . . . . . . . . . . . . . . . . 13-2
Changing the Buffering Mode with ondblog . . . . . . . . . . . . . . . . . . . . . . . 13-2
Canceling a Logging Mode Change with ondblog . . . . . . . . . . . . . . . . . . . . . 13-3
Ending Logging with ondblog . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3
Making a Database ANSI Compliant with ondblog . . . . . . . . . . . . . . . . . . . . 13-3
Changing the Logging Mode of an ANSI-Compliant Database . . . . . . . . . . . . . . . . . 13-3
Modifying the Database Logging Mode with ontape . . . . . . . . . . . . . . . . . . . . . 13-3
Turning On Transaction Logging with ontape . . . . . . . . . . . . . . . . . . . . . . 13-3
Ending Logging with ontape . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Changing Buffering Mode with ontape . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Making a Database ANSI Compliant with ontape . . . . . . . . . . . . . . . . . . . . . 13-4
Modifying Database Logging Mode with ISA . . . . . . . . . . . . . . . . . . . . . . . 13-4
Modifying Database Logging Mode with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . 13-5
Modifying the Table-Logging Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Altering a Table to Turn Off Logging . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Altering a Table to Turn On Logging . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring the Logging Mode of a Database . . . . . . . . . . . . . . . . . . . . . . . 13-5
Monitoring the Logging Mode with SMI Tables . . . . . . . . . . . . . . . . . . . . . . 13-6
Monitoring the Logging Mode with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . 13-6
Monitoring the Logging Mode with ISA . . . . . . . . . . . . . . . . . . . . . . . . 13-6

In This Chapter
This chapter covers the following topics on changing the database-logging mode:
v Understanding database-logging mode
v Modifying database-logging mode with ondblog
v Modifying database-logging mode with ontape
v Modifying database-logging mode with ON–Monitor
v Monitoring transaction logging

As a database server administrator, you can alter the logging mode of a database
as follows:
v Change transaction logging from buffered to unbuffered.
v Change transaction logging from unbuffered to buffered.
v Make a database ANSI compliant.
v Add transaction logging (buffered or unbuffered) to a database.
v End transaction logging for a database.

For information about database-logging mode, when to use transaction logging,

and when to buffer transaction logging, see Chapter 12, “Logging,” on page 12-1
To find out the current logging mode of a database, see “Monitoring the Logging
Mode of a Database” on page 13-5.

© Copyright IBM Corp. 1996, 2005 13-1

Changing the Database-Logging Mode
You can use ondblog, ontape, or ISA to add or change logging. Then use ON–Bar,
or ontape to back up the data. When you use ON–Bar or ontape, the database
server must be in online, single-user, or quiescent mode.

For information on ON–Bar and ontape, see the IBM Informix Backup and Restore
Guide.

Table 13-1 shows how the database server administrator can change the
database-logging mode. Certain logging mode changes take place immediately,
while other changes require a level-0 backup.
Table 13-1. Logging Mode Transitions
Converting to Converting to Converting to Converting to
Converting from: No Logging Unbuffered Logging Buffered Logging ANSI Compliant
No logging Not applicable Level-0 backup (of Level-0 backup (of Level-0 backup (of
affected storage affected storage affected storage
spaces) spaces) spaces)
Unbuffered Yes Not applicable Yes Yes
logging
Buffered logging Yes Yes Not applicable Yes
ANSI compliant Illegal Illegal Illegal Not applicable

Some general points about changing the database-logging mode follow:

v While the logging status is being changed, the database server places an
exclusive lock on the database to prevent other users from accessing the
database, and frees the lock when the change is complete.
v If a failure occurs during a logging-mode change, check the logging mode in ISA
or the flags in the sysdatabases table in the sysmaster database, after you restore
the database server data. For more information, see “Monitoring the Logging
Mode of a Database” on page 13-5. Then retry the logging-mode change.
v After you choose either buffered or unbuffered logging, an application can use
the SQL statement SET LOG to change from one logging mode to the other. This
change lasts for the duration of the session. For information on SET LOG, see
the IBM Informix Guide to SQL: Syntax.
v If you add logging to a database, the change is not complete until the next
level-0 backup of all the storage spaces for the database.

Modifying the Database-Logging Mode with ondblog

You can use the ondblog utility to change the logging mode for one or more
databases. If you add logging to a database, you must create a level-0 backup of
the dbspace(s) that contains the database before the change takes effect. For more
information, see the section on using ondblog in the IBM Informix Administrator's
Reference.

Changing the Buffering Mode with ondblog

To change the buffering mode from buffered to unbuffered logging on a database
called stores_demo, execute the following command:
ondblog unbuf stores_demo

13-2 IBM Informix Dynamic Server Administrator’s Guide

 To change the buffering mode from unbuffered to buffered logging on a database
called stores_demo, execute the following command:
ondblog buf stores_demo

Canceling a Logging Mode Change with ondblog

To cancel the logging mode change request before the next level-0 backup occurs,
execute the following command:
ondblog cancel stores_demo

You cannot cancel the logging changes that are executed immediately.

Ending Logging with ondblog

To end logging for two databases that are listed in a file called dbfile, execute the
following command:
ondblog nolog -f dbfile

Making a Database ANSI Compliant with ondblog

To make a database called stores_demo into an ANSI-compliant database with
ondblog, execute the following command:
ondblog ansi stores_demo

Changing the Logging Mode of an ANSI-Compliant Database

After you create or convert a database to ANSI mode, you cannot easily change it
to any other logging mode. If you accidentally convert a database to ANSI mode,
follow these steps to change the logging mode:

To change the logging mode:

1. To unload the data, use dbexport or any other migration utility. The dbexport
utility creates the schema file.
For information about how to load and unload data, see the IBM Informix
Migration Guide.
2. To re-create a database with buffered logging and load the data, use the
dbimport -l buffered command.
To re-create a database with unbuffered logging and load the data, use the
dbimport -l command.

Modifying the Database Logging Mode with ontape

If you use ontape as your backup tool, you can use ontape to change the logging
mode of a database.

Turning On Transaction Logging with ontape

Before you modify the database-logging mode, read “Changing the
Database-Logging Mode” on page 13-2.

You add logging to a database with ontape at the same time that you create a
level-0 backup.

For example, to add buffered logging to a database called stores_demo with

ontape, execute the following command:
ontape -s -B stores_demo

Chapter 13. Managing the Database-Logging Mode 13-3

 To add unbuffered logging to a database called stores_demo with ontape, execute
the following command:
ontape -s -U stores_demo

In addition to turning on transaction logging, these commands create full-system

storage-space backups. When ontape prompts you for a backup level, specify a
level-0 backup.

Tip: With ontape, you must perform a level-0 backup of all storage spaces.

Ending Logging with ontape

To end logging for a database called stores_demo with ontape, execute the
following command:
ontape -N stores_demo

Changing Buffering Mode with ontape

To change the buffering mode from buffered to unbuffered logging on a database
called stores_demo, using ontape, without creating a storage-space backup, execute
the following command:
ontape -U stores_demo

To change the buffering mode from unbuffered to buffered logging on a database

called stores_demo, using ontape, without creating a storage-space backup, execute
the following command:
ontape -B stores_demo

Making a Database ANSI Compliant with ontape

To make a database called stores_demo, which already uses transaction logging
(either unbuffered or buffered), into an ANSI-compliant database with ontape,
execute the following command:
ontape -A stores_demo

To make a database called stores_demo, which does not already use transaction
logging, into an ANSI-compliant database with ontape, execute the following
command:
ontape -s -A stores_demo

In addition to making a database ANSI compliant, this command also creates a

storage-space backup at the same time. Specify a level-0 backup when you are
prompted for a level.

Tip: After you change the logging mode to ANSI compliant, you cannot easily
change it again. To change the logging mode of ANSI-compliant databases,
unload the data, re-create the database with the new logging mode, and
reload the data. For details, see “Changing the Logging Mode of an
ANSI-Compliant Database” on page 13-3.

Modifying Database Logging Mode with ISA

ISA uses the ondblog utility to modify the database-logging mode. If you turn on
logging, perform a level-0 backup. For more information, see the ISA online help
and “Modifying the Database-Logging Mode with ondblog” on page 13-2.

13-4 IBM Informix Dynamic Server Administrator’s Guide

Modifying Database Logging Mode with ON-Monitor (UNIX)
You can use ON–Monitor to change the log-buffering mode between unbuffered
and buffered. If you want to add logging to a database or make it ANSI compliant,
you cannot use ON–Monitor. You must use ontape.

To change the log-buffering mode for a database, select the Logical-Logs >
Databases option.

Modifying the Table-Logging Mode

The database server creates standard tables that use logging by default. To create a
nonlogging table, use the CREATE TABLE statement with the WITH LOG clause.
For information on the CREATE TABLE and ALTER TABLE statements, see the
IBM Informix Guide to SQL: Syntax. For more information, refer to “Table Types for
Dynamic Server” on page 10-23.

Altering a Table to Turn Off Logging

To switch a table from logging to nonlogging, use the SQL statement ALTER
TABLE with the TYPE option of RAW. For example, the following statement
changes table tablog to a RAW table:
ALTER TABLE tablog TYPE (RAW)

Altering a Table to Turn On Logging

To switch from a nonlogging table to a logging table, use the SQL statement
ALTER TABLE with the TYPE option of STANDARD. For example, the following
statement changes table tabnolog to a STANDARD table:
ALTER TABLE tabnolog TYPE (STANDARD)

Warning: When you alter a table to STANDARD, you turn logging on for that
table. After you alter the table, perform a level-0 backup if you need to
be able to restore the table.

Monitoring Transactions
This section contains references for information on ways to monitor transactions.

Command Description Reference

onstat -x Monitor transactions. “Monitoring a Global Transaction” on page
23-14
onstat -g sql Monitor SQL statements, listed by session ID Performance monitoring in the IBM Informix
and database. Dynamic Server Performance Guide
onstat -g stm Monitor memory usage of prepared SQL Memory utilization in the IBM Informix Dynamic
statements. Server Performance Guide

Monitoring the Logging Mode of a Database

This section discusses ways to monitor the logging mode of your database and
tables.

Chapter 13. Managing the Database-Logging Mode 13-5

 Monitoring the Logging Mode with SMI Tables
Query the sysdatabases table in the sysmaster database to determine the logging
mode. This table contains a row for each database that the database server
manages. The flags field indicates the logging mode of the database. The
is_logging, is_buff_log, and is_ansi fields indicate whether logging is active, and
whether buffered logging or ANSI-compliant logging is used. For a description of
the columns in this table, see the sysdatabases section in the chapter about the
sysmaster database in the IBM Informix Administrator's Reference.

Monitoring the Logging Mode with ON-Monitor (UNIX)

To use ON–Monitor to find out the logging mode of a database, select the Status >
Databases option. When database logging is on, ON–Monitor shows the buffering
mode. ON–Monitor can only display up to 100 databases. If you have more than
100 databases on your database server, use the SMI tables to display the full list, as
described in “Monitoring the Logging Mode with SMI Tables” on page 13-6.

Monitoring the Logging Mode with ISA

To use ISA to display the logging status and buffering mode for your databases,
select SQL > Schema.

13-6 IBM Informix Dynamic Server Administrator’s Guide

Chapter 14. Logical Log
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
What Is the Logical Log? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Location of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Identification of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Status Flags of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Size of the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-3
Number of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Performance Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-4
Dynamic Log Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Freeing of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Action If the Next Logical-Log File Is Not Free . . . . . . . . . . . . . . . . . . . . . . 14-5
Action if the Next Log File Contains the Last Checkpoint . . . . . . . . . . . . . . . . . . 14-6
Logging Blobspaces and Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . . 14-6
Switching Log Files to Activate Blobspaces . . . . . . . . . . . . . . . . . . . . . . . 14-6
Backing Up Log Files to Free Blobpages . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Backing Up Blobspaces After Inserting or Deleting TEXT and BYTE Data . . . . . . . . . . . . . 14-7
Logging Sbspaces and Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Using Sbspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-7
Choosing Logging for Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . 14-8
Logging for Updated Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . 14-8
Turning Logging On or Off for an Sbspace . . . . . . . . . . . . . . . . . . . . . . 14-8
Using Smart-Large-Object Log Records . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Preventing Long Transactions When Logging Smart-Large-Object Data . . . . . . . . . . . . . . 14-9
Logging Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Dbspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Blobspace Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10

In This Chapter
The information in Chapter 12, “Logging,” on page 12-1, and this chapter will help
you understand how the database server uses the logical log. For information on
how to perform logical-log tasks, see Chapter 15, “Managing Logical-Log Files,” on
page 15-1, and Chapter 13, “Managing the Database-Logging Mode,” on page 13-1

What Is the Logical Log?

To keep a history of transactions and database server changes since the time of the
last storage-space backup, the database server generates log records. The database
server stores the log records in the logical log, a circular file that is composed of
three or more logical-log files. The log is called logical because the log records
represent logical operations of the database server, as opposed to physical
operations. At any time, the combination of a storage-space backup plus logical-log
backup contains a complete copy of your database server data.

As the database server administrator, you must configure and manage the logical
log. For example, if you do not back up the log files regularly, the logical log fills
and the database server suspends processing.

These responsibilities include the following tasks:

v Choosing an appropriate location for the logical log
See “Location of Logical-Log Files” on page 14-2.
v Monitoring the logical-log file status

© Copyright IBM Corp. 1996, 2005 14-1

 See “Identification of Logical-Log Files” on page 14-2.
v Allocating an appropriate amount of disk space for the logical log
See “Size of the Logical Log” on page 14-3.
v Allocating additional log files whenever necessary
See “Allocating Log Files” on page 15-8.
v Backing up the logical-log files to media
See “Backing Up Logical-Log Files” on page 15-3 and “Freeing of Logical-Log
Files” on page 14-5.
v Managing logging of blobspaces and sbspaces
See “Logging Blobspaces and Simple Large Objects” on page 14-6 and “Logging
Sbspaces and Smart Large Objects” on page 14-7.

Location of Logical-Log Files

When the database server initializes disk space, it places the logical-log files and
the physical log in the root dbspace. You have no control over this action. To
improve performance (specifically, to reduce the number of writes to the root
dbspace and minimize contention), move the logical-log files out of the root
dbspace to a dbspace on a disk that is not shared by active tables or the physical
log. See “Moving a Logical-Log File to Another Dbspace” on page 15-12.

To improve performance further, separate the logical-log files into two groups and
store them on two separate disks (neither of which contains data). For example, if
you have six logical-log files, you might locate files 1, 3, and 5 on disk 1, and files
2, 4, and 6 on disk 2. This arrangement improves performance because the same
disk drive never has to handle writes to the current logical-log file and backups to
tape at the same time.

The logical-log files contain critical information and should be mirrored for
maximum data protection. If you move logical-log files to a different dbspace, plan
to start mirroring on that dbspace.

Identification of Logical-Log Files

Each logical-log file, whether backed up to media or not, has a unique ID number.
The sequence begins with 1 for the first logical-log file filled after you initialize the
database server disk space. When the current logical-log file becomes full, the
database server switches to the next logical-log file and increments the unique ID
number for the new log file by one. Log files that are newly added or marked for
deletion have unique ID numbers of 0.

The actual disk space allocated for each logical-log file has an identification
number known as the log file number. For example, if you configure six logical-log
files, these files have log numbers one through six. The log numbers might be out
of sequence. As logical-log files are backed up and freed, the database server
reuses the disk space for the logical-log files.

Table 14-1 illustrates the relationship between the log numbers and the unique ID
numbers. Log 7 is inserted after log 5 and used for the first time in the second
rotation.

14-2 IBM Informix Dynamic Server Administrator’s Guide

 Table 14-1. Logical-Log File-Numbering Sequence
First Rotation Second Rotation Third Rotation
Log File Number Unique ID Number Unique ID Number Unique ID Number
1 1 7 14
2 2 8 15
3 3 9 16
4 4 10 17
5 5 11 18
7 0 12 19
6 6 13 20

Status Flags of Logical-Log Files

All logical-log files have one of the following status flags in the first position:
Added (A), Deleted (D), Free (F), or Used (U). Table 14-2 shows the possible
log-status flag combinations.
Table 14-2. Logical-Log Status Flags
Status Flag Status of Logical-Log File
A------ Log file has been added, and is available, but has not yet been used.
D------ If you drop a log file with a status of U-B, it is marked as deleted. This log file
is dropped and its space is freed for reuse when you take a level-0 backup of
all storage spaces.
F------ Log file is free and available for use.

A logical-log file is freed after it is backed up, all transactions within the
logical-log file are closed, and the oldest update stored in this file is flushed to
disk.
U Log file has been used but not backed up.
U-B---- Log file is backed up but still needed for recovery. (The log file is freed when it
is no longer needed for recovery.)
U-B---L Log is backed up but still needed for recovery. Contains the last checkpoint
record.
U---C The database server is currently filling the log file.
U---C-L This current log file contains the last checkpoint record.

Use the onstat -l command to list the log files by number and monitor the status
flags and percentage of log space used. For more details, see “onstat -l” on page
15-6.

Size of the Logical Log

Decide how many log files you want and what size. If you allocate more disk
space than necessary, space is wasted. If you do not allocate enough disk space,
however, performance might be adversely affected. Consider these points about the
size and number of the logical-log files:
v The minimum size for a logical-log file is 200 kilobytes.
v The maximum size for a logical-log file is 1048576 pages (equivalent to
0x100000).

Chapter 14. Logical Log 14-3

 v Smaller log files mean that you can recover to a later time if the disk that
contains the log files goes down. If continuous log backup is set, log files are
automatically backed up as they fill. Smaller logs result in slightly longer logical
recovery.
v Use larger log files when many users are writing to the logs at the same time.

Number of Logical-Log Files

When you think about the number of logical-log files, consider these points:
v You must always have at least three logical-log files and a maximum of 32,767
log files. The number of log files depends on the size of the log files.
v The number of log files affects the frequency of logical-log backups.
v The number of logical-log files affects the rate at which blobspace blobpages can
be reclaimed. See “Backing Up Log Files to Free Blobpages” on page 14-7.

Performance Considerations
For a given level of system activity, the less logical-log disk space that you allocate,
the sooner that logical-log space fills up, and the greater the likelihood that user
activity is blocked due to backups and checkpoints. Tune the logical-log size to
find the optimum value for your system.
v Logical-log backups
When the logical-log files fill, you have to back them up. The backup process
can hinder transaction processing that involves data located on the same disk as
the logical-log files. Put the physical log, logical logs, and user data on separate
disks. (See the IBM Informix Backup and Restore Guide.)
v Checkpoints
Checkpoints block user processing briefly. If log files are backed up and freed
more frequently, the checkpoints occur more frequently.
v Size of the logical log
A smaller logical log fills faster than a larger logical log. You can add a larger
logical-log file, as explained in “Adding Logical-Log Files Manually” on page
15-10.
v Size of individual logical-log records
The sizes of the logical-log records vary, depending on both the processing
operation and the database server environment. In general, the longer the data
rows, the larger the logical-log records. The logical log contains images of rows
that have been inserted, updated, or deleted. Updates can use up to twice as
much space as inserts and deletes because they might contain both
before-images and after-images. (Inserts store only the after-image and deletes
store only the before-image.)
v Number of logical-log records
The more logical-log records written to the logical log, the faster it fills.
Databases with transaction logging fill the logical log faster than transactions
against databases without transaction logging.
v Type of log buffering
Databases that use unbuffered transaction logging fill the logical log faster than
databases that use buffered transaction logging.
v Enterprise Replication on a table
Because Enterprise Replication generates before-images and after-images of the
replicated tables, it could cause the logical log to fill.
v Frequency of rollbacks

14-4 IBM Informix Dynamic Server Administrator’s Guide

 More rollbacks fill the logical log faster. The rollbacks themselves require
logical-log file space although the rollback records are small.
v Number of smart large objects
Smart large objects that have user data logging enabled and have a large volume
of user data updates can fill logical logs at a prodigious rate. Use temporary
smart large objects if you do not want to log the metadata.

Dynamic Log Allocation

Dynamic log allocation prevents log files from filling and hanging the system
during long transaction rollbacks. The only time that this feature becomes active is
when the next log file contains an open transaction. (A transaction is long if it is not
committed or rolled back when it reaches the long-transaction high-watermark.)

The database server automatically (dynamically) allocates a log file after the
current log file when the next log file contains an open transaction. Dynamic log
allocation allows you to do the following actions:
v Add a log file while the system is active
v Insert a log file after the current log file
v Immediately access new log files even if the root dbspace is not backed up

The best way to test dynamic log allocation is to produce a transaction that spans
all the log files and then use onstat -l to check for newly added log files. For more
information, see “Allocating Log Files” on page 15-8.

Important: You still must back up log files to prevent them from filling. If the log
files fill, the system hangs until you perform a backup.

Freeing of Logical-Log Files

Each time the database server commits or rolls back a transaction, it attempts to
free the logical-log file in which the transaction began. The following criteria must
be satisfied before the database server frees a logical-log file for reuse:
v The log file is backed up.
v No records within the logical-log file are associated with open transactions.
v The logical-log file does not contain the oldest update not yet flushed to disk.

Action If the Next Logical-Log File Is Not Free

If the database server attempts to switch to the next logical-log file but finds that
the next log file in sequence is still in use, the database server immediately
suspends all processing. Even if other logical-log files are free, the database server
cannot skip a file in use and write to a free file out of sequence. Processing stops
to protect the data within the logical-log file.

The logical-log file might be in use for any of the following reasons:
v The file contains the latest checkpoint or the oldest update not yet flushed to
disk.
Issue the onmode -c command to perform a full checkpoint and free the
logical-log file. For more information, see “Forcing a Full Checkpoint” on page
17-5.
v The file contains an open transaction.

Chapter 14. Logical Log 14-5

 The open transaction is the long transaction discussed in “Setting
High-Watermarks for Rolling Back Long Transactions” on page 15-15.
v The file is not backed up.
If the logical-log file is not backed up, processing resumes when you use
ON–Bar or ontape to back up the logical-log files.

Action if the Next Log File Contains the Last Checkpoint

The database server does not suspend processing when the next log file contains
the last checkpoint or the oldest update. The database server always forces a full
checkpoint when it switches to the last available log, if the previous checkpoint
record or oldest updated not-yet-flushed-to-disk is located in the log that follows
the last available log. For example, if four logical-log files have the status shown in
the following list, the database server forces a checkpoint when it switches to
logical-log file 3.
Log File Number Logical-Log File Status
1 U-B----
2 U---C--
3 F
4 U-B---L

Logging Blobspaces and Simple Large Objects

Simple-large-object data (TEXT and BYTE data types) is potentially too voluminous
to include in a logical-log record. If simple large objects are always logged, they
might be so large that they slow down the logical log.

The database server assumes that you designed your databases so that smaller
simple large objects are stored in dbspaces and larger simple large objects are
stored in blobspaces:
v The database server includes simple-large-object data in log records for simple
large objects stored in dbspaces.
v The database server does not include simple-large-object data in log records for
simple large objects stored in blobspaces. The logical log records blobspace data
only when you back up the logical logs.

To obtain better overall performance for applications that perform frequent updates
of simple large objects in blobspaces, reduce the size of the logical log. Smaller logs
can improve access to simple large objects that must be reused. For more
information, see the chapter on configuration effects on I/O utilization in your IBM
Informix Dynamic Server Performance Guide.

Switching Log Files to Activate Blobspaces

You must switch to the next logical-log file in these situations:
v After you create a blobspace, if you intend to insert simple large objects in the
blobspace right away
v After you add a new chunk to an existing blobspace, if you intend to insert
simple large objects in the blobspace that will use the new chunk

The database server requires that the statement that creates a blobspace, the
statement that creates a chunk in the blobspace, and the statements that insert

14-6 IBM Informix Dynamic Server Administrator’s Guide

 simple large objects into that blobspace appear in separate logical-log files. This
requirement is independent of the database-logging status.

For instructions on switching to the next log file, see “Switching to the Next
Logical-Log File” on page 15-4.

Backing Up Log Files to Free Blobpages

When you delete data stored in blobspace pages, those pages are not necessarily
freed for reuse. The blobspace pages are free only when both of the following
actions have occurred:
v The TEXT or BYTE data has been deleted, either through an UPDATE to the
column or by deleting the row
v The logical log that stores the INSERT of the row that has TEXT or BYTE data is
backed up

Backing Up Blobspaces After Inserting or Deleting TEXT and

BYTE Data
Be sure to back up all blobspaces and logical logs containing transactions on
simple large objects stored in a blobspace. During log backup, the database server
uses the data pointer in the logical log to copy the changed text and byte data
from the blobspace into the logical log.

Logging Sbspaces and Smart Large Objects

Sbspaces, described in “Sbspaces” on page 10-13, contain two components:
metadata and user data. By default, sbspaces are not logged.

The metadata component of the sbspace describes critical characteristics of smart

large objects stored in a particular sbspace. The metadata contains pointers to the
smart large objects. If the metadata were to be damaged or become inaccessible,
the sbspace would be corrupted and the smart large objects within that sbspace
would be unrecoverable.

Metadata in a standard sbspace is always logged, even if logging is turned off for a
database. Logging sbspace metadata ensures that the metadata can always be
recovered to a consistent transaction state. However, metadata in a temporary
sbspace is not logged.

Using Sbspace Logging

When an sbspace is logged, the database server slows down, and the logical logs
fill up quickly. If you use logging for sbspaces, you must ensure that the logical
logs are large enough to hold the logging data. For more information, see
“Estimating the Log Size When Logging Smart Large Objects” on page 15-3.

When you turn on logging for a database, the database server does not begin
logging until you perform a level-0 backup. However, when you turn on logging
for a smart large object, the database server begins logging changes to it
immediately. To reduce the volume of log entries, you could load smart large
objects with logging turned off and then turn logging back on to capture updates
to the smart large objects.

Warning: When you turn logging on for a smart large object, you must
immediately perform a level-0 backup to be able to recover and restore
the smart large object.
Chapter 14. Logical Log 14-7
 For more information, see “Backing Up Sbspaces” on page 15-4 and the IBM
Informix Backup and Restore Guide.

Choosing Logging for Smart Large Objects

Use logging for smart large objects if users are updating the data frequently or if
the ability to recover any updated data is critical. The database server writes a
record of the operation (insert, update, delete, read, or write) to the logical-log
buffer. The modified portion of the CLOB or BLOB data is included in the log
record.

To increase performance, turn off logging for smart large objects. Also turn off
logging if users are primarily analyzing the data and updating it infrequently, or if
the data is not critical to recover.

Logging for Updated Smart Large Objects

When you update a smart large object, the database server does not log the entire
object. Assume that the user is writing X bytes of data at offset Y with logging
enabled for smart large objects. The database server logs the following:
v If Y is set to the end of the large object, the database server logs X bytes (the
updated byte range).
v If Y is at the beginning or in the middle of the large object, the database server
logs the smallest of these choices:
– Difference between the old and new image
– Before-image and after-image
– Nothing is logged if the before- and after-images are the same

Turning Logging On or Off for an Sbspace

If you want to use logging in an sbspace, specify the -Df LOGGING=ON option
of the onspaces command when you create the sbspace. If logging is turned off in
the sbspace, you can turn on logging for smart large objects in specific columns.
One column that contains smart large objects could have logging turned on while
another column has logging turned off.

To verify that smart large objects in an sbspace are logged, use the following
command:
oncheck -pS sbspace | grep “Create Flags”

If you create smart large objects in the sbspace with the default logging option and
you see the LO_NOLOG flag in the output, the smart large objects in this sbspace
are not logged. If you see the LO_LOG flag in the output, all smart large objects in
this sbspace are logged.

You can modify the logging status of an sbspace in any of the following ways.

14-8 IBM Informix Dynamic Server Administrator’s Guide

Function or Statement to Specify Logging Action References
onspaces -ch -Df LOGGING=ON Turns logging on or off for an existing “Altering Storage Characteristics of
sbspace Smart Large Objects” on page 11-24

IBM Informix Administrator's Reference

LOG option in the PUT clause of the Turns on logging for all smart large “Logging” on page 10-17
CREATE TABLE or alter table objects that you load into the column
statement IBM Informix Guide to SQL: Syntax
mi_lo_create DataBlade API function Turns off logging for a smart large IBM Informix DataBlade API Function
object when it is initially loaded Reference
mi_lo_alter DataBlade API function Turns on logging after the load is IBM Informix DataBlade API Function
complete Reference
ifx_lo_create ESQL/C function Turns off logging for a smart large IBM Informix ESQL/C Programmer's
object when it is initially loaded Manual
ifx_lo_alter ESQL/C function Turns on logging after the load is IBM Informix ESQL/C Programmer's
complete Manual

Using Smart-Large-Object Log Records

When you create a smart large object with the LOG option, the logical log creates a
smart-blob log record. Smart-blob log records track changes to user data or metadata.
When smart large objects are updated, only the modified portion of the sbpage
appears in the log record. User-data log records appear in the logical log only
when logging is enabled for the smart large object.

Warning: Be careful about enabling logging for smart large objects that are
updated frequently. This logging overhead might significantly slow
down the database server.

For information on the log records for smart large objects, see the chapter on
interpreting logical-log records in the IBM Informix Dynamic Server Administrator's
Reference.

Preventing Long Transactions When Logging

Smart-Large-Object Data
You can use smart large objects in situations where the data collection process for a
single smart large object lasts for long periods of time. Consider, for example, an
application that records many hours of low-quality audio information. Although
the amount of data collected might be modest, the recording session might be long,
resulting in a long-transaction condition.

Tip: To prevent long transactions from occurring, periodically commit writes to

smart large objects.

Logging Process
This section describes in detail the logging process for dbspaces, blobspaces, and
sbspaces. This information is not required for performing normal database server
administration tasks.

Dbspace Logging
The database server uses the following logging process for operations that involve
data stored in dbspaces:

Chapter 14. Logical Log 14-9

 1. Reads the data page from disk to the shared-memory page buffer
2. Copies the unchanged page to the physical-log buffer, if needed
3. Writes the new data to the page buffer and creates a logical-log record of the
transaction, if needed
4. Flushes the physical-log buffer to the physical log on disk
5. Flushes the logical-log buffer to a logical-log file on disk
6. Flushes the page buffer and writes it back to disk

Blobspace Logging
The database server logs blobspace data, but the data does not pass through either
shared memory or the logical-log files on disk. The database server copies data
stored in a blobspace directly from disk to tape. Records of modifications to the
blobspace overhead pages (the free-map and bitmap pages) are the only blobspace
data that reaches the logical log.

14-10 IBM Informix Dynamic Server Administrator’s Guide

Chapter 15. Managing Logical-Log Files
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-1
Estimating the Size and Number of Log Files . . . . . . . . . . . . . . . . . . . . . . . 15-2
Estimating the Log Size When Logging Smart Large Objects . . . . . . . . . . . . . . . . . 15-3
Estimating the Number of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . 15-3
Backing Up Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-3
Backing Up Blobspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Backing Up Sbspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Switching to the Next Logical-Log File. . . . . . . . . . . . . . . . . . . . . . . . . . 15-4
Freeing a Logical-Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Deleting a Log File with Status D . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Freeing a Log File with Status U . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Freeing a Log File with Status U-B or F . . . . . . . . . . . . . . . . . . . . . . . . 15-5
Freeing a Log File with Status U-C or U-C-L. . . . . . . . . . . . . . . . . . . . . . . 15-6
Freeing a Log File with Status U-B-L . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
Monitoring Logging Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
Monitoring the Logical Log for Fullness . . . . . . . . . . . . . . . . . . . . . . . . 15-6
onstat -l . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-6
oncheck -pr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Monitoring Temporary Logical Logs . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-7
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Monitoring Log-Backup Status . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Allocating Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Adding Logs Dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-8
Size and Number of Dynamically Added Log Files . . . . . . . . . . . . . . . . . . . 15-9
Location of Dynamically Added Log Files . . . . . . . . . . . . . . . . . . . . . . 15-9
Adding Logical-Log Files Manually . . . . . . . . . . . . . . . . . . . . . . . . . 15-10
Dropping Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-11
Changing the Size of Logical-Log Files . . . . . . . . . . . . . . . . . . . . . . . . . 15-12
Moving a Logical-Log File to Another Dbspace . . . . . . . . . . . . . . . . . . . . . . 15-12
Changing Logging Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . 15-13
Using ON-Monitor to Change LOGFILES (UNIX). . . . . . . . . . . . . . . . . . . . . 15-14
Displaying Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . . . . . 15-14
Monitoring Events for Dynamically Added Logs . . . . . . . . . . . . . . . . . . . . . . 15-14
Setting High-Watermarks for Rolling Back Long Transactions . . . . . . . . . . . . . . . . . . 15-15
Long-Transaction High-Watermark (LTXHWM) . . . . . . . . . . . . . . . . . . . . . 15-16
Exclusive Access, Long-Transaction High-Watermark (LTXEHWM) . . . . . . . . . . . . . . . 15-16
Adjusting the Size of Log Files to Prevent Long Transactions . . . . . . . . . . . . . . . . . 15-16
Recovering from a Long Transaction Hang . . . . . . . . . . . . . . . . . . . . . . . 15-16

In This Chapter
You must manage logical-log files even if none of your databases uses transaction
logging. See Chapter 14, “Logical Log,” on page 14-1 for background information
on logical logs.

You must log in as either informix or root on UNIX to make any of the changes
described in this chapter. You must be a member of the Informix-Admin group on
Windows.

You perform these tasks when setting up your logical log:

v Before you initialize or restart the database server, use the LOGFILES parameter
to specify the number of logical-log files to create.

© Copyright IBM Corp. 1996, 2005 15-1

 v After the database server is online, estimate the size and number of logical-log
files that your system will need.
See “Estimating the Size and Number of Log Files” on page 15-2.
v If you do not want to use the default values, change the LOGSIZE and
LOGBUFF configuration parameters.
See “Changing Logging Configuration Parameters” on page 15-13.
v Add the estimated number of logical-log files.
See “Allocating Log Files” on page 15-8.

You perform the following tasks routinely:

v Backing up a logical-log file
v Switching to the next logical-log file
v Freeing a logical-log file
v Monitoring logging activity and log-backup status

You perform these tasks occasionally, if necessary:

v Adding a logical-log file
v Dropping a logical-log file
v Changing the size of a logical-log file
v Moving a logical-log file
v Changing the logical-log configuration parameters
v Monitoring event alarms for logical logs
v Setting high-watermarks for transactions

Estimating the Size and Number of Log Files

Use the LOGSIZE configuration parameter to set the size of the logical-log files. It
is difficult to predict how much logical-log space your database server system
requires until it is fully in use.

The easiest way to increase the amount of space for the logical log is to add
another logical-log file. See “Adding Logical-Log Files Manually” on page 15-10.

The following expression provides the recommended minimum total-log-space

configuration, in kilobytes:
LOGSIZE = (((connections * maxrows) * rowsize) / 1024) / LOGFILES

15-2 IBM Informix Dynamic Server Administrator’s Guide

 Expression
Element Explanation
LOGSIZE Specifies the size of each logical-log file in kilobytes.
connections Specifies the maximum number of connections for all network types that
you specify in the sqlhosts file or registry and in the NETTYPE parameter.
If you configured more than one connection by setting multiple NETTYPE
configuration parameters in your configuration file, sum the users fields for
each NETTYPE, and substitute this total for connections in the preceding
formula.
maxrows Specifies the largest number of rows to be updated in a single transaction.
rowsize Specifies the average size of a table row in bytes. To calculate the rowsize,
add up the length (from the syscolumns system catalog table) of the
columns in the row.
1024 Converts the LOGSIZE to units of kilobytes.
LOGFILES Specifies the number of logical-log files.

Estimating the Log Size When Logging Smart Large Objects

If you plan to log smart-large-object user data, you must ensure that the log size is
considerably larger than the amount of data being written. If you store smart large
objects in standard sbspaces, the metadata is always logged, even if the smart large
objects are not logged. If you store smart large objects in temporary sbspaces, there
is no logging at all.

Estimating the Number of Logical-Log Files

The LOGFILES parameter provides the number of logical-log files at system
initialization or restart. If all your logical-log files are the same size, you can
calculate the total space allocated to the logical-log files as follows:
total logical log space = LOGFILES * LOGSIZE

If the database server contains log files of different sizes, you cannot use the
(LOGFILES * LOGSIZE) expression to calculate the size of the logical log. Instead,
you need to add the sizes for each individual log file on disk. Check the size field
in the onstat -l output. For more information, see “onstat -l” on page 15-6.

For information on LOGSIZE, LOGFILES, and NETTYPE, see the chapter on

configuration parameters in the IBM Informix Administrator's Reference.

Backing Up Logical-Log Files

The logical logs contain a history of the transactions that have been performed.
The process of copying a logical-log file to media is referred to as backing up a
logical-log file. Backing up logical-log files achieves the following two objectives:
v It stores the logical-log records on media so that they can be rolled forward if a
data restore is needed.
v It makes logical-log-file space available for new logical-log records.
If you neglect to back up the log files, you can run out of log space.

You can initiate a manual logical-log backup or set up continuous logical-log

backups. After you restore the storage spaces, you must restore the logical logs to
bring the data to a consistent state. For more information on log backups, see the
IBM Informix Backup and Restore Guide.

Chapter 15. Managing Logical-Log Files 15-3

 Backing Up Blobspaces
It does not matter whether you back up the logical logs or blobspaces first.

To back up blobspace data:

1. Close the current logical log if it contains transactions on simple large objects in
a blobspace.
2. Perform a backup of the logical logs and blobspace as soon as possible after
updating simple-large-object data.

Warning: If you do not back up these blobspaces and logical logs, you might not
be able to restore the blobspace data. If you wait until a blobspace is
down to perform the log backup, the database server cannot access the
blobspace to copy the changed data into the logical log.

Backing Up Sbspaces
When you turn on logging for smart large objects, you must perform a level-0
backup of the sbspace.

Figure 15-1 shows what happens if you turn on logging in an sbspace that is not
backed up. The unlogged changes to smart large object LO1 are lost during the
failure, although the logged changes are recoverable. You will not be able to fully
restore LO1.

During fast recovery, the database server rolls forward all committed transactions
for LO1. If LO1 is unlogged, the database server would be unable to roll back
uncommitted transactions. Then the LO1 contents would be incorrect. For more
information, refer to “Fast Recovery” on page 16-11.

Logging is off

These updates are lost when

database server fails.

Turn on logging

These updates are recovered

in fast recovery.
Failure
Smart large object LO1 (not backed up)

Figure 15-1. Turning On Logging in an Sbspace

Switching to the Next Logical-Log File

You might want to switch to the next logical-log file before the current log file
becomes full for the following reasons:
v To back up the current log
v To activate new blobspaces and blobspace chunks

The database server can be in online mode to make this change. Execute the
following command to switch to the next available log file:
onmode -l

The change takes effect immediately. (Be sure that you type a lowercase L on the
command line, not a number 1.)

15-4 IBM Informix Dynamic Server Administrator’s Guide

Freeing a Logical-Log File
If a log file is newly added (status A), it is immediately available for use. It also
can be dropped immediately.

You might want to free a logical-log file for the following reasons:
v So that the database server does not stop processing
v To free the space used by deleted blobpages

The procedures for freeing log files vary, depending on the status of the log file.
Each procedure is described in the following sections. To find out the status of
logical-log files, see “Status Flags of Logical-Log Files” on page 14-3 and
“Monitoring Logging Activity” on page 15-6.

Tip: For information using ON–Bar or ontape to back up storage spaces and
logical logs, refer to the IBM Informix Backup and Restore Guide.

Deleting a Log File with Status D

When you drop a used log file, it is marked as deleted (status D) and cannot be
used again, and onparams prints this message:
Log file log_file_number has been pre-dropped. It will be
deleted from the log list and its space can be reused
once you take level 0 archives of all BLOBspaces,
Smart BLOBspaces and non-temporary DBspaces.

To delete the log file, create a level-0 backup of all storage spaces.

Freeing a Log File with Status U

If a log file contains records, but is not yet backed up (status U), back up the file
using the backup tool that you usually use.

If backing up the log file does not change the status to free (F), its status changes
to either U-B or U-B-L. See “Freeing a Log File with Status U-B or F,” following, or
“Freeing a Log File with Status U-B-L” on page 15-6.

Freeing a Log File with Status U-B or F

If a log file is backed up but still in use (status U-B), some transactions in the log
file are still under way, or the log file contains the oldest update that is required
for fast recovery. Because a log file with status F has been used in the past, it
follows the same rules as for status U-B.

To free a backed up log file that is in use:

1. If you do not want to wait until the transactions complete, take the database
server to quiescent mode. See “Immediately from Online to Quiescent” on page
4-12. Any active transactions are rolled back.
2. Because a log file with status U-B might contain the oldest update, you must
use the onmode -c command to force a full checkpoint.

A log file that is backed up but not in use (status U-B) does not need to be freed.
In the following example, log 34 does not need to be freed, but logs 35 and 36 do.
Log 35 contains the last checkpoint, and log 36 is backed up but still in use.

Chapter 15. Managing Logical-Log Files 15-5

 34 U-B-- Log is used, backed up, and not in use
35 U-B-L Log is used, backed up, contains last checkpoint
36 U-B-- Log is used, backed up, and not in use
37 U-C-- This is the current log file, not backed up

Tip: You can free a logical log with a status of U-B (and not L) only if it is not
spanned by an active transaction and does not contain the oldest update.

Freeing a Log File with Status U-C or U-C-L

Follow these steps to free the current log file.

To free the current log file (status C):

1. Execute the following command to switch the current log file to the next
available log file:
onmode -l
2. Back up the original log file with ON–Bar or ontape.
3. After all full log files are backed up, you are prompted to switch to the next
available log file and back up the new current log file.
You do not need to do the backup because you just switched to this log file.

After you free the current log file, if the log file has status U-B or U-B-L, refer to
“Freeing a Log File with Status U-B or F” on page 15-5 or “Freeing a Log File with
Status U-B-L.”

Freeing a Log File with Status U-B-L

If a log file is backed up and all transactions within it are closed but the file is not
free (status U-B-L), this logical-log file contains the most-recent checkpoint record.

To free log files with a status U-B-L, the database server must create a new
checkpoint. You can execute the following command to force a checkpoint:
onmode -c

UNIX Only

To force a checkpoint with ON–Monitor, select the Force-Ckpt option.

End of UNIX Only

Monitoring Logging Activity

Monitor the logical-log files to determine the total available space (in all the files),
the space available in the current file, and the status of a file (for example, whether
the log has been backed up yet). For information on monitoring the logical-log
buffers, see “Monitoring Physical and Logical-Logging Activity” on page 17-3.

Monitoring the Logical Log for Fullness

You can use the following command-line utilities to monitor logical-log files.

onstat -l
The onstat -l command displays information about physical and logical logs.

The output section that contains information on each logical-log file includes the
following information:

15-6 IBM Informix Dynamic Server Administrator’s Guide

 v The address of the logical-log file descriptor
v The log file number
v Status flags that indicate the status of each log (free, backed up, current, and so
on)
v The unique ID of the log file
v The beginning page of the file
v The size of the file in pages, the number of pages used, and the percentage of
pages used
The log file numbers in the numbers field can get out of sequence if you drop
several logs in the middle of the list or if the database server dynamically adds log
files.

For more information on and an example of onstat -l output, see the IBM Informix
Administrator's Reference.

oncheck -pr
The database server stores logical-log file information in the reserved pages
dedicated to checkpoint information. Because the database server updates this
information only during a checkpoint, it is not as recent as the information that the
onstat -l option displays. For more details on using these options to display
reserved page information, see the IBM Informix Dynamic Server Administrator's
Reference.

You can view the checkpoint reserved pages with the oncheck -pr command.
Figure 15-2 shows sample output for one of the logical-log files.

...
Log file number 1
Unique identifier 7
Log contains last checkpoint Page 0, byte 272
Log file flags 0x3 Log file in use
Current log file
Physical location 0x1004ef
Log size 750 (p)
Number pages used 1
Date/Time file filled 01/29/2001 14:48:32
...

Figure 15-2. oncheck -pr Output Containing Logical-Log File Information

Monitoring Temporary Logical Logs

The database server uses temporary logical logs to roll forward transactions during a
warm restore, because the permanent logs are not available then. When the roll
forward completes, the database server frees the temporary log files. If you issue
onstat -l during a warm restore, the output includes a fourth section on temporary
log files in the same format as regular log files. Temporary log files use only the B,
C, F, and U status flags.

Using SMI Tables

Query the syslogs table to obtain information on logical-log files. This table
contains a row for each logical-log file. The columns are as follows.
Column Description
number Identification number of the logical-log file
uniqid Unique ID of the log file

Chapter 15. Managing Logical-Log Files 15-7

 size Size of the file in pages
used Number of pages used
is_used Flag that indicates whether the log file is being used
is_current Flag that indicates whether the log file is current
is_backed_up Flag that indicates whether the log file has been backed up
is_new Flag that indicates whether the log file has been added since the
last storage space backup
is_archived Flag that indicates whether the log file has been written to the
archive tape
is_temp Flag that indicates whether the log file is flagged as a temporary
log file

Using ON-Monitor (UNIX)

The Status > Logs option displays much of the same information for logical-log
files as the onstat -l option displays. In addition, a column contains the dbspace in
which each logical-log file is located.

Monitoring Log-Backup Status

To monitor the status of the logs and to see which logs have been backed up, use
the onstat -l command. A status flag of B indicates that the log has been backed
up.

Allocating Log Files

When you initialize or restart the database server, it creates the number of
logical-log files that you specify in the LOGFILES configuration parameter. These
log files are the size that you specify in the LOGSIZE parameter.

Adding Logs Dynamically

The DYNAMIC_LOGS configuration parameter determines when the database
server dynamically adds a logical-log file. When you use the default value of 2 for
DYNAMIC_LOGS, the database server dynamically adds a new log file and sets
off an alarm if the next active log file contains the beginning of the oldest open
transaction.

The database server checks the logical-log space at these points:

v After switching to a new log file
v At the beginning of the transaction-cleanup phase of logical recovery

If the DYNAMIC_LOGS parameter is set to 1 and the next active log file contains
records from an open transaction, the database server prompts you to add a log
file manually and sets off an alarm. After you add the log file, the database server
resumes processing the transaction.

If the DYNAMIC_LOGS parameter is set to 0 and the logical log runs out of space
during a long transaction rollback, the database server can hang. (The long
transaction prevents the first logical-log file from becoming free and available for
reuse.) To fix the problem, set DYNAMIC_LOGS to 2 and restart the database
server. Then the long transaction should be able to complete.

15-8 IBM Informix Dynamic Server Administrator’s Guide

For more information, see “Monitoring Events for Dynamically Added Logs” on
page 15-14 and “Setting High-Watermarks for Rolling Back Long Transactions” on
page 15-15.

Size and Number of Dynamically Added Log Files

When dynamically adding a log file, the database server uses the following factors
to calculate the size of the log file:
v Average log size
v Amount of contiguous space available

If the logical log is low on space, the database server adds as many log files as
needed to complete the transaction. The number of log files is limited by:
v The maximum number of log files supported
v The amount of disk space for the log files
v The amount of free contiguous space in the root chunk

If the database server stops adding new log files because it is out of disk space, it
writes an error message and sets off an alarm. Add a dbspace or chunk to an
existing dbspace. Then the database server automatically resumes processing the
transaction.

The reserve pages in the root chunk store information about each log file. The
extents that contain this information expand as more log files are added. The root
chunk requires two extents of 1.4 megabytes each to track 32,767 log files, the
maximum number supported.

If during reversion, the chunk reserve page extent is allocated from a non-root
chunk, the server attempts to put it back in the root chunk. If not enough space is
available in the root chunk, the reversion fails. A message containing the required
space displays in the online log. The required space needs to be freed from the root
chunk before trying the reversion again.

Location of Dynamically Added Log Files

The database server allocates log files in dbspaces, in the following search order. A
dbspace becomes critical if it contains logical-log files or the physical log.
Pass Allocate Log File In
1 The dbspace that contains the newest log files
(If this dbspace is full, the database server searches other
dbspaces.)
2 Mirrored dbspace that contains log files (but excluding the root
dbspace)
3 All dbspaces that already contain log files (excluding the root
dbspace)
4 The dbspace that contains the physical log
5 The root dbspace
6 Any mirrored dbspace
7 Any dbspace

If you do not want to use this search order to allocate the new log file, you must
set the DYNAMIC_LOGS parameter to 1 and execute onparams -a -i with the

Chapter 15. Managing Logical-Log Files 15-9

 location you want to use for the new log. For details, refer to “Monitoring Events
for Dynamically Added Logs” on page 15-14.

Adding Logical-Log Files Manually

You might add logical-log files manually for the following reasons:
v To increase the disk space allocated to the logical log
v To change the size of your logical-log files
v To enable an open transaction to complete
v As part of moving logical-log files to a different dbspace

Warning: You cannot do the following:

v Add a log file to a blobspace or sbspace.
v Add logical or physical logs to dbspaces that have non-default page
sizes.

Add logical-log files one at a time, up to a maximum of 32,767 files, to any

dbspace. As soon as you add a log file to a dbspace, it becomes a critical dbspace.
You can add a logical-log file during a storage space backup.

The two ways you can add a logical-log file are:

v To the end of the file list using the onparams -a command or ISA
v After the current logical-log file using the onparams -a -i command or ISA

To add a logical-log file using onparams:

1. Login as user informix or root on UNIX or as a member of the
Informix-Admin group on Windows.
2. Ensure that the database server is in online, single-user, or quiescent, or
cleanup phase of fast-recovery mode.
The database server writes the following message to the log during the cleanup
phase:
Logical recovery has reached the transaction cleanup phase.
3. Decide whether you want to add the log file to the end of the log file list or
after the current log file.
You can insert a log file after the current log file regardless of the
DYNAMIC_LOGS parameter value. Adding a log file of a new size does not
change the value of LOGSIZE.
a. The following command adds a logical-log file to the end of the log file list
in the logspace dbspace, using the log-file size specified by the LOGSIZE
configuration parameter:
onparams -a -d logspace
b. The following command inserts a 1000-kilobyte logical-log file after the
current log file in the logspace dbspace:
onparams -a -d logspace -s 1000 -i
c. To add a logical-log file with a new size (in this case, 250 kilobytes), execute
the following command:
onparams -a -d logspace -s 250
4. Use onstat -l to check the status of the log files. The status of the new log file is
A and is immediately available.
5. The next time you need to back up data, perform a level-0 backup of the root
dbspace and the dbspaces that contain the new log files.

15-10 IBM Informix Dynamic Server Administrator’s Guide

 Although you no longer need to back up immediately after adding a log file,
your next backup should be level-0 because the data structures have changed.
For information on backing up data, refer to the IBM Informix Backup and
Restore Guide.

For more information on using onparams to add a logical-log file, see the IBM
Informix Administrator's Reference.

To add a logical-log file using ISA:

1. Select Logs > Logical and click Add Log File.
2. Use onstat -l to check the status of the log files.
For more information, see the ISA online help.

To add a logical-log file with ON-Monitor (UNIX):

1. Follow the instructions on adding a log file in “Adding Logical-Log Files
Manually” on page 15-10, except use ON–Monitor instead of onparams.
2. Select Parameters > Add-Log to add a logical-log file.
3. In the field labelled Dbspace Name, enter the name of the dbspace where the
new logical-log file will reside.
The size of the log file automatically appears in the Logical Log Size field. The
new log file is always the value specified by LOGSIZE.

Dropping Logical-Log Files

To drop a logical-log file and increase the amount of the disk space available
within a dbspace, you can use onparams or ISA. The database server requires a
minimum of three logical-log files at all times. You cannot drop a log if your
logical log is composed of only three log files.

The rules for dropping log files have changed:

v If you drop a log file that has never been written to (status A), the database
server deletes it and frees the space immediately.
v If you drop a used log file (status U-B), the database server marks it as deleted
(D). After you take a level-0 backup of the dbspaces that contain the log files
and the root dbspace, the database server deletes the log file and frees the space.
v You cannot drop a log file that is currently in use or contains the last checkpoint
record (status C or L).

To drop a logical-log file with onparams:

1. Ensure that the database server is in online, single-user, or quiescent mode.
2. Execute the following command to drop a logical-log file whose log file
number is 21:
onparams -d -l 21
Drop log files one at a time. You must know the log file number of each logical
log that you intend to drop.
3. If the log file has a status of newly Added (A), it is dropped immediately.
If the log file has a status of Used (U), it is marked as Deleted (D).
4. To drop a used log file, take a level-0 backup of all the dbspaces.
This backup prevents the database server from using the dropped log files
during a restore and ensures that the reserved pages contain information about
the current number of log files.

Chapter 15. Managing Logical-Log Files 15-11

 For information on using onparams to drop a logical-log file, see the IBM Informix
Administrator's Reference.

For information on using onlog to display the logical-log files and unique ID
numbers, see “Displaying Logical-Log Records” on page 15-14.

To drop a logical-log file with ON_Monitor (UNIX):

1. Ensure that the database server is in online, single-user, or quiescent mode.
2. To drop a logical-log file, select Parameters > Drop-Log.
3. If the log file has a status of newly Added (A), it is dropped immediately.
If the log file has a status of Used (U), it is marked as Deleted (D).
4. To drop a used log file, take a level-0 backup of all the dbspaces.

Tip: If the root dbspace has never been backed up, you can drop a used log file
immediately.

Changing the Size of Logical-Log Files

If you want to change the size of the log files, it is easier to add new log files of
the desired size and then drop the old ones. You can change the size of logical-log
files in the following ways:
v Use onparams with the -s option to add a new log file of a different size.
See “Adding Logical-Log Files Manually” on page 15-10.
v Increase the LOGSIZE value in the ONCONFIG file if you want the database
server to create larger log files.
See “Changing Logging Configuration Parameters” on page 15-13.

Moving a Logical-Log File to Another Dbspace

You might want to move a logical-log file for performance reasons or to make
more space in the dbspace, as explained in “Location of Logical-Log Files” on page
14-2. To find the location of logical-log files, see “Monitoring Logging Activity” on
page 15-6. Although moving the logical-log files is not difficult, it can be
time-consuming.

Moving logical-log files is a combination of two simpler actions:

v Dropping logical-log files from their current dbspace
v Adding the logical-log files to their new dbspace

The following procedure provides an example of how to move six logical-log files
from the root dbspace to another dbspace, dbspace_1.

Warning: You cannot move logical and physical log files in dbspaces that have
non-default page sizes.

To move the logical-log files out of the root dbspace (example):

1. Ensure that the database server is in online, single-user, quiescent, or
fast-recovery mode.
2. Add six new logical-log files to dbspace_1.
See “Adding Logical-Log Files Manually” on page 15-10.
3. Take a level-0 backup of all storage spaces to free all log files except the current
log file.

15-12 IBM Informix Dynamic Server Administrator’s Guide

 (If you use onbar -l -b -c, you back up all log files including the current log
file.) See “Freeing a Logical-Log File” on page 15-5.
4. Use onmode -l to switch to a new current log file.
See “Switching to the Next Logical-Log File” on page 15-4.
5. Drop all six logical-log files in the root dbspace.
You cannot drop the current logical-log file.
See “Dropping Logical-Log Files” on page 15-11.
6. Create a level-0 backup of the root dbspace and dbspace_1.
For more information, see the IBM Informix Backup and Restore Guide.

Changing Logging Configuration Parameters

You can use a text editor or ISA to change ONCONFIG parameters. This table
shows the configuration parameters for logical logs. For more information, see the
chapter on configuration parameters in the IBM Informix Administrator's Reference.

Configuration
Parameter Minimum Value Default Value Maximum Value
DYNAMIC_LOGS 0 or 1 2 2
LOGBUFF 2 * page size 32 KB LOGSIZE value
LOGFILES 3 files 6 files 32,767 files
LOGSIZE 1500 KB on UNIX 2000 KB See the IBM Informix
Administrator's Reference
500 KB on Windows
LTXEHWM LTXHWM value 90% 100%
LTXHWM 1% 80% 100%

Important: The change to LOGFILES does not take effect until you reinitialize or
restart the disk space.

To change the logical-log configuration parameters in the ONCONFIG file:

1. Bring the database server offline or into quiescent or single-user mode.
2. Use ISA or a text editor to update the configuration parameters.
The DYNAMIC_LOGS, LTXHWM, and LTXEHWM parameters are not in the
[Link] file. To change the values of these parameters, add them to your
ONCONFIG file.
3. Shut down and restart the database server.
4. Perform this step only if you are changing LOGFILES and want all of the log
files to be in continuous space. (Normally you add and drop LOGFILES using
the onparams utility.)
a. Unload all the database server data. Do this because you cannot rely on
storage space backups to unload and restore the data because a restore
returns the parameters to their previous value.
b. Reinitialize the database server disk space. See “Initializing Disk Space” on
page 4-2.
c. Re-create all databases and tables.
d. Reload all the database server data.
For information on loading and unloading data, see the IBM Informix
Migration Guide.

Chapter 15. Managing Logical-Log Files 15-13

 5. Back up the root dbspace to enable your changed logical logs.

Using ON-Monitor to Change LOGFILES (UNIX)

You can use ON–Monitor to change the values of LOGFILES.

To change these values:

1. Unload all the database server data.
You cannot rely on storage space backups to unload and restore the data
because a restore returns the parameters to their previous value.
2. Select Parameters > Initialize to reinitialize disk space or modify disk-space
parameters.
3. Change the value of LOGSIZE in the field labelled [Link] Size, or change the
value of LOGFILES in the field labelled Number of Logical Logs.
4. Proceed with the database server disk-space initialization.
5. Re-create all databases and tables.
6. Reload all the database server data.
For information on loading and unloading data, see the IBM Informix Migration
Guide.

Displaying Logical-Log Records

Use the onlog utility to display and interpret logical-log records. For information
on using onlog, see the IBM Informix Administrator's Reference.

Monitoring Events for Dynamically Added Logs

Monitor the following event alarms that dynamically added log files trigger (see
Table 15-1). When each alarm is triggered, a message is written to the message log.
For more information, see the chapters on event alarms and configuration
parameters in the IBM Informix Administrator's Reference.

You can include the onparams command to add log files in your alarm script for
event class ID 27, log file required. Your script can also execute the onstat -d
command to check for adequate space and execute the onparams a -i command
with the location that has enough space. You must use the -i option to add the
new log right after the current log file.

15-14 IBM Informix Dynamic Server Administrator’s Guide

Table 15-1. Event Alarms for Dynamically Added Log Files
Class ID Severity Class Message Message
26 3 Dynamically added log This message displays when the database server dynamically
file log_number adds a log file.

Dynamically added log file log_number to DBspace

dbspace_number.
27 4 Log file required This message displays when DYNAMIC_LOGS is set to 1 and the
database server is waiting for you to add a log file.

ALERT: The oldest logical log log_number contains records from

an open transaction transaction_address. Logical logging will
remain blocked until a log file is added. Add the log file with the
onparams -a command, using the -i (insert) option, as in:
onparams -a -d dbspace -s size-i

Then complete the transaction as soon as possible.

28 4 No space for log file ALERT: Because the oldest logical log log_number contains
records from an open transaction transaction_address, the
server is attempting to dynamically add a log file. But there is no
space available. Please add a dbspace or chunk. Then complete
the transaction as soon as possible.

Table 15-2 shows the actions that the database server takes for each setting of the
DYNAMIC_LOGS configuration parameter.
Table 15-2. DYNAMIC_LOGS Settings
DYNAMIC_
LOGS Meaning Event Alarm Wait to Add Log Dynamic Log Add
2 (default) Allows automatic allocation of new log Yes (26, 28) No Yes
files to prevent open transactions from
hanging the system.
1 Allows manual addition of new log files. Yes (27) Yes No
0 Does not allocate log files but issues the No No No
following message about open
transactions:

WARNING: The oldest logical-log file

log_number contains records from an open
transaction transaction_address, but the
dynamic log feature is turned off.

Setting High-Watermarks for Rolling Back Long Transactions

The database server uses the LTXHWM and LTXEHWM configuration parameters
to set high-watermarks for long transactions. If DYNAMIC_LOGS is set to 1 or 2,
the default LTXHWM value is 80 percent and LTXEHWM is 90 percent. If
DYNAMIC_LOGS is set to 0, the default LTXHWM value is 50 percent and the
default LTXHEWM value is 60 percent.

If you decrease your high-watermark values, you increase the likelihood of long
transactions. To compensate, allocate additional log space. For information on
LTXHWM and LTXEHWM, see the chapter on configuration parameters in the IBM
Informix Administrator's Reference.

Chapter 15. Managing Logical-Log Files 15-15

 Long-Transaction High-Watermark (LTXHWM)
The long-transaction high-watermark is the percentage of total log space that a
transaction is allowed to span before it is rolled back. If the database server finds
an open transaction in the oldest used log file, it dynamically adds log files.
Because the log space is increasing, the high-watermark expands outward. When
the log space reaches the high-watermark, the database server rolls back the
transaction. The transaction rollback and other processes also generate logical-log
records. The database server continues adding log files until the rollback is
complete to prevent the logical log from running out of space. More than one
transaction can be rolled back if more than one long transaction exists.

For example, the database server has ten logical logs and LTXHWM is set to 98. A
transaction begins in log file 1 and update activity fills logs 1 through 9. The
database server dynamically adds log file 11 after log file 10. As long as the
transaction does not complete, this process continues until the database server has
added 40 log files. When the database server adds the fiftieth log, the transaction
has caught up to the high-watermark and the database server rolls it back.

Exclusive Access, Long-Transaction High-Watermark

(LTXEHWM)
The exclusive-access, long-transaction high-watermark occurs when the long transaction
currently being rolled back is given exclusive access to the logical log. The database
server dramatically reduces log-record generation. Only threads that are currently
rolling back transactions and threads that are currently writing COMMIT records
are allowed access to the logical log. Restricting access to the logical log preserves
as much space as possible for rollback records that are being written by the user
threads that are rolling back transactions.

Warning: If you set both LTXHWM and LTXEHWM to 100, long transactions are
never stopped. Therefore, you should set LTXHWM to below 100 for
normal database server operations. Set LTXHWM to 100 to run
scheduled transactions of unknown length. Set LTXEHWM to 100 if you
never want to block other users while a long transaction is rolling back
and you have ample disk space.

Adjusting the Size of Log Files to Prevent Long Transactions

Use larger log files when many users are writing to the logs at the same time. If
you use small logs and long transactions are likely to occur, reduce the
high-watermark. Set the LTXHWM value to 50 and the LTXEHWM value to 60.

If the log files are too small, the database server might run out of log space while
rolling back a long transaction. In this case, the database server cannot block fast
enough to add a new log file before the last one fills. If the last log file fills, the
system will hang and display an error message. To fix the problem, shut down and
restart the database server. For details, see “Recovering from a Long Transaction
Hang” on page 15-16.

Recovering from a Long Transaction Hang

If your system has ample disk space and you want to perform transactions of
unknown length, consider setting LTXHWM to 100 to force the database server to
continue adding log files until you complete the transaction.

15-16 IBM Informix Dynamic Server Administrator’s Guide

A transaction might hang because the database server has run out of disk space.
The database server stops adding new log files, writes an error message, and sets
off an alarm.

To continue the transaction:

1. To continue the transaction, add a dbspace or chunk to a dbspace.
2. Resume processing the transaction.

If you cannot add more disk space to the database server, end the transaction.

To end the transaction:

v Issue the onmode -z command.
v Shut down and restart the database server.

When the database server comes up in fast-recovery mode, the transaction is rolled
back. Then perform the following steps:

To recover from a long transaction hang:

1. Add more disk space or another disk until the transaction is successfully rolled
back.
2. Perform a point-in time restore to a time before the long transaction began or
early enough for the database server to roll back the transaction.
3. Drop the extra log files, dbspaces, or chunks from the database server instance.
4. Perform a complete level-0 backup to free the logical-log space.

Chapter 15. Managing Logical-Log Files 15-17

15-18 IBM Informix Dynamic Server Administrator’s Guide
Chapter 16. Physical Logging, Checkpoints, and Fast
Recovery
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Physical Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-2
Fast Recovery Use of Physically-Logged Pages . . . . . . . . . . . . . . . . . . . . . . 16-2
Backup Use of Physically-Logged Pages . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Database Server Activity That Is Physically Logged . . . . . . . . . . . . . . . . . . . . 16-3
Physical Recovery Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Physical Logging and Simple Large Objects . . . . . . . . . . . . . . . . . . . . . . 16-3
Physical Logging and Smart Large Objects . . . . . . . . . . . . . . . . . . . . . . 16-4
Size and Location of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Specifying the Location of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . 16-4
Estimating the Size of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Configuring the Size of the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . 16-5
Physical-Log Overflow When Many Users Are in Critical Sections . . . . . . . . . . . . . . 16-5
Effect of Checkpoints on the Physical-Log Size . . . . . . . . . . . . . . . . . . . . . 16-5
Physical-Log Overflow When Transaction Logging Is Turned Off . . . . . . . . . . . . . . . 16-5
Details of Physical Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-6
Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7
Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7
Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-7
Fuzzy Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-8
Write-Ahead Logging and Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . 16-8
Fuzzy Checkpoints Improve Performance . . . . . . . . . . . . . . . . . . . . . . . 16-8
Events That Initiate a Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . 16-9
Events That Initiate a Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . 16-9
Sequence of Events in a Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . 16-9
User Threads Cannot Enter a Critical Section . . . . . . . . . . . . . . . . . . . . . 16-10
Logical-Log Buffer Is Flushed to the Logical-Log File on Disk . . . . . . . . . . . . . . . 16-10
The Physical-Log Buffer is Flushed to the Physical Log on Disk . . . . . . . . . . . . . . . 16-10
Modified Pages in the Buffer Pool Are Flushed to Disk . . . . . . . . . . . . . . . . . . 16-10
Checkpoint Thread Writes Checkpoint Record . . . . . . . . . . . . . . . . . . . . . 16-10
Physical Log Is Logically Emptied . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Backup and Restore Considerations . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Need for Fast Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-11
Situations When Fast Recovery Is Initiated . . . . . . . . . . . . . . . . . . . . . . . 16-11
Fast Recovery and Buffered Logging . . . . . . . . . . . . . . . . . . . . . . . . 16-12
Possible Physical Log Overflow During Fast Recovery . . . . . . . . . . . . . . . . . . 16-12
Fast Recovery and No Logging . . . . . . . . . . . . . . . . . . . . . . . . . . 16-12
Details of Fast Recovery After A Full Checkpoint . . . . . . . . . . . . . . . . . . . . . 16-12
Returning to the Last-Checkpoint State . . . . . . . . . . . . . . . . . . . . . . . 16-13
Finding the Checkpoint Record in the Logical Log . . . . . . . . . . . . . . . . . . . 16-13
Rolling Forward Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . . 16-13
Rolling Back Incomplete Transactions . . . . . . . . . . . . . . . . . . . . . . . . 16-13
Details of Fast Recovery After A Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . 16-14
Returning to the Last-Checkpoint State for Nonfuzzy Operations . . . . . . . . . . . . . . 16-15
Locating the Oldest Update in the Logical Log . . . . . . . . . . . . . . . . . . . . 16-15
Applying the Log Records for Fuzzy Operations . . . . . . . . . . . . . . . . . . . . 16-16
Rolling Forward Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . . 16-16
Rolling Back Incomplete Transactions . . . . . . . . . . . . . . . . . . . . . . . . 16-16

© Copyright IBM Corp. 1996, 2005 16-1

 Alternative Fast Restart Recovery Options for Fuzzy Operations . . . . . . . . . . . . . . . . 16-17

In This Chapter
This chapter covers the three procedures that the database server uses to achieve
data consistency:
v Physical logging
v Checkpoints
v Fast recovery

The physical log is a set of disk pages where the database server stores an
unmodified copy of the page called a before-image. Physical logging is the process of
storing a before-image of a page that the database server is going to change. A
checkpoint refers to a point when the database server synchronizes the pages on
disk with the pages in the shared-memory buffers. Fast recovery is an automatic
procedure that restores the database server to a consistent state after it goes offline
under uncontrolled conditions.

These procedures ensure that multiple, logically related writes are recorded as a
unit, and that data in shared memory is periodically made consistent with data on
disk.

For the tasks to manage and monitor the physical log and checkpoints, see
Chapter 17, “Managing the Physical Log,” on page 17-1.

Critical Sections
A critical section is a section of code (or machine instructions) that must be
performed as a single unit. A critical section ensures the integrity of a thread by
allowing it to execute a series of instructions before it is swapped out.

Physical Logging
Physical logging is the process of storing the pages that the database server is going
to change before the changed pages are actually recorded on disk. Before the
database server modifies certain pages in the shared-memory buffer pool, it stores
before-images of the pages in the physical-log buffer in shared memory.

The database server maintains the before-image page in the physical-log buffer in
shared memory for those pages until one or more page cleaners flush the pages to
disk. The unmodified pages are available in case the database server fails or the
backup procedure needs them to provide an accurate snapshot of the database
server data. Fast recovery and database server backups use these snapshots.

The database server empties the physical log at each checkpoint (except in the
special circumstances explained in “Configuring the Size of the Physical Log” on
page 16-5). For more information on checkpoints, see “Checkpoints” on page 16-7.

Fast Recovery Use of Physically-Logged Pages

After a failure, the database server uses the before-images of pages modified by
non-fuzzy operations to restore these pages on the disk to their state at the last
checkpoint. Then the database server uses the logical-log records to return all data
to physical and logical consistency, up to the point of the most-recently completed
transaction. “Fast Recovery” on page 16-11 explains this procedure in more detail.

16-2 IBM Informix Dynamic Server Administrator’s Guide

Backup Use of Physically-Logged Pages
When you perform a backup, the database server performs a checkpoint and uses
the physical log to find the changed pages. In a level-0 backup, the database server
backs up all disk pages. In a level-1 or level-2 backup, the database server backs
up only the changed pages. For more details, see the IBM Informix Backup and
Restore Guide.

Database Server Activity That Is Physically Logged

In case of multiple modifications before the next checkpoint, only the first
before-image is logged in the physical log.

The database server stores the before-images in the physical log only until the next
checkpoint. To control the amount of data that the database server logs, you can
tune the checkpoint interval configuration parameter CKPTINTVL.

The following dbspace page modifications are not physically logged:

v Pages that do not have a valid database server address
This situation usually occurs when the page was used by some other database
server or a table that was dropped.
v Pages that the database server has not used and that are located in a dbspace
where no table has been dropped since the last checkpoint
v Pages for fuzzy operations

Important: The database server no longer logs the before-images for fuzzy
operations in the physical log. It still tracks these updates in the logical
log. For a definition of fuzzy operations, see “Fuzzy Operations” on
page 16-8.

Physical Recovery Messages

When fast recovery begins, the database server logs the following message:
Physical recovery started at page chunk:offset.

When the fast recovery completes, the database server logs the following message:
Physical recovery complete: number pages examined, number pages restored.

If the number of pages examined is much larger than the number of pages restored,
increase the size of the buffer pool to reduce the number of duplicate
before-images. For more information, see the messages appendix in the IBM
Informix Administrator's Reference.

Physical Logging and Simple Large Objects

The database server pages in the physical log can be any database server page,
including simple large objects in tblspaces. Even overhead pages (such as chunk
free-list pages) are copied to the physical log before data on the page is modified
and flushed to disk.

Overhead pages also include blobspace free-map pages and blobspace bit-map
pages. Blobspace blobpages are not logged in the physical log. For further
information about blobspace logging, see “Logging Blobspaces and Simple Large
Objects” on page 14-6.

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-3

 Physical Logging and Smart Large Objects
The user-data portion of smart large objects is not physically logged. However, the
metadata is physically logged. For information on smart large objects, see
“Sbspaces” on page 10-13.

Size and Location of the Physical Log

This section describes how to configure the size and location of the physical log.

Specifying the Location of the Physical Log

When the database server initializes disk space, it places the logical-log files and
the physical log in the root dbspace. You have no initial control over this
placement. To improve performance (specifically, to reduce the number of writes to
the root dbspace and minimize disk contention), you can move the physical log
out of the root dbspace to another dbspace, preferably to a disk that does not
contain active tables or the logical-log files.

The physical log is located in the dbspace specified by the ONCONFIG parameter
PHYSDBS. (For information on PHYSDBS, see the chapter on configuration
parameters in the IBM Informix Administrator's Reference.) Change PHYSDBS only if
you decide to move the physical-log file from the root dbspace. (See “Changing the
Physical-Log Location and Size” on page 17-1.)

Because the physical log is critical, you should mirror the dbspace that contains the
physical log.

Estimating the Size of the Physical Log

If your workload is update intensive, you can use the following formula to
calculate the size of the physical log where PHYSFILE equals the physical-log size:
PHYSFILE = (users * max_log_pages_per_crit_sect * 4 * pagesize) / 1024

Variable in Formula Description

users The maximum number of concurrent user threads
for which you can obtain an estimate when you
execute onstat -u during peak processing. The last
line of the onstat -u output contains the maximum
number of concurrent user threads.
If you set the NETTYPE parameter, sum the values
specified in the users field of each NETTYPE
parameter in your ONCONFIG file.
max_log_pages_per_crit_sect Maximum number of pages that the database
server can physically log in a critical section.
Substitute one of the following values:
5 if you do not use R-tree indexes
10 if you use R-tree indexes
4 Necessary factor because this part of the formula
represents only 25 percent of the physical log:
users * max_log_pages_per_crit_sect
pagesize System page size in bytes that you can obtain with
oncheck -pr

16-4 IBM Informix Dynamic Server Administrator’s Guide

 1024 Necessary divisor, because you specify the
PHYSFILE parameter in units of kilobytes

This formula is based on how much physical logging space the database server
needs in a worst-case scenario. This scenario takes place when a checkpoint occurs
because the log becomes 75 percent full. This size might be too small or large for
your actual workload or configuration.

If you are using simple large objects in a dbspace in a database without logging,
substitute the size of the most-frequently occurring simple large object in the
dbspace for the maximum log pages per critical section.

For more information on monitoring and tuning the physical log, refer to the
chapter on configuration effects on I/O utilization in your IBM Informix Dynamic
Server Performance Guide.

Configuring the Size of the Physical Log

Because a checkpoint logically empties the physical log when it becomes 75 percent
full, it is unlikely that the log would become 100 percent full before the checkpoint
completes. To assure further that the physical log does not become full during a
checkpoint, take the following actions:
v Configure the database server according to the sizing guidelines for the physical
log and the logical-log files.
v Fine-tune the size of the physical log by monitoring it during production
activity.

Fuzzy checkpoints keep the physical log from filling up too quickly when
applications are doing intensive updates. (See “Fuzzy Checkpoint” on page 16-7.)
However, the physical log could still become full, as the following sections
describe.

Physical-Log Overflow When Many Users Are in Critical Sections

A checkpoint cannot occur if any thread is in a critical section. (See “Critical
Sections” on page 16-2.) This scenario can occur when the thread that does the
checkpoint also rolls back a long transaction.

Effect of Checkpoints on the Physical-Log Size

Fuzzy checkpoints keep the physical log from filling up too quickly when
applications are doing intensive updates. You can reduce the size of the physical
log when applications require less intensive updates or when updates tend to
cluster within the same pages. You can decrease the size of the physical log if you
intend to use physical-log fullness to trigger checkpoints.

If you increase the checkpoint interval or anticipate increased activity, consider

increasing the size of the physical log. For more information, see the chapter on
effects of configuration on I/O activity in your IBM Informix Dynamic Server
Performance Guide.

Physical-Log Overflow When Transaction Logging Is Turned Off

The physical log can overflow if you use simple large objects or smart large objects
in a database with transaction logging turned off, as the following example shows.

When the database server processes these simple large objects, each portion of the
simple large object that the database server stores on disk can be logged separately,
allowing the thread to exit the critical sections of code between each portion.

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-5

 However, if logging is turned off, the database server must carry out all operations
on the simple large object in one critical section. If the simple large object is large
and the physical log small, this scenario can cause the physical log to become full.
If this situation occurs, the database server sends the following message to the
message log:
Physical log file overflow

The database server then initiates a shutdown. For the suggested corrective action,
refer to this message in your message log.

Details of Physical Logging

This section describes the details of physical logging. It is provided to satisfy your
curiosity; you do not need to understand the information here in order to manage
your physical log.

The database server performs physical logging through six steps that are shown in
the table below.

Physical-Logging Steps the

Database Server Performs Detailed Explanation
Reads the data page from disk When a session requests a row, the database server
to the shared-memory page identifies the page on which the row resides and attempts
buffer (if the data page is not to locate the page in the database server shared-memory
there already). buffer pool. If the page is not already in shared memory, it
is read into the resident portion of the database server
shared memory from disk.
Copies the unchanged page to If the before-image of a modified page is stored in the
the physical-log buffer. physical-log buffer, it is eventually flushed from the
physical-log buffer to the physical log on disk. The
before-image of the page plays a critical role in restoring
data and fast recovery. For more details, see “Physical-Log
Buffer” on page 8-12.
Reflects the change in the The database server reflects changes to the data in the
page buffer after an shared-memory data buffer. Data from the application is
application modifies data. passed to the database server. After a copy of the
unchanged data page is stored in the physical-log buffer,
the new data is written to the page buffer already
acquired.
Flushes the physical-log buffer The database server flushes the physical-log buffer before
to the physical log on disk. it flushes the data buffer to ensure that a copy of the
unchanged page is available until the changed page is
copied to disk. The before-image of the page is no longer
needed after a checkpoint occurs. For more details, see
“Flushing the Physical-Log Buffer” on page 8-26.
Flushes the page buffer and After the physical-log buffer is flushed, the shared-memory
writes it back to disk. page buffer is flushed to disk (such as during a
checkpoint), and the data page is written to disk. Only
non-fuzzy pages are flushed to disk during a fuzzy
checkpoint. For conditions that lead to the flushing of the
page buffer, see “Flushing Data to Disk” on page 8-26.

16-6 IBM Informix Dynamic Server Administrator’s Guide

 Physical-Logging Steps the
Database Server Performs Detailed Explanation
When a checkpoint occurs, A checkpoint can occur at any point in the
flushes the physical-log buffer physical-logging process. The database server performs
to the physical log on disk two types of checkpoints: full and fuzzy. For information,
and empties the physical log. see “Checkpoints.”

The database server manages the physical log as a circular

file, constantly overwriting unneeded data. The checkpoint
procedure empties the physical log by resetting a pointer
in the physical log that marks the beginning of the next
group of required before-images.

Checkpoints
The database server performs two types of checkpoints: full checkpoints (also
known as sync checkpoints) and fuzzy checkpoints. The term checkpoint refers to
the point in the database server operation when the pages on disk are
synchronized with the pages in the shared-memory buffer pool. The default
checkpoint type is fuzzy.

The database server generates at least one checkpoint for each span of the
logical-log space to guarantee that it has a checkpoint at which to begin fast
recovery.

Although the database server performs checkpoints automatically, you can initiate
one manually or control how often the database server checks to see if a
checkpoint is needed. You can specify the checkpoint interval in the CKPTINTVL
configuration parameter.

To reduce the amount of work required at checkpoint, use the BUFFERPOOL

configuration parameter to lower the lru_max_dirty and lru_max_dirty values. For
instance, if the database server has several instances with a very large buffer pool,
set the lru_max_dirty value to less than 1 to reduce the checkpoint time required.

Note: Information that was specified with the BUFFERS, LRUS,

LRU_MAX_DIRTY, and LRU_MIN_DIRTY configuration parameters prior to
Version 10.0 is now specified using the BUFFERPOOL configuration
parameter.

For more information about CKPTINTVL and BUFFERPOOL, see the chapter on
configuration parameters in the IBM Informix Administrator's Reference. For
information on monitoring and tuning checkpoint parameters, see your IBM
Informix Dynamic Server Performance Guide.

Full Checkpoint
In a full checkpoint, the database server flushes all modified pages in the
shared-memory buffer pool to disk. When a full checkpoint completes, all physical
operations are complete, the MLRU queue is empty, and the database server is said
to be physically consistent.

Fuzzy Checkpoint
In a fuzzy checkpoint, the database server does not flush the modified pages in the
shared-memory buffer pool to disk for certain types of operations, called fuzzy

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-7

 operations. When a fuzzy checkpoint completes, the pages might not be consistent
with each other, because the database server does not flush all data pages to disk.
A fuzzy checkpoint completes much more quickly than a full checkpoint and
reduces the amount of physical logging during heavy update activity. When
necessary, the database server performs a full checkpoint to ensure the physical
consistency of all data on disk.

Fuzzy Operations
The following commonly used operations are fuzzy for built-in data types:
v Inserts
v Updates
v Deletes

The following operations are nonfuzzy:

v Inserts, updates, and deletes for rows that contain user-defined data types, smart
large objects (CLOB and BLOB data types), or simple large objects (TEXT and
Byte data types)
v Table alters and loads
v Operations that create or modify indexes (B-tree, R-tree, or user-defined indexes)

The database server flushes all the modified data pages for nonfuzzy operations to
disk during a fuzzy checkpoint in the same way as for a full checkpoint.

Important: Fuzzy checkpoints are disabled for the primary and secondary servers
in a High-Availability Data Replication pair.

Write-Ahead Logging and Fast Recovery

Fuzzy checkpoint uses write-ahead logging for fast recovery. Write-ahead logging
means that the logical-log records representing changes to fuzzy data must be on
disk before the changed data replaces the previous version of the data on disk.
Fast recovery begins with the oldest update not yet flushed to disk rather than
with the previous checkpoint.

Fuzzy checkpoints result in slightly longer roll-forward fast-recovery times. The

database server occasionally performs a full checkpoint to prevent loss of old
logical-log records.

Fuzzy Checkpoints Improve Performance

Fuzzy checkpoints are much faster than full checkpoints and improve transaction
throughput. Because the database server does not log fuzzy operations in the
physical log, the physical log does not fill as quickly, and checkpoints occur less
often. For example, if you are inserting and updating a lot of data, checkpoints
occur less frequently and are shorter.

The database server skips a full checkpoint if all data is physically consistent when
the checkpoint interval expires. It skips a fuzzy checkpoint only if no pages have
been dirtied since the last checkpoint.

To improve transaction throughput, use the BUFFERPOOL configuration parameter

to increase the lru_max_dirty and lru_max_dirty values. However, do not change
the gap between the lru_max_dirty and lru_max_dirty values.

For information on improving checkpoint performance, see the chapter about

configuration impacts on I/O in your IBM Informix Dynamic Server Performance
Guide.

16-8 IBM Informix Dynamic Server Administrator’s Guide

Events That Initiate a Fuzzy Checkpoint
Usually, when the database server performs an automatic checkpoint, it is a fuzzy
checkpoint. Any one of following conditions initiates a fuzzy checkpoint:
v The checkpoint interval, specified by the configuration parameter CKPTINTVL,
has elapsed, and one or more modifications have occurred since the last
checkpoint.
v The physical log on disk becomes 75 percent full.
v The database server detects that the next logical-log file to become current
contains the most recent checkpoint record.
v Certain administrative tasks, such as adding a chunk or a dbspace, take place.

Events That Initiate a Full Checkpoint

In the following situations, the database server performs a full checkpoint to
ensure the physical consistency of all data on disk:
v When you issue onmode -ky to shut down the database server
v When you force a checkpoint using onmode -c or ISA
For more information, see “Forcing a Full Checkpoint” on page 17-5.
v When you convert the database server to a newer version or revert to a previous
version
v When you perform a backup or restore using ON–Bar or ontape
The backup tool performs a full checkpoint automatically to ensure the physical
consistency of all data before it writes it to the backup media.
v At the end of fast recovery or full recovery
v If the database server is about to switch to the next free log and the log
following the free log contains the oldest update
For example, suppose four logical-log files have the status shown in the
following list. The database server forces a full checkpoint when it switches to
logical-log file 3 if the logical-log file 4 has the oldest update. The full
checkpoint advances the oldest update to logical-log file 3.
logid Logical-Log File Status
1 U-B----
2 U---C--
3 F
4 U-B---L

The database server performs a full checkpoint to prevent problems with fast
recovery of old log records.

For a list of situations in which you should initiate a full checkpoint, see the
following section.

Sequence of Events in a Checkpoint

The following section outlines the main events that occur from the time a
checkpoint is requested. This section also notes the differences between full and
fuzzy checkpoints:
1. The database server prevents user threads from entering critical sections.
2. The logical-log buffer is flushed to the current logical-log file on disk.
3. The database server flushes the physical-log buffer to the physical log.

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-9

 4. In a fuzzy checkpoint, the database server flushes modified pages for nonfuzzy
operations to disk.
In a full checkpoint, the database server flushes all modified pages to disk.
5. The database server writes a checkpoint record to the logical-log buffer.
6. The physical log is logically emptied. (Current entries can be overwritten).

User Threads Cannot Enter a Critical Section

This step is the same for both fuzzy and full checkpoints. After a checkpoint is
requested, user threads are prevented from entering portions of code that are
considered critical sections. User threads that are within critical sections of code are
permitted to continue processing to the end of the critical sections.

Logical-Log Buffer Is Flushed to the Logical-Log File on Disk

This step is the same for both fuzzy and full checkpoints. Next, the logical-log
buffer is flushed to the logical-log file on disk.

The Physical-Log Buffer is Flushed to the Physical Log on Disk

For both fuzzy and full checkpoints, the database server flushes the physical-log
buffer to the physical log on disk. For full checkpoints, the physical-log buffer
contains all modified pages whereas for fuzzy checkpoints, the physical-log buffer
holds pages that fuzzy operations modified. The time stamp of the physical-log
flush is stored in shared memory.

Modified Pages in the Buffer Pool Are Flushed to Disk

In a fuzzy checkpoint, the database server flushes modified pages for nonfuzzy
operations in the buffer pool to disk. The database server flushes modified pages
for fuzzy operations (inserts, deletes, updates) to disk. Figure 16-1 shows how the
database server writes only the nonfuzzy pages to disk. The shaded squares,
marked F, represent the fuzzy pages.

Shared memory
F F
F
F

Storage space

Figure 16-1. Selectively Writing Modified Pages from Shared Memory to Disk

In a full checkpoint, the database server flushes all modified pages in the
shared-memory buffer pool to disk.

Checkpoint Thread Writes Checkpoint Record

This step is the same for both fuzzy and full checkpoints. A checkpoint-complete
record is written to the logical-log buffer after the modified pages have been
written to disk.

In a fuzzy checkpoint, a dirty-pages table (DPT) record is written to the logical-log

buffer. For more information, see the chapter on logical-log record types in the IBM
Informix Administrator's Reference.

16-10 IBM Informix Dynamic Server Administrator’s Guide

 Physical Log Is Logically Emptied
This step is the same for both fuzzy and full checkpoints. After the
checkpoint-complete record is written to disk, the physical log is logically emptied,
meaning that current entries in the physical log can be overwritten.

Backup and Restore Considerations

If you perform a backup, the database server performs a full checkpoint and
flushes all changed pages, including those for fuzzy operations, to the disk. If you
perform a restore, the database server reapplies all logical-log records.

Important: Because the logical log contains records of fuzzy operations not yet
written to disk, you must back up the logical logs regularly.

For information on ON–Bar or ontape, see the IBM Informix Backup and Restore
Guide.

Fast Recovery
Fast recovery is an automatic, fault-tolerant feature that the database server
executes every time that it moves from offline to quiescent, single-user, or online
mode. You do not need to take any administrative actions for fast recovery; it is an
automatic feature.

The fast-recovery process checks if, the last time that the database server went
offline, it did so in uncontrolled conditions. If so, fast recovery returns the database
server to a state of physical and logical consistency.

If the fast-recovery process finds that the database server came offline in a
controlled manner, the fast-recovery process terminates, and the database server
moves to online mode.

Fast recovery works differently depending on whether the previous checkpoint

was a full or fuzzy checkpoint. This section contains information on fast recovery
after both kinds of checkpoints. See “Details of Fast Recovery After A Full
Checkpoint” on page 16-12 and “Details of Fast Recovery After A Fuzzy
Checkpoint” on page 16-14.

Need for Fast Recovery

Fast recovery restores the database server to physical and logical consistency after
any failure that results in the loss of the contents of memory for the database
server. For example, the operating system fails without warning. System failures
do not damage the database but instead affect transactions that are in progress at
the time of the failure.

Situations When Fast Recovery Is Initiated

Every time that the administrator brings the database server to quiescent,
single-user, or online mode from offline mode, the database server checks to see if
fast recovery is needed.

As part of shared-memory initialization, the database server checks the contents of

the physical log. The physical log is empty when the database server shuts down
under control. The move from online mode to quiescent mode includes a
checkpoint, which flushes the physical log. Therefore, if the database server finds

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-11

 pages in the physical log, the database server clearly went offline under
uncontrolled conditions, and fast recovery begins.

Fast Recovery and Buffered Logging

If a database uses buffered logging (as described in “Buffered Transaction
Logging” on page 12-6), some logical-log records associated with committed
transactions might not be written to the logical log at the time of the failure. If this
occurs, fast recovery cannot restore those transactions. Fast recovery can restore
only transactions with an associated COMMIT record stored in the logical log on
disk. (For this reason, buffered logging represents a trade-off between performance
and data vulnerability.)

Possible Physical Log Overflow During Fast Recovery

During fast recovery, the physical log can overflow. If this occurs, the database
server tries to extend the physical log space to a disk file named
plog_extend.servernum. The default location of this file is $INFORMIXDIR/tmp.

Use the ONCONFIG parameter PLOG_OVERFLOW_PATH to define the location

for creating this file.

The database server removes the plog_extend.servernum file when the first
checkpoint is performed during a fast recovery.

Fast Recovery and No Logging

For databases or tables that do not use logging, fast recovery restores the database
to its state at the time of the most recent checkpoint. All changes made to the
database since the last checkpoint are lost. All fuzzy operations (inserts, deletes,
updates) not yet flushed to disk are also lost.

Details of Fast Recovery After A Full Checkpoint

This section discusses fast recovery after a full checkpoint. (Also see “Details of
Fast Recovery After A Fuzzy Checkpoint” on page 16-14.)

Fast recovery returns the database server to a consistent state as part of

shared-memory initialization. The consistent state means that all committed
transactions are restored, and all uncommitted transactions are rolled back.

Fast recovery is accomplished in the following two stages:

v The database server uses the physical log to return to the most recent point of
known physical consistency, the most recent checkpoint.
v The database server uses the logical-log files to return to logical consistency by
rolling forward all committed transactions that occurred after the last checkpoint
and rolling back all transactions that were left incomplete.

Fast recovery occurs in the following steps:

1. Uses the data in the physical log to return all disk pages to their condition at
the time of the most recent checkpoint.
2. Locates the most recent checkpoint record in the logical-log files.
3. Rolls forward all logical-log records written after the most recent checkpoint
record.
4. Rolls back transactions that do not have an associated COMMIT or BEGCOM
record in the logical log.

16-12 IBM Informix Dynamic Server Administrator’s Guide

 The database server writes the BEGCOM record when a transaction commits.
For details, see the chapter on logical-log records in the IBM Informix
Administrator's Reference.

The paragraphs that follow describe each step in detail.

Returning to the Last-Checkpoint State

To accomplish the first step, returning all disk pages to their condition at the time
of the most recent checkpoint, the database server writes the before-images stored
in the physical log to shared memory and then back to disk. Each before-image in
the physical log contains the address of a page that was updated after the
checkpoint. When the database server writes each before-image page in the
physical log to shared memory and then back to disk, changes to the database
server data since the time of the most recent checkpoint are undone. Figure 16-2
illustrates this step.

The database server is now physically consistent.

Shared memory

Tblspace Physical log

Figure 16-2. Writing All Remaining Before-Images in the Physical Log Back to Disk

Finding the Checkpoint Record in the Logical Log

In the second step, the database server locates the address of the most recent
checkpoint record in the logical log. The most recent checkpoint record is
guaranteed to be in the logical log on disk.

Rolling Forward Logical-Log Records

The third step in fast recovery rolls forward the logical-log records that were
written after the most recent checkpoint record. This action reproduces all changes
to the databases since the time of the last checkpoint, up to the point at which the
uncontrolled shutdown occurred. Figure 16-3 illustrates this step.

Logical log

Dbspace Records since

the checkpoint
Changes rolled
forward since
the checkpoint

Figure 16-3. Rolling Forward the Logical-Log Records Written Since the Most Recent
Checkpoint

Rolling Back Incomplete Transactions

The final step in fast recovery rolls back all logical-log records for transactions that
were not committed at the time the system failed. All databases are logically
consistent because all committed transactions are rolled forward and all
uncommitted transactions are rolled back.

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-13

 Transactions that have completed the first phase of a two-phase commit are
exceptional cases. For more information, see “How the Two-Phase Commit
Protocol Handles Failures” on page 23-7.

Because one or more transactions possibly spanned several checkpoints without

being committed, this rollback procedure might read backward through the logical
log past the most recent checkpoint record. All logical-log files that contain records
for open transactions are available to the database server because a log file is not
freed until all transactions that it contains are closed. Figure 16-4 illustrates the
rollback procedure. When fast recovery is complete, the database server returns to
quiescent, single-user, or online mode.

Logical log

Dbspace

Uncommitted changes
rolled back

Disk A

Figure 16-4. Rolling Back All Incomplete Transactions

Details of Fast Recovery After A Fuzzy Checkpoint

This section describes the default fast recovery method that occurs after a fuzzy
checkpoint. For information on two configuration parameters that you can use to
decrease recovery time by enabling the database server to perform physical logging
on fuzzy checkpoints during the roll-forward (log replay) phase of recovery, see
“Alternative Fast Restart Recovery Options for Fuzzy Operations” on page 16-17.

Fast recovery is accomplished in the following stages:

v The database server uses the physical log to return to the most recent
checkpoint. The database server might not be physically consistent at this point
in fast recovery because fuzzy operations do not physically log the before-image
of pages.
v The database server processes the logical-log records starting with the oldest
update that has not yet been flushed to disk, rather than starting with the
previous checkpoint.
v The database server uses the logical-log files to return to logical consistency by
rolling forward all committed transactions that occurred after the last checkpoint
and rolling back all transactions that were left incomplete.

The following steps describe these stages in detail:

1. Uses the data in the physical log to return disk pages for nonfuzzy operations
to their condition at the time of the most recent checkpoint.
2. Locates the oldest update in the logical log that is not yet flushed to disk.
3. Applies the log records for fuzzy operations that occurred before the most
recent checkpoint.
4. Rolls forward all logical-log records written after the most recent checkpoint
record.
5. Rolls back transactions that do not have an associated COMMIT or BEGIN
COMMIT record in the logical log.

16-14 IBM Informix Dynamic Server Administrator’s Guide

Although fast recovery after a fuzzy checkpoint takes longer than after a full
checkpoint, you can optimize it. For details, see your IBM Informix Dynamic Server
Performance Guide.

Returning to the Last-Checkpoint State for Nonfuzzy Operations

To accomplish the first step and return all disk pages for nonfuzzy operations to
their condition at the time of the most recent checkpoint, the database server
writes the before-images stored in the physical log to shared memory and then
back to disk. Each before-image in the physical log contains the address of a page
that was updated after the checkpoint. When the database server writes each
before-image page in the physical log to shared memory and then back to disk,
changes to the database server data since the time of the most recent checkpoint
are undone. Figure 16-5 illustrates this step.

Shared memory

Nonfuzzy pages

Tblspace Physical log

Figure 16-5. Writing Nonfuzzy Before-Images in the Physical Log Back to Disk

Pages on which fuzzy operations occurred are not physically consistent because the
database server does not physically log the before-images. If the most recent
checkpoint was a fuzzy checkpoint, the changed pages for fuzzy operations were
not flushed to disk. The dbspace disk still contains the before-image of each page.
To undo changes to these pages prior to the fuzzy checkpoint, the database server
uses the logical log, as the next step describes.

Locating the Oldest Update in the Logical Log

The database server no longer starts fast recovery at the most recent checkpoint
record. In this step, the database server locates the oldest update record in the
logical log that was not flushed to disk during the most recent checkpoint. The
database server uses the log sequence numbers (LSN) in the logical log to find the
oldest update record. Figure 16-6 shows that the oldest update in the logical log
occurred several checkpoints ago and that all the log records are applied.

Logical log

Dbspace Fuzzy checkpoint

Fast recovery starts Records before

at the oldest update fuzzy checkpoint
not flushed to disk

Figure 16-6. Locating the Oldest Update Record in the Logical Log

The LSN cannot be further back in the log than one logical-log file and two
checkpoints. At each fuzzy checkpoint, the database server writes pages with time
stamps earlier than the oldest LSN and moves forward the LSN.

You cannot free the logical log that contains the oldest update record until after the
changes are recorded on disk. The database server automatically performs a full
checkpoint to prevent problems with fast recovery of very old log records.
Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-15
 Applying the Log Records for Fuzzy Operations
In the second step, the database server processes the log records for fuzzy
operations that occurred following the oldest update and before the last
checkpoint. The log records that represent changes to data must be on disk before
the changed data replaces the previous version on disk.

Log records for fuzzy operations are selectively redone, depending on whether the
update has already been applied to the page. If the time stamp in the logical-log
record is newer than the time stamp in the disk page, the database server applies
the record. Otherwise, the database server skips that record.

Figure 16-7 illustrates how the database server processes fuzzy records only prior
to checkpoint.

Logical log

Dbspace
Changes not flushed to Records after the
disk since the oldest oldest update
update was applied

Figure 16-7. Applying the Log Records for Fuzzy Operations

Rolling Forward Logical-Log Records

In the third step, the database server processes all logical-log records following the
last checkpoint. Fast recovery rolls forward the logical-log records that were
written after the most recent checkpoint record. This action reproduces all changes
to the databases since the time of the last checkpoint, up to the point at which the
uncontrolled shutdown occurred. Figure 16-8 illustrates the roll forward of all
records after the fuzzy checkpoint.

Logical log
Dbspace
Records after the
Changes since the oldest update
fuzzy checkpoint
rolled forward

Figure 16-8. Rolling Forward the Logical-Log Records Written Since the Most Recent Fuzzy
Checkpoint

Rolling Back Incomplete Transactions

The final step in fast recovery rolls back all logical-log records for transactions that
were not committed at the time that the system failed. This rollback procedure
ensures that all databases are left in a consistent state.

Because one or more transactions possibly spanned several checkpoints without

being committed, this rollback procedure might read backward through the logical
log past the most recent checkpoint record. All logical-log files that contain records
for open transactions are available to the database server because a log file is not
freed until all transactions contained within it are closed. Figure 16-9 illustrates the

16-16 IBM Informix Dynamic Server Administrator’s Guide

 rollback procedure. When fast recovery is complete, the database server goes to
quiescent, single-user or online mode.

Logical log

Dbspace

Uncommitted changes
rolled back

Figure 16-9. Rolling Back All Incomplete Transactions

Alternative Fast Restart Recovery Options for Fuzzy

Operations
For situations when you need recovery performance that is faster than the default
recovery operations described above, you can use the following configuration
parameters:
v The FAST_RESTART_PHYSLOG configuration parameter, which enables the
database server to perform physical logging on fuzzy pages while the server is
running normally.
v The FAST_RESTART_CKPT_FUZZYLOG configuration parameter, which enables
the database server to put unflushed dirty fuzzy pages in the physical log at
checkpoint time. These unflushed dirty fuzzy pages are taken into the database
server buffer pool at the beginning of the fast recovery.

When the database server is online:

v Set the FAST_RESTART_PHYSLOG configuration parameter to 1 to enable
physical logging. Only use this parameter if the buffer pool is at least 25 percent
larger than the physical log file size. The buffer pool must be large enough to
hold the physical log, log pages, and other pages read during recovery.
If the buffer pool is not configured correctly, fast recovery performance is
compromised.
v Set the FAST_RESTART_CKPT_FUZZYLOG configuration parameter to 1 to
enable the flushing of dirty-pages table records to the physical log at checkpoint.

You can use either parameter or both when using fuzzy checkpoints. The default
value for both parameters is 0 (off).

The FAST_RESTART_PHYSLOG and FAST_RESTART_CKPT_FUZZYLOG

configuration parameters improve recovery performance. You must set these
parameters when you start the database server. If you wait and set these
parameters when the server is running, the parameters will not take effect.

The extra physical logging that occurs when the database server uses the
FAST_RESTART_PHYSLOG parameter affects runtime performance. If you do not
want to sacrifice runtime performance, use the FAST_RESTART_CKPT_FUZZYLOG
parameter to reduce some recovery time. FAST_RESTART_CKPT_FUZZYLOG,
which needs less buffer pool space than the FAST_RESTART_PHYSLOG, needs up
to 20 percent of the physical log size and it needs extra buffer pool size. When
configuring the buffer pool before starting fast recovery, the number of unflushed
dirty buffer pages are written to physical log at checkpoint time can help you
determine how much more buffer pool space you should consider.

Chapter 16. Physical Logging, Checkpoints, and Fast Recovery 16-17

 Which configuration parameter is faster depends on your system configuration and
applications when the database server shuts down. For example:
v If the database server performs a fuzzy checkpoint, has a large number of
unflushed fuzzy dirty pages, and then shuts down shortly after this checkpoint,
FAST_RESTART_CKPT_FUZZYLOG makes a big difference in the fast recovery
performance. In this situation, and FAST_RESTART_PHYSLOG has little effect.
v However, if the database server performs a hard checkpoint or performs a fuzzy
checkpoint but has few or no unflushed fuzzy dirty pages and then shuts down
after running for a long time before next checkpoint, FAST_RESTART_PHYSLOG
makes a big difference in the fast recovery performance. In this situation,
FAST_RESTART_CKPT_FUZZYLOG has little effect.

Thus, if you want better performance during fast recovery and have a bigger
buffer pool configuration, always turn on FAST_RESTART_CKPT_FUZZYLOG.
This does not affect database server runtime performance. If you are willing to
sacrifice some runtime performance for better fast recovery performance, you can
also turn on FAST_RESTART_PHYSLOG.

FAST_RESTART_PHYSLOG takes effect when you restart the database server. If the
database server fails before the next checkpoint performs, maximum fast-recovery
performance does not occur because the database server did not log all of the
fuzzy updates in the checkpoint intervals.

FAST_RESTART_CKPT_FUZZYLOG takes effect when you restart the database

server. If the total number of unflushed, fuzzy dirty pages exceeds 20 percent of
the total physical log space, the pages will not be written to the physical log.

Neither parameter changes the way to initiate fast recovery.

16-18 IBM Informix Dynamic Server Administrator’s Guide

Chapter 17. Managing the Physical Log
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Changing the Physical-Log Location and Size . . . . . . . . . . . . . . . . . . . . . . . 17-1
Preparing to Make the Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-2
Checking For Adequate Contiguous Space . . . . . . . . . . . . . . . . . . . . . . . 17-2
Using a Text Editor to Change Physical-Log Location or Size . . . . . . . . . . . . . . . . . 17-2
Using onparams to Change Physical-Log Location or Size . . . . . . . . . . . . . . . . . . 17-2
Using ON-Monitor to Change Physical-Log Location or Size (UNIX). . . . . . . . . . . . . . . 17-3
Monitoring Physical and Logical-Logging Activity . . . . . . . . . . . . . . . . . . . . . . 17-3
Monitoring Checkpoint Information . . . . . . . . . . . . . . . . . . . . . . . . . . 17-4
Forcing a Full Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
Forcing a Fuzzy Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-5
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-6

In This Chapter
This chapter describes the following procedures:
v Changing the location and size of the physical log
v Monitoring the physical log, physical-log buffers, and logical-log buffers
v Monitoring and forcing checkpoints

See Chapter 16, “Physical Logging, Checkpoints, and Fast Recovery,” on page 16-1
for background information.

Changing the Physical-Log Location and Size

You can change your physical-log location or size in several ways:
v Using a text editor or ISA to edit the ONCONFIG file
v Using the onparams utility from the command line

UNIX Only

v Using ON–Monitor
End of UNIX Only

Log in as user informix or root on UNIX or as a member of the Informix-Admin

group on Windows when you make the changes. The following sections describe
each of these methods.

To activate the changes to the size or location of the physical log as soon as you
make them, shut down and restart the database server. The onparams utility
automatically shuts down and restarts the database server.

Create a level-0 backup immediately after you restart the database server. This
storage-space backup is critical for database server recovery.

You can move the physical-log file to try to improve performance. When the
database server initializes disk space, it places the disk pages allocated for the

© Copyright IBM Corp. 1996, 2005 17-1

 logical log and the physical log in the root dbspace. You might improve
performance by moving the physical log, the logical-log files, or both to other
dbspaces.

Note: You cannot add logical or physical logs to dbspaces that have non-default
page sizes.

For advice on where to place the physical log, see “Specifying the Location of the
Physical Log” on page 16-4. For advice on sizing the physical log, see “Size and
Location of the Physical Log” on page 16-4. To obtain information about the
physical log, see “Monitoring Physical and Logical-Logging Activity” on page 17-3.

Preparing to Make the Changes

The space allocated for the physical log must be contiguous. A fatal
shared-memory error occurs when you attempt to shut down and restart the
database server in these situations:
v If you move the physical log to a dbspace without adequate contiguous space
v If you increase the log size beyond the available contiguous space, a fatal
shared-memory error occurs when you attempt to restart the database server
with the new values.

If this error occurs, resize the physical log, or choose another dbspace with
adequate contiguous space and then shut down and restart the database server.

Checking For Adequate Contiguous Space

You can check whether adequate contiguous space is available with the oncheck
-pe option. For information on using the oncheck -ce and -pe options to check the
chunk free list, see the IBM Informix Administrator's Reference.

For more information, see “Monitoring Chunks” on page 11-33.

Using a Text Editor to Change Physical-Log Location or Size

You can change the physical-log location and size by editing the ONCONFIG file
while the database server is in online mode.
Parameter Description
PHYSFILE Specifies the size of the physical log file in kilobytes
PHYSDBS Moves the physical log to the specified dbspace

The changes do not take effect until you shut down and restart the database server.
Then create a level-0 backup immediately to ensure that all recovery mechanisms
are available.

For information on PHYSFILE and PHYSDBS, see the chapter on configuration

parameters in the IBM Informix Administrator's Reference.

Using onparams to Change Physical-Log Location or Size

To change the size and location of the physical log, execute the following
command after you bring the database server to quiescent or single-user mode:
onparams -p -s size -d dbspace -y
size is the new size of the physical log in kilobytes
dbspace specifies the dbspace where the physical log is to reside

17-2 IBM Informix Dynamic Server Administrator’s Guide

 The following example changes the size and location of the physical log. The new
physical-log size is 400 kilobytes, and the log will reside in the dbspace6 dbspace:
onparams -p -s 400 -d dbspace6 -y

The command shown above, with the -y option, changes the value of the
parameter in shared memory so that the change takes effect immediately.

After you shut down and restart the database server, create a level-0 backup to
ensure that all recovery mechanisms are available.

For information on using the onparams utility to modify the physical log, see the
IBM Informix Administrator's Reference.

Using ON-Monitor to Change Physical-Log Location or Size

(UNIX)
Select Parameters > Physical-Log to change the size or dbspace location, or both.

Then, create a level-0 backup immediately to ensure that all recovery mechanisms
are available.

Monitoring Physical and Logical-Logging Activity

Monitor the physical log to determine the percentage of the physical-log file that
gets used before a checkpoint occurs. This information allows you to find the
optimal size of the physical-log file. It should be large enough that the database
server does not have to force checkpoints too frequently and small enough to
conserve disk space and guarantee fast recovery.

Monitor physical-log and logical-log buffers to determine if they are the optimal
size for the current level of processing. The important statistic to monitor is the
pages-per-disk-write statistic. For more information on tuning the physical-log and
logical-log buffers, see your IBM Informix Performance Guide.

To monitor the physical-log file, physical-log buffers, and logical-log buffers, use
the following commands.

Chapter 17. Managing the Physical Log 17-3

Utility Command Additional Information
Command line or onstat -l The first line displays the following information for each physical-log
ISA buffer:
v The number of buffer pages used (bufused)
v The size of each physical log buffer in pages (bufsize)
v The number of pages written to the buffer (numpages)
v The number of writes from the buffer to disk (numwrits)
v The ratio of pages written to the buffer to the number of writes to
disk (pages/IO)

The second line displays the following information about the physical
log:
v The page number of the first page in the physical-log file
(phybegin)
v The size of the physical-log file in pages (physize)
v The current position in the log where the next write occurs,
specified as a page number (physpos)
v The number of pages in the log that have been used (phyused)
v The percentage of the total physical-log pages that have been used
(%used)

The third line displays the following information about each

logical-log buffer:
v The number of buffer pages used (bufused)
v The size of each logical-log buffer in pages (bufsize)
v The number of records written to the buffer (numrecs)
v The number of pages written to the buffer (numpages)
v The number of writes from the buffer to disk (numwrits)
v The ratio of records to pages in the buffer (recs/pages)
v The ratio of pages written to the buffer to the number of writes to
disk (pages/IO)
Command line or onparams -p Moves or resizes the physical log.
ISA
Command line or onmode -l Advances to the next logical-log file.
ISA
ISA Logs > Logical Click Advance Log File.

Note: For more information on and an example of onstat -l output, see the IBM
Informix Administrator's Reference

Monitoring Checkpoint Information

Monitor checkpoint activity to determine basic checkpoint information. This
information includes the number of times that threads had to wait for the
checkpoint to complete. This information is useful for determining if the
checkpoint interval is appropriate. For information on tuning the checkpoint
interval, see your IBM Informix Dynamic Server Performance Guide.

To monitor checkpoints, use the following commands.

17-4 IBM Informix Dynamic Server Administrator’s Guide

Utility Command Additional Information
Command line or onstat -m View the last 20 lines in the message log.
ISA
If a checkpoint message does not appear in the last 20 lines, read the
message log directly with a text editor. The database server writes
individual checkpoint messages to the log when the checkpoint ends.

If a checkpoint occurs, but the database server has no pages to write

to disk, the database server does not write any messages to the
message log.
Command line or onstat -p Obtains these checkpoint statistics:
ISA v numckpts: Number of checkpoints that occurred since the database
server was brought online.
v ckptwaits: Number of times that a user thread waits for a
checkpoint to finish. The database server prevents a user thread
from entering a critical section during a checkpoint.
ON–Monitor (UNIX) Status > Profile The Checkpoints and Check Waits fields display the same
information as the numckpts and ckpwaits fields in onstat -p.

Forcing a Full Checkpoint

To force a full checkpoint, execute one of the following commands.

Utility Command Additional Information

Command line or onmode -c None.
ISA
ISA Logs > Logical Click Force Checkpoint.
ON–Monitor (UNIX) Force-Ckpt option from The time in the Last Checkpoint Done field does not change until
the main menu a checkpoint occurs. The Last Checkpoint Check field shows the
time of the last checkpoint check. If no modifications have been
made since the time of the last checkpoint, the database server
does not perform a checkpoint.

You should force a full checkpoint in any of the following situations:

v To free a logical-log file that contains the most recent checkpoint record and that
is backed up but not yet released (onstat -l status of U-B-L or U-B)
v Before you issue onmode -sy to place the database server in quiescent mode
v After building a large index, if the database server terminates before the next
checkpoint (the index build will restart the next time that you restart the
database server)
v If a checkpoint has not occurred for a long time and you are about to attempt a
system operation that might interrupt the database server
v If foreground writes are taking more resources than you want (force a
checkpoint to bring this down to zero for a while)
v Before you execute dbexport or unload a table, to ensure physical consistency of
all data before you export or unload it
v After you perform a large load of tables using PUT or INSERT statements
Because table loads use the buffer cache, force a checkpoint to clean the buffer
cache.

Forcing a Fuzzy Checkpoint

To force a fuzzy checkpoint, execute the onmode -c fuzzy command.
Chapter 17. Managing the Physical Log 17-5
 Using SMI Tables
Query the sysprofile table to obtain statistics on the physical-log and logical-log
buffers. The sysprofile table also provides the same checkpoint statistics that are
available from the onstat -p option. These rows contain the following statistics.
Row Description
plgpagewrites Number of pages written to the physical-log buffer
plgwrites Number of writes from the physical-log buffer to the physical log
file
llgrecs Number of records written to the logical-log buffer
llgpagewrites Number of pages written to the logical-log buffer
llgwrites Number of writes from the logical-log buffer to the logical-log files
numckpts Number of checkpoints that have occurred since the database
server was brought online)
ckptwaits Number of times that threads waited for a checkpoint to finish to
enter a critical section during a checkpoint
value Values for numckpts and ckptwaits

17-6 IBM Informix Dynamic Server Administrator’s Guide

Part 4. Fault Tolerance

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
Chapter 18. Mirroring
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-1
Benefits of Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Costs of Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Consequences of Not Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Data to Mirror . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-2
Alternatives to Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Logical Volume Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Hardware Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
External Backup and Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Mirroring Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-3
Creation of a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Mirror Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-4
Actions During Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Disk Writes to Mirror Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Disk Reads from Mirror Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Detection of Media Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Chunk Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-5
Result of Stopping Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6
Structure of a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18-6

In This Chapter
This chapter describes the database server mirroring feature. For instructions on
how to perform mirroring tasks, refer to Chapter 19, “Using Mirroring,” on page
19-1

Mirroring
Mirroring is a strategy that pairs a primary chunk of one defined dbspace,
blobspace, or sbspace with an equal-sized mirror chunk.

Every write to the primary chunk is automatically accompanied by an identical

write to the mirror chunk. This concept is illustrated in Figure 18-1. If a failure
occurs on the primary chunk, mirroring enables you to read from and write to the
mirror chunk until you can recover the primary chunk, all without interrupting
user access to data.

Primary chunk Mirrored chunk

Database server

Writes

Figure 18-1. Writing Data to Both the Primary Chunk and the Mirror Chunk

Mirroring is not supported on disks that are managed over a network. The same
database server instance must manage all the chunks of a mirrored set.
© Copyright IBM Corp. 1996, 2005 18-1
 Benefits of Mirroring
If media failure occurs, mirroring provides the database server administrator with
a means of recovering data without having to take the database server offline. This
feature results in greater reliability and less system downtime. Furthermore,
applications can continue to read from and write to a database whose primary
chunks are on the affected media, provided that the chunks that mirror this data
are located on separate media.

Any critical database should be located in a mirrored dbspace. Above all, the root
dbspace, which contains the database server reserved pages, should be mirrored.

Costs of Mirroring
Disk-space costs as well as performance costs are associated with mirroring. The
disk-space cost is due to the additional space required for storing the mirror data.
The performance cost results from having to perform writes to both the primary
and mirror chunks. The use of multiple virtual processors for disk writes reduces
this performance cost. The use of split reads, whereby the database server reads
data from either the primary chunk or the mirror chunk, depending on the location
of the data within the chunk, actually causes performance to improve for read-only
data. For more information on how the database server performs reads and writes
for mirror chunks, see “Actions During Processing” on page 18-5.

Consequences of Not Mirroring

If you do not mirror your dbspaces, the frequency with which you have to restore
from a storage-space backup after media failure increases.

When a mirror chunk suffers media failure, the database server reads exclusively
from the chunk that is still online until you bring the down chunk back online. On
the other hand, when an mirrored chunk goes down, the database server cannot
access the data stored on that chunk. If the chunk contains logical-log files, the
physical log, or the root dbspace, the database server goes offline immediately. If
the chunk does not contain logical-log files, the physical log, or the root dbspace,
the database server can continue to operate, but threads cannot read from or write
to the down chunk. If an unmirrored chunk goes down, you must restore it by
recovering the dbspace from a backup.

Data to Mirror
Ideally, you should mirror all of your data. If disk space is an issue, however, you
might not be able to do so. In this case, select certain critical chunks to mirror.

Critical chunks always include the chunks that are part of the root dbspace, the
chunk that stores the logical-log files, and the chunk that stores the physical logs. If
any one of these critical chunks fail, the database server goes offline immediately.

If some chunks hold data that is critical to your business, give these chunks high
priority for mirroring.

Also give priority for mirroring to chunks that store frequently used data. This
action ensures that the activities of many users would not be halted if one widely
used chunk goes down.

18-2 IBM Informix Dynamic Server Administrator’s Guide

 Alternatives to Mirroring
Mirroring, as discussed in this manual, is a database server feature. Your operating
system or hardware might provide alternative mirroring solutions.

If you are considering a mirroring feature provided by your operating system

instead of database server mirroring, compare the implementation of both features
before you decide which to use. The slowest step in the mirroring process is the
actual writing of data to disk. The database server strategy of performing writes to
mirror chunks in parallel helps to reduce the time required for this step. (See “Disk
Writes to Mirror Chunks” on page 18-5.) In addition, database server mirroring
uses split reads to improve read performance. (See “Disk Reads from Mirror
Chunks” on page 18-5.) Operating-system mirroring features that do not use
parallel mirror writes and split reads might provide inferior performance.

Nothing prevents you from running database server mirroring and

operating-system mirroring at the same time. They run independently of each
other. In some cases, you might decide to use both the database server mirroring
and the mirroring feature provided by your operating system. For example, you
might have both database server data and other data on a single disk drive. You
could use the operating-system mirroring to mirror the other data and database
server mirroring to mirror the database server data.

Logical Volume Managers

Logical volume managers are an alternative mirroring solution. Some
operating-system vendors provide this type of utility to have multiple disks appear
as one file system. Saving data to more than two disks gives you added protection
from media failure, but the additional writes have a performance cost.

Hardware Mirroring
Another solution is to use hardware mirroring such as RAID (redundant array of
inexpensive disks). An advantage of this type of hardware mirroring is that it
requires less disk space than database server mirroring does to store the same
amount of data to prevent media failure.

Some hardware mirroring systems support hot swapping. You can swap a bad disk
while keeping the database server online. Reducing I/O activity before performing
a hot swap is recommended.

Important: If problems occur with the database server while using hardware
mirroring, refer to the operating-system or disk documentation or
technical support for assistance.

External Backup and Restore

If you use hardware disk mirroring, you can get your system online faster with
external backup and restore than with conventional ON–Bar commands. For more
information on external backup and restore, see the IBM Informix Backup and
Restore Guide.

Mirroring Process
This section describes the mirroring process in greater detail. For instructions on
how to perform mirroring operations such as creating mirror chunks, starting
mirroring, changing the status of mirror chunks, and so forth, see Chapter 19,
“Using Mirroring,” on page 19-1.

Chapter 18. Mirroring 18-3

 Creation of a Mirror Chunk
When you specify a mirror chunk, the database server copies all the data from the
primary chunk to the mirror chunk. This copy process is known as recovery.
Mirroring begins as soon as recovery is complete.

The recovery procedure that marks the beginning of mirroring is delayed if you
start to mirror chunks within a dbspace that contains a logical-log file. Mirroring
for dbspaces that contain a logical-log file does not begin until you create a level-0
backup of the root dbspace. The delay ensures that the database server can use the
mirrored logical-log files if the primary chunk that contains these logical-log files
becomes unavailable during a dbspace restore.

The level-0 backup copies the updated database server configuration information,
including information about the new mirror chunk, from the root dbspace reserved
pages to the backup. If you perform a data restore, the updated configuration
information at the beginning of the backup directs the database server to look for
the mirrored copies of the logical-log files if the primary chunk becomes
unavailable. If this new storage-space backup information does not exist, the
database server is unable to take advantage of the mirrored log files.

For similar reasons, you cannot mirror a dbspace that contains a logical-log file
while a dbspace backup is being created. The new information that must appear in
the first block of the dbspace backup tape cannot be copied there after the backup
has begun.

For more information on creating mirror chunks, refer to Chapter 19, “Using
Mirroring,” on page 19-1.

Mirror Status Flags

Dbspaces, blobspaces, and sbspaces have status flags that indicate whether they are
mirrored or unmirrored.

You must perform a level-0 backup of the root dbspace before mirroring starts.

Chunks have status flags that indicate the following information:

v Whether the chunk is a primary or mirror chunk
v Whether the chunk is currently online, down, a new mirror chunk that requires
a level-0 backup of the root dbspace, or in the process of being recovered

For descriptions of these chunk status flags, refer to the description of the onstat -d
option in the IBM Informix Administrator's Reference. For information on how to
display these status flags, refer to “Monitoring Disk Usage” on page 11-32.

Recovery
When the database server recovers a mirror chunk, it performs the same recovery
procedure that it uses when mirroring begins. The mirror-recovery process consists
of copying the data from the existing online chunk onto the new, repaired chunk
until the two are identical.

When you initiate recovery, the database server puts the down chunk in recovery
mode and copies the information from the online chunk to the recovery chunk.
When the recovery is complete, the chunk automatically receives online status. You
perform the same steps whether you are recovering the primary chunk of a
mirrored pair or recovering the mirror chunk.

18-4 IBM Informix Dynamic Server Administrator’s Guide

 Tip: You can still use the online chunk during the recovery process. If data is
written to a page that has already been copied to the recovery chunk, the
database server updates the corresponding page on the recovery chunk before
it continues with the recovery process.

For information on how to recover a down chunk, refer to the information on

recovering a mirror chunk on page 19-6.

Actions During Processing

This section discusses some of the details of disk I/O for mirror chunks and how
the database server handles media failure for these chunks.

Disk Writes to Mirror Chunks

During database server processing, the database server performs mirroring by
executing two parallel writes for each modification: one to the primary chunk and
one to the mirror chunk.

Disk Reads from Mirror Chunks

The database server uses mirroring to improve read performance because two
versions of the data reside on separate disks. A data page is read from either the
primary chunk or the mirror chunk, depending on which half of the chunk
includes the address of the data page. This feature is called a split read. Split reads
improve performance by reducing the disk-seek time. Disk-seek time is reduced
because the maximum distance over which the disk head must travel is reduced by
half. Figure 18-2 illustrates a split read.

Primary chunk Database server

Mirrored chunk

Data on this half of the chunk is Data on this half of the chunk is
read from the primary chunk. read from the mirrored chunk.

Figure 18-2. Split Read Reducing the Maximum Distance Over Which the Disk Head Must
Travel

Detection of Media Failures

The database server checks the return code when it first opens a chunk and after
any read or write. Whenever the database server detects that a primary (or mirror)
chunk device has failed, it sets the chunk-status flag to down (D). For information
on chunk-status flags, refer to “Mirror Status Flags” on page 18-4.

If the database server detects that a primary (or mirror) chunk device has failed,
reads and writes continue for the one chunk that remains online. This statement is
true even if the administrator intentionally brings down one of the chunks.

After the administrator recovers the down chunk and returns it to online status,
reads are again split between the primary and mirror chunks, and writes are made
to both chunks.

Chunk Recovery
The database server uses asynchronous I/O to minimize the time required for
recovering a chunk. The read from the chunk that is online can overlap with the
write to the down chunk, instead of the two processes occurring serially. That is,

Chapter 18. Mirroring 18-5

 the thread that performs the read does not have to wait until the thread that
performs the write has finished before it reads more data.

Result of Stopping Mirroring

When you end mirroring, the database server immediately frees the mirror chunks
and makes the space available for reallocation. The action of ending mirroring
takes only a few seconds.

Create a level-0 backup of the root dbspace after you end mirroring to ensure that
the reserved pages with the updated mirror-chunk information are copied to the
backup. This action prevents the restore procedure from assuming that mirrored
data is still available.

Structure of a Mirror Chunk

The mirror chunk contains the same control structures as the primary chunk, as
follows:
v Mirrors of blobspace chunks contain blobspace overhead pages.
v Mirrors of dbspace chunks contain dbspace overhead pages.
v Mirrors of sbspaces contain metadata pages.

For information on these structures, refer to the section on the structure of a mirror
chunk in the disk structures and storage chapter of the IBM Informix Administrator's
Reference.

A display of disk-space use, provided by one of the methods discussed under

“Monitoring Chunks” on page 11-33, always indicates that the mirror chunk is full,
even if the primary chunk has free space. The full mirror chunk indicates that none
of the space in the chunk is available for use other than as a mirror of the primary
chunk. The status remains full for as long as both primary chunk and mirror
chunk are online.

If the primary chunk goes down and the mirror chunk becomes the primary
chunk, disk-space allocation reports then accurately describe the fullness of the
new primary chunk.

18-6 IBM Informix Dynamic Server Administrator’s Guide

Chapter 19. Using Mirroring
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Preparing to Mirror Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-1
Enabling the MIRROR Configuration Parameter . . . . . . . . . . . . . . . . . . . . . . 19-2
Changing the MIRROR Parameter with ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 19-2
Allocating Disk Space for Mirrored Data . . . . . . . . . . . . . . . . . . . . . . . . . 19-2
Linking Chunks (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Relinking a Chunk to a Device After a Disk Failure . . . . . . . . . . . . . . . . . . . . 19-3
Using Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-3
Mirroring the Root Dbspace During Initialization . . . . . . . . . . . . . . . . . . . . . 19-4
Changing the Mirror Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Managing Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-4
Starting Mirroring for Unmirrored Storage Spaces . . . . . . . . . . . . . . . . . . . . . 19-4
Starting Mirroring for Unmirrored dbspaces Using onspaces . . . . . . . . . . . . . . . . 19-4
Starting Mirroring Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-5
Starting Mirroring for Unmirrored dbspaces Using ON-Monitor (UNIX) . . . . . . . . . . . . 19-5
Starting Mirroring for New Storage Spaces . . . . . . . . . . . . . . . . . . . . . . . 19-5
Starting Mirroring for New Spaces Using onspaces . . . . . . . . . . . . . . . . . . . 19-5
Starting Mirroring for New Spaces Using ISA . . . . . . . . . . . . . . . . . . . . . 19-5
Starting Mirroring for New dbspaces Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . 19-5
Adding Mirror Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Adding Mirror Chunks Using onspaces . . . . . . . . . . . . . . . . . . . . . . . 19-6
Adding Mirror Chunks Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Adding Mirror Chunks Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . 19-6
Taking Down a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Taking Down Mirror Chunks Using onspaces . . . . . . . . . . . . . . . . . . . . . 19-6
Taking Down Mirror Chunks Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . 19-6
Recovering a Mirror Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-6
Recovering a Mirror Chunk Using onspaces . . . . . . . . . . . . . . . . . . . . . . 19-6
Recovering a Mirror Chunk Using ISA. . . . . . . . . . . . . . . . . . . . . . . . 19-7
Recovering a Mirror Chunk Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . 19-7
Ending Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Ending Mirroring Using onspaces . . . . . . . . . . . . . . . . . . . . . . . . . 19-7
Ending Mirroring Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . 19-7
Ending Mirroring Using ISA . . . . . . . . . . . . . . . . . . . . . . . . . . . 19-7

In This Chapter
This chapter describes the various mirroring tasks that are required to use the
database server mirroring feature. It provides an overview of the steps required for
mirroring data.

Preparing to Mirror Data

This section describes how to start mirroring data on a database server that is not
running with the mirroring function enabled.

To prepare to mirror data:

1. Take the database server offline and enable mirroring.
See “Enabling the MIRROR Configuration Parameter” on page 19-2.
2. Bring the database server back online.
3. Allocate disk space for the mirror chunks.

© Copyright IBM Corp. 1996, 2005 19-1

 You can allocate this disk space at any time, as long as the disk space is
available when you specify mirror chunks in the next step. The mirror chunks
should be on a different disk than the corresponding primary chunks. See
“Allocating Disk Space for Mirrored Data” on page 19-2.
4. Choose the dbspace, blobspace, or sbspace that you want to mirror, and specify
a mirror-chunk pathname and offset for each primary chunk in that storage
space.
The mirroring process starts after you perform this step. Repeat this step for all
the storage spaces that you want to mirror. See “Using Mirroring” on page
19-3.

Enabling the MIRROR Configuration Parameter

Enabling mirroring invokes the database server functionality required for mirroring
tasks. However, when you enable mirroring, you do not initiate the mirroring
process. Mirroring does not actually start until you create mirror chunks for a
dbspace, blobspace, or sbspace. See “Using Mirroring” on page 19-3.

Enable mirroring when you initialize the database server if you plan to create a
mirror for the root dbspace as part of initialization; otherwise, leave mirroring
disabled. If you later decide to mirror a storage space, you can change the value of
the MIRROR configuration parameter.

To enable mirroring for the database server, you must set the MIRROR parameter
in ONCONFIG to 1. The default value of MIRROR is 0, indicating that mirroring
is disabled.

Do not set the MIRROR parameter to 1 if you are not using mirroring.

To change the value of MIRROR, you can edit the ONCONFIG file with a text
editor or ISA while the database server is in online mode. After you change the
ONCONFIG file, take the database server offline and then to quiescent for the
change to take effect.

Changing the MIRROR Parameter with ON-Monitor (UNIX)

To enable mirroring, choose Parameters > Initialize. In the field that is labelled
Mirror, enter Y. Press ESC to record changes.

After the last of these screens, a prompt appears to confirm that you want to
continue (to initialize the database server disk space and destroy all existing data).
Respond N (no) to this prompt.

Warning: If you respond Y (yes) at this prompt, you lose all your existing data.

Take the database server offline and then to quiescent mode for the change to take
effect.

Allocating Disk Space for Mirrored Data

Before you can create a mirror chunk, you must allocate disk space for this
purpose. You can allocate either raw disk space or cooked file space for mirror
chunks. For a discussion of allocating disk space, refer to “Allocating Disk Space”
on page 11-3.

19-2 IBM Informix Dynamic Server Administrator’s Guide

 Always allocate disk space for a mirror chunk on a different disk than the
corresponding primary chunk with, ideally, a different controller. This setup allows
you to access the mirror chunk if the disk on which the primary chunk is located
goes down, or vice versa.

Linking Chunks (UNIX)

Use the UNIX link (ln) command to link the actual files or raw devices of the
mirror chunks to mirror pathnames. If a disk failure occurs, you can link a new file
or raw device to the pathname, eliminating the need to physically replace the disk
that failed before the chunk is brought back online.

Relinking a Chunk to a Device After a Disk Failure

On UNIX, if the disk on which the actual mirror file or raw device is located goes
down, you can relink the chunk to a file or raw device on a different disk. This
action allows you to recover the mirror chunk before the disk that failed is brought
back online. Typical

UNIX commands that you can use for relinking are shown in the following
examples.

The original setup consists of a primary root chunk and a mirror root chunk,
which are linked to the actual raw disk devices, as follows:
ln -l
lrwxrwxrwx 1 informix 10 May 3 13:38 /dev/root@->/dev/rxy0h
lrwxrwxrwx 1 informix 10 May 3 13:40 /dev/mirror_root@->/dev/rsd2b

Assume that the disk on which the raw device /dev/rsd2b resides has gone down.
You can use the rm command to remove the corresponding symbolic link, as
follows:
rm /dev/mirror_root

Now you can relink the mirror chunk pathname to a raw disk device, on a disk
that is running, and proceed to recover the chunk, as follows:
ln -s /dev/rab0a /dev/mirror_root

Using Mirroring
Mirroring starts when you create a mirror chunk for each primary chunk in a
dbspace, blobspace, or sbspace.

When you create a mirror chunk, the database server copies data from the primary
chunk to the mirror chunk. When this process is complete, the database server
begins mirroring data. If the primary chunk contains logical-log files, the database
server does not copy the data immediately after you create the mirror chunk but
waits until you perform a level-0 backup. For an explanation of this behavior see
“Creation of a Mirror Chunk” on page 18-4.

Important: You must always start mirroring for an entire dbspace, blobspace, or
sbspace. The database server does not permit you to select particular
chunks in a dbspace, blobspace, or sbspace to mirror. You must create
mirror chunks for every chunk in the space.

You start mirroring a storage space when you perform the following operations:
v Create a mirrored root dbspace during system initialization

Chapter 19. Using Mirroring 19-3

 v Change the status of a dbspace from unmirrored to mirrored
v Create a mirrored dbspace, blobspace, or sbspace

Each of these operations requires you to create mirror chunks for the existing
chunks in the storage space.

Mirroring the Root Dbspace During Initialization

If you enable mirroring when you initialize the database server, you can also
specify a mirror pathname and offset for the root chunk. The database server
creates the mirror chunk when the server is initialized. However, because the root
chunk contains logical-log files, mirroring does not actually start until you perform
a level-0 backup.

To specify the root mirror pathname and offset, set the values of MIRRORPATH
and MIRROROFFSET in the ONCONFIG file before you bring up the database
server.

If you do not provide a mirror pathname and offset, but you do want to start
mirroring the root dbspace, you must change the mirroring status of the root
dbspace after the database server is initialized.

Changing the Mirror Status

You can make the following two changes to the status of a mirror chunk:
v Change a mirror chunk from online to down
v Change a mirror chunk from down to recovery

You can take down or restore a chunk only if it is part of a mirrored pair. You can
take down either the primary chunk or the mirror chunk, as long as the other
chunk in the pair is online.

For information on how to determine the status of a chunk, refer to “Monitoring

Disk Usage” on page 11-32.

Managing Mirroring
You can use the onspaces utility to manage mirroring. On UNIX, you can also use
ON–Monitor to manage mirroring. For a full description of the onspaces syntax,
see information on the onspaces utility in the IBM Informix Administrator's
Reference.

Starting Mirroring for Unmirrored Storage Spaces

You can prepare mirroring for a dbspace, blobspace, or sbspace at any time.
However, the mirroring does not start until you perform a level-0 backup.

Starting Mirroring for Unmirrored dbspaces Using onspaces

You can use the onspaces utility to start mirroring a dbspace, blobspace, or
sbspace. For example, the following onspaces command starts mirroring for the
dbspace db_project, which contains two chunks, data1 and data2:
onspaces -m db_project\
-p /dev/data1 -o 0 -m /dev/mirror_data1 0\
-p /dev/data2 -o 5000 -m /dev/mirror_data2 5000

19-4 IBM Informix Dynamic Server Administrator’s Guide

 The following example shows how to turn on mirroring for a dbspace called sp1.
You can either specify the primary path, primary offset, mirror path, and mirror
offset in the command or in a file.
onspaces -m sp1 -f mirfile

The mirfile file contains the following line:

/ix/9.3/sp1 0 /ix/9.2/sp1mir 0

In this line, /ix/9.3/sp1 is the primary path, 0 is the primary offset, /ix/9.3/sp1mir is
the mirror path, and 0 is the mirror offset.

Starting Mirroring Using ISA

To start mirroring with ISA:
1. Select Storage > Chunks.
2. Select the dbspace name and click Start Mirroring.

Starting Mirroring for Unmirrored dbspaces Using ON-Monitor

(UNIX)
Use the Dbspaces > Mirror option to start mirroring a dbspace.

To select the dbspace that you want to mirror, move the cursor down the list to the
correct dbspace and press CTRL-B. The Mirror option then displays a screen for
each chunk in the dbspace. You can enter a mirror pathname and offset in this
screen. After you enter information for each chunk, press ESC to exit the option.
The database server recovers the new mirror chunks, meaning it copies data from
the primary to the mirror chunk. If the chunk contains logical-log files, recovery is
postponed until after you create a level-0 backup.

Starting Mirroring for New Storage Spaces

You can also start mirroring when you create a new dbspace, blobspace, or
sbspace.

Starting Mirroring for New Spaces Using onspaces

You can use the onspaces utility to create a mirrored dbspace. For example, the
following command creates the dbspace db_acct with an initial chunk /dev/chunk1
and a mirror chunk /dev/mirror_chk1:
onspaces -c -d db_acct -p /dev/chunk1 -o 0 -s 2500 -m /dev/mirror_chk1 0

Another way to start mirroring is to select Index by Utility > onspaces > -m.

Starting Mirroring for New Spaces Using ISA

To start mirroring for new storage spaces with ISA
1. Select Storage > Spaces.
2. Click Add Dbspace, Add Blobspace, or Add Sbspace.
3. Enter the path and offset for the mirror chunk.

Starting Mirroring for New dbspaces Using ON-Monitor (UNIX)

To create a dbspace with mirroring, choose the Dbspaces > Create option. This
option displays a screen in which you can specify the pathname, offset, and size of
a primary chunk and the pathname and offset of a mirror chunk for the new
dbspace.

Chapter 19. Using Mirroring 19-5

 Adding Mirror Chunks
If you add a chunk to a dbspace, blobspace, or sbspace that is mirrored, you must
also add a corresponding mirror chunk.

Adding Mirror Chunks Using onspaces

You can use the onspaces utility to add a primary chunk and its mirror chunk to a
dbspace, blobspace, or sbspace. The following example adds a chunk, chunk2, to
the db_acct dbspace. Because the dbspace is mirrored, a mirror chunk,
mirror_chk2, is also added.
onspaces -a db_acct -p /dev/chunk2 -o 5000 -s 2500 -m /dev/mirror_chk2 5000

Adding Mirror Chunks Using ISA

To add mirror chunks with ISA:
1. Select Storage > Chunks.
2. Select the dbspace name and click Add Chunk.
3. Enter the path and offset for the mirror chunk.

Adding Mirror Chunks Using ON-Monitor (UNIX)

In ON–Monitor, the Dbspaces > Add-chunk option displays fields in which to
enter the primary-chunk pathname, offset, and size, and the mirror-chunk
pathname and offset.

Taking Down a Mirror Chunk

When a mirror chunk is down, the database server cannot write to it or read from
it. You might take down a mirror chunk to relink the chunk to a different device.
(See “Relinking a Chunk to a Device After a Disk Failure” on page 19-3.)

Taking down a chunk is not the same as ending mirroring. You end mirroring for a
complete dbspace, which causes the database server to drop all the mirror chunks
for that dbspace.

Taking Down Mirror Chunks Using onspaces

You can use the onspaces utility to take down a chunk. The following example
takes down a chunk that is part of the dbspace db_acct:
onspaces -s db_acct -p /dev/mirror_chk1 -o 0 -D

Taking Down Mirror Chunks Using ON-Monitor (UNIX)

To use ON–Monitor to take down a mirror chunk, choose the Dbspaces > Status
option. With the cursor on the dbspace that contains the chunk that you want to
take down, press F3 or CTRL-B. The database server displays a screen that lists all
the chunks in the dbspace. Move the cursor to the chunk that you want to take
down and press F3 or CTRL-B to change the status (take it down).

Recovering a Mirror Chunk

To begin mirroring the data in the chunk that is online, you must recover the
down chunk.

Recovering a Mirror Chunk Using onspaces

You can use the onspaces -s utility to recover a down chunk. For example, to
recover a chunk that has the pathname /dev/mirror_chk1 and an offset of 0
kilobytes, issue the following command:
onspaces -s db_acct -p /dev/mirror_chk1 -o 0 -O

19-6 IBM Informix Dynamic Server Administrator’s Guide

 Recovering a Mirror Chunk Using ISA
To recover a mirror chunk with ISA

Select Index by Utility > onspaces > -s.

Recovering a Mirror Chunk Using ON-Monitor (UNIX)

To use ON–Monitor to recover a down chunk, choose the Dbspaces > Status
option.

Ending Mirroring
When you end mirroring for a dbspace, blobspace, or sbspace, the database server
immediately releases the mirror chunks of that space. These chunks are
immediately available for reassignment to other storage spaces.

Only users informix and root on UNIX or members of the Informix-Admin group
on Windows can end mirroring.

You cannot end mirroring if any of the primary chunks in the dbspace are down.
The system can be in online mode when you end mirroring.

Ending Mirroring Using onspaces

You can end mirroring with the onspaces utility. For example, to end mirroring for
the root dbspace, enter the following command:
onspaces -r rootdbs

Another way to end mirroring is to select Index by Utility > onspaces > -r.

Ending Mirroring Using ON-Monitor (UNIX)

To end mirroring for a dbspace or blobspace with ON–Monitor, select the
Dbspaces > Mirror option. Select a dbspace or blobspace that is mirrored and
press CTRL-B or F3.

Ending Mirroring Using ISA

To end mirroring with ISA:
1. Select Storage > Chunks.
2. Select the dbspace name and click Stop Mirroring.

Chapter 19. Using Mirroring 19-7

19-8 IBM Informix Dynamic Server Administrator’s Guide
Chapter 20. High-Availability Data Replication
(Enterprise/Workgroup Editions)
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
High-Availability Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
HDR Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-2
Type of Data Replicated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Advantages of Data Replication . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-3
Primary and Secondary Database Servers . . . . . . . . . . . . . . . . . . . . . . . 20-3
HDR Versus Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-4
HDR Versus Two-Phase Commit . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
HDR and Enterprise Replication . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
How HDR Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
How Data Initially Replicates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-6
Reproduction of Updates to the Primary Database Server . . . . . . . . . . . . . . . . . . 20-6
How the Log Records Are Sent . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
HDR Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
When Log Records Are Sent . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
Synchronous Updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-7
Asynchronous Updating . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-8
Threads That Handle HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-9
Checkpoints Between Database Servers . . . . . . . . . . . . . . . . . . . . . . . . 20-10
How Data Synchronization Is Tracked . . . . . . . . . . . . . . . . . . . . . . . . 20-10
HDR Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
HDR Failures Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-10
Detection of HDR Failures . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11
Actions When an HDR Failure Is Detected . . . . . . . . . . . . . . . . . . . . . . . 20-11
Considerations After HDR Failure . . . . . . . . . . . . . . . . . . . . . . . . . . 20-11
Actions to Take If the Secondary Database Server Fails . . . . . . . . . . . . . . . . . . 20-12
Actions to Take If the Primary Database Server Fails . . . . . . . . . . . . . . . . . . 20-12
Redirection and Connectivity for Data-Replication Clients . . . . . . . . . . . . . . . . . . . 20-14
Designing Clients for Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . 20-14
Directing Clients Automatically with DBPATH . . . . . . . . . . . . . . . . . . . . . 20-14
How the DBPATH Redirection Method Works . . . . . . . . . . . . . . . . . . . . . 20-14
What the Administrator Needs to Do . . . . . . . . . . . . . . . . . . . . . . . . 20-15
What the User Needs to Do . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-15
Directing Clients with the Connectivity Information . . . . . . . . . . . . . . . . . . . . 20-15
How Redirection with the Connectivity Information Works . . . . . . . . . . . . . . . . 20-16
Changing the Connectivity Information . . . . . . . . . . . . . . . . . . . . . . . 20-16
Connecting to the Database Server. . . . . . . . . . . . . . . . . . . . . . . . . 20-18
Directing Clients with INFORMIXSERVER . . . . . . . . . . . . . . . . . . . . . . . 20-18
How Redirection Works with INFORMIXSERVER . . . . . . . . . . . . . . . . . . . 20-18
What the Administrator Needs to Do . . . . . . . . . . . . . . . . . . . . . . . . 20-18
What the User Needs to Do . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-18
Handling Redirection Within an Application . . . . . . . . . . . . . . . . . . . . . . 20-19
Comparing Different Redirection Mechanisms . . . . . . . . . . . . . . . . . . . . . . 20-20
Designing HDR Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-20
Setting Lock Mode to Wait for Access to Primary Database Server . . . . . . . . . . . . . . . 20-20
Designing Clients to Use the Secondary Database Server . . . . . . . . . . . . . . . . . . 20-21
No Data Modification Statements . . . . . . . . . . . . . . . . . . . . . . . . . 20-21
Locking and Isolation Level . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-21

© Copyright IBM Corp. 1996, 2005 20-1

 Use of Temporary Dbspaces for Sorting and Temporary Tables . . . . . . . . . . . . . . . 20-22

In This Chapter
This chapter contains general information on High-Availability Data Replication
(HDR), which is available with the standard version of Dynamic Server. HDR does
not work with the IBM Informix Dynamic Server Express Edition.

The chapter discusses the following topics:

v What HDR is
v How HDR works
v How HDR handles failures
v How to redirect a client to connect to the other database server in the HDR pair
(also called a replication pair)
v What the design considerations are for applications that connect to the
secondary database server

Chapter 21, “Using High-Availability Data Replication (Enterprise/Workgroup

Editions),” on page 21-1, contains instructions on how to accomplish the
administrative tasks that are involved in using HDR.

Tip: If you want to use asynchronous data replication, see the IBM Informix
Dynamic Server Enterprise Replication Guide.

High-Availability Data Replication

Data Replication refers to the process of representing database objects at more than
one distinct site. High-availability data replication provides synchronous data
replication for Dynamic Server. Use HDR if you require a hot standby.

One way of replicating data is simply to copy a database to a database server

installed on a different computer. This copy allows reports to access the data
without disturbing client applications that use the original database.

The database server implements nearly transparent data replication of entire

database servers. All the data that one database server manages is replicated and
dynamically updated on another database server, often at a separate geographical
location. HDR provides a way to maintain a backup copy of the entire database
server that applications can access quickly in the event of a catastrophic failure.

Important: HDR does not support network encryption during replication.

HDR Modes
The following table shows HDR modes.

HDR Mode Explanation

Standard Mode Not part of an HDR system
Primary Mode The primary mode of an HDR system. Data can be updated.
Secondary Mode The secondary mode of an HDR system. Data cannot be updated,
but the data can be read.

20-2 IBM Informix Dynamic Server Administrator’s Guide

 A database server running in standard mode or an HDR database server running
in primary or secondary mode can be in any database server operating mode, such
as quiescent or online. For information on operating modes, see “Database Server
Operating Modes” on page 4-7.

Type of Data Replicated

HDR replicates data in dbspaces and sbspaces. HDR does not replicate data in
blobspaces.

HDR replicates all built-in and extended data types. User-defined types (UDTs)
must be logged and reside in a single database server. Data types with out-of-row
data are replicated if the data is stored in an sbspace or in a different table on the
same database server. For data stored in an sbspace to be replicated, the sbspace
must be logged.

HDR does not replicate data stored in operating system files or persistent external
files or memory objects associated with user-defined routines.

User-defined types, user-defined routines, and DataBlade modules have special

installation and registration requirements. For instructions, see “How Data Initially
Replicates” on page 20-6.

Advantages of Data Replication

Advantages of data replication are as follows:
v Clients at the site to which the data is replicated experience improved
performance because those clients can access data locally rather than connecting
to a remote database server over a network.
v Clients at all sites experience improved availability of replicated data. If the local
copy of the replicated data is unavailable, clients can still access the remote copy
of the data.

These advantages do not come without a cost. Data replication obviously requires
more storage, and updating replicated data can take more processing time than
updating a single object.

You could implement data replication in the logic of client applications by

explicitly specifying where data must be updated. However, this method of
achieving data replication is costly, prone to error, and difficult to maintain.
Instead, the concept of data replication is often coupled with replication
transparency. Replication transparency is built into a database server (instead of into
client applications) to handle automatically the details of locating and maintaining
data replicas.

Primary and Secondary Database Servers

When you configure a pair of database servers to use HDR, one database server is
called the primary database server, and the other is called the secondary database
server. (In this context, a database server that does not use HDR is referred to as a
standard database server.)

During normal operation, clients can connect to the primary database server and
use it as they would an ordinary database server. Clients can also use the
secondary database server during normal operation, but only to read data. The
secondary database server does not permit updates from client applications.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-3

 As Figure 20-1 illustrates, the secondary database server is dynamically updated,
with changes made to the data that the primary database server manages.

Read-only clients

Client Client
Primary Secondary
Client Client

Figure 20-1. A Primary and Secondary Database Server in an HDR Pair

If one of the database servers in an HDR pair fails, as Figure 20-2 shows, you can
redirect the clients that use that database server to the other database server in the
pair.

Client

Client
Primary Secondary

Client

Client

Figure 20-2. Database Servers in an HDR Pair and Clients After a Failure

If a primary database server fails, you can change the secondary database server to
a standard database server so that it can accept updates.

HDR has the following features:

v Provides for quick recovery if one database server experiences a failure
v Allows for load balancing across the two database servers

HDR Versus Mirroring

HDR and mirroring are both transparent ways of making the database server more
fault tolerant. However, as Figure 20-3, shows, they are quite different.

Mirroring, described in “Mirroring” on page 18-1, is the mechanism by which a

single database server maintains a copy of a specific dbspace on a separate disk.
This mechanism protects the data in mirrored dbspaces against disk failure because
the database server automatically updates data on both disks and automatically
uses the other disk if one of the dbspaces fails.

On the other hand, HDR duplicates on an entirely separate database server all the
data that a database server manages (not just specified dbspaces). Because HDR
involves two separate database servers, it protects the data that these database
servers manage, not just against disk failures, but against all types of database
server failures, including a computer failure or the catastrophic failure of an entire
site.

20-4 IBM Informix Dynamic Server Administrator’s Guide

 Mirroring

Database server

Disks

Computer

High-Availability Data Replication

Database server Database server

Figure 20-3. A Comparison of Mirroring and HDR

HDR Versus Two-Phase Commit

The two-phase commit protocol, described in detail in Chapter 23, “Multiphase
Commit Protocols,” on page 23-1, ensures that transactions are uniformly
committed or rolled back across multiple database servers.

In theory, you could take advantage of two-phase commit to replicate data by

configuring two database servers with identical data and then defining triggers on
one of the database servers that replicate updates to the other database server.
However, this sort of implementation has numerous synchronization problems in
different failure scenarios. Also, the performance of distributed transactions is
inferior to HDR.

HDR and Enterprise Replication

You can combine HDR with Enterprise Replication to create a robust replication
system. HDR can ensure that an Enterprise Replication system remains fully
connected by providing backup database servers for critical replication nodes.

When you combine HDR and Enterprise Replication, only the primary HDR server
is connected to the Enterprise Replication system. The secondary HDR server does
not participate in Enterprise Replication unless the primary HDR server fails.

For more information, see IBM Informix Dynamic Server Enterprise Replication Guide.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-5

How HDR Works
This section describes the mechanisms that the database server uses to perform
HDR. For instructions on how to set up, start, and administer an HDR system,
refer to Chapter 21, “Using High-Availability Data Replication
(Enterprise/Workgroup Editions),” on page 21-1, and information on starting an
HDR pair using external backup and restore in the IBM Informix Backup and Restore
Guide.

How Data Initially Replicates

The database server uses storage-space and logical-log backups (both those backed
up to tape and those on disk) to perform an initial replication of the data on the
primary database server to the secondary database server.

To replicate data:
1. Install user-defined types, user-defined routines, and DataBlade modules on
both database servers, and then register them on the primary database server
only.
2. To make the bulk of the data managed by the two database servers the same,
create a level-0 backup of all the storage spaces on the primary database server,
and restore all the storage spaces from that backup on the secondary database
server in the data-replication pair.
The secondary database server that you restored from a storage-space backup
in the previous step then reads all the logical-log records generated since that
backup from the primary database server.
The database server reads the logical-log records first from any backed-up
logical-log files that are no longer on disk and then from any logical-log files
on disk.

For detailed instructions on performing the preceding steps, refer to “Starting HDR
for the First Time” on page 21-6. The IBM Informix Backup and Restore Guide
discusses how to start replication using ON–Bar.

You must perform the initial HDR with a storage-space backup. You cannot use
data-migration utilities such as onload and onunload to replicate data because the
physical page layout of tables on each database server must be identical in order
for HDR to work.

When HDR is working, the primary database server is online and accepts updates
and queries just as a standard database server does. The secondary database server
is in logical-recovery mode and cannot accept SQL statements that result in writes
to disk (except for sorting and temporary tables).

Reproduction of Updates to the Primary Database Server

HDR reproduces updates to the primary database server on the secondary
database server by having the primary database server send all its logical-log
records to the secondary database server as they are generated. The secondary
database server receives the logical-log records generated on the primary database
server and applies them to its dbspaces.

Important: The database server cannot replicate updates to databases that do not
use transaction logging.

20-6 IBM Informix Dynamic Server Administrator’s Guide

How the Log Records Are Sent
As shown in Figure 20-4 on page 20-7, when the primary database server starts to
flush the contents of the logical-log buffer in shared memory to the logical log on
disk, the database server also copies the contents of the logical-log buffer to a
data-replication buffer on the primary database server. The primary database server
then sends these logical-log records to the secondary database server.

The secondary database server receives the logical-log records from the primary
database server into a shared-memory reception buffer (which the database server
automatically adjusts to an appropriate size for the amount of data being sent).
The secondary database server then applies the logical-log records through logical
recovery.

HDR Buffers
The HDR buffers are part of the virtual shared memory that the primary database
server manages. The HDR buffers hold logical-log records before the primary
database server sends them to the secondary database server. The HDR buffers are
the same size as the logical-log buffers. Figure 20-4 shows this concept.

Primary Secondary

Shared memory Shared memory

Logical-log Recovery
buffer buffer

HDR buffer Reception

buffer

Disk Disk

Figure 20-4. How Logical-Log Records Are Sent from the Primary Database Server to the
Secondary Database Server

When Log Records Are Sent

The primary database server sends the contents of the HDR buffer to the
secondary database server either synchronously or asynchronously. The value of the
ONCONFIG configuration parameter DRINTERVAL determines whether the
database server uses synchronous or asynchronous updating. For more information
on DRINTERVAL, see the chapter on configuration parameters in the IBM Informix
Administrator's Reference.

Synchronous Updating
If you set DRINTERVAL to -1, HDR occurs synchronously. As soon as the primary
database server writes the logical-log buffer contents to the HDR buffer, it sends
those records from the HDR buffer to the secondary database server. The
logical-log buffer flush on the primary database server completes only after the
primary database server receives acknowledgment from the secondary database
server that the records were received.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-7

 With synchronous updating, no transactions committed on the primary database
server are left uncommitted or partially committed on the secondary database
server if a failure occurs.

Asynchronous Updating
If you set DRINTERVAL to any value other than -1, data replication occurs
asynchronously. The primary database server flushes the logical-log buffer after it
copies the logical-log buffer contents to the HDR buffer. Independent of that action,
the primary database server sends the contents of the HDR buffer across the
network when one of the following conditions occurs:
v The HDR buffer becomes full.
v The time interval, specified by the DRINTERVAL configuration parameter on the
primary database server, has elapsed since the last time that records were sent to
the secondary database server.

This method of updating might provide better performance than synchronous

updating. However, as the following section explains, transactions can be lost.

Lost-and-Found Transactions: With asynchronous updating, a transaction

committed on the primary database server might not be replicated on the
secondary database server. This situation can result if a failure occurs after the
primary database server copies a commit record to the HDR buffer but before the
primary database server sends that commit record to the secondary database
server.

If the secondary database server is changed to a standard database server after a

failure of the primary database server, it rolls back any open transactions. These
transactions include any that were committed on the primary database server but
for which the secondary database server did not receive a commit record. As a
result, transactions are committed on the primary database server but not on the
secondary database server. When you restart data replication after the failure, the
database server places all the logical-log records from the lost transactions in a file
(which the DRLOSTFOUND configuration parameter specifies) during logical
recovery of the primary database server. Figure 20-5 illustrates the process.

20-8 IBM Informix Dynamic Server Administrator’s Guide

 Records in Records in
primary logical secondary
log logical log

Records for
transaction Secondary
committed on switched to
primary but Records in standard
rolled back on primary logical
secondary log after recovery
Records in
lost-and-found
file after recovery

Figure 20-5. Using a Lost-and-Found File

If the lost-and-found file appears on the computer that is running the primary
database server after it restarts data replication, a transaction has been lost. The
database server cannot reapply the transaction records in the lost-and-found file
because conflicting updates might have occurred while the secondary database
server was acting as a standard database server.

To reduce the risk of a lost transaction without running data replication in

synchronous mode, use unbuffered logging for all the databases. This method
reduces the amount of time between the writing and transfer of the transaction
records from the primary database server to the secondary database server.

Threads That Handle HDR

The database server starts specialized threads to support data replication. As
Figure 20-6 shows, a thread called drprsend on the primary database server sends
the contents of the HDR buffer across the network to a thread called drsecrcv on
the secondary database server.

Client
Primary Secondary

sqlexec
drsecapply

drprsend drsecrcv

logrecvr
drprping drsecping

Figure 20-6. Threads That Manage Data Replication

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-9

 A thread called drsecapply on the secondary database server copies the contents of
the reception buffer to the recovery buffer. The logrecvr thread (or threads)
performs logical recovery with the contents of the recovery buffer, applying the
logical-log records to the dbspaces that the secondary database server manages.
The OFF_RECVRY_THREADS configuration parameter specifies the number of
logrecvr threads used.

The remaining threads that the database server starts for HDR are the drprping
and drsecping threads, which are responsible for sending and receiving the
messages that indicate if the two database servers are connected.

Checkpoints Between Database Servers

Checkpoints between database servers in a replication pair are synchronous,
regardless of the value of DRINTERVAL. (See “Checkpoints” on page 16-7.) A
checkpoint on the primary database server completes only after it completes on the
secondary database server. If the checkpoint does not complete within the time
that the DRTIMEOUT configuration parameter specifies, the primary database
server assumes that a failure has occurred. See “HDR Failures Defined” on page
20-10.

Tip: Synchronize the time on the operating systems of both database servers in the
pair and set DRTIMEOUT on both servers to the same value.

How Data Synchronization Is Tracked

To keep track of synchronization, each database server in the pair keeps track of
the following information in its reserved page:
v The ID of the logical-log file that contains the last completed checkpoint
v The position of the checkpoint record within the logical-log file
v The ID of the last logical-log file sent (or received)
v The page number of the last logical-log record sent (or received)

The database servers use this information internally to synchronize data

replication.

HDR Failures
This section discusses the causes and consequences of an HDR failure, as well as
the administrator’s options for managing failure and restarting data replication.

HDR Failures Defined

An HDR failure is a loss of connection between the database servers in a
replication pair. Any of the following situations might cause a data-replication
failure:
v A catastrophic failure (such as a fire or large earthquake) at the site of one of the
database servers
v A disruption of the networking cables that join the two database servers
v An excessive delay in processing on one of the database servers
v A disk failure on the secondary database server that is not resolved by a mirror
chunk

20-10 IBM Informix Dynamic Server Administrator’s Guide

 Tip: An HDR failure does not necessarily mean that one of the database servers
has failed, only that the HDR connection between the two database servers is
lost.

Detection of HDR Failures

The database server interprets either of the following conditions as an HDR failure:
v A specified time-out value was exceeded.
During normal HDR operation, a database server expects confirmation of
communication from the other database server in the pair. Each database server
in the pair has an ONCONFIG parameter, DRTIMEOUT, that specifies a number
of seconds. If confirmation from the other database server in a pair does not
return within the number of seconds that DRTIMEOUT specifies, the database
server assumes that an HDR failure has occurred.
v The other database server in the primary-secondary pair does not respond to the
periodic messaging (pinging) attempts over the network.
The database servers ping each other regardless of whether the primary
database server sends any records to the secondary database server. If one
database server of a primary-secondary pair does not respond to four sequential
ping attempts, the other database server assumes that an HDR failure has
occurred.
Each database server in the pair sends a ping to the other database server in the
pair when the number of seconds specified by the DRTIMEOUT parameter on
that database server has passed.

Actions When an HDR Failure Is Detected

After a database server detects an HDR failure, it writes a message to its message
log (for example, DR: receive error) and turns data replication off. If an HDR
failure occurs, the HDR connection between the two database servers is dropped
and the secondary database server remains in read-only mode.

If the secondary database server remains online after a high-availability

data-replication failure, and the DRAUTO configuration parameter is set to 1
(RETAIN_TYPE), the type of that database server changes automatically to
standard. If DRAUTO is set to 0 (off), the secondary database server periodically
attempts to reestablish communication with the primary database server. If
DRAUTO is set to 2 (REVERSE_TYPE), the secondary database server becomes a
primary database server as soon as the connection ends when the old primary
server fails, rather than when the old primary server is restarted

Considerations After HDR Failure

Consider the following issues when an HDR failure occurs:
v How the clients should react to the failure
If a real failure occurs (not just transitory network slowness or failure), you
probably want clients that are using the failed database server to redirect to the
other database server in the pair. For instruction on how to redirect clients, see
“Redirection and Connectivity for Data-Replication Clients” on page 20-14.
v How the database servers should react to the failure
Which administrative actions to take after an HDR failure depends on whether
the primary database server or the secondary database server failed. For a
discussion of this topic, see “Actions to Take If the Secondary Database Server
Fails” on page 20-12 and “Actions to Take If the Primary Database Server Fails”
on page 20-12.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-11

 If you redirect clients, consider what sort of load the additional clients place on
the remaining database server. You might need to increase the space devoted to
the logical log or back up the logical-log files more frequently.

Actions to Take If the Secondary Database Server Fails

If the secondary database server fails, the primary database server remains online.

To redirect clients that use the secondary database server to the primary database
server, use any of the methods explained in “Redirection and Connectivity for
Data-Replication Clients” on page 20-14. If you redirect these clients, the primary
database server might require an additional temporary dbspace for temporary
tables and sorting.

You do not need to change the type of the primary database server to standard.

To restart data replication after a failure of the secondary database server, follow
the steps in “Restarting If the Secondary Database Server Fails” on page 21-20.

Actions to Take If the Primary Database Server Fails

If the primary database server fails, the secondary database server can operate in
the following ways:
v The secondary database server can remain in logical-recovery mode. In this case,
no action is taken. This is desirable if you expect the HDR connection to be
restored very soon.
v The secondary database server can automatically become a standard database
server. This action is called automatic switchover.
v The secondary database server can become a standard database server if you use
manual switchover to change the database server mode to standard.

Automatic Switchover: Automatic switchover means that the secondary database

server automatically becomes a standard database server after it detects an HDR
failure. It first rolls back any open transactions and then comes into online mode as
a standard database server. Automatic switchover occurs only if the parameter
DRAUTO in the ONCONFIG file of the secondary database server is set to 1
(RETAIN_TYPE) or 2 (REVERSE_TYPE).

Because the secondary database server becomes a standard database server, you
must be sure that either:
v The secondary database server has enough logical-log disk space to allow
processing to continue without backing up logical-log files.
v The logical-log files are backed up.

The automatic switchover changes only the type of the database server. It does not
redirect client applications to the secondary database server. For information on
redirecting clients, see “Redirection and Connectivity for Data-Replication Clients”
on page 20-14.

Automatic switchover has the following advantages over manual switchover:

v Clients that you redirect from the primary database server to the secondary
database server can continue to write and update data.
v The switchover does not depend on an operator monitoring the message log to
see when high-availability data-replication failures occur and then manually
switching the secondary database server to a standard database server.

20-12 IBM Informix Dynamic Server Administrator’s Guide

The main disadvantage to automatic switchover is that it requires a very stable
network to function appropriately. For more information see “Using Automatic
Switchover Without a Reliable Network.”

See “The Secondary Database Server Is Changed to a Standard Database Server

Automatically” on page 21-21 for the steps required to restart data replication after
an automatic switchover.

Actions that Occur After Automatic Switchover: When you succeed in bringing
the original primary database server back online, the HDR connection is
automatically established.
v If DRAUTO is set to RETAIN_TYPE, the secondary-turned-standard database
server goes through a graceful shutdown (to ensure that all clients that might
potentially write to the database server are not connected) and then switches
back to a secondary database server.
v If DRAUTO is set to REVERSE_TYPE, the secondary-turned-standard database
server switches directly to the primary type. No shutdown occurs. Any
applications connected to this database server can stay connected. The original
primary database server is switched to a secondary database server.

Using Automatic Switchover Without a Reliable Network: Although automatic

switchover might appear to be the best solution, it is not appropriate for all
environments.

Consider what might happen if the primary database server does not actually fail
but appears to the secondary database server to fail. For example, if the secondary
database server does not receive responses when it signals (pings) the primary
database server because of a slow or unstable network, the secondary server
assumes that the primary database server failed and switches automatically to the
standard type. If the primary database server also does not receive responses when
it signals the secondary database server, it assumes that the secondary database
server failed and turns off data replication but remains in online mode. Now the
primary database server and the secondary database server (switched to the
standard type) are both in online mode.

If clients can update the data on both database servers independently, the database
servers in the pair reach a state in which each database server has the logical-log
records that are needed by the other. In this situation, you must start again and
perform initial data replication with a level-0 dbspace backup of one entire
database server, as described in “Starting HDR for the First Time” on page 21-6.
Therefore, if your network is not entirely stable, you might not want to use
automatic switchover.

Manual Switchover: Manual switchover means that the administrator of the

secondary database server changes the type of the secondary database server to
standard. The secondary database server rolls back any open transactions and then
comes into online mode as a standard database server, so that it can accept
updates from client applications. For an explanation of how to perform the
switchover, see “Changing the Database Server Type” on page 21-14.

Restarting After a Manual Switchover: For a list of the steps involved in

restarting data replication after a manual switchover, see “The Secondary Database
Server Is Changed to a Standard Database Server” on page 21-21.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-13

 Restarting If the Secondary Database Server Is Not Switched to Standard: If the
secondary database server is not changed to type standard, follow the steps in
“The Secondary Database Server Was Not Changed to a Standard Database Server”
on page 21-21.

Redirection and Connectivity for Data-Replication Clients

To connect to the database servers in a replication pair, clients use the same
methods with which they connect to standard database servers. For an explanation
of these methods, see the descriptions of the CONNECT and DATABASE
statements in the IBM Informix Guide to SQL: Syntax.

After a failure of one of the database servers in a pair, you might want to redirect
the clients that use the failed database server. (You might not want clients to be
redirected. For example, if you anticipate that the database servers will be
functioning again in a short time, redirecting clients might not be appropriate.)

The database server does not have a transparent mechanism for directing client
requests to different database servers in a replication pair, but you can automate
this action from within the application, as described in “Handling Redirection
Within an Application” on page 20-19. Some of the client connectivity drivers
included in the IBM Informix Client Software Developer's Kit have specific
mechanisms for automating redirection. For details, see the IBM Informix Client
Software Developer's Kit documentation.

Designing Clients for Redirection

When you design client applications, you must make some decisions on redirection
strategies. Specifically, you must decide whether to handle redirection within the
application and which redirection mechanism to use. The three different redirection
mechanisms are as follows:
v Automatic redirection with the DBPATH environment variable
v Administrator-controlled redirection with the connectivity information
v User-controlled redirection with the INFORMIXSERVER environment variable

The mechanism that you employ determines which CONNECT syntax you can use
in your application. The following sections describe each of the three redirection
mechanisms.

Directing Clients Automatically with DBPATH

This section explains the steps that you must follow to redirect clients with the
DBPATH environment variable and the connectivity strategy that supports this
method.

How the DBPATH Redirection Method Works

When an application does not explicitly specify a database server in the
CONNECT statement, and the database server that the INFORMIXSERVER
environment variable specifies is unavailable, the client uses the DBPATH
environment variable to locate the database (and database server).

If one of the database servers in a replication pair is unusable, applications that use
that database server need not reset their INFORMIXSERVER environment variable
if their DBPATH environment variable is set to the other database server in the
pair. Their INFORMIXSERVER environment variable should always contain the

20-14 IBM Informix Dynamic Server Administrator’s Guide

 name of the database server that they use regularly, and their DBPATH
environment variable should always contain the name of the alternative database
server in the pair.

For example, if applications normally use a database server called cliff_ol, and the
database server paired with cliff_ol in a replication pair is called beach_ol, the
environment variables for those applications would be as follows:
INFORMIXSERVER cliff_ol
DBPATH //beach_ol

Because the DBPATH environment variable is read only (if needed) when an
application issues a CONNECT statement, applications must restart in order for
redirection to occur.

An application can contain code that tests whether a connection has failed and, if
so, attempts to reconnect. If an application has this code, you do not need to
restart it.

You can use the CONNECT TO database statement with this method of redirection.
For this method to work, you cannot use any of the following statements:
v CONNECT TO DEFAULT
v CONNECT TO database@dbserver
v CONNECT TO @dbserver

The reason for this restriction is that an application does not use DBPATH if a
CONNECT statement specifies a database server. For more information about
DBPATH, refer to the IBM Informix Guide to SQL: Reference.

What the Administrator Needs to Do

Administrators take no action to redirect clients, but they might need to attend to
the type of the database server.

What the User Needs to Do

If your applications contain code that tests if a connection has failed and issues a
reconnect statement if necessary, redirection is handled automatically. The user has
no responsibilities.

If your applications do not include such code, users who are running clients must
quit and restart all applications.

Directing Clients with the Connectivity Information

This section explains the steps in redirecting clients with the connectivity
information and the connectivity strategy that supports this method.
Operating System Location of Connectivity Information
UNIX The INFORMIXSQLHOSTS environment variable
specifies the full pathname and filename of the
connection information in
$INFORMIXDIR/etc/sqlhosts. For more
information about INFORMIXSQLHOSTS, see the
IBM Informix Guide to SQL: Reference.
Windows The connectivity information is in a key in the
Windows registry called

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-15

 HKEY_LOCAL_MACHINE\SOFTWARE
\INFORMIX\SQLHOSTS.

How Redirection with the Connectivity Information Works

The connectivity information-redirection method relies on the fact that when an
application connects to a database server, it uses the connectivity information to
find that database server.

If one of the database servers in a replication pair is unusable, an administrator

can change the definition of the unavailable database server in the connectivity
information. As described in “Changing the Connectivity Information,” the fields
of the unavailable database server (except for the dbservername field) are changed
to point to the remaining database server in the replication pair.

Because the connectivity information is read when a CONNECT statement is

issued, applications might need to restart for redirection to occur. Applications can
contain code that tests whether a connection has failed and issues a reconnect
statement, if necessary. If a connection has failed, redirection is automatic, and you
do not need to restart applications for redirection to occur.

Applications can use the following connectivity statements to support this method
of redirection:
v CONNECT TO database@dbserver
v CONNECT TO @dbserver

Applications can also use the following connectivity statements, provided that the
INFORMIXSERVER environment variable always remains set to the same
database server name and the DBPATH environment variable is not set:
v CONNECT TO DEFAULT
v CONNECT TO database

Changing the Connectivity Information

To use the connectivity information to redirect clients, you must change the
connectivity information for the clients and change other connectivity files, if
necessary.

For more information, refer to “Configuring HDR Connectivity” on page 21-5 and
Chapter 3, “Client/Server Communications,” on page 3-1.

To change the connectivity information on the client computer:

1. Comment out the entry for the failed database server.
2. Add an entry that specifies the dbservername of the failed database server in
the servername field and information for the database server to which you are
redirecting clients in the nettype, hostname, and servicename fields.
3. Use the following options in the sqlhosts file or registry to redirect applications
to another database server if a failure should occur:
a. “Connection-Redirection Option” on page 3-21
b. “End-of-Group Option” on page 3-22
c. “Group Option” on page 3-22

Figure 20-7 on page 20-17 shows how connectivity values might be modified to
redirect clients.

20-16 IBM Informix Dynamic Server Administrator’s Guide

 You do not need to change entries in the connectivity information on either of the
computers that is running the database servers.

marsh delta river

Client
Client Client
Client

cliff_ol onsoctcp cliff ol_cl

cliff_ol onsoctc cliff ol_cl beach_o onsoctcp beach ol_bc
beach_ onsoctcp beach ol_bc

cliff beach

cliff_ol beach_ol

Before failure of cliff_ol

After failure of cliff_ol

marsh delta river

Client
Client Client
Client

#cliff_ol onsoctcp cliff ol_cl

#cliff_ol onsoctcp cliff ol_cl
beach_ol onsoctcp beach ol_bc
cliff_ol onsoctcp beach ol_bc
cliff_ol onsoctcp beach ol_bc

cliff beach
/etc/hosts
beach
cliff_ol beach_ol
/etc/services
ol_bc

Figure 20-7. Connectivity Values Before and After a Failure of the cliff_ol Database Server

To change other connectivity files:

You also must ensure that the following statements are true on the client computer
before that client can reconnect to the other database server.
1. The /etc/hosts file on UNIX or hosts file on Windows has an entry for the
hostname of the computer that is running the database server to which you are
redirecting clients.
2. The /etc/services file on UNIX or services file on Windows has an entry for the
servicename of the database server to which you are redirecting clients.

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-17

 Connecting to the Database Server
After the administrator changes the connectivity information and other
connectivity files (if needed), clients connect to the database server to which the
administrator redirects them when they issue their next CONNECT statement.

If your applications contain code that tests if a connection has failed and issues a
reconnect statement if necessary, redirection is handled automatically. The user has
no responsibilities. If your applications do not include such code, users who are
running clients must quit and restart all applications.

Directing Clients with INFORMIXSERVER

This section explains the steps in redirecting clients with the INFORMIXSERVER
environment variable and the connectivity strategy that supports this method.

How Redirection Works with INFORMIXSERVER

The INFORMIXSERVER redirection method relies on the fact that when an
application does not explicitly specify a database server in the CONNECT
statement, the database server connects to the client that the INFORMIXSERVER
environment variable specifies.

If one of the database servers in a replication pair is unusable, applications that use
that database server can reset their INFORMIXSERVER environment variable to
the other database server in the pair to access the same data.

Applications read the value of the INFORMIXSERVER environment variable only

when they start. Therefore, applications must be restarted to recognize a change in
the environment variable.

To support this method of redirection, you can use the following connectivity
statements:
v CONNECT TO DEFAULT
v CONNECT TO database

You cannot use the CONNECT TO database@dbserver or CONNECT TO @dbserver

statements for this method. When a database server is explicitly named, the
CONNECT statement does not use the INFORMIXSERVER environment variable
to find a database server.

What the Administrator Needs to Do

Administrators take no action to redirect the clients, but they might need to change
the type of the database server.

What the User Needs to Do

Users who are running client applications must perform the following three steps
when they decide to redirect clients with the INFORMIXSERVER environment
variable.

To redirect clients with the INFORMIXSERVER environment variable:

1. Quit their applications.
2. Change their INFORMIXSERVER environment variable to hold the name of
the other database server in the replication pair.
3. Restart their applications.

20-18 IBM Informix Dynamic Server Administrator’s Guide

Handling Redirection Within an Application
If you use DBPATH or connectivity information to redirect, you can include in
your clients a routine that handles errors when clients encounter an HDR failure.
The routine can call another function that contains a loop that tries repeatedly to
connect to the other database server in the pair. This routine redirects clients
without requiring the user to exit the application and restart it.

Figure 20-8 shows an example of a function in a client application using the

DBPATH redirection mechanism that loops as it attempts to reconnect. After it
establishes a connection, it also tests the type of the database server to make sure it
is not a secondary database server. If the database server is still a secondary type,
it calls another function to alert the user (or database server administrator) that the
database server cannot accept updates.

/* The routine assumes that the INFORMIXSERVER environment

* variable is set to the database server that the client
* normally uses and that the DBPATH environment variable
* is set to the other database server in the pair.
*/

#define SLEEPTIME 15
#define MAXTRIES 10

main()
{
int connected = 0;
int tries;
for (tries = 0;tries < MAXTRIES && connected == 0;tries++)
{
EXEC SQL CONNECT TO "superstores";
if (strcmp(SQLSTATE,"00000"))
{
if ([Link].sqlwarn6 != ’W’)
{
notify_admin();
if (tries < MAXTRIES - 1)
sleep(SLEEPTIME);
}
else connected =1;
}
}
return ((tries == MAXTRIES)? -1:0);
}

Figure 20-8. Example of a CONNECT Loop for DBPATH Redirection Mechanism

This example assumes the DBPATH redirection mechanism and uses a form of the
CONNECT statement that supports the DBPATH redirection method. If you used
the connectivity information to redirect, you might have a different connection
statement, as follows:
EXEC SQL CONNECT TO "superstores@cliff_ol";

In this example, superstores@cliff_ol refers to a database on a database server that

the client computer recognizes. For redirection to occur, the administrator must
change the connectivity information to make that name refer to a different
database server. You might need to adjust the amount of time that the client waits
before it tries to connect or the number of tries that the function makes. Provide
enough time for an administrative action on the database server (to change the
connectivity information or change the type of the secondary database server to
standard).

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-19

 Comparing Different Redirection Mechanisms
Table 20-1 summarizes the differences among the three redirection mechanisms.
Table 20-1. Comparison of Redirection Methods for Different Connectivity Strategies
DBPATH Connectivity Information INFORMIXSERVER
Comparison Automatic User Automatic User
Criteria Redirection Redirection Redirection Redirection User Redirection
When is a client When the client next tries to After the administrator changes the When the client restarts
redirected? connect with a specified connectivity information, when the and reads a new value
database client next tries to establish a for the
connection with a database server INFORMIXSERVER
environment variable
Do clients need No Yes No Yes Yes
to be restarted to
be redirected?
What is the scope Individual Individual All clients that use a Individual Individual clients
of the clients clients given database clients redirected
redirection? redirected redirected server redirected redirected
Are changes to No No Yes
environment
variables
required?

Designing HDR Clients

This section discusses various design considerations (in addition to the redirection
considerations discussed earlier) for clients that connect to database servers that
are running data replication.

Setting Lock Mode to Wait for Access to Primary Database

Server
When the database server performs a logical recovery, it normally defers index
builds until the end of the recovery. However, if the database server is acting as a
secondary database server, it is in logical recovery mode for as long as data
replication is running. Thus, secondary database servers must use a different
mechanism to perform index builds.

The mechanism used is as follows. When the secondary database server receives a
logical-log record that necessitates a corresponding index build, it sends a message
back to the primary database server to request a physical copy of the index. The
primary database server has a lock on the table that is being updated. The owner
of the lock is a dr_btsend thread. The application thread that is executing is free to
continue processing. The dr_btsend thread cannot release the lock, however, until
the secondary database server acknowledges receipt of the index. If the application
tries to access the table while it is locked, this attempt fails, unless the application
has set the lock mode to wait.

If applications do not have lock mode set to WAIT, some unexpected errors might
occur. For example, many SQL statements cause updates to the catalog table
indexes. The following sequence of SQL statements fails if the lock mode of the
application is not set to WAIT:

20-20 IBM Informix Dynamic Server Administrator’s Guide

 CREATE DATABASE db_name;
DATABASE db_name;
CREATE TABLE tab_name;

These SQL statements would fail because the CREATE DATABASE statement
creates indexes on the systables catalog table and, therefore, places a lock on the
table until the indexes are copied over to the secondary database server.
Meanwhile, the CREATE TABLE statement tries to insert a row into the systables
catalog table. The insert fails, however, because the table is locked.

This application would fail because both the CREATE DATABASE and CREATE
TABLE statements cause updates to the systables catalog table index.

Designing Clients to Use the Secondary Database Server

To achieve a degree of load balancing when you use data replication, have some
client applications use the secondary database server in a data-replication pair.
Design all client applications that use the secondary database server with the
following points in mind:
v Any SQL statements that attempt to modify data fail.
v Locking and isolation levels are not the same as on the standard database server.
v Temporary dbspaces must be used for sorting and temporary tables.

The following sections discuss these considerations in more detail.

No Data Modification Statements

SQL statements that update dbspaces in logical-recovery mode on the secondary
database server are not allowed. For example, the ALTER FRAGMENT and
CREATE DATABASE statements would produce errors. For a complete list of data
modification statements, see the IBM Informix Guide to SQL: Syntax.

To prevent clients that are using the secondary database server from issuing
updating statements, you can take either of the following actions:
v Write client applications that do not issue updating statements.
v Make all updating statements conditional.

To make statements that perform an update conditional, make sure that client
applications test slqwarn6 of the sqlwarn field in the ESQL/C sqlca structure (and
equivalent values for other SQL APIs). The database server sets slqwarn6 to W
when it runs as a secondary database server.

Locking and Isolation Level

Because all clients that use the secondary database server only read data, locking
to ensure isolation between those clients is not required. However, a client that
uses the secondary database server is not protected from the activity of users on
the primary database server because the logrecvr threads that perform logical
recovery do not use locking.

For example, if a client connected to the secondary database server reads a row,
nothing prevents a user on the primary database server from updating that row,
even if the client connected to the secondary database server has issued a SET
ISOLATION TO REPEATABLE READ statement. The update is reflected on the
secondary database server as the logical-log records for the committed transaction
are processed. Thus, all queries on the secondary database server are essentially
dirty with respect to changes that occur on the primary database server, even

Chapter 20. High-Availability Data Replication (Enterprise/Workgroup Editions) 20-21

 though a client that uses the secondary database server might explicitly set the
isolation level to something other than Dirty Read.

Important: All queries on the secondary database server are dirty reads. Do not
run queries on the secondary database server while log records that
contain data definition language (DDL) statements are being replicated
and applied on the secondary database server.

To perform DDL operations on the primary database server:

1. Stop all activity (such as transactions) on the secondary database server.
2. Run the DDL statements on the primary database server.
For a complete list of DDL statements, see the IBM Informix Guide to SQL:
Syntax.
3. To issue a checkpoint on the primary database server, use the onmode -c
command.
4. Wait for this checkpoint to get replicated on the secondary database server.
5. Resume activity on the secondary database server.

Use of Temporary Dbspaces for Sorting and Temporary Tables

Even though the secondary database server is in read-only mode, it does write
when it needs to perform a sort or create a temporary table. “Temporary
Dbspaces” on page 10-11 explains where the database server finds temporary space
to use during a sort or for a temporary table. To prevent the secondary database
server from writing to a dbspace that is in logical-recovery mode, you must take
the following actions:
v Ensure that one or more temporary dbspaces exist. For instructions on creating a
temporary dbspace, see “Creating a Dbspace that Uses the Default Page Size” on
page 11-8.
v Then, choose one of the following actions:
– Set the DBSPACETEMP parameter in the ONCONFIG file of the secondary
database server to the temporary dbspace or dbspaces.
– Set the DBSPACETEMP environment variable of the client applications to the
temporary dbspace or dbspaces.

20-22 IBM Informix Dynamic Server Administrator’s Guide

Chapter 21. Using High-Availability Data Replication
(Enterprise/Workgroup Editions)
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Planning for HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Configuring a System for HDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-2
Meeting Hardware and Operating-System Requirements . . . . . . . . . . . . . . . . . . . 21-2
Meeting Database and Data Requirements . . . . . . . . . . . . . . . . . . . . . . . 21-3
Meeting Database Server Configuration Requirements . . . . . . . . . . . . . . . . . . . 21-3
Database Server Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Storage Space and Chunk Configuration . . . . . . . . . . . . . . . . . . . . . . . 21-4
Using Non-default Page Sizes in an HDR Environment . . . . . . . . . . . . . . . . . . 21-4
Mirroring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Physical-Log Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-4
Dbspace and Logical-Log Tape Backup Devices . . . . . . . . . . . . . . . . . . . . . 21-5
Logical-Log Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5
HDR Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5
Configuring HDR Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-5
Starting HDR for the First Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-6
Decreasing Setup Time Through an Alternate Backup Method . . . . . . . . . . . . . . . . . 21-9
Performing Basic Administration Tasks . . . . . . . . . . . . . . . . . . . . . . . . . 21-9
Changing Database Server Configuration Parameters . . . . . . . . . . . . . . . . . . . . 21-9
Backing Up Storage Spaces and Logical-Log Files . . . . . . . . . . . . . . . . . . . . . 21-9
Changing the Logging Mode of Databases . . . . . . . . . . . . . . . . . . . . . . . 21-10
Adding and Dropping Chunks and Storage Spaces . . . . . . . . . . . . . . . . . . . . 21-10
Renaming Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-10
Saving Chunk Status on the Secondary Database Server . . . . . . . . . . . . . . . . . . 21-11
Using and Changing Mirroring of Chunks . . . . . . . . . . . . . . . . . . . . . . . 21-11
Managing the Physical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing the Logical Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing Virtual Processors. . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Managing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-12
Replicating an Index to the Secondary Database Server . . . . . . . . . . . . . . . . . . . 21-12
Changing the Database Server Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 21-13
Changing the Database Server Type . . . . . . . . . . . . . . . . . . . . . . . . . . 21-14
Monitoring HDR Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Using Command-Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
onstat -g dri . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
oncheck -pr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-15
Using SMI Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Using ON-Monitor (UNIX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Restoring Data After Media Failure Occurs . . . . . . . . . . . . . . . . . . . . . . . . 21-16
Restoring After a Media Failure on the Primary Database Server . . . . . . . . . . . . . . . 21-16
Restoring After a Media Failure on the Secondary Database Server . . . . . . . . . . . . . . . 21-17
Replicating An Index to the Secondary Server . . . . . . . . . . . . . . . . . . . . . . . 21-18
Restarting HDR After a Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-18
Restarting After Critical Data Is Damaged . . . . . . . . . . . . . . . . . . . . . . . 21-18
Critical Media Failure on the Primary Database Server . . . . . . . . . . . . . . . . . . 21-18
Critical Media Failure on the Secondary Database Server . . . . . . . . . . . . . . . . . 21-19
Critical Media Failure on Both Database Servers . . . . . . . . . . . . . . . . . . . . 21-19
Restarting If Critical Data Is Not Damaged . . . . . . . . . . . . . . . . . . . . . . . 21-20
Restarting After a Network Failure . . . . . . . . . . . . . . . . . . . . . . . . 21-20
Restarting If the Secondary Database Server Fails . . . . . . . . . . . . . . . . . . . . 21-20

© Copyright IBM Corp. 1996, 2005 21-1

 Restarting If the Primary Database Server Fails . . . . . . . . . . . . . . . . . . . . 21-20

In This Chapter
This chapter describes how to plan, configure, start, and monitor High-Availability
Data Replication (HDR) for Dynamic Server, and how to restore data after a media
failure. If you plan to use HDR, read this entire chapter first. If you plan to use
IBM Informix Enterprise Replication, see the IBM Informix Dynamic Server Enterprise
Replication Guide.

Chapter 20, “High-Availability Data Replication (Enterprise/Workgroup Editions),”

on page 20-1, explains what HDR is, how it works, and how to design client
applications for an HDR environment.

HDR is available with the standard version of Dynamic Server. HDR does not
work with the IBM Informix Dynamic Server Express Edition.

Planning for HDR

Before you start setting up computers and database servers to use HDR, you might
want to do some initial planning. The following list contains planning tasks to
perform:
v Choose and acquire appropriate hardware.
v If you are using more than one database server to store data that you want to
replicate, migrate and redistribute this data so that it can be managed by a
single database server.
v Ensure that all databases you want to replicate use transaction logging. To turn
on transaction logging, see Chapter 13, “Managing the Database-Logging Mode,”
on page 13-1.
v Develop client applications to make use of both database servers in the
replication pair. For a discussion of design considerations, refer to “Redirection
and Connectivity for Data-Replication Clients” on page 20-14 and “Designing
Clients to Use the Secondary Database Server” on page 20-21.
v Create a schedule for starting HDR for the first time.
v Design a storage-space and logical-log backup schedule for the primary database
server.
v Produce a plan for how to handle failures of either database server and how to
restart HDR after a failure. Read “Redirection and Connectivity for
Data-Replication Clients” on page 20-14.

Configuring a System for HDR

To configure your system for HDR, you must take the following actions:
v Meet hardware and operating-system requirements.
v Meet database and data requirements.
v Meet database server configuration requirements.
v Configure HDR connectivity.

Each of these topics is explained in this section.

Meeting Hardware and Operating-System Requirements

For an HDR database server pair to function, it must meet the following hardware
requirements:
21-2 IBM Informix Dynamic Server Administrator’s Guide
 v The computers that run the primary and secondary database servers must be
identical (same vendor and architecture).
v The operating systems on the computers that run the primary and secondary
database servers must be identical.
v The hardware that runs the primary and secondary database servers must
support network capabilities.
v The amount of disk space allocated to dbspaces for the primary and secondary
database servers must be equal. The type of disk space is irrelevant; you can use
any mixture of raw or cooked spaces on the two database servers.

Meeting Database and Data Requirements

For an HDR database server pair to function, you must meet the following
database and data requirements:
v All data must be logged
All databases that you want to replicate must have transaction logging turned
on.
This requirement is important because the secondary database server uses
logical-log records from the primary database server to update the data that it
manages. If databases managed by the primary database server do not use
logging, updates to those databases do not generate log records, so the
secondary database server has no means of updating the replicated data.
Logging can be buffered or unbuffered.
If you need to turn on transaction logging before you start HDR, see “Turning
On Transaction Logging with ontape” on page 13-3.
v The data must reside in dbspaces or sbspaces
If your primary database server has simple large objects stored in blobspaces,
modifications to the data within those blobspaces is not replicated as part of
normal HDR processing. However, simple-large-object data within dbspaces is
replicated.
Smart large objects, which are stored in sbspaces, are replicated. The sbspaces
must be logged. User-defined types (UDTs) are replicated, unless they have
out-of-row data stored in operating system files. Data types with out-of-row data
are replicated if the data is stored in an sbspace or in a different table on the
same database server.

Meeting Database Server Configuration Requirements

For an HDR database server pair to function, you must fully configure each of the
database servers. For information on configuring a database server, refer to
Chapter 1, “Installing and Configuring the Database Server,” on page 1-1. You can
then use the relevant aspects of that configuration to configure the other database
server in the pair. For more information on the configuration parameters, see the
IBM Informix Administrator's Reference.

This section describes the following configuration considerations for HDR database
server pairs:
v Database Server Version
v Storage Space and Chunk Configuration
v Mirroring
v Physical-Log Configuration
v Dbspace and Logical-Log Tape Backup Devices
v Logical-Log Configuration

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-3

 v HDR Configuration Parameters

Database Server Version

The versions of the database server on the primary and secondary database servers
must be identical.

Storage Space and Chunk Configuration

The number of dbspaces, the number of chunks, their sizes, their pathnames, and
their offsets must be identical on the primary and secondary database servers. In
addition, the configuration contain at least one temporary dbspace. See “Use of
Temporary Dbspaces for Sorting and Temporary Tables” on page 20-22.

UNIX Only

You should use symbolic links for the chunk pathnames, as explained in
“Allocating Raw Disk Space on UNIX” on page 11-5.

Important: If you do not use symbolic links for chunk pathnames, you cannot
easily change the pathname of a chunk. For more information, see
“Renaming Chunks” on page 21-10.
End of UNIX Only

The following ONCONFIG parameters must have the same value on each database
server:
v ROOTNAME
v ROOTOFFSET
v ROOTPATH
v ROOTSIZE

Using Non-default Page Sizes in an HDR Environment

The page size of a dbspace and the buffer pool specifications are automatically
propagated from the primary to the secondary database server. While both the
primary and the secondary database servers must have the same buffer pools, the
number of buffers in the buffer pools do not need to match.

Mirroring
You do not have to set the MIRROR parameter to the same value on the two
database servers; you can enable mirroring on one database server and disable
mirroring on the other. However, if you specify a mirror chunk for the root chunk
of the primary database server, you must also specify a mirror chunk for the root
chunk on the secondary database server. Therefore, the following ONCONFIG
parameters must be set to the same value on both database servers:
v MIRROROFFSET
v MIRRORPATH

Physical-Log Configuration
The physical log should be identical on both database servers. The following
ONCONFIG parameters must have the same value on each database server:
v PHYSDBS
v PHYSFILE

21-4 IBM Informix Dynamic Server Administrator’s Guide

 Dbspace and Logical-Log Tape Backup Devices
You can specify different tape devices for the primary and secondary database
servers.

If you use ON–Bar, set the ON–Bar configuration parameters to the same value on
both database servers. For information on the ON–Bar parameters, see the IBM
Informix Backup and Restore Guide.

If you use ontape, the tape size and tape block size for the storage-space and
logical-log backup devices should be identical. The following ONCONFIG
parameters must have the same value on each database server:
v LTAPEBLK
v LTAPESIZE
v TAPEBLK
v TAPESIZE

To use a tape to its full physical capacity, set LTAPESIZE and TAPESIZE to 0.

Logical-Log Configuration
All log records are replicated to the secondary server. You must configure the same
number of logical-log files and the same logical-log size for both database servers.
The following ONCONFIG parameters must have the same value on each database
server:
v LOGFILES
v LOGSIZE
v DYNAMIC_LOGS

The database server logs the addition of logical-log files. Logical-log files added
dynamically on the primary server are automatically replicated on the secondary
server. Although the DYNAMIC_LOGS value on the secondary server has no
effect, keep DYNAMIC_LOGS in sync with the value on the primary server, in case
their roles switch.

HDR Configuration Parameters

The following HDR configuration parameters must be set to the same value on
both database servers in the replication pair:
v DRAUTO
v DRINTERVAL
v DRTIMEOUT

Configuring HDR Connectivity

For an HDR database server pair to function, the two database servers must be
able to establish a connection with one another. To satisfy this requirement, the
connectivity information on each of the computers that is running the database
server in a replication pair must have at least the following entries:
v An entry that identifies the database server that is running on that computer
v An entry that identifies the other database server in the data-replication pair

Important: Set the nettype field of the sqlhosts file or registry and the NETTYPE
configuration parameter to a network protocol such as ontlitcp,
onsoctcp, or ontlispx so that the database servers on two different

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-5

 computers can communicate with each other. HDR does not work if
the nettype field specifies a non-network protocol such as onipcshm,
onipcstr, or onipcnmp.

For information on how to redirect clients and change connectivity information, see
“Redirection and Connectivity for Data-Replication Clients” on page 20-14.

Starting HDR for the First Time

After you complete the HDR configuration, you are ready to start HDR. This
section describes the necessary steps for starting HDR.

Suppose you want to start HDR on two database servers, ServerA and ServerB.
The procedure for starting HDR, using ServerA as the primary database server
and ServerB as the secondary database server, is described in the following steps.
Table 21-1 on page 21-7 lists the commands required to perform each step and the
messages sent to the message log. You can use ontape or ON–Bar to perform the
backup and restore. You must use the same utility throughout the procedure.

Important: If you use ON–Bar to perform the backup and restore, ontape is
required on both database servers. You cannot remove ontape from
database servers participating in HDR.
If desired, you can also set up HDR using standard ON–Bar or ontape commands
for external backup and restore.

To start HDR:
1. Install user-defined types, user-defined routines, and DataBlade modules on
both database servers, and then register them on ServerA only.
2. Create a level-0 backup of ServerA.
3. Perform a physical restore of ServerB from the level-0 backup that you created
in step 1. Do not perform a logical restore.
If you are using:
v ON–Bar, use the onbar -r -p command to perform a physical restore.
v ON–Bar and performing an external restore, use the onbar -r -p -e command
to perform the physical restore.
v ontape, use the ontape -p option. You cannot use the ontape -r option
because it performs both a physical and a logical restore.
v ontape and performing an external restore, use the ontape -p -e command to
perform the physical restore.
4. Use the onmode -d command to set the type of ServerA to primary and to
indicate the name of the associated secondary database server (in this case
ServerB).
When you issue an onmode -d command, the database server attempts to
establish a connection with the other database server in the HDR pair and to
start HDR operation. The attempt to establish a connection succeeds only if the
other database server in the pair is already set to the correct type.
At this point, ServerB is not online and is not set to type secondary, so the
HDR connection is not established.
5. Use the onmode -d command to set the type of ServerB to secondary and
indicate the associated primary database server.
ServerB tries to establish an HDR connection with the primary database server
(ServerA) and start operation. The connection should be successfully
established.

21-6 IBM Informix Dynamic Server Administrator’s Guide

 Before HDR begins, the secondary database server performs a logical recovery
using the logical-log records written to the primary database server since step
2. If all these logical-log records still reside on the primary database server disk,
the primary database server sends these records directly to the secondary
database server over the network and logical recovery occurs automatically.
If you have backed up and freed logical-log files on the primary database
server, the records in these files are no longer on disk. The secondary database
server prompts you to recover these files from tape. In this case, you must
perform step 6.

Important: You must complete steps 3 and 5 together. If you need to shut
down and restart the secondary database server after step 3, you
must redo step 3.
6. If logical-log records that were written to the primary database server are no
longer on the primary disk, the secondary database server prompts you to
recover these files from tape backups.
If the secondary database server must read the backed-up logical-log files over
the network, set the tape device parameters on the secondary database server
to a device on the computer that is running the primary database server or to a
device at the same location as the primary database server.
After you recover all the logical-log files on tape, the logical restore completes
using the logical-log files on the primary database server disk.
Table 21-1. Steps to Start HDR for the First Time
Step On the Primary On the Secondary
1. Install UDRs, UDTs, and DataBlade modules. Install UDRs, UDTs, and DataBlade modules.

Register UDRs, UDTs, and DataBlade modules.

2. ontape command

ontape -s -L 0

ON–Bar command

onbar -b -L 0

Messages to message log

Level 0 archive started on rootdbs.

Archive on rootdbs completed.

3 onmode command

onmode -d primary sec_name

Messages to message log

DR: new type = primary, secondary

server name = sec_name

DR: Trying to connect to secondary server

DR: Cannot connect to secondary server

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-7

Table 21-1. Steps to Start HDR for the First Time (continued)
Step On the Primary On the Secondary
4. ontape command

ontape -p or ontape -r -p -e

Answer no when you are prompted to back up the logs.

ON–Bar command

onbar -r -p or onbar -r -p -e

Messages to message log

IBM Informix Database Server Initialized -- Shared

Memory Initialized
Recovery Mode
Physical restore of rootdbs started.
Physical restore of rootdbs completed.
5. onmode command

onmode -d secondary prim_name

Messages to message log

DR: new type = secondary, primary

server name = prim_name

If all the logical-log records written to the primary

database server since step 1 still reside on the primary
database server disk, the secondary database server
reads these records to perform logical recovery.
(Otherwise, step 5 must be performed).
Messages to message log Messages to message log

DR: Primary server connected DR: Trying to connect to primary server

DR: Primary server operational DR: Secondary server connected
DR: Failure recovery from disk in process.
n recovery worker threads will be started.
Logical Recovery Started
Start Logical Recovery - Start Log n, End Log?
Starting Log Position - n 0xnnnnnDR: Secondary server
operational
6. ontape command

ontape -l

ON–Bar command

onbar -r -l
Messages to message log Messages to message log

DR: Primary server connected DR: Secondary server connected

DR: Primary server operational DR: Failure recovery from disk in process.
n recovery worker threads will be started.
Logical Recovery Started
Start Logical Recovery - Start Log n, End Log?
Starting Log Position - n 0xnnnnn
DR: Secondary server operational

21-8 IBM Informix Dynamic Server Administrator’s Guide

 Decreasing Setup Time Through an Alternate Backup Method
If you are using ontape to backup and restore data, you can improve the speed of
HDR setup by setting the TAPEDEV configuration parameter to the STDIO value,
instead of backing up a file to a device. TAPEDEV uses STDIO as a special value
for configuring standard I/O streams.

Important: When you use the STDIO value, ontape does not operate the same way
it does when you backup to a device.

See the IBM Informix Backup and Restore Guide for details about using the STDIO
value.

Performing Basic Administration Tasks

This section contains instructions on how to perform database server
administration tasks when your system is running HDR.

Changing Database Server Configuration Parameters

Some of the configuration parameters must be set to the same value on both
database servers in the replication pair (as listed under “Meeting Database Server
Configuration Requirements” on page 21-3.) Other Dynamic Server configuration
parameters can be set to different values.

To make changes to ONCONFIG files:

1. Bring each database server offline with the onmode -k option. If DRAUTO is
set to RETAIN_TYPE or REVERSE_TYPE, you can more easily bring the
secondary database server off-line first.
2. Change the parameters on each database server.
3. Starting with the last database server that you brought offline, bring each
database server back online.
For example, if you brought the secondary database server offline last, bring
the secondary database server online first. Table 21-1 on page 21-7 and
Table 21-1 on page 21-7 list the procedures for bringing the primary and
secondary database servers back online.

If the configuration parameter does not need to have the same value on each
database server in the replication pair, you can change the value on the primary or
secondary database server individually.

Backing Up Storage Spaces and Logical-Log Files

When you use HDR, you must back up logical-log files and storage spaces only on
the primary database server. Be prepared, however, to perform storage-space and
logical-log backups on the secondary database server in case the type of the
database server is changed to standard.

You must use the same backup and restore tool on both database servers.

The block size and tape size used (for both storage-space backups and logical-log
backups) must be identical on the primary and secondary database servers.

You can use ontape to set the tape size to 0 to automatically use the full physical
capacity of a tape.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-9

 Changing the Logging Mode of Databases
You cannot turn on transaction logging for databases on the primary database
server while you are using HDR. You can turn logging off for a database; however,
subsequent changes to that database are not duplicated on the secondary database
server.

To turn on database logging:

1. To turn HDR off, shut down the secondary database server.
2. Turn on database logging.
After you turn on logging for a database, if you start data replication without
performing the level-0 backup on the primary database server and restore on
the secondary database server, the database on the primary and secondary
database servers might have different data. This situation could cause
data-replication problems.
3. Perform a level-0 backup on the primary database server and restore on the
secondary database server. This procedure is described in “Starting HDR for
the First Time” on page 21-6.

Adding and Dropping Chunks and Storage Spaces

You can perform disk-layout operations, such as adding or dropping chunks and
dbspaces, only from the primary database server. The operation is replicated on the
secondary database server. This arrangement ensures that the disk layout on both
database servers in the replication pair remains consistent.

The directory pathname or the actual file for chunks must exist before you create
them. Make sure the pathnames (and offsets, if applicable) exist on the secondary
database server before you create a chunk on the primary database server, or else
the database server turns off data replication.

Renaming Chunks
If you use symbolic links for chunk pathnames, you can rename chunks while
HDR is operating. For instructions on renaming chunks, see the IBM Informix
Backup and Restore Guide.

If you do not use symbolic links for chunk pathnames, you must take both
database servers offline while renaming the chunks, for the time that it take to
complete a cold restore of the database server.

To rename chunks on a failed HDR server:

1. Change the mode of the undamaged server to standard.
2. Take a level-0 backup of the standard server.
3. Shut down the standard server.
4. Rename the chunks on the standard server during a cold restore from the new
level-0 archive (for instructions, see the IBM Informix Backup and Restore Guide).
5. Start the standard server.
6. Take another level-0 archive of the standard server. Be sure the server is in
standard mode.
7. Restore the failed server with the new level-0 backup and reestablish the HDR
pair.

21-10 IBM Informix Dynamic Server Administrator’s Guide

Saving Chunk Status on the Secondary Database Server
For a data-replication pair, if the status of a chunk (down, online) is changed on the
secondary database server, and that secondary server is restarted before a
checkpoint is completed, the updated chunk status is not saved.

To ensure that the new chunk status is flushed to the reserved pages on the
secondary database server, force a checkpoint on the primary database server and
verify that a checkpoint also completes on the secondary database server. The new
chunk status is now retained even if the secondary database server is restarted.

If the primary chunk on the secondary database server is down, you can recover
the primary chunk from the mirror chunk.

To recover the primary chunk from the mirror chunk:

1. Run onspaces -s on the secondary database server to bring the primary chunk
online.
You also can use ISA to bring the primary chunk online.
2. Run onmode -c on the primary database server to force a checkpoint.
3. Run onmode -m on the primary database server to verify that a checkpoint
was actually performed.
4. Run onmode -m on the secondary database server to verify that a checkpoint
was also completed on the secondary database server.

After you complete these steps, the primary chunk will be online when you restart
the secondary database server.

Using and Changing Mirroring of Chunks

Before you can add a mirror chunk, the disk space for that chunk must already be
allocated on both the primary and secondary database servers. If you want to
mirror a dbspace on one of the database servers in the replication pair, you must
create mirror chunks for that dbspace on both database servers. For general
information on allocating disk space, see “Allocating Disk Space” on page 11-3.

Do not set the MIRROR configuration parameter to 1 unless you are using
mirroring.

You can perform disk-layout operations from the primary database server only.
Thus, you can add or drop a mirror chunk only from the primary database server.
A mirror chunk that you add to or drop from the primary database server is added
to or dropped from the secondary database server as well. You must perform
mirror recovery for the newly added mirror chunk on the secondary database
server. For more information, see “Recovering a Mirror Chunk” on page 19-6.

When you drop a chunk from the primary database server, Dynamic Server
automatically drops the corresponding chunk on the secondary database server.
This applies to both primary and mirror chunks.

When you turn mirroring off for a dbspace on the primary database server,
Dynamic Server does not turn mirroring off for the corresponding dbspace on the
secondary database server. To turn off mirroring for a dbspace on the secondary
database server independent of the primary server, use onspaces -r. For more
information about turning off mirroring, see “Ending Mirroring” on page 19-7.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-11

 You can take down a mirror chunk or recover a mirror chunk on either the
primary or secondary database server. These processes are transparent to HDR.

Managing the Physical Log

The size of the physical log must be the same on both database servers. If you
change the size and location of the physical log on the primary database server,
this change is replicated to the secondary database server; however, the PHYSDBS
and PHYSFILE parameters in the secondary ONCONFIG file are not updated. You
must change these parameters manually by editing the ONCONFIG file. For the
procedure for making this change, see “Changing Database Server Configuration
Parameters” on page 21-9.

For information on changing the size and location of the physical log, refer to
Chapter 17, “Managing the Physical Log,” on page 17-1.

Managing the Logical Log

The size of the logical log must be the same on both database servers. You can add
or drop a logical-log file with the onparams utility, as described in Chapter 15,
“Managing Logical-Log Files,” on page 15-1. Dynamic Server replicates this change
on the secondary database server; however, the LOGFILES parameter on the
secondary database server is not updated. After you issue the onparams command
from the primary database server, therefore, you must manually change the
LOGFILES parameter to the desired value on the secondary database server.
Finally, for the change to take effect, you must perform a level-0 backup of the root
dbspace on the primary database server.

If you add a logical-log file to the primary database server, this file is available for
use and flagged F as soon as you perform the level-0 backup. The new logical-log
file on the secondary database server is still flagged A. However, this condition
does not prevent the secondary database server from writing to the file.

Managing Virtual Processors

The number of virtual processors has no effect on data replication. You can
configure and tune each database server in the pair individually.

Managing Shared Memory

If you make changes to the shared-memory ONCONFIG parameters on one
database server, you must make the same changes at the same time to the
shared-memory ONCONFIG parameters on the other database server. For the
procedure for making this change, see “Changing Database Server Configuration
Parameters” on page 21-9.

Replicating an Index to the Secondary Database Server

If an index on an HDR secondary database server becomes corrupt and needs to
be rebuilt, you can either:
v Manually replicate the index from the primary server to the secondary server.
v Let the secondary server automatically replicate the index if you enabled the
secondary server to do this.

To enable the secondary database server to automatically replicate the index, either:
v Set onmode -d idxauto to on.
v Set the value of the DRIDXAUTO configuration parameter to 1.

21-12 IBM Informix Dynamic Server Administrator’s Guide

 After you set either of these values, when one of the threads on the secondary
database server detects a corrupt index, the index is automatically replicated to the
secondary database server. Restarting index replication can take up to the amount
of time specified in seconds in the DRTIMEOUT configuration parameter.

Sometimes, you might want to replicate an index manually, for example, when you
want to postpone index repair because the table is locked. If you want to be able to
manually replicate an index on the HDR secondary server, turn off the automatic
replication feature.

To turn off the automatic index replication feature, either:

v Set onmode -d idxauto to off.
v Set the DRIDXAUTO configuration parameter to 0.

If onmode -d idxauto is set to off or DRIDXAUTO is set to 0 and the secondary

server detects a corrupt index, you can manually replicate an index on the HDR
secondary server by issuing an onmode -d index command in the following
format.

onmode -d index database:[ownername].table#index

For example:

onmode -d index cash_db:user_dx.table_12#index_z

In the case of a fragmented index with one corrupt fragment, the onmode -d
idxauto option only transfers the single affected fragment, whereas the onmode -d
index option transfers the whole index.

Note: When turning the automatic index replication feature on or off, you can use
either the onmode command or the DRIDXAUTO configuration parameter.
If you use the onmode command, you do not need to stop and restart the
database server. When you use the DRIDXAUTO parameter, the database
server is restarted with the setting you specify. The onmode command does
not change the DRIDXAUTO value. If you use the onmode command, you
must manually change the value of DRIDXAUTO.

The [Link] file produced by the secondary server contains information about
any replicated index.

Changing the Database Server Mode

To change the database server mode, use the onmode utility from the command
line or ISA. For information about onmode, see the IBM Informix Dynamic Server
Administrator's Reference.

Table 21-2 summarizes the effects of changing the mode of the primary database
server.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-13

Table 21-2. Mode Changes on the Primary Database Server
On the Primary On the Secondary To Restart HDR
Any mode to offline Secondary displays: Treat it like a failure of the primary. Two
DR: Receive error. different scenarios are possible, depending on
(onmode -k) what you do with the secondary database server
HDR is turned off. while the primary database server is offline. See
these sections for information:
The mode remains read-only.
v “The Secondary Database Server Was Not
If DRAUTO is set to 0 (OFF), the Changed to a Standard Database Server” on
mode remains read-only. page 21-21
v “The Secondary Database Server Is Changed
If DRAUTO is set to 1 to a Standard Database Server Automatically”
(RETAIN_TYPE), the secondary on page 21-21
server switches to standard type
and can accept updates. (If
DRAUTO is set to 2
(REVERSE_TYPE), the secondary
database server becomes a primary
database server as soon as the
connection ends when the old
primary server fails.)
to online, quiescent, or Secondary does not receive errors. Use onmode -m on the primary.
single-user
HDR remains on.
(onmode -s / onmode -u)
Mode remains read-only.
(onmode -j )

Table 21-3 summarizes the effects of changing the mode of the secondary database
server.
Table 21-3. Mode Changes on the Secondary Database Server
On the Secondary On the Primary To Restart HDR
Read-only offline Primary displays: Treat it as you would a failure of the secondary.
DR: Receive error. Follow the procedures in “Restarting If the
(onmode -k) Secondary Database Server Fails” on page 21-20.
HDR is turned off.

Note: Single-user mode operates the same way on an HDR secondary database
server as it does on the primary database server.

Changing the Database Server Type

You can change the type of either the primary or the secondary database server.

You can change the database server type from secondary to standard only if HDR
is turned off on the secondary database server. HDR is turned off when the data
replication connection to the primary database server breaks or data replication
fails on the secondary database server. When you take the standard database
server offline and bring it back online, it does not attempt to connect to the other
database server in the replication pair.

Use the following commands to switch the type:

v hdrmksec.[sh|bat] and hdrmkpri.[sh|bat] scripts

21-14 IBM Informix Dynamic Server Administrator’s Guide

 To switch the database server type using hdrmkpri and hdrmksec scripts:
1. Shut down the primary database server (ServerA):
onmode -ky
2. With the secondary database server (ServerB) online, run the [Link]
script on UNIX or [Link] script on Windows. Now ServerB is a primary
database server.
3. For ServerA, run the [Link] script on UNIX or [Link] script on
Windows. Now ServerA is a secondary database server.
4. Bring ServerB (primary database server) online.

Monitoring HDR Status

Monitor the HDR status of a database server to determine the following
information:
v The database server type (primary, secondary, or standard)
v The name of the other database server in the pair
v Whether HDR is on
v The values of the HDR parameters

Using Command-Line Utilities

The header information displayed every time you execute onstat has a field to
indicate if a database server is operating as a primary or secondary database
server.

The following example shows a header for a database server that is the primary
database server in a replication pair, and in online mode:
IBM Informix Dynamic
Server Version 9.30.UC1 -- online(Prim) -- Up 45:08:57

This example shows a database server that is the secondary database server in a
replication pair, and in read-only mode.
IBM Informix Dynamic Server Version 9.30.UC1 -- Read-Only (Sec) -- Up 45:08:57

The following example shows a header for a database server that is not involved
in HDR. The type for this database server is standard.
IBM Informix Dynamic Server Version 9.30.UC1 -- online -- Up 20:10:57

onstat -g dri
To obtain full HDR monitoring information, execute the onstat -g dri option. The
following fields are displayed:
v The database server type (primary, secondary, or standard)
v The HDR state (on or off)
v The paired database server
v The last HDR checkpoint
v The values of the HDR configuration parameters

For an example of onstat -g dri output, see the IBM Informix Administrator's
Reference.

oncheck -pr
If your database server is running HDR, the reserved pages PAGE_1ARCH and
PAGE_2ARCH store the checkpoint information that HDR uses to synchronize the

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-15

 primary and secondary database servers. An example of the relevant oncheck -pr
output is given in Figure 21-1.

Validating Informix Database Server reserved pages - PAGE_1ARCH &

PAGE_2ARCH
Using archive page PAGE_1ARCH.

Archive Level 0
Real Time Archive Began 01/11/95 16:54:07
Time Stamp Archive Began 11913
Logical Log Unique Id 3
Logical Log Position b018

DR Ckpt Logical Log Id 3

DR Ckpt Logical Log Pos 80018
DR Last Logical Log Id 3
DR Last Logical Log Page 128

Figure 21-1. oncheck -pr PAGE_1ARCH Output for Database Server Running HDR

Using SMI Tables

The sysdri table, described in the chapter on the sysmaster database in the IBM
Informix Administrator's Reference, contains the following columns.
Column Description
type HDR server type
state HDR server state
name Database server name
intvl HDR buffer flush interval
timeout Network timeout
lostfound HDR lost+found pathname

Using ON-Monitor (UNIX)

Choose Status > Replication to see information about HDR. This option displays
the same information as the onstat -g dri option.

Restoring Data After Media Failure Occurs

The result of a disk failure depends on whether the disk failure occurs on the
primary or the secondary database server, whether the chunks on the disk contain
critical media (the root dbspace, a logical-log file, or the physical log), and whether
the chunks are mirrored.

Restoring After a Media Failure on the Primary Database

Server
Table 21-4 on page 21-17 summarizes the various scenarios for restoring data if the
primary database server suffers media failure. The following issues are relevant:
v If chunks are mirrored, you can perform recovery just as you would for a
standard database server that used mirroring.
v In cases where the chunks are not mirrored, the procedure for restoring the
primary database server depends on whether the disk that failed contains critical
media.
If the disk contains critical media, the primary database server fails. You have to
perform a full restore using the primary dbspace backups (or the secondary

21-16 IBM Informix Dynamic Server Administrator’s Guide

 dbspace backups if the secondary database server was switched to standard
mode and activity redirected). See “Restarting After Critical Data Is Damaged”
on page 21-18.
If the disk does not contain critical media, you can restore the affected dbspaces
individually with a warm restore. A warm restore consists of two parts: first a
restore of the failed dbspace from a backup and next a logical restore of all
logical-log records written since that dbspace backup. For more information on
performing a warm restore, see the IBM Informix Backup and Restore Guide. You
must back up all logical-log files before you perform the warm restore.
Table 21-4. Scenarios for Media Failure on the Primary Database Server
HDR Critical Chunks Effect of Failure and Procedure for Restoring
Server Media Mirrored Media
Primary Yes No Primary database server fails. Follow the procedure
in “Restarting After Critical Data Is Damaged” on
page 21-18.
Primary Yes Yes Primary database server remains online. Follow the
procedures in “Recovering a Mirror Chunk” on page
19-6.
Primary No No Primary database server remains online. Follow the
procedure in your Dynamic Server backup and
restore manual for performing a warm restore of a
dbspace from a dbspace backup. Back up all
logical-log files before you perform the warm
restore.
Primary No Yes Primary database server remains online. Follow the
procedures in “Recovering a Mirror Chunk” on page
19-6.

Restoring After a Media Failure on the Secondary Database

Server
High-Availability Data Replication:Table 21-5 summarizes the various scenarios for
restoring data if the secondary database server suffers media failure. The following
issues are relevant:
v If chunks are mirrored, you can perform recovery just as you would for a
standard database server that uses mirroring.
v In cases where the chunks are not mirrored, the secondary database server fails
if the disk contains critical media but remains online if the disk does not contain
critical media. In both cases, you have to perform a full restore using the
dbspace backups on the primary database server. (See “Restarting After Critical
Data Is Damaged” on page 21-18.) In the second case, you cannot restore
selected dbspaces from the secondary dbspace backup because they might now
deviate from the corresponding dbspaces on the primary database server. You
must perform a full restore.
Table 21-5. Scenarios for Media Failure on the Secondary Database Server
HDR Critical Chunks
Server Media Mirrored Effect of Failure
Secondary Yes No Secondary database server fails. Primary database
server receives errors. HDR is turned off. Follow the
procedure in “Restarting After Critical Data Is
Damaged” on page 21-18.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-17

 Table 21-5. Scenarios for Media Failure on the Secondary Database Server (continued)
HDR Critical Chunks
Server Media Mirrored Effect of Failure
Secondary Yes Yes Secondary database server remains online in
read-only mode. Follow the procedures in
“Recovering a Mirror Chunk” on page 19-6.
Secondary No No Secondary database server remains online in
read-only mode. Primary database server receives
errors. HDR is turned off. Follow the procedure in
“Restarting After Critical Data Is Damaged” on
page 21-18.
Secondary No Yes Secondary database server remains online in
read-only mode. Follow the procedures in
“Recovering a Mirror Chunk” on page 19-6.

Replicating An Index to the Secondary Server

If an index on an HDR secondary database server becomes corrupt, the normal
process for correcting the problem is to drop the index on the primary database
server and then rebuild it. This process requires a lock on the table and can take a
considerable amount of time to complete. However, instead you can replicate the
index from the primary database server to the secondary database server without
rebuilding the index on the primary database server.

To manually start index replication, use the onmode -d command.

To set up automatic index replication if an index on the secondary database server

is detected as corrupt, set the DRIDXAUTO configuration parameter. Use the
onmode -d idxauto command to update the value of the DRIDXAUTO
configuration parameter for the session.

Restarting HDR After a Failure

See “HDR Failures Defined” on page 20-10 for information on the various types of
HDR failures. The procedure that you must follow to restart HDR depends on
whether or not critical data was damaged on one of the database servers. Both
cases are discussed in this section.

Restarting After Critical Data Is Damaged

If one of the database servers experiences a failure that damages the root dbspace,
the dbspace that contains logical-log files, or the dbspace that contains the physical
log, you must treat the failed database server as if it has no data on the disks, and
you are starting HDR for the first time. Use the functioning database server with
the intact disks as the database server with the data.

Critical Media Failure on the Primary Database Server

You might need to restart HDR after the primary database server suffers a critical
media failure. Table 21-6 lists the commands required to perform this procedure.

To restart HDR after a critical media failure:

1. If the original secondary database server was changed to a standard database
server, bring this database server (DRAUTO = 0) to quiescent mode and then
use the onmode -d command to change the type back to secondary.

21-18 IBM Informix Dynamic Server Administrator’s Guide

 If DRAUTO = 1 (RETAIN_TYPE), this step does not apply. The database server
automatically performs a graceful shutdown and switches back to type
secondary when you bring the primary database server back online.
If DRAUTO = 2 (REVERSE_TYPE), the secondary database server becomes a
primary database server as soon as the connection ends when the old primary
server fails, rather than when the old primary server is restarted.
2. Restore the primary database server from the last dbspace backup.
3. Use the onmode -d command to set the type of the primary database server
and to start HDR.
The onmode -d command starts a logical recovery of the primary database
server from the logical-log files on the secondary database server disk. If logical
recovery cannot complete because you backed up and freed logical-log files on
the original secondary database server, HDR does not start until you perform
step 4.
4. Apply the logical-log files from the secondary database server, which were
backed up to tape, to the primary database server.
If this step is required, the primary database server sends a message prompting
you to recover the logical-log files from tape. This message appears in the
message log. When all the required logical-log files have been recovered from
tape, any remaining logical-log files on the secondary disk are recovered.
Table 21-6. Steps for Restarting HDR After a Critical Media Failure on the Primary Database
Server
Step On the Primary Database Server On the Secondary Database Server
1. onmode command

onmode -s
onmode -d secondary prim_name
2. ON–Bar command

onbar -r -p

ontape command

ontape -p
3. onmode command

onmode -d primary sec_name

4. ontape command

ontape -l

Critical Media Failure on the Secondary Database Server

If the secondary database server suffers a critical media failure, you can follow the
same steps listed under “Starting HDR for the First Time” on page 21-6.

Critical Media Failure on Both Database Servers

In the unfortunate event that both of the computers that are running database
servers in a replication pair experience a failure that damages the root dbspace, the
dbspaces that contain logical-log files or the physical log, you need to restart HDR.

To restart HDR after a critical media failure on both database servers:

1. Restore the primary database server from the storage space and logical-log
backup.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-19

 2. After you restore the primary database server, treat the other failed database
server as if it had no data on the disks and you were starting HDR for the first
time.
(See “Starting HDR for the First Time” on page 21-6.) Use the functioning
database server with the intact disks as the database server with the data.

Restarting If Critical Data Is Not Damaged

If no damage occurred to critical data on either database server, the following four
scenarios, each requiring different procedures for restarting HDR, are possible:
v A network failure occurs.
v The secondary database server fails.
v The primary database server fails, and the secondary database server is not
changed to a standard database server.
v The primary database server fails, and the secondary database server is changed
to a standard database server.

Restarting After a Network Failure

After a network failure, the primary database server is in online mode, and the
secondary database server is in read-only mode. HDR is turned off on both
database servers (state = off). When the connection is reestablished, you can restart
HDR by issuing onmode -d secondary primary_name on the secondary database
server. Restarting HDR might not be necessary because the primary database
server attempts to reconnect every 10 seconds and displays a message regarding
the inability to connect every 2 minutes. You do not have to use onmode restart
the connection.

Restarting If the Secondary Database Server Fails

If you need to restart HDR after a failure of the secondary database server,
complete the steps in Table 21-7. The steps assume that you have been backing up
logical-log files on the primary database server as necessary since the failure of the
secondary database server.
Table 21-7. Steps in Restarting After a Failure on the Secondary Database Server
Step On the Primary On the Secondary
1. The primary database server should oninit
be in online mode.
If you receive the following message in the
message log, continue with step 2:

DR: Start Failure recovery from tape

2. ontape command

ontape -l

ON–Bar command

onbar -r -l

Restarting If the Primary Database Server Fails

The following sections describe how to restart HDR if the primary database server
fails under various circumstances.

21-20 IBM Informix Dynamic Server Administrator’s Guide

 The Secondary Database Server Was Not Changed to a Standard Database
Server: If you need to restart HDR after a failure of the primary database server if
the secondary database server is not changed to standard, simply bring the
primary database server back online using oninit.

The Secondary Database Server Is Changed to a Standard Database Server: If

you need to restart HDR after a failure of the primary database server, and you
have changed the secondary database server to be a standard database server,
complete the steps in Table 21-9.
Table 21-8. Steps to Restart If You Changed the Secondary Database Server to Standard
Step On the Primary Database Server On the Secondary Database Server
1. onmode -s

This step takes the secondary database

server (now standard) to quiescent
mode. All clients that are connected to
this database server must disconnect.
Applications that perform updates
must be redirected to the primary. See
“Redirection and Connectivity for
Data-Replication Clients” on page
20-14.
2. onmode -d secondary prim_name
3. oninit

If all the logical-log records that were written to the secondary

database server are still on the secondary database server disk, the
primary database server recovers these records from that disk
when you issue the oninit command.

If you have backed up and freed the logical-log files on the

secondary, the records in these files are no longer on disk. In this
case, you are prompted to recover these logical-log files from tape
(step 4).

For ontape users:

If you want to read the logical-log records over the network, set
the logical-log tape device to a device on the computer that is
running the secondary database server.
4. If you are prompted to recover logical-log records from tape,
perform this step.

ontape command

ontape -l

ON–Bar command

onbar -r -l

The Secondary Database Server Is Changed to a Standard Database Server

Automatically: If you need to restart HDR after a failure of the primary database
server, and the secondary database server was automatically changed to a standard
database server (as described in “Automatic Switchover” on page 20-12), complete
the steps shown in the following table.

Chapter 21. Using High-Availability Data Replication (Enterprise/Workgroup Editions) 21-21

Table 21-9. Steps to Restart If You Changed the Secondary Database Server to Standard Automatically
Step On the Primary Database Server On the Secondary Database Server
1. % oninit If DRAUTO = 1, the secondary
database server automatically goes
If DRAUTO = 1, the type of this database server will be set to through graceful shutdown when you
primary. bring the primary back up. This
ensures that all clients are
If DRAUTO = 2, the type of this database server will be set to disconnected. The type is then
secondary when it is restarted. switched back to secondary. Any
applications that perform updates
If all the logical-log records that were written to the secondary
must be redirected back to the primary
database server are still on the secondary database server disk, the
database server. See “Redirection and
primary database server recovers these records from that disk
Connectivity for Data-Replication
when you issue the oninit command.
Clients” on page 20-14.
If logical-log files that you have backed up and freed are on the
If DRAUTO = 2, the secondary
secondary database server, the records in these files are no longer
database server switches to primary
on disk. In this case, you are prompted to recover these logical-log
and then automatically to standard.
files from tape (step 2).
The old primary database server
For ontape users: becomes a secondary database server
after it restarts and connects to the
v Set the logical-log tape device to a device on the computer
other server and determines that it is
running the secondary database server.
now a primary database server.
2. If you are prompted to recover logical-log records from tape,
perform this step.

ontape command
% ontape -l

ON–Bar command

onbar -r -l

21-22 IBM Informix Dynamic Server Administrator’s Guide

Chapter 22. Consistency Checking
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-1
Performing Periodic Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Verifying Consistency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Validating System Catalog Tables . . . . . . . . . . . . . . . . . . . . . . . . . 22-2
Validating Data Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Validating Extents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Validating Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Validating Logical Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Validating Reserved Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Validating Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Monitoring for Data Inconsistency . . . . . . . . . . . . . . . . . . . . . . . . . . 22-3
Reading Assertion Failures in the Message Log and Dump Files . . . . . . . . . . . . . . . 22-3
Validating Table and Tablespace Data . . . . . . . . . . . . . . . . . . . . . . . . 22-4
Retaining Consistent Level-0 Backups . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Dealing with Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Finding Symptoms of Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Fixing Index Corruption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Fixing I/O Errors on a Chunk . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-5
Collecting Diagnostic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-6
Disabling I/O Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-7
Monitoring the Database Server for Disabling I/O Errors . . . . . . . . . . . . . . . . . . . 22-8
Using the Message Log to Monitor Disabling I/O Errors . . . . . . . . . . . . . . . . . . 22-8
Using Event Alarms to Monitor Disabling I/O Errors . . . . . . . . . . . . . . . . . . . . 22-8
Using No Bad-Sector Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 22-9

In This Chapter
Informix database servers are designed to detect database server malfunctions or
problems caused by hardware or operating-system errors. It detects problems by
performing assertions in many of its critical functions. An assertion is a consistency
check that verifies that the contents of a page, structure, or other entity match what
would otherwise be assumed.

When one of these checks finds that the contents are not what they should be, the
database server reports an assertion failure and writes text that describes the check
that failed in the database server message log. The database server also collects
further diagnostics information in a separate file that might be useful to IBM
Informix Technical Support staff.

This chapter provides an overview of consistency-checking measures and ways of

handling inconsistencies. It covers the following topics:
v Performing periodic consistency checking
v Dealing with data corruption
v Collecting advanced diagnostic information
v Monitoring the database server for disabling I/O errors

© Copyright IBM Corp. 1996, 2005 22-1

Performing Periodic Consistency Checking
To gain the maximum benefit from consistency checking and to ensure the
integrity of dbspace backups, you should periodically take the following actions:
v Verify that all data and the database server overhead information is consistent.
v Check the message log for assertion failures while you verify consistency.
v Create a level-0 dbspace backup after you verify consistency.

The following sections describe each of these actions.

Verifying Consistency
Because of the time needed for this check and the possible contention that the
check can cause, schedule this check for times when activity is at its lowest. You
should perform this check just before you create a level-0 backup.

Run the commands shown in Table 22-1 as part of the consistency check.
Table 22-1. Checking Data Consistency
Type of Validation Command
System catalog tables oncheck -cc
Data oncheck -cD dbname
Extents oncheck -ce
Indexes oncheck -cI dbname
Reserved pages oncheck -cr
Logical logs and reserved pages oncheck -cR
Metadata and smart large objects oncheck -cs

You can run each of these commands while the database server is in online mode.
For information about how each command locks objects as it checks them and which
users can perform validations, see oncheck in the IBM Informix Administrator's
Reference.

In most cases, if one or more of these validation procedures detects an error, the
solution is to restore the database from a dbspace backup. However, the source of
the error might also be your hardware or operating system.

Validating System Catalog Tables

To validate system catalog tables, use the oncheck -cc command.

Each database contains its own system catalog, which contains information about
the database tables, columns, indexes, views, constraints, stored procedures, and
privileges.

If a warning appears when validation completes, its only purpose is to alert you
that no records of a specific type were found. These warnings do not indicate any
problem with your data, your system catalog, or even your database design. This
warning indicates only that no synonym exists for any table; that is, the system
catalog contains no records in the table syssyntable. For example, the following
warning might appear if you validate system catalog tables for a database that has
no synonyms defined for any table:
WARNING: No syssyntable records found.

22-2 IBM Informix Dynamic Server Administrator’s Guide

 However, if you receive an error message when you validate system catalog tables,
the situation is quite different. Contact IBM Informix Technical Support
immediately.

Validating Data Pages

To validate data pages, use the oncheck -cD command.

If data-page validation detects errors, try to unload the data from the specified
table, drop the table, re-create the table, and reload the data. For information about
loading and unloading data, see the IBM Informix Migration Guide. If this procedure
does not succeed, perform a data restore from a storage-space backup.

Validating Extents
To validate extents in every database, use the oncheck -ce command.

Extents must not overlap. If this command detects errors, perform a data restore
from a storage-space backup.

Validating Indexes
To validate indexes on each of the tables in the database, use the oncheck -cI
command.

If this command detects errors, drop and re-create the affected index.

Validating Logical Logs

To validate logical logs and the reserved pages, use the oncheck -cR command.

Validating Reserved Pages

To validate reserved pages, use the oncheck -cr command.

Reserved pages are pages that reside at the beginning of the initial chunk of the
root dbspace. These pages contain the primary database server overhead
information. If this command detects errors, perform a data restore from
storage-space backup.

This command might provide warnings. In most cases, these warnings call your
attention to situations of which you are already aware.

Validating Metadata
Execute oncheck -cs for each database to validate metadata for all smart large
objects in a database. If necessary, restore the data from a dbspace backup.

Monitoring for Data Inconsistency

If the consistency-checking code detects an inconsistency during database server
operation, an assertion failure is reported to the database server message log. (See
the message-log chapter in the IBM Informix Administrator's Reference.)

Reading Assertion Failures in the Message Log and Dump Files

Figure 22-1 shows the form that assertion failures take in the message log.

Assert Failed: Short description of what failed

Who: Description of user/session/thread running at the time
Result: State of the affected database server entity
Action: What action the database server administrator should take
See Also: file(s) containing additional diagnostics

Figure 22-1. Form of Assertion Failures in the Message Log

Chapter 22. Consistency Checking 22-3

 The See Also: line contains one or more of the following filenames:
v [Link]
v [Link]

UNIX Only

v [Link]
v [Link]
v /pathname/core
End of UNIX Only

In all cases, xxx is a hexadecimal number common to all files associated with the
assertion failures of a single thread. The files [Link], [Link], and [Link] are
in the directory that the ONCONFIG parameter DUMPDIR specifies.

The file [Link] contains a copy of the assertion-failure message that was sent to the
message log, as well as the contents of the current, relevant structures and data
buffers.

The file [Link] contains a complete copy of the database server shared
memory at the time of the assertion failure, but only if the ONCONFIG parameter
DUMPSHMEM is set to 1.

UNIX Only

On UNIX, [Link] contains a core dump of the database server virtual process on
which the thread was running at the time, but only if the ONCONFIG parameter
DUMPGCORE is set to 1 and your operating system supports the gcore utility. The
core file contains a core dump of the database server virtual process on which the
thread was running at the time, but only if the ONCONFIG parameter
DUMPCORE is set to 1. The pathname for the core file is the directory from which
the database server was last invoked.
End of UNIX Only

Validating Table and Tablespace Data

To validate table and tablespace data, use the oncheck -cD command on the
database or table.

Most of the general assertion-failure messages are followed by additional

information that usually includes the tblspace where the error was detected. If this
check verifies the inconsistency, unload the data from the table, drop the table,
re-create the table, and reload the data. Otherwise, no other action is needed.

In many cases, the database server stops immediately when an assertion fails.
However, when failures appear to be specific to a table or smaller entity, the
database server continues to run.

When an assertion fails because of inconsistencies on a data page that the database
server accesses on behalf of a user, an error is also sent to the application process.
The SQL error depends on the operation in progress. However, the ISAM error is
almost always either -105 or -172, as follows:
-105 ISAM error: bad isam file format
-172 ISAM error: Unexpected internal error

22-4 IBM Informix Dynamic Server Administrator’s Guide

 For additional details about the objectives and contents of messages, see the
chapter on message-log messages in the IBM Informix Administrator's Reference.

Retaining Consistent Level-0 Backups

After you perform the checks described in “Verifying Consistency” on page 22-2
without errors, create a level-0 backup. Retain this storage-space backup and all
subsequent logical-log backup tapes until you complete the next consistency check.
You should perform the consistency checks before every level-0 backup. If you do
not, then at minimum keep all the tapes necessary to recover from the
storage-space backup that was created immediately after the database server was
verified to be consistent.

Dealing with Corruption

This section describes some of the symptoms of database server system corruption
and actions that the database server or you, as administrator, can take to resolve
the problems. Corruption in a database can occur as a consequence of hardware or
operating-system problems, or from some unknown database server problems.
Corruption can affect either data or database server overhead information.

Finding Symptoms of Corruption

The database server alerts the user and administrator to possible corruption in the
following ways:
v Error messages reported to the application state that pages, tables, or databases
cannot be found. One of the following errors is always returned to the
application if an operation has failed because of an inconsistency in the
underlying data or overhead information:
-105 ISAM error: bad isam file format
-172 ISAM error: Unexpected internal error
v Assertion-failure reports are written to the database server message log. They
always indicate files that contain additional diagnostic information that can help
you determine the source of the problem. See “Verifying Consistency” on page
22-2.
v The oncheck utility returns errors

Fixing Index Corruption

At the first indication of corruption, run the oncheck -cI command to determine if
corruption exists in the index.

If you check indexes while the database server is in online mode, oncheck detects
the corruption but does not prompt you for repairs. If corruption exists, you can
drop and re-create the indexes using SQL statements while you are in online mode
(the database server locks the table and index). If you run oncheck -cI in quiescent
mode and corruption is detected, you are prompted to confirm whether the utility
should attempt to repair the corruption.

Fixing I/O Errors on a Chunk

If an I/O error occurs during the database server operation, the status of the chunk
on which the error occurred changes to down.

If a chunk is down, the onstat -d display shows the chunk status as PD- for a
primary chunk and MD- for a mirror chunk. For an example of onstat -d output,
see the IBM Informix Administrator's Reference.

Chapter 22. Consistency Checking 22-5

 In addition, the message log lists a message with the location of the error and a
suggested solution. The listed solution is a possible fix, but does not always correct
the problem.

If the down chunk is mirrored, the database server continues to operate using the
mirror chunk. Use operating-system utilities to determine what is wrong with the
down chunk and correct the problem. You must then direct the database server to
restore mirror chunk data.

For information about recovering a mirror chunk, refer to “Recovering a Mirror

Chunk” on page 19-6.

If the down chunk is not mirrored and contains logical-log files, the physical log,
or the root dbspace, the database server immediately initiates a stop action.
Otherwise, the database server can continue to operate but cannot write to or read
from the down chunk or any other chunks in the dbspace of that chunk. You must
take steps to determine why the I/O error occurred, correct the problem, and
restore the dbspace from a backup.

If you take the database server to offline mode when a chunk is marked as down
(D), you can restart the database server, provided that the chunk marked as down
does not contain critical data (logical-log files, the physical log, or the root
dbspace).

Collecting Diagnostic Information

Several ONCONFIG parameters affect the way in which the database server
collects diagnostic information. Because an assertion failure is generally an
indication of an unforeseen problem, notify IBM Informix Technical Support
whenever one occurs. The diagnostic information collected is intended for the use
of IBM Informix technical staff. The contents and use of [Link] files and shared
core are not further documented.

To determine the cause of the problem that triggered the assertion failure, it is
critically important that you not destroy diagnostic information until IBM Informix
Technical Support indicates that you can do so. The [Link] file often contains
information that they need to resolve the problem.

Several ONCONFIG parameters direct the database server to preserve diagnostic

information whenever an assertion failure is detected or whenever the database
server enters into an end sequence:

UNIX Only

v DUMPDIR
v DUMPSHMEM
v DUMPCNT
v DUMPCORE
v DUMPGCORE
End of UNIX Only

For more information about the configuration parameters, see the IBM Informix
Administrator's Reference.

22-6 IBM Informix Dynamic Server Administrator’s Guide

 You decide whether to set these parameters. Diagnostic output can consume a
large amount of disk space. (The exact content depends on the environment
variables set and your operating system.) The elements of the output could include
a copy of shared memory and a core dump.

Tip: A core dump is an image of a process in memory at the time that the assertion
failed. On some systems, core dumps include a copy of shared memory. Core
dumps are useful only if this is the case.

Database server administrators with disk-space constraints might prefer to write a

script that detects the presence of diagnostic output in a specified directory and
sends the output to tape. This approach preserves the diagnostic information and
minimizes the amount of disk space used.

Disabling I/O Errors

Informix divides disabling I/O errors into two general categories: destructive and
nondestructive. A disabling I/O error is destructive when the disk that contains a
database becomes damaged in some way. This type of event threatens the integrity
of data, and the database server marks the chunk and dbspace as down. The
database server prohibits access to the damaged disk until you repair or replace
the disk and perform a physical and logical restore.

A disabling I/O error is nondestructive when the error does not threaten the
integrity of your data. Nondestructive errors occur when someone accidentally
disconnects a cable, you somehow erase the symbolic link that you set up to point
to a chunk, or a disk controller becomes damaged.

Before the database server considers an I/O error to be disabling, the error must
meet two criteria. First, the error must occur when the database server attempts to
perform an operation on a chunk that has at least one of the following
characteristics:
v The chunk has no mirror.
v The primary or mirror companion of the chunk under question is offline.

Second, the error must occur when the database server attempts unsuccessfully to
perform one of the following operations:
v Seek, read, or write on a chunk
v Open a chunk
v Verify that chunk information on the first used page is valid
The database server performs this verification as a sanity check immediately
after it opens a chunk.

You can prevent the database server from marking a dbspace as down while you
investigate disabling I/O errors. If you find that the problem is trivial, such as a
loose cable, you can bring the database server offline and then online again
without restoring the affected dbspace from backup. If you find that the problem is
more serious, such as a damaged disk, you can use onmode -O to mark the
affected dbspace as down and continue processing.

Chapter 22. Consistency Checking 22-7

Monitoring the Database Server for Disabling I/O Errors
The database server notifies you about disabling I/O errors in two ways:
v Message log
v Event alarms

Using the Message Log to Monitor Disabling I/O Errors

The database server sends the following message to the message log when a
disabling I/O error occurs:
Assert Failed: Chunk {chunk-number} is being taken OFFLINE.
Who: Description of user/session/thread running at the time
Result: State of the affected database server entity
Action: What action the database server administrator should take
See Also: DUMPDIR/[Link] containing more diagnostics

The result and action depend on the current setting of ONDBSPACEDOWN, as

described in the following table.

ONDBSPACEDOWN
Setting Result Action
0 Dbspace {space_name} is Restore dbspace {space_name}.
disabled.
Blobspace {space_name} is Restore blobspace {space_name}.
disabled.
1 The database server must stop. Shut down and restart the
database server.
2 The database server blocks at Use onmode -k to shut down, or
next checkpoint. use onmode -O to override.

For more information about interpreting messages that the database server sends
to the message log, see the chapter about message-log messages in the IBM
Informix Administrator's Reference.

Using Event Alarms to Monitor Disabling I/O Errors

When a dbspace incurs a disabling I/O error, the database server passes the
following values as parameters to your event-alarm executable file.
Parameter Value
Severity 4 (Emergency)
Class 5
Class message Dbspace is disabled: ’dbspace-name’
Specific message Chunk {chunk-number} is being taken OFFLINE.

If you want the database server to use event alarms to notify you about disabling
I/O errors, write a script that the database server executes when it detects a
disabling I/O error. For information about how to set up this executable file that
you write, see the appendix on event alarms and the chapter on configuration
parameters in the IBM Informix Administrator's Reference.

22-8 IBM Informix Dynamic Server Administrator’s Guide

Using No Bad-Sector Mapping
Dynamic Server relies on the operating system of your host computer for
bad-sector mapping. The database server learns of a bad sector or a bad track
when it receives a failure return code from a system call. When this situation
occurs, the database server retries the access several times to ensure that the
condition is not spurious. If the condition is confirmed, the database server marks
as down the chunk where the read or write was attempted.

The database server cannot take any action to identify the bad cylinder, track, or
sector location because the only information available is the byte displacement
within the chunk where the I/O operation was attempted.

If the database server detects an I/O error on a chunk that is not mirrored, it
marks the chunk as down. If the down chunk contains logical-log files, the
physical log, or the root dbspace, the database server immediately initiates a stop
action. Otherwise, the database server can continue to operate, but applications
cannot access the down chunk until its dbspace is restored.

Chapter 22. Consistency Checking 22-9

22-10 IBM Informix Dynamic Server Administrator’s Guide
Part 5. Distributed Data

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
 Chapter 23. Multiphase Commit Protocols
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Transaction Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Using the TP/XA Library With a Transaction Manager . . . . . . . . . . . . . . . . . . . 23-2
Using Microsoft Transaction Server (MTS/XA) . . . . . . . . . . . . . . . . . . . . . . 23-2
3 Using Dynamic Server Transaction Support for XA-Compliant, External Data Sources . . . . . . . . . 23-3
Using Loosely-Coupled and Tightly-Coupled Modes . . . . . . . . . . . . . . . . . . . . 23-4
Two-Phase Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
When the Two-Phase Commit Protocol Is Used . . . . . . . . . . . . . . . . . . . . . . 23-5
Two-Phase Commit Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Phases of the Two-Phase Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . 23-6
Precommit Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Postdecision Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7
How the Two-Phase Commit Protocol Handles Failures . . . . . . . . . . . . . . . . . . . 23-7
Types of Failures That Automatic Recovery Handles . . . . . . . . . . . . . . . . . . . 23-7
Administrator’s Role in Automatic Recovery . . . . . . . . . . . . . . . . . . . . . 23-7
Automatic-Recovery Mechanisms for Coordinator Failure . . . . . . . . . . . . . . . . . 23-7
Automatic-Recovery Mechanisms for Participant Failure . . . . . . . . . . . . . . . . . . 23-7
Presumed-End Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Independent Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-8
Situations That Initiate Independent Action . . . . . . . . . . . . . . . . . . . . . . . 23-8
Possible Results of Independent Action . . . . . . . . . . . . . . . . . . . . . . . . 23-9
Independent Actions That Allow Transactions to Complete Successfully . . . . . . . . . . . . 23-9
Independent Actions That Result in an Error Condition . . . . . . . . . . . . . . . . . . 23-9
Independent Actions That Result in Heuristic Decisions . . . . . . . . . . . . . . . . . 23-10
The Heuristic Rollback Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Conditions That Result in a Heuristic Rollback . . . . . . . . . . . . . . . . . . . . 23-10
Results of a Heuristic Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
The Heuristic End-Transaction Scenario . . . . . . . . . . . . . . . . . . . . . . . . 23-12
When to Perform a Heuristic End Transaction . . . . . . . . . . . . . . . . . . . . . 23-13
How to Use onmode -Z . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-13
Action When the Transaction Is Ended Heuristically . . . . . . . . . . . . . . . . . . . 23-14
Monitoring a Global Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14
Two-Phase Commit Protocol Errors . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15
Two-Phase Commit and Logical-Log Records . . . . . . . . . . . . . . . . . . . . . . . 23-15
Logical-Log Records When the Transaction Commits . . . . . . . . . . . . . . . . . . . 23-15
Logical-Log Records Written During a Heuristic Rollback . . . . . . . . . . . . . . . . . . 23-17
Logical-Log Records Written After a Heuristic End Transaction . . . . . . . . . . . . . . . . 23-18
Configuration Parameters Used in Two-Phase Commits . . . . . . . . . . . . . . . . . . . 23-19
Function of the DEADLOCK_TIMEOUT Parameter . . . . . . . . . . . . . . . . . . . . 23-20
Function of the TXTIMEOUT Parameter . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Heterogeneous Commit Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Gateways That Can Participate in a Heterogeneous Commit Transaction . . . . . . . . . . . . . 23-21
Enabling and Disabling of Heterogeneous Commit . . . . . . . . . . . . . . . . . . . . 23-21
How Heterogeneous Commit Works . . . . . . . . . . . . . . . . . . . . . . . . . 23-22
Precommit Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-22
Gateway Commit Phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-22
Heterogeneous Commit Optimization . . . . . . . . . . . . . . . . . . . . . . . 23-23
Implications of a Failed Heterogeneous Commit . . . . . . . . . . . . . . . . . . . . . 23-23
Database Server Coordinator Failure . . . . . . . . . . . . . . . . . . . . . . . . 23-23
Participant Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-24

© Copyright IBM Corp. 1996, 2005 23-1

 Interpretation of Heterogeneous Commit Error Messages . . . . . . . . . . . . . . . . . 23-24

In This Chapter
A two-phase commit protocol ensures that transactions are uniformly committed or
rolled back across multiple database servers. You can use Informix database servers
with IBM Informix Enterprise Gateway products or transaction managers to
manipulate data in non-Informix databases. Distributed queries across Informix
database servers support two-phase commit.

The heterogeneous commit protocol ensures that updates to one or more Informix
databases and one non-Informix database in a single transaction are uniformly
committed or rolled back.

This chapter contains information on the use of the two-phase commit protocol.
For information on recovering manually from a failed two-phase commit
transaction, see Chapter 24, “Recovering Manually from Failed Two-Phase
Commit,” on page 24-1.

3 This chapter also contains information on using transaction support for

3 XA-compliant, external data sources, which can participate in two-phase commit
3 transactions. See “Using Dynamic Server Transaction Support for XA-Compliant,
3 External Data Sources” on page 23-3.

Transaction Managers
Transaction managers support two-phase commit and roll back. For example, if
your database is Informix, your accounting system is Oracle, and your remittance
system is Sybase, you can use a transaction manager to communicate between the
different databases. You also can use transaction managers to ensure data
consistency between Informix or non-Informix databases by using distributed
transactions instead of Enterprise Replication or High-Availability Data Replication.

Using the TP/XA Library With a Transaction Manager

A global transaction is a distributed query where more than one database server is
involved in the query. A global transaction environment has the following parts:
v The client application
v The resource manager (Informix database server)
v The transaction manager (third-party software)

TP/XA is a library of functions that lets the database server act as a resource
manager in the X/Open DTP environment. Install the TP/XA library as part of
IBM Informix ESQL/C to enable communication between a third-party transaction
manager and the database server. The X/Open environment supports large-scale,
high-performance OLTP applications. For more information, see the IBM Informix
TP/XA Programmer's Manual.

Use TP/XA when your database has the following characteristics:

v Data is distributed across multivendor databases
v Transactions include Informix and non-Informix data

Using Microsoft Transaction Server (MTS/XA)

The database server supports the Microsoft Transaction Server (MTS/XA) as a
transaction manager in the XA environment. To use MTS/XA, install IBM Informix

23-2 IBM Informix Dynamic Server Administrator’s Guide

 Client Software Developer's Kit, the latest version of IBM Informix ODBC Driver,
and MTS/XA. MTS/XA works on Windows. For more information, contact IBM
Informix Technical Support, and see the IBM Informix Client Products Installation
Guide and the MTS/XA documentation.

3 Using Dynamic Server Transaction Support for XA-Compliant,

3 External Data Sources
3 The Dynamic Server Transaction Manager, which is an integral part of Dynamic
3 Server, not a separate module, recognizes XA-compliant, external data sources.
3 These data sources can participate in two-phase commit transactions.

3 The transaction manager invokes support routines for each XA-compliant, external
3 data source that participates in a distributed transaction at a particular
3 transactional event, such as prepare, commit, or rollback. This interaction conforms
3 to X/Open XA interface standards.

3 Transaction support for XA-compliant, external data sources, which are also called
3 resource managers, enables you to:
3 v Create XA-compliant, external data source types and instances of XA-compliant,
3 external data sources.
3 v Create or modify a user-defined routine (UDR), virtual table interface, or virtual
3 index interface to enable XA-compliant data sources to provide data access
3 mechanisms for external data from XA-compliant data sources.
3 The MQ DataBlade Module is an example of a set of UDRs that provide this
3 type of external data access.
3 v Register XA-compliant, external data sources with Dynamic Server.
3 v Unregister XA-compliant, external data sources.
3 v Use multiple XA-compliant, external data sources within the same global
3 transaction.

3 The transaction coordination with an XA-compliant, external data source is

3 supported only in Informix logged databases and ANSI-compliant databases, since
3 these databases support transactions. Transaction coordination with an
3 XA-compliant, external data source is not supported in non-logged databases.

3 You can use the following DDL statements, which are extensions to SQL statements
3 to manage XA data source types and data sources:
3
3 Statement Description
3 CREATE XADATASOURCE TYPE Creates a type of XA-compliant, external data source
3 CREATE XADATASOURCE Creates an instance of an XA-compliant, external
3 data source
3 DROP XADATASOURCE Deletes an instance of an XA-compliant, external
3 data source
3 DROP XADATASOURCE TYPE Deletes a type of XA-compliant, external data source
3

3 For more information on these statements, see the IBM Informix Guide to SQL:
3 Syntax.

3 The interaction between Dynamic Server and an XA-compliant, external data

3 source occurs through a set of user-defined XA-support routines, such as xa_open,
3 xa_end, xa_commit, and xa_prepare. You create these support routines before

Chapter 23. Multiphase Commit Protocols 23-3

3 using the CREATE XADATASOURCE TYPE statement. For more information, see
3 the IBM Informix DataBlade API Programmer's Guide.

3 After you create an external XA-compliant data source, you can register the data
3 source to a current transaction and you can unregister the data source using the
3 mi_xa_register_xadatasource() or ax_reg() and mi_xa_unregister_xadatasource() or
3 ax_unreg() functions. In a distributed environment, you must register a data source
3 at the local, coordinator server. Registration is transient, lasting only for the
3 duration of the transaction. For more information on using these functions, see the
3 IBM Informix DataBlade API Function Reference and the IBM Informix DataBlade API
3 Programmer's Guide.

3 Use the following onstat options to display information about transactions

3 involving XA-compliant data sources:
33 What XA-Compliant Data Source Information
3 onstat Option This Command Displays
3 onstat -x Displays information on XA participants in a transaction.
3 onstat -G Displays information on XA participants in a global transaction.
3 onstat -g ses session id Displays session information, including information about XA
3 data sources participating in a transaction.
3

3 The IBM Informix MQ DataBlade provides external data access mechanisms for XA
3 data sources. For information on this DataBlade Module, see the IBM Informix
3 Built-In DataBlade Modules User's Guide.

Using Loosely-Coupled and Tightly-Coupled Modes

The database server supports XA global transactions in loosely-coupled and
tightly-coupled modes:
v Loosely coupled mode means that the different database servers coordinate
transactions, but do not share resources. The records from all branches of the
transactions display as separate transactions in the logical log.
v Tightly coupled mode means that the different database servers coordinate
transactions and share resources such as locking and logging. The records from
all branches of the transactions display as a single transaction in the logical log.

The Tuxedo Transaction Manager, provided by BEA systems, supports

loosely-coupled mode. Tuxedo operates on both UNIX and Windows.

Windows Only

The MTS/XA Transaction Manager, which operates only on Windows, supports the
tightly-coupled mode. MTS tightly-coupled transaction support on the database
server includes:
v Support for application programs with two tiers (a business-logic layer and a
data-access layer).
v Connection pooling and session pooling.

MTS tightly-coupled transaction support does not affect existing

loosely-coupled-transaction support. The same database server can use both
loosely-coupled and tightly-coupled transaction support at the same time.

MTS tightly-coupled transaction support has the following restrictions:

23-4 IBM Informix Dynamic Server Administrator’s Guide

 v Temporary tables are limited to one transaction branch. Different transaction
branches within one global transaction cannot share a temporary table.
v Different transaction branches within one global transaction cannot share
cursors.
v Different transaction branches within one global transaction cannot share an
isolation level or lock-wait mode. The isolation level and lock-wait mode of each
transaction branch must be set individually or set to the default level. If you
want the same isolation level for all transaction branches, you must use SQL to
specify this information for each transaction branch.

End of Windows Only

For a complete list of supported transaction managers, contact your sales

representative.

Two-Phase Commit Protocol

The two-phase commit protocol provides an automatic recovery mechanism in case
a system or media failure occurs during execution of the transaction. The
two-phase commit protocol ensures that all participating database servers receive
and implement the same action (either to commit or to roll back a transaction),
regardless of local or network failure.

If any database server is unable to commit its portion of the transaction, all
database servers participating in the transaction must be prevented from
committing their work.

When the Two-Phase Commit Protocol Is Used

A database server automatically uses the two-phase commit protocol for any
transaction that modifies data on multiple database servers.

For example, suppose three database servers that have the names australia, italy,
and france, are connected, as shown in Figure 23-1.

italy

france australia

Figure 23-1. Connected Database Servers

If you execute the commands shown in Figure 23-2, the result is one update and
two inserts at three different database servers.

CONNECT TO stores_demo@italy
BEGIN WORK
UPDATE stores_demo:manufact SET manu_code = ’SHM’ WHERE manu_name = ’Shimara’
INSERT INTO stores_demo@france:manufact VALUES (’SHM’, ’Shimara’, ’30’)
INSERT INTO stores_demo@australia:manufact VALUES (’SHM’, ’Shimara’, ’30’)
COMMIT WORK

Figure 23-2. Example of a Distributed Transaction

Chapter 23. Multiphase Commit Protocols 23-5

 Two-Phase Commit Concepts
Every global transaction has a coordinator and one or more participants, defined as
follows:
v The coordinator directs the resolution of the global transaction. It decides whether
the global transaction should be committed or stopped.
The two-phase commit protocol always assigns the role of coordinator to the
current database server. The role of coordinator cannot change during a single
transaction. In the sample transaction in Figure 23-2 on page 23-5, the
coordinator is italy. If you change the first line in this example to the following
statement, the two-phase commit protocol assigns the role of coordinator to
france:
CONNECT TO stores_demo@france
Use the onstat -x option to display the coordinator for a distributed transaction.
For more information, see “Monitoring a Global Transaction” on page 23-14.
v Each participant directs the execution of one transaction branch, which is the part
of the global transaction involving a single local database. A global transaction
includes several transaction branches when:
– An application uses multiple processes to work for a global transaction
– Multiple remote applications work for the same global transaction
In Figure 23-1 on page 23-5, the participants are france and australia. The
coordinator database server, italy, also functions as a participant because it is
also doing an update.

The two-phase commit protocol relies on two kinds of communication, messages

and logical-log records:
v Messages pass between the coordinator and each participant. Messages from the
coordinator include a transaction identification number and instructions (such as
prepare to commit, commit, or roll back). Messages from each participant
include the transaction status and reports of action taken (such as can commit or
cannot commit, committed, or rolled back).
v Logical-log records of the transaction are kept on disk or tape to ensure data
integrity and consistency, even if a failure occurs at a participating database
server (participant or coordinator).
For more details, refer to “Two-Phase Commit and Logical-Log Records” on
page 23-15.

Phases of the Two-Phase Commit Protocol

In a two-phase commit transaction, the coordinator sends all the data modification
instructions (for example, inserts) to all the participants. Then, the coordinator
starts the two-phase commit protocol. The two-phase commit protocol has two
parts, the precommit phase and the postdecision phase.

Precommit Phase
During the precommit phase, the coordinator and participants perform the
following dialog:
1. Coordinator. The coordinator directs each participant database server to
prepare to commit the transaction.
2. Participants. Every participant notifies the coordinator whether it can commit
its transaction branch.
3. Coordinator. The coordinator, based on the response from each participant,
decides whether to commit or roll back the transaction. It decides to commit
only if all participants indicate that they can commit their transaction branches.

23-6 IBM Informix Dynamic Server Administrator’s Guide

 If any participant indicates that it is not ready to commit its transaction branch
(or if it does not respond), the coordinator decides to end the global
transaction.

Postdecision Phase
During the postdecision phase, the coordinator and participants perform the
following dialog:
1. Coordinator: The coordinator writes the commit record or rollback record to
the coordinator’s logical log and then directs each participant database server
to either commit or roll back the transaction.
2. Participants: If the coordinator issued a commit message, the participants
commit the transaction by writing the commit record to the logical log and then
sending a message to the coordinator acknowledging that the transaction was
committed. If the coordinator issued a rollback message, the participants roll
back the transaction but do not send an acknowledgment to the coordinator.
3. Coordinator: If the coordinator issued a message to commit the transaction, it
waits to receive acknowledgment from each participant before it ends the
global transaction. If the coordinator issued a message to roll back the
transaction, it does not wait for acknowledgments from the participants.

How the Two-Phase Commit Protocol Handles Failures

The two-phase commit protocol is designed to handle system and media failures in
such a way that data integrity is preserved across all the participating database
servers. The two-phase commit protocol performs an automatic recovery if a failure
occurs.

Types of Failures That Automatic Recovery Handles

The following events can cause the coordinating thread or the participant thread to
terminate or hang, thereby requiring automatic recovery:
v System failure of the coordinator
v System failure of a participant
v Network failure
v Termination of the coordinating thread by the administrator
v Termination of the participant thread by the administrator

Administrator’s Role in Automatic Recovery

The only role of the administrator in automatic recovery is to bring the coordinator
or participant (or both) back online after a system or network failure.

Important: A slow network cannot, and should not, trigger automatic recovery.
None of the recovery mechanisms described here go into effect unless a
coordinator system fails, a network fails, or the administrator
terminates the coordinating thread.

Automatic-Recovery Mechanisms for Coordinator Failure

If the coordinating thread fails, each participant database server must decide
whether to initiate automatic recovery before it commits or rolls back the
transaction or after it rolls back a transaction. This responsibility is part of the
presumed-end optimization. (See “Presumed-End Optimization” on page 23-8.)

Automatic-Recovery Mechanisms for Participant Failure

Participant recovery occurs whenever a participant thread precommits an item of
work that is terminated before the two-phase commit protocol can be completed.

Chapter 23. Multiphase Commit Protocols 23-7

 The goal of participant recovery is to complete the two-phase commit protocol
according to the decision reached by the coordinator.

Participant recovery is driven by either the coordinator or the participant,

depending on whether the coordinator decided to commit or to roll back the global
transaction.

Important: To support automatic recovery after a subordinate server is shut down

or restarted while a cross-server transaction is open, the sqlhosts file
should include an entry for every database server from which
distributed operations might be initiated. During automatic recovery,
the name of the coordinator is recovered from the logical logs, and the
subordinate server reconnects with the coordinator to complete the
transaction. Because the coordinator always identifies itself to the
participants using the name that is in the DBSERVERNAME
configuration parameter in its own ONCONFIG file, the
DBSERVERNAME of the coordinator should be a TCP/IP connection
name known to the participants. The subordinate server should be able
to connect to the coordinator using the DBSERVERNAME of the
coordinator.

Presumed-End Optimization
Presumed-end optimization is a term that describes how the two-phase commit
protocol handles the rollback of a transaction.

Rollback is handled in the following manner. When the coordinator determines

that the transaction must be rolled back, it sends a message to all the participants
to roll back their piece of work. The coordinator does not wait for an
acknowledgment of this message, but proceeds to close the transaction and remove
it from shared memory. If a participant tries to determine the status of this
transaction—that is, find out whether the transaction was committed or rolled back
(during participant recovery, for example)—it does not find any transaction status
in shared memory. The participant must interpret this as meaning that the
transaction was rolled back.

Independent Actions
An independent action in the context of two-phase commit is an action that occurs
independently of the two-phase commit protocol. Independent actions might or
might not be in opposition to the actions that the two-phase commit protocol
specifies. If the action is in opposition to the two-phase commit protocol, the action
results in an error or a heuristic decision. Heuristic decisions can result in an
inconsistent database and require manual two-phase commit recovery. Manual
recovery is an extremely complicated administrative procedure that you should try
to avoid. (For a discussion of the manual-recovery process, see Chapter 24,
“Recovering Manually from Failed Two-Phase Commit,” on page 24-1.)

Situations That Initiate Independent Action

Independent action during a two-phase commit protocol is rare, but it can occur in
the following situations:
v The participant’s piece of work develops into a long-transaction error and is
rolled back.
v An administrator stops a participant thread during the postdecision phase of the
protocol with onmode -z.

23-8 IBM Informix Dynamic Server Administrator’s Guide

 v An administrator ends a participant transaction (piece of work) during the
postdecision phase of the protocol with onmode -Z.
v An administrator ends a global transaction at the coordinator database server
with onmode -z or onmode -Z after the coordinator issued a commit decision
and became aware of a participant failure. This action always results in an error,
specifically error -716.

Possible Results of Independent Action

As mentioned earlier, not all independent actions are in opposition to the
two-phase commit protocol. Independent actions can yield the following three
possible results:
v Successful completion of the two-phase commit protocol
v An error condition
v A heuristic decision

If the action is not in opposition to the two-phase protocol, the transaction should
either commit or roll back normally. If the action ends the global transaction
prematurely, an error condition results. Ending the global transaction at the
coordinator is not considered a heuristic decision. If the action is in opposition to
the two-phase commit protocol, a heuristic decision results. All these situations are
discussed in the sections that follow.

Independent Actions That Allow Transactions to Complete

Successfully
Independent actions are not necessarily in opposition to the two-phase commit
protocol. For example, if a piece of work at a participant database server is rolled
back because it developed into a long transaction, and the coordinator issues a
decision to roll back the global transaction, the database remains consistent.

Independent Actions That Result in an Error Condition

If you, as administrator at the coordinator database server, execute either onmode
-z (stop the coordinator thread) or onmode -Z (stop the global transaction) after
the coordinator issues its final commit decision, you are removing all knowledge of
the transaction from shared memory at the coordinator database server.

This action is not considered a heuristic decision because it does not interfere with
the two-phase protocol; it is either acceptable, or it interferes with participant
recovery and causes an error.

The action is acceptable any time that all participants are able to commit the
transaction without difficulty. In this case, your action to end the transaction
forcibly is superfluous. The indication that you executed onmode -Z reaches the
coordinator only when the coordinator is preparing to terminate the transaction.

In practice, however, you would probably consider executing onmode -z or

onmode -Z at the coordinator database server only if you were attempting to
hasten the conclusion of a global transaction that has remained open for an
unusually long period. In this scenario, the source of the problem is probably a
failure at some participant database server. The coordinator has not received
acknowledgment that the participant committed its piece of work, and the
coordinator is attempting to establish communication with the participant to
investigate.

If you execute either onmode -z or onmode -Z while the coordinator is actively

trying to reestablish communication, the coordinating thread obeys your

Chapter 23. Multiphase Commit Protocols 23-9

 instruction to die, but not before it writes error -716 into the database server
message log. The action is considered an error because the two-phase commit
protocol was forcibly broken, preventing the coordinator from determining
whether the database is consistent.

Stopping a global transaction at a coordinator database server is not considered a

heuristic decision, but it can result in an inconsistent database. For example, if the
participant eventually comes back online and does not find the global transaction
in the coordinator shared memory, it rolls back its piece of work, thereby causing a
database inconsistency.

Independent Actions That Result in Heuristic Decisions

Some independent actions can develop into heuristic decisions when both of the
following conditions are true:
v The participant database server already sent a can commit message to the
coordinator and then rolls back.
v The coordinator’s decision is to commit the transaction.

When both conditions are true, the net result is a global transaction that is
inconsistently implemented (committed by one or more database servers and rolled
back by another). The database becomes inconsistent.

The following two heuristic decisions are possible:

v Heuristic rollback (described in “The Heuristic Rollback Scenario” on page
23-10)
v Heuristic end transaction (described in “The Heuristic End-Transaction Scenario”
on page 23-12)

After a heuristic rollback or end transaction occurs, you might have to perform
manual recovery, a complex and time-consuming process. You need to understand
heuristic decisions fully in order to avoid them. Always be wary of executing
onmode -z or onmode -Z within the context of two-phase commit.

The Heuristic Rollback Scenario

In a heuristic rollback, either the database server or the administrator rolls back a
piece of work that has already sent a can commit message.

Conditions That Result in a Heuristic Rollback

The following two conditions can cause a heuristic rollback:
v The logical log fills to the point defined by the LTXEHWM configuration
parameter. (See the chapter on configuration parameters in the IBM Informix
Administrator's Reference.) The source of the long-transaction condition is a piece
of work being performed on behalf of a global transaction.
v An administrator executes onmode -z session_id to stop a database server
thread that is executing a piece of work being performed on behalf of a global
transaction.

In either case, if the piece of work has already sent a can commit message to its
coordinator, the action is considered a heuristic decision.

Condition 1: Logical Log Fills to a High-Watermark: Under two-phase commit, a

participant database server that is waiting for instructions from the coordinator is
blocked from completing its transaction. Because the transaction remains open, the

23-10 IBM Informix Dynamic Server Administrator’s Guide

logical-log files that contain records associated with this transaction cannot be
freed. The result is that the logical log continues to fill because of the activity of
concurrent users.

If the logical log fills to the value of the long-transaction high-watermark

(LTXHWM) while the participant is waiting, the database server directs all
database server threads that own long transactions to begin rolling them back. If a
piece of work that is precommitted is the offending long transaction, the database
server has initiated a heuristic rollback. That is, this database server is rolling back
a precommitted piece of work without the instruction or knowledge of the
coordinator.

Under two-phase commit, the logical-log files that contain records associated with
the piece of work are considered open until an ENDTRANS logical-log record is
written. This type of transaction differs from a transaction involving a single
database server where a rollback actually closes the transaction.

The logical log might continue to fill until the exclusive high-watermark is reached
(LTXEHWM). If this happens, all user threads are suspended except those that are
currently rolling back or currently committing. In the two-phase commit scenario,
the open transaction prevents you from backing up the logical-log files and freeing
space in the logical log. Under these specific circumstances, the logical log can fill
completely. If this happens, the participant database server shuts down, and you
must perform a data restore.

Condition 2: System Administrator Executes onmode -z: You, as administrator,

can decide to initiate a heuristic rollback of a precommitted piece of work by
executing onmode -z. You might make this decision because you want to free the
resources that are held by the piece of work. (If you stop the participant thread by
executing onmode -z, you free all locks and shared-memory resources that are held
by the participant thread even though you do not end the transaction.)

Results of a Heuristic Rollback

This section describes what happens at both the coordinator and participant when
a heuristic rollback occurs and how this process can result in an inconsistent
database:
1. At the participant database server where the rollback occurred, a record is
placed in the database server logical log (type HEURTX). Locks and resources
held by the transaction are freed. The participant thread writes the following
message in the database server message log, indicating that a long-transaction
condition and rollback occurred:
Transaction Completed Abnormally (rollback):
tx=address flags=0xnn
2. The coordinator issues postdecision phase instructions to commit the
transaction.
The participant thread at the database server where the heuristic rollback
occurred returns error message -699 to the coordinator as follows:
-699 Transaction heuristically rolled back.
This error message is not returned to the application at this point; it is an
internal notification to the coordinator. The coordinator waits until all
participants respond to the commit instruction. The coordinator does not
determine database consistency until all participants report.
3. The next steps depend on the actions that occur at the other participants. Two
possible situations are possible.

Chapter 23. Multiphase Commit Protocols 23-11

 Situation 1: Coordinator Issues a Commit and All Participants Report Heuristic
Rollbacks: The coordinator gathers all responses from participants. If every
participant reports a heuristic rollback, the following events occur as a
consequence:
1. The coordinator writes the following message to its own database- server
message log:
Transaction heuristically rolled back.
2. The coordinator sends a message to all participants to end the transaction.
3. Each participant writes an ENDTRANS record in its logical-log buffer. (The
transaction entry is removed from the transaction table.)
4. The coordinator returns error -699 to the application, as follows:
-699 Transaction heuristically rolled back.
5. In this situation, all databases remain consistent.

Situation 2: Coordinator Issued a Commit; One Participant Commits and One

Reports a Heuristic Rollback: The coordinator gathers all responses from
participants. If at least one participant reports a heuristic rollback and at least one
reports an acknowledgment of a commit, the result is referred to as a
mixed-transaction result. The following events occur as a consequence:
1. The coordinator writes the following message to its own database server
message log:
Mixed transaction result. (pid=nn user=userid)
The pid value is the user-process identification number of the coordinator
process. The user value is the user ID associated with the coordinator process.
Associated with this message are additional messages that list each of the
participant database servers that reported a heuristic rollback. The additional
messages take the following form:
Participant database server dbservername heuristically rolled back.
2. The coordinator sends a message to each participant that heuristically rolled
back its piece of work, directing each one to end the transaction.
3. Each participant writes an ENDTRANS message in its logical-log buffer. (The
transaction entry is removed from the transaction table.)
4. The coordinator writes an ENDTRANS message in its logical-log buffer. (The
transaction entry is removed from the shared-memory transaction table.)
5. The coordinator returns error -698 to the application, as follows:
-698 Inconsistent transaction. Number and names of servers rolled back.
6. Associated with this error message is the list of participant database servers
that reported a heuristic rollback. If a large number of database servers rolled
back the transaction, this list could be truncated. The complete list is always
included in the message log for the coordinator database server.

In this situation, examine the logical log at each participant database server site
and determine whether your database system is consistent. (See “Determining If a
Transaction Was Implemented Inconsistently” on page 24-1.)

The Heuristic End-Transaction Scenario

A heuristic end transaction is an independent action taken by the administrator to
roll back a piece of work and remove all information about the transaction from
the transaction table. The heuristic end-transaction process is initiated when the
administrator executes the onmode -Z address command.

23-12 IBM Informix Dynamic Server Administrator’s Guide

Whenever you initiate a heuristic end transaction by executing onmode -Z, you
remove critical information required by the database server to support the
two-phase commit protocol and its automatic-recovery features. If you execute
onmode -Z, it becomes your responsibility to determine whether your networked
database system is consistent.

When to Perform a Heuristic End Transaction

You should execute the onmode -Z option to initiate a heuristic end transaction in
only one, rare, situation. This situation occurs when a piece of work that has been
heuristically rolled back remains open, preventing your logical-log files from
becoming free. As a result, the logical log is dangerously close to full.

In general, the coordinator issues its commit-or-rollback decision within a

reasonable period of time. However, if the coordinator fails and does not return
online to end a transaction that was heuristically rolled back at your participant
database server, you might face a serious problem.

The problem scenario begins in this way:

1. The participant thread that is executing a piece of work on behalf of a global
transaction has sent a can commit response to the coordinator.
2. The piece of work waits for instructions from the coordinator.
3. While the piece of work is waiting, the logical log fills past the long-transaction
high-watermark.
4. The piece of work that is waiting for instructions is the source of the long
transaction. The participant database server directs the executing thread to roll
back the piece of work. This action is a heuristic rollback.
5. The participant continues to wait for the coordinator to direct it to end the
transaction. The transaction remains open. The logical log continues to fill.

If the coordinator contacts the participant and directs it to end the transaction in a
reasonable period of time, no problem develops. The serious problem arises if the
heuristic rollback occurs at a participant database server and subsequently the
coordinator fails, preventing the coordinator from directing the participant to end
the transaction.

As a consequence, the transaction remains open. The open transaction prevents

you from backing up logical-log files and freeing space in the logical log. As the
logical log continues to fill, it might reach the point specified by the
exclusive-access, long-transaction high-watermark (LTXEHWM). If this point is
reached, normal processing is suspended. At some point after the high-watermark
is reached, you must decide if the open transaction is endangering your logical log.
The danger is that if the logical log fills completely, the database server shuts
down, and you must perform a data restore.

You must decide whether to end the transaction and protect your system against
the possibility of filling the logical log, despite all the problems associated with
executing onmode -Z, or to wait and see if communication with the coordinator
can be reestablished in time to end the transaction before the logical log fills.

How to Use onmode -Z

The onmode -Z address command is intended for use only if communication
between the coordinator and the participant is broken. To ensure that
communication is really broken, the onmode -Z command does not execute unless

Chapter 23. Multiphase Commit Protocols 23-13

 the thread that was executing the piece of work has been dead for the amount of
time specified by TXTIMEOUT. For more information on this option, see the IBM
Informix Administrator's Reference.

The address parameter is obtained from onstat -x output. For more information on
the onstat -x option, see the IBM Informix Administrator's Reference.

Action When the Transaction Is Ended Heuristically

When you execute onmode -Z, you direct the onmode utility to remove the
participant transaction entry, which is located at the specified address, from the
transaction table.

Two records are written in the logical log to document the action. The records are
type ROLLBACK and ENDTRANS, or if the transaction was already heuristically
rolled back, ENDTRANS only. The following message is written to the participant
database server message log:

(time_stamp) Transaction Completed Abnormally (endtx): tx=address

flags:0xnn user username tty ttyid

The coordinator receives an error message from the participant where the onmode
-Z occurred, in response to its COMMIT instruction. The coordinator queries the
participant database server, which no longer has information about the transaction.
The lack of a transaction-table entry at the participant database server indicates
that the transaction committed. The coordinator assumes that the acknowledgment
message was sent from the participant, but somehow it was not received. Because
the coordinator does not know that this participant’s piece of work did not commit,
it does not generate messages indicating that the global transaction was
inconsistently implemented. Only the administrator who executed the onmode -Z
command is aware of the inconsistent implementation.

Monitoring a Global Transaction

Use the onstat -x command to track open transactions and determine whether they
have been heuristically rolled back.

For example, in the output, an H flag in the flags field identifies a heuristic
rollback, the G flag identifies a global transaction, the L flag indicates
loosely-coupled mode, and the T flag indicates tightly-coupled mode.

The curlog and logposit fields provide the exact position of a logical-log record. If
a transaction is not rolling back, curlog and logposit describe the position of the
most recently written log record. When a transaction is rolling back, these fields
describe the position of the most recently “undone” log record. As the transaction
rolls back, the curlog and logposit values decrease. In a long transaction, the rate
at which the logposit and beginlg values converge can help you estimate how
much longer the rollback is going to take.

For more information on and an example of onstat -x output, see the IBM Informix
Administrator's Reference.

You also can use the onstat -u and onstat -k commands to track transactions and
the locks that they hold. For details, see the monitoring transactions section in your
IBM Informix Performance Guide. For a description of the fields that onstat -x
displays, see the IBM Informix Administrator's Reference.

23-14 IBM Informix Dynamic Server Administrator’s Guide

Two-Phase Commit Protocol Errors
The following two-phase commit protocol errors require special attention from the
administrator.
Error Number Description
-698 If you receive error -698, a heuristic rollback has occurred and has
caused an inconsistently implemented transaction. The
circumstances leading up to this event are described in “Results of
a Heuristic Rollback” on page 23-11. For an explanation of how the
inconsistent transaction developed and to learn the options
available to you, refer to this discussion.
-699 If you receive error -699, a heuristic rollback has occurred. The
circumstances leading up to this event are described in “Results of
a Heuristic Rollback” on page 23-11. For an explanation of how the
inconsistent transaction developed, refer to this discussion.
-716 If you receive error -716, the coordinating thread has been
terminated by administrator action after it issued its final decision.
This scenario is described under “Independent Actions That Result
in an Error Condition” on page 23-9.

Two-Phase Commit and Logical-Log Records

The database server uses logical-log records to implement the two-phase commit
protocol. You can use these logical-log records to detect heuristic decisions and, if
necessary, to help you perform a manual recovery. (See Chapter 24, “Recovering
Manually from Failed Two-Phase Commit,” on page 24-1.)

The following logical-log records are involved in distributed transactions:

v BEGPREP
v PREPARE
v TABLOCKS
v HEURTX
v ENDTRANS

For information about these logical-log records, see the chapter on interpreting the
logical log in the IBM Informix Administrator's Reference.

This section examines the sequence of logical-log records that are written during
the following database server scenarios:
v A transaction is committed.
v A piece of work is heuristically rolled back.
v A piece of work is heuristically ended.

Logical-Log Records When the Transaction Commits

Figure 23-3 illustrates the writing sequence of the logical-log records during a
successful two-phase commit protocol that results in a committed transaction.

Chapter 23. Multiphase Commit Protocols 23-15

 Start protocol

Coordinator:
C Writes log record: BEGPREP.
Sends message: precommit.

All participants:
P1 P2 P3 Write log record: TABLOCKS.
Write and flush log record: PREPARE.
Send message: can commit.

Coordinator:
C Writes log record: COMMIT.
Flushes logical-log buffer.
Sends message: commit

All participants:
P1 P2 P3 Writes log record: COMMIT.
Flushes logical-log buffer.
Send message: committed.

Coordinator:
C Writes log record: ENDTRANS.

End protocol

Figure 23-3. Logical-Log Records Written During a Committed Transaction

Some of the logical-log records must be flushed from the logical-log buffer
immediately; for others, flushing is not critical.

The coordinator’s commit-work record (COMMIT record) contains all information

needed to initiate the two-phase commit protocol. It also serves as the starting
point for automatic recovery in the event of a failure on the coordinator’s host
computer. Because this record is critical to recovery, it is not allowed to remain in
the logical-log buffer. The coordinator must immediately flush the COMMIT
logical-log record.

The participants in Figure 23-3 on page 23-16 must immediately flush both the
PREPARE and the COMMIT logical-log records. Flushing the PREPARE record
ensures that, if the participant’s host computer fails, fast recovery is able to
determine that this participant is part of a global transaction. As part of recovery,
the participant might query the coordinator to learn the final disposition of this
transaction.

Flushing the participant’s COMMIT record ensures that, if the participant’s host
computer fails, the participant has a record of what action it took regarding the
transaction. To understand why this information is crucial, consider the situation in
which a participant crashes after the PREPARE record is written but before the
COMMIT record flushes. After fast recovery, the PREPARE record is restored, but

23-16 IBM Informix Dynamic Server Administrator’s Guide

 the COMMIT record is lost (because it was in the logical-log buffer at the time of
the failure). The existence of the PREPARE record would initiate a query to the
coordinator about the transaction. However, the coordinator would know nothing
of the transaction, because it ended the transaction after it received the
participant’s acknowledgment that the commit occurred. In this situation, the
participant would interpret the lack of information as a final direction to roll back
the transaction. The two-phase commit protocol requires the participant’s COMMIT
record to be flushed immediately to prevent this kind of misunderstanding.

Logical-Log Records Written During a Heuristic Rollback

Figure 23-4 on page 23-18 illustrates the sequence in which the database server
writes the logical-log records during a heuristic rollback. Because a heuristic
rollback only occurs after the participant sends a message that it can commit and
the coordinator sends a message to commit, the first phase of this protocol is the
same as that shown in Figure 23-3 on page 23-16. When a heuristic rollback occurs,
the rollback is assumed to be the consequence of a long-transaction condition that
occurs at the Participant 1 (P1) database server. The end result is a transaction that
is inconsistently implemented. See “The Heuristic Rollback Scenario” on page
23-10.

Chapter 23. Multiphase Commit Protocols 23-17

 Start protocol

Coordinator:
C Writes log record: BEGPREP.
Sends message: precommit.
All Participants:
P1 P2 P3 Write log record: TABLOCKS.
Write log record: PREPARE.
Flush logical log.
Send message: commit ok.
Within P1 participant’s environment:
The database server detects long
transaction condition. Rollback starts.
Writes log record: HEURTX.
Writes log record: ROLLBACK.
Message written in message log.
Coordinator:
C Writes log record: COMMIT.
Flushes log record.
Sends message: commit.

P1 P2 P3 Participant 1:
Sends message: Transaction heuristically rolled back. Cannot commit.
Participants 2 and 3:
Write and flush log record: COMMIT.
Send message: committed.
Coordinator:
C Writes message in message log (-698).
Sends message to Participant 1: end-transaction.

Participant 1:
P1 P2 P3 Writes log record: ENDTRANS.
Sends message: Transaction ended.

Coordinator:
C Writes log record: ENDTRANS.
Returns error message to user: Error -698.
End protocol

Figure 23-4. Logical-Log Records Written During a Heuristic Rollback

Logical-Log Records Written After a Heuristic End Transaction

Figure 23-5 on page 23-19 illustrates the writing sequence of the logical-log records
during a heuristic end transaction. The event is always the result of a database
server administrator ending a transaction (see information on the onmode utility in
the IBM Informix Administrator's Reference) at a participant database server after the
participant has sent a can commit message. In Figure 23-5, the heuristic end
transaction is assumed to have occurred at the Participant 1 (P1) database server.
The result is an inconsistently implemented transaction. See “The Heuristic
End-Transaction Scenario” on page 23-12.

23-18 IBM Informix Dynamic Server Administrator’s Guide

 Start protocol

Coordinator:
C Writes log record: BEGPREP.
Sends message: precommit.

All participants:
P1 P2 P3 Write log record: TABLOCKS.
Write and flush log record: PREPARE.
Send message: can commit.
P1 participant’s environment:
Transaction is killed.
Writes log record: ROLLBACK.
Writes log record: ENDTRANS.
Message is written in the database server message log.
Coordinator:
C Writes log record: COMMIT.
Flushes logical-log buffer.
Sends message: commit.
Participant 1:
P1 P2 P3
Returns error message.
Participants 2 and 3:
Write log record: COMMIT.
Flush logical-log buffer.
Send message: committed.
Coordinator:
C Receives error message from P1.
Establishes new connection to P1 and sends TX Inquire message to P1.

Participant 1:
P1 P2 P3 Sends transaction status unknown message back to the coordinator.

Coordinator:
C Assumes unknown status means committed.
Writes log record: ENDTRANS.

End protocol

Figure 23-5. Logical-Log Records Written During a Heuristic End Transaction

Configuration Parameters Used in Two-Phase Commits

The following two configuration-file parameters are specific to distributed
environments:
v DEADLOCK_TIMEOUT
v TXTIMEOUT

Although both parameters specify time-out periods, the two are independent. For
more information on these configuration parameters, see the IBM Informix
Administrator's Reference.

Chapter 23. Multiphase Commit Protocols 23-19

 Function of the DEADLOCK_TIMEOUT Parameter
If a distributed transaction is forced to wait longer than the number of seconds
specified by DEADLOCK_TIMEOUT for a shared-memory resource, the thread
that owns the transaction assumes that a multiserver deadlock exists. The
following error message is returned:
-154 ISAM error: deadlock timeout expired - Possible deadlock.

The default value of DEADLOCK_TIMEOUT is 60 seconds. Adjust this value

carefully. If you set it too low, individual database servers end transactions that are
not deadlocks. If you set it too high, multiserver deadlocks could reduce
concurrency.

Function of the TXTIMEOUT Parameter

The TXTIMEOUT configuration parameter is specific to the two-phase commit
protocol. It is used only if communication between a transaction coordinator and
participant has been interrupted and needs to be reestablished.

The TXTIMEOUT parameter specifies a period of time that a participant database

server waits to receive a commit instruction from a coordinator database server
during a distributed transaction. If the period of time specified by TXTIMEOUT
elapses, the participant database server checks the status of the transaction to
determine if the participant should initiate automatic participant recovery.

TXTIMEOUT is specified in seconds. The default value is 300 (five minutes). The
optimal value for this parameter varies, depending on your specific environment
and application. Before you modify this parameter, read the discussion “How the
Two-Phase Commit Protocol Handles Failures” on page 23-7.

Heterogeneous Commit Protocol

Used in the context of Informix database servers, the term heterogeneous
environment refers to a group of database servers in which at least one of the
database servers is not an Informix database server. Heterogeneous commit ensures
the all-or-nothing basis of distributed transactions in a heterogeneous environment.

Unlike the two-phase commit protocol, the heterogeneous commit protocol

supports the participation of a non-Informix participant. The non-Informix
participant, called a gateway participant, must communicate with the coordinator
through an IBM Informix gateway.

The database server uses heterogeneous commit protocol when the following
criteria are met:
v Heterogeneous commit is enabled. (That is, the HETERO_COMMIT
configuration parameter is set to 1.)
v The coordinator of the commit is a Version 7.2 or later IBM Informix Dynamic
Server.
v The non-Informix participant communicates with the Informix database server
through an Informix gateway.
v At most, one non-Informix participant performs an update within a single
transaction.

Figure 23-6 illustrates this scenario.

23-20 IBM Informix Dynamic Server Administrator’s Guide

 Informix Non-Informix
gateway

Coordinator Gateway server

Informix client
Database server
Informix participants

Database server

Database server

Figure 23-6. Configuration That Requires Heterogeneous Commit for Distributed Transactions

Gateways That Can Participate in a Heterogeneous Commit

Transaction
An IBM Informix gateway acts as a bridge between an Informix application (in this
case, a database server) and a non-IBM Informix database server. An IBM Informix
gateway allows you to use an IBM Informix application to access and modify data
that is stored in non-Informix databases.

The following table lists the gateways and corresponding database servers that can
participate in a transaction in which the database server uses the heterogeneous
commit protocol.
Table 23-1. Gateways and corresponding database servers/heterogeneous commit
transaction
Gateway Database Servers
IBM Informix Enterprise Gateway with DRDA IBM DB2, OS/400, SQL/DS
IBM Informix Enterprise Gateway for EDA/SQL EDA/SQL
IBM Informix Enterprise Gateway Manager Any database server with ODBC
connectivity

Enabling and Disabling of Heterogeneous Commit

Use a text editor or ISA to change the HETERO_COMMIT configuration parameter
which enables or disables heterogeneous commit: The change takes effect when
you shut down and restart the database server.

When you set HETERO_COMMIT to 1, the transaction coordinator checks for

distributed transactions that require the use of heterogeneous commit. When the
coordinator detects such a transaction, it automatically executes the heterogeneous
commit protocol.

If you set HETERO_COMMIT to 0 or any number other than 1, the transaction

coordinator disables the heterogeneous commit protocol. The following table
summarizes which protocol the transaction coordinator uses, heterogeneous
commit or two-phase commit, to ensure the integrity of a distributed transaction.

Chapter 23. Multiphase Commit Protocols 23-21

 HETERO_COMMIT
Setting Gateway Participant Updated Database Server Protocol
Disabled No Two-phase commit
Disabled Yes Two-phase commit
Enabled No Two-phase commit
Enabled Yes Heterogeneous commit

How Heterogeneous Commit Works

The heterogeneous commit protocol is a modified version of the standard
two-phase commit protocol. The postdecision phase in the heterogeneous commit
protocol is identical to the postdecision phases in the two-phase commit protocol.
The precommit phase contains a minor modification, and a new phase, called the
gateway commit phase, is added to the heterogeneous commit protocol.

The following sections explain the modification to the precommit phase and the
gateway commit phase. For a detailed explanation of the postdecision phases, see
“Postdecision Phase” on page 23-7.

Precommit Phase
The coordinator directs each update participant (except the gateway participant) to
prepare to commit the transaction.

If the updates satisfy all deferred constraints, all participants (except the gateway
participant) return messages to the coordinator indicating that they can commit
their piece of work.

Gateway Commit Phase

If all participants successfully return a message indicating that they are prepared to
commit, the coordinator sends a commit message to the gateway. The gateway in
turn sends a response to the coordinator indicating whether the gateway
committed its piece of the transaction. If the gateway commits the transaction, the
coordinator decides to commit the entire transaction. Figure 23-7 on page 23-23
illustrates this process.

23-22 IBM Informix Dynamic Server Administrator’s Guide

 Start gateway commit phase

Coordinator
C
Sends a commit message to the gateway participant.

Gateway

Gateway Participant:
GP Commits the work. Returns message: committed.

Gateway

Coordinator
C Receives gateway committed message.

End gateway commit phase

Figure 23-7. Heterogeneous Commit Phase That Results in a Committed Transaction

If the gateway fails to commit the transaction, the coordinator rolls back the entire
transaction, as Figure 23-7 illustrates.

Heterogeneous Commit Optimization

The database server optimizes the heterogeneous commit protocol when the only
participant that receives an update is a non-Informix database. In this case, the
coordinator sends a single commit message to all participants without invoking the
heterogeneous commit protocol.

Implications of a Failed Heterogeneous Commit

At any time during a distributed transaction that the database server processes
using heterogeneous commit, the coordinator or any number of participants can
fail. The database server handles these failures in the same way as in the
two-phase commit protocol, except in certain instances. The following sections
examine these special instances in detail.

Database Server Coordinator Failure

The consistency of data after a coordinator failure depends on the point in the
heterogeneous commit process at which the coordinator fails. If the coordinator
fails before sending the commit message to the gateway, the entire transaction is
stopped upon recovery, as is the case with two-phase commit.

If the coordinator fails after it writes the commit log record, the entire transaction
is committed successfully upon recovery, as is the case with two-phase commit.

If the coordinator fails after it sends the commit message to the gateway but before
it writes the commit log record, the remote Informix database server sites in the
transaction are stopped upon recovery. This can result in inconsistencies if the
gateway received the commit message and committed the transaction.

Chapter 23. Multiphase Commit Protocols 23-23

 The following table summarizes these scenarios.

Point of Database Server Coordinator Failure Expected Result

After the coordinator writes the PREPARE log Data consistency is maintained.
record and before the gateway commit phase
After the coordinator sends a commit message to Data is probably inconsistent. No
the gateway but before it receives a reply indication of probable data inconsistency
from the coordinator.
After gateway commit phase but before the Data consistency is lost. No indication of
coordinator writes a COMMIT record to the data inconsistency from the coordinator.
logical log

Participant Failure
Whenever a participant in a distributed transaction that uses the heterogeneous
protocol fails, the coordinator sends the following error message:
-441 Possible inconsistent data at the target DBMS name due to an
aborted commit.

In addition, the database server sends the following message to the message log:
Data source accessed using gateway name might be in an inconsistent state.

A participant failure is not limited to the failure of a database server or gateway. In

addition, a failure of the communication link between the coordinator and the
gateway is considered a gateway failure. The gateway terminates if a link failure
occurs. The gateway must terminate because it does not maintain a transaction log
and therefore cannot reestablish a connection with the coordinator and resume the
transaction. Because of this restriction, some scenarios exist in which a gateway
failure might leave data in an inconsistent state. The following table summarizes
these scenarios.

Point of Participant Failure Expected Result

After participant receives commit Data consistency is maintained.
transaction message from coordinator, but
before participant performs commit
After participant receives commit Data is inconsistent.
transaction message from coordinator and
commits the transaction, but before the
participant replies to coordinator
After participant commits the transaction and If the communications link fails before the
sends a reply to coordinator coordinator receives the reply, then data is
inconsistent. If the coordinator receives the
reply, then data is consistent (provided the
coordinator does not fail before writing the
COMMIT record).

The recovery procedure that the database server follows when a participant fails is
identical to the procedure that is followed in two-phase commit. For more
information on this procedure, see “Participant Failure” on page 23-24.

Interpretation of Heterogeneous Commit Error Messages

When the database server fails to process a distributed transaction using
heterogeneous commit, it returns one of the two error messages that are discussed
in the following sections.

23-24 IBM Informix Dynamic Server Administrator’s Guide

Application Attempts to Update Multiple Gateway Participants: If your client
application attempts to update data at more than one gateway participant when
HETERO_COMMIT is set to 1, the coordinator returns the following error message:
-440 Cannot update more than one non-Informix DBMS within a transaction.

If you receive this error message, rewrite the offending application so that it
updates at most one gateway participant in a single distributed transaction.

Failed Attempt to Commit Distributed Transaction Using Heterogeneous

Commit: The database server can fail to commit a distributed transaction while it
is using the heterogeneous protocol for one or more of the following reasons:
v Communication error
v Site failure
v Gateway failure
v Other unknown error

When such a failure occurs, the coordinator returns the following message:
-441 Possible inconsistent data at the target DBMS name due to
an aborted commit.

After the database server sends this message, it rolls back all update sites that are
participating in the transaction, with the possible exception of the work done at the
site of the gateway participant. The gateway participant might have committed its
updates if the failure occurred after the gateway participant processed the commit
message. If the gateway participant committed the updates, you must manually
rollback these updates.

Chapter 23. Multiphase Commit Protocols 23-25

23-26 IBM Informix Dynamic Server Administrator’s Guide
Chapter 24. Recovering Manually from Failed Two-Phase
Commit
In This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-1
Determining If Manual Recovery Is Required . . . . . . . . . . . . . . . . . . . . . . . 24-1
Determining If a Transaction Was Implemented Inconsistently . . . . . . . . . . . . . . . . . 24-1
Global Transaction Ended Prematurely . . . . . . . . . . . . . . . . . . . . . . . 24-1
Heuristic End Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Heuristic Rollback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-2
Determining If the Distributed Database Contains Inconsistent Data . . . . . . . . . . . . . . . 24-2
Obtaining Information from the Logical Log . . . . . . . . . . . . . . . . . . . . . . 24-3
Obtaining the Global Transaction Identifier . . . . . . . . . . . . . . . . . . . . . . 24-3
Deciding If Action Is Needed to Correct the Situation. . . . . . . . . . . . . . . . . . . . 24-4
Example of Manual Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24-5

In This Chapter
Distributed transactions follow the two-phase commit protocol. Certain actions
occur independently of the two-phase commit protocol and cause the transaction
to be inconsistently implemented. (See “Independent Actions” on page 23-8.) In
these situations, it might be necessary to recover manually from the transaction.

This chapter describes the following topics:

v Determining if you need to recover manually from an inconsistently
implemented two-phase commit transaction
v Performing a manual recovery

Determining If Manual Recovery Is Required

The following list outlines the steps in the procedure to determine database
consistency and to correct the situation if required.

To determine database consistency:

1. Determine whether a transaction was implemented inconsistently.
2. Determine if the networked database system contains inconsistent data.
3. Decide if action to correct the situation is required.

Each of these steps is described in the following sections.

Determining If a Transaction Was Implemented Inconsistently

Your first task is to determine whether the transaction was implemented
inconsistently as a result of an independent action.

Global Transaction Ended Prematurely

If you executed an onmode -z command to end the global transaction on the
coordinator, the transaction might be inconsistently implemented. (For an
explanation of how this situation can arise, see “Independent Actions That Result
in an Error Condition” on page 23-9.) You can check for an inconsistent transaction
by first examining the database server message log for the coordinator. Look for
the following error message:
-716 Possible inconsistent transaction.
Unknown servers are server-name-list.

© Copyright IBM Corp. 1996, 2005 24-1

 This message lists all the database servers that were participants. Examine the
logical log of each participant. If at least one participant performed a commit and
one performed a rollback, the transaction was inconsistently implemented.

Heuristic End Transaction

If you executed an onmode -Z address command to end a piece of work
performed by a participant, and the coordinator decided to commit the transaction,
the transaction is implemented inconsistently. (For a description of this scenario,
see “The Heuristic End-Transaction Scenario” on page 23-12.) Examine the logical
log of each participant. If at least one participant performed a commit and one
performed a rollback, the transaction was inconsistently implemented.

Heuristic Rollback
You can determine the specific database server participants affected by a heuristic
decision to roll back a transaction in the following ways:
v Examine the return code from the COMMIT WORK statement in the application.
The following message indicates that one of the participants performed a
heuristic rollback:
-698 Inconsistent transaction. Number and names of servers rolled back.
v Examine the messages in the database server message-log file.
If a database inconsistency is possible because of a heuristic decision at a
participating database server, the following message appears in the database
server message-log file of the coordinator:
Mixed transaction result. (pid=nn user=user_id)
This message is written whenever error -698 is returned. Associated with this
message is a list of the participant database servers where the transaction was
rolled back. This is the complete list. The list that appears with the -698 error
message could be truncated if a large number of participants rolled back the
transaction.
v Examine the logical log for each participant.
If at least one participant rolls back its piece of work and one participant
commits its piece of work, the transaction is implemented incorrectly.

Determining If the Distributed Database Contains Inconsistent

Data
If you determine that a transaction was inconsistently implemented, you must
determine what this situation means for your distributed database system.
Specifically, you must determine if data integrity has been affected.

A transaction that is inconsistently implemented causes problems whenever the

piece of work rolled back by one participant is dependent on a piece of work that
was updated by another participant. It is impossible to define these dependencies
with SQL because distributed transactions do not support constraints that reference
data at multiple database servers. The pieces of work are independent (no
dependencies exist) only if the data could have been updated in two independent
transactions. Otherwise, the pieces of work are considered to be dependent.

Before you proceed, consider the transaction that caused the error. Are the pieces
of data that were updated and rolled back dependent on one another? Multiple
updates might be included in a single transaction for reasons other than
maintaining data integrity. For example, three possible reasons are as follows:
v Reduced transaction overhead
v Simplified coding

24-2 IBM Informix Dynamic Server Administrator’s Guide

v Programmer preference

Verify also that every participant database server that is assumed to have
committed the transaction actually modified data. A read-only database server
might be listed as a participant that committed a transaction.

If an inconsistent transaction does not lead to a violation of data integrity, you can
quit the procedure at this point.

Obtaining Information from the Logical Log

To determine if data integrity has been affected by an inconsistently implemented
global transaction, you need to reconstruct the global transaction and determine
which parts of the transaction were committed and which were rolled back. Use
the onlog utility to obtain the necessary information. The procedure is as follows:
1. Reconstruct the transaction at the participant that contains the HEURTX record.
a. A participant database server logical log is the starting point for your
information search. Each record in the log has a local transaction
identification number (xid). Obtain the xid of the HEURTX record.
b. Use the local xid to locate all associated log records that rolled back as part
of this piece of work.
2. Determine which database server acted as coordinator for the global
transaction.
a. Look for the PREPARE record on the participant that contains the same
local xid. The PREPARE record marks the start of the two-phase commit
protocol for the participant.
b. Use the onlog -l option to obtain the long output of the PREPARE record.
This record contains the global transaction identifier (GTRID) and the name
of the coordinating database server. For information about GTRID, see
“Obtaining the Global Transaction Identifier” on page 24-3.
3. Obtain a list of the other participants from the coordinator log.
a. Examine the log records on the coordinator database server. Find the
BEGPREP record.
b. Examine the long output for the BEGPREP record. If the first 32 bytes of the
GTRID in this record match the GTRID of the participant, the BEGPREP
record is part of the same global transaction. Note the participants
displayed in the ASCII part of the BEGPREP long output.
4. Reconstruct the transaction at each participant.
a. At each participant database server, read the logical log to find the
PREPARE record that contains the GTRID associated with this transaction
and obtain the local xid for the piece of work performed by this participant.
b. At each participant database server, use the local xid to locate all logical-log
records associated with this transaction (committed or rolled back).

After you follow this procedure, you know what all the participants for the
transaction were, which pieces of work were assigned to each participant, and
whether each piece of work was rolled back or committed. From this information,
you can determine if the independent action affected data integrity.

Obtaining the Global Transaction Identifier

When a global transaction starts, it receives a unique identification number called a
global transaction identifier (GTRID). The GTRID includes the name of the
coordinator. The GTRID is written to the BEGPREP logical-log record of the
coordinator and the PREPARE logical-log record of each participant.

Chapter 24. Recovering Manually from Failed Two-Phase Commit 24-3

 To see the GTRID, use the onlog -l option. The GTRID is offset 20 bytes into the
data portion of the record and is 144 bytes long. Figure 24-1 shows the onlog -l
output for a BEGPREP record. The coordinator is chrisw.

4a064 188 BEGPREP 4 0 4a038 0 1

000000bc 00000043 00000004 0004a038 .......C .......8
00087ef0 00000002 63687269 73770000 ..~..... chrisw..
00000000 00000000 00000000 00087eeb ........ ......~.
00006b16 00000000 00000000 00000000 ..k..... ........
00000000 00000000 00000000 00000000
00000000 00000000 00000000 00000000
00000000 00000000 00000000 00000000
00000000 00000000 00000000 00000000
00000000 00000000 00000000 00000000
00000000 00000000 00000000 00000000
00000000 00000001 6a756469 74685f73 ........ judith_s
6f630000 736f6374 63700000 oc..soct cp..

Figure 24-1. Output of the onlog -l Option for a BEGPREP Record

The first 32 bytes of the GTRID are identical for the BEGPREP record on the
coordinator and the PREPARE records on participants, which are part of the same
global transaction. For example, compare the GTRID for the PREPARE record in
Figure 24-2 with that of the BEGPREP record in Figure 24-1.

c7064 184 PREPARE 4 0 c7038 chrisw

000000b8 00000044 00000004 000c7038 .......D ......p8
00005cd6 00000002 63687269 73770000 ...... chrisw..
00000000 00000000 00000069 00087eeb ........ ...i..~.
00006b16 00000000 00000010 00ba5a10 ..k..... ......Z.
00000002 00ba3a0c 00000006 00000000 ......:. ........
00ba5a10 00ba5a1c 00000000 00000000 ..Z...Z. ........
00ba3a0e 00254554 00ba2090 00000001 ..:..%ET .. .....
00000000 00ab8148 0005fd70 00ab8148 .......H ...p...H
0005fe34 0000003c 00000000 00000000 ...4...< ........
00000000 00ab80cc 00000000 00ab80c4 ........ ........
00ba002f 63687269 73770000 00120018 .../chrisw......
00120018 00ba0000 ........

Figure 24-2. Output of the onlog -l Option for a PREPARE Record

Deciding If Action Is Needed to Correct the Situation

If an inconsistent transaction creates an inconsistent database, the following three
options are available to you:
v Leave the networked database in its inconsistent state.
v Remove the effects of the transaction wherever it was committed, thereby rolling
back the entire transaction.
v Reapply the effects of the transaction wherever it was rolled back, thereby
committing the transaction.

You can leave the database in its inconsistent state if the transaction does not
significantly affect database data. You might encounter this situation if the
application that is performing the transaction can continue as it is, and you decide
that the price (in time and effort) of returning the database to a consistent state by
either removing the effects or reapplying the transaction is too high.

You do not have to reach this decision immediately. You can use the methods
described in the following paragraphs to determine what data the transaction was
updating and which records are affected.

As you make your decision, consider that no automatic process or utility can
perform a rollback of a committed transaction or can commit part of a transaction

24-4 IBM Informix Dynamic Server Administrator’s Guide

 that has been rolled back. The following paragraphs describe how to look through
the database server message log and the logical log to locate affected records.
Without detailed knowledge of the application, messages are not enough to
determine what has happened. Based on your knowledge of your application and
your system, you must determine whether to roll back or to commit the
transaction. You must also program the compensating transaction that will perform
the rollback or the commit.

Example of Manual Recovery

This example illustrates the kind of work that is involved in manual recovery. The
following SQL statements were executed by user nhowe. Error -698 was returned.
dbaccess
CREATE DATABASE tmp WITH LOG;
CREATE TABLE t (a int);
CLOSE DATABASE;
CREATE DATABASE tmp@apex WITH LOG;
CREATE TABLE t (a int);
CLOSE DATABASE;
DATABASE tmp;
BEGIN WORK;
INSERT INTO t VALUES (2);
INSERT INTO tmp@apex:t VALUES (2);
COMMIT WORK;
### return code -698

The following excerpt is taken from the logical log at the current database server:
addr len type xid id link
.....
17018 16 CKPOINT 0 0 13018 0

18018 20 BEGIN 2 1 0 08/27/91 10:56:57

3482 nhowe

1802c 32 HINSERT 2 0 18018 1000018 102

4

1804c 40 CKPOINT 0 0 17018 1

begin xid id addr user

1 2 1 1802c nhowe

19018 72 BEGPREP 2 0 1802c 6d69 1

19060 16 COMMIT 2 0 19018 08/27/91 11:01:38

1a018 16 ENDTRANS 2 0 19060 580543

The following excerpt is taken from the logical log at the database server apex:
addr len type xid id link
.....
16018 20 BEGIN 2 1 0 08/27/91
10:57:07 3483 pault

1602c 32 HINSERT 2 0 16018 1000018 102

4

1604c 68 PREPARE 2 0 1602c eh

17018 16 HEURTX 2 0 1604c 1

17028 12 CLR 2 0 1602c

17034 16 ROLLBACK 2 0 17018 08/27/91 11:01:22

Chapter 24. Recovering Manually from Failed Two-Phase Commit 24-5

 17044 40 CKPOINT 0 0 15018 1

begin xid id addr user

1 2 1 17034 --------

18018 16 ENDTRANS 2 0 17034 8806c3

....

First, you would try to match the transactions in the current database server log
with the transactions in the apex database server log. The BEGPREP and PREPARE
log records each contain the GTRID. You can extract the GTRID by using onlog -l
and looking at the data portion of the BEGPREP and PREPARE log records. The
GTRID is offset 22 bytes into the data portion and is 68 bytes long. A more simple,
though less precise, approach is to look at the time of the COMMIT or ROLLBACK
records. The times should be close, although there is a slight delay because of the
time taken to transmit the commit (or rollback) message from the coordinator to
the participant. (This second approach lacks precision because concurrent
transactions could commit at the same time although concurrent transactions from
one coordinator would probably not commit at the same time.)

To correct this sample situation:

1. Find all records that were updated.
2. Identify their type (insert, delete, update) using onlog and the table of record
types.
3. Use the onlog -l output for each record to obtain the local xid, the tblspace
number, and the rowid.
4. Map the tblspace number to a table name by comparing the tblspace number to
the value in the partnum column of the systables system catalog table.
5. Using your knowledge of the application, determine what action is required to
correct the situation.

In this example, the time stamps on the COMMIT and ROLLBACK records in the
different logs are close. No other active transactions introduce the possibility of
another concurrent commit or rollback. In this case, an insert (HINSERT) of
assigned rowid 102 hex (258 decimal) was committed on the current database
server. Therefore, the compensating transaction is as follows:
DELETE FROM t WHERE rowid = 258

24-6 IBM Informix Dynamic Server Administrator’s Guide

Part 6. Appendixes

© Copyright IBM Corp. 1996, 2005

IBM Informix Dynamic Server Administrator’s Guide
Appendix. Accessibility
The syntax diagrams in the HTML version of this manual are available in dotted
decimal syntax format, which is an accessible format that is available only if you
are using a screen reader.

Dotted Decimal Syntax Diagrams

In dotted decimal format, each syntax element is written on a separate line. If two
or more syntax elements are always present together (or always absent together),
the elements can appear on the same line, because they can be considered as a
single compound syntax element.

Each line starts with a dotted decimal number; for example, 3 or 3.1 or 3.1.1. To
hear these numbers correctly, make sure that your screen reader is set to read
punctuation. All syntax elements that have the same dotted decimal number (for
example, all syntax elements that have the number 3.1) are mutually exclusive
alternatives. If you hear the lines 3.1 USERID and 3.1 SYSTEMID, your syntax can
include either USERID or SYSTEMID, but not both.

The dotted decimal numbering level denotes the level of nesting. For example, if a
syntax element with dotted decimal number 3 is followed by a series of syntax
elements with dotted decimal number 3.1, all the syntax elements numbered 3.1
are subordinate to the syntax element numbered 3.

Certain words and symbols are used next to the dotted decimal numbers to add
information about the syntax elements. Occasionally, these words and symbols
might occur at the beginning of the element itself. For ease of identification, if the
word or symbol is a part of the syntax element, the word or symbol is preceded by
the backslash (\) character. The * symbol can be used next to a dotted decimal
number to indicate that the syntax element repeats. For example, syntax element
*FILE with dotted decimal number 3 is read as 3 \* FILE. Format 3* FILE
indicates that syntax element FILE repeats. Format 3* \* FILE indicates that
syntax element * FILE repeats.

Characters such as commas, which are used to separate a string of syntax

elements, are shown in the syntax just before the items they separate. These
characters can appear on the same line as each item, or on a separate line with the
same dotted decimal number as the relevant items. The line can also show another
symbol that provides information about the syntax elements. For example, the lines
5.1*, 5.1 LASTRUN, and 5.1 DELETE mean that if you use more than one of the
LASTRUN and DELETE syntax elements, the elements must be separated by a comma.
If no separator is given, assume that you use a blank to separate each syntax
element.

If a syntax element is preceded by the % symbol, this identifies a reference that is

defined elsewhere. The string following the % symbol is the name of a syntax
fragment rather than a literal. For example, the line 2.1 %OP1 means that you
should refer to a separate syntax fragment OP1.

The following words and symbols are used next to the dotted decimal numbers:
? Specifies an optional syntax element. A dotted decimal number followed

© Copyright IBM Corp. 1996, 2005 A-1

 by the ? symbol indicates that all the syntax elements with a
corresponding dotted decimal number, and any subordinate syntax
elements, are optional. If there is only one syntax element with a dotted
decimal number, the ? symbol is displayed on the same line as the syntax
element (for example, 5? NOTIFY). If there is more than one syntax element
with a dotted decimal number, the ? symbol is displayed on a line by
itself, followed by the syntax elements that are optional. For example, if
you hear the lines 5 ?, 5 NOTIFY, and 5 UPDATE, you know that syntax
elements NOTIFY and UPDATE are optional; that is, you can choose one or
none of them. The ? symbol is equivalent to a bypass line in a railroad
diagram.
! Specifies a default syntax element. A dotted decimal number followed by
the ! symbol and a syntax element indicates that the syntax element is the
default option for all syntax elements that share the same dotted decimal
number. Only one of the syntax elements that share the same dotted
decimal number can specify a ! symbol. For example, if you hear the lines
2? FILE, 2.1! (KEEP), and 2.1 (DELETE), you know that (KEEP) is the
default option for the FILE keyword. In this example, if you include the
FILE keyword but do not specify an option, default option KEEP is applied.
A default option also applies to the next higher dotted decimal number. In
this example, if the FILE keyword is omitted, default FILE(KEEP) is used.
However, if you hear the lines 2? FILE, 2.1, 2.1.1! (KEEP), and 2.1.1
(DELETE), the default option KEEP only applies to the next higher dotted
decimal number, 2.1 (which does not have an associated keyword), and
does not apply to 2? FILE. Nothing is used if the keyword FILE is omitted.
* Specifies a syntax element that can be repeated zero or more times. A
dotted decimal number followed by the * symbol indicates that this syntax
element can be used zero or more times; that is, it is optional and can be
repeated. For example, if you hear the line 5.1* data-area, you know that
you can include more than one data area or you can include none. If you
hear the lines 3*, 3 HOST, and 3 STATE, you know that you can include
HOST, STATE, both together, or nothing.
Notes:
1. If a dotted decimal number has an asterisk (*) next to it and there is
only one item with that dotted decimal number, you can repeat that
same item more than once.
2. If a dotted decimal number has an asterisk next to it and several items
have that dotted decimal number, you can use more than one item
from the list, but you cannot use the items more than once each. In the
previous example, you could write HOST STATE, but you could not write
HOST HOST.
3. The * symbol is equivalent to a loop-back line in a railroad syntax
diagram.
+ Specifies a syntax element that must be included one or more times. A
dotted decimal number followed by the + symbol indicates that this syntax
element must be included one or more times. For example, if you hear the
line 6.1+ data-area, you must include at least one data area. If you hear
the lines 2+, 2 HOST, and 2 STATE, you know that you must include HOST,
STATE, or both. As for the * symbol, you can only repeat a particular item if
it is the only item with that dotted decimal number. The + symbol, like the
* symbol, is equivalent to a loop-back line in a railroad syntax diagram.

A-2 IBM Informix Dynamic Server Administrator’s Guide

Notices
IBM may not offer the products, services, or features discussed in this document in
all countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply
to you.

This information could include technical inaccuracies or typographical errors.

Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created

© Copyright IBM Corp. 1996, 2005 B-1

 programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:
IBM Corporation
J46A/G4
555 Bailey Avenue
San Jose, CA 95141-1003
U.S.A.

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM’s suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM’s application programming interfaces.

B-2 IBM Informix Dynamic Server Administrator’s Guide

 Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM
Corp. Sample Programs. © Copyright IBM Corp. (enter the year or years). All
rights reserved.

If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Trademarks
AIX; DB2; DB2 Universal Database; Distributed Relational Database Architecture;
NUMA-Q; OS/2, OS/390, and OS/400; IBM Informix®; C-ISAM®;
Foundation.2000™; IBM Informix ® 4GL; IBM Informix®DataBlade®Module; Client
SDK™; Cloudscape™; Cloudsync™; IBM Informix®Connect; IBM Informix®Driver
for JDBC; Dynamic Connect™; IBM Informix®Dynamic Scalable
Architecture™(DSA); IBM Informix®Dynamic Server™; IBM Informix®Enterprise
Gateway Manager (Enterprise Gateway Manager); IBM Informix®Extended Parallel
Server™; [Link] Services™; J/Foundation™; MaxConnect™; Object Translator™;
Red Brick™; IBM Informix® SE; IBM Informix® SQL; InformiXML™; RedBack®;
SystemBuilder™; U2™; UniData®; UniVerse®; wintegrate®are trademarks or
registered trademarks of International Business Machines Corporation.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and other countries.

Windows, Windows NT, and Excel are either registered trademarks or trademarks
of Microsoft Corporation in the United States and/or other countries.

UNIX is a registered trademark in the United States and other countries licensed
exclusively through X/Open Company Limited.

Other company, product, and service names used in this publication may be
trademarks or service marks of others.

Notices B-3
B-4 IBM Informix Dynamic Server Administrator’s Guide
Index
Special characters ALL keyword
DATASKIP 11-31
/etc/hosts file 20-17 ALLOCATE COLLECTION statement 12-5
/etc/services file 20-17 ALLOCATE DESCRIPTOR statement 12-5
/userva=xxxx switch 1-4 ALLOCATE ROW statement 12-5
.informix file 1-8 Allocating disk space
.rhosts file 3-12 cooked file space 11-4
(*), asterisk extent 10-8
See also Wildcard. initial chunk 11-6
wildcard in hostname field 3-26 metadata 11-23
$INFORMIXDIR mirrored data 19-2
permissions 5-2 overview 1-6
procedure 11-3
sbspaces 10-19
Numerics shared memory 1-4
32-bit platform UNIX
and buffer pool 11-14 cooked files 11-4
32-bit system support 1-4 raw files 11-5
64-bit addressing Windows
buffer pool 8-11 logical drive 11-6
database server support 1-4 NTFS files 11-6
defined 8-32 physical drive 11-7
maximum number of buffers 8-11 ALRM_ALL_EVENTS configuration parameter 2-9
memory use 8-32 ALTER ACCESS_METHOD statement 12-4
64-bit platform ALTER FRAGMENT statement 12-4
and buffer pool 11-14 ALTER FUNCTION statement 12-4
ALTER INDEX statement 12-4
ALTER PROCEDURE statement 12-4
A ALTER ROUTINE statement 12-4
ALTER SEQUENCE statement 12-4
Accessibility xxxi ALTER TABLE statement 12-4
dotted decimal format of syntax diagrams A-1 changing table type 10-24, 10-25
syntax diagrams, reading in a screen reader A-1 connecting to clients 3-29
Adding logging 12-4
virtual processors 6-10 ANSI-compliant database
ADM. changing logging mode 13-3
See Administration virtual processor class. ondblog utility 13-3
Administration virtual processor class 6-11 ontape utility 13-4
Administrative tasks ANSI-compliant transaction logging.
assigning storage 10-9 See Logging.
consistency checking 22-2 Apache server 4-9
routine tasks 1-17 Application
ADT. client.
See Audit virtual processor. See Client application.
ADTERR configuration parameter 2-10 archecker utility
ADTMODE configuration parameter 2-10, 6-26 overview 1-17
ADTPATH configuration parameter 2-10 Assertion failure
ADTSIZE configuration parameter 2-10 data corruption 22-5
Advanced Encryption Standard 5-9, 5-14 defined 22-1
Advanced User Rights 1-24 determining cause 22-6
AES. during consistency checking 22-3
See Advanced Encryption Standard. during processing of user request 22-4
AFF_NPROCS configuration parameter 7-2 message log format 22-3
AFF_SPROC configuration parameter 6-13, 7-2 Assertion failure file
Aggregate [Link] 22-4
parallel processing 6-6 [Link] 22-4
AIO list 22-4
virtual processors 6-20 [Link] 22-4
ALARMPROGRAM configuration parameter 1-21, 2-9 Asterisk (*)
Aliases. See also Wildcard.
See DBSERVERALIASES. wildcard in hostname field 3-26

© Copyright IBM Corp. 1996, 2005 X-1

Asynchronous I/O Binary large object.
defined 6-19 See BLOB data type.
kernel (KAIO) 6-17 Binding CPU virtual processors 6-7
Atomic data type. Bitmap page
See Built-in data type. index tblspace 10-29
Attaching to shared memory 8-6 tblspace 10-28
database server utilities 8-6 BLOB data type 10-13
virtual processors 8-7 BLOB data type.
Audit virtual processor 6-26 See Smart large object.
Auditing Blobpage
audit mode 6-26 defined 10-6
configuration parameters 2-10 freeing deleted pages 14-7
defined 5-6 fullness
overview 1-20 determining 11-38
Authentication oncheck -pB display 11-38
default policy 3-8 physical logging 16-3
defined 3-8 relationship to chunk 10-6
modules 5-23 sizing recommendations 11-21
Automatic database server storage statistics 11-22
shutdown 1-15 writes, bypassing shared memory 8-29
startup 1-14 Blobspaces
Automatic recovery, two-phase commit 23-7 activating 14-6
Availability adding with
critical data 10-9 onspaces 11-20
goal in efficient disk layout 10-33 backing up 11-8, 11-20
sample disk layout 10-35 buffers 8-30
Average size, smart large object 11-23 creating with
AVG_LO_SIZE tag 10-16, 11-23 onspaces 11-20
defined 10-12
dropping with
B initial tasks 11-27
ON-Monitor utility 11-28
B-tree index
onspaces 11-28
cleaner thread 8-17
free-map page
Backups
tracking blobpages 8-31
adding log files 15-10
logging tasks 10-12, 14-6
blobspaces 11-20
names 11-20
changing database logging 11-8
obtaining the number of free blobpages 11-33
checkpoints 16-11
restrictions
chunks 11-17
adding logs 15-10
converting table type 11-8
storage statistics 11-22
dbspaces 11-9
writing data to 8-29
defined 1-17
writing TEXT and BYTE data 10-12
deleted log files 15-11
Block device 10-4
freeing a log file 15-5
Blowfish 5-9
log files 11-8, 15-3
Boldface type xxiv
physical log 11-8
Boot file.
raw tables 10-25
See Startup script.
RAW tables 10-24, 10-25
[Link] file 1-4
reducing size 10-12
Buffer pools
sbspaces 10-19, 11-23, 15-4
64-bit addressing 8-11
STANDARD tables 10-24
bypassed by blobspace data 8-29
strategy 1-3
contents 8-10
TEXT and BYTE data 10-12
creating for a non-default page size 11-12
verification 1-17
creating to correspond to non-default page sizes 11-11
Bad-sector mapping, absence 22-9
defined 8-10
bargroup group 1-6
deleting 11-15
Before image
for 32-bit platform 11-14
contents 16-13, 16-15
for 64-bit platform 11-14
defined 16-2
for non-default page sizes 11-12
flushing 8-26
full checkpoint 16-7
physical log buffer 8-26
fuzzy checkpoint 16-7, 16-8
Before image journal.
LRU queues management 8-22
See Physical log.
minimum requirement 8-10
BEGIN WORK statement 12-4
monitoring activity 9-11
beginlg field 23-14
read-ahead 8-25
Big buffers, defined 8-17
resizing 11-15

X-2 IBM Informix Dynamic Server Administrator’s Guide

Buffer pools (continued) Calculating size (continued)
size of buffer 8-11 page size 11-21
smart large objects 8-31 root dbspace 10-31
synchronizing buffer flushing 8-27 smart large objects 10-16
Buffer size Cascading deletes 12-2
option 3-21 CDR_QDATA_SBSPACE configuration parameter 10-13
Buffered transaction logging Central registry
See also Logging. sqlhosts 3-14
when flushed 12-6 Changing
BUFFERING tag, in onspaces -c -Df option 10-16 chunk status 21-11
BUFFERPOOL configuration parameter 2-5, 8-10, 8-22, 11-12, database server type, HDR 21-15
16-7, 16-8 logging mode, ANSI database 13-3
and smart large objects 8-31 Character large object.
Buffers See Smart large object.
64-bit maximum number 8-11 Character-special devices 1-5
big buffers 8-17 Checkpoint
blobpage buffer 8-30 backup considerations 16-11
concurrent access 8-25 chunk writes 8-28
current lock-access level 8-15 data replication 21-11
data replication 8-13, 20-7 defined 16-7
dirty 8-26 events that initiate 16-9
exclusive mode 8-21 flushing of regular buffers 8-26
flushing 8-26 forced 21-11
how a thread full 16-7
accesses a buffer page 8-25 fuzzy 16-7
acquires 8-23 how it works 16-9
least-recently used 8-22 light appends 11-27
lock types 8-21 logical-log buffer 8-11
logical-log buffer 8-11 logical-log file 16-9
monitoring statistics and use 9-9 maximum connections 4-7
most-recently used 8-23 monitoring activity 17-4
not dirty 8-26 physical log buffer 8-27, 16-7, 16-9
physical-log buffer 8-12 role in fast recovery 16-12, 16-13
share lock 8-21 starting 4-5
smart large objects 8-31, 10-16 step in shared-memory initialization 4-7
synchronizing flushing 8-26, 8-27 CHKADJUP log record 11-24, 11-43
table, defined 8-15 chkenv utility 1-9
threads waiting 8-15 CHRESERV log record 11-24
write types during flushing 8-27 Chunks
Buffers value 11-13, 11-14 activity during mirror recovery 18-4
BUFFSIZE. adding to
See Page. dbspace 11-16
Built-in data types mirrored dbspace 19-6
fuzzy operations 16-8 sbspaces 10-19, 11-23
HDR replication 20-3 using ISA or onspaces 11-16
BYTE data type. adding with
See TEXT and BYTE data. ON-Monitor utility 11-17
Byte-range locking 8-13, 10-17 allocating initial 11-6
backing up 11-17
checking status 11-33, 22-5
C concepts 10-3
defined 1-16
C8BITLEVEL environment variable 1-8
disk layout guidelines 10-33
Cache
dropping from
See also Buffer.
blobspace 11-26
data distribution 8-19, 9-5
dbspace 11-26
monitoring shared-memory buffer 9-9, 9-10
sbspaces 11-26
Optical Subsystem memory 11-37
exceeding size limits with LVM 10-37
SPL routine cache
extents 10-8
hash size 2-6, 9-5
free list
pool size 9-5
combining and splitting pages 12-3
SQL statement cache
monitoring 17-2
configuration parameters 2-6
I/O errors during processing 22-5
enabling 9-6
linking to the pathname 1-6, 11-5, 19-3
specifying size 9-6
maximum number 1-16, 10-3, 11-8
Calculating size
maximum size 1-5, 1-16, 10-3, 11-7
blobpages 11-21
monitoring 11-33, 11-34, 22-5
metadata 10-19, 11-23

Index X-3
Chunks (continued) Client/server (continued)
name, when allocated as raw device 10-4 configuration example (continued)
recovering a down chunk 19-4 using IPX/SPX 3-33
saving status on secondary server 21-11 CLOB data type.
specifying metadata area 11-24 See Smart large object.
supporting a large 1-16 CLOSE DATABASE statement 12-4
supporting large 1-16 CLOSE statement 12-5
table, defined 8-16 Code, sample, conventions for xxvii
write Command-line conventions
checkpoints 8-28 how to read xxvi
monitoring 9-11 sample diagram xxvi
Cipher Commit
AES 5-12, 5-14 heterogeneous 23-20, 23-22
Blowfish 5-14 Commit protocol
defined 5-8 heterogeneous 23-2
DES 5-12, 5-14 two-phase 23-2, 23-5
in encryption 5-14 COMMIT statement 12-4, 12-5
supported types 5-12, 5-14 Communication configuration file.
Cipher tab 5-17 See ONCONFIG configuration file.
CKPTINTVL configuration parameter Communication Support Module 5-9
defined 2-5 [Link] entry 5-12, 5-19
initiating checkpoints 16-9 configuration file 3-8, 5-10
Classes network security 3-8
virtual processor 6-3 sqlhosts option field 3-22
CLASSPATH environment variable 1-7, 1-9 Communication support services
CLEANERS configuration parameter 2-6 defined 3-8
purpose 8-16 message confidentiality and integrity 3-8
Client application Communications
attaching to shared memory 8-6 client to database server.
beginning a session 8-18 See Connectivity.
configuring connectivity 1-9, 1-15, 3-8 shared memory
configuring environment 1-8 defined 8-20
configuring stack size 8-18 how client attaches 8-6
connecting to a host 3-13 size 8-20
connecting to primary or secondary server 20-3 Communications Support Module
connection type field 3-16 virtual processor 6-25
connections supported 3-5 Compliance
defined 3-2 with industry standards xxxiii
global transaction 23-2 [Link] file 5-10
host name field 3-18 building SMI tables 5-12
local-loopback connection 3-7 entry for network data encryption 5-19
multiplexed connections 3-4 entry for password encryption 5-12
network security files 3-11 location 5-10
ONCONFIG environment variable 1-7 Concurrency
options field 3-20 control 8-20
reacting to HDR failure 20-11 Confidentiality of communication messages 3-8
redirecting in data replication 20-12, 20-14 Configuration
remote hosts 3-11 database server environment 1-2
shared-memory connection 3-6 estimating required disk space 10-33
specifying a dbservername 3-29 J/Foundation 1-13
sqlhosts entries 3-13, 3-15, 3-26 monitoring 2-11
using data replication 20-3 multiple ports 3-10
wildcard addressing 3-28 planning for the database server 1-3
Windows network domains 3-3 requirements 1-2
CLIENT_LOCALE environment variable 1-8 using Server Setup 1-12
Client/server Windows 1-4
configuration Configuration file
listen and poll threads 6-22 avoid modifying [Link] 1-11
local loopback 3-7 connectivity 3-8
shared memory 3-6 network 1-10
configuration example [Link] 1-11
local loopback 3-32 Configuration parameters
multiple connection types 3-34 See also Individual parameter names.
multiple database servers 3-35 ADTERR 2-10
multiple residency 3-35 ADTMODE 2-10
network connection 3-33 ADTPATH 2-10
shared memory 3-31 ADTSIZE 2-10

X-4 IBM Informix Dynamic Server Administrator’s Guide

Configuration parameters (continued) Configuration parameters (continued)
AFF_NPROCS 7-2 ONDBSPACEDOWN 2-3
AFF_SPROC 6-13, 7-2 OPCACHEMAX 2-11, 11-37
ALARMPROGRAM 1-21, 2-9 OPTCOMPIND 2-7
ALRM_ALL_EVENTS 2-9 PC_HASHSIZE 2-6, 8-20, 9-5
BUFFERPOOL 2-5, 8-10, 11-12 PC_POOLSIZE 2-6, 8-20, 9-5
CDR_QDATA_SBSPACE 10-13 PHYSBUFF 2-4, 8-12
CKPTINTVL 2-5, 16-9 PHYSDBS 2-4
CLEANERS 2-6 PHYSFILE 2-4, 16-4, 17-2
CONSOLE 1-23, 2-5 PLOG_OVERFLOW_PATH 16-12
DATASKIP 2-7, 11-29, 11-30 RA_PAGES 2-6, 8-25
DB_LIBRARY_PATH 2-10, 5-32 RA_THRESHOLD 2-6, 8-25
DBCREATE_PERMISSION 2-10, 5-6 RESIDENT 2-6, 9-7
DBSERVERALIASES 2-2, 3-30 ROOTNAME 2-2, 10-11
DBSERVERNAME 2-2, 3-16, 3-29 ROOTOFFSET 2-2, 10-11, 11-4
DBSPACETEMP 2-3, 10-34, 11-16 ROOTPATH 2-2
DD_HASHMAX 2-5 ROOTSIZE 2-2
DD_HASHSIZE 2-5 SBSPACENAME 2-3, 10-14, 10-19, 11-23
DEADLOCK_TIMEOUT 2-8, 23-20 SBSPACETEMP 2-3, 10-19, 11-25
DEF_TABLE_LOCKMODE 2-6, 8-13 smart LO 11-23
diagnostic information 22-6 SECURITY_LOCALCONNECTION 2-10, 5-5
DIRECTIVES 2-9 SERVERNUM 2-2, 8-7
DRAUTO 2-8, 20-11, 20-12 setting with a text editor 9-5
DRIDXAUTO 2-8, 21-12, 21-13 shared memory 9-2
DRINTERVAL 2-8 SHMADD 2-5, 8-14
DRLOSTFOUND 2-8, 20-8 SHMBASE 2-5, 8-7, 9-3
DRTIMEOUT 2-8, 21-13 SHMTOTAL 2-5, 8-5
DS_HASHSIZE 8-19, 9-5 SHMVIRTSIZE 2-5, 8-14
DS_MAX_QUERIES 2-7 SINGLE_CPU_VP 2-7, 6-13
DS_MAX_SCANS 2-7 STACKSIZE 2-6, 8-18
DS_NONPDQ_QUERY_MEM 2-7, 8-14 STAGEBLOB 2-11
DS_POOLSIZE 8-19, 9-5 STMT_CACHE 2-6, 9-6
DS_TOTAL_MEMORY 2-7, 8-14 STMT_CACHE_HITS 2-6, 9-6
DUMPCNT 2-9, 22-6 STMT_CACHE_NOLIMIT 2-6, 9-6
DUMPCORE 2-9, 22-6 STMT_CACHE_NUMPOOL 2-6, 9-6
DUMPDIR 2-9, 22-4, 22-6 STMT_CACHE_SIZE 2-6, 9-6
DUMPGCORE 2-9, 22-4, 22-6 SYSSBSPACENAME 2-3
DUMPSHMEM 2-9, 22-4, 22-6 TAPEBLK 2-4, 21-5
DYNAMIC_LOGS 2-3, 15-10, 15-13, 15-15 TAPEDEV 2-4, 21-9
EXT_DIRECTIVES 2-9 TAPESIZE 2-4, 21-5
EXTSHMADD 2-5, 8-14 TBLTBLFIRST 2-2, 10-11, 11-10
FAST_RESTART_CKPT_FUZZYLOG 2-4, 16-17 TBLTBLNEXT 2-2, 3-28, 10-11, 11-10
FAST_RESTART_PHYSLOG 2-4, 16-17 TXTIMEOUT 2-8, 23-13, 23-20
FILLFACTOR 2-3 UNSECURE_ONSTAT 2-10, 5-33
HETERO_COMMIT 2-8, 23-21 USEOSTIME 2-8
IFX_EXTEND_ROLE 2-10, 5-32 VPCLASS 2-7, 6-17, 7-2
initial chunk of root dbspace 10-11 Configuration storage devices 1-17
LISTEN_TIMEOUT 1-10, 2-10, 5-7 CONNECT statement 3-29, 12-5
LOCKS 2-6 example 3-30
LOGBUFF 2-3, 8-12 Connection-redirection option 3-21
LOGFILES 2-3 Connections
LOGSIZE 2-3 between client applications and the server 3-5
LTAPEBLK 2-4, 21-5 database versus network 3-4
LTAPESIZE 2-4, 21-5 defined 6-22
LTXEHWM 2-3, 15-13, 15-16, 23-10 IPX/SPX 3-33
LTXHWM 2-3, 15-13, 15-16, 23-11 local loopback
MAX_INCOMPLETE_CONNECTIONS 1-10, 2-10, 5-7 defined 3-7
MAX_PDQPRIORTY 2-7 example 3-32
MIRROR 2-2, 19-2 methods 6-20
MIRROROFFSET 2-3, 10-11, 11-4 multiple
MIRRORPATH 2-2, 10-11 connection types, example 3-34
MSGPATH 1-22, 2-5 multiplexed 3-4
MULTIPROCESSOR 2-7, 6-13 network, example 3-33
NETTYPE 2-7, 3-30 security restrictions 3-11
NUMCPUVPS 6-13 shared memory, defined 3-6
OFF_RECVRY_THREADS 2-8, 20-10 TCP/IP 3-8, 3-11
ON_RECVRY_THREADS 2-8 type field 3-16

Index X-5
Connectivity CPU virtual processor (continued)
ASF 3-4 DataBlade modules 6-13
configuration parameters 3-29 defined 6-12
files, defined 3-8 how many 6-12
hosts file 3-10 multiprocessor computer 6-13
services file 3-10 poll threads 6-21, 6-22
sqlhosts file 1-10 restrictions 6-16
Windows 1-10 single-processor computer 6-13
Consistency checking threads 6-2
corruption of data 22-5 types of threads run by 6-12
data and overhead 22-2 user-defined routine 6-13
extents 22-3 CREATE ACCESS_METHOD statement 12-4
index corruption 22-5 CREATE AGGREGATE statement 12-4
indexes 22-3 CREATE CAST statement 12-4
logical logs 22-3 CREATE DATABASE statement 10-9, 12-4
monitoring for data inconsistency 22-3 CREATE DISTINCT TYPE statement 12-4
overview 1-18, 22-1 CREATE EXTERNAL TABLE statement 12-4
periodic tasks 22-2 CREATE FUNCTION FROM statement 12-4
sbspaces 10-19 CREATE FUNCTION statement 6-16, 12-4
system catalog tables 22-2 CREATE INDEX statement 12-4
validating metadata 22-3 CREATE OPAQUE TYPE statement 12-4
Console CREATE OPCLASS statement 12-4
messages 1-23 CREATE PROCEDURE FROM statement 12-4
CONSOLE configuration parameter 1-23, 2-5 CREATE PROCEDURE statement 12-4
Constraints CREATE ROLE statement 5-6, 12-4
checking, deferred 12-2 CREATE ROUTINE FROM statement 12-4
Contact information xxxiii CREATE ROUTINE statement 12-4
Contention. CREATE ROW TYPE statement 12-4
See Disk contention. CREATE SCHEMA statement 12-4
Context switching CREATE SEQUENCE statement 12-4
defined 6-8 CREATE SYNONYM statement 12-4
how functions when OS controls 6-6 CREATE TABLE statement 12-4
OS versus multithreaded 6-6 connecting to clients 3-29
Contiguous fragmenting
space for physical log 17-2 with partitions 11-18
Control structures IN dbspace option 10-9
defined 6-8 logging 12-4
queues 6-10 specifying sbspaces in a PUT clause 10-14
session control block 6-8 CREATE Temporary TABLE statement 12-4
stacks 6-9 CREATE TRIGGER statement 12-4
thread control block 6-8 CREATE VIEW statement 12-4
Conventions CREATE XADATASOURCE statement 12-4
command-line xxvi CREATE XADATASOURCE TYPE statement 12-4
documentation xxiii Creating
sample-code xxvii blobspaces 11-20
syntax diagrams xxiv dbspaces 11-8
syntax notation xxiv sbspaces 11-22
typographical xxiv smart large objects 10-14, 11-23
Conversion, during initialization 4-5 tables with CLOB or BLOB data types 10-19
Cooked file space temporary dbspaces 11-15
allocating 11-4 Critical dbspaces
compared with raw space 10-4 mirroring 10-34, 10-37
defined 1-6, 10-4 storage 10-9
for static data 10-4 Critical section of code
Coordinating database server 23-6 checkpoints 16-10
Core dump defined 16-2
See also DUMPCNT; DUMPDIR; DUMPGCORE; cron
DUMPSHMEM. utility 1-23
contents of [Link] 22-4 CSM.
when useful 22-7 See Communication Support Module.
core file 22-4 curlog field 23-14
Corruption, resolving I/O errors 22-5
CPU virtual processor
adding and dropping in online mode 6-14, 6-17
AFF_SPROC configuration parameter 6-13
D
Data
AFFNPROCS configuration parameter 6-13
estimating disk space for 10-33
binding 6-7
transmission encryption 5-9

X-6 IBM Informix Dynamic Server Administrator’s Guide

Data backup. Database logging status
See Backup. ANSI-compliant 12-6
Data block. changing mode 13-3
See Page. buffered logging 12-6
Data consistency canceling logging with ondblog 13-3
fast recovery 16-11 changes permitted 13-2
how achieved 16-2 changing buffering status
monitoring 22-3 using ondblog 13-2
symptoms of corruption 22-5 using ontape 13-4
verifying 22-2 using SET LOG 12-7
Data definition language defined 12-5
statements 20-22 ending logging
statements that are logged 12-3 using ondblog 13-3
Data encryption 5-8 using ontape 13-4
data in specified columns 5-8 making ANSI-compliant
of passwords 5-8 using ondblog 13-3
Data Encryption Standard 5-9 using ontape 13-4
See Encryption. modifying
Data files. using ISA 13-4
See Logging. using ON-Monitor 13-5
Data replication 12-2 using ondblog 13-2
See also High-Availability Data Replication. using ontape 13-3
buffer 8-13, 20-7 overview 1-18
data types that are replicated 20-3 setting 12-3
Enterprise Replication 1-20 turning on logging with ontape 13-3
flush interval 2-8 unbuffered logging 12-5
High-Availability Data Replication 1-20 Database server ID 2-2
mode 20-2 Database server name.
non-default page sizes in HDR environment 21-4 See DBSERVERNAME configuration parameter.
overview 1-20 Database servers
read-only mode 4-8 32-bit and 64-bit versions 1-4
restarting after failure 21-12 connecting with an SQL API 1-15
restarting after secondary-server index becomes database creation requirements 12-7
corrupt 21-12 groups 3-22, 3-23, 3-25, 5-5
security option 5-31 Enterprise Replication 3-23
using database server groups 3-23 HDR 3-23
wait time for response 2-8 message log 1-21
Data restore. multithreaded 6-3
See Restore. Password Communication Support Module 5-12
Data sources remote 3-12
XA-compliant 23-3 scheduling priority 1-13
Data storage starting 1-14
See also Disk space. DATABASE statement 3-29, 12-5
concepts 10-2 Databases
control 10-9, 10-14 See also Recovery.
maximum chunk ANSI compliant 12-7
size 11-4, 11-7 asynchronous I/O 6-19
maximum number of chunks 11-8 defined 10-21
maximum number of storage spaces 11-8 displaying logging status 13-6
Data Type segment. estimating size 10-33
See Disk space. fragmentation 10-22
Data types location of 10-21
CLOB and BLOB 10-14, 16-8 monitoring 11-32, 13-5
fuzzy operations 16-8 purpose of 10-21
nonfuzzy operations 16-8 size limits 10-22
replicated by HDR 20-3 sysutils 4-7
user defined 10-14 tuning.
Data-distribution cache 8-19, 9-5 See Performance tuning.
Data-recovery mechanisms DataBlade
fast recovery 16-11 restricting access for registering UDRs 5-32
smart large objects 10-13 DataBlade API
Database administrator. smart large object size 10-16
See Administrative tasks. smart large objects, accessing 10-13, 10-19
Database logging DataBlade modules
backups 11-8 virtual processors 6-13
DTP environment 12-7 DATASKIP configuration parameter 2-7
Enterprise Replication 12-2 ALL keyword 11-31

Index X-7
DATASKIP configuration parameter (continued) DDL.
defined 11-29 See Data definition language.
DB_LIBRARY_PATH configuration parameter 2-10, 5-32 DEADLOCK_TIMEOUT configuration parameter 2-8, 23-20
DB_LOCALE environment variable 1-8 two-phase commit protocol 23-19
DBCREATE_PERMISSION configuration parameter 2-10, 5-6 DEALLOCATE COLLECTION statement 12-5
DBLANG environment variable 1-8 DEALLOCATE DESCRIPTOR statement 12-5
dbload utility 11-44 DEALLOCATE ROW statement 12-5
DBPATH environment variable Decision-support query
dbserver group 3-24 See also Parallel database query.
use in automatic redirection 20-14 DS_MAX_QUERIES configuration parameter 2-7
Dbserver group 3-22 DECLARE statement 12-5
DBSERVERALIASES configuration parameter 1-7, 2-2 DEF_TABLE_LOCKMODE configuration parameter 2-6, 8-13
defined 3-30 DEFAULT keyword
example 3-30 with SET DATASKIP 11-30
multiple connection types 3-34 Default locale xviii
sqlhosts file 3-16 Defaults
DBSERVERNAME configuration parameter 1-7, 2-2 configuration file 1-11, 4-4
associated protocol 6-21 role
defined 3-29 creating 5-6
sqlhosts file 3-16 granting privileges 5-6
syntax rules 3-16 using 5-6
virtual processor for poll thread 6-21 Deferred checking of constraints 12-2
[Link] file 1-9, 1-12 DELETE statements 12-4
dbspaces Deleting
adding log files 15-11
chunk 11-16 RAW tables 10-24
ISA, with 11-8 smart-large-object data 11-27, 11-28
mirrored chunk 19-6 STANDARD tables 10-24
backing up 11-8, 11-9 Denial-of-service flood attacks 5-7
creating 11-8, 11-11 Dependencies, software xviii
initial dbspace 10-11 DES.
temporary 11-15 See Data Encryption Standard.
using onspaces 11-9 DES3.
creating initial dbspace 1-16 See Triple Data Encryption Standard.
defined 10-9 DESCRIBE statement 12-5
dropping Device
chunk 11-25 character-special 10-4
ON-Monitor utility 11-28 NFS 10-3
onspaces 11-28 when offsets are needed 11-4
overview 11-27 Diagnostic information
link between logical and physical units of storage 10-9 collecting 22-6
mirroring if logical-log files included 18-4 disk space restraints 22-7
monitoring simple large objects 11-38 parameters to set 22-6
names 11-7 Diagnostic messages.
non-default page sizes in HDR environment 21-4 See Message log.
page size, specifying 11-12 Dictionary cache 8-19
purpose of 10-9 DIRECTIVES configuration parameter 2-9
renaming 11-17 Directories
restrictions, adding logs 15-10 NFS 10-3
restrictions, moving logs 15-12 Dirty buffer, defined 8-26
root 10-11 Dirty Read isolation level 20-21
root dbspace defined 10-11 Disabilities, visual
shared-memory table 8-16 reading syntax diagrams A-1
smart large objects 10-8 Disabling I/O error
specifying page size when creating 11-11 destructive versus nondestructive 22-7
table monitoring with
defined 8-16 event alarms 22-8
dropping 11-27 message log 22-8
metadata 8-16 when they occur 22-7
temporary 10-11 DISCONNECT statement 12-5
DBSPACETEMP configuration parameter 2-3, 10-26, 11-16 Disk allocation 1-6
defining temporary tables 10-34 Disk configuration 1-3
load balancing 10-34 Disk contention
DBSPACETEMP environment variable 10-26, 11-16 reducing 10-33
DD_HASHMAX configuration parameter 2-5 Disk I/O
DD_HASHSIZE configuration parameter 2-5 buffers 11-14
errors during processing 22-5

X-8 IBM Informix Dynamic Server Administrator’s Guide

Disk I/O (continued) DRAUTO configuration parameter 2-8
kernel asynchronous I/O 6-17 role in recovering from data-replication failure 20-11,
logical log 6-17 20-12, 21-19
operating system I/O 10-4 DRIDXAUTO configuration parameter 2-8, 21-12, 21-13
physical log 6-17 DRINTERVAL configuration parameter 2-8
priorities 6-18 setting for
queues 6-20 asynchronous updating 20-8
raw I/O 10-4 synchronous updating 20-7
reads from mirror chunks 18-5 DRLOSTFOUND configuration parameter 2-8, 20-8
role of shared memory in reducing 8-2 DROP ACCESS_METHOD statement 12-4
smart large objects 10-13 DROP AGGREGATE statement 12-4
virtual processor classes 6-17 DROP CAST statement 12-4
writes to mirrored chunks 18-5 DROP DATABASE statement 12-4
Disk layout DROP FUNCTION statement 12-4
logical volume managers 10-38 DROP INDEX statement 12-4
mirroring 10-34 DROP OPCLASS statement 12-4
optimum performance 10-33 DROP PROCEDURE statement 12-4
sample disk layouts 10-35 DROP ROLE statement 12-4
table isolation 10-34 DROP ROUTINE statement 12-4
trade-offs 10-35 DROP ROW TYPE statement 12-4
Disk management 1-6 DROP SEQUENCE statement 12-4
Disk page DROP SYNONYM statement 12-4
before-images in physical log 8-26 DROP TABLE statement 12-4
read ahead 8-25 DROP TRIGGER statement 12-4
Disk space DROP TYPE statement 12-4
allocating DROP VIEW statement 12-4
cooked file space 11-4 DROP XADATASOURCE statement 12-4
on Windows 11-6 DROP XADATASOURCE TYPE statement 12-4
raw disk space 11-5 Dropping
chunk pathnames, offsets 11-4 chunk from dbspace 11-25
chunk, maximum size 1-16, 11-7 extspaces 11-29
creating a link to chunk pathname 1-6, 11-5 sbspaces 11-27
defined 11-3 storage spaces 11-27
estimating size 10-31 tables in dbspaces 11-27
initialization 1-14, 4-2, 4-3, 4-5 DRTIMEOUT configuration parameter 2-8, 21-13
layout guidelines 10-33 detecting data replication failures 20-11
middle partitions 10-34 DS_HASHSIZE configuration parameter 8-19, 9-5
monitoring with ISA 11-35 DS_MAX_QUERIES configuration parameter 2-7
requirements 10-33 DS_MAX_SCANS configuration parameter 2-7
storing TEXT and BYTE data 11-21 DS_NONPDQ_QUERY_MEM configuration parameter 2-7,
tracking usage by tblspace 10-28 8-14
Distributed databases 1-20 DS_POOLSIZE configuration parameter 8-19, 9-5
Distributed processing 23-2 DS_TOTAL_MEMORY configuration parameter 2-7, 8-14
Distributed queries DSS application.
defined 1-20 See Decision-support query.
sqlhosts setup 1-10 DTP.
two-phase commit 1-20 See Distributed transaction.
Distributed transactions 12-2 DUMPCNT configuration parameter 2-9, 22-6
determining if inconsistently implemented 24-2 DUMPCORE configuration parameter 2-9, 22-6
two-phase commit protocol 23-5 DUMPDIR configuration parameter 2-9, 22-4, 22-6
unbuffered logging 12-7 DUMPGCORE configuration parameter 2-9, 22-4, 22-6
Distribution statistics 8-19 DUMPSHMEM configuration parameter 2-9, 22-4, 22-6
Documentation conventions xxiii Dynamic Host Configuration Product 3-10
Documentation Notes xxix Dynamic lock allocation 8-13
Documentation set of all manuals xxxi Dynamic log allocation
Documentation, types of xxviii defined 15-8
machine notes xxix event alarms and messages 15-14
online manuals xxx location of files 15-9
printed manuals xxxi log file size 15-9
Domain overview 1-19
Windows Dynamic Server
controller 3-3 service 1-14
defined 3-3 DYNAMIC_LOGS configuration parameter 2-3
running as the specified user 1-24 adding log files 15-10, 15-15
trusted 3-3 editing value 15-13
user accounts 3-3, 3-4 enabling and disabling 15-8
Dotted decimal format of syntax diagrams A-1

Index X-9
E Error messages xxx
for server utilities security check 5-3
Editing I/O errors on a chunk 22-5
ONCONFIG file 1-12 two-phase commit protocol 23-15
sqlhosts information ESQL/C
UNIX 1-10 accessing smart large objects 10-13, 10-19
Email ESQLMF environment variable 1-8
notification of event alarms 2-9 Event alarm
en_us.8859-1 locale xviii defined 1-21, 2-9
ENCCSM dynamically added logs 15-14, 15-15
Communication Support Modules, encryption 5-10 Event Viewer, Windows NT 1-24
ENCCSM_CIPHERS encryption parameter 5-16 Examples
ENCCSM_MAC encryption parameter 5-16 /etc/services file entry 3-9
ENCCSM_MACFILES encryption parameter 5-16 DBSERVERALIASES configuration parameter 3-30
ENCCSM_SWITCH encryption parameter 5-16 how page cleaning begins 8-24
ENCRYPT function 5-19 IPX/SPX connection 3-33
Encrypt virtual processor 6-26 local-loopback connection 3-32
Encrypting multiple connection types 3-34
column data 5-21 shared-memory connection 3-31
Encryption TCP/IP connection 3-33
column-level 5-19, 5-21 Exclusive lock
data transmissions 5-9 buffer 8-21
defined 5-8 EXECUTE FUNCTION statement 12-4
modes 5-9 EXECUTE IMMEDIATE statement 12-4
of data in a column 5-19, 5-21 EXECUTE PROCEDURE statement 12-4
of network data transmissions 5-10 EXECUTE statement 12-4
of passwords 5-9 EXT_DIRECTIVES configuration parameter 2-9
options in Dynamic Server 5-9 Extended data types
virtual processors 6-26 HDR replication 20-3
End-of-group option 3-22 Extension virtual processor.
Enterprise Replication 5-31 See User-defined virtual processor.
database logging 12-2 Extents
HDR, using with 20-5 allocating 10-8
RAW tables 10-24 defined 10-8
sbspaces 10-13 how database server allocates 10-9
specifying sbspaces 10-13 key concepts concerning 10-8
STANDARD tables 10-24 monitoring 11-36
TEMP tables 10-24 monitoring with sysextents 11-36
using database server groups 3-23 purpose 10-8
Environment relationship to chunk 10-8
configuration file 1-8 sbspaces 10-7, 10-16
control application 1-9 size for sbspaces 10-7, 10-15
Environment variables xxiv size for tblspace tblspace 11-10
.profile or .login file 1-8 size, initial 10-8, 10-16, 11-10
CLASSPATH 1-7, 1-9 size, next-extent 10-8, 10-16, 11-10
client applications 1-7 structure 10-8, 10-16
CLIENT_LOCALE 1-8 validating 22-3
DB_LOCALE 1-8 External backup
[Link] file 1-9 and restore
DBSPACETEMP 11-16 using when setting up HDR 21-6
environment-configuration file 1-8 External modules
[Link] and .informix files 1-8 security for loading 5-32
INFORMIXCONCSMCFG 5-10 External routines
INFORMIXDIR 1-7, 1-15 security for 5-32
INFORMIXSERVER 1-7 External space.
INFORMIXSHMBASE 8-6 See Extspace.
INFORMIXSQLHOSTS 1-10, 3-13 EXTSHMADD configuration parameter 2-5, 8-14
JVPHOME 1-7, 1-9 Extspace
LD_LIBRARY_PATH 1-9 creating 11-29
ONCONFIG 1-7, 2-11 dropping with onspaces 11-29
PATH 1-8, 1-15
required 1-7
sample setup file 1-9
SERVER_LOCALE 1-8 F
setting 1-7 Fast recovery 4-5, 4-8, 12-2
TERM 1-8 alternative options for fuzzy operations 16-17
TERMCAP 1-8 cleanup phase 15-10
TERMINFO 1-8 defined 1-19, 16-11

X-10 IBM Informix Dynamic Server Administrator’s Guide

Fast recovery (continued) Foreground write
details of process 16-12, 16-14 before-image 8-26
effects of buffered logging 16-12 defined 8-27
how database server detects need for 16-11 monitoring 8-27, 9-11
no logging 16-12 Formula
physical log overflow 16-12 logical-log size 15-2
purpose of 16-11 physical-log size 16-4
sbspaces 10-13 FQDN 3-11
smart large objects 10-20 Fragment
table types 10-25 monitoring
when occurs 16-11 disk usage 11-36
FAST_RESTART_CKPT_FUZZYLOG configuration I/O requests for 11-34
parameter 2-4, 16-17 over multiple disks 10-34
FAST_RESTART_PHYSLOG configuration parameter 2-4, skipping
16-17 inaccessible fragments 11-29
FAT. selected fragments 11-31
See File Allocation Table. unavailable fragments 11-31
Fault tolerance using DATASKIP 11-30
data replication 20-4 tables and indexes 10-23
fast recovery 16-11 Fragmentation.
Features See Fragment.
SQL enhancements xxii Free list.
Features in IDS 10.0 xix See Chunk, free list.
Features in IDS 9.21 xxiii FREE statement 12-5
Features in IDS 9.3 xxii FREE_RE log record 11-43
Features in IDS 9.4 xxi Freeing log files 15-5, 15-6
FETCH statement 12-5 Full checkpoint
FIFO/LRU queues defined 16-7
defined 8-21 emptying the physical log 16-11
specifying information 8-21 events that initiate 16-9
File Allocation Table flushing buffer pool 16-8, 16-10
partitions 1-6 forcing 17-5
File I/O. last available log 14-6
See Disk I/O. oldest update 16-9
Files fully qualified domain name (FQDN) 3-11
configuration 1-11 Fuzzy checkpoint
connectivity configuration 3-8 defined 16-7
cooked 1-6 during initialization 4-7
core 22-4 emptying the physical log 16-11
hosts 1-10 fast recovery 16-14, 16-16
[Link] 3-11 flushing buffer pool 16-8, 16-10
JVP properties 1-13 forcing 17-5
network configuration 1-10 how it works 16-9
network security 1-10, 3-11 logical-log buffer 8-11
NTFS 10-3 oldest update 14-6
oncfg_servername.servernum 4-6 physical logging 16-5, 16-7
ONCONFIG 1-11, 4-3, 4-4 physical-log buffer 8-27
passwd 1-10 Fuzzy operations
permissions 11-5 alternative fast recovery options 16-17
services 1-10 buffer pool 16-10
sqlhosts 1-10 defined 16-8
FILLFACTOR configuration parameter 2-3
Fixed and Known Defects File xxix
FLRU queues
See also LRU queues.
G
Gateway, IBM Informix, in heterogeneous commit 23-20
defined 8-22
gcore
how database server selects 8-23
file 22-4
FLUSH statement 12-4
utility 2-9
Flushing
GET DESCRIPTOR statement 12-5
before-images 8-26
GET DIAGNOSTICS statement 12-5
buffers 8-26
GL_DATE environment variable 1-8
data-replication buffer, maximum interval 2-8
GL_DATETIME environment variable 1-8
Forced residency
Global Language Support (GLS) xviii, 1-8
setting 4-6
Global pool, defined 8-20
Forcing a checkpoint.
Global transaction identifier 24-3
See Checkpoint, forced.
GLS.
See Global Language Support.

Index X-11
GLS8BITFSYS environment variable 1-8 High-Availability Data Replication (continued)
GRANT DEFAULT ROLE statement 5-7 DRTIMEOUT configuration parameter 20-11
GRANT ROLE statement 5-6 Enterprise Replication 20-5
GRANT statement 12-4 hardware and operating-system requirements 21-2
when granting privileges to DataBlade users 5-32 hdrmkpri and hdrmksec scripts 21-15
Group how it works 20-6
bargroup 1-6 how updates are replicated 20-6
database server 3-22, 3-23, 3-25, 5-5 initial replication 20-6
parallel processing of 6-6 lost-and-found transactions 20-8
GTRID 24-3 manual switchover 20-12, 20-13
monitoring status 21-15
performing DDL operations 20-22
H planning for 21-2
possible failures 20-10
Hardware mirroring 18-3
restarting after a corrupt index is detected 21-18
Hash table 8-16
restarting after failure 20-13, 21-18, 21-20
HDR.
restoring system after media failure 21-16, 21-17
See High-Availability Data Replication.
role of
hdrmkpri script 21-15
log records 20-6
hdrmksec script 21-15
primary database server 20-3
Heaps 8-18
secondary database server 20-3
Help xxxi
temporary dbspaces 20-22
HETERO_COMMIT configuration parameter 2-8, 23-21
setting
Heterogeneous commit 23-20, 23-21, 23-22, 23-25
database server type 21-14
Heuristic decision
setting up 21-2
independent action 23-9
starting 21-6
types of 23-10
synchronization 20-10
Heuristic end-transaction
synchronous updating 20-7
defined 23-12
types of data replicated 20-3
determining effects on transaction 24-2
UDRs, installing with 20-6
illustration and log records 23-18
UDTs, installing with 20-6
messages returned by 23-14
High-Performance Loader 10-24, 10-25
results of 23-14
HKEY_LOCAL_MACHINE registry 1-10
when necessary 23-13
host name field
Heuristic rollback
defined 3-18
defined 23-10
IPX/SPX 3-18
illustration and log records 23-17
multiple network interface cards 6-25
indications that rollback occurred 24-2
shared memory 3-18, 3-20
long transaction 23-14
syntax rules 3-18
monitoring, onstat -x 23-14
using IP addresses 3-25
results of 23-11
wildcard addressing 3-26
High-Availability Data Replication
Hostname
See also Data replication.
changing 1-25
actions to take if
hosts file 1-10, 3-9, 3-10
primary 20-12
[Link] file 3-11
secondary fails 20-12
Hot site backup.
administration 21-9
See Data replication.
advantages 20-3
Hot swap 18-3
asynchronous updating 20-8
HPL.
changing database server mode 21-13
See High-Performance Loader.
changing database server type 21-15
chunk status on secondary 21-11
client redirection
comparison of methods 20-20 I
DBPATH 20-14 I/O.
handling within an application 20-19 See Disk I/O.
INFORMIXSERVER 20-18 IBM Informix Client Software Developer’s Kit 23-2
sqlhosts file 20-15 IBM Informix ODBC Driver 23-2
configuring connectivity 21-3, 21-5 IBM Informix Server Administrator
data requirements 21-3 adding chunks 11-16, 11-23
DataBlade modules, installing with 20-6 adding mirrored chunks 19-6
defined 20-3 changing database server modes 4-9
description 20-2 changing operating modes 4-9
designing clients to use configuring sqlhosts 1-10
primary database server 20-20 creating
secondary database server 20-21 dbspaces 1-16, 11-8
detecting failures 20-11 sbspaces 11-23
DRINTERVAL configuration parameter 20-7, 20-8 creating dbspaces 1-16

X-12 IBM Informix Dynamic Server Administrator’s Guide

IBM Informix Server Administrator (continued) INFORMIXDIR/bin directory xix
database server modes 4-9 INFORMIXSERVER 1-7
database-logging status 13-4 INFORMIXSERVER environment variable
displaying logging status 13-6 client applications 3-24
editing sqlhosts file 1-10 defined 1-7
editing the configuration 2-11 use in client redirection 20-18
end mirroring 19-7 INFORMIXSHMBASE environment variable 8-6
executing utility commands 9-11 INFORMIXSQLHOSTS environment variable 1-10, 3-13, 3-14
monitoring disk storage 11-35 INFORMIXSTACKSIZE environment variable 8-18
monitoring latches or spin locks 9-8 Initial configuration
overview 1-21 creating storage spaces 1-16
recovering a down chunk 19-7 disk layout 10-33
Server Setup 1-12 guidelines for root dbspace 10-11
shared memory 9-5 Initial-extent size 10-8
start mirroring 19-5 Initializing
starting 1-12 checkpoint 4-7
user permissions 4-9 configuration files 4-3, 4-5
using onmode 21-13 conversion of internal files 4-5
viewing messages 1-21 disk space 1-14, 4-2, 4-3, 4-5
virtual processors 7-2 forced residency 4-6
IBM Informix Storage Manager 1-17 maximum connections 4-7
ID message log 4-6
in a logical log 14-2 shared memory 4-1, 4-3
Identifier option 3-24 SMI tables 4-6
IDS 10.0 steps in 4-3
features xix sysmaster database 4-6
IDS 9.21 sysutils database 4-7
features xxiii virtual processors 4-5
IDS 9.3 INSERT statements 12-4
features xxii Inserting data
IDS 9.4 RAW tables 10-24
features xxi STANDARD tables 10-24
[Link] script 1-14 Installation
IFX_EXTEND_ROLE configuration parameter 2-10, 5-32 MaxConnect 3-36
ifx_lo_copy function 10-20 sqlhosts registry 3-14
ifx_lo_specset_flags function 10-20, 11-25 Windows 1-6
Ill-behaved user-defined routine 6-16 Installation Guides xxviii
imc protocol subfield 3-17 Instance Manager 1-11, 1-12, 1-13
imcadmin command 3-36 [Link] 1-11
Impersonate, client 3-13 Integrity of communication messages 3-8
Inconsistency, detecting 22-2 Integrity, data.
Incremental backup See Consistency checking.
defined 1-17 Internet Protocol Version 6 3-28
Index Interprocess communications
fragmentation 10-23 in nettype field 3-17
parallel building 6-6 shared memory 8-2
R-Tree 16-4 IP address
tblspace 10-28 how to find 3-26
validating 22-3 use in hostname field 3-25
Industry standards, compliance with xxxiii IPC.
INFO statement 12-5 See Interprocess communications.
Informix Dynamic Server documentation set xxxi ipcshm protocol and communications portion, shared
informix user memory 8-20
changing password 1-24 IPv4 addresses 3-28
managing log files 15-1 IPv6 addresses 3-28
Informix-Admin group IPX/SPX
changing operating modes 4-9 in hostname field 3-33
file ownership 1-6 in servicename field 3-20
managing log files 15-1 service, defined 3-20
[Link] file 1-8 sqlhosts entry 3-33
INFORMIXCONCSMCFG environment variable 5-10 ISA.
INFORMIXDIR directory See IBM Informix Server Administrator.
respective permissions 5-4 ISM.
INFORMIXDIR environment variable See IBM Informix Storage Manager.
defined 1-7 ISO 8859-1 code set xviii
shutdown script 1-15 Isolating tables 10-34
startup script 1-15 [Link] 1-24

Index X-13
[Link] utility 1-24 Light appends (continued)
STANDARD tables 10-24
Light scans 8-17
J Lightweight I/O 8-11, 10-17
Lightweight processes 6-2
J/Foundation
Limits
configuring 1-13
chunk number 11-8
environment variables 1-9
chunk size 11-7
JDBC installation directory 1-7
CPU VPs 6-12
setting CLASSPATH 1-7
JVPs 6-17
JAR file 1-13
user-defined VPs 6-15
Java configuration parameters 1-13
Links
Java Development Kit
creating 11-5
[Link] file 1-7
LIO virtual processors 6-18
Java virtual processor 6-17
Listen threads
JDBC Driver 1-7
adding 6-24
JDK.
defined 6-22
See Java Development Kit.
multiple interface cards 6-25
Join
LISTEN_TIMEOUT configuration parameter 1-10, 2-10, 5-7
parallel processing 6-6
Listener threads 5-7
JVP properties file 1-13
LO_CREATE_LOG flag 10-21
JVPHOME environment variable 1-7, 1-9
LO_CREATE_NOLOG flag 10-21
LO_CREATE_TEMP flag 10-21, 11-25
LO_LOG flag 14-8
K LO_NOLOG flag 14-8
KAIO thread 6-17, 6-19 Load balancing
Keep-alive option 3-24 done by virtual processors 6-6
Kernel asynchronous I/O performance goal 10-33
defined 6-19 using DBSPACETEMP 10-34
nonlogging disk I/O 6-17 LOAD statement 11-44, 12-4
Kernel parameters Loading data
modifying 1-4 express mode 10-24, 10-25
Key value methods 11-44
shared memory 8-7 utilities 11-44
Keywords Local loopback
in syntax diagrams xxvii connection 3-7, 6-21
example 3-32
restriction 3-7
L Locales xviii
default xviii
Large-chunk mode 1-5
Lock table
Latch
configuration 8-13
See also Mutex.
contents of 8-13
monitoring statistics 9-8
defined 8-13
wait queue 6-11
LOCK TABLE statement 12-5
lchwaits field 9-8
Locking
LD_LIBRARY_PATH environment variable 1-9
Dirty Read isolation level 20-21
LDAP Authentication Support on Windows 5-25
sbspaces 10-17
LDAP module
smart large objects 10-13
application development 5-27
Locks
authentication 5-27
defined 8-20
client APIs 5-27, 5-30
dynamic allocation 8-13
compatibility issues 5-30
initial number 8-13
configuring 5-26
onstat -k 23-14
configuring Dynamic Server 5-26
types 8-21
distributed transactions 5-29
wait queue 6-11
distributes transactions 5-27
LOCKS configuration parameter 2-6
with data replication 5-27
Log position 23-14
LDAP server 5-25
LOGBUFF configuration parameter 2-3, 15-13
Level-0 backup
logical log buffers 8-12
checking consistency 22-5
smart large objects 8-31
Levels, backup
LOGFILES configuration parameter 2-3, 15-13
defined 1-17
editing ONCONFIG value 15-13
sbspaces 15-4
setting logical-log size 15-3
Licensed users, maximum allowed 4-3, 4-7
Logging
Light appends
See also Database logging status.
physical logging 11-27
activity that is always logged 12-3
RAW tables 10-24

X-14 IBM Informix Dynamic Server Administrator’s Guide

Logging (continued) Logical log buffer
altering a table to turn it off 13-5 checkpoints 8-11
altering a table to turn it on 13-5 defined 8-11
ANSI compliant databases 13-3 flushing
buffering transaction logging 12-6 defined 8-28
database server processes requiring 12-2 logical log buffer 8-28
displaying status with ISA 13-6 nonlogging databases 8-29
DTP environment 12-7 synchronizing 8-26
effect of buffering on logical log fill rate 14-4 unbuffered logging 8-29
Enterprise Replication 10-13, 12-2 when a checkpoint occurs 8-29
metadata and user data 10-20 when no before-image 8-29
physical logging logical log records 8-28
defined 16-2 monitoring 17-3
process 16-6 Logical log file
sizing guidelines 16-4 adding a log file
suppression in temporary dbspaces 10-12 using ON-Monitor 15-11
point-in-time restore 10-24 using onparams 15-10
process for adding log files manually 15-10
blobspace data 14-6, 14-7 allocating disk space for 14-3
dbspace data 14-9 backup
R-tree indexes 16-4 adding log files 15-10
RAW tables 10-24 changing physical schema 11-8
role in data replication 20-6 effect on performance 14-4
sbspaces 10-17, 14-7 free deleted blobpages 14-7
smart large objects 8-31, 10-21, 14-8 goals 15-3
STANDARD tables 10-24 cannot add to blobspace or sbspace 15-10
suppression for implicit tables 10-12 cannot add to dbspace with non-default page size 15-10,
table types 13-5 15-12
tables changing size 15-12
summary of 10-23 consequences of not freeing 14-5
TEXT and BYTE data 14-6 defined 12-1, 14-1
transaction logging defined 12-3 deleting 15-11
using transaction logging 12-5 dropping a log file
when to use logging tables 14-8 using ON-Monitor 15-12
Logging database using onparams 15-11
RAW tables 10-24 dynamic allocation
SQL statements defined 15-8
always logged 12-3, 12-4 file size 15-9
never logged 12-4 location of files 15-9
STANDARD tables 10-24 monitoring 15-14, 15-15
table types supported 10-23 size 15-9
LOGGING tag, onspaces 10-17 estimating number needed 14-4, 15-3
Logical consistency, defined 16-12, 16-14 event alarms 15-14, 15-15
Logical log freeing files 14-5, 15-5, 15-6
See also Logical log buffer; Logical log file. full checkpoint to free 17-5
administrative tasks 1-18, 14-6 I/O to 6-17, 6-18
backup LIO virtual processor 6-17, 6-18
checkpoints 16-11 location 14-2, 15-9
defined 1-17 log file number 14-2
schedule 1-17 log position 23-14
configuration parameters 15-13 Logical log file
defined 8-11, 12-1, 14-1 resizing 15-10
dynamic allocation 1-19 role in fast recovery 16-16
global transactions 23-4, 23-14 minimum and maximum sizes 14-3
log position 23-14 mirroring a dbspace that contains a file 18-4
logging smart large objects 15-3 moving to another dbspace 15-12
monitoring for fullness using onstat 15-6 role in fast recovery 16-12, 16-13, 16-14, 16-16
onlog utility 15-14 status
performance considerations 14-4 A 15-5, 15-10, 15-11, 15-12
record B 15-5, 15-6
database server processes requiring 12-2 C 15-6
SQL statements that generate 12-4 D 15-5, 15-11, 15-12
two-phase commit protocol 23-6, 23-15, 23-16 defined 14-3
size guidelines 14-3, 15-2 F 15-11, 15-12
types of records 8-11 L 15-6
validating 22-3 U 15-5, 15-6, 15-11, 15-12
switching 14-6, 15-4

Index X-15
Logical log file (continued) Manual recovery
switching to activate blobspaces 14-6 deciding if action needed 24-4
temporary 15-7 determining if data inconsistent 24-2
unique ID number 14-2 example 24-5
using SMI tables 15-7 obtaining information from logical-log files 24-3
Logical recovery, data replication 20-7 procedure to determine if necessary 24-1
Logical units of storage use of GTRID 24-3
list of 10-2 Mapping, bad sector 22-9
Logical volume manager MAX_INCOMPLETE_CONNECTIONS configuration
defined 10-37, 18-3 parameter 1-10, 2-10, 5-7
Logical volume or unit storage space MAX_PDQPRIORTY configuration parameter 2-7
defined 1-16 MaxConnect
Logical-log file. defined 3-35
See Logical log file. imc protocol subfield 3-17
Logid 14-2 imcadmin command 3-36
logposit field 23-14 installation 3-36
LOGSIZE configuration parameter 2-3, 15-13 monitoring 3-36
adding log files 15-10 onsocimc protocol 3-18
changing 15-13 ontliimc protocol 3-18
increasing log size 15-12 packet aggregation 3-36
logical-log size 15-2 Maximum
Long transaction chunk size 11-7
consequences 14-6 number of chunks 11-8
defined 14-5 number of storage spaces 11-8
heuristic rollback 23-14 user connections 4-3, 4-7
preventing 1-18 Media failure
two-phase commit 23-8, 23-11, 23-13 detecting 18-5
Loosely-coupled mode 23-4 recovering from 18-2
LRU queues Memory
buffer pool management 8-22 See also Shared memory.
configuring multiple 8-23 64-bit platforms 8-32
defined 8-21 adding a segment 9-7
FLRU queues 8-22 Message log
MLRU queues 8-22 data corruption 22-5
pages in least-recent order 8-22 defined 1-21
specifying information 8-21 during initialization 4-6
LRU write dynamically added logs 15-15
defined 8-28 metadata usage 11-43
monitoring 9-11 physical recovery 16-3
performing 8-28 viewing messages 1-21
triggering 8-28 Metadata
lru_max_dirty value 8-22, 8-24, 8-25, 11-14 allocating 11-23
example of use 8-24 calculating area 10-19, 11-23
lru_min_dirty value 8-22, 8-25, 11-14 chunks 11-24
in page cleaning 8-25 creating 10-16
lrus value 11-14 dbspace table 8-16
LTAPEBLK configuration parameter 2-4, 21-5 defined 8-31, 10-14
LTAPEDEV configuration parameter dropping sbspace chunks 11-27
Configuration parameters logging 16-4
LTAPEDEV 2-4 moving space from reserved area 11-43
LTAPESIZE configuration parameter 2-4, 21-5 sbspace logging 14-7
LTXEHWM configuration parameter 2-3, 23-10 sizing 10-16, 11-23
defined 15-13 temporary sbspace 10-19
preventing long transactions 15-16 validating 22-3
role in heuristic rollback 23-10 mi_lo_copy() function 10-20
LTXHWM configuration parameter 2-3 mi_lo_specset_flags() function 10-20, 11-25
defined 15-13 Microsoft Transaction Server 23-2
preventing long transactions 15-16 Mirror chunk
role in heuristic rollback 23-11 adding 19-6
LVM. changing status of 19-4
See Logical volume manager. creating 19-3
disk reads 18-5
disk writes 18-5
M recovering 18-4, 18-5, 19-4
structure 18-6
MAC key files 5-14
MIRROR configuration parameter 2-2
Mac tab 5-18
changing 19-2
Machine notes xxix

X-16 IBM Informix Dynamic Server Administrator’s Guide

MIRROR configuration parameter (continued) Mode (continued)
initial configuration value 19-2 quiescent to single-user 4-12
Mirror dbspace recovery 4-8
creating 11-6 reinitializing shared memory 4-10
root dbspace 10-11 shutdown 4-8
Mirroring single-user 4-8, 4-12
activity during processing 18-5 taking offline 4-13
alternatives 18-3 MODE ANSI keywords
benefits 18-2 database logging status 12-6
changing chunk status 19-4 Monitoring
chunk table 8-16 database server 1-21
chunks in HDR 21-11 extents 11-36
costs 18-2 global transactions 23-14
creating mirror chunks 19-3 licensed users 4-3, 4-7
defined 18-1 locks 23-14
detecting media failures 18-5 MaxConnect usage 3-36
during processing 18-5 memory size 9-3
during system initialization 19-4 metadata and user-data areas 11-43
enabling 19-2 number of users 16-4
ending 19-7 sbspaces 10-19, 11-40
hardware 18-3 spin locks 9-8
holding logical-log files in dbspace 18-4 SQL statement cache 9-6
hot swap 18-3 tblspaces 11-36
network restriction 18-1 user activity 23-14
overview 1-18 user connections 4-3, 4-7
recommended disk layout 10-34 Monitoring database server 1-22
recovering a chunk 19-4 blobspace storage 11-22
recovery activity 18-4 buffer-pool activity 9-11
split reads 18-5 buffers 9-9
starting 19-1, 19-3, 19-5, 19-6 checkpoints 17-4
status flags 18-4 chunks 11-33
steps required 19-1 configuration parameter values 2-11
stopping 19-7 data-replication status 21-15
when mirroring begins 18-4 databases 11-32, 13-5
when mirroring ends 18-6 disk I/O queues 6-20
MIRROROFFSET configuration parameter 2-3, 10-11 extents 11-36
when needed 11-4 fragmentation disk use 11-34, 11-36
MIRRORPATH configuration parameter 2-2, 10-11 global transactions 1-21
Miscellaneous virtual processor 6-26 latches 9-8
Mixed transaction result 23-12 length of disk I/O queues 6-20
MLRU queues log files 15-6
See also LRU queues. logging status 13-5
defined 8-22 logical-log buffers 17-3
end of cleaning 8-24 physical-log buffer 8-12, 17-3
ending page-cleaning 8-25 physical-log file 17-3
limiting number of pages 8-24 profile of activity 9-8
placing buffers 8-23 shared memory 9-8
Mode simple large objects in dbspaces 11-37, 11-38
adding log files 15-10 user threads 8-17
changing 4-8 using ON-Monitor 1-22
defined 4-7 using oncheck 1-22
dropping log files 15-11, 15-12 using onstat 1-23
graceful shutdown 4-11 using SMI tables 1-23
HDR server 20-2 virtual processors 7-5
immediate shutdown 4-12 Monitoring tools
moving log files 15-12 UNIX 1-23
offline 4-8 Windows Performance Monitor 1-24
offline from any mode 4-13 MSGPATH configuration parameter 1-22, 2-5
offline to online 4-10 MTS/XA 23-2
offline to quiescent 4-10 Multiple concurrent threads 6-8
offline to single-user 4-11 Multiple connection types
online 4-8 See also Connection
online to quiescent example 3-34
gracefully 4-11 sqlhosts 3-30
immediately 4-12 Multiple network interface cards 6-25
online to single-user 4-12 Multiple residency
quiescent 4-8 example 3-35

Index X-17
Multiplexed connection 3-4 NIS servers, effect on /etc/hosts and /etc/services 3-9
Multiprocessor computer Non-default page size
MULTIPROCESSOR configuration parameter 6-13 creating a buffer pool for 11-12
processor affinity 6-7 for a dbspace 11-11
MULTIPROCESSOR configuration parameter 2-7, 6-13, 7-2 in HDR environment 21-4
Multithreaded processes Nonfuzzy operations
defined 6-3 defined 16-8
OS resources 6-6 flushing buffer pool 16-8
Mutex flushing buffers 16-10
defined 6-12, 8-20, 8-21 Nonlogging database
synchronization 6-12 RAW tables 10-24
using 8-21 SQL statements
never logged 12-4
table types supported 10-23
N Nonlogging tables 10-23
Nonyielding virtual processor 6-16
Name
[Link] 1-25
storage spaces 11-7
NTFS files 10-3
Named-pipe connection
converting 1-6
defined 3-5, 3-7
Null file
platforms supported 3-5
creating 11-6
netrc file
NUMCPUVPS configuration parameter 6-13
defined 3-12
sqlhosts security options 3-24
NETTYPE configuration parameter 2-7, 3-30, 7-2
multiple network addresses 6-25 O
multiplexed connection 3-4 ODBC Driver 23-2
poll threads 6-21 OFF_RECVRY_THREADS configuration parameter 2-8, 20-10
purpose 3-30 Offline mode
role in specifying a protocol 6-21 defined 4-8
VP class entry 6-21 Offset
nettype field prevent overwriting partition information 10-5, 11-3
format 3-16 purpose 10-5
summary of values 3-18 subdividing partitions 11-3
syntax 3-16 when needed 11-3
using interface type 3-33 Oldest update, freeing logical-log file 14-3
NetWare file server 3-18 OLTP applications.
Network See Parallel database query.
configuration files 1-10 ON_RECVRY_THREADS configuration parameter 2-8
data encryption 5-19 ON-Bar utility
interface cards setting up 1-17
using 6-25 ON-Monitor utility
security files 1-10 adding
Network communication chunk 11-17
implementing 6-22 logical-log file 15-11
types 6-20 mirror chunks 19-6
using IPX/SPX 3-18, 3-20, 3-33 changing database server modes 4-10
using TCP/IP 3-18, 3-19 copying the configuration 2-11
Network data transmissions creating blobspaces 11-21
encryption of 5-10 creating dbspaces 11-9
Network Information Service 3-9 dropping a logical-log file 15-12
Network protocol dropping storage spaces 11-27, 11-28
defined 3-2 monitoring database server 1-22
Network protocols 6-21 recovering a chunk 19-7
Network security setting parameters
.netrc file 3-12 shared memory 9-6
files 3-11 virtual processors 7-3
[Link] 3-11 starting mirroring 19-5
Network virtual processors taking a chunk down 19-6
defined 6-20 oncfg_servername.servernum file 4-6
how many 6-22 oncheck utility
poll threads 6-21 -cc option 22-2
Network-protocol driver -cD option 22-3
defined 3-2 -ce option 22-2
New Technology File System 1-6 -cI option 22-2, 22-3
Next-extent -cr option 22-2
size 10-8 -cR option 22-2
NFS-mounted directory 10-3 -cs option 11-40, 11-42, 22-3

X-18 IBM Informix Dynamic Server Administrator’s Guide

oncheck utility (continued) onlog utility (continued)
-pB option 11-38 reconstructing a global transaction 24-3
-pe option 11-34, 11-40, 11-41 onmode -d index command 21-13
-pr option 2-11, 15-7, 16-4 onmode utility
-ps option 11-42, 22-2 -a option 9-7
-pS option 11-42 -c option 9-7
blobpage information 11-38 -d idxauto option 21-13
consistency checking 22-3 -e option 9-6
monitoring metadata and user-data areas 11-42 -O option 22-7
monitoring sbspaces 11-23, 11-40, 11-41 -W option 9-6
obtaining information -W parameters 9-6
blobspaces 11-34, 11-41 adding a segment 9-7
chunks 11-34 changing shared-memory residency 9-7
configuration 11-38 configuring SQL statement cache 9-6
extents and fragmentation 11-36 dropping CPU virtual processors 7-4
logical logs 15-7 ending
tblspaces 11-36 participant thread 23-10
validating session 24-1
data pages 22-2 transaction 23-9, 23-13
extents 22-2, 22-3 forcing a full checkpoint 11-27, 17-5, 21-11
indexes 22-3 freeing a logical-log file 15-6
logs and reserved pages 22-2 setting
metadata 22-2, 22-3 database server type 21-13
reserved pages 22-2 switching logical-log files 15-4
system catalog tables 22-2 user thread servicing requests from 6-3
ONCONFIG configuration file using in ISA 21-13
connectivity 1-11 onparams utility
defined 2-11 adding logical-log file 15-10
displaying with onstat -c 2-11 changing physical log
during initialization 4-3, 4-4 location 17-2
during server setup 1-12 size 17-2
editing 1-13 dropping a logical-log file 15-11
Java parameters 1-13 onperf utility 1-22
missing parameters 1-11 onpladm utility 11-44
multiple residency 3-35 onsocimc utility 3-18
parameters 1-11, 2-11 onspaces utility
preparing 1-11 -a option 11-23, 19-6
shared-memory connection 3-32 -c -b option 11-20
ONCONFIG environment variable -c -d option 11-9
defined 1-7 -c -S option 11-22
multiple database servers 1-15 -c -t option 11-16
setting 1-11 -c -x option 11-29
ONCONFIG file parameters. -ch option 10-15, 10-18, 11-24, 21-11
See Configuration parameter. -cl option 11-27
[Link] file 1-11 -d option 11-22, 11-28
[Link] file -Df tags 10-15, 11-26
buffer pool information 11-12 -f option 11-30
[Link] template file 1-7, 1-11 -g option 11-20
ondblog utility -k option 11-15
ANSI compliant database 13-4 -s option 10-14
changing logging mode -t option 10-34
ISA 13-2 -U option 11-24
ondblog utility 13-2 adding mirror chunks 11-23
ONDBSPACEDOWN configuration parameter 2-3 adding sbspace chunks 11-23
oninit utility change chunk status 21-11
-p option 4-6, 10-20 creating sbspaces 11-22
starting the database server 4-1, 4-2 creating temporary sbspace 10-19
temporary tables 10-28 defined 1-16
Online help xxxi dropping sbspace chunks 11-26
Online manuals xxx ending mirroring 19-7
Online mode modifying DATASKIP 11-30
defined 4-8 recovering a down chunk 19-6
Online notes xxviii, xxix taking a chunk down 19-6
Online transaction processing. onstat utility
See Parallel database query. -c option 2-11
onlog utility -d option 11-33, 11-40
displaying log records 15-14 -d update option 1-22, 11-33

Index X-19
onstat utility (continued) Optical Subsystem memory cache (continued)
-g ath option 7-5 session ID for user 11-37
-g cac option 9-6 size 11-37
-g glo option 7-5 user ID of client 3-21, 11-37
-g imc 3-36 Optical virtual processor 6-26
-g ioq option 7-5 Options field
-g rea option 7-6 buffer-size option 3-21
-g seg option 9-3 connection-redirection 3-22
-g smb c option 11-40, 11-44 CSM option 3-22
-g sql option 13-5 end-of-group 3-22
-g ssc options 9-6 group option 3-24
-g stm option 13-5 identifier option 3-24
-k option 23-14 keep-alive option 3-24
-l option 15-10 overview 3-20
-m option 1-22 security option 3-24
-p option 9-8 syntax rules 3-20
-s option 9-8 OUTPUT statement
-u option 6-3, 16-4, 23-14 logging 12-5
-x option 13-5, 23-14
CPU virtual processors 6-3
displaying
messages 1-22
P
Packet aggregation 3-36
monitoring
Page
blobspace 11-33
defined 10-5
buffer use 9-9, 9-10, 9-11
determining database server page size 11-21
buffer-pool 9-11
least-recently used 8-22
chunk status 11-33
most-recently used 8-23
configuration 2-11
relationship to chunk 10-5
data replication 21-15
specifying size for a standard or temporary dbspace 11-11
database server profile 9-8
PAGE_CONFIG reserved page 2-11, 4-5
fragment load 11-34
PAGE_PZERO reserved page 4-5
latches 9-8
Page-cleaner table
logical-log buffer 15-6, 17-3
defined 8-16
logical-log files 15-10, 17-4
number of entries 8-16
physical log 17-4
Page-cleaner threads
shared memory 9-8
alerted during foreground write 8-27
SQL statement cache 9-6
defined 8-26
SQL statements 13-5
flushing buffer pool 8-26
transactions 7-5
flushing of regular buffers 8-26
virtual processors 7-5
monitoring 8-16
overview 1-23
role in chunk write 8-28
profiling user activity 23-14
Pagermail
temporary sbspace flags 11-25
notification of event alarms 2-9
tracking
PAM.
global transaction 23-14
See Pluggable Authentication Module.
locks 23-14
Parallel database queries
updating blobpage statistics 11-33
Decision-support query
ontape utility
See DS_MAX_QUERIES configuration parameter.
alternative backup method 21-9
DS_MAX_QUERIES configuration parameter 2-7
backing up logical-log files 14-6
DS_NONPDQ_QUERY_MEM configuration
modifying database logging status 13-3
parameter 2-7, 8-14
setting up 1-17
DS_TOTAL_MEMORY configuration parameter 2-7, 8-14
ontliimc protocol 3-18
MAX_PDQPRIORTY configuration parameter 2-7
OPCACHEMAX configuration parameter 2-11, 11-37
Parallel processing
configuring memory 11-37
virtual processors 6-6
OPEN statement 12-5
Participant database server 23-6
Operating system
automatic recovery 23-7
32-bit and 64-bit versions 9-2
Partitions
parameters 9-2
creating and using 11-18
tools 1-23
creating in a fragmented table or index 11-19
Operating-system files.
creating in a previously defined table or index 11-19
See Cooked file space.
mentioning in ALTER FRAGMENT statement 11-19
OPTCOMPIND configuration parameter 2-7
Password Communication Support Module 5-12
Optical Subsystem memory cache
Password encryption 5-9
allocation 11-38
CSM configuration file 5-10, 5-12
kilobytes of TEXT and BYTE data written 11-37
database server initialization 5-11
number of objects written 2-11, 11-37, 11-38

X-20 IBM Informix Dynamic Server Administrator’s Guide

Passwords Physical log (continued)
changing for user informix 1-24 physical recovery messages 16-3
PATH environment variable 1-8, 1-15 reinitialize shared memory 17-1
shutdown script 1-15 role in fast recovery 16-6, 16-11, 16-12, 16-15
startup script 1-7, 1-15 sizing guidelines 16-5
PC_HASHSIZE configuration parameter 2-6, 8-20, 9-5 virtual processors 6-19
PC_POOLSIZE configuration parameter 2-6, 8-20, 9-5 when you have non-default page sizes 11-12
PDQ. where located 16-3
See Parallel database query. Physical logging
Performance activity logged 16-3
capturing data 1-22 backups 16-3
evaluating CPU VP 6-12 blobspace blobpages 16-6
how frequently buffers are flushed 8-23 data buffer 16-6
monitoring tool 1-24 defined 16-2
parameters, setting fast recovery 16-5
with ON-Monitor 9-6 fuzzy checkpoints 16-7
read-ahead 8-25 light appends 11-27
resident shared-memory 8-9 logging details 16-4
shared memory 3-6, 6-6, 8-2 smart large objects 16-3
VP-controlled context switching 6-9 Physical recovery messages 16-3
yielding functions 6-6 Physical units of storage, list 10-2
Performance enhancements Physical-log buffer
version 9.3 xxii checkpoints 8-27
Performance tuning dbspace logging 16-6
amount of data logged 16-3 defined 8-12
disk-layout guidelines 10-33 events that prompt flushing 8-26
foreground writes 8-27 flushing 8-12
logical volume managers 10-38 monitoring 17-3
logical-log size 14-4, 17-1 number 8-12
logical-log, relocating 17-1 PHYSBUFF configuration parameter 8-12
LRU write 8-28 PIO virtual processors
moving the physical log 17-1 defined 6-19
sample disk layout for optimal performance 10-36 how many 6-20
spreading data across multiple disks 10-38 PLOG_OVERFLOW_PATH configuration parameter 16-12
Performing Pluggable Authentication Module 5-23
DDL operations on primary server 20-22 application development 5-27
Permissions client APIs 5-30
for creating databases 5-6 compatibility issues 5-30
setting 1-6 configuring the server 5-25
PHYSBUFF configuration parameter 2-4, 8-12 defined 5-23
PHYSDBS configuration parameter 2-4, 17-2 distributed transactions 5-29
changing size and location 16-4 implicit connections 5-25
PHYSFILE configuration parameter 2-4, 16-4, 17-2 required stack size 5-24
Physical consistency supported platforms 5-24
defined 16-12, 16-14 Point-in-time restore
fast recovery 16-12 logging 10-24
Physical log Poll threads
backing up 11-8 connection 6-21
becoming full 16-5 DBSERVERNAME configuration parameter 6-22
before-image contents 16-6 defined 6-22
buffer 8-12, 16-6 how many 6-21
changing size and location message queues 6-23
possible methods 17-1 multiple for a protocol 6-21
reasons 17-2 nettype entry 6-21
restrictions 17-2 on CPU or network virtual processors 6-21
using a text editor 17-3 Post-decision phase 23-6
using ON-Monitor 17-3 Precommit phase 23-6
using onparams 17-2 PREPARE statement 12-5
contiguous space 17-2 Presumed-end optimization 23-8
ensuring does not become full 16-6 Primary chunk 10-3
flushing of buffer 16-7 Primary database server 20-3
how emptied 16-7 Printed manuals xxxi
I/O, virtual processors 6-19, 17-2 Priority
increasing size 11-12, 16-5, 17-3 aging, preventing 6-14
monitoring 17-3 disk I/O 6-18
overflow during fast recovery 16-12 Priority scheduling 1-12
overview 1-19

Index X-21
Processes Recovery (continued)
attaching to shared memory 8-6 mode
comparison to threads 6-6 defined 4-8
DSA versus dual process architecture 6-7 parallel processing 6-6
Processor affinity RAW tables 10-24
defined 6-14 STANDARD tables 10-24
using 6-14 two-phase commit protocol 23-5
Profile Redundant array of inexpensive disks 18-3
statistics 9-8 Referential constraint 10-24, 12-2
Program counter and thread data 8-18 Registry
Protocol changing the hostname 1-25
specifying 6-21 defining multiple network addresses 6-25
PSWDCSM. Regular buffers
See Password encryption. events that prompt flushing 8-26
PUT statement 12-4 Release Notes xxix
Remote
client 3-11
Q hosts and clients 3-11
RENAME COLUMN statement 12-4
Query plans 8-19
RENAME DATABASE statement 12-4
Queues
RENAME INDEX statement 12-4
defined 6-10
RENAME SEQUENCE statement 12-4
disk I/O 6-17
RENAME TABLE statement 12-4
ready 6-11
Renaming
sleep 6-11
database server instance 1-13
wait 6-11
dbspace 11-17
Quiescent mode 4-8
Replication servers.
See Data replication.
Requirements
R configuration 1-11
R-tree index Reserved area
logging 16-4 defined 10-14
RA_PAGES configuration parameter 2-6, 8-25 monitoring size 11-40, 11-44
RA_THRESHOLD configuration parameter 2-6, 8-25 moving space to metadata area 11-43
RAID. Reserved pages
See Redundant array of inexpensive disks. chunk status for secondary 21-11
Raw disk devices 1-5 validating 22-3
Raw disk space Residency.
allocating on UNIX 10-4, 11-5 See Multiple residency.
allocating on Windows 10-3 RESIDENT configuration parameter 2-6
character-special interface 10-4 during initialization 4-6
defined 10-4 setting with onmode 9-7
RAW table 1-18 Resident shared memory
altering 13-5 defined 4-4, 8-9, 8-10
backing up 10-25 internal tables 8-15
backup and restore 10-25 Resource manager 23-2
fast recovery 10-25 Resource managers 23-3
overview 10-24 Resource planning 1-3
properties 8-25 Restore
restore 10-26 RAW tables 10-24
Read-ahead STANDARD tables 10-24
defined 8-25 table types 10-26
RA_PAGES configuration parameter 8-25 Revectoring table 11-4
RA_THRESHOLD configuration parameter 8-25 REVOKE DEFAULT ROLE statement 5-7
when used 8-25 REVOKE FRAGMENT statement 12-4
Read-only mode REVOKE statement 12-4
defined 4-8 when granting privileges to DataBlade users 5-32
Ready queue Role
defined 6-10 creating 5-7
moving a thread 6-11, 20-7 default 5-6
Reception buffer 20-7 defined 5-7
Recommendations Roll back
allocation of disk space 10-5 fast recovery 16-13, 16-16
consistency checking 22-2 heuristic, monitoring 23-14
mirroring the physical log 16-4 RAW tables 10-24
Recovery smart large objects 10-21
from media failure 18-2 SQL statements logged 12-4

X-22 IBM Informix Dynamic Server Administrator’s Guide

Roll back (continued) sbspaces (continued)
STANDARD tables 10-20 temporary (continued)
Roll forward, fast recovery 16-13, 16-16 dropping chunks 10-20, 11-26
Root dbspace dropping sbpace 11-27
calculating size 10-31 example 11-25
default location 10-11, 10-26 LO_CREATE_TEMP flag 11-25
defined 10-11 user-data area 8-31, 10-14, 11-39
location of logical-log files 14-2 using onstat -g smb c 11-40, 11-44
mirroring 19-4 SBSPACETEMP configuration parameter 2-3, 10-19, 11-25
temporary tables 10-24, 10-28 Scans
ROOTNAME configuration parameter 2-2, 10-11 indexes 8-25
ROOTOFFSET configuration parameter 2-2, 10-11, 11-4 parallel processing 6-6
ROOTPATH configuration parameter 2-2, 10-11 sequential tables 8-25
ROOTSIZE configuration parameter 2-2 Scheduling
priority 1-13
Screen reader
S reading syntax diagrams A-1
Secondary database server 20-3, 21-11
Sample-code conventions xxvii
Security
sbpage
auditing database events 5-6
defined 10-7
disabling server utilities check 5-3
sizing recommendations 10-7
encryption options 5-8
SBSPACENAME configuration parameter 2-3, 10-14, 10-19,
enhancements in version 10.0 xix
11-23
files for network 1-10
sbspaces
for DataBlade user-defined routines 5-32
adding chunks 10-19, 11-23
for external routines 5-32
allocating space 10-19
for loading external modules 5-32
altering storage characteristics 11-24
INFORMIXDIR directory permissions 5-4
backing up 10-19, 11-23, 11-24
options
buffering mode 10-16
sqlhosts 3-24
calculating metadata 10-19
Pluggable Authentication Module 5-23
characteristics 10-20
preventing denial-of-service flood attacks 5-7
checking consistency 10-20
risks with shared-memory communications 3-6
creating
server utilities check before starting on UNIX 5-2, 5-3
using ISA 11-23
through LDAP Authentication Support 5-25
using onspaces 11-22
through roles 5-6
defined 10-13
using column-level encryption 5-19
defining replication server 10-13
using Communication Support Modules 5-9
disk structures 10-18
security option 5-31
dropping
SECURITY_LOCALCONNECTION configuration
CLOB and BLOB columns 11-27
parameter 2-10, 5-5
using onspaces 11-27
Segment identifier 8-7
Enterprise Replication 10-13
Segment.
fast recovery 10-13
See Chunk.
incremental backups 15-4
SELECT INTO TEMP statement 12-4
JAR files 1-13
SELECT statements 12-5
last-access time 10-17
Semaphores, UNIX parameters 9-3
lightweight I/O 8-11, 10-17
Server Setup 1-12
locking 10-17
customizing configuration 1-12
logging 10-17, 14-7
SERVER_LOCALE environment variable 1-8
metadata 8-31, 10-14, 10-16
SERVERNUM configuration parameter 2-2
mirroring 11-22
defined 8-7
moving space from reserved area 11-43
using 8-7
names 11-7
Service
recoverability 10-13
IPX/SPX 3-20
reserved area 10-14
Service name field in sqlhosts
restrictions
defined 3-19
adding logs 15-10
IPX/SPX 3-20
sbpages 10-7
shared memory 3-19
sizing metadata 11-23
stream pipes 3-19
specifying storage characteristics 10-15, 11-22
syntax rules 3-18
statistics for user-defined data 2-3
services file 1-10, 3-10
storing smart large objects 8-31, 10-13
Session
temporary
active tblspace 8-16
adding chunks 10-20, 11-23
control block 6-8
backup and restore 10-20
defined 6-8
creating 11-25
dictionary cache 8-19
defined 10-19

Index X-23
Session (continued) Shared memory (continued)
locks 8-13 monitoring
primary thread 8-18 ISA 9-5
shared memory 8-18 onstat utility 9-8
shared-memory pool 8-14 mutex 8-21
sqlexec threads 6-3 nonresident portion 9-4
threads 8-18 operating-system segments 8-4
UDR cache 8-20 overview 1-19
Session control block 6-8 page-cleaner table 8-16
defined 8-18 performance options 8-2, 9-6
shared memory 8-18 physical-log buffer 8-12
SET ... statement 12-5 pools 8-14
SET DATASKIP statement 11-29, 11-30 portions 8-3
SET ENCRYPTION PASSWORD statement 5-19 purpose 8-2
SET ROLE DEFAULT statement 5-7 resident portion
SET statement 5-6 creating 4-4
[Link] file 1-9 defined 8-10
Setnet32 utility 1-10 ISA 9-5
Setting up ON-Monitor utility 9-6
environment variables 1-9 text editor 9-5
ON-Bar utility 1-17 segment identifier 8-7
ontape utility 1-17 semaphore guidelines 9-3
Share lock SERVERNUM configuration parameter 8-7
defined 8-21 session control block 8-18
Shared data 8-2 setting up 9-7
Shared memory SHMADD configuration parameter 8-14
allocating 1-4, 4-4, 8-14 SHMBASE configuration parameter 2-5, 8-7
attaching 8-6 SHMTOTAL configuration parameter 2-5, 8-5
attaching additional segments 8-7, 8-8, 9-5 SHMVIRTSIZE configuration parameter 2-5, 8-14
attaching utilities 8-6 size
blobpages 8-29 displayed by onstat 8-4
buffer 11-14 virtual portion 8-14
buffer allocation 8-10 smart large objects 8-31, 10-18
buffer hash table 8-16 sorting 8-19
buffer locks 8-21 SQL statement cache 2-6, 8-4, 8-19, 9-6
buffer pool 8-10, 16-6 stacks 8-18
buffer table 8-15 STACKSIZE configuration parameter 8-18
changing residency with onmode 9-7 synchronizing buffer flushing 8-26
checkpoint 16-7 tables 8-15
chunk table 8-16 tblspace table 8-16
communications 3-18, 3-20, 8-20 thread control block 8-18
configuration 8-4, 8-14, 9-2 thread data 8-18
configuration parameters 2-6 thread isolation and buffer locks 8-21
connection 6-21 transaction table 8-17
contents 8-20 user table 8-17
copying to a file 9-8 user-defined routine cache 8-20
critical sections 16-2 virtual portion 8-13, 8-15, 9-6, 9-8
data-distribution cache 8-19 ISA 9-5
data-replication buffer 20-7 Shared-memory connection
dbspace table 8-16 example 3-31
defined 8-2 how a client attaches 8-6
dictionary cache 8-19, 9-5 message buffers 8-20
effect of operating-system parameters 9-2 servicename field 3-19
first segment 8-7 virtual processor 6-21
global pool 8-20 SHMADD configuration parameter 2-5, 8-14
header 8-8, 8-10 SHMBASE configuration parameter
heaps 8-18 attaching first shared-memory segment 8-7
identifier 8-7 defined 2-5, 8-7
initializing 4-1, 4-3 setting higher 9-3
initializing or restarting 4-4 shmem file
internal tables 8-15 assertion failures 22-4
interprocess communication 8-2 shmkey
key value 8-7 attaching additional segments 8-8
logical-log buffer 8-11 defined 8-7
lower-boundary address problem 8-8 SHMTOTAL configuration parameter 2-5, 8-5
mirror chunk table 8-16 SHMVIRTSIZE configuration parameter 2-5, 8-14

X-24 IBM Informix Dynamic Server Administrator’s Guide

Shutdown Smart large objects (continued)
automatically 1-15 storage characteristics 10-14, 10-15, 11-24
graceful 4-11 turning logging on or off 14-7
immediate 4-12, 4-13 user data 10-13
mode using logging 14-8
defined 4-8 SMI tables
taking offline 4-13 [Link] 5-12
Shutdown script 1-14 during initialization 4-6
Simple large objects monitoring
See also TEXT and BYTE data. buffer information 9-10
buffers 8-30 buffer pool 9-9, 17-6
creating in a blobspace 8-30 buffer use 11-36
descriptor 8-31 checkpoints 17-6
illustration of blobspace storage 8-31 chunks 11-32
writing to disk 8-30 data replication 21-16
Simple Password Communication Support Module databases 9-9, 11-32, 13-6
CSM configuration file 5-12 extents 11-36
Single processor computer 2-7, 6-13 latches 9-9
SINGLE_CPU_VP configuration parameter 2-7, 6-13, 7-2 log buffer use 17-6
single processor computer 6-13 logical-log files 15-7
Single-user mode 4-8, 4-11, 4-12 mutexes 9-9
for HDR pair 21-14 shared memory 9-9
Sizing guidelines tblspaces 11-36
logical log 14-3, 15-2, 15-10 virtual processors 7-6
physical log 16-5 write types 9-12
Skipping fragments preparation during initialization 4-6
all fragments 11-29 sysextents 11-36
all unavailable 11-31 systabnames 11-36
effect on transactions 11-31 using to monitor database server 1-23
selected fragments 11-31 Socket 3-5
using features 11-30 in nettype field 3-17
Sleep queues, defined 6-11 Software dependencies xviii
Sleeping threads Sorting
forever 6-11 parallel process 6-6
types 6-11 shared memory 8-19
Smart large objects Spin locks
accessing in applications 10-19 monitoring 9-8
AVG_LO_SIZE 10-16, 11-23 SPL routines
buffering 10-16 cache
mode 8-31 See UDR cache.
recommendation 8-29 PC_HASHSIZE configuration parameter 2-6
byte-range locking 8-13 PC_POOLSIZE configuration parameter 2-6
calculating average LO size 10-16 specifying pool size 8-20
calculating extent size 10-8, 11-23 UDR cache hash size 2-6, 8-20, 9-5
creating 10-14, 14-8 Split read 18-2, 18-5
data retrieval 10-13 SPWDCSM 5-9
dbspaces 10-8 SQL code xxvii
defined 10-13 SQL Enhancements xxii
deleting CLOB or BLOB data 11-27 SQL statement cache
deleting, reference count of 0 11-27 configuring 9-6
Enterprise Replication use 10-13 defined 8-19
estimated size 11-24 monitoring 9-6
extents and chunks 10-8 overview 2-6
I/O properties 10-14 shared-memory location 8-14
last-access time 10-17 specifying size 2-6
lightweight I/O 8-11, 10-17 SQL statements
LO_CREATE_TEMP flag 10-20 ALTER TABLE 10-8
locking 10-13, 10-17 always logged 12-3
logging 10-17, 14-7 create dbspace 10-14
memory 10-18 CREATE ROLE 5-6
metadata 10-13 CREATE TABLE 10-9
physical logging 16-4 CREATE TABLE, PUT clause 10-14
sbpages 10-7 DECLARE 12-4
shared-memory buffer 8-31 GRANT DEFAULT ROLE 5-7
sizing metadata area 11-43 GRANT ROLE 5-6
specifying data types 10-14 initial connection to database server 1-15
statistics for user-defined data 2-3 logging databases 12-4

Index X-25
SQL statements (continued) Statistics.
monitoring 13-5 See onstat utility.
new features xxii Status
not logged 12-4 log file
parsing and optimizing 9-6 added 15-5, 15-6, 15-11
REVOKE DEFAULT ROLE 5-7 backed up 15-6, 15-11
SET ROLE 5-6 checkpoint 15-12
SET ROLE DEFAULT 5-7 current 15-5
UPDATE STATISTICS 8-19 deleted 15-6, 15-11, 15-12
using temporary disk space 10-26 free 15-5, 15-12
sqlexec thread used 2-6, 15-5, 15-11
client application 6-22 STDIO value 21-9
role in client/server connection 6-22 STMT_CACHE configuration parameter 2-6, 9-6
user thread 6-3 STMT_CACHE_HITS configuration parameter 2-6, 9-6
sqlhosts file STMT_CACHE_NOLIMIT configuration parameter 2-6, 9-6
connection type field 3-16 STMT_CACHE_NUMPOOL configuration parameter 2-6, 9-6
CSM option 3-20 STMT_CACHE_SIZE configuration parameter 2-6, 9-6
dbservername field 3-16, 3-23 Storage characteristics
defined 3-22 hierarchy 10-17
defining multiple network addresses 6-25 onspaces -ch 10-15, 11-24
editing with ISA 1-10 onspaces -Df 11-22
end of group option 3-22 sbspaces 10-16
entries for multiple interface cards 6-25 smart large objects 10-16, 11-24
group option 3-24 storage spaces 1-17
host name field 3-18 Storage devices
identifier option 3-22 setup 1-17
keep-alive option 3-24 Storage manager
local-loopback example 3-32 ISM 1-17
multiple connection types example 3-33 role in ON-Bar system 1-17
multiplexed connection 3-4 Storage spaces
network connection example 3-33 backup schedule 1-17
options field 3-19 ending mirroring 19-7
security options 3-24 starting mirroring 19-4
service name field 3-19, 6-22 storing NTFS partitions 1-6
shared-memory example 3-31 Storage statistics
specifying network poll threads 6-21 blobspaces 11-22
sqlhosts registry Stored procedure.
defined 3-14 See SPL routine.
INFORMIXSQLHOSTS environment variable 3-14 Stored-procedure cache.
location 3-14 See UDR cache.
on Windows 1-10 stores_demo database xix
Stack Stream-pipe connection
and thread control block 6-10 advantages and disadvantages 3-7
defined 6-9, 8-18 servicename field 3-19
INFORMIXSTACKSIZE environment variable 8-18 Structured Query Language
pointer 6-10 See SQL statements.
size 2-6, 8-18 superstores_demo database xix
STACKSIZE configuration parameter 8-18 Swapping memory 8-9
thread 8-18 Switch tab 5-19
STACKSIZE configuration parameter 2-6 Switching
changing the stack size 8-18 between threads 6-10
defined 8-18 next log file 15-4
STAGEBLOB configuration parameter 2-11 Sync checkpoint.
Standard database server 20-3 See Checkpoint.
STANDARD table Syntax diagrams
allowed in logging database 1-18 conventions for xxiv
backup 10-25 keywords in xxvii
fast recovery 10-25 reading in a screen reader A-1
properties 10-24 variables in xxvii
restore 10-25, 10-26 Syntax segment xxvi
Starting the database server sysdistrib table 1-23, 8-19
automatically 1-15 syslogs table 15-7
initializing disk space 1-14 sysmaster database
with oninit 4-1 See also SMI table
starts dbservername command 1-14 creation 4-6
Startup script 1-14 SMI tables 1-23
sysprofile table 9-9

X-26 IBM Informix Dynamic Server Administrator’s Guide

sysroleauth table 5-32 TCP/IP communication protocol (continued)
SYSSBSPACENAME configuration parameter 2-3 listen port number 3-28
systables service name field 3-19
flag values 10-23 using
System catalog tables [Link] 3-10
dictionary cache 8-19 internet IP address 3-28
location 10-21 IPX/SPX 3-33
optimal storage 10-36 multiple ports 3-10
sysdistrib 8-19 TCP listen port number 3-28
validating 22-2 wildcards 3-26
System console 1-23 TCP/IP connectivity files 3-8
System failure TEMP table 1-18
effect on database 16-11 restore 10-26
System requirements Temporary dbspace
database xviii amount required for temporary tables 10-32, 20-22
software xviii creating 11-15
System timer 6-11 data replication 20-21, 21-4
System-monitoring interface. DBSPACETEMP 10-26
See SMI table. defined 11-16
sysutils database Temporary logical logs 15-7
creating 4-7 Temporary sbspace
sysvpprof table 7-6 adding chunks 10-19, 11-25
backup and restore 10-20
characteristics 10-19
T creating 11-25
defined 10-19
Table
dropping chunks 10-20, 11-25
creating with CLOB or BLOB data types 10-19
dropping sbspace 11-27
defined 10-22
example 11-25
disk-layout guidelines 10-34
LO_CREATE_TEMP flag 11-25
dropping 11-27
Temporary smart large object
extent 10-8, 10-22
creating 10-20
fragmentation 10-24
defined 10-20
isolating high-use 10-34
Temporary tables
middle partitions of disks 10-36
backup 10-26
standard 10-24
Enterprise Replication 10-24
storage considerations 10-33
restore 10-24
temporary
smart large object, temporary 10-19
cleanup during restart 10-28
TERM environment variable 1-8
estimating disk space 10-32
TERMCAP environment variable 1-8
Table types
Terminal interface 1-8
backing up before converting 11-8
TERMINFO environment variable 1-8
fast recovery 10-25
TEXT and BYTE data
flag values in systables 10-24
See also Simple large object.
in logging databases 1-18
absence of compression 11-44
properties 10-26
loading 11-44
RAW 10-23, 13-5
monitoring in a dbspace 11-38
restoring 10-26
writing to a blobspace 8-29
STANDARD 10-23, 13-5
TEXT data type.
summary 10-24
See TEXT and BYTE data.
tail -f command 1-22
Text editor
TAPEBLK configuration parameter 2-4, 21-5
creating ONCONFIG file 1-11, 7-1
TAPEDEV configuration parameter 2-4, 21-9
setting configuration parameters
TAPESIZE configuration parameter 2-4, 21-5
performance 9-5
Tblspace
shared memory 9-5
contents of table 8-16
virtual processors 7-2
defined 10-28
Thread control block
drop temporary 4-6
creation 8-18
monitoring
role in context switching 8-18
systabnames 11-36
Thread-safe virtual processor 6-4
size, extent, for tblspace tblspace 11-10
Threads
temporary, during server restart 4-6
access to resources 6-8
types of pages contained 10-28
accessing shared buffers 8-21
TBLTBLFIRST configuration parameter 2-2, 10-11, 11-10
B-tree scanner 6-3
TBLTBLNEXT configuration parameter 2-2, 3-28, 10-11, 11-10
client applications 6-3
TCP connections 6-21
concurrency control 8-20
TCP/IP communication protocol
context 6-8
host name field 3-18

Index X-27
Threads (continued) Two-phase commit protocol (continued)
control block 6-8 automatic recovery (continued)
defined 6-3 participant recovery 23-7
heaps 8-18 configuration parameters 23-19
how virtual processors service 6-19 contrast with heterogeneous commit 23-20
internal 6-3, 6-12 coordinator recovery 23-5
kernel asynchronous I/O 6-19 DEADLOCK_TIMEOUT 23-20
migrating 6-10 defined 23-5
mirroring 6-3 distributed queries 1-20
multiple concurrent 6-8 errors messages 23-15
onmode 6-3 flushing logical log records 23-16
page cleaner 6-2, 6-3, 8-16 global transaction ended prematurely 24-1
primary session 8-18 global transaction identifier 24-3
recovery 6-3 heuristic decisions
relationship to a process 6-3, 6-12 heuristic end-transaction 23-12
scheduling and synchronizing 6-8 heuristic rollback 23-10
session 6-10, 8-18 types 23-8
sleeping 6-11 independent action 23-8
stacks 8-18 defined 23-8
switching between 6-8 errors 23-9
user 6-3, 8-18 initiating 23-8
waking up 6-9 results 23-9
yielding 6-8 logical-log records 23-10
Tightly-coupled mode 23-6 messages 23-6
TLI. overview 1-20
See Transport-layer interface. participant activity 23-6
TOC Notes xxix participant recovery 23-7
TP/XA 1-21, 8-17, 23-2 postdecision phase 23-7
Transaction branch 23-6 precommit phase 23-7
Transaction logging presumed-end optimization 23-7, 23-8
See also Logging. role of current server 23-6
buffered 12-5 TXTIMEOUT configuration parameter 23-20
defined 12-3, 12-5 when used 23-5
Enterprise Replication 10-13 TXTIMEOUT configuration parameter 2-8, 23-13, 23-20
unbuffered 12-5 defined 23-20
when to use 12-5 onmode -Z 23-13
Transaction manager two-phase commit protocol 23-19
MTS/XA 23-2 Types of buffer writes 8-27
purpose 23-2 Typographical conventions xxiv
TP/XA 1-21, 23-2
Transaction table
defined 8-17
tracking with onstat 8-17
U
UDR cache 8-20
Transactions
Unbuffered disk access
global
compared to buffered 10-4
defined 23-2, 23-6
data storage 10-4
determining if implemented consistently 24-1
Unbuffered logging
identification number, GTRID 24-3
flushing the logical-log buffer 8-29
tracking 13-5, 23-14
Unbuffered transaction logging.
loosely coupled 23-4
See Logging.
mixed result 23-12
Units of storage 10-2
monitoring 13-5, 23-6, 23-14
UNIX devices
RAW tables 10-24
displaying links to a pathname 1-6, 11-5
tightly coupled 23-4
ownership, permissions on
Transport-layer interface
character-special 11-5
in nettype field 3-17
cooked files 11-5
Triple Data Encryption Standard 5-9
UNIX operating system
Trusted
link command 1-6, 11-5
clients 3-3
modifying kernel 1-4
database server 3-3
setting environment variables 1-8
domain 3-3
shutdown script 1-14
Windows domains 3-3
startup script 1-14
Trusted domain 23-7
UNLOAD statement 12-4
Two-phase commit protocol
UNLOCK TABLE statement 12-5
automatic recovery 23-7
UNSECURE_ONSTAT configuration parameter 2-10, 5-33
administrator’s role 23-7
UPDATE statements 12-4
coordinator recovery 23-7
UPDATE STATISTICS statement 2-3, 8-19, 10-24

X-28 IBM Informix Dynamic Server Administrator’s Guide

Updating data Virtual portion
RAW tables 10-24 shared memory
STANDARD tables 10-24 adding a segment 9-7
Usability enhancements configuration 8-15
version 10.0 xix contents 8-15
version 9.4 xxi data-distribution cache 8-19
USEOSTIME configuration parameter 2-8 global pool 8-20
User accounts and Windows domains 3-3 SHMVIRTSIZE configuration parameter 8-14
User connections SQL statement cache 8-19
monitoring 4-7 stacks 8-18
User data UDR cache 8-20
creating 3-13 virtual extension portion 8-3
defined 10-14 Virtual processors
User impersonation 3-13 access to shared memory 8-4
User table adding and dropping
defined 8-17 ISA 7-2
maximum number of entries 8-17 ON-Monitor utility 7-3
User thread ADM class 6-11
acquiring a buffer 8-23 ADT class 6-26
critical sections 16-2 advantages 6-5
defined 6-3 AIO class 6-20, 8-7
monitoring 8-17 attaching to shared memory 8-7
tracking 8-17 binding to CPUs 6-7
User-data area, sbspace 8-31 classes 6-6, 6-12
User-defined routines context switching 6-8
configuring cache 8-20 coordination of access to resources 6-6
external 5-32 CPU class 6-6
ill-behaved 6-16 defined 6-2
Java 1-13 disk I/O 6-17
memory cache 8-20 dropping CPU in online mode 7-3, 7-4
nonyielding virtual processor 6-6 during initialization 4-5
parallel processing 6-6 encryption 6-26
registering 5-32 extension.
shared-memory location 6-15 See User-defined virtual processor.
virtual processors 6-13 LIO class 6-18
User-defined virtual processors logical-log I/O 6-18
how many 6-15 managing 1-19
purpose 6-16 monitoring
running UDRs 8-20 ISA 7-2
using 6-15 onstat utilities 7-5
using onperf 1-22 moving threads 6-3
Utilities MSC class 6-4
See also oncheck; ondblog; oninit; onlog; onmode; multithreaded process 6-5
onparams; onspaces; onstat; ontape; ON-Monitor. network 6-20
attaching to shared-memory 8-6 nonyielding 6-16
chkenv 1-9 OPT class 6-26
cron 1-23 overview 6-2
iostat 1-23 parallel processing 6-7
ISA 11-32 physical log I/O 6-19
onstat utility PIO class 6-10, 6-19
-d option 11-41 poll threads 6-21
ps 1-23 ready queue 6-10
sar 1-23 servicing threads 6-8
UNIX 1-23 setting configuration parameters 7-1
vmstat 1-23 sharing processing 6-6
UDR written in Java 6-17
user-defined class 6-15
V user-defined routine 6-4
using stacks 6-10
Validating
Visual disabilities
data pages 22-3
reading syntax diagrams A-1
extents 22-3
Volume table of contents 11-4
indexes 22-3
VP class in NETTYPE configuration parameter 6-21
logical logs 22-3
VPCLASS configuration parameter 2-7, 6-17, 7-2
metadata 22-3
configuring CPU VPs 6-12
reserved pages 22-3
JVPs 6-17
system catalog tables 22-2
user-defined VPs 6-16
Variables, in syntax diagrams xxvii

Index X-29
W
Wait queue
buffer locks 8-21
defined 6-11
Waking up threads 6-11
Warning messages
for server utilities security check 5-3
Warnings
files on NIS systems 3-9
oncheck -cc output 22-2
WHENEVER statement 12-5
Wildcard addressing
client application 3-26
example 3-28
hostname field 3-28
Windows
allocating raw disk space 11-6
automatic startup 1-14
configuring memory 1-4
converting to NTFS 1-6
Environment Variables control application 1-9
Event Viewer 1-24
ixpasswd utility 1-24
ixsu utility 1-24
larger shared memory 1-4
maximum address space 1-4
ntchname utility 1-25
setting environment variables 1-9
setting up connectivity 1-10
shared memory issues 9-3
Windows convert utility 1-6
Windows Instance Manager 1-12, 4-2
Windows Internet Name Service 3-10, 3-26
Windows Performance Monitor 1-24
Write types
chunk write 8-28
foreground write 8-27
LRU write 8-28

X
X/Open
DTP environment 8-17, 12-7
XA interface standards 23-3
XA data-source types 23-3
XA-compliant external data sources 23-3

Y
Yielding threads
conditions 6-8
defined 6-10
predetermined point 6-9
ready queue 6-10
switching between 6-8

X-30 IBM Informix Dynamic Server Administrator’s Guide




Printed in USA

G251-2267-02
Spine information:

IBM Informix Version 10.0 IBM Informix Dynamic Server Administrator’s Guide