Oninitii Informix Administrator’s Reference Published by Informix Press Informix Corporation 4100 Bohannon Drive Menlo Park, CA 94025-1032 © 1999 Informix Corporation

InformixAdministrator’sReference

Informix Extended Parallel Server, Version 8.3Informix Dynamic Server.2000, Version 9.2

December 1999Part No. 000-6521

ii Informix Administrato

Published by Informix Press Informix Corporation4100 Bohannon DriveMenlo Park, CA 94025-1032

© 1999 Informix Corporation. All rights reserved. The following are trademarks of Informix Corporationor its affiliates, one or more of which may be registered in the United States or other jurisdictions:

Answers OnLineTM; C-ISAM; Client SDKTM; DataBlade; Data DirectorTM; Decision FrontierTM;Dynamic Scalable ArchitectureTM; Dynamic ServerTM; Dynamic ServerTM, Developer EditionTM;Dynamic ServerTM with Advanced Decision Support OptionTM; Dynamic ServerTM with ExtendedParallel OptionTM; Dynamic ServerTM with MetaCube; Dynamic ServerTM with Universal Data OptionTM;Dynamic ServerTM with Web Integration OptionTM; Dynamic ServerTM, Workgroup EditionTM;Dynamic Virtual MachineTM; Extended Parallel ServerTM; FormationTM; Formation ArchitectTM;Formation Flow EngineTM; Gold Mine Data Access; IIF.2000TM; i.ReachTM; i.SellTM; Illustra; Informix;Informix 4GL; Informix InquireSM; Informix Internet Foundation.2000TM; InformixLink;Informix Red Brick Decision ServerTM; Informix Session ProxyTM; Informix VistaTM; InfoShelfTM;InterforumTM; I-SpyTM; MediazationTM; MetaCube; NewEraTM; ON-BarTM; OnLine Dynamic ServerTM;OnLine/Secure Dynamic ServerTM; OpenCase; OrcaTM; PaVERTM; Red Brick and Design;Red Brick Data MineTM; Red Brick Mine BuilderTM; Red Brick DecisionscapeTM; Red Brick ReadyTM;Red Brick Systems; Regency Support; Rely on Red BrickSM; RISQL; Solution DesignSM; STARindexTM;STARjoinTM; SuperView; TARGETindexTM; TARGETjoinTM; The Data Warehouse Company;The one with the smartest data wins.TM; The world is being digitized. We’re indexing it.SM;Universal Data Warehouse BlueprintTM; Universal Database ComponentsTM; Universal Web ConnectTM;ViewPoint; VisionaryTM; Web Integration SuiteTM. The Informix logo is registered with the United StatesPatent and Trademark Office. The DataBlade logo is registered with the United States Patent andTrademark Office.

Documentation Team: Diana Chase, Erin Cizina, Karen Goldman-Smith, Mary Kraemer, Hanna Nelson,Barbara Nomiyama, Virginia Panlasigui, Liz Suto, Keldyn West

GOVERNMENT LICENSE RIGHTS

Software and documentation acquired by or for the US Government are provided with rights as follows:(1) if for civilian agency use, with rights as restricted by vendor’s standard license, as prescribed in FAR 12.212;(2) if for Dept. of Defense use, with rights as restricted by vendor’s standard license, unless superseded by anegotiated vendor license, as prescribed in DFARS 227.7202. Any whole or partial reproduction of software ordocumentation marked with this legend must reproduce this legend.

r’s Reference

Table of Contents

Table ofContents

IntroductionIn This Introduction . . . . . . . . . . . . . . . . . 3About This Manual . . . . . . . . . . . . . . . . . . 3

Types of Users . . . . . . . . . . . . . . . . . . 3Software Dependencies . . . . . . . . . . . . . . . 4Assumptions About Your Locale. . . . . . . . . . . . 4Demonstration Databases . . . . . . . . . . . . . . 5

New Features . . . . . . . . . . . . . . . . . . . . 6New Features in Version 9.2 . . . . . . . . . . . . . 6New Features in Version 8.3 . . . . . . . . . . . . . 9

Documentation Conventions . . . . . . . . . . . . . . 11Typographical Conventions . . . . . . . . . . . . . 12Icon Conventions . . . . . . . . . . . . . . . . . 13Command-Line Conventions . . . . . . . . . . . . . 14Sample-Code Conventions . . . . . . . . . . . . . . 17Screen-Illustration Conventions . . . . . . . . . . . . 17

Additional Documentation . . . . . . . . . . . . . . . 18On-Line Manuals . . . . . . . . . . . . . . . . . 18Printed Manuals . . . . . . . . . . . . . . . . . 18On-Line Help . . . . . . . . . . . . . . . . . . 19Error Message Documentation . . . . . . . . . . . . 19Documentation Notes, Release Notes, Machine Notes . . . . 19Related Reading . . . . . . . . . . . . . . . . . 21

Compliance with Industry Standards . . . . . . . . . . . 21Informix Welcomes Your Comments . . . . . . . . . . . . 21

iv Inform

Chapter 1 Configuration ParametersIn This Chapter . . . . . . . . . . . . . . . . . . . 1-7ONCONFIG File Conventions . . . . . . . . . . . . . 1-7

Format of ONCONFIG File . . . . . . . . . . . . . 1-7ONCONFIG File Templates . . . . . . . . . . . . . 1-8

ONCONFIG Parameters . . . . . . . . . . . . . . . 1-10AC_MSGPATH, AC_STORAGE, and AC_VERBOSE . . . . . . 1-19ADTERR, ADTMODE, ADTPATH, and ADTSIZE . . . . . . . 1-19AFF_NPROCS . . . . . . . . . . . . . . . . . . . 1-20AFF_SPROC . . . . . . . . . . . . . . . . . . . . 1-21ALARMPROGRAM . . . . . . . . . . . . . . . . . 1-22ALLOW_NEWLINE . . . . . . . . . . . . . . . . . 1-25ASYNCRQT . . . . . . . . . . . . . . . . . . . . 1-26BUFFERS . . . . . . . . . . . . . . . . . . . . . 1-26CDR_DSLOCKWAIT, CDR_EVALTHREADS,

CDR_LOGBUFFERS, and CDR_QUEUEMEM . . . . . 1-28CKPTINTVL . . . . . . . . . . . . . . . . . . . . 1-29CLEANERS . . . . . . . . . . . . . . . . . . . . 1-30CONFIGSIZE . . . . . . . . . . . . . . . . . . . 1-30CONSOLE . . . . . . . . . . . . . . . . . . . . 1-32COSERVER . . . . . . . . . . . . . . . . . . . . 1-33Datagram Configuration Parameters . . . . . . . . . . . 1-34DATASKIP . . . . . . . . . . . . . . . . . . . . 1-35DBSERVERALIASES . . . . . . . . . . . . . . . . . 1-36DBSERVERNAME . . . . . . . . . . . . . . . . . . 1-38DBSPACETEMP . . . . . . . . . . . . . . . . . . 1-40DD_HASHMAX . . . . . . . . . . . . . . . . . . 1-45DD_HASHSIZE . . . . . . . . . . . . . . . . . . 1-45DEADLOCK_TIMEOUT . . . . . . . . . . . . . . . 1-46DIRECTIVES . . . . . . . . . . . . . . . . . . . 1-46DRAUTO . . . . . . . . . . . . . . . . . . . . . 1-47DRINTERVAL . . . . . . . . . . . . . . . . . . . 1-48DRLOSTFOUND . . . . . . . . . . . . . . . . . . 1-49DRTIMEOUT . . . . . . . . . . . . . . . . . . . 1-50DS_ADM_POLICY . . . . . . . . . . . . . . . . . 1-51DS_MAX_QUERIES . . . . . . . . . . . . . . . . . 1-51DS_MAX_SCANS . . . . . . . . . . . . . . . . . . 1-53DS_TOTAL_MEMORY . . . . . . . . . . . . . . . . 1-54DUMPCNT . . . . . . . . . . . . . . . . . . . . 1-58

ix Administrator’s Reference

DUMPCORE . . . . . . . . . . . . . . . . . . . 1-59DUMPDIR . . . . . . . . . . . . . . . . . . . . 1-60DUMPGCORE . . . . . . . . . . . . . . . . . . 1-61DUMPSHMEM . . . . . . . . . . . . . . . . . . 1-62END . . . . . . . . . . . . . . . . . . . . . . 1-63FILLFACTOR . . . . . . . . . . . . . . . . . . . 1-63HETERO_COMMIT . . . . . . . . . . . . . . . . 1-64IDX_RA_PAGES . . . . . . . . . . . . . . . . . . 1-65IDX_RA_THRESHOLD . . . . . . . . . . . . . . . 1-66ISM_DATA_POOL and ISM_LOG_POOL . . . . . . . . . 1-67ISOLATION_LOCKS . . . . . . . . . . . . . . . . 1-67JVPxxx and JVMTHREAD . . . . . . . . . . . . . . 1-68LBU_PRESERVE . . . . . . . . . . . . . . . . . . 1-69LOCKS . . . . . . . . . . . . . . . . . . . . . 1-70LOG_BACKUP_MODE . . . . . . . . . . . . . . . 1-71LOGBUFF . . . . . . . . . . . . . . . . . . . . 1-71LOGFILES . . . . . . . . . . . . . . . . . . . . 1-72LOGSIZE . . . . . . . . . . . . . . . . . . . . 1-74LOGSMAX . . . . . . . . . . . . . . . . . . . . 1-76LRUS . . . . . . . . . . . . . . . . . . . . . . 1-77LRU_MAX_DIRTY . . . . . . . . . . . . . . . . . 1-78LRU_MIN_DIRTY . . . . . . . . . . . . . . . . . 1-78LTAPEBLK . . . . . . . . . . . . . . . . . . . . 1-79LTAPEDEV . . . . . . . . . . . . . . . . . . . 1-81LTAPESIZE . . . . . . . . . . . . . . . . . . . 1-82LTXEHWM . . . . . . . . . . . . . . . . . . . 1-83LTXHWM . . . . . . . . . . . . . . . . . . . . 1-84MAX_CHUNKS . . . . . . . . . . . . . . . . . . 1-85MAX_DBSLICES . . . . . . . . . . . . . . . . . . 1-86MAX_DBSPACES . . . . . . . . . . . . . . . . . 1-87MAX_PDQPRIORITY . . . . . . . . . . . . . . . . 1-88MIRROR . . . . . . . . . . . . . . . . . . . . 1-90MIRROROFFSET . . . . . . . . . . . . . . . . . 1-91MIRRORPATH . . . . . . . . . . . . . . . . . . 1-92MSGPATH . . . . . . . . . . . . . . . . . . . . 1-93MULTIPROCESSOR . . . . . . . . . . . . . . . . 1-94NETTYPE . . . . . . . . . . . . . . . . . . . . 1-94NOAGE . . . . . . . . . . . . . . . . . . . . . 1-99NODE . . . . . . . . . . . . . . . . . . . . . 1-100

Table of Contents v

vi Inform

NUMAIOVPS . . . . . . . . . . . . . . . . . . . 1-101NUMCPUVPS . . . . . . . . . . . . . . . . . . . 1-102NUMFIFOVPS . . . . . . . . . . . . . . . . . . . 1-103OFF_RECVRY_THREADS . . . . . . . . . . . . . . . 1-103ON_RECVRY_THREADS . . . . . . . . . . . . . . . 1-104ON-Bar Parameters . . . . . . . . . . . . . . . . . 1-105ONDBSPACEDOWN . . . . . . . . . . . . . . . . . 1-108OPCACHEMAX . . . . . . . . . . . . . . . . . . 1-109OPTCOMPIND . . . . . . . . . . . . . . . . . . 1-110OPT_GOAL . . . . . . . . . . . . . . . . . . . . 1-111PAGESIZE . . . . . . . . . . . . . . . . . . . . 1-112PC_HASHSIZE . . . . . . . . . . . . . . . . . . . 1-114PC_POOLSIZE . . . . . . . . . . . . . . . . . . . 1-114PDQPRIORITY . . . . . . . . . . . . . . . . . . . 1-115PHYSBUFF . . . . . . . . . . . . . . . . . . . . 1-117PHYSDBS . . . . . . . . . . . . . . . . . . . . . 1-118PHYSFILE . . . . . . . . . . . . . . . . . . . . 1-120PHYSSLICE . . . . . . . . . . . . . . . . . . . . 1-121PLAN_MONITORING . . . . . . . . . . . . . . . . 1-122RA_PAGES . . . . . . . . . . . . . . . . . . . . 1-122RA_THRESHOLD . . . . . . . . . . . . . . . . . . 1-123RESIDENT . . . . . . . . . . . . . . . . . . . . 1-124RESTARTABLE_RESTORE . . . . . . . . . . . . . . . 1-125ROOTNAME . . . . . . . . . . . . . . . . . . . 1-126ROOTOFFSET . . . . . . . . . . . . . . . . . . . 1-127ROOTPATH . . . . . . . . . . . . . . . . . . . . 1-128ROOTSIZE . . . . . . . . . . . . . . . . . . . . 1-129ROOTSLICE . . . . . . . . . . . . . . . . . . . . 1-130SBSPACENAME . . . . . . . . . . . . . . . . . . 1-131SENDEPDS . . . . . . . . . . . . . . . . . . . . 1-132SERVERNUM . . . . . . . . . . . . . . . . . . . 1-133SHMADD . . . . . . . . . . . . . . . . . . . . 1-134SHMBASE . . . . . . . . . . . . . . . . . . . . 1-135SHMTOTAL . . . . . . . . . . . . . . . . . . . . 1-136SHMVIRTSIZE . . . . . . . . . . . . . . . . . . . 1-137SINGLE_CPU_VP . . . . . . . . . . . . . . . . . . 1-138STACKSIZE . . . . . . . . . . . . . . . . . . . . 1-140STAGEBLOB . . . . . . . . . . . . . . . . . . . 1-141STMT_CACHE . . . . . . . . . . . . . . . . . . . 1-141


STMT_CACHE_SIZE . . . . . . . . . . . . . . . . 1-142SYSALARMPROGRAM . . . . . . . . . . . . . . . 1-143SYSSBSPACENAME . . . . . . . . . . . . . . . . 1-143TAPEBLK . . . . . . . . . . . . . . . . . . . . 1-145TAPEDEV . . . . . . . . . . . . . . . . . . . . 1-146TAPESIZE . . . . . . . . . . . . . . . . . . . . 1-147TBLSPACE_STATS . . . . . . . . . . . . . . . . . 1-148TXTIMEOUT . . . . . . . . . . . . . . . . . . . 1-148USEOSTIME . . . . . . . . . . . . . . . . . . . 1-149VPCLASS . . . . . . . . . . . . . . . . . . . . 1-150XMF Configuration Parameters . . . . . . . . . . . . . 1-158

Chapter 2 The sysmaster DatabaseIn This Chapter . . . . . . . . . . . . . . . . . . 2-3The sysmaster Database . . . . . . . . . . . . . . . 2-3

The buildsmi Script . . . . . . . . . . . . . . . 2-5The bldutil.sh Script . . . . . . . . . . . . . . . 2-5

The System-Monitoring Interface . . . . . . . . . . . . 2-6Understanding the SMI Tables . . . . . . . . . . . 2-6Accessing SMI Tables . . . . . . . . . . . . . . . 2-7

The System-Monitoring Interface Tables . . . . . . . . . . 2-8The sysutils Tables . . . . . . . . . . . . . . . . 2-10Backup Scheduler Tables . . . . . . . . . . . . . 2-10sysadtinfo. . . . . . . . . . . . . . . . . . . 2-11sysaudit . . . . . . . . . . . . . . . . . . . 2-12syschkio . . . . . . . . . . . . . . . . . . . 2-13syschunks. . . . . . . . . . . . . . . . . . . 2-13sysconfig . . . . . . . . . . . . . . . . . . . 2-15sysdatabases . . . . . . . . . . . . . . . . . . 2-16sysdbslocale . . . . . . . . . . . . . . . . . . 2-17sysdbspaces . . . . . . . . . . . . . . . . . . 2-17sysdri . . . . . . . . . . . . . . . . . . . . 2-19sysextents . . . . . . . . . . . . . . . . . . . 2-20sysextspaces . . . . . . . . . . . . . . . . . . 2-20syslocks . . . . . . . . . . . . . . . . . . . 2-21syslogs . . . . . . . . . . . . . . . . . . . . 2-22sysprofile . . . . . . . . . . . . . . . . . . . 2-23sysptprof . . . . . . . . . . . . . . . . . . . 2-25syssesprof. . . . . . . . . . . . . . . . . . . 2-26syssessions . . . . . . . . . . . . . . . . . . 2-28

Table of Contents vii

viii Infor

sysseswts . . . . . . . . . . . . . . . . . . . 2-30systabnames . . . . . . . . . . . . . . . . . . 2-31sysvpprof . . . . . . . . . . . . . . . . . . . 2-32syscogroups . . . . . . . . . . . . . . . . . . 2-33syscogroupmembers . . . . . . . . . . . . . . . 2-33

The SMI Tables Map . . . . . . . . . . . . . . . . . 2-34Information from onstat in the SMI Tables . . . . . . . . . 2-37

Chapter 3 UtilitiesIn This Chapter . . . . . . . . . . . . . . . . . . . 3-3The -V Option . . . . . . . . . . . . . . . . . . . 3-4Multibyte Characters . . . . . . . . . . . . . . . . . 3-4oncheck: Check, Repair, or Display . . . . . . . . . . . . 3-5ondblog: Change Logging Mode . . . . . . . . . . . . . 3-24oninit: Initialize the Database Server . . . . . . . . . . . 3-26onlog: Display Logical-Log Contents . . . . . . . . . . . 3-31onmode: Change Mode and Shared Memory . . . . . . . . 3-37onparams: Modify Log-Configuration Parameters . . . . . . . 3-57onspaces: Manage Storage Spaces . . . . . . . . . . . . 3-62onstat: Monitor Database Server Operation . . . . . . . . . 3-88ontape: Log, Back Up, and Restore . . . . . . . . . . . . 3-132onutil: Check, Define, and Modify Storage Objects . . . . . . 3-135

ALTER DBSLICE ADD DBSPACE . . . . . . . . . . . 3-150ALTER DBSPACE . . . . . . . . . . . . . . . . 3-159ALTER LOGSLICE ADD LOGS . . . . . . . . . . . . 3-167CHECK CATALOGS . . . . . . . . . . . . . . . 3-170CHECK DATA . . . . . . . . . . . . . . . . . 3-171CHECK INDEX . . . . . . . . . . . . . . . . . 3-174CHECK INDEX KEYS WITH DATA . . . . . . . . . . 3-176CHECK INFO . . . . . . . . . . . . . . . . . . 3-178CHECK LOGS. . . . . . . . . . . . . . . . . . 3-181CHECK RESERVED. . . . . . . . . . . . . . . . 3-183CHECK SPACE . . . . . . . . . . . . . . . . . 3-186CREATE COGROUP . . . . . . . . . . . . . . . 3-188CREATE DBSLICE . . . . . . . . . . . . . . . . 3-194CREATE DBSPACE . . . . . . . . . . . . . . . . 3-207CREATE LOGICAL LOG . . . . . . . . . . . . . . 3-212CREATE LOGICAL LOGSLICE. . . . . . . . . . . . 3-215DISPLAY PAGE . . . . . . . . . . . . . . . . . 3-217DROP COGROUP . . . . . . . . . . . . . . . . 3-220DROP DBSLICE . . . . . . . . . . . . . . . . . 3-222

mix Administrator’s Reference

DROP DBSPACE . . . . . . . . . . . . . . . . 3-223DROP LOGICAL LOG . . . . . . . . . . . . . . 3-224DROP LOGSLICE . . . . . . . . . . . . . . . . 3-226

xctl: Execute Utilities Across Coservers . . . . . . . . . . 3-227

Chapter 4 ON-MonitorIn This Chapter . . . . . . . . . . . . . . . . . . 4-3Using ON-Monitor . . . . . . . . . . . . . . . . . 4-3

Navigating ON-Monitor and Using Help . . . . . . . . 4-4Executing Shell Commands Within ON-Monitor . . . . . 4-4

ON-Monitor Screen Options . . . . . . . . . . . . . . 4-5Setting Configuration Parameters in ON-Monitor . . . . . . 4-12

Chapter 5 Message-Log MessagesIn This Chapter . . . . . . . . . . . . . . . . . . 5-3How the Messages Are Ordered in This Chapter . . . . . . . 5-4How to View These Messages . . . . . . . . . . . . . 5-4Message Categories . . . . . . . . . . . . . . . . . 5-5Messages: A-B . . . . . . . . . . . . . . . . . . 5-6Messages: C . . . . . . . . . . . . . . . . . . . 5-8Messages: D-E-F . . . . . . . . . . . . . . . . . . 5-16Messages: G-H-I . . . . . . . . . . . . . . . . . . 5-20Messages: J-K-L-M . . . . . . . . . . . . . . . . . 5-23Messages: N-O-P . . . . . . . . . . . . . . . . . . 5-29Messages: Q-R-S . . . . . . . . . . . . . . . . . . 5-37Messages: T-U-V . . . . . . . . . . . . . . . . . . 5-43Messages: W-X-Y-Z . . . . . . . . . . . . . . . . . 5-47Messages: Symbols . . . . . . . . . . . . . . . . . 5-48Violations Table Messages . . . . . . . . . . . . . . 5-50Truncate Table Messages . . . . . . . . . . . . . . . 5-54

Chapter 6 Interpreting Logical-Log RecordsIn This Chapter . . . . . . . . . . . . . . . . . . 6-3About Logical-Log Records . . . . . . . . . . . . . . 6-4

Transactions That Drop a Table or Index . . . . . . . . 6-4Transactions That Are Rolled Back . . . . . . . . . . 6-4Checkpoints with Active Transactions . . . . . . . . . 6-5Distributed Transactions. . . . . . . . . . . . . . 6-5

Table of Contents ix

x Inform

Logical-Log Record Structure . . . . . . . . . . . . . . 6-6Logical-Log Record Header . . . . . . . . . . . . . 6-6Logical-Log Record Types and Additional Columns. . . . . 6-7Log Record Types for Smart Large Objects . . . . . . . . 6-21

Chapter 7 Disk Structures and StorageIn This Chapter . . . . . . . . . . . . . . . . . . . 7-3Dbspace Structure and Storage . . . . . . . . . . . . . 7-4

Structure of the Root Dbspace . . . . . . . . . . . . 7-4Structure of a Regular Dbspace . . . . . . . . . . . . 7-5Structure of a Mirrored Chunk . . . . . . . . . . . . 7-7Structure of the Chunk Free-List Page . . . . . . . . . 7-8Structure of the Tblspace Tblspace . . . . . . . . . . . 7-9Structure of the Database Tblspace. . . . . . . . . . . 7-12Structure and Allocation of an Extent . . . . . . . . . . 7-13Structure and Storage of a Dbspace Page . . . . . . . . 7-22Structure of Fragmented Tables . . . . . . . . . . . . 7-26Structure of B-Tree Index Pages . . . . . . . . . . . . 7-27Structure of Bitmap Indexes . . . . . . . . . . . . . 7-35Structure of R-Tree Index Pages . . . . . . . . . . . . 7-35

Storage of Simple Large Objects . . . . . . . . . . . . . 7-36Structure of a Blobspace . . . . . . . . . . . . . . 7-36Structure of a Dbspace Blobpage . . . . . . . . . . . 7-37Simple-Large-Object Storage and the Descriptor . . . . . . 7-37Blobspace Page Types . . . . . . . . . . . . . . . 7-38Structure of a Blobspace Blobpage . . . . . . . . . . . 7-39

Sbspace Structure . . . . . . . . . . . . . . . . . . 7-40Structure of the Metadata Area . . . . . . . . . . . . 7-42Sbpage Structure . . . . . . . . . . . . . . . . . 7-43Multiple Chunk Sbspace . . . . . . . . . . . . . . 7-44

Database and Table Creation: What Happens on Disk . . . . . 7-45Database Creation . . . . . . . . . . . . . . . . 7-45Table Creation . . . . . . . . . . . . . . . . . . 7-46

Chapter 8 Loading with External Tables for Extended Parallel ServerIn This Chapter . . . . . . . . . . . . . . . . . . . 8-3Getting an Overview of High-Performance Loading . . . . . . 8-3

Loading and UnLoading Data . . . . . . . . . . . . 8-4Data-Format Conversion . . . . . . . . . . . . . . 8-8Data Load . . . . . . . . . . . . . . . . . . . 8-8


Data Unload . . . . . . . . . . . . . . . . . . 8-8File Types and Formats . . . . . . . . . . . . . . 8-9Loading Modes . . . . . . . . . . . . . . . . . 8-9Optimization . . . . . . . . . . . . . . . . . 8-10

Starting to Load and Unload Data . . . . . . . . . . . . 8-12Specifying the External Table . . . . . . . . . . . . 8-12Loading Data in Express Mode . . . . . . . . . . . 8-13Loading Data in Deluxe Mode. . . . . . . . . . . . 8-15

Loading, Unloading, and Reorganizing Data . . . . . . . . 8-16Loading from a Delimited File with Unchanged Columns . . 8-17Unloading to a Delimited File . . . . . . . . . . . . 8-17Mapping Columns to Other Columns . . . . . . . . . 8-18Unloading to an Informix Data File . . . . . . . . . . 8-19Loading Between Tables That Have the Same Schema . . . 8-19Loading from a Fixed-ASCII File . . . . . . . . . . . 8-20Unloading to a Fixed-ASCII File . . . . . . . . . . . 8-21Loading from an IBM Fixed-EBCDIC File . . . . . . . . 8-22Loading from and Unloading to a Named Pipe . . . . . 8-22Adding an End-of-Line Character to a Fixed-ASCII File . . . 8-26Loading Values into Serial Columns. . . . . . . . . . 8-28Loading Data Warehousing Tables . . . . . . . . . . 8-28

Loading Simple Large Objects . . . . . . . . . . . . . 8-32Formats for Simple Large Objects . . . . . . . . . . 8-32Loading Simple Large Objects from an External Table . . . 8-38Using Pipe Staging . . . . . . . . . . . . . . . 8-40

Monitoring the Load or Unload Operations . . . . . . . . 8-44Monitoring Frequent Loads and Unloads . . . . . . . . 8-44Monitoring FIFO Virtual Processors . . . . . . . . . . 8-45Monitoring Loads and Unloads of Data . . . . . . . . 8-46

Recovering After Errors . . . . . . . . . . . . . . . 8-49Reject Files . . . . . . . . . . . . . . . . . . 8-49Error Messages . . . . . . . . . . . . . . . . . 8-51Recoverability of Table Types . . . . . . . . . . . . 8-52

Table of Contents xi

xii Inform

Appendix A Files That the Database Server Uses

Appendix B Trapping Errors

Appendix C Thread Suspension

Appendix D Event Alarms

Index


Introduction

Introduction

In This Introduction . . . . . . . . . . . . . . . . 3

About This Manual . . . . . . . . . . . . . . . . . 3Types of Users . . . . . . . . . . . . . . . . . 3Software Dependencies . . . . . . . . . . . . . . 4Assumptions About Your Locale . . . . . . . . . . . 4Demonstration Databases . . . . . . . . . . . . . 5

New Features . . . . . . . . . . . . . . . . . . . 6New Features in Version 9.2 . . . . . . . . . . . . 6

Extensibility Enhancements . . . . . . . . . . . 6Performance Improvements . . . . . . . . . . . 7Special Features . . . . . . . . . . . . . . . 7New Logical-Log Records . . . . . . . . . . . . 8Version 9.2 Features from Version 7.30 . . . . . . . 8

New Features in Version 8.3 . . . . . . . . . . . . 9Configuration Enhancements . . . . . . . . . . 9Performance Enhancements . . . . . . . . . . . 10New SQL Functionality . . . . . . . . . . . . 10Year 2000 Compliance . . . . . . . . . . . . . 10New Logical-Log Records . . . . . . . . . . . . 10Utility Enhancements . . . . . . . . . . . . . 11Version 8.3 Features from Version 7.30 . . . . . . . 11

Documentation Conventions . . . . . . . . . . . . . 11Typographical Conventions . . . . . . . . . . . . 12Icon Conventions . . . . . . . . . . . . . . . . 13

Comment Icons . . . . . . . . . . . . . . . 13Feature, Product, and Platform Icons . . . . . . . . 13

2 Inform

Command-Line Conventions . . . . . . . . . . . . 14How to Read a Command-Line Diagram. . . . . . . 16

Sample-Code Conventions . . . . . . . . . . . . . 17Screen-Illustration Conventions . . . . . . . . . . . 17

Additional Documentation . . . . . . . . . . . . . . 18On-Line Manuals . . . . . . . . . . . . . . . . 18Printed Manuals . . . . . . . . . . . . . . . . 18On-Line Help . . . . . . . . . . . . . . . . . 19Error Message Documentation . . . . . . . . . . . 19Documentation Notes, Release Notes, Machine Notes . . . 19Related Reading . . . . . . . . . . . . . . . . 21

Compliance with Industry Standards. . . . . . . . . . . 21

Informix Welcomes Your Comments . . . . . . . . . . . 21


In This IntroductionThis Introduction provides an overview of the information in this manualand describes the conventions it uses.

About This ManualThis manual provides reference material for Informix Dynamic Server 2000and Informix Extended Parallel Server. It provides the syntax of databaseserver utilities such as onmode and onstat, and comprehensive descriptionsof configuration parameters, the sysmasters tables, and logical-log records. Italso provides information about loading and unloading external tables inExtended Parallel Server.

This book has two companion volumes, the Administrator’s Guide and thePerformance Guide.

Types of UsersThis manual is written for the following users:

■ Database users

■ Database administrators

■ Database server administrators

■ Programmers in the following categories

❑ Application developers

❑ DataBlade module developers

❑ Authors of user-defined routines

Introduction 3

Software Dependencies

This manual assumes that you have the following background:

■ A working knowledge of your computer, your operating system,and the utilities that your operating system provides

■ Some experience working with relational databases or exposure todatabase concepts

■ Some experience with computer programming

■ Some experience with database server administration, operating-system administration, or network administration

If you have limited experience with relational databases, SQL, or youroperating system, refer to the Getting Started manual for your database serverfor a list of supplementary titles.

Software DependenciesThis manual assumes that you are using one of the following databaseservers:

■ Informix Extended Parallel Server, Version 8.3

■ Informix Dynamic Server 2000, Version 9.2

Assumptions About Your LocaleInformix products can support many languages, cultures, and code sets. Allculture-specific information is brought together in a single environment,called a Global Language Support (GLS) locale.

This manual assumes that you use the U.S. 8859-1 English locale as thedefault locale. The default is en_us.8859-1 (ISO 8859-1) on UNIX platforms oren_us.1252 (Microsoft 1252) for Windows NT environments. This localesupports U.S. English format conventions for dates, times, and currency, andalso supports the ISO 8859-1 or Microsoft 1252 code set, which includes theASCII code set plus many 8-bit characters such as é, è, and ñ.

4 Informix Administrator’s Reference

Demonstration Databases

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, andother considerations related to GLS locales, see the Informix Guide to GLSFunctionality.

Demonstration DatabasesThe DB-Access utility, which is provided with your Informix database serverproducts, includes one or more of the following demonstration databases:

■ The stores_demo database illustrates a relational schema with infor-mation about a fictitious wholesale sporting-goods distributor.Many examples in Informix manuals are based on the stores_demodatabase.

■ The sales_demo database illustrates a dimensional schema for datawarehousing applications. For conceptual information about dimen-sional data modeling, see the Informix Guide to Database Design andImplementation. ♦

■ The superstores_demo database illustrates an object-relationalschema. The superstores_demo database contains examples ofextended data types, type and table inheritance, and user-definedroutines. ♦

For information about how to create and populate the demonstrationdatabases, see the DB-Access User’s Manual. For descriptions of the databasesand their contents, see the Informix Guide to SQL: Reference.

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

XPS

IDS

Introduction 5

New Features

New FeaturesFor a comprehensive list of new database server features, see the releasenotes. This section lists new features relevant to this manual and theAdministrator’s Guide.

New Features in Version 9.2This manual describes new features in Version 9.2 of Dynamic Server. Thefeatures fall into the following areas:

■ Extensibility enhancements

■ Performance improvements

■ Special features

■ New logical-log records

■ Version 9.2 features from Version 7.30 of Dynamic Server

Extensibility Enhancements

This manual describes the following extensibility enhancements toVersion 9.2 of Dynamic Server:

■ Enhancements to the database server: dynamic lock allocation

■ New configuration parameters for the following features:

❑ Embedded newline characters in quoted strings

❑ User-defined statistics routines

■ Enhancements to smart large objects:

❑ Round-robin fragmentation for smart large objects

❑ ALTER TABLE for smart large objects

■ Extensions to utilities:

❑ onstat for user-defined aggregates

❑ oncheck and onlog for R-tree indexes


New Features in Version 9.2

Performance Improvements

This manual describes the following performance improvements toVersion 9.2 of Dynamic Server:

■ For the database server: fuzzy checkpoints

■ New configuration parameters for the SQL statement cache

■ Extensions to onstat for the SQL statement cache

Your Performance Guide describes additional performance improvements toVersion 9.2 of Dynamic Server.

Special Features

This manual describes administration considerations for the followingspecial features of Version 9.2 of Dynamic Server:

■ Long identifiers:

❑ 128-character identifier

❑ 32-character user names

■ New configuration parameters:

❑ AC_MSGPATH

❑ AC_STORAGE

❑ AC_VERBOSE

❑ ALLOW_NEWLINE

❑ BAR_HISTORY

❑ BAR_PROGRESS_FREQ

❑ DD_HASHMAX

❑ DD_HASHSIZE

❑ PC_HASHSIZE

❑ PC_POOLSIZE

❑ STMT_CACHE

❑ STMT_CACHE_SIZE

❑ SYSSBSPACENAME

Introduction 7


New Logical-Log Records

This manual describes the new logical-log records in Version 9.2 of DynamicServer:

■ DPT logical-log record

■ SBLOB logical-log record

Version 9.2 Features from Version 7.30

This manual also describes features first released in Version 7.30. Thesefeatures fall into the following areas:

■ Windows NT-specific features:

❑ Multiple residency

❑ Raw device support

❑ Microsoft cluster support

❑ Local-connection support with named pipes

■ Informix Storage Manager (ISM) to manage the storage devices andmedia that contain backups

■ Connectivity:

❑ Greater network security available through support of third-party security services

❑ Client interfaces (ESQL/C, Informix ODBC, C++, Java, JDBC, GLS)supported in a single package

■ Optical Subsystem shared-library support: no need to order aseparate product

■ New options for the oncheck utility:

❑ The oncheck -w option to check and print an index withoutplacing a shared lock on the table

❑ The oncheck -R option to check the reserved pages, physical-logpages, and logical-log pages


❑ OPT_GOAL

❑ TBLSPACE_STATS



New Features in Version 8.3This manual describes new features in Version 8.3 of Extended ParallelServer. The features fall into the following areas:

■ Configuration enhancements

■ Performance enhancements

■ New SQL functionality

■ Year 2000 compliance

■ New logical-log records

■ Utility enhancements

■ Version 8.3 features from Version 7.30 of Dynamic Server

Configuration Enhancements

This manual describes the following configuration enhancements toVersion 8.3 of Extended Parallel Server:

■ Increased maximum number of chunks, dbspaces, and dbslices

■ Increased maximum chunk size

■ Configurable page size

■ 64-bit very large memory (VLM)


❑ ALARMPROGRAM

❑ BAR_HISTORY

❑ BAR_PROGRESS_FREQ

❑ IDX_RA_PAGES

❑ IDX_RA_THRESHOLD

❑ ISOLATION_LOCKS

❑ MAX_CHUNKS

❑ MAX_DBSLICES

❑ MAX_DBSPACES

❑ OPTCOMPIND

❑ PAGESIZE

Introduction 9


❑ PC_HASHSIZE

❑ PC_POOLSIZE

❑ PLAN_MONITORING

❑ SYSALARMPROGRAM

Performance Enhancements

This manual describes the following performance enhancements toVersion 8.3 of Extended Parallel Server:

■ Dynamic lock allocation

■ Fuzzy checkpoints

■ Skipping logical-log replay during restore

■ Thread suspension to prevent database server failure for severeerrors

Your Performance Guide describes additional performance improvements toVersion 8.3 of Extended Parallel Server.

New SQL Functionality

You can now load and unload simple large objects to external tables.

Year 2000 Compliance

This manual describes the following Year 2000 compliance features inVersion 8.3 of Extended Parallel Server:

■ DBCENTURY environment variable

■ Support for ISM, Version 2.2

New Logical-Log Records

This manual describes the following new logical-log records in Version 8.3 ofExtended Parallel Server:

■ DPT logical-log record (fuzzy checkpoints)

■ Three logical-log records for the TRUNCATE TABLE statement


Documentation Conventions

Utility Enhancements

Version 8.3 of Extended Parallel Server provides new options for the onutilutility.

■ onutil CHECK, without locks

■ onutil CHECK, repair improvements

■ onutil ALTER DBSLICE

■ onutil ALTER LOGSLICE

Version 8.3 Features from Version 7.30

This manual describes the following features from Version 7.30 of DynamicServer in Version 8.3 of Extended Parallel Server:

■ Deferred constraints for all constraint types

■ Memory-resident tables

■ ondblog to change database logging

■ TBLSPACE_STATS configuration parameter

■ Violations table

Documentation ConventionsThis section describes the conventions that this manual uses. Theseconventions make it easier to gather information from this and other volumesin the documentation set.

The following conventions are discussed:

■ Typographical conventions

■ Icon conventions

■ Command-line conventions

■ Sample-code conventions

Introduction 11

Typographical Conventions

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

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

Convention Meaning

KEYWORD All primary elements in a programming language statement(keywords) appear in uppercase letters in a serif font.

italicsitalicsitalics

Within text, new terms and emphasized words appear in italics.Within syntax and code examples, variable values that you areto specify appear in italics.

boldfaceboldface

Names of program entities (such as classes, events, and tables),environment variables, file and pathnames, and interfaceelements (such as icons, menu items, and buttons) appear inboldface.

monospacemonospace

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

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

♦ This symbol indicates the end of one or more product- orplatform-specific paragraphs.

➞ This symbol indicates a menu item. For example, “ChooseTools➞Options” means choose the Options item from theTools menu.


Icon Conventions

Icon ConventionsThroughout the documentation, you will find text that is identified by severaldifferent types of icons. This section describes these icons.

Comment Icons

Comment icons identify three types of information, as the following tabledescribes. This information always appears in italics.

Feature, Product, and Platform Icons

Feature, product, and platform icons identify paragraphs that containfeature-specific, product-specific, or platform-specific information.

Icon Label Description

Warning: Identifies paragraphs that contain vital instructions,cautions, or critical information

Important: Identifies paragraphs that contain significantinformation about the feature or operation that isbeing described

Tip: Identifies paragraphs that offer additional details orshortcuts for the functionality that is being described

Icon Description

Identifies information or syntax that is specific toDB-Access

Identifies information or syntax that is specific to InformixESQL/C

Identifies information that relates to the Informix GlobalLanguage Support (GLS) feature

(1 of 2)

DB

E/C

GLS

Introduction 13

Command-Line Conventions

These icons can apply to an entire section or to one or more paragraphswithin a section. If an icon appears next to a section heading, the informationthat applies to the indicated feature, product, or platform ends at the nextheading at the same or higher level. A ♦ symbol indicates the end of feature-,product-, or platform-specific information that appears within one or moreparagraphs within a section.

Command-Line ConventionsThis section defines and illustrates the format of commands that are availablein Informix products. These commands have their own conventions, whichmight include alternative forms of a command, required and optional partsof the command, and so forth.

Each diagram displays the sequences of required and optional elements thatare valid in a command. A diagram begins at the upper-left corner with acommand. It ends at the upper-right corner with a vertical line. Betweenthese points, you can trace any path that does not stop or back up. Each pathdescribes a valid form of the command. You must supply a value for wordsthat are in italics.

Identifies information that is specific to Informix DynamicServer 2000

Identifies information that is specific to the Java language

Identifies information that is specific to UNIX platforms

Identifies information that is specific to the Windows NTenvironment

Identifies information or syntax that is specific to InformixExtended Parallel Server

Icon Description

(2 of 2)

IDS

Java

UNIX

WIN NT

XPS



You might encounter one or more of the following elements on a command-line path.

Element Description

command This required element is usually the product name orother short word that invokes the product or calls thecompiler or preprocessor script for a compiled Informixproduct. It might appear alone or precede one or moreoptions. You must spell a command exactly as shownand use lowercase letters.

variable A word in italics represents a value that you mustsupply, such as a database, file, or program name. A tablefollowing the diagram explains the value.

-flag A flag is usually an abbreviation for a function, menu, oroption name, or for a compiler or preprocessorargument. You must enter a flag exactly as shown,including the preceding hyphen.

.ext A filename extension, such as .sql or .cob, might followa variable that represents a filename. Type this extensionexactly as shown, immediately after the name of the file.The extension might be optional in certain products.

( . , ; + * - / ) Punctuation and mathematical notations are literalsymbols that you must enter exactly as shown.

' ' Single quotes are literal symbols that you must enter asshown.

A reference in a box represents a subdiagram. Imaginethat the subdiagram is spliced into the main diagram atthis point. When a page number is not specified, thesubdiagram appears on the same page.

A shaded option is the default action.

Syntax within a pair of arrows indicates a subdiagram.

The vertical line terminates the command.

(1 of 2)

Privilegesp. 5-17

Privileges

ALL

Introduction 15


How to Read a Command-Line Diagram

Figure 1 shows a command-line diagram that uses some of the elements thatare listed in the previous table.

To construct a command correctly, start at the top left with the command.Follow the diagram to the right, including the elements that you want. Theelements in the diagram are case sensitive.

Figure 1 illustrates the following steps:

1. Type setenv.

2. Type INFORMIXC.

3. Supply either a compiler name or a pathname.

After you choose compiler or pathname, you come to the terminator.Your command is complete.

4. Press RETURN to execute the command.

A branch below the main path indicates an optionalpath. (Any term on the main path is required, unless abranch can circumvent it.)

A loop indicates a path that you can repeat. Punctuationalong the top of the loop indicates the separator symbolfor list items.

A gate ( ) on a path indicates that you can only usethat path the indicated number of times, even if it is partof a larger loop. You can specify size no more than threetimes within this statement segment.

Element Description

(2 of 2)

ON

-f OFF

variable

,

size3

, 3

Figure 1Example of a Command-Line Diagram

pathname

compilersetenv INFORMIXC


Sample-Code Conventions

Sample-Code ConventionsExamples of SQL code occur throughout this manual. Except where noted,the code is not specific to any single Informix application development tool.If only SQL statements are listed in the example, they are not delimited bysemicolons. For instance, you might see the code in the following example:

CONNECT TO stores_demo...

DELETE FROM customerWHERE customer_num = 121

...

COMMIT WORKDISCONNECT CURRENT

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

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

For detailed directions on using SQL statements for a particular applicationdevelopment tool or SQL API, see the manual for your product.

Screen-Illustration ConventionsThe illustrations in this manual represent a generic rendition of variouswindowing environments. The details of dialog boxes, controls, andwindows were deleted or redesigned to provide this generic look. Therefore,the illustrations in this manual depict your product interface a little differ-ently than the way it appears on your screen.

Introduction 17

Additional Documentation

Additional DocumentationFor additional information, you might want to refer to the following types ofdocumentation:

■ On-line manuals

■ Printed manuals

■ On-line help

■ Error message documentation

■ Documentation notes, release notes, and machine notes

■ Related reading

On-Line ManualsAn Answers OnLine CD that contains Informix manuals in electronic formatis provided with your Informix products. You can install the documentationor access it directly from the CD. For information about how to install, read,and print on-line manuals, see the installation insert that accompaniesAnswers OnLine.

Printed ManualsTo order printed manuals, call 1-800-331-1763 or send email [email protected]. Please provide the following information whenyou place your order:

■ The documentation that you need

■ The quantity that you need

■ Your name, address, and telephone number


On-Line Help

On-Line HelpInformix provides on-line help with each graphical user interface (GUI) thatdisplays information about those interfaces and the functions that theyperform. Use the help facilities that each GUI provides to display the on-linehelp.

Error Message DocumentationInformix software products provide ASCII files that contain all of theInformix error messages and their corrective actions.

To read error messages and corrective actions on UNIX, use one of thefollowing utilities.

To read error messages and corrective actions in Windows environments, usethe Informix Find Error utility. To display this utility, chooseStart➞Programs➞Informix from the Task Bar. ♦

Instructions for using the preceding utilities are available in AnswersOnLine. Answers OnLine also provides a listing of error messages andcorrective actions in HTML format.

Documentation Notes, Release Notes, Machine NotesIn addition to printed documentation, the following sections describe the on-line files that supplement the information in this manual. Please examinethese files before you begin using your database server. They contain vitalinformation about application and performance issues.

Utility Description

finderr Displays error messages on line

rofferr Formats error messages for printing

♦

WIN NT

UNIX

WIN NT

Introduction 19

Documentation Notes, Release Notes, Machine Notes

On UNIX platforms, the following on-line files appear in the$INFORMIXDIR/release/en_us/0333 directory. Replace x.y in the filenameswith the version number of your database server.

The following items appear in the Informix folder. To display this folder,choose Start➞Programs➞Informix from the Task Bar.

The machine notes do not apply to Windows environments. ♦

On-Line File Purpose

ADREFDOC_x.y The documentation notes file for your version of thismanual describes topics that are not covered in themanual or that were modified since publication.

SERVERS_x.y The release notes file describes feature differences fromearlier versions of Informix products and how thesedifferences might affect current products. This file alsocontains information about any known problems andtheir workarounds.

IDS_9.2 orXPS_x.y

The machine notes file describes any special actionsthat you must take to configure and use Informixproducts on your computer. The machine notes arenamed for the product described.

♦

Program Group Item Description

Documentation Notes This item includes additions or corrections to manuals,along with information about features that might notbe covered in the manuals or that have been modifiedsince publication.

Release Notes This item describes feature differences from earlierversions of Informix products and how these differ-ences might affect current products. This file alsocontains information about any known problems andtheir workarounds.

UNIX

WIN NT


Related Reading

Related ReadingThe following publications provide additional information about the topicsthat are discussed in this manual:

■ An Introduction to Database Systems by C.M. Date (Addison-WesleyPublishing, 1995)

■ C: The Complete Reference by Herbert Schildt (Osborne McGraw-Hill,1995)

For a list of publications that provide an introduction to database servers andoperating-system platforms, refer to your Getting Started manual.

Compliance with Industry StandardsThe American National Standards Institute (ANSI) has established a set ofindustry standards for SQL. Informix SQL-based products are fully compliantwith SQL-92 Entry Level (published as ANSI X3.135-1992), which is identicalto ISO 9075:1992. In addition, many features of Informix database serverscomply with the SQL-92 Intermediate and Full Level and X/Open SQL CAE(common applications environment) standards.

Informix Welcomes Your CommentsLet us know what you like or dislike about our manuals. To help us withfuture versions of our manuals, we want to know about any corrections orclarifications that you would find useful. Include the following information:

■ The name and version of the manual that you are using

■ Any comments that you have about the manual

■ Your name, address, and phone number

Introduction 21

Informix Welcomes Your Comments

Send electronic mail to us at the following address:

[email protected]

The doc alias is reserved exclusively for reporting errors and omissions in ourdocumentation.

We appreciate your suggestions.


1Chapter

Configuration Parameters

In This Chapter . . . . . . . . . . . . . . . . . . . . 1-7

ONCONFIG File Conventions . . . . . . . . . . . . . . . 1-7Format of ONCONFIG File. . . . . . . . . . . . . . . 1-7ONCONFIG File Templates . . . . . . . . . . . . . . 1-8

ONCONFIG Parameters . . . . . . . . . . . . . . . . . 1-10

AC_MSGPATH, AC_STORAGE, and AC_VERBOSE . . . . . . . 1-19

ADTERR, ADTMODE, ADTPATH, and ADTSIZE . . . . . . . . 1-19

AFF_NPROCS . . . . . . . . . . . . . . . . . . . . 1-20

AFF_SPROC . . . . . . . . . . . . . . . . . . . . . 1-21

ALARMPROGRAM . . . . . . . . . . . . . . . . . . 1-22

ALLOW_NEWLINE . . . . . . . . . . . . . . . . . . 1-25

ASYNCRQT . . . . . . . . . . . . . . . . . . . . . 1-26

BUFFERS . . . . . . . . . . . . . . . . . . . . . . 1-26

CDR_DSLOCKWAIT, CDR_EVALTHREADS, CDR_LOGBUFFERS,and CDR_QUEUEMEM . . . . . . . . . . . . . . 1-28

CKPTINTVL . . . . . . . . . . . . . . . . . . . . . 1-29

CLEANERS . . . . . . . . . . . . . . . . . . . . . 1-30

CONFIGSIZE . . . . . . . . . . . . . . . . . . . . . 1-30

CONSOLE . . . . . . . . . . . . . . . . . . . . . . 1-32

COSERVER . . . . . . . . . . . . . . . . . . . . . 1-33

1-2 Infor

Datagram Configuration Parameters . . . . . . . . . . . . . 1-34

DATASKIP . . . . . . . . . . . . . . . . . . . . . . 1-35

DBSERVERALIASES . . . . . . . . . . . . . . . . . . 1-36

DBSERVERNAME . . . . . . . . . . . . . . . . . . . 1-38

DBSPACETEMP . . . . . . . . . . . . . . . . . . . . 1-40

DD_HASHMAX . . . . . . . . . . . . . . . . . . . . 1-45

DD_HASHSIZE . . . . . . . . . . . . . . . . . . . . 1-45

DEADLOCK_TIMEOUT . . . . . . . . . . . . . . . . . 1-46

DIRECTIVES . . . . . . . . . . . . . . . . . . . . . 1-46

DRAUTO . . . . . . . . . . . . . . . . . . . . . . 1-47

DRINTERVAL . . . . . . . . . . . . . . . . . . . . 1-48

DRLOSTFOUND . . . . . . . . . . . . . . . . . . . 1-49

DRTIMEOUT . . . . . . . . . . . . . . . . . . . . . 1-50

DS_ADM_POLICY . . . . . . . . . . . . . . . . . . . 1-51

DS_MAX_QUERIES . . . . . . . . . . . . . . . . . . 1-51

DS_MAX_SCANS . . . . . . . . . . . . . . . . . . . 1-53

DS_TOTAL_MEMORY . . . . . . . . . . . . . . . . . 1-54

DUMPCNT . . . . . . . . . . . . . . . . . . . . . 1-58

DUMPCORE . . . . . . . . . . . . . . . . . . . . . 1-59

DUMPDIR . . . . . . . . . . . . . . . . . . . . . . 1-60

DUMPGCORE . . . . . . . . . . . . . . . . . . . . 1-61

DUMPSHMEM . . . . . . . . . . . . . . . . . . . . 1-62

END . . . . . . . . . . . . . . . . . . . . . . . . 1-63

FILLFACTOR . . . . . . . . . . . . . . . . . . . . . 1-63

HETERO_COMMIT . . . . . . . . . . . . . . . . . . 1-64


IDX_RA_PAGES . . . . . . . . . . . . . . . . . . . . 1-65

IDX_RA_THRESHOLD . . . . . . . . . . . . . . . . . . 1-66

ISM_DATA_POOL and ISM_LOG_POOL . . . . . . . . . . . 1-67

ISOLATION_LOCKS . . . . . . . . . . . . . . . . . . . 1-67

JVPxxx and JVMTHREAD . . . . . . . . . . . . . . . . . 1-68

LBU_PRESERVE . . . . . . . . . . . . . . . . . . . . 1-69

LOCKS . . . . . . . . . . . . . . . . . . . . . . . 1-70

LOG_BACKUP_MODE . . . . . . . . . . . . . . . . . . 1-71

LOGBUFF . . . . . . . . . . . . . . . . . . . . . . 1-71

LOGFILES . . . . . . . . . . . . . . . . . . . . . . 1-72

LOGSIZE . . . . . . . . . . . . . . . . . . . . . . . 1-74

LOGSMAX . . . . . . . . . . . . . . . . . . . . . . 1-76

LRUS . . . . . . . . . . . . . . . . . . . . . . . . 1-77

LRU_MAX_DIRTY . . . . . . . . . . . . . . . . . . . 1-78

LRU_MIN_DIRTY. . . . . . . . . . . . . . . . . . . . 1-78

LTAPEBLK . . . . . . . . . . . . . . . . . . . . . . 1-79

LTAPEDEV . . . . . . . . . . . . . . . . . . . . . . 1-81

LTAPESIZE . . . . . . . . . . . . . . . . . . . . . . 1-82

LTXEHWM . . . . . . . . . . . . . . . . . . . . . . 1-83

LTXHWM . . . . . . . . . . . . . . . . . . . . . . 1-84

MAX_CHUNKS . . . . . . . . . . . . . . . . . . . . 1-85

MAX_DBSLICES . . . . . . . . . . . . . . . . . . . . 1-86

MAX_DBSPACES . . . . . . . . . . . . . . . . . . . . 1-87

MAX_PDQPRIORITY . . . . . . . . . . . . . . . . . . 1-88

MIRROR . . . . . . . . . . . . . . . . . . . . . . . 1-90

Configuration Parameters 1-3

1-4 Infor

MIRROROFFSET . . . . . . . . . . . . . . . . . . . 1-91

MIRRORPATH . . . . . . . . . . . . . . . . . . . . 1-92

MSGPATH . . . . . . . . . . . . . . . . . . . . . . 1-93

MULTIPROCESSOR . . . . . . . . . . . . . . . . . . 1-94

NETTYPE . . . . . . . . . . . . . . . . . . . . . . 1-94

NOAGE . . . . . . . . . . . . . . . . . . . . . . . 1-99

NODE . . . . . . . . . . . . . . . . . . . . . . . 1-100

NUMAIOVPS. . . . . . . . . . . . . . . . . . . . . 1-101

NUMCPUVPS . . . . . . . . . . . . . . . . . . . . 1-102

NUMFIFOVPS . . . . . . . . . . . . . . . . . . . . 1-103

OFF_RECVRY_THREADS . . . . . . . . . . . . . . . . 1-103

ON_RECVRY_THREADS . . . . . . . . . . . . . . . . 1-104

ON-Bar Parameters . . . . . . . . . . . . . . . . . . . 1-105

ONDBSPACEDOWN . . . . . . . . . . . . . . . . . . 1-108

OPCACHEMAX . . . . . . . . . . . . . . . . . . . . 1-109

OPTCOMPIND . . . . . . . . . . . . . . . . . . . . 1-110

OPT_GOAL . . . . . . . . . . . . . . . . . . . . . 1-111

PAGESIZE . . . . . . . . . . . . . . . . . . . . . . 1-112

PC_HASHSIZE . . . . . . . . . . . . . . . . . . . . 1-114

PC_POOLSIZE . . . . . . . . . . . . . . . . . . . . 1-114

PDQPRIORITY . . . . . . . . . . . . . . . . . . . . 1-115

PHYSBUFF. . . . . . . . . . . . . . . . . . . . . . 1-117

PHYSDBS . . . . . . . . . . . . . . . . . . . . . . 1-118

PHYSFILE . . . . . . . . . . . . . . . . . . . . . . 1-120

PHYSSLICE . . . . . . . . . . . . . . . . . . . . . 1-121


PLAN_MONITORING . . . . . . . . . . . . . . . . . . 1-122

RA_PAGES . . . . . . . . . . . . . . . . . . . . . . 1-122

RA_THRESHOLD. . . . . . . . . . . . . . . . . . . . 1-123

RESIDENT . . . . . . . . . . . . . . . . . . . . . . 1-124

RESTARTABLE_RESTORE . . . . . . . . . . . . . . . . . 1-125

ROOTNAME . . . . . . . . . . . . . . . . . . . . . 1-126

ROOTOFFSET . . . . . . . . . . . . . . . . . . . . . 1-127

ROOTPATH . . . . . . . . . . . . . . . . . . . . . . 1-128

ROOTSIZE . . . . . . . . . . . . . . . . . . . . . . 1-129

ROOTSLICE . . . . . . . . . . . . . . . . . . . . . . 1-130

SBSPACENAME . . . . . . . . . . . . . . . . . . . . 1-131

SENDEPDS . . . . . . . . . . . . . . . . . . . . . . 1-132

SERVERNUM . . . . . . . . . . . . . . . . . . . . . 1-133

SHMADD . . . . . . . . . . . . . . . . . . . . . . 1-134

SHMBASE . . . . . . . . . . . . . . . . . . . . . . 1-135

SHMTOTAL . . . . . . . . . . . . . . . . . . . . . . 1-136

SHMVIRTSIZE . . . . . . . . . . . . . . . . . . . . . 1-137

SINGLE_CPU_VP . . . . . . . . . . . . . . . . . . . . 1-138

STACKSIZE . . . . . . . . . . . . . . . . . . . . . . 1-140

STAGEBLOB . . . . . . . . . . . . . . . . . . . . . 1-141

STMT_CACHE . . . . . . . . . . . . . . . . . . . . . 1-141

STMT_CACHE_SIZE. . . . . . . . . . . . . . . . . . . 1-142

SYSALARMPROGRAM. . . . . . . . . . . . . . . . . . 1-143

SYSSBSPACENAME . . . . . . . . . . . . . . . . . . . 1-143

TAPEBLK. . . . . . . . . . . . . . . . . . . . . . . 1-145


1-6 Infor

TAPEDEV . . . . . . . . . . . . . . . . . . . . . . 1-146

TAPESIZE . . . . . . . . . . . . . . . . . . . . . . 1-147

TBLSPACE_STATS . . . . . . . . . . . . . . . . . . . 1-148

TXTIMEOUT . . . . . . . . . . . . . . . . . . . . . 1-148

USEOSTIME . . . . . . . . . . . . . . . . . . . . . 1-149

VPCLASS . . . . . . . . . . . . . . . . . . . . . . 1-150

XMF Configuration Parameters. . . . . . . . . . . . . . . 1-158


In This ChapterThis chapter describes the ONCONFIG file conventions, lists the configurationparameters in the ONCONFIG file, and provides a short discussion of eachparameter.

ONCONFIG File ConventionsThe ONCONFIG environment variable specifies the file that contains theconfiguration parameters. This manual often refers to this file as theONCONFIG file. The database server uses the ONCONFIG file duringinitialization.

Format of ONCONFIG FileIn the ONCONFIG file, each parameter is on a separate line. The file can alsocontain blank lines and comment lines that start with a # symbol. Thefollowing line shows the syntax for a parameter line:

PARAMETER_NAME parameter_value #comment

Parameters and their values in the ONCONFIG file are case sensitive. Theparameter names are always uppercase. If the value entry is described withuppercase letters, you must use uppercase (for example, the CPU value of theNETTYPE parameter). You must put white space (tabs, spaces, or both)between the parameter name, parameter value, and optional comment. Donot use any tabs or spaces within a parameter value.


ONCONFIG File Templates

ONCONFIG File TemplatesThe database server provides a template for a configuration file that containsinitial values for many of the ONCONFIG parameters. You can copy and tailorthe template to your specific configuration.

Informix Dynamic Server 2000 provides onconfig.std as a template configu-ration file that you can copy and tailor to your specific configuration. ♦

Informix Extended Parallel Server provides two templates for the ONCONFIGfile that you can copy and tailor to your specific configuration:

■ onconfig.std for a single-coserver configuration

■ onconfig.xps for a multiple-coserver configuration ♦

If you omit a parameter value in your copy of the configuration file, thedatabase server either uses default values in onconfig.std or calculates valuesbased on other parameter values. For information on the order of files inwhich the database server looks for configuration values during initial-ization, refer to the chapter on initializing the database server in theAdministrator’s Guide.

Warning: Do not modify onconfig.std. The database server provides theonconfig.std configuration file as a template and not as a functional configuration.

The following table lists the locations of the ONCONFIG and onconfig.stdfiles.

IDS

XPS

OperatingSystem ONCONFIG File Template File

UNIX $INFORMIXDIR/etc/$ONCONFIG $INFORMIXDIR/etc/onconfig.std$INFORMIXDIR/etc/onconfig.xps (XPS)

Windows NT(IDS)

%INFORMIXDIR%\etc\%ONCONFIG% %INFORMIXDIR%\etc\onconfig.std

1-8 Informix Administrator’s Reference

ONCONFIG File Templates

To prepare the ONCONFIG file

1. Copy the pertinent template file:

■ onconfig.std

■ onconfig.xps ♦2. Modify the copy of the template file.

3. Set the ONCONFIG environment variable to the name of the copy ofthe pertinent template file.

If you do not set ONCONFIG, the default filename is onconfig.

For more details on why you might want to modify the default configurationparameters, refer to the chapter on installing and configuring the databaseserver in the Administrator’s Guide.

For more information about the ONCONFIG environment variable, see theInformix Guide to SQL: Reference. For more information about the ONCONFIGfiles, see Appendix A, “Files That the Database Server Uses.”

XPS


ONCONFIG Parameters

ONCONFIG ParametersThis section provides the following information:

■ A list of each configuration parameter with database servercompatibility

■ A description of the attributes listed for each configurationparameter

Summary of Configuration ParametersThe configuration parameters and database server compatibility are asfollows.

Configuration Parameter IDS XPS

Can becoserverspecific

Alwayscoserverspecific Reference

AC_MSGPATH ✔ page 1-19

AC_STORAGE ✔ page 1-19

AC_VERBOSE ✔ page 1-19

ADTERR ✔ page 1-19

ADTMODE ✔ page 1-19

ADTPATH ✔ page 1-19

ADTSIZE ✔ page 1-19

AFF_NPROCS ✔ ✔ ✔ page 1-20

AFF_SPROC ✔ ✔ ✔ page 1-21

ALARMPROGRAM ✔ ✔ page 1-22

ALLOW_NEWLINE ✔ page 1-25

ASYNCRQT ✔ page 1-26

BAR_ACT_LOG ✔ ✔ page 1-104

(1 of 8)


ONCONFIG Parameters

BAR_BOOT_DIR ✔ page 1-104

BAR_BSALIB_PATH ✔ ✔ page 1-104

BAR_DBS_COSVR ✔ page 1-104

BAR_HISTORY ✔ ✔ page 1-104

BAR_IDLE_TIMEOUT ✔ page 1-104

BAR_LOG_COSVR ✔ page 1-104

BAR_MAX_BACKUP ✔ page 1-104

BAR_NB_XPORT_COUNT ✔ page 1-104

BAR_PROGRESS_FREQ ✔ ✔ page 1-104

BAR_RETRY ✔ ✔ page 1-104

BAR_SM ✔ page 1-104

BAR_SM_NAME ✔ page 1-104

BAR_WORKER_COSVR ✔ page 1-104

BAR_WORKER_MAX ✔ page 1-104

BAR_XFER_BUF_SIZE ✔ page 1-104

BAR_XFER_BUFSIZE ✔ page 1-104

BAR_XPORT_COUNT ✔ page 1-104

BUFFERS ✔ ✔ page 1-26

CDR_DSLOCKWAIT ✔ page 1-28

CDR_EVALTHREADS ✔ page 1-28

CDR_LOGBUFFERS ✔ page 1-28

CDR_QUEUEMEM ✔ page 1-28

CKPTINTVL ✔ ✔ page 1-29




(2 of 8)


ONCONFIG Parameters

CLEANERS ✔ ✔ page 1-30

CONFIGSIZE ✔ page 1-30

CONSOLE ✔ ✔ page 1-32

COSERVER ✔ ✔ page 1-33

DATASKIP ✔ ✔ page 1-35

DBSERVERALIASES ✔ ✔ page 1-36

DBSERVERNAME ✔ ✔ page 1-38

DBSPACETEMP ✔ ✔ page 1-40

DD_HASHMAX ✔ page 1-45

DD_HASHSIZE ✔ page 1-45

DEADLOCK_TIMEOUT ✔ page 1-46

DGINFO ✔ page 1-34

DIRECTIVES ✔ page 1-46

DRINTERVAL ✔ page 1-47

DRLOSTFOUND ✔ page 1-48

DRTIMEOUT ✔ page 1-49

DS_ADM_POLICY ✔ page 1-50

DS_MAX_QUERIES ✔ ✔ page 1-50

DS_MAX_SCANS ✔ page 1-52

DS_TOTAL_MEMORY ✔ ✔ page 1-53

DUMPCNT ✔ ✔ page 1-57

DUMPCORE ✔ ✔ page 1-58

DUMPDIR ✔ ✔ page 1-59




(3 of 8)


ONCONFIG Parameters

DUMPGCORE ✔ ✔ page 1-60

DUMPSHMEM ✔ ✔ page 1-61

END ✔ ✔ page 1-62

FILLFACTOR ✔ ✔ page 1-62

HADDR ✔ ✔ page 1-34

HBUFFER ✔ page 1-156

HETERO_COMMIT ✔ page 1-63

IDX_RA_PAGES ✔ page 1-64

IDX_RA_THRESHOLD ✔ page 1-65

ISM_DATA_POOL ✔ ✔ ✔ page 1-66

ISM_LOG_POOL ✔ ✔ ✔ page 1-66

ISOLATION_LOCKS ✔ page 1-66

JDKVERSION ✔ page 1-67

JVPHOME ✔ page 1-67

JVPLOGFILE ✔ page 1-67

JVPPROPFILE ✔ page 1-67

JVPJAVAVM ✔ page 1-67

JVPJAVAHOME ✔ page 1-67

JVMTHREAD ✔ page 1-67

JVPJAVALIB ✔ page 1-67

JVPCLASSPATH ✔ page 1-67

LADDR ✔ ✔ page 1-34

LBUFFER ✔ page 1-156




(4 of 8)


ONCONFIG Parameters

LBU_PRESERVE ✔ page 1-68

LOCKS ✔ ✔ page 1-69

LOG_BACKUP_MODE ✔ page 1-70

LOGBUFF ✔ ✔ page 1-70

LOGFILES ✔ ✔ page 1-71

LOGSIZE ✔ ✔ page 1-73

LOGSMAX ✔ ✔ page 1-75

LRUS ✔ ✔ page 1-76

LRU_MAX_DIRTY ✔ ✔ page 1-77

LRU_MIN_DIRTY ✔ ✔ page 1-77

LTAPEBLK ✔ page 1-78

LTAPEDEV ✔ page 1-80

LTAPESIZE ✔ page 1-80

LTXEHWM ✔ ✔ page 1-82

LTXHWM ✔ ✔ page 1-83

MAX_CHUNKS ✔ page 1-84

MAX_DBSLICES ✔ page 1-85

MAX_DBSPACES ✔ page 1-86

MAX_PDQPRIORITY ✔ ✔ page 1-87

MIRROR ✔ ✔ page 1-89

MIRROROFFSET ✔ ✔ ✔ page 1-90

MIRRORPATH ✔ ✔ ✔ page 1-91

MSGPATH ✔ ✔ page 1-92




(5 of 8)


ONCONFIG Parameters

MULTIPROCESSOR ✔ ✔ page 1-93

NETTYPE ✔ ✔ page 1-93

NOAGE ✔ ✔ page 1-98

NODE ✔ ✔ page 1-99

NUMAIOVPS ✔ ✔ page 1-100

NUMCPUVPS ✔ ✔ page 1-101

NUMFIFOVPS ✔ page 1-102

OFF_RECVRY_THREADS ✔ ✔ page 1-102

ON_RECVRY_THREADS ✔ ✔ page 1-103

ONDBSPACEDOWN ✔ ✔ page 1-107

OPCACHEMAX ✔ page 1-108

OPTCOMPIND ✔ ✔ page 1-109

OPT_GOAL ✔ page 1-110

PAGESIZE ✔ page 1-111

PC_HASHSIZE ✔ ✔ page 1-113

PC_POOLSIZE ✔ ✔ page 1-113

PDQPRIORITY ✔ page 1-114

PHYSBUFF ✔ ✔ page 1-116

PHYSDBS ✔ ✔ ✔ page 1-117

PHYSFILE ✔ ✔ ✔ page 1-118

PHYSSLICE ✔ page 1-119

PLAN_MONITORING ✔ page 1-120

RA_PAGES ✔ ✔ page 1-120




(6 of 8)


ONCONFIG Parameters

RA_THRESHOLD ✔ ✔ page 1-121

RESIDENT ✔ ✔ page 1-122

RESTARTABLE_RESTORE ✔ page 1-123

ROOTNAME ✔ ✔ ✔ page 1-124

ROOTOFFSET ✔ ✔ ✔ page 1-125

ROOTPATH ✔ ✔ ✔ page 1-126

ROOTSIZE ✔ ✔ ✔ page 1-127

ROOTSLICE ✔ page 1-128

SADDR ✔ ✔ page 1-34

SBSPACENAME ✔ ✔ page 1-129

SBUFFER ✔ page 1-156

SENDEPDS ✔ page 1-130

SERVERNUM ✔ ✔ page 1-131

SHMADD ✔ ✔ page 1-132

SHMBASE ✔ ✔ page 1-133

SHMTOTAL ✔ ✔ page 1-134

SHMVIRTSIZE ✔ ✔ page 1-135

SINGLE_CPU_VP ✔ ✔ page 1-136

STACKSIZE ✔ ✔ page 1-138

STAGEBLOB ✔ page 1-139

STMT_CACHE ✔ page 1-139

STMT_CACHE_SIZE ✔ page 1-140

SYSALARMPROGRAM ✔ page 1-141




(7 of 8)


ONCONFIG Parameters

Parameter AttributesThis chapter describes one or more of the following attributes (if relevant) foreach parameter.

SYSSBSPACENAME ✔ page 1-141

TAPEBLK ✔ page 1-143

TAPEDEV ✔ page 1-144

TAPESIZE ✔ page 1-145

TBLSPACE_STATS ✔ ✔ page 1-146

TXTIMEOUT ✔ page 1-146

USEOSTIME ✔ ✔ page 1-147

VPCLASS ✔ page 1-148

Attribute Description

onconfig.std value

The default value that appears in the onconfig.std file

The database server uses these default values for both a singlecoserver configuration and a multiple-coserver configuration.(XPS)

if not present The value that the database server supplies if the parameter ismissing from your ONCONFIG file

This value might not be present in onconfig.std, and thedatabase server calculates the value based on other values inonconfig.std.

units The units in which the parameter is expressed

(1 of 2)




(8 of 8)


ONCONFIG Parameters

Using a Utility to Change a Parameter ValueUse one of these tools to change the value of a configuration parameter.

separators The separators that can be used when the parameter value hasseveral parts

Do not use white space within a parameter value.

range of values The valid values for this parameter

takes effect The time at which a change to the value of the parameter affectsthe operation of the database server

Reinitialize shared memory means to shut down and restart thedatabase server.

Disk is initialized means to reinitialize the database server.

utilities The database server utilities that you can use to change thevalue of the parameter

For more information, see “Using a Utility to Change aParameter Value” on page 1-18.

refer to Cross-reference to further discussion

Tool Description

ON-Monitor(IDS, UNIX)

In the attributes section of each parameter description, theutilities section lists the menu choices and item name that displaythe parameter in ON-Monitor.

In ON-Monitor, some of the responses are Y/N (yes/no). Whenthose responses are recorded in the ONCONFIG file, Y becomes1, and N becomes 0.

Command-lineutility

In the attributes section of the descriptions for most parameters,the utilities section lists one or more command-line utilities thatyou can use to change a parameter value.

Text editor You can use a text editor to modify the ONCONFIG file.

Attribute Description

(2 of 2)


AC_MSGPATH, AC_STORAGE, and AC_VERBOSE

AC_MSGPATH, AC_STORAGE, and AC_VERBOSEAC_MSGPATH, AC_STORAGE, and AC_VERBOSE are archecker configurationparameters that are stored in the AC_CONFIG file. The ac_config.std filecontains the default archecker configuration parameters, which you canmodify. ON-Bar uses these parameters when it verifies a backup. For infor-mation on these parameters, see the Backup and Restore Guide.

These parameters take effect when ON-Bar starts.

ADTERR, ADTMODE, ADTPATH, and ADTSIZEADTERR, ADTMODE, ADTPATH, and ADTSIZE are configuration parametersfor auditing. For information on these parameters, see the Trusted FacilityManual.

ConfigurationParameter Description

AC_MSGPATH Specifies the location of the archecker message file.

AC_STORAGE Specifies the location of the temporary files thatarchecker builds.

AC_VERBOSE Specifies either verbose or quiet mode for archeckermessages.

IDS

IDS

UNIX


AFF_NPROCS

AFF_NPROCS

On multiprocessor computers that support processor affinity, AFF_NPROCSspecifies the number of CPUs to which the database server can bind CPUvirtual processors. Binding a CPU virtual processor to a CPU causes thevirtual processor to run exclusively on that CPU. The database server assignsCPU virtual processors to CPUs in serial fashion, starting with the processornumber that AFF_SPROC specifies.

Extended Parallel Server can run on the following types of parallel-processing platforms:

■ Massively parallel processing (MPP) systems composed of multiplecomputers that are connected to a single high-speed communicationsubsystem

■ Clusters of stand-alone computers that are connected over a high-speed network

■ Symmetric multiprocessing (SMP) computers

onconfig.std value

0

units Number of CPUs

range of values 0 through number of CPUs in the computer

For Extended Parallel Server:The number of CPUs in a node or a computer

takes effect When shared memory is initialized

utilities ON-Monitor: Parameters, perFormance, Num Procs toAffinity (IDS, UNIX)

refer to The following material:

■ Virtual-processor classes in the chapter on virtualprocessors and threads in the Administrator’s Guide

■ “AFF_SPROC” on page 1-21

XPS


AFF_SPROC

On parallel-processing platforms that support processor affinity, AFF_NPROCSspecifies the number of CPUs to which the database server or coserver bindsCPU virtual processors. Binding a CPU virtual processor to a CPU causes thevirtual processor to run exclusively on that node. The database server orcoserver assigns CPU virtual processors to CPUs in serial fashion, startingwith the processor number that AFF_SPROC specifies. ♦

Informix recommends that you use VPCLASS instead of AFF_NPROCS tospecify the number of CPUs. You cannot use both AFF_NPROCS and VPCLASScpu in the same ONCONFIG file. For more information, refer to “VPCLASS”on page 1-148. ♦

AFF_SPROC

On multiprocessor computers that support processor affinity, AFF_SPROCspecifies the CPU, starting with 0, on which the database server starts bindingCPU virtual processors to CPUs. The AFF_NPROCS parameter specifies thenumber of CPUs that the database server will use. The NUMCPUVPSparameter specifies the number of CPU virtual processors to be started, andthe AFF_SPROC parameter specifies the CPU on which the first virtualprocessor is to start. For example, if you assign eight CPUs (AFF_NPROCS =8), and set NUMCPUVPS to 3 and AFF_SPROC to 5, the database server bindsCPU virtual processors to the fifth, sixth, and seventh CPUs.

onconfig.std value

0

units CPU number

range of values 0 through (AFF_NPROCS - NUMCPUVPS + 1)


utilities ON-Monitor: Parameters, perFormance, Proc num (tostart with) (IDS, UNIX)

refer to Virtual-processor classes in the chapter on virtualprocessors and threads in the Administrator’s Guide

IDS


ALARMPROGRAM

On parallel-processing platforms that support processor affinity, AFF_SPROCspecifies the CPU at which the database server or coserver starts binding CPUvirtual processors to CPUs. The AFF_NPROCS parameter specifies the numberof CPUs to be assigned to the database server or coserver. ♦

Informix recommends that you use VPCLASS instead of AFF_SPROC tospecify processor affinity. You cannot use both AFF_SPROC and VPCLASS cpuin the same ONCONFIG file. For more information, refer to “VPCLASS” onpage 1-148. ♦

ALARMPROGRAMUse the ALARMPROGRAM parameter to display event alarms.

ALARMPROGRAM on Dynamic Serveronconfig.std value

On UNIX: /usr/informix/etc/log_full.shOn Windows NT: %INFORMIXDIR%\etc\log_full.bat

if not present On UNIX: /usr/informix/etc/no_log.shOn Windows NT: %INFORMIXDIR%\etc\no_log.bat

range of values Pathname


utilities ON-Monitor: Parameters, diaGnostics (UNIX)

refer to The following materials:

■ Appendix D, “Event Alarms”

■ Backup and Restore Guide

XPS

IDS

IDS


ALARMPROGRAM

Informix has supplied two sample scripts: log_full.sh automates logical-logbackups, and no_full.sh disables automatic logical-log backups. SetALARMPROGRAM to log_full.sh to back up logical logs automatically whenthe database server issues a log-full event alarm. Backup media shouldalways be available for automatic log backups.

Set ALARMPROGRAM to no_log.sh if you do not want to back up logical logsautomatically. ♦

On Windows NT, use the log_full.bat and no_log.bat files to controlautomatic backup of logical logs. ♦

Instead of using the scripts that Informix supplies, you can write your ownshell script, batch file, or binary program to execute events. Set ALARM-PROGRAM to the full pathname of this file. The database server executes thisscript when noteworthy events occur. These events include database, table,index, or simple-large-object failure; all logs are full; internal subsystemfailure; initialization failure; and long transactions.

For example, your script can use the event class ID ($EVENT_CLASS) andevent class message ($EVENT_MSG) parameters to take administrative actionwhen a table failure occurs. For more information, see “Event-Alarm Param-eters” on page D-2.

UNIX

WIN NT


ALARMPROGRAM

ALARMPROGRAM on Extended Parallel Server

By default, no alarms are reported. Set ALARMPROGRAM to the pathname ofyour alarm script to process alarms as they occur. Informix provides a samplealarm script, $INFORMIXDIR/bin/onsyslog.sh, which formats and forwardsalarms to syslog,s the UNIX system message logger. Examples of alarmsinclude messages about database server mode changes or logical logs.

The arguments that are passed to the alarm script are different for ExtendedParallel Server and Dynamic Server. For details, see “Using ALARM-PROGRAM to Capture Events” on page D-1.

ALARMPROGRAM does not control continuous logical-log backups. To startcontinuous logical-log backups, set the LOG_BACKUP_MODE parameter toCONT. For details, see “LOG_BACKUP_MODE” on page 1-70.

onconfig.std value

None

if not present None

range of values Pathname of the script that you run to display event alarms



■ Appendix D, “Event Alarms”

■ Documentation notes (see “Documentation Notes,Release Notes, Machine Notes” on page 19)

XPS


ALLOW_NEWLINE

ALLOW_NEWLINE

You can specify that you want the database server to allow the newlinecharacter (\n) in a quoted string either for all sessions or for a specific session.A session is the duration of a client connection to the database server.

To allow or disallow newline characters in quoted strings for all sessions, setthe ALLOW_NEWLINE parameter.

To allow or disallow a newline character in a quoted string for a particularsession, you must execute the ifx_allow_newline(boolean) user-definedroutine.

onconfig.std value

0

range of values 0 = Disallow the newline character in quoted strings forall sessions.

1 = Allow the newline character in quoted strings for allsessions.



■ Quoted strings in the Informix Guide to SQL: Syntax

■ Newline characters in quoted strings in the InformixESQL/C Programmer’s Manual

IDS


ASYNCRQT

ASYNCRQT

ASYNCRQT specifies the number of outstanding receive requests used foreach small and large endpoint on a coserver when you configure largecommunications buffers to send and receive data between coservers. IfASYNCRQT is not configured, the number of requests is 10 for each small andlarge endpoint. The number of requests for huge endpoints is fixed at 4.

BUFFERS

onconfig.std value

None

units Number of requests

range of values Positive integers


refer to “SENDEPDS” on page 1-130

onconfig.std value

1000

onconfig.xpsvalue

1000

units Number of buffers

range of values For Dynamic Server or Extended Parallel Server on UNIX:100 through 786,432 buffers (786,288 = 768 * 1024)

For Dynamic Server on Windows NT:100 through 524,288 buffers (524,288 = 512 * 1024)

For any 64-bit platform:100 through 231-1 (Might be less on some 64 -bitplatforms due to operating-system limitations)

XPS


BUFFERS

BUFFERS specifies the maximum number of shared-memory buffers that thedatabase server user threads have available for disk I/O on behalf of clientapplications. Therefore, the number of buffers that the database serverrequires depends on the applications. For example, if the database serveraccesses 15 percent of the application data 90 percent of the time, you need toallocate enough buffers to hold that 15 percent.

In general, buffer space should range from 20 to 25 percent of physicalmemory. Informix recommends that you calculate all other shared-memoryparameters after you set buffer space (BUFFERS * system page size) to 20percent of physical memory.

BUFFERS and Read-AheadIf you also want to perform read-ahead, increase the value of BUFFERSfurther. Once you have configured all other shared-memory parameters, ifyou find that you can afford to increase the size of shared memory, increasethe value of BUFFERS until buffer space reaches the recommended 25 percentmaximum.

System Page SizeThe system page size is platform dependent on Dynamic Server. ♦

The system page size is configurable, with a default page size of 4096 bytes.For more information, see “PAGESIZE” on page 1-111. ♦


utilities ON-Monitor: Parameters, Shared_Memory, Max # ofBuffers (IDS, UNIX)


■ Shared-memory buffer pool in the shared-memorychapter of the Administrator’s Guide

■ “RA_PAGES” on page 1-120

■ “RA_THRESHOLD” on page 1-121

■ Your Performance Guide

IDS

XPS


CDR_DSLOCKWAIT, CDR_EVALTHREADS, CDR_LOGBUFFERS, and CDR_QUEUEMEM

You can use the following utilities to display the system page size.

BUFFERS and Smart Large ObjectsIf your databases contain smart large objects, you need to consider themwhen you calculate the value for BUFFERS because smart large objects passthrough the regular shared-memory buffer pool. Informix recommends thefollowing formula for calculating the minimum impact of smart large objectson the value of BUFFERS:

BUFFERS = BUFFERS + (Server page size in kilobytes *concurrently open smart large objects) + desired amount oflarge-object user data to buffer

CDR_DSLOCKWAIT, CDR_EVALTHREADS,CDR_LOGBUFFERS, and CDR_QUEUEMEMThe CDR_DSLOCKWAIT, CDR_EVALTHREADS, CDR_LOGBUFFERS, andCDR_QUEUEMEM parameters apply to Enterprise Replication. For infor-mation about these parameters, see the Guide to Informix EnterpriseReplication.

Utility Description

onstat -b Displays the system page size, given as buffer size on the last line ofthe output.

oncheck -pr(IDS)

Checks the root-dbspace reserved pages and displays the systempage size in the first section of its output.

ON-Monitor(IDS, UNIX)

Displays the system page size under the Parameters:Shared-Memory option, which does not require the database server to berunning, and the Parameters:Initialize option.

onutil CHECKRESERVED(XPS)

Checks the root-dbspace reserved pages and displays the systempage size in the first section of its output.

IDS

IDS


CKPTINTVL

CKPTINTVL

CKPTINTVL specifies the frequency, expressed in seconds, at which thedatabase server checks to determine whether a checkpoint is needed. Whena full checkpoint occurs, all pages in the shared-memory buffer pool arewritten to disk. When a fuzzy checkpoint occurs, nonfuzzy pages are writtento disk, and the page numbers of fuzzy pages are recorded in the logical log.

If you set CKPTINTVL to an interval that is too short, the system spends toomuch time performing checkpoints, and the performance of other worksuffers. If you set CKPTINTVL to an interval that is too long, fast recoverymight take too long.

In practice, 30 seconds is the smallest interval that the database server checks.If you specify a checkpoint interval of 0, the database server does not checkif the checkpoint interval has elapsed. However, the database server stillperforms checkpoints. Other conditions, such as the physical log becoming75 percent full, also cause the database server to perform checkpoints.

onconfig.std value

300

units Seconds

range of values Any value greater than or equal to 0


utilities ON-Monitor: Parameters, perFormance, CheckpointInterval (IDS, UNIX)


■ Checkpoints in the shared-memory and fast-recoverychapters of the Administrator’s Guide



CLEANERS

CLEANERS

CLEANERS specifies the number of page-cleaner threads available during thedatabase server operation. By default, the database server always runs onepage-cleaner thread. A general guideline is one page cleaner per disk drive.The value specified has no effect on the size of shared memory.

CONFIGSIZE

CONFIGSIZE specifies the size of the safewrite area, which is a portion of theinitial chunk of the root dbspace in which the database server stores coserver-configuration information and other data that is required for maintainingdata consistency across coservers.

onconfig.std value

1

units Number of page-cleaner threads

range of values 32-bit platforms: 1 through 12864-bit platforms: 1 through 512


utilities ON-Monitor: Parameters, Shared-Memory, Number ofPage Cleaners (IDS, UNIX)

refer to How the database server flushes data to disk in theshared-memory chapter of the Administrator’s Guide

onconfig.std value

STANDARD

range of values SMALL, STANDARD, or LARGE


refer to Safewrite area in the chapter on where data is stored inthe Administrator’s Guide

XPS


CONFIGSIZE

If you are using a single-coserver configuration with no more that 128dbspaces, set CONFIGSIZE to SMALL. If you are using more than one coserveror more than 128 dbspaces, use the following table to select a value forCONFIGSIZE. Use the largest value that matches any one of the configurationcriteria listed in the table for your database server. For example, if yourdatabase server has 30 coservers and 3 logslices, use STANDARD as the valuefor CONFIGSIZE.

If you need to use more chunks, dbspaces, or dbslices than a CONFIGSIZE ofLARGE allows, set the MAX_CHUNKS, MAX_DBSPACES, or MAX_DBSLICESparameter to the desired value. The following table displays the range ofCONFIGSIZE values for various items.

ConfigurationCriteria

Range of CONFIGSIZE Values

SMALL STANDARD LARGE MAX* Values

Chunks 1 to 128 1 to 2048 1 to 8192 MAX_CHUNKS0 to 32,767(See page 1-84.)

Dbspaces 1 to 128 1 to 2048 1 to 8192 MAX_DBSPACES0 to 32,767(See page 1-85.)

Coservers 1 to 20 1 to 256 1 to 511

Cogroups 1 to 20 1 to 256 1 to 511

Cogroup Members 1 to 400 1 to 4096 1 to 8911

Dbslices 0 to 28 1 to 256 1 to 512 MAX_DBSLICES0 to 2047(See page 1-86.)

Logslices 0 to 16 1 to 63 1 to 63


CONSOLE

When you allocate the initial chunk for the root dbspace of any coserver, youmust ensure that enough space is available for the safewrite area. This spaceis in addition to any other space you might need for other information thatyou store in the root dbspace. The following table indicates the amount ofspace that is required for each value of CONFIGSIZE. Add this amount to thesize of the initial chunk of the root dbspace in each coserver.

If you do not provide enough space for the safewrite area, the database writesa message to the transaction log to report this situation. To increase the sizeof the safewrite area, select the next-larger value for CONFIGSIZE and reini-tialize the database server. If insufficient space is available in the rootdbspace, you might have to add a chunk before you reinitialize the databaseserver.

CONSOLE

CONSOLE specifies the pathname and the filename for console messages.

Value Size

SMALL 170 kilobytes

STANDARD 1.7 megabytes

LARGE 6.2 megabytes

onconfig.std value

On UNIX: /dev/consoleOn Windows NT: console.log



utilities ON-Monitor: Parameters, diaGnostics, Console Msgs(IDS, UNIX)

refer to The system console in the chapter on database serveradministration in the Administrator’s Guide


COSERVER

COSERVER

The COSERVER configuration parameter specifies the numeric identificationof a coserver. The coserver number must be unique among all coserverswithin Extended Parallel Server. The coservers must be numbered consecu-tively, starting at 1.

The COSERVER parameter begins a coserver-specific section in yourONCONFIG file.

You can assign COSERVER 1 to any node. To facilitate administration, youmight want to assign COSERVER 1 on NODE 1, COSERVER 2 on NODE 2, andso forth.

Clients specify a coserver name when they connect to a connection coserver.The COSERVER parameter is part of this coserver name, which has thefollowing format:

dbservername.coserver-number

In the name, dbservername is the value that you assign to theDBSERVERNAME configuration parameter when you prepare the ONCONFIGconfiguration file. And coserver-number is the value that you assign to theCOSERVER configuration parameter for the connection coserver.

onconfig.std value

None

onconfig.xps values

1 and 2

units Integer

range of values 1 to n


refer to Coserver-specific configuration parameters in the chapteron configuring the database server in the Administrator’sGuide

XPS


Datagram Configuration Parameters

Datagram Configuration ParametersThe Datagram configuration parameters override the automatic configu-ration of the datagram (DG) layer.

By default, the database server loads the single, most efficient DG layershared library for the platform. Communication between coservers on thesame node passes through the same network protocol layers (and possiblyeven onto the network media) as messages passed between coservers ondifferent nodes.

On some platforms, Extended Parallel Server supports the DG layer with theshared-memory extension. This DG layer uses shared memory to passmessages between coservers on the same node, thus bypassing networkprotocol layers. When the database server uses shared memory for intranodecommunication, performance improves because shared-memory communi-cation eliminates the overhead of network communication. The databaseserver creates and uses shared-memory segments automatically whenmultiple coservers are configured on a node. (Messages passed betweencoservers on different nodes continue to use the network protocol layers.)

For more information on these parameters, including the correct stringformat, see the machine notes.

Configuration Parameter Description

DGINFO Passes optional, platform-specific information to theDG layer. For a list of available DGINFO parametersand default values, see the machine notes.

HADDR Specifies the endpoint address for huge buffers. SeeHBUFFER on page 1-156.

LADDR Specifies the endpoint address for large buffers. SeeLBUFFER on page 1-156.

SADDR Specifies the endpoint address for small buffers. SeeSADDR on page 1-156.

XPS


DATASKIP

DATASKIP

DATASKIP lets you avoid points of media failure. This capability can result inhigher availability for your data. To instruct the database server to skip someor all unavailable fragments, set this parameter. Whenever the databaseserver skips over a dbspace during query processing, a warning is returned.

The previously reserved SQLCA warning flag sqlwarn.sqlwarn7 is set to W forInformix ESQL/C. ♦

Use the following syntax in the parameter line:

DATASKIP OFFDATASKIP ON dbspace1 dbspace2...DATASKIP ALL

syntax DATASKIP state

or

DATASKIP state dbspace1 dbspace2 ...

The state entry is required. If state is ON, at least one dbspaceentry is required.

onconfig.std value

None

if not present OFF

separators Space

range of values ALL = Skip all unavailable fragments.OFF = Turn off dataskip.ON = Skip some unavailable fragments.

utilities onspaces -f (See page 3-87.)ON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)


■ “Specify DATASKIP Parameter” on page 3-87


E/C


DBSERVERALIASES

Use the -f option of the onspaces utility to alter the value of the databaseserver configuration parameter at runtime. ♦

An application can use the SQL statement SET DATASKIP to override theDATASKIP value that the ONCONFIG parameter or onspaces sets. If the appli-cation then executes the SQL statement SET DATASKIP DEFAULT, theDATASKIP value for that session returns to whatever value is currently set forthe database server.

DBSERVERALIASESonconfig.std value

None

if not present None

separators Comma

range of values For Dynamic Server: Up to 128 lowercase characters forthe dbserver alias. The value for DBSERVERALIASES mustbe unique, begin with a letter or underscore, and containonly letters, numbers, underscores, or $ characters.

For Extended Parallel Server: Up to 18 lowercasecharacters for the coserver name. The value forDBSERVERALIASES must be unique, begin with a letter orunderscore, and contain only letters, numbers, orunderscores.

takes effect When shared memory is initialized. In addition, youmight need to update the sqlhosts file or registry of eachdatabase server.

UNIX utilities ON-Monitor: Parameters, Shared-Memory, Server Aliases(IDS, UNIX)

refer to The following topics in the chapter on client/servercommunications in the Administrator’s Guide:

■ ONCONFIG parameters for connectivity

■ Using multiple connection types

IDS


DBSERVERALIASES

DBSERVERALIASES specifies a list of alternative dbservernames. If thedatabase server supports more than one communication protocol (forexample, both an IPC mechanism and the TCP network protocol), you mustdescribe each valid connection to the database server with an entry in thesqlhosts file or registry. DBSERVERALIASES lets you assign multiple aliases toa database server, so each entry in the sqlhosts file or registry can have aunique name.

Important: You can specify up to 10 DBSERVERALIASES for a database server. If youattempt to define more than 10 DBSERVERALIASES, a warning message displays inthe database server message log.

For each alternate name listed in DBSERVERALIASES, the database serverstarts an additional listener thread. If you have many client applicationsconnecting to the database server, you can distribute the connection requestsbetween several listener threads and reduce connection time. To takeadvantage of the alternate connections, instruct some of your client applica-tions to use a CONNECT TO dbserveralias statement instead of CONNECT TOdbservername.

In Extended Parallel Server, clients specify a coserver name when theyconnect to a connection coserver. The DBSERVERALIASES parameter is part ofthis coserver name, which has the following format:

dbservername.coserver-number

In the name, dbservername is the same value that you assign to theDBSERVERALIASES configuration parameter when you specify more than onecommunication protocol in the ONCONFIG configuration file. And coserver-number is the same value that you assign to the COSERVER configurationparameter for the connection coserver. ♦

XPS


DBSERVERNAME

DBSERVERNAMEonconfig.std value

None

onconfig.xps value (XPS)

xps

if not present On UNIX: hostnameOn Windows NT: ol_hostname(The hostname variable is the name of the host computer.)

range of values For Dynamic Server: Up to 128 lowercase characters

For Extended Parallel Server: Up to 18 lowercasecharacters

DBSERVERNAME must begin with a letter and can includeany printable character except the following characters:

■ Uppercase characters

■ A field delimiter (space or tab)

■ A newline character

■ A comment character

■ A hyphen or minus character

takes effect When shared memory is initialized. The sqlhosts file orregistry of each database server that communicates withthis database server might need to be updated. Inaddition, the INFORMIXSERVER environment variablefor all users might need to be changed.

utilities ON-Monitor: Parameters, Shared-Memory, Server Name(IDS, UNIX)

refer to DBSERVERNAME configuration parameter in the chapteron client/server communications in the Administrator’sGuide


DBSERVERNAME

When you install the database server, specify the DBSERVERNAME.DBSERVERNAME specifies a unique name associated with this specificoccurrence of the database server. The value of DBSERVERNAME is called thedbservername. Each dbservername is associated with a communicationprotocol in the sqlhosts file or registry. If the database server uses multiplecommunication protocols, additional values for dbservername must bedefined with the DBSERVERALIASES configuration parameter.

Client applications use dbservername in the INFORMIXSERVERenvironment variable and in SQL statements such as CONNECT andDATABASE, which establish a connection to a database server.

Informix recommends that you use DBSERVERNAME to assign a nameinstead of using the default name because of possible conflict with otherdatabase servers on the same host computer.

Important: To avoid conflict with other instances of Informix database servers on thesame computer or node, Informix recommends that you use DBSERVERNAME toassign a dbservername explicitly.

Client applications can connect to any coserver in Extended Parallel Server.The database server appends the number of the coserver to thedbservername to form a coserver name (unless the dbservername is a dbservergroup name). You associate each coserver name with a communicationprotocol in the sqlhosts file. If the database server uses multiple communi-cation protocols, additional values for coserver name must be defined withthe DBSERVERALIASES configuration parameter.

Warning: Do not change the DBSERVERNAME configuration parameter to use adifferent communication protocol. Use a value that you specified in theDBSERVERALIASES configuration parameter instead.

For more information on coserver names, see preparing the connectivityinformation in the chapter on configuring the database server in the Admin-istrator’s Guide. ♦

XPS


DBSPACETEMP

DBSPACETEMPDBSPACETEMP gives the administrator the option to specify the location oftemporary tables. Use of this parameter enables the database server to spreadout I/O for temporary tables efficiently across multiple disks. The databaseserver also uses temporary dbspaces during backups to store the before-images of data that is overwritten while the backup is occurring.

For the order of precedence that the database server uses when it createsimplicit sort files, see your Performance Guide.

If a client application needs to specify an alternative list of dbspaces to use forits temporary-table locations, the client can use the DBSPACETEMPenvironment variable to enumerate them.

DBSPACETEMP for Dynamic Server

DBSPACETEMP specifies a list of dbspaces that the database server uses tomanage globally the storage of temporary tables.

onconfig.std value

None

if not present ROOTNAME

separators Comma or colon (no white space)

range of values A list of dbspaces. The length of the list cannot exceed 254characters.


utilities onspaces -t (See page 3-67.)ON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)


■ What is a temporary table in the chapter on where datais stored in the Administrator’s Guide

■ Informix Guide to SQL: Reference

IDS


DBSPACETEMP

The list of dbspaces can contain standard dbspaces, temporary dbspaces, orboth. Use a colon or comma to separate the dbspaces in your list. If bothstandard and temporary dbspaces are listed in the DBSPACETEMP configu-ration parameter or environment variable, the following rules apply:

■ Sort, backup, implicit, and nonlogging explicit temporary tables arecreated in temporary dbspaces if adequate space exists.

■ Explicit temporary tables created without the WITH NO LOG optionare created in standard (rather than temporary) dbspaces.

Important: The dbspaces that you list in the DBSPACETEMP configurationparameter must be composed of chunks that are allocated as unbuffered (sometimesreferred to as “raw”) UNIX devices.

When Changes to DBSPACETEMP Take Effect

When you create a temporary dbspace with ON-Monitor (for Dynamic Serveron UNIX) or onspaces, the database server does not use the newly createdtemporary dbspace until you perform the following steps:

1. Add the name of a new temporary dbspace to your list of temporarydbspaces in the DBSPACETEMP configuration parameter, theDBSPACETEMP environment variable, or both.

2. Reinitialize shared memory. In other words, restart the databaseserver with the oninit command (UNIX) or restart the databaseserver service (Windows NT).

Using Hash Join Overflow and DBSPACETEMP

Dynamic Server uses an operating-system directory or files to direct anyoverflow that results from the following database operations if you do not setthe DBSPACETEMP environment variable or DBSPACETEMP configurationparameter. You can specify the operating-system directory or files in thefollowing ways:

■ SELECT statement with GROUP BY clause

■ SELECT statement with ORDER BY clause

■ Hash-join operation

■ Nested-loop join operation

■ Index builds


DBSPACETEMP

If you do not set the DBSPACETEMP environment variable or DBSPACETEMPconfiguration parameter, the database server directs any overflow thatresults from the preceding operations to the operating-system directory orfile that you specify in one of the following variables:

■ On UNIX, the operating-system directory or directories that thePSORT_DBTEMP environment variable specifies, if it is set. IfPSORT_DBTEMP is not set, the database server writes sort files to theoperating-system file space in the tmp directory. ♦

■ On Windows NT, the directory specified in TEMP or TMP in the UserEnvironment Variables window on Control Panel➞System. ♦

DBSPACETEMP for Extended Parallel Serveronconfig.std value

NOTCRITICAL

units None

range of values ALL allows the database server to use all dbspaces at eachnode for temporary storage, giving preference totemporary dbspaces.

NOTCRITICAL allows the database server to use alldbspaces except the rootdbs and other dbspaces that ittreats as critical (for example, the dbspace that containslog files).

TEMP restricts the database server to use only temporarydbspaces for temporary storage.

A list of dbspace names or dbslice names, separated bycolons or commas.

takes effect Used with the keywords ALL, NOTCRITICAL, or TEMP,DBSPACETEMP can appear only in the ONCONFIG file, soit takes effect when the database server is brought on-line.

Alternately, you can specify a list of dbspaces or dbsliceswith the DBSPACETEMP environment variable. Theseitems take effect for the current session only.

UNIX

WIN NT

XPS


DBSPACETEMP

By default, Extended Parallel Server uses all noncritical dbspaces, givingpreference to dbspaces marked temporary. The database server never usesthe root dbspace or the logging dbspace when DBSPACETEMP is set toNOTCRITICAL.

The DBSPACETEMP configuration parameter gives the database adminis-trator the option of restricting which dbspaces or dbslices the database serveruses for temporary storage.

When your queries use temporary space on multiple coservers, you cancreate a temporary dbslice to facilitate management of these temporarydbspaces.

The list of dbslices can contain standard dbslices, temporary dbslices, orboth. Use a colon or comma to separate the dbslices in your list.

The list of dbspaces can contain standard dbspaces, temporary dbspaces, orboth.

If the DBSPACETEMP configuration parameter or environment variablecontains both standard and temporary dbspaces or dbslices, the followingrules apply:

■ Sort, backup, implicit, and nonlogging explicit temporary tables arecreated in temporary dbspaces if adequate space exists.

■ Explicit temporary tables created without the WITH NO LOG optionare created in standard (rather than temporary) dbspaces.

Important: The dbspaces that you list in the DBSPACETEMP configurationparameter must consist of chunks that are allocated as raw UNIX devices.

For the order of precedence that the database server uses when it createsimplicit sort files, see your Performance Guide.

utilities onutil CREATE TEMP DBSLICE(See pages 3-194 and 3-206.)

onutil CREATE TEMP DBSPACE(See pages 3-207 and 3-210.)

refer to What is a temporary dbspace in the chapter on where datais stored in the Administrator’s Guide


DBSPACETEMP

If an individual client application needs to specify an alternative list ofdbspaces to use for its temporary-table locations, the client can use theDBSPACETEMP environment variable to enumerate them. For informationabout the DBSPACETEMP environment variables, see the Informix Guide toSQL: Reference.

Important: If you set the DBSPACETEMP configuration parameter to TEMP, youmust either include some nonlogging dbspaces or specify nonlogging temporarytables when you try to create a temporary table. For example, in SQL statements suchas SELECT...INTO TEMP, you must specify the WITH NO LOG option.

Warning: If you set the DBSPACETEMP configuration parameter to a blank, errorsresult when you try to create a temporary table with SQL statements such asSELECT...INTO TEMP or SELECT...INTO SCRATCH.

When Changes to DBSPACETEMP Take Effect

When you create a temporary dbspace or dbslice with the onutil CREATETEMP command, the database server does not use the newly createdtemporary dbspace or dbslice until you take both of the following steps:

1. Add the name of a new temporary dbspace or dbslice to your list oftemporary dbspaces in the DBSPACETEMP configuration parameter,the DBSPACETEMP environment variable, or both.

2. Reinitialize the database server.

Using Hash-Join Overflow and DBSPACETEMP

If you do not set the DBSPACETEMP environment variable, you specify novalue for DBSPACETEMP configuration parameter, and the optimizer choosesto perform a join or group-by operations with a hash join, the database serverdirects any overflow that results from the join to the root dbspace directory.


DD_HASHMAX

DD_HASHMAX

DD_HASHMAX specifies the maximum number of entries in each hash bucketin the data-dictionary cache.

DD_HASHSIZE

DD_HASHSIZE specifies the number of hash buckets, or lists, in the data-dictionary cache.

onconfig.stdvalue

None

units Maximum number of entries in a hash bucket



utilities Use a text editor to modify the configuration file.

refer to Configuration effects on memory in your PerformanceGuide

onconfig.stdvalue

None

units Number of hash buckets, or lists



utilities Use a text editor to modify the configuration file.

refer to Configuration effects on memory in your PerformanceGuide

IDS

IDS


DEADLOCK_TIMEOUT

DEADLOCK_TIMEOUT

DEADLOCK_TIMEOUT specifies the maximum number of seconds that adatabase server thread can wait to acquire a lock. Use this parameter only fordistributed queries that involve a remote database server. Do not use thisparameter for nondistributed queries.

DIRECTIVES

onconfig.stdvalue

60

units Seconds



utilities ON-Monitor: Parameters, Shared-Memory, DeadlockTimeout (UNIX)

refer to Configuration parameters used in two-phase commits inthe chapter on multiphase commit protocols in theAdministrator’s Guide

onconfig.stdvalue

1

range of values 0 or 1



■ IFX_DIRECTIVES environment variable in the InformixGuide to SQL: Reference

■ SQL directives in the Informix Guide to SQL: Syntax

■ Performance impact of directives in your PerformanceGuide

IDS

IDS


DRAUTO

The DIRECTIVES parameter enables or disables the use of SQL directives. SQLdirectives allow you to specify behavior for the query optimizer in devel-oping query plans for SELECT, UPDATE, and DELETE statements.

Set DIRECTIVES to 1, which is the default value, to enable the database serverto process directives. Set DIRECTIVES to 0 to disable the database server fromprocessing directives. Client programs also can set the IFX_DIRECTIVESenvironment variable to ON or OFF to enable or disable processing of direc-tives by the database server. The setting of the IFX_DIRECTIVES environmentvariable overrides the setting of the DIRECTIVES configuration parameter. Ifyou do not set the IFX_DIRECTIVES environment variable, all sessions for aclient inherit the database server configuration for processing SQL directives.

DRAUTOHigh-availability data replication (HDR) no longer supports the DRAUTOconfiguration parameter. If an HDR failure occurs, the secondary databaseserver remains in read-only mode. You must perform the transition fromsecondary to standard mode manually. The database server automaticallysets DRAUTO to 0.

IDS


DRINTERVAL

DRINTERVAL

DRINTERVAL specifies the maximum interval in seconds between flushing ofthe high-availability data-replication buffer. To update synchronously, set theparameter to -1.

onconfig.stdvalue

30

units Seconds

range of values -1, 0, and positive integer values


utilities ON-Monitor: Parameters, data-Replication, Interval(UNIX)

refer to When log records are sent in the chapter on high-avail-ability data replication in the Administrator’s Guide

IDS


DRLOSTFOUND

DRLOSTFOUND

DRLOSTFOUND specifies the pathname to the dr.lostfound.timestamp file.This file contains transactions committed on the primary database server butnot committed on the secondary database server when the primary databaseserver experiences a failure. The file is created with a time stamp appendedto the filename so that the database server does not overwrite another lost-and-found file if one already exists.

This parameter is not applicable if updating between the primary andsecondary database servers occurs synchronously (that is, if DRINTERVAL isset to -1).

onconfig.stdvalue

On UNIX: /usr/etc/dr.lostfoundOn Windows NT: drive:\informix\etc\dr.lostfound



utilities ON-Monitor: Parameters, data-Replication, Lost & Found(UNIX)

refer to Lost-and-found transactions in the chapter onhigh-availability data replication in the Administrator’sGuide

IDS


DRTIMEOUT

DRTIMEOUT

DRTIMEOUT applies only to high-availability data-replication pairs. Thisvalue specifies the length of time, in seconds, that a database server in a high-availability data-replication pair waits for a transfer acknowledgment fromthe other database server in the pair. Use the following formula to calculateDRTIMEOUT:

DRTIMEOUT = wait_time / 4

In this formula, wait_time is the length of time, in seconds, that a databaseserver in a high-availability data-replication pair must wait before it assumesthat a high-availability data-replication failure occurred.

For example, suppose you determine that wait_time for your system is 160seconds. Use the preceding formula to set DRTIMEOUT as follows:

DRTIMEOUT = 160 seconds / 4 = 40 seconds

onconfig.stdvalue

30

units Seconds



utilities ON-Monitor: Parameters, data-Replication, Timeout(UNIX)

refer to How high-availability data-replication failures aredetected in the chapter on high-availability data repli-cation in the Administrator’s Guide

IDS


DS_ADM_POLICY

DS_ADM_POLICY

The DS_ADM_POLICY parameter specifies how the Resource Grant Manager(RGM) should schedule queries.

If DS_ADM_POLICY is set to STRICT, the RGM processes queries in the orderdetermined by the SET SCHEDULE LEVEL setting specified in the query andthe order in which queries are submitted. The RGM processes the oldestquery with the highest scheduling level before other queries, which meansthat a more recent query with a lower scheduling level might never run.

If DS_ADM_POLICY is set to FAIR, the RGM takes scheduling level, PDQpriority, and wait time into account when it decides which query to process.In general, the query with the highest scheduling level runs first, but a querywith a lower scheduling level can run if it has been waiting for a long time.

DS_MAX_QUERIES

onconfig.stdvalue

FAIR

if not present FAIR

range of values STRICT or FAIR

refer to Your Performance Guide

onconfig.stdvalue

On UNIX: NoneOn Windows NT: 32

if not present For Dynamic Server:NUMCPUVPS * 2 * 128

For Extended Parallel Server:DS_TOTAL_MEMORY / NUMCPUVPS * 4 * 128

units Number of queries

XPS


DS_MAX_QUERIES

DS_MAX_QUERIES is the maximum number of PDQ queries that can runconcurrently. The Memory Grant Manager (MGM) reserves memory for aquery based on the following formula:

memory_reserved = (DS_TOTAL_MEMORY / DS_MAX_QUERIES) *DS_MAX_QUERIES * (PDQ-priority / 100) *(MAX_PDQPRIORITY / 100)

The value of PDQPRIORITY is specified in either the PDQPRIORITYenvironment variable or the SQL statement SET PDQPRIORITY. ♦

In Extended Parallel Server, DS_MAX_QUERIES is the maximum number ofmemory-consuming queries that can run concurrently. A memory-consuming query is defined as a query with PDQ priority set to a high value.The Resource Grant Manager (RGM) enforces this limit.

The value of PDQPRIORITY is specified in the PDQPRIORITY configurationparameter, the PDQPRIORITY environment variable, or the SQL statementSET PDQPRIORITY. ♦

range of values Minimum = 1

Maximum for Dynamic Server and for Extended ParallelServer on 32-bit platforms: 8 megabytes

Maximum for Extended Parallel Server on 64-bitplatforms: 16 megabytes

utilities onmode -Q (See page 3-52.)ON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)


IDS

XPS


DS_MAX_SCANS

DS_MAX_SCANS

DS_MAX_SCANS limits the number of PDQ scan threads that the databaseserver can execute concurrently. When a user issues a query, the databaseserver apportions some number of scan threads, depending on the followingvalues:

■ The value of PDQ priority (set by the environment variablePDQPRIORITY or the SQL statement SET PDQPRIORITY)

■ The ceiling that you set with DS_MAX_SCANS

■ The factor that you set with MAX_PDQPRIORITY

■ The number of fragments in the table to scan (nfrags in the formula)

The Memory Grant Manager (MGM) tries to reserve scan threads for a queryaccording to the following formula:

reserved_threads = min (nfrags, (DS_MAX_SCANS *PDQPRIORITY / 100 *MAX_PDQPRIORITY / 100) )

If the DS_MAX_SCANS part of the formula is greater than or equal to thenumber of fragments in the table to scan, the query is held in the ready queueuntil as many scan threads are available as there are table fragments. Onceunderway, the query executes quickly because threads are scanningfragments in parallel.

For example, if nfrags equals 24, DS_MAX_SCANS equals 90, PDQPRIORITYequals 50, and MAX_PDQPRIORITY equals 60, the query does not beginexecution until nfrags scan threads are available. Scanning takes place inparallel.

onconfig.stdvalue

1,048,576 (1024 * 1024)

units Number of PDQ scan threads

range of values 10 through (1024 * 1024)

utilities onmode -S (See page 3-52.)ON-Monitor: Parameters menu, pdQ screen (UNIX)


IDS


DS_TOTAL_MEMORY

If you cause the DS_MAX_SCANS formula to fall below the number offragments, the query might begin execution sooner, but the query takeslonger to execute because some threads scan fragments serially.

If you reduce DS_MAX_SCANS to 40 in the previous example, the query needsfewer resources (12 scan threads) to begin execution, but each thread needsto scan two fragments serially. Execution takes longer.

DS_TOTAL_MEMORYonconfig.std

valueOn UNIX: NoneOn Windows NT: 4,096

if not present For Dynamic Server:

If SHMTOTAL=0 and DS_MAX_QUERIES is set,DS_MAX_QUERIES * 128.

If SHMTOTAL=0 and DS_MAX_QUERIES is not set,NUMCPUVPS * 2 * 128.

For Extended Parallel Server:If SHMTOTAL=0, NUMCPUVPS * 4 * 128.

If SHMTOTAL is greater than 0, the value is SHMTOTALminus all memory other than decision-support memory,which includes the resident memory segment, memoryreserved for buffer cache, and memory reserved for userconnections in various protocols, which is specified by thethird argument of the NETTYPE parameter. (The defaultvalue for this argument to NETTYPE is 50 connections.)

units Kilobytes


DS_TOTAL_MEMORY

DS_TOTAL_MEMORY specifies the amount of memory available for PDQqueries. It should be smaller than the computer physical memory, minusfixed overhead such as operating-system size and buffer-pool size.

Do not confuse DS_TOTAL_MEMORY with the configuration parameterSHMTOTAL. For OLTP applications, set DS_TOTAL_MEMORY to between 20and 50 percent of the value of SHMTOTAL in kilobytes. For applications thatinvolve large decision-support queries, increase the value ofDS_TOTAL_MEMORY to between 50 and 80 percent of SHMTOTAL. If you useyour database server for decision-support queries exclusively, set thisparameter to 90 percent of SHMTOTAL.

For DSS-only applications that do not need to balance resources against OLTPapplications, you can allocate all of the virtual portion to your decision-support queries. Set the DS_TOTAL_MEMORY configuration parameter to anyvalue not greater than the quantity (SHMVIRTSIZE - 10 megabytes).

range of values The maximum value is 2 gigabytes on 32-bit platforms and4 gigabytes on 64-bit platforms.

For Dynamic Server:

If DS_MAX_QUERY is set, the minimum value isDS_MAX_QUERY * 128.

If DS_MAX_QUERY is not set, the minimum value isNUMCPUVPS * 2 * 128.

For Extended Parallel Server:The minimum value is NUMCPUVPS * 4 * 128.

utilities onmode -M (See page 3-52.)ON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)


■ Your Performance Guide for the algorithms

■ “Derive a Minimum for Decision-Support Memory” onpage 1-55


DS_TOTAL_MEMORY

Algorithm for DS_TOTAL_MEMORYThe database server derives a value for DS_TOTAL_MEMORY when you donot set DS_TOTAL_MEMORY or if you set it to an inappropriate value.Whenever the database server changes the value that you assigned toDS_TOTAL_MEMORY, it sends the following message to your console:

DS_TOTAL_MEMORY recalculated and changed from old_value Kb to new_value Kb

The algorithm that the database server uses to derive the new value forDS_TOTAL_MEMORY is documented in the following sections. When youreceive the preceding message, you can use the algorithm to investigate whatvalues the database server considers inappropriate and take corrective actionbased on your investigation.

Derive a Minimum for Decision-Support Memory

In the first part of the algorithm, the database server establishes a minimumfor decision-support memory. When you assign a value to the configurationparameter DS_MAX_QUERIES, the database server sets the minimum amountof decision-support memory according to the following formula:

min_ds_total_memory = DS_MAX_QUERY * 128 kilobytes

When you do not assign a value to DS_MAX_QUERIES, the database serverinstead uses the following formula based on the value of VPCLASS cpu orNUMCPUVPS:

min_ds_total_memory = (number_of_CPU_VPS) * 2 * 128 kilobytes

Derive a Working Value for Decision-Support Memory

In the second part of the algorithm, the database server establishes a workingvalue for the amount of decision-support memory. The database serververifies this amount in the third and final part of the algorithm.


DS_TOTAL_MEMORY

When DS_TOTAL_MEMORY Is Set

The database server first checks if SHMTOTAL is set. When SHMTOTAL is set,the database server uses the following formula to calculateDS_TOTAL_MEMORY:

IF DS_TOTAL_MEMORY <= SHMTOTAL - nondecision_support_memory THENdecision_support_memory = DS_TOTAL_MEMORY

ELSEdecision_support_memory = SHMTOTAL - nondecision_support_memory

This algorithm effectively prevents you from setting DS_TOTAL_MEMORY tovalues that the database server cannot possibly allocate to decision-supportmemory.

When SHMTOTAL is not set, the database server sets decision-supportmemory equal to the value that you specified in DS_TOTAL_MEMORY.

When DS_TOTAL_MEMORY Is Not Set

When you do not set DS_TOTAL_MEMORY, the database server proceeds asfollows. First, the database server checks if you set SHMTOTAL. WhenSHMTOTAL is set, the database server uses the following formula to calculatethe amount of decision-support memory:

decision_support_memory = SHMTOTAL - nondecision_support_memory

When the database server finds that you did not set SHMTOTAL, it setsdecision-support memory as in the following example:

decision_support_memory = min_ds_total_memory

Check Derived Value for Decision-Support Memory

The final part of the algorithm verifies that the amount of shared memory isgreater than min_ds_total_memory and less than the maximum possiblememory space for your computer. When the database server finds that thederived value for decision-support memory is less than min_ds_total_memory,it sets decision-support memory equal to min_ds_total_memory.

When the database server finds that the derived value for decision-supportmemory is greater than the maximum possible memory space for yourcomputer, it sets decision-support memory equal to the maximum possiblememory space.


DUMPCNT

Inform User When Derived Value Is Different from User Value

When the database server changes the value that you set forDS_TOTAL_MEMORY at any point during the processing of this algorithm, itsends a message to your console in the following format:

DS_TOTAL_MEMORY recalculated and changed from old_value Kb to new_value Kb

In the message, old_value represents the value that you assigned toDS_TOTAL_MEMORY in your configuration file, and new_value represents thevalue that the database server derived.

DUMPCNT

DUMPCNT specifies the number of assertion failures for which one databaseserver thread dumps shared memory or generates a core file by calling gcore.An assertion is a test of some condition or expression with the expectationthat the outcome is true. For example, the following statement illustrates theconcept of an assertion failure:

if (a != b)assert_fail("a != b");

onconfig.stdvalue

1

if not present 1

units Number of assertion failures



utilities ON-Monitor: Parameters, diaGnostics, Dump Count (IDS)

refer to Collecting diagnostic information in the chapter onconsistency checking in the Administrator’s Guide

UNIX


DUMPCORE

DUMPCORE

DUMPCORE controls whether assertion failures cause a virtual processor todump a core image. The core file is left in the directory from which thedatabase server was last invoked. (The DUMPDIR parameter has no impacton the location of the core file.)

Warning: When DUMPCORE is set to 1, an assertion failure causes a virtualprocessor to dump a core image, which in turn causes the database server to abort.Set DUMPCORE only for debugging purposes in a controlled environment.

onconfig.stdvalue

0

range of values 0 = Do not dump core image.1 = Dump core image.


utilities ON-Monitor: Parameters, diaGnostics, Dump Core (IDS)


UNIX


DUMPDIR

DUMPDIR

DUMPDIR specifies a directory in which the database server dumps sharedmemory, gcore files, or messages from a failed assertion. Because sharedmemory can be large, set DUMPDIR to a file system with a significant amountof space.

onconfig.stdvalue

tmp

if not present tmp

range of values Any directory to which user informix has write access


utilities ON-Monitor: Parameters, diaGnostics, Dump Directory(IDS)


UNIX


DUMPGCORE

DUMPGCORE

DUMPGCORE is used with operating systems that support gcore. If you setDUMPGCORE, but your operating system does not support gcore, messagesin the database server message log indicate that an attempt was made todump a core image, but the database server cannot find the expected file. (Ifyour operating system does not support gcore, set DUMPCORE instead.)

If DUMPGCORE is set, the database server calls gcore whenever a virtualprocessor encounters an assertion failure. The gcore utility directs the virtualprocessor to dump a core image to the directory that DUMPDIR specifies andcontinue processing.

The core dump output that gcore generates is saved to the file core.pid.cnt.The pid value is the process identification number of the virtual processor.The cnt value is incremented each time that this process encounters anassertion failure. The cnt value can range from 1 to the value of DUMPCNT.After that, no more core files are created. If the virtual processor continues toencounter assertion failures, errors are reported to the message log (andperhaps to the application), but no further diagnostic information is saved.

onconfig.stdvalue

0

range of values 0 = Do not dump gcore.1 = Dump gcore.


utilities ON-Monitor: Parameters, diaGnostics, Dump Gcore (IDS)


UNIX


DUMPSHMEM

DUMPSHMEM

DUMPSHMEM indicates that shared memory should be dumped on anassertion failure. All the shared memory that the database server uses isdumped; it is probably quite large. The shared-memory dump is placed in afile in the directory that DUMPDIR specifies.

The filename takes the format shmem.pid.cnt. The pid value is the processidentification number for the virtual processor. The cnt value is incrementedeach time that this virtual processor encounters an assertion failure. The cntvalue can range from 1 to the value of DUMPCNT. After the value ofDUMPCNT is reached, no more files are created. If the database servercontinues to detect inconsistencies, errors are reported to the message log(and perhaps to the application), but no further diagnostic information issaved.

onconfig.stdvalue

1

range of values 0 = Do not dump shared memory.1 = Dump shared memory.


utilities ON-Monitor: Parameters, diaGnostics, Dump SharedMemory (IDS, UNIX)


UNIX


END

END

END marks the end of a coserver-specific section or storage-manager sectionin the ONCONFIG file.

FILLFACTOR

FILLFACTOR specifies the degree of index-page fullness. A low valueprovides room for growth in the index. A high value compacts the index. Ifan index is full (100 percent), any new inserts result in splitting nodes. Youcan also set the FILLFACTOR as an option on the CREATE INDEX statement.The setting on the CREATE INDEX statement overrides the ONCONFIG filevalue.

onconfig.stdvalue

None

range of values None


refer to Setting coserver-specific parameters in the chapter onconfiguration parameters in the Administrator’s Guide.

range of values None

onconfig.stdvalue

90

units Percent

range of values 1 through 100

takes effect When the index is built. Existing indexes are not changed.To use the new value, the indexes must be rebuilt.

utilities ON-Monitor: Parameters, Shared-Memory, Index PageFill Factor (IDS, UNIX)

refer to “Structure of B-Tree Index Pages” on page 7-27

XPS


HETERO_COMMIT

HETERO_COMMIT

The HETERO_COMMIT configuration parameter specifies whether or not thedatabase server is prepared to participate with Informix Gateway productsin heterogeneous commit transactions. Setting HETERO_COMMIT to 1 allowsa single transaction to update one non-Informix database (accessed with anyof the Gateway products) and one or more Informix databases.

If HETERO_COMMIT is 0, a single transaction can update databases asfollows:

■ One or more Informix databases and no non-Informix databases

■ One non-Informix database and no Informix databases

You can read data from any number of Informix and non-Informix databases,regardless of the setting of HETERO_COMMIT.

IDS

onconfig.stdvalue

0

range of values 1 = Enable heterogeneous commit.0 = Disable heterogeneous commit.


utilities ON-Monitor: Parameters, Shared-Memory, Heteroge-neous Commit (UNIX)


■ Heterogeneous commit protocol in the chapter onmultiphase commit protocols in the Administrator’sGuide

■ INFORMIX-Enterprise Gateway Manager User Manual


IDX_RA_PAGES

IDX_RA_PAGES

The IDX_RA_PAGES parameter specifies the number of disk pages to attemptto read ahead during sequential scans of index records. Read-ahead cangreatly speed database processing by compensating for the slowness of I/Oprocessing relative to the speed of CPU processing.

This parameter works with the IDX_RA_THRESHOLD parameter. Use a largerIDX_RA_PAGES value if the range of index values scanned is big. Specifyingvalues that are too large can result in excessive buffer-caching activity. Formore information on calculating IDX_RA_PAGES and IDX_RA_THRESHOLD,see your Performance Guide.

onconfig.stdvalue

None

if not present 4 if MULTIPROCESSOR is 08 if MULTIPROCESSOR is 1

units Number of index pages

range of values IDX_RA_THRESHOLD through BUFFERS



■ Configuring the database server to read-ahead in theshared-memory chapter of the Administrator’s Guide

■ Calculating IDX_RA_PAGES and IDX_RA_THRESHOLDin your Performance Guide

XPS


IDX_RA_THRESHOLD

IDX_RA_THRESHOLD

The IDX_RA_THRESHOLD parameter is used with IDX_RA_PAGES when thedatabase server reads during sequential scans of index records.IDX_RA_THRESHOLD specifies the read-ahead threshold; that is, the numberof unprocessed index pages in memory that signals the database server toperform the next read-ahead.

If the value of IDX_RA_THRESHOLD is greater than the value ofIDX_RA_PAGES, then IDX_RA_THRESHOLD has a value of IDX_RA_PAGES/2.

Use a larger IDX_RA_PAGES value if the range of index values scanned is big.Specifying values that are too large for IDX_RA_PAGES andIDX_RA_THRESHOLD can result in excessive buffer-caching activity.

onconfig.stdvalue

None

if not present IDX_RA_PAGES/2

units Number of index pages

range of values 0 through (IDX_RA_PAGES - 1)



■ Configuring the database server to read ahead in theshared-memory chapter of the Administrator’s Guide

■ Calculating IDX_RA_PAGES and IDX_RA_THRESHOLDin your Performance Guide

XPS


ISM_DATA_POOL and ISM_LOG_POOL

ISM_DATA_POOL and ISM_LOG_POOLThe ISM_DATA_POOL and ISM_LOG_POOL parameters control whereInformix Storage Manager stores backed-up data and logical logs. For infor-mation on these parameters, see the Backup and Restore Guide or the InformixStorage Manager Administrator’s Guide.

On Extended Parallel Server, you can specify these parameters for a specificcoserver or for the database server. ♦

ISOLATION_LOCKS

ISOLATION_LOCKS specifies the maximum number of rows (counting theuser’s current row) that should be locked at any given time on any given scanwhile Cursor Stability isolation is in effect. The user does not have controlover which rows are locked or when those locks are released. The user isguaranteed only that the specified maximum number of rows is locked at anygiven moment for any given cursor.

ISOLATION_LOCKS offers an intermediate solution between RepeatableRead, which locks the entire table, and Committed Read, which does notobtain read locks. Increasing ISOLATION_LOCKS allows more efficient rowbuffering, but holding many locks can reduce concurrency for a given table.

Important: If you set ISOLATION_LOCKS to a value greater than 1, ensure that thevalue you specify for the LOCKS configuration parameter accounts for this increasein the number of locks.

onconfig.stdvalue

None

if not present 1

units Rows

range of values Positive integers less than or equal to the value of theLOCKS parameter


XPS

XPS


JVPxxx and JVMTHREAD

JVPxxx and JVMTHREADThe following configuration parameters apply to the database server imple-mentation of the Informix JDBC driver. In addition to the JDKVERSION,JVMTHREAD, and JVPxxx configuration parameters, the VPCLASS configu-ration parameter has a JVP option.

For more information on these parameters, see Creating UDRs in Java.

ConfigurationParameter Description

JDKVERSION Version number of the DataBlade Developers Kit(DBDK) with Java support

JVPHOME Directory where the JDBC driver is installed

JVPLOGFILE Log file for the JDBC driver

JVPPROPFILE Pathname for the properties file

JVPJAVAVM List of Java VM libraries to be loaded

JVPJAVAHOME Directory where the DBDK is installed

JVMTHREAD Thread package to use for the Java VM

JVPJAVALIB Pathname for the Java VM libraries

JVPCLASSPATH Initial Java class path setting

VPCLASS JVP Number of Java virtual processors (Refer to“VPCLASS” on page 1-148.)

IDS

Java


LBU_PRESERVE

LBU_PRESERVE

LBU_PRESERVE reserves the last logical log for administrative tasks by settingthe logs-full high-water mark. When LBU_PRESERVE is enabled, the databaseserver blocks further OLTP activity when the next-to-last log fills, rather thanthe last log. Setting LBU_PRESERVE prevents backups from failing due to lackof logical-log space.

If LOG_BACKUP_MODE is set to MANUAL or CONT, LBU_PRESERVE isenabled for all coservers. You cannot change the LBU_PRESERVE value in theONCONFIG file. If LOG_BACKUP_MODE is set to NONE, LBU_PRESERVE isdisabled for all coservers. ♦

onconfig.stdvalue

For Dynamic Server: 0For Extended Parallel Server: 1

range of values For Dynamic Server:1 = Enable the logs-full high-water mark.0 = Disable the logs-full high-water mark.


utilities ON-Monitor: Parameters, Shared-Memory, Preserve Logfor Log Backup (IDS, UNIX)

refer to Enabling the logs-full high-water mark in the chapter onwhat is the logical log in the Administrator’s Guide

XPS


LOCKS

LOCKS

LOCKS specifies the initial size of the lock table. The lock table holds an entryfor each lock that a session uses. If the number of locks that sessions allocateexceeds the value of LOCKS, the database server increases the size of the locktable.

Although each additional lock takes up just 44 bytes of resident sharedmemory, locks can become a resource drain if you have a limited amount ofshared memory. For example, if you set LOCKS to 1,000,000, the databaseserver allocates 40 megabytes of resident shared memory for locks.

Tip: When you drop a database, a lock is acquired and held on each table in thedatabase until the database is dropped. For more information on the DROPDATABASE statement, see the “Informix Guide to SQL: Syntax.”

onconfig.stdvalue

2,000

range of values For Dynamic Server: 2,000 through 8,000,000

For Extended Parallel Server: 2,000 through 8,000,000 on32-bit platforms and 2,000 through 16,000,000 on 64-bitplatforms


utilities ON-Monitor: Parameters, Shared-Memory, Max # ofLocks (IDS, UNIX)

refer to The memory and locking chapters in your PerformanceGuide


LOG_BACKUP_MODE

LOG_BACKUP_MODE

In Extended Parallel Server, edit your ONCONFIG file to setLOG_BACKUP_MODE. Use of NONE is not recommended because you cannotuse ON-Bar to restore if logical-log backups have been disabled.

LOGBUFF

LOGBUFF specifies the size in kilobytes of each of the three logical-log buffersin shared memory. Triple buffering permits user threads to write to the activebuffer while one of the other buffers is being flushed to disk. If flushing is notcomplete by the time the active buffer fills, the user thread begins writing tothe third buffer.

onconfig.stdvalue

MANUAL

range of values CONT = Continuous log backupsMANUAL = Manual log backupsNONE = No log backups

refer to Backup and Restore Guide

onconfig.stdvalue

32

units Kilobytes

range of values (2 * page size) through LOGSIZE


utilities ON-Monitor: Parameters, Shared-Memory, Logical LogBuffer Size (IDS, UNIX)

refer to Logical-log buffer in the shared-memory chapter of theAdministrator’s Guide

XPS


LOGFILES

Informix recommends that you set LOGBUFF to 16 or 32 kilobytes, or perhaps64 kilobytes for heavy workloads.

If you log smart-large-object columns, you must ensure that the log buffer isbig enough to accommodate your largest smart-large-object page size plusone database server page. The database server logs only the portion of asmart-large-object page that changed. ♦

Important: The database server uses the LOGBUFF parameter to set the size ofinternal buffers that are used during recovery. If you set LOGBUFF too high, thedatabase server can run out of memory and shut down during recovery.

System Page SizeTo verify the page size that the database server uses on your platform, youcan use one of the utilities listed in “BUFFERS and Read-Ahead” onpage 1-27.

LOGFILESonconfig.std

value6

if not present For Dynamic Server: 6For Extended Parallel Server: 3

units Number of logical-log files

range of values 3 through LOGSMAX (integers only)

takes effect During disk initialization and when you add a new logfile. You add a new log with one of the following utilities.

IDS


LOGFILES

LOGFILES specifies the number of logical-log files that the database servercreates during disk initialization. To change the number of logical-log files,add or drop logical-log files.

If you use ON-Monitor (UNIX) or onparams to add or drop log files, thedatabase server automatically updates LOGFILES. ♦

Extended Parallel Server treats LOGFILES as an initialization parameter anddoes not update it when you change the number of logical-log files with theonutil CREATE LOGICAL LOG command. ♦

utilities onparams (IDS)See page 3-57.

ON-Monitor: Parameters, Initialize, Number of LogicalLogs (IDS, UNIX)

onutil CREATE LOGICAL LOG command (XPS)See page 3-212.

onutil CREATE LOGICAL LOGSLICE command (XPS)See page 3-215.

refer to The following topics in the Administrator’s Guide:

■ The size and number of logical-log files in the chapteron what is the logical log

■ The chapter on managing the logical log:

❑ Adding or dropping a logical-log file

❑ Adding or dropping a logslice (XPS)

IDS

XPS


LOGSIZE

LOGSIZEonconfig.std

valueFor Dynamic Server: 1500For Extended Parallel Server: 1024

if not present For Dynamic Server:UNIX: 1500Windows NT: 200

For Extended Parallel Server:UNIX: 200Windows NT: 500

units Kilobytes

range of values Minimum = 200Maximum =(ROOTSIZE - PHYSFILE - 512 -(63 * ((pagesize)/1024))) / LOGFILES

For Dynamic Server:The pagesize value is platform dependent.

For Extended Parallel Server:Specify the pagesize value in the PAGESIZEconfiguration parameter.

takes effect When shared memory is initialized. The size of log filesadded after shared memory is initialized reflects the newvalue, but the size of existing log files does not change.

utilities ON-Monitor: Parameters, Initialize, Log, Log Size (IDS,UNIX)

onparams (IDS)See “Change Physical-Log Parameters” on page 3-60.

onutil (XPS)See “onutil: Check, Define, and Modify Storage Objects”on page 3-135.


LOGSIZE

LOGSIZE specifies the size that is used when logical-log files are created. Itdoes not change the size of existing logical-log files. The total logical-log sizeis LOGSIZE * LOGFILES.

To verify the page size that the database server uses on your platform, useone of the utilities listed in “System Page Size” on page 1-27.

LOGSIZE for Extended Parallel ServerLOGSIZE is a global configuration parameter that specifies the size of thelogical-log files and logslices when you initialize the database server.Extended Parallel Server also uses the value of LOGSIZE as the default sizewhen you add another logslice or individual logical-log file.

Tip: A coserver can have individual log files at the same time as log files that are partof logslices. However, you cannot change or delete individual log files that are part ofa logslice. Extended Parallel Server manipulates all files in a given logslice as a unit.

Extended Parallel Server treats LOGSIZE as an initialization parameter anddoes not update it when you change the size of a logslice or logical-log file.

LOGSIZE for Smart Large ObjectsIf you declare logging for a smart-large-object column, you must ensure thatthe logical log is considerably larger than the amount of data logged duringinserts or updates.

Important: The logical-log size must exceed the total amount of data logged while atransaction is active, even if the user-data portion of the smart large object is notlogged. Otherwise, you increase the possibility of incurring a long-transaction con-dition because multimedia updates can collect data over a long period of time.


■ Size of the logical log in the chapter on what is thelogical log

■ Size and number of logical-log files in the chapter onwhat is the logical log

■ Changes to LOGSIZE or LOGFILES in the chapter onmanaging logical logs

XPS

IDS


LOGSMAX

For more information, refer to logging smart large objects in the chapter onwhat is logging in the Administrator’s Guide.

LOGSMAX

LOGSMAX specifies the maximum number of logical-log files that an instanceof the database server supports. The database server requires at least threelogical-log files for operation.

On Extended Parallel Server, LOGSMAX specifies the maximum number oflogical-log files and logslices. ♦

In general, you can set the value of LOGSMAX equal to the value of LOGFILES.If you plan to relocate the logical-log files out of the root dbspace after youinitialize the database server, assign LOGSMAX the value of LOGFILES + 3.

onconfig.stdvalue

6

if not present 3

units Number of logical-log files

range of values LOGFILES through 32,767 (integers only)


utilities ON-Monitor: Parameters, Shared-Memory, Max # ofLogical Logs (IDS, UNIX)


■ Determining the size and number of logical-log files inthe chapter on what is the logical log

■ Moving a logical-log file to another dbspace in thechapter on managing logical logs

■ Changing logical-log configuration parameters in thechapter on managing logical logs

XPS


LRUS

LRUS

LRUS specifies the number of LRU (least-recently-used) queues in theshared-memory buffer pool. You can tune the value of LRUS, in combinationwith the LRU_MIN_DIRTY and LRU_MAX_DIRTY parameters, to control howfrequently the shared-memory buffers are flushed to disk.

Setting LRUS too high might result in excessive page-cleaner activity.

onconfig.stdvalue

8

if not present If MULTIPROCESSOR is set: MAX(4, NUMCPUVPS)If MULTIPROCESSOR is not set: 4

units Number of LRU queues

range of values For Dynamic Server and for Extended Parallel Server on32-bit platforms: 1 through 128

For Extended Parallel Server on 64-bit platforms:1 through 512


utilities ON-Monitor: Parameters, perFormance, Num of LRUqueues (IDS, UNIX)


■ LRU queues in the shared-memory chapter of theAdministrator’s Guide

■ Chapter on configuration effects on memory in yourPerformance Guide


LRU_MAX_DIRTY

LRU_MAX_DIRTY

LRU_MAX_DIRTY specifies the percentage of modified pages in the LRUqueues at which the queue is cleaned.

LRU_MIN_DIRTY

onconfig.stdvalue

60

units Percent


For Extended Parallel Server:Noninteger values are allowed (for example, .1).


utilities ON-Monitor: Parameters, perFormance, LRU Max Dirty(IDS, UNIX)

refer to The following topics in the shared-memory chapter of theAdministrator’s Guide:

■ LRU queues

■ Limiting the number of pages added to the MLRUqueues

onconfig.stdvalue

50

units Percent


For Extended Parallel Server:Noninteger values are allowed (for example, .1).


LTAPEBLK

LRU_MIN_DIRTY specifies the percentage of modified pages in the LRUqueues at which page cleaning is no longer mandatory. Page cleaners mightcontinue cleaning beyond this point under some circumstances.

LTAPEBLK


utilities ON-Monitor: Parameters, perFormance, LRU Min Dirty(IDS, UNIX)

refer to The following topics in the shared-memory chapter of theAdministrator’s Guide:

■ LRU queues

■ When MLRU cleaning ends

onconfig.stdvalue

16

units Kilobytes

range of values Values greater than (page size/1024)

takes effect For ontape: When you execute ontape

For onload and onunload: When shared memory isinitialized

utilities ON-Monitor: Parameters, Initialize, Block Size (followsLog Tape Dev) (UNIX)


■ How this parameter affects ontape in the Archive andBackup Guide

■ How this parameter affects onload and onunload in theInformix Migration Guide

IDS


LTAPEBLK

LTAPEBLK specifies the block size of the device to which the logical logs arebacked up when you use ontape for dbspace backups. LTAPEBLK alsospecifies the block size for the device to which data is loaded or unloadedwhen you use the -l option of onload or onunload. If you are using onloador onunload, you can specify a different block size at the command line.

Specify LTAPEBLK as the largest block size permitted by your tape device.The database server does not check the tape device when you specify theblock size. Verify that the LTAPEDEV tape device can read the block size thatyou specify. If not, you might not be able to read from the tape.

The UNIX dd utility can verify that the LTAPEDEV tape device can read theblock size. It is available with most UNIX systems. ♦


You can use the following utilities to display the system page size.

Utility Description

onstat -b Displays the system page size, given as buffer size on the last lineof the output.

oncheck -pr Checks the root-dbspace reserved pages and displays the systempage size in the first section of its output.

ON-Monitor(UNIX)

Provides these options to obtain the system page size:

■ Parameters:Shared-Memory, which does not require thedatabase server to be running

■ Parameters:Initialize

UNIX

IDS


LTAPEDEV

LTAPEDEV

LTAPEDEV specifies the device to which the logical logs are backed up whenyou use ontape for backups. LTAPEDEV also specifies the device to whichdata is loaded or unloaded when you use the -l option of onload oronunload.

If you are using LTAPEDEV to specify a device for onunload or onload, thesame information for TAPEDEV is relevant for LTAPEDEV.

Warning: Do not set LTAPEDEV to /dev/null or nul when you use ON-Bar to backup logical logs.

onconfig.stdvalue

On UNIX: /dev/tapedevOn Windows NT: \\.\TAPE1

if not present On UNIX: /dev/nullOn Windows NT: nul

takes effect For ontape: When shared memory is initialized if set to/dev/null on UNIX or nul on Windows NT. Takes effectwhen you execute ontape if set to a tape device.


utilities ON-Monitor: Parameters, Initialize, Log Tape Dev (UNIX)


■ How to set and change the LTAPEDEV value for ontapein the Archive and Backup Guide

■ How this parameter affects onload or onunload in theInformix Migration Guide

■ “TAPEDEV” on page 1-144

IDS


LTAPESIZE

LTAPESIZE

LTAPESIZE specifies the maximum tape size of the device to which the logicallogs are backed up when you use ontape for backups. LTAPESIZE alsospecifies the maximum tape size of the device to which data is loaded orunloaded when you use the -l option of onload or onunload. If you are usingonload or onunload, you can specify a different tape size on the commandline.

onconfig.stdvalue

10,240

units Kilobytes


takes effect For ontape: When you execute ontape


utilities ON-Monitor: Parameters, Initialize, Total Tape Size(follows Log Tape Dev) (UNIX)



■ How this parameter affects onload or onunload in theInformix Migration Guide

IDS


LTXEHWM

LTXEHWM

LTXEHWM specifies the long-transaction, exclusive-access, high-water mark. Ifthe logical log fills to LTXEHWM, the long transaction currently being rolledback is given exclusive access to the logical log. For example, if you setLTXEHWM to 60 percent of the logical-log space, and the log fills to thatpercentage, at that point the thread that is rolling back the long transaction isgiven exclusive access to the logical log. The term exclusive is not entirelyaccurate. Most database server activity is suspended until the transaction hascompleted its rollback, but transactions that are in the process of rolling backor committing a transaction retain access to the logical log.

When the database server is initialized, if the value in the current configu-ration file is greater than 60, a warning is issued. Informix recommends thatyou change the value in your configuration file and increase the size of yourlogical-log files proportionately.

For more information about setting high-water marks, see the logical-logchapter in the Administrator’s Guide.

onconfig.stdvalue

60

units Percent

range of values LTXHWM through 100


utilities ON-Monitor: Parameters, Shared-Memory, Long TX HWMExclusive (IDS, UNIX)


■ “LTXHWM” on page 1-83

■ Avoiding long transactions in the chapter on what is thelogical log in the Administrator’s Guide


LTXHWM

LTXHWM

LTXHWM specifies the long-transaction high-water mark. The value of LTXHWMis the percentage of available logical-log space that, when filled, triggers thedatabase server to check for a long transaction. If a long transaction is found,the transaction is aborted, and the database server rolls back all modificationsassociated with it. Other transactions continue to execute, and the rollbackprocedure itself generates logical-log records, so the logical log continues tofill. (The LTXEHWM parameter exists for this reason.)

When the database server is initialized, if the value in the current configu-ration file is greater than 50, a warning is issued. Informix recommends thatyou change the value in your configuration file and increase the size of yourlogical-log files proportionately.

onconfig.stdvalue

50

units Percent



utilities ON-Monitor: Parameters, Shared-Memory, LongTX HWM (IDS, UNIX)

refer to Avoiding long transactions in the chapter on what is thelogical log in the Administrator’s Guide


MAX_CHUNKS

MAX_CHUNKS

MAX_CHUNKS allows you to increase the maximum number of chunks up to32,767. The safewrite area in the first chunk of the root dbspace grows toaccommodate the new maximum number of chunks. If you set theMAX_CHUNKS value and later decrease it, the database server ignores thenew value and uses the previously set value. However, you can increase theMAX_CHUNKS value at any time.

The database server ignores the MAX_CHUNKS value if it is smaller than thenumber of chunks that CONFIGSIZE allows. For example, a CONFIGSIZEvalue of LARGE allows a maximum of 8192 chunks. If you set CONFIGSIZE toLARGE and specify a MAX_CHUNKS value of 2048, the maximum number ofchunks is 8192. For more information, see “CONFIGSIZE” on page 1-30.

When you allocate the initial chunk for the root dbspace of any coserver, youmust ensure that enough space is available for the safewrite area. Allow anextra 6.2 megabytes for a CONFIGSIZE of LARGE, plus 302 bytes per additionalchunk for the safewrite area. Add this amount to the size of the initial chunkof the root dbspace in each coserver. In the formula, additional_chunks meansmore chunks than the CONFIGSIZE maximum (8193 to 32,767 chunks).

total space for the safewrite area in bytes =6200000 bytes + (302 bytes * additional_chunks)

If you do not provide enough space for the safewrite area, the database writesa message to the transaction log to report this situation. If insufficient spaceis available in the root dbspace, you might need to reinitialize the databaseserver and reload your data.

onconfig.stdvalue

0

units Number of chunks

range of values 0 through 32,767


refer to Chapter on managing disk space in the Administrator’sGuide

XPS


MAX_DBSLICES

MAX_DBSLICES

MAX_DBSLICES allows you to increase the maximum number of dbslices to2047. The safewrite area in the first chunk of the root dbspace grows toaccommodate the new maximum number of dbslices. If you set theMAX_DBSLICES value and later decrease it, the database server ignores thenew value and uses the previously set value. However, you can increase theMAX_DBSLICES value at any time.

The database server ignores the MAX_DBSLICES value if it is smaller than thenumber of dbslices that the CONFIGSIZE parameter allows. For example, aCONFIGSIZE value of LARGE allows a maximum of 512 dbslices. If you setCONFIGSIZE to LARGE and specify a MAX_DBSLICES value of 10, themaximum number of dbslices is 512. For more information, see“CONFIGSIZE” on page 1-30.

When you allocate the initial chunk for the root dbspace of any coserver, youmust ensure that enough space is available for the safewrite area. Allow anextra 6.2 megabytes for a CONFIGSIZE of LARGE, plus 20 bytes per additionaldbslice for the safewrite area. Add this amount to the size of the initial chunkof the root dbspace in each coserver. In the formula, additional_dbslices meansmore dbslices than the CONFIGSIZE maximum (513 to 2047 dbslices).

total space for the safewrite area in bytes=6200000 bytes + (20 bytes * additional_dbslices)

If the safewrite area does not have enough space, the database writes amessage to the transaction log to report this situation. If insufficient space isavailable in the root dbspace, you might need to reinitialize the databaseserver and reload your data.

onconfig.stdvalue

0

units Number of dbslices




XPS


MAX_DBSPACES

MAX_DBSPACES

MAX_DBSPACES allows you to increase the maximum number of dbspaces.The safewrite area in the first chunk of the root dbspace grows to accom-modate the new maximum number of dbspaces. If you use a CONFIGSIZEvalue of LARGE, the maximum number of dbspaces is 8192, but you can useMAX_DBSPACES to specify up to 32,767 dbspaces. For more information, see“CONFIGSIZE” on page 1-30.

If you set the MAX_DBSPACES value and later decrease it, the database serverignores the new value and uses the previously set value. However, you canincrease the MAX_DBSPACES value at any time.

When you allocate the initial chunk for the root dbspace of any coserver, youmust ensure that enough space is available for the safewrite area. If youcreate more than 8192 dbspaces, allow an extra 56 bytes per additionaldbspace for the safewrite area. For example, if you set MAX_DBSPACES to8200, allow an extra 448 bytes (56 bytes * 8 dbspaces).

If you do not provide enough space for the safewrite area, the database writesa message to the transaction log to report this situation. If insufficient spaceis available in the root dbspace, you might need to reinitialize the databaseserver and reload your data.

onconfig.stdvalue

0

units Number of dbspaces

range of values 0 through 32,767



XPS


MAX_PDQPRIORITY

MAX_PDQPRIORITY

MAX_PDQPRIORITY limits the PDQ resources that the database server canallocate to any one DSS query. MAX_PDQPRIORITY is a factor that is used toscale the value of PDQ priority set by users. For example, suppose that thedatabase administrator sets MAX_PDQPRIORITY to 80. If a user sets thePDQPRIORITY environment variable to 50 and then issues a query, thedatabase server silently processes the query with a PDQ priority of 40.

You can use the onmode utility to change the value of MAX_PDQPRIORITYwhile the database server is on-line. Refer to “Change Decision-SupportParameters” on page 3-52.

PDQ resources include memory, CPU, disk I/O, and scan threads.MAX_PDQPRIORITY lets the database administrator run decision supportconcurrently with OLTP without a deterioration of OLTP performance.However, if MAX_PDQPRIORITY is too low, the performance of decision-support queries can degrade.

onconfig.stdvalue

100

if not present 100


takes effect On all user sessions

utilities onmode -DON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)


IDS


MAX_PDQPRIORITY

You can set MAX_PDQPRIORITY to one of the following values.

In Extended Parallel Server, PDQPRIORITY affects only memory resources.The values of the MAX_PDQPRIORITY and PDQPRIORITY parameters do notaffect parallel operations. Parallel operations (such as scans, sorts, and joins)can occur if multiple coservers and CPU VPs are involved in the operationand the default memory is sufficient for parallel threads. For more infor-mation on parallel operations, refer to your Performance Guide.

Value Database Server Action

0 Turns off PDQ. DSS queries use no parallelism.

1 Fetches data from fragmented tables in parallel (parallel scans) butuses no other form of parallelism.

100 Uses all available resources for processing queries in parallel.

number Sets the percentage of the user-requested PDQ resources actuallyallocated to the query. The number variable is an integer between 0and 100.

♦

XPS


MIRROR

You can set MAX_PDQPRIORITY to one of the following values.

MIRROR

In Dynamic Server, MIRROR is a flag that indicates whether mirroring isenabled for the database server. Enable mirroring if you plan to create amirror for the root dbspace as part of initialization. Otherwise, leavemirroring disabled. If you later decide to add mirroring, you can edit yourconfiguration file to change the parameter value. ♦

In Extended Parallel Server, MIRROR is a global configuration parameter thatindicates whether mirroring is enabled. Enable mirroring if you plan to createa mirror for all root dbspaces as part of initialization. Otherwise, leavemirroring disabled. If you later decide to add mirroring, you can edit yourconfiguration file to change the parameter value. ♦

Value Database Server Action

100 Uses all available memory for processing queries in parallel.

number Sets the percentage of the user-requested PDQ resources actuallyallocated to the query. The number variable is an integer between 0and 100.

♦

onconfig.stdvalue

0

range of values 0 = Disable mirroring.1 = Enable mirroring.


utilities ON-Monitor: Parameters, Initialize, Mirror (IDS, UNIX)


■ Mirroring critical data in the chapter on where is datastored

■ Enabling mirroring in the chapter on using mirroring

IDS

XPS


MIRROROFFSET

MIRROROFFSET

In Dynamic Server, MIRROROFFSET specifies the offset into the disk partitionor into the device to reach the chunk that serves as the mirror for the initialchunk of the root dbspace.♦

In Extended Parallel Server, MIRROROFFSET specifies the offset into the diskpartition to reach the chunk that serves as the mirror for the initial chunk ofeach root dbspace.

You can specify MIRROROFFSET as a global configuration parameter to applyto all coservers. Optionally, you can also specify MIRROROFFSET in thecoserver-specific section of the ONCONFIG file to override the global value ifyou want a different offset for a specific coserver. ♦

onconfig.stdvalue

0

units Kilobytes



utilities ON-Monitor: Parameters, Initialize, Offset (below MirrorPath) (IDS, UNIX)

refer to Mirroring the root dbspace during initialization in thechapter on using mirroring in the Administrator’s Guide

IDS

XPS


MIRRORPATH

MIRRORPATH

MIRRORPATH specifies the full pathname of the mirrored chunk for the initialchunk of the root dbspace. MIRRORPATH should be a link to the chunkpathname of the actual mirrored chunk for the same reasons that ROOTPATHis specified as a link. Similarly, select a short pathname for the mirroredchunk. ♦

MIRRORPATH specifies the full pathname, including the device or filename,of the initial chunk of the mirror for the root dbspace of each coserver.

You can specify MIRRORPATH as a global configuration parameter to apply toall coservers. Optionally, you can also specify MIRRORPATH in the coserver-specific section of the ONCONFIG file to override the global value andprovide a different pathname for a specific coserver.

You can use the following formatting characters to apply the globalMIRRORPATH parameter to all coservers.

onconfig.stdvalue

None

range of values 65 or fewer characters


utilities ON-Monitor: Parameters, Initialize, Mirror Path (IDS,UNIX)

refer to Mirroring the root dbspace during initialization in thechapter on using mirroring in the Administrator’s Guide

Format Description

%c Replaced with the specific coserver number

%n Replaced with the host name of the node

♦

IDS

XPS


MSGPATH

Setting PermissionsYou must set the permissions of the file that MIRRORPATH specifies to 660.The owner and group must both be informix.

If you use raw disk space for your mirror chunk on a UNIX platform, Informixrecommends that you define MIRRORPATH as a pathname that is a link to theinitial chunk of the mirror dbspace instead of entering the actual device namefor the initial chunk. For a rationale for using links rather than device names,refer to allocating disk space on UNIX platforms in the chapter on managingdisk space in the Administrator’s Guide.

MSGPATH

MSGPATH specifies the full pathname of the message-log file. The databaseserver writes status messages and diagnostic messages to this file duringoperation.

If the file that MSGPATH specifies does not exist, the database server createsthe file in the specified directory. If the directory that MSGPATH specifies doesnot exist, the database server sends the messages to the database adminis-trator’s terminal.

If the file that MSGPATH specifies does exist, the database server opens it andappends messages to it as they occur.

onconfig.stdvalue

On UNIX: /usr/informix/online.logOn Windows NT: online.log

if not present On UNIX: /dev/tty



utilities ON-Monitor: Parameters, diaGnostics, Message Log (IDS,UNIX)

refer to Message log in the chapter on overview of databaseserver administration in the Administrator’s Guide

UNIX


MULTIPROCESSOR

MULTIPROCESSOR

If MULTIPROCESSOR is set to 0, the AFF_NPROCS and AFF_SPROC parametersare ignored.

In Dynamic Server, MULTIPROCESSOR specifies whether the database serverperforms locking in a manner that is suitable for a single-processor computeror a multiprocessor computer. ♦

In Extended Parallel Server, MULTIPROCESSOR specifies whether thedatabase server or coserver performs locking in a manner that is suitable fora single-processor computer or a multiprocessor computer. ♦

NETTYPE

onconfig.stdvalue

0

if not present Platform dependent

range of values 0 = No multiprocessor1 = Multiprocessor available


utilities ON-Monitor: Parameters, perFormance, MultiprocessorMachine (IDS, UNIX)

refer to CPU virtual processors in the chapter on virtualprocessors and threads in the Administrator’s Guide

syntax NETTYPEprotocol,poll_threads,connections,VP_class

The protocol value is required. You cannot use any whitespace in the fields, but you can omit trailing commas.

onconfig.stdvalues

On UNIX: NoneOn Windows NT: onsoctcp,1,NET

IDS

XPS


NETTYPE

if not present protocol:

■ On UNIX: nettype field from the sqlhosts file(optionally minus the database server prefix of on or ol)

■ On Windows NT: onsoctcp

poll_threads: 1connections: 50VP_class: NET if for DBSERVERALIASES; CPU if forDBSERVERNAME

units poll_threads: NUMCPUVPSconnections: Number of connections

separators Commas

range of values protocol:

■ On UNIX: Same as the nettype values (with or withoutthe database server prefix of on or ol) that are acceptedin the sqlhosts file

■ On Windows NT: onsoctcp

poll_threads:

■ On UNIX:If VP_class is NET, a value greater than or equal to 1If VP_class is CPU, 1 through NUMCPUVPS

■ On Windows NT:Any value greater than or equal to 1

connections: 1 through 32,767VP_class:CPU = CPU VPs (on UNIX)NET = Network VPs

For Dynamic Server:To enable multiplexed connections on UNIX, use SQLMUXas the only parameter value.



NETTYPE

The NETTYPE parameter usually provides tuning options for the protocolsthat dbservername entries define in the sqlhosts file or registry.

In Dynamic Server, the NETTYPE parameter also lets the database serverimplement multiplexed connections on UNIX. For more information, refer tomultiplexed connections in the chapter on client/server communications. ♦

Each dbservername entry in the sqlhosts file or registry is defined on eitherthe DBSERVERNAME parameter or the DBSERVERALIASES parameter in theONCONFIG file.

The NETTYPE configuration parameter describes a network connection asfollows:

■ The protocol (or type of connection)

■ The number of poll threads assigned to manage the connection

■ The expected number of concurrent connections per poll thread

■ The class of virtual processor that will run the poll threads

You can specify a NETTYPE parameter for each protocol that you want thedatabase server to use. The following example illustrates NETTYPE param-eters for two types of connections to the database server, a shared memoryconnection for local clients and a network connection that uses sockets:

NETTYPE ipcshm,3,,CPUNETTYPE soctcp,,20,NET

utilities ON-Monitor: Parameters: perFormance, Protocol,Threads, Users (connections), VP-class entries for theprotocols supported on the computer (IDS, UNIX)

refer to The following sections in the Administrator’s Guide:

■ The nettype and protocol field in the chapter onclient/server communications

■ Network virtual processors in the chapter on virtualprocessors and threads

■ Should poll threads run on CPU or network virtualprocessors in the chapter on virtual processors andthreads

IDS


NETTYPE

The NETTYPE parameter for the shared-memory connection (ipcshm)specifies three poll threads to run in CPU virtual processors. The number ofconnections is not specified, so it is set to 50. The NETTYPE parameter for thesockets connection (soctcp) specifies that only 20 simultaneous connectionsare expected for this protocol and that one poll thread (because the numberof poll threads is not specified) will run in a network virtual processor (in thiscase, SOC).

ProtocolThe protocol entry is the same as the nettype field in the sqlhosts file orregistry, except that the database server prefix of on or ol is optional. The firstthree characters of the protocol entry specify the interface type, and the lastthree characters specify the IPC mechanism or the network protocol. Forinformation on the possible values for the protocol entry, see the nettype andprotocol field in the chapter on client/server communications in the Admin-istrator’s Guide.

Number of Poll ThreadsThis field specifies the number of poll threads for a specific protocol. Thedefault value of poll_threads is 1.

If your database server has a large number of connections, you might be ableto improve performance by increasing the number of poll threads. In general,each poll thread can handle approximately 200 to 250 connections.

The following example illustrates NETTYPE parameters to increase thenumber of poll threads and decrease the number of connections per pollthread. This example allows up to 60 connections of a shared memoryconnection.

NETTYPE ipcshm,3,20,CPU

For more information on monitoring and tuning the number of poll threadsand connections, refer to your Performance Guide. ♦

On Windows NT, the number of connections per poll thread is ignored for allNETTYPE connections other than shared memory. ♦

UNIX

WIN NT


NETTYPE

Number of ConnectionsThis field specifies the maximum number of connections per poll thread thatcan use this protocol at the same time.

The default value of connections is 50. If you know that only a few connectionswill be using a protocol concurrently, you might save memory by explicitlysetting the estimated number of connections.

For all net types other than ipcshm, the poll threads dynamically reallocateresources to support more connections as needed. Avoid setting the value forthe number of concurrent connections to much higher than you expect.Otherwise, you might waste system resources.

On Windows NT, the number of connections per poll thread is ignored for allNETTYPE connections other than shared memory. ♦

For more information on poll threads, refer to network virtual processors inthe chapter on virtual processors and threads in the Administrator’s Guide.

Class of Virtual ProcessorYou can set the VP_class entry to specify either CPU or NET. However, thecombined number of poll threads defined with the CPU VP class for all nettypes cannot exceed the maximum number of CPU VPS.

For advice on whether to run the poll threads on CPU or NET virtualprocessors, refer to the section about poll threads running on CPU or networkvirtual processors in the chapter on virtual processors and threads in theAdministrator’s Guide.

Database servers on Windows NT should use the NET designation. ♦

Default ValuesInformix recommends that you use NETTYPE to configure each of yourconnections. However, if you do not use NETTYPE, the database server usesthe default values to create a single poll thread for the protocol. If thedbservername is defined by DBSERVERNAME, by default the poll thread isrun by the CPU class. If the dbservername is defined by DBSERVERALIASES,the default VP class is NET.

WIN NT

WIN NT


NOAGE

Multiplexed ConnectionsTo enable the database server to use multiplexed connections, you mustinclude a special NETTYPE parameter with the value SQLMUX, as in thefollowing example:

NETTYPE SQLMUX

For more information, refer to multiplexed connections in the chapter onclient/server communications in the Administrator’s Guide.

NOAGE

Some operating systems lower the priority of processes as the processes runover a long period of time. NOAGE, when set to 1, disables priority aging ofCPU virtual processors by the operating system. When NOAGE is set to thedefault of 0, the operating system might lower the priority of CPU virtualprocessors, as well as other processes, as they accumulate processing time. Ifyour operating system supports priority aging, Informix recommends thatyou set NOAGE to 1.

Informix suggests that you specify priority aging with the VPCLASSparameter instead of the NOAGE parameter. You cannot use both NOAGE andVPCLASS CPU in the same ONCONFIG file. For more information, refer to“VPCLASS” on page 1-148. ♦

onconfig.stdvalue

0

range of values 0 = Use priority aging.1 = Disable priority aging.


utilities ON-Monitor: Parameters, perFormance, Disable PriorityAging (IDS, UNIX)

refer to Preventing priority aging in the chapter on virtualprocessors and threads in the Administrator’s Guide

IDS

IDS


NODE

NODE

The NODE name is the host name of the node where the coserver executes.The host name is located in the hosts connectivity file. You assign eachcoserver to a node when you specify this NODE parameter in the coserver-specific section of the ONCONFIG configuration file.

Some computer platforms on which Extended Parallel Server executesrequire separate host names or host-name aliases for nodes that connect tothe high-speed communication interface. If your platform requires the use ofsuch names, be sure to list the proper host names for high-speed access in thisNODE configuration parameter.

The machine notes file indicates if these names are required.

onconfig.xpsvalue

node1

if not present None

range of values 64 or fewer lowercase characters

protocol: hostname field from the hosts connectivity file

takes effect When shared memory is initialized. In addition, thesqlhosts file of each database server and client appli-cation might need to be updated.

refer to Setting coserver-specific parameters in the chapter onconfiguration parameters in the Administrator’s Guide

if not present None

XPS


NUMAIOVPS

NUMAIOVPS

NUMAIOVPS specifies the number of virtual processors of the AIO class torun. Unless kernel asynchronous I/O is implemented, the AIO virtualprocessors perform all the database server disk I/O, other than I/O to the logfiles.

If kernel-asynchronous I/O is supported on your platform, the databaseserver uses AIO virtual processors to perform I/O only to regular (cooked)files that you have configured as chunks. ♦

Informix suggests that you specify the number of AIO VPs with VPCLASS AIOinstead of NUMAIOVPS. You cannot use both NUMAIOVPS and VPCLASS AIOin the same ONCONFIG file. For more information, refer to “VPCLASS” onpage 1-148. ♦

For information about using onmode -p, see “Add or Remove VirtualProcessors” on page 3-49.

onconfig.stdvalue

None

if not present (2 * number_of_chunks) or 6, whichever is greater;number_of_chunks is the number of chunks that you haveallocated.

units Number of AIO VPs

range of values Integer greater than or equal to 1


utilities onmode -pON-Monitor: Parameters, perFormance, AIO VPs (IDS,UNIX)

refer to Asynchronous I/O in the chapter on virtual processorsand threads in the Administrator’s Guide

UNIX

IDS


NUMCPUVPS

NUMCPUVPS

NUMCPUVPS specifies the number of virtual processors of the CPU class torun. CPU virtual processors run all threads that start as the result of aconnection by a client application, as well as internal threads. On a single-processor computer, allocate only one CPU virtual processor. On amultiprocessor computer, do not allocate more CPU virtual processors thanthere are CPUs on the computer.

On a single-processor computer or node, allocate only one CPU virtualprocessor. On a multiprocessor computer or node, do not allocate more CPUvirtual processors than there are CPUs. ♦

Informix suggests that you specify the number of CPU virtual processorswith VPCLASS CPU instead of NUMCPUVPS. You cannot use bothNUMCPUVPS and VPCLASS CPU in the same ONCONFIG file. For information,refer to ““VPCLASS” on page 1-148. ♦

For information about using onmode -p, see “Add or Remove VirtualProcessors” on page 3-49.

On UNIX, use the onmode -p -1 CPU command to decrease the number ofCPU VPs. On Windows NT, you can add a CPU VP, but you cannot subtract it.

onconfig.stdvalue

1

units Number of CPU VPs

range of values 1 through the number of CPUs


utilities onmode -pON-Monitor: Parameters, perFormance, CPU VPs (IDS,UNIX)

refer to CPU virtual processors in the chapter on virtualprocessors and threads in the Administrator’s Guide

XPS

IDS


NUMFIFOVPS

NUMFIFOVPS

NUMFIFOVPS specifies the number of virtual processors of the FIF class torun. The database server uses two FIF virtual processors to run loads andunloads through named pipes.

For information about onmode -p, see “Add or Remove Virtual Processors”on page 3-49.

OFF_RECVRY_THREADS

onconfig.stvalue

2



utility onmode -p

refer to First-in-first-out virtual processor in the chapter onvirtual processors and threads in the Administrator’s Guide

onconfig.stdvalue

10

units Number of recovery threads



utilities ON-Monitor: Parameters, perFormance, Off-LineRecovery Threads (IDS, UNIX)

refer to One of the following manuals:

■ Backup and Restore Guide for ON-Bar

■ Archive and Backup Guide for ON-Archive or ontape

XPS


ON_RECVRY_THREADS

OFF_RECVRY_THREADS is the number of recovery threads used in logicalrecovery when the database server is off-line (during a cold restore). Thisnumber of threads is also used to roll forward logical-log records in fastrecovery.

Before you perform a cold restore, you can set the value of this parameter toapproximately the number of tables that have a large number of transactionsagainst them in the logical log. For single-processor computers, more than 30to 40 threads is probably too many because the overhead of threadmanagement probably offsets the increase in parallel processing.

In Extended Parallel Server, for single-processor computers or nodes, morethan 30 to 40 threads is probably too many because the overhead of threadmanagement probably offsets the increase in parallel processing. ♦

ON_RECVRY_THREADS

ON_RECVRY_THREADS is the maximum number of recovery threads that thedatabase server uses for logical recovery when the database server is on-line(that is, during a warm restore).

onconfig.stdvalue

1

units Number of recovery threads



utilities ON-Monitor: Parameters, perFormance, On-LineRecovery Threads (IDS, UNIX)

refer to One of the following manuals:

■ Backup and Restore Guide for ON-Bar

■ Archive and Backup Guide for ON-Archive or ontape

XPS


ON-Bar Parameters

You can tune ON_RECVRY_THREADS to the number of tables that are likely tobe recovered because the logical-log records that are processed duringrecovery are assigned threads by table number. The maximum degree ofparallel processing occurs when the number of recovery threads matches thenumber of tables being recovered.

With fuzzy checkpoints, fast recovery might take longer than with full check-points. To improve the performance of fast recovery, increase the number offast-recovery threads with the ON_RECVRY_THREADS parameter. Thenumber of threads should usually match the number of tables or fragmentsthat are frequently updated to roll forward the transactions recorded in thelogical log.

ON-Bar ParametersThe following table lists the configuration parameters that apply to theON-Bar backup and restore utility. For more information on these param-eters, see the Backup and Restore Guide.

The ONCONFIG file can contain BAR_SM-specific sections that begin with theBAR_SM parameter and end with the END parameter. The BAR_SM parameterintroduces a BAR_SM paragraph that cannot be nested or located inside thestorage-manager specific section.

You must specify some ON-Bar parameters in the BAR_SM section only, somein the BAR_SM or global section, and some in the global section only. ♦

XPS

Configuration Parameter Description IDS XPS

Can beBAR_SMspecific

AlwaysBAR_SMspecific

BAR_ACT_LOG Specifies the location of theON-Bar activity log file.

✔ ✔

BAR_BOOT_DIR Specifies the directory for theemergency boot files.

✔

BAR_BSALIB_PATH Specifies the pathname andfilename of the XBSA sharedlibrary for the storage manager.

✔ ✔ ✔

(1 of 3)


ON-Bar Parameters

BAR_DBS_COSVR Specifies coservers that sendbackup and restore data to thestorage manager.

✔ ✔

BAR_HISTORY Specifies whether the sysutilsdatabase maintains a backuphistory.

✔ ✔

BAR_IDLE_TIMEOUT Specifies the maximum number ofminutes that an onbar-workerprocess is idle before it is shutdown.

✔ ✔

BAR_LOG_COSVR Specifies coservers that send logbackup data to the storagemanager.

✔ ✔

BAR_MAX_BACKUP Specifies the maximum number ofbackup processes per ON-Barcommand.

✔

BAR_NB_XPORT_COUNT Specifies the number of shared-memory data buffers for eachbackup or restore process.

✔

BAR_PROGRESS_FREQ Specifies in minutes howfrequently the backup or restoreprogress messages display in theactivity log.

✔ ✔

BAR_RETRY Specifies how many times ON-Barshould retry a backup or restoreoperation.

✔ ✔

BAR_SM Specifies the storage-managernumber.

✔ ✔

BAR_SM_NAME Specifies the storage-managername.

✔ ✔

BAR_WORKER_COSVR Lists the coservers that can accessthe storage manager.

✔ ✔




(2 of 3)


ON-Bar Parameters

BAR_WORKER_MAX Specifies the maximum number ofonbar-worker processes startedfor a storage manager.

✔ ✔

BAR_XFER_BUF_SIZE Specifies the size in pages of thebuffers.

✔

BAR_XFER_BUFSIZE Specifies the size in pages of thebuffers.

✔

BAR_XPORT_COUNT Specifies the number of shared-memory data buffers for eachbackup or restore process.

✔

ISM_DATA_POOL Specifies the volume pool that youuse for backing up storage spaces.

✔ ✔ ✔

ISM_LOG_POOL Specifies the volume pool that youuse for backing up logical logs.

✔ ✔ ✔

LOG_BACKUP_MODE Specifies whether to use manual orcontinuous logical-log backups.For more information, see“LOG_BACKUP_MODE” onpage 1-70.

✔

RESTARTABLE_RESTORE Controls how ON-Bar restarts afailed physical or logical restore.For more information, see“RESTARTABLE_RESTORE” onpage 1-123.

✔




(3 of 3)


ONDBSPACEDOWN

ONDBSPACEDOWN

ONDBSPACEDOWN defines the action that the database server will take whenany disabling event occurs on a noncritical dbspace. The following values arevalid for this parameter.

onconfig.stdvalue

2

range of values 0, 1, 2

utilities ON-Monitor: Parameters, Shared-Memory, DbspaceDown Option (IDS, UNIX)

refer to Monitoring the database server for disabling I/O errors inthe chapter on managing disk space in the Administrator’sGuide

Value Description

0 Continue. Causes the database server to mark a noncritical dbspacedown and continue whenever a disabling I/O error occurs on it.

1 Abort. Causes the database server to fail without allowing a checkpointto occur whenever a disabling I/O error occurs on any dbspace. Criticaldbspaces run only in this mode.

2 Wait. Causes the database server to hang all updating threads as soonas the next checkpoint request occurs after a disabling I/O occurs on anoncritical dbspace.


OPCACHEMAX

OPCACHEMAX

OPCACHEMAX specifies the size of the memory cache for the OpticalSubsystem. The database server stores pieces of TEXT or BYTE data in thememory cache before it delivers them to the subsystem. Use this parameteronly if you use the Optical Subsystem.

The INFORMIXOPCACHE environment variable lets the client restrict the sizeof the optical cache that it uses.

onconfig.stdvalue

0

if not present 128

units Kilobytes

range of values 0 through (4 * 1024 * 1024)

takes effect When the Optical Subsystem needs more memory

utilities ON-Monitor: Parameters, Initialize, StageBlob


■ Guide to the Optical Subsystem

■ INFORMIXOPCACHE environment variable in theInformix Guide to SQL: Reference

IDS

UNIX


OPTCOMPIND

OPTCOMPIND

OPTCOMPIND helps the optimizer choose an appropriate query plan for yourapplication.

Tip: You can think of the name of the variable as arising from “OPTimizer COMPare(the cost of using) INDexes (with other methods).”

onconfig.stdvalue

2

range of values 0 = When appropriate indexes exist for each ordered pairof tables, the optimizer chooses index scans (nested-loopjoins), without consideration of the cost, over table scans(hash joins). This value ensures compatibility withprevious versions of the database server.

1 = The optimizer uses costs to determine an executionpath if the isolation level is not Repeatable Read.Otherwise, the optimizer chooses index scans (it behavesas it does for the value 0). Informix recommends thissetting for optimal performance.

2 = The optimizer uses cost to determine an executionpath for any isolation level. Index scans are not givenpreference over table scans; the optimizer bases itsdecision purely on cost. This value is the default if thevariable is not set.

utilities ON-Monitor: Parameters menu, pdQ screen (IDS, UNIX)



■ OPTCOMPIND environment variable in the InformixGuide to SQL: Reference


OPT_GOAL

Because of the nature of hash joins, an application with isolation mode set toRepeatable Read might temporarily lock all records in tables that are involvedin the join (even those records that fail to qualify the join) for each ordered setof tables. This situation leads to higher contention among connections.Conversely, nested-loop joins lock fewer records but provide inferior perfor-mance when the database server retrieves a large number of rows. Thus, bothjoin methods offer advantages and disadvantages. A client application canalso influence the optimizer in its choice of a join method.

OPT_GOAL

The OPT_GOAL parameter enables you to specify one of the followingoptimization goals for queries:

■ Optimize for FIRST ROWS

■ Optimize for ALL ROWS

A value of 0 sets the optimization goal to FIRST_ROWS. A value of -1 sets theoptimization goal to ALL_ROWS, which is the default.

When you set the optimization goal to optimize for FIRST ROWS, you specifythat you want the database server to optimize queries for perceived responsetime. In other words, users of interactive applications perceive response timeas the time that it takes to display data on the screen. Setting the optimizationgoal to FIRST ROWS configures the database server to return the first rows ofdata that satisfy the query.

onconfig.stdvalue

-1

range of values 0 or -1


refer to The following manuals:

■ Informix Guide to SQL: Reference

■ Informix Guide to SQL: Syntax


IDS


PAGESIZE

When you set the optimization goal to optimize for ALL ROWS, you specifythat you want the database server to optimize for the total execution time ofthe query. Making ALL ROWS the optimization goal instructs the databaseserver to process the total query as quickly as possible, regardless of howlong it takes to return the first rows to the application.

You can specify the optimization goal in one of four ways:

■ By query (SELECT statement)

Use the ALL_ROWS and FIRST_ROWS directives.

■ By session

Use the SET OPTIMIZATION statement.

■ By environment

Set the OPT_GOAL environment variable.

■ By database server

Set the OPT_GOAL configuration parameter.

To determine the optimization goal, the database server examines thesettings in the order shown. The first setting encountered determines theoptimization goal. For example, if a query includes the ALL_ROWS directivebut the OPT_GOAL configuration parameter is set to FIRST_ROWS, thedatabase server optimizes for ALL_ROWS, as the query specifies.

For information on the ALL_ROWS and FIRST_ROWS directives and on theSET OPTIMIZATION statement, refer to the Informix Guide to SQL: Syntax. Forinformation on the OPT_GOAL environment variable, refer to the InformixGuide to SQL: Reference. For more information on the performance issuesassociated with setting an optimization goal, refer to your Performance Guide.

PAGESIZEonconfig.std

value4096

if not present 4096

units Bytes

XPS


PAGESIZE

When you install Extended Parallel Server, use PAGESIZE to configure thedatabase server page size. You can specify a page size of 2048, 4096, or 8192bytes. If you do not set the PAGESIZE parameter, the database server uses thedefault page size of 4096 bytes. Once you set the PAGESIZE value, you cannotchange it until you reinitialize the database server, upgrade, or revert to anearlier version.

Use the following chart to select the best page size for your database server.If your workload is mostly DSS queries, a larger page size provides betterperformance. If your workload is mostly OLTP, a smaller page size providesbetter performance.

To check the page size, use the onstat -b or onutil CHECK RESERVED utility.

If you change the page size, old backups will not be compatible with the newdatabase server version. You should back up your data if you change thepage size or upgrade the database server.

If you are migrating to a new version of the database server and decide tochange the page size, the total size of the buffer pool and log buffers willchange. For details, see the Informix Migration Guide.

range of values 2048, 4096, or 8192

takes effect When the database server is initialized


■ Chapter on managing disk space in the Administrator’sGuide


■ Informix Migration Guide

Workload Type PAGESIZE Value

OLTP 2048 bytes

Mixture of OLTP and DSS (50%-50%) 4096 bytes

DSS 8192 bytes

Many simple large objects or long rows 8192 bytes


PC_HASHSIZE

PC_HASHSIZE

Use PC_HASHSIZE to specify the number of hash buckets in the caches thatthe database server uses.

Cache types include UDR caches. ♦

PC_POOLSIZE

Use PC_POOLSIZE to specify the maximum number of entries in severalmemory caches that the database server uses.

For the UDR cache, PC_POOLSIZE specifies the maximum number of UDRsand SPL routines stored in the UDR cache. ♦

onconfig.stdvalue

None

range of values Any positive value



onconfig.stdvalue

None

range of values Any positive value



IDS

IDS


PDQPRIORITY

PDQPRIORITY

PDQPRIORITY specifies the relative amount of memory resources that a queryrequests. A query can request a percentage of memory or a minimum andmaximum range of memory. The database server balances this request withthe requests of other applications and determines the amount of memory thatthe query actually receives.

In Extended Parallel Server, the value of PDQPRIORITY does not affect thedegree of parallelism. The database server determines the best degree ofparallelism for each component of a PDQ query, based on various consider-ations such as the number of available coservers, the number of virtualprocessors (VPs) on each coserver, the fragmentation of the tables that arebeing queried, the complexity of the query, and so forth.

onconfig.stdvalue

0

range of values 0 through 100Integer, integerLOWHIGH

takes effect On all user sessions, unless overridden by thePDQPRIORITY environment variable or the SQLstatement SET PDQPRIORITY


XPS


PDQPRIORITY

The PDQPRIORITY configuration parameter takes one of the values in thefollowing table and affects all user sessions. If unset, the default value ofPDQPRIORITY is 0.

If you specify a single integer for PDQPRIORITY, the query can run only whenthe specified percentage of memory is available. If you specify a range ofmemory, you leave the choice of the actual PDQPRIORITY value to thediscretion of the RGM, and the choice depends on the current workload. Thelargest PDQPRIORITY value in the range is the desired memory allocation,while the smallest PDQPRIORITY value is the minimum acceptable memoryallocation for the query.

Although it is usually true that the more memory the database server uses,the better the performance for a given query, over-allocation can causecontention for memory and take away memory from other queries, resultingin degraded performance. For more information on performance consider-ations for PDQPRIORITY, refer to your Performance Guide.

Value Description

integer Integer value that requests the percentage of memory resources toprocess the query. Value must be in the range 0 to 100. Value 0requests the minimum 128 kilobytes of memory.

If you do not specify this PDQPRIORITY parameter, 0 is thedefault setting.

, integer Optional integer value that establishes the maximum percentageof memory that a query can request. When you specify this secondinteger value, you request a range of memory percentage.

HIGH When the database server allocates resources among all users, itprovides as much memory resources as possible to the query.

LOW This setting indicates that data is fetched from fragmentedtables in parallel. Other parallel operations can occur whenPDQPRIORITY is LOW.

Even when PDQPRIORITY is 0 or LOW, Extended Parallel Servercan execute a query in parallel, depending upon the availability ofmultiple of coservers, multiple virtual processors, disks on whichfragments of the data reside, and if the default size of memory isadequate to process the SQL operators involved in the query.


PHYSBUFF

If the PDQPRIORITY environment variable is set, its value overrides thevalue of the PDQPRIORITY configuration parameter. An application canoverride the setting of the PDQPRIORITY environment variable when itissues the SQL statement SET PDQPRIORITY. However, regardless of whatvalue is specified, the effective value of PDQPRIORITY is factored by the valueof the MAX_PDQPRIORITY configuration parameter.

PHYSBUFF

PHYSBUFF specifies the size in kilobytes of each of the two physical-logbuffers in shared memory. Double buffering permits user threads to write tothe active physical-log buffer while the other buffer is being flushed to thephysical log on disk. The value of the PHYSBUFF parameter determines howfrequently the database server needs to flush the physical-log buffer to thephysical-log file.

A write to the physical-log buffer is exactly one page in length. Choose avalue for PHYSBUFF that is evenly divisible by the page size. If the value ofPHYSBUFF is not evenly divisible by the page size, the database server roundsdown the size to the nearest value that is evenly divisible by the page size.

The minimum value for PHYSBUFF is the size of one page. The recommendedvalue for PHYSBUFF is 16 pages.

For Dynamic Server, the user-data portion of a smart large object does notpass through the physical-log buffers. ♦

onconfig.stdvalue

32

units Kilobytes

range of values Page size through PHYSFILE


utilities ON-Monitor: Parameters, Shared-Memory, Physical-logBuffer Size (IDS, UNIX)

refer to Physical-log buffer in the shared-memory chapter of theAdministrator’s Guide

IDS


PHYSDBS

System Page SizeThe system page size is platform dependent on Dynamic Server. You can usethe commands listed in the table in “System Page Size” on page 1-27 to obtainthe system page size. ♦

You can configure the system page size with a default page size of 4096 bytes.For more information, see “PAGESIZE” on page 1-111. ♦

PHYSDBSonconfig.std

valuerootdbs

if not present The dbspace that ROOTNAME specifies

units A dbspace

range of values For Dynamic Server: Up to 128 characters. PHYSDBS mustbe unique, begin with a letter or underscore, and containonly letters, numbers, underscores, or $ characters.

For Extended Parallel Server: Up to 18 characters.PHYSDBS must be unique, begin with a letter or under-score, and contain only letters, numbers, or underscores.


utilities ON-Monitor: Parameters, Physical-Log, Dbspace Name(IDS, UNIX)

onutil (XPS)See “onutil: Check, Define, and Modify Storage Objects”on page 3-135.

IDS

XPS


PHYSDBS

PHYSDBS specifies the name of the dbspace that contains the physical log. Toreduce disk contention, you can move the physical log to a dbspace otherthan the root dbspace.

When you initialize disk space (oninit -i), the PHYSDBS value must be equalto the ROOTDBS value.

The PHYSDBS parameter specifies the name of the dbspace that contains thephysical log for a particular coserver.

If you use the PHYSSLICE parameter to create a dbslice for physical logs, youcan list the PHYSDBS parameter in the coserver-specific section of yourONCONFIG file to change the location of the physical log on a specificcoserver. ♦


■ “Change Physical-Log Parameters” on page 3-60

■ Where the physical log is located in the chapter on whatis the physical log in the Administrator’s Guide

■ Changing the physical-log location and size inthe chapter on managing the physical log in theAdministrator’s Guide

XPS


PHYSFILE

PHYSFILE

PHYSFILE specifies the size of the physical log.

When you specify the PHYSFILE parameter in the global section of theONCONFIG file, the database server uses this value when it initializes thephysical log for each coserver. Optionally, you can specify the PHYSFILEparameter in a coserver-specific section if you want a different physical logsize for a specific coserver. ♦

onconfig.stdvalue

For Dynamic Server: 1000For Extended Parallel Server: 1500

if not present 200

units Kilobytes

range of values 200 or more


utilities ON-Monitor: Parameters, Init, Phys Log Size (IDS, UNIX)


■ Sizing the physical log in the chapter on the physical log

■ Changing the physical-log location and size in thechapter on managing the physical log

XPS


PHYSSLICE

PHYSSLICE

The PHYSSLICE parameter specifies the name of the derived dbspace ordbslice on each coserver that contains the physical log. The PHYSSLICEparameter is a global configuration parameter. You cannot specify it in thecoserver-specific section of the ONCONFIG file. To reduce disk contention,you can use this parameter to move the physical log to a dbspace other thanthe root dbspace.

Important: If you specify PHYSSLICE, the derived dbspace name for each physical-log dbspace contains a period and the coserver number. The total name, including theperiod and coserver number, must not exceed 18 characters.

onconfig.xpsvalue

rootdbs

if not present None

range of values 18 characters maximum. Valid characters are restricted todigits, letters, and the underscore.

The value must be a valid dbslice name that exists onevery coserver.

takes effect When shared memory is initialized (destroys all data)

refer to Setting the global configuration parameters in the chapteron installing and configuring the database server in theAdministrator’s Guide

XPS


PLAN_MONITORING

PLAN_MONITORING

You can use the Query Monitor on a Windows NT console to view a queryplan or to monitor database server performance. The Plan Monitoring Infra-structure (PMI) gathers the data that the Query Monitor displays.

Use the PLAN_MONITORING configuration parameter to turn the PlanMonitoring Infrastructure (PMI) on or off.

RA_PAGES

onconfig.stdvalue

1

if not present 0

range of values 0 if Plan Monitoring is off1 if Plan Monitoring is on

takes effect When the database server is restarted


onconfig.stdvalue

None

if not present 4 if MULTIPROCESSOR is 0;8 if MULTIPROCESSOR is 1

units Number of data pages

range of values RA_THRESHOLD through BUFFERS


utilities ON-Monitor: Parameters, perFormance, Num of ReadAhead Pages (IDS, UNIX)

XPS


RA_THRESHOLD

RA_PAGES specifies the number of disk pages to attempt to read aheadduring sequential scans of data records. Read-ahead can greatly speed updatabase processing by compensating for the slowness of I/O processingrelative to the speed of CPU processing.

This parameter works with the RA_THRESHOLD parameter. Specifyingvalues that are too large can result in excessive buffer-caching activity.

RA_THRESHOLD



■ Calculating RA_PAGES and RA_THRESHOLD in yourPerformance Guide

onconfig.stdvalue

None

if not present RA_PAGES/2

units Number of data pages

range of values 0 through (RA_PAGES - 1)


utilities ON-Monitor: Parameters, perFormance, Read AheadThreshold (IDS, UNIX)



■ Calculating RA_PAGES and RA_THRESHOLD in yourPerformance Guide


RESIDENT

RA_THRESHOLD is used with RA_PAGES when the database server readsduring sequential scans of data records. RA_THRESHOLD specifies the read-ahead threshold; that is, the number of unprocessed data pages in memorythat signals the database server to perform the next read-ahead.

If the value of RA_THRESHOLD is greater than the value of RA_PAGES,RA_THRESHOLD has a value of RA_PAGES/2.

Specifying values that are too large for RA_PAGES and RA_THRESHOLD canresult in excessive buffer-caching activity.

RESIDENTonconfig.std

value0

range of values 0 = Off-1 = Keep all resident and virtual segments resident.

number, where number > 0 = Keep number segmentsresident.

For Dynamic Server:1 = Keep resident portion of shared-memory resident.

if not present 0


utilities onmodeON-Monitor: Parameters, Shared-Memory, ForcedResidency (IDS, UNIX)

refer to The following topics in the Administrator’s Guide for adiscussion of residency:

■ Resident portion of shared memory in the shared-memory chapter

■ Setting database server shared-memory configurationparameters in the chapter on managing shared memory


RESTARTABLE_RESTORE

The RESIDENT parameter specifies whether resident and virtual segments ofshared memory remain resident in operating-system physical memory.

For information about using onmode, see “Change Shared-MemoryResidency” on page 3-43.

Some systems allow you to specify that the resident portion of sharedmemory must stay (be resident) in memory at all times. If your operatingsystem supports forced residency, you can specify that resident and virtualsegments of shared memory not be swapped to disk.

Warning: Before you decide to enforce residency, verify that the amount of physicalmemory available after satisfying the database server requirements is sufficient toexecute all required operating-system and application processes.

RESTARTABLE_RESTORE

If you set RESTARTABLE_RESTORE to ON, you enable the database server torestart a failed physical or warm logical restore at the point at which thefailure occurred. To perform a restartable restore with ON-Bar, use theonbar -RESTART command.

Increase the size of your physical log if you plan to use restartable restore. Formore information, see “PHYSFILE” on page 1-118. Although a restartablerestore slows down the logical restore if many logs need to be restored, yousave a lot of time from not having to repeat the entire restore.

Important: If the database server fails in the middle of a cold logical restore, you mustrepeat the entire restore.

onconfig.stdvalue

OFF

range of values OFF = Restartable restore is disabled.ON = Restartable restore is enabled.


refer to Backup and Restore Guide

IDS


ROOTNAME

The database server uses physical recovery and logical recovery to restoredata as follows:

■ Physical recovery. The database server writes dbspace pages fromthe backup media to disk. This action leaves the dbspace consistentto the point in time at which it was originally backed up. However,the point in time is different for each dbspace that the database servermanages because the backup times are usually different. Arestartable restore is restartable to the level of a dbspace. If only somechunks of a dbspace are restored when the restore fails, the entiredbspace needs to be recovered again when you restart the restore.

■ Logical recovery. The database server replays logical-log records onmedia to bring data in all of the dbspaces up to date. At the end oflogical recovery, all dbspaces are consistent to the same point in time.

ROOTNAMEonconfig.std

valuerootdbs

units A dbspace

range of values For Dynamic Server: Up to 128 characters. ROOTNAMEmust begin with a letter or underscore and must containonly letters, numbers, underscores, or $ characters.

For Extended Parallel Server: Up to 18 lowercasecharacters. ROOTNAME must be unique, begin with aletter or underscore, and contain only letters, numbers, orunderscores.

takes effect When disk is initialized (destroys all data)

utilities ON-Monitor: Parameters, Initialize, Root Name (IDS,UNIX)

refer to Allocating disk space in the chapter on managing diskspace in the Administrator’s Guide


ROOTOFFSET

ROOTNAME specifies a name for the root dbspace for this database serverconfiguration.

The name must be unique among all dbspaces that the database servermanages. Informix recommends that you select a name that is easilyrecognizable as the root dbspace.

In Extended Parallel Server, the ROOTNAME parameter specifies a name forthe root dbspace of a particular coserver. The ROOTNAME parameter is partof the coserver-specific section of the ONCONFIG file.

The database server generates the root dbspace name when you use theROOTSLICE global configuration parameter. If you use the ROOTSLICEparameter, the generated rootnames are in the following format, where n isthe coserver number:

rootslicename.n

Tip: Because single global values are easier to define and manage, Informix recom-mends that you use the global configuration parameter ROOTSLICE rather than thecoserver-specific ROOTNAME parameter. ♦

ROOTOFFSET

ROOTOFFSET specifies the offset into an allocation of disk space (file, diskpartition, or device) at which the initial chunk of the root dbspace begins.

onconfig.stdvalue

0

units Kilobytes



utilities ON-Monitor: Parameters, Initialize, Offset (follows RootSize) (IDS, UNIX)

refer to Allocating raw disk space on UNIX in the chapter onmanaging disk space in the Administrator’s Guide

XPS


ROOTPATH

On some UNIX platforms, it is not valid to set ROOTOFFSET to 0. When thisparameter is set incorrectly, you must reinitialize disk space and reload datato resume proper operation of the database server. Before you configure thedatabase server, always check your machine notes file for information aboutproper settings. ♦

In Extended Parallel Server, the ROOTOFFSET parameter is optionally part ofthe coserver-specific section of the ONCONFIG file to override the value thatis given in the global section of the ONCONFIG file. ♦

ROOTPATH

ROOTPATH specifies the full pathname, including the device or filename, ofthe initial chunk of the root dbspace. ROOTPATH is stored in the reservedpages as a chunk name.

On UNIX, you must set the permissions of the file that ROOTPATH specifies to660, and the owner and group must both be informix. On Windows NT, amember of the Informix-Admin group must own the file that ROOTPATHspecifies.

onconfig.stdvalue

On UNIX: /dev/online_rootOn Windows NT: None

onconfig.value

On UNIX: /dev/online_root.%cOn Windows NT: None



utilities ON-Monitor: Parameters, Initialize, Primary Path (IDS,UNIX)

refer to Allocating disk space in the chapter on managing diskspace in the Administrator’s Guide

UNIX

XPS


ROOTSIZE

If you use unbuffered disk space for your initial chunk on UNIX, Informixrecommends that you define ROOTPATH as a pathname that is a link to theinitial chunk of the root dbspace instead of entering the actual device namefor the initial chunk. For a rationale for using links rather than device names,refer to creating links to each raw device in the chapter on managing diskspace in the Administrator’s Guide. ♦

In Extended Parallel Server, the ROOTPATH parameter specifies the fullpathname, including the device or filename, of the initial chunk of the rootdbspace on each coserver. You can list this parameter in the global section ofyour ONCONFIG file and use the following formatting characters to apply theROOTPATH parameter to all coservers.

ROOTSIZE

FormattingCharacter Description

%c Replaced with the specific coserver number.

%n Replaced with the specific node name.

♦

onconfig.stdvalue

For Dynamic Server: 30,000For Extended Parallel Server: 20,000

if not present 0

units Kilobytes

range of values 0 through maximum capacity of the storage device


UNIX utilities ON-Monitor: Parameters, Initialize, Root Size (IDS, UNIX)

refer to Calculating the size of the root dbspace in the chapter onwhere is data stored in the Administrator’s Guide

UNIX

XPS


ROOTSLICE

ROOTSIZE specifies the size of the initial chunk of the root dbspace, expressedin kilobytes. The size that you select depends on your immediate plans foryour database server.

To change ROOTSIZE after you initialize the database server, completelyunload and reload your data.

In Extended Parallel Server, the ROOTSIZE parameter is optionally part of thecoserver-specific section of the ONCONFIG file to override the value that isgiven in the global section of the ONCONFIG file. ♦

ROOTSLICE

The ROOTSLICE parameter specifies a name for the root dbslice. TheROOTSLICE parameter is a global configuration parameter. You cannotspecify it in the coserver-specific section of the ONCONFIG file.

The name must be unique among all dbspaces that the database servermanages. Informix recommends that you select a name that is easilyrecognizable as the root dbslice.

If you specify ROOTSLICE, the database server derives a dbspace name for theroot dbspace on each coserver. This dbspace name has the following format,where n is the coserver identification number:

rootslicename.n

onconfig.xpsvalue

rootdbs

if not present None

range of values 18 characters


refer to The following material in the Administrator’s Guide:

■ Chapter on managing disk space

■ Setting the global configuration parameters in theconfiguration-parameter chapter

XPS

XPS


SBSPACENAME

The name cannot exceed 18 characters. Valid characters are restricted todigits, letters, and the underscore character. If the dbspace name is derived,it can include a period.

Important: If you specify ROOTSLICE, the derived dbspace name for each rootdbspace contains a period and the coserver number. The total name, including theperiod and coserver number, must not exceed 18 characters.

SBSPACENAME

SBSPACENAME specifies the name of the system default sbspace. Unless youspecify an sbspace name when you create a table that contains a column forsmart large objects (CLOB or BLOB data type), the database server stores it inthe default sbspace.

onconfig.stdvalue

None

if not present 0

range of values Up to 128 characters. SBSPACENAME must be unique,begin with a letter or underscore, and contain only letters,digits, underscores, or $ characters.

takes effect When shared memory is reinitialized

utilities ON-Monitor: Parameters, Initialize, Root Size (IDS, UNIX)onspaces


■ What is an sbspace in the chapter on where data isstored in the Administrator’s Guide

■ Altering sbspace characteristics in the chapter onmanaging data on disk in the Administrator’s Guide

■ CREATE TABLE and ALTER TABLE statements in theInformix Guide to SQL: Syntax

IDS


SENDEPDS

Informix recommends that users create their own sbspace (with the onspacesutility) and specify the sbspace or sbspaces in the PUT clause of the CREATETABLE and ALTER TABLE statements.

Even though you specify a default sbspace with the SBSPACENAMEparameter, you must create the sbspace with the -c -S option of the onspacesutility before you can use it. The database server does not validate the nameof the default sbspace until one of the following occurrences:

■ You specify the default sbspace as the storage option for a CLOB orBLOB column in a CREATE TABLE statement.

■ The database server attempts to write a smart large object to thedefault sbspace when no sbspace was specified for the column.

For information about sbspaces, refer to “Sbspace Structure” on page 7-40.For information about assigning a smart large object to an sbspace, refer tothe CREATE TABLE and ALTER TABLE statements in the Informix Guide to SQL:Syntax. For information about using onspaces, refer to “Create an Sbspace”on page 3-68.

SENDEPDS

SENDEPDS specifies the number of send endpoints per CPU virtual processorwhen you configure communications buffers to send and receive databetween coservers. The default value of SENDEPDS is 5.

onconfig.stdvalue

None

units Number of send endpoints per CPU VP



refer to “ASYNCRQT” on page 1-26“XMF Configuration Parameters” on page 1-156

XPS


SERVERNUM

You should not need to change the value of SENDEPDS unless your XMF(Extended Messaging Facility) statistics report a large number of retransmis-sions with a small number of duplicate packets received, indicating thatpackets are being transmitted but are not arriving at the remote destination.In this case, you can increase the value of SENDEPDS. However, keep in mindthat more send endpoints consume more system resources.

SERVERNUM

SERVERNUM specifies a relative location in shared memory. The value thatyou choose must be unique for each database server on your local computer.The value does not need to be unique on your network. Because the value 0is included in the onconfig.std file, Informix suggests that you choose a valueother than 0 to avoid inadvertent duplication of SERVERNUM.

onconfig.stdvalue

0



utilities ON-Monitor: Parameters, Shared-Memory, ServerNumber (IDS, UNIX)

refer to Role of the SERVERNUM configuration parameter in themultiple-residency chapter of the Administrator’s Guide


SHMADD

SHMADD

SHMADD specifies the size of a segment that is dynamically added to thevirtual portion of shared memory.

It is more efficient to add memory in large segments, but wasteful if theadded memory is not used. Also, the operating system might require you toadd memory in a few large segments rather than many small segments.

Informix recommends the following guidelines for setting the initial value ofSHMADD.

onconfig.stdvalue

8192

range of values For Dynamic Server: 1024 through 524,288

For Extended Parallel Server: 1024 through 524,288 on 32-bit platforms and 1024 through 4 gigabytes on 64-bitplatforms

units Kilobytes


utilities ON-Monitor: Parameters, Shared-Memory, Add Seg Size(IDS, UNIX)

refer to Virtual portion of shared memory in the shared-memorychapter of the Administrator’s Guide

Amount of Physical MemoryRecommendedSHMADD Value

Less than 256 megabytes 8192

Greater than 256 megabytes and less than 512 megabytes 16,384

Greater than 512 megabytes 32,768


SHMBASE

The following command displays the size of memory segments and theamount of memory that is used or free in each:

onstat -g seg

SHMBASE

SHMBASE specifies the base address where shared memory is attached to thememory space of a virtual processor. Do not change the value of SHMBASE.The onconfig.std value for SHMBASE is platform dependent.

ON-Monitor does not prompt for this value during initialization. ♦

onconfig.stdvalue

On UNIX: Platform dependentOn Windows NT: 0xC000000L

units Address



refer to Setting operating-system shared-memory configurationparameters in the chapter on managing shared memoryin the Administrator’s Guide

IDS

UNIX


SHMTOTAL

SHMTOTAL

SHMTOTAL specifies the total amount of shared memory (resident, virtual,communications, and virtual extension portions) to be used by the databaseserver for all memory allocations. The onconfig.std value of 0 implies that nolimit on memory allocation is stipulated.

SHMTOTAL enables you to limit the demand for memory that the databaseserver can place on your system. However, applications might fail if thedatabase server requires more memory than the limit imposed bySHMTOTAL. When this situation occurs, the database server writes thefollowing message in the message log:

size of resident + virtual segments xx + yy > zz total allowedby configuration parameter SHMTOTAL

This message includes the following values.

onconfig.stdvalue

0

units Kilobytes



utilities ON-Monitor: Parameters, Shared-Memory, Total Memory(IDS, UNIX)

refer to How much shared memory the database server needs inthe shared-memory chapter of the Administrator’s Guide

Value Description

xx Current size of resident segments

yy Current size of virtual segments

zz Total shared memory required


SHMVIRTSIZE

SHMVIRTSIZE

SHMVIRTSIZE specifies the initial size of a virtual shared-memory segment.Use the following algorithm to determine the size of the virtual portion ofshared memory:

fixed_overhead + shared_structures + (mncs * private_structures)

onconfig.stdvalue

For Dynamic Server: 8000 on UNIX and 8192 onWindows NT

For Extended Parallel Server: 8192

if not present If SHMADD is present: SHMADDIf SHMADD is not present: 8

units Kilobytes

range of values 32-bit platforms:Positive integer with a maximum of 2 gigabytes.

64-bit platforms:Positive integer with a maximum value of 4 gigabytes.The maximum value might be less on some 64-bitplatforms due to operating-system limitations. For theactual maximum value for your UNIX platform, see themachine notes.


utilities ON-Monitor: Parameters, Shared-Memory, Non Res. SegSize (IDS, UNIX)


■ Virtual portion of shared memory in the shared-memory chapter of the Administrator’s Guide

■ Chapter on configuration effects on memory utilizationin your Performance Guide


SINGLE_CPU_VP

This algorithm includes the following values.

If messages in the message file indicate that the database server is addingsegments to the virtual portion of shared memory for you, add the amountthat these messages indicate to the value of SHMVIRTSIZE. Informix recom-mends that you initially create a virtual portion of shared memory of a sizethat is more than sufficient for your daily processing, if possible.

Then use the following command to determine peak usage and lower thevalue of SHMVIRTSIZE accordingly:

% onstat -g seg

SINGLE_CPU_VP

Value Description

fixed_overhead Global pool + thread pool after booting (partially dependent on the number ofvirtual processors)

shared_structures AIO vectors + sort memory + dbspace backup buffers + dictionary size + size ofstored-procedure cache + histogram pool + other pools (See the onstat display.)

mncs Maximum number of concurrent sessions

private_structures Stack (generally 32 kilobytes but dependent on recursion in SPL routines andtriggers) + heap (about 30 kilobytes) + session-control-block structures

onconfig.stdvalue

0

range of values 0 = Running with multiple CPU VPsAny nonzero value = Running with one CPU VP


utilities ON-Monitor: Parameters, perFormance, Single CPU VP(IDS, UNIX)

refer to Running on a single-processor computer in the chapter onvirtual processors and threads in the Administrator’s Guide


SINGLE_CPU_VP

SINGLE_CPU_VP specifies whether or not the database server is running withonly one CPU virtual processor.

Setting SINGLE_CPU_VP to nonzero allows the database server to useoptimized code based on the knowledge that only one CPU virtual processoris running. It enables the database server to bypass many of the mutex callsthat it must use when it runs multiple CPU virtual processors.

Informix strongly recommends that you set this parameter when thedatabase server will run only one CPU virtual processor. Depending on theapplication and work load, setting this parameter can improve performanceby up to 10 percent.

If you set SINGLE_CPU_VP to nonzero and try to add a CPU virtual processor,you receive one of the following messages:

onmode: failed when trying to change the number of classname VPs by n.

onmode: failed when trying to change the number of cpu virtual processors by n.

If you set this parameter to nonzero and then attempt to bring up thedatabase server with NUMCPUVPS set to a value greater than 1, you receivethe following error message, and the database server initialization fails:

Cannot have SINGLE_CPU_VP non-zero and CPU VPs greater than 1.

Dynamic Server supports user-defined virtual-processor classes.

Important: The database server treats user-defined virtual-processor classes as ifthey were CPU virtual processors. Thus, if you set SINGLE_CPU_VP to nonzero, youcannot create any user-defined virtual-processor classes.

If you set this parameter to nonzero and then attempt to bring up thedatabase server with NUMCPUVPS or the VPCLASS cpu value for num= set toa value greater than 1, you receive the following error message, and thedatabase server initialization fails:

Cannot have SINGLE_CPU_VP non-zero and CPU VPs greater than 1.

If you set this parameter to nonzero and then attempt to bring up thedatabase server with a user-defined VPCLASS, you receive the followingerror message, and the database server initialization fails:

oninit: Cannot have SINGLE_CPU_VP non-zero and user-definedVP classes

♦

IDS


STACKSIZE

STACKSIZE

The STACKSIZE parameter specifies the stack size for the database server userthreads. The value of STACKSIZE does not have an upper limit, but setting avalue that is too large wastes virtual memory space and can cause swap-space problems.

Informix has determined that the default size of 32 kilobytes is sufficient fornonrecursive database activity. When the database server performs recursivedatabase tasks, as in some SPL routines, for example, it explicitly checks forthe possibility of stack-size overflow and automatically expands the stack.

User threads execute user-defined routines. To increase the stack size for aparticular routine, use the stack modifier on the CREATE FUNCTIONstatement. ♦

Warning: Setting the value of STACKSIZE too low can cause stack overflow, theresult of which is undefined but usually undesirable.

onconfig.stdvalue

32

units Kilobytes

range of values 32 through limit determined by the database serverconfiguration and the amount of memory available


utilities ON-Monitor: Parameters, Shared-Memory, Stack Size(kilobytes) (IDS, UNIX)


■ Stacks in the chapter on virtual processors and threadsin the Administrator’s Guide

■ CREATE FUNCTION statement in the Informix Guide toSQL: Syntax

IDS


STAGEBLOB

STAGEBLOB

Use this parameter only if you are storing TEXT or BYTE data on opticalstorage with the Optical Subsystem. This parameter has no effect on ordinaryblobspaces or sbspaces.

STAGEBLOB is the blobspace name for the area where the Optical Subsystemstages TEXT and BYTE data that is destined for storage on optical disk.

STMT_CACHE

onconfig.stdvalue

None

range of values Up to 128 characters. STAGEBLOB must be unique, beginwith a letter or underscore, and contain only digits,letters, underscores, or $ characters.


utilities ON-Monitor: Parameters, Initialize, Stage Blob (UNIX)

refer to Guide to the Optical Subsystem

onconfig.stdvalue

0

range of values 0, 1, or 2


utilities None


IDS

IDS


STMT_CACHE_SIZE

STMT_CACHE determines whether the database server uses the SQLstatement cache. The following table describes the possible values.

STMT_CACHE_SIZE

The STMT_CACHE_SIZE configuration parameter specifies the size of the SQLstatement cache in kilobytes.

Possible Value Meaning

0 SQL statement cache not used

1 SQL statement cache used for sessions that set the STMT_CACHEenvironment variable to 1 or that execute the SET STATEMENTCACHE ON statement

2 SQL statement cache used unless a session turns it off by settingthe STMT_CACHE environment variable to 0 or by executing theSET STATEMENT CACHE OFF statement

onconfig.stdvalue

0

units Kilobytes

range of values Positive integer


utilities None


IDS


SYSALARMPROGRAM

SYSALARMPROGRAM

Set SYSALARMPROGRAM to the full pathname of the evidence.sh script. Thedatabase server executes evidence.sh when a database server failure occurs.Informix Technical Support uses the output from the evidence.sh script todiagnose the cause of a database server failure.

SYSSBSPACENAME

onconfig.stdvalue

On UNIX: evidence.sh (expands to$INFORMIXDIR/etc/evidence.sh)

On Windows NT: %INFORMIXDIR%\etc\evidence.bat



utilities None

refer to None

onconfig.stdvalue

None

if not present 0

range of values Up to 128 characters. SYSSBSPACENAME must be unique,begin with a letter or underscore, and contain only digits,letters, underscores, or $ characters.


utilities onspacesON-Monitor: Parameters, Initialize, Root Size (UNIX)

IDS


SYSSBSPACENAME

SYSSBSPACENAME specifies the name of the sbspace in which the databaseserver stores statistics that the UPDATE STATISTICS statement collects forcertain user-defined data types. Normally, the database server storesstatistics in the system catalog table. Because the data distributions for user-defined data types can be large, you have the option to store them in ansbspace instead of in the sysdistrib system catalog table.

Even though you specify an sbspace with the SYSSBSPACENAME parameter,you must create the sbspace with the -c -S option of the onspaces utilitybefore you can use it. The database server does not validate the name of thissbspace until one of the following occurrences:

■ The database server attempts to write data distributions of the multi-representational type to SYSSBSPACENAME when it executes theUPDATE STATISTICS statement with the MEDIUM or HIGH keywords.

■ The database server attempts to delete data distributions of themultirepresentational type to SYSSBSPACENAME when it executesthe UPDATE STATISTICS statement with the DROP DISTRIBUTIONSkeywords.

For information about sbspaces, refer to “Sbspace Structure” on page 7-40.For information about writing user-defined statistics, refer to the perfor-mance chapter in Extending Informix Dynamic Server 2000. For informationabout using onspaces, see “Create an Sbspace” on page 3-68.


■ Updating statistics in the chapter on individual queryperformance in your Performance Guide

■ Sbspace characteristics in the chapter on configurationeffects on I/O in your Performance Guide

■ Performance chapter in Extending Informix DynamicServer 2000


TAPEBLK

TAPEBLK

TAPEBLK specifies the block size of the device to which ontape writes duringa dbspace backup. TAPEBLK also specifies the default block size of the deviceto which data is loaded or unloaded when you use onload or onunload. Ifyou are using onload or onunload, you can specify a different block size onthe command line.

The database server does not check the tape device when you specify theblock size. Verify that the TAPEBLK tape device can read the block size thatyou specify. If not, you might not able to read from the tape.


You can use the commands in the table in “System Page Size” on page 1-79 todisplay the system page size.

onconfig.stdvalue

16

units Kilobytes

range of values Values greater than page size/1024

takes effect For ontape: When you execute ontapeFor onload and onunload: When shared memory isinitialized

utilities ON-Monitor: Parameters, Initialize, Block Size (followsTape Dev) (UNIX)

refer to Informix Migration Guide

IDS


TAPEDEV

TAPEDEV

TAPEDEV specifies the device to which ontape backs up dbspace data.TAPEDEV also specifies the default device to which data is loaded orunloaded when you use onload or onunload.

Using Symbolic Links and a Remote DeviceTAPEDEV can be a symbolic link, enabling you to switch between tapedevices without changing the pathname that TAPEDEV specifies.

You can use the following syntax to specify a tape device attached to anotherhost computer:

host_machine_name:tape_device_pathname

The following example specifies a tape device on the host computer kyoto:

kyoto:/dev/rmt01

♦

onconfig.stdvalue

On UNIX: /dev/tapedevOn Windows NT: \\.\TAPE0

if not present On UNIX: /dev/null

units Pathname


utilities ON-Monitor: Parameters, Initialize, Tape Dev (UNIX)



■ How this parameter affects onload and onunload in theInformix Migration Guide

IDS

UNIX


TAPESIZE

Verifying the Tape Block Size and Tape SizeIf you change the tape device, verify that TAPEBLK and TAPESIZE are correctfor the new device.

Rewinding Tape Devices Before Opening and on ClosingThe tape device that TAPEDEV specifies must perform a rewind before itopens and when it closes. The database server requires this action because ofa series of checks that it performs before it writes to a tape.

When the database server attempts to write to any tape other than the firsttape in a multivolume dbspace or logical-log backup, the database server firstreads the tape header to make sure that the tape is available for use. Then thedevice is closed and reopened. The database server assumes the tape wasrewound when it closed, and the database server begins to write.

Whenever the database server attempts to read a tape, it first reads the headerand looks for the correct information. The database server does not find thecorrect header information at the start of the tape if the tape device did notrewind when it closed during the write process.

TAPESIZEonconfig.std

value10,240

units Kilobytes



utilities ON-Monitor: Parameters, Initialize, Total Tape Size(follows Tape Dev) (UNIX)

refer to Informix Migration Guide

IDS


TBLSPACE_STATS

The TAPESIZE parameter specifies the size of the device to which ontapebacks up dbspace data. TAPESIZE also specifies the size of the default deviceto which data is loaded or unloaded when you use onload or onunload. Ifyou are using onload or onunload, you can specify a different tape size onthe command line.

TBLSPACE_STATS

The TBLSPACE_STATS configuration parameter turns on and off collection oftblspace statistics that the database server performs.

To turn off collection of tblspace statistics, set TBLSPACE_STATS to 0. Turningoff tablespace statistics might improve overall database server performance,but you cannot list tblspace statistics with onstat -g ppf. To turn on collectionof tablespace statistics, set TBLSPACE_STATS to 1.

TXTIMEOUT

onconfig.stdvalue

1

if not present 1

units Integer

range of values 0 or 1


onconfig.stdvalue

300

units Seconds


IDS


USEOSTIME

TXTIMEOUT specifies the amount of time that a participant in a two-phasecommit waits before it initiates participant recovery.

This parameter is used only for distributed queries that involve a remotedatabase server. Nondistributed queries do not use this parameter.

USEOSTIME

Setting USEOSTIME to 1 specifies that the database server is to use subsecondprecision when it obtains the current time from the operating system for SQLstatements. The following example shows subseconds in a DATETIME value:

1998-09-29 12:50:04.612


utilities ON-Monitor: Parameters, Shared-Memory, TransactionTimeout (UNIX)

refer to How the two-phase commit protocol handles failures inthe chapter on multiphase commit protocols in theAdministrator’s Guide

onconfig.stdvalue

0

range of values 0 = Off1 = On

takes effect During initialization

utilities ON-Monitor: Parameters, perFormance, Use OS Time(IDS, UNIX)



■ Using the CURRENT function to return a DATETIMEvalue in the Informix Guide to SQL: Syntax


VPCLASS

If subsecond precision is not needed, the database server retrieves the currenttime from the operating system once per second, making the precision oftime for client applications one second. If you set USEOSTIME to 0, theCURRENT function returns a zero (.000) for the YEAR TO FRACTION field.

When the host computer for Dynamic Server or node for Extended ParallelServer has a clock with subsecond precision, applications that depend onsubsecond accuracy for their SQL statements should set USEOSTIME to 1.

Systems that run with USEOSTIME set to nonzero notice a performancedegradation of up to 4 to 5 percent compared to running with USEOSTIMEturned off.

This setting does not affect any calls regarding the time from applicationprograms to Informix embedded-language library functions.

VPCLASSsyntax classname, options

The classname variable is required. Unlike most configu-ration parameters, VPCLASS has several option fields thatcan appear in any order, separated by commas. Youcannot use any white space in the fields. VPCLASS has thefollowing options:

num=num_VPsmax=max_VPsaff=affinitynoagenoyield

For more information about using these options, refer tothe individual discussions later in this section.

onconfig.stdvalue

None

range of values Up to 128 characters. VPCLASS must be unique, beginwith a letter or underscore, and contain only digits,letters, underscores, or $ characters.

IDS


VPCLASS

The VPCLASS parameter allows you to designate a class of virtual processors(VPs), create a user-defined VP, and specify the following information for it:

■ The number of virtual processors that the database server shouldstart initially

■ The maximum number of virtual processors allowed for this class

■ The assignment of virtual processors to CPUs if processor affinity isavailable

■ The disabling of priority aging by the operating system if theoperating system implements priority aging

You can put several VPCLASS parameter definitions in your ONCONFIG file.Each VPCLASS parameter describes one class of virtual processors. Put eachdefinition on a separate line, as in the following example:

VPCLASS cpu,num=8,aff=0-7,noageVPCLASS new,num=0


utilities None


■ User-defined classes of virtual processors in the chapteron virtual processors and threads in the Administrator’sGuide

■ Extending Informix Dynamic Server 2000

■ Creating UDRs in Java


VPCLASS

Default Values for the VPCLASS OptionsThe following table shows the defaults and value ranges for the VPCLASSparameter options.

VPCLASSoption Class Default Value Range of Values

num_VPs AIO (2 * number_of_chunks) or 6,whichever is greater, wherenumber_of_chunks is the number ofchunks allocated

1 to 10,000

num_VPs CPU 1 if MULTIPROCESSOR is 0,2 otherwise

1 to 10,000

num_VPs All otherclasses

1 1 to 10,000

max_VPs All Unlimited 1 to 10,000

affinity All VPs are assigned to availableprocessors in round-robin fashion.

Integers from 0 to(number of CPUs -1)

noage All Priority aging is in effect. noage or omitted

noyield Userdefined

Threads will yield. noyield or omitted


VPCLASS

Interaction of VPCLASS with Other ConfigurationParametersInformix suggests that you use the VPCLASS parameter instead of theAFF_SPROC, AFF_NPROCS, NOAGE, NUMCPUVPS, and NUMAIOVPS param-eters. If you use VPCLASS, you must explicitly remove other parameters fromyour ONCONFIG file. The following table shows the parameters that youmust remove.

VPCLASS NameThe first item in the VPCLASS parameter provides the name of the virtual-processor class that you are describing. The VPCLASS name is not casesensitive.

You can define new virtual-processor classes for user-defined routines orDataBlade modules, or you can set values for a predefined virtual-processorclass. The following virtual-processor classes are predefined by the databaseserver and have specific functions:

adm lio shmadt msc soccpu opt strjvp lio tlikio

The following example specifies that the database server should start threevirtual processors of the CPU class:

VPCLASS cpu,num=3

The JVP option of the VPCLASS configuration parameter sets the number ofJava virtual processors. This parameter is required when you use theInformix JDBC driver. On UNIX, you must define multiple Java virtualprocessors to execute Java user-defined routines in parallel. ♦

Parameter Parameter to Remove

VPCLASS cpu NUMCPUVPS, AFF_SPROC, AFF_NPROCS, NOAGE

VPCLASS user-defined SINGLE_CPU_VP

VPCLASS aio NUMAIOVPS

Java


VPCLASS

Creating a User-Defined ClassThe VPCLASS configuration parameter also allows you to create a class ofuser-defined virtual processors (VPs). A user-defined class of VPs can run ill-behaved user-defined routines (UDRs).

Warning: Execution of an ill-behaved routine in the CPU VP can cause serious inter-ference with the operation of the database server. In addition, the routine itself mightnot produce correct results.

For more information on ill-behaved UDRs, see user-defined classes of virtualprocessors in the chapter on virtual processors and threads in the Adminis-trator’s Guide.

You might want to describe a user-defined class of virtual processors to runDataBlade or user-defined routines. The following example creates the user-defined class new, for which the database server starts three virtualprocessors initially:

VPCLASS new,num=3

At a later time, you can use onmode -p to add virtual processors to the class.The following command adds three virtual processors to the new class:

onmode -p +3 new

For information about onmode -p, refer to “Add or Remove VirtualProcessors” on page 3-49.

By default, the VPCLASS parameter defines a yielding VP class, which allowsthe C UDR to yield to other threads that need access to the user-defined VPclass. A UDR can perform blocking I/O calls if it executes in a yielding user-defined VP. However, it must still yield for other threads to have access to theVP.

You can also define nonyielding user-defined VPs with the noyield option ofVPCLASS. For more information, refer to “Using the noyield Option” onpage 1-155.


VPCLASS

When you create a user-defined routine or function, you use the CLASSparameter of the CREATE FUNCTION statement to assign it to a class of virtualprocessors. When you create a class user-defined virtual processor to runuser-defined routines, you must ensure that the name of the class agrees withthe name that you assigned in the CREATE FUNCTION statement. For moreinformation on how to assign a user-defined routine to either CPU or user-defined classes of virtual processors, refer to the DataBlade API Programmer’sManual. For more information on the syntax of the CREATE FUNCTION orCREATE PROCEDURE statement, refer to the Informix Guide to SQL: Syntax.

Tip: You can use the CREATE FUNCTION statement to create routines or functionsthat reference any user-defined class you want, and that class need not exist when thefunction is created. However, if you try to use a function that refers to a user-definedclass, that class must exist and have virtual processors assigned to it. If the class doesnot have any virtual processors, you receive an SQL error.

For more information on user-defined routines, refer to Extending InformixDynamic Server 2000.

Using the num_VPs OptionThe num_VPs option sets the number of virtual processors of the specifiedclass that the database server should start during initialization.

On a single-processor computer, allocate only one CPU virtual processor. Ona multiprocessor computer, do not allocate more CPU and user-definedvirtual processors, combined, than there are CPUs on the computer.

Use the following syntax to specify the number of virtual processors:

num=num_VPs

For example, the following parameter specifies that the database servershould start four virtual processors for the cpu class:

VPCLASS cpu,num=4

At a later time, you can use the onmode -p command to add virtualprocessors for the class. For information about onmode -p, refer to “Add orRemove Virtual Processors” on page 3-49.


VPCLASS

Using the max_VPs OptionThe max_VPs option specifies the maximum number of virtual processorsthat the database server can start for the class.

Use the following syntax to specify the number of virtual processors:

max=max_VPs

The value can be any integer greater than 0. If you omit the max_VPs option,the number is unlimited.

Using the affinity OptionOn multiprocessor computers that support processor affinity, the affinityoption specifies the CPUs to which the database server binds virtualprocessors.

The affinity option has the following two forms:

aff=processor_numberaff=start_range,end_range

In the first form, the database server binds all virtual processors in the classto the CPU numbered processor_number. (On a multiprocessor system, theoperating system numbers the CPUs from 0 to (number of CPUs-1)). In thesecond form, the database server assigns the virtual processors of the class toprocessors in the range start_range to end_range, inclusive. The valueend_range must be larger than start_range, and all values must be less than thetotal number of available CPUs.

For example, if your platform has eight CPUs, your ONCONFIG file mightinclude the following VPCLASS entries:

VPCLASS first,aff=3VPCLASS second,num=3,aff=5-7VPCLASS cpu,num=8,aff=0-7,noage

For more information about using processor affinity, refer to the chapter onvirtual processors and threads in the Administrator’s Guide.


VPCLASS

Using the noyield OptionThe noyield option specifies creation of a nonyielding user-defined VP class.A nonyielding user-defined VP class executes a user-defined routine in a waythat gives the routine exclusive use of the virtual-processor class. In otherwords, user-defined routines that use a noyield virtual-processor class runserially. They never yield the VP to another thread.

You do not need to specify more than one VP in a nonyielding user-definedVP class because the UDR runs on a single VP until it completes and anyadditional virtual processors would be idle.

Important: If your UDR uses global variables, you must have only one VP in theuser-defined virtual-processor class to be nonyielding.

The following example specifies a user-defined class of virtual processorscalled new_noyield, which runs in no-yield mode:

VPCLASS new_noyield,noyield,num=1

The noyield option applies only to user-defined VP classes. The databaseserver ignores noyield if it is part of a VPCLASS parameter that defines apredefined VP class such as CPU, AIO, and so on.

For more information, see the following sections in the chapter on virtualprocessors and threads in the Administrator’s Guide:

■ Specifying user-defined classes of virtual processors

■ Specifying a nonyielding user-defined virtual processor (noyieldoption)


XMF Configuration Parameters

XMF Configuration ParametersThe Extended Message Facility (XMF) component manages communicationbetween the current coserver and all other coservers of Extended ParallelServer.

Depending on the size of the data to transfer to another coserver, the XMFchooses the appropriate buffer (SBUFFER, LBUFFER, or HBUFFER) to use. TheXMF configuration parameters are used to set the buffer size on each coserver.In general, you should not change the default values of these configurationparameters.

For more information about XMF, refer to the chapter on monitoring dataflow between coservers in your Performance Guide.

Configuration Parameter Description

ASYNCRQT Specifies the number of outstanding receive requestsused for each large endpoint on a coserver when youconfigure large communications buffers to send andreceive data between coservers. See “ASYNCRQT” onpage 1-26.

HBUFFER Sets the huge buffer size. The default value forHBUFFER is 48 kilobytes.

LBUFFER Sets the large buffer size. The default value forLBUFFER is 8 kilobytes.

SBUFFER Sets the small buffer size. The default value forSBUFFER is 1 kilobyte.

SENDEPDS Specifies the number of send endpoints per CPUvirtual processor when you configure communica-tions buffers to send and receive data betweencoservers. See “SENDEPDS” on page 1-130.

XPS


2Chapter

The sysmaster Database

In This Chapter . . . . . . . . . . . . . . . . . . . . 2-3

The sysmaster Database . . . . . . . . . . . . . . . . . 2-3The buildsmi Script . . . . . . . . . . . . . . . . . 2-5The bldutil.sh Script . . . . . . . . . . . . . . . . . 2-5

The System-Monitoring Interface . . . . . . . . . . . . . . 2-6Understanding the SMI Tables . . . . . . . . . . . . . 2-6Accessing SMI Tables. . . . . . . . . . . . . . . . . 2-7

SELECT Statements . . . . . . . . . . . . . . . . 2-7Triggers and Event Alarms . . . . . . . . . . . . . 2-7SPL and SMI Tables . . . . . . . . . . . . . . . . 2-8Locking and SMI Tables . . . . . . . . . . . . . . 2-8

The System-Monitoring Interface Tables . . . . . . . . . . . 2-8The sysutils Tables. . . . . . . . . . . . . . . . . . 2-10Backup Scheduler Tables . . . . . . . . . . . . . . . 2-10sysadtinfo . . . . . . . . . . . . . . . . . . . . 2-11sysaudit . . . . . . . . . . . . . . . . . . . . . 2-12syschkio . . . . . . . . . . . . . . . . . . . . . 2-13syschunks . . . . . . . . . . . . . . . . . . . . 2-13sysconfig . . . . . . . . . . . . . . . . . . . . . 2-15sysdatabases. . . . . . . . . . . . . . . . . . . . 2-16sysdbslocale . . . . . . . . . . . . . . . . . . . . 2-17sysdbspaces . . . . . . . . . . . . . . . . . . . . 2-17sysdri . . . . . . . . . . . . . . . . . . . . . . 2-19sysextents. . . . . . . . . . . . . . . . . . . . . 2-20sysextspaces . . . . . . . . . . . . . . . . . . . . 2-20syslocks . . . . . . . . . . . . . . . . . . . . . 2-21syslogs. . . . . . . . . . . . . . . . . . . . . . 2-22

2-2 Infor

sysprofile . . . . . . . . . . . . . . . . . . . . . 2-23sysptprof . . . . . . . . . . . . . . . . . . . . . 2-25syssesprof . . . . . . . . . . . . . . . . . . . . . 2-26syssessions . . . . . . . . . . . . . . . . . . . . 2-28sysseswts . . . . . . . . . . . . . . . . . . . . . 2-30systabnames . . . . . . . . . . . . . . . . . . . . 2-31sysvpprof . . . . . . . . . . . . . . . . . . . . . 2-32syscogroups . . . . . . . . . . . . . . . . . . . . 2-33syscogroupmembers . . . . . . . . . . . . . . . . . 2-33

The SMI Tables Map . . . . . . . . . . . . . . . . . . 2-34

Information from onstat in the SMI Tables . . . . . . . . . . . 2-37


In This ChapterThis chapter describes the sysmaster database and contains reference infor-mation for the system-monitoring interface (SMI). It provides information onthe following topics:

■ What is the sysmaster database

■ How to use SMI tables

■ Descriptions of the SMI tables

■ A map of the documented SMI tables

The sysmaster database also contains information about ON-Archive catalogtables. For information about ON-Archive, see your Archive and BackupGuide. ♦

For information about the ON-Bar tables, see the Backup and Restore Guide.

The sysmaster DatabaseThe database server creates and maintains the sysmaster database. It isanalogous to the system catalog for databases, which is described in theInformix Guide to SQL: Reference. Just as a system catalog for every databasemanaged by the database server keeps track of objects and privileges in thedatabase, a sysmaster database for every database server keeps track of infor-mation about the database server.

IDS

UNIX

The sysmaster Database 2-3

The sysmaster Database

The sysmaster database contains the following tables:

■ SMI tables

The system-monitoring interface tables in the sysmaster databaseprovide information about the state of the database server. You canquery these tables to identify processing bottlenecks, determineresource usage, track session or database server activity, and so on.This chapter describes these tables, which are slightly different thanordinary tables.

■ ON-Archive catalog tables

The ON-Archive catalog tables store information about ON-Archiverequests, volume sets, and save sets. Your Archive and Backup Guidedescribes these tables. ♦

Warning: The database server relies on information in the sysmaster database. Donot change any of the tables in sysmaster or any of the data within the tables. Suchchanges could cause unpredictable and debilitating results.

The database server creates the sysmaster database when it initializes diskspace. The database server creates the database with unbuffered logging. Youcannot drop the database or any of the tables in it, and you cannot turnlogging off.

As user informix on UNIX or a member of the Informix-Admin group onWindows NT, you can create SPL routines in the sysmaster database. (Youcan also create triggers on tables within sysmaster, but the database servernever executes those triggers.)

Joins of multiple tables in sysmaster might return inconsistent resultsbecause the database server does not lock the tables during a join. You canjoin sysmaster tables with tables in other databases. However, to joinsysmaster tables with tables in a nonlogging database, first make thenonlogging database the current database.

IDS

UNIX


The buildsmi Script

The buildsmi ScriptWhen you bring the database server up for the first time, it runs a scriptcalled buildsmi, which is in the etc directory. This script builds the databaseand tables that support SMI. The database server requires approximately1750 free pages of logical-log space to build the sysmaster database.

Extended Parallel Server usually requires 1100 free pages to build thesysmaster database. However, the actual number of free pages for sysmasterdepends on the configurable page size. ♦

If you receive an error message that directs you to run the buildsmi script, aproblem probably occurred while the database server was building the SMIdatabase, tables, and views. When you use buildsmi, the existing sysmasterdatabase is dropped and then re-created.

If you have information in the ON-Archive catalog tables, it will beoverwritten. ♦

The bldutil.sh ScriptWhen you initialize the database server for the first time, it runs a scriptcalled bldutil.sh on UNIX or bldutil.bat on Windows NT. This script buildsthe sysutils database. If it fails, the database server creates an output file inthe tmp directory. The output file is bldutil.process_id on UNIX andbldutil.out on Windows NT. The messages in this output file reflect errorsthat occurred during the script execution.

XPS

UNIX

IDS


The System-Monitoring Interface

The System-Monitoring InterfaceThis section describes the SMI tables and how you access them to monitor thedatabase server operation.

Understanding the SMI TablesThe system-monitoring interface consists of tables and pseudo-tables that thedatabase server maintains automatically. While the SMI tables appear to theuser as tables, they are not recorded on disk as normal tables are. Instead, thedatabase server constructs the tables in memory, on demand, based on infor-mation in shared memory at that instant. When you query an SMI table, thedatabase server reads information from these shared-memory structures.Because the database server continually updates the data in shared memory,the information that SMI provides lets you examine the current state of yourdatabase server.

The SMI tables provide information about the following topics:

■ Auditing ♦■ Disk usage

■ User profiling

■ Database-logging status

■ Tables

■ Chunks

■ Chunk I/O

■ Dbspaces

■ Locks

■ Extents

■ Virtual-processor CPU usage

■ System profiling

The data in the SMI tables changes dynamically as users access and modifydatabases that the database server manages.

IDS


Accessing SMI Tables

Accessing SMI TablesAny user can use SQL SELECT statements to query an SMI table, but standardusers cannot execute statements other than SELECT. Attempts to do so resultin permission errors. The administrator can execute SQL statements otherthan SELECT, but the results of such statements are unpredictable.

Dynamic Server provides the sysadtinfo and sysaudit tables. Only userinformix on UNIX or members of the Informix-Admin group onWindows NT can query sysadtinfo and sysaudit. ♦

You cannot use dbschema or dbexport on any of the tables in the sysmasterdatabase. If you do, the database server generates the following errormessage:

Database has pseudo tables - can't build schema

SELECT Statements

You can use SELECT statements on SMI tables wherever you can use SELECTagainst ordinary tables (from DB-Access, in an SPL routine, with ESQL/C, andso on) with one restriction: you cannot (meaningfully) reference rowid whenyou query SMI tables. SELECT statements that use rowid do not return anerror, but the results are unpredictable.

All standard SQL syntax, including joins between tables, sorting of output,and so on, works with SMI tables. For example, if you want to join an SMItable with an non-SMI table, name the SMI table with the following standardsyntax:

sysmaster:[@dbservername][owner.]tablename

Triggers and Event Alarms

Triggers based on changes to SMI tables never run. Although you can definetriggers on SMI tables, triggers are activated only when an INSERT, UPDATE,or DELETE statement occurs on a table. The updates to the SMI data occurwithin the database server, without the use of SQL, so a trigger on an SMItable is never activated, even though the data returned by a SELECTstatement indicates that it should be.

IDS


The System-Monitoring Interface Tables

To create an event alarm, query for a particular condition at predefinedintervals, and execute an SPL routine if the necessary conditions for the alarmare met.

SPL and SMI Tables

You can access SMI tables from within a SPL routine. When you reference SMItables, use the same syntax that you use to reference a standard table.

Locking and SMI Tables

The information in the SMI tables changes based on the database serveractivity. However, the database server does not update the information usingSQL statements. When you use SMI tables with an isolation level that locksobjects, it prevents other users from accessing the object, but it does notprevent the data from changing. In this sense, all the SMI tables have apermanent Dirty Read isolation level.

The System-Monitoring Interface TablesThe database server supports the following SMI tables.

Table Description Reference

sysadtinfo Auditing configuration information (IDS) page 2-11

sysaudit Auditing event masks (IDS) page 2-11

syschkio Chunk I/O statistics page 2-13

syschunks Chunk information page 2-13

syscogroup Cogroup information (XPS) page 2-33

syscogroupmembers Cogroup information (XPS) page 2-33

sysconfig Configuration information page 2-15

sysdatabases Database information page 2-16

(1 of 2)


The System-Monitoring Interface Tables

Many other tables in the sysmaster database are part of the system-monitoring interface but are not documented. Their schemas and columncontent can change from version to version.

sysdbslocale Locale information page 2-17

sysdbspaces Dbspace information page 2-20

sysdri Data-replication information (IDS) page 2-19

sysextents Extent-allocation information page 2-20

sysextspaces External spaces information (IDS) page 2-20

syslocks Active locks information page 2-22

syslogs Logical-log file information page 2-22

sysprofile System-profile information page 2-23

sysptprof Table information page 2-25

syssesprof Counts of various user actions page 2-26

syssessions Description of each user connected page 2-28

sysseswts User’s wait time on each of several objects page 2-30

systabnames Database, owner, and table name for thetblspace tblspace

page 2-31

sysvpprof User and system CPU used by each virtualprocessor

page 2-32

Table Description Reference

(2 of 2)


The sysutils Tables

The sysutils TablesON-Bar uses the following tables in the sysutils database. For more infor-mation, see the Backup and Restore Guide.

Backup Scheduler TablesON-Bar on Extended Parallel Server supports the following BackupScheduler tables in the sysmaster database. For more information, see theBackup and Restore Guide.

Table Description

bar_action Lists all backup and restore actions that are attemptedagainst an object, except during a cold restore. Use theinformation in this table to track backup and restorehistory.

bar_instance Writes a record to this table for each successful backup.ON-Bar might later use the information for a restoreoperation.

bar_object Describes each backup object. This table provides a list ofall storage spaces and logical logs from each databaseserver for which at least one backup attempt was made.

bar_server Lists the database servers in an installation. This table isused to ensure that backup objects are returned to theirproper places during a restore.

Table Description

sysbuobject Detailed information about backup objects that the BackupScheduler is processing

sysbuobjses Backup object name and session ID

sysbusession Session status information

sysbusm Storage-manager configuration information

sysbusmdbspace Storage manager for backing up dbspaces on a coserver

(1 of 2)

XPS


sysadtinfo

sysadtinfoThe sysadtinfo table contains information about the auditing configurationfor the database server. For more information, see your Trusted FacilityManual. You must be user informix or user root on UNIX or a member of theInformix-Admin group on Windows NT to retrieve information from thesysadtinfo table.

sysbusmlog Storage manager for backing up logical logs on a coserver

sysbusmworker Coserver where onbar-worker processes can access astorage manager

sysbuworker Detailed onbar-worker process status

Column Type Description

adtmode integer If auditing is on or off:

■ 0 for off

■ 1 for on

adterr integer Action on errors:

■ 0 to continually retry audit writes until they succeed.Processing for the thread that generated the error stops.

■ 1 to write all failed audit writes to the message log andcontinue processing.

adtsize integer Maximum size of an audit file

adtpath char(256) Directory where audit files are written

adtfile integer Number of the audit file

Table Description

(2 of 2)

IDS


sysaudit

sysauditFor each defined audit mask (that is, for each username), the sysaudit tablecontains flags that represent the database events that generate audit records.The success and failure columns represent the bitmasks that compose theaudit masks. If a bit is set in both the success the and failure columns, thecorresponding event generates an audit record whether or not the eventsucceeded.

You must be user informix or user root on UNIX or a member of theInformix-Admin group on Windows NT to retrieve information from thesysaudit table.

Use the onaudit utility to list or modify an audit mask. For information aboutonaudit and auditing, see your Trusted Facility Manual.


username char(32) Name of the mask

succ1 integer Bitmask of the audit mask for success





fail1 integer Bitmask of the audit mask for failure





IDS


syschkio

syschkioThe syschkio table provides I/O statistics for individual chunks that thedatabase server manages.

syschunksThe syschunks table describes each of the chunks that the database servermanages. In the flags and mflags columns, each bit position represents aseparate flag. Thus, it might be easier to read values in the flags and mflagscolumns if the values are returned using the HEX function.


chunknum smallint Chunk number

reads integer Number of physical reads

pagesread integer Number of pages read

writes integer Number of physical writes

pageswritten integer Number of pages written

mreads integer Number of physical reads (mirror)

mpagesread integer Number of pages read (mirror)

mwrites integer Number of physical writes (mirror)

mpageswritten integer Number of pages written (mirror)


chknum smallint Chunk number

dbsnum smallint Dbspace number

nxchknum smallint Number of the next chunk in this dbspace

chksize integer Number of pages in this chunk

offset integer Page offset of the chunk in its device or path

(1 of 3)


syschunks

nfree integer Number of free pages in the chunk

is_offline integer 1 if the chunk is off-line, 0 if not

is_recovering integer 1 if the chunk is being recovered, 0 if not

is_blobchunk integer 1 if the chunk is in a blobspace, 0 if not (IDS)

is_sbchunk integer 1 if the chunk is a sbspace, 0 if not (IDS)

is_inconsistent integer 1 if the chunk is undergoing logical restore, 0 if not

flags smallint Flags Hexadecimal Meaning

16 0x0010 Chunk is a mirroredchunk.

32 0x0020 Chunk is in off-line mode.

64 0x0040 Chunk is in on-line mode.

128 0x0080 Chunk is in recoverymode.

256 0x0100 Chunk has just beenmirrored.

512 0x0200 Chunk is part of ablobspace (IDS).

1024 0x0400 Chunk is being dropped.

2048 0x0800 Chunk is part of anoptical stageblob (IDS).

4096 0x1000 Chunk is inconsistent.

16384 0x4000 Chunk containstemporary log space,

32768 0x8000 Chunk was added duringroll forward.

fname char(256) Pathname for the file or device of this chunk


(2 of 3)


sysconfig

sysconfigThe sysconfig table describes the effective, original, and default values of theconfiguration parameters. For more information about the ONCONFIG fileand the configuration parameters, see Chapter 1, “ConfigurationParameters.”

mfname char(256) Pathname for the file or device of the mirroredchunk, if any

moffset integer Page offset of the mirrored chunk

mis_offline integer 1 if mirror is off-line, 0 if not

mis_recovering integer 1 if mirror is being recovered, 0 if not

mflags smallint Mirrored chunk flags; values and meanings are thesame as the flags column.


cf_id integer Unique numeric identifier

cf_name char(128) Configuration parameter name

cf_flags integer Reserved for future use

cf_original char(256) Value in the ONCONFIG file at boot time

cf_effective char(256) Value currently in use

cf_default char(256) Value provided by the database server if no value isspecified in the ONCONFIG file


(3 of 3)


sysdatabases

sysdatabasesThe sysdatabases table describes each database that the database servermanages.


name char(128) Database name

partnum integer The partition number (tblspace identifier) for thesystables table for the database

owner char(32) User ID of the creator of the database

created date Date created

is_logging integer 1 if logging is active, 0 if not

is_buff_log integer 1 if buffered logging, 0 if not

is_ansi integer 1 if ANSI-compliant, 0 if not

is_nls integer 1 if GLS-enabled, 0 if not

flags smallint Logging flags

0 No logging

1 Unbuffered logging

2 Buffered logging

4 ANSI-compliant database

8 Read-only database

16 Database that supports GLS

1000 Long ID support is enabled (IDS)


sysdbslocale

sysdbslocaleThe sysdbslocale table lists the locale of each database that the databaseserver manages.

sysdbspacesThe sysdbspaces table describes each of the dbspaces that the databaseserver manages. In the flags column, each bit position represents a separateflag. Thus, it might be easier to read values in the flags column if the valuesare returned using the HEX function.


dbs_dbsname char(128) Database name

dbs_collate char(32) The locale of the database


dbsnum smallint Dbspace number

name char(128) Dbspace name

owner char(32) User ID of owner of the dbspace

fchunk smallint Number of the first chunk in the dbspace

nchunks smallint Number of chunks in the dbspace

is_mirrored integer 1 if dbspace is mirrored, 0 if not

is_blobspace integer 1 if the dbspace is a blobspace, 0 if not (IDS)

is_sbspace integer 1 if the dbspace is a sbspace, 0 if not (IDS)

is_temp integer 1 if the dbspace is a temporary dbspace, 0 if not

is_skipreplay integer 1 if log replay can be skipped for this dbspace(XPS)

(1 of 2)


sysdbspaces

flags smallint Flags

1

Hexadecimal

0x0001

Meaning

Dbspace has no mirror.

2 0x0002 Dbspace uses mirroring.

4 0x0004 Dbspace mirroring isdisabled.

8 0x0008 Dbspace is newlymirrored.

16 0x0010 Space is a blobspace(IDS).

32 0x0020 Blobspace is onremovable media (IDS).

64 0x0040 Blobspace is on opticalmedia (IDS).

128 0x0080 Blobspace has beendropped (IDS).

256 0x0100 Blobspace is an opticalstageblob (IDS).

512 0x0200 Space is being recovered.

1024 0x0400 Space has been physi-cally recovered.

2048 0x0800 Space is in logicalrecovery.

32768 0x8000 Space is an sbspace (IDS).

131072 0x20000 Skip logical replay (XPS).


(2 of 2)


sysdri

sysdriThe sysdri table provides information about the high-availability data-repli-cation status of the database server.


type char(50) High-availability data replication typePossible values:

primarysecondarystandardnot initialized

state char(50) State of high-availability data replicationPossible values:

offonconnectingfailerread-only

name char(128) The name of the other database server in the high-availability data-replication pair

intvl integer The high-availability data-replication interval

timeout integer The high-availability data-replication timeout valuefor this database server

lostfound char(256) The pathname to the lost-and-found file

IDS


sysextents

sysextentsThe sysextents table provides information about extent allocation.

sysextspacesThe sysextspaces table provides information about external spaces. Indexesfor the id column and the name column allow only unique values.


dbsname char(128) Database name

tabname char(128) Table name

start integer Physical address for the extent

size integer Size of the extent, in pages


id integer External space ID

name char(128) External space name

owner char(32) External space owner

flags integer External space flags (reserved for future use)

refcnt integer External space reference count.

locsize integer Size of external space location, in bytes

location char (256) Location of external space

IDS


syslocks

syslocksThe syslocks table provides information about all the currently active locksin the database server.




rowidlk integer Real rowid, if it is an index key lock

keynum smallint Key number of index key lock

type char(4) Type of lock

B byte lock

IS Intent shared lock

S Shared lock

XS Shared key value held by a repeatable reader

U Update lock

IX Intent exclusive lock

SIX Shared intent exclusive lock

X Exclusive lock

XR Exclusive key value held by a repeatable reader

owner integer Session ID of the lock owner

waiter integer Session ID of the user waiting for the lock. If more thanone user is waiting, only the first session ID appears.


syslogs

syslogsThe syslogs table provides information about space use in logical-log files. Inthe flags column, each bit position represents a separate flag. For example, fora log file, the flags column can have flags set for both current log file andtemporary log file. Thus, it might be easier to read values in the flags columnif the values are returned using the HEX function.


number smallint Logical-log file number

uniqid integer Log-file ID

size integer Number of pages in the log file

used integer Number of pages used in the log file

is_used integer 1 if file is used, 0 if not

is_current integer 1 if file is the current file, 0 if not

is_backed_up integer 1 if file has been backed up, 0 if not

is_new integer 1 if the log has been added since the last level-0dbspace backup, 0 if not

is_archived integer 1 if file has been placed on the backup tape, 0 if not

is_temp integer 1 if the file is flagged as a temporary log file, 0 if not

flags smallint Flags Hexadecimal Meaning

1 0x01 Log file is in use.

2 0x02 File is current log file.

4 0x04 Log file has been backedup.

8 0x08 File is newly added log file.

16 0x10 Log file has been written todbspace backup media.

32 0x20 Log is a temporary log file.


sysprofile

sysprofileThe sysprofile table contains profile information about the database server.

The following table lists the events that, together with a corresponding value,make up the rows of the sysprofile table.


name char(13) Name of profiled event (See table that follows for a list ofpossible events.)

value integer Value of profiled event (See table that follows for a list ofpossible events.)

Events Profiled insysprofile Description

dskreads Number of actual reads from disk

bufreads Number of reads from shared memory

dskwrites Actual number of writes to disk

bufwrites Number of writes to shared memory

isamtot Total number of calls

isopens isopen calls

isstarts isstart calls

isreads isread calls

iswrites iswrite calls

isrewrites isrewrite calls

isdeletes isdelete calls

iscommits iscommit calls

isrollbacks isrollback calls

ovlock Overflow lock table

(1 of 3)


sysprofile

ovuser Overflow user table

ovtrans Overflow transaction table

latchwts Latch request waits

bufwts Buffer waits

lockreqs Lock requests

lockwts Lock waits

ckptwts Checkpoint waits

deadlks Deadlocks

lktouts Deadlock time-outs

numckpts Number checkpoints

plgpagewrites Physical-log pages written

plgwrites Physical-log writes

llgrecs Logical-log records

llgpagewrites Logical-log writes

llgwrites Logical-log pages written

pagreads Page reads

pagwrites Page writes

flushes Buffer-pool flushes

compress Page compresses

fgwrites Foreground writes

lruwrites Least-recently used (LRU) writes

chunkwrites Writes during a checkpoint

btradata Read-ahead data pages read through index leaf node


(2 of 3)


sysptprof

sysptprofThe sysptprof table lists information about a tblspace. Tblspaces correspondto tables.

Profile information for a table is available only when a table is open. Whenthe last user who has a table open closes it, the tblspace in shared memory isfreed, and any profile statistics are lost.

btraidx Read-ahead data pages read through index branch or rootnode

dpra Data pages read into memory with read-ahead feature

rapgs_used Read-ahead data pages that user used

seqscans Sequential scans

totalsorts Total sorts

memsorts Sorts that fit in memory

disksorts Sorts that did not fit in memory

maxsortspace Maximum disk space used by a sort




partnum integer Partition (tblspace) number

lockreqs integer Number of lock requests

lockwts integer Number of lock waits

deadlks integer Number of deadlocks

(1 of 2)


(3 of 3)


syssesprof

syssesprofThe syssesprof table lists cumulative counts of the number of occurrences ofuser actions such as writes, deletes, or commits.

lktouts integer Number of lock timeouts

isreads integer Number of isreads

iswrites integer Number of iswrites

isrewrites integer Number of isrewrites

isdeletes integer Number of isdeletes

bufreads integer Number of buffer reads

bufwrites integer Number of buffer writes

seqscans integer Number of sequential scans

pagreads integer Number of page reads

pagwrites integer Number of page writes


sid integer Session ID

lockreqs integer Number of locks requested

locksheld integer Number of locks currently held

lockwts integer Number of times waited for a lock

deadlks integer Number of deadlocks detected

lktouts smallint Number of deadlock timeouts

logrecs integer Number of logical-log records written

isreads integer Number of reads

(1 of 2)


(2 of 2)


syssesprof

iswrites integer Number of writes

isrewrites integer Number of rewrites

isdeletes integer Number of deletes

iscommits integer Number of commits

isrollbacks integer Number of rollbacks

longtxs integer Number of long transactions

bufreads integer Number of buffer reads

bufwrites integer Number of buffer writes

seqscans integer Number of sequential scans

pagreads integer Number of page reads

pagwrites integer Number of page writes

total_sorts integer Number of total sorts

dsksorts integer Number of sorts that did not fit in memory

max_sortdiskspace integer Maximum space used by a sort

logspused integer Number of bytes of logical-log space used bycurrent transaction of session

maxlogsp integer Maximum number of bytes of logical-log spaceever used by the session


(2 of 2)


syssessions

syssessionsThe syssessions table provides general information on each user connectedto the database server. In the state column, each bit position represents aseparate flag. Thus, it might be easier to read values in the state column if thevalues are returned using the HEX function.



username char(32) User ID

uid smallint User ID number

pid integer Process ID of the client

hostname char(16) Hostname of client

tty char(16) Name of the user’s stderr file

connected integer Time that user connected to the database server

feprogram char(16) Reserved for future use

pooladdr integer Session pool address

is_wlatch integer 1 if the primary thread for the session is waiting for a latch

is_wlock integer 1 if the primary thread for the session is waiting for a lock

is_wbuff integer 1 if the primary thread for the session is waiting for abuffer

is_wckpt integer 1 if the primary thread for the session is waiting for acheckpoint

is_wlogbuf integer 1 if the primary thread for the session is waiting for a logbuffer

is_wtrans integer 1 if the primary thread for the session is waiting for atransaction

is_monitor integer 1 if the session is a special monitoring process

is_incrit integer 1 if the primary thread for the session is in a criticalsection

(1 of 2)


syssessions

state integer Flags Hexadecimal Meaning

1 0x00000001 User structure in use

2 0x00000002 Waiting for a latch

4 0x00000004 Waiting for a lock

8 0x00000008 Waiting for a buffer

16 0x00000010 Waiting for a checkpoint

32 0x00000020 In a read call

64 0x00000040 Writing logical-log file tobackup tape

128 0x00000080 ON-Monitor (IDS, UNIX)

256 0x00000100 In a critical section

512 0x00000200 Special daemon

1024 0x00000400 Archiving (IDS)

2048 0x00000800 Clean up dead processes

4096 0x00001000 Waiting for write of log buffer

8192 0x00002000 Special buffer-flushing thread

16384 0x00004000 Remote database server

32768 0x00008000 Deadlock timeout used to setRS_timeout

65536 0x00010000 Regular lock timeout

262144 0x00040000 Waiting for a transaction

524288 0x00080000 Primary thread for a session

1048576 0x00100000 Thread for building indexes

2097152 0x00200000 B-tree cleaner thread


(2 of 2)


sysseswts

sysseswtsThe sysseswts table provides information on the amount of time that userswait for various database objects.



reason char(50) Description of reason for wait:

■ Unspecified

■ Buffer

■ Lock

■ Asynchronous I/O

■ Mt yield 0

■ Mt yield n

■ Mt yield

■ Checkpoint

■ Log I/O

■ Log copy

■ Condition

■ Lock mutex

■ Lockfree mutex

■ Deadlock mutex

■ LRUs mutex

■ Tblspace mutex

■ Log mutex

■ Checkpoint mutex

■ Mutex

■ Mt ready

■ Mt yield x

■ Running

(1 of 2)


systabnames

systabnamesThe systabnames table describes each table that the database servermanages.

numwaits integer Number of waits for this reason

cumtime float Cumulative time waited for this reason (in microseconds)

maxtime integer Maximum time waited during this session for this reason


partnum integer Tblspace identifier


owner char(32) User ID of owner


collate char(32) Collation associated with a database that supports GLS


(2 of 2)


sysvpprof

sysvpprofThe sysvpprof table lists user and system CPU time for each virtual processor.


vpid integer Virtual processor ID

class char(50) for IDS

char(16) for XPS

Type of virtual processor:

■ cpu

■ adm

■ lio

■ pio

■ aio

■ tli

■ soc

■ str

■ shm

■ opt

■ msc

■ adt

usercpu float Number of microseconds of user time

syscpu float Number of microseconds of system time


syscogroups

syscogroupsThe syscogroups table lists the cogroups that are currently configured onyour database server.

syscogroupmembersThe syscogroupmembers table lists the coservers that are part of eachcogroup that is currently configured on your database server.


cogroup_num smallint Cogroup number

name char(18) Cogroup name

nmembers smallint Number of cogroup members

is_clustered smallint Reserved for future use, displays 0


cogroup_num smallint Cogroup number

nmembers smallint Coserver number

XPS

XPS


The SMI Tables Map

The SMI Tables MapFigure 2-1 displays the columns in some of the SMI tables.

Figure 2-1Columns in the SMI tables

(1 of 4)

sysadtinfo (IDS)

adtmode

adterr

adtsize

adtpath

adtfile

sysaudit (IDS)

username

succ1

succ2

succ3

succ4

fail1

fail2

fail3

fail4

fail5

syschkio

chunknum

reads

pagesread

writes

pageswritten

mreads

mpagesread

mwrites

mpageswritten

syschunks

chknum

dbsnum

nxchknum

chksize

offset

nfree

is_offline

is_recovering

is_blobchunk (IDS)

is_sbchunk (IDS)

is_inconsistent

flags

fname

mfname

moffset

mis_offline

mis_recovering

mflags

sysconfig

cf_id

cf_name

cf_flags

cf_originals

cf_effective

cf_default

sysdatabases

name

partnum

owner

created

is_logging

is_buff_log

is_ansi

is_nls

flags


The SMI Tables Map

(2 of 4)

sysdbslocale

dbs_dbsname

dbs_collate

sysdbspaces

dbsnum

name

owner

fchunk

nchunks

is_mirrored

is_blobspace (IDS)

is_sbspace (IDS)

is_temp

is_skipreplay (XPS)

flags

sysdri

type

state

name

intvl

timeout

lostfound

sysextents

dbsname

tabname

start

size

sysextspaces (IDS)

id

name

owner

flags

refcnt

locsize

location

syslocks

dbsname

tabname

rowidlk

keynum

type

owner (sid)

waiter (sid)


The SMI Tables Map

(3 of 4)

syslogs

number

uniqid

size

used

is_used

is_current

is_backed_up

is_new

is_archived

is_temp

flags

sysprofile

name

value

sysptprof

dbsname

tabname

partnum

lockreqs

lockwts

deadlks

lktouts

isreads

iswrites

isrewrites

isdeletes

bufreads

bufwrites

seqscans

pagreads

pagwrites

syssesprof

sid

lockreqs

locksheld

lockwts

deadlks

lktouts

logrecs

isreads

iswrites

isrewrites

isdeletes

iscommits

isrollbacks

longtxs

bufreads

bufwrites

seqscans

pagreads

pagwrites

total_sorts

dsksorts

max_sort diskspace

logspused

maxlogsp

syssessions

sid

username

uid

pid

hostname

tty

connected

feprogram

pooladdr

is_wlatch

is_wlock

is_wbuff

is_wckpt

is_wlogbuf

is_wtrans

is_monitor

is_incrit

state


Information from onstat in the SMI Tables

Information from onstat in the SMI TablesTo obtain information provided by the onstat utility, you can use SQL toquery appropriate SMI tables. The following table indicates which SMI tablesto query to obtain the information provided by a given onstat option. Fordescriptions of the onstat options, see “onstat: Monitor Database ServerOperation” on page 3-88.

(4 of 4)

syscogroupmembers (XPS)

cogroup_num

nmembers

syscogroups (XPS)

cogroup_num

name

nmembers

is_clustered

sysseswts

sid

reason

numwaits

cumtime

maxtime

systabnames

partnum

dbsname

owner

tabname

collate

sysvpprof

vpid

class

usercpu

syscpu

onstat Option SMI Tables to Query onstat Fields Not in SMI Tables

-d sysdbspacessyschunks

addressbpages

-D sysdbspacessyschkio

-F sysprofile addressflushersnoozerstatedata

-g dri(IDS)

sysdri Last DR CKPT (id/pg)DRAUTO

-g glo sysvpprof Listing of virtual processors by class

(1 of 2)


Information from onstat in the SMI Tables

-k syslocks addresslklisttblsnum

-l syslogssysprofile

All physical-log fields (except numpagesand numwrits)All logical-log buffer fields (exceptnumrecs, numpages, and numwrits)addressbegin% used

-p sysprofile

-u syssessionssyssesprof

addresswaitnreadsnwrites

onstat Option SMI Tables to Query onstat Fields Not in SMI Tables

(2 of 2)


3Chapter

Utilities

In This Chapter . . . . . . . . . . . . . . . . . . . . 3-3

The -V Option . . . . . . . . . . . . . . . . . . . . 3-4

Multibyte Characters . . . . . . . . . . . . . . . . . . 3-4

oncheck: Check, Repair, or Display . . . . . . . . . . . . . 3-5

ondblog: Change Logging Mode . . . . . . . . . . . . . . 3-24

oninit: Initialize the Database Server . . . . . . . . . . . . . 3-26

onlog: Display Logical-Log Contents. . . . . . . . . . . . . 3-31

onmode: Change Mode and Shared Memory . . . . . . . . . . 3-37

onparams: Modify Log-Configuration Parameters . . . . . . . . 3-57

onspaces: Manage Storage Spaces . . . . . . . . . . . . . . 3-62

onstat: Monitor Database Server Operation . . . . . . . . . . 3-88

ontape: Log, Back Up, and Restore . . . . . . . . . . . . . 3-132

onutil: Check, Define, and Modify Storage Objects . . . . . . . . 3-135ALTER DBSLICE ADD DBSPACE . . . . . . . . . . . . 3-150ALTER DBSPACE . . . . . . . . . . . . . . . . . . 3-159ALTER LOGSLICE ADD LOGS . . . . . . . . . . . . . 3-167CHECK CATALOGS . . . . . . . . . . . . . . . . . 3-170CHECK DATA . . . . . . . . . . . . . . . . . . . 3-171CHECK INDEX. . . . . . . . . . . . . . . . . . . 3-174CHECK INDEX KEYS WITH DATA . . . . . . . . . . . 3-176CHECK INFO . . . . . . . . . . . . . . . . . . . 3-178CHECK LOGS . . . . . . . . . . . . . . . . . . . 3-181

3-2 Infor

CHECK RESERVED . . . . . . . . . . . . . . . . . 3-183CHECK SPACE . . . . . . . . . . . . . . . . . . . 3-186CREATE COGROUP . . . . . . . . . . . . . . . . . 3-188CREATE DBSLICE . . . . . . . . . . . . . . . . . . 3-194CREATE DBSPACE . . . . . . . . . . . . . . . . . 3-207CREATE LOGICAL LOG . . . . . . . . . . . . . . . 3-212CREATE LOGICAL LOGSLICE . . . . . . . . . . . . . 3-215DISPLAY PAGE. . . . . . . . . . . . . . . . . . . 3-217DROP COGROUP . . . . . . . . . . . . . . . . . . 3-220DROP DBSLICE . . . . . . . . . . . . . . . . . . 3-222DROP DBSPACE . . . . . . . . . . . . . . . . . . 3-223DROP LOGICAL LOG . . . . . . . . . . . . . . . . 3-224DROP LOGSLICE . . . . . . . . . . . . . . . . . . 3-226

xctl: Execute Utilities Across Coservers . . . . . . . . . . . . 3-227


In This ChapterThis chapter provides reference material for the Informix database serverutilities. These utilities allow you to perform administrative tasks directlyfrom the command line.

You can use the following utilities:

■ ondblog

■ oninit

■ onlog

■ onmode

■ onstat

Dynamic Server also provides the following utilities:

■ oncheck

■ onparams

■ onspaces

■ ontape ♦

Extended Parallel Server also provides the following utilities:

■ onutil

Use onutil instead of oncheck, onparams, and onspaces.

■ xctl

Use xctl to execute the other utilities on different coservers. For moreinformation, see “xctl: Execute Utilities Across Coservers” onpage 3-227.

■ Use ON-Bar instead of ontape to back up and restore data. ♦

IDS

XPS

Utilities 3-3

The -V Option

The database server must be on-line before you execute a utility, with thefollowing exceptions:

■ oninit

■ Some onlog options

■ Some oncheck options ♦■ onutil and xctl ♦

The -V OptionAll Informix command-line utilities allow you to use the -V option. Thisoption displays the software version number and the serial number. You usethe -V option primarily for debugging. When an Informix Technical Supportrepresentative asks for the version number, you can use -V to find theinformation.

Multibyte CharactersThe database server utilities support multibyte command-line arguments.For a complete list of the utilities that support multibyte command-linearguments, see the Informix Guide to GLS Functionality.

IDS

XPS

GLS


oncheck: C
heck, Repair, or Display
oncheck: Check, Repair, or DisplayDepending on the options that you choose, oncheck can perform thefollowing functions:

■ Check specified disk structures for inconsistencies

■ Repair indexes that are found to contain inconsistencies

■ Display information about the disk structures

For background information on the various disk structures that the databaseserver manages, see Chapter 7, “Disk Structures and Storage.”

The oncheck utility is sometimes confused with onstat. For information, seemonitoring with the onstat and oncheck utilities in the chapter on databaseserver administration in the Administrator’s Guide.

oncheck Check-and-Repair OptionsThe oncheck utility can repair the following types of structures:

■ Partition page statistics

■ Bitmap pages

■ Partition blobpages

■ Blobspace blobpages

■ Indexes

■ Sbspace pages

■ Metadata partitions

If oncheck detects inconsistencies in other structures, messages alert you tothese inconsistencies, but oncheck cannot resolve the problem. For moreinformation, see the chapter on consistency checking in the Administrator’sGuide.

IDS

Utilities 3-5

oncheck: Check, Repair, or Display

What Does Each Option Do?

As Figure 3-1 shows, the oncheck options fall into three categories: check,repair, and display. The display or print options (those prefixed with theletter p) are identical in function to the -c options, except that the -p optionsdisplay additional information about the data that is being checked as theoncheck utility executes.

In general, the -c options check for consistency and display a message on thescreen only if they find an error or inconsistency.

Any user can execute the check options. On UNIX platforms, you must beuser informix or root to display database data or initiate repair options. OnWindows NT, you must be a member of the Informix-Admin group todisplay database data or initiate repair options.

Figure 3-1 associates oncheck options with their function.

Figure 3-1oncheck Options and Their Functionk

Object Check Repair Display

Blobspace simple large objects -pB

Chunks and extents -ce -pe

Data rows, no simple largeobjects or smart large objects

-cd -pd

Data rows, simple large objectsbut no smart large objects

-cD -pD

Table with a user-definedaccess method

-cd, -cD

Index (key values) -ci, -cix -ci -y-pk -y, -pkx -y

-pk

Index (keys plus rowids) -cI, -cIw -cI -y-pK -y, -pKx -y

-pK

Index with a user-definedaccess method

-ci, -cI

Index (leaf key values) -pl -y, -plx -y -pl

(1 of 2)



Using the -y Option to Perform Repairs

Use the -y option to instruct oncheck to perform repairs automatically, as thefollowing examples show:

oncheck -cd -yoncheck -cD -yoncheck -ci -yoncheck -cI -y

If you do not use the -y option, oncheck prompts you when it encounters aninconsistency and allows you to request a repair. If you specify option -n,oncheck does not prompt you because this option instructs oncheck to notperform repairs.

Repairing Fragmented Tables

The oncheck utility cannot repair a table in a dbspace, sbspace, or externalspace.

Index (leaf keys plus rowids) -pL -y, -pLx -y -pL

Metadata for smart largeobjects

-cs, -cS -ps, -pS

Pages (by table or fragment) -pp

Pages (by chunk) -pP

Root reserved pages -cr, -cR -pr, -pR

Space usage (by tableor fragment)

-pt

Space usage (by table,with indexes)

-pT

System catalog tables -cc -pc

Object Check Repair Display

(2 of 2)

Utilities 3-7


Repairing Indexes in Sbspaces and External Spaces

The oncheck utility can repair an index in an sbspace or external space if theindex is created using an access method that supports the oncheck -y option.Although the oncheck utility does not repair fragmented indexes, user-defined access methods can repair them. For more information about theoncheck options that access methods support, see the DataBlade APIProgrammer’s Manual or the Virtual-Index Interface Programmer’s Manual.

Locking and oncheck

The oncheck utility places a shared lock on a table during the followingoperations:

■ When it checks data

■ When it checks indexes (with -ci, -cI, -pk, -pK, -pl, or -pL) and thetable uses page locking

■ When you specify the -x option with -ci, -cI, -pk, -pK, -pl, or -pL andthe table uses row locking

When no shared lock is on the table during an index check, other users canupdate rows during the check.

When the oncheck utility (without the -x option) checks an index on a tablewith row locking, it places an intent shared lock on the table. An intent sharedlock prevents another user from dropping or modifying the table during theoncheck operation. If you include the -x option, oncheck locks the table inshared mode for tables with or without row locking.

For more information about the -x option, refer to “Turning On Locking with-x” on page 3-23. For information on shared locks and intent shared locks, seethe Performance Guide.

The oncheck utility places a shared lock on system catalog tables when theyare checked. It places an exclusive lock on a table when it executes repairoptions.



Syntax

-cr

-pe

-pr

-pd

-y

-n -q

database

database

table:

owner. rowid

database

table:

owner.

-ci

-cI-pk

-pK

-pl

-pL

-pt

-pT

logical pagenum

tblspacenum

-pD

index_name#

frag_dbs,

oncheck Options (1 of 2)

x

-cD

database-cd

frag_dbs,owner.

-pB

-cR

-pR

oncheck -ce

: table

-cc

-pc

database

frag_dbs,owner.

table:

Utilities 3-9


Element Purpose Key Considerations-cc Checks system catalog tables for

the specified database.References: See “Checking System Catalog Tableswith -cc” on page 3-15.

-cd Reads all pages except simplelarge objects from the tblspace forthe specified database, table, orfragment and checks each pagefor consistency.

Also checks tables that employa user-defined access method.

Restrictions: Does not check simple or smart largeobjects.

References: See “Checking Pages with -cd and -cD”on page 3-15.

-cD Same as -cd but also reads theheader of each blobpage andchecks it for consistency.

Restrictions: Checks simple large objects but notsmart large objects.

References: See “Checking Pages with -cd and -cD”on page 3-15.

(1 of 5)

-pP chunknum logical pagenum

tblspacenum logical pagenum

oncheck

frag_dbs,owner.

-cs

sbspace.-cS

-ps

sbspace partnum pagenum-pS

-pp database table: rowid

oncheck Options (2 of 2)

-u option

(arg_string)



-ce Checks each chunk-free list andcorresponding free space and eachtblspace extent. Also checks smart-large-object extents and sbspacemetadata.

Additional Information: The oncheck process veri-fies that the extents on disk correspond to thecurrent control information that describes them.References: See “Checking the Chunk Free Listwith -ce and -pe” on page 3-17. For background in-formation, see “Next-Extent Allocation” onpage 7-19 and “Structure of the Chunk Free-ListPage” on page 7-8.

-ci Checks the ordering of key valuesand the consistency of horizontaland vertical node links for allindexes associated with thespecified table. Also checks indexesthat employ a user-defined accessmethod.

References: See “Checking Index Node Links with-ci and -cI” on page 3-17.

-cI Same as -ci but also checks thatthe key value tied to a rowid inan index is the same as the keyvalue in the row.

References:. See “Checking Index Node Links with-ci and -cI” on page 3-17.

-cr Checks each of the root dbspacereserved pages for severalconditions.

References: See “Checking Reserved Pages with -crand -cR” on page 3-18.

-cR Checks the root dbspace reservedpages, physical-log pages, andlogical-log pages.

None.

-cs Checks smart large object andsbspace metadata for an sbspace.

References: See “Checking and Displaying SbspaceInformation with -cs, -cS, -ps, -pS” on page 3-19.

-cS Checks smart large object andsbspace metadata for an sbspaceas well as extents.


sbspace Indicates optional sbspace name.If not supplied, all sbspaces arechecked.

None.

-n Indicates that no index repairshould be performed, even iferrors are detected.

Additional Information: Use with the index repairoptions (-ci, -cI, -pk, -pK, -pl, and -pL).

Element Purpose Key Considerations

(2 of 5)

Utilities 3-11


-pB Displays statistics that describethe average fullness of blobspaceblobpages in a specified table.

Additional Information: These statistics provide ameasure of storage efficiency for individual simplelarge objects in a database or table. If a table or frag-ment is not specified, statistics are displayed for theentire database.

References: See “Displaying Blobspace Statisticswith -pB” on page 3-19. For information about opti-mizing blobspace blobpage size, see the chapter onmanaging disk space in the Administrator’s Guide.

-pc Same as -cc but also displays thesystem catalog information as itchecks the system catalog tables,including extent use for each table.

None.

-pd Displays rows in hexadecimalformat.

References: See “Displaying Rows in HexadecimalFormat with -pd and -pD” on page 3-20.

-pD Displays rows in hexadecimalformat and simple-large-objectvalues stored in the tblspace orheader information for smart largeobjects stored in an sbspace sbpageand simple large objects stored in ablobspace blobpage.

References: See “Displaying Rows in HexadecimalFormat with -pd and -pD” on page 3-20.

-pe Same as -ce but also displays thechunk and tblspace extent infor-mation as it checks the chunk freelist, the corresponding free space,and each tblspace extent.

None.

-pk Same as -ci but also displays thekey values for all indexes on thespecified table as it checks them.

References: See “Displaying Index Informationwith -pk, -pK, -pl, -pL” on page 3-20.

-pK Same as -cI but also displays thekey values and rowids as it checksthem.


-pl Same as -ci but also displays thekey values. Only leaf-node indexpages are checked.


-pL Same as -cI but also displays thekey values and rowids for leaf-nodeindex pages only.


-pp Displays contents of a logical page. References: See “Displaying the Contents of aLogical Page with -pp and -pP” on page 3-21.


(3 of 5)



-pP Same as -pp but requires a chunknumber and logical page number orinternal rowid as input.

References: See “Displaying the Contents of aLogical Page with -pp and -pP” on page 3-21.

-pr Same as -cr but also displays thereserved-page information as itchecks the reserved pages.

References: See “Displaying Reserved-Page Infor-mation with -pr” on page 3-22.

-pR Same as -cR but also displays theinformation for the reserved pages,physical-log pages, and logical-logpages.

None.

-ps Checks and displays smart-large-object and sbspace metadata for ansbspace.


-pS Checks and displays smart-large-object and sbspace metadata, aswell as extents, for an sbspace.


-pt Displays tblspace information fora table or fragment.

References: See “Displaying Tblspace Informationfor a Particular Table or Fragment with -pt and -pT”on page 3-22.

-pT Same as -pt but also displaysindex-specific information andpage-allocation information bypage type (for dbspaces).

References: See “Displaying Tblspace Informationfor a Particular Table or Fragment with -pt and -pT”on page 3-22.

-q Suppresses all checking andvalidation messages.

None.

-x Places a shared lock on the tablewhen you check and print an index.

Additional information: Use with the -ci, -cI, -pk,-pK, -pl, or -pL options.

References: See “Turning On Locking with -x” onpage 3-23.

-y Repairs indexes when errors aredetected.

None.

chunknum Specifies a decimal value that youuse to indicate a particular chunk.

Restrictions: Value must be an unsigned integergreater than 0. Chunk must exist.Additional Information: Execute the -pe option tolearn which chunk numbers are associated withspecific dbspaces, blobspaces or sbspaces.

database Specifies the name of a databasethat you want to check forconsistency.

Restrictions: You cannot use oncheck to checkdatabases on remote database servers.References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax.


(4 of 5)

Utilities 3-13


frag_dbs Specifies the name of a dbspacethat contains a fragment you wantto check for consistency.

Restrictions: Dbspace must exist and contain thefragment that you want to check for consistency.References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax.

index_name Specifies the name of the index thatyou want to check for consistency.

Restrictions: Index must exist on table and indatabase specified.References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax.

logical pagenum Specifies an integer value that youuse to indicate a particular page ina tblspace.

Restrictions: Value must be an unsigned integerbetween 0 and 16,777,215, inclusive.Additional Information: Value can be expressed asan unsigned integer or hexadecimal that beginswith 0x identifier.

owner Specifies the owner of a table. Restrictions: Owner that you specify must becurrent owner of table.References: Syntax must conform to the TableName segment; see Informix Guide to SQL: Syntax.

pagenum Indicates the page number of thesbspace metadata portion to checkand display.

None.

partnum Identifies the sbspace metadatapartition to check and display.

None.

rowid Identifies the rowid of the rowwhose contents you want todisplay. The rowid is displayedas part of oncheck -pD output.

Restrictions: Value must be an unsigned integerbetween 0 and 4,277,659,295, inclusive.Additional Information: Value can be expressed asan unsigned integer or hexadecimal that beginswith 0x identifier.

sbspace Specifies the name of the sbspacethat you want to check forconsistency.

None.

table Specifies the name of the tablethat you want to check forconsistency.

Additional Information: Table exists when youexecute the utility.References: Syntax must conform to the TableName segment; see Informix Guide to SQL: Syntax.

tblspacenum Identifies the tblspace whosecontents you want to display.

Restrictions: Value must be an unsigned integerbetween 0 and 208,666,624, inclusive.Additional Information: Value can be expressed asan unsigned integer or hexadecimal that beginswith 0x identifier.


(5 of 5)



Option DescriptionsYou cannot combine oncheck option flags except as the following paragraphsdescribe.

Checking System Catalog Tables with -cc

The -cc option checks all system catalog tables for the specified database. Ifyou do not specify a database, it checks all system catalog tables for alldatabases. Before you execute oncheck, execute the SQL statement UPDATESTATISTICS to ensure that an accurate check occurs.

To check a table, oncheck compares each system catalog table to its corre-sponding entry in the tblspace tblspace. (See “Structure of the TblspaceTblspace” on page 7-9.) The -pc option performs the same checks and alsodisplays the system catalog information, including extent use, for each table.

% oncheck -cc% oncheck -cc superstores_demo

Checking Pages with -cd and -cD

The -cd option reads all pages, excluding blobpages and sbpages, from thetblspace for the specified database, table, or fragment and checks each pagefor consistency. It checks entries in the bit-map page against the pages toverify mapping.

If the database contains fragmented tables, but you do not specify a fragment,the option checks all fragments in the table. If you do not specify a table, itchecks all tables in the database. (The -pd option displays a hexadecimaldump of specified pages but does not check for consistency.)

If an index that uses an access method provided by a DataBlade modulecannot find the access method, you receive the following message:

-9845 Access method access_method_name does not exist indatabase. Ensure that the DataBlade installation wassuccessful.

Utilities 3-15


The -cD option performs checks similar to those performed when you use the-cd option, but it includes a consistency check of blobpages. The -cD optiondoes not read entire blobpages as it does standard pages. Instead, oncheckreads only the header of each blobpage and checks it for consistency. Thislimited consistency checking prevents the performance degradation thatcould occur if oncheck read each blobpage. Because oncheck does not readthe entire page, it does not compare beginning time stamps (stored in theheader) with ending time stamps (stored at the end of a blobpage).

To monitor blobspace blobpages, refer to oncheck -pB. (See “DisplayingBlobspace Statistics with -pB” on page 3-19).

The following example checks the data rows, including simple large objectsand smart large objects, in the catalog table:

% oncheck -cD superstores_demo:catalog

If oncheck finds an inconsistency, it displays a message similar to thefollowing one:

BAD PAGE 20001c:pg_addr 20001c != bp-> bf_pagenum 200045

If oncheck finds no inconsistencies, it displays a header similar to thefollowing one for each table that it checks:

TBLSPACE data check for stores_demo:informix.customer

The oncheck utility displays a header similar to the following one forfragmented tables, one per fragment:

TBLspace data check for stores_demo:informix.tab1Table fragment in DBspace db1

If you specify a single fragment, oncheck displays a single header for thatfragment.

For both the -cd and -cD options, the oncheck utility locks each table as itchecks the indexes for the table.



Checking the Chunk Free List with -ce and -pe

The -ce option checks each chunk free list and corresponding free space andeach tblspace extent. (See “Next-Extent Allocation” on page 7-19 and“Structure of the Chunk Free-List Page” on page 7-8, respectively.) Theoncheck process verifies that the extents on disk correspond to the currentcontrol information that describes them.

The -pe option performs the same checks and also displays the chunk andtblspace extent information during the check.

% oncheck -ce

The -ce and -pe options also check smart-large-object extent and metadatainformation. For information about using oncheck -ce and -pe with sbspaces,see monitoring sbspaces in the Performance Guide.

Checking Index Node Links with -ci and -cI

The -ci option checks the ordering of key values and the consistency ofhorizontal and vertical node links for all indexes associated with thespecified table. (See “Structure of B-Tree Index Pages” on page 7-27.)

If you do not specify an index, the option checks all indexes. If you do notspecify a table, the option checks all tables in the database.

If the option detects inconsistencies, it prompts you for confirmation to repairthe problem index. If you specify the -y (yes) option, indexes are automati-cally repaired. If you specify the -n (no) option, the problem is reported butnot repaired; no prompting occurs.

If oncheck does not find inconsistencies, the following message appears:

validating indexes......

The message displays the names of the indexes that oncheck is checking.

Index rebuilding can be time consuming if you use oncheck. Processing isusually faster if you use the SQL statements DROP INDEX and CREATE INDEXto drop the index and re-create it.

The -cI option performs the same checks as -ci, but it also checks that the keyvalue tied to a rowid in an index is the same as the key value in the row. Thesame -ci repair options are available with -cI.

Utilities 3-17


The following example checks all indexes on the customer table:

% oncheck -cI -n stores_demo:customer

The following example checks the index zip_ix on the customer table:

% oncheck -cI -n stores_demo:customer#zip_ix

By default, both the -ci and -cI options cause oncheck to lock each table as itchecks the indexes that belong to the table. However, you can append option-x to instruct oncheck not to place a shared lock on a table. If you use option-x with the repair option, -y, oncheck still places an exclusive lock on the tablewhen it must perform a repair action. For more information on option -x, see“Turning On Locking with -x” on page 3-23.

When you execute oncheck on an external index, the user-defined accessmethod is responsible for checking and repairing an index. If an index thatemploys a user-defined access method cannot find the access method, thedatabase server reports an error. The oncheck utility does not repair incon-sistencies in external indexes.

Checking Reserved Pages with -cr and -cR

The -cr option checks each of the root dbspace reserved pages (see “ReservedPages” on page 7-5) as follows:

■ It validates the contents of the ONCONFIG file with thePAGE_CONFIG reserved page.

■ It ensures that all chunks can be opened, that chunks do not overlap,and that chunk sizes are correct.

The following example checks each of the root dbspace reserved pages:

% oncheck -cr

The -cR option performs the same operations as the -cr option, but it alsochecks all logical-log and physical-log pages for consistency. The -cr option isconsiderably faster because it does not check the log-file pages.

If you have changed the value of a configuration parameter (either throughON-Monitor or by editing the configuration file), but you have not yet reini-tialized shared memory, oncheck -cr and oncheck -cR detect theinconsistency and return an error message.



The -pr and -pR options perform the same checks as oncheck -cr andoncheck -cR, respectively, and also display the reserved-page information asthey check the reserved pages.

If oncheck -cr does not display any error messages after you execute it,you can assume that all three items in the preceding list were checkedsuccessfully.

Checking and Displaying Sbspace Information with -cs, -cS, -ps, -pS

The -cs option checks sbspaces. The -ps option checks sbspaces and theirextents. If you do not specify the sbspace name, the option checks allsbspaces. The following example checks the sbspace test_sbspace:

% oncheck -cs test_sbspace

The -cS and -pS options validate and display metadata for an sbspace. If youdo not specify the sbspace name, the option checks all sbspaces. You canoptionally specify metadata partition and page number. The followingexample checks and displays metadata on sbpage 32 in partition 25:

% oncheck -ps test_sbspace 25 32

If you specify rootdbs as the sbspace name with the -cs or -ps options,oncheck checks the root dbspace.

For information about using oncheck -cs, -cS, -ps, and -pS with sbspaces, seemonitoring sbspaces in the Performance Guide.

Displaying Blobspace Statistics with -pB

The -pB option displays statistics that describe the average fullness ofblobspace blobpages in a specified table. These statistics provide a measureof storage efficiency for individual simple large objects in a database or table.If you do not specify a table or fragment, the option displays statistics for theentire database. (See optimizing blobspace blobpage size in the chapter onmanaging disk space in the Administrator’s Guide.)

% oncheck -pB photo_base:photos

Utilities 3-19


Displaying Rows in Hexadecimal Format with -pd and -pD

The -pd option takes a database, a table, a fragment, and a specific rowid ortblspace number and logical page number as input. In every case, -pd printspage-header information and displays the specified rows for the databaseobject (database, table, fragment, internal rowid, or page number) that youspecify in hexadecimal and ASCII format. No checks for consistency areperformed.

If you specify an internal rowid (expressed as a hexadecimal value), therowid maps to a particular page, and all rows from that page are printed.

If you specify a logical page number (expressed as a decimal), all the rows ofthe tblspace number with the logical page number are printed.

If you specify a fragment, all the rows in the fragment are printed, with theirrowids, forward pointers, and page type.

If you specify a table, all the rows in the table are printed, with their rowids,forward pointers, and page type.

If you specify a database, all the rows in all the tables in the database areprinted. TEXT and BYTE column descriptors stored in the data row areprinted, but TEXT and BYTE data itself is not.

The -pD option prints the same information as -pd. In addition, -pD printsTEXT and BYTE values stored in the tblspace or header information for simplelarge objects stored in a blobspace blobpage.

% oncheck -pd stores_demo:customer,frgmnt1% oncheck -pd stores_demo:customer% oncheck -pD stores_demo:customer 0x101

Displaying Index Information with -pk, -pK, -pl, -pL

Repair options are available for each option.

The -pk option performs the same checks as the -ci option. (See “CheckingIndex Node Links with -ci and -cI” on page 3-17.) In addition, -pk displaysthe key values for all indexes on the specified table as it checks them.

The -pK option performs the same checks as the -cI option. The -pK optiondisplays the key values and rowids as it checks them.



The -pl option performs the same checks as the -ci option and displays thekey values, but it checks only leaf-node index pages. It ignores the root andbranch-node pages. See “Structure of B-Tree Index Pages” on page 7-27.

The -pL option performs the same checks as the -cI option and displays thekey values and rowids, but it checks only leaf-node index pages. It ignoresthe root and branch-node pages.

% oncheck -pL -n stores_demo.customer

The following example displays information about all indexes on thecustomer table:

% oncheck -pl -n stores_demo:customer

The following example displays information about the index zip_ix, whichwas created on the customer table:

% oncheck -pl -n stores_demo:customer#zip_ix

Displaying the Contents of a Logical Page with -pp and -pP

The -pp option requires as input either of the following values:

■ A tblspace number and logical page number

If the table that you want to check is fragmented, you must alsosupply the name of the dbspace in which the fragment is located.

■ A table name and an Informix internal rowid

You can obtain this internal rowid with the oncheck -pD command.This internal rowid is not the serial rowid that is assigned in tablescreated with the CREATE TABLE tabname WITH ROWIDS statement.

For more information, see “Definition of Rowid” on page 7-23.

Use the -pp option to dump the contents of the logical page numbercontained in the rowid. The page contents appear in ASCII format. Thedisplay also includes the number of slot-table entries on the page.

The -pP option provides the same information as the -pp option but requiresa chunk number and logical page number as input.

% oncheck -pp stores_demo:customer,frag_dbspce1 0x211% oncheck -pp stores_demo:orders 0x211% oncheck -pP 0x100000a 25% oncheck -pP 3 15

Utilities 3-21


Displaying Reserved-Page Information with -pr

The -pr option performs the same checks as the -cr option. (For a descriptionof the -cr option, see “Checking Reserved Pages with -cr and -cR” onpage 3-18.) In addition, -pr displays the reserved-page information as itchecks the reserved pages. For a listing and explanation of oncheck -proutput, see “Reserved Pages” on page 7-5.

% oncheck -pr

If you have changed the value of a configuration parameter (either by usingON-Monitor on UNIX or by editing the ONCONFIG file), but you have not yetreinitialized shared memory, oncheck -cr detects the inconsistency, printsboth values, and displays an error message.

Displaying Tblspace Information for a Particular Table or Fragmentwith -pt and -pT

The -pt option prints a tblspace report for a given table or fragment whosename and database you specify when you execute oncheck at the commandline. The report contains general allocation information including themaximum row size, the number of keys, the number of extents, their sizes,the pages allocated and used per extent, the current serial value, and the datethat the table was created. The Extents fields list the physical address for thetblspace tblspace entry for the table and the address of the first page of thefirst extent. If you do not specify a table, the option displays this informationfor all tables in the database.

The -pT option prints the same information as the -pt option. In addition, the-pT option displays index-specific information and page-allocationinformation by page type (for dbspaces).

Output for both -pt and -pT contains listings for Number of pages used. Thevalue shown in the output for this field is never decremented because thedisk space allocated to a tblspace as part of an extent remains dedicated tothat extent even after you free space by deleting rows. (See the PerformanceGuide.) For an accurate count of the number of pages currently used, refer tothe detailed information on tblspace use (organized by page type) that the-pT option provides.

% oncheck -pT stores_demo:customer



Turning On Locking with -x

If you append the -x option to the index-checking options, oncheck places ashared lock on affected tables while it checks the indexes, meaning no otherusers can perform inserts, updates, and deletions while oncheck checks orprints the index. Without the -x option for tables with row locking, oncheckonly places an IS (intent shared) lock on the table, which prevents actionssuch as dropping the table or the indexes during the check.

You can append the -x option to the -ci, -cI, -pk, -pK, -pl, and -pL options. Forexample, the following sample command instructs oncheck to lock indexesfor the customer table while it validates the order of key values, validateshorizontal links, and ensures that no node appears twice in the index:

oncheck -cix stores_demo:customer

When you specify option -x, oncheck locks indexes for tables that use rowlocking. If oncheck detects page-lock mode, it displays a warning messageand places a shared lock on the table regardless.

Sending Special Arguments to the Access Method with -u

You can use the -u option to send special arguments to the access method.The possible arguments depend on the access method. For example, theR-tree access method supports the display option, as the following exampleshows:

oncheck -pl -u "display"

Use commas to separate multiple arguments in the argument string.

For information on valid arguments for your access method, refer to the usermanual for your access method.

Utilities 3-23


ondblog: Change Logging Mode

ondblog: Change Logging ModeThe ondblog utility lets you change the logging mode for one or moredatabases.

If you turn on transaction logging for a database, you must create a level-0backup of all the storage spaces that contain data in the database before thechange takes effect.

For more information and examples, see the following topics in the chapteron managing database-logging status in the Administrator’s Guide:

■ Modifying the database-logging status

■ Modifying table-logging status

Syntax

Element Purpose Key Considerationsbuf Sets the logging mode so that transaction

information is written to a buffer before it iswritten to a logical log.

None.

unbuf Sets the logging mode so that data is notwritten to a buffer before it is written to alogical log.

None.

nolog Sets the logging mode so that no databasetransactions are logged.

None.

(1 of 2)

buf

unbufdb_list

-f dbfile

ondblog

IDS

nolog

ansi

cancel

ondblog: Change Logging Mode

The Database option in the ON-Monitor Logical-Logs menu is similar to theseondblog command options.

For information about how to change the log mode with ON-Archive, see theArchive and Backup Guide. ♦

You can use ondblog to change the database-logging mode but not to turn offdatabase logging. Extended Parallel Server supports nonlogging tables butnot nonlogging databases. ♦

ansi Changes database logging to be ANSIcompliant.

Additional Information: Once you createor convert a database to ANSI mode, youcannot change it back to any of the otherlogging modes.

cancel Cancels the logging-mode change requestbefore the next level-0 backup occurs.

None.

-f dbfile Changes the logging status of the databasesthat are listed (one per line) in the text filewhose pathname is given by dbfile.

Additional Information: This command isuseful if the list of databases is long orused often.

db_list Names a space-delimited list of databaseswhose logging status is to be changed.

Additional Information: If you do notspecify anything, all databases that thedatabase server manages are modified.


(2 of 2)

IDS

UNIX

XPS

Utilities 3-25


oninit: Initialize the Database Server

oninit: Initialize the Database ServerExecute the oninit utility from the command line to initialize database servershared memory and bring the database server on-line. If you use oninitoptions, you can also initialize disk space.

On UNIX, you must be logged in as root or user informix to execute oninit.On Windows NT, you must be a member of the Informix-Admin group.

Before you initialize the database server, set the INFORMIXSERVERenvironment variable to the dbservername that you chose when you set theconfiguration parameter DBSERVERNAME. INFORMIXSERVER is notrequired for initialization. However, if INFORMIXSERVER is not set, thedatabase server does not build the sysmaster tables. Also, the DB-Accessutility requires INFORMIXSERVER to be set.

For information about what happens during initialization, see the chapter oninitializing the database server in the Administrator’s Guide.

On Extended Parallel Server, you can perform oninit operations on specificcoservers. Use oninit with xctl to initialize multiple coservers or to initializea coserver on a node that is different from your login node. You can also bringup the database server or coserver in microkernel mode (oninit -m). ♦

Syntax

XPS

-y

Initialize Disk Space and Shared Memory,p. 3-29

oninit

XPS

-Xcoserver_ID

Initialize Shared Memory Only,p. 3-27


Initialize Shared Memory Only

Element Purpose Key Considerations-y Causes the database server or

coserver to automaticallyrespond yes to all prompts.

None.

-Xcoserver_ID Performs the action on thecoserver that coserver_IDindicates.

Additional Information: No white space appears be-tween the -X option and the coserver_ID argument. Ifyour database server has multiple coservers, you mustinitialize each one. To initialize all coservers with asingle command, use xctl -C oninit. For more informa-tion about xctl, refer to “xctl: Execute Utilities AcrossCoservers” on page 3-227.

Element Purpose Key Considerations-p Directs oninit not to search for

(and delete) temporary tables.Additional Information: If you use this option, thedatabase server or coserver returns to on-line modemore rapidly, but space used by temporary tables left ondisk is not reclaimed.

-s Initializes shared memory andleaves the database server orcoserver (XPS) in quiescentmode. See “Initializing SharedMemory with the -s Option” onpage 3-28.

Additional Information: This option is equivalent to theON-Monitor Mode menu, Startup option (IDS, UNIX).The database server or coserver (XPS) should be inoff-line mode to initialize shared memory.

-s-p

Initialize SharedMemory Only

Utilities 3-27


Initializing Shared Memory with No Options

If you execute oninit without options, the database server is left in on-linemode after shared memory is initialized. For example, the followingcommands take the database server off-line and then reinitialize sharedmemory:

% onmode -ky% oninit

The following commands take the database server off-line and then reini-tialize shared memory on all coservers:

% onmode -ky% xctl onmode -ky

♦

Initializing Shared Memory with the -s Option

The -s option initializes shared memory and leaves the database server inquiescent mode.

The following commands take the database server off-line, reinitialize sharedmemory, and leave the database server in quiescent mode:

% onmode -ky% oninit -s

The following commands take the database server off-line, reinitialize sharedmemory on all coservers, and leave the database server in quiescent mode:

% onmode -ky% xctl -C oninit -sy

♦

The -s option is equivalent to the ON-Monitor Mode menu, Startup option. ♦

XPS

XPS

IDS

UNIX



Initialize Disk Space and Shared Memory

Warning: When you initialize disk space, the initialization destroys all data thatyour database server currently manages.

The database server must be off-line when you initialize disk space.

Specify the Number of Virtual ProcessorsUse NUMCPUVPS and NUMAIOVPS to specify the initial number of VPs forthe CPU and AIO classes. For more information about these parameters, see“NUMCPUVPS” and “NUMAIOVPS” on page 1-101.

Element Purpose Key Considerations-i Causes the database server or coserver to

initialize disk space and shared memory.Leaves the database server in on-line modeafter it initializes disk space.

None.

-m Causes the database server or coserverto come up in microkernel mode inpreparation for a cold restore.

Additional Information: For informationabout cold restores, see the Backup and RestoreGuide.

-s When used with -i, causes the databaseserver to be left in quiescent mode after diskinitialization.

None.

-s

Initialize Disk Spaceand Shared Memory

-m

-i

XPS

Utilities 3-29


The VPCLASS configuration parameter allows you to specify, for each class ofvirtual processors, the number of VPs that the database server should start oninitialization. Alternatively, you can use NUMCPUVPS and NUMAIOVPS tospecify the initial number of VPs for the CPU and AIO classes. However, youcannot use both VPCLASS and NUMCPUVPS and NUMAIOVPS in the sameconfiguration file. If your ONCONFIG file contains conflicting parameters,oninit returns one of the following messages:

oninit: Can't mix VPCLASS cpu and NUMCPUVPS, SINGLE_CPU_VP,AFF_SPROC, AFF_NPROCS, or NOAGE parameters

oninit: Can't mix VPCLASS aio and NUMAIOVPS parameters

For more information, refer to “VPCLASS” on page 1-150. ♦

IDS


onlog: Displ
ay Logical-Log Contents
onlog: Display Logical-Log ContentsThe onlog utility displays the contents of a logical-log file, either on disk oron backup.

The onlog output is useful in debugging situations when you want to tracka specific transaction or see what changes have been made to a specifictblspace. (For information about interpreting the logical-log file contents, seeChapter 6, “Interpreting Logical-Log Records.”)

Any user can run all of the onlog options except the -l option. Only userinformix on UNIX or a member of the Informix-Admin group onWindows NT can run the -l option.

If the database server is in off-line mode when you execute onlog, only thefiles on disk are read. If the database server is in quiescent or on-line mode,onlog also reads the logical-log records stored in the logical-log buffers inshared memory (after all records on disk have been read).

When the database server reads a logical-log file with status U from diskwhile in on-line mode, the database server denies all access to the logical-logfiles, effectively stopping database activity for all sessions. (For more infor-mation, see “The onstat -l Option” on page 3-113.) For this reason, Informixrecommends that you wait until the files have been backed up and then readthe contents of the logical-log files from backup.

When Extended Parallel Server is off-line, you can perform onlog operationson specific coservers. ♦

To display the contents of backups that ON-Archive created, use theLIST/LOGRECORDS command as the Archive and Backup Guide describes. ♦

XPS

IDS

UNIX

Utilities 3-31

onlog: Display Logical-Log Contents

Syntax

Read Filters

You direct onlog to read the following portions of the logical log as it searchesfor records to display:

■ Records stored on disk

■ Records stored on backup media

■ Records from the specified logical-log file

By default, onlog displays the logical-log record header, which describes thetransaction number and the record type. The record type identifies the typeof operation performed.

Element Purpose Key Considerations-q Suppresses the initial header

and the one-line header thatappears every 18 records bydefault.

None.

-X cos_number Specifies the coserver for whichto read logs.

Additional Information: The -X option works onlyif the database server is off-line. If the databaseserver is running, onlog uses the value of theINFORMIXSERVER environment variable toconnect to the database server.

XPS-q

-X cos_number

onlogLog-Record Read Filters,

page 3-34Log-Record Display Filters,

page 3-35



In addition to the header, you can use the read filters to direct onlog todisplay the following information:

■ Logical-log record header and data (including copies of simple largeobjects stored in a dbspace or tblspace)

■ Copies of blobpages from blobspaces

They are copied from the logical-log backup only. They are notavailable from disk. ♦

Display Filters

You can display every logical-log record header, or you can specify outputbased on the following criteria:

■ Records associated with a specific table

■ Records initiated by a specific user

■ Records associated with a specific transaction

If an Error Is Detected

If onlog detects an error in the log file, such as an unrecognizable log type, itdisplays the entire log page in hexadecimal format and terminates.

IDS

Utilities 3-33


Log-Record Read FiltersThe onlog utility uses the pathnames that are stored in the root dbspacereserved pages to locate the logical-log files. If you use ON-Bar to back up thelogical logs, onlog asks the storage manager to retrieve the appropriatelogical-log records from the backup media.

Element Purpose Key Considerations-b Displays logical-log records

associated with blobspaceblobpages.

Additional Information: The database server stores theserecords on the logical-log backup media as part ofblobspace logging.

-d device Names the pathname of thestorage device where thedesired logical-log backupis mounted.

Restriction: If you use ontape, the device that you namemust be the same as the pathname of the device assigned tothe configuration parameter LTAPEDEV. If the -d option isnot used, onlog reads the logical-log files stored on disk,starting with the logical-log file with the lowest logid.

Additional Information: You do not need to use the -doption if you use ON-Bar because the storage managerretrieves the logical-log records from the storage device.

References: For pathname syntax, see your operating-system documentation.

-n uniqid Directs onlog to read onlythe logical-log recordscontained in the log file thatyou specify with uniqid.

Additional Information: The uniqid is the unique IDnumber of the logical log. It marks how many times the diskspace was used for the logical log. To determine the uniqidof a particular logical-log file, use the onstat -l command.

If you do not use the -n option, onlog reads all logical-logfiles that are available (either on disk or on tape).

References: For information about the onstat utility, see“onstat: Monitor Database Server Operation” on page 3-88.

Log-RecordRead Filters

-b

-d device -n uniqid



Log-Record Display Filters

Element Purpose Key Considerations-l Displays the long listing

of the logical-log record.Additional Information: The long listing of a log recordincludes a complex hexadecimal and ASCII dump of theentire log record. The listing is not intended for casual use.

-t tblspace_num Displays recordsassociated with thetblspace that youspecify.

Restrictions: Unsigned integer. Number, greater than 0,must be in the partnum column of the systables systemcatalog table.

Additional Information: Specify this value as either aninteger or hexadecimal value. (If you do not use a 0x prefix,the value is interpreted as an integer.) To determine thetblspace number of a particular tblspace, query thesystables system catalog table as described in “TblspaceNumbers” on page 7-10.

-u username Displays records for aspecific user.

Restrictions: User name must be an existing login name.User name must conform to operating-system-specific rulesfor login name.

-x transaction_id Displays only recordsassociated with thetransaction that youspecify.

Restriction: Value must be an unsigned integer between0 and TRANSACTIONS - 1, inclusive.

Additional Information: You should need to use the -xoption only in the unlikely case that an error is generatedduring a rollforward. When this situation occurs, thedatabase server sends a message to the message log thatincludes the transaction ID of the offending transaction.You can use this transaction ID with the -x option of onlogto investigate the cause of the error.

Log-RecordDisplay Filters

- l1

-t tblspace_num1

-u username1

-x transaction_id1

Utilities 3-35


If you do not specify any options, onlog displays a short listing of all therecords in the log. You can combine options with any other options toproduce more selective filters. For example, if you use both the -u and -xoptions, onlog displays only the activities that the specified user initiatedduring the specified transaction. If you use both the -u and -t options, onlogdisplays only the activities initiated by the specified user and associated withthe specified tblspace.


onmode: Change M
ode and Shared Memory
onmode: Change Mode and Shared MemoryThe onmode flags determine which of the following operations onmodeperforms:

■ Change the database server operating mode

■ Force a checkpoint

■ Change residency of the resident and virtual portions of sharedmemory

■ Switch the logical-log file

■ Kill a database server session

■ Add a shared-memory segment to the virtual shared-memoryportion

■ Add or remove virtual processors

■ Regenerate a .infos file

■ Set decision-support parameters

■ Free unused memory segments

■ Override the WAIT mode of the ONDBSPACEDOWN configurationparameter

You can use the following onmode options:

■ The onmode -b option to change data to an earlier database serverformat

For information about migrating from or reverting to earlier versionsof the database server, see the Informix Migration Guide.

■ The onmode -d option to set data-replication types ♦

On UNIX, you must be user root or user informix to execute onmode. OnWindows NT, you must be a member of the Informix-Admin group.

IDS

Utilities 3-37

onmode: Change Mode and Shared Memory

Syntax

Force a Checkpoint, p. 3-41

IDS

Change Database Format with onmode -bSee Informix Migration Guide.

Change Usage of the SQL Statement Cache, p. 3-55

Set Data-Replication Types, p. 3-46

Kill a Distributed Transaction, p. 3-44

Change Database Server Mode, p. 3-39

Switch the Logical-Log File, p. 3-43

Kill a Database Server Session, p. 3-44

Add a Shared-Memory Segment, p. 3-48

Add or Remove Virtual Processors, p. 3-49

Regenerate .infos or .infxdirs File, p. 3-50

Change Decision-Support Parameters, p. 3-51

Free Unused Memory Segments, p. 3-53

Override ONDBSPACEDOWN WAIT Mode, p. 3-54

onmode

- y

Change Shared-Memory Residency, p. 3-43



If you do not use any options, the database server returns a usage statement.

Change Database Server Mode

Element Purpose Key Considerations-y Causes the database server to automatically respond yes

to all prompts.None.

Element Purpose Key Considerations-k Takes the database server to off-line

mode and removes shared memory.Additional Information: You might want to use thisoption to reinitialize shared memory.References: See “Taking the Database Server to Off-LineMode with the -k Option” on page 3-40.

-m Takes the database server fromquiescent to on-line mode.

References: See “Bringing the Database Server On-Linewith the -m Option” on page 3-40.

-s Shuts down the database servergracefully.

Additional Information: Users who are using thedatabase server are allowed to finish before the databaseserver comes to quiescent mode, but no new connectionsare allowed. When all processing is finished, -s takes thedatabase server to quiescent mode. The -s option leavesshared memory intact.References: See “Shutting Down the Database ServerGracefully with the -s Option” on page 3-40.

-u Shuts down the database serverimmediately.

Additional Information: This option brings the databaseserver to quiescent mode without waiting for users tofinish their sessions. Their current transactions are rolledback, and their sessions are terminated.References: See “Shutting Down the Database ServerImmediately with the -u Option” on page 3-40.

Change DatabaseServer Mode

-k

-m

-s

-u

Utilities 3-39


The following sections describe the options that take the database serverfrom one mode to another.

Taking the Database Server to Off-Line Mode with the -k Option

The -k option takes the database server to off-line mode and removesdatabase server shared memory. You might want to use this option to reini-tialize shared memory.

A prompt asks for confirmation. Another prompt asks for confirmation to killuser threads before the database server comes off-line. If you want toeliminate these prompts, execute the -y option with the -s option.

Bringing the Database Server On-Line with the -m Option

The -m option brings the database server on-line from quiescent mode.

Shutting Down the Database Server Gracefully with the -s Option

The -s option causes a graceful shutdown. Users who are using the databaseserver are allowed to finish before the database server comes to quiescentmode, but no new connections are allowed. When all processing is finished,-s takes the database server to quiescent mode. The -s option leaves sharedmemory intact.

A prompt asks for confirmation. If you want to eliminate this prompt,execute the -y option with the -s option.

Shutting Down the Database Server Immediately with the -u Option

The -u option causes immediate shutdown. This option brings the databaseserver to quiescent mode without waiting for users to finish their sessions.Their current transactions are rolled back, and their sessions are terminated.

A prompt asks for confirmation. Another prompt asks for confirmation to killuser threads before the database server comes to quiescent mode. If you wantto eliminate these prompts, execute the -y option with the -s option.



Changing Database Server Mode with ON-Monitor

You can also use ON-Monitor options to change the database server mode.The following table shows ON-Monitor options that are equivalent to theonmode options.

Force a Checkpoint

onmode Option ON-Monitor Option

-k Take-Offline

-m On-Line

-s Graceful-Shutdown

-u Immediate-Shutdown

IDS

UNIX

Force aCheckpoint

-c

block

fuzzy

unblock

IDS

Utilities 3-41


Element Purpose Key Considerations-c Forces a checkpoint that

flushes the buffers to disk.Additional Information: You can use the -c option to forcea sync checkpoint if the most recent checkpoint record inthe logical log was preventing the logical-log file from beingfreed (status U-B-L).

block Blocks the database serverfrom any transactions.

Additional Information: While the database server isblocked, users can access it in read-only mode. Use thisoption to perform an external backup on Dynamic Server.References: For more information, see the Backup andRestore Guide.

unblock Unblocks the database server. When the database server is unblocked, data transactionsand normal database server operations can resume. Usethis option after you complete an external backup onDynamic Server.References: For more information, see the Backup andRestore Guide.

fuzzy Performs a fuzzy checkpoint. Additional Information: Use the onmode -c fuzzy optionto force a fuzzy checkpoint. Then use the onstat -bcommand to check the number of modified (dirty) buffers.The modified buffers that are still in the buffer cachecontain fuzzy transactions.References: For more information, see the chapter oncheckpoints and fast recovery in the Administrator’s Guide.



Change Shared-Memory Residency

Important: Set the RESIDENT parameter to 1 before you use the onmode -r or -noptions.

For information on using the forced-residency parameter to turn residencyon or off for the next time that you reinitialize shared memory, see the chapteron managing shared memory in the Administrator’s Guide.

Switch the Logical-Log File

IDS

Element Purpose Key Considerations-n Ends forced residency of the

resident portion of sharedmemory.

Additional Information: This command does not affect thevalue of RESIDENT, the forced-residency parameter in theONCONFIG file.

-r Starts forced residency of theresident portion of sharedmemory.

Additional Information: This command does not affect thevalue of RESIDENT, the forced-memory parameter in theONCONFIG file.

Change Shared-Memory Residency

-n

-r

Switch the Logical-Log File

-l

Utilities 3-43


Kill a Database Server Session

To use the -z option, first obtain the session identification (sessid) withonstat -u, then execute onmode -z, substituting the session identificationnumber for sid.

When you use onmode -z, the database server attempts to kill the specifiedsession. If the database server is successful, it frees any resources that thesession holds. If the database server cannot free the resources, it does not killthe session.

If the session does not exit the section or release the latch, the database serveradministrator can take the database server off-line, as described in “Takingthe Database Server to Off-Line Mode with the -k Option” on page 3-40, toclose all sessions.

Element Purpose Key Considerations-l Switches the current

logical-log file to thenext logical-log file.

Additional Information: You must use onmode to switch to thenext logical-log file.References: For information on switching to the next logical-logfile, see the chapter on managing logical-log files in the Adminis-trator’s Guide.

Element Purpose Key Considerations-z sid Kills the session that

you specify in sid.Restrictions: This value must be an unsigned integer greater than0 and must be the session identification number of a currentlyrunning session.

-z sid

Kill a DatabaseServer Session



Kill a Distributed Transaction

Distributed transactions provide the ability to query data on different databaseservers.

Warning: If applications are performing distributed transactions, killing one of thedistributed transactions can leave your client/server database system in aninconsistent state. Try to avoid this situation.

IDS

Element Purpose Key Considerations-Z address Kills a distributed transaction

associated with the shared-memory address address.

Restrictions: This argument must be the address of anongoing distributed transaction that has exceeded theamount of time that TXTIMEOUT specifies. The addressmust conform to the operating-system-specific rules foraddressing shared-memory. (The address is available fromonstat -x output.)

Additional Information: This option is not valid until theamount of time that the ONCONFIG parameterTXTIMEOUT specifies has been exceeded. The -Z optionshould rarely be used and only by an administrator of adatabase server involved in distributed transactions.

References: For information on initiating independentactions in a two-phase commit protocol, see the chapter onmultiphase commit protocols in the Administrator’s Guide.

-Z address

Kill a DistributedTransaction

Utilities 3-45


Set Data-Replication Types

Using the -d standard Option

The -d standard option drops the connection between database servers in adata replication pair (if one exists) and sets the database server type of thecurrent database server to standard. This option does not change the mode ortype of the other database server in the pair.

IDS

Element Purpose Key Considerations-d Used to set the high-availability

data-replication type, eitherstandard, primary, or secondary,as the following sectionsdescribe.

Restrictions: You can use the -d primary and -dsecondary options only when the database server is inquiescent mode. You can use the -d standard optionwhen the database server is in quiescent, on-line, orread-only mode.

dbservername Identifies the database servername of the primary orsecondary database server.

Restrictions: The dbservername argument must corre-spond to the DBSERVERNAME parameter in theONCONFIG file of the intended secondary databaseserver. It should not correspond to one of the databaseservers that the DBSERVERALIASES parameterspecifies.

Additional Information: The dbservername argumentof the other database server in the data-replicationpair and the type of a database server (standard,primary, or secondary) is preserved after reinitial-ization of shared memory.

References: For more information, see range of valuesfor the DBSERVERNAME configuration parameter onpage 1-38.

- d standard

primary

secondary

dbservername

Set Data-ReplicationTypes



Using the -d primary dbservername Option

The -d primary dbservername option sets the database server type to primaryand attempts to connect with the database server that dbservername specifies.If the connection is successful, data replication is turned on. The primarydatabase server goes into on-line mode, and the secondary database servergoes into read-only mode. If the connection is not successful, the databaseserver comes to on-line mode, but data replication is not turned on.

Using the -d secondary dbservername Option

The -d secondary dbservername option sets the database server type tosecondary and attempts to connect with the database server that dbserv-ername specifies. If the connection is successful, data replication is turned on.The primary database server goes on-line, and the secondary database servergoes into read-only mode. If the connection is not successful, the databaseserver comes to read-only mode, but data replication is not turned on.

Utilities 3-47


Add a Shared-Memory Segment

Ordinarily, you do not need to add segments to the virtual portion of sharedmemory because the database server automatically adds segments as theyare needed. However, as segments are added, the database server mightreach the operating-system limit for the maximum number of segmentsbefore it acquires the memory that it needs. This situation typically occurswhen SHMADD is set so small that the database server exhausts the numberof available segments before it acquires the memory that it needs for someoperation.

If you manually add a segment that is larger than the segment specified bySHMADD, you can avoid exhausting the operating-system limit for segmentsbut still meet the need that the database server has for additional memory.

Element Purpose Key Considerations-a seg_size Allows you to add a new virtual

shared-memory segment. Sizeis specified in kilobytes.

Restrictions: The value of seg_size must be a positiveinteger. It must not exceed the operating-system limit onthe number of shared-memory segments.

Add a Shared-Memory Segment

- a seg_size



Add or Remove Virtual Processors

number

Add or RemoveVirtual Processors

SHM

CPU

SOC

TLI

+

vpclass+/-

number- p AIO

XPS

FIFIDS

+/-

IDS

Utilities 3-49


Extended Parallel Server supports adding or dropping all virtual processorclasses except CPU and AIO. ♦

For more information on the types of virtual processors, see the chapter onvirtual processors and threads in the Administrator’s Guide.

Element Purpose Key Considerations-p number Adds or removes virtual

processors. The numberargument indicates the numberof virtual processors to add orremove.

Restrictions: If this value is a negative integer, processorsare removed. If this value is a positive integer, processorsare added. You can use the -p option only when thedatabase server is in on-line mode, and you can add toonly one class of virtual processors at a time.

You cannot remove a virtual processor of any class, butyou can add virtual processors. (WIN NT)

For Extended Parallel Server, you cannot add or remove aCPU virtual processor. Although you can add a FIF VP inon-line mode, you cannot drop it in on-line mode.

Additional Information: If you are removing virtualprocessors, the maximum cannot exceed the actualnumber of processors of the specified type. If you areadding virtual processors, the maximum is less than 64kilobytes, but Informix recommends that the number ofCPU VPs not be greater than the number of physicalprocessors.

vpclass Names a user-defined virtualprocessor class.

Additional Information: For Dynamic Server, the user-defined virtual-processor class is defined by theVPCLASS parameter in the ONCONFIG file.References: For more information on extension classes,see “VPCLASS” on page 1-150.

XPS



Regenerate .infos or .infxdirs File

The database server uses information from the .infos.dbservername filewhen it accesses utilities. The database server creates and manages this file,and you should never need to do anything to the file. However,if .infos.dbservername is accidentally deleted, you must either re-create thefile or reinitialize shared memory.

Element Purpose Key Considerations-R Re-creates the

.infos.dbservername file (IDS).Restrictions: Before you use the -R option, set theINFORMIXSERVER environment variable to match theDBSERVERNAME parameter from the ONCONFIG file.Do not use the -R option if INFORMIXSERVER is one ofthe DBSERVERALIAS names.

Additional Information: For more information, see“.infos.dbservername” on page A-9.

Re-creates the.infos.dbservername file (XPS).

Additional Information: For more information, see“.infos.dbservername” on page A-9.

Re-creates the fileINFORMIXTMP/.infxdirsand removes invalid directoriesfrom it.

Additional Information: The .infxdirs file is used indatabase server discovery. This file contains a line forevery INFORMIXDIR from which a database server hasbeen launched. For more information, see “.infxdirs” onpage A-10.

Regenerate .infosor .infxdirs File

-R

infos

infxdirs

XPS

Utilities 3-51


Change Decision-Support Parameters

Element Purpose Key Considerations-D max_priority Changes the value of

MAX_PDQPRIORITY.Restrictions: This value must be an unsigned integerbetween 0 and 100.

Additional Information: Specify max_priority as a factor totemper user requests for PDQ resources.

References: For information on parameters used forcontrolling PDQ in Dynamic Server, see the chapter on tablefragmentation and PDQ in the Administrator’s Guide,“MAX_PDQPRIORITY” on page 1-88 and the PerformanceGuide.

-M kilobytes Changes the value ofDS_TOTAL_MEMORY.

Restrictions: This value must be an unsigned integerbetween 128 * DS_MAX_QUERIES and 1,048,576.

Additional Information: Specify kilobytes for the maximumamount of memory available for parallel queries.

References: For more information, see“DS_TOTAL_MEMORY” on page 1-54 and the PerformanceGuide.

(1 of 2)

Change Decision-Support Parameters

-M kilobytes

-Q queries

-S scans

-D max_priority

IDS



These options allow you to change configuration parameters while thedatabase server is on-line. The new values affect only the current instance ofthe database server; the values are not recorded in the ONCONFIG file. If youreinitialize shared memory, the values of the parameters revert to the valuesin the ONCONFIG file. For more information about these configurationparameters, see Chapter 1, “Configuration Parameters.”

To check the current values for the MAX_PDQPRIORITY, DS_TOTAL_MEMORY,DS_MAX_SCANS, and DS_MAX_QUERIES configuration parameters, useonstat -g mgm. ♦

To check the current values for the MAX_PDQPRIORITY, DS_TOTAL_MEMORY,and DS_MAX_QUERIES configuration parameters, use onstat -g rgm. ♦

-Q queries Changes the value ofDS_MAX_QUERIES.

Restrictions: This value must be an unsigned integerbetween 1 and 8,388,608.

Additional Information: Specify queries for the maximumnumber of concurrently executing parallel queries.

References: For information on parameters used forcontrolling PDQ (IDS), see the chapter on table fragmen-tation and PDQ in the Administrator’s Guide,“DS_MAX_QUERIES” on page 1-51, and the PerformanceGuide.

-S scans Changes the value ofDS_MAX_SCANS.

Restrictions:This value must be an unsigned integer between 10 and1,048,576.

Additional Information: Specify scans for the maximumnumber of concurrently executing parallel scans.

References: For information on parameters used forcontrolling PDQ, see the chapter on table fragmentation andPDQ in the Administrator’s Guide and “DS_MAX_SCANS”on page 1-53.


(2 of 2)

IDS

XPS

Utilities 3-53


Free Unused Memory Segments

When you execute onmode -F, the memory manager examines each memorypool for unused memory. When the memory manager locates 8 kilobytes ofcontiguous unused memory, it immediately frees the memory. After thememory manager checks each memory pool, it begins checking memorysegments and frees any that the database server no longer needs.

Informix recommends that you run onmode -F from an operating-systemscheduling facility regularly and after the database server performs anyfunction that creates additional memory segments, including large indexbuilds, sorts, or backups.

Running onmode -F causes a significant degradation of performance for anyusers that are active when you execute the utility. Although the executiontime is brief (1 to 2 seconds), degradation for a single-user database servercan reach 100 percent. Systems with multiple CPU virtual processorsexperience proportionately less degradation.

To confirm that onmode freed unused memory, check your message log. Ifthe memory manager frees one or more segments, it displays a message thatindicates how many segments and bytes of memory were freed.

Element Purpose Key Considerations-F Frees unused memory

segments.None.

Free UnusedMemory Segments

-F



Override ONDBSPACEDOWN WAIT Mode

Use the onmode -O option only in the following circumstances:

■ ONDBSPACEDOWN is set to WAIT.

■ A disabling I/O error occurs that causes the database server to blockall updating threads.

■ You cannot or do not want to correct the problem that caused thedisabling I/O error.

■ You want the database server to mark the disabled dbspace as downand continue processing.

When you execute this option, the database server marks the dbspaceresponsible for the disabling I/O error as down, completes a checkpoint, andreleases blocked threads. Then onmode prompts you with the followingmessage:

This will render any dbspaces which have incurred disablingI/O errors unusable and require them to be restored from anarchive.Do you wish to continue?(y/n)

If onmode does not find any disabling I/O errors on noncritical dbspaceswhen you run the -O option, it notifies you with the following message:

There have been no disabling I/O errors on any noncriticaldbspaces.

Element Purpose Key Considerations-O Overrides the WAIT mode of the ONDBSPACE-

DOWN configuration parameter.None.

OverrideONDBSPACEDOWN

WAIT Mode

-O

Utilities 3-55


Change Usage of the SQL Statement Cache

For more information on the SQL statement cache, see the Performance Guide.

IDS

Element Purpose Key Considerations-e mode Changes usage of the SQL

statement cache.If mode = ENABLE, the SQL statement cache is enabled, but asession does not use it unless the session sets theSTMT_CACHE environment variable to 1 or executes theSET STATEMENT CACHE ON statement.

If mode = ON, the SQL statement cache is enabled, and asession uses it unless the session sets the STMT_CACHEenvironment variable to 0 or executes the SET STATEMENTCACHE OFF statement.

If mode = OFF, the SQL statement cache is not enabled.

If mode = FLUSH, all statements in the SQL statement cacheare flushed when the database server releases them.

Change Usage of the SQLStatement Cache

-e mode


onparams: Modify Log-C
onfiguration Parameters
onparams: Modify Log-Configuration ParametersThe onparams flags determine which of the following operations onparamsperforms:

■ Change the size or location of the physical log

■ Add a logical-log file

■ Drop a logical-log file

The database server must be in quiescent mode.

On UNIX platforms, you must be logged in as user root or user informix toexecute onparams. On Windows NT, you must be a member of the Informix-Admin group.

To change the size or location of the physical log, you must edit theONCONFIG file and restart the database server. For information, see using atext editor to change the physical-log location and size in the chapter onmanaging the physical log in the Administrator’s Guide.

Syntax

Any onparams command fails if a storage-space backup is in progress. If youdo not use any options, onparams returns a usage statement.

IDS

onparams

Drop a Logical-Log Filep. 3-59

Change Physical-LogParameters

p. 3-60

Add a Logical-Log Filep. 3-58

Utilities 3-57

onparams: Modify Log-Configuration Parameters

Add a Logical-Log File

Using the -a option of onparams to add a logical-log file is one of the steps inthe procedure for moving logical-log files to another dbspace. See moving alogical-log file to another dbspace in the chapter on managing logical-log filesin the Administrator’s Guide.

Element Purpose Key Considerations-a -d dbspace Adds a logical-log file in

the location specified bydbspace.

Additional Information: The space allocated for a logical-logfile must be contiguous. The database server does not allow youto add a log file to a dbspace without adequate contiguousspace. You cannot add a log file during a backup (quiescent oron-line). The newly added log files retain a status of A and donot become available until you create a level-0 backup. If you areusing ON-Bar or ON-Archive, you only need to create a level-0backup of the root dbspace for the log file to become available.

References: Syntax must conform to the Identifier segment; seeInformix Guide to SQL: Syntax.

-s size Specifies a size inkilobytes for the newlogical-log file.

Restrictions: This value must be an unsigned integer greaterthan or equal to 200 kilobytes.

Additional Information: If you do not specify a size with the -soption, the size of the log file is taken from the value of theLOGSIZE parameter in the ONCONFIG file when databaseserver disk space was initialized.

References: For information on changing LOGSIZE orLOGFILES, see the chapter on managing logical-log files in theAdministrator’s Guide.

Add a Logical-Log File

-a -d dbspace

-s size



Drop a Logical-Log File

The onparams command to drop a logical-log file is one of the steps in theprocedure for moving logical-log files to another dbspace. See moving alogical-log file in the chapter on managing logical-log files in the Adminis-trator’s Guide.

Element Purpose Key Considerations-d -l logid Allows you to drop a

logical-log file specifiedby logid.

Restrictions: This value must be an unsigned integer greaterthan or equal to 0.

Additional Information: You can obtain the logid from thenumber field of onstat -l. The database server requires aminimum of three logical-log files at all times. You cannot drop alog file if the database server is configured for three logical-logfiles. The database server must be in quiescent mode before youdrop a logical log. Drop log files one at a time. You can only dropa log file that has a a status of Free (F) or newly Added (A).

After your configuration reflects the desired number of log files,create a level-0 backup. If you are using ON-Bar or ON-Archive,you only need to create a level-0 backup of the root dbspace. Useonstat -l to view the status of your logical-log files.

-y Causes the databaseserver to automaticallyrespond yes to allprompts.

None.

Drop a Logical-Log File

-d -l logid

-y

Utilities 3-59


Change Physical-Log Parameters

Element Purpose Key Considerations-p Changes the location or size of

the physical log.Additional Information: You can use onparams -p with-s, -d, or both.

-d dbspace Changes the location of thephysical log to the specifieddbspace.

Additional Information: The space allocated for thephysical log must be contiguous.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax.

-s size Changes the size (in kilobytes) ofthe physical log.

Restrictions: This value must be an unsigned integergreater than or equal to 200 kilobytes.

Additional Information: If you move the log to a dbspacewithout adequate contiguous space or increase the logsize beyond the available contiguous space, a fatal shared-memory error occurs when you attempt to reinitializeshared memory with the new value.

-y Causes the database server toautomatically respond yes to allprompts.

None.

Change Physical-Log Parameters

-d dbspace

-p 1

1-s size

-y



After You Change the Physical-Log Size or Location

Changes to the physical log do not take effect until you reinitialize sharedmemory. To reinitialize shared memory immediately, execute the onparamscommand with the -y option.

Create a level-0 backup immediately after you reinitialize shared memory.This backup is critical for proper recovery of the database server. If you areusing ON-Bar or ON-Archive, you only need to create a level-0 backup of theroot dbspace.

If you move the log to a dbspace without adequate contiguous space, a fatalshared-memory error occurs when you attempt to reinitialize sharedmemory with the new value.

For information on changing the physical-log location and size, see thechapter on managing the physical log in the Administrator’s Guide.

Utilities 3-61


onspaces: Manage Storage Spaces

onspaces: Manage Storage SpacesYou can perform the following tasks with the onspaces utility:

■ Create a dbspace, temporary dbspace, blobspace, or extspace

■ Create an sbspace

■ Drop a dbspace, blobspace, sbspace, or extspace

■ Add a chunk to a dbspace or blobspace

■ Add a chunk to an sbspace

■ Drop a chunk in a dbspace, blobspace, or sbspace

■ Start mirroring

■ End mirroring

■ Change status of a mirrored chunk

■ Specify the DATASKIP parameter

When you perform one of the preceding tasks on a storage space, either withthe onspaces utility or ON-Monitor, the database server updates informationabout the space in the oncfg_servername.servernum file.

For more information on the oncfg* file, refer to Appendix A, “Files That theDatabase Server Uses.”

On UNIX, you must be logged in as user root or user informix to executeonspaces. On Windows NT, you must be a member of the Informix-Admingroup.

IDS


Syntax

onspaces

Create a Dbspace, Temporary Dbspace, Blobspace, or Extspace,p. 3-64

Create an Sbspace,p. 3-68

Drop a Dbspace, Blobspace, Sbspace, or Extspace,p. 3-74

Add a Chunk to a Dbspace or Blobspace,p. 3-76

Add a Chunk to an Sbspace,p. 3-78

Drop a Chunk in a Dbspace, Blobspace, or Sbspace,p. 3-80

Start Mirroring,p. 3-82

End Mirroring,p. 3-84

Change Status of a Mirrored Chunk,p. 3-85

Specify DATASKIP,p. 3-87

Utilities 3-63


Create a Dbspace, Temporary Dbspace, Blobspace, orExtspace

Element Purpose Key Considerations-b blobspace Names the blobspace to be

created.Restrictions: The blobspace name must be uniqueand cannot exceed 128 characters. It must beginwith a letter or underscore and must contain onlyletters, numbers, underscores, or the $ character.

References: For more information, see creating ablobspace in the chapter on managing disk space inthe Administrator’s Guide. The syntax must conformto the Identifier segment. For more information, seethe Informix Guide to SQL: Syntax.

(1 of 4)

-t

-x extspace -l location

Create a Dbspace, Temporary Dbspace,Blobspace, or Extspace

-p pathname-c -d dbspace

-g pageunit-b blobspace -p \\.\drive

-o offset -s size

-m pathname offset

-m \\.\drive offset

WIN NT

WIN NT



-c Creates a dbspace, blobspace, orextspace.

Additional Information: After you create a storagespace, you must back it up and also the rootdbspace. If you create a storage space with the samename as a deleted storage space, perform anotherlevel-0 backup to ensure that future restores do notconfuse the new storage space with the old one.

References: For background information, seecreating a dbspace, blobspace, or extspace in thechapter on managing disk space in the Adminis-trator’s Guide.

drive Specifies the Windows NT driveto allocate as unbuffered diskspace. The format can be either\\.\<drive>, where drive is thedrive letter assigned to a diskpartition, or\\.\PhysicalDrive<number>,where PhysicalDrive is aconstant value and number is thephysical drive number.

References: For information on allocating unbuf-fered disk space on Windows NT platforms, seeallocating unbuffered disk space on Windows NT inthe chapter on managing disk space in the Adminis-trator’s Guide.

Examples:

\\.\F:\\.\PhysicalDrive2

References: For pathname syntax, see youroperating-system documentation.

-d dbspace Names the dbspace to becreated.

Restrictions: The dbspace name must be uniqueand cannot exceed 128 characters. It must beginwith a letter or underscore and must contain onlyletters, numbers, underscores, or the $ character.

References: For more information, see creating adbspace in the chapter on managing disk space inthe Administrator’s Guide. The syntax must conformto the Identifier segment. For more information, seethe Informix Guide to SQL: Syntax.

-g pageunit Specifies the blobspaceblobpage size in terms ofpage_unit, the number of diskpages per blobpage.

Restrictions: Unsigned integer. Value must begreater than 0.

References: For more information, see blobpagesize considerations in the chapter on I/O Activity inthe Performance Guide.

-l location Specifies the location of theextspace. The access methoddetermines the format of thisstring.

Restrictions: String. Value must not be longer than255 bytes.

References: For background information, seecreating an extspace in the chapter on managingdisk space in the Administrator’s Guide.


(2 of 4)

Utilities 3-65


-m pathname offset Specifies an optional pathnameand offset to the chunk thatmirrors the initial chunk of thenew blobspace or dbspace. Alsosee the entries for -p pathnameand -o offset in this table.

References: For more information, see creating adbspace or a blobspace in the chapter on managingdisk space in the Administrator’s Guide.

-o offset Indicates, in kilobytes, the offsetinto the disk partition or into thedevice to reach the initial chunkof the new blobspace, dbspace,or sbspace.

Restrictions: Unsigned integer. Value must begreater than 0. On most platforms, size must notexceed 2 gigabytes, which is the same as themaximum chunk size. On some platforms, themaximum chunk size is 4 gigabytes. To determinewhich chunk size your platform supports, refer toyour release notes file.

References: For more information, see allocatingraw disk space in the chapter on managing diskspace in the Administrator’s Guide.

-p pathname Indicates the disk partition ordevice of the initial chunk of theblobspace or dbspace that youare creating.

Additional Information: The chunk must be anexisting unbuffered device or buffered file. Whenyou specify a pathname, you can use either a fullpathname or a relative pathname. However, if youuse a relative pathname, it must be relative to thedirectory that was the current directory when youinitialized the database server.

UNIX example (unbuffered device):

/dev/rdsk/c0t3d0s4

UNIX example (buffered device):

/ix/ids9.2/db1chunk

Windows NT example:

c:\Ifmxdata\ol_icecream\mychunk1.dat


-s size Indicates, in kilobytes, the sizeof the initial chunk of the newblobspace or dbspace.

Restrictions: Unsigned integer. Value must begreater than 0. Size must not exceed 2 gigabytes onmost platforms, but on some platforms themaximum chunk size is 4 gigabytes. To determinewhich chunk size your platform supports, refer toyour machine notes file (UNIX) or release notes file(Windows NT).


(3 of 4)



Creating a Temporary Dbspace with the -t OptionWhen you create a temporary dbspace with onspaces, the database serverdoes not use the newly created temporary dbspace until you perform thefollowing steps:

■ Add the name of the new temporary dbspace to your list oftemporary dbspaces in the DBSPACETEMP configuration parameter,the DBSPACETEMP environment variable, or both.

■ Reinitialize the database server.

You can also use ON-Monitor to create a temporary dbspace. ♦

-t Creates a temporary dbspace. References: For more information, see creating atemporary dbspace with the -t option and what is atemporary dbspace in the chapter on managing diskspace in the Administrator’s Guide.

-x extspace Names the extspace to becreated.

Restrictions: Extspace names can be up to 128characters. They must be unique, begin with a letteror underscore, and contain only letters, digits,underscores, or $ characters.

References: For background information, see whatis an extspace in the chapter on managing diskspace in the Administrator’s Guide.


(4 of 4)

UNIX

Utilities 3-67


Create an Sbspace

Element Purpose Key Considerations-S sbspace Names the sbspace to be

created.Restrictions: The sbspace name must be unique,and must not exceed 128 characters. It must beginwith a letter or underscore and must contain onlyletters, numbers, underscores, or the $ character.


-c Creates an sbspace. References: For more information, see creating ansbspace in the chapter on managing disk space inthe Administrator’s Guide.

-m pathname offset Specifies an optional pathnameand offset to the chunk thatmirrors the initial chunk of thenew sbspace. Also see theentries for -p pathname and -ooffset in this table.

References: For background information, seecreating an sbspace in the chapter on managing diskspace in the Administrator’s Guide.

-Mo mdoffset Indicates, in kilobytes, the offsetinto the disk partition or into thedevice where metadata will bestored.

Restrictions: Integer. Value must not be longer than255 bytes.

References: For more information, see sizingsbspace metadata in the chapter on managing diskspace in the Administrator’s Guide.

-Ms mdsize Specifies the size, in kilobytes,of the metadata area allocated inthe initial chunk. The remainderis user-data space.

Restrictions: Integer. Value must not be longer than255 bytes.

References: For more information, see sizingsbspace metadata in the chapter on managing diskspace in the Administrator’s Guide.

(1 of 2)

Create an Sbspace

-S sbspace -o offset -s size

-m pathname offset

-c -p pathname

-Df default list-Mo mdoffset-Ms mdsize



The onspaces -g option is not used for sbspaces. The database server uses adifferent method to determine the number of pages to transfer in an I/Ooperation for sbspaces than for blobspaces. The database server can automat-ically determine the block size to transfer in an I/O operation for smart largeobjects. For more information, see sbspace extent sizes in the chapter on I/Oactivity in your Performance Guide.

Creating an Sbspace with the -Df option

When you create an sbspace with the -Df option, you can specify severaldefault specifications that affect the behavior of the smart large objects storedin the sbspace. The default specifications must be expressed as a listseparated by commas. The list need not contain all of the tags, and -Df isoptional. The list of tags must be enclosed in double quotation marks (“). Thetable in Figure 3-2 describes the tags and their default values.

-o offset Indicates, in kilobytes, the offsetinto the disk partition or into thedevice to reach the initial chunkof the sbspace.


References: For more information, see allocatingraw disk space on UNIX in the chapter on managingdisk space in the Administrator’s Guide.

-p pathname Indicates the disk partition orunbuffered device of the initialchunk of the sbspace.



-s size Indicates, in kilobytes, the sizeof the initial chunk of the newsbspace.

Restrictions: Unsigned integer. Value must begreater than 0. Size must not exceed 2 gigabytes.

-Df default list Lists default specifications forsmart large objects stored in thesbspace.

Restrictions: Tags are separated by commas. If a tagis not present, system defaults take precedence. Thelist must be enclosed in double quotation marks (“)on the command line.

References: For a list of tags and their parameters,see Figure 3-2 on page 3-70.


(2 of 2)

Utilities 3-69


The four levels of inheritance for sbspace characteristics are system, sbspace,column, and smart large objects. For more information, see smart largeobjects in the chapter on where data is stored in the Administrator’s Guide.

Figure 3-2-Df Default Specifications

Tag ValuesSystemDefault Description

ACCESSTIME ON or OFF OFF When set to ON, the database server tracks the time ofaccess to all smart large objects stored in the sbspace.

References: For information about using the access time,see the chapter on smart large objects in the DataBlade APIProgrammer’s Manual.

AVG_LO_SIZE For Windows NT:4 to 2**31

For UNIX:2 to 2**31

8 Specifies the average size, in kilobytes, of the smart largeobject stored in the sbspace. The database server uses thisvalue to calculate the size of the metadata area to allocatewhen the -Ms option is not specified.

Error 131 is returned if you run out of metadata area inthe sbspace. To allocate additional chunks to the sbspacethat consist of metadata area only, use the -Ms option.

References: For more information, see creating smartlarge objects in the chapter on managing data on disk inthe Administrator’s Guide.

BUFFERING ON or OFF ON Specifies the buffering mode of smart large objects storedin the sbspace. If set to ON, the database server uses thebuffer pool in the resident portion of shared memory forsmart-large-object I/O operations. If set to OFF, thedatabase server uses light I/O buffers in the virtualportion of shared memory (lightweight I/O operations).

References: For more information, see lightweight I/O inthe chapter on configuration effects on memory in thePerformance Guide.

LOCK_MODE RANGE or BLOB BLOB Specifies the locking mode of smart large objects stored inthe sbspace. If set to RANGE, only a range of bytes in thesmart large object is locked. If set to BLOB, the entire smartlarge object is locked.

References: For more information, see smart large objectsin the chapter on locking in the Performance Guide.

(1 of 2)



LOGGING ON or OFF OFF Specifies the logging status of smart large objects storedin the sbspace. If set to ON, the database server logschanges to the user data area of the sbspace.

When you turn on logging for an sbspace, take a level-0backup of the sbspace.

References: For more information, see smart large objectsin the chapters on where data is stored and logging in theAdministrator’s Guide.

EXTENT_SIZE 4 to 2**31 16 Specifies the size, in kilobytes, of the first allocation ofdisk space for smart large objects stored in the sbspacewhen you create the table.

Let the system select the EXTENT_SIZE value. To reducethe number of extents in a smart large object, usemi_lo_specset_estbytes (DataBlade API) orifx_lo_specset_estbytes (ESQL/C) to obtain the size ofthe smart large object.

References: For more information, see smart large objectsin the chapter on where data is stored in the Adminis-trator’s Guide. For information about obtaining the size ofsmart large objects, see the DataBlade API Programmer’sManual or the Informix ESQL/C Programmer’s Manual.

MIN_EXT_SIZE 2 to 2**31 4 Specifies the minimum amount of space, in kilobytes, toallocate for each smart large object.

References: For information about tuning this value, seesmart large objects in the chapter on configuration effectson I/O utilization in the Performance Guide.

NEXT_SIZE 4 to 2**31 16 Specifies the extent size, in kilobytes, of the nextallocation of disk space for smart large objects when theinitial extent in the sbspace becomes full.

Let the system select the NEXT_SIZE value. To reduce thenumber of extents in a smart large object, usemi_lo_specset_estbytes (DataBlade API) orifx_lo_specset_estbytes (ESQL/C) to obtain the size ofthe smart large object.

References: For more information, see smart large objectsin the chapter on where data is stored in the Adminis-trator’s Guide. For information about obtaining the size ofsmart large objects, see the DataBlade API Programmer’sManual or the Informix ESQL/C Programmer’s Manual.

Tag ValuesSystemDefault Description

(2 of 2)

Utilities 3-71


For example, you can create an sbspace with onspaces, as the followingexample illustrates.

% onspaces -c -S eg_sbsp -p /dev/raw_dev1 -o 500 -s 20000-m /dev/raw_dev2 500 -Ms 150 -Mo 200 -Df "AVG_LO_SIZE=32,LOGGING=ON"

♦

This example creates a 20-megabyte mirrored sbspace, eg_sblobsp, with thefollowing specifications:

■ An offset of 500 kilobytes for the primary and mirrored chunks

■ A metadata size of 150 kilobytes with a 200 kilobyte offset

■ An average expected smart-large-object size of 32 kilobytes

■ Log changes to the smart large objects in the user data area of thesbspace

As the database server administrator, you can override or change the -Dfdefault settings in one of the following ways:

■ To change the default settings for an sbspace, use the onspaces -choption. For more information, refer to “Change Sbspace DefaultSpecifications” on page 3-73.

■ To override the following -Df default settings for a specific table, usethe SQL statements CREATE TABLE or ALTER TABLE:

❑ LOGGING

❑ ACCESSTIME

❑ EXTENT_SIZE

❑ NEXT_SIZE

For more information on the ALTER TABLE and CREATE TABLE state-ments, see the Informix Guide to SQL: Syntax.

The programmer can override these -Df default settings with functions thatthe DataBlade API and ESQL/C programming interface provide. For moreinformation on the DataBlade API functions for smart large objects, refer tothe DataBlade API Programmer’s Manual. For more information on the ESQL/Cfunctions for smart large objects, refer to the Informix ESQL/C Programmer’sManual.

Important: When you are adding a chunk to an existing sbspace, the -Df option isignored.

UNIX



Change Sbspace Default Specifications

You can change any of the -Df tags with the onspaces -ch option. Thedatabase server applies the change to each smart large object that was createdprior to changing the default specification.

For example, to turn off logging for the sbspace that you created on page3-72, use the following command:

onspaces -ch eg_sbsp -Df "LOGGING=OFF"

Important: After you turn on logging for an sbspace, take a level-0 backup of thesbspace to create a point from which to recover.

Element Purpose Key Considerations-ch Indicates that one or more

sbspace default specificationsare to be changed.

None.

sbspace Names the sbspace for which tochange the defaultspecifications.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. Forbackground information, see changing defaultspecifications of an sbspace with onspaces in thePerformance Guide.

-Df default list Lists new default specificationsfor smart large objects stored inthe sbspace.

Restrictions: Tags are separated by commas. If a tagis not present, system defaults take precedence. Thelist must be enclosed in double quotation marks (“)on the command line.

References: For a list of tags and their parameters,see Figure 3-2 on page 3-70.

Change Sbspace Default Specifications

sbspace -Df default list-ch

Utilities 3-73


Drop a Dbspace, Blobspace, Sbspace, or Extspace

Element Purpose Key Considerations-d Indicates that a dbspace,

blobspace, sbspace, orextspace is to be dropped.

Additional Information: You can drop a dbspace,blobspace, sbspace, or extspace while the database server ison-line or in quiescent mode. After you drop a storagespace, you must back it up to ensure that the sysutilsdatabase and the reserved pages are up-to-date.

Restriction: Execute oncheck -pe to verify that no table iscurrently storing data in the dbspace, blobspace, or sbspace.

References: For more information, see dropping a storagespace in the chapter on managing disk space in the Admin-istrator’s Guide.

-y Causes the database server toautomatically respond yes toall prompts.

None.

-f Drops an sbspace that con-tains user data and metadata.

Additional Information: You must use the -f (force) optionto drop an sbspace that contains data.

Restriction: Use the -f option with sbspaces only.

Warning: If you use the -f option, the tables in the databaseserver might have dead pointers to the smart large objectsthat were deleted with this option.

References: For more information, see dropping a chunkfrom an sbspace with onspaces in the chapter on managingdisk space in the Administrator’s Guide.

(1 of 2)

Drop a Dbspace, Blobspace, Sbspace, or Extspace

-y

-f

-d dbspace

blobspace

sbspace

extspace



Important: Do not specify a pathname when you drop these storage spaces.

blobspace Names the blobspace to bedropped.

Additional Information: Before you drop a blobspace,drop all tables that include a TEXT or BYTE column thatreferences the blobspace.

dbspace Names the dbspace to bedropped.

Additional Information: Before you drop a dbspace, dropall databases and tables that you previously created in thedbspace.

extspace Names the extspace to bedropped.

Additional Information: You cannot drop an extspace if itis associated with an existing table or index.

sbspace Names the sbspace to bedropped.

Additional Information: Before you drop an sbspace, dropall tables that include a BLOB or CLOB column that refer-ences the sbspace.


(2 of 2)

Utilities 3-75


Add a Chunk to a Dbspace or Blobspace

Element Purpose Key Considerations-a Indicates that a chunk is to be

added.None.

drive Specifies the Windows NT driveto allocate as unbuffered diskspace. The format can be either\\.\<drive>, where drive is thedrive letter assigned to a diskpartition, or\\.\PhysicalDrive<number>,where PhysicalDrive is aconstant value and number is thephysical drive number.

References: For more information on allocating unbuf-fered disk space on Windows NT, see allocating raw diskspace on Windows NT in the chapter on managing diskspace in the Administrator’s Guide.

Example:

\\.\F:


-m pathnameoffset

Specifies an optional pathnameand offset to the chunk thatmirrors the new chunk. Also seethe entries for pathname andoffset in this table.

References: For more information, see adding a chunk toa dbspace and adding a chunk to a blobspace in thechapter on managing disk space in the Administrator’sGuide.

(1 of 2)

blobspace

-s size

-p pathname

Add a Chunk to a Dbspace or Blobspace

-o offset

-m \\.\drive offset

-a dbspace

-p \\.\drive

WIN NT

-m pathname offset

WIN NT



-o offset After the -a option, offsetindicates, in kilobytes, the offsetinto the disk partition or into thedevice to reach the initial chunkof the new blobspace ordbspace.

Restrictions: Unsigned integer. Value must be greaterthan 0.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see allocating raw disk space on UNIX in thechapter on managing disk space in the Administrator’sGuide.

-p pathname Indicates the disk partition orunbuffered device of the initialchunk of the blobspace ordbspace that you are adding.The chunk must be an existingunbuffered device or bufferedfile.

Additional Information: The chunk name can be up to128 characters. When you specify a pathname, you canuse either a full pathname or a relative pathname.However, if you use a relative pathname, it must berelative to the directory that was the current directorywhen you initialized the database server.

UNIX example (unbuffered device):

/dev/rdsk/c0t3d0s4

UNIX example (buffered device):

/ix/ids9.2/db1chunk

Windows NT example:

c:\Ifmxdata\ol_icecream\mychunk1.dat



Restrictions: Unsigned integer. Value must be greaterthan 0. Size must not exceed 2 gigabytes.

blobspace Names the blobspace to whichyou are adding a chunk.

Restrictions: See adding a chunk to a blobspace in thechapter on managing disk space in the Administrator’sGuide.


dbspace Names the dbspace to whichyou are adding a chunk.

Restrictions: See adding a chunk to a dbspace in thechapter on managing disk space in the Administrator’sGuide.



(2 of 2)

Utilities 3-77


Add a Chunk to an Sbspace

Element Purpose Key Considerations-a Indicates that a chunk is to be

added.None.

-m pathname offset Specifies an optional pathnameand offset to the chunk thatmirrors the new chunk. Also seethe entries for pathname andoffset in this table.

References: For background information, seeadding a chunk to an sbspace in the chapter onmanaging disk space in the Administrator’s Guide.

-Mo mdoffset Indicates, in kilobytes, the offsetinto the disk partition or into thedevice where metadata shouldbe stored.

Restrictions: String not longer than 255 bytes.

References: For background information, see sizingsbspace metadata in the chapter on managing diskspace in the Administrator’s Guide.

-Ms mdsize Specifies the size, in kilobytes,of the metadata area allocated inthe initial chunk. The remainderis user-data space.

Restrictions: String not longer than 255 bytes.

References: For background information, see sizingsbspace metadata in the chapter on managing diskspace in the Administrator’s Guide.

-o offset After the -a option, offsetindicates, in kilobytes, the offsetinto the disk partition or into theunbuffered device to reach theinitial chunk of the newblobspace or dbspace.


References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax. Forbackground information, see allocating raw diskspace on UNIX in the chapter on managing diskspace in the Administrator’s Guide.

(1 of 2)

Add a Chunk to an Sbspace

sbspace -o offset -s size-a -p pathname

-Mo mdoffset -U

-m pathname offset

-Ms mdsize



-p pathname Indicates the disk partition orunbuffered device of the initialchunk of the sbspace that youare creating. The chunk must bean existing unbuffered device orbuffered file.

Additional Information: The chunk name can beup to 128 characters. When you specify a pathname,you can use either a full pathname or a relativepathname. However, if you use a relative pathname,it must be relative to the directory that was thecurrent directory when you initialized the databaseserver.


-U Specifies that the entire chunkshould be used to store userdata.

Restrictions: The -M and -U options are mutuallyexclusive.References: For background information, seeadding a chunk to an sbspace in the chapter onmanaging disk space in the Administrator’s Guide.


Restrictions: Unsigned integer. Value must begreater than 0. Size must not exceed 2 gigabytes.

sbspace Names the sbspace to whichyou are adding a chunk.

Restrictions: See adding a chunk to an sbspace inthe chapter on managing disk space in the Adminis-trator’s Guide.



(2 of 2)

Utilities 3-79


Drop a Chunk in a Dbspace, Blobspace, or Sbspace

Element Purpose Key Considerations-d Drops a chunk. Restrictions: You can drop a chunk from a dbspace or

temporary dbspace when the database server is on-line orquiescent. For more information, see the chapter onmanaging disk space in the Administrator’s Guide.

You can drop a chunk from a blobspace or sbspace onlywhen the database server is in quiescent mode.

-f Drops an sbspace chunk thatcontains user data but no meta-data. If the chunk containsmetadata for the sbspace, youmust drop the entire sbspace.

Restrictions: Use the -f option with sbspaces only. If youomit the -f option, you cannot drop an sbspace thatcontains data.

References: For more information, see dropping a chunkfrom an sbspace with onspaces in the chapter onmanaging disk space in the Administrator’s Guide.

-o offset Indicates, in kilobytes, the offsetinto the disk partition or into theunbuffered device to reach theinitial chunk of the dbspace,blobspace, or sbspace that youare dropping.

Restrictions: Unsigned integer. Value must be greaterthan or equal to 0.

References: For more information, see allocating raw diskspace on UNIX in the chapter on managing disk space inthe Administrator’s Guide.

-p pathname Indicates the disk partition orunbuffered device of the initialchunk of the dbspace,blobspace, or sbspace that youare dropping.

Additional Information: The chunk must be an existingunbuffered device or buffered file. When you specify apathname, you can use either a full pathname or a relativepathname. However, if you use a relative pathname, itmust be relative to the directory that was the currentdirectory when you initialized the database server.


(1 of 2)

-d

Drop a Chunk

-p pathname -o offset

-y

-f

dbspace

blobspace

sbspace



Important: You must specify a pathname to indicate to the database server that youare dropping a chunk.


None.

blobspace Names the blobspace fromwhich the chunk is dropped.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see dropping a chunk from a blobspace inthe chapter on managing disk space in the Administrator’sGuide.

dbspace Names the dbspace from whichthe chunk is dropped.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see dropping a chunk from a dbspace withonspaces in the chapter on managing disk space in theAdministrator’s Guide.

sbspace Names the sbspace from whichthe chunk is dropped.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. Forbackground information, see dropping a chunk from adbspace with onspaces in the chapter on managing diskspace in the Administrator’s Guide.


(2 of 2)

Utilities 3-81


Start Mirroring

Element Purpose Key Considerations-f filename Indicates that chunk-location

information is in a file namedfilename.

Additional Information: The file must be a bufferedfile that already exists. The pathname must conformto the operating-system-specific rules forpathnames.

References: For more information, see “Using a Fileto Specify Chunk-Location Information with the-f Option” on page 3-84.

-m Adds mirroring for an existingdbspace, blobspace, or sbspace.

Additional Information: User-data chunks in amirrored sbspace need not be mirrored.

-m pathname offset The second time that pathnameoccurs in the syntax diagram, itindicates the disk partition orunbuffered device of the initialchunk of the dbspace,blobspace, or sbspace thatperforms the mirroring. Thesecond time offset appears in thesyntax diagram, it indicates theoffset to reach the mirroredchunk of the newly mirroreddbspace, blobspace, or sbspace.Also see the entries for pathnameand offset in this table.

None.

(1 of 2)

-m

Start Mirroring

-o offset-p pathname -m pathname offset

-f filename -y

dbspace

blobspace

sbspace



-o offset The first time that offset occursin the syntax diagram, itindicates, in kilobytes, the offsetinto the disk partition or into theunbuffered device to reach theinitial chunk of the newlymirrored dbspace, blobspace, orsbspace.


References: For background information, seeallocating raw disk space on UNIX in the chapter onmanaging disk space in the Administrator’s Guide.

-p pathname The first time pathname occurs inthe syntax diagram, it indicatesthe disk partition or unbuffereddevice of the initial chunk of thedbspace, blobspace, or sbspacethat you want to mirror.




None.

blobspace Names the blobspace that youwant to mirror.

References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax. For moreinformation, see the chapter on using mirroring inthe Administrator’s Guide.

dbspace Names the dbspace that youwant to mirror.

References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax. Forbackground information, see the chapter on usingmirroring in the Administrator’s Guide.

sbspace Names the sbspace that youwant to mirror.

References: Syntax must conform to the Identifiersegment; see Informix Guide to SQL: Syntax. Forbackground information, see the chapter on usingmirroring in the Administrator’s Guide.


(2 of 2)

Utilities 3-83


Using a File to Specify Chunk-Location Information with the -f Option

You can create a file that contains the chunk-location information. Then,when you execute onspaces, use the -f option to indicate to the databaseserver that this information is in a file whose name you specify in filename.

If the dbspace that you are mirroring contains multiple chunks, you mustspecify a mirrored chunk for each of the primary chunks in the dbspace thatyou want to mirror. For an example that enables mirroring for a multichunkdbspace, see starting mirroring for unmirrored dbspaces with onspaces inthe chapter on using mirroring in the Administrator’s Guide.

End Mirroring

Element Purpose Key Considerations-r Indicates to the database server

that mirroring should be endedfor an existing dbspace,blobspace, or sbspace.

References: For background information, see the chapteron using mirroring in the Administrator’s Guide.

-y Causes the database server torespond yes to all promptsautomatically.

None.

-r

End Mirroring

-y

dbspace

blobspace

sbspace



Change Status of a Mirrored Chunk

blobspace Names the blobspace for whichyou want to end mirroring.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see the chapter on using mirroring in theAdministrator’s Guide.

dbspace Names the dbspace for whichyou want to end mirroring.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see the chapter on using mirroring in theAdministrator’s Guide.

sbspace Names the sbspace for whichyou want to end mirroring.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. Forbackground information, see the chapter on usingmirroring in the Administrator’s Guide.


-y

-s

-O

-D-o offset-p pathname

Change Chunk Status

dbspace

blobspace

sbspace

Element Purpose Key Considerations-D Indicates that you want to take

the chunk down.None.

-o offset Indicates, in kilobytes, the offsetinto the disk partition or unbuf-fered device to reach the chunk.

Restrictions: Unsigned integer. Value must be greaterthan or equal to 0.

References: For more information, see allocating rawdisk space on UNIX in the chapter on managing diskspace in the Administrator’s Guide.

-O Indicates that you want torestore the chunk and bring iton-line.

None.

(1 of 2)

Utilities 3-85


-p pathname Indicates the disk partition orunbuffered device of the chunk.

Additional Information: The chunk can be an unbuf-fered device or a buffered file. When you specify apathname, you can use either a full pathname or arelative pathname. However, if you use a relativepathname, it must be relative to the directory that wasthe current directory when you initialized the databaseserver.


-s Indicates that you want tochange the status of a chunk.

Restrictions: You can only change the status of a chunkin a mirrored pair.

References: For more information, see changing themirror status in the Administrator’s Guide.

-y Causes the database server torespond yes to all promptsautomatically.

None.

blobspace Names the blobspace whosestatus you want to change.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see changing the mirror status in the Admin-istrator’s Guide.

dbspace Names the dbspace whosestatus you want to change.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. For moreinformation, see changing the mirror status in the Admin-istrator’s Guide.

sbspace Names the sbspace whosestatus you want to change.

References: Syntax must conform to the Identifiersegment; see the Informix Guide to SQL: Syntax. Forbackground information, see changing the mirror statusin the Administrator’s Guide.


(2 of 2)



Specify DATASKIP Parameter

The onspaces utility lets you specify DATASKIP on a dbspace level or acrossall dbspaces.

Element Purpose Key Considerations-f Indicates to the database

server that you want tochange the DATASKIPdefault for specifieddbspaces or all dbspaces.

Additional Information: All changes in the DATASKIPstatus are recorded in the message log.

-y Causes the database serverto automatically respondyes to all prompts.

None.

dbspace-list Specifies the name of one ormore dbspaces for whichDATASKIP will be turnedON or OFF.

References: Syntax must conform to the Identifier segment;see the Informix Guide to SQL: Syntax. For more information,see “DATASKIP” on page 1-35 and the Performance Guide.

OFF Turns off DATASKIP. Additional Information: If you use OFF without dbspace-list,DATASKIP is turned off for all fragments. If you use OFFwith dbspace-list, only the specified fragments are set withDATASKIP off.

ON Turns on DATASKIP. Additional Information: If you use ON without dbspace-list,DATASKIP is turned on for all fragments. If you use ON withdbspace-list, only the specified fragments are set withDATASKIP on.

ON dbspace-list

Specify DATASKIP

-y

OFF-f

Utilities 3-87


onstat: Monitor Database Server Operation

onstat: Monitor Database Server OperationThe onstat utility reads shared-memory structures and provides statisticsabout the database server that are accurate at the instant that the commandexecutes. The system-monitoring interface also provides information about thedatabase server. For information on the system-monitoring interface, seeChapter 2, “The sysmaster Database.”

The contents of shared memory might change as the onstat output displays.The onstat utility does not place any locks on shared memory, so running theutility does not affect performance.


Syntax

filename_dest- -

filename_source

onstat

filename_dest

1IDS

seconds

-j1

-a1

-b1

-B1

-c1

-C1

-d1

-D1

-f1

-g1

-h1

-k1

-l1

-m1

-O

-p1

1 -P

-r1

-R1

-s1

-t1

-u1

-x1

-z1-o1

-F1

1 -X

-i1

-K1

Utilities 3-89


Element Purpose Key Considerations-- Displays a listing of all onstat options

and their functions.Additional Information: This option is the onlyoption flag that you cannot combine with anyother flag.

References: See “The onstat -- Option” onpage 3-95.

-a Interpreted as onstat -cuskbtdlp.Displays output in that order.

References: See “The onstat -a Option” onpage 3-95.

-b Displays information about bufferscurrently in use, including number ofresident pages in the buffer pool.

References: See “The onstat -b Option” onpage 3-95.

-B Obtains information about alldatabase server buffers, not justbuffers currently in use. See the entryfor -b in this table.

Additional Information: The -B output displayfields are the same as the fields that appear inthe -b output.

-c Displays the ONCONFIG file:

■ $INFORMIXDIR/etc/$ONCONFIG for UNIX

■ %INFORMIXDIR%\etc\%ONCONFIG% for Windows NT

References: See “The onstat -c Option” onpage 3-98.

-C Prints B-tree cleaner information. None.-d Displays information for chunks in

each storage space.References: See “The onstat -d Option” onpage 3-98.

-D Displays page-read and page-writeinformation for the first 50 chunks ineach dbspace.

References: See “The onstat -D Option” onpage 3-102.

-f Lists the dbspaces currently affectedby the DATASKIP feature.

References: See “The onstat -f Option” onpage 3-103.

-F Displays a count for each type ofwrite that flushes pages to disk.

References: See “The onstat -F Option” onpage 3-103.

-g Provides monitoring options. References: See “The onstat -g MonitoringOptions” on page 3-104.

-h Prints information about buffer hashchain.

None.

-i Puts the onstat utility into interactivemode.

References: See “The onstat -i Option” onpage 3-110.

-k Displays information about activelocks.

References: See “The onstat -k Option” onpage 3-111.

-K Displays information about byte-range locks.

References: See “The onstat -K Option” onpage 3-112.

(1 of 3)



-l Displays information about physicaland logical logs, including pageaddresses.

References: See “The onstat -l Option” onpage 3-113.

-m Displays the 20 most recent lines ofthe database server message log.

Additional Information: Output from this optionlists the full pathname of the message-log file andthe 20 file entries. A date-and-time headerseparates the entries for each day. A time stampprefaces single entries within each day. The nameof the message log is specified as MSGPATH inthe ONCONFIG file.

References: See “The onstat -m Option” onpage 3-114.

-o Saves a copy of the shared-memorysegment to filename.

Additional Information: If you omit a filenamein the onstat command, the copy of sharedmemory is saved to onstat.out in the currentdirectory.

-O Displays information about theOptical Subsystem memory cacheand staging-area blobspace (IDS).

References: See “The onstat -O Option” onpage 3-115.

-p Displays profile counts. References: See “The onstat -p Option” onpage 3-117.

-P Displays for all partitions thepartition number and the break-up ofthe buffer-pool pages that belong tothe partition.

References: See “The onstat -P Option” onpage 3-120.

-r Repeats the accompanying onstatoptions after they wait the specifiedseconds between each execution. Thedefault value of seconds is 5.

Additional Information: To end execution, pressDEL or CTRL-C.

-R Displays detailed information aboutthe LRU queues, FLRU queues, andMLRU queues.

References: See “The onstat -R Option” onpage 3-121.

-s Displays general latch information. References: See “The onstat -s Option” onpage 3-123.

-t Displays tblspace information,including residency state, for activetblspaces.

References: See “The onstat -t Option” onpage 3-125.

-u Prints a profile of user activity. References: See “The onstat -u Option” onpage 3-126.


(2 of 3)

Utilities 3-91


Statistics Culled from Source File

Use the filename_source parameter with other option flags to derive therequested onstat statistics from the shared-memory segment thatfilename_source contains. You must first use the onstat -o command to createa file that contains a shared-memory segment.

Interactive Execution

To put the onstat utility in interactive mode, use the -i option. Interactivemode allows you to enter multiple options, one after the other, withoutexiting the program. For information on using interactive mode, see “Theonstat -i Option” on page 3-110.

-x Displays information abouttransactions.

References: See “The onstat -x Option” onpage 3-129.

-X Obtains precise information aboutthe threads that are sharing andwaiting for buffers.

References: See “The onstat -X Option” onpage 3-131.

-z Sets the profile counts to 0. References: See “The onstat -z Option” onpage 3-131.

filename_dest Specifies destination file for the copyof the shared-memory segment.

Restrictions: Name must not match the name ofany existing file.


filename_source Specifies file that onstat readsas source for the requestedinformation.

Restrictions: This file must include a previouslystored shared-memory segment that you createdwith the -o option of onstat.

References: For specific details on this option,see “Statistics Culled from Source File.” Forpathname syntax, see your operating-systemdocumentation.

seconds Specifies number of seconds betweeneach execution of the onstat -rcommand.

Restrictions: This value must be an unsignedinteger greater than 0.


(3 of 3)



Continuous onstat Execution

Use the seconds parameter with the -r option flag to cause all other flags toexecute repeatedly after they wait the specified seconds between eachexecution.

Output HeaderAll onstat output includes a header. The header takes the following form:

Version--Mode (Type)--(Checkpnt)--Up Uptime--Sh_mem Kbytes

Version is the product name and version number.

Mode is the current operating mode.

(Type) is the data-replication type of the database server. If thedatabase server is not involved in data replication, this fielddoes not appear. If the type is primary, the value P appears. Ifthe type is secondary, the value S appears. (IDS)

This field does not appear. (XPS)

(Checkpnt) is a checkpoint flag. If it is set, the header might display twoother fields after the mode if the timing is appropriate:

(CKPT REQ) indicates that a user thread has requested acheckpoint.

(CKPT INP) indicates that a checkpoint is in progress.During the checkpoint, access is limited to readonly. The database server cannot write orupdate data until the checkpoint ends.

Uptime indicates how long the database server has been running.

Sh_mem is the size of database server shared memory, expressed inkilobytes.

Utilities 3-93


A sample header for Dynamic Server follows:

Dynamic Server Version 9.20.UC1--On-Line--Up 15:11:41--9216 Kbytes

♦

Extended Parallel Server displays a similar header. ♦

Logs Full Subheader

If the database server is blocked, the onstat header output includes an extraline that reads as follows:

Blocked: reason(s)

The reason can be one or more of the following.

Reason Explanation

CKPT Checkpoint

LONGTX Long transaction

ARCHIVE Ongoing storage-space backup

MEDIA_FAILURE Media failure

HANG_SYSTEM Database server failure

DBS_DROP Dropping a dbspace

DDR Discrete data replication (IDS)

LBU Logs full high-water mark

IDS

XPS



Option DescriptionsYou can combine multiple onstat option flags in a single command.

No Options

If you invoke onstat without any options, the command is interpreted asonstat -pu (-p option and -u option).

The onstat -- Option

The -- option displays a listing of all onstat options and their functions. Thisoption is the only option flag that you cannot combine with any other flag.

The onstat -a Option

The -a option is interpreted as onstat -cuskbtdlp, and output is displayed inthat order. For an explanation of each option, refer to the appropriate flag inthe paragraphs that follow.

The onstat -b Option

The -b option displays information about buffers currently in use, includingthe total number of resident pages in the buffer pool. (For information aboutall buffers, not just those in use, refer to onstat -B. For information about thebig buffers, refer to onstat -g iob.) You can interpret output from the -b optionas follows:

address is the address of the buffer header in the buffer table.

userthread is the address of the most recent user thread to access thebuffer table. Many user threads might be reading the samebuffer concurrently.

flgs uses the following flag bits to describe the buffer:

0x01 Modified data

0x02 Data

0x04 LRU

Utilities 3-95


0x08 Error

pagenum is the physical page number on the disk.

memaddr is the buffer memory address.

nslots is the number of slot-table entries in the page. This fieldindicates the number of rows (or portions of a row) that arestored on the page.

pgflgs uses the following values, alone or in combination, to describethe page type:

1 Data page

2 Tblspace page

4 Free-list page

8 Chunk free-list page

9 Remainder data page

b Partition resident blobpage

c Blobspace resident blobpage (IDS)

Reserved (XPS)

d Blob chunk free-list bit page

e Blob chunk blob map page

10 B-tree node page

20 B-tree root-node page

40 B-tree branch-node page

80 B-tree leaf-node page

100 Logical-log page

200 Last page of logical log

400 Sync page of logical log



The maximum number of buffers available is specified as BUFFERS in theONCONFIG file.

The -b and -B options also provide summary information about the numberof modified buffers, the total number of resident pages in the buffer pool, thetotal number of buffers available, the number of hash buckets available, andthe size of the buffer in bytes (the page size).

123 modified, 23 resident, 2000 total, 2048 hash buckets, 2048 buffer size.

♦

The -b and -B options also provide summary information about the numberof modified buffers, the total number of buffers, the number of hash buckets,and the buffer size.

123 modified, 200 total, 256 hash buckets, 4096 buffer size.

♦

800 Physical log

1000 Reserved root page

2000 No physical log required

8000 B-tree leaf with default flags

xflgs uses the following flag bits to describe buffer access:

0x10

0x80

share lock

exclusive lock

owner is the user thread that set the xflgs buffer flag.

waitlist is the address of the first user thread that is waiting for accessto this buffer. For a complete list of all threads waiting for thebuffer, refer to “The onstat -X Option” on page 3-131.

IDS

XPS

Utilities 3-97


The onstat -c Option

Use the onstat -c option to display the contents of the ONCONFIG file. Thedatabase server first checks if you have assigned a value to the environmentvariable ONCONFIG.

On UNIX, if you have set ONCONFIG, onstat -c displays the contents of the$INFORMIXDIR/etc/$ONCONFIG file. If not, by default, onstat -c displays thecontents of $INFORMIXDIR/etc/onconfig.

On Windows NT, if you have set ONCONFIG, onstat -c displays the contentsof the %INFORMIXDIR%\etc\%ONCONFIG% file. If not, by default, onstat -cdisplays the contents of %INFORMIXDIR%\etc\onconfig.

The onstat -d Option

Use the -d option to display information for chunks in each storage space.You can interpret output from this option as follows. The first section of thedisplay describes the storage spaces:

address is the address of the storage space in the shared-memory spacetable.

number is the unique ID number of the storage space assigned atcreation.

flags uses the following hexadecimal values to describe eachstorage space:

0x0001 No mirror

0x0002 Mirror

0x0004 Down

0x0008 Newly mirrored

0x0010 Blobspace (IDS)

0x0020 Blobspace on removable media (IDS)

0x0040 Blobspace is on optical media (IDS)

0x0080 Blobspace is dropped (IDS)



0x0100 Blobspace is the optical STAGEBLOB(IDS)

0x0200 Space is being recovered

0x0400 Space is fully recovered

0x0800 Logical log is being recovered

0x1000 Table in dbspace is dropped

0x2000 Temporary dbspace

0x4000 Blobspace is being backed up (IDS)

0x8000 Root dbspace (XPS)Sbspace (IDS)

0x00010000 Critical dbspace (XPS)Physical or logical log changed (IDS)

0x00020000 No log replay required (XPS)Dbspace or chunk tables havechanged (IDS)

0x0040000 Dbspace added by ALTER DBSLICE(XPS)

0x0080000 Dbspace does not contain a logslice(XPS)

0x0100000 Dbspace or chunk tables havechanged (XPS)

fchunk is the ID number of the first chunk.

nchunks is the number of chunks in the storage space.

flags uses the following letter codes to describe each storage space:

Position 1: M Mirrored

N Not Mirrored

Position 2: X Newly mirrored

Utilities 3-99


The line immediately following the storage-space list includes the number ofactive spaces (the current number of dbspaces in the database server instanceincluding the rootdbs) and the number of total spaces.

Active spaces refers to the current number of storage spaces in the databaseserver instance including the rootdbs. Total refers to total allowable spaces forthis database server instance.

The second section of the onstat -d output describes the chunks:

P Physically recovered, waiting for P --logical recovery

L Being logically recovered

R Being recovered

Position 3: B Blobspace (IDS)

S Sbspace (IDS)

S Skip logical replay for this dbspace(XPS)

owner is the owner of the storage space.

name is the name of the storage space.

address is the address of the chunk.

chk/dbs is the chunk number and the associated space number.

offset is the offset into the file or raw device in pages.

size is the size of the chunk in pages.

free is the number of free pages in the chunk for a dbspace.

For a blobspace, a tilde indicates an approximate number offree blobpages. (IDS)

For an sbspace, indicates the number of free pages of user dataspace and total user data space. (IDS)



The line immediately following the chunk list displays the number of activechunks (including the root chunk) and the total number of chunks.

Using onstat -d with Sbspaces

For information about using onstat -d to determine the size of sbspaces, user-data areas, and metadata areas, see monitoring sbspaces in the PerformanceGuide.

bpages is the size of the chunk in blobpages. Blobpages can be largerthan disk pages; therefore, the bpages value can be less than thesize value. (IDS)

for an sbspace, is the size of the chunk in sbpages. (IDS)

is blank. (XPS)

flags provides the chunk status information as follows:

Position 1: P Primary

Mirror

On-line

Down

Newly mirrored

Inconsistent

Dbspace

Blobspace (IDS)

M

Position 2: O

D

X

I

Position 3: -

B

S Sbspace (IDS)

T Temporary dbspace

pathname is the pathname of the physical device.

IDS

Utilities 3-101


Freeing Blobpages and Timing of the onstat -d Command

Occasionally, the timing of the onstat -d command can affect the utilityoutput. Timing becomes a factor in two cases. The first case occurs immedi-ately after blobspace blobpages are allocated. The onstat -d routine looksdirectly at the disk to obtain blobpage statistics from the blobspace free-mappage. If blobpages were recently allocated, onstat -d might not reflect the newallocation. This situation could arise if you execute onstat -d while thenewest version of the blobspace free-map page remains in a memory bufferand is not yet flushed to disk.

The second case in which timing affects output occurs after blobspaceblobpages are freed. The onstat -d output does not show a blobpage as freeuntil the logical log in which the page or pages were deallocated is freed. Thatis, if you modify simple-large-object data, onstat -d shows that the pageswhere the obsolete simple-large-object data is stored are still in use until youback up and free the logical log that contains the modifying statement.

The oncheck -pB command, which examines the disk pages, does not reflectthis timing nuance. If you delete simple-large-object data from a blobspace,oncheck -pB output reflects the freed space immediately. For this reason,output from onstat -d and oncheck -pB might appear to be inconsistent.

For information about page reads and page writes, refer to onstat -D.

The onstat -D Option

Use the -D option to display page-read and page-write information for thefirst 50 chunks in each space. All but two of the fields that appear in the -Doutput also appear in the onstat -d output. You can interpret the two fieldsthat are unique to the -D output as follows:

page Rd is the number of pages read.

page Wr is the number of pages written.

IDS



The onstat -f Option

Use the -f option to list the dbspaces that the dataskip feature currentlyaffects. The -f option lists both the dbspaces that were set with the DATASKIPconfiguration parameter and the -f option of onspaces. When you executeonstat -f, the database server displays one of the following three outputs:

■ Dataskip is OFF for all dbspaces.

■ Dataskip is ON for all dbspaces.

■ Dataskip is ON for the following dbspaces:dbspace1 dbspace2...

The onstat -F Option

Use the -F option to display a count for each type of write that flushes pagesto disk. You can interpret output from this option as follows:

Fg Writes is the number of times that a foreground write occurred.

LRU Writes is the number of times that an LRU write occurred.

Chunk Writes is the number of times that a chunk write occurred.

address is the address of the user structure assigned to thispage-cleaner thread.

flusher is the page-cleaner number.

state uses the following codes to indicate the current page-cleaneractivity:

C Chunk write

E Exit

I Cleaner is idle.

L LRU queue

Utilities 3-103


The onstat -g Monitoring Options

The following onstat -g options are provided for support and debuggingonly. You can include only one of these options per onstat -g command Formore information, see yourPerformance Guide.

The exit code indicates either that the database server isperforming a shutdown or that a page cleaner did not returnfrom its write in a specific amount of time. When anoperation fails to complete within the allotted time, thissituation is known as a time-out condition. The databaseserver does not know what happened to the cleaner, so it ismarked as exit. In either case, the cleaner thread eventuallyexits.

data provides additional information in concert with the statefield. If state is C, data is the chunk number to which the pagecleaner is writing buffers. If state is L, data is the LRU queuefrom which the page cleaner is writing. The data value isdisplayed as a decimal, followed by an equal sign, andrepeated as a hexadecimal.

onstat -g Option IDS XPS Topic or Function

-g act ✔ ✔ Prints active threads.

-g afr pool name |session id

✔ ✔ Prints allocated memory fragments for aspecified session or shared-memory pool.Each session is allocated a pool of sharedmemory.

To obtain the pool name, see the -memoption.

-g all ✔ ✔ Prints all multithreading information.

-g ath ✔ ✔ Prints all threads. The sqlmain threadsrepresent client sessions, and the rstcbvalue corresponds to the user field of theonstat -u command.

(1 of 6)



-g bus ✔ Prints current backup scheduler sessions,backups in progress, and backups to beperformed. Issue from any coserver.

-g bus_sm ✔ Prints current storage manager configu-ration and active work. Issue from anycoserver.

-g cac agg ✔ Prints the definitions for user-definedaggregates that are currently in the cache.

-g cac stmt ✔ Prints the contents of the SQL statementcache.

-g con ✔ ✔ Prints conditions with waiters.

-g dfm ✔ Prints data flow information betweencoservers. Can be used with the xctl utility.

-g dic table ✔ ✔ Without any parameters, prints one line ofinformation for each table cached in theshared-memory dictionary.

If given a specific table name as aparameter, prints internal SQL informationfor that table.

Also shows the following information:State of violations (XPS)

For more information, see your PerformanceGuide.

-g dll ✔ ✔ Prints a list of dynamic libraries that havebeen loaded.

-g dri ✔ Prints data-replication information. Seemonitoring high-availability data-repli-cation status in the Administrator’s Guide.

-g dsc ✔ ✔ Prints data-distribution cache information.

-g ffr pool name |session id

✔ ✔ Prints free fragments for a pool of sharedmemory.


(2 of 6)

Utilities 3-105


-g glo ✔ ✔ Prints global multithreading information.This information includes CPU use infor-mation about the virtual processors, thetotal number of sessions, and other multi-threading global counters.

-g ioa ✔ ✔ Prints combined information from-g ioq, -g iov, and -g iob.

-g iob ✔ ✔ Prints big-buffer use by I/O virtual-processor class.

-g iof ✔ ✔ Prints asynchronous I/O statistics by chunkor file. This option is similar to the -Doption, except that information onnonchunk files is also displayed. It includesinformation about temporary files and sort-work files.

-g iog ✔ ✔ Prints AIO global information.

-g ioq queue name ✔ ✔ Prints pending I/O operations for the queuename. If given the gfd or kaio queue name, aqueue for each CPU VP is displayed. Ifqueue name is omitted, I/O statistics for allqueues are displayed.

-g iov ✔ ✔ Prints asynchronous I/O statistics byvirtual processor.

-g lmx ✔ ✔ Prints all locked mutexes.

-g mem pool name |session id

✔ ✔ Prints memory statistics for a pool. Sessionpools are named with the session number. Ifno argument is provided, informationabout all pools is displayed.

-g mgm ✔ Prints Memory Grant Manager resourceinformation.

-g nbm ✔ ✔ Prints block bit map for the nonresidentsegments, one bit per 8-kilobyte block. Bitset indicates block free.


(3 of 6)



-g nsc client id ✔ ✔ Prints shared-memory status by client id. Ifclient id is omitted, all client status areas aredisplayed.

This command prints the same status dataas the nss command.

-g nsd ✔ ✔ Prints network shared-memory data forpoll threads.

-g nss session id ✔ ✔ Prints network shared-memory status bysession id. If session id is omitted, all sessionstatus areas are displayed.

This command prints the same status dataas the nsc command.

-g nta ✔ ✔ Prints combined network statistics from -gntd, -g ntm, -g ntt, and -g ntu.

-g ntd ✔ ✔ Prints network statistics by service.

-g ntm ✔ ✔ Prints network mail statistics.

-g ntt ✔ ✔ Prints network user times.

-g ntu ✔ ✔ Prints network user statistics.

-g pos ✔ ✔ Prints $INFORMIXDIR/etc/.infos.DBSERVERNAME file for UNIXand %INFORMIXDIR%\etc\.infos.DBSERVERNAME for Windows NT.

-g ppf partitionnumber | 0

✔ ✔ Prints partition profile for partition number;0 prints profiles for all partitions.

If TBLSPACE_STATS configurationparameter is set to 0, displays:Partition profiles disabled.

-g prc ✔ ✔ Prints information about SPL routine cache.

-g qst ✔ ✔ Prints queue statistics.

-g rbm ✔ ✔ Prints block bit map for the residentsegment (communication message area).


(4 of 6)

Utilities 3-107


-g rea ✔ ✔ Prints ready threads.

-g rgm ✔ Prints Resource Grant Manager infor-mation. Issue from coserver 1 only. Can beused with the xctl utility.

-g sch ✔ ✔ Prints the number of semaphore opera-tions, spins, and busy waits for each virtualprocessor.

-g seg ✔ ✔ Prints shared-memory-segment statistics.This option shows how many segments areattached and their sizes.

-g ses session id ✔ ✔ Prints session information by session id. Ifsession id is missing, a one-line summary ofeach session prints.

Can be used with the xctl utility. (XPS)

-g sle ✔ ✔ Prints all sleeping threads.

-g spi ✔ ✔ Prints spin locks that virtual processorshave spun more than 10,000 times toacquire. These spin locks are calledlongspins. The total number of longspins isprinted in the heading of the glo command.Excessive longspins might indicate anoverloaded system, too many virtualprocessors for a given computer or node, oran internal problem. To reduce longspins,reduce the number of virtual processors(generally class CPU), reduce the load onthe computer, or use the no-age or processoraffinity features.

-g sql session id ✔ ✔ Prints SQL information by session id. Ifsession id is omitted, a one-line summary foreach session prints.

Can be used with the xctl utility. (XPS)

-g stk tid ✔ ✔ Dumps stack of thread specified by threadID. This option is not supported on allplatforms and is not always accurate.


(5 of 6)



-g sts ✔ ✔ Prints maximum and current stack use perthread.

-g tpf tid ✔ ✔ Prints thread profile for tid; 0 prints profilesfor all threads.

-g ufr pool name |session id

✔ ✔ Prints allocated fragments by use.

-g wai ✔ ✔ Prints waiting threads; all threads waitingon mutex or condition, or yielding.

-g wmx ✔ ✔ Prints all mutexes with waiters.

-g wst ✔ ✔ Prints wait statistics.

-g xmf ✔ Prints communication informationbetween coservers. Can be used with thexctl utility.

-g xmp ✔ Prints information about the querysegments and SQL operators that arecurrently executing on a coserver. Issuefrom the connection coserver only. Can beused with xctl utility.

-g xqp qryid ✔ Prints information about a specific queryplan. Issue from the connection coserveronly.

-g xqs qryid ✔ Prints query statistics for an active plan.Issue from the connection coserver only.Can be used with the xctl utility.


(6 of 6)

Utilities 3-109


The onstat -i Option

Use the -i option to put onstat in interactive mode. In interactive mode, youcan enter multiple onstat options per session, but only one at a time. Anonstat prompt appears and allows you to enter an option.

In interactive mode, do not precede the option with a dash.

Two additional options, r seconds and rz seconds, are available in interactivemode. The r seconds option is similar to the current onstat -r seconds option,which repeatedly generates a display. If an administrator executes r secondsat the interactive-mode prompt, the prompt changes to reflect the specifiedinterval in seconds and reappears, waiting for the next command. In thefollowing example, the display generated by the next command repeatsevery three seconds:

onstat> r 3onstat[3]>

The rz seconds option enables you to repeat the next command as specifiedand set all profile counters to 0 between each execution.

To terminate interactive mode, press CTRL-D.

To terminate a repeating sequence, press CTRL-C.



The onstat -k Option

Use the -k option to display information about active locks. You can interpretoutput from this option as follows:

address is the address of the lock in the lock table. If a user thread iswaiting for this lock, the address of the lock appears in thewait field of the onstat -u (users) output.

wtlist is the first entry in the list of user threads that is waiting forthe lock, if there is one.

owner is the shared-memory address of the thread that is holdingthe lock. This address corresponds to the address in theaddress field of onstat -u (users) output.

lklist is the next lock in a linked list of locks held by the owner justlisted.

type uses the following codes to indicate the type of lock:

HDR Header

B Bytes

S Shared

X Exclusive

I Intent

U Update

IX Intent-exclusive

IS Intent-shared

SIX Shared, intent-exclusive

tblsnum (IDS)

lockid (XPS)

is the tblspace number of the locked resource.

Utilities 3-111


The maximum number of locks available is specified as LOCKS in theONCONFIG file.

The onstat -K Option

Use the -K option to display information about byte-range locks held.

rowid is the row identification number. The rowid provides thefollowing lock information:

■ If the rowid equals zero, the lock is a table lock.

■ If the rowid ends in two zeros, the lock is a pagelock.

■ If the rowid is six digits or fewer and does not endin zero, the lock is probably a row lock.

■ If the rowid is more than six digits, the lock isprobably an index key-value lock.

key#/bsiz is the index key number, or the number of bytes locked for aVARCHAR lock.



The onstat -l Option

Use the -l option to display information about physical and logical logs. Youcan interpret output from this option as follows. The first section of thedisplay describes the physical-log configuration:

The second section of the onstat -l display describes the logical-logconfiguration:

buffer is the number of the physical-log buffer.

bufused is the number of pages of the physical-log buffer that are used.

bufsize is the size of each physical-log buffer in pages.

numpages is the number of pages written to the physical log.

numwrits is the number of writes to disk.

pages/io is calculated as numpages/numwrits. This value indicates howeffectively physical-log writes are being buffered.

phybegin is the physical page number of the beginning of the log.

physize is the size of the physical log in pages.

phypos is the current position in the log where the next log-recordwrite is to occur.

phyused is the number of pages used in the log.

%used is the percent of pages used.

buffer is the number of the logical-log buffer.

bufused is the number of pages used in the logical-log buffer.

bufsize is the size of each logical-log buffer in pages.

numrecs is the number of records written.

numpages is the number of pages written.

Utilities 3-113


The following fields are repeated for each logical-log file:

numwrits is the number of writes to the logical log.

recs/pages is calculated as numrecs/numpages. You cannot affect thisvalue. Different types of operations generate different types(and sizes) of records.

pages/io is calculated as numpages/numwrits. You can affect this valueby changing the size of the logical-log buffer (specified asLOGBUFF in the ONCONFIG file) or by changing the loggingmode of the database (from buffered to unbuffered, or viceversa).

address is the address of the log-file descriptor.

number is logid number for the logical-log file.

flags provides the status of each log as follows:

A Newly added

B Backed up

C Current logical-log file

F Free, available for use

L The most recent checkpoint record

U Used

uniqid is the unique ID number of the log.

begin is the beginning page of the log file.

size is the size of the log in pages.

used is the number of pages used.

%used is the percent of pages used.



The onstat -m Option

Use the -m option to display the 20 most-recent lines of the system messagelog.

Output from this option lists the full pathname of the message-log file andthe 20 file entries. A date-and-time header separates the entries for each day.A time stamp prefaces single entries within each day. The name of themessage log is specified as MSGPATH in the ONCONFIG file.

The onstat -O Option

Use the -O option of the onstat utility to display information about theOptical Subsystem memory cache and staging-area blobspace. You caninterpret output from this option as follows. The totals shown in the displayaccumulate from session to session. The database server resets the totals to 0only when you execute onstat -z.

The first section of the display provides the following information on system-cache totals:

size is the size that the OPCACHEMAX configuration parameterspecifies.

alloc is the number of 1-kilobyte allocations to the cache.

avail describes how much of alloc (in kilobytes) is not used.

number is the number of simple large objects that the database serversuccessfully put in the cache without overflowing.

kbytes is the number of kilobytes of TEXT or BYTE data that the databaseserver put in the cache without overflowing.

number is the number of simple large objects that the database serverwrote to the staging-area blobspace.

kbytes is the number of kilobytes of TEXT or BYTE data that the databaseserver wrote to the staging-area blobspace.

IDS

Utilities 3-115


Although the size output indicates the amount of memory that is specified inthe configuration parameter OPCACHEMAX, the database server does notallocate memory to OPCACHEMAX until necessary. Therefore, the allocoutput reflects only the number of 1-kilobyte allocations of the largest simplelarge object that has been processed. When the values in the alloc and availoutput are equal to each other, the cache is empty.

The second section of the display describes the following user-cache totalsinformation:

The last line of the display lists the total number of sessions that are using thecache.

SID is the session ID for the user.

user is the user ID of the client.

size is the size specified in the INFORMIXOPCACHE environmentvariable, if it is set. If you do not set the INFORMIXOPCACHEenvironment variable, the database server uses the size that youspecify in the configuration parameter OPCACHEMAX.

number is the number of simple large objects that the database server putinto cache without overflowing.

kbytes is the number of kilobytes of TEXT or BYTE data that the databaseserver put in the cache without overflowing.

number is the number of simple large objects that the database serverwrote to the staging-area blobspace.

kbytes is the number of kilobytes of TEXT or BYTE data that the databaseserver wrote to the staging-area blobspace.



The onstat -p Option

Use the -p option to display profile counts either since you started thedatabase server or since you ran onstat with the -z option.

The first portion of the display describes reads and writes.

Reads and writes are tabulated in three categories: from disk, from buffers,and number of pages (read or written).

The first %cached field is a measure of the number of reads from bufferscompared to reads from disk. The second %cached field is a measure of thenumber of writes to buffers compared to writes to disk.

The database server buffers information and writes to the disk in pages. Forthis reason, the number of disk writes displayed as dskwrits is usually lessthan the number of writes that an individual user executes:

dskreads is the number of actual reads from disk.

pagreads is the number of pages read.

bufreads is the number of reads from shared memory.

%cached is the percent of reads cached, calculated as follows:

100 * (bufreads - dskreads) / bufreads

If bufreads exceeds the maximum integer (or long) value, itsinternal representation becomes a negative number, but thevalue appears as 0.0.

dskwrits is the actual number of physical writes to disk. This numberincludes the writes for the physical and logical logs reported inonstat -l.

pagwrits is the number of pages written.

bufwrits is the number of writes to shared memory.

%cached is the percent of writes cached, calculated as follows:

100 *(bufwrits - dskwrits) / bufwrits

If dskwrits exceeds bufwrits, the value appears as 0.0.

Utilities 3-117


The next portion of the -p display tabulates the number of times differentISAM calls were executed. The calls occur at the lowest level of operation anddo not necessarily correspond one-to-one with SQL statement execution. Asingle query might generate multiple ISAM calls. These statistics are gatheredacross the database server and cannot be used to monitor activity on a singledatabase unless only one database is active or only one database exists:

The third portion of the -p display tracks the number of times that a resourcewas requested when none was available:

isamtot is the total number of calls.

open increments when a tblspace is opened.

start increments the pointer within an index.

read increments when the read function is called.

write increments with each write call.

rewrite increments when an update occurs.

delete increments when a row is deleted.

commit increments each time that an iscommit() call is made. No one-to-one correspondence exists between this value and thenumber of explicit COMMIT WORK statements that areexecuted.

rollbk increments when a transaction is rolled back.

ovlock is the number of times that the database server attempted toexceed the maximum number of locks (specified as LOCKS inthe ONCONFIG file).

ovuserthread is the number of times that a user attempted to exceed themaximum number of user threads.

ovbuff is the number of times that the database server could not finda free shared-memory buffer. When no buffers are free, thedatabase server writes a dirty buffer to disk and then tries tofind a free buffer.



The next portion of the -p display contains miscellaneous information, asfollows:

The last portion of the -p display contains the following information:

usercpu is the total user CPU time that all user threads use, expressedin seconds. This entry is updated every 15 seconds.

syscpu is the total system CPU time that all user threads use, expressedin seconds. This entry is updated every 15 seconds.

numckpts is the number of checkpoints since the boot time.

flushes is the number of times that the buffer pool has been flushed tothe disk.

bufwaits increments each time that a user thread must wait for a buffer.

lokwaits increments each time that a user thread must wait for a lock.

lockreqs increments each time that a lock is requested.

deadlks increments each time that a potential deadlock is detected andprevented.

dltouts increments each time that the distributed deadlock time-outvalue is exceeded while a user thread is waiting for a lock.

ckpwaits is the number of checkpoint waits.

compress increments each time that a data page is compressed.

seqscans increments for each sequential scan.

ixda-RA is the count of read-aheads that go from index leaves to datapages.

idx-RA is the count of read-aheads that traverse index leaves.

Utilities 3-119


The onstat -P Option

Use the -P option to display for all partitions the partition number and thepages in the buffer pool that belong to the partition.

da-RA is the count of data-path-only scans.

RA-pgsused indicates the number of pages used that the database serverread ahead. If this number is significantly less than the totalnumber of pages read ahead, the read-ahead parametersmight be set too high.

lchwaits increments when a thread waits to gain access to ashared-memory resource.

partnum is the partition number

total is the total number of partitions

btree is the number of B-tree pages in the partition

data is the number of data pages in the partition

other is the number of other pages in the partition

resident is the number of resident pages in the partition

dirty is the number of dirty pages in the partition



The onstat -R Option

Use the -R option to display detailed information about the LRU queues,FLRU queues, and MLRU queues. For an in-depth discussion of the threetypes of queues, see LRU queues in the shared-memory chapter of the Admin-istrator’s Guide.

For each queue, onstat -R lists the number of buffers in the queue and thenumber and percentage of buffers that have been modified. You can interpretoutput from this option as follows:

# shows the queue number. Each LRU queue is composed of twosubqueues: an FLRU queue and a MLRU queue. (For adefinition of FLRU and MLRU queues, see LRU queues in theshared-memory chapter of the Administrator’s Guide.) Thus,queues 0 and 1 belong to the first LRU queue, queues 2 and 3belong to the second LRU queue, and so on.

f/m identifies queue type. This field has four possible values:

f Free LRU queue

In this context, free means not modified. Althoughnearly all the buffers in an LRU queue are availablefor use, the database server attempts to use buffersfrom the FLRU queue rather than the MLRU queue.(A modified buffer must be written to disk before thedatabase server can use the buffer.)

F Free LRU with fewest elements

The database server uses this estimate to determinewhere to put unmodified (free) buffers next.

m MLRU queue

M MLRU queue that a flusher is cleaning

Utilities 3-121


The -R option also lists the priority levels. ♦

Summary information follows the individual LRU queue information. Youcan interpret the summary information as follows:

length tracks the length of the queue measured in buffers.

% of shows the percent of LRU queue that this subqueue composes.For example, suppose that an LRU queue has 50 buffers, with30 of those buffers in the MLRU queue and 20 in the FLRUqueue. The % of column would list percents of 60.00 and 40.00,respectively.

pair total provides the total number of buffers in this LRU queue.

dirty is the total number of buffers that have been modified in allLRU queues.

queued is the total number of buffers in LRU queues.

total is the total number of buffers.

hash buckets is the number of hash buckets.

buffer size is the size of each buffer.

start clean is the value of LRU_MAX_DIRTY.

stop at is the value of LRU_MIN_DIRTY.

IDS



The onstat -s Option

Use the -s option to display general latch information. You can interpretoutput from this option as follows:

name identifies the resource that the latch controls with thefollowing abbreviations:

archive Storage-space backup

bf Buffers

bh Hash buffers

chunks Chunk table

ckpt Checkpoints

dbspace Dbspace table

flushctl Page-flusher control

flushr Page cleaners

locks Lock table

loglog Logical log

LRU LRU queues

physb1 First physical-log buffer

physb2 Second physical-log buffer

physlog Physical log

pt Tblspace tblspace

tblsps Tblspace table

users User table

address is the address of the latch. This address appears in the -u(users) output wait field if a thread is waiting for the latch.

Utilities 3-123


lock indicates if the latch is locked and set. The codes that indicatethe lock status (1 or 0) are computer dependent.

wait indicates if any user thread is waiting for the latch.

userthread is the shared-memory address of the owner of the latch. Incontrast to the user fields of other onstat options, this fielddoes not contain the rstcb address because not all threads thatown latches are user threads. Instead this field contains thethread-control block address, which all threads have. To obtainthe rstcb address from the tcb address, examine the output ofthe onstat -g ath option, which lists both addresses for eachuser thread.



The onstat -t Option

Use the -t option to display tblspace information for active tblspaces,including whether tblspaces are memory resident. You can interpret outputfrom this option as follows:

The -t option also lists the number of active tblspaces, the number of availabletblspaces, and the number of available hash buckets.

n is a counter of open tblspaces.

address is the address of the tblspace in the shared-memory tblspacetable.

flgs uses the following flag bits to describe the flag:

0x01 Busy

0x02 Dirty (modified pages that have not been flushedto disk)

ucnt is the usage count, which indicates the number of user threadscurrently accessing the tblspace.

tblnum is the tblspace number expressed as a hexadecimal value. Theinteger equivalent appears as the partnum value in thesystables system catalog table.

lockid is the table ID. (XPS)

physaddr is the physical address (on disk) of the tblspace.

npages is the number of pages allocated to the tblspace.

nused is the number of used pages in the tblspace.

npdata is the number of data pages used.

nrows is the number of data rows used.

nextns is the number of noncontiguous extents allocated. Thisnumber is not the same as the number of times that a nextextent has been allocated.

resident indicates whether tblspace is memory-resident; 1 = yes,0 = no. (IDS)

Utilities 3-125


The onstat -u Option

Use the -u option to print a profile of user activity. The -u option provides thefollowing output for each user thread.

address is the shared-memory address of the user thread (in the usertable). Compare this address with the addresses displayed inthe -s output (latches); the -b, -B, and -X output (buffers); andthe -k output (locks) to learn what resources this thread isholding or waiting for.

flags provides the status of the session.

The flag codes for position 1:

B Waiting for a buffer

C Waiting for a checkpoint

G Waiting for a write of the logical-log buffer

L Waiting for a lock

S Waiting for mutex

T Waiting for a transaction

Y Waiting for condition

X Waiting for a transaction cleanup (rollback)

DEFUNCT The thread has incurred a serious assertion failure,and has been suspended to allow other threads tocontinue their work. If this status flag appears, referto Appendix C, “Thread Suspension,” forinstructions.

The flag code for position 2:

* Transaction active during an I/O failure


A A dbspace backup thread



For other values that appear here, see the third position of flagcodes for the -x option.


P Primary thread for a session


R Reading

X Thread in critical section (IDS)

Transaction is XA prepared. The database server (inan X/Open DTP environment) is prepared to commitor is currently in the process of committing. (XPS)


B A B-tree cleaner thread

C Terminated user thread waiting for cleanup

D A daemon thread

F A page-cleaner thread

M Special ON-Monitor (monitor) thread (IDS, UNIX)

sessid is the session identification number. During operations such asparallel sorting and parallel index building, a session mighthave many user threads associated with it. For this reason, thesession ID identifies each unique session.

user is the user login name (derived from the operating system).

tty indicates the tty that the user is using (derived from theoperating system).

wait if the user thread is waiting for a specific latch or lock, this fielddisplays the address of the resource. Use this address to map toinformation provided in the -s (latch) or -k (lock) output.

tout is the number of seconds left in the current wait. If the value is0, the user thread is not waiting for a latch or lock. If the valueis -1, the user thread is in an indefinite wait.

Utilities 3-127


Figure 3-3 shows output from onstat -u. The last line of onstat -u outputdisplays the maximum number of concurrent user threads that wereallocated since you initialized the database server. For example, the last lineof a sample onstat -u output is as follows:

4 active, 128 total, 17 maximum concurrent

The last part of the line, 17 maximum concurrent, indicates that themaximum number of user threads that were running concurrently since youinitialized the database server is 17.

The output also indicates the number of active users and the maximumnumber of users allowed.

locks is the number of locks that the user thread is holding. (The -koutput should include a listing for each lock held.)

nreads is the number of disk reads that the user thread has executed.

nwrites is the number of write calls that the user thread has executed.All write calls are writes to the shared-memory buffer cache.

Userthreadsaddress flags sessid user tty wait tout locks nreads nwrites80eb8c ---P--D 0 informix - 0 0 0 33 1980ef18 ---P--F 0 informix - 0 0 0 0 080f2a4 ---P--B 3 informix - 0 0 0 0 080f630 ---P--D 0 informix - 0 0 0 0 04 active, 128 total, 17 maximum concurrent

Figure 3-3Output from

onstat -u



The onstat -x Option

Use the -x option to display transaction information on the database server.

The transaction information is required only in the following situations:

■ X/Open environment

■ Database server participation in distributed queries (formerly calledINFORMIX-STAR) ♦

You can interpret output from onstat -x as follows:

address is the shared-memory address of the transaction structure.

flags The flag codes for position 1:

A User thread attached to the transaction

S TP/XA suspended transaction (IDS)

C TP/XA waiting for rollback (IDS)


B Begin work

P Distributed query prepared for commit (IDS)

X TP/XA prepared for commit (IDS)

C Committing or committed

R Rolling back or rolled back

H Heuristically rolling back or rolled back


G Global transaction

C Distributed query coordinator (IDS)

S Distributed query subordinate (IDS)

B Both distributed query coordinator and subordinate(IDS)

IDS

Utilities 3-129


Figure 3-4 shows output from onstat -x. The last line of the onstat -x outputdisplays the maximum number of concurrent transactions since youinitialized the database server. For example, the last line of onstat -u outputis as follows:

11 active, 128 total, 6 maximum concurrent

The last part of the line, 6 maximum concurrent, indicates that the maximumnumber of transactions that were running concurrently since you initializedthe database server is 6.

userthread is the user that owns the transaction (rstcb address).

locks is the number of locks that the transaction holds.

log begin is the log in which begin work was logged.

isolation is the isolation level.

retries is the attempts to start a recovery thread for the distributedquery. (IDS)

coordinator is the transaction coordinator when this transaction is asubordinate.

Transactionsaddress flags userthread locks log begin isolation retrys coordinator40a7e4 A---- 406464 0 0 COMMIT 040a938 A---- 4067c4 0 0 COMMIT 040aa8c A---- 406b24 0 0 COMMIT 040abe0 A---- 40a124 0 0 COMMIT 011 active, 128 total, 6 maximum concurrent


onstat -x



The onstat -X Option

Use the -X option to obtain precise information about the threads that aresharing and waiting for buffers.

For each buffer in use, the -X option displays general buffer information thatis also available with either the -b or -B option. For an explanation of thesefields, refer to onstat -b on page 3-95.

Unique to the -X option are the sharers and waiter fields. More than onethread can share data in a buffer. The sharers field lists the addresses of alluser threads that share each buffer. During an update operation, a threadplaces an exclusive lock on a buffer, and no sharing occurs. In this situation,the waiter field lists the addresses of all user threads that are waiting for thebuffer.

The onstat -b and -B options contain a waitlist field that displays the addressof the first user thread that is waiting for the buffer. The -X option provides acomplete list of addresses for all waiting threads.

The maximum number of shared buffers is specified as BUFFERS in theONCONFIG file.

The onstat -z Option

Use the -z option to set the profile counts to 0.

If you use the -z option to reset and monitor the count of some fields, beaware that profile counts are incremented for all activity that occurs in anydatabase that the database server manages. Any user can reset the profilecounts and thus interfere with monitoring that another user is conducting.

Utilities 3-131


ontape: Log, Back Up, and Restore

ontape: Log, Back Up, and RestoreThe ontape utility lets you perform several different tasks. Alternatively, youcan use ON-Bar or ON-Archive to perform these tasks. For information aboutON-Bar, see the Backup and Restore Guide. For information about ON-Archive,see the Archive and Backup Guide.

The ontape utility lets you perform the following tasks:

■ Back up data that the database server manages

■ Change database-logging status

■ Back up logical-log files

■ Start continuous logical-log file backups

■ Restore data from an archive tape

■ Use data replication

On UNIX, you must be logged in as user root or user informix to executeontape. On Windows NT, you must be a member of the Informix-Admingroup.

IDS


Syntax

ABG refers to the Archive and Backup Guide. Syntax for ontape options otherthan -t and -l appears in that manual.

Things to Consider

If more than one tape is needed during data replication, ontape prompts foreach additional tape. Do not run ontape in background mode because youmight need to provide input from the terminal or window.

ontape Back Up Database Serversee ABG

Back Up Logical-LogFiles

see ABG

Start ContinuousLogical-Log Backups

see ABG

Restore Datafrom Backup

see ABG

Prepare forData Replication

p. 3-134

Change Database-Logging Status

see ABG

Utilities 3-133


Exit Codes

The ontape utility has two exit codes:

Prepare for Data Replication

Use the -p and -l options to replicate data initially in a pair of databaseservers that use data replication. For information on starting high-availability data replication for the first time, see the chapter on using high-availability data replication in the Administrator’s Guide.

0 indicates a normal exit from ontape.

1 indicates an exceptional condition.

Element Purpose Key Considerations-l Directs ontape to perform a logical restore

on all the storage spaces that have justbeen physically restored on the databaseserver in a data-replication pair.

Additional Information: This option rolls forwardlogical-log records from the last checkpoint up tothe last available logical-log record on disk.

-p Directs ontape to perform a physicalrestore of a database server.

Additional Information: Use this option toreplicate data before you initiate thedata-replication feature.

Prepare for DataReplication

-p

-l


onutil: Check, Define, and
Modify Storage Objects
onutil: Check, Define, and Modify Storage ObjectsThis section contains the following topics:

■ Overview of onutil commands

■ How to invoke onutil

■ Syntax for individual onutil commands

Overview of onutil CommandsThe onutil command-line utility modifies storage objects, checks theintegrity of certain objects, and often generates a diagnostic display. Theonutil utility performs many checks in parallel, utilizing the parallel-processing capabilities of Extended Parallel Server.

The onutil utility accepts commands that allow you to create, alter, anddelete cogroups and dbslices. You also can use onutil commands to configuredbspaces, logical logs, and logical logslices:

■ Cogroups

■ Dbslices

■ Dbspaces

■ Logical logs

■ Logical logslices

The onutil utility lets you check and display the following database charac-teristics if a connection to the database server is available:

■ The root reserved pages of each coserver

■ Chunks and extents of each coserver

■ Data rows of a table

■ Index keys

■ Index keys with rowids

■ Tblspace reports

■ Tblspace-allocation reports

■ Content of specified pages

XPS

Utilities 3-135

onutil: Check, Define, and Modify Storage Objects

■ System catalog tables of a database

The onutil utility can perform the following functions when the databaseserver is off-line:

■ Check and display the root reserved pages on one coserver

■ Dump a specified page

Important: The onutil utility runs with PDQ set to 0 regardless of the currentsetting of the PDQPRIORITY environment variable.

How to Invoke onutilBefore you invoke onutil, note the following items:

■ To execute the onutil CHECK options, you must be user informix orroot on UNIX.

■ You can invoke certain onutil commands in off-line mode. To startonutil in off-line mode, use the -o option.

onutil -o

You can execute the onutil command in the following input modes:

■ Input from a file

■ Interactive input

■ Single command

Important: Although onutil commands resemble SQL, you cannot use them inqueries, and onutil cannot use standard SQL statements. Neither DB-Access nor anyother SQL utility or application supports them. Only onutil supports them.

Running onutil with Input from a File

To invoke the onutil command with a file as input, enter the onutil commandfollowed by the name of the input file.

onutil filename

onutil -i filename



The onutil command executes each command as it reads the command fromthe input file. As each command completes successfully, onutil sends acompletion message to the standard output. If any error occurs while onutilis executing a command that is contained in an input file, onutil sends anerror message to the standard output and halts by default. If you invokeonutil with the -i option, processing continues after errors are detected.

Running onutil with Interactive Input

To invoke onutil for interactive input, enter the onutil command with noarguments. The onutil command collects input lines until you either includea semicolon to indicate that you have entered a complete onutil command ortype quit or the end-of-file character (typically CTRL-D) to exit.

Every new line starts with a prompt that consists of the line number and the> symbol. The line numbers help you locate the position of syntax errors. Youcan enter any number of commands during a single invocation of onutil.

As each command completes successfully, onutil sends a completionmessage to the standard output. If a syntax error or internal database servererror occurs during interactive operations, onutil displays an error messageand prompts for a new command.

The following example shows onutil running with interactive input:

% onutil1> CREATE DBSPACE acctgdbsp_12> CHUNK "/dev/bdbs_1" SIZE 1500;DBspace successfully added.3> QUIT;%

Warning: The onutil utility cannot check objects that are named “IN,” “WITH,” and“DATABASE,” because they are onutil keywords. Before you invoke onutil, renameany objects that contain these keywords. For example, if your database is namedwith, rename the database before you check it with onutil.

Running onutil as a Single Command

To invoke onutil for a single command, enter the onutil command with theoption at the command prompt. The following example shows how you canrun a single command without bringing up the onutil command interface:

onutil CHECK DATA IN database stores_demo

Utilities 3-137


Warning: If you run onutil from the command line, you must escape the doublequotes around the filename; otherwise, the UNIX shell returns an error.

Using the onutil CHECK OptionsOn Extended Parallel Server, use the onutil CHECK options because theoncheck utility is not supported. The sysmaster database must be builtbefore you invoke onutil CHECK commands. The onutil utility supports thefollowing commands for monitoring database server status:

Data Display and Error Reporting Options

The onutil CHECK commands have two data-display options:

■ DISPLAY

■ SAVE

The DISPLAY keyword displays output on the terminal for the client. Theoutput also is stored in DUMPDIR while the command is running, then thosefiles are displayed to the terminal and deleted. If errors are generated in caseof a failed check, errors are placed in DUMPDIR.

Command Reference

CHECK CATALOGS See page 3-170.

CHECK DATA See page 3-171.

CHECK INDEX See page 3-174.

CHECK INDEX WITH DATA See page 3-176.

CHECK INFO See page 3-178.

CHECK LOGS See page 3-181.

CHECK RESERVED See page 3-183.

CHECK SPACE See page 3-186.

DISPLAY PAGE See page 3-217.



If onutil encounters errors, the name of the file that contains diagnostic infor-mation is displayed on the terminal for the client. The diagnostic file resideson the coserver where the error is detected and can be found in the directorythat the DUMPDIR configuration parameter indicates.

The SAVE [IN filename] clause collects the data in files but does not display theoutput on the terminal for the client. The filename can contain a path relativeto the location where you run onutil, or it can be an absolute path.

Locking with onutil CHECK Options

The database server places a shared lock on tables when the onutil CHECKcommand checks system catalog tables or when you execute the onutilCHECK INDEX WITH DATA command. The database places a shared-intentlock for onutil CHECK options that check table data or indexes. A shared-intent lock allows other users to select, insert, update and delete rows, but nouser can delete the table during the locking operation.

Because data modification can occur with a shared-intent lock, onutil mustdistinguish between real corruption and temporary data inconsistencies. (Anexample of a temporary data inconsistency is the ever-changing structure ofa B-tree index.) The onutil CHECK utility uses time stamps to find data incon-sistencies. If onutil CHECK reports an inconsistency while it checks adatabase table or index, Informix recommends that you rerun the onutilCHECK command with the LOCK option. The LOCK option places a share lockon the table while the check is performed. Then, if the onutil CHECK...LOCKcommand reports data inconsistency, repair the data.

Using the onutil ALTER, CREATE, and DROP CommandsThe onutil utility supports the following commands for creating, modifying,and dropping database server storage objects:

■ ALTER DBSLICE ADD DBSPACE

Utilities 3-139


■ ALTER DBSPACE

❑ ADD CHUNK

❑ DROP CHUNK

❑ CHANGE STATUS OFFLINE/ONLINE CHUNK

❑ START MIRRORING

❑ STOP MIRRORING

■ ALTER LOGSLICE ADD LOG

■ CREATE COGROUP

■ CREATE DBSLICE

■ CREATE DBSPACE

■ CREATE LOGICAL LOG

■ CREATE LOGICAL LOGSLICE

■ DROP COGROUP

■ DROP DBSLICE

■ DROP DBSPACE

■ DROP LOGICAL LOG

■ DROP LOGSLICE

Identifiers in onutil CommandsAn identifier names a storage object such as a dbspace. The onutil commandsuse identifiers for the following objects:

■ Cogroup name (cogroup_name and cogroup_range_identifier)

■ Coserver name (coserver_name, coserver_list, andcoserver_range_identifier)

■ Dbslice name (dbslice_name)

■ Dbspace name (dbspace_name and dbspace_list)

■ Generated dbspace name (derived_dbspace_identifier)

■ Index name (index_name)

■ Logslice name (logslice_name)

■ Pathname (pathname_format)



A simple identifier is a string of at most 18 characters. The first character ofan identifier must be a letter. The remaining characters can be any combi-nation of letters, digits, or underscores.

Cogroup Name

You define the cogroup name in the onutil CREATE COGROUP command. Thedefault cogroup name is cogroup_all which includes all the coservers on thesystem.

Cogroup Range Identifier

A cogroup_range_identifier specifies one or more cogroup names to be created,checked, or dropped. Use cogroup_name or cogroup_range_identifier in thefollowing onutil commands.

Cogroup range identifiers can include embedded formatting characters ofthe following form:

%r(first..last)

These formatting characters have the following meaning:

Command Reference

ALTER DBSLICE ADD DBSPACE See page 3-150.

CREATE COGROUP See page 3-188.

CREATE DBSLICE See page 3-194.

DROP COGROUP See page 3-220.

%r(first..last) are formatting characters that are replaced by integervalues in the range that first and last specify to producea list of coserver names.

Utilities 3-141


For example, the following onutil command contains a cogroup rangeidentifier for cogroups eds.1_acctg and eds.2_acctg:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..2)_acctg;

Coserver Name

The database server automatically generates the coserver_name. A coservername has the following format:

dbservername.coserver_number

For more information about these configuration parameters, see“DBSERVERNAME” on page 1-38 and “COSERVER” on page 1-33.

Use a coserver name in the following onutil commands.

dbservername is the value that you specify in the DBSERVERNAMEconfiguration parameter.

coserver_number is the integer that you specify in each COSERVERconfiguration parameter.

Command Reference








CREATE DBSPACE See page 3-207.

DROP LOGICAL LOG See page 3-224.



Coserver List

The coserver_list specifies one or more coserver names to define as membersof a cogroup.

Syntax

Element Purpose Restrictions Syntax

prefix The alphabetic portion of thegenerated cogroup name thatprecedes the formattingcharacter

Each coserver name that ismatched by the combination ofthe prefix, formatting character,and suffix must not exceed 18characters.

See “Identifiers inonutil Commands”on page 3-140.

%c A formatting character thatonutil replaces with the coservernumber for each coserver in thelist of coservers

The coserver number is thevalue that you specified in theCOSERVER configurationparameter for this coserver.


%n A formatting character thatonutil replaces with the hostname of the node for eachcoserver in the generated list ofcoservers

The host name is the value thatyou specified in the NODEconfiguration parameter for thiscoserver.


%o A formatting character thatonutil replaces with the ordinalnumber of each coserver in thegenerated list of coservers

None. See “Identifiers inonutil Commands”on page 3-140.

(1 of 2)

" prefix

suffix

"

first( ).. last%r

,Coserver_List

. %c

%n

%o

Utilities 3-143


Usage

Use the coserver_list identifier to list coservers that can be included in a range.Use a coserver list identifier in the same onutil commands that use thecoserver range identifier on page 3-143. For a description of a coserver name,see “Coserver Name” on page 3-142.

For example, to include coservers eds.1, eds.3, and eds.7, you can list severalcoserver names. The following onutil command creates cogroupsacctg_cogroup and sales_cogroup from a list of coservers:

% onutil1> CREATE COGROUP acctg_cogroup2> CREATE COGROUP sales_cogroup3> FROM eds.1, eds.3, eds.7;

%r A formatting character thatindicates a range of successiveinteger values bounded by firstand last inclusively

Numbers within the range thatfall outside of the ordinal rangeof existing coservers are ignored.


first The starting integer value tosubstitute in a coserver name

This value must be a smallerinteger than last.

When last is in a FROM clause, itmust be one of the values that isspecified in the COSERVERconfiguration parameter.

This value must bean unsigned integer.

last The ending integer value tosubstitute for the coserver name

This value must be equal to orlarger than first.

When last is in a FROM clause, itmust be one of the values that isspecified in the COSERVERconfiguration parameter.

This value must bean unsigned integer.

suffix The alphabetic portion of thegenerated cogroup name thatfollows the formatting character

The combination of the prefix,formatting character, and suffixmust not exceed 18 characters.



(2 of 2)



Coserver Range Identifier

A coserver_range_identifier specifies one or more coserver names to define asmembers of a cogroup. For a description of a coserver name, see “CoserverName” on page 3-142.

Use a coserver range identifier in the following onutil commands.

Coserver range identifiers can include embedded formatting characters ofthe following form:

%r(first..last)

These formatting characters have the following meaning:

For example, the following onutil command contains a coserver rangeidentifier for coserver names eds.1 through eds.8:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..8);

Command Reference








DROP COGROUP See page 3-220.

%r(first..last) are formatting characters that are replaced by integer values inthe range that first and last specify to produce a list of coservernames.

Utilities 3-145


Dbslice Name

You define the dbslice name in the onutil CREATE DBSLICE command. Thedbslice name can be up to 18 characters.

Use a dbslice name in the following onutil commands.

Dbspace Name

You define the dbspace name when you create the dbspace with the onutilCREATE DBSPACE command. The dbspace name can be up to 18 characters.

Derived Dbspace Identifier

A derived_dbspace_identifier is generated for a dbspace that is part of a dbslice.A derived_dbspace_identifier has the same syntax as other identifiers except itcan contain at most one period. The period is not valid in other identifiers.

A number follows the period. This number is called the ordinal of thedbspace. The ordinal number indicates the placement of the dbspace withina dbslice, based on the order in which the dbspaces were created. When youcreate more than one dbspace in a dbslice, each dbspace contains a differentordinal number.

For example, if acctg_dbsp is the name of a dbslice, the onutil CREATEDBSLICE command creates the following derived dbspace identifiers:

acctg_dbsp.1acctg_dbsp.2

Command Reference



CREATE LOGICAL LOGSLICE See page 3-215.

DROP DBSLICE See page 3-222.



Use a derived_dbspace_identifier in the following onutil commands.

Index Name

An index_name is generated for an index or indexes of a table or a database. Ithas the same syntax as other identifiers.

Use an index_name in the following onutil commands.

Logslice Name

You define the logslice name in the onutil CREATE LOGICAL LOGSLICEcommand. The logslice name can be up to 18 characters.

Command Reference


ALTER DBSPACE See page 3-159.




CREATE LOGICAL LOG See page 3-212.

DISPLAY PAGE See page 3-217.

DROP DBSPACE See page 3-223.

Command Reference

CHECK INDEX See page 3-174.

CHECK INDEX WITH DATA See page 3-176.

Utilities 3-147


Use a logslice name in the following onutil commands.

Pathname Format

Use a pathname_format variable to generate a pathname for a chunk when youcreate a dbslice for root dbspaces, mirrors for root dbspaces, physical-logdbspaces, and dbspaces for database tables, or add dbspaces to a dbslice.

When you create or alter a dbslice, you can use a pathname format. You canuse the following embedded formatting characters for pathname formats:

%c%n%o%r(first..last)

These embedded formatting characters have the following meanings:

Command Reference

ALTER LOGICAL LOGSLICE See page 3-167.

CREATE LOGICAL LOGSLICE See page 3-215.

DROP LOGSLICE See page 3-226.

%c is a formatting character that is replaced with the coserver number ofthe coserver on which a dbspace is to be created. The coserver numberis the value that you specified on the COSERVER configurationparameter for this coserver. If the number is less than 10, the numberdoes not have a leading zero.

%n is a formatting character that is replaced with the host name of thenode for the coserver on which a dbspace is to be created. The hostname is the value that you specified in the NODE configurationparameter for this coserver.

%o is a formatting character that is replaced with the ordinal number of adbspace within a dbslice.



When you create a dbslice from multiple dbspaces on each coserver, you canuse the following embedded formatting characters for pathname formats:

For more details on the use of pathname formats and the onutil CREATEDBSLICE command, refer to “CREATE DBSLICE” on page 3-194. For infor-mation about what a dbslice is, refer to the chapter on where data is stored inthe Administrator’s Guide.

You can also use the %c and %n formatting characters in the followingsituations:

■ In conjunction with the ROOTSLICE configuration parameter

To use a pathname format to create root dbspaces on multiplecoservers, specify the pathname format in the ROOTPATH configu-ration parameter. For more information, refer to “ROOTPATH” onpage 1-128.

■ In the MIRRORPATH configuration parameter

To use a pathname format to create mirrors for root dbspaces onmultiple coservers, specify the pathname format in the MIRRORPATHconfiguration parameter. For more information, refer to“MIRRORPATH” on page 1-92.

■ In conjunction with the PHYSSLICE configuration parameter

To use a pathname format to assign dbspaces for physical logs onmultiple coservers, specify the pathname format in the PHYSDBSconfiguration parameter. For more information, refer to “PHYSDBS”on page 1-118.

The xctl onstat -d command displays the generated value of the pathnameformat when you display dbspaces and chunks that are part of a dbslice. Formore information about monitoring chunks, refer to monitoring the databaseserver for disabling I/O errors in the chapter on managing disk space in theAdministrator’s Guide.

%r(first..last) are formatting characters that are replaced by integer values inthe range that first and last specify to produce a list of coservernames.

Utilities 3-149

ALTER DBSLICE ADD DBSPACE

ALTER DBSLICE ADD DBSPACEUse the onutil ALTER DBSLICE ADD DBSPACE command to add dbspaces toa dbslice. You can either add dbspaces to a dbslice on the coservers wherethey were created or expand a dbslice to another coserver.

The onutil ALTER DBSLICE ADD DBSPACE command does not move orredefine user data. After you alter the dbslice, you can store new tables ineither the new or old dbspaces.

These new dbspaces are not automatically visible to the existing tables in thedbslice. Refragment the existing tables to enable them to use the newdbspaces in the dbslice. To refragment existing tables, use the ALTERFRAGMENT command, described in the Informix Guide to SQL: Syntax.

Syntax

FROMALTER DBSLICE dbslice_name DbsliceComponent

,

CHUNK SIZE size

KBYTES

MBYTES

GBYTES

PathnameDefinitionp. 3-152

DbsliceComponent

MIRRORPathnameDefinitionp. 3-152

ADD DBSPACE

CoserverComponent

p. 3-151



Coserver Component

Element Purpose Restrictions Syntaxdbslice_name The name of the dbslice to alter The dbslice must exist. See “Dbslice Name”

on page 3-146.size The size of the initial chunk of

each new dbspaceValue must be greater than 0.Size must not exceed4 gigabytes. Can specify units ofkilobytes, megabytes, orgigabytes.

Unsigned integer;default unit iskilobytes.

Element Purpose Restrictions Syntaxcogroup_name The name of a cogroup in the

database serverThe cogroup name must existwhen you execute thecommand. Name must beunique within a databaseserver.

See “Cogroup Name”on page 3-141.

coserver_name The name of a coserver that thedatabase server automaticallygenerates. A coserver name hasthe following format:dbserername.coserver_number

See “Coserver Name”on page 3-142.

coserver_range_identifier

The range of coservers in thedbslice. Coserver range identi-fiers can include embeddedformatting characters of thefollowing form: %r(first..last)

These formatting charactersare replaced by integer valuesin the range that first and lastspecify to produce a list ofcoserver names.

See “Coserver RangeIdentifier” onpage 3-145.

COGROUP cogroup_name

CoserverComponent

coserver_name

coserver_range_identifier

Utilities 3-151


Pathname Definition

Element Purpose Restrictions Syntaxfirst The starting value of the integer

to substitute for each path

When first is in the pathname, itsvalue can be any integer thatmakes each generated pathnameunique.

The value of first must be equalto or less than the value of last.

Unsigned integer

last The ending value of the integerto substitute in each path

When last is in the pathname, itsvalue can be any integer thatmakes each generated pathnameunique.

The value of last must be equal toor larger than first.

Unsigned integer

(1 of 3)

OFFSET offset" pathname "

PathnameFormat

PathnameDefinition

"

PathnameFormat

%c

%n

prefix "

,first( ),, last%r

%o

pathname_fragment

1



offset The offset, in kilobytes, into thefile or raw device to reach thechunk of each dbspace

Value must be greater than orequal to 0. See specifying anoffset in the chapter onmanaging disk space in theAdministrator’s Guide.

Unsigned integer

pathname The file or raw device of the firstchunk in the dbspace on eachnode

The pathname can optionallycontain formatting characters.

The chunk must be a file or rawdevice. Use a full pathname.

Pathname mustconform to the rulesspecific to youroperating system.See “PathnameFormat” onpage 3-148.

prefix The portion of the directoryname pathname that precedes theformatting character

The directory name must corre-spond to files that exist on theapplicable coservers.

The directory namemust conform to therules specific to youroperating system.

pathname_fragment

The portion of the generatedpathname that follows theformatting characters

The generated pathnames mustcorrespond to files that exist onthe applicable coservers. You canintersperse the formattingcharacters in between parts ofthe pathname.


%c A formatting character that isreplaced with the number of thecoserver on which a dbspace isto be created. The number is thevalue that you specified in theCOSERVER configurationparameter for this coserver.

If the number is less than 10, thenumber does not have a leadingzero.

See “GeneratingPathnames withCoserver Numbers”on page 3-200.

%n A formatting character that isreplaced with the host name ofthe node for the coserver onwhich a dbspace is to be created.


See “GeneratingPathnames withNode Names” onpage 3-201.


(2 of 3)

Utilities 3-153


UsageUse the onutil ALTER DBSLICE ADD DBSPACE command to add dbspaces toa dbslice on one or more coservers. The new dbspaces do not need to be thesame size as the old dbspaces in the dbslice. The database server must be inon-line or quiescent mode when you alter a dbslice.

Before you alter the dbslice, use the touch command to allocate storage forthe chunk files. Use any chunk name that you want. The database serverderives the dbspace names from the dbslice name and a dbspace identifier.For more details, see “Derived Dbspace Identifier” on page 3-146.

The new dbspaces in the dbslice are the same type as the original dbspaces inthe dbslice. If you alter a dbslice that contains mirrored dbspaces, the newdbspaces are also mirrored. If you alter a temporary dbslice, the newdbspaces are also temporary dbspaces.

Altering a Simple Dbslice

The following example shows the onutil ALTER DBSLICE ADD DBSPACEcommand that adds a dbspace to the dbslice dbsl on coserver eds.1. Thedbslice must exist.

% onutil1> ALTER DBSLICE dbsl ADD DBSPACE2> FROM COGROUP eds.13> CHUNK "/dev/dbsl_more" SIZE 2048;

%o A formatting character that isreplaced with the ordinalnumber of a dbspace within adbslice

The ordinal number startsnumbering at 1 plus the olddbspace count of the dbslice.

See “GeneratingPathnames withDbspace OrdinalNumbers” onpage 3-201.

%r(first..last) Formatting characters that arereplaced by successive integervalues in the range that first andlast specify

You can specify the %r(first..last)formatting characters only oncein a pathname format.

See “GeneratingPathnames forMultiple Dbspacesper Coserver” onpage 3-202.


(3 of 3)



Using Formatting Characters in a Pathname

When you alter a dbslice and add more than one dbspace to each coserver,use embedded formatting characters in the pathname to generate uniformchunk names for the dbspaces that make up a dbslice. The pathname specifi-cation with the embedded formatting characters is referred to as apathname_format. A pathname format generates unique chunk names for allof the dbspaces in a dbslice.

You can embed the following formatting characters within a pathnameformat. The onutil utility substitutes values stored internally for the %c, %n,and %o formatting characters:

■ Use the %c formatting character to generate a pathname with thecoserver number embedded in it.

■ Use the %n formatting character to generate a pathname with thehost name of the node, or node name, embedded in it.

■ Use the %o formatting character to generate a pathname with thedbspace ordinal number embedded in it. The database serverautomatically generates the dbspace ordinal number when you adddbspaces to a dbslice.The ordinal number indicates the order inwhich the dbspaces were created.

■ Use the %r(first..last) formatting characters to generate uniquepathnames or chunk names for each dbspace on a coserver. You cancreate multiple uniform dbspaces per coserver within the samedbslice.

■ The following rules describe how to combine the formattingcharacters:

❑ You can combine the %r(first..last) formatting characters withany number of %c, %n, and %o formatting characters in a singledbslice component.

❑ You can specify multiple instances of the %c, %n, and %oformatting characters in a single dbslice component.

❑ You can specify the %r(first..last) formatting characters only oncein a pathname format.

Utilities 3-155


Adding Dbspaces on a New Coserver to a Dbslice

The following example shows the onutil CREATE COGROUP command tocreate a cogroup for three coservers and the onutil CREATE DBSLICEcommand to create a dbslice that contains six dbspaces numbered dbsl.1through dbsl.6:

% onutil1> CREATE COGROUP c123 FROM eds.%r(1..3)Cogroup successfully created.2> CREATE DBSLICE dbsl FROM COGROUP c1233> CHUNK "/dev/dbspaces/dbsl_123.%r(1..2)" SIZE 1024;

The database server creates the following dbspaces on the three coservers.The %r(first..last) formatting characters tell the database server to create twodbspace chunks on coservers eds.1 through eds.3.

Then you add a new coserver, eds.4, to the system and want to expand thedbslice to that coserver. The following example shows the onutil ALTERDBSLICE ADD DBSPACE command to add dbspaces dbsl.7 and dbsl.8 tocoserver eds.4. The new dbspaces can be either the same size as the olddbspaces in the dbslice or a different size.

% onutil1> ALTER DBSLICE dbsl ADD DBSPACE FROM2> COGROUP eds.43> CHUNK "/dev/dbspaces/dbsl_4.%r(1..2)" SIZE 1024;

The range identifier %r(1..2) tells the database server to create two dbspaceson coserver eds.4 and automatically numbers them.

Coserver Dbspace Name Pathname of Primary Chunkeds.1 dbsl.1 /dev/dbspaces/dbsl_123.1eds.1 dbsl.2 /dev/dbspaces/dbsl_123.2eds.2 dbsl.3 /dev/dbspaces/dbsl_123.1eds.2 dbsl.4 /dev/dbspaces/dbsl_123.2eds.3 dbsl.5 /dev/dbspaces/dbsl_123.1eds.3 dbsl.6 /dev/dbspaces/dbsl_123.2

eds.1 eds.2 eds.3 eds.4dbsl.1 dbsl.3 dbsl.5 dbsl.7dbsl.2 dbsl.4 dbsl.6 dbsl.8



Tip: To expand a dbslice to two or more coservers, you can specify either acoserver_range_identifier or a cogroup composed of the new coservers in the onutilALTER DBSLICE ADD DBSPACE command.

Adding Dbspaces to a Dbslice on All Coservers

Now you want to add more dbspaces to the dbslice on all four coservers. Thefollowing example shows the onutil ALTER DBSLICE ADD DBSPACEcommand to add dbspaces dbsl.9 through dbsl.12 to all four coservers. Thistime, use cogroup_all to include all the coservers on the database server.

% onutil1> ALTER DBSLICE dbsl ADD DBSPACE FROM2> COGROUP cogroup_all3> CHUNK "/dev/dbspaces/dbsl_1234" SIZE 1024;

The database server creates the additional dbspaces on the four coservers.

Adding Mirrored Dbspaces to a Dbslice

Suppose you have a database server that is using mirroring with twocoservers. The following example shows the onutil CREATE DBSLICEcommand to create mirrored dbspaces on each coserver:

% onutil1> CREATE DBSLICE dbsl FROM COGROUP cogroup_all2> CHUNK "/disk3/dbspace/dbsl.%c" SIZE 500 MBYTES3> MIRROR "/disk4/dbspace/dbsl_mir.%c";

The database server creates the mirrored dbspaces on the coservers.

eds.1 eds.2 eds.3 eds.4dbsl.1 dbsl.3 dbsl.5 dbsl.7dbsl.2 dbsl.4 dbsl.6 dbsl.8dbsl.9 dbsl.10 dbsl.11 dbsl.12

Coserver Dbspace Primary Chunk Mirror Chunk

eds.1 dbsl.1 /disk3/dbspace/dbsl.1 /disk4/dbspace/dbsl_mir.1eds.2 dbsl.2 /disk3/dbspace/dbsl.2 /disk4/dbspace/dbsl_mir.2

Utilities 3-157


The following example shows the onutil ALTER DBSLICE ADD DBSPACEcommand with the MIRROR option to add mirrored dbspaces to dbslice dbslon each coserver:

% onutil1> ALTER DBSLICE dbsl ADD DBSPACE2> FROM COGROUP cogroup_all3> CHUNK "/disk3/dbspace/dbsl2.%c" SIZE 1000 MBYTES3> MIRROR "/disk4/dbspace/dbsl_mir2.%c";

The database server adds mirrored dbspaces to the dbslice on both coservers.

Coserver Dbspace Primary Chunk Mirror Chunk

eds.1 dbsl.1 /disk3/dbspace/dbsl.1 /disk4/dbspace/dbsl_mir.1eds.2 dbsl.2 /disk3/dbspace/dbsl.2 /disk4/dbspace/dbsl_mir.2eds.1 dbsl.3 /disk3/dbspace/dbsl2.1 /disk4/dbspace/dbsl_mir2.1eds.2 dbsl.4 /disk3/dbspace/dbsl2.2 /disk4/dbspace/dbsl_mir2.2


ALTER DBSPACE

ALTER DBSPACEThe onutil ALTER DBSPACE command lets you perform the following actions:

■ Add a chunk

■ Drop a chunk

■ Start mirroring

■ Stop mirroring

■ Change chunk status to on-line or off-line

Syntax

Element Purpose Restrictions Syntaxdbspace_identifier

The generated name of thedbspace that you want toalter

This element must be an existingdbspace that was generated whenyou created a dbslice. Name must beof the form:

slicename.ordinal

The value for slicename must be thesame as the dbslice name that youused when you created the dbslice

The value for ordinal must be anunsigned integer.

See “Derived DbspaceIdentifier” onpage 3-146.

dbspace_name

Name of the dbspace thatyou want to alter

The dbspace name must exist. See “Identifiers in onutilCommands” onpage 3-140.

ALTER DBSPACE

DROP CHUNK Clause p. 3-163

ADD CHUNK Clause p. 3-160

START MIRRORING Clause p. 3-164

STOP MIRRORING Clause p. 3-166

CHANGE STATUS Clause p. 3-162

dbspace_identifier

dbspace_name

Utilities 3-159

ALTER DBSPACE

UsageThe database server must be in on-line or quiescent mode when you use theonutil ALTER DBSPACE command.

Add a Chunk

Element Purpose Restrictions Syntaxpathname The file or raw device for the

dbspace chunk that you areadding

When you specify a pathname, use afull pathname. If you use a relativepathname, it must be relative to thedirectory that was the currentdirectory when you initialized thedatabase server.

Pathname mustconform to theoperating-system-specific rules forpathnames.

offset The offset, in kilobytes, intothe file or raw device to reachthe chunk

Value must be greater than 0. Seespecifying an offset in the chapter onmanaging disk space in the Adminis-trator’s Guide.

Unsigned integer.

size The chunk size of the newdbspace

Value must be greater than 0. Sizemust not exceed 4 gigabytes.

Unsigned integer;default size unit iskilobytes.

Chunk DefinitionADD CHUNK

ADD CHUNK Clause

Mirror Definition

SIZE size

KBYTES

MBYTES

GBYTES

"pathname "MIRROR

OFFSET offset

Chunk Definition

Mirror Definition

"pathname "

OFFSET offset


ALTER DBSPACE

Usage

Use the onutil ALTER DBSPACE command with the ADD CHUNK clause toadd a chunk to an existing dbspace. You can use the following keywords.

Adding a Chunk to a Dbspace

The following example shows how to use onutil ALTER DBSPACE to add a1000-kilobyte chunk, test_chunk, to the root dbspace:

% onutil1> ALTER DBSPACE rootdbs2> ADD CHUNK "/ix/mywork/test_chunk"3> OFFSET 0 SIZE 1000;Chunk successfully added.

Keyword Description

CHUNK Specifies the file or raw device for the chunk that you want to add.

MIRROR Specifies the file or raw device for the chunk that performs themirroring. Use the MIRROR keyword when you want to mirror thenew chunk.

Utilities 3-161

ALTER DBSPACE

Change Status of a Mirrored Chunk

Usage

Use the onutil ALTER DBSPACE command with the OFFLINE or ONLINEclause to change the status of an existing chunk. You can use the followingkeywords.

Element Purpose Restrictions Syntaxoffset The offset, in kilobytes, into

the file or raw device toreach the chunk

Value must be greater than or equal to0. See the chapter on managing diskspace in the Administrator’s Guide.

Unsigned integer.

pathname The pathname of the chunk. The chunk must be an existing file orraw device. Use a full pathname.


OFFSET offset

Change StatusClause

CHUNK " pathname "OFFLINE

ONLINE

)(

Keyword Description

OFFLINE Takes the chunk down.

ONLINE Restores the chunk and brings it on-line.


ALTER DBSPACE

Taking a Mirrored Chunk Off-line

You can only change the status of a chunk in a mirrored pair. The followingexample shows how to use onutil ALTER DBSPACE to take a mirrored chunkoff-line. For more information, refer to the chapter on using mirroring in theAdministrator’s Guide.

% onutil1> ALTER DBSPACE rootdbs OFFLINE2> CHUNK "/ix/mywork/mirr_chunk";

Drop a Chunk

Usage

Use the onutil ALTER DBSPACE command with the DROP CHUNK clause todrop a chunk. If you drop a chunk that is mirrored, the mirrored chunk is alsodropped.



Value must be greater than or equal to0. See the chapter on managing diskspace in the Administrator’s Guide.

Unsigned integer.

pathname The file or raw device for thechunk that you aredropping

The chunk must be an existing file orraw device. Use a full pathname.


DROP CHUNK Clause

" pathname "DROP CHUNK

OFFSET offset

Utilities 3-163

ALTER DBSPACE

Dropping a Chunk from a Dbspace

The following example shows how to use onutil ALTER DBSPACE to drop achunk, test_chunk, from the root dbspace:

% onutil1> ALTER DBSPACE rootdbs2> DROP CHUNK "/ix/mywork/test_chunk"3> OFFSET 0Chunk successfully dropped.

The chunk must be empty before you can drop it. You must free all pagesother than overhead pages. If any pages remain allocated to nonoverheadentities, onutil returns the following error:

Chunk is not empty.

You cannot drop the initial chunk of a dbspace. Use the chunk column of xctlonstat -d to determine the initial chunk of a dbspace. For more information,see “The onstat -d Option” on page 3-98.

Start Mirroring

START MIRRORING Clause

START MIRRORING

CHUNK MIRROR

,

Path Definition

OFFSET offsetOFFSET offset

Path Definition

" pathname " " pathname "


ALTER DBSPACE

Usage

Use the ALTER DBSPACE onutil command with the START MIRRORING clauseto mirror an existing dbspace. You can use the following keywords.

Enabling Mirroring for a Chunk

Before you can enable mirroring, set the MIRROR parameter to 1 in theONCONFIG file and restart the database server. Also, allocate disk space forthe mirrored chunk. The following example shows how to use onutil ALTERDBSPACE to start mirroring for the root dbspace:

% onutil1> ALTER DBSPACE rootdbs START MIRRORING2> CHUNK "/ix/mywork/root_chunk.1"3> MIRROR "/ix/mywork/mirr_chunk";



Value must be greater than 0. See thechapter on managing disk space in theAdministrator’s Guide.

Unsigned integer.

pathname The file or raw device for thechunk

The chunk that you want to mirrormust be an existing file or raw device.You can use a full pathname or arelative pathname. However, if youuse a relative pathname, it must berelative to the directory that was thecurrent directory when you initializedthe database server.


Keyword Description

CHUNK Specifies the file or raw device of the initial chunk of the dbspacethat you want to mirror.

MIRROR Specifies the file or raw device of the initial chunk of the dbspacethat performs the mirroring. Use the MIRROR keyword when youwant to mirror the new chunk.

Utilities 3-165

ALTER DBSPACE

Stop Mirroring

Usage

Use the onutil ALTER DBSPACE command with the STOP MIRRORING clauseto end mirroring of an existing dbspace.

Element Purpose Restrictions Syntaxdbspace_identifier

The generated name of thedbspace for which you wantto end mirroring

Element must be an existing dbspacethat was generated when you createda dbslice. Name must be of the form:

slicename.ordinal

The slicename value must be the sameas the dbslice name that you usedwhen you created the dbslice.

The ordinal value must be anunsigned integer.

See “Derived DbspaceIdentifier” onpage 3-146.

dbspace_name

Name of the dbspace forwhich you want to endmirroring

See ending mirroring in the chapteron using mirroring in the Adminis-trator’s Guide.

See “Identifiers in onutilCommands” onpage 3-140.

STOP MIRRORING Clause

STOP MIRRORING


ALTER LOGSLICE ADD LOGS

ALTER LOGSLICE ADD LOGSThe onutil ALTER LOGSLICE ADD LOGS command allows you to add logical-log files to a logslice.

Syntax

Element Purpose Restrictions Syntaxlogslice_name Name of the logslice The name must identify

an existing logslice.See “Logslice Name” onpage 3-147.

LOGICAL Optional keyword that doesnot change the command.

None.

ALTER LOGSLICE ADD LOGSlogslice_name

LOGICALLOGICAL

Utilities 3-167


UsageThe database server must be in quiescent mode when you alter a logslice.

Use the onutil ALTER LOGSLICE ADD LOGS command with the onutil ALTERDBSLICE command, which adds new dbspaces to a specific dbslice. If thisdbslice contains a logslice, use the onutil ALTER LOGSLICE command to addlogical logs to the new dbspaces in dbslice, thus extending the number oflogical logs in this logslice. Each dbspace that was added to the dbslice sincethe logslice was last created or altered gets a new log file.

The database server automatically figures the size of the new log files in thelogslice. One log file is put into every dbspace in this dbslice.

When to Add Log Files to a Logslice

If you add more dbspaces to a dbslice but do not change the number ofcoservers represented in the dbslice, you do not need to add more log files tothe logslice.

If you add new coservers to the database server, you should add log files tothe logslice for the dbspaces on the new coservers. If you add existingcoservers to a dbslice, you might want to add log files to the logslice.

Procedure for Altering a Logslice

Before you can use the onutil ALTER LOGSLICE ADD LOGS command, youmust already have created a logslice. (A given dbslice can have more thanone logslice.)

To alter a logslice

1. Alter this dbslice. (When you alter a dbslice, you are addingdbspaces to the coservers represented in this dbslice).

2. Ensure that the new dbspaces in the dbslice are large enough to holda log file.

3. Place the database server in quiescent mode.

4. Now you can alter the logslice (add log files to it).



Adding Log Files to a Logslice

This example shows a dbslice dbsl that contains six dbspaces on threecoservers, eds.1 through eds.3. Coserver eds.4 does not contain any dbspacesin the dbslice. The onutil CREATE LOGICAL LOGSLICE command places two512-kilobyte logical logs on each coserver.

% onutil1> CREATE LOGICAL LOGSLICE mylogslice2> IN DBSLICE dbsl SIZE 512;

Then you alter dbslice dbsl by adding three dbspaces to coserver eds.4 andone dbspace each to coservers eds.1 through eds.3. The database servercreates additional dbspaces on the four coservers.

Then you use the onutil ALTER LOGSLICE ADD LOGS command to add logfiles to the six new dbspaces in the dbslice. This command adds one log fileeach to coservers eds.1 through eds.3 and three log files to coserver eds.4 fora total of three log files on each coserver. The logslice mylogslice nowcontains a total of twelve 512-kilobyte log files.

% onutil1> ALTER LOGSLICE mylogslice ADD LOGS;

If the database server cannot accommodate more logical logs, increase theLOGSMAX and LOGFILES values in the ONCONFIG file and restart thedatabase server.

The space allocated for a logical-log file must be contiguous. The databaseserver does not allow you to add a log file to a dbspace without adequatecontiguous space.

eds.1 eds.2 eds.3 eds.4

dbsl.1 dbsl.3 dbsl.5 dbsl.7dbsl.2 dbsl.4 dbsl.6 dbsl.8dbsl.9 dbsl.10 dbsl.11 dbsl.12

Utilities 3-169

CHECK CATALOGS

CHECK CATALOGSThis command checks the internal integrity of the system catalog tables for adatabase.

Syntax

UsageUse the onutil CHECK CATALOGS command to check the internal integrity ofthat system catalog tables of a database.

For example, you can check the system catalog tables of a database with thisonutil command:

% onutil1> CHECK CATALOGS sysmaster;2> CHECK CATALOGS;

Element Purpose Restrictions Syntaxdatabase_name The name of the database

where the system catalogtables reside

The database must exist.You cannot check databaseson remote database servers.

See Database Name in theInformix Guide to SQL:Syntax.

CHECK CATALOGS

database_name


CHECK DATA

CHECK DATAThe onutil CHECK DATA command checks pages and rows of a table. Withthe DISPLAY clause, this command also displays the information. The WITHBLOBS clause forces a check of all simple large objects (TEXT or BYTE data) inthe target tables.

Syntax

databaseIN DATABASE COSERVER

REPAIR

database

owner .

table_name: dbspace_name

TABLE

TABLE_FRAG

CHECK DATA

WITH BLOBS

table_namedatabase

TABLE

TABLE_FRAG

Coserver_Listp. 3-143

partnum pagenumIN TABLESPACE PAGE

DISPLAY

SAVE

LOCK

IN TABLE

IN TABLE

IN filename

:

owner .

,

Utilities 3-171

CHECK DATA

UsageUse the onutil CHECK DATA command to check the consistency of all pagesof a table fragment or a single page of data. The onutil CHECK DATAcommand checks entries in the bit-map page against the pages to verifymapping.

Use the LOCK option of onutil CHECK DATA to place a shared lock on thedata being checked while the check is in progress. Use the REPAIR option torepair any inconsistent indexes that CHECK DATA encounters.

A specific coserver owns and manages each dbspace. The physical disk onwhich the dbspace resides belongs to the node on which the coserverexecutes. This coserver is referred to as the home coserver.

Element Purpose Restrictions Syntaxdatabase The name of the database

where the table residesThe database must exist. Youcannot check databases onremote database servers.

See Database Name in theInformix Guide to SQL:Syntax.

partnum The tblspace number that youwant to check for consistency

Value must be an integerbetween 0 and 208,666,624,inclusive.

Unsigned integer.

pagenum An integer value that you useto indicate a particular pagein a tblspace

Value must be an unsignedinteger between 0 and16,777,215, inclusive.

Unsigned integer.

filename The relative or absolute pathand name of the file in whichonutil stores the commandoutput

If you run the onutilcommand from the commandline, escape the double quotesaround the filename.

Use the operating-systemrules for the filename.

owner The name of the owner of atable

Owner that you specify mustbe current owner of table.Owner is mandatory for ANSIdatabases.

The user name mustconform to the conventionsof your operating system.

table_name The name of the table that youwant to check

Table must exist. See “Identifiers in onutilCommands” on page 3-140.

dbspace_name The name of the dbspace thatyou want to check

The dbspace must exist. See the chapter on wheredata is stored in the Admin-istrator’s Guide.


CHECK DATA

To examine only a table fragment

1. Obtain the tblspace number for each fragment in a fragmented table.You can use the following SQL statement:

SELECT partn FROM sysfragments,systables WHEREsystables.tabid = sysfragments.tabidAND systables.tabname = tablename;

2. Run the CHECK DATA command with the TABLESPACE clause, usingthe tblspace number for the fragment that you want to examine.

$onutil> CHECK DATA IN TABLESPACE 196626;

You can specify a single page to check for consistency when you specify thePAGE clause. Use the DISPLAY clause to display a hexadecimal dump of thespecified page.

The following example shows other ways to check the consistency of a table:

$onutil> CHECK DATA IN TABLE mydb:myname.mytable, myfrags1 PAGE 5;> CHECK DATA IN TABLE mydb:myname.mytable COSERVER svr.2;> CHECK DATA WITH BLOBS IN DATABASE mydb;

Messages

If onutil CHECK DATA finds an inconsistency, a message similar to thefollowing example appears:

BAD PAGE 20001c:pg_addr 20001c != bp-> bf_pagenum 200045

If onutil CHECK DATA finds no inconsistencies, onutil displays a header,similar to the following example, for each table that it checks:

TBLSPACE data check for stores_demo:informix.customer

If the onutil CHECK DATA command specifies a table fragment that is notmanaged by the coserver to which the onutil client is connected, a messagesimilar to the following example appears:

Error opening TBLspace acctg_table.ISAM error: TBLspace does not exist

Utilities 3-173

CHECK INDEX

CHECK INDEXThe onutil CHECK INDEX command checks the ordering of key values andthe consistency of horizontal and vertical node links for B-tree indexes andbitmaps that are associated with the specified table. With the DISPLAY clause,onutil CHECK INDEX also displays the key values for the B-tree indexes andbitmaps of the specified table as it checks them.

Syntax

CHECK INDEX

DISPLAY

SAVE

TABLE

database :

owner .table_name

IN DATABASE database

IN TABLESPACE partnum

TABLE

IN TABLE

LOCK

INDEX

database # index_name

INDEX

IN filename

owner .


CHECK INDEX

UsageUse the onutil CHECK INDEX command to check the integrity of a B-treeindex and display the contents of all nodes.

The LOCK option locks the table in share mode, so no other users can insert,update, or delete rows in the table while the check occurs.

For example, you can check the index of a table with these onutil commands:

% onutil1> CHECK INDEX IN DATABASE mydb;2> CHECK INDEX IN TABLE mydb:myname.mytable;3> CHECK INDEX IN TABLESPACE 11111 DISPLAY;

Another way to check the index of a table follows:

1> CHECK INDEX mydb#myname.myindex

Element Purpose Restrictions Syntaxdatabase The name of the database where

the index residesThe database must exist.You cannot check databases onremote database servers.

See Database Namein the Informix Guideto SQL: Syntax.

partnum The table or index partitionnumber that you want to checkfor consistency


Unsigned integer.

filename The relative or absolute path andname of the file in which onutilstores the command output

If you run the onutil commandfrom the command line, escapethe double quotes around thefilename.

Use the operating-system rules for thefilename.

database The name of the database wherethe table or index resides

The database must exist.You cannot check databases onremote database servers.

See Database Namein the Informix Guideto SQL: Syntax.

owner The name of the owner of a table Owner that you specify must becurrent owner of table. Owner ismandatory for ANSI databases.

The user name mustconform to theconventions of youroperating system.

table_name The name of the table that youwant to check

Table must exist. See “Identifiers inonutil Commands”on page 3-140.

index_name The name of the index that youwant to check

The index must exist. See “Index Name”on page 3-147.

Utilities 3-175

CHECK INDEX KEYS WITH DATA

CHECK INDEX KEYS WITH DATAThe onutil CHECK INDEX WITH DATA command checks the ordering of keyvalues and the consistency of horizontal and vertical node links for B-treeindexes and bitmaps that are associated with the specified table. Thiscommand also checks that the key value tied to a rowid in an index is thesame as the key value in the row.

Syntax

CHECK INDEX WITH DATA

TABLE


INDEX

DISPLAY

SAVE

LOCK

IN filenameTABLE

database :

owner .table_nameIN TABLE

database # index_name

INDEX

owner .


CHECK INDEX KEYS WITH DATA

UsageUse the onutil CHECK INDEX WITH DATA command to check the internalintegrity of a B-tree index and cross-check the indexed data entities.

The LOCK option locks the table in share mode, so no other users can insert,update, or delete rows in the table while the check occurs.

For example, you can use the following onutil command to check the B-treeindex of a table:

% onutil1> CHECK INDEX WITH DATA IN DATABASE mydb;2> CHECK INDEX WITH DATA IN TABLE mydb:myname.mytable;

Element Purpose Restrictions Syntaxdatabase The name of the database

where the index residesThe database must exist.You cannot check databaseson remote database servers.

See Database Name in theInformix Guide to SQL: Syntax.

filename The name of the file in whichonutil stores the commandoutput

If you run the onutilcommand from thecommand line, escape thedouble quotes around thefilename.


database The name of the databasewhere the table resides

The database must exist.You cannot check databaseson remote database servers.

See Database Name in theInformix Guide to SQL: Syntax.


Owner that you specify mustbe current owner of table.Owner is mandatory forANSI databases.

The user name must conformto the conventions of youroperating system.

table_name The name of the table thatyou want to check

Table must exist. See “Identifiers in onutilCommands” on page 3-140.

index_name The name of the index thatyou want to check

The index must exist. See Object Name in theInformix Guide to SQL: Syntax.

Utilities 3-177

CHECK INFO

CHECK INFOThe onutil CHECK INFO command checks space usage for a table. With theDISPLAY clause, this command also displays the information.

Syntax

CHECK

ALLOCATION

INFO

IN TABLESPACE partnum

TABLE

TABLE_FRAG



dbspace,

TABLE

owner .

database :

tabledatabaseIN TABLE

IN TABLE

:

owner .

TABLE_FRAG

DISPLAY

SAVE

LOCK

IN filename

REPAIR

table


CHECK INFO

UsageUse the onutil CHECK INFO command to display space usage for a tablefragment. The space usage includes the maximum row size, the number ofkeys, the number of extents, the extent sizes, the pages allocated and used perextent, the current serial value, and the date that the table was created. TheExtents fields list the physical address for the tblspace entry for the table andthe address of the first page of the first extent.

To obtain a list of all the fragments in a table, query the systabnames table inthe sysmaster database or systables system catalog table. The value in thepartnum column in this systabnames table or systables system catalog tableis the value that you specify in the partnum element in the TABLESPACEclause.

Element Purpose Restrictions Syntaxpartnum A number that identifies the

tblspace that you want to checkfor consistency


Unsigned integer.

database The name of the database wherethe table resides

The database must exist. Youcannot check databases onremote database servers.

See the InformixGuide to SQL: Syntax.


If you run the onutil commandfrom the command line, escapethe double quotes around thefilename.


owner The name of the owner of thetable

The owner that you specify mustbe the current owner of the table.Owner is mandatory for ANSIdatabases.

The user name mustconform to theconventions of youroperating system.

table The name of the table that youwant to check for consistency

Table must exist. See “Identifiers inonutil Commands”on page 3-140.

dbspace The name of a dbspace thatcontains a fragment you want tocheck for consistency

Dbspace must exist and containthe fragment that you want tocheck for consistency.


Utilities 3-179

CHECK INFO

Use the ALLOCATION clause to display index-specific information and page-allocation information by page type, as the following example shows:

$onutil> CHECK INFO IN TABLESPACE 1111;> CHECK ALLOCATION INFO IN DATABASE mydb;

The LOCK option locks the table in share mode, so no other users can insert,update, or delete rows in the table while the check occurs. The REPAIR optionrepairs any inconsistencies the CHECK INFO command finds.

The command also displays the current lock level for the table. A table canhave table-level locking (instead of page-level or row-level locking). If table-level locking is set, the onutil CHECK [ALLOCATION] INFO commanddisplays the following message:

Page locking at RSAM levelTable locking at SQL level

If coarse-grain locking is set for an index, the onutil CHECK ALLOCATIONINFO IN TABLE tabname DISPLAY or onutil CHECK INFO command displaysthis extra line in the section on what flags are set:

coarse-grain locking

Messages

If the onutil CHECK INFO command specifies a table fragment that is notmanaged by the coserver to which the onutil client is connected, a messagesimilar to the following example appears:

Error opening TBLspace acctg_table.ISAM error: TBLspace does not exist


CHECK LOGS

CHECK LOGSThe onutil CHECK LOGS command checks consistency of pages in thephysical and logical logs. With the DISPLAY clause, this command alsodisplays information about the logs.

Syntax

UsageUse the onutil CHECK LOGS command to check pages from the physical andlogical log. You can run CHECK LOGS when the database server is offline oronline.

Element Purpose Restrictions Syntaxlognbr The logical-log uniqid. Value must be a valid used logical-

log uniqid.Unsigned integer.


If you run the onutil command fromthe command line, put backslashes infront of the double quotes around thefilename.


CHECK LOGS

Coserver_Listp. 3-143UNIQID lognbr

DISPLAY

SAVE

IN filename

Utilities 3-181

CHECK LOGS

To check an individual logical log, use the UNIQID clause. Determine theunique ID of the logical log that you want to check with the xctl onstat -lcommand and place it after the UNIQID keyword.

The following examples show different options of the CHECK LOGSstatement:

$onutil> CHECK LOGS DISPLAY;> CHECK LOGS UNIQID 4 SAVE IN "myfile";> CHECK LOGS COSERVER ifmx.2;


CHECK RESERVED

CHECK RESERVEDThe onutil CHECK RESERVED command checks each of the root dbspacereserved pages for several conditions. You can use this command when thedatabase is off-line. With the DISPLAY clause, this command displaysreserved-page information on your terminal.

Syntax

CHECK RESERVED

Database On-Line

Database Off-Line

Database On-Line

PAGE Page_Listp. 3-184

Database Off-Line

PAGEPage_Listp. 3-184

DISPLAY

SAVE

IN filename


COSERVER

DISPLAY

COSERVER coserver_name

SAVE

IN filename

Utilities 3-183

CHECK RESERVED

Page List

Element Purpose Restrictions Syntaxcoserver_name The name of a coserver that

the database serverautomatically generates

Name must have the followingformat:

dbservername.number

The dbservername must be thesame value that theDBSERVERNAME configurationparameter specifies.

The number must be one of theintegers that the COSERVERconfiguration parameter specifies.


filename The relative or absolutepath and name of the file inwhich onutil stores thecommand output

If you run the onutil commandfrom the command line, escape thedouble quotes around thefilename.


Page_List

ARCH

,

CHUNK

CKPT

CONFIG

DBSP

hexadecimal_number

MCHUNK

decimal_number

PCHUNK

PZERO

SAFEWRITE


CHECK RESERVED

UsageUse the onutil CHECK RESERVED command to check the integrity of the rootreserved pages and display the contents of these pages.

For example, you can check the reserved pages with the following onutilcommand:

% onutil1> CHECK RESERVED COSERVER svr.2 DISPLAY;

For an off-line check of coserver svr.2, use the following syntax:

% onutil -o1> CHECK RESERVED COSERVER svr.2 DISPLAY;

Important: For an off-line check, you must specify a single coserver name. You cancheck only a single coserver that is local to the computer from which you areexecuting onutil.

If you run onutil CHECK RESERVED from the command line, you must escapethe double quotes around the filename; otherwise, the UNIX shell returns anerror:

% onutil CHECK RESERVED SAVE IN \“myfile\”

For more details about onutil CHECK RESERVED, refer to monitoring config-uration information in the chapter on installing and configuring the databaseserver in the Administrator’s Guide.

Element Purpose Restrictions Syntaxdecimal_number The page number that you

want to checkValue must be greater than 0. Unsigned decimal.

hexadecimal_number The page number that youwant to check

Value must be greater than 0. Unsignedhexadecimal.

Utilities 3-185

CHECK SPACE

CHECK SPACEThe onutil CHECK SPACE command checks each chunk free list and corre-sponding free space and each tblspace extent. This command also checksoverlapping extents. With the DISPLAY clause, this command also displaysthe chunk and tblspace extent information as it checks the chunk free list andcorresponding free space and each tblspace extent.

Syntax

UsageUse the onutil CHECK SPACE to check the extent layout of a space and tocheck overlapping extents.

Element Purpose Restrictions Syntaxfilename The name of the file in

which onutil stores thecommand output

If you run the onutil command fromthe command line, escape thedouble quotes around the filename.


CHECK SPACE

COSERVER Coserver_Listp. 3-143

DISPLAY

SAVE

IN filename


CHECK SPACE

For example, you can check the index of a table with the following onutilcommand:

% onutil1> CHECK SPACE;2> CHECK SPACE COSERVER svr.2 DISPLAY:

Utilities 3-187

CREATE COGROUP

CREATE COGROUPCogroups help you administer a large number of coservers. You can groupcoservers into subsets to use for specific applications, system administration,and database administration.

Extended Parallel Server automatically defines a special system cogroup,cogroup_all, to represent all the coservers specified in your ONCONFIGconfiguration file that are initialized.

Syntax

FROMCREATE COGROUP

,

prefix

Coserver_Range_Identifier

Cogroup_Range_Identifier


cogroup_name

coserver_name

Formatting Characters

first( )%r .. last

Formatting Characters suffix

prefix Formatting Characters

Coserver_Range_Identifier

dbservername Formatting Characters.


CREATE COGROUP

Element Purpose Restrictions Syntaxcogroup_name The name of the new

cogroup in the databaseserver

Name must be unique within adatabase server.

See “Cogroup Name” onpage 3-141.

coserver_name The name of a coserverthat the database serverautomatically generates

Name must have the followingformat:

dbservername.number

The dbservername must be thesame value that theDBSERVERNAME configurationparameter specifies.

The number must be one of theintegers that the COSERVERconfiguration parameterspecifies.

See “Coserver Name” onpage 3-142.

prefix The alphabetic portion ofthe generated cogroupname that precedes theformatting character


See “Pathname Format”on page 3-148 and“Coserver List” onpage 3-143.

suffix The alphabetic portion ofthe generated cogroupname that follows theformatting character


See “Identifiers in onutilCommands” onpage 3-140 and “CoserverList” on page 3-143.

dbservername The name of the databaseserver

You must use the same value thatthe DBSERVERNAME configu-ration parameter specifies.

See “DBSERVERNAME”on page 1-38.

(1 of 2)

Utilities 3-189

CREATE COGROUP

UsageYou must create a cogroup before you can create a dbslice. Use the onutilCREATE COGROUP command to create a new group of coservers in yourdatabase server. Cogroups make managing coservers simpler. Instead ofspecifying a long list of coservers in onutil commands, you specify a cogroupname.

The following examples assume that your ONCONFIG file contains theconfiguration parameters shown in Figure 3-5 on page 3-191, an excerpt of asample ONCONFIG file that configures an Extended Parallel Server databaseserver and 16 coservers.

first The starting integer valueto substitute in a cogroupor coserver name

The value of first must be equal toor less than last.

When first is in the COGROUPclause, its value can be anyinteger that makes the cogroupname unique.

When last is in a FROM clause, itmust be one of the values that theCOSERVER configurationparameter specifies.

This value must be anunsigned integer.

last The ending integer valueto substitute for thecogroup or coservername


When last is in the COGROUPclause, its value can be anyinteger that makes the cogroupname unique.

When last is in a FROM clause, itmust be one of the values that theCOSERVER configurationparameter specifies.

This value must be anunsigned integer.


(2 of 2)


CREATE COGROUP

Creating the New Cogroup

When you create a cogroup, you can specify the cogroup name with either anidentifier or a cogroup range identifier. For more details on identifiers andcogroup range identifiers, see “Identifiers in onutil Commands” onpage 3-140 and “Coserver List” on page 3-143.

The following example shows an onutil CREATE COGROUP command inwhich an identifier names the new cogroup:

% onutil1> CREATE COGROUP acctg_cogroup_east2> FROM eds.1, eds.2, eds.3, eds.4, eds.5, eds.6;

DBSERVERNAME eds

ROOTSLICE rootdbsROOTPATH /work/dbspaces/rootdbs_%cROOTOFFSET 0ROOTSIZE 40000

MIRRORSLICE mirrorMIRRORPATH /work/dbspaces/mirror_%cMIRROROFFSET 0MIRROR 1 # 1 = yes

PHYSSLICE rootdbsPHYSDBS physdbs_%cPHYSSIZE 8000

LOGFILES 3LOGSIZE 1000...COSERVER 1 NODE NODE1

...END...COSERVER 16 NODE NODE16

...END

Figure 3-5Excerpt of Sample

ONCONFIG File

Utilities 3-191

CREATE COGROUP

The following example shows a CREATE COGROUP command in which acogroup range identifier names the new cogroup:

% onutil1> CREATE COGROUP cg%r(1..2)2> FROM eds.%r(13..16);

To produce a list of cogroup names, the %r formatting character in theCOGROUP clause is iteratively substituted with the integer values that therange list specifies.

This example creates the following cogroups:

■ The cg1 cogroup consists of coservers eds.13 and eds.14.

■ The cg2 cogroup consists of coservers eds.15 and eds.16.

To produce a list of coserver names, the %r formatting character in the FROMclause is iteratively substituted with the integer values that the range listspecifies.

Important: The number of coserver values in the FROM clause must be a multiple ofthe number of cogroup values in COGROUP.

Specifying Coservers for the New Cogroup

You can create a cogroup from:

■ a list of coserver names.

■ a coserver range identifier.

■ a combination of coserver names and coserver range identifier.

Creating a Cogroup from a List of Coserver Names

The following example shows the onutil CREATE COGROUP command tocreate a cogroup from coserver names for the first six coservers shown in“Excerpt of Sample ONCONFIG File” on page 3-191:

% onutil1> create cogroup acctg_cogroup_east2> from eds.1, eds.2, eds.3, eds.4, eds.5, eds.6;


CREATE COGROUP

Creating a Cogroup from a Coserver Range Identifier

The following example shows the CREATE COGROUP command to create acogroup from a coserver range identifier for the next six coservers:

% onutil1> CREATE COGROUP acctg_cogroup_west2> FROM eds.%r(7..12);

To produce a list of coserver names, the %r formatting character is iterativelysubstituted with the integer values that the range list specifies.

Creating a Cogroup from a Combination of Coserver Names and CoserverRange Identifiers

The following example shows the CREATE COGROUP command to create acogroup from a combination of coserver names and coserver range identifier:

% onutil1> CREATE COGROUP acctg_cogroup_west2> FROM eds.5, eds.%r(7..12);

ReferencesFor more information, see coserver groups in the chapter that introduces thedatabase server in the Administrator’s Guide. For more information aboutconfiguring coservers, refer to the chapter on configuration parameters in theAdministrator’s Guide.

Utilities 3-193

CREATE DBSLICE

CREATE DBSLICEUse the onutil CREATE DBSLICE command to create a set of dbspaces that aremanaged as a single storage object across multiple coservers.

Syntax

FROMCREATE DBSLICE dbslice_nameDbslice

Component

,

TEMP

CHUNKCOGROUP cogroup_name SIZE size

KBYTES

MBYTES

GBYTES

PathnameDefinitionp. 3-195

DbsliceComponent

MIRRORPathnameDefinitionp. 3-195


CREATE DBSLICE

Pathname Definition

Element Purpose Restrictions Syntaxcogroup_name The name of a cogroup or

coserver in the database serverThe cogroup name must existwhen you execute the command.Name must be unique within adatabase server.


dbslice_name The name of the dbslice to create Name must be unique within adatabase server.


size The size of the initial chunk ofeach new dbspace

Value must be greater than 0.Size must not exceed4 gigabytes. Can specify units ofkilobytes, megabytes, orgigabytes.

Unsigned integer;default unit iskilobytes.

OFFSET offset" pathname "

PathnameFormat

PathnameDefinition

"

PathnameFormat

%c

%n

prefix "

1

.

first( ).. last%r

%o

pathname_fragment

Utilities 3-195

CREATE DBSLICE

Element Purpose Restrictions Syntaxfirst The starting value of the integer

to substitute for each path

When first is in the pathname, itsvalue can be any integer thatmakes each generated pathnameunique.


Unsigned integer

last The ending value of the integerto substitute in each path

When last is in the pathname, itsvalue can be any integer thatmakes each generated pathnameunique.


Unsigned integer

offset The offset, in kilobytes, into thefile or raw device to reach thechunk of each dbspace

Value must be greater than orequal to 0. See specifying anoffset in the chapter onmanaging disk space in theAdministrator’s Guide.

Unsigned integer

pathname The file or raw device of the firstchunk in the dbspace on eachnode

The chunk must be a file or rawdevice. Use a full pathname.

The pathname can optionallycontains formatting characters.


prefix The portion of the directoryname that precedes theformatting character

The generated directory namesmust correspond to directoriesthat exist on the applicablecoservers.

The directory namemust conform to therules specific to youroperating system.

pathname_fragment

The portion of the generatedpathname that follows theformatting characters

The generated pathnames mustcorrespond to files that exist onthe applicable coservers. You canintersperse the formattingcharacters in between parts ofthe pathname.


(1 of 2)


CREATE DBSLICE

UsageUse the onutil CREATE DBSLICE command to create groups of dbspaces thatyou manage as a single logical storage unit. The database server must be inon-line or quiescent mode when you create a dbslice.

Specifying Uniform Dbspaces in a Dbslice

When you create a dbslice, the database server creates uniform dbspacesacross one or more existing cogroups.

%c A formatting character that isreplaced with the number of thecoserver on which a dbspace isto be created

The number is the value that youspecified in the COSERVERconfiguration parameter for thiscoserver.

If the number is less than 10, thenumber does not have a leadingzero.

See “GeneratingPathnames withCoserver Numbers”on page 3-200.

%n A formatting character that isreplaced with the host name ofthe node for the coserver onwhich a dbspace is to be created


See “GeneratingPathnames withNode Names” onpage 3-201.

%o A formatting character that isreplaced with the ordinalnumber of a dbspace within adbslice

The ordinal numbering starts at1.

See “GeneratingPathnames withDbspace OrdinalNumbers” onpage 3-201.

%r(first..last) Formatting characters that arereplaced by successive integervalues in the range that first andlast specify

You can specify the %r(first..last)formatting characters only oncein a pathname format.

See “GeneratingPathnames forMultiple Dbspacesper Coserver” onpage 3-202.


(2 of 2)

Utilities 3-197

CREATE DBSLICE

Each dbslice component in the FROM clause specifies the dbspaces to createfor a dbslice. You must specify the cogroup, pathname, and size in eachdbslice component. The following example shows the onutil CREATEDBSLICE command that creates a dbspace on each coserver in cogroup_all:

% onutil1> CREATE DBSLICE dbsl2> FROM cogroup cogroup_all3> CHUNK "/dev/dbsl_all"4> OFFSET 1024 SIZE 1024;

This example assumes that your ONCONFIG file defines 16 coservers, asshown in Figure 3-5 on page 3-191. Therefore, cogroup_all consists ofcoservers eds.1 to eds.16.

This example creates the following dbspaces on all 16 coservers.

The database server derives the names of the dbspaces from the name of thedbslice. These derived names are referred to as derived_dbspace_identifiers. Formore details on derived_dbspace_identifiers, refer to “Derived DbspaceIdentifier” on page 3-146.

A derived_dbspace_identifier contains a period and a number at the end of thedbspace name. The number is called the ordinal of the dbspace within thedbslice. The ordinal indicates the order in which the dbspaces were created.

Generating Pathnames Without Formatting Characters

This example assumes that one coserver exists on each node. In this case, youcan use a regular pathname, rather than a pathname format when you createa dbslice with one dbspace per coserver.

Coserver Dbspace Identifier Pathname of Primary Chunk Offset

eds.1 dbsl.1 /dev/dbsl_all 1024eds.2 dbsl.2 /dev/dbsl_all 1024eds.3 dbsl.3 /dev/dbsl_all 1024...eds.16 dbsl.16 /dev/dbsl_all 1024


CREATE DBSLICE

The following examples show the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand to create a dbslice for this cogroup:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..8);Cogroup successfully created.3> CREATE DBSLICE acctg_sl4> FROM COGROUP acctg_cogroup5> CHUNK "/dev/dbsl_acctg"6> OFFSET 1024 SIZE 1024;

This example generates the following dbspace names (also referred to asdbspace identifiers) and pathnames for the first chunk of each dbspacecreated on the corresponding coserver.

Specifying Uniform Chunk Names in a Dbslice

When you create a dbslice, you can use embedded formatting characters inthe pathname to generate uniform chunk names for the dbspaces that makeup a dbslice. The pathname specification with the embedded formattingcharacters is referred to as a pathname_format. A pathname format generatesunique chunk names for all of the dbspaces in a dbslice.

You can embed the following formatting characters within a pathnameformat:

%c%n%o%r(first..last)

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.1 acctg_sl.1 /dev/dbsl_acctg 1024eds.2 acctg_sl.2 /dev/dbsl_acctg 1024eds.3 acctg_sl.3 /dev/dbsl_acctg 1024eds.4 acctg_sl.4 /dev/dbsl_acctg 1024eds.5 acctg_sl.5 /dev/dbsl_acctg 1024eds.6 acctg_sl.6 /dev/dbsl_acctg 1024eds.7 acctg_sl.7 /dev/dbsl_acctg 1024eds.8 acctg_sl.8 /dev/dbsl_acctg 1024

Utilities 3-199

CREATE DBSLICE

The onutil utility substitutes values stored internally for the %c, %n, and %oformatting characters.

Creating a Dbslice from Multiple Dbspaces on Each Coserver

When you intend to create a dbslice with multiple dbspaces on each coserver,you can use the following methods to specify unique pathnames for eachdbspace on a coserver:

■ Use the %r(first..last) formatting characters in the pathname.

■ Use multiple dbslice components in the FROM clause.

Generating Pathnames with Coserver Numbers

Use the %c formatting character to generate a pathname with the coservernumber embedded in it. The coserver number is the number that theCOSERVER configuration parameter in your ONCONFIG file specifies.

The following example shows the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand with the %c formatting character embedded in the pathname:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(9..16);Cogroup successfully created.3> CREATE DBSLICE acctg_sl4> FROM COGROUP acctg_cogroup5> CHUNK "/dev/dbsl.%c.acctgdbsp"6> OFFSET 1024 SIZE 1024;

This example assumes the coserver numbers in the ONCONFIG file shown inFigure 3-5 on page 3-191, and it generates the following pathnames.

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.9 acctg_sl.1 /dev/dbsl.9.acctgdbsp 1024eds.10 acctg_sl.2 /dev/dbsl.10.acctgdbsp 1024eds.11 acctg_sl.3 /dev/dbsl.11.acctgdbsp 1024...eds.16 acctg_sl.8 /dev/dbsl.16.acctgdbsp 1024


CREATE DBSLICE

Generating Pathnames with Node Names

Use the %n formatting character to generate a pathname with the host nameof the node, or node name, embedded in it. The node name is the value thatthe NODE configuration parameter in your ONCONFIG file specifies.

The following example shows the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand with the %n formatting character embedded in the pathname:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..8);Cogroup successfully created.3> CREATE DBSLICE acctg_sl4> FROM COGROUP acctg_cogroup5> CHUNK "/dev/dbsl.%n.acctgdbsp"6> OFFSET 1024 SIZE 1024;

This example assumes the coserver numbers in the ONCONFIG file shown inFigure 3-5 on page 3-191, and it generates the following pathnames.

Generating Pathnames with Dbspace Ordinal Numbers

Use the %o formatting character to generate a pathname with the dbspaceordinal number embedded in it. The database server automatically generatesthe dbspace ordinal number when you create a dbslice. The ordinal numberindicates the order in which the dbspaces were created. The ordinal numberstarts at 1 and increments to the total number of dbspaces in the dbslice.

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.1 acctg_sl.1 /dev/dbsl.node1.acctgdbsp 1024eds.2 acctg_sl.2 /dev/dbsl.node2.acctgdbsp 1024eds.3 acctg_sl.3 /dev/dbsl.node3.acctgdbsp 1024...eds.8 acctg_sl.8 /dev/dbsl.node8.acctgdbsp 1024

Utilities 3-201

CREATE DBSLICE

The following example shows the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand with the %o formatting character embedded in the pathname:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(9..16);Cogroup successfully created.3> CREATE DBSLICE acctg_sl4> FROM COGROUP acctg_cogroup5> CHUNK "/dev/dbsl.%o.acctgdbsp"6> OFFSET 1024 SIZE 1024;

The preceding example assumes the coserver numbers in the ONCONFIG fileshown in Figure 3-5 on page 3-191. Therefore, the preceding examplegenerates the following pathnames.

Generating Pathnames for Multiple Dbspaces per Coserver

You can create multiple uniform dbspaces per coserver within the samedbslice. Use the %r(first..last) formatting characters to generate uniquepathnames for each dbspace on a coserver.

The following example shows the onutil CREATE DBSLICE command tocreate three dbspaces on each coserver within the acctg_cogroup cogroupcreated in the previous example:

% onutil1> CREATE DBSLICE acctg_sl2> FROM COGROUP acctg_cogroup3> CHUNK "/dev/dbsl_acctg.%r(1..3)"4> OFFSET 1024 SIZE 1024;

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.9 acctg_sl.1 /dev/dbsl.1.acctgdbsp 1024eds.10 acctg_sl.2 /dev/dbsl.2.acctgdbsp 1024eds.11 acctg_sl.3 /dev/dbsl.3.acctgdbsp 1024...eds.16 acctg_sl.8 /dev/dbsl.8.acctgdbsp 1024


CREATE DBSLICE

The database server creates the following dbspaces on the eight coservers.

Generating Pathnames with a Combination of Formatting Characters

The following rules describe how to combine the formatting characters:

■ You can combine the %r(first..last) formatting characters with anynumber of %c, %n, and %o formatting characters in a single dbslicecomponent.

■ You can specify multiple instances of the %c, %n, and %o formattingcharacters in a single dbslice component.

■ You can specify the %r(first..last) formatting characters only once in apathname format.

Creating Two Dbspaces on Each Coserver for Cogroup acct_cogroup

The following example shows the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand to create two dbspaces on each coserver for this cogroup:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..8);Cogroup successfully created.3> CREATE DBSLICE acctg_sl4> FROM cogroup acctg_cogroup5> CHUNK "/dev/dbsl_acctg.%n.%r(1..2)"6> SIZE 1024;

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.9 acctg_sl.1 /dev/dbsl_acctg.1 1024eds.9 acctg_sl.2 /dev/dbsl_acctg.2 1024eds.9 acctg_sl.3 /dev/dbsl_acctg.3 1024eds.10 acctg_sl.4 /dev/dbsl_acctg.1 1024eds.10 acctg_sl.5 /dev/dbsl_acctg.2 1024eds.10 acctg_sl.6 /dev/dbsl_acctg.3 1024...eds.16 acctg_sl.22 /dev/dbsl_acctg.1 1024eds.16 acctg_sl.23 /dev/dbsl_acctg.2 1024eds.16 acctg_sl.24 /dev/dbsl_acctg.3 1024

Utilities 3-203

CREATE DBSLICE


Creating Three Dbspaces on Each Coserver in Different Directories

You might want to spread the dbspaces among different drives to improveperformance and parallel I/O. The following example shows the onutilCREATE DBSLICE command to create a dbslice that contains dbspaces in threedifferent directories on each coserver. The cogroup, workgroup, containsthree coservers.

% onutil1> CREATE DBSLICE slice52> FROM cogroup workgroup3> CHUNK "/work%r(3..5)/dbspaces/slice5.%c"4> SIZE 200 MBYTES;

In the chunk names, the formatting character %c is replaced with the coservernumber. The %r formatting character expands into the following directorynames on each coserver: work3, work4, and work5.

The database server creates the following dbspaces on the three coservers.

Coserver Dbspace Identifier Pathname of Primary Chunk Offseteds.1 acctg_sl.1 /dev/dbsl_acctg.node1.1 1024eds.1 acctg_sl.2 /dev/dbsl_acctg.node1.2 1024eds.2 acctg_sl.3 /dev/dbsl_acctg.node2.1 1024eds.2 acctg_sl.4 /dev/dbsl_acctg.node2.2 1024...eds.8 acctg_sl.15 /dev/dbsl_acctg.node8.1 1024eds.8 acctg_sl.16 /dev/dbsl_acctg.node8.2 1024

Coserver Dbspace Name Pathname of Primary Chunkeds.1 slice5.1 /work3/dbspaces/slice5.1eds.1 slice5.2 /work4/dbspaces/slice5.1eds.1 slice5.3 /work5/dbspaces/slice5.1eds.2 slice5.4 /work3/dbspaces/slice5.2eds.2 slice5.5 /work4/dbspaces/slice5.2eds.2 slice5.6 /work5/dbspaces/slice5.2eds.3 slice5.7 /work3/dbspaces/slice5.3eds.3 slice5.8 /work4/dbspaces/slice5.3eds.3 slice5.9 /work5/dbspaces/slice5.3


CREATE DBSLICE

Specifying Nonuniform Dbspaces in a Dbslice

You can create nonuniform dbslices when you use multiple dbslice compo-nents in the FROM clause of the onutil CREATE DBSLICE command.

The following examples show the onutil CREATE COGROUP command tocreate a cogroup for eight coservers and the onutil CREATE DBSLICEcommand to create a nonuniform dbslice for this cogroup and the defaultcogroup_all that contains sixteen coservers:

% onutil1> CREATE COGROUP acctg_cogroup2> FROM eds.%r(1..8);Cogroup successfully created.3> CREATE DBSLICE dbsl4> FROM COGROUP acctg_cogroup5> CHUNK "/dev/dbsl_acctg"6> SIZE 2056,7> COGROUP cogroup_all8> CHUNK "/dev/dbsl_all"9> OFFSET 1024 SIZE 1024;

This example assumes the coserver numbers in the ONCONFIG file shown inFigure 3-5 on page 3-191 and generates the following dbspace names andpathnames.

Mirroring Dbspaces in a Dbslice

You can mirror chunks in your dbslice when you use the MIRROR option inthe onutil CREATE DBSLICE command. Specify mirror chunk pathnames inthe same way as for a primary chunk, including the use of formattingcharacters.

Coserver Dbspace Name Chunk Offseteds.1 dbsl.1 /dev/dbsl_acctg 0eds.2 dbsl.2 /dev/dbsl_acctg 0...eds.8 dbsl.8 /dev/dbsl_acctg 0eds.9 dbsl.9 /dev/dbsl_all 1024eds.10 dbsl.10 /dev/dbsl_all 1024...eds.16 dbsl.16 /dev/dbsl_all 1024

Utilities 3-205

CREATE DBSLICE

The following example shows the onutil CREATE DBSLICE command tocreate mirror dbspaces on each coserver in the acctg_cogroup cogroup:

% onutil1> CREATE DBSLICE acctg_sl2> FROM COGROUP acctg_cogroup3> CHUNK "/dev/dbsl_acctg.%r(1..2)"4> OFFSET 1024 SIZE 10245> MIRROR "/dev/mirr_dbsl_acctg.%r(1..2)";


Defining Temporary Dbspaces in a Dbslice

To create temporary dbspaces on each coserver, specify the TEMP keyword inthe onutil CREATE DBSLICE command. Some SQL queries create and accesslarge temporary files.

You cannot mirror a temporary dbslice.

For more information, see creating dbslices in the chapter on managing diskspace in the Administrator’s Guide.

Coserver Dbspace Identifier Primary or Mirror Chunk Offseteds.1 acctg_sl.1 /dev/dbsl_acctg.1 1024eds.1 /dev/mirr_dbsl_acctg.1 0eds.1 acctg_sl.2 /dev/dbsl_acctg.2 1024eds.1 /dev/mirr_dbsl_acctg.2 0eds.2 acctg_sl.3 /dev/dbsl_acctg.1 1024eds.2 /dev/mirr_dbsl_acctg.1 0eds.2 acctg_sl.4 /dev/dbsl_acctg.2 1024eds.2 /dev/mirr_dbsl_acctg.2 0...eds.8 acctg_sl.15 /dev/dbsl_acctg.1 1024eds.8 /dev/mirr_dbsl_acctg.1 0eds.8 acctg_sl.16 /dev/dbsl_acctg.2 1024eds.8 /dev/mirr_dbsl_acctg.2 0


CREATE DBSPACE

Modifying a Dbspace Within a Dbslice

To modify individual dbspaces that were generated when you created adbslice, use the onutil ALTER DBSPACE command. For more informationabout how to use this command, refer to “ALTER DBSPACE” on page 3-159.

Adding Dbspaces to a Dbslice

To add dbspaces to a dbslice, use the onutil ALTER DBSLICE ADD DBSPACEcommand. For more information, see “ALTER DBSLICE ADD DBSPACE” onpage 3-150.

CREATE DBSPACEUse the onutil CREATE DBSPACE command to create a new dbspace ortemporary dbspace.

Syntax

Utilities 3-207

CREATE DBSPACE

CREATE DBSPACE dbspace_name ChunkDefinition

MirrorDefinition

ChunkDefinition

SIZE size

KBYTES

CHUNK

OFFSET offset

MBYTES

GBYTES

MirrorDefinition

MIRROR

OFFSET offset

TEMP

" pathname "

" pathname "

COSERVER

coserver_name

coserver_number


CREATE DBSPACE

Element Purpose Restrictions Syntaxdbspace_name The dbspace to create For the restrictions, see creating a

dbspace in the chapter on managingdisk space in the Administrator’s Guide.

See “Dbspace Name”on page 3-146.

coserver_name

Name of the coserver onwhich the dbspace is toreside

The coserver name must have thefollowing format:


The value for dbservername must be thesame value that the DBSERVERNAMEconfiguration parameter specifies.

The value for coserver_number must beone of the integers that the COSERVERconfiguration parameter specifies.

See “CoserverName” onpage 3-142.

coserver_number

The number of thecoserver on which thedbspace is to reside

The coserver number must be one of theintegers that the COSERVER configu-ration parameter specifies.

Unsigned integer.

pathname The file or raw device ofthe first chunk of the newdbspace

The chunk must be an existing file orraw device. Use a full pathname.

Pathname mustconform to the rulesspecific to youroperating system.

offset The offset, in kilobytes,into the file or raw deviceto reach the chunk

Value must be greater than 0. Seeallocating raw disk space on UNIX inthe chapter on managing disk space inthe Administrator’s Guide.

Unsigned integer.

size The size of the initialchunk of the new dbspace

Value must be greater than 0. Size mustnot exceed 4 gigabytes.

Unsigned integer;default size unit iskilobytes.

Utilities 3-209

CREATE DBSPACE

UsageUse the onutil CREATE DBSPACE command to create a new dbspace ortemporary dbspace on a coserver. The database server must be in on-line orquiescent mode when you create a dbspace or temporary dbspace.

When you create separate dbspaces without using a dbslice, a specificcoserver owns and manages each dbspace. The physical disk on which thedbspace resides belongs to the node on which the coserver executes. Thiscoserver is referred to as the home coserver.

Defining a Temporary Dbspace

You can create a temporary dbspace on a coserver when you specify theTEMP keyword in the onutil CREATE DBSPACE command.

You cannot mirror a temporary dbslice.

For more information about what a temporary dbspace is, refer to the chapteron where data is stored in the Administrator’s Guide.

Keyword Description

DBSPACE Specifies the name of the new dbspace.

CHUNK Specifies the file or raw device of the chunk that you want to add.Use the SIZE option in the chunk definition, followed by a size ineither kilobytes, megabytes, or gigabytes, to specify a size for thenew dbspace.

MIRROR Specifies the file or raw device of the chunk that performs themirroring. Use the MIRROR keyword when you want to mirror thenew chunk.


CREATE DBSPACE

Using the Coserver Option

When you do not specify the COSERVER option, the database server assignsthe dbspace to coserver number 1.

The following example shows the onutil CREATE DBSPACE command tocreate a dbspace that coserver eds.2 owns:

% onutil1> CREATE DBSPACE acctg_dbsp2> CHUNK "/work/dbspaces/dbs_0"3> OFFSET 0 size 15004> COSERVER eds.2;

Utilities 3-211

CREATE LOGICAL LOG

CREATE LOGICAL LOGThe onutil CREATE LOGICAL LOG command allows you to add a logical-logfile.

Syntax

CREATE

LOGICAL

LOG DBSPACE

SIZE size

dbspace_identifier

dbspace_name

GBYTES

MBYTES

KBYTES


CREATE LOGICAL LOG

Element Purpose Restrictions Syntaxdbspace_name Name of the dbspace

where the logical-logfile resides

The space that is allocated for a logical-log file must be contiguous. Thedatabase server does not allow you toadd a log file to a dbspace withoutadequate contiguous space.

You cannot add a log file during abackup.

See “DbspaceName” onpage 3-146.

dbspace_identifier Generated name of thedbspace where thelogical log resides

The database servergenerates the namewhen you create adbslice.

The dbspace identifier must be anexisting dbspace that was generatedwhen you created a dbslice. The namemust be of the form:

slicename.ordinal

The value for slicename must be the sameas the dbslice name that you used whenyou created the dbslice.

The ordinal value must be an unsignedinteger.

See “DerivedDbspace Identifier”on page 3-146.

size The size of the newlogical-log file

Value must be greater than or equal tothe minimum of 200 kilobytes. If you donot specify a SIZE clause, the size of thelog file is taken from the value of theLOGSIZE parameter in the ONCONFIGfile when database server disk spacewas initialized. (See changing LOGSIZEor LOGFILES in the chapter onmanaging logical-log files in theAdministrator’s Guide.)

Unsigned integer;the default unit iskilobytes.

Utilities 3-213

CREATE LOGICAL LOG

UsageThe database server must be in quiescent mode when you add a logical-logfile. Use the onutil CREATE LOGICAL LOG command to add a new logical-logfile. You can use the following keywords.

The following example shows how to add a logical log to the root dbspace. Ifyou receive an error message that states that the maximum number of logicallogs has been exceeded, use the LOGSMAX parameter to increase themaximum number of logical logs and reinitialize the shared memory.

% onutil1> CREATE LOG DBSPACE rootdbs2> SIZE 1400;Logical log successfully added.

To monitor the logical-log status, use the onstat -l command. For more infor-mation, see “The onstat -l Option” on page 3-113.

Keyword Description

LOGICAL Does not change the command. This keyword is optional.

DBSPACE Specifies the name of the dbspace in which the new logical log resides.

SIZE Specifies the size of the new logical-log file in kilobytes, megabytes, orgigabytes.


CREATE LOGICAL LOGSLICE

CREATE LOGICAL LOGSLICEThe onutil CREATE LOGICAL LOGSLICE command allows you to add alogslice.

Syntax

Element Purpose Restrictions Syntaxlogslice_name Name of the

logsliceThe name must identify an existing logslice. See “Identifiers in

onutil Commands”on page 3-140.

dbslice_name The name of thedbslice where thelogical logsliceresides

The name must identify an existing dbslice.One log file is put into every dbspace of thisdbslice.


size The size of eachnew logical-log file

Value must be greater than or equal to 200kilobytes. If you do not specify a SIZE clause,the size of the files in the logslice is taken fromthe value of the LOGSIZE parameter in theONCONFIG file when database server diskspace was initialized. (See changing LOGSIZE,LOGFILES, or LOGSMAX in the chapter onmanaging logical-log files in the Administrator’sGuide.)

Unsigned integer;the default unit iskilobytes.

CREATE

LOGICAL

LOGSLICE

SIZE size

IN DBSLICE dbslice_namelogslice_name

KBYTES

MBYTES

GBYTES

Utilities 3-215

CREATE LOGICAL LOGSLICE

UsageUse the onutil CREATE LOGICAL LOGSLICE command to add a new logicallogslice. A logslice enables you to manage logical logs across multiplecoservers. For more information, see managing logical-log files on a coserverin the chapter on logical logs in the Administrator’s Guide.

The database server must be in quiescent mode before you can add a logicallogslice. Specify the keywords and options as follows.

The space allocated for a logical-log file must be contiguous. The databaseserver does not allow you to add a log file to a dbspace without adequatecontiguous space.

You cannot add a logslice during a backup (whether the database server isquiescent or on-line).

The following example shows the onutil CREATE LOGSLICE command tocreate a logical logslice:

% onutil1> CREATE LOGSLICE logslice3 IN DBSLICE dbslice22> SIZE 20 MBYTES;

Adding More Logs to a Logslice

After you alter a dbslice that contains a logslice, you can add new logical-logfiles to the logslice. Thus, each new dbspace in the dbslice gets its own log file.For more information, see “ALTER LOGSLICE ADD LOGS” on page 3-167.

Keyword Description

LOGICAL Does not change the command. This keyword is optional.

IN DBSLICE Specifies the name of the dbslice in which the new logical logsliceresides.

SIZE Specifies the size of each log file of the logslice in kilobytes,megabytes, or gigabytes.


DISPLAY PAGE

DISPLAY PAGEThe onutil DISPLAY PAGE command displays contents of a single logical pageon the user’s terminal.

Syntax

DISPLAY PAGE

chunk_number

TABLE

IN TABLESPACE partnumpagenum

TABLE

:database

owner .

table_name

,

offset

IN TABLE

INDEXpagenum

pagenum

:

COUNT nbr

HEADER

HEX

SAVE

IN filename

dbspace_name

INDEX

#database

owner .

index_name

,IN INDEX

dbspace_name

Utilities 3-217

DISPLAY PAGE

UsageThe onutil DISPLAY PAGE and DISPLAY PAGE IN TABLESPACE commandsdisplay the contents of a single page on the terminal.

You use the onutil DISPLAY PAGE pagenum IN TABLESPACE or onutil DISPLAYPAGE chunk_number:offset command in off-line mode.

Element Purpose Restrictions Syntaxpagenum An integer value that you use

to indicate a particular pagein a tblspace

Value must be an unsignedinteger between 0 and16,777,215, inclusive.

Unsigned integer.

partnum The tblspace number that youwant to display


Unsigned integer.

chunk_number The number of the chunk thatyou want to display

The chunk number must exist. Unsigned integer.

offset The number of pages into thechunk where you want tostart the display

Unsigned integer.

nbr The number of pages that youwant to display

Unsigned integer.

filename The filename that you want tocontain the output of theonutil command.

database The name of the databasewhere the table resides

The database must exist.You cannot check databases onremote database servers.

See the Informix Guide toSQL: Syntax.


Owner that you specify must becurrent owner of table. Owner ismandatory for ANSI databases.

The user name mustconform to the conven-tions of your operatingsystem.

dbspace_name The name of the dbspacewhere the page resides

The dbspace must exist. See “Dbspace Name” onpage 3-146.

table_name The name of the table thatyou want to display

Table must exist. See “Identifiers in onutilCommands” onpage 3-140.

index_name The name of the index thatyou want to display

The index must exist. See Object Name in theInformix Guide to SQL:Syntax.


DISPLAY PAGE

The DISPLAY PAGE command, when run without the HEX keyword, displaysthe page header whether it recognizes the page type. It attempts to displaythe body of the page in the appropriate format. If it does not recognize thepage type, it does not print anything after the header. Use the HEX keywordto display the entire page in hexadecimal format with an ASCII translation ofeach byte on the right side.

The following example shows the onutil DISPLAY PAGE command to displaypage information in tblspace 1111:

% onutil1> DISPLAY PAGE 0xF IN TABLESPACE 0x10001;

You can use the onutil DISPLAY PAGE and DISPLAY PAGE IN TABLESPACEcommands in off-line mode. You must specify a local single coserver name,as in the following example:

% onutil1> DISPLAY PAGE 5:4 COSERVER eds.3;

Utilities 3-219

DROP COGROUP

DROP COGROUPUse the onutil DROP COGROUP command to drop one or more cogroups.

Syntax



prefix


cogroup_name



DROP COGROUP

suffixprefix

first last.. )(%r


DROP COGROUP

UsageUse the onutil DROP COGROUP command to delete one or more cogroups. Ifyou specify a cogroup range identifier, the database server drops the list ofcogroups that the cogroup range identifier represents.

Element Purpose Restrictions Syntaxcogroup_name The name of a coserver or

cogroup in the database serverName must be unique within adatabase server.

See “CogroupName” onpage 3-141.

prefix The alphabetic portion of thegenerated cogroup name thatprecedes the formattingcharacter


See “Identifiers inonutil Commands”on page 3-140 and“Coserver List” onpage 3-143.

suffix The alphabetic portion of thegenerated cogroup name thatfollows the formatting character


See “Identifiers inonutil Commands”on page 3-140 and“Coserver List” onpage 3-143.

first The starting value of the integerto substitute for the coservername


Unsigned integer.

last The ending value of the integerto substitute for the coservername


Unsigned integer.

Utilities 3-221

DROP DBSLICE

DROP DBSLICEThe onutil DROP DBSLICE command allows you to drop a dbslice.

Syntax

UsageUse the onutil DROP DBSLICE command to drop dbspaces that belong to adbslice. The database server must be in on-line or quiescent mode when youdrop a dbslice.

Element Purpose Restrictions Syntaxdbslice_name Name of the dbslice to

dropThe dbslice name must have beencreated with the onutil CREATEDBSLICE command. All deriveddbspaces in the dbslice must be empty.

See “Dbslice Name”on page 3-146.

DROP DBSLICE dbslice_name


DROP DBSPACE

DROP DBSPACEThe onutil DROP DBSPACE command allows you to drop a dbspace.

Syntax

UsageUse the onutil DROP DBSPACE command to drop a dbspace or a temporarydbspace. The database server must be in on-line or quiescent mode when youdrop a dbspace or temporary dbspace.

Element Purpose Restrictions Syntaxdbspace_identifier The generated names

of the dbspaces thatyou want to drop

The value must be an existing dbspacethat was generated when you createda dbslice. Name must be of the form:

slicename.ordinal

The value of slicename must be thesame as the dbslice name that youused when you created the dbslice.

The value of ordinal must be anunsigned integer.

See “DerivedDbspace Identifier”on page 3-146.

dbspace_name Name of the dbspacethat you want to drop

None. See “Dbspace Name”on page 3-146.

DROP DBSPACE dbspace_identifier

dbspace_name

Utilities 3-223

DROP LOGICAL LOG

DROP LOGICAL LOGThe onutil DROP LOGICAL LOG command allows you to drop a logical-logfile.

Syntax

Element Purpose Restrictions Syntaxlogid Name of the logical-

log file to dropThe database server requires aminimum of three logical-log files atall times. The database server mustbe in quiescent mode when you drop alogical log.

You can drop only log files that havestatus of Free (F) or newly Added (A).To view the status of the logical logs,use xctl onstat -l.

Unsigned integer.

coserver_name Name of the coserverfrom which to dropthe logical log

The coserver name must have thefollowing format:


The value of dbservername must be thesame as the value in theDBSERVERNAME configurationparameter.

The value of coserver_number must beone of the integers that the COSERVERconfiguration parameter specifies.


coserver_number The number of thecoserver on which thedbspace is to reside

The coserver number must be one ofthe integers that the COSERVERconfiguration parameter specifies.

Unsigned integer.

DROP LOG logid

LOGICAL COSERVER coserver_number

coserver_name


DROP LOGICAL LOG

UsageThe onutil DROP LOGICAL LOG statement to drop a logical-log file is one ofthe steps in the procedure for moving logical-log files to another dbspace.The database server must be in quiescent mode when you drop a logical-logfile.

Use the LOG clause, followed by a logid to specify which logical-log file youwant to drop. (You can obtain the logid of a logical log from the number fieldof xctl onstat -l.) After your configuration reflects the desired number of logfiles, create a level-0 backup of the root dbspace. For information about howto create a level-0 backup, see the Backup and Restore Guide.

A specific coserver owns and manages each dbspace. This coserver isreferred to as the home coserver. You can specify the home coserver with theCOSERVER option.

When you do not specify the COSERVER option, the database server drops thelogical log from coserver number 1.

Utilities 3-225

DROP LOGSLICE

DROP LOGSLICEThe onutil DROP LOGSLICE command allows you to drop a logical logslice.

Syntax

UsageUse the onutil DROP LOGSLICE command to drop a logical logslice. Thedatabase server must be in quiescent mode when you drop a logslice.

Element Purpose Restrictions Syntaxlogslice_name Name of an existing

logslice to dropThe keyword LOGICAL is optionaland does not change the command.

See “Logslice Name”on page 3-147.

DROP LOGSLICE

LOGICAL

logslice_name


xctl: Execute Utilities Across Coservers

xctl: Execute Utilities Across CoserversThe xctl utility lets you execute database server utilities on one or morecoservers and execute operating-system commands on one or more nodes.You can invoke the xctl utility on any node in your platform or from anycomputer that can initiate commands remotely on your platform.

Syntax

XPS

xctl

-Xs -b

-i

command

-ddirectory

,

start_num end_num-

,

c-opts

-C

env_var_name-e

-c coserver_num

Utilities 3-227


UsageThe xctl utility uses the NODE parameter in each coserver-specific section ofyour configuration file to execute database server utilities on one or morecoservers. For more information, refer to setting the coserver-specific param-eters in the chapter on configuration parameters in the Administrator’s Guide.

Important: To use the xctl utility, you must ensure that all coserver nodes are listedin the sqlhosts connectivity file.

You can specify several options in the xctl command. You can specify theseoptions in any order:

Element Purpose-Xs Specifies a substitution character that stands for the coserver number. Replace s with a

substitution character that can be used in arguments to command. Informix recom-mends = or . as substitution characters. For details, see “Specifying Coservers” onpage 3-230. You might need to use an escape character before some special charactersto prevent interpretation by a particular operating-system shell.

-b Indicates that the command or operation is to be performed in the background on eachapplicable node.

-i Indicates that xctl is to print a message command or that operation is to be performedinteractively; xctl asks for confirmation before it routes the command to each node.

-ddirectory Specifies the name of the directory on each applicable node in which to perform thecommand; directory must be a valid pathname on the target node or nodes. Do not typea space between -d and the directory name.

-e en_var_name Specifies an environment variable to export to each node. The variable must be definedin the environment of the user that performs the xctl command, and it must conform tothe naming conventions for the target nodes.

-C Indicates that the command is to be executed for every coserver. This option isequivalent to the following xctl command:

xctl -b -X= command -yX=

The command is performed on the nodes assigned to each coserver. Use this optiononly with the oninit command.

-c coserver_numstart_num -end_num

Specifies the coserver number of a single coserver or a range of coserver numbers. Theindicated command is performed on the nodes assigned to the indicated coservers.Each coserver number must be listed in the ONCONFIG file. You can specify a list ofcoserver numbers. The list can include a range of coserver numbers.

commandc-opts

Specifies a database server utility or operating-system command. Typical databaseserver utilities to use with xctl are as follows: oninit, onlog, onmode, and onstat.



■ Working directory

■ Environment variables

■ Coserver numbers

■ Interactive or background processing

■ Wait time for coserver initialization

Specifying the Working Directory

The working directory is where the remote command executes. If you use the-b option and the command creates any output, a file calledstdout.coserver_num is created in the working directory.

If you use the -b option and the command creates any error messages, a filecalled stderr.coserver_num is created in the working directory.

The remote command executes in the home directory of the user by default.You can use the -d option to specify the remote directory where you want toexecute the command.

You can use the -d option to specify a working directory on each node. If youuse the -d option without a directory argument, xctl obtains the name of thecurrent working directory.

Setting Environment Variables

You must set INFORMIXDIR and ONCONFIG before you execute xctl. Whenyou execute xctl, the environment variables INFORMIXDIR, ONCONFIG,LANG, and PATH are copied to the environment of the remote command. Usethe -e option to copy additional environment variables to the remoteenvironment.

File Purpose

stdout.coserver_num For output and completion messages

stderr.coserver_num For error messages

Utilities 3-229


Specifying Coservers

By default, xctl executes the specified command-line utility once on the nodeassigned to each coserver that your ONCONFIG file defines. The -Xs optionreplaces any instance of s in the cmd-opts list with the coserver number of eachcoserver in turn. The first -Xs option indicates that any instance of s is to bereplaced in the cmd-opts list.

The following examples show operations that you would want to execute onevery coserver:

■ Start all of the coservers that your ONCONFIG configuration filedefines.

xctl -C -b oninit

■ Shut down the database server.xctl onmode -ky

The -c option allows you to specify a subset of coservers. The nodes thatcorrespond to those coservers perform the command. You can specifyindividual coserver numbers or a range of coserver numbers. For example, todisplay the status of dbspaces and chunks on coservers with coservernumbers 12 through 15, enter the following command:

xctl -c 12-15 onstat -d

Selecting Interactive or Background Processing

You can select which type of processing to use when you enter the xctlcommand.

Background Processing

The -b option starts each command in the background, and xctl exits withoutwaiting for the commands to finish.

Important: You must use the -b option when you start more than one coserver.

The following example shows the start-up command in the background ifyou have defined a large number of coservers in your ONCONFIG configu-ration file:

xctl -b -X= oninit -yX=



Interactive Processing

The -i option displays each remote command as that commands starts. Whenyou enter the end-of-file character (usually CTRL-D), you end execution onlyfor the remote command that is currently running.

Any output that the remote commands generate is preceded by a messagethat identifies which coserver produced the output.

Execution on Multiple NodesThe xctl command uses remote access to initiate execution of commands onremote nodes. The remote command executes with the same login and groupIDs as the initiating user.

Important: You must ensure that database server administrators have remote-loginaccess on every node that supports a coserver.

If initial communication between xctl and any node stalls for more than 20seconds, the node is assumed to have failed, and xctl goes on to the nextnode. The xctl command returns a nonzero result code when it exits.

Utilities 3-231

4Chapter

ON-Monitor

In This Chapter . . . . . . . . . . . . . . . . . . . . 4-3

Using ON-Monitor . . . . . . . . . . . . . . . . . . . 4-3Navigating ON-Monitor and Using Help . . . . . . . . . . 4-4Executing Shell Commands Within ON-Monitor . . . . . . . 4-4

ON-Monitor Screen Options . . . . . . . . . . . . . . . 4-5

Setting Configuration Parameters in ON-Monitor . . . . . . . . 4-12

4-2 Infor

In This ChapterThis section provides a quick reference for the ON-Monitor screens. You canuse it to determine the purpose and use of a specific screen or option.

Using ON-MonitorTo start ON-Monitor, execute the following command from the operating-system prompt:

% onmonitor

If you are logged in as user informix or user root, the main menu appears.All users other than informix and root have access only to the Status menu.

The ON-Monitor main menu displays six additional menus, the Force-Ckptoption, and the Exit option. The six additional menus are as follows:

■ Status menu

■ Parameters menu

■ Dbspaces menu

■ Mode menu

■ Archive menu

■ Logical-Logs menu

The main menu, the six additional menus, and the Force-Ckpt option areshown on the following pages (Figure 4-1 on page 4-5 through Figure 4-7 onpage 4-11).

IDS

UNIX

ON-Monitor 4-3

Navigating ON-Monitor and Using Help

Navigating ON-Monitor and Using HelpAll menus and screens in ON-Monitor function in the same way. For menus,use the arrow keys or SPACEBAR to scroll to the option that you want toexecute and press RETURN, or press the first capitalized letter of the option(usually the first letter). When you move from one option to the next bypressing SPACEBAR or an arrow key, the option explanation (line 2 of themenu) changes.

If you want general instructions for a specific screen, press CTRL-W. If youneed help to determine what you should enter in a field on the screen, use theTAB key to highlight the field and press CTRL-F or F2.

Some of the menus display ellipses (...) on the far right or left side. Theellipses indicate that you can move in the direction of the dots, using thearrow keys or SPACEBAR, to view other options.

Executing Shell Commands Within ON-MonitorTo execute a shell command from within ON-Monitor, type an exclamationpoint (!) followed by the command. For example, to list the files in thecurrent directory, type the following command:

!ls


ON-Monitor Screen Options

ON-Monitor Screen OptionsThe following pages show the options that are available from theON-Monitor menus and describe what the options do.

Figure 4-1Status Menu

ExitStatus

Exit

Profile

Userthreads

Spaces

Databases

Logs

Archive

Output

Configuration

Use the Profile option to display database server performance statistics.

Use the Userthreads option to display the status of active user threads.

Use the Spaces option to display status information about database server storagespaces or each chunk that is part of a storage space.

Use the Databases option to display the name, owner, and logging status of the first100 databases.

Use the Logs option to display status information about the physical-log buffer, thephysical log, the logical-log buffer, and the logical-log files.

Use the Archive option to display a list of all archive tapes and logical log files thatwould be needed if a data restore using ontape were required now.

Use the Output option to store the output of any other status information in a specifiedfile.Use the Configuration option to create a copy of the current database server configu-ration to a specified file.

Dbspaces Mode Archive Logical-LogsForce-CkptParameters

data-Replication Use the data-Replication option to display data-replication status and configuration.

ON-Monitor 4-5


Figure 4-2Parameters Menu

ExitDbspaces Mode Archive Logical-LogsForce-Ckpt

Exit

Initialize Use the Initialize option to initialize database server disk space or to modifydatabase server disk-space parameters.

Shared- Use the Shared-Memory option to initialize database server shared-memory orto modify database server shared-memory parameters.

Add-Log Use the Add-Log option to add a logical-log file to a database server dbspace.

Drop-Log Use the Drop-Log option to drop a logical-log file from a database serverdbspace.

Physical-Log Use the Physical-Log option to change the size or the location of the databaseserver physical log.

Memory

Status Parameters

perFormance Use the perFormance option to specify the number of virtual processors for eachVP class.

data-Replication Use the data-Replication option to specify the data-replication parameters.

diaGnostics Use the diaGnostics option to specify values for the diagnostics parameters.

pdQ Use the pdQ option to change parameters for parallel database queries.



Figure 4-3Dbspaces Menu

ExitMode Archive Logical-LogsForce-CkptStatus Parameters

Exit

Create Use the Create option to create a dbspace.

BLOBSpace Use the BLOBSpace option to create a blobspace.

Mirror Use the Mirror option to add mirroring to an existing storage space or to endmirroring for a storage space.

Drop Use the Drop option to drop a storage space from the database serverconfiguration.

Info Use the Info option to see the identification number, location, and fullness ofeach chunk assigned to a storage space.

Add_chunk Use the Add_chunk option to add a chunk to a storage space.

Status Use the Status option to change the status of a chunk in a mirrored pair.

Dbspaces

datasKip Use the datasKip option to change the database parameter.

ON-Monitor 4-7


Figure 4-4Mode Menu

ExitArchive Logical-LogsForce-CkptStatus Parameters Dbspaces Mode

Exit

Startup Use the Startup option to initialize shared memory and take thedatabase server to quiescent mode.

On-Line Use the On-Line option to take the database server fromquiescent to on-line mode.

Graceful- Use the Graceful-Shutdown option to take the database serverfrom on-line to quiescent mode. Users can complete their

Immediate- Use the Immediate-Shutdown option to take the databaseserver from on-line to quiescent mode in 10 seconds.

Take- Use the Take-Offline option to detach shared memory andimmediately take the database server to off-line mode.

Shutdown

Offline

Shutdown

Drop- Use the Drop-Proc option to drop virtual processors.Proc

Add- Use the Add-Proc option to add virtual processors.Proc

deCision- Use the deCision-support option to set decision-supportparameters dynamically.support



Figure 4-5Force-Ckpt Option

Mode Archive Logical-Logs ExitStatus Parameters Dbspaces Force-Ckpt

Use the Force-Ckpt option to see the time of the most-recent checkpoint or to force the database server toexecute a checkpoint.

ON-Monitor 4-9


Figure 4-6Archive Menu

Archive

Exit

Mode Logical-Logs ExitStatus Parameters Dbspaces Force-Ckpt

Tape-Use the Tape-Parameters option to modify the parameters of the ontapearchive tape device. Parameters



Figure 4-7Logical-Logs Menu

Dbspaces Mode Archive Logical-LogsForce-Ckpt ExitStatus Parameters

Exit

DatabasesUse the Databases option to modify the logging status of a database.

Tape-Use the Tape-Parameters option to modify the parameters of the ontapelogical-log backup tape device. Parameters

ON-Monitor 4-11

Setting Configuration Parameters in ON-Monitor

Setting Configuration Parameters in ON-MonitorEach ON-Monitor parameters screen is represented here by a pair ofexamples (Figure 4-8 through Figure 4-18). The first example in each pairshows the ON-Monitor screen. The second example in each pair shows whichparameters from the ONCONFIG configuration file correspond to the param-eters screen.

INITIALIZATION: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DISK PARAMETERSPage Size [ 2] Kbytes Mirror [N]

Tape Dev. [/dev/tapedev ]Block Size [ 16] Kbytes Total Tape Size [ 10240] KbytesLog Tape Dev. [/dev/tapedev ]Block Size [ 16] Kbytes Total Tape Size [ 10240] KbytesStage Blob [ ]

Root Name [rootdbs ] Root Size [ 20000] KbytesPrimary Path [/dev/cynsrv_root ]

Root Offset [ 0] KbytesMirror Path [ ]

Mirror Offset [ 0] KbytesPhy. Log Size [ 1000] Kbytes Log. Log Size [ 500] Kbytes

Number of Logical Logs [ 6 ]

Figure 4-8INITIALIZATION

Screen

INITIALIZATION: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DISK PARAMETERSPage Size {not in ONCONFIG} Mirror {MIRROR}

Tape Dev. {TAPEDEV}Block Size {TAPEBLK} Total Tape Size {TAPESIZE}Log Tape Dev. {LTAPEDEV}Block Size {LTAPEBLK} Total Tape Size {LTAPESIZE}Stage Blob {STAGEBLOB}

Root Name {ROOTNAME} Root Size {ROOTSIZE}Primary Path {ROOTPATH}

Root Offset {ROOTOFFSET}Mirror Path {MIRRORPATH}

Mirror Offset {MIRROROFFSET}Phy. Log Size {PHYSFILE} Log. Log Size {LOGSIZE}

Number of Logical Logs {LOGFILES}

Figure 4-9INITIALIZATION

Screen withParameter Names



SHARED MEMORY: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

SHARED MEMORY PARAMETERSServer Number [ 0] Server Name [a_server ]Server Aliases [ ]Dbspace Temp [ ]Deadlock Timeout (Secs) [ 60] Number of Page Cleaners [ 1]Forced Residency [N] Stack Size (Kbytes) [ 32]Non Res. SegSize (Kbytes) [8000] Optical Cache Size (Kbytes)[ 0]

Physical Log Buffer Size [ 32] Kbytes Dbspace Down Option [0]Logical Log Buffer Size [ 32] Kbytes Preserve Log for Log Backup [N]Max # of Logical Logs [ 6] Transaction Timeout [ 300]Max # of Locks [ 2000] Long TX HWM [ 50]Max # of Buffers [ 200] Long TX HWM Exclusive [ 60]

Index Page Fill Factor [ 90]Add SegSize (Kbytes) [ 8192]Total Memory(Kbytes) [ 0]

Resident Shared memory size [ 864] Kbytes Page Size [ 2] Kbytes

Enter a unique value to be associated with this version of Dynamic Server.

Figure 4-10Shared Memory

Screen

SHARED MEMORY: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

SHARED MEMORY PARAMETERSServer Number {SERVERNUM} Server Name {DBSERVERNAME}Server Aliases {DBSERVERALIASES}Dbspace Temp {DBSPACETEMP}Deadlock Timeout {DEADLOCK_TIMEOUT} Number of Page Cleaners {CLEANERS}Forced Residency {RESIDENCY} Stack Size (Kbytes) {STACKSIZE}Non Res. SegSize {SHMVIRTSIZE} Optical Cache Size {OPCACHEMAX}

Physical Log Buffer Size {PHYSBUFF} Dbspace Down Option {ONDBSPDOWN}Logical Log Buffer Size{LOGBUFF} Preserve Log for Log Backup{LBU PRESERVE}Max # of Logical Logs {LOGSMAX} Transaction Timeout {TXTIMEOUT}Max # of Locks {LOCKS} Long TX HWM {LTXHWM}Max # of Buffers {BUFFERS} Long TX HWM Exclusive {LTXEHWM}

Index Page Fill Factor {FILLFACTOR}Add SegSize {SHMADD}Total Memory {SHMTOTAL}

Resident Shared memory size [ ] Kbyte Page Size {not in ONCONFIG}Enter a unique value to be associated with this version of Dynamic Server.

Figure 4-11SHARED MEMORY


ON-Monitor 4-13


PERFORMANCE: Make desired changes and press ESC to record changes. Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help. PERFORMANCE TUNING PARAMETERS

Multiprocessor Machine [N] LRU Max Dirty [ 60] Num Procs to Affinity [ 0] LRU Min Dirty [ 50] Proc num to start with [ 0] Checkpoint Interval [ 300] Num of Read Ahead Pages [ 4] CPU VPs [ 1] Read Ahead Threshold [ 2] AIO VPs [ 2] Single CPU VP [N] NETTYPE settings: Use OS Time [N] Protocol Threads Users VP-class Disable Priority Aging [N] [ ] [ ] [ ] [ ] Off-Line Recovery Threads [ 10] [ ] [ ] [ ] [ ] On-Line Recovery Threads [ 1] [ ] [ ] [ ] [ ] Num of LRUS queues [ 8] [ ] [ ] [ ] [ ]

Are you running on a multiprocessor machine?

Figure 4-12PERFORMANCE

Screen

PERFORMANCE: Make desired changes and press ESC to record changes. Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help. PERFORMANCE TUNING PARAMETERS

{MULTIPROCESSOR} {LRU_MAX_DIRTY} {AFF_NPROCS} {LRU_MIN_DIRTY} {AFF_SPROC} {CKPTINTVL} {RA_PAGES} {NUMCPUVPS} {RA_THRESHOLD} {NUMAIOVPS} {SINGLE_CPU_VP} NETTYPE settings: {USE_OS_TIME} (NETTYPE values are assembled {NOAGE} from the responses in these {OFF_RECVRY_THREADS} blanks) {ON_RECVRY_THREADS} {LRUS}

Are you running on a multiprocessor machine?

Figure 4-13PERFORMANCE




DATA REPLICATION: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DATA REPLICATION PARAMETERS

Interval [ 30]Timeout [ 30]Auto [0]Lost & Found [/usr/informix/etc/dr.lostfound ]

Figure 4-14DATA REPLICATION

Screen

DATA REPLICATION: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DATA REPLICATION PARAMETERS

Interval {DRINTERVAL}Timeout {DRTIMEOUT}Auto {DRAUTO}Lost & Found {DRLOSTFOUND}

Figure 4-15DATA REPLICATION


DIAGNOSTICS: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DIAGNOSTIC PARAMETERS

Message Log [/usr/informix/server.log ]Console Msgs. [/dev/console ]Alarm Program [ ]

Dump Shared Memory [Y]Dump Gcore [N]Dump Core [N]Dump Count [ 1]Dump Directory [/tmp ]

Figure 4-16DIAGNOSTICS

Screen

ON-Monitor 4-15


DIAGNOSTICS: Make desired changes and press ESC to record changes.Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

DIAGNOSTIC PARAMETERS

Message Log {MSGPATH}Console Msgs. {CONSOLE}Alarm Program {ALARMPROGRAM}

Dump Shared Memory {DUMPSHMEM}Dump Gcore {DUMPGCORE}Dump Core {DUMPCORE}Dump Count {DUMPCNT}Dump Directory {DUMPDIR}

Figure 4-17DIAGNOSTICS


PDQ: Make desired changes and press ESC to record changes. Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

PARALLEL DATABASE QUERIES PARAMETERS

Maximum Priority [100]Decision Support Queries [ ] Decision Support Memory (Kbytes) [ ]Maximum Decision Support Scans [ 3]Dataskip [ ]Optimizer Hint [2]

Figure 4-18PDQ Screen

PDQ: Make desired changes and press ESC to record changes. Press Interrupt to abort changes. Press F2 or CTRL-F for field-level help.

PARALLEL DATABASE QUERIES PARAMETERS

Maximum Priority {MAX_PDQPRIORITY}Decision Support Queries {DS_MAX_QUERIES} Decision Support Memory (Kbytes) {DS_TOTAL_MEMORY}Maximum Decision Support Scans {DS_MAX_SCANS}Dataskip {DATASKIP}Optimizer Hint {OPTCOMPIND}

Figure 4-19PDQ Screen with

Parameter Names


5Chapter

Message-Log Messages

In This Chapter . . . . . . . . . . . . . . . . . . . . 5-3

How the Messages Are Ordered in This Chapter . . . . . . . . 5-4

How to View These Messages . . . . . . . . . . . . . . . 5-4

Message Categories . . . . . . . . . . . . . . . . . . 5-5

Messages: A-B . . . . . . . . . . . . . . . . . . . . 5-6

Messages: C . . . . . . . . . . . . . . . . . . . . . 5-8

Messages: D-E-F . . . . . . . . . . . . . . . . . . . . 5-16

Messages: G-H-I . . . . . . . . . . . . . . . . . . . . 5-20

Messages: J-K-L-M . . . . . . . . . . . . . . . . . . . 5-23

Messages: N-O-P . . . . . . . . . . . . . . . . . . . 5-29

Messages: Q-R-S . . . . . . . . . . . . . . . . . . . . 5-37

Messages: T-U-V. . . . . . . . . . . . . . . . . . . . 5-43

Messages: W-X-Y-Z . . . . . . . . . . . . . . . . . . . 5-47

Messages: Symbols . . . . . . . . . . . . . . . . . . . 5-48

Violations Table Messages . . . . . . . . . . . . . . . . 5-50

Truncate Table Messages . . . . . . . . . . . . . . . . . 5-54

5-2 Infor

In This ChapterThis chapter contains nonnumbered messages that are printed in themessage log for the database server. It lists the nonnumbered messages thatcan appear in the message log and provides explanatory notes for themessages. If numbered messages appear, see Informix Error Messages inAnswers OnLine to look up their explanations and corrective actions.

Of the messages included here, a few might require you to contact InformixTechnical Support staff. Such messages are rarely, if ever, seen at customerlocations.

For information on what the message log is, the location of the file where thedatabase server sends the messages, and some guidance on how and whenyou might want to read it, see the chapter on overview of database serveradministration.

For information on the unnumbered ON-Bar messages, see Informix ErrorMessages in Answers OnLine. For error messages that pertain to ON-Archive,see your Archive and Backup Guide.

Message-Log Messages 5-3

How the Messages Are Ordered in This Chapter

How the Messages Are Ordered in This ChapterDatabase server message-log messages are arranged in this chapter inalphabetical order, sorted with the following additional rules:

■ The time stamp that precedes each message is ignored.

■ Letter case is ignored in alphabetization.

■ Spaces are ignored.

■ Quotation marks are ignored.

■ The word the is ignored if it is the first word in the message.

■ Messages that begin with numbers or punctuation symbols appeartoward the end of the list in a special section labeled “Messages:Symbols” on page 5-48.

A cause and suggested corrective action for a message or group of messagesfollow the message text.

How to View These MessagesUse one of the following methods to view these messages:

■ On-line message log

To see the messages displayed as they occur, use the tail -f online.logcommand.

■ onstat -m command

For more information, see “The onstat -m Option” on page 3-115.

To see the error number associated with these unnumbered messages, viewthe logmessage table in the sysmaster database:

SELECT * FROM logmessage;


Message Categories

Message CategoriesFour general categories of messages can be defined, although some messagesfall into more than one category:

■ Routine information

■ Assertion-failed messages

■ Administrative action needed

■ Fatal error detected

The assertion-failed messages reflect their traditional use by Informixtechnical staff to assist in troubleshooting and diagnostics. The informationthat they report often falls into the category of unexpected events that might ormight not develop into problems caught by other error codes. Moreover, themessages are terse and often extremely technical. They might report on oneor two isolated statistics without providing an overall picture of what ishappening.

When technical staff are investigating a problem, this information cansuggest to them possible research paths. However, you might find that theinformation has little or no application when it is taken out of this context orwhen processing is proceeding normally.


Messages: A-B

Messages: A-BAborting Long Transaction: tx 0xn

Affinitied VP mm to phys proc nn

Affinity not enabled for this server

Assert Failed: Error from SBSpace cleanup thread

Cause: The transaction spans the log space specified by transaction high-water mark (LTXHWM), and the offending long transaction isrolling back.

Action: No additional action is needed. The address of the transactionstructure in shared memory is displayed as a hexadecimal value.

Cause: The database server successfully bound a CPU virtual processor toa physical processor.

Action: None required.

Cause: You tried to bind your CPU virtual processors to physicalprocessors, but the database server that you are running does notsupport process affinity.

Action: Set AFF_NPROCS to 0, or remove the affinity setting fromVPCLASS.

Cause: The sbspace cleanup thread encountered an error while cleaningup stray smart large objects.

Action: See the action suggested in the message log file.

Most of the time, running onspaces -cl sbspacename on the failedsbspace succeeds in cleaning up any stray smart large objects. Ifyou encounter an unrecoverable error, contact Informix TechnicalSupport.


Messages: A-B

Assert Failed: Short description of what failedWho: Description of user/session/thread running at the timeResult: State of the affected database server entityAction: What action the database administrator should takeSee Also: DUMPDIR/af.uniqid containing more diagnostics.

Begin re-creating indexes deferred during recovery.

Building 'sysmaster' database requires ~mm pages of logical log.Currently there are nn pages available.Prepare to back up your logs soon.

Building 'sysmaster' database...

Cause: This message indicates an internal error.

Action: The af.uniqid file in the directory specified by the ONCONFIGparameter DUMPDIR contains a copy of the assertion-failuremessage that was sent to the message log, as well as the contentsof the current, relevant structures and/or data buffers. The infor-mation included in this message is intended for InformixTechnical Support.

Contact Informix Technical Support.

Cause: During recovery, indexes to be created are deferred until afterrecovery completes. This message indicates that the databaseserver deferred re-creating indexes and that it is now creating theindexes. During the time that the database server re-creates theindexes, it locks the affected tables with a shared lock.


Cause: You do not currently have the approximate amount of free logspace necessary to complete a build of the sysmaster database.

Action: Back up your logs.

Cause: The database server is building the sysmaster database.



Messages: C

Messages: CCannot Allocate Physical-log File, mm wanted, nn available

Cannot change to mode.

Cannot Commit Partially Complete Transactions

Cause: The database server attempted to initialize shared memory with aphysical-log size that exceeds the amount of contiguous spaceavailable in the dbspace (specified as PHYSDBS in ONCONFIG).Both quantities of space, wanted and available, are expressed askilobytes.

Action: You must either reduce the size of the physical log (specified asPHYSFILE in ONCONFIG) or change the location of the physical logto a dbspace that contains adequate contiguous space to accom-modate the physical log.

Cause: Some error during fast or full recovery has prevented the systemfrom changing to on-line or quiescent mode.

Action: See previous messages in the log file for information, or contactInformix Technical Support.

Cause: Transactions that drop tables or indexes do not perform the dropuntil a COMMIT statement is processed (with a few exceptions). Inthese cases, a beginning commit log record is written, followed bythe usual commit log record. If the database server fails inbetween the two, the fast recovery process attempts to completethe commit the next time that you initialize the database server.

If this completion of the commit fails, the database servergenerates the preceding message.

Action: To determine if you need to take action, examine the logical log asdescribed in Chapter 6, “Interpreting Logical-Log Records.”


Messages: C

Cannot create a user-defined VP class with 'SINGLE_CPU_VP' non-zero

Cannot Open Dbspace nnn

Cannot Open Logical Log

Cannot Open Mirror Chunk pathname, errorno = nn

Cause: SINGLE_CPU_VP is set to nonzero, and onmode was used to createa user-defined VP class.

Action: If user-defined VP classes are necessary, stop the database server,change SINGLE_CPU_VP to zero, and restart the database server.

Cause: The database server is unable to access the specified dbspace. Thismessage indicates a problem opening the tblspace or corruption inthe initial chunk of the dbspace.

Action: Verify that the device or devices that make up the chunks of thisdbspace are functioning properly and that you assigned them thecorrect operating-system permissions (rw-rw----). You might berequired to perform a data restore.

Cause: The database server is unable to access the logical-log files.Because the database server cannot operate without access to thelogical log, you must resolve this problem.

Action: Verify that the chunk device where the logical-log files reside isfunctioning and has the correct operating-system permissions(rw-rw----).

Cause: The database server cannot open the mirrored chunk of amirrored pair. The chunk pathname and the operating-systemerror are returned.

Action: For more information about corrective actions, see youroperating-system documentation.


Messages: C

Cannot Open Primary Chunk pathname, errorno = nnn

Cannot Open Primary Chunk chunkname

Cannot Perform Checkpoint, shut system down.

Cannot Restore to Checkpoint

Cannot Rollback Incomplete Transactions

Cause: The primary chunk of a mirrored pair cannot be opened. Thechunk pathname and the operating-system error are returned.

Action: For more information about corrective actions, see youroperating-system documentation.

Cause: The initial chunk of the dbspace cannot be opened.

Action: Verify that the chunk device is running properly and has thecorrect operating-system permissions (rw-rw----).

Cause: A thread that is attempting to restore a mirrored chunk hasrequested a checkpoint, but the checkpoint cannot be performed.

Action: Shut down the database server.

Cause: The database server is unable to recover the physical log and thusunable to perform fast recovery.

Action: If the database server does not come on-line, perform a datarestore from dbspace backup.

Cause: Within the fast-recovery or data-restore procedure, the logical-logrecords are first rolled forward. Then, open transactions that havenot committed are rolled back. An open transaction could failduring the rollback, leaving some of the modifications from theopen transaction in place. This error does not prevent the databaseserver from moving to quiescent or on-line mode, but it mightindicate an inconsistent database.

Action: To determine if any action is needed, use the onlog utility toexamine the logical log.


Messages: C

Cannot update pagezero

Can’t affinity VP mm to phys proc nn

Checkpoint blocked by down space, waiting for override orshutdown

Checkpoint Completed: duration was n seconds

Checkpoint Page Write Error

Cause: A failure occurred while the database server was trying to rewritea reserved page during the reversion process.

Action: See previous messages in the log file for information, or callInformix Technical Support.

Cause: The database server supports process affinity, but the system callto bind the virtual processor to a physical processor failed.

Action: See your operating-system documentation.

Cause: A dbspace has gone down during a checkpoint interval. Thedatabase server is configured to wait for an override when thissituation occurs.

Action: Either shut down the database server or issue an onmode -Ocommand to override the down dbspace. For more information onthe onmode utility, see “onmode: Change Mode and SharedMemory” on page 3-37.

Cause: A checkpoint completed successfully.


Cause: The database server detected an error in an attempt to writecheckpoint information to disk.

Action: For additional assistance in resolving this situation, contactInformix Technical Support.


Messages: C

Checkpoint Record Not Found in Logical Log

Chunk chunkname added to space spacename

Chunk chunk-name dropped from space spacename

Chunk number nn pathname -- Offline

Cause: The logical log or the chunk that contains the logical log iscorrupted. The database server cannot initialize.

Action: Perform a data restore from dbspace backup.

Description: The variables in this message have the following values:

chunkname is the name of the chunk that the databaseserver administrator is adding.

spacename is the name of the storage space to which thedatabase server administrator is adding thechunk.

Cause: The database server administrator added chunk chunknameto space spacename.


Cause: The database server administrator dropped chunk chunknamefrom space spacename.


Cause: The indicated chunk in a mirrored pair has been marked withstatus D and taken off-line. The other chunk in the mirrored pair isoperating successfully.

Action: Take steps now to repair the chunk device and restore the chunk.The chunk number and chunk device pathname are displayed.


Messages: C

Chunk number nn pathname -- Online

The chunk pathname must have READ/WRITE permissions for ownerand group.

The chunk pathname must have owner-ID and group-ID set toinformix.

The chunk pathname will not fit in the space specified.

Cleaning stray LOs in sbspace 'sbspace-name'.

Cause: The indicated chunk in a mirrored pair has been recovered and ison-line (marked with status O). The chunk number and chunkdevice pathname are displayed.


Cause: The chunk pathname does not have the correct owner and grouppermissions.

Action: Make sure that you assigned the correct permissions(-rw-rw---) to the device on which the chunk is located.

Cause: The chunk chunkname does not have the correct owner and groupID.

Action: Make sure the device on which the chunk is located has theownership. On UNIX, both owner and group should be informix.On Windows NT, the owner must be a member of the Informix-Admin group.

Cause: The chunk pathname does not fit in the space that you specified.

Action: Choose a smaller size for the chunk, or free space where the chunkis to be created.

Cause: The database server administrator is running onspaces -clsbspacename.



Messages: C

Completed re-creating indexes.

Configuration has been grown to handle up to integer chunks.

Configuration has been grown to handle up to integer dbslices.

Configuration has been grown to handle up to integer dbspaces.

Continuing Long Transaction (for COMMIT): tx 0xn

Cause: The database server finished re-creating the deferred indexes.


Cause: The database server administrator increased the number ofchunks to the specified value by changing CONFIGSIZE or settingMAX_CHUNKS to a higher value.

Action: None required. The change was successful.

Cause: The database server administrator increased the number ofdbslices to the specified value by changing CONFIGSIZE or settingMAX_DBSLICES to a higher value.


Cause: The database server administrator increased the number ofdbspaces to the specified value by changing CONFIGSIZE orsetting MAX_DBSPACES to a higher value.


Cause: The logical log has filled beyond the long-transaction high-watermark (LTXHWM), but the offending long transaction is in theprocess of committing. In this case, the transaction is permitted tocontinue writing to the logical log and is not rolled back. Theaddress of the transaction structure in shared memory isdisplayed as hexadecimal value tx 0xn.



Messages: C

Could not disable priority aging: errno = nn

Could not fork a virtual processor: errno = nn

Create_vp: cannot allocate memory

Cause: An operating-system call failed while it was trying to disablepriority aging for the CPU virtual processor. The system errornumber associated with the failure is returned.


Cause: The fork of a virtual processor failed. The database server returnsthe operating-system error number associated with the failure.

Action: For information on determining the maximum number ofprocesses available per user and for the system as a whole, refer toyour operating-system documentation.

Cause: The database server cannot allocate new shared memory.

Action: The database server administrator must make more sharedmemory available. This situation might require increasingSHMTOTAL or reconfiguring the operating system. This messageis usually accompanied by other messages that give additionalinformation.


Messages: D-E-F

Messages: D-E-Fdataskip is OFF for all dbspaces

dataskip is ON for all dbspaces

dataskip is ON for dbspaces: <dbspacelist>.

dataskip will be turned {ON|OFF} for <dbspacename>.

DBSPACETEMP internal list not initialized, using default

The DBspace/BLOBspace spacename is now mirrored.

Cause: Informational.


Cause: Informational.


Cause: Informational; DATASKIP is ON for the specified dbspaces.


Cause: Informational; DATASKIP is ON or OFF for the specified dbspace.


Cause: An error occurred while initializing a user-specifiedDBSPACETEMP list. Typically this condition is due to a memory-allocation failure.

Action: Check for accompanying error messages.

Cause: You successfully added mirroring to the indicated storage space.



Messages: D-E-F

The DBspace/BLOBspace spacename is no longer mirrored.

Dbspace dbspacename for Physical-log File not found

devname: write failed, file system is full.

Dropping temporary tblspace 0xn, recovering nn pages.

Dynamically allocated new shared memory segment (size nnnn)

Cause: You have ended mirroring for the indicated storage space.


Cause: The dbspace dbspacename specified by the PHYSDBS configurationparameter does not exist. As a consequence, the database servercannot complete initialization.

Action: Use a dbspace known to exist.

Cause: Because the file system devname is full, the write failed.

Action: Free some space in devname.

Cause: During shared-memory initialization, the database serverroutinely searches for temporary tables that are left withoutproper cleanup. If the database server finds a temporary table, itdrops the table and recovers the space. The database serverlocated the specified temporary tblspace and dropped it. Thevalue 0xn is the hexadecimal representation of the tblspacenumber.


Cause: This status message informs you that the database server success-fully allocated a new shared-memory segment of size nnnn.



Messages: D-E-F

ERROR: NO "waitfor" locks in Critical Section.

Error building sysmaster database. See outfile.

Error writing pathname errno = nn

Error writing shmem to file filename (error)Unable to create output file filename errno=mmError writing filename errno=nn

Cause: The database server does not permit a thread to own locks thatmight have to wait while that thread is within a critical section.Any such lock request is denied, and an ISAM error message isreturned to the user.

Action: The error reported is an internal error. Contact Informix TechnicalSupport.

Cause: Errors were encountered in building the sysmaster database. Thefile outfile contains the result of running the script buildsmi.

Action: See the file outfile.

Cause: The operating system cannot write to pathname. The number nn isthe number of the operating-system error that was returned.

Action: Investigate the cause of the operating-system error. Usually itmeans that no space is available for the file. It might also meanthat the directory does not exist or that no write permissions exist.

Cause: The database server detected an error in an attempt to writeshared memory to filename. The first message is followed by one ofthe next two. Either the attempt failed because the output filecould not be created or because the contents of shared memorycould not be written. The error refers to the operating-systemerror that prompted the attempted write of shared memory to afile. The value of nn is the operating-system error.



Messages: D-E-F

Existing sysmaster database renamed to sysmaster_pre60

Fatal error initializing CWD string.Check permissions on current working directory. Group groupnamemust have at least execute permission on '.'.

Fragments dbspacename1 dbspacename2 of table tablename set tonon-resident.

Forced-resident shared memory not available

Freed mm shared-memory segment(s) nn bytes

Cause: When the database server was building the sysmaster database, itfound that a database with the name of sysmaster already exists.The database server renamed the database sysmaster_pre60.


Cause: Group groupname does not have execute permission for thecurrent working directory.

Action: Check permissions on the current working directory. You or thesystem administrator must give your group execute permissionon the current working directory. After your group has been givenpermission, retry the operation that generated this message.

Cause: The specified fragments of tablename either have been set tononresident by the SET TABLE statement.


Cause: The database server port for your computer does not supportforced-resident shared memory.


Cause: The database server sends this message to the message log afteryou run the -F option of the onmode utility to free unusedmemory. The message informs you of the number of segmentsand bytes that the database server successfully freed.



Messages: G-H-I

Messages: G-H-Igcore pid; mv core.pid dir/core.pid.ABORT

I/O function chunk mm, pagenum nn, pagecnt aa --> errno = bb

I/O error, primary/mirror Chunk pathname -- Offline (sanity)

Indexes idx1 and idx2 set to non-resident

Cause: This status message during a database server failure provides thename and place of each core file associated with the virtualprocessors.


Cause: An operating-system error occurred during an attempt to accessdata from disk space. The operating-system function that failed isdefined by function. The chunk number and physical address ofthe page where the error occurred are displayed as integers.Thepagecnt value refers to the number of pages that the thread wasattempting to read or write. If an errno value is displayed, it is thenumber of the operating-system error and might explain thefailure. If function is specified as bad request, some unexpectedevent caused the I/O attempt on an invalid chunk or page.

Action: If the chunk status changes to D, or down, restore the chunk fromits mirror or repair the chunk. Otherwise, perform a data restore.

Cause: The database server detected an I/O error on a primary ormirrored chunk with pathname. The chunk was taken off-line.

Action: Check that the device on which the chunk was stored isfunctioning as intended.

Cause: The specified indexes have been set to nonresident through theSET TABLE statement.



Messages: G-H-I

Informix database_server Initialized - Complete DiskInitialized

Informix database_server Initialized - Shared MemoryInitialized

Informix database_server Stopped

ERROR: Insufficient available disk in the root dbspace toincrease the entire Configuration save area.

Cause: Disk space and shared memory have been initialized. Anydatabases that existed on the disk before the initialization are nowinaccessible.


Cause: Shared memory has been initialized.


Cause: The database server has moved from quiescent mode to off-linemode. The database server is off-line.


Cause: The user attempted to increase the number of storage objects to aspecific value by changing CONFIGSIZE or settingMAX_DBSPACES, MAX_DBSLICES, or MAX_CHUNKS to a highervalue, but the database server did not have enough rootspace forthe increased number of storage objects. A storage object might bea dbspace, dbslice, or chunk.

Action: Increase the size of the root dbspace or reset CONFIGSIZE,MAX_DBSPACES, MAX_DBSLICES, or MAX_DBSLICES to a lowervalue and restart the database server. For example, if you setMAX_CHUNKS to 32,768, but the root dbspace did not haveenough space, set MAX_CHUNKS to a lower value.


Messages: G-H-I

Insufficient available disk in the root dbspace for the CM savearea. Increase the size of the root dbspace in the ONCONFIG fileand reinitialize the server.

Internal overflow of shmid's, increase system max shared memorysegment size.

Cause: The cause might be one of the following:

■ The user attempted to increase the number of storageobjects to a specific value by changing CONFIGSIZE orsetting MAX_DBSPACES, MAX_DBSLICES, orMAX_CHUNKS to a higher value, but the database serverdid not have enough rootspace for the increased numberof storage objects. A storage object might be a dbspace,dbslice, or chunk.

■ The user converted to a database server version thatrequires slightly more rootspace, but it is not available(this case is unlikely).

Action: Take one of the following actions:

■ Increase the size of the root dbspace or reset CONFIGSIZE,MAX_DBSPACES, MAX_DBSLICES, or MAX_DBSLICES to alower value and restart the database server. For example,if you set MAX_DBSPACES to 32,768 but the root dbspacedid not have enough space, set MAX_DBSPACES to a lowervalue.

■ Increase the size of the root dbspace and reinitialize thedatabase server.

Cause: The database server was initializing shared memory when it ranout of internal storage for the shared-memory IDs associated withthis segment.

Action: Increase the value of your maximum kernel shared-memorysegment size, usually SHMMAX. For more information, see youroperating-system documentation.


Messages: J-K-L-M

Messages: J-K-L-MListener-thread err = error_number: error_message

Lock table overflow - user id mm session id nn

Logical-log File not found

Logical Log nn Complete

Cause: A listener thread has encountered an error. This message displaysthe error number and message text.

Action: For the cause and corrective action, see Informix Error Messages inAnswers OnLine.

Cause: A thread attempted to acquire a lock when no locks wereavailable. The user ID and session ID are displayed.

Action: Increase the LOCKS configuration parameter, and initialize sharedmemory.

Cause: The checkpoint record in the root dbspace reserved page iscorrupted.

Action: Perform a data restore from dbspace backup.

Cause: The logical-log file identified by log-ID number nn is full. Thedatabase server automatically switches to the next logical-log filein the sequence.



Messages: J-K-L-M

Logical logging vberror for type:subtype in (????)

Log Record: log = ll, pos = 0xn, type = type:subtype(snum),trans = xx

Description: The log record that caused the error is identified as follows:

type is the logical-log record type.

subtype is the logging subsystem.

???? is the name of an internal function thatindicates what system failed to log.

Cause: Logging failed.

Action: Contact Informix Technical Support.


ll is the logical-log ID where the record is stored.

0xn is the hexadecimal address position within thelog.



snum is the subsystem number.

xx is the transaction number that appears in thelogical log.

Cause: The database server detected an error during the rollforwardportion of fast recovery or logical-log restore.



Messages: J-K-L-M

Log record (type:subtype) at log nn, 0xn was not undone

Log record (type:subtype) failed, partnum pnum row rid iserrnonum




nn is the logical-log ID where the record is stored.

0xn is the hexadecimal address position within thelog.

Cause: A log undo failed because a log is corrupt.

Action: To determine if any action is needed, use the onlog utility toexamine the logical log. Contact Informix Technical Support.




pnum is the part number.

rid is the row ID.

num is the iserror number.

Cause: A logging failure occurred.



Messages: J-K-L-M

Log record (type:subtype) in log nn, offset 0xn was not rolledback

Logical Recovery allocating nn worker threads thread_type.

Logical Recovery Started




log is the logical-log ID where the record is stored.

offset is the hexadecimal address position within thelog.

Cause: A log undo failed because a log is corrupt.

Action: To determine if any action is needed, use the onlog utility toexamine the logical log. Contact Informix Technical Support.

Cause: The database server determined the number of worker threadsthat will be used for parallel recovery. The variable thread_type canassume the values ON_RECVRY_THREADS orOFF_RECVRY_THREADS.

Action: This status message requires no action. If you want a differentnumber of worker threads allocated for parallel recovery, changethe value of the ONCONFIG configuration parameterON_RECVRY_THREADS or OFF_RECVRY_THREADS.

Cause: Logical recovery began.

Action: This status message requires no action.


Messages: J-K-L-M

Memory allocation error.

Mirror Chunk chunkname added to space spacename. Perform manualrecovery.

Mixed transaction result. (pid=nn user=userid)

mt_shm_free_pool: pool 0xn has blocks still used (id nn)

Cause: Not enough main (OS) memory or not enough internal (databaseserver) memory might cause this error.

Action: See your operating-system documentation for information onhow to increase OS memory. Alternatively, increase the virtual-memory size (SHMVIRTSIZE), the size of the added segments,(SHMADD), or your total shared-memory size (SHMTOTAL).

Cause: Fast recovery, full recovery, or an HDR secondary has recoveredthe add of a mirror chunk. It does not perform automatic mirrorrecovery, however. The administrator must do this.

Action Use either the onspaces utility or ON-Monitor to attempt torecover the mirror chunks.

Cause: You receive this message only when more than one databaseserver is involved in a transaction. This message indicates that adatabase server, after preparing a transaction for commit, heuris-tically rolled back the transaction, and the global transactioncompleted inconsistently. The pid value is the user-process identi-fication number of the coordinator process. The value of user is theuser ID associated with the coordinator process.

Action: See the information on recovering manually from failed two-phase commit in your Administrator’s Guide.

Cause: An internal error occurred during a pool deallocation becauseblocks are still associated with the pool.



Messages: J-K-L-M

mt_shm_init: can’t create resident/virtual segment

mt_shm_remove: WARNING: may not have removed all/correctsegments

Cause: The causes for the failure to create the resident or virtual segmentare as follows: (1) the segment size is less than the minimumsegment size; (2) the segment size is larger than the maximumsegment size; (3) allocating another segment would exceed theallowable total shared-memory size; or (4) a failure occurredwhile the database server was trying to allocate the segment.

Action: If you suspect that this error was generated because of item 1 or 2in the preceding paragraph, contact Informix Technical Support.To correct item 3, increase the SHMTOTAL value in yourONCONFIG configuration file. For additional information abouterrors generated because of item 4, see your logical-log file.

Cause: When the operating system tried to remove the shared-memorysegments associated with the database server, the last segment didnot equal the last segment registered internally. This situation isprobably due to the unexpected failure of the database server.

Action: Remove any segments that were not cleaned up.


Messages: N-O-P

Messages: N-O-PNewly specified value of value for the pagesize in the config-uration file does not match older value of value. Using theolder value.

Not enough main memory

Not enough logical-log files, Increase LOGFILES

Not enough physical procs for affinity

Cause: This message displays upon database server restart. ThePAGESIZE value changed in the ONCONFIG file after the databaseserver was initialized.

Action: The database server uses the older PAGESIZE value.

Cause: The database server detected an error in an attempt to acquiremore memory space from the operating system.

Action: For more information about shared-memory configuration andmanagement, refer to your operating-system documentation.

Cause: During a data restore, the value of the LOGFILES configurationmust always be greater than or equal to the total number oflogical-log files. At some point during the restore, the number oflogical-log files exceeded the value of LOGFILES.

Action: Increase the value of LOGFILES in ONCONFIG.

Cause: The ONCONFIG parameters AFF_NPROCS and AFF_SPROC are notcorrectly set. AFF_SPROC plus AFF_NPROCS is greater than thenumber of physical processors on your computer or node.

Action: Reset AFF_NPROCS and AFF_SPROC, such that the valueAFF_SPROC plus value of AFF_NPROCS is less than or equal to thenumber of physical processors.


Messages: N-O-P

The number of configured CPU poll threads exceeds NUMCPUVPS.

onconfig parameter parameter modified from old_value tonew_value

oninit: Cannot have SINGLE_CPU_VP non-zero and number of CPU VPsgreater than 1.

oninit: Cannot have SINGLE_CPU_VP non-zero and user-defined VPclasses.

Cause: The number of in-line poll threads that you specified in theONCONFIG configuration file exceeds the number of CPU virtualprocessors.

Action: Reduce the number of in-line poll threads to be less than or equalto the number of CPU virtual processors.

Cause: When the database server shared memory is reinitialized, thismessage documents any changes that occurred since the lastinitialization.


Cause: The ONCONFIG file contains VPCLASS cpu with a num= valuegreater than 1 and a nonzero value for SINGLE_CPU_VP.SINGLE_CPU_VP must be 0 (or omitted) when there are more than1 CPU VPS.

Action: Correct the ONCONFIG file and restart the database server.

Cause: The ONCONFIG file contains a user-defined VPCLASS as well as anonzero value for SINGLE_CPU_VP. SINGLE_CPU_VP must be 0 (oromitted) when the ONCONFIG file contains a user-definedVPCLASS.



Messages: N-O-P

oninit: Cannot mix VPCLASS cpu and NUMCPUVPS, AFF_SPROC,AFF_NPROCS, or NOAGE parameters

oninit: Cannot mix VPCLASS aio and NUMAIOVPS parameters.

oninit: Fatal error in initializing ASF with 'ASF_INIT_DATA'flags asfcode = '25507'

oninit: invalid or missing name for Subsystem Staging Blobspace.

oninit: Too many VPCLASS parameters specified.

Cause: The ONCONFIG file contains both VPCLASS cpu and one or moreof the other listed parameters. It cannot contain both.


Cause: The ONCONFIG file contains both VPCLASS aio and NUMAIOVPS.It cannot contain both.


Cause: The nettype value specified in the sqlhosts file or registry for thedatabase server is invalid or unsupported, or the servicenamespecified in the sqlhosts file or registry for the database server isinvalid.

Action: Check the nettype and servicename values in the sqlhosts file orregistry for each DBSERVERNAME and for the DBSERVERALIASES.Check the nettype value in each NETTYPE parameter in theONCONFIG file.

Cause: You set the configuration parameter STAGEBLOB to a blobspacethat does not exist.

Action: Use the -d option of onspaces to create the blobspace specified inSTAGEBLOB, and restart the database server.

Cause: Too many VPCLASS parameter lines have been specified in theONCONFIG file.

Action: Reduce the number of VPCLASS lines, if possible. If not possible,contact Informix Technical Support.


Messages: N-O-P

oninit: VPCLASS classname bad affinity specification

oninit: VPCLASS classname duplicate class name.

oninit: VPCLASS classname illegal option

oninit: VPCLASS classname maximum number of VPs is out of therange 0-10000.

oninit: VPCLASS classname name is too long. Maximum length ismaxlength.

Cause: The affinity specification for the VPCLASS line is incorrect. Affinityis specified as a range:

For m, use processor m.

For m to n, use processors in the range m to n inclusive, where m<= n, m >= 0, and n >= 0.

Action: Correct the VPCLASS parameter in the ONCONFIG file and restartthe database server.

Cause: The VPCLASS classname in the ONCONFIG file has a duplicatename. VP class names must be unique.

Action: Correct the duplicate name and restart the database server.

Cause: One of the fields in the VPCLASS classname parameter is illegal.

Action: Correct the parameter in the ONCONFIG file and restart thedatabase server.

Cause: The maximum number of VPs specified by a VPCLASS parameterline must be in the range 1 to 10,000.

Action: Correct the value and restart the database server.

Cause: The length of the name field in VPCLASS classname is too long.

Action: Choose a shorter class name, correct the ONCONFIG file, andrestart the database server.


Messages: N-O-P

oninit: VPCLASS classname number of VPs is greater than themaximum specified

oninit: VPCLASS classname number of VPs is out of the range0-10000.

onmode: VPCLASS classname name is too long. Maximum length ismaxlength.

Optical Subsystem is running.

Optical Subsystem is not running.

Cause: The initial number of VPs specified by a VPCLASS parameter isgreater than the maximum specified by the same VPCLASSparameter.

Action: Correct the VPCLASS PARAMETER AND restart the databaseserver.

Cause: The initial number of VPs specified by a VPCLASS parameter linemust be in the range 1 to 10,000.

Action: Correct the value and restart the database server.

Cause: The name of a dynamically added VP class that onmode -pspecifies is too long.

Action: Choose a shorter name, and retry the onmode -p command.

Cause: You set the value of the STAGEBLOB parameter in the configu-ration file, and the database server is communicating properlywith the optical-storage subsystem.

Action: No action is required.

Cause: You set the value of the STAGEBLOB parameter in the configu-ration file, but the database server cannot detect the existence ofthe optical-storage subsystem.

Action: Check that the optical subsystem is on-line.


Messages: N-O-P

Optical Subsystem STARTUP Error.

On-Line Mode.

onspaces: unable to reset dataskip

Open transaction detected when changing log versions.

Out of message shared memory

Cause: The database server detects that the optical-storage subsystem isrunning, but the database server cannot communicate with itproperly.

Action: Check your optical subsystem for errors.

Cause: The database server is in on-line mode. Users can access alldatabases

Action: This status message requires no action.

Cause: This error message comes from the onspaces utility. For somereason, the utility cannot change the specification of DATASKIP(ON or OFF) across all dbspaces in the database server instance.

Action: You are unlikely to receive this message. If the error persists afteryou restart the database server, contact Informix TechnicalSupport.

Cause: The database server detected an open transaction while it wastrying to convert the data from a previous version of the databaseserver.

Action: Conversion is not allowed unless the last record in the log is acheckpoint. You must restore the previous version of the databaseserver, force a checkpoint, and then retry conversion.

Cause: The database server could not allocate more memory for thespecified segment.

Action: For additional information, see the log file.


Messages: N-O-P

out of resident shared memory

out of virtual shared memory

PANIC: Attempting to bring system down

Participant site database_server heuristically rolled back

Possible mixed transaction result.





Cause: A fatal database server error occurred.

Action: See the error that caused the panic and attempt the correctiveaction suggested by the error message. For additional informationthat might explain the failure, refer also to other messages in themessage-log file.

Cause: A remote site rolled back a transaction after it reached theprepared-for-commit phase.

Action: You might need to roll back the transaction on other sites and thenrestart it.

Cause: This message indicates that error -716 has been returned.Associated with this message is a list of the database serverswhere the result of a transaction is unknown.

Action: For information on determining if a transaction was implementedinconsistently, see the Administrator’s Guide.


Messages: N-O-P

Prepared participant site server_name did not respond

Prepared participant site server_name not responding

Cause: Too many attempts were made to contact remote site server_name.After several timeout intervals were met, the site was determinedto be down.

Action: Verify that the remote site is on-line and that it is correctlyconfigured for distributed transactions. Once the remote site isready, reinitiate the transaction.

Cause: The database server is attempting to contact remote siteserver_name. For some unknown reason, the database servercannot contact the remote site.

Action: Verify that the remote site is on-line and that it is correctlyconfigured for distributed transactions.


Messages: Q-R-S

Messages: Q-R-SQuiescent Mode

Recovery Mode

Reversion cancelled

Reversion complete

Recreating index: 'dbsname:"owner".tabname-idxname'

Cause: The database server has entered quiescent mode from some otherstate. On UNIX, only users logged in as informix or as root caninteract with the database server. On Windows NT, only membersof the Informix-Admin group can interact with the databaseserver. No user can access a database.


Cause: The database server entered the recovery mode. No user canaccess a database until recovery is complete.


Cause: The reversion process was cancelled because of errorsencountered.

Action: Correct the cause of the errors, and restart reversion.

Cause: The reversion process was completed successfully.


Cause: This message indicates which index is currently being re-created.



Messages: Q-R-S

Rollforward of log record failed, iserrno = nn

scan_logundo: subsys ss, type tt, iserrno ee

scan_logundo: type mm, iserrno nn

Session completed abnormally. Committing tx id 0xm, flags 0xn

Cause: The message appears if, during fast recovery or a data restore, thedatabase server cannot roll forward a specific logical-logrecord.The database server might be able to change to quiescent oron-line mode, but some inconsistency could result. For furtherinformation, see the message that immediately precedes this one.The iserrno value is the error number.



ss is the logical-log record type.

tt is the logical-log record type.

ee is the iserror number.

Cause: A log undo failed because log type tt is corrupt.

Action: Examine the logical log with the onlog utility to determine ifany action is needed. Contact Informix Technical Support.

Cause: A log undo failed because log type nn is corrupt.

Action: Examine the logical log with the onlog utility to determine if anyaction is needed. Contact Informix Technical Support.

Cause: Abnormal session completion occurs only when the databaseserver is attempting to commit a transaction that has no currentowner, and the transaction develops into a long transaction.Thedatabase server forked a thread to complete the commit.



Messages: Q-R-S

Session completed abnormally. Rolling back tx id 0xm, flags 0xn

semctl: errno = nn

semget: errno = nn

shmat: some_string os_errno: os_err_text

shmctl: errno = nn

Cause: Abnormal session completion occurs only when the databaseserver is attempting to commit a distributed transaction that hasno current owner, and the transaction develops into a long trans-action. The database server forked a thread that rolled back thetransaction.


Cause: When the database server initialized a semaphore, an erroroccurred. The operating-system error is returned.


Cause: An allocation of a semaphore set failed. The operating-systemerror is returned.


Cause: An attempt to attach to a shared-memory segment failed. Thesystem error number and the suggested corrective action arereturned.

Action: Review the corrective action (if given), and determine if it isreasonable to try. For more information, refer to your operating-system documentation.

Cause: An error occurred while the database server tried to remove orlock a shared-memory segment. The operating-system errornumber is returned.



Messages: Q-R-S

shmdt: errno = nn

shmem sent to filename

shmget: some_str os_errno: key shmkey: some_string

Shutdown (onmode -k) or override (onmode -O)

Cause: An error occurred while the database server was trying to detachfrom a shared-memory segment. The operating-system errornumber is returned.


Cause: The database server wrote a copy of shared memory to thespecified file as a consequence of an assertion failure.

Action: None.

Cause: Either the creation of a shared-memory segment failed, or anattempt to get the shared-memory ID associated with a certain keyfailed. The system error number and the suggested correctiveaction are returned.

Action: Consult your operating-system documentation.

Cause: A dbspace has gone down during a checkpoint interval. Thedatabase server is configured to wait for an override when thissituation occurs.

When the checkpoint actually happens, the following messageappears: Checkpoint blocked by down space, waiting foroverride or shutdown.

Action: Either shut down the database server or issue an onmode -Ocommand to override the down dbspace. For more information onthe onmode utility, see “onmode: Change Mode and SharedMemory” on page 3-37.


Messages: Q-R-S

Shutdown Mode

Space spacename added.

Space spacename dropped.

Space spacename -- Recovery Begins(addr)

Cause: The database server is in the process of moving from on-line modeto quiescent mode.


Cause: The database server administrator added a new storage spacespacename to the database server.


Cause: The database server administrator dropped a storage spacespacename from the database server.



spacename is the name of the storage space that thedatabase server is recovering.

addr is the address of the control block.

Cause: This informational message indicates that the databaseserver is attempting to recover the storage space.



Messages: Q-R-S

Space spacename -- Recovery Complete(addr)

Space spacename -- Recovery Failed(addr)

sysmaster database built successfully


spacename is the name of the storage space that thedatabase server has recovered.


Cause: This informational message indicates that the databaseserver recovered the storage space.



spacename is the name of the storage space that thedatabase server failed to recover.


Cause: This informational message indicates that the databaseserver was unable to recover the storage space.


Cause: The database server successfully built the sysmaster database.



Messages: T-U-V

Messages: T-U-VTable tablename set to resident

Table tablename and all its indexes set to resident

The following tables have outstanding old version datapages due to an In-Place Alter Table. PerformUPDATE table-name SET column = column WHERE 1=1;to clear these pages from the following tables.

Cause: The indicated table has been made resident by the SET TABLEstatement.


Cause: The indicated table and all its indexes have been made resident bythe SET TABLE statement.


Cause: Reversion to a previous version of the database server has beenattempted while an in-place ALTER TABLE is in progress. Theprevious versions of the database server cannot handle tables thathave multiple schemas of rows in them.

Action: Force any in-place alters to complete by updating the rows in theaffected tables before you attempt to revert to a previous versionof the database server. To do this, create a dummy update in whicha column in the table is set to its own value, forcing the row to beupdated to the latest schema in the process without actuallychanging column values. Rows are always altered to the latestschema, so a single pass through the table that updates all rowscompletes all outstanding in-place alters.


Messages: T-U-V

TIMER VP: Could not redirect I/O in initialization, errno = nn

Too Many Active Transactions.

Transaction Not Found

Transaction heuristically rolled back

Transaction table overflow - user id nn, process id nn

Cause: The operating system could not open the null device or duplicatethe file descriptor associated with the opening of that device. Thesystem error number is returned.


Cause: During a data restore, there were too many active transactions. Atsome point during the restore, the number of active transactionsexceeded 32 kilobytes.

Action: None.

Cause: The logical log is corrupt. This situation can occur when a newtransaction is started, but the first logical-log record for the trans-action is not a BEGWORK record.


Cause: A heuristic decision occurred to roll back a transaction after itcompleted the first phase of a two-phase commit.


Cause: A thread attempted to allocate an entry in the transaction tablewhen no entries in the shared-memory table were available. Theuser ID and process ID of the requesting thread are displayed.

Action: Try again later.


Messages: T-U-V

Unable to create output file filename errno = nn

Unable to extend nn reserved pages for purpose in root chunk.

Unable to initiate communications with the Optical Subsystem.

Unable to start SQL engine

Unable to open tblspace nn, iserrno = nn

Cause: The operating system cannot create output file filename. The errnois the number of the operating-system error returned.

Action: Verify that the directory exists and has write permissions.

Cause: The operating system cannot extend to nn reserved pages forpurpose in root chunk. (The value purpose can be either Check-point/Log, DBSpace, Chunk, or Mirror Chunk.)

Action: Reduce the ONCONFIG parameter for the resource cited; bring thedatabase server up and free some space in the primary root chunk.Then reattempt the same operation.

Cause: The optical driver supplied by the optical-drive vendor hasindicated that the drive is not accessible.

Action: Check driver installation and cabling between the computer andthe drive.

Cause: The database server encountered an out-of-memory condition.

Action: No action is necessary.

Cause: The database server cannot open the specified tblspace. (Thevalue nn is the hexadecimal representation of the tblspacenumber.)

Action: See the ISAM error message number nn, which should explainwhy the tblspace cannot be accessed. The error message appearsin Informix Error Messages in Answers OnLine.


Messages: T-U-V

The value of pagesize pagesize specified in the config file isnot a valid pagesize. Use 2048, 4096 or 8192 as the value forPAGESIZE in the onconfig file and restart the server.

Virtual processor limit exceeded

VPCLASS classname name is too long. Maximum length is maxlength.

VPCLASS classname duplicate class name.

VPCLASS classname Not enough physical procs for affinity

Cause: This message displays upon disk initialization. The value ofPAGESIZE that was specified in the ONCONFIG file is not a validvalue.

Action: Restart the database server with a valid PAGESIZE value.

Cause: You configured the database server with more than the maximumnumber of virtual processors allowed (1000).

Action: To reduce the number of virtual processors, decrease the values ofVPCLASS, NUMCPUVPS, NUMAIOVPS, or NETTYPE in yourONCONFIG file.





Cause: The physical processors in the affinity specification for the VPclass classname do not exist or are off-line. The problem might bewith the VPCLASS parameter for cpu class VPs or with theAFF_SPROC and AFF_NPROCS parameters.

Action: Make sure the named processors are on-line. Correct the affinityspecification for the named VP class. Restart the database server.


Messages: W-X-Y-Z

Messages: W-X-Y-ZWARNING: aio_wait: errno = nn

WARNING: Buffer pool size may cause database server to get intoa locked state. Recommended minimum buffer pool size is numtimes maximum concurrent user threads.

warning: chunk timestamps are invalid.

Warning: unable to allocate requested big buffer of size nn

Cause: While the database server was waiting for an I/O request tocomplete, it generated error number nn on an operation that it wasattempting to execute.

Action: Contact Informix Technical Support for assistance.

Cause: There are not enough buffers in the buffer pool. The databaseserver could use all available buffers and cause a deadlock tooccur.

Action: Change the BUFFERS parameter in the ONCONFIG FILE to thenumber that this message recommends. For more information onthe BUFFERS parameter, see “BUFFERS” on page 1-26.

Cause: A sanity check is performed on chunks when they are first openedat system initialization. The chunk specified did not pass thecheck and will be brought off-line.

Action: Restore the chunk from a dbspace backup or its mirror.

Cause: The internal memory allocation for a big buffer failed.

Action: Increase either virtual memory size (SHMVIRTSIZE), the size of theadded segments (SHMADD), or your total shared-memory size(SHMTOTAL).


Messages: Symbols

Messages: Symbols... dropping sysmaster database

... reverting reserved pages

... reverting tables that underwent In-Place Alter

HH:MM:SS Informix database server Version R.VV.PPPPP SoftwareSerial Number RDS#XYYYYYY

Cause: The database server is dropping sysmaster database during thereversion process.


Cause: The database server is reverting reserved pages.


Cause: The database server is reverting tables that underwent in-placealter.


Cause: This message indicate the start-up of the database server, after theinitialization of shared memory.



Messages: Symbols

argument: invalid argument

function_name: cannot allocate memory

Cause: This internal error indicates that an invalid argument was passedto an internal Informix routine.


Cause: The database server cannot allocate memory from internal shared-memory pool.

Action: Increase either virtual-memory size (SHMVIRTSIZE), the size of theadded segments (SHMADD), or your total shared-memory size(SHMTOTAL).


Violations Table Messages

Violations Table MessagesCannot alter a table which has associated violations table.

Cannot create violations/diagnostics table.

Cause: The user tried to add, drop, or modify a column in a table that hasa violations table associated with it.

Action: Do not change the columns in the user table.

Cause: The user issued a START VIOLATIONS TABLE statement for a targettable. The database server cannot create the violations table forthis target table. Any of the following situations might be thereason for this failure:

■ The target table already has a violations table.

■ You specified an invalid name for the violations table inthe START VIOLATIONS TABLE statement. For example, ifyou omit the USING clause from the statement and if thenumber of characters in the target table plus fourcharacters is longer than the maximum identifier length,the generated names of the violations table exceed themaximum identifier length.

■ You specified a name for the violations table in the STARTVIOLATIONS TABLE statement that match the names ofexisting tables in the database.

■ The target table contains columns with the namesinformix_tupleid, informix_optype, orinformix_recowner. Because these column namesduplicate the informix_tupleid, informix_optype, orinformix_recowner columns in the violations table, thedatabase server cannot create the violations table.

■ The target table is a temporary table.

■ The target table is serving as a violations table for someother table.

■ The target table is a system catalog table.



Cannot insert from the violations table to the target table.

Cannot modify/drop a violations/diagnostics table.

Action: To resolve this error, perform one of the following actions:

■ If the violations table name was invalid, specify a uniquename for the violations table in the USING clause of theSTART VIOLATIONS TABLE statement.

■ If the target table contains columns with the namesinformix_tupleid, informix_optype, orinformix_recowner, rename them to something else.

■ Choose a permanent target table that is not a systemcatalog table or a violations table for some other table.

Cause: The user has issued a statement that attempts to insert rows fromthe violations table into the target table. For example, the userenters the following invalid statement:

INSERT INTO mytable SELECT * FROM mytable_vio;

Also, if the target table has filtering-mode constraints, you receivethis error. Extended Parallel Server does not support filtering-mode constraints.

Action: To recover from this error, perform the following actions:

■ Do not use filtering constraints.

■ Stop the violations table.

■ Insert rows from the violations table into a temporarytable, and then insert rows from the temporary table intothe target table.

Cause: The user has tried to alter or drop a table that is serving as a viola-tions table for another table.

Action: Do not alter or drop the violations table.



This ddl operation is not allowed due to deferred constraintspending on this table and dependent tables.

Too many violations.

Cause: This error gets returned when you attempt to start a violationstable when constraints are in deferred mode.

Note: No error is returned if you start a violations table and thenlater set the constraints to deferred. However, the violations getundone immediately rather than written into the deferredconstraint buffer. For more information, see Chapter 8, “Loadingwith External Tables for Extended Parallel Server,” and theInformix Guide to SQL: Syntax.

Action: If you would like to start a violations table, you must eitherchange the constraint mode to immediate or commit thetransaction.

Cause: The number of violations in the diagnostics table exceeds the limitthat is specified in the MAX VIOLATIONS clause of the STARTVIOLATIONS TABLE statement. When a single statement on thetarget table (such as an INSERT or UPDATE statement) inserts morerecords into the violations table than the limit that is specified bythe MAX VIOLATIONS clause, this error is returned to the user whoissued the statement on the target table.

This MAX VIOLATIONS limit applies to each coserver. Forexample, if you reach the MAX VIOLATIONS limit on coserver 2,you can continue to issue statements that violate rows on othercoservers until you reach the MAX VIOLATIONS limit.

Action: To resolve this error, perform one of the following actions:

■ Omit the MAX VIOLATIONS clause in the START VIOLA-TIONS TABLE statement when you start a violations table.Here, you are specifying no limit to the number of rows inthe violations table.

■ Set MAX VIOLATIONS to a high value.



Violations table is not started for the target table.

Violations table reversion test completed successfully.

Violations table reversion test failed.

Violations table reversion test start.

Cause: If you issue a STOP VIOLATIONS TABLE statement for which noviolations table is started, you receive this message.

Action: To recover from this error, you must start a violations table for thetarget table.

Cause: This message is recorded in the logmessage table in the sysmasterdatabase when the revtestviolations.sh script has completedsuccessfully (no open violations tables were found).

Action: No action is necessary. For more information onrevtestviolations.sh, see the Informix Migration Guide.

Cause: When the database server finds an open violations table, it reportserrors 16992 and 16993 in the logmessage table in the sysmasterdatabase and aborts the reversion process.

Action: When this message appears, you must issue the STOP VIOLA-TIONS TABLE FOR table_name command for each open violationstable. After you close all open violations tables, you can restart thereversion process.

Cause: This message is recorded in the logmessage table in the sysmasterdatabase when the revtestviolations.sh script is executed.

Action: No action is necessary. For more information onrevtestviolations.sh, see the Informix Migration Guide.


Truncate Table Messages

Violations tables still exist.

Truncate Table MessagesThe table cannot be truncated if it has an open cursor or dirtyreaders.

The table cannot be truncated. It has at least one non-emptychild table with referential constraints.

Cause: This message is recorded in the logmessage table in the sysmasterdatabase when an open violations table is found.

Action: When this message appears, you must issue the STOPVIOLATIONS TABLE FOR table_name command for each open viola-tions table. After you close all open violations tables, you canrestart the reversion process.

Cause: You must have exclusive access to the table.

Action: Wait for dirty readers to complete or close all the open cursors andreissue the TRUNCATE TABLE command.

Cause: You cannot truncate a table if it has child tables with referentialconstraints and at least one row.

Action: Empty the child tables before you truncate this table.


Truncate Table Messages

TRUNCATE table statement cannot be executed if already inside atransaction.

Cause: Because you must issue the TRUNCATE TABLE statement as asingleton transaction, you cannot nest it inside another trans-action. For example, you cannot issue TRUNCATE TABLE within aBEGIN WORK and COMMIT WORK block or inside a trigger.

Action: Issue the TRUNCATE TABLE statement as a singleton transaction,outside of a BEGIN WORK and COMMIT WORK block or trigger.

Break the transaction into several parts, as follows:

■ Commit the first part of the transaction.

You can roll back only the first part of the transaction.

■ Issue the TRUNCATE TABLE statement.

■ Execute the remaining part of the transaction as a newtransaction inside a BEGIN WORK and COMMIT WORKblock.

Example:

COMMIT WORK;TRUNCATE TABLE tab1;BEGIN WORK;INSERT INTO tabl1 VALUES ("James");...COMMIT WORK;


6Chapter

Interpreting Logical-LogRecords

In This Chapter . . . . . . . . . . . . . . . . . . . . 6-3

About Logical-Log Records . . . . . . . . . . . . . . . . 6-4Transactions That Drop a Table or Index . . . . . . . . . . 6-4Transactions That Are Rolled Back . . . . . . . . . . . . 6-4Checkpoints with Active Transactions . . . . . . . . . . . 6-5Distributed Transactions . . . . . . . . . . . . . . . 6-5

Logical-Log Record Structure . . . . . . . . . . . . . . . 6-6Logical-Log Record Header . . . . . . . . . . . . . . 6-6Logical-Log Record Types and Additional Columns . . . . . . 6-7Log Record Types for Smart Large Objects . . . . . . . . . 6-21

6-2 Infor

In This ChapterTo display the logical-log records that the logical-log files contain, use thefollowing methods:

■ onlog utility

■ ON-Archive command LIST/LOGRECORDS

For information about ON-Archive, see the Archive and BackupGuide. ♦

This chapter provides the following information:

■ Brief guidance on reading logical-log records

■ A listing of the different logical-log record types

In general, you do not need to read and interpret your logical-log files.However, onlog output is useful in debugging situations. For example, youmight want to use onlog to track a specific transaction or to see what changesthe database server made to a specific tblspace. You can also use onlog toinvestigate the cause of an error that occurs during a rollforward. For moreinformation about the specific instances in which you can use onlog, see“onlog: Display Logical-Log Contents” on page 3-31.

IDS

UNIX

Interpreting Logical-Log Records 6-3

About Logical-Log Records

About Logical-Log RecordsMost SQL statements generate multiple logical-log records. Interpretinglogical-log records is more complicated when the database server records thefollowing events in the logical log:

■ A transaction that drops a table or index

■ A transaction that rolls back

■ A checkpoint in which transactions are still active

■ A distributed transaction

The following sections discuss the logical-log records for these events.

Transactions That Drop a Table or IndexOnce the database server drops a table or index from a database, it cannot rollback that drop operation. If a transaction contains a DROP TABLE or DROPINDEX statement, the database server handles this transaction as follows:

1. The database server completes all the other parts of the transactionand writes the relevant logical-log records.

2. The database server writes a BEGCOM record to the logical log andthe records associated with the DROP TABLE or DROP INDEX(DINDEX, for example).

3. The database server writes a COMMIT record.

If the transaction is terminated unexpectedly after the database server writesthe BEGCOM record to the logical log, the database server rolls forward thistransaction during recovery because it cannot roll back the drop operation.

Transactions That Are Rolled BackWhen a rollback occurs, the database server generates a compensation-logrecord (CLR) for each record in the logical log that is rolled back. The databaseserver uses the CLRs if a system failure takes place during a rollback. The CLRsprovide the database server with information on how far the rollbackprogressed before the failure occurred. In other words, the database serveruses the CLRs to log the rollback.


Checkpoints with Active Transactions

If a CLR contains the phrase includes next record, the next log record thatis printed is included within the CLR log record as the compensatingoperation. Otherwise, you must assume that the compensating operation isthe logical undo of the log record to which the link field of the CLR points.

Checkpoints with Active TransactionsIf any transactions are active at the time of a checkpoint, checkpoint recordsinclude subentries that describe each of the active transactions using thefollowing columns:

■ Log begin (decimal format)

■ Transaction ID (decimal format)

■ Unique log number (decimal format)

■ Log position (hexadecimal format)

■ User name

Distributed TransactionsWhen distributed transactions (transactions that span multiple databaseservers) generate log records, they are slightly different than nondistributedtransactions. You might need to read and interpret them to determine thestate of the transaction on both database servers if a failure occurs as atransaction was committing.

The following log records are involved in distributed transactions:

■ BEGPREP

■ ENDTRANS

■ HEURTX

■ PREPARE

■ TABLOCKS

For more information about this type of logical-log record, see the materialon two-phase commit and logical-log records in the Administrator’s Guide.

If you are performing distributed transactions with TP/XA, the databaseserver uses an XAPREPARE record instead of a PREPARE record.

IDS


Logical-Log Record Structure

Logical-Log Record StructureEach logical-log record has header information. Depending on the recordtype, additional columns of information also appear in the output, asexplained in “Logical-Log Record Types and Additional Columns” onpage 6-7.

Logical-Log Record HeaderFigure 6-1 contains sample output to illustrate the header columns thatdisplay for a logical-log record.

Figure 6-1Sample Output from onlog

addr len type xid id link

2c018 32 BEGIN 6 3 0

2c038 140 HDELETE 6 0 2c018

2c0c4 64 DELITEM 6 0 2c038

2c104 40 DELITEM 6 0 2c0c4

2c12c 72 HDELETE 6 0 2c104

2c174 44 DELITEM 6 0 2c12c

2c1a0 72 HDELETE 6 0 2c174

2c1e8 44 DELITEM 6 0 2c1a0

2c214 64 HDELETE 6 0 2c1e8

2c254 56 DELITEM 6 0 2c214

2c28c 48 DELITEM 6 0 2c254

2c2bc 24 PERASE 6 0 2c28c

2c2d4 20 BEGCOM 6 0 2c2bc

(1 of 2)


Logical-Log Record Types and Additional Columns

Figure 6-2 defines the contents of each header column.

Figure 6-2Definition of onlog Header Columns

Logical-Log Record Types and Additional ColumnsIn addition to the six header columns that display for every record, somerecord types display additional columns of information. The information thatappears varies, depending on record type. Figure 6-3 on page 6-8 lists all therecord types and their additional columns.

The Action column indicates the type of database server action thatgenerated the log entry. The Additional Columns and Format columnsdescribe what information appears for each record type in addition to theheader described in “Logical-Log Record Header” on page 6-6.

2c2e8 24 ERASE 6 0 2c2d4

2c300 28 CHFREE 6 0 2c2e8

2c31c 24 COMMIT 6 0 2c300

Header Field Contents Format

addr Log-record address (log position) Hexadecimal

len Record length Decimal

type Record-type name ASCII

xid Transaction number Decimal

id Logical-log number Decimal

link Link to the previous record in the transaction Hexadecimal

addr len type xid id link

(2 of 2)



Figure 6-3Logical-Log Record Types

Record Type Action Additional Columns Format

ADDCHK Add chunk. chunk number

chunk name

decimal

ASCII

ADDDBS Add dbspace. dbspace name ASCII

ADDITEM Add item to index. tblspace ID

rowid

logical page

key number

key length

hexadecimal

hexadecimal

decimal

decimal

decimal

ADDLOG Add log. log number

log size (pages)

pageno

decimal

decimal

hexadecimal

ALTERDONE Alter of fragment complete. tblspace ID

physical page numberprevious page

logical page number

version of alter

hexadecimal

hexadecimal

decimal

decimal

BADIDX Bad index tblspace ID hexadecimal

BEGCOM Begin commit. (none) (none)

BEGIN Begin work. date

time

PID

user

decimal

decimal

decimal

ASCII

BEGPREP(IDS)

Written by the coordinator databaseserver to record the start of the two-phase commit protocol.

flags

no. of participants

decimal(Value is 0 ina distributedtransaction.)

decimal

(1 of 14)



BFRMAP Simple-large-object free-map change. tblspace ID

bpageno

status

log ID

prev page

hexadecimal

hexadecimal

USED/FREE

decimal

hexadecimal

BLDCL Build tblspace. tblspace ID

fextsize

nextsize

row size

ncolumns

table name

hexadecimal

decimal

decimal

decimal

decimal

ASCII

BMAPFULL Bitmap modified to prepare for alter. tblspace ID

bitmap page num

hexadecimal

decimal

BMAP2TO4 2-bit bitmap altered to two 4-bitbitmaps.

tblspace ID

2-bit bitmap pagenumber

flags

hexadecimal

decimal

decimal

BSPADD(IDS)

Add blobspace. blobspace name ASCII

BTCPYBCK Copy back child key to parent. tblspace ID

parent logical page

child logical page

slot

rowoff

key number

hexadecimal

decimal

decimal

decimal

decimal

decimal


(2 of 14)



BTMERGE Merge B-tree nodes. tblspace ID

parent logical page

left logical page

right logical page

left slot

left rowoff

right slot

right rowoff

key number

hexadecimal

decimal

decimal

decimal

decimal

decimal

decimal

decimal

decimal

BTSHUFFL Shuffle B-tree nodes. tblspace ID

parent logical page

left logical page

right logical page

left slot

left rowoff

key number

flags

hexadecimal

decimal

decimal

decimal

decimal

decimal

decimal

hexadecimal

BTSPLIT Split B-tree node. tblspace ID

rowid

parent logical page

left logical page

right logical page

infinity logical page

rootleft logical page

midsplit

key number

key length

hexadecimal

hexadecimal

decimal

decimal

decimal

decimal

decimal

decimal

decimal

decimal

CHALLOC Chunk extent allocation. pageno

size

hexadecimal

hexadecimal

CHCOMBINE Chunk extent combine. pageno hexadecimal


(3 of 14)



CHFREE Chunk extent free. pageno

size

hexadecimal

hexadecimal

CHPHYLOG Change physical-log location. pageno

size in kilobytes

dbspace name

hexadecimal

hexadecimal

ASCII

CHSPLIT Chunk extent split. pageno hexadecimal

CINDEX Create index. tblspace ID

low rowid

high rowid

index descriptor

hexadecimal

decimal

decimal

ASCII

COARSELOCK Coarse-grain locking tblspace ID

old coarse-locking flagvalue

new coarse-lockingflag value

hexadecimal

decimal

decimal

CKPOINT Checkpoint. max users

number ofactive transactions

decimal

decimal

CLR Compensation-log record; part of arollback.

(none) (none)

CLUSIDX Create clustered index. tblspace ID

key number

hexadecimal

decimal

COLREPAI Adjust BYTE, TEXT, or VARCHARcolumn.

tblspace ID

no. of columnsadjusted

hexadecimal

decimal

COMMIT Commit work. date

time

decimal

decimal

DELETE Delete before-image. tblspace ID

rowid

hexadecimal

hexadecimal


(4 of 14)



DELITEM Delete item from index. tblspace ID

rowid

logical page

key number

key length

hexadecimal

hexadecimal

decimal

decimal

decimal

DERASE Drop tblspace in down dbspace. tblspace ID

lockid

hexadecimal

hexadecimal

DINDEX Drop index. tblspace ID

key number

hexadecimal

decimal

DPT List all dirty pages not flushed to diskduring a fuzzy checkpoint. This recordis written just before the CKPOINTrecord and linked to it.

The DPT records are not written duringa full checkpoint because all the dirtypages are flushed to disk

number of dirty pages hexadecimal

DRPBSP(IDS)

Drop blobspace. blobspace name ASCII

DRPCHK Drop chunk. chunk number

chunk name

decimal

ASCII

DRPDBS Drop dbspace. dbspace name ASCII

DRPLOG Drop log. log number

log size (pages)

pageno

decimal

decimal

hexadecimal


(5 of 14)



ENDTRANS(IDS)

Written by both the coordinator andparticipant database servers to recordthe end of the transaction. ENDTRANSinstructs the database server to removethe transaction entry from its shared-memory transaction table and close thetransaction.

In the coordinator logical log, eachBEGPREP that results in a committedtransaction is paired with anENDTRANS record. If the final deci-sion of the coordinator is to roll back thetransaction, no ENDTRANS record iswritten.

In the participant logical log, eachENDTRANS record is paired with acorresponding HEURTX record.

(none) (none)

ERASE Drop tblspace. tblspace ID hexadecimal

HDELETE Delete home row. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

HEURTX(IDS)

Written by a participant databaseserver to record a heuristic decision toroll back the transaction. It should beassociated with a standard ROLLBACKrecord indicating that the transactionwas rolled back.

flag hexadecimal(Value isalways 1.)

HINSERT Home row insert. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

HUPAFT Home row update, after-image. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal


(6 of 14)



HUPBEF Home row update, before-image. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

HUPDATE If the home row update before-imagesand after-images can both fit into asingle page, the database server writesa single HUPDATE record.

tblspace ID

rowid

forward ptr rowid

old slotlen

new slotlen

no. of pieces

hexadecimal

hexadecimal

hexadecimal

decimal

decimal

decimal

IDXFLAGS Index flags. tblspace ID

key number

hexadecimal

hexadecimal

INSERT Insert after-image. tblspace ID

rowid

hexadecimal

hexadecimal

LCKLVL Locking mode. tblspace ID

old lockmode

new lockmode

hexadecimal

hexadecimal

hexadecimal

LG_CDINDEX Create detached index. database name

owner

table name

index name

ASCII

ASCII

ASCII

ASCII

LG_DERASE Drop tblspace in disabled dbspace. tblspace number

table lock number

hexadecimal

decimal

LG_ENDTRUNCATE(XPS)

Indicate that the TRUNCATE TABLEoperation, which removes all the rowsfrom tables and indexes, completed.

tblspace ID hexadecimal

LG_PTRUNCATE(XPS)

Mark tblspace for truncation at committime.


LG_TRUNCATE(XPS)

Truncate has freed the extents and thetransaction will be committed.



(7 of 14)



MVIDXND Index node moved to allow for 2-bit to4-bit bitmap conversion.

tblspace ID

old page number

new page number

parent page number

parent slot number

parent slot offset

key number

hexadecimal

decimal

decimal

decimal

decimal

decimal

decimal

PBDELETE Delete tblspace blobpage. bpageno

status

unique ID

hexadecimal

USED/FREE

decimal

PBINSERT Insert tblspace blobpage. bpageno

tblspace ID

rowid

slotlen

pbrowid

hexadecimal

hexadecimal

hexadecimal

decimal

hexadecimal

PDINDEX Predrop index. tblspace ID hexadecimal

PGALTER Page altered in-place. tblspace ID

physical page number

hexadecimal

hexadecimal


(8 of 14)



PGMODE Page mode modified in bitmap. tblspace ID

logical page number

old mode

new mode

hexadecimal

decimal

hexadecimal

hexadecimal

PERASE Preerase old file. tblspace ID hexadecimal

PNLOCKID Change tblspaces lockid. tblspace ID

old lock ID

new lock ID

hexadecimal

hexadecimal

hexadecimal

PNSIZES Set tblspace extent sizes. tblspace ID

fextsize

nextsize

hexadecimal

decimal

decimal

PREPARE(IDS)

Written by a participant databaseserver to record the ability of theparticipant to commit the transaction,if so instructed.

DBSERVERNAME ofcoordinator

ASCII

PTADESC Add alter description information. tblspace ID

physical page numberof previous page

logical page number

number of columnsadded

hexadecimal

hexadecimal

decimal

decimal


(9 of 14)



PTALTER Alter of fragment begun. tblspace ID

physical page numberprevious page

logical page number

alter desc pagenumber

num columns added

version of alter

added rowsize

hexadecimal

hexadecimal

decimal

decimal

decimal

decimal

decimal

PTCOLUMN Add special columns to fragment. tblspace ID

number of columns

hexadecimal

decimal

PTEXTEND Tblspace extend. tblspace ID

last logical page

first physical page

hexadecimal

decimal

hexadecimal

PTRENAME Rename table. tblspace ID

old table name

new table name

hexadecimal

ASCII

ASCII

RDELETE Remainder page delete. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

REVERT Logs the reversion of a database spaceto a database space of an earlierversion.

type of reversionevent

arg1

arg2

arg3

decimal

decimal

decimal

decimal

RINSERT Remainder page insert. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal


(10 of 14)



ROLLBACK Rollback work. date

time

decimal

decimal

RSVEXTEN Logs the extension to the reservedpages.

no. of pages

physical page numberof extent

decimal

hexadecimal

RUPAFT Remainder page update, after-image. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

RUPBEF Remainder page update, before-image. tblspace ID

rowid

slotlen

hexadecimal

hexadecimal

decimal

RUPDATE If the remainder page updatebefore-images and after-images canboth fit into a single page, the databaseserver writes a single RUPDATErecord.

tblspace ID

rowid

forward ptr rowid

old slotlen

new slotlen

no. of pieces

hexadecimal

hexadecimal

hexadecimal

decimal

decimal

decimal


(11 of 14)



SBLOB(IDS)

Indicates a subsystem log record for asmart large object.

The various record subtypes are:

■ CHALLOC

■ CHCOMBINE

■ CHFREE

■ CHSPLIT

■ CREATE

■ DELETES

■ EXTEND

■ HDRUPD

■ PDELETE

■ PTRUNC

■ REFCOUNT

■ UDINSERT

■ UDINSERT_LT

■ UDUPAFT

■ UDUPAFT_LT

■ UDUPAFT

■ UDUPAFT_LT

■ UDWRITE

■ UDWRITE_LT

Varies

For more information,see “Log Record Typesfor Smart LargeObjects” on page 6-21.

Varies

SYNC Written to a logical-log file if that logfile is empty and administratorinstructs the database server to switchto next log file.

(none) (none)


(12 of 14)



TABLOCKS(IDS)

Written by either a coordinator or aparticipant database server. It is associ-ated with either a BEGPREP or aPREPARE record and contains a list ofthe locked tblspaces (by tblspacenumber) held by the transaction. (In adistributed transaction, transactionsare shown as the owners of locks.)

no. of locks

tblspace number

decimal

hexadecimal

UDINSERT Append of new user data. chunk

page within chunk

offset within page

data length

decimal

hexadecimal

hexadecimal

hexadecimal

UDUPAFT Update of user data after-image if aUDWRITE is too expensive.

chunk

page within chunk

offset within page

data length

decimal

hexadecimal

hexadecimal

hexadecimal

UDUPBEF Update of user-data before-image if aUDWRITE is too expensive.

chunk

page within chunk

offset within page

data length

decimal

hexadecimal

hexadecimal

hexadecimal

UDWRITE Update of user data (difference image). chunk

page within chunk

offset within chunk

length before write

length after write

decimal

hexadecimal

hexadecimal

hexadecimal

hexadecimal

UNDO Header record to a series of transac-tions to be rolled back.

count decimal

UNDOBLDC This record is written if a CREATETABLE statement should be rolled backbut cannot be because the relevantchunk is down. When the log file isreplayed, the table will be dropped.

tblspace number hexadecimal


(13 of 14)


Log Record Types for Smart Large Objects

Log Record Types for Smart Large ObjectsAll smart-large-object log records are the SBLOB type. Each smart-large-objectlog record contains six header columns, described in “Logical-Log RecordHeader” on page 6-6; the record subtype; and additional information. Theinformation that appears varies, depending on record subtype.

Figure 6-4 lists all the smart-large-object record types. The Subtype columndescribes the smart-large-object record type. The Action column indicatesthe type of database server action that generated the log entry. TheAdditional Columns and Format columns describe what informationappears for each record type.

Figure 6-4Record Subtypes for Smart Large Objects

UNIQID Logged when a new serial value isassigned to a row.

tblspace ID

unique ID

hexadecimal

decimal

UPDAFT Update after-image. tblspace ID

rowid

hexadecimal

hexadecimal

UPDBEF Update before-image. tblspace ID

rowid

hexadecimal

hexadecimal

XAPREPARE Participant can commit this XAtransaction.

(none) (none)


(14 of 14)

Record Subtype Action Additional Columns Format

CHALLOC Allocate chunk extent. extent (chk,page,len)

flags

decimal

hexadecimal

CHCOMBINE Combine two pages inthe user-data extent list.

chunk number

first page

second page

decimal

decimal

decimal

(1 of 3)

IDS



CHFREE Frees chunk extent. extent (chk,page,len) decimal

CHSPLIT Split a page in the user-data extent list.

chunk number

UDFET page to split

decimal

decimal

CREATE Create smart large object. smart-large-object ID[sbs,chk,page,oid]

number of extents inlomaphdr

decimal

decimal

DELETE Delete a smart largeobject at commit.

smart-large-object ID[sbs,chk,page,oid]

decimal

EXTEND Add extent to an extentlist of a smart largeobject.


decimal

extent (chk,page,len) decimal

lomap overflow pagenumber

decimal

HDRUPD Update smart-large-object header page.


old EOF offset

new EOF offset

old times

new times

decimal

string

string

decimal

decimal

PDELETE Queue a smart largeobject for deletion atcommit.


decimal

PTRUNC Queue a smart largeobject for truncation atcommit.


old offset

new offset

decimal

string

string

REFCOUNT Increment or decrementthe reference count of asmart large object.


1 if increment; 0 ifdecrement

decimal

decimal


(2 of 3)



For an example of smart-large-object records in onlog output, see smart-large-object log records in the chapter on what is the logical log in the Admin-istrator’s Guide.

UDINSERT,

UDINSERT_LT

Append of new userdata.

chunk

page within chunk

offset within page

data length

decimal

decimal

decimal

decimal

UDUPAFT,

UDUPAFT_LT

Update of user-dataafter-image if aUDWRITE is tooexpensive.

chunk

page within chunk

offset within page

data length

decimal

decimal

decimal

decimal

UDUPBEF,

UDUPBEF_LT

Update of user-databeforeimage if aUDWRITE is tooexpensive.

chunk

page within chunk

offset within page

data length

decimal

decimal

decimal

decimal

UDWRITE,

UDWRITE_LT

Update of user data(difference image).

chunk

page within chunk

offset within page

length before write

length after write

number of differentimage pieces

decimal

decimal

decimal

decimal

decimal

decimal


(3 of 3)



Figure 6-5 shows an example of smart-large-object records in onlog output.The first two records show that an extent was freed. The next group ofrecords, flanked by BEGIN and COMMIT, shows the allocation of storage andcreation of the smart large objects.

addr len type xid id link subtype specific-info

4e8428 40 SBLOB 8 0 4e7400 CHFREE (2,53,421)4e8450 40 SBLOB 8 0 4e8428 CHFREE (2,579,421)

c8018 40 BEGIN 8 3 0 07/13/98 10:23:04 34 informixc8040 264 SBLOB 8 0 c8018 CREATE [2,2,1,900350517] 10c8148 44 SBLOB 8 0 c8040 CHALLOC (2,53,8) 0x1c8174 68 SBLOB 8 0 c8148 EXTEND [2,2,1,900350517] (2,53,8) -1c81b8 264 SBLOB 8 0 c8174 CREATE [2,2,2,900350518] 10c82c0 44 SBLOB 8 0 c81b8 CHALLOC (2,61,1) 0x1c82ec 68 SBLOB 8 0 c82c0 EXTEND [2,2,2,900350518] (2,61,1) -1c8330 56 SBLOB 8 0 c82ec REFCOUNT [2,2,1,900350517] 1c8368 56 SBLOB 8 0 c8330 REFCOUNT [2,2,2,900350518] 1c83a0 36 COMMIT 8 0 c8368 07/13/98 10:23:05

c83c4 40 BEGIN 8 3 0 07/13/98 10:23:05 34 informixc83ec 264 SBLOB 8 0 c83c4 CREATE [2,2,3,900350519] 10c84f4 44 SBLOB 8 0 c83ec CHALLOC (2,62,1) 0x1c8520 68 SBLOB 8 0 c84f4 EXTEND [2,2,3,900350519] (2,62,1) -1c8564 56 SBLOB 8 0 c8520 REFCOUNT [2,2,3,900350519] 1c859c 36 COMMIT 8 0 c8564 07/13/98 10:23:05

Figure 6-5Smart-Large-Object

Records in onlogOutput


7Chapter

Disk Structures and Storage

In This Chapter . . . . . . . . . . . . . . . . . . . . 7-3

Dbspace Structure and Storage . . . . . . . . . . . . . . . 7-4Structure of the Root Dbspace . . . . . . . . . . . . . . 7-4

Reserved Pages . . . . . . . . . . . . . . . . . 7-5Safewrite Area. . . . . . . . . . . . . . . . . . 7-5

Structure of a Regular Dbspace . . . . . . . . . . . . . 7-5Structure of an Additional Dbspace Chunk . . . . . . . . 7-6

Structure of a Mirrored Chunk . . . . . . . . . . . . . 7-7Structure of the Chunk Free-List Page . . . . . . . . . . . 7-8Structure of the Tblspace Tblspace . . . . . . . . . . . . 7-9

Tblspace Tblspace Entries . . . . . . . . . . . . . . 7-9Tblspace Numbers . . . . . . . . . . . . . . . . 7-10Tblspace Number Elements . . . . . . . . . . . . . 7-11Tblspace Tblspace Size . . . . . . . . . . . . . . . 7-11Tblspace Tblspace Bit-Map Page . . . . . . . . . . . 7-12

Structure of the Database Tblspace . . . . . . . . . . . . 7-12Database Tblspace Number . . . . . . . . . . . . . 7-13Database Tblspace Entries. . . . . . . . . . . . . . 7-13

Structure and Allocation of an Extent . . . . . . . . . . . 7-13Extent Structure . . . . . . . . . . . . . . . . . 7-14Next-Extent Allocation . . . . . . . . . . . . . . . 7-19

Structure and Storage of a Dbspace Page . . . . . . . . . . 7-22Rows in Nonfragmented Tables . . . . . . . . . . . . 7-22Rows in Fragmented Tables . . . . . . . . . . . . . 7-24Recommendations on Use of Rowid . . . . . . . . . . 7-24Data-Row Format and Storage . . . . . . . . . . . . 7-25

Structure of Fragmented Tables . . . . . . . . . . . . . 7-26Attached and Detached Indexes. . . . . . . . . . . . 7-27

7-2 Infor

Structure of B-Tree Index Pages . . . . . . . . . . . . . 7-27Definition of B-Tree Terms . . . . . . . . . . . . . . 7-28Logical Storage of Indexes . . . . . . . . . . . . . . 7-29Functional Indexes . . . . . . . . . . . . . . . . 7-34

Structure of Bitmap Indexes . . . . . . . . . . . . . . 7-35Structure of R-Tree Index Pages . . . . . . . . . . . . . 7-35

Storage of Simple Large Objects . . . . . . . . . . . . . . 7-36Structure of a Blobspace . . . . . . . . . . . . . . . . 7-36Structure of a Dbspace Blobpage . . . . . . . . . . . . . 7-37Simple-Large-Object Storage and the Descriptor . . . . . . . 7-37

Creation of Simple Large Objects . . . . . . . . . . . 7-37Deletion or Insertion of Simple Large Objects . . . . . . . 7-38Size Limits for Simple Large Objects . . . . . . . . . . 7-38

Blobspace Page Types. . . . . . . . . . . . . . . . . 7-38Blobspace Free-Map Page . . . . . . . . . . . . . . 7-38Blobspace Bit-Map Page . . . . . . . . . . . . . . 7-39Blobpage . . . . . . . . . . . . . . . . . . . . 7-39

Structure of a Blobspace Blobpage . . . . . . . . . . . . 7-39Blobpage Structure . . . . . . . . . . . . . . . . 7-40

Sbspace Structure . . . . . . . . . . . . . . . . . . . 7-40Structure of the Metadata Area . . . . . . . . . . . . . 7-42Sbpage Structure . . . . . . . . . . . . . . . . . . 7-43Multiple Chunk Sbspace. . . . . . . . . . . . . . . . 7-44

Database and Table Creation: What Happens on Disk . . . . . . . 7-45Database Creation . . . . . . . . . . . . . . . . . . 7-45

Disk-Space Allocation for System Catalog Tables . . . . . . 7-45Tracking of System Catalog Tables . . . . . . . . . . . 7-46

Table Creation . . . . . . . . . . . . . . . . . . . 7-46Disk-Space Allocation . . . . . . . . . . . . . . . 7-47Entry in the Tblspace Tblspace . . . . . . . . . . . . 7-47Entries in the System Catalog Tables . . . . . . . . . . 7-47Creation of a Temporary Table . . . . . . . . . . . . 7-48


In This ChapterThe database server achieves its high performance by managing its own I/O.The database server manages storage, search, and retrieval. As the databaseserver stores data, it creates the structures it needs to search for and retrievethe data later. The database server disk structures also store and track controlinformation needed to manage logging and backups. Database server struc-tures contain all the information needed to ensure data consistency, bothphysical and logical.

Before you read this chapter, familiarize yourself with the disk-space termsand definitions in the chapter on where data is stored in the Administrator’sGuide.

This chapter discusses the following topics related to disk data structures:

■ Dbspace structure and storage

■ Storage of simple large objects

■ Sbspace structure ♦■ Database and table creation: what happens on disk

IDS

Disk Structures and Storage 7-3

Dbspace Structure and Storage

Dbspace Structure and StorageThis section explores the disk structures and storage techniques that thedatabase server uses to store data in a dbspace.

Structure of the Root DbspaceThe ROOTNAME, ROOTOFFSET, ROOTPATH, and ROOTSIZE configurationparameters specify the size and location of the initial chunk of the rootdbspace. If the root dbspace is mirrored, the MIRROROFFSET andMIRRORPATH configuration parameters specify the mirror-chunk location.For more information about these parameters, see Chapter 1, “ConfigurationParameters.”

As part of disk-space initialization, the database server initializes thefollowing structures in the initial chunk of the root dbspace:

■ Twelve reserved pages

■ The first chunk free-list page

■ The tblspace tblspace

■ The database tblspace

■ The physical log

■ The logical-log files

■ The safewrite area ♦

To check that your root dbspace follows this organization, execute thefollowing command, which produces a dbspace usage report by chunk:

■ onutil CHECK SPACE

For more information, see “CHECK SPACE” on page 3-186. ♦■ oncheck -pe

For more information, see “Checking the Chunk Free List with -ceand -pe” on page 3-17. ♦

XPS

XPS

IDS


Structure of a Regular Dbspace

Reserved Pages

The first 12 pages of the initial chunk of the root dbspace are reserved pages.Each reserved page contains specific control and tracking information usedby the database server.

To obtain a listing of the contents of your reserved pages, execute thecommand oncheck -pr.

Safewrite Area

The safewrite area is used to store information about the configuration ofcoservers within Extended Parallel Server. The safewrite area is stored oncoserver 1. The CONFIGSIZE parameter determines the size of the safewritearea. For information about how to configure the safewrite area, refer to“CONFIGSIZE” on page 1-30.

Structure of a Regular DbspaceAfter disk-space initialization, you can add new dbspaces. When you createa dbspace, you assign at least one chunk (either raw or cooked disk space) tothe dbspace. This chunk is referred to as the initial chunk of the dbspace.Figure 7-1 on page 7-6 illustrates the structure of the initial chunk of a regular(nonroot) dbspace.

When the dbspace is first created, it contains the following structures:

■ The first chunk free-list page in the chunk

■ The tblspace tblspace for this dbspace

■ Unused pages

XPS


Structure of a Regular Dbspace

Structure of an Additional Dbspace Chunk

You can create a dbspace that contains more than one chunk. The initialchunk in a dbspace contains the tblspace tblspace for the dbspace. Additionalchunks do not. When an additional chunk is first created, it contains thefollowing structures:

■ Two reserved pages (reserved for future use)

■ The first chunk free-list page

■ Unused pages

Figure 7-1Initial Chunk of

Regular DbspaceChunk free-listpage

Tblspace tblspace

Unused pages


Structure of a Mirrored Chunk

Figure 7-2 illustrates the structure of all additional chunks in a dbspace. (Thestructure also applies to additional chunks in the root dbspace.)

Structure of a Mirrored ChunkEach mirrored chunk must be the same size as its primary chunk. When amirrored chunk is created, the database server writes the contents of theprimary chunk to the mirrored chunk immediately.

The mirrored chunk contains the same control structures as the primarychunk. Mirrors of either blobspace (Dynamic Server) or dbspace chunkscontain the same physical contents as their primary counterpart after thedatabase server brings them on-line.

Figure 7-2Additional Dbspace

ChunkChunk free-listpage

Unused pages

Reserved pages


Structure of the Chunk Free-List Page

Figure 7-3 illustrates the mirror-chunk structure as it appears after the chunkis created.

The mirror-chunk structure always shows no free space because all of itsspace is reserved for mirroring. For more information, see the chapter onwhat is mirroring in the Administrator’s Guide.

Structure of the Chunk Free-List PageIn every chunk, the page that follows the last reserved page is the first of oneor more chunk free-list pages that tracks available space in the chunk. Theinitial length of the free space is equal to the size of the chunk minus threepages. If an additional chunk free-list page is needed to accommodate newentries, a new chunk free-list page is created in one of the free pages in thechunk. Figure 7-4 illustrates the location of the free-list page.

Use onutil CHECK SPACE DISPLAY to obtain the physical layout of pages inthe chunk. For more information, see “CHECK SPACE” on page 3-186. ♦

Use oncheck -pe to obtain the physical layout of pages in the chunk. For moreinformation, see “Checking the Chunk Free List with -ce and -pe” onpage 3-17. ♦

Figure 7-3Mirror-Chunk

StructureNumber and type ofoverhead pagesvary, depending onchunk type.Overhead pages

XPS

IDS


Structure of the Tblspace Tblspace

Structure of the Tblspace TblspaceIn the initial chunk of every dbspace, the page that follows the chunk free-listpage is the first page of the tblspace tblspace. The tblspace tblspace is acollection of pages that describe the location and structure of all tblspaces inthis dbspace.

Tblspace Tblspace Entries

Each page in the tblspace tblspace describes one tblspace in the dbspace andis considered one entry. Entries in the tblspace tblspace are added when anew table is created or when a fragment is added to a fragmented table.

The first page in every tblspace tblspace is a bit map of the pages in thetblspace tblspace. The second page is the first tblspace entry, and it describesitself. The third page describes the first user-created table in this dbspace.Each tblspace tblspace entry (page) includes the following components.

To display information on the tblspace, use the onutil CHECK INFO INTABLESPACE partnum DISPLAY command. For more information, see“CHECK INFO” on page 3-178. ♦

To display information on the tblspace, use the oncheck -pt command. Formore information, see “Displaying Tblspace Information for a ParticularTable or Fragment with -pt and -pT” on page 3-22. ♦

Figure 7-4Free-List PageChunk free-list page

Free pages

Reservedpages

XPS

IDS



Tblspace Numbers

Each tblspace that is described in the tblspace tblspace receives a tblspacenumber. This tblspace number is the same value that is stored as the partnumfield in the systables system catalog table and as the partn field in thesysfragments system catalog table.

The following SQL query retrieves the partnum for every table in thedatabase (these can be located in several different dbspaces) and displays itwith the table name and the hexadecimal representation of partnum:

SELECT tabname, tabid, partnum, HEX(partnum) hex_tblspace_name FROM systables

Component Description

Page header 56 bytes, standard page-header information

Page-ending time stamp 4 bytes

Tblspace header 68 bytes, general tblspace information.

Column information Each special column in the table is tracked with an12-byte entry. (A special column is defined as aVARCHAR, BYTE, or TEXT data type.)

Tblspace name 80 bytes, database.owner.tablename

Index information Each index on the table contains a 20-byte header thatcontains general information about the index, followedby a 4-byte entry for each column component of theindex.

Extent information Each extent allocated to this tblspace is tracked with a12-byte entry.



If the output includes a row with a table name but a partnum of 0, this tableconsists of two or more table fragments, each located in its own tblspace. Forexample, Figure 7-5 shows a table called account that has partnum 0.

To obtain the actual tblspace numbers for the fragments that make up thetable, you must query the sysfragments table for the same database.Figure 7-6 shows that the account table from Figure 7-5 has three tablefragments and three index fragments.

Tblspace Number Elements

The first page in a tblspace is logical page 0. (Physical page numbers refer tothe address of the page in the chunk.) The root space tblspace tblspace isalways contained in the first dbspace and on logical page 1 within thetblspace tblspace. (The bit-map page is page 0.)

Tblspace Tblspace Size

The initial size of the tblspace tblspace is always 50 pages. These tblspacetblspace pages are allocated as an extent when the dbspace is initialized. Ifthe database server attempts to create a table, but the tblspace tblspace is full,the database server allocates a next extent to the tblspace.

tabname tabid partnum hex_tblspace_name

sysfragments 25 1048611 0x00100023branch 100 1048612 0x00100024teller 101 1048613 0x00100025account 102 0 0x00000000history 103 1048615 0x00100027results 104 1048616 0x00100028


systables Querywith partnum Values

tabid fragtype partn hex_tblspace_name

102 T 1048614 0x00100026102 T 2097154 0x00200002102 T 3145730 0x00300002102 I 1048617 0x00100029102 I 2097155 0x00200003102 I 3145731 0x00300003


sysfragments Tablewith partn Values


Structure of the Database Tblspace

When a table is removed from the dbspace, its corresponding entry in thetblspace tblspace is deleted.

Tblspace Tblspace Bit-Map Page

The first page of the tblspace tblspace, like the first page of any initial extent,is a bit map that describes the page fullness of the following pages. Each pagethat follows has an entry on the bit-map page. If needed, additional bit-mappages are located throughout the contiguous space allocated for the tblspace,arranged so that each bit map describes only the pages that follow it, until thenext bit map or the end of the dbspace. Bit-map pages fall at distinct intervalswithin tblspaces pages. Each bit-map page describes a fixed number of pagesthat follow it.

Structure of the Database TblspaceThe database tblspace appears only in the initial chunk of the root dbspace.The database tblspace contains one entry for each database managed by thedatabase server. Figure 7-7 illustrates the location of the database tblspace.

Figure 7-7Database Tblspace

Location in InitialChunk of Root

Dbspace

Reserved pages

Tblspace tblspace

Database tblspace

Free pages

Chunk free-list page


Structure and Allocation of an Extent

Database Tblspace Number

The tblspace number of the database tblspace is always 0x10002. Thistblspace number appears in an onstat -t listing if the database tblspace isactive.

Database Tblspace Entries

Each database tblspace entry includes the following five components:

■ Database name

■ Database owner

■ Date and time that the database was created

■ The tblspace number of the systables system catalog table for thisdatabase

■ Flags that indicate logging mode

The database tblspace includes a unique index on the database name toensure that every database is uniquely named. For any database, thesystables table describes each permanent table in the database. Therefore, thedatabase tblspace only points to the detailed database information locatedelsewhere.

When the root dbspace is initialized, the database tblspace first extent isallocated. The initial-extent size and the next-extent size for the databasetblspace are four pages. You cannot modify these values.

Structure and Allocation of an ExtentThis section covers the following topics:

■ Extent structure

■ Next-extent allocation



Extent Structure

An extent is a collection of contiguous pages within a dbspace. Everypermanent 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 firstcreated. The next-extent size is the number of kilobytes allocated to the tablewhen the initial extent, and every extent thereafter, becomes full.

Blobspaces do not use extents. ♦

For specific instructions on how to specify and calculate the size of an extent,see your Performance Guide.

Extent Size

The minimum size of an extent is four pages. The default size of an extent iseight pages. The maximum size limit of an extent is two gigabytes. If theextent goes into a chunk that is smaller than two gigabytes, the maximumextent size depends on the contiguous space available in the chunk.

Tblspaces that hold index fragments follow different rules for extent size. Thedatabase server bases the extent size for these tblspaces on the extent size forthe corresponding table fragment. The database server uses the ratio of therow size to index key size to assign an appropriate extent size for the indextblspace (see the section on estimating index page size in the PerformanceGuide). For more information, see fragmenting table indexes in the chapter ontable fragmentation and PDQ in the Administrator’s Guide.

Page Types Within a Table Extent

Within the extent, individual pages contain different types of data. Extentpages for a table can be separated into the following categories:

■ Data pages

Data pages contain the data rows for the table.

■ Bit-map pages

Bit-map pages contain control information that monitors the fullnessof every page in the extent.

IDS



■ Blobpages

Blobpages contain TEXT and BYTE data that is stored with the datarows in the dbspace. TEXT and BYTE data that resides in a blobspaceis stored in blobpages, a structure that is completely different thanthe structure of a dbspace blobpage. ♦

■ Free pages

Free pages are pages in the extent that are allocated for tblspace use,but whose function has not yet been defined. Free pages can be usedto store any kind of information: data, including TEXT or BYTE datatypes; index; or bit map.

Figure 7-8 on page 7-16 illustrates the possible structure of a nonfragmentedtable with an initial-extent size of 8 pages and a next-extent size of 16 pages.

IDS



Figure 7-8Extent Structure

of a Table

Bit-map page

Data pages

Blobpage

Data pages

Initial extent

Next extent

Data pages

Blobpage

Free pages



Page Types Within an Index Extent

The database server stores index pages into different tblspaces than the tablewith which it is associated. Within the extent, individual index pages containdifferent types of data. Index pages can be separated into the followingcategories:

■ Index pages (root, branch, and leaf pages)

Index pages contain the index information for the table.

■ Bit-map pages

Bit-map pages contain control information that monitors the fullnessof every page in the extent.

■ Free pages

Free pages are pages in the extent that are allocated for tblspace use,but whose function has not yet been defined. Free pages can be usedto store any kind of information: data, index, TEXT or BYTE data, orbit map.

All indexes are detached unless you explicitly specify attached indexes.

Important: An extent that is allocated for a table fragment does not contain indexpages. Index pages for a fragmented table always reside in a separate tblspace. Formore information, see fragmenting table indexes in the chapter on table fragmen-tation and PDQ in the “Administrator’s Guide.”

Figure 7-9 on page 7-18 illustrates the extent structure of an index.



Figure 7-9Extent Structure

of an Index

Bit-map page

Index pages

Initial extent

Next extent

Index pages

Free pages



Next-Extent Allocation

After the initial extent fills, the database server attempts to allocate anotherextent of contiguous disk space. The procedure that the database serverfollows is referred to as next-extent allocation.

Extents for a tblspace are tracked as one component of the tblspace tblspaceinformation for the table. The maximum number of extents allocated for anytblspace is application and machine dependent because it varies with theamount of space available on the tblspace tblspace entry.

Next-Extent Size

The number of kilobytes that the database server allocates for a next extentis, in general, equal to the size of a next extent, as specified in the SQLstatement CREATE TABLE. However, the actual size of the next-extentallocation might deviate from the specified size because the allocationprocedure takes into account the following three factors:

■ Number of existing extents for this tblspace

■ Availability of contiguous space in the chunk and dbspace

■ Location of existing tblspace extents

The effect of each of these factors on next-extent allocation is explained in theparagraphs that follow and in Figure 7-10 on page 7-21.

Extent Size Doubling

If a tblspace already has 16 extents allocated, the database server automati-cally doubles the size for subsequent allocations. This doubling occurs every16 extents. For example, if you create a table with NEXT SIZE equal to 20kilobytes, the database server allocates the first 16 extents at a size of 20kilobytes each. The database server allocates extents 17 to 32 at 40 kilobyteseach, extents 33 to 48 at 80 kilobytes each, and so on.



Lack of Contiguous Space

If the database server cannot find available contiguous space in the firstchunk equal to the size specified for the next extent, it extends the search tothe next chunk in the dbspace. Extents are not allowed to span chunks.

If the database server cannot find adequate contiguous space anywhere inthe dbspace, it allocates to the table the largest available amount ofcontiguous space. (The minimum allocation is four pages. The default valueis eight pages.) No error message is returned if an allocation is possible, evenwhen the amount of space allocated is less than the requested amount.

Merge of Extents for the Same Table

If the disk space allocated for a next extent is physically contiguous with diskspace already allocated to the same table, the database server allocates thedisk space but does not consider the new allocation as a separate extent.Instead, the database server extends the size of the existing contiguousextent. Thereafter, all disk-space reports reflect the allocation as an extensionof the existing extent. That is, the number of extents reported is always thenumber of physically distinct extents, not the number of times a next extenthas been allocated plus one (the initial extent). Figure 7-10 illustratesextent-allocation strategies.



Figure 7-10Next-Extent

AllocationStrategies

Chunk 1

Chunk 1

Chunk 1

Chunk 6

Extent sizes double every 16 extents.

If the dbspace is too full to accommodate the next-extent size, the databaseserver allocates the largest available contiguous block of disk space.

If the next extent is physically contiguous to an existing extent for the sametblspace, the disk space is treated as a single extent.

Some other tblspace extent

16th extent 17th extent size is doubled.

3rd extent 4th extent

3rd extent

3rd extent

Next extent allocation


Structure and Storage of a Dbspace Page

After disk space is allocated to a tblspace as part of an extent, the spaceremains dedicated to that tblspace even if the data contained in it is deleted.For alternative methods of reclaiming this empty disk space, see your Perfor-mance Guide.

Structure and Storage of a Dbspace PageThe basic unit of database server I/O is a page. Page size might vary amongcomputers.

In Extended Parallel Server, configure the page size through the PAGESIZEconfiguration parameter. For more information, see “PAGESIZE” onpage 1-112. ♦

In Dynamic Server, the page size depends on the operating system. ♦

Rows in Nonfragmented Tables

The database server can store rows that are longer than a page. The databaseserver also supports the VARCHAR data type, which results in rows ofvarying length. As a result, rows do not conform to a single format.

Rows within a table are not necessarily the same length if the table containsone or more columns of type VARCHAR. In addition, the length of a row insuch a table might change when an end user modifies data contained in theVARCHAR column.

The length of a row can be greater than a page.

TEXT and BYTE data is not stored within the data row. Instead, the data rowcontains a 56-byte descriptor that points to the location of the data. Thedescriptor can point to a dbspace page.

The descriptor can point to a blobspace blobpage. If you are using the OpticalSubsystem, the descriptor can also point to an optical-storage subsystem. ♦

For instructions about how to estimate the length of fixed-length andvariable-length data rows, see your Performance Guide.

XPS

IDS

IDS



Definition of Rowid

Informix uses two different types of rowids to identify data in tables:

■ Serial rowid

These rowids are fields in a table and are assigned to tables createdwith the WITH ROWID option.

■ Internal rowid

The database server identifies each data row in a table with a uniqueinternal rowid. This rowid identifies the location of the row withinthe dbspace. To obtain the internal rowids for a table, use theoncheck -pD option. For more information, see “Checking Pageswith -cd and -cD” on page 3-15.

In a nonfragmented table, the term rowid refers to a unique 4-byte integer thatdefines the physical location of the row in the table. The page that containsthe first byte of the data row is the page that is specified by the rowid. Thispage is called the data row home page.

Fragmented tables can also have rowids, but they are implemented in adifferent way. For more information on this topic, see “Rows in FragmentedTables” on page 7-24.

Use of Rowids

Every data row in a nonfragmented table is uniquely identified by anunchanging rowid. When you create an index for a nonfragmented table, therowid is stored in the index pages associated with the table to which the datarow belongs. When the database server requires a data row, it searches theindex to find the key value and uses the corresponding rowid to locate therequested row. If the table is not indexed, the database server might sequen-tially read all the rows in the table.

Eventually, a row might outgrow its original storage location. If this occurs,a forward pointer to the new location of the data row is left at the positiondefined by the rowid. The forward pointer is itself a rowid that defines thepage and the location on the page where the data row is now stored.



Rows in Fragmented Tables

Unlike rows in a nonfragmented table, the database server does not assign arowid to rows in fragmented tables. If you want to access data by rowid, youmust explicitly create a rowid column as described in your Performance Guide.If user applications attempt to reference a rowid in a fragmented table thatdoes not contain a rowid that you explicitly created, the database serverreturns an appropriate error code to the application.

Access to Data in Fragmented Tables with Rowid

From the viewpoint of an application, the functionality of a rowid column ina fragmented table is identical to the rowid of a nonfragmented table.However, unlike the rowid of a nonfragmented table, the database serveruses an index to map the rowid to a physical location.

When the database server accesses a row in a fragmented table using therowid column, it uses this index to look up the physical address of the rowbefore it attempts to access the row. For a nonfragmented table, the databaseserver uses direct physical access without an index lookup. As a conse-quence, accessing a row in a fragmented table using rowid takes slightlylonger than accessing a row using rowid in a nonfragmented table. Youshould also expect a small performance impact on the processing of insertsand deletes due to the cost of maintaining the rowid index for fragmentedtables.

Primary-key access can lead to significantly improved performance in manysituations, particularly when access is in parallel.

Recommendations on Use of Rowid

Informix recommends that application developers use primary keys as amethod of access rather than rowids. Because primary keys are defined in theANSI specification of SQL, using them to access data makes your applicationsmore portable.

For a complete description on how to define and use primary keys to accessdata, see the Informix Guide to SQL: Reference and the Informix Guide to SQL:Tutorial.



Data-Row Format and Storage

The variable length of a data row has the following consequences for rowstorage:

■ A page might contain one or more whole rows.

■ A page might contain portions of one or more rows.

■ A page might contain a combination of whole rows and partial rows.

■ An updated row might increase in size and become too long to returnto its original storage location in a row.

The following paragraphs describe the guidelines that the database serverfollows during data storage.

Storage of Row

To minimize retrieval time, rows are not broken across page boundariesunnecessarily. Rows that are shorter than a page are always stored as wholerows. A page is considered full when the count of free bytes is less than thenumber of bytes needed to store a row of maximum size.

Location of Rows

When the database server receives a row that is longer than a page, the rowis stored in as many whole pages as required. The database server then storesthe trailing portion in less than a full page.

The page that contains the first byte of the row is the row home page. Thenumber of the home page becomes the logical page number contained in therowid. Each full page that follows the home page is referred to as a big-remainder page. If the trailing portion of the row is less than a full page, it isstored on a remainder page.

After the database server creates a remainder page to accommodate a longrow, it can use the remaining space in this page to store other rows.


Structure of Fragmented Tables

Figure 7-11 illustrates the concepts of home page, big-remainder page, andremainder page.

Page Compression

Over time, the free space on a page can become fragmented. When thedatabase server attempts to store data, it first checks row length against thenumber of free bytes on a page to determine if the row fits. If adequate spaceis available, the database server checks if the page contains adequatecontiguous free space to hold the row (or row portion). If the free space is notcontiguous, the database server calls for page compression.

Structure of Fragmented TablesAlthough table fragmentation is transparent to applications, as databaseserver administrator you should be aware of how the database serverallocates disk space for table fragments and how the database serveridentifies rows in those fragments.

Figure 7-11Remainder PagesData row represented in whole-page-sized segments

Remainder page

Big-remainder page

Big-remainder page

Home page


Structure of B-Tree Index Pages

Each table fragment has its own tblspace with a unique tblspace_id orfragment_id. Figure 7-12 shows the disk allocation for a fragmented table.

Attached and Detached Indexes

With an attached index, the index and data are fragmented in the same way.You can decide whether to store the index pages with the corresponding datapages in the same dbspace or store them in separate dbspaces. For infor-mation on choosing a fragmentation strategy, see the Performance Guide.

Structure of B-Tree Index PagesThis section provides general information about the structure of B-tree indexpages. It is designed as an overview for the interested reader. For more infor-mation on B-tree indexes, see “Related Reading” on page 21.

Figure 7-12Disk Structures for a

Fragmented Table

Dbspace 1

Fragments of afragmented table

Tblspace

Dbspace 2

Extent 1 Extent 2

Tblspace

Extent 1 Extent 2



Definition of B-Tree Terms

The database server uses a B-tree structure to organize index information.Figure 7-13 shows that a fully developed B-tree index is composed of thefollowing three different types of index pages or nodes:

■ One root node

A root node contains node pointers to branch nodes.

■ Two or more branch nodes

A branch node contains pointers to leaf nodes or other branch nodes.

■ Many leaf nodes

A leaf node contains index items and horizontal pointers to other leafnodes.

Each node serves a different function. The following sections describe eachnode and the role that it plays in indexing.

Figure 7-13Full B-Tree Structure

Rootnode

Branchnodes

Leafnodes

Index item



Index Items

The fundamental unit of an index is the index item. An index item contains akey value that represents the value of the indexed column for a particularrow. An index item also contains rowid information that the database serveruses to locate the row in a data page.

Nodes

A node is an index page that stores a group of index items. For the three typesof nodes, see “Definition of B-Tree Terms” on page 7-28.

Logical Storage of Indexes

This section presents an overview of how the database server creates and fillsan index.

Creation of Root and Leaf Nodes

When you create an index for an empty table, the database server allocates asingle index page. This page represents the root node and remains emptyuntil you insert data in the table.

At first, the root node functions in the same way as a leaf node. For each rowthat you insert into the table, the database server creates and inserts an indexitem in the root node. Figure 7-14 illustrates how a root node appears beforeit fills.

Figure 7-14Root NodeRoot node 1

AlbertsonBaxterBeattyCurrieKeyesLawsonMuellerWallach

rowid informationrowid informationrowid informationrowid informationrowid informationrowid informationrowid informationrowid information



When the root node becomes full of index items, the database server splits theroot node by performing the following steps:

■ Creates two leaf nodes

■ Moves approximately half of the root-node entries to each of thenewly created leaf nodes

■ Puts pointers to leaf nodes in the root node

As you add new rows to a table, the database server adds index items to theleaf nodes. When a leaf node fills, the database server creates a new leaf node,moves part of the contents of the full index node to the new node, and addsa node pointer to the new leaf node in the root node.

For example, suppose that leaf node 3 in Figure 7-15 becomes full. When thissituation occurs, the database server adds yet another leaf node. Thedatabase server moves part of the records from leaf node 3 to the new leafnode, as Figure 7-15 shows.

Creation of Branch Nodes

Eventually, as you add rows to the table, the database server fills the rootnode with node pointers to all the existing leaf nodes. When the databaseserver splits yet another leaf node, and the root node has no room for anadditional node pointer, the following process occurs.

Figure 7-15Leaf Node 4 Created After Leaf Node 3 Fills

Root node 1

Leaf node 3Leaf node 2 Leaf node 4



The database server splits the root node and divides its contents among twonewly created branch nodes. As index items are added, more and more leafnodes are split, causing the database server to add more branch nodes.Eventually, the root node fills with pointers to these branch nodes. When thissituation occurs, the database server splits the root node again. The databaseserver then creates yet another branch level between the root node and thelower branch level. This process results in a four-level tree, with one rootnode, two branch levels, and one leaf level. The B-tree structure can continueto grow in this way to a maximum of 20 levels.

Branch nodes can point either to other branch nodes below them (for largeindexes of four levels or more) or to leaf nodes. In Figure 7-16, the branchnode points to leaf nodes only. The first item in the left branch node containsthe same key value as the largest item in the leftmost leaf node and a nodepointer to it. The second item contains the largest item in the next leaf nodeand a node pointer to it. The third item in the branch node contains only apointer to the next higher leaf node. Depending on the index growth, thisthird item can contain the actual key value in addition to the pointer at a laterpoint during the lifespan of the index.

Figure 7-16Typical Contents of

a Branch Node

Leaf node 5

Branch node 2

Higgins

Grant

Leaf node 3

Leaf node 4

pointer to leaf nodeLawson

rowid informationHanlon rowid information

Higgins rowid informationHenry rowid information

Jaeger rowid informationJewell rowid information

Lawson rowid informationKeyes rowid information

Miller rowid informationNeelie rowid information

pointer to leaf nodepointer to leaf node



Duplicate Key Values

Duplicate key values occur when the value of an indexed column is identicalfor multiple rows. For example, suppose that the third and fourth leaf nodesof a B-tree structure contain the key value Smith. Suppose further that thisvalue is duplicated six times, as Figure 7-17 illustrates.

The first item on the third leaf page contains the duplicate key value, Smith,and the rowid information for the first physical row in the table that containsthe duplicate key value. To conserve space, the second item does not repeatthe key value Smith but instead contains just the rowid information. Thisprocess continues throughout the page; no other key values are on the leaf,only rowid information.

The first item on the fourth leaf page again contains the duplicated key valueand rowid information. Subsequent items contain only rowid information.

Now consider the branch node. The third item in the branch node containsthe same key value and rowid as the largest item in the third leaf node and anode pointer to it. The fourth item would contain only a node pointer to thefourth leaf node, thus saving the space of an additional duplicate key value.

Key-Value Locking

To increase concurrency, the database server supports key-value locking in theB-tree index. Key-value locking locks only the value of the key instead of thephysical location in the B-tree index.

Figure 7-17Leaf Nodes 3 and 4Left leaf node 3

Right leaf node 4

Smith rowid informationrowid informationrowid informationrowid information

Smith rowid informationrowid information

Branch node 2

Higgins pointer to leaf nodeLawsonSmith pointer to leaf node

pointer to leaf node



One of the most important uses for key-value locking is to assure that aunique key remains unique through the end of the transaction that deleted it.Without this protection mechanism, user A might delete a unique key withina transaction, and user B might insert a row with the same key before thetransaction commits. This scenario makes rollback by user A impossible.Key-value locking prevents user B from inserting the row until the end ofuser A’s transaction.

Adjacent Key Locking

With Repeatable Read isolation level, the database server is required toprotect the read set. The read set consists of the rows that meet the filters in theWHERE clause of the query. To guarantee that the rows do not change, thedatabase server obtains a lock on the index item that is adjacent to the right-most item of the read set.

Freed Index Pages

When the database server physically removes an index item from a node andfrees an index page, the freed page is reused.

Filling Indexes

When you create an index, you can specify how densely or sparsely filled youwant the index. The index fill factor is a percentage of each index page thatwill be filled during the index build. Use the FILLFACTOR option of theCREATE INDEX statement or the FILLFACTOR configuration parameter to setthe fill factor. This option is particularly useful for indexes that you do notexpect to grow after they are built. For additional information about theFILLFACTOR option of the CREATE INDEX statement, see the Informix Guide toSQL: Syntax.

Calculating the Length of Index Items

For data types other than VARCHAR, the length of an index item is calculatedby adding the length of the key value plus 5 bytes for each rowid informationassociated with the key value.



The key values in an index are typically of fixed length. If an index holds thevalue of one or more columns of the VARCHAR data type, the length of thekey value is at least the sum of the length-plus-one of each VARCHAR valuein the key.

In Extended Parallel Server, the maximum length of a key value is 255 bytes.The combined size of VARCHAR columns that make up a key must be lessthan 255, minus an additional byte for each VARCHAR column. For example,the key length of the index that the database server builds for the followingstatements equals 255, or ((1+155) + (1+100)):

CREATE TABLE T1 (c1 varchar(155, 10), c2 varchar(100, 10));CREATE INDEX I1 on T1(c1, c2);

♦

In Dynamic Server, the maximum length of a key value is 390 bytes. Thecombined size of VARCHAR columns that make up a key must be less than390, minus an additional byte for each VARCHAR column. For example, thekey length of the index that the database server builds for the following state-ments equals 390, or ((1+255) + (1+133)):

CREATE TABLE T1 (c1 varchar(255, 10), c2 varchar(133, 10));CREATE INDEX I1 on T1(c1, c2);

♦

Functional Indexes

A functional index is one in which all keys derive from the results of a function.If you have a column of pictures, for example, and a function to identify thepredominant color, you can create an index on the result of the function. Suchan index would enable you to quickly retrieve all pictures having the samepredominant color, without re-executing the function.

A functional index uses the same B-tree structure as any other B-tree index.The only difference is that the determining function is applied during aninsert or an update whenever the column that is the argument to the functionchanges. For more information on the nature of functional indexes, refer toyour Performance Guide.

To create a functional index, use the CREATE FUNCTION and CREATE INDEXstatements. For more information on these statements, refer to the InformixGuide to SQL: Syntax.

XPS

IDS

IDS


Structure of Bitmap Indexes

Structure of Bitmap IndexesA bitmap index has exactly the same structure as a B-tree index except for theformat of the leaf nodes that have duplicate keys. The traditional B-tree leafpage stores the key value and a list of duplicates (see Figure 7-17). A bitmapindex instead stores a bitmap in which each bit represents one row in thetblspace.

Without any compression, a bitmap stored in this fashion could have amaximum of 232 (or approximately 4 gigabytes) possible values, which is toolarge to be of any practical use in an efficient indexing scheme. To reduce thesize of this value, the database server compresses the bitmap.

Structure of R-Tree Index PagesAn index structure that relies on one-dimensional ordering of key valuesdoes not work for spatial data; for example, two dimensional geometricshapes such as circles, squares, and triangles. Efficient retrieval of spatialdata, such as the data used in geographic information systems (GIS) andcomputer-aided design (CAD) applications, requires an access method thathandles multidimensional data. The database server implements an R-treeindex to access spatial data efficiently.

For information about the structure of index pages, refer to the Informix R-Tree Index User’s Guide.

XPS

IDS


Storage of Simple Large Objects

Storage of Simple Large ObjectsThis section explains the structures and storage techniques that the databaseserver uses to store simple large objects (TEXT or BYTE data).

Structure of a BlobspaceWhen you create a blobspace, you can specify the effective size of the datapages, which are called blobpages. The blobpage size for the blobspace isspecified when the blobspace is created. Blobpage size must be a multiple ofpage size. (For information on determining database server page size, see thechapter on managing disk space in the Administrator’s Guide.) All blobpageswithin a blobspace are the same size, but the size of the blobpage can varybetween blobspaces. Blobpage size can be greater than the page size becausedata stored in a blobspace is never written to the page-sized buffers in sharedmemory.

The advantage of customizing the blobpage size is storage efficiency. Withina blobspace, TEXT and BYTE data is stored in one or more blobpages, butsimple large objects do not share blobpages. Storage is most efficient whenthe TEXT or BYTE data is equal to or slightly smaller than the blobpage size.

The blobspace free-map pages and bit-map pages are the size specified as adatabase server page, which enables them to be read into shared memoryand to be logged.

When the blobspace is first created, it contains the following structures:

■ Blobspace free-map pages

■ The blobspace bit map that tracks the free-map pages

■ Unused blobpages

IDS


Structure of a Dbspace Blobpage

Structure of a Dbspace BlobpageTEXT or BYTE data that is stored in the dbspace is stored in a blobpage. Thestructure of a dbspace blobpage is similar to the structure of a dbspace datapage. The only difference is an extra 12 bytes that can be stored along withthe TEXT or BYTE data in the data area.

Simple large objects can share dbspace blobpages if more than one simplelarge object can fit on a single page, or if more than one trailing portion of asimple large object can fit on a single page.

For a discussion of how to estimate the number of dbspace blobpages neededfor a specific table, see your Performance Guide.

Each segment of TEXT or BYTE data stored in a dbspace page might bepreceded by up to 12 bytes of information that does not appear on any otherdbspace page. These extra bytes are overhead.

Simple-Large-Object Storage and the DescriptorData rows that include TEXT or BYTE data do not include the data in the rowitself. Instead, the data row contains a 56-byte descriptor with a forwardpointer (rowid) to the location where the first segment of data is stored. Thedescriptor can point to one of the following items:

■ A page (if the data is stored in a dbspace)

■ A blobpage (if the data is stored in a blobspace)

■ An optical platter (if you are using the Optical Subsystem) ♦

Creation of Simple Large Objects

When a row that contains TEXT or BYTE data is to be inserted, the simple largeobjects are created first. After the simple large objects are written to disk (oroptical medium), the row is updated with the descriptor and inserted.

IDS


Blobspace Page Types

Deletion or Insertion of Simple Large Objects

The database server cannot modify simple large objects. It can only insert ordelete them. Deleting a simple large object means that the database serverfrees the space consumed by the deleted object for reuse.

When TEXT or BYTE data is updated, a new simple large object is created, andthe data row is updated with the new blob descriptor. The old image of therow contains the descriptor that points to the obsolete value for the simplelarge object. The space consumed by the obsolete simple large object is freedfor reuse after the update is committed. Simple large objects are automati-cally deleted if the rows that contain their blob descriptors are deleted.(Blobpages that stored a deleted simple large object are not available for reuseuntil the logical log that contains the original INSERT record for the deletedsimple large object is backed up. For more information, see backing uplogical-log files to free blobpages in the chapter on what is the logical log inthe Administrator’s Guide.)

Size Limits for Simple Large Objects

The largest simple large object that the blob descriptor can accommodate is(231 - 1), or about 2 gigabytes.

Blobspace Page TypesEvery blobspace chunk contains three types of pages:

■ A blobspace free-map page

■ A bit-map page

■ Blobpages

Blobspace Free-Map Page

The blobspace free-map page identifies unused blobpages so that thedatabase server can allocate them as part of simple-large-object creation.When a blobpage is allocated, the free-map entry for that page is updated. Allentries for a single simple large object are linked.

IDS


Structure of a Blobspace Blobpage

A blobspace free-map page is the size of one database server page. Each entryon a free-map page is 8 bytes, stored as two 32-bit words, as follows:

■ The first bit in the first word specifies whether the blobpage is free orused.

■ The next 31 bits in the first word identify the logical-log file that wascurrent when this blobpage was written. (This information is neededfor logging TEXT or BYTE data.)

■ The second word contains the tblspace number associated with thesimple large object stored on this page.

The number of entries that can fit on a free-map page depends on the pagesize of your computer. The number of free-map pages in a blobspace chunkdepends on the number of blobpages in the chunk.

Blobspace Bit-Map Page

The blobspace bit-map page tracks the fullness and number of blobspacefree-map pages in the chunk. Each blobspace bit-map page is capable oftracking a quantity of free-map pages that represent more than 4,000,000blobpages. Each blobspace bit-map page is the size of one page.

Blobpage

The blobpage contains the TEXT or BYTE data. Blobpage size is specified bythe database server administrator who creates the blobspace. Blobpage sizeis specified as a multiple of the page size.

Structure of a Blobspace BlobpageThe storage strategy used to store simple large objects in a blobspace differsfrom the dbspace storage strategy. The database server does not combinewhole simple large objects or portions of a simple large object on a singleblobspace blobpage. For example, if blobspace blobpages are 24 kilobyteseach, a simple large object that is 26 kilobytes is stored on two 24-kilobytepages. The extra 22 kilobytes of space remains unused.

IDS


Sbspace Structure

Blobpage Structure

The structure of a blobpage includes a blobpage header, the TEXT or BYTEdata, and a page-ending time stamp. The blobpage header includes, amongother information, the page-header time stamp and the blob time stampassociated with the forward pointer in the data row. If a simple large object isstored on more than one blobpage, a forward pointer to the next blobpageand another blob time stamp are also included in the blobpage header.

Sbspace StructureAn sbspace is similar in concept to a blobspace except that it holds smartlarge objects.

When an sbspace is created in a database, it contains the following structures:

■ Sbspace chunk header pages

■ An sbspace metadata area

■ A user-data area

For best performance, we recommend that the metadata area be located inthe middle of the sbspace. Figure 7-18 illustrates the chunk structure of ansbspace as it appears immediately after the sbspace is created.

Figure 7-18A Single Sbspace

Chunk

IDS

A single sbspace chunk

Chunk one

Chunk header pages

Metadata

User data

User data

Pages 0 through 52compose the chunk

header.


Sbspace Structure

Because the chunk in Figure 7-18 is the first in the sbspace, its chunk headercontains additional information not found in the chunk header of chunksadded to the sbspace subsequently. The chunk header pages for chunk onecontain information that tracks various information about chunk one and forall chunks added to the sbspace thereafter. Figure 7-19 illustrates the chunkheader structure for the first chunk in an sbspace.

The chunk header pages of the first chunk in a sbspace, along with allmetadata areas in all additional chunks, are managed as an entirely separatedbspace within the sbspace. The chunk free-extent list tracks extents of theassociated chunk only. The tblspace tblspace bitmap is the standard bitmapof free pages within the tblspace tblspace. The tblspace tblspace header is therequired header for the tblspace tblspace. The tblspace tblspace pages (thatis, the tblspace header pages) are stored in pages five through fifty-two. Ifmore space is required, it is allocated from chunk one metadata. When youadd additional chunks to an sbspace, the chunk header for the additionalchunks includes only the two reserved pages and the chunk free-extent list.

Figure 7-19Chunk Header

Structure for theFirst Chunk in a

Sbspace

Chunk header structure for the first chunk in an sbspace

Chunk one

Chunk header pages

Metadata

User data

User data

Chunk header pages

Reserved page

Reserved page

chunk free-extent list

Tblspace tblspace bitmap

Tblspace tblspace header

Tblspace header pages


Structure of the Metadata Area

Structure of the Metadata AreaAs with the chunk header pages, four areas are exclusive to the first chunk ina sbspace: the sbspace descriptor tblspace, the chunk adjunct tblspace, andthe level-1 and level-2 archive tblspaces. The tblspace header section containsa tblspace header for each of these tblspaces (notably excluding the tblspacetblspace). Figure 7-20 shows the layout of the metadata in the single-chunksbspace.

When you specify the sbspace name in the oncheck -ps option, you candisplay the number of pages allocated and used for each tblspace in themetadata area.

Figure 7-20Structure of the

Metadata Area for aSingle-Chunk

Sbspace

Structure of the metadata area for a single-chunk sbspace

Chunk one

Chunk header pages

Metadata

User data

User data

Metadata area

Sbspace descriptor tblspace

Chunk adjunct tblspace

Level-1 archive tblspace

Level-2 archive tblspace

Chunk one LO header tblspace

Chunk one user-data free-list tblspace


Sbpage Structure

Sbpage StructureEach sbpage is composed of three elements: an sbpage header, the actual userdata itself, and an sbpage trailer. Figure 7-21 shows the structure of ansbpage.

The sbpage header consists of the standard page header. The sbpage trailer isused to detect an incomplete write on the page and to detect page corruption.

Figure 7-21Sbpage StructureSbpage structure

Chunk one

Sbpage

Chunk header pages

Metadata

User data

User data

User data

Sbpage trailer

Sbpage header


Multiple Chunk Sbspace

Multiple Chunk SbspaceThe following figure illustrates a possible configuration for a three-chunksbspace. In this example, chunk two contains no metadata of its own.Metadata information for chunk two is stored in the metadata area of chunkone.

The user-data areas in chunk one of the example are actually optional.Chunk one could contain metadata for all other chunks in the sbspace.

Figure 7-22Multiple-Chunk

Sbspace StructureMultiple-chunk sbspace structure

Chunk one Chunk two Chunk three

Chunk header pages Chunk header pagesChunk header pages

Metadata for chunks oneand two

Metadata for chunk three

User data

User data

User data

User data

User data

Sbspace one


Database and Table Creation: What Happens on Disk

Database and Table Creation: What Happenson DiskThis section explains how the database server stores data related to thecreation of a database or table and allocates the disk structures that arenecessary to store your data.

Database CreationAfter the root dbspace exists, users can create a database. The paragraphsthat follow describe the major events that occur on disk when the databaseserver adds a new database.

Disk-Space Allocation for System Catalog Tables

The database server searches the chunk free-list pages in the dbspace,looking for free space in which to create the system catalog tables. For eachsystem catalog table, in turn, the database server allocates eight contiguouspages, the size of the initial extent of each system catalog table. The tables arecreated individually and do not necessarily reside next to each other in thedbspace. They can be located in different chunks. As adequate space is foundfor the initial extent of each table, the pages are allocated, and the associatedchunk free-list page is updated.


Table Creation

Tracking of System Catalog Tables

The database server tracks newly created databases in the database tblspace,which resides in the root dbspace. An entry describing the database is addedto the database tblspace in the root dbspace. (See “Structure of the DatabaseTblspace” on page 7-12.) For each system catalog table, the database serveradds a one-page entry to the tblspace tblspace in the dbspace where thedatabase was built. (See “Structure of the Tblspace Tblspace” on page 7-9.)Figure 7-23 illustrates the relationship between the database tblspace entryand the location of the systables system catalog table for the database.

For instructions on how to list your databases after you create them, seemonitoring databases in the chapter on managing database-logging status inthe Administrator’s Guide.

Table CreationAfter the root dbspace exists, and a database has been created, users with thenecessary SQL privileges can create a database table. When users create atable, the database server allocates disk space for the table in units calledextents (see what is an extent in the chapter on where data is stored in theAdministrator’s Guide). The paragraphs that follow describe the major eventsthat occur when the database server creates a table and allocates the initialextent of disk space.

Figure 7-23New DatabasesAn entry in the database tblspace (located

in the root dbspace) points to the databasesystables system catalog table.

Database tblspace

Tblspaces

Dbspace

systables


Table Creation

Disk-Space Allocation

The database server searches the chunk free-list pages in the dbspace forcontiguous free space equal to the initial extent size for the table. Whenadequate space is found, the pages are allocated, and the associated chunkfree-list page is updated.

If the database server cannot find adequate contiguous space anywhere inthe dbspace, it allocates to the table the largest available amount ofcontiguous space. No error message is returned if an allocation is possible,even when the amount of space allocated is less than the requested amount.If the minimum extent size cannot be allocated, an error is returned. (Extentscannot span two chunks.)

Entry in the Tblspace Tblspace

The database server adds a one-page entry for this table to the tblspacetblspace in this dbspace. The tblspace number assigned to this table isderived from the logical page number in the tblspace tblspace where the tableis described. See “Tblspace Numbers” on page 7-10.

The tblspace number indicates the dbspace where the tblspace is located.Tblspace extents can be located in any of the dbspace chunks.

If you must know exactly where the tblspace extents are located, execute thefollowing command for a listing of the dbspace layout by chunk:

■ onutil CHECK SPACE DISPLAY ♦■ oncheck -pe ♦

Entries in the System Catalog Tables

The table itself is fully described in entries stored in the system catalog tablesfor the database. Each table is assigned a table identification number or tabid.The tabid value of the first user-defined table in a database is always 100. Fora complete discussion of the system catalog, see the Informix Guide to SQL:Reference.

A table can be located in a dbspace that is different than the dbspace thatcontains the database. The tblspace itself is the sum of allocated extents, nota single, contiguous allocation of space. The database server tracks tblspacesindependently of the database.

XPS

IDS


Table Creation

Creation of a Temporary Table

The tasks involved in creating temporary tables are similar to the tasks thatthe database server performs when it adds a new permanent table. The keydifference is that temporary tables do not receive an entry in the systemcatalog for the database. For more information, see what is a temporary tablein the chapter on where data is stored in the Administrator’s Guide.


8Chapter

Loading with External Tablesfor Extended Parallel Server

In This Chapter . . . . . . . . . . . . . . . . . . . . 8-3

Getting an Overview of High-Performance Loading . . . . . . . 8-3Loading and UnLoading Data. . . . . . . . . . . . . . 8-4

Using the Reject File and Violations Table to HandleLoad Errors . . . . . . . . . . . . . . . . 8-4

Setting Up Loading and Unloading Tasks . . . . . . . . 8-5Data-Format Conversion . . . . . . . . . . . . . . . 8-8Data Load . . . . . . . . . . . . . . . . . . . . 8-8Data Unload . . . . . . . . . . . . . . . . . . . . 8-8File Types and Formats . . . . . . . . . . . . . . . . 8-9Loading Modes . . . . . . . . . . . . . . . . . . . 8-9Optimization . . . . . . . . . . . . . . . . . . . 8-10

Starting to Load and Unload Data. . . . . . . . . . . . . . 8-12Specifying the External Table . . . . . . . . . . . . . . 8-12Loading Data in Express Mode . . . . . . . . . . . . . 8-13Loading Data in Deluxe Mode . . . . . . . . . . . . . 8-15

Loading, Unloading, and Reorganizing Data . . . . . . . . . . 8-16Loading from a Delimited File with Unchanged Columns . . . . 8-17Unloading to a Delimited File . . . . . . . . . . . . . . 8-17Mapping Columns to Other Columns . . . . . . . . . . . 8-18Unloading to an Informix Data File . . . . . . . . . . . . 8-19Loading Between Tables That Have the Same Schema . . . . . 8-19Loading from a Fixed-ASCII File . . . . . . . . . . . . . 8-20Unloading to a Fixed-ASCII File . . . . . . . . . . . . . 8-21Loading from an IBM Fixed-EBCDIC File . . . . . . . . . . 8-22

8-2 Infor

Loading from and Unloading to a Named Pipe . . . . . . . . 8-22Loading with Named Pipes . . . . . . . . . . . . . 8-23Using FIFO Virtual Processors . . . . . . . . . . . . 8-24Unloading with Named Pipes . . . . . . . . . . . . 8-25

Adding an End-of-Line Character to a Fixed-ASCII File . . . . . 8-26Using a Program or Script . . . . . . . . . . . . . . 8-26Adding a Newline Field in a SELECT Statement . . . . . . 8-27

Loading Values into Serial Columns. . . . . . . . . . . . 8-28Loading Data Warehousing Tables . . . . . . . . . . . . 8-28

Loading Initially . . . . . . . . . . . . . . . . . 8-28Refreshing Periodically . . . . . . . . . . . . . . 8-29Refreshing Frequently or Continuously . . . . . . . . . 8-30Initial Loading of OLTP Data from Other Database Servers . . 8-31

Loading Simple Large Objects . . . . . . . . . . . . . . . 8-32Formats for Simple Large Objects . . . . . . . . . . . . 8-32

Using Informix Internal Format . . . . . . . . . . . . 8-33Using Delimited Format . . . . . . . . . . . . . . 8-34

Loading Simple Large Objects from an External Table . . . . . 8-38Using Pipe Staging. . . . . . . . . . . . . . . . . . 8-40

Using Parallel Execution . . . . . . . . . . . . . . 8-40Using Temporary Space for Pipe Staging of

Simple Large Objects . . . . . . . . . . . . . 8-41

Monitoring the Load or Unload Operations . . . . . . . . . . 8-44Monitoring Frequent Loads and Unloads . . . . . . . . . . 8-44Monitoring FIFO Virtual Processors . . . . . . . . . . . . 8-45Monitoring Loads and Unloads of Data . . . . . . . . . . 8-46

Using SET EXPLAIN ON Output . . . . . . . . . . . 8-46Using onstat to Monitor Pipe Staging . . . . . . . . . . 8-48

Recovering After Errors . . . . . . . . . . . . . . . . . 8-49Reject Files . . . . . . . . . . . . . . . . . . . . 8-49Error Messages . . . . . . . . . . . . . . . . . . . 8-51Recoverability of Table Types . . . . . . . . . . . . . . 8-52


In This ChapterThis chapter describes how Extended Parallel Server performs high-performance loading with external tables. An external table is a data file thatyou use to load and unload data. The data file is not managed by an Informixdatabase server. The definition of the external table includes data-formattingtype, external data description fields, and global parameters.

This chapter describes the following tasks:

■ Getting an overview of high-performance loading

■ Starting to load and unload data

■ Loading, unloading, and reorganizing data

■ Loading simple large objects

■ Monitoring the load or unload operations

■ Recovering after errors

Getting an Overview of High-Performance LoadingThe database server provides high-performance parallel loading andunloading of tables. To set up high-performance loading, you issue a seriesof SQL statements that perform the following functions:

■ Partition load activity over available resources to provide high-performance parallel loading

■ Transfer operational data efficiently from a mainframe to a datawarehouse

■ Transfer data files across platforms in Informix internal data format

■ Use the database server to convert data between delimited ASCII,fixed-ASCII, EBCDIC, and Informix internal (raw) representation

XPS

Loading with External Tables for Extended Parallel Server 8-3

Loading and UnLoading Data

■ Use SQL INSERT and SELECT statements to specify the mapping ofdata to new columns in a database table

■ Provide parallel standard INSERT operations so that data can beloaded without dropping indexes

■ Use named pipes to support loading data to and unloading datafrom storage devices, including tape drives and direct networkconnections to mainframes

■ Maintain a record of load and unload statistics during the run

■ Check constraints

■ Perform express (high-speed) and deluxe (data-checking) transfers

The database server can use parallel SQL operators to distribute these taskseasily.

You can issue the SQL statements with DB-Access or embed them in anESQL/C program. ♦

Loading and UnLoading DataTo map external data to internal data, the database server views the externaldata as an external table. Treating the external data as a table provides apowerful method for moving data into or out of the database and for speci-fying transformations of the data.

When the database server runs a load task, it reads data from the externalsource and performs the conversion required to create the row and theninserts the row into the table. The database server writes errors to two places:

■ The reject file

■ The violations table

Using the Reject File and Violations Table to Handle Load Errors

If the data in the external table cannot be converted or violates checkconstraints, you can specify that the database server write the record to areject file, along with the reason for the failure. To do this, you specify theREJECTFILE keyword in the CREATE EXTERNAL TABLE statement. For moreinformation, see “Reject Files” on page 8-49.

DB

E/C



During a load, rows that violate unique or referential constraints are recordedin a violations table. During an insert, update, or delete operation, any type ofconstraint violation gets recorded in the violations table. The bad row is sentto the violations table, permitting the load to continue successfully. For infor-mation on starting a violations table, see the Informix Guide to SQL: Syntaxand “Loading Data in Deluxe Mode” on page 8-15.

Setting Up Loading and Unloading Tasks

To set up loading and unloading tasks, you issue a series of SQL statements:

■ CREATE EXTERNAL TABLE to describe the data file to load or unload

■ CREATE TABLE to define the table to load

■ INSERT...SELECT to load

A second method, which uses a SELECT...INTO EXTERNAL statement, is alsoavailable for unloading data to an external table. For more information aboutthese SQL statements and the violations table, see the Informix Guide to SQL:Syntax.

Figure 8-1 on page 8-7 shows the relationship of these SQL statements to theload process. The following steps outline the load process:

1. The CREATE EXTERNAL TABLE statement describes the location ofthe various external files, which can be on disk or come from a pipe(tape drive or direct network connection), and the format of theexternal data.

The following sample CREATE EXTERNAL TABLE statement showsthat the data files exist on coservers in the cogroup_cust cogroup,which consists of coservers 1 and 5:

CREATE EXTERNAL TABLE emp_ext( name CHAR(18) EXTERNAL CHAR(18),

hiredate DATE EXTERNAL CHAR(10),address VARCHAR(40) EXTERNAL CHAR(40),empno INTEGER EXTERNAL CHAR(6) )

USING (FORMAT 'FIXED',DATAFILES

("DISK:cogroup_cust:/work2/mydir/emp.fix"));



2. The CREATE TABLE statement defines the table to load.

The following sample CREATE TABLE statement defines thecustomer table in the cust_dbsl dbslice:

CREATE TABLE customer(cust_id integer,...)FRAGMENT BY HASH (cust_id)

IN cust_dbslc;

Figure 8-1 on page 8-7 shows that the cust_dbsl dbslice consists often dbspaces, with two dbspaces on each of the five coservers.

3. The INSERT...SELECT statement maps the movement of the externaldata from or to the database table.

The following sample INSERT statement loads the customer tablefrom the external table to the cust_dbsl dbslice:

INSERT INTO employee SELECT * FROM emp_ext

The INSERT...SELECT statement uses the multithreaded architectureof the database server to perform the load process in the followingsteps:

a. Execute multiple read operations from tapes, files, or pipes. Inthis example, coservers 1 and 5 contain data files. During theload process, the xlr (xload load reader) operators on coservers 1and 5 read each data file.

b. The Data Flow Manager ships the data from the xlr operators tothe xlc (xload load converter) operators on coservers 1 through 5.The xlc operators convert the data in parallel.

c. Load multiple fragments of the table in parallel. The load processhas a separate INSERT operator per fragment.



Figure 8-1Overview of Load Process

External files

INSERT

Client/serverconnections

cust_dbsl.5 cust_dbsl.10. . .

. . .

cust_dbsl.1 cust_dbsl.6 cust_dbsl.2 cust_dbsl.7

Coserver 2 Coserver 5Coserver 1

DB-Access

xlr xlr

External files (tape, pipe, disk)

cust_dbsl dbslice

1

2

3

1

2 2

3a

INSERT INSERT INSERT

3a

3c 3c 3c

xlc3b xlc3b xlc3b


Data-Format Conversion

Data-Format ConversionThe database server provides a number of different conversion mechanisms,which are performed within the database server and therefore providemaximum performance during the conversion task. The database serveroptimizes data conversion between ASCII and Informix data representations,and between EBCDIC and Informix data representation in both fixed anddelimited formats.

To perform customized conversions, you can create a filter program thatwrites converted data to a named pipe. The database server then reads itsinput from the named pipe in one of the common formats.

Data LoadTo load data, define the external data as an external table and then insert thedata into the internal database. For a detailed explanation, see “Specifyingthe External Table” on page 8-12.

Data UnloadTo unload data, create an external table and insert the data into it, or selectdata from an internal table into an external file.

To unload data in parallel, initiate a query that runs in parallel and writes itsoutput to multiple files. The unload job uses a round-robin technique toequalize the number of rows in the output files.

To direct the output to a specific external table, run a separate SELECTstatement for each coserver and use the LOCAL keyword for the source tableand specify only data files on that coserver.

If multiple data files reside on a coserver and a data file fills up its disk, theunload task redirects the data to the remaining data files on that coserver. Ifall of the data files on a single coserver fill up, the unloading task fails. Theredirection works only on a single coserver, not across coservers. No similarredirection capability exists for named pipes.


File Types and Formats

File Types and FormatsThe database server supports both disk and named-pipe external files.

The external data files can be in delimited ASCII and EBCDIC formats, fixed-ASCII and EBCDIC formats, IBM-format files, and Informix internal format.For simple large objects, which contain TEXT or BYTE data, the data file canbe in raw (Informix internal format) or delimited format. For more infor-mation, refer to “Formats for Simple Large Objects” on page 8-32.

Loading ModesThe database server performs express-mode loads and deluxe-mode loads.Mode selection is determined by the logging mode (table type) of the desti-nation table and the presence or absence of the DELUXE or EXPRESS keywordsin the USING clause of the CREATE EXTERNAL TABLE statement. You canperform express-mode loads only when the table is type RAW or OPERA-TIONAL and does not have any active indexes. The database server allowsconstraint checking for both load modes.

Express mode provides the highest performance during a load. For detailedprocedures on using express mode, refer to “Loading Data in Express Mode”on page 8-13.

Deluxe mode combines fast parallel loading with evaluation of indexes andunique constraints. Use deluxe mode in the following situations:

■ The cost of rebuilding an index is too high for the amount of data thatyou are loading.

■ You want to use the empty space from deleted rows in the table thatyou are loading.

For detailed procedures on using deluxe mode, refer to “Loading Data inDeluxe Mode” on page 8-15.


Optimization

OptimizationTo optimize performance and load balancing, the database server data-flowmanager partitions the conversion task into separate threads from the readand insert threads and then routes the conversions to coservers that haveavailable resources. Once the rows are converted, the data-flow managersends each row to the appropriate insert thread.

Figure 8-2 on page 8-11 shows how multiple data-flow managers and conver-sions tasks balance the load process across multiple coservers:

■ A user on coserver_x issues an INSERT statement via DB-Access toload a file from disk and convert its format.

■ The data-flow manager discovers that the source file resides on onedisk on coserver_x and two disks on coserver_z.

■ Readers (sometimes referred to as loader threads) on coserver_x andcoserver_z read the file in parallel through named pipes. Thedatabase server receives the data through a named pipe.

■ The data-flow manager uses a round-robin scheme to distribute thedata to all coservers.

■ Converter threads (one per CPU VP) on each coserver perform anyrequired data reformatting and pass rows of data back to the data-flow manager.

■ The data-flow manager buffers and partitions the data among thecoservers that have disks with dbspaces allocated to the table(disk_y5 and disk_z2).

■ Insert threads place the data on disk.


Optimization

Figure 8-2The Load Process

dbspace_y5 dbspace_z2

coserver_z

Reader

Flow Mgr

Flow Mgr

Insert

coserver_x

Reader

Flow Mgr

Converter

Flow Mgr

coserver_y

Flow Mgr

Flow Mgr

Insert

dbaccess

ConverterConverterConverterConverter

disk_x1 disk_z1 disk_z3

External files External files

Dbspace or dbslice Dbspace or dbslice


Starting to Load and Unload Data

Starting to Load and Unload DataThis section discusses the fundamental procedures used to load and unloaddata:

■ Specifying the external table

■ Loading data in express mode

■ Loading data in deluxe mode

Specifying the External TableWhen you load data into the database, the FROM table portion of the SELECTclause refers to the external table that the CREATE EXTERNAL statementdefined. When you unload data to an external file, the SELECT clause controlsthe retrieval of the data from the database.

The external table is handled in the same way as a TEMP table. To create theexternal table definition, issue one of two statements:

■ CREATE EXTERNAL TABLE...USING

■ SELECT...INTO EXTERNAL table-name USING (when unloading)

Unlike a TEMP table, the external table has a definition that remains in thecatalog until it is dropped. Creating an external table allows you to save theexternal description of the data for reuse. This action is particularly helpfulwhen you unload a table into the Informix internal data representationbecause you can later use the same external table description to reload thatdata.

The external table definition contains all the information needed to define thedata in the external data file as follows:

■ The description of the fields in the external data

■ The DATAFILES clause

This clause specifies:

❑ whether the data file resides on disk or a named pipe.

❑ the coserver where the data file resides.

❑ the pathname of the file.


Loading Data in Express Mode

■ The FORMAT clause

This clause specifies the type of data formatting in the external datafile. The database server converts external data from several dataformats, including delimited ASCII and EBCDIC, fixed ASCII andEBCDIC, and Informix internal.

■ Any global parameters that affect the format of the data

When you describe the external table with a CREATE EXTERNAL TABLEstatement, you specify column mapping and use an INSERT INTO...SELECTstatement to perform the task. If you map the external table directly into theinternal database table in delimited format, you can use the CREATEEXTERNAL TABLE statement to define the columns and add the clauseSAMEAS internal-table instead of enumerating the columns explicitly.

Important: If you specify more than one INSERT INTO...SELECT statement to unloaddata, each subsequent INSERT statement overwrites the data file. Use absolute pathsfor data files.

Loading Data in Express ModeChoose express mode for fast loading of data. Express-mode loads use lightappends, which bypass the buffer pool. Light appends eliminate theoverhead associated with buffer management but do not log the data. Inexpress mode, the database server automatically locks the table exclusively.No other users can access the table.

If you do not use the DELUXE keyword, the database server uses expressmode unless the target table has indexes or is a STANDARD table.

Warning: Express mode loads are not allowed for STANDARD tables.

You can use express mode for any newly created table with no data if youdefine the table as type RAW or OPERATIONAL and do not define any indexesuntil after you load the data. Choose RAW tables if you do not want to uselogging. Choose OPERATIONAL tables if you want to use logging.

To prepare an existing table for express-mode load, drop all indexes, andmake sure the table type is either RAW or OPERATIONAL. For more infor-mation on table types, see “Recoverability of Table Types” on page 8-52.


Loading Data in Express Mode

Consider a table with the following schema:

TABLE employee (name CHAR(18),hiredate DATE,address CHAR(40),empno INTEGER);

To use express-mode load on an existing table

1. Alter the table type to allow fast loading.ALTER TABLE employee TYPE (OPERATIONAL);

2. Create the external table description.CREATE EXTERNAL TABLE emp_extSAMEAS employeeUSING (

FORMAT 'DELIMITED',DATAFILES

("DISK:cogroup_all:/work2/mydir/emp%c.dat"),REJECTFILE "/work2/mydir/emp%c.rej",EXPRESS);

3. Optionally begin a transaction.BEGIN WORK;

4. Perform the load.INSERT INTO employee SELECT * FROM emp_ext;

Because you specified express mode (step 2), the load stops with anerror message if the destination table contains indexes, constraints,or any other problem conditions.

5. Commit the transaction if you started it with BEGIN WORK.COMMIT WORK;

6. Perform a level-0 backup.

Because the data is not logged, you must perform a level-0 backup toallow data recovery. If a disk fails, you cannot recover the dataautomatically. You need to use the most recent level-0 backup files.

If the table type is RAW (nonlogging), omit the statements BEGIN WORK andCOMMIT WORK.

You can define check constraints on the external table to filter out bad rowseven if you load in express mode.


Loading Data in Deluxe Mode

Important: If you delete many rows from a table and then load many new rows intothe table in EXPRESS mode, the table grows in size because light appends append tothe end of the table and do not reuse the empty space inside the table. (If you do notspecify EXPRESS mode, the loader might choose DELUXE mode to fill in the space ifa table has many deleted rows.)

Loading Data in Deluxe ModeDeluxe-mode loads use regular single-row inserts, which add rows to a tablethat can contain indexes. The insert modifies each index for each row duringthe load. The insert also checks all constraints for each row. A deluxe-modeload allows you to keep the table unlocked during the load so other users cancontinue to use it.

You also can use deluxe mode on tables that do not contain indexes; forinstance, if you want to have complete recoverability or maintain access totables during a load.

To prepare a table for deluxe-mode load, create the internal table as typeOPERATIONAL or STANDARD, and create the external table with the optionalkeyword DELUXE.

To use deluxe-mode load on a table

1. If you want row locking, specify row locking in CREATE TABLE.(Page locking is the default.) If you want other users to be able toread the table during the load, set the lock mode to share.Otherwise, set it to exclusive.

BEGIN WORK;LOCK TABLE employee IN SHARE MODE;

2. Create the external table description.CREATE EXTERNAL TABLE emp_extSAMEAS employeeUSING (

DATAFILES("DISK:cogroup_all:/work2/mydir/emp%c.dat"),

REJECTFILE "/work2/mydir/emp%c.rej",DELUXE);


Loading, Unloading, and Reorganizing Data

3. Start the violations table if you want the load operation to completesuccessfully even if constraint violations exist.

Informix does not recommend that you start a violations table andthen set constraints to deferred. (You also cannot start a violationstable when constraints are already set to deferred.) For more infor-mation on the violations table and deferred constraints, see theInformix Guide to SQL: Syntax.

4. Perform the load.INSERT INTO employee SELECT * FROM emp_ext;

5. Commit the load, releasing row or page locks.COMMIT WORK;

Tip: Configure logical logs to allow maximum concurrent deluxe-load transactionsto complete.

Loading, Unloading, and Reorganizing DataThis section describes the following procedures:

■ Loading from a delimited file with unchanged columns

■ Unloading to a delimited file

■ Mapping columns to other columns

■ Unloading to an Informix data file

■ Loading between tables that have the same schema

■ Loading from a fixed-ASCII file

■ Unloading to a fixed-ASCII file

■ Loading from an IBM fixed-EBCDIC file

■ Using a named pipe to load or unload

■ Adding an end-of-line (EOL) character to a fixed-ASCII file

■ Loading values into serial columns

■ Loading simple large objects (TEXT or BYTE data)


Loading from a Delimited File with Unchanged Columns

Loading from a Delimited File with Unchanged ColumnsConsider loading a delimited ASCII text file into a table with the followingschema:

TABLE employee (name CHAR(18) NOT NULL,hiredate DATE DEFAULT TODAY,address VARCHAR(40),empno INTEGER);

The SQL statements to load into this table would be as follows:

CREATE EXTERNAL TABLE emp_extSAMEAS employeeUSING (

DATAFILES ("DISK:1:/work2/mydir/emp.dat"),REJECTFILE "/work2/mydir/emp.%c.rej");

INSERT INTO employee SELECT * FROM emp_ext;

The external table has the same name, type, default, and check constraint foreach column because the CREATE statement includes the SAMEAS keyword.The default format is delimited, so no format keyword is required.

Delimited files are ASCII by default. For EBCDIC files, specify CODESETEBCDIC in the USING clause. The default row delimiter is an end-of-linecharacter unless you use the RECORDEND keyword to specify a differentdelimiter when you created the external table. (The RECORDEND keywordworks for delimited format only.)

Unloading to a Delimited FileYou can unload data to a delimited-ASCII text file from a table, as thefollowing example shows:

SELECT * FROM employeeWHERE hiredate > "1/1/1996"INTO EXTERNAL emp_extUSING (

DATAFILES ("DISK:1:/work2/mydir/emp.unl"));


Mapping Columns to Other Columns

Another SQL statement sequence to unload from this table is as follows:

CREATE EXTERNAL TABLE emp_extSAMEAS employeeUSING (

DATAFILES ("DISK:1:/work2/mydir/emp.dat"));

INSERT INTO emp_ext SELECT * FROM employee;

Delimited files are ASCII by default. For EBCDIC files, specify CODESETEBCDIC in the USING clause.

Mapping Columns to Other ColumnsIf the data file is to have fields in a different order (for example, empno,name, address, hiredate), you can use the INSERT statement to map thecolumns. First, create the table with the columns in the order in which theyare found in the external file.

CREATE EXTERNAL TABLE emp_ext(f01 INTEGER,f02 CHAR(18),f03 VARCHAR(40),f04 DATE)

USING (DATAFILES ("DISK:1:/work2/mydir/emp.dat"),REJECTFILE "/work2/mydir/emp.%c.rej");

INSERT INTO employee (empno, name, address, hiredate)SELECT * FROM emp_ext;

With this method, the insert columns are mapped to match the field order ofthe external table.

Another way to reorder columns is to use the SELECT list clause to match theorder of the database table.

INSERT INTO employeeSELECT f02, f04, f03, f01 FROM emp_ext;


Unloading to an Informix Data File

Unloading to an Informix Data FileTo unload from the employee table to a table in Informix internal format onevery coserver, use statements similar to the following ones:

SELECT * FROM employeeWHERE hiredate > "1/1/1996"INTO EXTERNAL emp_extUSING (

FORMAT 'INFORMIX',DATAFILES ("DISK:cogroup_all:/work2/mydir/emp.dat"));

Because the output files use Informix internal representation, you need tospecify the FORMAT 'INFORMIX' option in the USING clause. (The default isdelimited-ASCII format.)

The DATAFILES entry specifies cogroup_all. The database server automati-cally includes all coservers in a cogroup named cogroup_all at execution.Therefore, this example unloads the employee table into a file on eachcoserver.

Loading Between Tables That Have the Same SchemaYou can load data from one table to another with the same schema (forexample, worldemp) with a simple INSERT statement.

INSERT INTO worldemp SELECT * FROM emp_ext;

If you used the database server to unload the data with a SELECT...INTOEXTERNAL statement and you have not yet dropped the external table, youdo not have to create an external table.


Loading from a Fixed-ASCII File

Loading from a Fixed-ASCII FileThe following SQL statements load data from the emp_exp external table toa fixed-position table (employee):



USING (FORMAT 'FIXED',DATAFILES ("DISK:1:/work2/mydir/emp.fix"));


The enumerated columns use the keyword EXTERNAL to describe the formatin which to store the data in the external file.

If the data file has fields that you do not want to insert, you can definedummy fields so that you can skip them. Consider the following scenario:

TABLE company (comp_no SERIAL,acode DECIMAL(3),city CHAR(15),state CHAR(2),zip_code DECIMAL(5),phone CHAR(8),dateentered DATE);

The data file consists of the following two rows:

Sunnyvale++++++CA94086408-789-8075Tempe++++++++++AZ85253xxx-xxx-xxxx


Unloading to a Fixed-ASCII File

The SQL statements to load this file would be as follows:

CREATE EXTERNAL TABLE extcompany( city CHAR(15) EXTERNAL CHAR(15),

state CHAR(2) EXTERNAL CHAR(2),zip DECIMAL(5) EXTERNAL CHAR(5),area DECIMAL(3) EXTERNAL CHAR(3) NULL 'xxx',dummychar CHAR(1) EXTERNAL CHAR(1),

{ this is the '-' }phone CHAR(8) EXTERNAL CHAR(8) NULL 'xxx-xxxx',dummyeol CHAR(1) EXTERNAL CHAR(1)

{ this is the newline character })

using (FORMAT 'FIXED',DATAFILES("DISK:1:/work2/mydir/company.fix"));

INSERT INTO company(city, state, zip_code, acode, phone)SELECT TRIM(trailing '+' from city), state, zip, area, phoneFROM extcompany;

In the internal table, the column dateentered is not initialized from theexternal data file, so you do not enumerate it in the list of columns for theinsert table. Columns that you do not enumerate are loaded with the defaultvalues defined for the columns on the target table.

You can use the TRIM function to clean up data before you enter it in the table.

Unloading to a Fixed-ASCII FileThe following SQL statements unload the employee table in fixed-ASCIIformat into the emp_ext external table:



USING (FORMAT 'FIXED',DATAFILES ("DISK:1:/work2/mydir/emp.fix"));


These statements create a fixed-ASCII file with 20 character positions in thefirst field, the next 10 character positions in the second field, and so on.Because you are choosing the rows with a SELECT statement, you can formatthe SELECT list in any way that you want.


Loading from an IBM Fixed-EBCDIC File

Loading from an IBM Fixed-EBCDIC FileYou can load and unload IBM-format data files. As an example, consider thefollowing IBM employee data file:

CREATE TABLE employee( name CHAR(18),

salary DECIMAL(7,2),hiredate DATE,empno INTEGER

The following SQL statements load the data from the emp_exp external tableto the employee table:


salary DECIMAL(7,2) EXTERNAL "PACKED(7,2)",hiredate DATE EXTERNAL CHAR(10),empno INTEGER EXTERNAL "BINARY(4)" )

USING (FORMAT 'FIXED',CODESET "EBCDIC",DATAFILES ("DISK:1:/work2/mydir/emp.fix")) ;


The packed-decimal salary (seven digits, two of them after the decimal point)is stored in four bytes. Three bytes contain six of the digits. The fourth bytecontains the seventh digit and the sign.

Loading from and Unloading to a Named PipeYou can use a named pipe, also referred to as a first-in-first-out (FIFO) datafile, to load from and unload to a nonstandard device, such as a tape drive.

Unlike ordinary operating-system files, named pipes do not have a 2-gigabyte size limitation. The operating system opens and checks for the endof file differently for named pipes than for ordinary files.


Loading from and Unloading to a Named Pipe

Loading with Named Pipes

To use named pipes to load data from external tables, follow these steps:

1. Specify the named pipes in the DATAFILES clause of the CREATEEXTERNAL TABLE statement in SQL.

Suppose you have a database server system with 16 coservers, butonly 3 coservers have tape drives attached (for example, coservers 2,5, and 9).

a. Set up a cogroup to facilitate the load and unload commands. Toset up the cogroup, use the onutil command, as the followingexample shows:

% onutil1> CREATE COGROUP tape_group2> FROM cosv.2, cosv.5, cosv.9;Cogroup successfully created.

b. Specify the file locations for the named pipes in the CREATEEXTERNAL TABLE statement.



USING (FORMAT 'FIXED',DATAFILES("PIPE:tape_group:/usr/local/TAPE.%c"));

The filenames expand as follows:DATAFILES ("PIPE:2:/usr/local/TAPE.2","PIPE:5:/usr/local/TAPE.5","PIPE:9:/usr/local/TAPE.9")

2. Create the named pipes that you specified in the DATAFILES clause.Use operating-system commands to create the named pipes.

Use the mknod UNIX command with the -p option to create a namedpipe. To avoid blocking open problems for pipes on UNIX, startseparate UNIX processes for pipe-readers and pipe-writers or openthe pipes with the O_NDELAY flag set.



3. Open the named pipes with a program that reads the named pipe.

The database server provides a sample pipe-reader program in$INFORMIXDIR/demo/xmp/rpipe.c and a sample pipe-writerprogram in $INFORMIXDIR/demo/xmp/wpipe.c.

4. Execute the INSERT statement in SQL.INSERT INTO employee SELECT * FROM emp_ext;

Warning: If you do not create and open the named pipes before you execute theINSERT statement, the INSERT succeeds, but no rows are loaded.

Using FIFO Virtual Processors

The database server uses FIFO virtual processors (VPs) to read and write toexternal tables on named pipes. The NUMFIFOVPS configuration parameterspecifies the number of FIFO VPs for each coserver. The default number is 2.

The database server uses one FIFO VP for each named pipe that you specifyin the DATAFILES clause of the CREATE EXTERNAL TABLE statement. Forexample, suppose you define an external table with the following SQLstatement:

CREATE EXTERNAL TABLE atab_extSAMEAS atabUSING (

DATAFILES("PIPE:1:/tmp/pipe1","PIPE:1:/tmp/pipe2","PIPE:1:/tmp/pipe3"

));

If you use the default value of 2 for FIFO VPs, the database server does notread from pipe3 until it finishes reading all the data from pipe1 or pipe2.

For more information, refer to the chapter about virtual processors andthreads in the Administrator’s Guide. For more information about using theNUMFIFOVPS configuration parameter, refer to “NUMFIFOVPS” onpage 1-103 and “Monitoring FIFO Virtual Processors” on page 8-45.



Unloading with Named Pipes

To use named pipes to unload data to external tables, follow these steps:

1. Specify the named pipes in the DATAFILES clause of either theCREATE EXTERNAL TABLE statement or the SELECT INTO EXTERNALin SQL.

DATAFILES ("PIPE:tape_group:/usr/local/TAPE.%c")

2. Create the named pipes that you specified in the DATAFILES clause.Use operating-system commands to create the named pipes.

3. Open the named pipes with a program that writes to the named pipe.

The database server provides a sample pipe-reader program in$INFORMIXDIR/demo/xmp/rpipe.c and a sample pipe-writerprogram in $INFORMIXDIR/demo/xmp/wpipe.c.

4. Unload to the named pipe.

You can use the SELECT INTO EXTERNAL statement to unload fromnamed pipes, as the following example shows:

SELECT * FROM employeeWHERE hiredate > "1/1/1996"

INTO EXTERNAL emp_extUSING (

FORMAT 'DELIMITED',DATAFILES

("PIPE:2:/usr/local/TAPE.2","PIPE:5:/usr/local/TAPE.5","PIPE:9:/usr/local/TAPE.9")

);

Alternatively, you can use the following SQL statement sequence tounload from named pipes:



USING (FORMAT 'FIXED',DATAFILES("PIPE:tape_group:/usr/local/TAPE.%c"));



Adding an End-of-Line Character to a Fixed-ASCII File

Warning: If you do not create and open the named pipes before you execute theSELECT or INSERT statement, the unload fails with the ENXIO error message (nosuch device or address).

Adding an End-of-Line Character to a Fixed-ASCII FileIf you are writing text in a fixed-ASCII format, separate lines for each recordare helpful. For example, consider a table with the following schema:

TABLE sample (lastname CHAR(10),firstname CHAR(10),dateofbirth DATE);

This table contains the following values:

Adams Sam 10-02-1957 Smith John 01-01-1920

Next, consider an external table with the following schema:

CREATE EXTERNAL TABLE sample_ext (lastname CHAR(10) EXTERNAL CHAR(10),firstname CHAR(10) EXTERNAL CHAR(10),dateofbirth DATE EXTERNAL CHAR(12));

Unloading sample_ext without an end-of-line character produces thefollowing output:

Adams Sam 10-02-1957 Smith John 01-01-1920

An end-of-line character makes the date more legible and clear. If you usedelimited format defaults, an end-of-line character is automatic. However,for fixed-format unloads, you need to add an end-of-line character to yourrecords. You can add end-of-line characters in several ways.

Using a Program or Script

To add an end-of-line character, you can write the fixed-length records to adata file and then modify the data file with a program or script. For example,you could use a C program to find the length of each record, locate the end ofa line, and then add an end-of-line character.


Adding an End-of-Line Character to a Fixed-ASCII File

Adding a Newline Field in a SELECT Statement

To add an end-of-line character, select a final value from a table that containsa newline character. You can use an external table to load the newlinecharacter in your internal table, as in the following example:

1. Create a file that contains only a newline character.echo "" > /tmp/cr.fixed

2. Create an internal table to store this newline value to use later withyour unload.

CREATE TABLE dummyCr (cr CHAR(1));

3. Create the external table to load in the newline value.CREATE EXTERNAL TABLE x_cr (cr (CHAR(1) EXTERNALCHAR(1))USING (DATAFILES ("disk:1:/tmp/cr.fixed"), FORMAT'FIXED');

4. Load the external table in the internal dummyCr table.INSERT INTO dummyCr SELECT * FROM x_cr;

The internal table, dummyCr, now contains an end-of-line character that youcan use to unload in a SELECT statement:

1. To unload from your internal table to an external table, create theexternal table with the end-of-line character as an external character.

CREATE EXTERNAL TABLE sample_ext(

lastname CHAR(10) EXTERNAL CHAR(10),firstname CHAR(10) EXTERNAL CHAR(10),dateofbirth DATE EXTERNAL CHAR(12),eol CHAR(1) EXTERNAL CHAR(1))

USING (DATAFILES ....), FORMAT 'FIXED');

2. Select from the internal table and the dummyCr table to create anoutput file that has rows separated by end-of-line characters.

INSERT INTO sample_ext(lastname, firstname,dateofbirth, eol)SELECT a.lastname, a.firstname, a.dateofbirth, b.crFROM mytable a, dummyCr b;

Important: If you are unloading fixed-ASCII data with EBCDIC, end-of-linecharacters are not usually expected, but they are not illegal.


Loading Values into Serial Columns

Loading Values into Serial ColumnsThe database server loads serial columns with either the values from theoriginal data file or values that the database server automatically generates.

If you want the serial column values to be the values found in the data file,the INSERT statement does not require special handling. On the other hand,if you want the database server to generate the value automatically, omit theserial column from the INSERT statement. For example, if the first column inthe table (col1) is the serial column and you use the following statement, thedefault mechanism provides the serial value:

INSERT INTO mytable (col2, ...) SELECT ...

If the table is being loaded into multiple partitions, the serial values are incre-mented in the same sequence as the table fragments.

Loading Data Warehousing TablesThis section discusses various scenarios to load very large tables:

■ Loading initially

■ Refreshing periodically

■ Refreshing frequently or continuously

■ Initial loading of OLTP data from database servers other thanExtended Parallel Server

Loading Initially

The following scenario creates and loads a data warehouse table with datafrom outside of the Informix database server.

To load a table initially

1. Create the table as type RAW to take advantage of light appends andto avoid the overhead of logging during the load.

CREATE RAW TABLE tab1 ...

2. Describe the external data file to the Informix database server withthe CREATE EXTERNAL TABLE statement.


Loading Data Warehousing Tables

3. Load the table in express mode.INSERT INTO tab1 SELECT * FROM EXTERNAL TABLE ext_tab

The table loads quickly, and the operation consumes only aminuscule amount of log space.

4. Verify integrity of the data.

5. If you do not plan to update the table, change it to type STATIC.ALTER TABLE tab1 TYPE(STATIC);

If you plan to update the table, change it to a logging type such asOPERATIONAL or STANDARD.

6. Create indexes on the table to speed queries against it.

7. Perform a level-0 backup now to enable you to restore the table later,if necessary. You do not need to perform this level-0 backup if youfeel it would be just as easy to reload the table from the originalsource in the case of a catastrophe.

Refreshing Periodically

This scenario loads new data in a data warehouse table periodically fromsome other source. The scenario assumes that the table is type STATIC duringnormal operation and that the CREATE EXTERNAL TABLE statement has beenpreviously executed.

To refresh a table periodically

1. Drop all indexes on the table.

2. Alter the table to type RAW.ALTER TABLE tab1 TYPE(RAW);

3. Load the new data in the table in express mode.INSERT INTO tab1 SELECT * FROM EXTERNAL TABLE ext_tab

This INSERT statement quickly appends new data to the end of thetable, and the operation consumes only a minuscule amount of logspace.


5. Change the table to type STATIC.ALTER TABLE tab1 TYPE(STATIC);



6. Re-create indexes on the table to speed queries against it.

7. Perform a level-0 backup now to enable you to restore the table later,if necessary. You do not need to perform this level-0 backup if youfeel it would be just as easy to reload the table from the originalsource in the case of a catastrophe.

Refreshing Frequently or Continuously

In this scenario, you have a data warehouse table into which new data contin-uously trickles from some other source. You can easily reload the data fromthe original source, so it is not worth the trouble to do the backups.

The following table types are not appropriate for this scenario:

■ RAW tables are not appropriate for this scenario because the tablesneed indexes or constraints on them.

■ STATIC tables are not appropriate because the refreshes occur toooften. You do not have sufficient time to drop and re-create indexesconstantly in order to change the table to RAW for the inserts.

■ STANDARD tables might be appropriate, but OPERATIONAL tablesare better because you can take advantage of light appends to loaddata quickly.

To refresh a table frequently or continuously

1. Create the table as type OPERATIONAL

2. Optionally, use the TRUNCATE statement to quickly delete all therows in the table before you load the new data, as the followingexample shows:

TRUNCATE tab1

For more information on the TRUNCATE statement, see the InformixGuide to SQL: Syntax.

3. Start the violations table if you want to check referential or uniqueconstraints during the load. The load operation completes success-fully even if constraint violations exist. (Do not set constraints todeferred when you use the violations table.)

(The database server detects and rejects check constraints in theexternal table.)



4. Use one of the following methods to load the new data:

a. Express mode for bulk inserts of new data if no indexes or refer-ential or unique constraints exist

b. Ordinary inserts performed one record at a time

5. Create and drop indexes and constraints as necessary.

Initial Loading of OLTP Data from Other Database Servers

This scenario loads data in Extended Parallel Server for the first time, as youmight do when you migrate from a different database server. In this scenario,the table to load will be used for OLTP, so you need logged transactions,rollback, and recoverability.

To load OLTP data initially from a different database server

1. Create the table as type RAW to take advantage of light appends andto avoid the overhead of logging during the load.

CREATE RAW TABLE tab1 ...

2. Describe the external data file to the Informix database server withthe CREATE EXTERNAL TABLE statement.

3. Load the table in express mode.INSERT INTO tab1 SELECT * FROM EXTERNAL TABLE ext_tab

The table loads quickly, and the operation consumes only aminuscule amount of log space.


5. Perform a level-0 backup to provide a point from which to recover.

6. Change the table to type STANDARD.ALTER TABLE tab1 TYPE(STANDARD);

7. Create indexes on the table to speed queries against it.

8. Enable constraints on the table to preserve the integrity of the data.

Tip: For information on using external tables to load data from a Version 7.2 orVersion 7.3 database server to a Version 8.3 database server, see the “InformixMigration Guide.”


Loading Simple Large Objects

Loading Simple Large ObjectsYou can use the following methods to load and unload simple large objects,which contain TEXT or BYTE data:

■ LOAD and UNLOAD statements in DB-Access for data in delimitedformat

■ INSERT statement with external tables

When you use external tables to load and unload simple large objects, yougain the following performance advantages: The external table is integratedin the database server and bypasses the client-server connection. Externaltables enable the parallel processing of multiple data files on multiplecoservers.

You can also use either DB-Access or ESQL/C statements to insert simple largeobjects, but these methods pass data through the client-server connection andmight reduce performance.

Use external tables to insert or load many rows or columns of simple largeobjects at a time. Use DB-Access or ESQL/C only to insert a few rows orcolumns at a time.

The following sections describe how to use external tables to load and unloadsimple large objects. They include the following topics:

■ Formats for simple large objects

■ Procedure for loading

■ Pipe staging

Formats for Simple Large ObjectsA format describes the structure of the data in a data file. Before you can loadrows from a data file to an Informix database or unload rows from a databaseto a data file, you must define a format that describes the data file.


Formats for Simple Large Objects

The database server supports the following file formats for simple largeobjects:

■ Informix internal format

■ Delimited format

Using Informix Internal Format

Informix internal format always loads and unloads simple large objects ininternal format and does not use the external TEXT or HEX type definition forsimple large objects. In Informix internal format, the data for the simple largeobject follows the row. The row contains a four-byte integer indicating thelength of the simple large object. It is followed by a simple large object ofvariable length. The length and data are in internal binary format. Forexample, suppose you want to load the following table:

CREATE TABLE tab1(col1 INT,largeobj1 BYTE,col2 CHAR(10),largeobj2 BYTE,col3 CHAR(10)) ...

The following diagram shows the layout of the data file.

Figure 8-3Simple Large Objects with Informix Internal Format

Variable-length simple large objectFixed-size row

col1 text1 length byte2 lengthcol2 col3 text1 data byte2 data



You can define an external data file that specifies Informix internal format forsimple large objects with the following CREATE EXTERNAL TABLE statement:

CREATE EXTERNAL TABLE extab (col1 INT,text TEXT,byte2 BYTE)

USING (FORMAT 'INFORMIX',DATAFILES('disk:1:/datafile1'));

If you are concerned with the length of time to load or unload a very largetable that contains simple large objects, use internal format for the fasterexecution time. However, you can use internal format only in the followingsituations:

■ Moving data between two Version 8.3 database servers

■ Using the High-Performance Loader (HPL) or the onxfer utility tounload data from a table in Version 7.2 or Version 7.3 and load thatdata in a table in a Version 8.3 database server

For more information on onxfer, refer to the Informix Migration Guide.

Using Delimited Format

In delimited format, the data for the simple large object is inserted directly inthe row at the point where the TEXT or BYTE column is defined. Delimitedformat affords slower performance than Informix internal format. Usedelimited format when neither of the two preceding conditions applies.

The database server supports two external column types for simple largeobjects in delimited format:

■ TEXT

■ HEX

The database server converts the data between the internal and externalcolumn types during loading and unloading.



You can define an external data file that specifies delimited format with eitherTEXT or HEX column types for simple large objects with the followingCREATE EXTERNAL TABLE statement:

CREATE EXTERNAL TABLE extab (col1 INT,text1 TEXT EXTERNAL 'TEXT', col2 CHAR(10),byte2 BYTE EXTERNAL 'HEX', col3 CHAR(10))

USING (FORMAT 'DELIMITED',DATAFILES('disk:1:/datafile1'));

Figure 8-4 shows the layout of the data file. The external format of thesecolumns is variable length but the internal format is fixed length, exceptVARCHAR, TEXT, and BYTE data types.

External TEXT Type

You can encode a TEXT or BYTE column in the external TEXT type. Use onlydelimited TEXT and BYTE columns with this external type. Fixed formats arenot allowed. If you do not specify the external type in the CREATE EXTERNALTABLE statement, TEXT columns default to the external TEXT data type andBYTE columns default to the HEX data type.

The database server uses the default field delimiter '| ' and record delimiter'\n' (newline). If you define custom delimiters for an external table, thecustom delimiters are escaped instead. You can not define the character '\' asa delimiter.

Figure 8-4Delimited Format of Simple Large Objects

Dark lines represent delimiters

col1 col2 col3text1 data (TEXT type) byte2 data (HEX type)

Column not TEXT or BYTE data type

Simple-large-object column Simple-large-object column



For simple large objects in external TEXT format, the database server alwaysrecognizes the “\” (backslash) escape sequences. TEXT data often contains thedefault record delimiter '\n' (newline), and it is often difficult for a user to tellwhether or not TEXT data contains delimiters before a load.

When the database server unloads, it writes each character in the simple largeobject literally, except for field and record delimiters and backslashes, whichare escaped. The database server inserts the escape character (backslash)before it writes the escaped character. When the database server loads, itinterprets the escape sequence. A backslash followed by any character isinterpreted as a literal character. Nonprintable characters are embedded inthe data file unchanged if you specify the external TEXT data type.

The ESCAPE keyword in an external table definition does not affect TEXT datain a simple large object. It affects only character columns. Figure 8-5 showsthis byte sequence represented in the TEXT data file; one cell represents onebyte in a data file. Escaped characters are circled.

Figure 8-5Expansion of Simple Large Object Loaded in TEXT Data Type

0x00 0x01 0x02 0x03 \ \ x \ | y \ \n z

0x00 0x01 0x02 0x03 \ x | y \n z

TEXT data file

Original byte sequence



Multibyte Characters

In multibyte GLS locales, you can define only characters with a length ofexactly one byte as delimiters.

The database server does not alter simple large objects. A simple large objectmight contain invalid text and incomplete or invalid multibyte characters. Incontrast to character columns, the database server does not pad with blanksor truncate invalid multibyte characters in a simple large object. In bothsingle-byte and multibyte locales, the database server always traverses TEXTdata byte by byte instead of character by character. If a byte matches one ofthe delimiters or a backslash, the database server puts an escape characterbefore it.

External HEX Type

You can encode a BYTE or TEXT column in the external HEX type. Use onlydelimited BYTE and TEXT columns with this external type. Fixed formats arenot allowed. If you do not specify the external type in the CREATE EXTERNALTABLE statement, BYTE columns default to the external HEX data type andTEXT columns default to the external TEXT data type.

The external HEX data type uses two hexadecimal digits (0 through 9, Athrough F, case insensitive) to represent one byte of data. The digits arecontinuously written to the data file. No character marks the boundary ofbytes. Therefore, one byte of simple-large-object data occupies two bytes in adata file. This expansion might cause a problem if you have large simple largeobjects and limited disk space.

Because the HEX output always contains printable characters, you cannotescape HEX data. Do not define any hexadecimal character as a field or recorddelimiter.

For example, suppose you have the following byte sequence where a byte isrepresented either with its hexadecimal value or a quoted character:

{0x00, 0x01, 0x02, 0x03, '\', 'x', '|', 'y', '\n','z'}

GLS


Loading Simple Large Objects from an External Table

Figure 8-6 shows this byte sequence represented in hex; one cell representsone byte in a data file.

Loading Simple Large Objects from an External TableTo load from an external table that contains simple large objects, follow thesesteps:

1. Define an external table with simple-large-object columns. For tableswith simple-large-object columns, you can specify only INFORMIX orDELIMITED formats. (Use the FORMAT keyword.)

In this example, the external table uses data in delimited format.CREATE EXTERNAL TABLE extab (

col1 INT,text1 TEXT EXTERNAL 'TEXT',byte2 BYTE EXTERNAL 'HEX')

USING (FORMAT 'DELIMITED',DATAFILES('disk:1:/datafile1'));

External type for simple-large-object columns is optional. TEXTcolumns default to external TEXT data types, and BYTE columnsdefault to external HEX data types. Use quote marks for external datatypes. They are case insensitive.

Figure 8-6Expansion of Simple Large Object Loaded in Hex Data Type

0x00 0x01 0x02 0x03 \ x | y \n z

00 01 02 03 5c 78 7c 79 0a 7a

Simple-large-object data, 10 bytes

Printed in HEX data type in the external table, expanded to 20 bytes


Loading Simple Large Objects from an External Table

In this example, the external table uses data in Informix format. Donot use the EXTERNAL keyword when you define a simple-large-object column in Informix format.

CREATE EXTERNAL TABLE extab2 (col1 INT,t4 TEXT,b4 BYTE)

USING (FORMAT 'INFORMIX',DATAFILES('disk:1:/datafile1'));

For information about data-file formats, refer to “Formats for SimpleLarge Objects” on page 8-32. For format compatibility among thevarious load and unload utilities, refer to the Informix MigrationGuide.

2. Load or unload the external table.

Load to the internal table as in the following example:INSERT INTO internal_tab SELECT * FROM extab;

Unload from the external table as in the following example:INSERT INTO extab SELECT * FROM internal_tab;

When you use delimited format, the database server interprets two adjacentfield delimiters as a simple large object with a null value, not a zero-lengthobject. The behavior is consistent with that for other data types, such asVARCHAR. When you unload a simple large object of zero length to anexternal table, it is written as two adjacent field delimiters. When you loadthe same object back, it becomes null.

When you use Informix format, null and zero-length data have differentvalues. Simple large objects with null values are represented as having a '-1'length in the external data file. You can reload the exact value.


Using Pipe Staging

Using Pipe StagingPipe staging is the process of writing simple large objects to a temporary filewhen they are too large to fit in memory. The database server uses stagingwith simple large objects when all of the following conditions apply:

■ Simple large objects are read in from a pipe.

Data read in from a pipe does not persist on disk. The databaseserver does not stage simple-large-object data from disk files becausethe data can be retrieved from disk if the row overflows the memorybuffer.

■ The input file is in delimited format and contains simple large objectswith rows that exceed the length of the memory buffer.

Because a table in Informix internal format places simple largeobjects after the row rather than in it, the database server does notstage data when it reads a table with this format.

■ The data read in from a pipe contains rows whose length exceeds thesize of the memory buffer (136 kilobytes).

The database server must reach the end of the row when it evaluatesfilters or determines which coserver the row will go to based on thefragmentation scheme of the table. The database server temporarilybuffers the row.

Using Parallel Execution

The reader thread handles the staging of simple large objects to disk. Theonstat command and the SET EXPLAIN ON output display this reader threadas the SQL operator xlread, which means load reader.

The database server creates multiple xlread instances on each coserver, butno more than the number of CPU virtual processors. Figure 8-7 shows howmultiple xlread instances on each coserver might handle the pipe staging.


Using Pipe Staging

Using Temporary Space for Pipe Staging of Simple Large Objects

The database server creates multiple xlread instances for parallel execution.You need temporary space for each xlread instance.

When you load simple large objects from named pipes in delimited format,you might need to increase the temporary space if the simple large objects arelarge. If a delimited row is larger than 136 kilobytes, the load routine stagesit to disk.

Figure 8-7Pipe Staging

dbspace_2

coserver_2

Flow Mgr

Flow Mgr

Insert

coserver_1

Flow Mgr

Load Converters

Flow Mgr

ConverterLoad Converters

dbspace_1

Pipe

Insert

Pipe

Load Readers Load Readers

temp_2

temp_1

temp_2

temp_1


Using Pipe Staging

The database server uses temporary space for the staging file. You can useone of the following temporary spaces for the staging files:

■ Temporary dbspaces on the same coserver as the named pipe

The load routine uses these by default. The default value for theDBSPACETEMP configuration parameter is NOTCRITICAL, whichincludes all dbspaces except the root and log dbspaces. The databaseserver uses temporary dbspaces first among these noncriticaldbspaces.

■ Dbspaces or dbslices

You can specify these in the DBSPACETEMP configuration parameter.

■ DBSPACETEMP environment variable

You can override the DBSPACETEMP configuration parameter withthis environment variable.

For the following reasons, Informix recommends that you useDBSPACETEMP instead of the PSORT_DBTEMP environment variable toprovide temporary file space:

■ DBSPACETEMP usually yields better performance.

When dbspaces reside on character-special devices (also known asraw disk devices), the database server uses unbuffered disk access.I/O is faster to raw devices than to regular (buffered) operating-system files because the database server manages the I/O operationdirectly.

■ PSORT_DBTEMP specifies one or more operating-system directoriesin which to place temporary files.

These operating-system files can unexpectedly fill on your computerbecause the database server does not manage them and the databaseserver utility programs do not monitor them.


Using Pipe Staging

To estimate and create temporary space on coservers for pipe staging

1. The size of the staging file required for each xlread operator instanceis the size of the largest input data row, including its TEXT or BYTEdata. Estimate the number of bytes required for the largest input datarow with the following formula:

bytes_per_xlread = row_size + overhead

Estimate overhead as 34 kilobytes rounded up to the next wholepage for each 34 kilobyte of TEXT or BYTE data. Page size is userconfigurable, with a default of 4 kilobytes. With a page size of 4kilobytes, each 34 kilobytes of data uses 36 kilobytes of temporaryspace. Therefore the 40-kilobyte simple large object would require 72kilobytes of space.

The preceding formula is most accurate for rows larger than 1megabyte. For smaller rows, the row might overflow the 136-kilobyte buffer because part of it might be in the memory bufferwhile the rest is in the staging file. With larger rows, the buffer size isrelatively insignificant.

2. The total temporary space needed on a coserver is the sum of spacesrequired for all xlread instances on the coserver. Calculate it with thefollowing formula:

tempspace_per_coserver = bytes_per_xlread * number_xlr

The number of xlread instances is not more than the number of datafiles or the number of CPU virtual processors.

3. Although you can use standard dbspaces for the temporary fileswith the appropriate DBSPACETEMP setup, Informix recommendsyou create the temporary dbspace with onutil:

a. For an even distribution of temporary dbspaces across thecoservers, use the onutil CREATE TEMP DBSLICE option.

b. For more temporary dbspaces on specific coservers, use theonutil CREATE TEMP DBSPACE option for each specific coserver.

For information about monitoring temporary space for pipe staging, refer to“Monitoring Loads and Unloads of Data” on page 8-46.


Monitoring the Load or Unload Operations

Monitoring the Load or Unload OperationsYou might want to monitor the load or unload operations for the followingsituations:

■ If you expect to load and unload the same table often to build a datamart or data warehouse, monitor the progress of the job to estimatethe time of similar jobs for future use.

■ If you load or unload from named pipes, monitor the I/O queues todetermine if you have a sufficient number of FIFO virtual processors.

■ If you load unusually large simple large objects from named pipes,monitor the temporary dbspaces.

Monitoring Frequent Loads and UnloadsUse the onstat -g iof command to find out the global file descriptor (gfd) inthe file that you want to examine. Figure 8-8 shows sample output.

To determine if the load or unload can use parallel execution, execute the SETEXPLAIN ON statement prior to the INSERT statement. The SET EXPLAINoutput shows the following counts:

■ Number of parallel SQL operators that the optimizer chooses for theINSERT statement

■ Number of rows to be processed by each SQL operator

To monitor a load job, first run onstat -g sql to obtain the session ID, and runonstat -g xmp to obtain the query ID for the session ID. Then you can runonstat -g xqs query id to obtain the runtime number of rows processed by eachSQL operator that the SET EXPLAIN output listed.

AIO global files:gfd pathname totalops dskread dskwrite io/s19 /tmp/pipe

Figure 8-8onstat -g iof Output


Monitoring FIFO Virtual Processors

To obtain statistics for a coserver to which you are not connected or formultiple coservers, use the xctl utility to execute the onstat command. Thexctl prefix displays onstat information for each coserver that is currentlyinitialized.

Monitoring FIFO Virtual ProcessorsYou can monitor the effective usage of FIFO VPs with onstat commands.

Use the onstat -g ioq option to display the length of each FIFO queue that iswaiting to perform I/O requests. Figure 8-9 shows sample output.

The q name field in the sample output in Figure 8-9 shows the type of thequeue, such as fifo for a FIFO VP or aio for an AIO VP. If the q name fieldshows gfd or gfdwq, it is a queue for a file whose global file descriptormatches the id field of the output. Disk files have both read and writerequests in one queue. One line per disk file displays in the onstat -g ioqoutput. Pipes have separate read and write queues. Two lines per pipedisplay in the output: gfd for read requests and gfdwq for write requests.

The len or maxlen field has a value of up to 4 for a load or4 * number_of_writer_threads for an unload. The xuwrite operatorcontrols the number of writer threads.

AIO I/O queues:q name/id len maxlen totalops dskread dskwrite dskcopy fifo 0 0 0 0 0 0 0 adt 0 0 0 0 0 0 0 msc 0 0 1 153 0 0 0 aio 0 0 9 3499 1013 77 0 pio 0 0 2 3 0 2 0 lio 0 0 2 2159 0 2158 0 gfd 3 0 16 39860 38 39822 0 gfd 4 0 16 39854 32 39822 0 gfd 5 0 1 2 2 0 0 gfd 6 0 1 2 2 0 0... gfd 19 0 1 2 2 0 0

Figure 8-9onstat -g ioq Output


Monitoring Loads and Unloads of Data

Use the values in the totalops field rather than the len or maxlen field tomonitor the number of read or write requests done on the file or pipe. The opfield represents 34 kilobytes of data read from or written to the file. If totalopsis not increasing, it means the read or write operation on a file or pipe isstalled (because the FIFO VPs are busy).

To improve performance, use the onmode -p command to add more FIFOVPs. The default value for the NUMFIFOVPS configuration parameter is 2 percoserver. If you define multiple pipes for each coserver, monitor the len fieldfor the FIFO queue. In this sample output, the FIFO queue does not containany data. For example, if you usually define more than two pipes percoserver to load or unload, increase the number of FIFO VPs with thefollowing sample onmode command:

onmode -p +2 FIF

For more information, see “Add or Remove Virtual Processors” on page 3-49.

Monitoring Loads and Unloads of DataYou can use the following tools to monitor the load of simple large objectsand other data from named pipes:

■ SET EXPLAIN ON output

■ onstat -g xqs

Using SET EXPLAIN ON Output

To obtain the information that Figure 8-10 shows, you can issue the SETEXPLAIN ON statement prior to the INSERT statement to load a simple largeobject:

■ The xlread fields show the number of xlread SQL operators on eachcoserver. If the data is in fixed or delimited format, the rows_readfield represents the number of 34-kilobyte buffers that xlread hasread.

■ The rows_rej fields show the number of rows that were rejectedduring the load.



■ The xlcnv field shows information about the number of rows that thexlcnv (load converter) has converted and read. If the data is inInformix format, no data displays in the xlcnv field because no loadconverter operator is created.

■ In the XMP Query Plan section, the width field is the total number ofiterator instances on all coservers.

■ The XMP Query Statistics section shows how these instances are laidout on the coservers and how many rows each instance produces.

XMP Query Plan

oper segid brid width--------------------------xlread 2 0 2xlcnv 2 0 2insert 1 0 1

XMP Query Statistics

type segid brid information--------------------------------xlread 2 0 inst cosvr time rows_read rows_rej ---- ----- ---- --------- -------- 0 2 8 23 0 1 1 9 23 0 -------------------------------------- 2 46 0

xlcnv 2 0 inst cosvr time rows_converted rows_rej ---- ----- ---- ------------- -------- 0 2 8 20004 0 1 1 9 20004 0 -------------------------------------- 2 40008 0

insert 1 0 inst cosvr time it_count ---- ----- ---- -------- 0 1 8 40008 --------------------------- 1 40008

Figure 8-10SET EXPLAIN

Output During theLoad of Simple

Large Objects



Using onstat to Monitor Pipe Staging

While the INSERT statement is executing to load simple large objects, you canuse the onstat -g xqs command to display the following statistics:

■ Number of actual xlread SQL operators currently executing on eachcoserver

■ Number of rows read and number of rows rejected by each xlreadSQL operator

Because the onstat -g xqs command gathers statistics periodically, the outputmight not be accurate. For more information on interpreting the statistics, seeyour Performance Guide. Figure 8-11 shows sample output for onstat -g xqsthat is similar to the SET EXPLAIN output in Figure 8-10 on page 8-47.

type segid brid information---- ---- ---- -----------xlread 2 0 inst cosvr time rows_read rows_rej ---- ----- ---- --------- -------- 0 2 4 16 0 1 2 5 14 0 ----------------------------------- 2 30 0

insert 1 0 inst cosvr time it_count ---- ----- ---- -------- 1 2 4 15 ------------------------- 2 15

Figure 8-11onstat -g xqs Output


Recovering After Errors

Recovering After ErrorsThis section describes how to use the reject file, error messages, and recover-ability if the load or unload operation fails.

Reject FilesRows that have conversion errors during a load or rows that violate checkconstraints defined on the external table are written to a reject file on thecoserver that performs the conversion. Each coserver manages its own rejectfile. The REJECTFILE keyword in the CREATE EXTERNAL TABLE statementdetermines the name given to the reject file on each coserver.

Instead of using a reject file, you can use the MAXERRORS keyword in theCREATE EXTERNAL TABLE statement to specify the number of errors that areallowed per coserver before the database server stops the load. (If you do notset MAXERRORS, the database server processes all data regardless of thenumber of errors.)

You can use the formatting characters %c and %n (but not %r) in the rejectfilename. Use the %c formatting characters to make the filenames unique.You must use %c if multiple coservers reside on one node. Each coservermust have its own reject file or other coservers will overwrite the data. Thedatabase server removed the reject files, if any, at the beginning of a load. Thereject files are re-created and written only if errors occur during the load.


Reject Files

Reject file entries are single lines with the following comma-separated fields:

coserver-number, filename, record, reason-code, field-name: bad-line

The load operation writes coserver-number, filename, record, field-name, andreason-code in ASCII.

The bad-line information varies with the type of input file:

■ For delimited files or fixed-ASCII files, the entire bad line is copieddirectly into the reject file. However, if the delimited format table hasTEXT or BYTE columns, the reject file does not include any bad data.The load operation generates only a header for each rejected row.

■ For Informix internal data files, the bad line is not placed in the rejectfile because you cannot edit the binary representation in a file.However, coserver-number, filename, record, reason-code, and field-nameare still reported in the reject file so that you can isolate the problem.

Field Description

coserver-number Number of the coserver from which the file is read

filename Name of the input file

record Record number in the input file where the error was detected

reason-code Description of the error

field-name The external field name where the first error in the lineoccurred or <none> if the rejection is not specific to a particularcolumn

bad-line For delimited or fixed-ASCII files only, the bad line itself


Error Messages

The following types of errors can cause a row to be rejected.

For INFORMIX format, if the data file contains simple-large-object columns,the load query terminates on the first data error, even if you specify a rejectfile. In this format, a complete row precedes the TEXT or BYTE data, and thedatabase server might not detect an error until it inserts the row. The databaseserver does not undo such insertions and terminates the whole statement.

For DELIMITED format, the rejection behavior is the same whether or not thetable has simple-large-object columns. The reader thread scans the entire row,which includes the simple-large-object columns, before it submits the row forinsertion. The reader thread detects any bad data and rejects it, and the loadcontinues.

Error MessagesMost of the relevant error messages are in the -23700 to -23799 range.Additional messages are -615, -999, -23852, and -23855. In the messages,c macro, n macro, and r macro refer to the values generated from the substi-tution characters %c, %n, and %r(first..last). For a list of error messages, referto Informix Error Messages in Answers OnLine or use the finderr utility. Forinformation on the violations table error messages, see Chapter 5, “Message-Log Messages.”

Error Type Description

CONSTRAINT constraint name This constraint was violated.

CONVERT_ERR Any field encounters a conversion error.

MISSING_DELIMITER No delimiter was found.

MISSING_RECORDEND No record end was found.

NOT NULL A null was found in field-name.

ROW_TOO_LONG The input record is longer than 64 kilobytes.


Recoverability of Table Types

Recoverability of Table TypesThe database server checks the recoverability level of the table during a load:

■ If the table type is RAW, the database server can use light-append (orexpress) mode to load data and process check constraints. If thedatabase server crashes during the load, the data loaded is not rolledback, and the table might be left in an unknown state.

■ If the table type is STATIC, the database server cannot load the dataat all.

■ If the table type is OPERATIONAL, the database server can roll backto the preload state if the database server fails. If you want to havecomplete recoverability of the table without reloading the data, youmust run a level-0 backup after the load.

■ Only deluxe mode supports data recoverability. Deluxe mode useslogged, regular inserts. To recover data after a failed express-modeload, revert to the most recent level-0 backup. The table type must beSTANDARD for this level of recoverability.

For more information on fast recovery of table types, see the chapter on fastrecovery in the Administrator’s Guide. For information on restoring tabletypes, see the Backup and Restore Guide.


AAppendix

Files That the DatabaseServer Uses

This appendix provides brief summaries of the files that you usewhen you configure and use the database server. It also includesdescriptions of files (and one directory) created and used inter-nally by the database server. For many of these files, your onlyresponsibilities are to recognize that those files are legitimateand refrain from deleting them.

Pathnames that appear in the following format indicate files thatreside on UNIX: /directory/filename. Pathnames that appear inthe following format indicate files that reside on Windows NT:\directory\filename.

In some cases, environment variables are used to specify theinitial pathname of a file. On UNIX, references to environmentvariables begin with a dollar sign: $INFORMIXDIR. OnWindows NT, references to environment variables begin and endwith percent signs: %INFORMIXDIR%.

Database Server Files

Database Server FilesFigure A-1 lists the database server files and the directories in which theyreside.

Figure A-1List of Files That the Database Server Uses

Filename Directory Purpose Created

af.xxx Specified by DUMPDIRconfigurationparameter

Assertion-failureinformation

By the database server

ac_msg.log (IDS) /tmp,%INFORMIXDIR%\etc

archecker message log (forInformix Technical Support)


ac_config.std (IDS) $INFORMIXDIR/etc,%INFORMIXDIR%\etc

Template for archecker-parameter values


bar_act.log /tmp,%INFORMIXDIR%\etc

ON-Bar activity log By ON-Bar

bldutil.process_id /tmp,\tmp

Error messages about thesysutils database appear inthis file.


buildsmi.xxx /tmp,%INFORMIXDIR%\etc

Error messages about SMIdatabase


.conf.dbservername The onsnmp utility uses thisfile to obtain the databaseserver configuration.


core Directory from whichthe database serverwas invoked

Core dump By the database server

Emergency boot files(For filenames, seepage A-7.)

$INFORMIXDIR/etc,%INFORMIXDIR%\etc

Used in a cold restore By ON-Bar

gcore (UNIX) Specified by DUMPDIRconfigurationparameter

Assertion failure information By the database server

(1 of 4)

A-2 Informix Administrator’s Reference


illlsrra.xx $INFORMIXDIR/lib,%INFORMIXDIR%\lib

Shared libraries for thedatabase server and someutilities

By install procedure

.informix (UNIX) User’s home directory Set personal environmentvariables

By the user

informix.rc (UNIX) $INFORMIXDIR/etc Set default environmentvariables for all users

By the databaseadministrator

INFORMIXTMP /tmp,\tmp

Temporary directory forinternal files


.inf.servicename /INFORMIXTMP,drive:\INFORMIXTMP

Connection information By the database server

.infos.dbservername $INFORMIXDIR/etc,%INFORMIXDIR%\etc


.infxdirs /INFORMIXTMP,drive:\INFORMIXTMP

Database server discoveryfile that onsnmp use


InstallServer.log(IDS, WIN NT)

C:\temp Database server installationlog.


ISM catalog $INFORMIXDIR/ism,%ISMDIR%

Records saved backupobjects and storage volumesthat Informix StorageManager (ISM) uses

By ISM

ISM logs $INFORMIXDIR/ism/logs,%ISMDIR%\logs

Operator alert messages,backend status, additionalISM information

By ISM

ISMversion $INFORMIXDIR/ism,%ISMDIR%

ISM version During installation

The message log Specified by MSGPATHconfigurationparameter

Error messages and statusinformation


The ONCONFIG file $INFORMIXDIR/etc,%INFORMIXDIR%\etc

Configuration information By the databaseadministrator


(2 of 4)

Files That the Database Server Uses A-3


onconfig $INFORMIXDIR/etc,%INFORMIXDIR%\etc

Default ONCONFIG file(optional)

By the database serveradministrator

onconfig.std $INFORMIXDIR/etc Template for configuration-parameter values

During installation

onconfig.xps (XPS) $INFORMIXDIR/etc Template for multiple-coserver ONCONFIG file

During installation

oncfg_servername.servernum (IDS)

$INFORMIXDIR/etc,%INFORMIXDIR%\etc

Configuration informationfor whole-system restores


oncfg_servername.servernum.coserverid(XPS)

$INFORMIXDIR/etc Information for ON-Barrestores


onsnmp.servername.coservernum.log (XPS)

onsnmp.servername(IDS)

/tmp,\tmp

Log file that the onsnmpsubagent uses.

By onsnmp

onsrvapd.log /tmp,\tmp

Log file for the databaseserver daemon onsrvapd.

By onsnmp

oper_deflt.arc(IDS, UNIX)

Command qualifier valuesfor ON-Archive


postInstall.tmp (XPS) /tmp Output from the postinstallscript.

By the database server.

servicename.exp /INFORMIXTMP,drive:\INFORMIXTMP


servicename.str /INFORMIXTMP,drive:\INFORMIXTMP


shmem.xxx (UNIX) Specified by DUMPDIRconfigurationparameter

Assertion-failureinformation


sm_versions.std $INFORMIXDIR/etc,%INFORMIXDIR%\etc

Identifies storage manager inuse.

During installation


(3 of 4)


Descriptions of Files

Descriptions of FilesThis section provides short descriptions of the files listed in Figure A-1.

af.xxxThe database server writes information about an assertion failure to theaf.xxx file. The file is stored in the directory that the DUMPDIR configurationparameter specifies. For more information, see the information onmonitoring for data inconsistency in your Administrator’s Guide.

ac_msg.logWhen you use archecker with ON-Bar to verify a backup, it writes brief statusand error messages to the ON-Bar activity log and writes detailed status anderror messages to the archecker message log (ac_msg.log). InformixTechnical Support uses the archecker message log to diagnose problems withbackups and restores.

snmpd.log /tmp,\tmp

Log file for the SNMP masteragent, snmpdm.

By onsnmp.

sqlhosts (UNIX) $INFORMIXDIR/etc Connection information;contained in the registry onWindows NT.

During installation;modified by thedatabase serveradministrator

VP.servername.nnx /INFORMIXTMP,drive:\INFORMIXTMP


xbsa.messages $INFORMIXDIR/ism/applogs,%ISMDIR%\applogs

XBSA library call information By ISM

xcfg_servername.servernum (XPS)

$INFORMIXDIR/etc Internal configuration infor-mation for ON-Bar restores



(4 of 4)

IDS


ac_config.std

You specify the location of the archecker message log with the AC_MSGPATHconfiguration parameter. For more information, see the Backup and RestoreGuide.

ac_config.stdThe ac_config.std file contains the default archecker (archive checking)utility parameters. To use the template, copy it into another file, and modifythe values. For a comprehensive list of the archecker parameters and how touse archecker with ON-Bar, see the Backup and Restore Guide.

bar_act.logAs ON-Bar backs up and restores data, it writes progress messages, warnings,and error messages to the ON-Bar activity log (bar_act.log). You specify thelocation of the ON-Bar activity log with the BAR_ACT_LOG configurationparameter. For more information, see the Backup and Restore Guide.

bldutil.process_idIf the database server cannot build the sysutils database, it creates thebldutil.<process_id> file which contains the error messages. The process_idvalue is the process ID of the bldutil.sh program. To access this output file,specify ${RESFILE}.

buildsmi.xxxIf the database server cannot build the sysmaster database, it places amessage in the message log that refers you to the buildsmi.xxx file. This fileprovides information about why the build failed. For information about thesysmaster database, refer to Chapter 2, “The sysmaster Database.”

.conf.dbservernameThe .conf.dbservername file is created when you initialize the databaseserver. The onsnmp utility queries this file to find out the configuration statusof the database server. Do not delete this file.

IDS


core

coreThe core file contains a core dump caused by an assertion failure. Thedatabase server writes this file to the directory from which the databaseserver was invoked. For more information on monitoring for data inconsis-tency, see the chapter on consistency checking in the Administrator’s Guide.

Emergency Boot Files for ON-BarThe ON-Bar emergency boot files contain the information needed to performa cold restore, and are updated after every backup. For details, see the Backupand Restore Guide.

You can specify the location of the emergency boot files with theBAR_BOOT_DIR configuration parameter. The filenames for the emergencyboot files are as follows:

■ Bixbar_hostname.servernum (backup boot file)

■ Mixbar_hostname.servernum (merge boot file)

■ Rixbar_hostname.servernum (restore boot file) ♦

The filename for the Dynamic Server emergency boot file isixbar_hostname.servernum. ♦

gcore.xxxThe database server writes information about an assertion failure to thegcore.xxx file. The file is stored in the directory specified by the DUMPDIRconfiguration parameter. For more information on monitoring for data incon-sistency, see the chapter on consistency checking in the Administrator’s Guide.

illlsrra.xxThe illlsrra.xx files are shared libraries that the database server and somedatabase server utilities use. The shared libraries, if supported on yourplatform, are installed in $INFORMIXDIR/lib or %INFORMIXDIR%\lib.

XPS

IDS

UNIX


~/.informix

The naming convention of the Informix shared library filename is as follows:

illlsrra.xx

Symbolic links to these files are automatically created in /usr/lib when theproducts are installed on your computer.

Important: The symbolic links to the shared libraries in /usr/lib are automaticallycreated by the product installation procedures. However, if your $INFORMIXDIR isnot installed using the standard installation method (for example, your$INFORMIXDIR is NFS-mounted from another computer or node), you or yoursystem administrator might need to create manually the symbolic links of the sharedlibraries in /usr/lib. ♦

~/.informixThe ~/.informix file is the private-environment file. Users can create this fileand store it in their home directory. The Informix Guide to SQL: Referencediscusses the environment-configuration files.

informix.rcThe /informix.rc file is the environment-configuration file. You can use it to setenvironment variables for all users of Informix products. The Informix Guideto SQL: Reference discusses the environment-configuration files.

lll library class (for example, asf or smd)

s library subclass (d=DSA; s=standard)

rr major release number (for example, 07 or 08)

a library version ID (for example, a or b)

xx shared-library filename extension (for example, so)

UNIX

UNIX


INFORMIXTMP

INFORMIXTMPThe INFORMIXTMP directory is an internal database server directory. Duringinitialization, the database server creates this directory (if it does not existyet) for storing internal files that must be local and relatively safe fromdeletion. onsnmp uses the files in the INFORMIXTMP directory.

.inf.servicenameThe database server creates the .inf.servicename file if any DBSERVERNAMEor DBSERVERALIASES uses a shared-memory connection type. The databaseserver removes the file when you take the database server off-line. The nameof this file is derived from the servicename field of the sqlhosts file or registry.

The database server keeps information about client/server connections inthis file. You do not use the .inf.servicename file directly. You only need torecognize that it is a legitimate file when it appears in the INFORMIXTMPdirectory.

If this file is accidentally deleted, you must restart the database server.

.infos.dbservernameThe database server creates the .infos.dbservername file when you initializeshared memory and removes the file when you take the database server off-line. This file resides in $INFORMIXDIR/etc or %INFORMIXDIR%\etc. Thename of this file is derived from the DBSERVERNAME parameter in theONCONFIG configuration file.

The database server and onsnmp use the .infos.dbservername file fordatabase server discovery. The database server uses this file to attach toutilities such as onstat, so do not delete it.


.infxdirs

.infxdirsThe database server maintains an .infxdirs file in the INFORMIXTMPdirectory. This file contains a line for every INFORMIXDIR from which adatabase server has been launched. If you remove the .infxdirs file, onsnmpcannot discover any database servers until the next time you restart thedatabase server. Each time you restart the database server, it re-creates the.infxdirs file.

InstallServer.logThe database server creates the InstallServer.log during installation.

ISM CatalogISM creates the ISM catalog during the ism_startup initialization. The ISMcatalog records information about backup and restore save sets and aboutstorage volumes that the storage manager uses. The ISM catalog records arestored in the mm, index, and res files in the $INFORMIXDIR/ism or%ISMDIR%\ism directory. For more information, see the Informix StorageManager Administrator’s Guide.

ISM LogsISM creates several logs during ON-Bar backup and restore operations. Themessage window in the ISM Administrator GUI displays messages from theselogs.

For more information, see the Informix Storage Manager Administrator’s Guide.

Log Description

daemon.log ISM backend status

messages Operator alert messages

summary Additional ISM information

XPS

IDS, WIN NT


ISMversion

ISMversionThe ISMversion file, which is installed with the database server, identifies theISM version. Do not edit this file.

The Message LogThe database server writes status and error information to the message-logfile. You specify the filename and location of the message log with theMSGPATH configuration parameter. For more information, refer to“MSGPATH” on page 1-93.

onconfig.stdThe onconfig.std file serves as the template for creating the ONCONFIGconfiguration file. To use the template, copy it to another file and modify thevalues.

The onconfig.std file also serves as the template for single-coserverONCONFIG files that you create. ♦

Important: Do not modify onconfig.std. The database server uses values listed inthis file when those values are missing from the ONCONFIG file.

“Sample onconfig.std File” on page A-17 shows the contents of theonconfig.std file. For an overview, see the chapter on configuration param-eters in the Administrator’s Guide. For a comprehensive list of the ONCONFIGparameters, see Chapter 1, “Configuration Parameters.”

onconfig.xpsThe onconfig.xps file serves as the template for multiple-coserver ONCONFIGfiles that you create. To use the template, copy it into another file, and modifythe values.

“Sample onconfig.xps File” on page A-26 shows the contents of theonconfig.xps file. The Administrator’s Guide provides an overview of theadditional parameters required for a multiple-coserver configuration. For acomprehensive list of the ONCONFIG parameters, see Chapter 1, “Configu-ration Parameters.”

XPS

XPS


The ONCONFIG File

The ONCONFIG FileThe current configuration file is the %INFORMIXDIR%\etc\%ONCONFIG% or$INFORMIXDIR/etc/$ONCONFIG file. The database server uses theONCONFIG file during initialization.

If you start the database server with oninit and do not explicitly set theONCONFIG environment variable, the database server looks for configu-ration values in the onconfig.std file. If no onconfig.std file exists, thedatabase server returns the following error message:

WARNING: Cannot access configuration file $INFORMIXDIR/etc/$ONCONFIG.

For more information on the order of files where the database server looks forconfiguration values during initialization, refer the material on initializingthe database server in the Administrator’s Guide.

For more information on setting up your ONCONFIG file, refer to thematerials on installing and configuring the database server in the Adminis-trator’s Guide.

onconfigThe onconfig file is an optional file that you create in the $INFORMIXDIR/etcor %INFORMIXDIR%\etc directory. The onconfig file is the default configu-ration file if the ONCONFIG environment variable is not set. For moreinformation, refer to processing the configuration file in the Administrator’sGuide.

To create the onconfig file, you can copy onconfig.std or one of yourcustomized configuration files. For more information on setting up yourONCONFIG file, refer to installing and configuring the database server in theAdministrator’s Guide.


oncfg_servername.servernum

oncfg_servername.servernumThe database server creates the oncfg_servername.servernum file in the$INFORMIXDIR/etc or %INFORMIXDIR%\etc directory when you initializedisk space. The database server updates the file every time that you add ordelete a dbspace, a logical-log file, or a chunk. The database server uses theoncfg_servername.servernum file when it salvages logical-log files during awhole-system restore. The database server derives the name of this file fromthe values of the DBSERVERNAME and SERVERNUM parameters in theONCONFIG configuration file.

The database server uses the oncfg_servername.servernum files, so do notdelete them. For more information, refer to creating theoncfg_servername.servernum file in the Administrator’s Guide and the Backupand Restore Guide.

On Extended Parallel Server, the oncfg* filenames include the coserver ID:oncfg_servername.servernum.coserverid.

onsnmp.servernameThe onsnmp subagent uses this log file. For more information, see theInformix SNMP Subagent Guide. This log file is called onsnmp.servername onDynamic Server or onsnmp.servername.coservername on Extended ParallelServer.

onsrvapd.logThe onsrvapd daemon uses this log file. For more information, see theInformix SNMP Subagent Guide.

oper_deflt.arcThe oper_deflt.arc file contains default command qualifier values thatON-Archive uses. Your Archive and Backup Guide describes the oper_dflt.arcfile.

XPS

IDS

UNIX


PostInstall.tmp

Users can set the ARC_DEFAULT environment variable to point to a file thatcontains personal defaults that are different from the defaults in theoper_deflt.arc file.

PostInstall.tmpAfter the database server is installed, the installation server runs thepostinstall script and writes the output to the PostInstall.tmp file in the tmpdirectory. If you receive error messages after installation, review this file tosee what went wrong.

servicename.expThe database server creates a servicename.exp file on some platforms if anyDBSERVERNAME or DBSERVERALIASES uses a stream-pipe connection type.This file is used for handling expedited data, which occurs when the clientprogram issues sqlbreak() or the user enters CTRL-C. The database serverremoves the file when you take the database server off-line. The name of thisfile is derived from the servicename field of the sqlhosts file or registry.

You do not use the servicename.exp file directly. You only need to recognizethat it is a legitimate file when it appears in the INFORMIXTMP directory.

servicename.strThe database server creates the servicename.str file if any DBSERVERNAME orDBSERVERALIASES uses a stream-pipe connection type. The database serverremoves the file when you take the database server off-line. The name of thisfile is derived from the servicename field of the sqlhosts file or registry.

The database server keeps information about client/server connections inthis file. You do not use the .inf.servicename.str file directly. You only need torecognize that it is a legitimate file when it appears in the INFORMIXTMPdirectory.


XPS

XPS


shmem.xxx

shmem.xxxThe database server writes information about an assertion failure to theshmem.xxx file. The file is stored in the directory that the DUMPDIR configu-ration parameter specifies. For more information on monitoring for datainconsistency, see the chapter on consistency checking in the Administrator’sGuide.

sm_versions.stdThe sm_versions.std file is a template for the sm_versions file that youcreate. The sm_versions file contains a line identifying the current storage-manager version.

The storage manager uses the data in the sm_versions file (no .std suffix). Ifyou need to update the storage-manager version, you can edit thesm_versions file directly, run the ism_startup script. For more information,see the Backup and Restore Guide.

snmpd.logThe SNMP master agent, snmpdm uses this log file. For more information, seethe Informix SNMP Subagent Guide.

sqlhostsThe sqlhosts file is the connectivity file on UNIX platforms. It contains infor-mation that lets an Informix client connect to an Informix database server. Formore information on the sqlhosts file, see client/server communications inthe Administrator’s Guide. ♦

On Windows NT, the connectivity information is in theHKEY_LOCAL_MACHINE\SOFTWARE\Informix\SQLHOSTS key in theWindows registry. ♦

UNIX

UNIX

WIN NT


VP.servername.nnx

VP.servername.nnxThe database server creates the VP.servername.nnx file, if needed, when youinitialize shared memory. The name of this file comes from DBSERVERNAMEor DBSERVERALIASES in the ONCONFIG file, the VP number (nn), and aninternal identifier (x).

The database server keeps information about client/server connections in theVP.servername.nnx file. You do not use the file directly. You only need torecognize that it is a legitimate file.


xbsa.messagesThe xbsa.messages log contains XBSA library call information. ON-Bar andISM use XBSA to communicate with each other. Informix Technical Supportwould use the xbsa.messages log to diagnose problems with ON-Bar and ISMcommunications.

xcfg_servername.servernumThe database server creates the xcfg_servername.servernum.coserverid file,which contains information about coserver location and dbslice definitions.

XPS


Sample onconfig.std File

Sample onconfig.std FileThe following files are sample copies of the onconfig.std file. Some of thevalues might be different from the ones in your onconfig.std file becausesome values are platform dependent.

This onconfig.std file is for Dynamic Server.

#*******************************************************************************## INFORMIX SOFTWARE, INC.## Title:onconfig.std# Description: Informix Dynamic Server 2000 Configuration Parameters##*******************************************************************************

# Root Dbspace Configuration

ROOTNAME rootdbs # Root dbspace nameROOTPATH /dev/online_root # Path for device containing root dbspaceROOTOFFSET 0 # Offset of root dbspace into device (Kbytes)ROOTSIZE 30000 # Size of root dbspace (Kbytes)

# Disk Mirroring Configuration Parameters

MIRROR 0 # Mirroring flag (Yes = 1, No = 0)MIRRORPATH # Path for device containing mirrored rootMIRROROFFSET 0 # Offset into mirrored device (Kbytes)

# Physical Log Configuration

PHYSDBS rootdbs # Location (dbspace) of physical logPHYSFILE 2000 # Physical log file size (Kbytes)

# Logical Log Configuration

LOGFILES 6 # Number of logical log filesLOGSIZE 1500 # Logical log size (Kbytes)

# Diagnostics

MSGPATH /usr/informix/online.log # System message log file pathCONSOLE /dev/console # System console message pathALARMPROGRAM /usr/informix/etc/log_full.sh # Alarm program path

TBLSPACE_STATS 1 # Maintain tblspace statistics

IDS



# System Archive Tape DeviceTAPEDEV dev/tapedev # Tape device pathTAPEBLK 16 # Tape block size (Kbytes)TAPESIZE 10240 # Maximum amount of data to put on tape (Kbytes)

# Log Archive Tape Device

LTAPEDEV dev/tapedev # Log tape device pathLTAPEBLK 16 # Log tape block size (Kbytes)LTAPESIZE 10240 # Max amount of data to put on log tape (Kbytes)

# Optical

STAGEBLOB # Optical Subsystem staging area

# System Configuration

SERVERNUM 0 # Unique id corresponding to a database server instanceDBSERVERNAME # Name of default database serverDBSERVERALIASES # List of alternate dbservernamesNETTYPE # Override sqlhosts nettype parametersDEADLOCK_TIMEOUT 60 # Max time to wait of lock in distributed env.RESIDENT 0 # Forced residency flag (Yes = 1, No = 0)

MULTIPROCESSOR 0 # 0 for single-processor, 1 for multi-processorNUMCPUVPS 1 # Number of user (cpu) vpsSINGLE_CPU_VP 0 # If non-zero, limit number of cpu vps to one

NOAGE 0 # Process agingAFF_SPROC 0 # Affinity start processorAFF_NPROCS 0 # Affinity number of processors

# Shared Memory Parameters

LOCKS 2000 # Maximum number of locksBUFFERS 1000 # Maximum number of shared buffersNUMAIOVPS # Number of asynchronous I/O VPsPHYSBUFF 32 # Physical-log buffer size (Kbytes)LOGBUFF 32 # Logical-log buffer size (Kbytes)LOGSMAX 6 # Maximum number of logical-log filesCLEANERS 1 # Number of buffer cleaner processesSHMBASE # Shared memory base address (platform dependent)SHMVIRTSIZE 8000 # Initial virtual shared memory segment sizeSHMADD 8192 # Size of new shared memory segments (Kbytes)SHMTOTAL 0 # Total shared memory (Kbytes). 0=>unlimitedCKPTINTVL 300 # Check point interval (in seconds)LRUS 8 # Number of LRU queuesLRU_MAX_DIRTY 60 # LRU percent dirty begin cleaning limitLRU_MIN_DIRTY 50 # LRU percent dirty end cleaning limitLTXHWM 50 # Long transaction high water mark percentageLTXEHWM 60 # Long transaction high water markTXTIMEOUT 300 # Transaction timeout (in seconds)STACKSIZE 32 # Stack size (Kbytes)



# System Page Size

# BUFFSIZE - The database server no longer supports this configuration parameter.# To determine the page size used by the database server on your platform,# see the last line of output from the command, 'onstat -b'.

# Recovery Variables# OFF_RECVRY_THREADS:# Number of parallel worker threads during fast recovery or an offline restore.# ON_RECVRY_THREADS:# Number of parallel worker threads during an online restore.

OFF_RECVRY_THREADS 10 # Default number of offline worker threadsON_RECVRY_THREADS 1 # Default number of online worker threads

# Data Replication VariablesDRINTERVAL 30 # DR max time between DR buffer flushes (secs)DRTIMEOUT 30 # DR network timeout (in sec)DRLOSTFOUND /usr/informix/etc/dr.lostfound # DR lost+found file path

Enterprise Replication VariablesCDR_EVALTHREADS 1,2 # Evaluator threads (per-cpu-vp, additional)CDR_DSLOCKWAIT 5 # DS lockwait timeout (seconds)CDR_QUEUEMEN 4096 # Maximum amount of memory for any ER queue (Kbytes)CDR_LOGDELTA 30 # Percentage of log space allowed in queue memoryCDR_NUMCONNECT 16 # Expected connections per serverCDR_NIFRETRY 300 # Connection retry (seconds)CDR_NIFCOMPRESS 0 # Link level compression # (-1 = never, 0 = none, 9 = max)

# Backup/Restore VariablesBAR_ACT_LOG /tmp/bar_act.log # File for errors, warnings, and messagesBAR_MAX_BACKUP 0 # Number of processes to start for backup or restoreBAR_RETRY 1 # Number of times to retry failuresBAR_NB_XPORT_COUNT 10 # Number of transport buffersrBAR_XFER_BUF_SIZE 31 # Size of each transport bufferRESTARTABLE_RESTORE OFF # 1 = enables restartable restore, # 0 = turns off restartable restoreBAR_HISTORY 0 # ON-Bar message history levelBAR_PROGRESS_FREQ 0 # ON-Bar progress output intervalBAR_BSALIB_PATH /usr/lib/ibsad001.so # Full pathname of storage-manager

# XBSA shared library (platform dependent)# Informix Storage Manager VariablesISM_DATA_POOL ISMData # Default volume pool for spacesISM_LOG_POOL ISMLogs # Default volume pool for logical-log files

# Read Ahead VariablesRA_PAGES # Number of pages to attempt to read aheadRA_THRESHOLD # Number of pages left before next group



# DBSPACETEMP:# The list of dbspaces that the database server SQL engine will use to create temp# tables. If specified,it must be a colon-separated list of dbspaces that exist# when the database serveris brought on-line. If not specified, or if all dbspaces# specified are invalid, various ad hoc queries will create temporary files in /tmp# instead.

DBSPACETEMP # Default temp dbspaces

# DUMP*:# The following parameters control the type of diagnostics information which# is preserved when an unanticipated error condition (assertion failure) occurs# during database server operations.# For DUMPSHMEM, DUMPGCORE and DUMPCORE 1 means Yes, 0 means No.

DUMPDIR /tmp # Preserve diagnostics in this directoryDUMPSHMEM 1 # Dump a copy of shared memoryDUMPGCORE 0 # Dump a core image using 'gcore'DUMPCORE 0 # Dump a core image (Warning: this # aborts the database serverDUMPCNT 1 # Number of shared memory or gcore dumps # for a single user's session

# Index Fill Factor

FILLFACTOR 90 # Fill factor for building indexes

# Method for the database server to use when determining current time

USEOSTIME 0 # 0: use internal time (fast), # 1: get time from OS (slow)

# Parallel Database Queries (pdq)MAX_PDQPRIORITY 100 # Maximum allowed pdqpriorityDS_MAX_QUERIES # Maximum number of decision-support queriesDS_TOTAL_MEMORY # Decision-support memory (Kbytes)DS_MAX_SCANS 1048576 # Maximum number of decision-support scansDATASKIP # List of dbspaces to skip

# OPTCOMPIND# 0 => Nested loop joins are preferred (where possible) over sortmerge# joins and hash joins.# 1 => If the transaction isolation mode is not "repeatable read", optimizer# behaves as in (2) below. Otherwise it behaves as in (0) above.# 2 => Use costs regardless of the transaction isolation mode. Nested# loop joins are not necessarily preferred. Optimizer bases its# its decision purely on costs.OPTCOMPIND 2 # To hint the optimizerDIRECTIVES 1 # Optimizer DIRECTIVES (1 = ON, 0 = OFF)

ONDBSPACEDOWN 2 # Dbspace down option: 0 = CONTINUE, # 1 = ABORT, 2 = WAITLBU_PRESERVE 0 # Preserve last log for log backupOPCACHEMAX 0 # Maximum optical cache size (Kbytes)



HETERO_COMMIT 0 # Gateway participation in distributed transactions # 1 => Heterogeneous Commit is enabled

# 0 (or any other value) => Heterogeneous Commit is disabled

SBSPACENAME # Default smart large object space name i # f no sbspace specifiedSYSSBSPACENAME # Default smart large object space name for # statistics collection

BLOCKTIMEOUT 3600 # Default timeout for system blockSYSALARMPROGRAM /usr/informix/etc/evidence.sh # System alarm program path

OPT_GOAL -1 # Optimization goal: # -1 = ALL_ROWS (default), 0 = FIRST_ROW

ALLOW_NEWLINE 0 # embedded newlines # (Yes = 1, No = 0 or anything but 1)

# The following are default settings for enabling Java in the database.# Replace all occurrences of /usr/informix with $INFORMIXDIR.

#VPCLASS jvp,num=1 # Number of JVPs to start

JVPJAVAHOME /usr/java # JDK installation root directoryJVPHOME /usr/informix/extend/krakatoa # Krakatoa installation directory

JVPPROPFILE /usr/informix/extend/krakatoa/.jvpprops # JVP property fileJVPLOGFILE /usr/informix/jvp.log # JVP log file.

JDKVERSION 1.1 # JDK version (1.1 vs. 1.2)JVMTHREAD native # Java VM thread type (green or native)

# The path from JVPJAVAHOME to the JDK librariesJVPJAVALIB /lib/sparc/native_threads

# The JDK libraries to use for the Java VM (use _g version for debugging)

# JVPJAVAVM java:net:zip:mmedia:jpeg:sysresourceJVPJAVAVM java_g:net_g:zip_g:mmedia_g:jpeg_g:sysresource_g

# Class path to use upon Java VM start-up (use _g version for debugging)

# JVPCLASSPATH/usr/informix/extend/krakatoa/krakatoa.jar:/usr/informix/extend/krakatoa/jdbc.jarJVPCLASSPATH/usr/informix/extend/krakatoa/krakatoa_g.jar:/usr/informix/extend/krakatoa/jdbc_g.jar

♦



This onconfig.std file is for Extended Parallel Server.

#*******************************************************************************## INFORMIX SOFTWARE, INC.## Title: onconfig.std# Sccsid: @(#)onconfig.std 9.24 9/30/93 10:04:32# Description: Extended Parallel Server Configuration Parameters##**************************************************************************


ROOTNAME rootdbs # Root dbspace nameROOTPATH /dev/online_root # Path for device containing root dbspaceROOTOFFSET 0 # Offset of root dbspace into device (Kbytes)

# On some UNIX platforms, it is an error to set ROOTOFFSET to 0.# When this parameter is incorrectly set, you might have to# reinitialize the disk space and reload the data before# resuming proper operation of the database server.# Always check the machine notes to get machine-specific information# before setting your configuration parameters.

ROOTSIZE 20000 # Size of root dbspace (Kbytes)




PHYSDBS rootdbs # Location (dbspace) of physical logPHYSFILE 1500 # Physical log file size (Kbytes)



# Configuration Manager

CONFIGSIZE STANDARD # Amt of rootdbs space to reserve for CM data # Only applies to CM coservers

XPS



# Diagnostics

MSGPATH /usr/informix/online.log # System message log file pathCONSOLE /dev/console # System console message pathALARMPROGRAM # Alarm program pathSYSALARMPROGRAM evidence.sh # System Alarm program path (a relative path # is expanded to $INFORMIXDIR/etc/<path>)


SERVERNUM 0 # Unique id corresponding to a DB server instanceDBSERVERNAME # Name of default database serverDBSERVERALIASES # List of alternate dbservernamesNETTYPE # Override sqlhosts nettype parametersRESIDENT 0 # Forced residency flag: All = -1,No = 0, or > 0



PAGESIZE 4096 # System pagesize# Shared Memory Parameters

LOCKS 2000 # Maximum number of locksBUFFERS 100 # Maximum number of shared buffersNUMAIOVPS # Number of IO vpsNUMFIFOVPS 2 # Number of FIFO vpsPHYSBUFF 32 # Physical log buffer size (Kbytes)LOGBUFF 32 # Logical log buffer size (Kbytes)LOGSMAX 6 # Maximum number of logical-log filesCLEANERS 1 # Number of buffer cleaner processesSHMBASE SHMBASE_DIST # Shared memory base addressSHMVIRTSIZE 8192 # Initial virtual shared memory segment sizeSHMADD 8192 # Size of new shared memory segments (Kbytes)SHMTOTAL 0 # Total shared memory (Kbytes). 0=>unlimitedCKPTINTVL 300 # Check point interval (in sec)LRUS 8 # Number of LRU queuesLRU_MAX_DIRTY 60 # LRU percent dirty begin cleaning limitLRU_MIN_DIRTY 50 # LRU percent dirty end cleaning limitLTXHWM 50 # Long transaction high water mark percentageLTXEHWM 60 # Long transaction high water mark (exclusive)STACKSIZE 32 # Stack size (Kbytes)

# System Page Size# BUFFSIZE - The database server no longer supports this configuration parameter.# To determine the page size used on your platform,# see the last line of output from the command: 'onstat -b'.



# Recovery Variables# OFF_RECVRY_THREADS:# Number of parallel worker threads during fast recovery or an off-line restore.# ON_RECVRY_THREADS:# Number of parallel worker threads during an on-line restore operation

OFF_RECVRY_THREADS 10 # Default number of off-line worker threadsON_RECVRY_THREADS 1 # Default number of on-line worker threads

# Read Ahead VariablesRA_PAGES # Number of pages to attempt to read aheadRA_THRESHOLD # Number of pages left before next groupIDX_RA_PAGES # Number of index pages to attempt to read aheadIDX_RA_THRESHOLD # Number of index pages left before next group

# DBSPACETEMP:# This is the list of dbspaces# that the SQL Engine will use to create temp tables, etc.# The list can be specified using various preset "sets" that are# ALL - all dbspaces can be used for temp files# TEMP - use only temporary dbspaces for temp files# NOTCRITICAL - use only noncritical dbspaces for temp files# Critical dbspaces are the root dbspaces and dbspaces containing# log files.# The list can also be specified as an explicit list of dbspaces/dbslices# that exist when the database server is brought on-line. If not specified,# or if all dbspaces specified are invalid, various ad hoc queries will create# temporary files in /tmp instead. If a dbspace in this list is# added to the system at a later point in time, it is automatically added# to the list of dbspaces that can be used for temp purposes.

DBSPACETEMP NOTCRITICAL # Default temp dbspaces

# DUMP*:# The following parameters control the type of diagnostics information which# is preserved when an unanticipated error condition (assertion failure) occurs# during database server operations.# For DUMPSHMEM, DUMPGCORE, and DUMPCORE 1 means Yes, 0 means No.

DUMPDIR /tmp # Preserve diagnostics in this directoryDUMPSHMEM 1 # Dump a copy of shared memoryDUMPGCORE 0 # Dump a core image using 'gcore'DUMPCORE 0 # Dump a core image (Warning: aborts XPS)DUMPCNT 1 # Number of shared memory or gcore dumps for # a single user's session


# method for the database server to use when determining current timeUSEOSTIME 0 # 0: use internal time (fast), 1: get time from OS (slow)



# Parallel Database Queries (pdq)PDQPRIORITY 0 # Degree of parallelism: 0 => OFF, 1 => LOW, # -2 => HIGH, max of 100.MAX_PDQPRIORITY 100 # Maximum allowed pdqpriorityDS_ADM_POLICY FAIR # Decision-support admission and allocation policy # FAIR: service queries based on scheduling level # but preferring lower pdqpriority queries, # STRICT: service queries based on scheduling level # (highest before lowest) and FCFS within each levelDS_MAX_QUERIES # Maximum number of decision-support queriesDS_TOTAL_MEMORY # Decision-support memory (Kbytes)DS_MAX_SCANS 1048576 # Maximum number of decision-support scansDATASKIP # List of dbspaces to skip

ONDBSPACEDOWN 2 # Dbspace down option: 0 = CONTINUE, 1 = ABORT, 2 = WAIT

CAMPORT 10300 # start of UDP port range used to monitor coserversPLAN_MONITORING 1 # Turns on Plan Monitoring for the Query Monitor. # To leave Plan Monitoring inactive, set it to 0.

# Backup/Restore VariablesBAR_ACT_LOG /tmp/bar_act.log # File for errors, warnings, and messagesBAR_BOOT_DIR /usr/informix/etcBAR_RETRY 0 # Number of times to retry failuresBAR_WORKER_MAX 0 # Do not auto-start onbar workersBAR_IDLE_TIMEOUT 0 # Never timeout onbar workersBAR_XPORT_COUNT 10 # Number of transport buffers per onbar workerBAR_XFER_BUFSIZE 8 # Size of each transport bufferBAR_BSALIB_PATH /usr/lib/ibsad001.so # Full pathname of storage-manager # XBSA shared library (platform dependent)BAR_HISTORY 0 # ON-Bar message history levelBAR_PROGRESS_FREQ 0 # ON-Bar progress output intervalISM_DATA_POOL ISMData # Default volume pool for spacesISM_LOG_POOL ISMLogs # Default volume pool for logical log files

LOG_BACKUP_MODE MANUAL # When to back up logical log files: # CONT - backup as soon as the file fills # MANUAL - user must perform log backups # NONE - do not back up logs and re-use them # as soon as they fill. Use of NONE is not # recommended as data will be lost if the # database server must be restored.

♦


Sample onconfig.xps File

Sample onconfig.xps FileThe following file is a sample copy of the onconfig.xps file for ExtendedParallel Server. A few of the values might be different from the ones in youronconfig.xps file because some values are platform dependent.

#*******************************************************************************## INFORMIX SOFTWARE, INC.## Title:onconfig.xps# Description: Extended Parallel Server Configuration Parameters##*******************************************************************************


ROOTSLICE rootdbs # Root dbspace nameROOTPATH /dev/online_root.%c # Path for device containing root dbspaceROOTOFFSET 0 # Offset of root dbspace into device (Kbytes)

# On some UNIX platforms, it is an error to set ROOTOFFSET to 0.# When this parameter is incorrectly set, you might have to# reinitialize the disk space and reload the data before# resuming proper operation of the database server.# Always check the machine notes to get machine-specific information# before setting your configuration parameters.

ROOTSIZE 20000 # Size of root dbspace (Kbytes)




PHYSSLICE rootdbs # Location (dbslice) of physical logPHYSFILE 1500 # Physical log file size (Kbytes)



# Configuration Manager

CONFIGSIZE STANDARD # Amt of rootdbs space to reserve for CM data # Only applies to CM coservers

XPS



# Diagnostics

MSGPATH /usr/informix/online.log # System message log file pathCONSOLE /dev/console # System console message pathALARMPROGRAM # Alarm program pathSYSALARMPROGRAM evidence.sh # System Alarm program path (a relative path # is expanded to $INFORMIXDIR/etc/<path>)


SERVERNUM 0 # Unique ID corresponding to a database serverinstanceDBSERVERNAME xps # Name of default database serverDBSERVERALIASES # List of alternate dbservernamesNETTYPE # Override sqlhosts nettype parametersRESIDENT 0 # Forced residency flag: All = -1, No = 0, or >0



PAGESIZE 4096 # System pagesize

# Shared Memory ParametersLOCKS 2000 # Maximum number of locksBUFFERS 1000 # Maximum number of shared buffersNUMAIOVPS # Number of IO vpsNUMFIFOVPS 2 # Number of FIFO vpsPHYSBUFF 32 # Physical log buffer size (Kbytes)LOGBUFF 32 # Logical log buffer size (Kbytes)LOGSMAX 6 # Maximum number of logical log filesCLEANERS 1 # Number of buffer cleaner processesSHMBASE SHMBASE_DIST # Shared memory base addressSHMVIRTSIZE 8192 # initial virtual shared memory segment sizeSHMADD 8192 # Size of new shared memory segments (Kbytes)SHMTOTAL 0 # Total shared memory (Kbytes). 0=>unlimitedCKPTINTVL 300 # Check point interval (in sec)LRUS 8 # Number of LRU queuesLRU_MAX_DIRTY 60 # LRU percent dirty begin cleaning limitLRU_MIN_DIRTY 50 # LRU percent dirty end cleaning limitLTXHWM 50 # Long transaction high water mark percentageLTXEHWM 60 # Long transaction high water mark (exclusive)STACKSIZE 32 # Stack size (Kbytes)

# System Page Size# BUFFSIZE - The database server no longer supports this configuration parameter.# To determine the page size used on your platform,# see the last line of output from the command: 'onstat -b'.



# Recovery Variables# OFF_RECVRY_THREADS:# Number of parallel worker threads during fast recovery or an off-line restore.# ON_RECVRY_THREADS:# Number of parallel worker threads during an on-line restore operation

OFF_RECVRY_THREADS 10 # Default number of off-line worker threadsON_RECVRY_THREADS 1 # Default number of on-line worker threads

# Read Ahead VariablesRA_PAGES # Number of pages to attempt to read aheadRA_THRESHOLD # Number of pages left before next groupIDX_RA_PAGES # Number of index pages to attempt to read aheadIDX_RA_THRESHOLD # Number of index pages left before next group

# DBSPACETEMP:# This is the list of dbspaces# that the SQL engine will use to create temp tables.# The list can be specified using various preset "sets" that are# ALL - all dbspaces can be used for temp files# TEMP - use only temporary dbspaces for temp files# NOTCRITICAL - use only noncritical dbspaces for temp files.# Critical dbspaces are the rootdbspaces and dbspaces containing# log files.# The list can also be specified as an explicit list of dbspaces/dbslices# that exist when the database serfer is brought on-line. If not specified,# or if all dbspaces specified are invalid, various ad hoc queries will create# temporary files in /tmp instead. If a dbspaces in this list is# added to the system at a later point in time, it is automatically added# to the list of dbspaces that can be used for temp purposes.

DBSPACETEMP NOTCRITICAL # Default temp dbspaces# DUMP*:# The following parameters control the type of diagnostics information which# is preserved when an unanticipated error condition (assertion failure) occurs# during database server operations.# For DUMPSHMEM, DUMPGCORE and DUMPCORE 1 means Yes, 0 means No.

DUMPDIR /tmp # Preserve diagnostics in this directoryDUMPSHMEM 1 # Dump a copy of shared memoryDUMPGCORE 0 # Dump a core image using 'gcore'DUMPCORE 0 # Dump a core image (Warning:this aborts db server)DUMPCNT 1 # Number of shared memory or gcore dumps for # a single user's session


# method for the database server to use when determining current timeUSEOSTIME 0 # 0: use internal time (fast), 1: get time from OS (slow)



# Parallel Database Queries (pdq)PDQPRIORITY 0 # Degree of parallelism: 0 => OFF, 1 => LOW, # -2 => HIGH, max of 100.MAX_PDQPRIORITY 100 # Maximum allowed pdqprioirityDS_ADM_POLICY FAIR # Decision-support admission and allocation policy # FAIR: service queries based on scheduling level # but preferring lower pdqpriority queries, # STRICT: service queries based on scheduling level # (highest before lowest) and FCFS within each levelDS_MAX_QUERIES # Maximum number of decision-support queriesDS_TOTAL_MEMORY # Decision-support memory (Kbytes)DS_MAX_SCANS 1048576 # Maximum number of decision-support scansDATASKIP # List of dbspaces to skip

ONDBSPACEDOWN 2 # Dbspace down option: 0 = CONTINUE, 1 = ABORT, 2 = WAIT

CAMPORT 10300 # start of UDP port range used to monitor coserversPLAN_MONITORING 1 # Turns on Plan Monitoring for the Query Monitor. # To leave Plan Monitoring inactive, set it to 0.

# Backup/Restore variablesBAR_ACT_LOG /tmp/bar_act.log # File for errors, warnings, and messagesBAR_BOOT_DIR /usr/informix/etcBAR_RETRY 0 # Number of times to retry failuresBAR_XPORT_COUNT 10 # Number of transport buffers per workerBAR_XFER_BUFSIZE 8 # Size of each transport bufferBAR_HISTORY 0 # ON-Bar message history levelBAR_PROGRESS_FREQ 0 # ON-Bar progress output interval

LOG_BACKUP_MODE MANUAL # When to backup logical log files: # CONT - backup as soon as the file fills # MANUAL - user must perform log backups # NONE - do not backup logs and re-use them # as soon as they fill. Use of # NONE is not recommended as data # will belost if the database server # must be restored# Storage Manager instancesBAR_SM 1 # Storage manager IDBAR_SM_NAME # Storage manager nameBAR_WORKER_COSVR 1 # Storage manager is located on coserver 1BAR_DBS_COSVR 1 # Route dbspaces from this coserver to this # storage-manager instanceBAR_LOG_COSVR 1 # Route logical log files from this coserver to this # storage-manager instanceBAR_WORKER_MAX 0 # Number of backup/restore objects this storage # manager can support concurrentlyBAR_IDLE_TIMEOUT 0 # Number of idle minutes before an onbar_w # process is stoppedBAR_BSALIB_PATH /usr/lib/ibsad001.so # full pathname of storage-manager # XBSA shared library (platform dependent)ISM_DATA_POOL ISMData # Default volume pool for spacesISM_LOG_POOL ISMLogs # Default volume pool for logical log filesEND



COSERVER 1NODE node1END

COSERVER 2NODE node2END

♦


BAppendix

Trapping Errors

Occasionally, a series of events causes the database server toreturn unexpected error codes. If you do not have the appro-priate diagnostic tools in place when these events occur, it mightbe difficult for you to determine the cause of these errors. Thissection discusses the following diagnostic tools:

■ onmode -I

■ tracepoints ♦■ onclean utility ♦

Collecting DiagnosticsTo help collect additional diagnostics, you can use onmode -I toinstruct the database server to perform the diagnostics collectionprocedures that the Administrator’s Guide describes. To useonmode -I when you encounter an error number, supply theiserrno and an optional session ID. The -I option is just one ofmany onmode options. For more information about onmode,see “onmode: Change Mode and Shared Memory” on page 3-37.

IDS

XPS

Creating Tracepoints

Syntax

Whenever the database server sets iserrno to this value, the correspondingdiagnostics events produce an af.* file that you can fax or email to InformixTechnical Support.

Creating TracepointsTracepoints are useful in debugging user-defined routines. You can create auser-defined tracepoint to send special information about the currentexecution state of a user-defined routine.

Each tracepoint has the following parts:

■ A trace class groups related tracepoints together so that they can beturned on or off at the same time.

You can either use the built-in trace class called _myErrors or createyour own. To create your own trace class, you insert rows into thesystraceclasses system catalog table.

■ A trace message is the text that the database server sends to thetracing-output file.

You can store internationalized trace messages in the systracemsgssystem catalog table.

■ A tracepoint threshold determines when the tracepoint executes.

Element Purpose Key Considerations-I iserrno Error number of the error for which you want to collect diagnostic

informationNone.

sid Session ID of the session for which you want to collect diagnosticinformation

None.

iserrnoonmode -I

sid

,

IDS

B-2 Informix Administrator’s Reference

The onclean Utility

By default, the database server puts all trace messages in the trace-output filein the tmp directory with the following filename:

session_num.trc

For more information on tracing user-defined routines, see the DataBlade APIProgrammer’s Manual.

The onclean UtilityThe onclean utility allows you to clean up resources (shared memory,semaphores, and processes) and shut down the database server. You must beuser root or informix to execute onclean.

Syntax

UsageSpecify onclean or onclean -v to remove resources when all the coservers areoff-line. Specify onclean -k to remove resources if one or more coservers arerunning.

XPS

Element Purpose Restrictions-v Displays messages about what onclean is

removing. If you do not specify -v, you seeno output unless an error occurs.

None.

-k Kills all the processes, semaphores, andshared-memory segments on this coservereven if it is running.

You can use the -k option when the databaseserver is on-line or off-line.

onclean

-v -k

Trapping Errors B-3

The onclean Utility

Use onclean to clean up one or more coservers that fail to respond to normalshutdown commands (onmode -yuk or onmode -ky), or when you cannotrestart the database server. Perhaps the database server shut down in anuncontrolled way and cannot recover, or it is hung. If the database server failsto restart, the old instance of the database server still has the shared-memorysegment.

Check the message log to see if the database server shut down abnormally.

Warning: Do not use onclean to perform a normal shut down of the database server.The onclean utility kills all processes and removes all shared-memory segments andsemaphores that are recorded in the /sqldist/etc/.conf file. Transactions andprocesses fail to complete, and user sessions are disconnected abruptly. However, thedatabase server rolls back transactions when it comes back up.

To shut down the database server with onclean

If you cannot shut down the database server with onmode -yuk oronmode -ky, follow these steps:

1. Execute the xctl onclean command.

2. If onclean cannot clean up any of the coservers but reports that theyare still up, try shutting down those coservers with the onmodecommand.

3. Issue the UNIX ipcs and ps commands to determine whether userinformix still owns system resources. If ipcs displays shared-memory segments and semaphores, or if ps displays processes, issuethe xctl onclean -k command to shut down all the coservers.

If the onclean command successfully cleans up the coservers, it issues returncode 0. If you use the -v option, onclean displays messages on the screenabout which resources it is trying to remove, as the following example shows:

looking for shmem key 5266c802looking for semaphore ID 21168129

Coserver was shut down cleanly

If no error messages display, it means the resources were successfullyremoved. You can write a UNIX script to test the return codes.

B-4 Informix Administrator’s Reference

The onclean Utility

If onclean is unsuccessful, one of the following error messages displays, andreturn code 1 is issued:

The coserver is still up, use onmode or "onclean -k"

Must be user informix or root to run this program

INFORMIXDIR env var not set

open of .conf.* filename failed

unknown option: -xusage: onclean [-v] [-k]

-v verbose, display full info while cleaning -k kill coserver if still running

If onclean encounters an operating-system error while it attempts to removea process, semaphore, or shared-memory segment, it reports the name of thesystem call that failed and its error code and issues return code 2.

Examples of oncleanThe following command kills only the coserver to which yourINFORMIXSERVER environment variable is set (usually coserver 1) anddisplays verbose output messages:

onclean -v -k

Use the xctl and onclean commands to kill coserver eds.3 only. The othercoservers might still have processes executing. If killing one coserver doesnot solve the database server problem, try killing all of the coservers.

xctl -C eds.3 onclean -k

The following command kills and cleans up all the coservers on your systemwhen the database server is off-line:

xctl onclean

The following command kills and cleans up all the coservers on your systemwhether or not they are running:

xctl onclean -k

Trapping Errors B-5

CAppendix

Thread SuspensionXPS

For increased reliability, in certain specific circumstances,Extended Parallel Server can suspend a thread that has failed anassertion instead of shutting down the entire database server.

Thread suspension is part of the fault isolation strategy that thethe database server uses. If a problem thread is isolated, the otherthreads in the process can continue their work.

In addition to increasing database server stability, this featureimproves problem diagnostics. Because the suspended threadstill exists, you can examine it to help diagnose the problem.

For more information on threads, see the chapter on paralleldatabase queries in your Performance Guide.

When a Thread Can Be Suspended

When a Thread Can Be SuspendedWhen a thread fails, the database server can perform a set of tests todetermine whether it can safely suspend the thread. The thread must meetthese requirements:

■ It must not be a member of a class of threads that are critical to thedatabase server. For example, secondary session threads (x_exec_*)are critical to database server operation and cannot be suspended,but parallel sort threads (psortproc) are not critical and can besuspended.

■ It must not be holding a shared resource, such as a mutex.

■ It must not be in a critical section.

If the thread meets these requirements, the database server can suspend it.When the database server suspends a thread, it also rolls back any work thatthe thread has performed and sets appropriate alarms.

If the suspended thread is the primary session thread of the client, such as thesqlexec or onutil thread, the client is disconnected. If the suspended threadis not the primary session thread, the client remains connected to thedatabase server and can start a new transaction. If the suspended thread wasprocessing a transaction, the transaction is rolled back globally after thethread is suspended.

The client receives the following two error messages.

If the database server cannot suspend a thread that has failed an assertion, itwrites an appropriate message to the message log before it shuts down.

Number Message

-959 The current transaction has been rolled back due to aninternal error.

-172 ISAM error: Unexpected internal error.

C-2 Informix Administrator’s Reference

Finding Out If Threads Are Suspended

For information about identifying threads that have been suspended andremoved, refer to the examples of onstat output in “Examples of SuspendedThread Output” on page C-3. For information about what to do if processesincur suspended threads, see “Reporting and Clearing Suspended Threads”on page C-5.

Finding Out If Threads Are SuspendedTo find out if threads are suspended, use one or all of these methods:

■ Examine the message log for suspended-thread alarm messages.

■ Run onstat -u.

■ Run onstat -g ath.

■ Run onstat -g con.

When you know the number of the session that spawned the suspendedthread, you can also run onstat -g ses session_number.

Examples of Suspended Thread Output

The following output examples show a suspended thread. In all output, theword defunct marks the suspended thread.

The onstat -u output shows the following user-thread information:

Userthreadsaddress flags sessid user tty wait tout locks nreads nwritesb3a4018 ---P--D 9 root - 0 0 0 40 21...b3a7244 DEFUNCT 18 informix - - - - - -14 active, 128 total, 15 maximum concurrent

The onstat -g ath output shows the following list of threads:

Threads:tid tcb rstcb prty status vp-class name2 b336730 0 2 running 2adm adminthd...45 b93b670 b3a6a8c 2 sleeping secs: 27 1cpu bum_sched47 b93be88 0 2 yield forever 1cpu bum_rcv52 b990278 b3a66b0 2 cond wait sm_read 1cpu sqlexec_1.1553 b9906b8 b3a6e68 2 yield forever 1cpu x_exec_1.1554 b990c68 b3a7244 2 cond wait defunct 1cpu x_update_0

Thread Suspension C-3

Finding Out If Threads Are Suspended

The onstat -g con output shows the following waiting conditions:

Conditions with waiters:cid addr name waiter waittime271 b990230 sm_read 52 105273 b990f70 defunct 54 110

When you run onstat -g ses 18 to examine session 18, you see the followingoutput:

local #RSAM total usedsessid sessid user tty pid hostname threads memory memory1.15 18 informix - 8925 - 2 90112 61592

tid tcb rstcb flags curstk status name53 b9906b8 b3a6e68 ---P--- 912 yield forever x_exec_1.1554 b990c68 b3a7244 DEFUNCT 5560 cond wait(defunct) x_update_0

Memory pools count 1name class addr totalsize freesize #allocfrag #freefrag18 V ba85018 90112 28520 180 10

name free used name free usedoverhead 0 128 scb 0 96...sqtcb 0 1016 fragman 0 1232

Sess SQL Current Iso Lock SQL ISAM F.E.Id Stmt type Database Lvl Mode ERR ERR Vers1.15 - ts_test_db CR Not Wait 0 0 8.30

No current SQL statement.

Examples of Output After the Suspended Thread Exits

After the session that spawned the suspended thread exits, you see thefollowing output for onstat -u, which shows that no session is associatedwith the suspended thread:

Userthreadsaddress flags sessid user tty wait tout locks nreads nwritesb3a4018 ---P--D 9 root - 0 0 0 40 21...b3a7244 DEFUNCT - informix - - - - - -12 active, 128 total, 15 maximum concurrent

For more information on these onstat options, see the chapter on theResource Grant Manager in your Performance Guide and “onstat: MonitorDatabase Server Operation” on page 3-88.

C-4 Informix Administrator’s Reference

Reporting and Clearing Suspended Threads

Reporting and Clearing Suspended ThreadsAny assertion failure that results in a suspended thread is a serious error.Report information about the context of the suspended threads to InformixTechnical Support as soon as possible.

Be prepared to provide the assertion-failure file that the database servergenerates. The path to this file is recorded in the database server message logas part of the message that reports the suspended thread.

To clear suspended threads, shut down and restart the database server.

Thread Suspension C-5

DAppendix

Event Alarms

The database server provides a mechanism for automaticallytriggering administrative actions based on an event that occursin the database server environment. This mechanism is theevent-alarm feature. Events can be informative (for example,Backup Complete) or can indicate an error condition thatrequires your attention (for example, Unable to AllocateMemory).

Using ALARMPROGRAM to Capture EventsTo use the event-alarm feature, set the ALARMPROGRAM config-uration parameter to the full pathname of an executable file thatperforms the necessary administrative actions. You mustprovide this executable file. It can be a shell script or binaryprogram. When any of the events in a predefined set occur, thedatabase server invokes this executable file and passes it theevent-alarm parameters (see Figure D-1 on page D-2). Theexecutable file must be written to accept these parameters.

Some of the events that the database server reports to themessage log cause it to invoke the alarm program. The classmessages indicate the events that the database server reports.

The database server reports a nonzero exit code in the messagelog. In the alarm program, set the EXIT_STATUS variable to 0 forsuccessful completion and to another number for a failure.

Event-Alarm Parameters

For example, if a thread attempts to acquire a lock, but the maximum numberof locks that LOCKS specifies has already been reached, the database serverwrites the following message to the message log:

10:37:22 Checkpoint Completed: duration was 0 seconds.10:51:08 Lock table overflow - user id 30032, rstcb 1013226410:51:10 Lock table overflow - user id 30032, rstcb 1013226410:51:12 Checkpoint Completed: duration was 1 seconds.

If you set ALARMPROGRAM to the pathname of an alarm program, thedatabase server passes the following arguments to your alarm program:

321Database server resource overflow: 'Locks'.Lock table overflow - user id 30032, rstcb 10132264

In this example, the database server does not pass a value for a see-also file.

Event-Alarm ParametersFigure D-1 lists the event-alarm parameters.

Figure D-1Event-Alarm Parameters

Parameter Type

Event severity (See Figure D-2 for values.) integer

Event class ID (See Figure D-3 for values.) integer

Event class message (See Figure D-3 for IDSmessages or Figure D-4 for XPS messages.)

string

Event specific message (IDS)Tag ID (XPS)

string

Event see-also file string

D-2 Informix Administrator’s Reference

Event Severity

Event SeverityThe first parameter passed to the alarm program is the event-severity code.All events reported to the message log have one of the severity codes listedin Figure D-2. Message-log events that have severity 1 do not cause thedatabase server to invoke the alarm program.

Figure D-2Event-Severity Codes

Event Class IDAn event class ID is an integer that the database server substitutes as thesecond parameter in your alarm program. Each event class ID is associatedwith one of the events that causes the database server to run your alarmprogram.

Severity Description

1 Not noteworthy. The event is not reported to the alarm program (forexample, date change in the message log).

2 Information. No error has occurred, but some routine event completedsuccessfully (for example, checkpoint or log backup completed).

3 Attention. This event does not compromise data or prevent the use of thesystem; however, it warrants attention (for example, one chunk of amirrored pair goes down).

4 Emergency. Something unexpected occurred that might compromisedata or access to data (assertion failure, or oncheck reports data corrupt).Take action immediately.

5 Fatal. Something unexpected occurred and caused the database server tofail.

Event Alarms D-3

Class Message

Class MessageA class message is the text of the message that the database server substitutesfor the third parameter of your alarm program when an event causes thedatabase server to run your alarm program. The class messages are differentfor Dynamic Server and Extended Parallel Server.

Specific MessagesThe database server substitutes additional information for the fourthparameter of your alarm program. In general, the text of this message is thatof the message written to the message log for the event.

Tag IDEach alarm contains a tag ID to identify it.

See Also PathsFor some events, the database server writes additional information to a filewhen the event occurs. The pathname in this context refers to the pathnameof the file where the database server writes the additional information.

Event Alarms on Dynamic ServerFigure D-3 on page D-5 shows the class IDs and class messages for alarms onDynamic Server. The first column lists the class IDs that identify each alarmand the second column lists the class messages. For more information aboutsetting the ALARMPROGRAM parameter, which controls alarms, see“ALARMPROGRAM on Dynamic Server” on page 1-22.

IDS

XPS

IDS


Event Alarms on Dynamic Server

Figure D-3Event Alarms on Dynamic Server

Class ID Class Message

1 Table failure: '%s' (dbsname:"owner".tabname)

2 Index failure: '%s' (dbsname:"owner".tabname-idxname)

3 Blob failure: '%s' (dbsname:"owner".tabname)

4 Chunk is off-line, mirror is active: %ld (chunk number)

5 Dbspace is off-line: '%s' (dbspace name)

6 Internal subsystem failure: '%s'

7 Database server initialization failure

8 Physical restore failed

9 Physical recovery failed

10 Logical recovery failed

11 Cannot open chunk: '%s' (pathname)

12 Cannot open dbspace: '%s' (dbspace name)

13 Performance improvement possible

14 Database failure. '%s' (database name)

15 High-availability data-replication failure (IDS)

16 Backup completed: '%s' (dbspace list)

17 Backup aborted: '%s' (dbspace list)

18 Log backup completed: %ld (log number)

19 Log backup aborted: %ld (log number)

20 Logical logs are full -- Backup is needed

21 Database server resource overflow: '%s' (resource name)

22 Long transaction detected

(1 of 2)

Event Alarms D-5

Alarms on Extended Parallel Server

Alarms on Extended Parallel ServerFigure D-4 shows the class IDs, tag IDs, and class messages for alarms onExtended Parallel Server. Some class IDs do not have an associated tag ID.The combination of the class and tag IDs identify each alarm.

The database server generates an alarm when the database server modechanges. For more information about setting the ALARMPROGRAMparameter, which controls alarms, see “ALARMPROGRAM on ExtendedParallel Server” on page 1-24.

Figure D-4Alarms on Extended Parallel Server

23 Logical log '%ld' (number) complete

24 Unable to allocate memory

N/A Chunk (storage) failure

N/A Data capacity

N/A Logical log capacity

N/A Maximum locks

N/A Maximum capacity

N/A Maximum sessions

Class ID Tag ID Class Message

1 1 Current log is full

1 2 All logs are full

2 1 Dbspace backup completed

2 2 Log backup completed

(1 of 2)

Class ID Class Message

(2 of 2)

XPS


Alarms on Extended Parallel Server

3 1 Dbspace backup failed

3 2 Log backup failed

4 0 Database server is initializing

4 1 Database server mode changed to quiescent

4 2 Database server in micro-kernel mode

4 3 Database server in fast recovery mode

4 4 Database server performing a backup

4 5 Database server is shutting down

4 6 Database server is on-line

4 7 Database server is aborting

4 8 Database server is terminating

5 1 Preconfigured limit hit (such as too many locks ortransactions)

5 2 Long transaction high-water mark hit

5 3 Database server is out of memory

6 Sub-system failure

7 1 Corrupt table

7 2 Corrupt index

7 3 Corrupt simple large object

8 1 Device problem: chunk problem

8 2 Device problem: dbspace problem

10 Performance improvement possible

12 Error occurred during database server initialization

Class ID Tag ID Class Message

(2 of 2)

Event Alarms D-7

@

Index

O QCA B D E F G H I J K L M N P R S T U V W X Y Z

Index

Numerics64-bit addressing

and buffer pool 1-26and locks 1-70and LRU queues 1-77and maximum queries 1-52and memory 1-134, 1-137

Aac_config.std file A-6AC_MSGPATH parameter 1-19ac_msg.log file A-5AC_STORAGE parameter 1-19AC_VERBOSE parameter 1-19ADDCHK logical-log record 6-8ADDDBS logical-log record 6-8Adding end-of-line character 8-26Adding virtual processors

CPU 3-50syntax diagram 3-49

ADDITEM logical-log record 6-8ADDLOG logical-log record 6-8ADTERR parameter 1-19ADTMODE parameter 1-19ADTPATH parameter 1-19ADTSIZE parameter 1-19AFF_NPROCS parameter

and VPCLASS 1-21description of 1-20, 1-21with MULTIPROCESSOR

parameter 1-94

AFF_SPROC parameterand VPCLASS 1-22description of 1-21, 1-22with MULTIPROCESSOR

parameter 1-94af.xxx file A-5ALARMPROGRAM

parameter 1-22, 1-24, D-1Aliases. See DBSERVERALIASES

parameter.ALLOW_NEWLINE

parameter 1-25ALTER FRAGMENT

statement 3-150ALTERDONE logical-log

record 6-8Alternate dbservername 1-37ANSI compliance Intro-21Archive configuration file A-13ARC_KEYPAD environment

variables A-14Assertion failure

af.xxx file A-5DUMPCNT parameter 1-58DUMPCORE parameter 1-59DUMPSHMEM parameter 1-62gcore file A-7shmem.xxx file A-15suspended threads C-5

Asynchronous I/O 1-101ASYNCRQT parameter 1-26, 1-158Audit records

configuration parameters 1-19sysadtinfo table 2-11sysaudit table 2-12

O QCA B D E F G H I J K L M N P R S T U V W X Y Z @

BBackup

and onstat -g bus 3-105and onstat -g bus_sm 3-105displaying contents of 3-31external 3-42logical log, parameters 1-71using ontape 3-132

Backup boot filebixbar A-7ixbar A-7

Backup Scheduler tables 2-10BADIDX logical-log record 6-8bar_action table 2-10bar_act.log file A-6BAR_ACT_LOG parameter 1-105BAR_BOOT_DIR parameter 1-105BAR_BSALIB_PATH

parameter 1-105BAR_DBS_COSVR

parameter 1-106BAR_HISTORY parameter 1-106BAR_IDLE_TIMEOUT

parameter 1-106bar_instance table 2-10BAR_LOG_COSVR

parameter 1-106BAR_MAX_BACKUP

parameter 1-106BAR_NB_XPORT_COUNT

parameter 1-106bar_object table 2-10BAR_PROGRESS_FREQ

parameter 1-106BAR_RETRY parameter 1-106bar_server table 2-10BAR_SM parameter 1-106BAR_SM_NAME parameter 1-106BAR_WORKER_COSVR

parameter 1-106BAR_WORKER_MAX

parameter 1-107BAR_XFER_BUFSIZE

parameter 1-107BAR_XFER_BUF_SIZE

parameter 1-107

BAR_XPORT_COUNTparameter 1-107

Before-image journal. See Physicallog.

BEGCOM logical-log record 6-8BEGIN logical-log record 6-8BEGPREP logical-log record 6-8BFRMAP logical-log record 6-9Big-remainder page 7-25Binding CPU virtual

processors 1-20, 1-21Bit-map page

blobspace 7-39tblspace tblspace 7-11, 7-12

BLDCL logical-log record 6-9bldutil.sh script 2-5, A-6BLOB data type. See Smart large

objects.Blobpage

average fullness statistics 3-12,3-19

blobpage size 7-36size, storage efficiency of 7-36specifying size of 7-36structure and storage 7-36, 7-39structure in dbspace 7-37

Blobspacebit-map page 7-39blobpage structure 7-39blobspace mirror chunk,

structure 7-7free-map page

description of 7-38location in blobspace 7-36role in blobpage logging 7-39tracked by bit-map 7-39

page types 7-38restriction, dropping 3-74simple-large-object storage 7-37structure 7-36

Blocking database server 3-42BMAP2TO4 logical-log record 6-9BMAPFULL logical-log record 6-9Boldface type Intro-12Bringing the database server on-

line 3-39, 3-40BSPADD logical-log record 6-9BTCPYBCK logical-log record 6-9BTMERGE logical-log record 6-10

B-treefunctional index 7-34key-value locking 7-32structure 7-27

BTSHUFFL logical-log record 6-10BTSPLIT logical-log record 6-10Buffer

access-level flag bits 3-97page-type codes 3-96

Buffer pool, 64-bit addressing 1-26Buffered transaction logging. See

Logging.BUFFERS parameter

64-bit addressing 1-26description of 1-27

buildsmi scriptbuildsmi.xxx file, description A-6error log message 5-18failure of A-6initializing database server 2-5

buildsmi.xxx file A-6BYTE data type. See Simple large

objects.

CCDR_DSLOCKWAIT

parameter 1-28CDR_EVALTHREADS

parameter 1-28CDR_LOGBUFFERS

parameter 1-28CDR_QUEUEMEM

parameter 1-28CHALLOC

logical-log record 6-10record subtype (SBLOB) 6-21

CHCOMBINElogical-log record 6-10record subtype (SBLOB) 6-21

Check constraints and rejectfile 8-4, 8-49

Checkingcatalog tables 3-170data pages 3-171free space 3-186index keys 3-176index pages 3-174



logical logs 3-181physical logs 3-181reserved pages 3-183space usage with onutil 3-178

CHFREElogical-log record 6-11record subtype (SBLOB) 6-22

CHSPLITlogical-log record 6-11record subtype (SBLOB) 6-22

Chunkchecking for overlap 3-18checking free list 3-186free-list page 7-5, 7-6, 7-8initial chunk of dbspace 7-4initial mirror offset 1-91monitoring 2-13structure

additional dbspace chunk 7-6initial dbspace chunk 7-5mirror chunk 7-7

using a symbolic link for thepathname 1-93, 1-129

Chunk free listchecking with CHECK

SPACE 3-186oncheck

checking with 3-11, 3-17displaying with 3-12, 3-17

CINDEX logical-log record 6-11CKPOINT logical-log record 6-11CKPTINTVL parameter 1-29CLEANERS parameter 1-30Client

and USEOSTIMEparameter 1-150

killing a client session 3-44printing client sessions (onstat -g

ath) 3-104results of connection 1-102specifying coserver name 1-39specifying dbservername 1-39

CLOB data type. See Smart largeobjects.

CLR logical-log record 6-11CLUSIDX logical-log record 6-11COARSELOCK logical-log

record 6-11Code set, ISO 8859-1 Intro-4

CODESET EBCDIC 8-17Code, sample, conventions

for Intro-17Cogroup

creating with onutil 3-188description 3-193dropping with onutil 3-220

cogroup_all 3-188Cogroup_range_identifier 3-141Cold restore, number of recovery

threads 1-104COLREPAI logical-log record 6-11Command-line conventions

elements of Intro-15example diagram Intro-16how to read Intro-16

Comment icons Intro-13COMMIT logical-log record 6-11Communication configuration file.

See ONCONFIG configurationfile.

Compactness of index page 1-63Compliance with industry

standards Intro-21CONFIGSIZE parameter 1-30Configuration file

processing A-12warning about not modifying

onconfig.std 1-8, A-11Configuration parameter

AC_MSGPATH 1-19AC_STORAGE 1-19AC_VERBOSE 1-19ADTERR 1-19ADTMODE 1-19ADTPATH 1-19ADTSIZE 1-19AFF_NPROCS 1-20, 1-21AFF_SPROC 1-21, 1-22ALARMPROGRAM 1-22, 1-24,

D-1ALLOW_NEWLINE 1-25ASYNCRQT 1-26, 1-158BAR_ACT_LOG 1-105BAR_BOOT_DIR 1-105BAR_BSALIB_PATH 1-105BAR_DBS_COSVR 1-106BAR_HISTORY 1-106BAR_IDLE_TIMEOUT 1-106

BAR_LOG_COSVR 1-106BAR_MAX_BACKUP 1-106BAR_NB_XPORT_COUNT 1-106BAR_PROGRESS_FREQ 1-106BAR_RETRY 1-106BAR_SM 1-106BAR_SM_NAME 1-106BAR_WORKER_COSVR 1-106BAR_WORKER_MAX 1-107BAR_XFER_BUFSIZE 1-107BAR_XFER_BUF_SIZE 1-107BAR_XPORT_COUNT 1-107BUFFERS 1-27CDR_DSLOCKWAIT 1-28CDR_EVALTHREADS 1-28CDR_LOGBUFFERS 1-28CDR_QUEUEMEM 1-28CKPTINTVL 1-29CLEANERS 1-30CONFIGSIZE 1-30CONSOLE 1-32COSERVER 1-33DATASKIP 1-35DBSERVERALIASES 1-37, 3-46DBSERVERNAME 1-39, 3-46DBSPACETEMP 1-40, 8-42DD_HASHMAX 1-45DD_HASHSIZE 1-45DEADLOCK_TIMEOUT 1-46DGINFO 1-34DIRECTIVES 1-46DRAUTO 1-47DRINTERVAL 1-48DRLOSTFOUND 1-49DRTIMEOUT 1-50DS_ADM_POLICY 1-51DS_MAX_QUERIES 1-51, 3-53DS_MAX_SCANS 1-53, 3-53DS_TOTAL_MEMORY 1-54, 3-52DUMPCNT 1-58DUMPCORE 1-59DUMPDIR 1-60DUMPGCORE 1-61DUMPSHMEM 1-62END 1-63FILLFACTOR 1-63, 7-33HADDR 1-34HBUFFER 1-158HETERO_COMMIT 1-64

Index 3

@O QCA B D E F G H I J K L M N P R S T U V W X Y Z

IDX_RA_PAGES 1-65IDX_RA_THRESHOLD 1-66ISM_DATA_POOL 1-67ISM_LOG_POOL 1-67, 1-107ISOLATION_LOCKS 1-67JVPxx and JVMTHREAD 1-68LADDR 1-34LBUFFER 1-158LBU_PRESERVE 1-69LOCKS 1-70LOGBUFF 1-71LOGFILES 1-73LOGSIZE 1-75LOGSMAX 1-76LOG_BACKUP_MODE 1-71,

1-107LRUS 1-77LRU_MAX_DIRTY 1-78LRU_MIN_DIRTY 1-79LTAPEBLK 1-79LTAPEDEV 1-81LTAPESIZE 1-82LTXEHWM 1-83LTXHWM 1-84MAX_CHUNKS 1-85MAX_DBSLICES 1-86MAX_DBSPACES 1-87MAX_PDQPRIORITY 1-88, 3-52MIRROR 1-90MIRROROFFSET 1-91MIRRORPATH 1-92MSGPATH 1-93MULTIPROCESSOR 1-94NETTYPE 1-96NOAGE 1-99NODE 1-100NUMAIOVPS 1-101NUMCPUVPS 1-102NUMFIFOVPS 1-103, 8-24OFF_RECVRY_THREADS 1-104ON-Bar, types of 1-105ONDBSPACEDOWN 1-108, 3-55ON_RECVRY_THREADS 1-104OPCACHEMAX 1-109OPTCOMPIND 1-110, 1-111OPT_GOAL 1-111PAGESIZE 1-112PC_HASHSIZE 1-114

PC_POOLSIZE 1-114PDQPRIORITY 1-115PHYSBUFF 1-117PHYSDBS 1-119PHYSFILE 1-120PHYSSLICE 1-121PLAN_MONITORING 1-122RA_PAGES 1-123RA_THRESHOLD 1-124RESIDENT 1-125, 3-43RESTARTABLE_RESTORE

1-107, 1-125ROOTOFFSET 1-127ROOTPATH 1-127, 1-128, 1-129ROOTSIZE 1-130ROOTSLICE 1-130SADDR 1-34SBSPACENAME 1-131SBUFFER 1-158SENDEPDS 1-132SERVERNUM 1-133SHMADD 1-134SHMBASE 1-135SHMTOTAL 1-136SHMVIRTSIZE 1-137SINGLE_CPU_VP 1-139STACKSIZE 1-140STAGEBLOB 1-141STMT_CACHE 1-142STMT_CACHE_SIZE 1-142SYSALARMPROGRAM 1-143SYSSBSPACENAME 1-144TAPEBLK 1-145TAPEDEV 1-146TAPESIZE 1-147TBLSPACE_STATS 1-148TXTIMEOUT 1-149, 3-45USEOSTIME 1-149VPCLASS 1-151, 3-50See also Configuration parameter

use; individual parameternames; and Administrator’sGuide.

Configuration parameter use,displayed in

data-replication screen 4-15diagnostics screen 4-16initialization screen 4-12

PDQ screen 4-16performance screen 4-14shared-memory screen 4-13

.conf.dbservername file A-6CONSOLE parameter 1-32Contact information Intro-22Continuous log backups 1-71Conventions

documentation Intro-11naming tables 3-151, 3-194

Conversiondata-format 8-8errors during a load 8-49, 8-51optimizing 8-10

Converter threads 8-10Core dump

and DUMPCORE parameter 1-59contained in core file A-7See also DUMPCNT; DUMPDIR;

DUMPGCORE;DUMPSHMEM.

core.pid.cnt file 1-61Coserver group. See Cogroup.Coserver name

DBSERVERALIASES 1-37DBSERVERNAME 1-39definition of 3-142

COSERVER parameter 1-33Coservers

balancing the load process 8-10home 3-172, 3-210list of 3-143range identifiers 3-145xcfg_servername.servernum

file A-16coserver_list identifier 3-143coserver_range_identifier 3-145CPU virtual processor

and SINGLE_CPU_VPparameter 1-139

binding 1-20, 1-21CPU, time tabulated 3-119CREATE EXTERNAL TABLE

statementadding a newline 8-27adding an end-of-line

character 8-26delimited format example 8-14,

8-17



deluxe load example 8-15EBCDIC format example 8-22fixed format example 8-5, 8-20Informix internal format

example 8-34loading from another database

server 8-31loading simple large objects 8-38mapping columns 8-18named-pipes example 8-23, 8-24refreshing a data warehouse

table 8-29CREATE FUNCTION

statement 1-155CREATE INDEX statement, using

FILLFACTOR 1-63CREATE record subtype

(SBLOB) 6-22CREATE TABLE statement

example, defining a fragmentedtable in a dbslice 8-6

newline example 8-27row-locking example 8-15simple large objects 8-33

Creatingcogroups 3-188dbslices 3-194dbspaces 3-207log files 3-212logslices 3-215

Ddaemon.log A-10Data block. See Page.Data distributions

sbspace 1-144user-defined data type 1-144

Data files. See Logging.Data file, formats 8-9, 8-32Data load. See Loading data with

external tables.Data pages

and oncheck 3-10, 3-15checking with onutil 3-171displaying with onutil 3-217number to read ahead 1-123

Data replicationflush interval 1-48information in sysdri table 2-19lost-and-found file 1-49wait time for response 1-50

Data rowand rowid 7-23big-remainder page 7-25forward pointer 7-23home page 7-23, 7-25how database server locates 7-23storage strategies 7-22storing data on a page 7-25TEXT and BYTE data

descriptor 7-37Data storage. See Disk space.Data Type segment. See Disk space.Data unload. See Unloading data.Data warehouse tables

initial load 8-28loading from other database

servers 8-31refreshing tables

continually 8-30periodically 8-29

Databasecreating, what happens on

disk 7-45effect of creation 7-45information in sysdatabases

table 2-16locale, in sysdbslocale table 2-17owner, in sysmaster

database 2-16Database server

assertion failures C-5blocking 3-42bringing on-line from quiescent

mode 3-39, 3-40quiescent mode 3-39, 3-40remote 2-29restarting 1-18shutting down 3-39, 3-40unblocking 3-42

Database server name 1-38Database tblspace

entries 7-13location in root dbspace 7-4, 7-12

relation to systable 7-46structure and function 7-12tblspace number 7-13

DATAFILES clause 8-12Data-flow manager 8-10Data-format conversion 8-8Datagram (DG) layer 1-34DATASKIP parameter

description of 1-35specifying with onspaces

utility 3-87DB-Access utility Intro-5dbexport. See Informix Migration

Guide.dbimport. See Informix Migration

Guide.dbschema. See Informix Migration

Guide.DBSERVERALIASES parameter

description of 1-37use with onmode 3-46

dbservername 1-39DBSERVERNAME parameter

description of 1-39use with onmode 3-46

Dbslicealtering 3-150creating uniform dbspaces 3-197creating with onutil 3-194derived identifiers 3-146dropping 3-222specified in onutil 3-146specifying formatting characters

in pathname 3-155, 3-199Dbspace

altering 3-159blobpage structure 7-37creating with onutil 3-207dropping 3-223list of structures contained in 7-5modifying with onspaces

utility 3-87monitoring with SMI 2-17root name 1-127simple-large-object storage 7-37specified in onutil 3-146storage 7-4

Index 5


structure 7-4, 7-5, 7-6of additional dbspace chunk 7-6of chunk free-list page 7-8of mirror chunk 7-7of nonroot dbspace 7-5of tblspace tblspace 7-9

usage report 7-4DBSPACETEMP environment

variable 8-42DBSPACETEMP parameter

and PSORT_DBTEMP 8-42description of 1-40load staging from pipes 8-42temporary spaces for pipes 8-42

DD_HASHMAX parameter 1-45DD_HASHSIZE parameter 1-45Deadlock. See

DEADLOCK_TIMEOUTparameter.

DEADLOCK_TIMEOUTparameter 1-46

Decision-support queryDS_MAX_QUERIES

parameter 1-52DS_TOTAL_MEMORY

parameter 1-54MAX_PDQPRIORITY

parameter 1-88setting parameters with

onmode 3-52See also PDQ.

Default configuration file 1-8, A-12Default locale Intro-4DELETE


Deleting all the rows in a table 8-30Delimited format

description 8-34external column types 8-34loading 8-17loading simple large objects 8-34unloading 8-17when to use 8-34

DELITEM logical-log record 6-12

Deluxe-mode loaddefinition of 8-9procedure 8-15

Demonstration databases Intro-5Dependencies, software Intro-4DERASE logical-log record 6-12derived_dbspace_identifier 3-146Descriptor, TEXT and BYTE

data 7-37DGINFO parameter 1-34Diagnostic messages. See Message

log.Diagnostics, using onmode B-1DIRECTIVES parameter 1-46Disk page

page compression 7-26storing data on a page 7-25structure

blobspace blobpage 7-15dbspace page 7-22

types of pages in an extent 7-14,7-17

Disk spaceallocating

when a database is created 7-45when a table is created 7-47

allocation for systemcatalogs 7-45

checking with onutil 3-178, 3-186chunk free-list page 7-8initialization with oninit 3-26limits due to maximum chunk

size 3-66list of structures 7-3page compression 7-26tracking

available space in ablobspace 7-38

available space in a chunk 7-8Distributed transactions

killing 3-45monitoring (onstat -x) 3-129

Documentation notes Intro-20Documentation, types of

documentation notes Intro-20error message files Intro-19machine notes Intro-20

on-line help Intro-19on-line manuals Intro-18printed manuals Intro-18related reading Intro-21release notes Intro-20

DPT logical-log record 6-12DRAUTO parameter 1-47DRINTERVAL parameter 1-48DRLOSTFOUND parameter 1-49Dropping

cogroups 3-220dbslices 3-222dbspaces 3-223logical-log files 3-224logslice 3-226

DRPBSP logical-log record 6-12DRPCHK logical-log record 6-12DRPDBS logical-log record 6-12DRPLOG logical-log record 6-12DRTIMEOUT parameter 1-50dr.lostfound file 1-49DS_ADM_POLICY parameter 1-51DS_MAX_QUERIES parameter

64-bit addressing 1-52changing the value 3-53description of 1-52

DS_MAX_SCANS parameterchanging the value of 3-53description of 1-53

DS_TOTAL_MEMORY parameterchanging the value of 3-52deriving the value of 1-56description of 1-55recalculated by database

server 1-56DUMPCNT parameter 1-58DUMPCORE parameter 1-59DUMPDIR parameter

af.xxx assertion failure file A-5and shmem file A-15description of 1-60gcore file A-7

DUMPGCORE parameter 1-61Dumping stack of thread (onstat -g

stk) 3-108DUMPSHMEM parameter 1-62Dynamic lock allocation 1-70



EEBCDIC format

FORMAT clause 8-13loading 8-22unloading 8-27

Emergency boot files A-7END parameter 1-63ENDTRANS logical-log

record 6-13Enterprise Replication

parameters 1-28See also Guide to Informix Enterprise

Replication.Environment configuration file A-8Environment variables Intro-12

affecting I/O 8-42ARC_KEYPAD A-14DBSPACETEMP 8-42for xctl 3-229INFORMIXOPCACHE 1-109INFORMIXSERVER 3-51ONCONFIG 3-98, A-12OPTCOMPIND 1-110PSORT_DBTEMP 8-42STMT_CACHE 3-56

en_us.8859-1 locale Intro-4ERASE logical-log record 6-13Error messages

files Intro-19thread suspension C-2

Errorsload and unload 8-49reject files 8-49, 8-51violations table 8-4

Event alarmsALARMPROGRAM

parameter D-1class ID parameter D-3class message parameter D-4description D-1event severity codes D-3exit code D-1mentioned 2-8

Event severity codes D-3Exit codes, ontape utility 3-134EXIT_STATUS exit code D-1

Express-mode loaddefinition of 8-9procedure 8-13

EXTEND record subtype(SBLOB) 6-22

Extentautomatic doubling of size 7-19default size 7-14disk page types 7-14, 7-17information in sysextents

table 2-20initial size 7-14merging 7-20next-extent

allocation 7-19allocation strategies 7-21size 7-19

procedure for allocating 7-19size

index fragments 7-14limitations 7-14

structure 7-13External backup, commands 3-42External spaces, in sysextspaces

table 2-20External tables

adding end-of-line character 8-26adding newline character 8-27conceptual diagram 8-11data-format conversion 8-8description of 8-4diagram of load process 8-6high-performance loading of

data 8-3loading

from a delimited file 8-17from a named pipe 8-23simple large objects 8-32, 8-38tables with the same

schema 8-19to a fixed-ASCII file 8-20to an EBCDIC file 8-22

mapping columns 8-18pipe staging 8-41

unloadingfrom a named pipe 8-25to a delimited file 8-17, 8-34to a fixed-ASCII file 8-21to Informix internal

format 8-19, 8-33

FFast recovery of table types 8-52Feature icons Intro-13Features of this product,

new Intro-6FIFO 8-22, 8-46FIFO file. See Named pipes.File

ac_config.std A-6ac_msg.log A-5af.xxx A-5archecker configuration file A-6bar_act.log A-6buildsmi.xxx A-6configuration file A-11.conf.dbservername A-6core A-7core.pid.cnt 1-61default configuration file A-12dr.lostfound 1-49first-in-first-out 8-22gcore 1-60gcore. xxx A-7in INFORMIXTMP directory A-9.informix A-8informix.rc environment file A-8.infos.dbservername A-9.infxdirs A-10.inf.servicename A-9ISM logs A-10ISMVersion A-11oncfg* A-13onconfig A-12onconfig.std

description of A-11sample file A-17, A-26

onconfig.xps A-11oper_deflt.arc A-13private environment file A-8servicename.exp A-14

Index 7


servicename.str A-14shmem.pid.cnt 1-62shmem.xxx A-15sm_versions A-15summary of database server

files A-1VP.servername.nnx A-16xbsa.messages A-16xcfg_servername.servernum A-1

6File I/O. See Disk I/O.FILLFACTOR parameter

control how indexes fill 7-33description of 1-63

Find Error utility Intro-19finderr utility Intro-19First-in-first-out data file 8-22Fixed-ASCII files

adding end-of-line character 8-26unloading 8-20, 8-21

Flushing, data-replicationbuffer 1-48

Forced residency, starting andending with onmode 3-43

Forcing a checkpoint. SeeCheckpoint.

FORMAT clause 8-13Format, definition of 8-32Formula, temporary space for pipe

staging 8-43Forward pointer

description of 7-23role in a blobspace blobpage 7-40role in dbspace storage of simple

large objects 7-37Fragment

and rowids 7-24index 7-14internal structure of tables 7-26turning DATASKIP ON or OFF

for 3-87warning returned when skipped

during query 1-35Fragmentation. See Fragment.Fragmented table, using primary

keys 7-24Free list. See Chunk free list.Freeing blobpages 3-102

Freeing unused memorysegments 3-54

Free-map page, description ofblobspace free-map page 7-38

Functional index 7-34Fuzzy checkpoint

forcing 3-42log record 6-12

GGateway transactions 1-64gcore, utility 1-58, 1-61gcore.xxx file A-7Global Language Support

(GLS) Intro-4

HHADDR parameter 1-34HBUFFER parameter 1-158HDELETE logical-log record 6-13HDRUPD record subtype

(SBLOB) 6-22Heterogeneous-commit

transactions 1-64HETERO_COMMIT

parameter 1-64HEURTX logical-log record 6-13HEX external type

definition of 8-37SQL example 8-35

High-availability data replication(HDR). See Data replication.

HINSERT logical-log record 6-13Home coserver 3-172, 3-210Home page 7-23, 7-25Host name, specifying in NODE

parameter 1-100Hosts file 3-228HUPAFT logical-log record 6-13HUPBEF logical-log record 6-14HUPDATE logical-log record 6-14

IIBM EBCDIC format. See EBCDIC

format.Icons

feature Intro-13Important Intro-13platform Intro-13product Intro-13Tip Intro-13Warning Intro-13

Identifier, description of 1-38, 3-140IDXFLAGS logical-log record 6-14IDX_RA_PAGES parameter 1-65IDX_RA_THRESHOLD

parameter 1-66illlsrra.xx file A-7Important paragraphs, icon

for Intro-13Index

branch node 7-28checking with onutil

index keys 3-176index pages 3-174

configuration 7-33duplicate key values 7-32functional 7-34how created and filled 7-29item described 7-29key-value locking 7-32leaf node 7-28names, specified in onutil 3-147repairing structures with oncheck

utility 3-5reuse of freed pages 7-33root node 7-28structure of B-tree 7-27

Index itemcalculating the length of 7-33defined 7-29

Index pagecompactness 1-63creation of first 7-29effect of creation 7-29number to read ahead 1-65structure of 7-27

Industry standards, compliancewith Intro-21

.informix file A-8



Informix internal formatand simple large objects 8-33description of 8-33unloading 8-19

Informix Storage Manager (ISM)catalog A-10ISMversion file A-11logs A-10sm_versions file A-15

INFORMIXDIR/bindirectory Intro-5

INFORMIXOPCACHEenvironment variables 1-109

INFORMIXSERVER environmentvariable

relation toDBSERVERNAME 1-39

INFORMIXSERVER environmentvariables 3-51

INFORMIX-STAR queries 3-129INFORMIXTMP directory

description of A-9servicename.exp file A-14servicename.str file A-14.inf.servicename file A-9

informix.rc environment file A-8.infos.dbservername file

description of A-9regenerate 3-51

.infxdirs file A-10

.inf.servicename file A-9Initialization

disk structures initialized 1-18,7-4

shared memory initialized 1-18In-Place ALTER TABLE

message 5-43INSERT logical-log record 6-14InstallServer.log file A-10Internal format

load file type 8-33, 8-35when to use 8-34

Internal format. See Informixinternal format.

Interval, checkpoint 1-29ISAM calls tabulated 3-118ISMVersion file A-11ISM. See Informix Storage Manager

(ISM).

ISM_DATA_POOLparameter 1-67, 1-107

ISM_LOG_POOL parameter 1-67,1-107

ISO 8859-1 code set Intro-4ISOLATION_LOCKS

parameter 1-67

JJava configuration parameters 1-68JDBC parameters 1-68

KKey value

checking order withoncheck 3-11, 3-17

checking order with onutil 3-174,3-176

duplicates 7-32locking 7-32

Killing a session 3-44

LLADDR parameter 1-34Latch

displaying information withonstat 3-91

displaying information withonstat -s 3-123

identifying the resourcecontrolled 3-123

LBUFFER parameter 1-158LBU_PRESERVE parameter 1-69LCKLVL logical-log record 6-14LG_CDINDEX logical-log

record 6-14LG_DERASE logical-log

record 6-14LG_ENDTRUNCATE logical-log

record 6-14LG_PTRUNCATE logical-log

record 6-14LG_TRUNCATE logical-log

record 6-14

Linking, name of rootdbspace 1-128, 1-129

LIST/LOGRECORDS command(ON-Archive) 6-3

Load converter 8-47Loader threads 8-10Loading data with external tables

balancing the load process acrossmultiple coservers 8-10

data warehouse tableinitial load 8-28refreshing continually 8-30refreshing periodically 8-29

definition of 8-8deluxe-mode procedure 8-15diagram 8-6express-mode procedure 8-13file types and formats 8-9from a delimited file 8-17from an EBCDIC file 8-22from other database servers 8-31loading modes 8-9monitoring time for 8-44named pipes 8-23reject file 8-4serial columns 8-28tables with the same schema 8-19to a delimited file 8-34to a fixed-ASCII file 8-20to an Informix file 8-33violations table 8-4

Loading modes. See Express-modeload or Deluxe-mode load.

Locale Intro-4default Intro-4en_us.8859-1 Intro-4

Lockand oncheck 3-6buffer-access-level flag bits 3-97information in syslocks table 2-21key-value 7-32maximum time to acquire 1-46monitoring 3-90monitoring with onstat -k 3-111,

3-112type codes 3-111

Index 9


Lockingdynamic allocation 1-70for multiprocessor 1-94with onutil CHECK options 3-139

LOCKS parameter64-bit addressing 1-70description of 1-70

LOGBUFF parameter 1-71LOGFILES parameter 1-73Logging

role of blobspace free-mappage 7-39

See also Administrator’s Guide.Logical log

adding log files with onutil 3-212backups 1-71checking consistency 3-18dropping 3-224in root dbspace 7-4maximum number of files 1-76monitoring with SMI 2-22See also Logical-log file.

Logical logschecking 3-181

Logical recovery, number ofthreads 1-104

Logical-log buffer and LOGBUFFparameter 1-71

Logical-log filecreated during initialization 1-73displaying contents 3-31reading the log file 3-31size 1-75switching with onmode 3-44See also Logical log.

Logical-log recordadditional columns of 6-7displaying 3-31for a checkpoint 6-5for a DROP TABLE operation 6-4generated by a rollback 6-4header columns 6-6involved in distributed

transactions 6-5involved in two-phase commit

protocol 6-5types 6-7, 6-21

logical-log record 6-12logmessage table 5-4

LOGSIZE parameter 1-75Logslice

altering 3-167creating with onutil 3-215dropping 3-226specified in onutil 3-147

LOGSMAX parameter 1-76LOG_BACKUP_MODE

parameter 1-71, 1-107Long transaction, starting

percentage 1-83, 1-84LRU queues


displaying information withonstat -R 3-121

FLRU queues 3-121MLRU queues 3-121modified pages, percentage

of 1-78, 1-79LRUS parameter

64-bit addressing 1-77description of 1-77

LRU_MAX_DIRTY parameter 1-78LRU_MIN_DIRTY parameter 1-79LTAPEBLK parameter 1-79LTAPEDEV parameter 1-81LTAPESIZE parameter 1-82LTXEHWM parameter 1-83LTXHWM parameter 1-84

MMachine notes Intro-20Manual log backups 1-71Mapping columns in a load 8-18MAX_CHUNKS parameter 1-85MAX_DBSLICES parameter 1-86MAX_DBSPACES parameter 1-87MAX_PDQPRIORITY parameter

changing the value 3-52description of 1-88

Memoryfreeing unused segments 3-54specifying size of 1-109See also Shared memory.

Merge boot file (mixbar) A-7

Message file for errormessages Intro-19

Message logalphabetical listing of

messages 5-4and event alarms D-1categories of messages 5-5description of 5-3displaying with onstat -m 3-115displaying with onstat

utility 3-91file pathname 1-93location of 1-93mentioned A-11syslogd 1-24viewing messages 5-4

Messages for onspaces 5-34Metadata

area, structure of 7-42checking with oncheck 3-5

Microkernel mode 3-26Mirror chunk, structure 7-7MIRROR parameter 1-90Mirroring

enable flag 1-90initial chunk 1-92

MIRROROFFSET parameter 1-91MIRRORPATH parameter

description of 1-92specifying a link pathname 1-92

mknod UNIX command 8-23MLRU queues. See LRU queues.Mode, microkernel 3-26Monitoring

distributed queries 3-129FIFO queues 8-45loads and unloads 8-44, 8-46pipe staging 8-48SET EXPLAIN ON 8-46

MSGPATH parameter 1-93Multibyte characters 8-37Multiprocessor computer

AFF_SPROC parameter 1-21processor affinity 1-156

MULTIPROCESSORparameter 1-94

MVIDXND logical-log record 6-15



NNamed pipes

anonymity of 8-10creating with mknod 8-23definition of 8-22FIF virtual processors 1-103loading 8-23unloading 8-25

NETTYPE parameterdescription of 1-96tuning example 1-96

New features of thisproduct Intro-6

Newline characteradding 8-27delimiter usage 8-35

NOAGE parameterand VPCLASS 1-99description of 1-99

NODE parameterdescription of 1-100specifying host name 1-100

Node, coserver ID assigned to 1-33Node, index

branchcreating 7-30, 7-31definition of 7-28what points to 7-31

checking horizontal and verticalnodes 3-11, 3-17, 3-174, 3-176

definition of 7-29leaf

contents of 7-30definition of 7-28

pointer 7-30root 7-29root node

creating 7-29definition of 7-28

types of 7-28when root node fills 7-30

NUMAIOVPS parameterand VPCLASS 1-101description of 1-101

Number of page-cleanerthreads 1-30

NUMCPUVPS parameterand VPCLASS 1-102description of 1-102used by

DS_TOTAL_MEMORY 1-56NUMFIFOVPS parameter 1-103,

8-24

OOFF_RECVRY_THREADS

parameter 1-104ON-Bar

activity log A-6configuration parameters 1-105emergency boot files A-7sm_versions file A-15system tables 2-10xbsa.messages log A-16

oncfg_servername.servernumfile A-13

oncheck utilityand locking 3-8check-and-repair options 3-5description of 3-5list of functions 3-6option descriptions 3-9options

-cc 3-15-cd and -cD 3-15-ce 3-11, 3-17-ci and -cI 3-17-cr and -cR 3-18-cS 3-19-cs 3-19-cS and -pS 3-19-cs and -ps 3-19-n 3-7, 3-11-pB 3-19, 3-102-pD 3-20-pd 3-20-pe 3-17, 7-4-pK 3-20-pk 3-20-pL 3-21-pl 3-21

-pP 3-21-pp 3-21-pr 3-22-pS 3-19-ps 3-19-pT 3-22-pt 3-22-u 3-23-x 3-23-y 3-7, 3-13

overview of functionality 3-5suppressing messages 3-13syntax 3-9

onclean utility B-3ONCONFIG configuration file

conventions 1-7, 1-10description A-12displaying 3-90, 3-98templates 1-8white space 1-7

ONCONFIG environmentvariable 3-98, A-12

onconfig file A-12ONCONFIG file parameters. See

Configuration parameter.onconfig.std file

description A-11sample A-17, A-26

onconfig.xps file A-11ondblog utility 3-24ONDBSPACEDOWN parameter

description of 1-108overriding WAIT mode 3-55

oninit utility-m option 3-26option descriptions 3-29starting database server 3-26temporary tables 3-27

On-line help Intro-19On-line manuals Intro-18onload utility. See Informix

Migration Guide.onlog utility

description of 3-31filters for logical-log records

displaying 3-35reading 3-34

Index 11


onmode utilityadding a shared-memory

segment 3-48changing

database server mode 3-39, 3-41shared-memory residency 3-43SQL statement cache usage 3-56

decision-support parameters,changing 3-52

description of 3-37forcing a checkpoint 3-41killing a session 3-44options

-a add shared-memorysegment 3-48

block 3-42-c fuzzy 3-42-D change value of

MAX_PDQPRIORITY 3-52-d set data replication type 3-46-e change SQL statement cache

usage 3-56-F free memory segments 3-54-I collect diagnostics B-1-k take off-line 3-39, 3-40-l switch logical-log file 3-44-m bring on-line 3-39, 3-40-M change value of

DS_TOTAL_MEMORY 3-52-n end forced residency 3-43-O mark disabled dbspace as

down 3-55-p add or remove virtual

processor 3-50-Q change value of

DS_MAX_QUERIES 3-53-r begin forced residency 3-43-R regenerate .infos file 3-51-S change value of

DS_MAX_SCANS 3-53-s take to quiescent 3-39, 3-40-u shut down immediately 3-39,

3-40unblock 3-42vpclass 3-50-y confirm action 3-39-z kill a session 3-44-Z kill transaction 3-45

overriding ONDBSPACEDOWNparameter 3-55

setting database server type 3-46setting decision-support

parameters 3-52switching logical-log files 3-43trapping errors B-1

ON-Monitorarchive menu and options 4-11changing database server

mode 3-41data-replication screen 4-15dbspaces menu and options 4-5diagnostics screen 4-15force-ckpt option 4-9, 4-11help 4-4initialization screen 4-12mode menu and options 4-11parameters menu and options 4-5parameters screens 4-12 to 4-16PDQ screen 4-16performance screen 4-14status menu and options 4-5

onparams utilityadding a logical-log file 3-58changing physical log size and

location 3-60description of 3-57dropping a logical-log file 3-59

onsnmp log file A-13onspaces utility

adding a chunk 3-76adding a chunk to an

sbspace 3-78changing chunk status 3-85changing sbspace default

specifications 3-73creating a blobspace, dbspace,

extspace, or temporarydbspace 3-64

creating an sbspace 3-68creating an sbspace with -Df 3-69-Df and CREATE TABLE 3-72dropping a blobspace, dbspace,

extspace, or sbspace 3-74dropping a chunk 3-80ending mirroring 3-84specifying DATASKIP 3-87starting mirroring 3-82

onsrvapd.log file A-13onstat utility

description of 3-88displaying the ONCONFIG

file 3-90filename_dest 3-92filename_source 3-92freeing blobpages and

timing 3-102header 3-93options

-a 3-90, 3-95-B 3-90, 3-97-b 3-90, 3-95-C 3-90-c 3-90, 3-98-D 3-90, 3-102-d 3-90, 3-98, 3-102-F 3-90, 3-103-f 3-90-g 3-104-g act 3-104-g afr 3-104-g all 3-104-g ath 3-104, C-3-g bus 3-105-g bus_sm 3-105-g cac agg 3-105-g cac stmt 3-105-g con 3-105, C-4-g dfm 3-105-g dic 3-105-g dll 3-105-g dri 3-105-g dsc 3-105-g ffr 3-105-g glo 3-106-g ioa 3-106-g iob 3-95, 3-106-g iof 3-106-g iog 3-106-g ioq 3-106, 8-44, 8-45-g iov 3-106-g lmx 3-106-g mgm 3-53, 3-106-g nbm 3-106-g nsc 3-107-g nsd 3-107-g nss 3-107



-g nta 3-107-g ntd 3-107-g ntm 3-107-g ntt 3-107-g ntu 3-107-g pos 3-107-g ppf 3-107-g prc 3-107-g qst 3-107-g rbm 3-107-g rea 3-108-g rgm 3-108-g sch 3-108-g seg 3-108-g ses C-4-g sle 3-108-g spi 3-108-g sql 3-108, 8-44-g stk 3-108-g sts 3-109-g tpf 3-109-g ufr 3-109-g wai 3-109-g wmx 3-109-g wst 3-109-g xmf 3-109-g xmp 3-109, 8-44-g xqp 3-109-g xqs 3-109, 8-44, 8-48-h 3-90-i 3-90, 3-110-k 3-90, 3-111, 3-112-l 3-91, 3-113-m 3-91, 3-115, 5-4-O 3-91, 3-115-o 3-91-P 3-91-p 3-117-R 3-91, 3-121-r 3-91-s 3-91, 3-123-t 3-91, 3-125-u 3-91, 3-126, C-3, C-4-X 3-92, 3-131-x 3-45, 3-92, 3-129-z 3-92, 3-131-- 3-90, 3-95(none) 3-95

repeated execution with -r 3-91repeated execution with seconds

parameter 3-93syntax 3-89table of options and

functions 3-90terminating interactive

mode 3-110terminating repeating

sequence 3-110using SMI tables for onstat

information 2-37using with shared-memory

source file 3-92ontape utility

data-replication functions 3-134description of 3-132exit codes 3-134LTAPEBLK, use of 1-79, 1-145LTAPEDEV, use of 1-81LTAPESIZE, use of 1-82TAPEDEV, use of 1-146TAPESIZE, use of 1-147tasks performed by 3-132

onunload utilityLTAPEBLK, use of 1-79, 1-145LTAPEDEV, use of 1-81LTAPESIZE, use of 1-82TAPEDEV, use of 1-146TAPESIZE, use of 1-147See also Informix Migration Guide.

onutil thread C-2onutil utility

cogroup name 3-141cogroup_range_identifier 3-141commands

ALTER DBSLICE ADDDBSPACE 3-150

ALTER DBSPACE 3-159ALTER LOGSLICE ADD

LOG 3-167CHECK CATALOGS 3-170CHECK DATA 3-171CHECK INDEX 3-174CHECK INDEX KEYS WITH

DATA 3-176CHECK INFO 3-178, 3-179,

3-181CHECK LOGS 3-181

CHECK RESERVED 3-183CHECK SPACE 3-186CREATE COGROUP 3-188CREATE DBSLICE 3-194CREATE DBSPACE 3-207CREATE LOGICAL LOG 3-212CREATE LOGICAL

LOGSLICE 3-215DISPLAY PAGE 3-217DROP COGROUP 3-220DROP DBSLICE 3-222DROP DBSPACE 3-223DROP LOGICAL LOG 3-224DROP LOGSLICE 3-226

coserver_list 3-143coserver_name 3-142coserver_range_identifier 3-145dbslice names 3-146dbspace names 3-146derviced_dbspace_identifier 3-14

6description of 3-135DISPLAY and SAVE

keywords 3-138identifers 3-140index names 3-147invoking 3-136logslice names 3-147

onxfer utility. See InformixMigration Guide.

ON_RECVRY_THREADSparameter 1-104

OPCACHEMAX parameter 1-109OPERATIONAL table

express-mode loads 8-9, 8-13,8-30

recovery of 8-52oper_deflt.arc file, contents A-13OPTCOMPIND

configuration parameter 1-110environment variables 1-110

Optical storage and STAGEBLOBparameter 1-141

Optical Subsystem memory cacheallocation 3-115availability of memory 3-115description of 3-91, 3-115kilobytes of TEXT and BYTE data

written to staging area 3-116

Index 13


number of kilobytes 3-115number of objects written 3-115,

3-116number of simple large objects

written 3-116session ID for user 3-116size 3-115size of simple large object 3-116user ID of client 3-116

Optimizinghash joins and nested-loop

joins 1-111load performance 8-10

OPT_GOAL parameter 1-111

PPage

bit-map page 7-38blobspace blobpage 7-38blobspace free-map page 7-38components of dbspace page 7-22compression 7-26dbspace blobpage 7-37dbspace page types 7-14, 7-17definition of full page 7-25displaying contents with

oncheck 3-21free page, definition of 7-15, 7-17page types in extent 7-14, 7-17reuse of index page 7-33size, shown with onstat -b 3-97structure and storage of 7-22

Page compression 7-26Page-cleaner threads

codes for activity state 3-103monitoring activity 3-90, 3-103number of 1-30

PAGESIZE parameter 1-112PAGE_CONFIG reserved

page 3-18Parallel database query. See PDQ.Parallel sort threads

(psortproc) C-2Parallel-processing platform 1-20,

1-21Parameters, setting decision-

support with onmode 3-52

Partition. See Tblspace.Partnum field in systables 7-10Pathname-format

description of 3-148specifying in ALTER

DBSLICE 3-155specifying in CREATE

DBSLICE 3-199PBDELETE logical-log record 6-15PBINSERT logical-log record 6-15PC_HASHSIZE parameter 1-114PC_POOLSIZE parameter 1-114PDELETE record subtype

(SBLOB) 6-22PDINDEX logical-log record 6-15PDQ (parallel database query)

DS_MAX_QUERIESparameter 1-52

DS_MAX_SCANSparameter 1-53

DS_TOTAL_MEMORYparameter 1-55

MAX_PDQPRIORITYparameter 1-88

PDQPRIORITY parameter 1-88PDQPRIORITY parameter

and MAX_PDQPRIORITY 1-88description of 1-115

Pending transaction 3-129PERASE logical-log record 6-16PGALTER logical-log record 6-15PGMODE logical-log record 6-16PHYSBUFF parameter 1-117PHYSDBS parameter 1-119PHYSFILE parameter 1-120Physical log

checking consistency 3-18in root dbspace 7-4size of 1-120

Physical-log bufferdbspace location 1-119size of 1-117

PHYSSLICE parameter 1-121Pipe staging

and simple large objects 8-40definition 8-40illustration 8-40using temporary dbspaces 8-41xlread operators 8-43

Plan Monitoring Infrastructure(PMI), usingPLAN_MONITORINGparameter 1-122

PLAN_MONITORINGparameter 1-122

Platform icons Intro-13Platform, parallel-processing 1-20,

1-21PNLOCKID logical-log record 6-16PNSIZES logical-log record 6-16Point-in-time restore. See Backup and

Restore Guide or Archive andBackup Guide.

PostInstall.tmp file A-14PREPARE logical-log record 6-16Primary key, use in fragmented

table 7-24Primary thread C-2Printed manuals Intro-18Printing

active threads (onstat -gact) 3-104

AIO global information (onstat -giog) 3-106

allocated fragments (onstat -gufr) 3-109

allocated memory fragments(onstat -g afr) 3-104

asynchronous I/O statistics(onstat -g iof) 3-106

asynchronous I/O statistics(onstat -g iov) 3-106

backup scheduler status (onstat -gbus) 3-105

big-buffer use (onstat -giob) 3-106

block bit map (onstat -gnbm) 3-106

block bit map (onstat -grbm) 3-107

combined information (onstat -gioa) 3-106

conditions with waiters (onstat -gcon) 3-105

coserver communications (onstat-g xmf) 3-109



data-distribution cacheinformation (onstat -gdsc) 3-105

data-flow information (onstat -gdfm) 3-105

data-replication information(onstat -g dri) 3-105

free fragments for a shared-memory pool (onstat -gffr) 3-105

global multithreadinginformation (onstat -gglo) 3-106

information about query plan(onstat -g xqp) 3-109

information about querysegments (onstat -gxmp) 3-109

list of loaded dynamic libraries(onstat -g dll) 3-105

locked mutexes (onstat -glmx) 3-106

MGM resource information(onstat -g mgm) 3-106

multithreading information(onstat -g all) 3-104

mutexes with waiters (onstat-wmx) 3-109

network statisticsby service (onstat -g ntd) 3-107combined (onstat -g nta) 3-107mail (onstat -g ntm) 3-107users (onstat -g ntu) 3-107

network user times (onstat -gntt) 3-107

partition profile (onstat -gppf) 3-107

pending I/O operations (onstat -gioq) 3-106

query statistics for active plans(onstat -g xqs) 3-109

queue statistics (onstat -gqst) 3-107

ready threads (onstat -grea) 3-108

RGM information (onstat -grgm) 3-108

semaphores, spins, busy waits(onstat -g sch) 3-108

shared-memory data for pollthreads (onstat -g nsd) 3-107

shared-memory segment statistics(onstat -g seg) 3-108

shared-memory status for clients(onstat -g nsc) 3-107

shared-memory status forsessions (onstat -g nss) 3-107

sleeping threads (onstat -gsle) 3-108

spin locks (onstat -g spi) 3-108SPL routine cache (onstat -g

prc) 3-107SQL information (onstat -g

sql) 3-108SQL statement cache (onstat -g cac

stmt) 3-105stack use per thread (onstat -g

sts) 3-109storage-manager configuration

(onstat -g bus_sm) 3-105tables cached in shared-memory

dictionary (onstat -gdic) 3-105

thread profile (onstat -g tpf) 3-109wait statistics (onstat -g

wst) 3-109waiting threads (onstat -g

wai) 3-109.infos.dbservername file (onstat -g

pos) 3-107Priority aging, of CPU virtual

processors 1-99Private environment file A-8Processor affinity

AFF_NPROCS parameter 1-20and AFF_SPROC parameter 1-21,

1-156set with VPCLASS 1-156

Processor, locking for multiple orsingle 1-94

Product icons Intro-13Profile

displaying counts withonstat -p 3-117

displaying counts with onstatutility 3-91

monitoring with SMI 2-23setting counts to zero 3-92, 3-131

Program groupDocumentation notes Intro-20Release notes Intro-20

psortproc threads C-2PSORT_DBTEMP environment

variable 8-42PTADESC logical-log record 6-16PTALTER logical-log record 6-17PTCOLUMN logical-log

record 6-17PTEXTEND logical-log record 6-17PTRENAME logical-log

record 6-17PTRUNC record subtype

(SBLOB) 6-22

QQuery Monitor,

PLAN_MONITORINGparameter 1-122

Query plan, XMP section 8-47Quiescent mode

oninit -s option 3-27, 3-28, 3-39,3-40

RRAW table

express-mode loads 8-9, 8-13,8-28

loading from another databaseserver 8-31

recovery of 8-52RA_PAGES parameter 1-123RA_THRESHOLD

parameter 1-124RDELETE logical-log record 6-17Read-ahead

number ofdata pages 1-123index pages 1-65

threshold fordata pages 1-124index pages 1-66

RECORDEND keyword 8-17

Index 15


Recovery threadsoff-line 1-104on-line 1-104

REFCOUNT record subtype(SBLOB) 6-22

Referential constraints andviolations table 8-5

Reject files 8-4, 8-49REJECTFILE keyword 8-49Related reading Intro-21Release notes Intro-20Remainder page, description

of 7-25Removing virtual processors

CPU 3-50syntax diagram 3-49

Replication server. See Datareplication.

Reserved pageschecking with oncheck 3-11, 3-18checking with onutil 3-183description of 7-5location in root dbspace 7-4viewing contents 7-5

RESIDENT parameterand onmode utility 3-43description of 1-125

Resident shared memoryRESIDENT parameter 1-125turning on and off residency 3-43

RESTARTABLE_RESTOREparameter 1-107, 1-125

Restarting the database server 1-18Restore boot file (rixbar) A-7Reuse of freed index pages 7-33Reversion. See Informix Migration

Guide.REVERT logical-log record 6-17RINSERT logical-log record 6-17rofferr utility Intro-19ROLLBACK logical-log record 6-18Root dbspace

initial chunk 1-128, 1-129linking to 1-129mirroring 1-92specified by ROOTNAME

parameter 1-127structure 7-4using a link 1-128

ROOTNAME parameterdescription of 1-127use by PHYSDBS 1-118

ROOTOFFSET parameter 1-127ROOTPATH parameter

description of 1-128, 1-129specifying as a link 1-93, 1-129

ROOTSIZE parameter 1-130ROOTSLICE parameter 1-130Row

data, storage of 7-25displaying contents with

oncheck 3-20storage location 7-25

Rowiddescription of 7-23for fragmented table 7-24functions as forward pointer 7-23locking information derived

from 3-112stored in index pages 7-23

RSVEXTEN logical-log record 6-18RUPAFT logical-log record 6-18RUPBEF logical-log record 6-18RUPDATE logical-log record 6-18

SSADDR parameter 1-34sales_demo database Intro-5Sample onconfig.std file A-17, A-26Sample-code conventions Intro-17SBLOB logical-log record 6-19, 6-21Sbpage structure 7-43Sbspace

chunk free extent list 7-41chunk header structure 7-41default name 1-131metadata area structure 7-42multiple chunk 7-44onstat -d usage 3-101sbpage structure 7-43statistics for user-defined

data 1-144structure 7-40

SBSPACENAME parameter 1-131SBUFFER parameter 1-158

Screen-illustrationconventions Intro-17

Secondary session thread(x_exec_*) C-2

Segment. See Chunk.SENDEPDS parameter 1-132, 1-158Serial columns, loading 8-28SERVERNUM parameter 1-133servicename.exp file A-14servicename.str file A-14Session, information in SMI

tables 2-25, 2-26SET EXPLAIN ON example 8-46SET STATEMENT CACHE ON

statement 3-56Setting the data replication

type 3-46Shared library files A-7Shared memory

adding segment withonmode 3-48

base address 1-135buffer, frequency of flushing 1-77buffer, maximum number 1-27changing residency with

onmode 3-43changing with onmode 3-52dumps 1-60, 1-62examining with SMI 2-6initializing 3-26monitoring 3-88physical-log buffer 1-117resident portion, flag 1-125saving copy of with onstat 3-91segments, dynamically added,

size of 1-134size displayed by onstat 3-93use of SERVERNUM

parameter 1-133virtual segment, initial size 1-137

SHMADD parameter64-bit addressing 1-134description of 1-134

SHMBASE parameter 1-135shmem file

and DUMPSHMEMparameter 1-62

shmem.xxx A-15SHMTOTAL parameter 1-136



SHMVIRTSIZE parameter64-bit addressing 1-137description of 1-137

Shutting down the databaseserver 3-39, 3-40

Simple large objectsloading with external tables 8-32,

8-38pipe staging 8-40

SINGLE_CPU_VP parameter 1-139Size, index fragments 7-14Smart large object

default name 1-131logging 3-71, 3-73logical-log records 6-21statistics for user-defined

data 1-144SMI table

Backup Scheduler tables 2-10description of 2-6list of supported tables 2-8See also sysmaster database;

System-monitoring interface.sm_versions.std file A-15snmpd.log file A-15Software dependencies Intro-4SQL code Intro-17SQL statement cache, changing

usage 3-56SQLCA, warning flag when

fragment skipped duringquery 1-35

sqlexec thread C-2sqlhosts file A-15sqlhosts file and registry, multiple

dbservernames 1-37sqlmux, multiplexed connections in

NETTYPE parameter 1-99STACKSIZE parameter 1-140STAGEBLOB parameter 1-141Staging. See Pipe staging.STANDARD table

deluxe-mode load 8-13, 8-15recovery of 8-52

Starting database server withoninit 3-26

STATIC tableloading data 8-29recovery of 8-52

Statistics. See onstat utility.STMT_CACHE environment

variables 3-56STMT_CACHE parameter 1-142STMT_CACHE_SIZE

parameter 1-142Storage manager

and onstat -g bus_sm 3-105xbsa.messages log A-16

stores_demo database Intro-5Structured Query Language (SQL)

UPDATE STATISTICSstatement 1-144

superstores_demo database Intro-5Suspension, thread. See Thread

Suspension.Symbolic link

using with shared libraries A-8using with TAPEDEV 1-146

SYNC logical-log record 6-19sysadtinfo table 2-11SYSALARMPROGRAM

parameter 1-143sysaudit table 2-12sysbuobject table 2-10sysbuobjses table 2-10sysbusession table 2-10sysbusm table 2-10sysbusmdbspace table 2-10sysbusmlog table 2-11sysbusmworker table 2-11sysbuworker table 2-11syschkio table 2-13syschunks table 2-13syscogroupmembers table 2-33syscogroups table 2-33sysconfig table 2-15sysdatabases table 2-16sysdbslocale table 2-17sysdbspaces table 2-17sysdri table 2-19sysessions table 2-28sysextents table 2-20sysextspaces table 2-20syslocks table 2-21syslogd (UNIX message log) 1-24syslogs table 2-22

sysmaster databasebuildsmi.xxx file A-6description 2-3failure to build A-6functionality of 2-3initialization 3-26list of topics covered by 2-6SMI tables 2-6space required to build 2-5sysextspaces 2-20types of tables 2-3warning 2-4when created 2-4See also SMI table; System-

monitoring interface.sysprofile table 2-23sysptprof table 2-25SYSSBSPACENAME

parameter 1-144syssesprof table 2-26sysseswts table 2-30systabnames table 2-31, 3-179System catalog tables

and oncheck 3-15checking with onutil 3-170disk space allocation for 7-45how tracked 7-46listing 3-12, 3-186sysdistrib 1-144sysfragments table 7-11systraceclasses B-2systracemsgs B-2tracking a new database 7-46tracking a new table 7-47

System requirementsdatabase Intro-4software Intro-4

System-monitoring interface (SMI)accessing SMI tables 2-7and locking 2-8and SPL 2-8and triggers 2-7description 2-3obtaining onstat information 2-37tables

Backup Scheduler tables 2-10list of supported 2-8sysadtinfo 2-11sysaudit 2-12

Index 17


sysbuobject 2-10sysbuobjses 2-10sysbusession 2-10sysbusm 2-10sysbusmdbspace 2-10sysbusmlog 2-11sysbusmworker 2-11sysbuworker 2-11syschkio 2-13syschunks 2-13syscogroupmembers 2-33syscogroups 2-33sysconfig 2-15sysdatabases 2-16sysdbslocale 2-17sysdbspaces 2-17sysdri 2-19sysextents 2-20sysextspaces 2-20syslocks 2-21syslogs 2-22sysprofile 2-23sysptprof 2-25syssesprof 2-26syssessions 2-28sysseswts 2-30systabnames 2-31sysvpprof 2-32

using SELECT statements 2-7viewing tables with dbaccess 2-7See also SMI table.

systraceclasses system catalogtable B-2

systracemsgs system catalogtable B-2

sysutil tables 2-10sysvpprof table 2-32

TTable

creating, what happens ondisk 7-45, 7-46

displaying allocationinformation 3-22

migration. See also InformixMigration Guide.

monitoring with SMI 2-31

naming conventions 3-151, 3-194pseudotables 2-6SMI tables 2-6temporary

effects of creating 7-48message reporting cleanup 5-17

TABLOCKS logical-log record 6-20tail -f command 5-4Tape device, block size 1-80TAPEBLK parameter 1-145TAPEDEV parameter

description of 1-146using a symbolic link 1-146

TAPESIZE parameter 1-147Tblspace


displaying information withonstat -t 3-125

for table fragment 7-11, 7-27monitoring with SMI 2-25number 7-10

displayed 3-125elements 7-11

Tblspace numberdescription of 7-10displaying with onstat -t 3-125for table fragment 7-11includes dbspace number 7-10

Tblspace tblspacebit-map page 7-12description of 7-9entries 7-9location in a chunk 7-5location in root dbspace 7-4size 7-11structure and function 7-9tracking new tables 7-47

TBLSPACE_STATSparameter 1-148

TemplateAC_CONFIG file A-6ONCONFIG file

multicoserver A-11standard A-11

Temporary dbspacecreating 3-207, 3-210staging of simple large

objects 8-41

Temporary tableDBSPACETEMP parameter 1-40rules for use 1-41with oninit utility 3-27

TEXT and BYTE datadescriptor, description of 7-22,

7-37effect of modifying on

storage 7-38role of descriptor 7-38role of descriptor in storage 7-37size limitations 7-38storage on disk 7-37storing 7-36updating 7-38when modified 7-38when written 7-37

TEXT data typeSee Simple large objects.

TEXT external typedefinition of 8-35SQL example 8-35

Threadcoserver 8-10onstat -X usage 3-92, 3-131suspension

monitoring C-3primary threads C-2reporting and clearing C-5secondary threads C-2

Thread suspension C-1Time stamp, blobspace

blobpage 7-40Time-out condition 3-104Tip icons Intro-13Trace class B-2Trace message B-2Tracepoints B-2Transaction

heterogeneous commit 1-64kill with onmode -Z 3-45pending 3-129

Transaction logging. See Logging.Trapping errors with onmode B-1TRUNCATE statement 8-30Truncating a table 8-30Tuning

large number of users 1-97use of NETTYPE parameter 1-96



Two-phase commit protocol, killingdistributed transactions 3-45

TXTIMEOUT parameterand onmode utility 3-45description of 1-149

UUDINSERT


UDUPAFTlogical-log record 6-20record subtype (SBLOB) 6-23

UDUPBEFlogical-log record 6-20record subtype (SBLOB) 6-23

UDWRITElogical-log record 6-20record subtype (SBLOB) 6-23

Unblocking database server 3-42Unbuffered transaction logging. See

Logging.UNDO logical-log record 6-20UNDOBLDC logical-log

record 6-20UNIQID logical-log record 6-21Unique constraints and violations

table 8-5UNIX operating system, default

locale for Intro-4Unloading data

from a fixed-ASCII file 8-21from Informix internal

format 8-33named pipes 8-25to a delimited file 8-17, 8-34to an Informix file 8-19

UPDAFT logical-log record 6-21UPDATE STATISTICS statement

DROP DISTRIBUTIONS 1-144HIGH mode 1-144MEDIUM mode 1-144

UPDBEF logical-log record 6-21USEOSTIME parameter 1-149

User sessionmonitoring with SMI 2-28status codes 3-126

User-defined aggregate, definitionsin cache (onstat -g cacagg) 3-105

User-defined data type, datadistributions 1-144

User-defined routines,debugging B-2

Users, types of Intro-3Utilities

gcore 1-58, 1-61oncheck 3-5onclean B-3ondblog 3-24oninit 3-26onlog 3-31onmode 3-37onparams 3-57onspaces 3-62onstat 3-88ontape 3-132onutil 3-135-V option 3-4xctl 3-227

V-V option 3-4VARCHAR data type

4-bit bit map requirement 7-14,7-17

implications for data rowstorage 7-25

indexing considerations 7-34storage considerations 7-22

Violations tabledeferred constraints 8-16description of 8-4errors 8-51messages 5-50, 5-53referential or unique

constraints 8-5, 8-30

Virtual processoradding or removing with

onmode 3-49number in

AIO class 1-101CPU class 1-102FIF class 1-103, 8-46

priority aging 1-99VPCLASS parameter

and AFF_NPROCS 1-21and AFF_SPROC 1-22and NOAGE 1-99and NUMAIOVPS 1-101and onmode utility 3-50default values 1-152description of 1-151in ONCONFIG file 1-151reserved names 1-153setting maximum VPs 1-156setting number of VPs 1-155setting processor affinity 1-156use by

DS_TOTAL_MEMORY 1-56user-defined classes 1-154

VP.servername.nnx file A-16

WWarning

buildsmi script 2-5when fragment skipped during

query processing 1-35Warning icons Intro-13White space in ONCONFIG file 1-7wids 7-23Windows NT

adding or removing virtualprocessors 3-50

default locale for Intro-4

Index 19


XXAPREPARE logical-log

record 6-21xbsa.messages log A-16xcfg_servername.servernum

file A-16xctl utility

environment variables for 3-229execution on multiple

coservers 3-231hosts file 3-228selecting type of processing

background 3-230interactive 3-231

specifying coservers 3-230syntax 3-227working directory 3-229

xlc (xload load converter) 8-6xlcnv (load converter) 8-47xlr (xload load reader) 8-6xlread instance

and pipe staging 8-41, 8-43coservers 8-46

XMF configurationparameters 1-158

XMF (eXtended MessageFacility) 1-158

XMP query plan 8-47X/Open compliance level Intro-21x_exec_* thread C-2

Symbols%c formatting character 3-143,

3-148, 3-153, 3-197%n formatting character 3-143,

3-148%o formatting character 3-143,

3-148%r formatting character 3-141


Documents

Oninitii Informix Administrator’s Reference Published by Informix Press Informix Corporation 4100 Bohannon Drive Menlo Park, CA 94025-1032 © 1999 Informix Corporation