IBM solidDB

IBM solidDB Universal Cache

Version 6.5

Administrator Guide



SC23-9869-05
 Note
Before using this information and the product it supports, read the information in “Notices” on page 331.

First edition, fifth revision

This edition applies to version 6, release 5, Fix Pack 12 of IBM solidDB (product number 5724-V17) and IBM
solidDB Universal Cache (product number 5724-W91) and to all subsequent releases and modifications until
otherwise indicated in new editions.

Note: Information in this document might have been updated since this document was made available. For the
latest available information, see the IBM solidDB and IBM solidDB Universal Cache V6.5 Information Center at
http://pic.dhe.ibm.com/infocenter/soliddb/v6r5/index.jsp.
© Oy International Business Machines Ab Ltd. 1993, 2012
Contents
Figures . . . . . . . . . . . . . . vii Making backups over network . . . . . . . 28
Configuring and automating backups . . . . 30
Tables . . . . . . . . . . . . . . . ix What happens during backup . . . . . . . 31
Administering network backup server . . . . 32
Monitoring and controlling backups . . . . . 33
Summary of changes . . . . . . . . . xi Correcting a failed backup . . . . . . . . 33
Troubleshooting backups . . . . . . . . . 34
About this manual . . . . . . . . . . xv Restoring backups . . . . . . . . . . . 34
Typographic conventions . . . . . . . . . . xv Transaction logging. . . . . . . . . . . 35
Syntax notation conventions . . . . . . . . xvi Creating checkpoints . . . . . . . . . . . 36
Entering timed commands . . . . . . . . . 36
1 solidDB fundamentals . . . . . . . . 1 Compacting database files (database reorganization) 37
solidDB data management components . . . . . 1 Encrypting a database . . . . . . . . . . . 38
Programming interfaces (ODBC and JDBC) . . . 2 Encrypting database and log files . . . . . . 38
Network communications layer . . . . . . . 3 Disabling encryption . . . . . . . . . . 39
SQL parser and optimizer . . . . . . . . . 3 Starting an encrypted database . . . . . . . 40
solidDB . . . . . . . . . . . . . . . 3 Changing the encryption password . . . . . 40
System tools and utilities . . . . . . . . . 4 Decrypting a database . . . . . . . . . . 41
Automated and manual administration . . . . 5 Querying database encryption level . . . . . 41
solidDB architecture . . . . . . . . . . . . 5 Making backups of encrypted databases . . . . 41
Data storage for disk-based tables . . . . . . 5 Encrypting HotStandby servers . . . . . . . 41
Data storage for memory-based tables . . . . . 6 Encryption and performance . . . . . . . 41
solidDB SQL optimizer . . . . . . . . . . 7
solidDB Network Services . . . . . . . . . 8 3 Configuring solidDB . . . . . . . . 43
Multithread processing . . . . . . . . . . 8 Managing parameters . . . . . . . . . . . 43
Configuration files and parameter settings . . . 44
2 Administering solidDB . . . . . . . 11 Viewing and setting parameters with ADMIN
User roles for database administration . . . . . 11 COMMAND . . . . . . . . . . . . . 45
Starting and stopping solidDB . . . . . . . . 11 Setting parameters through the solid.ini
Starting solidDB . . . . . . . . . . . . 11 configuration file . . . . . . . . . . . 49
Closing a database . . . . . . . . . . . 13 Format of configuration parameter names and
Shutting down solidDB . . . . . . . . . 14 values . . . . . . . . . . . . . . . 52
Creating a new database . . . . . . . . . . 15 Most important server-side parameters . . . . 53
Usernames, passwords, and system catalog Most important client-side parameters . . . . 58
names . . . . . . . . . . . . . . . 15 Using solidDB command line options. . . . . . 60
Unicode and partial Unicode database modes . . 16 Setting solidDB-specific environment variables . . 60
Setting up database environment . . . . . . 17
solidDB configuration file (solid.ini) . . . . 19 4 Monitoring solidDB . . . . . . . . 63
Setting database block size (BlockSize) and Viewing error messages and log files . . . . . . 63
location (FileSpec) . . . . . . . . . . . 19 Controlling message log output. . . . . . . 63
Defining database objects . . . . . . . . . 20 Viewing error message descriptions with ADMIN
Connecting to solidDB with solidDB tools (solsql COMMAND 'errorcode' . . . . . . . . . . 64
and solcon) . . . . . . . . . . . . . . 20 Using trace files . . . . . . . . . . . . 64
Running solidDB as a Windows service . . . . . 21 Tracing failed login attempts . . . . . . . 64
Starting solidDB as a service for the first time . . 21 Checking solidDB version . . . . . . . . . 65
Starting and stopping solidDB services . . . . 23 Checking overall database status . . . . . . . 65
Removing solidDB services . . . . . . . . 23 Obtaining currently connected users . . . . . . 66
Running several servers on one computer . . . . 24 Throwing out a connected solidDB user . . . . . 66
Using solidDB with SELinux . . . . . . . . 25 Querying the status of the most recent backup . . 66
Using solidDB audit trail (AuditTrailEnabled) . . . 26 Producing status reports . . . . . . . . . . 66
Enabling and disabling audit trail . . . . . . 27 Performance counters (perfmon) . . . . . . . 67
Querying audit trail data in the ADMIN COMMAND 'perfmon'. . . . . . . . . 67
SYS_AUDIT_TRAIL system table . . . . . . 27 ADMIN COMMAND 'perfmon diff' - producing a
Performing backup and recovery . . . . . . . 27 continuous performance monitoring report . . . 68
Making local backups . . . . . . . . . . 28 Full list of perfmon counters. . . . . . . . 68

iii
5 Managing network connections . . . 81 Tuning network messages . . . . . . . . . 131
Communication between client and server . . . . 81 Tuning I/O . . . . . . . . . . . . . . 132
Network listening names (Com.Listen) . . . . . 81 Distributing I/O . . . . . . . . . . . 132
Viewing supported protocols for the server . . . 83 Setting the MergeInterval parameter. . . . . 132
Viewing network names for the server . . . . 83 Tuning checkpoints . . . . . . . . . . . 133
Adding and modifying a network name for the Reducing Bonsai Tree size by committing
server . . . . . . . . . . . . . . . 84 transactions . . . . . . . . . . . . . . 134
Removing network name from the server . . . 84 Preventing excessive Bonsai Tree growth . . . 134
Connect strings for clients . . . . . . . . . 84 Diagnosing poor performance . . . . . . . . 136
Default connect string (Com.Connect) . . . . 86
Logical data source names . . . . . . . . 86 8 Troubleshooting and support. . . . 139
Communication protocols . . . . . . . . . 87 Troubleshooting a problem . . . . . . . . . 139
TCP/IP protocol . . . . . . . . . . . . 88 Tools for troubleshooting . . . . . . . . 141
UNIX Pipes . . . . . . . . . . . . . 89 Troubleshooting solidDB Universal Cache . . . 147
Named Pipes . . . . . . . . . . . . . 90 Troubleshooting SMA . . . . . . . . . 149
Shared Memory . . . . . . . . . . . . 90 Troubleshooting database file size (file write
Summary of protocols . . . . . . . . . . 91 fails) . . . . . . . . . . . . . . . 151
Troubleshooting MME.ImdbMemoryLimit . . . 152
6 Using solidDB data management Troubleshooting solidDB Data Dictionary
tools. . . . . . . . . . . . . . . . 93 (soldd) . . . . . . . . . . . . . . 153
solidDB Remote Control (solcon) . . . . . . . 93 Searching knowledge bases . . . . . . . . . 154
Starting solidDB Remote Control (solcon) . . . 94 Getting fixes. . . . . . . . . . . . . . 155
Entering commands in solidDB Remote Control IBM Software Support for solidDB and solidDB
(solcon). . . . . . . . . . . . . . . 95 Universal Cache . . . . . . . . . . . . 155
solidDB SQL Editor (solsql) . . . . . . . . . 95 Contacting IBM Support. . . . . . . . . 155
Starting solidDB SQL Editor . . . . . . . . 96 Collecting diagnostics data . . . . . . . . 157
Executing SQL statements with solidDB SQL Subscribing to Support and other updates . . . 162
Editor . . . . . . . . . . . . . . . 98
Executing an SQL script from a file . . . . . 98 Appendix A. Server-side configuration
solidDB SQL Editor (solsql) commands . . . . 99 parameters . . . . . . . . . . . . 165
solidDB Speed Loader (solloado and solload). . . 100 Accelerator section . . . . . . . . . . . 165
File types. . . . . . . . . . . . . . 100 Cluster section . . . . . . . . . . . . . 166
Starting solidDB Speed Loader (solloado and Communication section . . . . . . . . . . 166
solload) . . . . . . . . . . . . . . 101 General section . . . . . . . . . . . . . 168
Tips for speeding up loading . . . . . . . 104 HotStandby section . . . . . . . . . . . 179
Examples . . . . . . . . . . . . . . 104 IndexFile section . . . . . . . . . . . . 182
Control file syntax. . . . . . . . . . . 106 Logging section . . . . . . . . . . . . 184
solidDB Export (solexp) . . . . . . . . . . 114 LogReader section . . . . . . . . . . . . 187
Starting solidDB Export (solexp) . . . . . . 114 MME section . . . . . . . . . . . . . 189
solidDB Data Dictionary (soldd) . . . . . . . 116 Passthrough section . . . . . . . . . . . 193
Starting solidDB Data Dictionary (soldd) . . . 116 SharedMemoryAccess section . . . . . . . . 195
Entering password from a file . . . . . . . . 119 Sorter section . . . . . . . . . . . . . 196
Configuration file . . . . . . . . . . . . 119 SQL section . . . . . . . . . . . . . . 197
Using solidDB tools with Unicode . . . . . . 120 Srv section . . . . . . . . . . . . . . 201
Example: Reloading a database using solidDB tools 121 Synchronizer section . . . . . . . . . . . 214

7 Performance tuning . . . . . . . . 123 Appendix B. Client-side configuration

Logging and transaction durability . . . . . . 123 parameters . . . . . . . . . . . . 217
Background . . . . . . . . . . . . . 123 Client section . . . . . . . . . . . . . 217
Balancing performance and safety . . . . . 124 Communication section . . . . . . . . . . 218
How relaxed transaction durability can improve Data sources section . . . . . . . . . . . 219
performance . . . . . . . . . . . . . 125 SharedMemoryAccess section . . . . . . . . 220
Choosing transaction isolation levels . . . . . 125 TransparentFailover section. . . . . . . . . 220
Setting the isolation level . . . . . . . . 126
Controlling memory consumption . . . . . . 126
Appendix C. solidDB command line
Controlling process size . . . . . . . . . 126
Tuning your operating system . . . . . . . 128 options . . . . . . . . . . . . . . 221
Database cache . . . . . . . . . . . . 129
Sorting . . . . . . . . . . . . . . 130 Appendix D. Environment variables 225
Using in-memory database . . . . . . . . 131

iv IBM solidDB: Administrator Guide

Appendix E. Error codes . . . . . . 227 solidDB LOG (logging) messages . . . . . . . 294
solidDB system errors . . . . . . . . . . 229 solidDB INI (configuration file) messages . . . . 294
solidDB database errors . . . . . . . . . . 232 solidDB HSB (HotStandby) errors and messages 295
solidDB table errors . . . . . . . . . . . 241 solidDB SNC (synchronization) messages . . . . 297
solidDB session errors . . . . . . . . . . 256 solidDB XS (external sorter) errors and messages 298
solidDB communication errors. . . . . . . . 257 solidDB FIL (file system) messages . . . . . . 298
solidDB server errors . . . . . . . . . . . 260 solidDB TAB (table) messages . . . . . . . . 299
solidDB procedure errors . . . . . . . . . 266 solidDB SMA (shared memory access) errors . . . 299
solidDB API errors . . . . . . . . . . . 269 solidDB PT (passthrough) errors . . . . . . . 299
solidDB sorter errors . . . . . . . . . . . 269 solidDB SQL errors . . . . . . . . . . . 300
solidDB RPC errors and messages . . . . . . 270 solidDB executable errors . . . . . . . . . 306
solidDB synchronization errors . . . . . . . 271 solidDB Speed Loader (solloado and solload) errors 307
solidDB HotStandby errors . . . . . . . . . 286
solidDB SSA (SQL API) errors . . . . . . . . 287 Appendix F. solidDB ADMIN
solidDB COM (communication) messages . . . . 288 COMMAND syntax . . . . . . . . . 309
solidDB SRV (server) errors . . . . . . . . 289 ADMIN COMMAND . . . . . . . . . . 309
solidDB DBE (database engine) errors and
messages . . . . . . . . . . . . . . . 291
Index . . . . . . . . . . . . . . . 323
solidDB CP (checkpoint) messages . . . . . . 293
solidDB BCKP (backup) messages . . . . . . 293
solidDB AT (timed commands) messages . . . . 293 Notices . . . . . . . . . . . . . . 331

Contents v
vi IBM solidDB: Administrator Guide
Figures
1. solidDB components . . . . . . . . . . 2 2. solidDB components . . . . . . . . . . 4

vii
viii IBM solidDB: Administrator Guide
Tables
1. Typographic conventions . . . . . . . . xv 46. Communication parameters . . . . . . . 166
2. Syntax notation conventions. . . . . . . xvi 47. General parameters . . . . . . . . . 168
3. Starting the server . . . . . . . . . . 12 48. HotStandby parameters . . . . . . . . 179
4. solidDB default files . . . . . . . . . 18 49. IndexFile parameters . . . . . . . . . 182
5. Connecting to solidDB . . . . . . . . . 21 50. Logging parameters . . . . . . . . . 184
6. Options for the backup command . . . . . 28 51. Log Reader parameters . . . . . . . . 187
7. Options for the netbackup command . . . . 29 52. MME parameters . . . . . . . . . . 189
8. Parameter correspondence to the solid.ini file 53. SQL passthrough parameters . . . . . . 193
for local backup . . . . . . . . . . . 30 54. Shared memory access parameters . . . . 195
9. Parameter correspondence to the solid.ini file 55. Sorter parameters . . . . . . . . . . 196
for netbackup . . . . . . . . . . . . 30 56. SQL parameters . . . . . . . . . . . 197
10. Backup and netbackup commands . . . . . 33 57. Srv parameters . . . . . . . . . . . 201
11. Arguments and defaults for different timed 58. Synchronizer parameters . . . . . . . . 214
commands . . . . . . . . . . . . . 37 59. Client parameters . . . . . . . . . . 217
12. Connect string options . . . . . . . . . 59 60. Communication parameters . . . . . . . 218
13. solidDB environment variables . . . . . . 61 61. Data Sources parameters . . . . . . . . 219
14. Perfmon counters . . . . . . . . . . 68 62. Shared memory access parameters
15. Network listening name options . . . . . 82 (client-side) . . . . . . . . . . . . 220
16. Com.Listen factory values . . . . . . . . 83 63. TransparentFailover parameters . . . . . 220
17. Connect string options . . . . . . . . . 85 64. solidDB environment variables. . . . . . 225
18. TCP/IP protocol in the network listening name 65. solidDB error categories . . . . . . . . 227
(Com.Listen) . . . . . . . . . . . . 88 66. solidDB system errors. . . . . . . . . 229
19. TCP/IP protocol in the client connect string 67. solidDB database errors . . . . . . . . 232
(Com.Connect) . . . . . . . . . . . . 88 68. solidDB session errors . . . . . . . . 256
20. UNIX Pipes protocol in the network name 89 69. solidDB communication errors . . . . . . 257
21. Named Pipes protocol in the network name 90 70. solidDB server errors . . . . . . . . . 260
22. Shared Memory protocol in the network name 90 71. solidDB SA API errors . . . . . . . . 269
23. solidDB protocols and network names . . . 91 72. solidDB sorter errors . . . . . . . . . 269
24. Application protocols and network names 91 73. solidDB RPC errors and messages . . . . 270
25. solcon command options . . . . . . . . 94 74. solidDB synchronization errors. . . . . . 271
26. solcon specific commands . . . . . . . . 95 75. solidDB HotStandby errors . . . . . . . 286
27. solsql command options . . . . . . . . 96 76. solidDB SSA (SQL API) errors . . . . . . 287
28. solidDB SQL Editor (solsql) commands 99 77. solidDB COM (communication) messages 288
29. solloado and solload command options 102 78. solidDB SRV errors . . . . . . . . . 289
30. Speed Loader reserved words . . . . . . 106 79. solidDB DBE errors and messages . . . . 291
31. Full syntax of the control file . . . . . . 106 80. solidDB CP (checkpoint) messages . . . . 293
32. Data masks . . . . . . . . . . . . 108 81. solidDB BCKP (backup) messages. . . . . 293
33. solexp command options. . . . . . . . 114 82. solidDB AT (timed commands) messages 293
34. soldd command line options . . . . . . 117 83. solidDB LOG (logging) messages . . . . . 294
35. Command line options for solidDB tools for 84. solidDB INI (configuration file) messages 294
partial Unicode and Unicode databases . . . 121 85. solidDB HSB errors and messages . . . . 295
36. Determining command status . . . . . . 135 86. solidDB SNC (synchronization) messages 297
37. Determining which connections have 87. solidDB XS (external sorter) errors . . . . 298
committed transactions . . . . . . . . 135 88. solidDB FIL (file system) messages . . . . 298
38. Diagnosing poor performance . . . . . . 136 89. solidDB TAB (table) messages . . . . . . 299
39. SQL Info levels . . . . . . . . . . . 142 90. solidDB SMA (shared memory access) errors 299
40. Ping facility levels . . . . . . . . . . 146 91. solidDB passthrough errors . . . . . . . 299
41. SMA default address spaces. . . . . . . 150 92. solidDB SQL errors . . . . . . . . . 300
42. solidsupport . . . . . . . . . . . 157 93. solidDB executable errors . . . . . . . 306
43. solidDB Support Assistant (solidsupport) 94. solidDB Speed Loader (solloado and solload)
options . . . . . . . . . . . . . 158 errors . . . . . . . . . . . . . . 307
44. Accelerator parameters . . . . . . . . 165 95. ADMIN COMMAND syntax and options 310
45. Cluster parameters. . . . . . . . . . 166

ix
x IBM solidDB: Administrator Guide
Summary of changes
Changes for revision 05
v Editorial corrections.

Changes for revision 04

v Information about the ADMIN COMMAND 'userlist' command updated in
section ADMIN COMMAND. As of V6.5 Fix Pack 10, the ODBC and JDBC client
version is included in the ADMIN COMMAND 'userlist' printouts.
v Parameter changes in section Server-side configuration parameters:
– New parameters added:
- Srv.InifileLineSplitting
- Srv.MaxUsers
- Srv.ReportInterval
– Factory value for server-side parameter Com.SocketLinger changed from yes
to no.
– Factory value for server-side parameters SQL.InfoFileSize,
Srv.MessageLogSize, and TraceLogSize changed from 1M to 10M.
– Factory value for server-side parameter Srv.TraceSecDecimals changed from
0 to 3.
v Description of error message 14507 updated in section solidDB® server errors:
Server Error 14507: Exceeded maximum number of user connections defined
with Srv.MaxUsers or limited by license. Only connections from solcon
allowed..
v Section for client-side parameter ODBCHandleValidation corrected; the
ODBCHandleValidation is in the Client section.
v New performance counters for Fix Pack 9 added in section Full list of perfmon
counters; see Release Notes for Fix Pack 9 for details.
v Previously undocumented client-side parameters Com.SocketLinger and
Com.SocketLingerTime added in section Client-side configuration parameters.
v Information about error message Server Error 14534: Only administrative
statements are allowed. updated in section solidDB server errors. The error is
returned when the solidDB process size has exceeded the limit set with
parameter Srv.ProcessMemoryLimit.
v The use of quotation marks in ADMIN COMMAND clarified in section ADMIN
COMMAND: the command_name in ADMIN COMMAND 'command_name' must
be given with single quotation marks.

Changes for revision 03

v Information about using encrypted databases when running solidDB as a
Windows service added in section Starting solidDB as a service for the first time.
The encryption password must be provided with the -S<password>
command-line option when installing the service.
v New performance counters for Fix Pack 8 added in section Full list of perfmon
counters; see Release Notes for Fix Pack 8 for details.
v New parameter General.BackupFlushInterval added in section General section.
v New parameters Transparent.ReconnectTimeout and Transparent.WaitTimeout
added in section TransparentFailover section.

xi
 v Formatting rules for solid.ini file clarified in section Rules for formatting the
solid.ini file; the maximum line length is 79 characters.
v ADMIN COMMAND ’info’ updated in section ADMIN COMMAND: added unit
values for all size related output options.
v ADMIN COMMAND ’filespec’ and ADMIN COMMAND ’parameter’ updated
in section ADMIN COMMAND:
– Previously undocumented options -d and -a added to ADMIN COMMAND
’filespec’.
– Previously undocumented option -t added to ADMIN COMMAND
’parameter’.
v Section Troubleshooting database file size (file write fails) updated: new database
file specifications can be added dynamically with the command ADMIN
COMMAND ’filespec -a’
v Section Troubleshooting backups updated with information about backups that
can slow down the database.
v New High Availability Controller (HAC) related option added for solidDB
Support Assistant (solidsupport) in section solidDB Support Assistant: option -c
HAC_directory_path specifies the location of the HAC related message and trace
files.
v New section added: Using solidDB with SELinux
v New error codes for Fix Pack 5 added is section Error codes; see Release Notes for
Fix Pack 5 for details.
v Missing solidDB SQL Editor (solsql) startup option -tt added in section
Starting solidDB SQL Editor; option -tt prints the prepare, execute, fetch, and
execution time for each command executed in solsql.

Changes for revision 02

v New performance counters for Fix Pack 4 added in section Full list of perfmon
counters; see Release Notes for Fix Pack 4 for details.
v New error codes for Fix Pack 4 added is section Error codes; see Release Notes for
Fix Pack 4 for details.
v Information about the behavior and factory values of the following parameters
has been updated:
– General.MultiprocessingLevel in section General section
– MME.RestoreThreads in section MME section
– Srv.ProcessMemoryLimit in section Srv section
– Sorter.MaxMemPerSort and Sorter.MaxCacheUsePercent in section Sorter
section
v ADMIN COMMAND 'trace' command updated in section ADMIN COMMAND
– New option 'hac' added for tracing High Availability Controller (HAC)
– The following undocumented options added:
- est - SQL estimator information
- estplans - SQL execution plan
- flow - advanced replication statements
- rexec - remote procedure call information
- batch - background job and deferred procedure call information
- xa - distributed transaction information
v Recovery information for Database error 10031 updated in section solidDB
database errors: The error can be caused by lock wait timeouts or deadlocks. To

xii IBM solidDB: Administrator Guide

 avoid lock timeouts, you need to adjust the lock wait timeout settings. To avoid
deadlocks, adjust the data access order in concurrent transactions.
v New section added: solidDB SQL Editor (solsql) commands
v Information about the usage of the Srv.ProcessMemoryLimit parameter updated
in section Srv section: you should not set the Srv.ProcessMemoryLimit parameter
when using SMA. If you need to limit the memory the SMA server uses, use the
SharedMemoryAccess.MaxSharedMemorySize parameter.
v Information about the usage of the General.CheckpointDeleteLog parameter
updated in section General section: if LogReader.LogReaderEnabled is set to 'yes',
the CheckpointDeleteLog parameter is not effective: the log files are not deleted
after a checkpoint. Instead, the log entries are removed only after the log size
defined by LogReader.MaxLogSize has been reached.
v New sections added:
– Checking solidDB version
– Troubleshooting database file size (file write fails)

Changes for revision 01

v Information on TCP/IPv6 protocol added in section TCP/IP protocol.
v New parameters added in section Server-side configuration parameters:
– MME.MaxTransactionSize
– MME.MemoryPoolScope
– Passthrough.ComplexNumNonindexedConstr
– Passthrough.ComplexNumOrderedRows
– Passthrough.ComplexNumTables
v New performance counters for Fix Pack 3 added in section Full list of perfmon
counters; see Release Notes for Fix Pack 3Release Notes for Fix Pack 3 for details.
v New error messages added in section Error codes; see Release Notes for Fix Pack
3Release Notes for Fix Pack 3 for details.
v Information on the support of IndexFile.DirectIO and Logging.DirectIO
parameters added in section Server-side configuration parameters: these
parameters are not effective in Windows environments; in Windows
environments, database files always use Direct I/O.
v solidDB Speed Loader (solloado and solload) updates for Fix Pack 2 in section
solidDB Speed Loader (solloado and solload)
– New ODBC-based solloado added.
– New month format B (three-letter abbreviation in English, for example,
01-DEC-2010) added for DATE and TIMESTAMP masks in section DATE,
TIME, and TIMESTAMP.
v New section Troubleshooting and support added, including details on the
solidDB Support Assistant introduced in Fix Pack 2.
v New Fix Pack 2 parameters Srv.StackTraceEnabled,
SharedMemoryAccess.SignalHandler, and SharedMemoryAccess.Signals added in
sections Srv section and Client-side configuration parameters.
v New performance counters added in section Full list of perfmon counters; see
Release Notes for Fix Pack 2Release Notes for Fix Pack 2 for details.
v New error codes added in section Error codes; see Release Notes for Fix Pack
2Release Notes for Fix Pack 2 for details.
v Missing options -I and -i for ADMIN COMMAND ’netbackup’ added in section
Making netbackup.

Summary of changes xiii

 v Factory value for connection (read) timeout corrected from 60 000 milliseconds
to 0 (infinite); client-side parameters Com.ClientReadTimeout and Com.Connect,
option -rmilliseconds updated in sections Connect strings for clients and
Communication section.
v Section SQL section updated: the SQL.CharPadding=yes parameter setting is not
effective in Unicode databases; blank characters in CHAR values are always
discarded.
v Missing solidDB SQL Editor (solsql) startup options -S <schema name> and -C
<catalog name> added in section Starting { IDEP206A: File not found. } SQL
Editor.
v New parameter Accelerator.ReturnListenErrors (FP1) added in Accelerator
section.
v New parameter Passthrough.Force32bitODBCHandles (FP1) added in
Passthrough section.
v Section Full list of perfmon counters updated with new FP1 counters.
v Missing parameters added in section Server-side configuration parameters:
– General.UseEncryption (Interim Fix 01)
– SQL.SQLInfo
– MME.MaxBytesCachedInPrivateMemoryPool
v Factory value for parameter General.LockHashSize changed from 1000 to
1000000 in General section (Interim Fix 01).
v Section Error codes updated to correspond to ADMIN COMMAND ’errorcode all’
output. Previously undocumented messages added in the following sections:
– API errors
– AT (timed commands) messages
– BCKP (backup) messages
– COM (communication) messages
– CP (checkpoint) messages
– DBE (database engine) errors and messages
– FIL (file system) messages
– HSB (HotStandby) errors and messages
– INI (configuration file) messages
– LOG (logging) messages
– RPC errors and messages
– SMA (shared memory access) errors
– SNC (synchronization) messages
– SRV (server) errors
– TAB (table) messages
– XS (external sorter) errors and messages
v New section added: Viewing error message descriptions with ADMIN COMMAND
’errorcode’
v Information about creating database in the Unicode mode added in section
Unicode and partial Unicode database modes.
v Factory default for parameter HotStandby.TCConnect corrected in section
HotStandby section; there is no factory value.
v List of performance counters updated in section Full list of perfmon counters.
v Section Encrypting a database updated; information about how to disable
encryption added.

xiv IBM solidDB: Administrator Guide

About this manual
IBM® solidDB is a versatile database management system that can be used in
systems starting from small embedded systems to large-scale systems. Various
functional solidDB components may be enacted to serve special needs. Such
components are:
v an in-memory database
v a highly available hot standby configuration
v advanced asynchronous replication
v a library for directly linking applications with the server code.

All of the above mentioned components are orthogonal, that is they can be used in
the presence of other components. An administrator of solidDB can use a wide
range of configuration options and tools to set up the product in the most
appropriate way.

This guide describes how to set up, monitor, manage, and optimize the basic
database server function of the product. More detailed information about
configuring specific solidDB components are included in the related manuals.

This guide assumes the reader has general database management system (DBMS)
knowledge and a familiarity with SQL.

Typographic conventions
solidDB documentation uses the following typographic conventions:
Table 1. Typographic conventions
Format Used for

Database table This font is used for all ordinary text.

NOT NULL Uppercase letters on this font indicate SQL keywords and
macro names.

solid.ini These fonts indicate file names and path expressions.

SET SYNC MASTER YES;

COMMIT WORK; This font is used for program code and program output.
Example SQL statements also use this font.

run.sh This font is used for sample command lines.

TRIG_COUNT() This font is used for function names.

java.sql.Connection This font is used for interface names.

LockHashSize This font is used for parameter names, function arguments,

and Windows registry entries.

argument Words emphasized like this indicate information that the

user or the application must provide.

xv
 Table 1. Typographic conventions (continued)
Format Used for

Administrator Guide This style is used for references to other documents, or

chapters in the same document. New terms and emphasized
issues are also written like this.

File path presentation Unless otherwise indicated, file paths are presented in the
UNIX format. The slash (/) character represents the
installation root directory.

Operating systems If documentation contains differences between operating

systems, the UNIX format is mentioned first. The Microsoft
Windows format is mentioned in parentheses after the
UNIX format. Other operating systems are separately
mentioned. There may also be different chapters for
different operating systems.

Syntax notation conventions

solidDB documentation uses the following syntax notation conventions:
Table 2. Syntax notation conventions
Format Used for

INSERT INTO table_name

Syntax descriptions are on this font. Replaceable sections are
on this font.

solid.ini This font indicates file names and path expressions.

[] Square brackets indicate optional items; if in bold text,

brackets must be included in the syntax.

| A vertical bar separates two mutually exclusive choices in a

syntax line.

{} Curly brackets delimit a set of mutually exclusive choices in

a syntax line; if in bold text, braces must be included in the
syntax.

... An ellipsis indicates that arguments can be repeated several

times.

.
. A column of three dots indicates continuation of previous
. lines of code.

xvi IBM solidDB: Administrator Guide

1 solidDB fundamentals
The core of solidDB is a relational database server. This database server accepts
queries in the SQL language. Usually, these SQL queries are submitted by a client
application that sends SQL statements to the server and receives result sets back
from the server.

In addition, solidDB has synchronization features that allow updated data in one
solidDB to be sent to one or more other solidDBs.

solidDB also allows you to run a pair of solidDBs in a hot standby configuration,
and link your client application directly to the database server routines for higher
performance and tighter control over the server. These features are called
HotStandby and shared memory access (SMA) or linked library access (LLA).

The sections below describe the underlying components and processes that make
solidDB the solution for managing distributed data in today's complex distributed
system environments. They provide background information necessary to
administer and maintain solidDB in your network environment.

solidDB data management components

The solidDB data management components are shown in the figure below and
described in the sections that follow.

1
 Application

ODBC 1 SA API JDBC

Network communication layer

Network communication layer

SQL parser and optimizer

Query executor

solidDB

solidDB
database

1. SA API is solidDB's own API for use with the shared memory access (SMA) or linked library access (LLA)
libraries. For details, see IBM solidDB Shared Memory Access and Linked Library Access User Guide.

Figure 1. solidDB components

Programming interfaces (ODBC and JDBC)

To submit a query (an SQL statement) to a database server, a client must be able to
communicate with that database server. solidDB, like many other database servers,
uses "drivers" to enable this communication. Client applications call functions in
the driver, and the driver then handles the communications and other details with
the server. For example, you might write a C program that calls functions in the
ODBC driver, or you might write a Java™ program that calls functions in the JDBC
driver.

ODBC
The solidDB ODBC Driver conforms to the Microsoft ODBC 3.51 API standard.
solidDB ODBC Driver supported functions are accessed with solidDB ODBC API, a
Call Level Interface (CLI) for solidDB databases, which is compliant with ANSI
X3H2 SQL CLI.

For more details on the solidDB ODBC Driver, see IBM solidDB Programmer Guide.

2 IBM solidDB: Administrator Guide

 JDBC
The solidDB JDBC Driver allows Java applications to access the database by using
JDBC. The solidDB JDBC Driver implements most of the JDBC 2.0 specification.

For more details on the solidDB JDBC Driver, see IBM solidDB Programmer Guide.

Proprietary interfaces
solidDB also provides two proprietary interfaces, solidDB Application
Programming Interface (SA API) and solidDB Server Control API (SSC API). These
allow, for example, C programs to directly call functions inside the database server.
These proprietary interfaces are provided with the solidDB shared memory access
(SMA) and linked library access (LLA) libraries.

For more details on the solidDB proprietary programming interfaces, see IBM
solidDB Shared Memory Access and Linked Library Access User Guide and IBM solidDB
Programmer Guide.

Network communications layer

solidDB runs on all major network types and supports all of the main
communication protocols (such as TCP/IP). Developers can create distributed
applications for use in heterogeneous computing environments. Read 5, “Managing
network connections,” on page 81, for more details on network communication.

SQL parser and optimizer

solidDB uses SQL syntax based on the ANSI X3H2 and IEC/ISO 9075 SQL
standards. SQL-89 Level 2 standard is fully supported as well as SQL-92 Entry
Level. Many features of full SQL-92 and SQL-99 standards are also supported.
solidDB contains a cost-based optimizer, which ensures that even complex queries
can be run efficiently. The optimizer automatically maintains information about
table sizes, the number of rows in tables, the available indices, and the statistical
distribution of the index values.

solidDB
The solidDB processes the data requests submitted via solidDB SQL. The solidDB
server shown in Figure 2 on page 4 stores data and retrieves it from the database.

1 solidDB fundamentals 3
 Application

ODBC 1 SA API JDBC

Network communication layer

Network communication layer

SQL parser and optimizer

Query executor

solidDB

solidDB
database

1. SA API is solidDB's own API for use with the shared memory access (SMA) or linked library access (LLA)
libraries. For details, see IBM solidDB Shared Memory Access and Linked Library Access User Guide.

Figure 2. solidDB components

System tools and utilities

solidDB includes a set of tools for data management and administration.

Console tools: solidDB SQL Editor (solsql) and solidDB Remote

Control (solcon)
v solidDB SQL Editor (solsql) is a console tool used to issue SQL statements and
solidDB ADMIN COMMANDs at the command prompt, or by executing a script
file that contains the SQL statements.
v solidDB Remote Control (solcon) is a console tool for administration; users with
administrator rights can issue ADMIN COMMANDs at the command prompt or
by executing a script file that contains the commands. With solcon, the ADMIN
COMMANDs can be issued as part of the solcon startup command line.

Tools for exporting and loading data

solidDB provides the following tools for exporting and loading data:
v solidDB Speed Loader (solloado or solload) loads data from external files into a
solidDB database.

4 IBM solidDB: Administrator Guide

 v solidDB Export (solexp) exports data from a solidDB database to files. It also
creates control files used by solidDB Speed Loader (solloado or solload) to
perform data load operations.
v solidDB Data Dictionary (soldd) exports the data dictionary of a database. It
produces an SQL script that contains data definition statements that describe the
structure of the database.

Automated and manual administration

solidDB is designed for continuous, unattended operation, and ease of deployment.
It requires minimal maintenance. Administrative operations, including backups,
can be performed programmatically using SQL extensions which can run
automatically or at an administrator's request.

When necessary, you can administer solidDB also manually.

solidDB provides the following tools and methods for performing manual
administration:
v ADMIN COMMANDs
To perform administration tasks, you can issue solidDB SQL's own ADMIN
COMMANDs in solidDB SQL Editor (solsql). For a comprehensive list of
commands, refer to Appendix F, “solidDB ADMIN COMMAND syntax,” on
page 309.
v solidDB Server Control API (SSC API)
If you are using solidDB with linked library access, the solidDB Server Control
API (SSC API) gives a user application programmatic control over task
execution. The SSC API functions are available for assigning priorities for such
tasks as database backup, database checkpoint, and merge of the Bonsai Tree.
The priority assignment determines in what order a task is run once it is
executed. For details, see IBM solidDB Shared Memory Access and Linked Library
Access User Guide.
v solidDB Remote Control (solcon)
solidDB Remote Control (solcon) lets you enter administrative commands
without using the ADMIN COMMAND syntax. See “solidDB Remote Control
(solcon)” on page 93 for details.

solidDB architecture
This section provides conceptual information that can give you an understanding
in configuring solidDB to meet the needs of your own applications and platforms.
It looks at the following:
v Data Storage
– Main Storage Tree
– Bonsai Tree Multiversioning and Concurrency Control
v Dynamic SQL Optimization
v Network Services
v Multithread processing

Data storage for disk-based tables

The main data structure used to store disk-based tables (D-tables) is a B-tree
variation. The server uses two of these structures; the "main storage tree" holds
permanent data, and a differential index tree called "Bonsai Tree" stores "new" data
temporarily until it is ready to be moved to the main storage tree.

1 solidDB fundamentals 5
 The internal part of the server taking care of storing D-tables is called the
disk-based engine (DBE).

Main storage tree

The main storage tree contains all the data in the server, including tables and
indexes. Internally, the server stores ALL data in "indexes" — there are no separate
tables. Each index contains either complete primary keys (i.e. all the data in a row)
or secondary keys (what SQL refers to as "indexes" — just the column values that
are part of the SQL index). There is no separate storage method for data rows,
except for Binary Large Objects (BLOB) and other long column values.

All the indexes are stored in a single tree, which is the main storage tree. Within
that tree, indexes are separated from each other by a system-defined index
identification inserted in front of every key value. This mechanism divides the
index tree into several logical index subtrees, where the key values of one index
are clustered close to each other. For details on data clustering and primary key
indexes, read the discussion of Primary Key Indexes in IBM solidDB SQL Guide.

solidDB Bonsai Tree multiversioning and concurrency control

The Bonsai Tree is a small active "index" (data storage tree) that efficiently stores
new data (deletes, inserts, updates) in central memory, while maintaining
multiversion information. Multiple versions of a row (old and new) can coexist in
the Bonsai Tree. Both the old and new data are used for concurrency control and
for ensuring consistent read levels for all transactions without any locking
overhead. With the Bonsai Tree, the effort needed for concurrency control is
significantly reduced.

When a transaction is started, it is given a sequential Transaction Start Number

(TSN). The TSN is used as the "read level" of the transaction; all key values
inserted later into the database from other connections are not visible to searches
within the current transaction. This offers consistent index read levels that appear
as if the read operation was performed atomically at the time the transaction was
started. This guarantees read operations are presented with a consistent view of
the data without the need for locks, which have higher overhead.

Old versions of rows (and the newer version(s) of those same rows) are kept in the
Bonsai Tree for as long as there are transactions that need to see those old versions.
After the completion of all transactions that reference the old versions, the "old"
versions of the data are discarded from the Bonsai tree, and new committed data is
moved from the Bonsai Tree to the main storage tree. The presorted key values are
merged as a background operation concurrently with normal database operations.
This offers significant I/O optimization and load balancing. During the merge, the
deleted key values are physically removed.

Index compression
Two methods are used to store key values in the Bonsai Tree and the storage tree.
First, only the information that differentiates the key value from the previous key
value is saved. The key values are said to be prefix-compressed. Second, in the
higher levels of the index tree, the key value borders are truncated from the end;
that is, they are suffix-compressed.

Data storage for memory-based tables

solidDB allows for creation of memory-resident tables, so-called M-tables. The
advantage of M-tables is their performance. M-tables have the same properties in
terms of durability and recoverability as traditional disk-based tables (D-tables).
The only difference is the location of the primary storage. M-tables are primarily

6 IBM solidDB: Administrator Guide

 stored in main memory, meaning that the bigger the in-memory database is, the
more room it occupies in main memory. In addition to the actual data, the indexes
for M-tables are built in main memory as well. solidDB uses a
main-memory-optimized index technology called "tries" to implement the indexes.
To evaluate the amount of memory needed to store the M-tables and their indexes,
see the IBM solidDB In-Memory Database User Guide.

The internal part of the server taking care of storing M-tables is called
Main-Memory Engine (MME)

solidDB SQL optimizer

The solidDB SQL optimizer is a cost-based optimizer that ensures that SQL
statements are executed efficiently. It uses the same techniques as a rules-based
optimizer, relying on a preprogrammed set of rules to determine the shortest path
to the results. For example, the optimizer considers whether or not an index exists,
if the index is unique, and if the index is over single or composite table columns.
However, unlike a rule-based optimizer, the cost-based optimizer can adapt to the
actual contents of the database — for example, the number of rows and the value
distribution of individual columns.

solidDB maintains the statistical information about the actual data automatically,
ensuring optimal performance. Even when the amount and content of data
changes, the optimizer can still determine the most effective route to the data.

Query processing
Query processing is performed in small steps to ensure that one time-consuming
operation does not block another application's request. A query is processed in a
sequence containing the following phases:
v Syntax analysis
v Creating the execution graph
v Processing the execution graph

Syntax analysis
An SQL query is analyzed and the server produces either a parse tree for the
syntax or a syntax error. When a statement is parsed, the information necessary for
its execution is loaded into the statement cache. A statement can be executed
repeatedly without re-optimization, as long as its execution information remains in
the statement cache.

Creating the execution graph

The execution graph, with the following features, is created from the query parse
tree.
v Complex statements are written to a uniform and more simple form.
v If better performance will be realized, OR criteria are converted to UNION
clauses. (For more details about OR vs. UNION, see the discussion of
CONVERTORSTOUNIONS in the IBM solidDB SQL Guide.
v Intelligent join constraint transfer is performed to produce intermediate join
results that reduce the join process execution time.

For details on each operation or unit in the execution plan, read the discussion of
the EXPLAIN PLAN FOR statement in the IBM solidDB SQL Guide.

1 solidDB fundamentals 7
 Processing the execution graph
Processing of the execution graph is performed in three consecutive phases:
v Type-evaluation phase
The column data types of the result set are derived from the underlying table
and view definitions
v Estimate-evaluation phase
The cost of retrieving first rows and also entire result sets is evaluated, and an
appropriate search strategy is dynamically selected based on the parameter
values that are bound to the statement.
The SQL Optimizer bases cost estimates on automatically maintained
information about key value distribution, table sizes, and other dynamic
statistical data. No manual updates to the index histograms or any other
estimation information is required.
v Row-retrieval phase
The result rows of the query are retrieved and returned to the client application.

Optimizer hints
Optimizer hints (which are an extension of SQL) are directives specified through
embedded pseudo comments within query statements. The optimizer detects these
directives or hints and bases its query execution plan accordingly. Optimizer hints
allow applications to be optimized under various conditions to the data, query
type, and the database. They not only provide solutions to performance problems
occasionally encountered with queries, but shift control of response times from the
system to the user.

For more details on optimizer hints, read IBM solidDB SQL Guide.

solidDB Network Services

solidDB Network Services are based on the remote procedure call (RPC) paradigm,
which makes the communication interface simple to use. When a client sends a
request to the server, it resembles calling a local function. The Network Services
invisibly route the request and its parameters to the server, where the actual
service function is called by the RPC Server. When the service function completes,
the return parameters are sent back to the calling application.

In a distributed system, several applications may request a server to perform

multiple operations concurrently. For maximum parallelism, solidDB Network
Services use the operating system threads when available to offer a seamless
multiuser support. On single-threaded operating systems, the Network Services
extensively use asynchronous operations for the best possible performance.

Communication session layer

solidDB communication protocol DLLs (or static libraries) offer a standard internal
interface to each protocol. The lowest part of the communication session layer
works as a wrapper that takes care of choosing the correct protocol DLL or library
that relates with the given address information. After this point, the actual protocol
information of the session is hidden.

solidDB can listen to many protocols simultaneously.

Multithread processing
solidDB's multithread architecture provides an efficient way of sharing the
processor within an application. A thread is a dispatchable piece of code that

8 IBM solidDB: Administrator Guide

merely owns a stack, registers (while the thread is executing), and its priority. It
shares everything else with all other active threads in a process. Creating a thread
requires much less system overhead than creating a process, which consists of
code, data, and other resources such as open files and open queues.

Threads are loaded into memory as part of the calling program; no disk access is
therefore necessary when a thread is invoked. Threads can communicate using
global variables, events, and semaphores.

If the operating system supports symmetric multithreading between different

processors, solidDB automatically takes advantage of the multiple processors.

Types of threads
The solidDB threading system consists of general purpose threads and dedicated
threads.

General purpose threads

General purpose threads execute tasks from the server's tasking system. They
execute such tasks as serving user requests, making backups, executing timed
commands, merging indexes, and making checkpoints (storing consistent data to
disk).

General purpose threads take a task from the tasking system, execute the task step
to completion and switch to another task from the tasking system. The tasking
system works in a round-robin fashion, distributing the client operations evenly
between different threads.

The number of general purpose threads can be set in the solid.ini configuration
file.

Dedicated threads

Dedicated threads are dedicated to a specific operation. The following dedicated

threads may exist in the server:
v I/O manager thread
This thread is used for intelligent disk I/O optimization and load balancing. All
I/O requests go through the I/O manager, which determines whether to pass
each I/O request to the cache or to schedule it among other I/O requests. I/O
requests are ordered by their logical file address. The ordering optimizes the file
I/O since the file addresses accessed on the disk are in close range, reducing the
disk read head movement.
v Communication read threads
Applications always connect to a listener session that is running in the selector
thread. After the connection is established, a dedicated read thread can be
created for each client.
v One communication select thread per protocol (known as the selector thread)
There is usually one communication selector thread per protocol. Each running
selector thread writes incoming requests into a common message queue.
v Communication server thread (also known as the RPC server main thread)
This thread reads requests from the common message queue and serves
applications by calling the requested service functions.

1 solidDB fundamentals 9
10 IBM solidDB: Administrator Guide
2 Administering solidDB
This section describes how to maintain your solidDB installation. The
administration tasks covered in this section are:
v Performing basic solidDB operations, such as starting and stopping the server
v Backing up the server
v Encrypting a database

Important: If you are using solidDB with shared memory access (SMA) or linked
library access (LLA), there are some differences in administration from standard
solidDB. Wherever necessary, this chapter refers you to the IBM solidDB Shared
Memory Access and Linked Library Access User Guide for SMA or LLA specific
information.

User roles for database administration

solidDB has the following roles for administration and maintenance:
v SYS_ADMIN_ROLE
This is the Database Administrator (DBA) role and has privileges to all tables,
indexes, and users, as well as the right to use solidDB Remote Control (solcon).
This is also the role of the creator of the database.
v SYS_CONSOLE_ROLE
This role has the right to use solidDB Remote Control, but has no other
administration privileges.
v SYS_SYNC_ADMIN_ROLE
This is an administration role for performing administrative operations related to
synchronization, such as the following:
– Dropping or re-executing stopped synchronization messages
– Dropping replica databases from master databases
– Creating bookmarks
All SYS_SYNC_ADMIN_ROLE are granted with all synchronization roles
automatically. This role automatically includes the SYS_SYNC_REGISTER_ROLE.
v SYS_SYNC_REGISTER_ROLE
This is a role only for registering or unregistering a replica database to the
master.

You define these roles using the GRANT ROLE statement. For details, see Managing
user privileges and roles in IBM solidDB SQL Guide.

Starting and stopping solidDB

Starting solidDB
You can start solidDB by issuing the command solid [options] at the command
prompt, or in Windows environments, using the Start > Programs > IBM solidDB
menu path.

The syntax for starting solidDB is

solid [options]

11
 For options, see Appendix C, “solidDB command line options,” on page 221.

To start solidDB, a valid license file must be located in your working directory or
in the location specified with a SOLIDDIR environment variable.
Table 3. Starting the server

Operating system To start the server...

Linux and UNIX In the working directory, enter the command solid [options] at the command prompt.

When you start the server for the first time, use the command line option -f to force the
server to run in the foreground:

solid -f
Windows v Click the icon labeled Start IBM solidDB server through the Start > Programs > IBM
solidDB menu path.
v In the working directory, enter the command solid [options] at the command prompt.
v To start the server to run in the background, enter the command start solid.

When solidDB is started, it checks if a database already exists. The server first
looks for a solid.ini configuration file and reads the value of FileSpec parameter.
Then the server checks if there is a database file with the names and paths
specified in the FileSpec parameter. If a database file is found, solidDB will
automatically open that database. If no database is found, the server creates a new
database.

Note:

This section applies to standard solidDB only. If you are using solidDB with shared
memory access (SMA) or linked library access (LLA), see the IBM solidDB Shared
Memory Access and Linked Library Access User Guide for instructions on how to start
solidDB SMA or LLA server.
Related reference:
Appendix C, “solidDB command line options,” on page 221
Related information:
“FileSpec_[1...n] parameter” on page 53

Login
solidDB database requires users to login to the database with their username and
password.

If you try to login four times with an incorrect username and/or password, the
system will block your IP address for a maximum of 60 seconds. This feature
cannot be configured or switched off.

Modifying Windows shortcuts for solidDB server and solidDB

SQL Editor (solsql)
By default the Start IBM solidDB server and solsql SQL Editor icons in the Start
> Programs > IBM solidDB menu path start programs in the eval_kit\standalone
directory. To change the default settings, modify the Properties of the shortcuts.

12 IBM solidDB: Administrator Guide

 Modifying Start IBM solidDB server shortcut

By modifying the Properties of the Start IBM solidDB server shortcut you can
specify the working directory, login data and system catalog name, and additional
command line options used when starting solidDB.
1. Right-click on the Start IBM solidDB server icon.
2. Select Properties and then the Shortcut tab.
3. To change the login data and catalog name (or other startup options), modify
the command line options given in the Target field:
v -C — system catalog name
v -P — password
v -U — username
For example:
"C:\Program Files\IBM\solidDB\solidDB6.5\bin\solid.exe" -C mycatalog -P
mypassword -U myname
See section Appendix C, “solidDB command line options,” on page 221 for a
list of available solidDB startup options.
4. To change the working directory, modify the directory path in the Start in field.
For example:
"C:\Program Files\IBM\solidDB\solidDB6.5\eval_kit\mytest\"

Modifying solsql SQL Editor shortcut

By modifying the Properties of the solsql SQL Editor shortcut you can specify the
connection information and the login data for the solidDB server to which solidDB
SQL Editor (solsql) connects to.
1. Right-click on the solsql SQL Editor icon.
2. Select Properties and then the Shortcut tab.
3. To change the connection information and login data, modify the server name,
username, and password given in the Target field.
For example:
"C:\Program Files\IBM\solidDB\solidDB6.5\bin\solsql.exe" "tcp 2315"
myname mypassword
You can also specify startup options in the Target field. See section “Starting
solidDB SQL Editor” on page 96 for a list of available solsql startup options.

Closing a database
You can close the database, which means no new connections to the database are
allowed. To do this, issue the following command in solidDB SQL Editor (solsql):

ADMIN COMMAND 'close';

You use the close command when you want to prevent users from connecting to
the database. For example, when you are shutting down solidDB, you must
prevent new users from connecting to the database. As part of the shut down
procedure you use the close command. Read “Shutting down solidDB” on page 14
for procedures to shut down a database.

2 Administering solidDB 13
 After closing the database, connections from solidDB Remote Control will only be
accepted. Closing the database does not affect existing user connections. When the
database is closed no new connections are accepted (clients will get solidDB Error
Message 14506).

To revert the effect of the close command, use:

ADMIN COMMAND 'open';

Shutting down solidDB

Note:

This section applies to standard solidDB only. If you are using solidDB with shared
memory access (SMA) or linked library access (LLA), see the IBM solidDB Shared
Memory Access and Linked Library Access User Guide for instructions on how to stop
the solidDB SMA or LLA server.

You can shut down the solidDB in the following ways:

v Programmatically from an application such as solidDB Remote Control (solcon)
or solidDB SQL Editor (solsql). To do this, perform the steps below.
1. To prevent new connections to solidDB, close the database(s) by entering the
following command:
close
Note that you can revert the effect by entering the command:
open
2. Exit all users of solidDB (except the current connection) by entering the
following command:
throwout all
Note that this command does not wait for open transactions to finish; it
aborts and rolls back all open transactions.
3. Stop solidDB by entering the following command:
shutdown

Note: When using solidDB SQL Editor for the steps 1-3 above, enter the full
SQL Syntax,
ADMIN COMMAND ’<command_name>’

For example:
ADMIN COMMAND ’close’
v Using command ADMIN COMMAND 'shutdown force" that includes all of the above.
v Right-clicking the server icon and selecting Close from the menu appearing in
the Microsoft Windows environment.
v Remotely, using the command 'net stop' through the Windows system services.
Note that you may also start up solidDB remotely, using the 'net start'
command.

Each of these shutdown mechanisms will start the same routine, which writes all
buffered data to the database file, frees cache memory, and finally terminates the
server program. Shutting down a server may take a while since the server must
write all buffered data from main memory to the disk.

14 IBM solidDB: Administrator Guide

Creating a new database
solidDB databases are created at solidDB server startup.

When solidDB is started, it checks if a database already exists. If a database does

not exist, solidDB will prompt you to create a new database.
v In Windows environments, a dialog window prompts you for the database
administrator's username, password, and a name for the default (system)
catalog.
v In Linux and UNIX environments, the following message appears:
Database does not exist. Do you want to create a new database (y/n)?
By answering 'yes', solidDB prompts you for the database administrator's
username, password, and a name for the default (system) catalog.

After accepting the database administrator's username and password, solidDB

creates the new database.

By default the database is created as one file (solid.db) in the solidDB working
directory.

An empty database that contains only the system tables and views uses
approximately four megabytes of disk space. The time it takes to create the
database depends on the hardware platform you are using. If you have a very
small database (less than four megabytes) and want to keep the disk space less
than four megabytes, set the value of the IndexFile.ExtendIncrement parameter in
the solid.ini configuration file to less than 500 (default). This parameter and other
parameters are discussed in Appendix A, “Server-side configuration parameters,”
on page 165.

After the database has been created, solidDB starts listening to the network for
client connection requests. In Windows environments, a solidDB icon appears, but
in most environments solidDB runs invisibly in the background as a daemon
process.

Usernames, passwords, and system catalog names

The database system administrator account is created when the solidDB database is
created; the creator of the database has the SYS_ADMIN_ROLE user role. The
system catalog name is also created when the database is created and it cannot be
changed later.

Important:
v You must remember your username and password to be able to connect to
solidDB. There are no default usernames; the administrator username you enter
when creating the database is the only username available for connecting to the
new database for the first time.
v Lowercase characters in usernames, passwords, and system catalog names are
converted to uppercase.

Username
v Minimum length: 2 characters.
v Maximum length: 80 characters

2 Administering solidDB 15
 v The username must begin with a letter or an underscore. Use lower case letters
from a to z, upper case letters from A to Z, the underscore character "_", and
numbers from 0 to 9.

The database system administrator's username cannot be changed with the ALTER
USER command. See Changing administrator's username and password in the IBM
solidDB SQL Guide.

Password
v Minimum length: 3 characters.
v Maximum length: 80 characters
v The password can begin with any letter, underscore, or number. Use lower case
letters from a to z, upper case letters from A to Z, the underscore character "_",
and numbers from 0 to 9.
v You cannot use the double quotation mark (") character in the password. The
use of apostrophe ('), semicolon (;), or space (' ') is strongly discouraged, because
some tools may not accept these characters in the password.
v If you plan to use solidDB Remote Control (solcon), do not create passwords
with non-ASCII characters, because solcon does not perform UTF-8 translation
for any input.
v You can also enter the password from a file. For more information, see “Entering
password from a file” on page 119.

System catalog
v Minimum length: 1 character.
v Maximum length: 39 characters
v The system catalog name must not contain spaces.

The solidDB syntax for database object hierarchy is the following:

catalog_name.schema_name.database_object

The default schema name is the username.

When creating objects in solidDB, if you do not specify the catalog and schema
name, the server uses the system catalog and the username of the object creator to
determine which object to use.

For details on solidDB catalogs and schemas, see section Managing database objects
in IBM solidDB SQL Guide.

Unicode and partial Unicode database modes

Starting from version 6.5, the solidDB databases can be created in two modes:
Unicode mode or partial Unicode mode (default). This database mode is based on
the encoding of character data types (CHAR, VARCHAR and so on) in the solidDB
server. Wide character data types (WCHAR, WVARCHAR and so on) are Unicode
encoded in both modes.
v Unicode mode
In the Unicode mode, the internal representation for character data types is
UTF-8.
The internal representation for wide character data types is UTF-16.
v partial Unicode mode

16 IBM solidDB: Administrator Guide

 In the partial Unicode mode, the internal representation for character data types
uses no particular encoding; instead, the data is stored in byte strings with the
assumption that user applications are aware of this and handle the conversion as
necessary.
The internal representation for wide character data types is UTF-16.
The databases created with solidDB version 6.3 or earlier are of the partial
Unicode type.

Important: The default database mode in 6.5 is partial Unicode.

Creating Unicode databases

The solidDB database mode is controlled with the parameter

General.InternalCharEncoding.
v Unicode mode: General.InternalCharEncoding=UTF8
When the InternalCharEncoding is set to UTF8, the internal representation for
character data types is UTF-8. Both character data types and wide character data
types are converted between the solidDB server and the application.
v partial Unicode mode: General.InternalCharEncoding=Raw
When the InternalCharEncoding is set to Raw, the internal representation for
character data types uses no particular encoding; instead, the data is stored in
byte strings with the assumption that user applications are aware of this and
handled the conversion as necessary. Wide character data types are converted
between the solidDB server and the application.
The databases created with solidDB version 6.3 or earlier are of the partial
Unicode type.

Important: The database mode must be defined when the database is created and
it cannot be changed later.

If the database already exists in either mode and the database mode contradicts the
value of the parameter, the server startup fails with the following error message in
the solerr.out:
Parameter General.InternalCharEncoding contradicts the existing database mode

Setting up database environment

By default the solidDB database files, log, message, and trace files are created in
the solidDB working directory. For production environments, you may want to set
up an environment where, for example, database files, backup files, and log files
are located on different disks.

Default working directory settings

A working directory is the directory that contains the files related to running a
particular solidDB instance.

The following table shows the most common solidDB files, their factory value
locations, and how to modify the locations.

2 Administering solidDB 17
 Table 4. solidDB default files
Factory value
File location How to modify
license file (solid.lic, working Define path in SOLIDDIR environmental
soliduc.lic, or directory variable
solideval.lic)
solid.ini configuration file working Define path in SOLIDDIR environmental
directory variable
database files (solid.db) working Define with IndexFile.FileSpec parameter
directory
transaction log files working Define location with Logging.LogDir
(sol#####.log) directory parameter

or

Define location and file name with

Logging.FileNameTemplate parameter
Note: If you specify a directory for the log
files, the directory must exist before you start
solidDB: solidDB cannot create directories.
message file (solmsg.out) working Location and name cannot be changed; the
directory solmsg.out file is always output in the
working directory.
error file (solerror.out) working Location and name cannot be changed; the
directory solerror.out file is always output in the
working directory.
trace file (soltrace.out) working Define with Com.TraceFile parameter
directory
backup files <working Define with General.BackupDirectory
directory>/ parameter
backup Note: The directory for the backup files must
exist before you make a backupsolidDB:
solidDB cannot create directories.

Recommendations for production environments

v If you do not wish to run the installer on your production environment node,
install solidDB on a separate node and copy the executables, libraries, and
drivers manually to your production node, as applicable for your setup.
v To prevent loss of data in case of a disk failure, store the database files and
transaction log files on different physical drives. This will also provide best
performance, especially during database checkpoints when both database files
and transaction log files are written at the same time.
v Use local disks (instead of network disks) for storing the database files and log
files.
This is especially important with a solidDB HotStandby setup. The HotStandby
configurations are targeted for environments with shared nothing architecture,
and this is best achieved by having the primary and secondary databases in
separate nodes, each using local disks. Network disks have a risk of being a
logical/physical single point of failure in the system.

18 IBM solidDB: Administrator Guide

 Related concepts:
“Viewing error messages and log files” on page 63
By default, solidDB outputs errors and messages in the solmsg.out and
solerror.out log files in the solidDB working directory. To view the descriptions
of single or all error messages, use ADMIN COMMAND ’errorcode’.
Related information:
“Configuration files and parameter settings” on page 44
There are two different solid.ini configuration files, one for the server and one
for the ODBC client. Neither configuration file is obligatory. If there is no
configuration file, the factory values are used.
“Managing database files and caching (IndexFile section)” on page 53
“Performing backup and recovery” on page 27
“Running several servers on one computer” on page 24

solidDB configuration file (solid.ini)

When you start solidDB, it reads configuration parameters from the solid.ini
configuration file.

The solid.ini file specifies parameters that help customize and optimize the
solidDB database server. For example, the FileSpec parameter in the solid.ini file
specifies the directory and file names of the data files in which the server stores
the user data. Another parameter specifies the block size for the database. The
block size affects performance and also limits the maximum record size. The
FileSpec and BlockSize parameters are described in the next section.

You can find a complete description of all parameters, details about the proper
format of the solid.ini file, and instructions for specifying solid.ini
configuration parameters in Appendix A, “Server-side configuration parameters,”
on page 165. For more details about setting parameters, read 3, “Configuring
solidDB,” on page 43.

Setting database block size (BlockSize) and location

(FileSpec)
The default block size for the solidDB database file is 16 KB. The block size is
defined in multiples of 2 KB. The minimum block size is 2 KB and the maximum
is 64 KB. The maximum size of the database is 64 TB.

The block size is set with the parameter Indexfile.BlockSize. If you want solidDB
to create a database with a different block size, you have to set the
Indexfile.BlockSize value before creating a new database. If you have an existing
database, remember to move the old database (.db) and log files (.log) to another
directory; the next time you start solidDB, a new database is created.

To modify the constant value for the new database, add the following lines in the
solid.ini file, providing the size in bytes :
[Indexfile]
BlockSize=size_in_bytes

The unit of size is 1 byte (as in all size-related parameters). The unit symbols of K
and M (for KB and MB, respectively) can also be used.

After you save the file and start solidDB, it creates a new database with the new
constant value from the solid.ini file.

2 Administering solidDB 19
 Similarly, you can also modify the Indexfile.FileSpec parameter to define the
following:
v name and location of the database files – the default file name is solid.db and
the default location is the solidDB directory
v maximum size (in bytes) the database file can reach – the default value is
2147483647, which equals 2 G-1 bytes. The maximum file size is (4
G-1)*blocksize. With the default 16 KB block size, this makes 64 TB - 1.

You can also use the Indexfile.FileSpec parameter to divide the database file into
multiple files and onto multiple disks. This may be required if you want to create a
large physical database.

For details on configuring the database file locations and sizes with the
Indexfile.FileSpec parameter, read “Managing database files and caching
(IndexFile section)” on page 53.

Defining database objects

solidDB database objects include catalogs, schemas, tables, views, indexes, stored
procedures, triggers, and sequences. By default, database object names are
qualified with the object owner's user id and a system catalog name that you
specify when creating a database for the first time or converting an old database to
a new format. You can also specify that database objects be qualified by a schema
name. For details, see section Managing database objects in the IBM solidDB SQL
Guide.

solidDB supports a practically unlimited number of tables, rows, and indexes.

Character strings and binary data are stored in variable length format. This feature
saves disk space. It also makes programming easier on developers since the
lengths of strings or binary fields do not have to be fixed. The maximum size for a
single column value is 2G-1 bytes.

By configuring the MaxBlobExpressionSize parameter, you can set the maximum

size of LONG VARCHAR (or CLOB) columns that are used in string functions.
(The size can be specified in kilobytes (K) or megabytes (M).) By default, the size is
1MB (1 megabyte).

For efficiency, solidDB can store BLOB data outside the table. When BLOBs (Binary
Large Objects), such as objects, images, video, graphics, or digitized sound are
larger than a particular size, solidDB automatically detects this and stores the
objects to a special file area that has optimized block sizes for large files. No
administrative action is required. For more information, see section BLOBs and
CLOBs in the Appendix: Data Types in the IBM solidDB SQL Guide.

Connecting to solidDB with solidDB tools (solsql and solcon)

After starting solidDB, you can connect to the server from your workstation using,
for example, the solidDB data management tools, solidDB SQL Editor (solsql) or
solidDB Remote Control (solcon).

Note: This section applies to standard solidDB only. If you are using solidDB with
shared memory access (SMA) or linked library access (LLA), see the IBM solidDB
Shared Memory Access and Linked Library Access User Guide for instructions on how
to connect to a SMA or LLA server.

To connect to solidDB:

20 IBM solidDB: Administrator Guide

 1. View the solmsg.out file in your database directory for valid network names
that you can use to connect to solidDB.
The following messages indicate what names you can use.
Listening of ’tcp hobbes 1313’ started.
2. Start one of the following tools and give the network name of the server as a
command line parameter:
Table 5. Connecting to solidDB

Tool Command

solcon "networkname" [userid [password]]

solidDB Remote Control (solcon)
For example:
solcon "tcp hobbes 1313"

If you did not specify the database administrator's user name and password on the
command line, solcon will prompt you to enter them.
Important: You must have administrator rights (SYS_ADMIN_ROLE) to use solcon.

solsql "networkname" [userid [password]]

solidDB SQL Editor (solsql)
For example:
solsql "tcp hobbes 1313"

If you did not specify the database administrator's user name and password on the
command line, solsql will prompt you to enter them.

After a while you will see a message indicating that a connection to the server has
been established.
Related information:
5, “Managing network connections,” on page 81
6, “Using solidDB data management tools,” on page 93
solidDB data management tools are a set of utilities for performing various
database tasks.

Running solidDB as a Windows service

solidDB can be run as a service in Windows. The first time you want to run
solidDB as a service, you must install the service, that is, allow Windows to run
solidDB as a service. After that, you can start and stop the services with the
Windows Service dialog or command prompt, or remove the services using
solidDB command line options.

Starting solidDB as a service for the first time

The first time you want to run solidDB as a service, you must first install the
service, and then start the service with the Windows Service dialog or command
prompt.

Before you begin

v If you have not created a database before, you must create the database by
starting the server for the first time as a foreground process. If solidDB is
running as a service, it does not interact with a display and cannot create a new
database. You can start the server as a foreground process from the command
line with the command solid or use the Start IBM solidDB icon in the
Programs menu.

2 Administering solidDB 21
 v The solidDB that you intend to run as a service cannot be located on a network
drive.

Procedure
1. Allow (install) Windows to run solidDB as a service.
In the command prompt, issue the following command:
solid -s"install,<service_name>,<fullexepath> -c<working directory>[,autostart] [<option>]"
where
<service_name> is the name of the service
<fullexepath> is the full path for solid.exe
<working directory> is the full path for solidDB working directory (where
your solid.ini configuration file and license file are located)
autostart is an optional parameter that sets the Startup Type of the service to
Automatic, that is, solidDB runs automatically as a service when Windows is
started.

Note:

Regardless of the autostart parameter, the service is not started automatically

at the time of installation. For the first time, the service has to be started
manually in the Windows Services dialog or command prompt.
<option> can be one of the Appendix C, “solidDB command line options,” on
page 221. For example, when using an encrypted database, the encryption
password must be provided with the -S<password> option. Example 1
The following command installs a service named SOLID (with Startup Type
Manual) when solidDB is installed into the directory C:\soliddb and the
working directory is C:\soliddb.
solid -s"install,SOLID,C:\soliddb\bin\solid.exe -cC:\soliddb"

Example 2
The following command installs a service named SOLID (with Startup Type
Automatic) when solidDB is installed into the directory C:\soliddb and the
working directory is C:\soliddb. The next time Windows is started, solidDB
runs automatically as a service.
solid -s"install,SOLID,C:\soliddb\bin\solid.exe -cC:\soliddb,autostart"

Example 3
The following command installs a service named SOLID (with Startup Type
Manual) when solidDB is installed into the directory C:\soliddb and the
working directory is C:\soliddb. The solidDB database is encrypted; the
encryption password is abcd.
solid -s"install,SOLID,C:\soliddb\bin\solid.exe -Sabcd -cC:\soliddb"

Tip:

Alternatively, you can create the service using the Windows command-line
utility sc.exe. In that case, to start solidDB in a services mode, you must
include the solidDB -sstart command-line option in the command. For
example:
sc create SOLID binPath= "c:\soliddb\bin\solid.exe -cC:\soliddb -sstart"

22 IBM solidDB: Administrator Guide

 The -sstart command-line option is required to remove the GUI-based
interactions between the solidDB server and the user. Programs running as a
Windows service cannot use GUI-based interactions.
2. Start the service manually in the Windows Services dialog or command
prompt.
v You can access the Windows Services dialog through Control Panel: Control
Panel > Administrative Tools > Services.
v In the command prompt, issue the following command:
sc start <service_name>
or
net start <service_name>

Results

When running as an Windows service, solidDB will log warning and error
messages to the Windows event log. These messages can be viewed from Windows
by using the Event Viewer, available through Control Panel: Control Panel >
Administrative Tools > Event Viewer. Messages are also logged to the solmsg.out
file.

Starting and stopping solidDB services

The solidDB services can be started and stopped using the Windows Services
dialog or command prompt.

Procedure
v You can access the Services dialog through Control Panel: Control Panel >
Administrative Tools > Services.
v In the command prompt,
– issue the following command to start the service:
sc start <service_name>
or
net start <service_name>
– issue the following command to stop the service:
sc stop <service_name>
or
net stop <service_name>
where <service_name> is the name of the service you want to start or stop.

Removing solidDB services

You can remove the solidDB services using solidDB command line options.

Procedure
1. Stop the service in the Windows Services dialog or command prompt.
v You can access the Windows Services dialog through Control Panel: Control
Panel > Administrative Tools > Services.
v In the command prompt, issue the following command:
sc stop <service_name>
or
net stop <service_name>

2 Administering solidDB 23
 where <service_name> is the name of service you want to stop.
2. Remove the solidDB service.
In the command prompt, issue the following command:
solid -s"remove,<name>"

Example
The following command removes a service named SOLID.
solid -s"remove,SOLID"

Running several servers on one computer

In some cases, you may want to run two or more databases on one computer. For
example, you may need a configuration with a production database and a test
database running on the same computer.

solidDB uses a concept of a working directory. Typically the working directory

contains files related to running a particular solidDB instance:
v license file
v solid.ini configuration file
v database files
v transaction log files
v message and trace files

If you want to run several servers concurrently on one computer, you have to set
up separate working directories for each solidDB instance.

To run several servers on one computer:

v start each solidDB server process in its working directory,
or
v use the command line option -c directory_name to change the working directory.

To avoid network conflicts, use different network listen names for each server in
the solid.ini configuration files.

Example:

To start two solidDB server instances:

1. Create two working directories. For example:
v C:\solid1
v C:\solid2
2. Copy the license file into both directories.
3. In each working directory create a solid.ini configuration file, specifying
different listen names.
For example:
solid1:
[Com]
Listen=tcpip 2315
solid2:
[Com]
Listen=tcpip 2316
4. In the solidDB installation root directory:
24 IBM solidDB: Administrator Guide
 a. Start the first solidDB server instance with the following command:
bin\solid -c C:\solid1
b. Start the second solidDB server instance with the following command:
bin\solid -c C:\solid2

Using solidDB with SELinux

SELinux (Security Enhanced Linux) is a security enhancement feature in Linux that
provides administrators additional control over which users and applications can
access which system resources. solidDB supports SELinux on Red Hat Enterprise
Linux (RHEL) operating systems.

Before you begin

The instructions in this section assume that you are familiar with SELinux for
RHEL 6. For information on SELinux on RHEL 6, see the Red Hat Enterprise Linux
6 Security-Enhanced Linux User Guide.

You also need to have the following SELinux policy tools installed on your system:
v selinux-policy-version (for example, selinux-policy-3.7.19-54.el6.noarch)
v policycoreutils-python-version (for example, policycoreutils-python-2.0.83-
19.1.el6.x86_64)

About this task

With default installation, all solidDB processes run in an unconfined domain, that
is, unconfined users can run solidDB processes without any further action.

The following procedure uses the sepolgen utility to create and install SELinux
policy modules for solidDB so that also confined system level users (system_u) can
start solidDB processes.

Tip: You need to run the sepolgen utility separately for each solidDB process.

Procedure
1. In the selinux/devel directory, create the policy modules by issuing the
following command:
sepolgen <solidDB_installation_directory>/bin/<solidDB_executable>
The sepolgen utility creates the policy modules; the file names use the
<solidDB_executable>.xx naming pattern, for example,
<solidDB_executable>.te.
2. Install and apply the security policy permanently by issuing the following
command:
sh <solidDB_executable>.sh

Results

The sepolgen utility creates the source and binary files for the policy module. If
you want to enforce a more strict policy, for example, for specific users, you need
to modify, recompile, and reinstall the policy modules - for details, see the Red Hat
Enterprise Linux 6 Security-Enhanced Linux User Guide.

2 Administering solidDB 25
 Examples

Creating and applying the system's default SELinux policy on the solidDB server
(solid) executable.
# cd /usr/share/selinux/devel
# secpolgen <solidDB_installation_directory>/bin/solid
# sh solid.sh

Creating and applying the system's default SELinux policy on the SMA server
(solidsma) executable.
# cd /usr/share/selinux/devel
# secpolgen <solidDB_installation_directory>/bin/solidsma
# sh solidsma.sh

Creating and applying the system's default SELinux policy on the solidDB High
Availability Controller (solidhac) executable.
# cd /usr/share/selinux/devel
# secpolgen <solidDB_installation_directory>/bin/solidhac
# sh solidhac.sh

Using solidDB audit trail (AuditTrailEnabled)

The solidDB audit trail feature enables tracking of user and schema changes
persistently within the solidDB database. The audit trail is controlled with the
Sql.AuditTrailEnabled parameter. When audit trail is enabled, information about
the database activities are written into a SYS_AUDIT_TRAIL system table. Users
with administrator rights can query the SYS_AUDIT_TRAIL system table with
normal SQL syntax.

When audit trail is enabled, the system records the following database activities:
v Changes in user and login information
v Changes in schemas and catalogs
v Status of audit trail (enabled/disabled/deletes)

The status of audit trail is written at each server startup. This status message can
be used to check when the audit trail data has been collected, and when the server
has been started up with the audit trail disabled. If auditing is disabled later on, at
the next startup, the system will write a status message to indicate that audit trail
is disabled.

User access

Only administrators (SYS_ADMIN_ROLE) can query the SYS_AUDIT_TRAIL

system table. Administrators are also allowed to DELETE data from the table; the
DELETE statements are audited unless the DELETE affected zero rows.

Audit trail and High Availability

In a High Availability setup, only the primary server can write the audit trail.
However, audit trail must be enabled in both servers. This is because each server
records database activities according to the configuration settings in its own
solid.ini file. In case of a switchover (old primary had
SQL.AuditTrailEnabled=yes), the new primary will continue recording the changes
only if the Sql.AuditTrailEnabled parameter for it was set to 'yes' at the last
startup. The state of the new primary is stored as a status message in the system
table (AUDIT TRAIL ENABLED (HSB) or AUDIT TRAIL DISABLED (HSB).

26 IBM solidDB: Administrator Guide

 Enabling and disabling audit trail
The audit trail is controlled with the Sql.AuditTrailEnabled parameter. The access
mode of the Sql.AuditTrailEnabled parameter is RO (read-only).

Procedure
v Enabling audit trail
1. Set the Sql.AuditTrailEnabled parameter to yes in the solid.ini
configuration file.
[SQL]
AuditTrailEnabled=yes
2. Restart solidDB.
ResultAt the startup, the system writes a status message to the
SYS_AUDIT_TRAIL system table to indicate that audit trail is enabled. Changes
in database activities are recorded in the SYS_AUDIT_TRAIL system table until
audit trail is disabled.
v Disabling audit trail
1. Set the Sql.AuditTrailEnabled parameter to no in the solid.ini
configuration file.
2. Restart solidDB.
ResultAt the startup, the system writes a STATUS message to the
SYS_AUDIT_TRAIL system table to indicate that audit trail is disabled. Changes
in database activities are not recorded in the SYS_AUDIT_TRAIL system table
until audit trail is enabled again.

Querying audit trail data in the SYS_AUDIT_TRAIL system

table
Users with administrator rights can query the SYS_AUDIT_TRAIL table using
normal SQL syntax.

Procedure
v Example: Viewing the SYS_AUDIT_TRAIL system table
SELECT CREATIME, LOGIN_USER, SQLSTR FROM sys_audit_trail

CREATIME LOGIN_USER SQLSTR

-------- ---------- ------
2009-03-05 13:21:31 _SYSTEM AUDIT TRAIL ENABLED
2009-03-05 13:21:42 DBA CREATE USER DBUSER IDENTIFIED BY
2009-03-05 13:23:13 DBA CREATE SCHEMA DBA2
2009-03-05 13:23:23 DBA DROP SCHEMA DBA2
2009-03-05 13:23:24 DBA CREATE USER DBA2 IDENTIFIED BY
2009-03-05 13:32:22 DBUSER CREATE TABLE TEST (ID INTEGER)
2009-03-05 13:49:37 DBA CREATE CATALOG DBUSER
2009-03-05 13:49:59 DBUSER CREATE TABLE TEST_TAB (ID INTEGER PRIMARY KEY NOT NULL)

v Example: Querying CREATE USER operations

SELECT CREATIME, LOGIN_USER, SQLSTR FROM sys_audit_trail WHERE type=’CREATE USER’"

CREATIME LOGIN_USER SQLSTR

-------- ---------- ------
2009-03-05 13:21:42 DBA CREATE USER DBUSER IDENTIFIED BY
2009-03-05 13:23:24 DBA CREATE USER DBA2 IDENTIFIED BY

Performing backup and recovery

Backups are made to secure the information stored in your database files. If your
database files become corrupted or they are lost due to a system failure, you can
restore the database from the backup files. To ensure that data is secure in the
event of a system failure, you should regularly back up master and possibly also
the replica databases.

2 Administering solidDB 27
 solidDB main memory engine supports both local backups and backups made over
the network, that is, network backups.
v Local backup produces a copy — one database file — of the current logical
database, which possibly consists of multiple files.
v Network backup does the same local backup except that the backup database is
sent over the network to Network Backup Server.

The sections below describe how to back up your solidDB in-memory databases
and recover from system failure. Furthermore, means of configuring,
administering, and monitoring backup operations are presented.

For guidelines for backing up and restoring the master and replica databases, see
the IBM solidDB Advanced Replication User Guide.

Making local backups

You can initiate a local backup by entering the following command in solsql:
ADMIN COMMAND ’backup [-s] [dir backup dir]’

Available options for the backup command:

Table 6. Options for the backup command

Option Description

-s Synchronized execution. The call returns either when the backup

is completed or due to an error.

dir backup dir is a path expression determining the backup directory

in the local file system.

If the backup directory is omitted, it must be specified in the

solid.ini configuration file.

If the specified backup directory does not exist, solidDB

database error 10030 is given. For more information about this
error, see Appendix E, “Error codes,” on page 227

The backup directory can be set beforehand in the configuration file by setting the
parameter BackupDirectory in the [General] section of the configuration file. For
the full list of available configuration parameters see Appendix A, “Server-side
configuration parameters,” on page 165.

CAUTION:
If two databases are copied to the same directory, the earlier will be overwritten
by the latter. The backup dir must be different at least for each database.
Moreover, although database files may be stored to different directories and
partitions at the source server they all are copied to the same backup directory.
Therefore equally named database files will conflict in the backup directory. As
a consequence, only the last backed-up file among the equally named ones has
backup copy in the backup directory.

Making backups over network

A network backup command may be sent to any host running a solidDB server. A
server playing the role of the backup receiver is called a NetBackup Server.

28 IBM solidDB: Administrator Guide

Making netbackup
Start a network backup (netbackup) with the following command:
ADMIN COMMAND ’netbackup [options] [DELETE_LOGS | KEEP_LOGS]
[connect connect str] [dir backup dir]’

where
v options can be:
Table 7. Options for the netbackup command

Option Description

-s Synchronized execution.

The call returns either when the netbackup is completed or if there is an

error.
-I Executes a full database integrity check
-i Executes a database index integrity check

v DELETE_LOGS | KEEP_LOGS defines whether backup logs are deleted or kept in the
source server. Default is DELETE_LOGS.

Note:
– DELETE_LOGS is referred to as Full backup
– KEEP_LOGS is referred to as Copy backup. Using KEEP_LOGS corresponds to
setting the General.NetbackupDeleteLog parameter to "no".
v connect connect str specifies the connection to the NetBackup Server. If the
connect str is omitted, it must be specified in the solid.ini configuration file. For
the full connect string syntax see “Format of the connect string” on page 58.
v dir backup dir defines the backup directory in the NetBackup Server. The path
can be either absolute or relative to the netbackup root directory.

Important: If two databases are copied to the same directory, the earlier will be
overwritten by the latter. The backup dir should never point, for instance, to the
root directory of the Netbackup Server.

Note:
v The command ADMIN COMMAND ’netbackup’ is not supported within the Srv.At
configuration parameter.
v The ADMIN COMMAND ’status netbackup’ is synonymous to ADMIN COMMAND
’status backup’; it reports on both local and network backups.
v The ADMIN COMMAND ’netbackuplist' is synonymous to ADMIN COMMAND
’backuplist’; it reports on both local and network backups.

Flat and deep NetBackup directory structures

The NetBackup Server sees all the database files sent to it as one logical database
even though the source database may consist of multiple files stored in different
directories and on different permanent storage devices. By default, netbackup
copies all the files of the source database to a single directory, that is, the
user-specified netbackup directory.

It is, however, possible to explicitly specify the directories, the names and sizes of
the backup files stored into the file system of the NetBackup Server. This is done
by creating a backup.ini netbackup configuration file to the netbackup directory.
The netbackup configuration file follows the syntax of [IndexFile] section in

2 Administering solidDB 29
 solidDB configuration file. Therefore, in addition to the section name, it may
include multiple specifications for file names and sizes. Formally the syntax is as
follows:
[IndexFile]
FileSpec_[1...N]=[path/]file name [maximum file size]

A NetBackup Server having such a backup.ini file receives the incoming database
as a whole, splits it into N separate parts and stores the parts as files in accordance
with the specifications in the backup.ini file.

Tip:

An easy way to retain the directory structure of the source server is to copy and
rename the source server's solid.ini to backup.ini and move it to the backup
directory at the NetBackup Server. The NetBackup Server reads only the
FileSpec_[1...N] specifications from the [IndexFile] section, creates similar directory
structure and stores backup files with their original properties to the NetBackup
Server.

Configuring and automating backups

For both local and network backup, all the optional settings except the
synchronized execution, -s, can be set beforehand in the database configuration file.
Since the name and the syntax of the configuration parameters differ from the
ADMIN COMMAND options, the corresponding parameter-option pairs are listed
in the table below.

Corresponding ADMIN COMMAND options and configuration parameters for

local backup
Table 8. Parameter correspondence to the solid.ini file for local backup

parameter in section [General] of

Option Value solid.ini

dir backup dir BackupDirectory = backup dir

default: no default

Corresponding ADMIN COMMAND options and configuration parameters for

netbackup
Table 9. Parameter correspondence to the solid.ini file for netbackup

parameter in section [General] of

option value solid.ini

connect connect str NetBackupConnect = connect str

default: no default

dir backup dir NetBackupDirectory = backup dir

default: no default

netbackup DELETE_LOGS NetbackupDeleteLog = yes

default: yes

30 IBM solidDB: Administrator Guide

Table 9. Parameter correspondence to the solid.ini file for netbackup (continued)

parameter in section [General] of

option value solid.ini

netbackup KEEP_LOGS NetbackupDeleteLog = no

default: yes

For the complete list of configuration parameters and ADMIN COMMAND

options see Appendix A, “Server-side configuration parameters,” on page 165 and
Appendix F, “solidDB ADMIN COMMAND syntax,” on page 309, respectively.

Note: The options entered in ADMIN COMMAND command override

corresponding parameters specified in the solid.ini database configuration file.

Making backups can be automated by using timed commands. Read “Entering

timed commands” on page 36 for details.

What happens during backup

Both local and network backup create a self-contained and self-consistent image of
a database by copying necessary files to the user-specified backup directory.

Every backup makes a checkpoint as its first action. This guarantees that the
possible restore starts with as fresh backup as possible. This way, the slower
roll-forward portion of the restore is minimized. The following files are then
copied by default to the specified backup directory:
v the database files containing the checkpointed database itself,
v the log files including changes made by those transactions that are active when
the backup takes place,
v the solmsg.out database message file (this is for convenience in diagnosing
problems — the message file is not required during a restore), and
v the solid.ini configuration file is also copied by default because after a disk
crash the original might be destroyed (the configuration file is not required
during a restore).

The solid.lic licence file is not automatically copied.

Note: The name of the database files and their maximum size are specified in the
FileSpec[1...N] parameters in the [IndexFile] section of the solid.ini
configuration file. The name and location of log files is specified in the [Logging]
section of the configuration file.

The log files are typically deleted from the source server after they have been
copied to the backup directory since they have become useless. This is the default
backup procedure and it is referred to as Full backup.

It is, however, possible to retain all the log files produced over time by the update
transactions in the database server directory. Keeping all the log files is
space-consuming but allows, for instance, bringing the database up-to-date by
re-executing all the updates by using the log files only. This backup type is called
Copy backup.

2 Administering solidDB 31
 Note: If you want to use Copy backups, that is, retain the full log file history, you
also must ensure that the log files are not deleted at the end of checkpoint. This
can be done by ensuring that you do not have the line CheckpointDeleteLog=yes in
section [General] of the solid.ini configuration file.

Local backup
In local backup the database and the log files are copied from the database
directory to user specified backup directory accessible from within the same
machine.

If the backup directory already includes files with same names, they will be
overwritten. If the specified backup directory does not exist, the backup fails and
the call returns an error.

CAUTION:

Ensure that backup and database directories are both on different physical
device and in different file system than database files. If one disk drive is
damaged, you will lose either your database files or backup files but not both.
Similarly, if one file system fails, either the backup or the database files will
survive.

Network backup
Netbackup is a facility for storing the whole database at some remote location.
This is done by way of a solidDB Netbackup Server whose function is to receive
backups over the network. One Netbackup Server can serve multiple simultaneous
backup source servers.

Similarly to local backup, the files are written into a user specified directory in the
Netbackup Server. If the target netbackup directory includes files with the same
names, they will be overwritten. Unlike the local backup, if the specified remote
directory does not exist, it is created automatically.

solidDB Netbackup Server requires the administrator privileges from the caller of
netbackup. Less privileged users can perform netbackups by using stored
procedures that are created by an administrator. In that case the user must be
granted the right to execute the procedure.

Netbackup can be performed between different server versions provided that they
are netbackup compatible. By principle, a newer version of the Netbackup Server
will serve older versions of source servers. In other cases, the protocol version is
checked and an incompatibility error is returned at the netbackup's request.

Administering network backup server

Every solidDB database server since version 4.5 also acts as a Network Backup
Server. One configuration parameter, however, must be set in the in [Srv] section in
the solid.ini configuration file:
NetBackupRootDir=netbackup root path

The path is relative to the working directory and the default is the working
directory.

You can shut down a Netbackup Server by following the normal shutdown
sequence and using the normal close and shutdown commands.
1. ADMIN COMMAND 'close'

32 IBM solidDB: Administrator Guide

 No new netbackup requests are accepted.
2. ADMIN COMMAND 'throwout all'
Aborts the backups in progress.
3. ADMIN COMMAND 'shutdown"
Shuts down the server.

Monitoring and controlling backups

solidDB offers a set of ADMIN COMMANDs for monitoring and controlling
backups.

The syntax is as follows:

ADMIN COMMAND ’command’

where command is any of the options presented in the table below.

Table 10. Backup and netbackup commands

Local backup command Network backup command Description

status backup status netbackup Displays the status of the most recent
backup.

backuplist netbackuplist Displays a status list of last backups.

info bcktime - Displays the time of the latest completed

backup.

abort backup abort netbackup Cancels the ongoing backup process.

Querying the list of all completed backups and their success

status

To query the list of all completed backups and their success status, issue the
following command:
ADMIN COMMAND ’backuplist’

Aborting an active network backup operation

To abort an active network backup operation, issue the following command:

ADMIN COMMAND ’abort netbackup’

Correcting a failed backup

When solidDB is performing a backup — local or network — the command
ADMIN COMMAND ’status [backup | netbackup]’

returns the value "ACTIVE". The default option is backup. Once the backup is
completed, the command returns either "OK" or "FAILED".

If the backup failed, you can find the error message that describes the reason for
the failure in the solmsg.out file in the database directory. Correct the cause of the
error and try again.

2 Administering solidDB 33
 Troubleshooting backups
Backup media is out of disk space

Making a backup requires the same amount of disk space as the database being
backed-up. Ensure that you have enough disk space in the backup storage device.

Invalid path for backup directory

The backup directory must be a valid path name in the server operating system.
For example, if the server runs on a UNIX operating system, path separators must
be slashes, not backslashes.

Local backup directory does not exist

If you specify a non-existent backup directory, the server prints an error message
and the backup fails. If you perform backups as timed operations, you can ensure
the success of backups from solmsg.out file.

Local backup directory is the same as the database directory

Because the backup copies database files with their original names to the target
directory, using the same source and target directories leads to a file sharing
conflict.

solidDB network backup server does not exist in the specified

location

If you try to start a network backup without setting up solidDB network backup
server properly, the netbackup will fail.

Backup slows down the database

Backup can slow down the database if the backup uses same storage resources as
the database. This can happen, for example, in the following cases:
v The backup write uses the same device controller as the database.
v The backup write uses the same physical storage device as the database.
v The operating system buffers large amounts of the backup data into memory.

Restoring backups
You can restore the database to the state it was in when the backup was created by
following the instructions below. Furthermore, you can revive a backup database to
the current state by using log files generated after the backup was made. Those log
files include information about the data inserted or updated since the latest
backup.

Preparing netbackup files for recovery

Two preliminary steps may have to be taken before a database can be recovered
from remote backup files.
1. If backup.ini was not used, the original naming and sizing of the database
files must be restored from the solid.db file.
2. All the backup files must be copied to the node where the restore takes place.

Besides these steps, restoring a netbackup is similar to restoring local backup.

34 IBM solidDB: Administrator Guide

 Returning to the state of the last backup
1. Shut down solidDB, if it is running.
2. Delete all log files from the log file directory. The default log file names are
sol00001.log, sol00002.log, and so on.
3. Copy the database files from the backup directory to the database file
directory.
4. Start solidDB.

This method will not perform any recovery because no log files exist.

Refreshing database from the backup to the current state

1. Shut down solidDB, if it is running.
2. Copy the database files from the backup directory to the database directory.
3. Copy the log files from the backup directory to the log directory. If the same
log files exist in both directories, do not overwrite the newer log files with the
older backup log files.
4. Start solidDB.

solidDB will automatically use the log files to perform a roll-forward recovery.

Recovering from abnormal shutdown

If the server was closed abnormally, that is, if it was not shut down using the
procedures described earlier, solidDB automatically uses the log files to perform a
roll-forward recovery during the next start up. No administrative procedures are
required to start the recovery.

Transaction logging
Transaction logging guarantees that no committed operations are lost in the case of
a system failure. When an operation is executed in the server, the operation is also
saved to a transaction log file. The log file is used for recovery in case the server is
shut down abnormally.

There are two different logging modes:

v Ping-pong method
This method uses the last two allocated disk blocks in the log file to write the
two latest versions of the same logical incomplete disk block. The ping-pong
method toggles between these two blocks until one block becomes full.
v Overwriting method
This method rewrites incomplete blocks at each commit until it becomes full. It
may be used when data loss from the last log file disk block is affordable.

solidDB allows you to decide whether you want to use logging or not. If logging is
used, abnormally shut down databases can be restored to the state they were at the
moment the failure took place. If the logging is disabled, databases can be restored
to the backup state only. Transaction logging is enabled by default. If the full
transaction recovery is not needed, logging can be disabled. To do this, set the
[Logging] parameter LogEnabled to "no".

Logging may be synchronous or asynchronous, depending on the transaction

durability setting. For more on transaction durability, see the subsection Logging
and transaction durability in 7, “Performance tuning,” on page 123.

2 Administering solidDB 35
Creating checkpoints
A checkpoint updates the database files on disk. Specifically, a checkpoint copies
pages from the database server's memory cache to the database file on the disk
drive. The server does the copy in a transactionally-consistent way; that is, only
results of committed transactions are copied. The result is that all of the data in the
database file is committed data from complete transactions. If the server fails
between checkpoints, the disk drive will have a consistent and valid (although not
necessarily up-to-date) snapshot of the data.

Between checkpoints, the server writes committed transactions to a transaction log.

If the server fails, any transactions committed since the last checkpoint can be
recovered from this transaction log. After a system crash, the database will start
recovering transactions from the latest checkpoint.

Checkpoints can be seen as the main write operations to the database files on disk.
The server does not write the results of each individual INSERT/UPDATE/
DELETE statement (or even the result of each transaction) to the disk as it
happens. Instead, the server accumulates committed transactions in the form of
updated pages in memory and writes them to the disk only during checkpoints.
The server can also use part of the database file as swap space if the server's cache
overflows. In this situation, the server also writes to the database file.

solidDB has an automatic checkpoint creation daemon, which creates a checkpoint

after a certain number of writes to the log files. A checkpoint is also created at
startup and during shutdown and backup. For more information about controlling
the frequency of checkpoints, see “Tuning checkpoints” on page 133.

Checkpoints apply also to persistent in-memory tables, not just disk-based tables.

Note: There can only be one checkpoint in the database at a time. When a new
checkpoint is created successfully, the older checkpoint is automatically erased. If
the server process is terminated in the middle of checkpoint creation, the previous
checkpoint is used for recovery.

A checkpoint can require a substantial amount of I/O, and can affect the server's
responsiveness while the checkpoint is occurring.

Creating checkpoints manually

If you want to create a checkpoint manually, for example, before and after a
database operation, issue the following command:
ADMIN COMMAND ’makecp’

You can also create a checkpoint using a timed command. See “Entering timed
commands” for more details.

Entering timed commands

solidDB has a built-in timer which allows you to automate your administrative
tasks. You can use timed commands to execute operating system commands, to
create backups, checkpoints, and database status reports, to open and close
databases, and to disconnect users and shut down servers.

To enter a timed command, edit the At parameter in the [Srv] section of the
solid.ini file. The syntax is:

36 IBM solidDB: Administrator Guide

 At = At_string
At_string ::= timed_command [, timed_command]
timed_command ::= [ day ] HH:MM command argument
day ::= sun | mon | tue | wed | thu | fri | sat

If the day is not given, the command is executed daily.

Example:
[Srv]
At = 20:30 makecp, 21:00 backup, sun 23:00 shutdown

Note: The format used is HH:MM (24-hour format).

The following table contains a list of valid commands and their arguments.
Table 11. Arguments and defaults for different timed commands

Command Argument Default

backup backup directory the default backup directory that is set in the
configuration file

throwout user name, all no default, argument compulsory

makecp no arguments no default

shutdown no arguments no default

report report file name no default, argument compulsory

system operating system command no default

For example in Linux

environments:

cp solmsg.out solmsg2.out

open no argument no default

close no argument no default

Compacting database files (database reorganization)

Database reorganization returns unused space back to the file system. This is
useful, for example, in case your application causes short-term peaks in the
database space usage, resulting in large allocated disk space. The database
reorganization is started at solidDB startup with the command line option solid
-x reorganize.

About this task

When databases grow, solidDB server allocates new disk pages. However, it does
not free the space allocated previously in the database files even if it is not needed
any more. Instead, it maintains a list of unused pages for later use.

The solidDB database file compaction feature works in offline mode at the page
level. Offline means that a database file being compacted cannot be actively used

2 Administering solidDB 37
 by the server. Page level means that only empty pages are discovered and removed
from the file. No intra-page compaction is performed; data is not moved among
pages.

Important: The reorganization operation is not recoverable. If there is a failure

during the reorganization run, the reorganization or the database file cannot be
recovered later. To avoid losing data, make a database backup before starting the
reorganization.

Procedure
1. View information about the database file size by starting solidDB with the
following command:
solid -x infodbfreefactor
The -x infodbfreefactor option outputs a report of how many free pages there
are in the database, how much space in kilobytes is free, and a percentage
value of free space. After printing the report to ssdebug.log and console, the
solidDB process returns with a success return value.
Example output:
------------------------------------------------------------
2010-10-26 16:45:05
IBM solidDB - Version 6.5.0.3 Build 2010-10-04 (Linux 2.6.18 AMD64 64bit MT)
Infodbfreefactor option is activated.
------------------------------------------------------------
Database file size = 152064 Kbytes
Free blocks = 82128 Kbytes
Log file size = 0 Kbytes
Free space = 54.01%
Block size = 16384 bytes
2. Start database reorganization by starting solidDB with the following command:
solid -x reorganize

The -x reorganize option invokes database reorganization. The operation

moves pages to unused slots in the database file, if there are any. When the
page relocation is complete, the unused space is released back to the file
system; the database file is truncated, a new checkpoint is created, and the
solidDB process terminates with a success return code. The report of the
reorganization run is written to the ssdebug.log file.

Encrypting a database
By default, solidDB always encrypts passwords using the DES algorithm. If you
want to encrypt also the database files and log files, you need to create an
encrypted database using solidDB command line options. You can also disable the
encryption of passwords.

The DES algorithm shipped with solidDB is based on a symmetric-key algorithm

that uses a 56-bit key. To protect the symmetric encryption key, a startup password
must be specified when creating, starting, or decrypting an encrypted database.

The solidDB DES algorithm is a weak DES algorithm that is not recommended for
applications that require strong security.

Encrypting database and log files

The encryption of the entire database (database and log files) is enabled using
command line options -E and -x keypwdfile:<filename>.

38 IBM solidDB: Administrator Guide

 About this task
v The -E option invokes database encryption. The database can be encrypted when
creating a new database or when starting an existing database.
v The -x keypwdfile:<filename> option provides the encryption password from a
file.
The encryption password is needed to protect the symmetric encryption key
which is stored in an unencrypted header page of the database file.
The encryption password is mandatory when -E is specified. The minimum
length of the password is three characters. If your specify an empty password,
the encryption key is left unprotected.

Note: Alternatively, option -S can be used to provide the password as part of

the startup command. However, this is not secure on most of systems. For
example in UNIX systems, the password can be seen in the ps command output.
Use the -S option only for debugging or evaluation purposes.

Procedure
v Creating a new encrypted database
To create an encrypted database, include the -E and -x keypwdfile:<filename>
options in the solidDB startup command.
For example:
solid -C mycatalog -U admin -P admin -E -x keypwdfile:pwd.txt
v Encrypting an existing database
To encrypt an existing database, include the -E and -x keypwdfile:<filename>
options in the solidDB startup command.
For example:
solid -U admin -P admin -E -x keypwdfile:pwd.txt

Disabling encryption
The default encryption of passwords can be disabled with server-side or client-side
parameters, or at connection time using ODBC Connect Info settings or
non-standard JDBC connection properties.

By default, solidDB always encrypts passwords using the DES algorithm.

Databases and log files are not encrypted by default.

If you want to create an database without any encryption, disable the encryption
of passwords using the parameter settings or connection properties described
below.

Disabling the encryption of passwords disables also the encryption of database and
log files, if used.

Server-side parameter setting

To disable encryption in the solidDB server, set the server-side parameter

General.UseEncryption to No.
[General]
UseEncryption=No

The default setting is Yes.

2 Administering solidDB 39
 Client-side parameter setting

To disable the encryption for a specific ODBC client connection, set the client-side
parameter Client.UseEncryption to No.
[Client]
UseEncryption=No

The default setting is Yes.

Alternatively, disable the encryption using the connect string option

USE_ENCRYPTION=NO.

ODBC connect info option

In ODBC environments, encryption can be disabled by including the option
USE_ENCRYPTION=NO in the ODBC connect info string.

The option must be given before the server connect string, for example:
USE_ENCRYPTION=NO tcp 1964

The default is USE_ENCRYPTION=YES.

JDBC connection property

In JDBC environments, encryption can be disabled by setting the non-standard

JDBC connection property "solid_use_encryption" to NO.

Starting an encrypted database

To start an encrypted database, you must provide the encryption password at the
startup. If you do not include the password in the startup command, the server
prompts you for the password.

Procedure

Start solidDB using the following command:

solid -x keypwdfile:<filename>

For example:
solid -x keypwdfile:pwd.txt

Alternative, you can provide the password using the -S command line option:
solid -S <password>

Changing the encryption password

To change the password of the encryption key, solidDB must be started using
option -E and the options specifying the old and the new password.

Procedure

Changing the encryption password

To change the encryption password, start solidDB with the following command
syntax:
solid -E -x keypwdfile:<old key filename> -x keypwdfile:<new key filename>

40 IBM solidDB: Administrator Guide

 For example:
solid -E -x keypwdfile:pwd.txt -x keypwdfile:newpdw.txt

Alternatively, you can specify the new and old password in the command line
using the -S option
solid -E -S <old_password> -S <new_password>

Decrypting a database
You can decrypt a database with the option -x decrypt. You also need to provide
the encryption password.

Procedure

Decrypting a database
To decrypt a database, start solidDB with the following command syntax:
solid -x decrypt -x keypwdfile:<filename>

For example:
solid -x decrypt -x keypwdfile:pwd.txt

Querying database encryption level

You can check the database encryption level using the
DATABASE_ENCRYPTION_LEVEL() function. This can be useful, for example, if
your system does not allow storing data in an unencrypted file, and you need to
register a new replica.

Procedure

Use the DATABASE_ENCRYPTION_LEVEL() function. The function has the

following return values:
v 0 - no encryption
v 1 - encrypted, the key is not protected (empty password)
v 2 - encrypted, the key is protected by a separate startup password

Making backups of encrypted databases

Database backups and netbackups create encrypted copies of the database with the
same encryption key and password.

Encrypting HotStandby servers

In High Availability (HotStandby) configurations, the Primary and Secondary
servers must use the same encryption method and encryption key.

Encrypt the Primary database first and then copy or netcopy it.

HotStandby traffic is not encrypted by means of database file encryption. To

protect the HSB traffic, other security means are needed. When making an HSB
copy or netcopy, the database file and logs are transferred in encrypted form to
avoid redundant encryption/decryption of the files.

Encryption and performance

Using an encrypted database affects the database server performance for both read
and write operations.

2 Administering solidDB 41
 1. On read type operations, performance impact is mostly determined by the
cache hit rate and is not significant when the cache hit rate is high.
2. On insert and update operations, the server encrypts and decrypts the log files
(if they are used) and in this case performance penalty can be more significant.

42 IBM solidDB: Administrator Guide

3 Configuring solidDB
The various solidDB configuration options help you to meet your environment,
performance, and operation needs.

Most solidDB configuration settings are defined using configuration parameters.

There are two solid.ini configuration files, one for the server and one for the
ODBC client. Neither configuration file is obligatory. If there is no configuration
file, the factory values are used. Also, all parameters do not need to be present in
the solid.ini file; if a parameter is not present in the solid.ini file or if the value
for a particular parameter is not set, the factory value is used.

Generally the factory values offer good performance and operability but in some
cases modifying some parameter values can improve performance. You might also
need to set configuration parameters to enable or disable certain functionality.

You can set the configuration parameter values by editing the solid.ini
configuration file manually or, in most cases, using ADMIN COMMANDs.

Some parameter settings can also be overridden per session or per transaction by
using the SQL commands SET or SET TRANSACTION, or, by defining the settings
per connection with the ODBC connection attributes or JDBC connection
properties. The precedence hierarchy is the following (from high precedence to
low):
v SET TRANSACTION: transaction-level settings
v SET: session-level settings
v ODBC connection attributes and JDBC connection properties
v Parameter settings specified by the value in the solid.ini configuration file
v Factory value for the parameter

Additionally, you can control some solidDB server operations with the following
options:
v solidDB command line options at solidDB startup
v environment variables
v ODBC client connect string arguments
Related reference:
Appendix C, “solidDB command line options,” on page 221
Related information:
Appendix A, “Server-side configuration parameters,” on page 165
Appendix B, “Client-side configuration parameters,” on page 217
The client-side configuration parameters are stored in the solid.ini configuration
file and are read when the client starts.

Managing parameters
You can view and modify server-side configuration parameters using ADMIN
COMMANDs or by editing the solid.ini configuration file. Client-side
configuration parameters can only be viewed and modified using the solid.ini
file.

43
 Configuration files and parameter settings
There are two different solid.ini configuration files, one for the server and one
for the ODBC client. Neither configuration file is obligatory. If there is no
configuration file, the factory values are used.
v The server-side solid.ini is used as the main configuration file for the server.
v The client-side solid.ini file is used with the solidDB ODBC client (driver). The
client-side solid.ini file can also be used with the solidDB data management
tools, for example, to define logical data source names.

Note: In solidDB documentation, solid.ini usually refers to the server-side

solid.ini file.

When solidDB (or the ODBC client) starts, it attempts to open solid.ini first from
the directory set by the SOLIDDIR environment variable. If the file is not found
from the path specified by this variable or if the variable is not set, the server or
client attempts to open the file from the current working directory. The current
working directory is normally the same as the directory from which you started
the solidDB server, or a client application. You may also specify a different
working directory by using the -c command line option at solidDB startup.

If a value for a specific parameter is not set in the solid.ini file, solidDB will use
a factory value for the parameter. The factory values may depend on the operating
system you are using.

The configuration parameters are defined as parameter name – value pairs. The
parameters are grouped according to section categories. Each section category
starts with a section name inside square braces, for example:
[Com]

The [Com] section lists communication information. The section names are case
insensitive. The section names [COM], [Com], and [com] are equivalent.

Tip: In documentation, parameters are typically referred to in the format

section.parameter, for example, Logging.LogEnabled.

Example

Below is a sample section from a server-side solid.ini configuration file:

[IndexFile]
FileSpec_1=C:\soldb\solid1.db 1000M
CacheSize=64M

Sample solid.ini files

The samples directory in the solidDB installation directory contains samples for
different use cases. Each sample contains a solid.ini file with relevant settings for
each use case; you can use the sample solid.ini files as a reference when
configuring your environment.

Tip: If the solidDB server and the client are run on the same machine and use the
same working directory, a single solid.ini configuration file can be both the
server-side and the client-side configuration file. For example, the solid.ini
configuration file in the solidDB_installation_directory\eval_kit\standalone
directory contains both the server-side Com.Listen and the client-side Com.Data
Sources parameter settings.

44 IBM solidDB: Administrator Guide

 Related concepts:
“Logical data source names” on page 86
The solidDB tools and client libraries support logical data source names. Logical
data source names can be used for giving a database a descriptive name.
Related information:
Appendix A, “Server-side configuration parameters,” on page 165
Appendix B, “Client-side configuration parameters,” on page 217
The client-side configuration parameters are stored in the solid.ini configuration
file and are read when the client starts.

Viewing and setting parameters with ADMIN COMMAND

You can change most server-side parameters with ADMIN COMMANDs without
the need to restart the solidDB server. All parameters are accessible with the
ADMIN COMMANDs even if they are not present in the solid.ini configuration
file.

Viewing parameters
You can view the parameter settings by all parameters, all parameters in a section,
or a single parameter at a time.

About this task

The syntax for viewing parameters is the following:

ADMIN COMMAND ’parameter [-r] [section_name[.parameter_name]]’;

where:
v -r specifies that only the current value is shown
v section_name is the category name where the parameter is located in solid.ini

Procedure
v To view all parameters, use the following command:
ADMIN COMMAND ’parameter’;
RC TEXT
-- ----
0 Accelerator ImplicitStart Yes Yes Yes
0 Accelerator ReturnListenErrors No No No
0 Com Listen tcpip 2315, tcpip 2315, tcpip 1964
0 Com MaxPhysMsgLen 8192 8192 8192
0 Com RConnectLifetime 60 60 60
0 Com RConnectPoolSize 10 10 10
0 Com RConnectRPCTimeout 0 0 0
0 Com ReadBufSize 2048 2048 2048
0 Com SocketLinger Yes Yes Yes
0 Com SocketLingerTime 0 0 0
.
.
.
192 rows fetched.
v To view a single parameter, include the section name and parameter name in the
command. For example:
admin command ’parameter logging.durabilitylevel’;
RC TEXT
-- ----
0 Logging DurabilityLevel 3 2 2
1 rows fetched.

3 Configuring solidDB 45
 v To view all parameters in a section, include the section name in the command.
For example:
admin command ’parameter logging’;
RC TEXT
-- ----
0 Logging BlockSize 16384 16384 16384
0 Logging DigitTemplateChar # # #
0 Logging DurabilityLevel 1 1 1
0 Logging FileFlush Yes Yes Yes
0 Logging FileNameTemplate sol#####.log sol#####.log sol#####.log
0 Logging LogDir logs logs
0 Logging LogEnabled Yes Yes Yes
0 Logging LogWriteMode 2 2 2
0 Logging MinSplitSize 10485760 10485760 10485760
0 Logging RelaxedMaxDelay 5000 5000 5000
0 Logging SyncWrite No No No
11 rows fetched.

Results

The output show three values in the following order:

v current value
v startup value that was used when the server was started up
v factory value preset in the product

To show only the current value, use the -r option. For example:
admin command ’parameter -r logging’;
RC TEXT
-- ----
0 Logging BlockSize 16384
0 Logging DigitTemplateChar #
0 Logging DurabilityLevel 1
0 Logging FileFlush Yes
0 Logging FileNameTemplate sol#####.log
0 Logging LogDir logs
0 Logging LogEnabled Yes
0 Logging LogWriteMode 2
0 Logging MinSplitSize 10485760
0 Logging RelaxedMaxDelay 5000
0 Logging SyncWrite No
11 rows fetched.

Viewing the description of a specific parameter

You can view a detailed description of a specific parameter, which includes valid
parameter types and access modes.

Note: Parameter support may vary between platforms.

To view a parameter's description, enter the following command using solidDB

SQL Editor (teletype):
ADMIN COMMAND ’describe parameter [section_name[.parameter_name]] ’;

A result set for a single parameter looks like this:

admin command ’describe parameter logging.durabilitylevel’;
RC TEXT
-- ----
0 DurabilityLevel
0 Default transaction durability level
0 LONG
0 RW

46 IBM solidDB: Administrator Guide

 0 2
0 3
0 2
7 rows fetched.

The rows of the resultset are:

v Parameter name is the name of the parameter, for example CacheSize.
v Description of the parameter
v Data type
v Access mode that may be one of the following:
– RO: read-only, the value cannot be changed dynamically
– RW: read/write, the value may be changed dynamically and the change
takes effect immediately
– RW/STARTUP: the value may be changed dynamically but the change takes
effect upon next server startup
– RW/CREATE: the value may be changed dynamically but the change takes
effect when a new database is created
v Startup value displays the parameter's startup value
v Current value displays the parameter's current value
v Factory value displays the value preset in the product

Setting a parameter value

Most parameters can be changed with ADMIN COMMAND ’parameter’. Depending on
the access mode of the parameter, the change may or may not apply immediately.

The syntax of the command is:

ADMIN COMMAND ’parameter param_name = value [temporary]’
v The param_name and value follow the rules specified in “Format of configuration
parameter names and values” on page 52.
– The param_name must include the section name and the parameter name,
separated by a period.
For example, to set the value of the DurabilityLevel parameter in the
[Logging] section to '1', issue the command:
ADMIN COMMAND ’parameter Logging.DurabilityLevel=1’;
– The value must be a valid value, or:
If no value is specified, the parameter is set to the factory (or unset) value.
If you assign a parameter value with an asterisk (*), the parameter will be set
to its factory value.
v You can provide blanks around the equal sign. For example:
ADMIN COMMAND ’parameter com.trace = yes’
v When temporary is set, the changed value is not stored in the solid.ini file.
v When the value of a parameter is changed with an ADMIN command, the
change may or may not apply immediately, and may or may not apply the next
time that the server is started.
– If a parameter value is written to the solid.ini file, it will take effect the next
time that the server starts.
– If the temporary option is used, the value will affect the server's current
behavior, but will not affect the server when it restarts.

3 Configuring solidDB 47
 – In some cases, changing a parameter may take effect immediately and be
written to the solid.ini file so that it also applies the next time that the
server starts. This depends on the access mode of the parameter.

The commands return the new value as the resultset. If the parameter's access
mode is RO (read-only) or the value entered is invalid, the ADMIN COMMAND
statement returns an error.

Note: Parameter management operations are not part of a transaction and cannot
be rolled back.
Related information:
“Access mode and persistence of parameter modifications”
The access mode of a parameter defines whether the parameter can be changed
dynamically via an ADMIN COMMAND, and when the change takes effect.

Access mode and persistence of parameter modifications

The access mode of a parameter defines whether the parameter can be changed
dynamically via an ADMIN COMMAND, and when the change takes effect.

The possible access modes are:

v RO (read-only): the value cannot be changed; the current value is always
identical to the startup value.
v RW: the value can be changed via an ADMIN COMMAND and the change takes
effect immediately.
v RW/Startup: the value can be changed via an ADMIN COMMAND and the
change takes effect the next time that the server starts.
v RW/Create: the value can be changed via an ADMIN COMMAND and the
change applies when a new database is created.

All the changes made to parameters having the access mode RW* are stored in the
solid.ini file at the next checkpoint. This does not apply to values set with the
temporary option.

Saving parameters

It is also possible to request an immediate storing of changed values with the

command:
ADMIN COMMAND ’save parameters [ini_file_name]’;

If ini_file_name is not specified, the current solid.ini file is rewritten. If

ini_file_name is specified, a full configuration file is written to a new location. This
is a convenient way to save configuration file checkpoints for later use.

Example: Read-only (RO) parameter IndexFile.BlockSize

The access mode of the IndexFile.BlockSize parameter is RO. The parameter is

set when the database is created and cannot be modified afterwards.

If you want to use a different constant value, you have to create a new database.
Before creating a new database, set the new parameter constant value by editing
the solid.ini file.

The following example sets a new block size for the index file by adding the
following lines to the solid.ini file :

48 IBM solidDB: Administrator Guide

 [IndexFile]
Blocksize = 4096

After editing and saving the solid.ini file, move or delete the old database and
log files, and start solidDB.

Tip: The log block size can be changed between startups of the server.

Setting parameters through the solid.ini configuration file

When the solidDB server (or ODBC client) is started, it attempts to open the
configuration file solid.ini. If the file does not exist, the factory values for the
parameters are used. If the file exists, but a value for a particular parameter is not
set in the solid.ini file, factory value for that parameter is used. The factory
values depend on the operating system you are using.

By default, the server looks for the solid.ini file in the current working directory,
which is normally the directory from which you started the server.

You can specify a different directory to be used as the current working directory in
the following ways:
v Use the -c solidDB command line option.
v Set the SOLIDDIR environment variable to specify the location of the solid.ini
file.

When searching for the solid.ini file, solidDB uses the following precedence
(from high to low):
v location specified by the SOLIDDIR environment variable (if set)
v current working directory
Related reference:
Appendix C, “solidDB command line options,” on page 221

Rules for formatting the solid.ini file

The configuration file solid.ini is an ASCII file with line breaks. Comments are
preceded with a semicolon (;).
[section_name]
param_name1=param_value
param_name2=param_value ;This is a comment

[section_name2]
param_name3=param_value
;This is a comment line (less than 79 characters)

Section names

The solid.ini configuration file is divided into sections. Each section contains a
group of one or more loosely-related parameters.

Each section has a unique name. The name is delimited with square brackets. For
example:
[SQL]

Every parameter must be under a section header. If you put a parameter before
any section header, you get an error message indicating that there is an
unrecognized entry in the section named "<no section>".

3 Configuring solidDB 49
 Section names can be repeated. For example:
[Index]
BlockSize=2048
[Com]
...
[Index]
CacheSize=8m

However, repeating sections names makes it more difficult for users to keep the
file up-to-date and consistent.

Parameter names and values

Parameters are specified in the following format:

param_name=param_value

For example:
Listen=tcp 127.123.45.156 1313
DurabilityLevel=2

Blank spaces around the equals sign are allowed but not required. The following
are equivalent:
DurabilityLevel=2
DurabilityLevel = 2

If you omit the parameter value, the server will use the factory value. For example:
; Use the factory value
DurabilityLevel=

If you omit the parameter value and the equals sign, you get an error message.

Parameter names can be repeated (you will not get a warning message), but this is
very strongly discouraged. The last occurrence of the parameter in the file takes
the precedence.

There are a few cases where two or more sections have parameters with the same
name. Therefore, you must be careful to place each parameter in the correct
section.

Most sections and parameters are optional. You do not need to specify a value for
every parameter in every section, and in fact you can omit entire sections. If you
omit a parameter, the server will use the factory value.

Comments

The configuration file can contain comments; comments must begin with a
semicolon (;). The comments can be put on separate lines or on the same line as a
parameter.
; This is a valid comment.
DurabilityLevel=2 ; This is also a valid comment.

The maximum length of a line is 79 characters. If you create comments longer than
79 characters, the server splits the comments on separate lines using a backslash (\)
at the end of the line but without adding a comment marker (;) on the new line.
The server can handle the lines that have been split in this way; however,
applications such as watchdogs might see the file as corrupted and thus fail. If you

50 IBM solidDB: Administrator Guide

do not want the server to split long lines, set the Srv.InifileLineSplitting
parameter to no.

Validation of entries

The server checks each entry in the solid.ini file.

v If the entry is not a comment, the server checks that the combination of section
name and parameter name is valid.
v If the entry is invalid, the server will display an error message in the solmsg.out
file.
If the server is running as a foreground process, the message will also be
displayed on the console.
The message will be similar to one of the following:
v Warning: Unrecognized entry in inifile: '<section>.<parameter>'.
You will see this message if you have entries that fit the proper form, but which
do not have the predefined section names and parameter names.
For example, you can get this message with the following type of solid.ini
entry:
; This has a valid section name, but an invalid parameter name.
[Logging]
NoSuchParam=NoSuchValue

;This has an invalid section name.

[NoSuchSectionName]
The message for the first of these errors would be similar to: Warning:
Unrecognized entry 'Logging.NoSuchParam' in inifile.
v Warning: Illegal entry in inifile: <whole illegal line>
The server will display this message if a line could not be recognized as a
section header, parameter name, comment, or blank line. You might see this
message if you have entries that are not in the proper form.
For example, you can get this message with the following type of solid.ini
entry:
; This text was intended to be a comment
but part of it is not preceded with a semicolon.
v Warning: <number> unrecognized or illegal entries in '<inifilename>'.
After the server has finished processing the solid.ini file, it will list the total
number of errors detected.
v Warning: Unregistered parameter <section>.<parameter> is used.
If this error occurs, it is a sign of a possible problem inside the server itself;
report the error to IBM Software Support.

Important:
v The server does not necessarily display an error message if you use an invalid
value for a parameter. The server may simply use the factory value without
issuing an error message.
v The solid.ini parameter file is checked only when the server starts. If you edit
it after the server starts, the server will not see the changes until the next time
that the server starts.
v If you make changes to the solid.ini file AND you make changes to
parameters in the server by using an ADMIN COMMAND, the behavior is
unpredictable. While the server is running, you can safely change the solid.ini

3 Configuring solidDB 51
 file OR make changes to server values using the ADMIN COMMAND, but you
should not do both during the same "run" of the server.

Summary of solid.ini formatting rules

v Section name is in the format [section_name]
v The same section name may be used several times (not recommended).
v Each parameter is set in a separate line.
v The comment marker is the semicolon (;).
v Comments may follow other entries that are in the same line.
v The maximum length of a line is 79 characters.
v Entries in the files may be preceded with blanks.
v If the first non-blank character is the comment character, the whole line is
ignored (that is, it is treated as a comment line).
v Lines that have no characters, or that have only blank characters, are ignored.
v The maximum length of a line is 78 characters.

Example

The following example shows a simple solid.ini file entry that contains a section
heading, a parameter, and a comment:
[Logging]
; Use "relaxed logging", which improves performance but may
; risk losing the last few transactions during a failure.
DurabilityLevel=1

[Com]
...

Format of configuration parameter names and values

The rules for configuration parameter names and values are the same regardless of
whether the parameters are set through the solid.ini file or an ADMIN
COMMAND:
v The section and parameter names are not case-sensitive.
v The string values are not case-sensitive.
v In most cases, units are not case-sensitive. For example, to specify that the units
are in megabytes, you may use any of the following: m, M, MB, mb, Mb, or mB.
Some units (for example, time units 's' (seconds) and 'ms' (milliseconds)) are case
sensitive and such cases are documented.
v The syntax for general parameter value setting is:
param_name [space characters] = [space characters] value_literal
The syntax for the value is
value_literal [space characters] unit_of_measure
where
param_name is the parameter name. When this is used in an ADMIN
COMMAND, the name should be the full parameter name, including the section
name, for example, Logging.DurabilityLevel. When this is used in the
solid.ini file, it should NOT include the section name, since the parameter
should already be listed under the appropriate section header.
value_literal is the value to be assigned to the parameter. This is usually a literal,
such as the number 12, or the string "tcp MyServer2 1315". If you give no value,
the parameter will be set to its startup value. If you assign a parameter value

52 IBM solidDB: Administrator Guide

 with an asterisk (*), the parameter will be set to its factory value. Note that
string literals should normally be in double quotes if they are used in an
ADMIN COMMAND.
unit_of_measure is the unit of measure, for example MB for megabytes or ms for
milliseconds.
[space characters] represents places where spaces are allowed but not required.
Spaces around the equals sign are optional. Spaces between the value and the
unit of measure are optional.
For example, allowed forms include:
CacheSize=32M
cachesize=32m
CacheSize = 32 m

Most important server-side parameters

This section describes the most important solidDB server-side parameters and their
default settings.

Defining network names (Com section)

When a server is started, it starts listening to one or more protocols with network
names that distinguish it in the network. A client application uses a similar
network name (connect string) to specify which protocol to use and which server
to connect to.

The network name is defined with the Listen parameter in the [Com] section, for
example:
[Com]
Listen = tcpip localhost 1313

The default value is operating system dependent. See 5, “Managing network

connections,” on page 81 for details on the parameter format.

Managing database files and caching (IndexFile section)

In solidDB, data and indexes are stored in the same file(s). The term "index file" is
used as a synonym for the term "database file". The [IndexFile] section of the
solid.ini file contains parameters that specify the name and location of the file(s)
used to store the database. The [IndexFile] section of solid.ini also controls the
caching-related parameters.

FileSpec_[1...n] parameter: The Indexfile.FileSpec parameter describes the

location and the maximum size of an index file (database file). To define the
location and maximum size, the FileSpec parameter accepts the following three
arguments:
v database file name
v maximum file size
v device number (optional)
[IndexFile]
FileSpec_1=SOLID.DB 2000M

The default value for this parameter is solid.db 2147483647 (2 GB-1 expressed in
bytes).

The size unit is 1 byte. You can use K and M unit symbols to denote kilobytes and
megabytes, respectively. The maximum file size is (4G-1)*blocksize. With the
default 16 KB block size, this makes 64 TB - 1.

3 Configuring solidDB 53
 The FileSpec parameter is also used to divide the database into multiple files and
onto multiple disks. To divide the database into multiple files, specify another
FileSpec parameter identified by the number 2. The index file will be written to
the second file if it grows over the maximum value of the first FileSpec parameter.

In the following example, the parameters divide the database file on the disks C:,
D: and E: to be split after growing larger than about 1 GB (=1073741824 bytes).
This example does not use the optional device number.
[IndexFile]
FileSpec_1=C:\soldb\solid.1 1000M
FileSpec_2=D:\soldb\solid.2 1000M
FileSpec_3=E:\soldb\solid.3 1000M

Note:

The index file locations entered must be valid path names in the server's operating
system. For example, if the server runs on a UNIX operating system, path
separators must be slashes instead of backslashes.

Although the database files reside in different directories, the file names must be
unique. In the above example, the different device numbers indicate that C:, D: and
E: partitions reside on separate disks.

There is no practical limit to the number of database files you may use.

Splitting the database file on multiple disks will increase the performance of the
server because multiple disk heads will provide parallel access to the data in your
database.

You may need to have multiple files on a single disk if your physical disk is
partitioned into multiple logical disks and no single logical disk can accommodate
the size of the database file you expect to create.

If the database file is split into multiple physical disks, the multithreaded solidDB
is capable of assigning a separate disk I/O thread for each device. This way the
server can perform database file I/O in a parallel manner. Read section Dedicated
threads in “Types of threads” on page 9 for more details.

The optional device number that you may specify for each data file helps the server
optimize its performance. The actual device number serves only as a means for
you to designate a distinct number for each physical device; the device number
serves no other purpose, such as indicating the brand, model, or other
characteristics of your storage device.

If you have different files on the same physical device, use the same device
number for each of those files. For example, on a Windows system that has two
physical disk drives, the first physical disk drive is typically C:. A second physical
disk drive could be partitioned into two logical disk drives, D: and E:. If one data
file is put on C:, one on D:, and one on E:, then the solid.ini file might look like
the following:
FileSpec_1=C:\soldb\solid.1 1000M 1
FileSpec_2=D:\soldb\solid.2 1000M 2
FileSpec_3=E:\soldb\solid.3 1000M 2

54 IBM solidDB: Administrator Guide

In this case, FileSpec_2 and FileSpec_3 use the same physical device (even though
the device names D: and E: are different), so they are assigned the same device
number. The actual values used for the device number (1 for C:, 2 for D:, and 2 for
E:) are arbitrary and meaningless.

If your database has reached the maximum size specified by the FileSpec
parameter, you need to increase the maximum file size limit or divide the database
into multiple files.

CAUTION:
Do not attempt to use the FileSpec parameter to decrease the size of a database;
you risk losing existing data and corrupting the database.
Related concepts:
“Troubleshooting database file size (file write fails)” on page 151
If your database has reached the maximum size specified by the
IndexFile.FileSpec parameter, you need to increase the maximum file size limit or
divide the database into multiple files.

CacheSize: The CacheSize parameter defines the amount of main memory used to
maintain the shared buffer pool of the disk database. This buffer pool is called the
database cache. The factory value depends on the server operating system. For the
pure in-memory database operation, the cache size is mostly irrelevant once it is
not less than 8 MB. The absolute minimum size is 512 kilobytes. For example:
[IndexFile]
CacheSize=512

The size unit is bytes. You may also specify the amount of space in units of
megabytes, for example, "10M" for 10 megabytes. Although solidDB is able to run
with a small cache size, a larger cache size generally speeds up the server. The
cache size needed depends on the size of the database, the number of connected
users, and the nature of the operations executed against the server.

The default cache size is 32 MB.

Specifying default table storage type (General section)

By default, new tables are created as in-memory tables (M-tables). You can set the
default table type with the General.DefaultStoreIsMemory parameter.

You can override the value set with General.DefaultStoreIsMemory by using the
STORE clause in the CREATE TABLE statement.

For example:
CREATE TABLE employees (name CHAR(20)) STORE MEMORY;
CREATE TABLE ... STORE DISK;
ALTER TABLE network_addresses SET STORE MEMORY;

Specifying local backup directory (General section)

Backups of the database, log files and the configuration file solid.ini are copied
to the local backup directory. The directory must exist and it must have enough
disk space for the backup files since all the database files of one database are
copied to the same directory. It can be set to any existing directory except the
solidDB database file directory, the log file directory or the working directory.

The name and location for your backup directory is defined with the
BackupDirectory parameter in the [General] section.

3 Configuring solidDB 55
 The default location is a directory relative to your solidDB working directory.

For example:
[General]
BackupDirectory=backup

With the above value 'backup', the backup will be written to a directory that is a
subdirectory of the solidDB directory.

The backup directory entered must be a valid path name in the server's operating
system. For example, if the server runs on a UNIX operating system, path
separators must be slashes instead of backslashes.

Specifying the network backup directory (General section)

The target directory in the NetBackup Server for the backup files, log files and the
configuration file is set with the NetBackupDirectory parameters in the source
server and the network server side. If the remote directory does not exist, it is
created (write rights needed).

Source-side parameter: The parameter

[General]
NetBackupDirectory=netbackupdir

in the source server sets the remote directory for use of Network Backup. The
netbackupdir is either absolute or relative to the root directory of the NetBackup
Server.

Netbackup server-side parameter: The parameter

[Srv]
NetBackupRootDir=netbackup root dir

in the NetBackup Server sets the root directory to all netbackup operations using
relative path expressions by their NetBackupDirectory specifications. The netbackup
root dir is either absolute or relative to the working directory.

Important:

NetBackup copies logical database consisting of multiple files to one flat file to the
NetBackupDirectory by default. Instead of flattening the structure to one file you
can define multiple files to which the source database files are mapped in
netbackup. Mapping source database file(s) to multiple backup database files is
done by way of using the backup.ini file.)

To ensure the durability of committed transactions, transaction results are written

immediately to a file in a specified directory when the transaction is committed.
This file must be stored to a local drive using local disk names to avoid problems
with network I/O and to achieve better performance. The default log file directory
is the solidDB working directory.

FileNameTemplate: The FileNameTemplate parameter in the Logging section

defines a filename structure for the transaction log files. For example, the following
setting
[Logging]
FileNameTemplate = d:\logdir\sol#####.log

56 IBM solidDB: Administrator Guide

instructs solidDB to create log files to directory d:\logdir and to name them
sequentially starting from sol00001.log.

Note:

Placing log files on a physical disk separate from database files improves
performance.

The filename can also be structured by using the FileNameTemplate parameter

together with the LogDir parameter, in which case the LogDir parameter defines
the directory prefix of the filename and the FileNameTemplate parameter defines
the actual filename. For more information, see “Logging section” on page 184.

Setting threads for processing (Srv section)

In addition to the communication, I/O, and log manager threads, solidDB can start
general purpose worker threads to execute user tasks in the server's tasking
system. Read “Multithread processing” on page 8 for more details.

The Threads parameter in the [Srv] section defines the number of general purpose
worker threads used by solidDB. For example:
[Srv]
Threads=9

The optimum number of threads depends on the number of processors the system
has installed. Usually it is most efficient to have between two and eight threads
per processor.

You must experiment to find the value that provides the best performance on your
hardware and operating system. A good formula to start with is:

threads= (2 x number of processors) + 1

Setting SQL trace level (SQL section)

The SQL Info facility lets you specify a tracing level on the SQL Parser and
Optimizer. For details on each level, see IBM solidDB SQL Guide.

The SQL Info facility is turned on by setting the Info parameter in the [SQL]
section to a non-zero value of the configuration file. The output is written to a file
named soltrace.out in the solidDB directory.

Use this parameter for troubleshooting purposes only as it slows down the server
performance significantly. This parameter is typically used for analyzing
performance for a specific single query or specific queries. Standard solidDB
monitoring is a better choice for generic application SQL database tracing.

Specifying network communication tracing (Com section)

The communication tracing facility is necessary, for instance, if the network
hardware is not functioning properly. By turning the tracing on, the
communication layer is capable of logging even the system specific errors and may
help in diagnosing the real problem in the network. For details, read “Network
trace facility” on page 144. The following parameters control the outputting of
network trace information.

3 Configuring solidDB 57
 Trace: If you change the Trace parameter default setting from No to Yes, solidDB
starts logging trace information about network messages for all the established
network connections to the default trace file or to the file specified in the
TraceFile parameter.

TraceFile: If the Trace parameter is set to Yes, then trace information about
network messages is written to a file specified by the TraceFile parameter. If no
file name is specified, the server uses the default value soltrace.out, which is
written to the current working directory of the server or client, depending on
which end the tracing is started at.

Most important client-side parameters

This section describes the most important solidDB client-side parameters and their
default settings.

Defining network names (Com section)

A client application uses a network name to specify which protocol to use when
communicating with the server, and which server to connect to.

Connect parameter: The Com.Connect parameter defines the default connect string
for a client to connect to when it communicates with a server. Since the client
should talk to the same network name as the server is listening to, the value of the
Com.Connect parameter on the client should match the value of the Com.Listen
parameter on the server.

The following connect line tells the client to communicate with the server by using
the TCP/IP protocol to talk to a computer named 'spiff' using server port number
'1313'.
[Com]
connect = tcpip spiff 1313

When an application program is using a solidDB ODBC Driver, the ODBC Data
Source Name can used instead of the Com.Connect parameter.

Important: The [HotStandby] and [Synchronizer] sections in the solid.ini file

also have Connect parameters. These parameters work independently from each
other; however, they use the same format for the connect string.

Format of the connect string: A default connect string can be defined with the
client-side Com.Connect configuration parameter. The connect string can also be
supplied, for example, at connection time or when configuring data sources with
an ODBC driver manager.

The same format of the connect string applies to the Com.Connect parameter as
well as to the connect string used by solidDB tools or ODBC applications.

The format of a connect string is the following:

protocol_name [options] [host_computer_name] server_name

where
v options can be any combination of the following:

58 IBM solidDB: Administrator Guide

Table 12. Connect string options

Option Description Protocol

-4 Specifies that client connects using IPv4 protocol only. TCP/IP
-6 Specifies that client connects using IPv6 protocol only. TCP/IP

In Windows environments, this option is mandatory if IPv6 protocol is used.

All
-z Enables data compression for this connection
-c milliseconds Specifies the login timeout (the default is operating-system-specific). A login request TCP/IP
fails after the specified time has elapsed.
Specifies the connection (or read) timeout. A network request fails when no response is TCP/IP
-r milliseconds received during the time specified. The value 0 (default) sets the timeout to infinite
(operating system default timeout applies).
-ofilename Turns on the Network trace facility and defines the name of the trace output file All

See Network trace facility in the IBM solidDB Administrator Guide for details.
-plevel Pings the server at the given level (0-5). All

Clients can always use the solidDB Ping facility at level 1 (0 is no operation/default).
Levels 2, 3, 4 or 5 may only be used if the server is set to use the Ping facility at least at
the same level.

See Ping facility in the IBM solidDB Administrator Guide for details.
-t Turns on the Network trace facility All

See Network trace facility in the IBM solidDB Administrator Guide for details.

v host_computer_name is needed with TCP/IP and Named Pipes protocols, if the

client and server are running on different machines.
v server_name depends on the communication protocol:
– In TCP/IP protocol, server_name is a service port number, such as '2315'.
– In other protocols, server_name is a name, such as 'soliddb' or 'chicago_office'.
For details on the syntax in different communication protocols, see
Communication protocols in the IBM solidDB Administrator Guide.

Note:
v The protocol_name and the server_name must match the ones that the server is
using in its network listening name.
v If given at the connection time, the connect string must be enclosed in double
quotation marks.
v All components of the connect string are case insensitive.

Examples
[Com]
Connect=tcp -z -c1000 1315
[Com]
Connect=nmpipe host22 SOLID
solsql "tcp localhost 1315"
solsql "tcp 192.168.255.1 1315"
rc = SQLConnect(hdbc, "upipe SOLID", (SWORD)SQL_NTS, "dba", 3, "dba", 3);
rc = SQLDriverConnect(hdbc,
(SQLHWND)NULL,
(SQLCHAR*)"DSN=tcp localhost 1964;UID=dba;PWD=dba",
38,
out_string,

3 Configuring solidDB 59
 255,
&out_length,
SQL_DRIVER_NOPROMPT);

Trace and TraceFile parameters: The client-side Com.Trace parameter controls

whether solidDB collects trace information about network messages for the
established network connection.

When Com.Trace is set to Yes, solidDB writes the trace log to the default trace file
(soltrace.out) in the current working directory or to the file specified with the
Com.TraceFile parameter.

Using solidDB command line options

When starting up solidDB, you can use command line options, for example, to
override certain parameter settings or invoke database operations such as database
conversion.

About this task

v A full list of the available command line options is available in section
Appendix C, “solidDB command line options,” on page 221. You can also view
the options with the command line option -h or -?, for example:
solid -h
v If the syntax of the command is incorrect, Usage information is displayed.
v The command line options are case sensitive.

Procedure

At your operating system command prompt, use the following syntax:

solid [option] [option] [...]

Example
solid -Udba -Pdba -x listen:"tcp 2315" -E -Sadmin

The above command starts a solidDB server and encrypts an existing database
where:
v -U = user name: admin
v -P = password: admin123
v -x listen = network listening name: tcp 2315
v -E = encrypts the database
v -S = encryption password: admin

Setting solidDB-specific environment variables

The solidDB-specific environment variables enable you to define default settings,
for example, for the location of solid.ini file, license files and trace files.

60 IBM solidDB: Administrator Guide

 About this task

The solidDB-specific environment variables are listed in the following table.

Table 13. solidDB environment variables
Environment
variable Purpose Example
SOLAPPINFO Identifies applications running in the same computer and under export SOLAPPINFO=testapp
the same username for the purposes of tracing and management

SOLAPPINFO is set on the client node. The ADMIN COMMAND

'userlist' returns the value of SOLAPPINFO on the server side.The
value of SOLAPPINFO must not contain blanks.
Tip: In JDBC environments, the SOLAPPINFO can be set with the
connection property solid_appinfo.

Alternatively, the following Java command line may be used to

pass the value of the environmental variable to the driver:
java -Dsolid_appinfo=%SOLAPPINFO% java_program_name
SOLIDDIR Defines the default directory for solid.ini and license files export SOLIDDIR=/home/
soliddb/settings/
SOLSMASTART Forces the start address space for the SMA server to the solidDB export
default SOLSMASTART=0x2c0000000000

The value depends on the operating system; see SOLSMASTART

default address spaces in the IBM solidDB Shared Memory Access and
Linked Library Access User Guide for more details.
SOLTRACE Turns on the Network trace facility, overriding the Com.Trace export SOLTRACE=yes
setting in the solid.ini file
SOLTRACEFILE Defines the name and location of the file where trace information export SOLTRACEFILE=/home/
is output, overriding the Com.TraceFile setting in the solid.ini soliddb/settings/trace.out
file

Defining the SOLTRACEFILE environment variable automatically

turns on the Network trace facility.

Procedure
v In Linux and UNIX environments, use following command:
export <environment_variable>=<value>
v In Windows environments, use following command:
set <environment_variable>=<value>

3 Configuring solidDB 61
62 IBM solidDB: Administrator Guide
4 Monitoring solidDB
The following sections describe the methods used for querying the status of a
solidDB database.

Viewing error messages and log files

By default, solidDB outputs errors and messages in the solmsg.out and
solerror.out log files in the solidDB working directory. To view the descriptions
of single or all error messages, use ADMIN COMMAND ’errorcode’.

Controlling message log output

If you want to process the message files programmatically, you can enable the
messages to be output with an 8-character unique code. You can also disable the
generation of message log files.

solidDB maintains the following message log files:

v solmsg.out – log file for normal informational events, such as connects,
disconnects, checkpoints, backups, failed logins and so on
v solerror.out – log file for fatal errors, typically causing the server to crash

Additionally, solidDB can also produce trace files (soltrace.out) for

troubleshooting purposes.

You can view the message log files with a text editor.

The message log file size is controlled with the Srv.MessageLogSize parameter.
When the maximum size of the message log file is reached, the current solxxx.out
file is renamed to solxxx.bak, and a new solxxx.out file is started. To avoid
overwriting the contents of the backup solxxx.bak message log the next time the
maximum size of the message log file is reached, use the Srv.KeepAllOutFiles
parameter to enable the log files to be named incrementally.

Enabling message codes in message logs

Each error and status message is identified with an 8-character unique code. If the
message files are processed programmatically, it is easier to parse them if the
message codes are included. To enable the message code output, set the
Srv.PrintMsgCode to yes (default is no).

Disabling message log generation

To disable the generation of the solmsg.out and the solerror.out log files, set the
Srv.DisableOutput parameter to yes (default is no).

Important: Disabling the generation of log files makes it difficult to diagnose

problems. Turning off message logging will increase performance and reduce disk
space usage; however, in most cases the improvement is minimal. This option is
useful only in unusual situations, such as when I/O is "expensive" (as it is in some
systems that use FLASH memory), or in systems where data storage space is
extremely limited and the message log file accumulates indefinitely without being
deleted.

63
 Viewing error message descriptions with ADMIN COMMAND
'errorcode'
Each error and status message is identified with a unique number that you can use
with ADMIN COMMAND ’errorcode’ to view the error description.

The command ADMIN COMMAND ’errorcode <error_number>’ displays the

description of the given error message.

For example:
ADMIN COMMAND ’errorcode 14706’;
RC TEXT
-- ----
0 Code: SRV_ERR_HSBINVALIDREADTHREADMODE (14706)
0 Class: Server
0 Type: Error
0 Text: Invalid read thread mode for HotStandby, only mode 2 is supported.
4 rows fetched.

The command ADMIN COMMAND ’errorcode all’ displays the descriptions of all
error messages in a Comma Separate Value (CSV) format.

The error codes and their descriptions are also available in Appendix E, “Error
codes,” on page 227.

Using trace files

The trace files (soltrace.out) are needed primarily for troubleshooting of
exceptional events.

Monitoring the trace files is not necessary for everyday operation of the server. For
more details about the trace files and how to use them, see “Network trace
facility” on page 144.

Tracing failed login attempts

When login fails, the information about the attempt is recorded for security
reasons.

Failed attempt always

v raises a SYS_EVENT_ILL_LOGIN event, and
v prints message to both solmsg.out and solerror.out.

Messages include the IP address and the username of the attempt, for instance. The
syntax of the message is as follows:
timestamp [message code] User username tried to
connect from {hostname | unnamed host} with an
illegal username or password. [SOLAPPINFO is solappinfo value.]

Example:
Thu May 12 17:55:17 2005
12.05 17:55:17 User ’FOO’ tried to connect
from localhost.localdomain (127.0.0.1)
with an illegal username or password.

Note: The message code is only included if message code printing is enabled
(Srv.PrintMsgCode=yes) in solid.ini.

64 IBM solidDB: Administrator Guide

 Note: The SOLAPPINFO part is only included if the corresponding environment
variable is set at the client computer.

Checking solidDB version

Procedure

To check the version and build of solidDB:

v Issue the following command:
ADMIN COMMAND ’version’
or
v Check the version in the solmsg.out file.
The version information is added to the solmsg.out file every time the server is
started.

Checking overall database status

The general server status may be retrieved by using the following command in
solidDB SQL Editor (solsql):
admin command ’status’;
RC TEXT
-- ----
0 IBM solidDB started at 2009-08-13 12:48:24
0 Current directory is C:\solidsw\solid64\eval_kit\standalone
0 Using configuration file C:\solidsw\solid64\eval_kit\standalone\solid.ini
0 Memory statistics:
0 39269 kilobytes
0 Process size statistics:
0 Resident set size: 16312 kilobytes
0 Virtual size: 43040 kilobytes
0 Transaction count statistics:
0 Commit Abort Rollback Total Read-only Trxbuf Active Validate
0 114 0 1 115 237 0 1 0
0 Cache count statistics:
0 Hit rate Find Read Write
0 100.0 28809 0 56
0 Database statistics:
0 Index writes 3623 After last merge 0
0 Log writes 2277 After last cp 0
0 Active searches 0 Average 1
0 Database size 8064 kilobytes
0 Log size 16 kilobytes
0 User count statistics:
0 Current Maximum Total
0 1 1 1

The result set fields are described below:

v Memory statistics show the amount of memory solidDB has allocated from the
operating system. This number does not include the size of the executable itself.
v Transaction count statistics show the number of different transaction operations
since startup.
v Cache count statistics show cache hit rate and number of cache operations since
startup. Cache hit rate usually should be above 95 percent. If it is below 95
percent, consider increasing the cache size.
v Database statistics show a number of the most important database operations
since startup. The Index writes - After last merge is an important figure here.
It reveals the size of the multiversioning storage tree ofsolidDB, known as the
"Bonsai Tree." The smaller this value is, the better the server performance. A

4 Monitoring solidDB 65
 large value indicates that there is a long-running transaction active in the engine.
Note that an excessively large Bonsai Tree causes performance degradation. For
details on reducing Bonsai tree size, read “Reducing Bonsai Tree size by
committing transactions” on page 134.
v User count statistics shows the current and the maximum number of concurrent
users.

Obtaining currently connected users

You can also obtain a listing of connected users by entering the following
command in solidDB SQL Editor (solsql):

ADMIN COMMAND 'userlist';

The command provides the following kind of result set:

RC TEXT
-- ----
0 User name: User id: Type: Machine id: Login time:
0 DBA 1 SQL Local 27.05 16:13:22

Throwing out a connected solidDB user

To disconnect a single user from the server, enter the following command in
solidDB SQL Editor (solsql):
ADMIN COMMAND ’throwout user_id’;

Note that this command throws out user connections; it does not break the
connection between a HotStandby Primary and HotStandby Secondary server.

Querying the status of the most recent backup

To obtain a status of the most recently run local backup, enter the following
command in solsql:

ADMIN COMMAND 'status backup';

Obtaining the status of the most recently made network backup, enter the
command:

ADMIN COMMAND 'status netbackup"

If the last backup is successful, the result set looks as follows:

RC TEXT
-- ----
0 SUCCESS

If the latest backup has failed, then the RC column returns an error code. Return
code 14003 with text "ACTIVE" means that the backup is currently running.

Producing status reports

The ADMIN COMMAND ’report’ command produces a report that contains information
about the server, users, and database operations. The report also includes the
configuration file (solid.ini) settings and a list of the performance counters. IBM
Support may ask you to produce the report for troubleshooting purposes.

66 IBM solidDB: Administrator Guide

 To create a report about the current status of solidDB, issue the following
command:
ADMIN COMMAND ’report report_filename’

In general, IBM Software Support and development teams use the reports for
troubleshooting. IBM Support may ask you to produce the report for
troubleshooting purposes. You can also generate the report to gain information
about a problem that you are investigating, but its use might be limited without
knowledge of the solidDB source code.

Performance counters (perfmon)

The solidDB performance counters (perfmons or pmons) provide information about
various database operations and performance. The performance counters are
controlled with ADMIN COMMAND ’perfmon’.

There are two commands for viewing and collecting performance information:
v ADMIN COMMAND ’perfmon’ returns performance information for the past few
minutes at approximately one minute intervals.
v ADMIN COMMAND ’perfmon diff’ collects performance information at given
intervals and outputs it into a file in a comma-separated value format.

ADMIN COMMAND 'perfmon'

The ADMIN COMMAND ’perfmon’ command returns a result set of all solidDB
performance counters. For troubleshooting purposes, you should execute ADMIN
COMMAND ’perfmon’ during problematic situation or immediately after.

Example output:
ADMIN COMMAND ’perfmon’;
RC TEXT
-- ----
0 Performance statistics:
0 Time (sec) 30 42 44 30 34 32 32 33 Total
0 File open : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 File read : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 File write : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 File append : 0.0 0.0 0.1 0.0 0.0 0.0 0.1 0.0 0.0
0 File flush : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 File lock : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache find : 0.0 0.0 0.5 0.2 0.2 6.1 0.9 0.0 0.4
0 Cache read : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache write : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache prefetch : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache prefetch wait : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache preflush : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
0 Cache LRU write : 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0
...

Each column represents a snapshot of the average performance information for a

period of approximately one minute. The first row Time (sec) shows the point in
time when the snapshot is taken. The Total column shows average information
since solidDB was started.

Most values are shown as the average number of events per second. Counters that
cannot be expressed as events per second (for example, database size) are
expressed in absolute values.

ADMIN COMMAND 'perfmon' options

The ADMIN COMMAND ’perfmon’ command syntax also has options that allow you to
specify output options. For example, you can restrict the output by providing a list
of prefixes of counter names ADMIN COMMAND ’perfmon name_prefix_list’.

Example:

4 Monitoring solidDB 67
 ADMIN COMMAND ’perfmon db’ returns all pmon counters starting with 'db':
ADMIN COMMAND ’perfmon db’;
RC TEXT
-- ----
0 Performance statistics:
0 Time (sec) 19 Total
0 DBE insert : 0.0 0.0
0 DBE delete : 0.0 0.0
0 DBE update : 0.0 0.0
0 DBE fetch : 0.0 41.2
0 DBE dd operation : 0 0
0 Db size : 8064 8064
0 Db free size : 7440 7440
0 DB actiongate lock time, latest: 0 0
0 DB actiongate lock time, sum : 0 0
0 DB actiongate lock count : 0 0
12 rows fetched.

For more information about the ADMIN COMMAND ’perfmon’ options, see “ADMIN
COMMAND” on page 309.

ADMIN COMMAND 'perfmon diff' - producing a continuous

performance monitoring report
The command ADMIN COMMAND ’perfmon diff’ allows you to start and stop
producing continuous performance counter reports to a file.

To start collecting performance counter information, issue the following command:

ADMIN COMMAND ’perfmon diff start filename interval’

where
v filename is the name of the output file. The performance data is output in
comma-separated value format; the first row contains the counter names, and
each subsequent row contains the performance data per each sampling time.
The default file name is pmondiff.out.
v interval is the interval in milliseconds at which performance data is collected.
The default interval is 1000 milliseconds.

To stop the collection of performance data, issue the following command.

ADMIN COMMAND ’pmon diff stop’

Example

To start logging performance counters into the counter_log.csv file with 2 second
interval, issue the following command:
ADMIN COMMAND ’pmon diff start counter_log.csv 2000’

Full list of perfmon counters

The counters are listed in the order they appear in the ADMIN COMMAND ’pmon’
output.
Table 14. Perfmon counters

Perfmon Variable Description

Time (sec) In onetime report: length of the measurement time interval, in

seconds. The latest interval is on the right side of the table.

68 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

TimeMs In a differential report: measurement time interval, in

milliseconds. The oldest interval is in the first row of the table.

File open File open calls/sec

File read File read calls/sec

File write File write calls/sec

File append File append calls/sec

File flush File flush calls/sec

File lock File lock calls/sec

Cache find Cache fetches/sec

Cache read Cache misses/sec

Cache write Cache page flushes/sec

Cache prefetch Cache prefetched pages/sec

Cache prefetch wait Cache waits for prefetched pages/sec

Cache preflush Preflushing cache pages/sec

Cache LRU write A write from cache is done when performing an LRU
replacement. This indicates that the client thread must write one
block to disk before reading a new block from the disk because
there has not been a free disk block available. A very high value
can indicate just high I/O load, or it can indicate that I/O
preflusher values are not optimal.

Cache slot wait This counter indicates that there is concurrent access to the same
block and one thread must wait for the other. Depending on the
cache configuration, it can also indicate that the mutex count for
the cache is not optimal and there are false conflicts. The default
mutex count does not cause false conflicts here.
Cache slot replace Database cache slot is replaced and old slot is removed.
Cache write storage leaf Database cache has written a storage tree leaf page to disk.
Cache write storage index Database cache has written a storage tree index page to disk.
Cache write bonsai leaf Database cache has written a Bonsai-tree leaf page to disk.
Cache write bonsai index Database cache has written a Bonsai-tree index page to disk.
Cache preflush bytes Number of bytes written by preflusher before log file is flushed.
The counter is reset at each flush.
Cache preflush flush Number of preflush calls/sec before log file is flushed.

RPC messages Total number of sent messages/sec

RPC read Total number of read messages/s

RPC write Total number of write messages/sec

4 Monitoring solidDB 69
Table 14. Perfmon counters (continued)

Perfmon Variable Description

RPC uncompressed When RPC compression enabled, number of bytes/sec

RPC compressed When RPC compression enabled, number of compressed byte/s

RPC connected Number of client connect requests
RPC disconnected Number of client disconnect requests

Com sel empty TCP socket select nil returns/sec

Com sel found TCP socket select successes/sec

SQL prepare SQL prepare statements/sec

SQL execute SQL execute statements/sec

SQL execute simple Number of simple SQL statement executes

A simple SQL statement is a statement that accesses a single

table and does not contain joins, subqueries, function calls,
ORDER BY or GROUP BY constructions, and all WHERE
conditions are combined with an AND logical operator.
SQL execute complex Number of complex SQL executes

SQL fetch SQL fetch statements/sec

DBE insert Table engine row inserts/sec

DBE delete Table engine row deletes /sec

DBE update Table engine row updates /sec

DBE fetch Table engine row fetches /sec

DBE fetch M-table Number of rows fetched from in-memory tables
DBE fetch D-table Number of rows fetched from disk-based tables
DBE dd operation Server has executed SQL data dictionary operation.
Proc compile Number of procedure compilations

Proc exec Procedure executions/sec

Proc SQL prepare Number of SQL prepare calls from a procedure code
Proc SQL execute Number of SQL execute calls from a procedure code
Proc SQL fetch Number of SQL fetch calls from a procedure code
Trig compile Number of trigger compilations

Trig exec Trigger executions/sec

Trig SQL prepare Number of SQL prepare calls from a trigger code
Trig SQL execute Number of SQL execute calls from a trigger code
Trig SQL fetch Number of SQL fetch calls from a trigger code

SA fetch SA-level row fetches/sec

SA insert SA-level row inserts/sec

SA delete SA-level row deletes/sec

70 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

SA update SA-level row updates/sec

Trans commit Committed transactions/sec

Trans abort Aborted transactions/sec

Trans rollback Rolled back transactions/sec

Trans readonly Read-only transactions/sec

Trans buf Current transaction buffer size

Trans buf cleanup Cumulative number of cleanup operations since startup

Trans buf added Cumulative number of transactions added since startup

Trans buf removed Cumulative number of transactions removed since startup

Trans validate Current number of active commit-time validations

Trans active Current number of active transactions

Trans read level This counter indicates the current transaction read level. This
counter value increases all the time. Because the counter value is
32-bit variable, it can have a negative value, but still logically
the value is increasing. If the value stays the same for a long
time with concurrent write transactions, it indicates that a long
transaction is blocking the read level and can cause merge
blocking and an increase in the Bonsai tree size.

Ind write Index writes/sec

Ind nomrg write number of nonmerged rows (committed and uncommitted)

Search active Table engine-level active searches.

Search replan Number of search replans

A search is replanned when table content is significantly

changed. Replan is done to make sure that search plans are
optimal for the changed table content.

Db size Total database size on disk, in KB

Db free size Free space in the database (page level), in KB

Mem size Total size of dynamically allocated memory, in KB

Merge quickstep Quick merge steps/sec

Merge step Full merge steps/sec

Merge step (purge) Node split-inflicted merge keys/sec (if enabled)

Merge step (user) User thread-activated merge row/sec

4 Monitoring solidDB 71
Table 14. Perfmon counters (continued)

Perfmon Variable Description

Merge oper Lower-level merge operations/sec

Merge cleanup Transaction buffer cleanup calls/sec (if split purge enabled)

Merge active Yes/no (1/0)

Merge nomrg write Current number of index entries waiting for merge

Merge file write Merge-inflicted file writes/sec

Merge file read Merge-inflicted file reads/sec

Merge level Current merge level (read level of the oldest active transaction)

Backup step Database backup steps/sec (also in netbackup and netcopy)

Backup active Yes/no (1/0)

Checkpoint active Checkpoint status

Value 0 means checkpoint is not active. Values 1 and above

means checkpoint is active; values above 1 indicate the progress
of the checkpoint.

Checkpoint count Checkpoint serial number from startup

Checkpoint file write Checkpoint file writes/sec

Checkpoint file read Checkpoint file reads/sec

Est read samples Estimator sample refresh call/s

Sorter start sort Number of external sorts started
Sorter add row Number of rows added to external sorter
Sorter fetch row Number of rows read from external sorter
Sorter open file Number of files opened/sec in external sorter
Sorter activecnt Number of currently active external sorts
Sorter waitcnt Number of external sort requests waiting to be started.
Sorter wait Number of external sort requests waits/sec.
Sorter filecnt Number of temporary files currently used for external sorting.
Sorter memblockcnt Number of memory blocks currently used for external sorting.
Sorter failed Number of time external sort has failed to start.

Sync repl msg forw Replica: forwarded messages/sec

Sync repl msg getr Replica: received message replies/sec

Sync repl msg exec Replica: executed messages/sec

Sync mast msg read Master: message reads/sec

Sync mast msg exec Master: message execs/sec

72 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

Sync mast msg write Master: message writes/sec

Sync mast subs Master: refreshes/sec

Log write Log record writes/sec

Log file write Log block writes/sec

Log file write bytes Number of log block writes in bytes before log file is flushed

Log nocp write Pending log records since last checkpoint

Log size Total size of log file, in KB

Log flush (L) Logical log flushes/sec (for example, commit)

Log flush (P) Physical log flushes/sec

Log grpcommwkup Group commit wakeups/sec

Log flush full Log page full flushes/sec

Log wait flush Current number of user threads waiting for log operation

Log writeq full rec Log writes while log write queue full (in number of records)
Log writeq full byt (byte size) Log writes while log write queue full (in bytes)
Log writeq records Number of records in current log writer queue.
Log writeq bytes Number of bytes in log writer queue.
Log writeq pending bytes Number of bytes for the next log writer queue flush.
Log availq items Number of records added to available items queue
Log writeq add Number of records added to log writer queue.
Log writeq write Number of records written from log writer queue to log file.
Log writeq item count Number of write queue items in the system

HSB operation count Primary/Secondary: transferred log record/sec

HSB commit count Primary: commit record/sec

HSB packet count Primary: messages/sec

HSB flush count Primary/Secondary: message flushes/sec

HSB cached bytes Primary/Secondary: current size memory based log buffer, in
bytes

HSB cached ops Primary/Secondary: current size of the memory-based log

buffer, in operations (log records)

HSB flusher bytes Number of bytes of the HSB log in the send queue to the
Secondary

HSB notsent bytes Number of bytes in the HSB log that has been accumulated (for
example, during a catchup) and not sent to the Secondary yet

4 Monitoring solidDB 73
Table 14. Perfmon counters (continued)

Perfmon Variable Description

HSB grouped acks Secondary: current number of ack groups (physical acks)

HSB state Name of the current HSB state

HSB wait cpmes Yes/no (1/0) Primary: waiting for checkpoint ack from the
Secondary

HSB secondary queues Secondary: current number of queues pending processing

HSB log reqcount HSB log write requests/sec

HSB log waitct HSB log waits-for-write requests/sec

HSB log freespc HSB: number of log operations there is space for in the protocol
window

HSB catchup reqcnt HSB log write requests/sec, for catchup

HSB catchup waitcnt HSB log waits-for-write requests/sec, for catchup

HSB catchup freespc HSB: number of log operations there is space for in the protocol
window, for catchup

HSB alone freespc Primary: in Primary alone, bytes there is room for in the
transaction log
Tabcur create Number of internal table cursor calls
Tabcur reset full Number of full constraint reset calls in table cursor
Tabcur reset smpl Number of simple constraint reset calls in table cursor
Tabcur estimate Number of cost estimate calls in table cursor
Tabcur table scan Number of table scans executed in SQL statements.

A high number of table scans can mean that SQL statements are
not executed optimally or some index definitions are missing
from tables.
Tabcur index access Number of index accesses executed in SQL statements

A high number of index accesses in comparison to number of

table scans usually means that SQL statements are properly
optimized and correct indexes are defined for tables.

Thread count Current number of threads

Trans wait readlvl Waits/sec for read level at commit

Trans wait readlvl is a counter that is incremented every time a

transaction needs to wait for global read level to become
sufficiently high so that the transaction changes become visible
(to others) at commit. In regular load situations, this is
instantaneous and no wait is needed. In high load situations, a
short wait loop might be required.

The value of this counter is never decremented. Minor

increments (single digits) during 30 second pmon interval are
only an indication of a short high-load situation in the server.

Lock ok Successful lock requests/sec

74 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

Lock timeout Lock timeouts/sec

Lock deadlock Deadlocks/s

Lock deadlock check Number of lock manager deadlock checks done.
Lock deadlock loop Number of lock manager deadlock check loops done.

Lock wait Lock waits/sec

Lock count Number of locks in lock manager.
Dropped search buffers Number of search buffers removed from disk based table
searches because too many buffers were used.
Number of search buffers Current number of search buffers used for disk based tables.
NOCHECK operations Internal number of nocheck operations performed.

MME cur num of locks Current no. MME locks

MME max num of locks Peak number of MME locks (since startup)

MME cur num of lock chains Current no. MME hash buckets

MME max num of lock chains Peak no. MME hash buckets (since startup)

MME longest lock chain path MME: longest hash overflow path

MME mem used by tuples MME memory allocated to tuples in kilobytes

MME mem used by indexes MME memory allocated to indexes in kilobytes

MME mem used by page structs MME memory allocated to the shadow structures in kilobytes
MME page splits Number of MME page splits
MME page joins Number of MME page joins
MME unnec mutexed searches Number of MME rows fetched while unnecessarily in exclusive
mode
MME nonmatched (RO) Number of MME rows that did not match search criteria fetched
in shared mode
MME nonmatched (EXCL) Number of MME rows that did not match search criteria fetched
in exclusive mode
MME inserts with x gate Number of inserts done in exclusive mode. Insert switches from
shared mode to exclusive mode for example, when the insert
causes index node split.
MME deletes with x gate Number of MME deletes performed in exclusive mode
MME hotspot protection Number of times an MME search enters exclusive mode to
access a hotspot
Number of keys inserted to MME indexes, includes keys
MME index key inserts inserted during a database recovery (not accurate1)
MME index key deletes Number of keys deleted from MME indexes. (not accurate1)
MME bnode resizes Number of times a MME bnode has been resized
Number of times optimistic mutexing in vtrie has collided (not
MME vtrie mutex collisions accurate1, congestion2)
Number of times a version check in vtrie has collided (not
MME vtrie version colls accurate1, congestion2)

4 Monitoring solidDB 75
Table 14. Perfmon counters (continued)

Perfmon Variable Description

Number of times a search path in vtrie has been vertically split
MME vtrie vertical splits by a key insert (not accurate1)
Number of times a new branch has been added to a vtrie node
(not accurate1)

The approximate branching factor of the vtrie can be calculated

as

(MME vtrie new branches - MME vtrie branch deletes) / (MME

vtrie vertical splits - MME vtrie vertical joins) + 2.

This branching factor is only for the vtrie part of the index, the
MME vtrie new branches bnode leaf level branching factor cannot be estimated.
Number of times a key delete from vtrie has caused a node on
MME vtrie vertical joins the search path to be deleted (not accurate1)
Number of times a key delete from vtrie has caused a branch to
MME vtrie branch deletes be removed from a vtrie node (not accurate1)
Number of times a vtrie insert has been retried because of a
MME vtrie insert retries collision (not accurate1, congestion2)
Number of times a vtrie delete has been retried because of a
MME vtrie delete retries collision (not accurate1, congestion2)
Number of times bnode accesses have caused a mutex collision
MME bnode mutex collisions (not accurate1, congestion2)
Number of times bnode accesses have failed because of a
MME bnode version colls version collision (not accurate1, congestion2)

Posted events queue Number of posted events that has not been consummated by
the subscribers

Index search both Search is done from both the Bonsai tree and the storage tree

Index search storage Index search is done from storage tree only

B-tree node search keys DBE B tree searches/sec

B-tree node search mismatch A search was done by using the mismatch index search
structure within a B-tree node. Mismatch index is a search
structure where an array of mismatch index positions is built
within a B-tree node. This mismatch index is a compact and
linear data structure that is used to perform a fast scan over
compressed key information to find a key position within the
B-tree node. It attempts to optimize the search by using fast
access in the processor cache row by packing relevant search
information in one to three processor cache pages.

B-tree node build mismatch A new mismatch index search structure is built within a B-tree
node. Mismatch index is a search structure where an array of
mismatch index positions is built within a B-tree node. This
mismatch index is a compact and linear data structure that is
used to perform a fast scan over compressed key information to
find a key position within the B-tree node. It attempts to
optimize the search by using fast access in the processor cache
row by packing relevant search information in one to three
processor cache pages.

B-tree node split DBE B tree node splits/sec

76 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

B-tree node relocate A B-tree node is relocated. This happens when a block that
belongs to a previous checkpoint is changed for the first time.
Typically, this value is highest immediately after a checkpoint.

B-tree node delete empty An empty B-tree node is deleted.

B-tree node exclusive Exclusive access to the B-tree is used. This can happen, for
example, in a node split case such as when the tree root is split.

B-tree key read Normal key value is read from the B-tree.

B-tree key read delete Delete mark is read from the B-tree.

B-tree key read oldversion Old row version is read from the B-tree.

B-tree key read abort A row from an aborted transaction is read from the B-tree. This
includes all transactions that were not successfully completed.
B-tree storage leaf len Average length for storage tree leaf node.
B-tree storage index len Average length for storage tree index node.
B-tree bonsai leaf len Average length for Bonsai-tree leaf node.
B-tree bonsai index len Average length for Bonsai-tree index node.
Bonsai-tree height Current Bonsai tree height in levels.
B-tree lock node Number of B-tree node lock calls.
B-tree lock tree Number of whole B-tree lock calls.
B-tree lock full path Number of B-tree full node path lock calls.
B-tree lock partial path Number of B-tree partial node path lock calls.
B-tree get no lock Number of B-tree no lock calls.
B-tree get shared lock Number of B-tree shared lock calls.
Pessimistic gate wait Number of waits for pessimistic disk based table gate.
Merge gate wait Number of waits for merge gate.
Storage gate wait Number of waits for storage tree gate.
Bonsai Gate wait Number of waits for Bonsai-tree gate.
Action gate wait Number of action gait waits
MME pages gate wait Number of gate waits when accessing pages in MME storage
MME index gate wait Number of gate waits when accessing MME index

Gate wait There is a wait in a gate object. A gate object is an internal

synchronization mechanism.

Logreader spm reqcount Logreader log space request/sec

Logreader spm waitct Logreader log space waits/sec

Logreader spm freespc min Minimum value of log reader space manager free space (number
of operations that can be buffered).

Each log reader cursor has its own free space counter; if there
are multiple open log reader cursors, the value is the minimum
value of free space of all open cursors. If the free space of any
log reader cursor is zero, the value of this counter is zero and
transaction throttling (slowdown) is enacted.

4 Monitoring solidDB 77
Table 14. Perfmon counters (continued)

Perfmon Variable Description

Logreader spm freespc max Maximum value of log reader space manager free space
(number of operations that can be buffered). If there are
multiple open log reader cursors, the value is the maximum
value of free space of all open cursors.

Logreader logdata queue len Logreader: number of log record blocks waiting for processing.

Logreader record queue len Logreader: number of log records waiting for propagation.

Logreader stmt queue len Logreader: number of statements waiting for statement
commit/rollback.

Logreader open cursors Logreader: number of open cursors to SYS_LOG.

Logreader records processed Logreader: number of log records processed/sec.

Logreader records sent Logreader: number of log records sent for propagation/sec.

Logreader commits processed Logreader: number of commits processed/sec.

Logreader commits sent Logreader: number of commits sent to the propagator/sec.

Logreader messages sent Logreader: number of wakeup messages to open cursors/sec.

Logreader catchup state Logreader catchup state.

Logreader catchup queue len Logreader: number of log records in catchup queue.

Logreader catchup queue size Logreader: size of the catchup queue, in bytes.

Logreader pending queue len Logreader: number of pending log records in the in-memory log
buffer.

Logreader memcache queue len Logreader: length of the in-memory buffer queue, in operations.

Logreader batch queue len Logreader: current number of operations queued for the next
batch.
Logreader: a full transaction back was flushed from logreader.
Logreader flush batch full
Logreader flush batch force Logreader: a non-full transaction batch was flushed from
logreader.
Number of transactions applied into solidDB by InfoSphere®
TS applied transactions CDC instance when solidDB is a target datastore.
Passthrough open connections Number of SQL passthrough connections to back-end
Passthrough open statements Number of prepared statements to back-end
Passthrough reads Number of executed read-type statements that return rows (for
example, SELECT statements)
Passthrough non reads Number of executed write-type statements that return rows (for
example, INSERT statements)
Passthrough commits Number of committed statements
Passthrough rollbacks Number of rollback statements

78 IBM solidDB: Administrator Guide

Table 14. Perfmon counters (continued)

Perfmon Variable Description

Passthrough result cnv Number of fetched (read) rows for which conversion between
back-end and solidDB data types have been performed. For
example, conversion is needed if the data type in back-end is
CHAR(5) and VARCHAR in solidDB.
Passthrough param cnv Number of statements for which conversion between statement
parameters have been performed
Passthrough failures Number of statements that could not be prepared in back-end
Passthrough reprepared Number of statements that have been reprepared because
write-type statements other that INSERT, UPDATE, and
DELETE have been executed in the back-end. Repreparation is
needed in such cases to ensure that the table definitions have
not been changed, which in turn would cause errors with the
prepared statements.
Passthrough complex by num non indexed constraints Number of statements that are passed through based on the
parameter Passthrough.ComplexNumNonindexedConstr
Passthrough complex by num ordered rows Number of statements that are passed through based on the
parameter Passthrough.ComplexNumOrderedRows
Passthrough complex by num tables Number of statements that are passed through based on the
parameter Passthrough.ComplexNumTables
XA trans start Number of XA transactions that have been started
XA trans end Number of XA transactions that have ended
XA trans resume Number of XA transactions that have been resumed
XA trans prepare Number of XA transactions that have been prepared
XA trans commit Number of XA transactions that have been committed
XA trans rollback Number of XA transactions that have been rolled back
XA trans forget Number of XA transactions that have been forgotten
XA trans recover Number of XA transactions that have been recovered
XA trans active Number of XA transactions that are active at the time of the
query
SMA connection count Number of SMA connections
SMA shared memory used Amount of shared memory used
DB actiongate lock time, latest Amount of time in milliseconds the last lock lasted
DB actiongate lock time, sum Amount of time in milliseconds all locks have lasted since
server startup
DB actiongate lock count Number of locks since server startup
Time sec Printout time of this pmon in seconds

1
Counters marked as not accurate are not accurate because they are not mutex
protected for performance reasons.
2
In counters marked as congestion, large increases imply that there is congestion in
parallel access when several threads are updating same parts of the database at the
same time.

4 Monitoring solidDB 79
80 IBM solidDB: Administrator Guide
5 Managing network connections
solidDB provides simultaneous support for multiple network protocols and
connection types. Both the database server and the client applications can connect
simultaneously to multiple sites using multiple different network protocols.

Note: Some operating systems may limit the number of concurrent users to a
single solidDB server process.

Communication between client and server

The database server and the client transfer information between each other through
the computer's network communication protocol. The connection between the
server and the client is defined with a network name. The server listens to the
network using certain protocols and server names or port numbers. Client
processes must use a matching connect string when connecting to the server.

At the server side, the network name is defined as a network listening name that
identifies the server in the network. When a database server process is started, it
publishes at least one network listening name. The server starts to listen to the
network using the given network listening name. The network listening name is
defined with the Com.Listen configuration parameter.

At the client side, the network name is defined as a connect string that the client
process uses to specify which server it will connect to. To establish a connection
from a client to a server, the client has to know the network listening name of the
server and in some cases, also the location of the server in the network. A default
connect string can be defined with the client-side Com.Connect configuration
parameter. The connect string can also be supplied, for example, at connection time
or when configuring data sources with an ODBC driver manager.

The network name consists of a communication protocol, a possible set of options,

and a server name, which can be, depending on the protocol, a name or a port
number, for example, tcpip 1315 or nmpipe solid1.

Tip:
v Because the network listening name and the connect string must match, the
generic term network name is used for referring to either one as it is the string
that defines the connection between the server and the client.
v In connection with the ODBC API, the network name can also be called
servername (following the ServerName argument in the SQLConnect() function).

Network listening names (Com.Listen)

The network name of a server is a network listening name that consists of a
communication protocol and a server name (port number). This combination identifies
the server in the network. The network name is defined with the Com.Listen
parameter in the solid.ini file.

The syntax of the Com.Listen parameter and the network listening name is the
following:

81
 [Com]
Listen = network_listening_name, network_listening_name, ...

where
network_listening_name = protocol_name [options] server_name | none
v [options] can be any combination of the following:
Table 15. Network listening name options

Option Description Protocol

-4 Specifies that solidDB listens to IPv4 protocol only. TCP/IP
-6 Specifies that solidDB listens to IPv6 protocol only. TCP/IP

In Windows environments, this option is mandatory if IPv6 protocol is used.

-iip_address|host_name solidDB listens only to the specified IP address or host name. TCP/IP

This is useful in multi-homed systems that support many TCP/IP interfaces

or have multiple ip-addresses.

Example:
[Com]
Listen = tcp -i127.0.0.1 1313

A server with the above setting accepts connection requests only from inside
the same machine, either referred by IP address 127.0.0.1 or with the name
'localhost', if the DNS is correctly configured:

DNS entries can be used instead of IP addresses, for example:

[com]
Listen = tcp -ilocalhost 1313
-ofilename Turns on the Network trace facility and defines the name of the trace output All
file

See “Network trace facility” on page 144 for details.

-plevel Sets the highest level at which the clients can use the solidDB Ping facility. All

For example, if the server side is set to -p3, clients applications can run the
Ping facility at levels 1, 2, and 3, but not at 4 and 5.

See “Ping facility” on page 145 for details.

-t Turns on the Network trace facility All

See “Network trace facility” on page 144 for details.

v server_name depends on the communication protocol:

– In TCP/IP protocol, server_name is a service port number, such as '2315'.
– In other protocols, server_name is a name, such as 'soliddb' or 'chicago_office'.
For details on the syntax in different communication protocols, see
“Communication protocols” on page 87.
v none means that all listening ports are disabled.
The value none cannot be set with ADMIN COMMAND 'par'.

Note:
v A server may use an unlimited number of network names.
v All components of network names are case insensitive.
v When a database server process is started, it publishes the network names that it
starts to listen to. This information is also written to the solmsg.out file.

82 IBM solidDB: Administrator Guide

 v Network names must be unique within one host computer. For example, you
cannot run two database servers that are both listening to the same TCP/IP port
in one host. However, it is possible that the same port number is in use in
different hosts.

Example of solid.ini entry:

[Com]
Listen = tcpip 1313, nmpipe soliddb

The example contains two network names which are separated by a comma. The
first one uses the protocol TCP/IP and the service port 1313; the other one uses the
Named Pipes protocol with the name 'soliddb'. The 'tcpip' and 'nmpipe' are
communication protocols, while '1313' and 'soliddb' are server names.

Factory value for a network name

If the Listen parameter is not set in the solid.ini file or if the value is empty,
solidDB listens to the following network names by default:
Table 16. Com.Listen factory values
Platform Com.Listen factory values
Windows NmPipe SOLID

ShMem SOLID

TCP/IP 1964
Linux and UNIX UPipe SOLID

TCP/IP 1964

Viewing supported protocols for the server

All protocols are not supported in all environments and operating systems.

To view supported protocols for your server, use the following command:
ADMIN COMMAND ’protocols’

A list of all available communication protocols is displayed. The command

provides the following kind of result set, which contains one row for each
supported communication protocol:
admin command ’protocols’;
RC TEXT
-- ----
0 NmPipe np
0 TCP/IP tc
2 rows fetched.

Viewing network names for the server

You can view the network names for the server in the following ways:
v View the Listen parameter in the [Com] section in the solid.ini file.
v Use the following ADMIN COMMAND:
ADMIN COMMAND ’parameter -r com.listen’;
A list of all the currently set network names for the server is displayed.
Example:

5 Managing network connections 83

 ADMIN COMMAND ’parameter com.listen’;
RC TEXT
-- ----
0 Com Listen tcpip 2315, tcpip 1315, tcpip 1964
1 rows fetched.

Adding and modifying a network name for the server

You can add and modify network names for solidDB server in the following ways:
v To add network names for the server, use the following ADMIN COMMAND:
ADMIN COMMAND ’parameter com.listen=network_name’
The command returns the new value as the resultset. If the network name
entered is invalid, the ADMIN COMMAND statement returns an error.
Otherwise the new name is enacted immediately. The changes are written to
solid.ini at the next checkpoint.

Note: The ADMIN COMMAND ’par com.listen=value’ command does not replace
existing network listening names; it appends new listening names to the existing
list.
v Modify the Com.Listen setting in the solid.ini file.
Use a comma (,) to separate network names.
Example:
[Com]
Listen = tcpip 1313, nmpipe soliddb
You must restart the solidDB server to activate the changes.
v To enable a network name temporarily, use the option -x listen:<connect-
string> at solidDB startup, enclosing the network name in double quotation
marks.
Example:
solid -x listen:"tcp 2313"

Removing network name from the server

To remove a network name for the server permanently, modify the Com.Listen
setting in the solid.ini file.

You must restart the solidDB server to activate the changes.

Connect strings for clients

The network name used by a client is a data source connect string. A connect string
consists of a communication protocol, a possible set of options, an optional host
computer name, and a server name. By this combination, the client specifies the
server it will establish a connection to. The connect string can also be mapped to
logical data source name.

A default connect string can be defined with the client-side Com.Connect

configuration parameter. The connect string can also be supplied, for example, at
connection time or when configuring data sources with an ODBC driver manager.

The same format of the connect string applies to the Com.Connect parameter as
well as to the connect string used by solidDB tools or ODBC applications.

The format of a connect string is the following:

protocol_name [options] [host_computer_name] server_name

84 IBM solidDB: Administrator Guide

 where
v options can be any combination of the following:
Table 17. Connect string options

Option Description Protocol

-4 Specifies that client connects using IPv4 protocol only. TCP/IP
-6 Specifies that client connects using IPv6 protocol only. TCP/IP

In Windows environments, this option is mandatory if IPv6 protocol is used.

All
-z Enables data compression for this connection
-c milliseconds Specifies the login timeout (the default is operating-system-specific). A login request TCP/IP
fails after the specified time has elapsed.
Specifies the connection (or read) timeout. A network request fails when no response is TCP/IP
-r milliseconds received during the time specified. The value 0 (default) sets the timeout to infinite
(operating system default timeout applies).
-ofilename Turns on the Network trace facility and defines the name of the trace output file All

See Network trace facility in the IBM solidDB Administrator Guide for details.
-plevel Pings the server at the given level (0-5). All

Clients can always use the solidDB Ping facility at level 1 (0 is no operation/default).
Levels 2, 3, 4 or 5 may only be used if the server is set to use the Ping facility at least at
the same level.

See Ping facility in the IBM solidDB Administrator Guide for details.
-t Turns on the Network trace facility All

See Network trace facility in the IBM solidDB Administrator Guide for details.

v host_computer_name is needed with TCP/IP and Named Pipes protocols, if the

client and server are running on different machines.
v server_name depends on the communication protocol:
– In TCP/IP protocol, server_name is a service port number, such as '2315'.
– In other protocols, server_name is a name, such as 'soliddb' or 'chicago_office'.
For details on the syntax in different communication protocols, see
Communication protocols in the IBM solidDB Administrator Guide.

Note:
v The protocol_name and the server_name must match the ones that the server is
using in its network listening name.
v If given at the connection time, the connect string must be enclosed in double
quotation marks.
v All components of the connect string are case insensitive.

Examples
[Com]
Connect=tcp -z -c1000 1315
[Com]
Connect=nmpipe host22 SOLID
solsql "tcp localhost 1315"
solsql "tcp 192.168.255.1 1315"
rc = SQLConnect(hdbc, "upipe SOLID", (SWORD)SQL_NTS, "dba", 3, "dba", 3);

5 Managing network connections 85

 rc = SQLDriverConnect(hdbc,
(SQLHWND)NULL,
(SQLCHAR*)"DSN=tcp localhost 1964;UID=dba;PWD=dba",
38,
out_string,
255,
&out_length,
SQL_DRIVER_NOPROMPT);

Default connect string (Com.Connect)

When no network name is specified for the connection, the default connect string
is used. The default connect string is defined with the Com.Connect parameter in
the client-side solid.ini configuration file.

The value of the Com.Connect parameter is read by all solidDB tools (solsql and so
on) and client libraries when no network name is specified for the connection. The
client libraries do not need this value if a valid connect string is supplied at run
time, or when an ODBC driver manager is used.

If the Com.Connect parameter is not found in the solid.ini configuration file, the
client uses the default value tcp localhost 1964 (Windows ) or upipe (Linux and
UNIX) instead. The server-side Com.Listen and client-side Com.Connect factory
values are set so that if the parameter settings are not available in the solid.ini
file, the application (client) will always connect to a local solidDB server that is
listening with the default network name. Thus, local communication (inside one
machine) does not necessarily need a solid.ini configuration file for establishing a
connection.

Example

The following parameter setting in the solid.ini of the application workstation

defines that the application (client) connects using TCP/IP protocol to a solidDB
server that is running on a host computer named spiff and listening with the
name (port number in this case) 1313.
[Com]
Connect = tcpip spiff 1313

Logical data source names

The solidDB tools and client libraries support logical data source names. Logical
data source names can be used for giving a database a descriptive name.

The logical data source name can be mapped to a data source as a 'logical name'
and 'connect string' (network name) pair in the following ways:
v Using the [Data Sources] section in the client-side solid.ini file
The syntax of the parameters is the following:
[Data Sources]
logical_name = connect_string; Description
where Description can be used for comments on the purpose of the logical
name
Example:
To map a logical name My_application to a database that you want to connect
using TCP/IP, include the following lines in the solid.ini file:
[Data Sources]
My_application = tcpip irix 1313; Sample data source

86 IBM solidDB: Administrator Guide

 When an application calls the data source 'My_application', the solidDB client
maps this to a call to 'tcpip irix 1313'.
v In Windows environments, using the registry settings (ODBC Driver
Manager)
You can use the Control Panel > Administrative Tools > Data Sources (ODBC)
dialog or the Registry Editor (regedit) to add mappings.
For details, see Configuring the solidDB ODBC Data Source for Windows in the IBM
solidDB Programmer Guide.

Tip: The solidDB data management tools use the solidDB ODBC API. If you
have defined an ODBC Data Source, you can use the logical name source name
also when connecting to solidDB server with the solidDB tools.

For example, if you have created a data source named 'solid_1' with ServerName
'tcp 2525', you can connect to solidDB with solidDB SQL Editor (solsql) with
the following command:
solsql solid_1

When connecting to the solidDB server, if the network name is not a valid connect
string, the solidDB tools and clients assume it is a logical data source name. To
find a mapping between the logical data source name and a valid connect string,
the solidDB tools and clients check the client-side solid.ini file.

In Windows environments, if the solid.ini file is not found or the logical data
source name is not defined in the [Data Sources] section, the data source settings
made with the Windows registry settings are checked in the following order.
1. Look for the Data Source Name from the following registry path:
HKEY_CURRENT_USER\software\odbc\odbc.ini\DSN
2. Look for the Data Source Name from the following registry path
HKEY_LOCAL_MACHINE\software\odbc\odbc.ini\DSN

The check for the logical data source mappings might impact performance:
v If the file system is particularly slow, for example, because the working directory
is mapped to a network drive, checking the existence of the solid.ini file can
have a measurable performance impact.
v In Windows environments, all logical data source mappings in the ODBC
registry are checked. The time consumed for this operation is proportional to the
amount of defined data sources.
– With only few (1 to 5) data sources, the connection time will be
approximately 5 ms.
– With 1000 data sources, the connection time will be approximately 200 ms.
However, if the solid.ini file contains the logical data source name mapping,
the tools and clients do not try to access the ODBC registry for the mapping.

Communication protocols
The client process and the solidDB server communicate with each other by using
computer networks and network protocols. Supported communication protocols
depend on the type of computer and network you are using.

The following sections describe the supported communication protocols and

common environments that may be used. They also describe the required forms of
network names for the various protocols.

5 Managing network connections 87

 Tip: You can view the available communication protocols in your system with the
ADMIN COMMAND ’protocols’ command.

TCP/IP protocol
solidDB supports both TCP/IPv4 and TCP/IPv6 protocols. To use the TCP/IP
protocol, you need to specify tcp as the protocol, specify the host computer
(optional), and use a non-reserved port number.

There are differences in the use of the TCP/IPv4 and TCP/IPv6 protocols,
depending on the platform.
v In Linux and UNIX environments, solidDB can listen to both the TCP/IPv4 and
TCP/IPv6 protocols automatically, based on the format of the IP address in the
network name. If the network name does not specify an IP address, solidDB
tries to start listening on IPv6 (::0) first, if it is not possible, it retries on IPv4
(0.0.0.0).
If you want solidDB to listen to only one protocol type, you can specify the
protocol explicitly with the -4 (IPv4) and -6 (IPv6) option in the network name.
v In Windows environments, solidDB listens to the IPv4 protocol by default.
To use the IPv6, you need to specify the IPv6 protocol using the option -6 in the
network name.
Table 18. TCP/IP protocol in the network listening name (Com.Listen)
Platform IPv4 syntax IPv6 syntax
Listen = tcp [-4] [-ihost_computer] port_number Listen = tcp [-6] [-ihost_computer] port_number
Linux and
UNIX Examples: Examples:
Listen = tcp 1315 Listen = tcp 1315
Listen = tcp -i9.11.22.314 1315 Listen = tcp -ife80::9:1122::0314 1315
Listen = tcp [-4] [-ihost_computer] port_number Listen = tcp -6 [-ihost_computer] port_number
Windows
Examples: Examples:
Listen = tcp 1315 Listen = tcp -6 1315
Listen = tcp -i9.11.22.314 1315 Listen = tcp -6 -ife80::9:1122::0314 1315

Table 19. TCP/IP protocol in the client connect string (Com.Connect)

Platform IPv4 syntax IPv6 syntax
Connect = tcp [-4] [host_computer] port_number Connect = tcp [-6] [host_computer] port_number
Linux and
UNIX Examples: Examples:
Connect = tcp 1315 Connect = tcp 1315
Connect = tcp 9.11.22.314 1315 Connect = tcp fe80::9:1122::0314 1315
Connect = tcpip -4 accounting_dept_server 1315 Connect = tcpip accounting_dept_server 1315
Connect = tcp [-4] [host_computer] port_number Connect = tcp -6 [host_computer] port_number
Windows
Examples: Examples:
Connect = tcp 1315 Connect = tcp -6 1315
Connect = tcp 9.11.22.314 1315 Connect = tcp -6 fe80::9:1122::0314 1315
Connect = tcpip accounting_dept_server 1315 Connect = tcpip -6 accounting_dept_server 1315

where

host_computer = ip_address|host_name

88 IBM solidDB: Administrator Guide

 v If the server is running in the same computer with the client program,
host_computer does not need to be specified.
v If host_computer is specified as a host_name, the host_name must be listed in
the/etc/hosts file or it must be recognized by the DNS (Domain Name Server).
v If a client attempts to open a TCP/IP connection without specifying a hostname,
it uses the local loopback interface address, 127.0.0.1 (IPv4) or ::1 (IPv6) as the
default IP address.

port_number must be an unreserved port; reserved port numbers are listed in the
/etc/services file of your system. Select a free number greater than 1024 – smaller
numbers are usually reserved for the operating system.

-i ip_address or -i host_name means that the solidDB listens only to the

specified IP address or host name. This is useful in multihomed systems that
support many TCP/IP interfaces or have multiple IP addresses.

UNIX Pipes
The UNIX domain sockets (UNIX Pipes) are typically used when communicating
between two processes running in the same UNIX machine. UNIX Pipes usually
have a very good throughput. They are also more secure than TCP/IP, since Pipes
can only be accessed from applications that run on the computer where the server
executes.

When using the UNIX Pipes protocol, you must reserve a unique listening name
(server name) within the node for the server, for instance, 'soliddb'. Because UNIX
Pipes handle the UNIX domain sockets as standard file system entries, there is
always a corresponding file created for every listened pipe. In solidDB's case, the
entries are created under the path /tmp.

For example, the server name 'soliddb' creates the directory /tmp/solunp_SOLIDDB
and shared files in that directory. The /tmp/solunp_ is a constant prefix for all
created objects while the latter part ('SOLIDDB' in this case) is the server name in
upper case format.

To use the UNIX Pipes protocol, select upipe or unp as the protocol and enter a
server name.
Table 20. UNIX Pipes protocol in the network name

Where Syntax example

Listen = upipe server_name

Server

Connect = upipe server_name

Client

Note:
v To use the UNIX Pipes protocol, the server and client processes must run in the
same machine.
v The server process must have "write" permission to the directory /tmp.
v The client that is accessing UNIX Pipes must have "execute" permission on the
directory /tmp.
v The directory /tmp must exist.

5 Managing network connections 89

 Named Pipes
Named Pipes is a protocol commonly used in the Windows operating systems. To
use the Named Pipes protocol, select nmpipe or nmp as the protocol and enter a
server name.
Table 21. Named Pipes protocol in the network name

Where Syntax example

Listen = nmpipe server_name

Server

Connect = nmpipe [host_computer_name] server_name

Client

Note:
v server_name must be a character string at most 50 characters long.
v If the server is running in the same computer with the client program, the
host_computer_name must not be specified.
v If host_computer_name is used, the host_computer_name must be listed in
the/etc/hosts file or it must be recognized by the DNS (Domain Name Server).
v To connect to the solidDB server with the Named Pipes protocol, the user must
have at least the same rights as the user who started the server.
For example, if an administrator starts the server, only users with administrator
rights are able to connect to the server through Named Pipes. Similarly, if a user
with normal user rights starts the server, all users with equal or greater rights
are able to connect the server through Named Pipes.
If a user does not have proper rights, the solidDB Communication Error 21306
message is given.
v Do not use the Named Pipes protocol with solidDB Remote Control (solcon); the
asynchronous nature of communication between solcon and the solidDB server
may cause problems with the Named Pipes protocol (solidDB server can output
messages to solcon command prompt even though solcon does not query for
such messages explicitly).

Shared Memory
In some cases, the Shared Memory protocol can be the fastest way two processes
can exchange information. The Shared Memory protocol can be used only when
solidDB and application processes are both running in the same computer. The
Shared Memory protocol uses a shared memory location for moving data from one
process to another.

To use the Shared Memory protocol in solidDB, select shmem as the protocol and
enter the server name.
Table 22. Shared Memory protocol in the network name

Where Syntax example

Listen = shmem server_name

Server

Connect = shmem server_name

Client

Note:
v server_name must be a character string less than 128 characters long.

90 IBM solidDB: Administrator Guide

 v server_name has to be unique only in this computer.

Summary of protocols
The following tables summarize the possible operating systems and required forms
for network names for the various communication protocols.
Table 23. solidDB protocols and network names

Protocol Server OS Network name in solid.ini file

Named Pipes Windows Listen = nmpipe server

TCP/IP Linux, UNIX, Windows Listen = tcpip port

UNIX Pipes Linux, UNIX Listen = upipe server

Shared Memory Windows Listen = shmem server

Table 24. Application protocols and network names

Protocol Server OS Network name in solid.ini file

Named Pipes Windows Connect = nmpipe [host] server

TCP/IP Linux, UNIX, Windows Connect = tcpip [host] port

UNIX Pipes Linux, UNIX Connect = upipe server

Shared Memory Windows Connect = shmem server

5 Managing network connections 91

92 IBM solidDB: Administrator Guide
6 Using solidDB data management tools
solidDB data management tools are a set of utilities for performing various
database tasks.

Console tools: solidDB SQL Editor (solsql) and solidDB Remote

Control (solcon)
v solidDB SQL Editor (solsql) is a console tool used to issue SQL statements and
solidDB ADMIN COMMANDs at the command prompt, or by executing a script
file that contains the SQL statements.
v solidDB Remote Control (solcon) is a console tool for administration; users with
administrator rights can issue ADMIN COMMANDs at the command prompt or
by executing a script file that contains the commands. With solcon, the ADMIN
COMMANDs can be issued as part of the solcon startup command line.

Tools for exporting and loading data

solidDB provides the following tools for exporting and loading data:
v solidDB Speed Loader (solloado or solload) loads data from external files into a
solidDB database.
v solidDB Export (solexp) exports data from a solidDB database to files. It also
creates control files used by solidDB Speed Loader (solloado or solload) to
perform data load operations.
v solidDB Data Dictionary (soldd) exports the data dictionary of a database. It
produces an SQL script that contains data definition statements that describe the
structure of the database.

Note: solidDB data management tools do not support the Transparent Failover
(TF) feature used in High Availability configurations. Transparent Failover hides
the server change from the user. For more information, refer to IBM solidDB High
Availability User Guide.

solidDB Remote Control (solcon)

solidDB Remote Control (solcon) is a console tool for administration; it can be
used to issue ADMIN COMMANDs at the command prompt or by executing a
script file that contains the commands. The ADMIN COMMANDs can be issued as
part of the solcon startup command line. Only users with administrator rights can
issue commands with solcon.

Because solcon can be used to issue only ADMIN COMMANDs, it can be useful to
deploy only solcon on a production node; with solcon, administrators cannot
accidentally access or change data in the database by issuing SQL statements.

With solcon, the ADMIN COMMAND syntax differs from the syntax used with
solidDB SQL Editor (solsql). In solcon, the command includes the ADMIN
COMMAND option only, without the single quotation marks. The semicolon used
with solsql is not used with solcon either.

For example:

93
 solcon:
backup

solsql:
ADMIN COMMAND ’backup’;

Starting solidDB Remote Control (solcon)

Start solidDB Remote Control (solcon) with the command solcon, followed by
argument options.

The syntax for starting solcon is:

solcon [options][network_name][username][password]

where
v options can be:
Table 25. solcon command options

Option Syntax Description

-c dir Change working directory.

-e command string Execute the specified ADMIN COMMAND.

-f filename Execute command string from a script file.

-x pwdfile: filename Read password from the filename.

-h, -? Help = Usage.

v network_name is the network name of a solidDB server that you are connected
to.
The given network name must be enclosed in double quotation marks.

Note: Logical data source names can also be used with tools; refer to 5,
“Managing network connections,” on page 81 for further information.
v username is required to identify the user and to determine the user's
authorization. Without appropriate rights, command execution is denied.
v password is the user's password for accessing the database.

solcon connects to the first server specified in the Com.Connect parameter in the
solid.ini file. If you specify no arguments, you are prompted for the database
administrator's user name and password. You can give connection information at
the command line to override the connect definition in solid.ini.

Access rights

To use solcon, you must have SYS_ADMIN_ROLE or SYS_CONSOLE_ROLE rights,

or the connection will be refused.

Error messages
When there is an error in the command line, solcon gives you a list of the possible
syntax options as a result. Check the command line you entered.

94 IBM solidDB: Administrator Guide

 Exiting solcon

To exit Remote Control, enter the command exit.

Examples: solidDB Remote Control (solcon)

Start up solcon with the server name "tcp localhost 1313" and the administrator
username 'admin' and password 'iohi4y':
solcon "tcp localhost 1313" admin iohi4y

Start up solcon to back up a specific database:

solcon -ebackup ’tcpip 1313" dbadmin iohi4y

Entering commands in solidDB Remote Control (solcon)

After the connection to the server is established, the command prompt appears.

You can execute all commands at the command line with the -e option or in a text
file with the -f option.

When you execute administrative commands in solidDB Remote Control, you

provide only the ADMIN COMMAND option (command_name) as the syntax for
the command string (without single quotation marks); for example, the SQL
command ADMIN COMMAND 'backup' in solidDB Remote Control is:
backup

For a list of the administrative commands, see section “ADMIN COMMAND” on

page 309.

When there is an error in the command line, solidDB Remote Control gives you a
list of the possible options as a result. Check the command line you entered.
Table 26. solcon specific commands

Command Abbreviation Explanation

exit ex Exits solidDB Remote Control

help ? Displays available Remote Control

commands

solidDB SQL Editor (solsql)

solidDB SQL Editor (solsql) is a console tool that is used for issuing SQL
statements and ADMIN COMMANDs. The commands and statements can be
issued at the command prompt or by executing a script file that contains the SQL
statements.

For a formal definition of SQL statements, see section solidDB SQL syntax in the
IBM solidDB SQL Guide.

For a list of ADMIN COMMANDs and the ADMIN COMMAND syntax, see
“ADMIN COMMAND” on page 309.

Tip: To access a short description of available ADMIN COMMANDs and their

abbreviations, execute the following command:

6 Using solidDB data management tools 95

 ADMIN COMMAND ’help’

Starting solidDB SQL Editor

Start solidDB SQL Editor (solsql) with the command solsql, followed by
argument options.

The syntax for starting solsql is:

solsql [options] [network_name] username [password]

where
v options can be:
Table 27. solsql command options

Option Syntax Description

-a Autocommit every statement

-c dir Change working directory

-e sql-string Execute the SQL string; if used commit can only be done using
-a

-f filename Execute SQL string from a script file

-o filename Write result set to this file

-O filename Append result set to this file

-S schema_name Use only this schema

-C catalog_name Use only this catalog

-t Print execution time per command

-tt Print prepare, execute, fetch, and execution time per command
-2 Creates two connections to the database

You can switch between the two connections with the command
switch.

v In Unicode databases (General.InternalCharEncoding=UTF8),

-u
expect the data in character and wide character data type
columns to be encoded in UTF-8.
v In partial Unicode databases
(General.InternalCharEncoding=Raw), expect the data in wide
character data type columns to be encoded in UTF-8. Data in
character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120
for more information.

96 IBM solidDB: Administrator Guide

Table 27. solsql command options (continued)

Option Syntax Description

-m v In Unicode databases (General.InternalCharEncoding=UTF8),
expect the data in character and wide character data type
columns to be encoded in the console's locale/codepage,
despite the settings in the server-side and client-side character
data binding parameters.
v In partial Unicode databases
(General.InternalCharEncoding=Raw), expect the data in wide
character data type columns to be encoded in the console's
locale/codepage, despite the settings in the server-side and
client-side character data binding parameters. Data in
character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120
for more information.
-M locale_name v In Unicode databases (General.InternalCharEncoding=UTF8),
expect the data in character and wide character data type
columns to be encoded in the specified locale/codepage.
v In partial Unicode databases
(General.InternalCharEncoding=Raw), expect the data in wide
character data type columns to be encoded in the specified
locale/codepage. Data in character data type columns is not
converted.
The format of locale_name depends on the operating system.
For example, in Linux environments, the locale name for the
code page GB18030 in Chinese/China is zh_CN.gb18030.
In Windows environments, the locale name for Latin1 code
page in Finnish/Finland is fin_fin.1252.
See section “Using solidDB tools with Unicode” on page 120
for more information.

-h, -? Help = Usage

-x onlyresults Print only rows

-x pwdfile: filename Read password from the filename

-x stoponerror This command-line switch is used to force stop and exit solsql
immediately when an error is detected.

-x returnerroronexit This command-line switch is used to display return codes for

SQL errors and user raised procedure errors. The possible return
codes are:
v Code 60: the execution of an SQL statement fails.
v Code 61: a procedure call returns an error.

If several SQL statements and/or procedure calls fail during the

execution of an SQL script, the returned code is that of the first
failure.

-x outputsql This command-line switch prints out the executed SQL

commands instead of only printing out the results of each
operation.

v network_name is the network name of a solidDB server that you are connected
to.
The given network name must be enclosed in double quotation marks. Refer to
5, “Managing network connections,” on page 81 for further information.

6 Using solidDB data management tools 97

 Tip: Logical data source names can also be used with the solidDB tools.
v username is required to identify the user and to determine the user's
authorization. Without appropriate rights, command execution is denied.
v password is the user's password for accessing the database. The password is
– mandatory, if the password is not read from a file (defined with option -x
pwdfile: filename)
– optional, if the password is read from a file

Note:
v If the username and password are specified at the command line, the
network_name must also be specified.
v If the name of the SQL script file is specified at the command line (except with
the -f option), the network_name, username, and password must also be specified.

Remember to commit work at the end of the SQL script or before exiting solsql.

The solidDB tools connect to the first server specified in the Com.Connect parameter
in the solid.ini file. If you specify no arguments, you are prompted for the
database administrator's user name and password.

Error messages

When there is an error in the command line, solsql gives you a list of the possible
syntax options as a result. Check the command line you entered.

Exiting solsql

To exit solsql, enter the command exit.

Related reference:
“solidDB SQL Editor (solsql) commands” on page 99
In addition to SQL statements and ADMIN COMMANDs, there are a number of
solsql specific commands that you can use to operate solsql.

Executing SQL statements with solidDB SQL Editor

After the connection to the server has been established, a command prompt
appears. solidDB SQL Editor executes SQL statements terminated by a semicolon.

Example:
create table testtable (value integer, name varchar);
commit work;

insert into testtable (value, name) values (31, ’Duffy Duck’);

select value, name from testtable;
commit work;

drop table testtable;

commit work;

Executing an SQL script from a file

You can execute SQL scripts from a file directly in the solidDB SQL Editor or by
specifying the script filename in the solidDB SQL Editor startup command line.

98 IBM solidDB: Administrator Guide

 Executing an SQL script in the solidDB SQL Editor

The syntax for script calls in solsql is:

@filename

For example:
---Execute the SQL script named "insert_rows.sql" in the
-- root ("\") directory of the C: drive.
@\c:\insert_rows.sql;

Both absolute and relative path names are supported. If you specify a relative path,
it should be relative to the solsql working directory.

Executing an SQL script from a file at the solidDB SQL Editor

startup

To execute an SQL script from a file at solsql startup, the name of the script file
must be given as a command line parameter:
solsql network_name username password filename

All statements in the script must be terminated by a semicolon. solsql exits after all
statements in the script file have been executed.

Example:
solsql "tcp localhost 1313" admin iohe4y tables.sql

Note:

Remember to commit work at the end of the SQL script or before exiting solsql. If
an SQL string is executed with the option -e, commit can only be done using the
-a option.

solidDB SQL Editor (solsql) commands

In addition to SQL statements and ADMIN COMMANDs, there are a number of
solsql specific commands that you can use to operate solsql.

Note: The solsql commands must be terminated by a semicolon.

Table 28. solidDB SQL Editor (solsql) commands
Command Description
bye Shuts down solsql
exit Shuts down solsql
help Displays usage information for solsql
quit Shuts down solsql
solsql_silent Makes solsql sleep for seconds
seconds
switch Switches between the two connections to the database that have been
created using the -2 startup option

6 Using solidDB data management tools 99

solidDB Speed Loader (solloado and solload)
solidDB Speed Loader (solload) is a tool for loading data from external files into a
solidDB database.

As of solidDB 6.5 Fix Pack 2, there are two variants of the solidDB Speed Loader:
v solloado provides support for Unicode and partial Unicode databases. It also
enables loading of data with multiple threads. solloado is based on the solidDB
ODBC API; the client-side configuration parameters can be used to control the
behavior of solloado.
v solload provides support for partial Unicode databases only. solload is based
on the solidDB SA API.

The solidDB Speed Loader can load data in a variety of formats and produce
detailed information of the loading process into a log file. The format of the import
file, that is, the file containing the external data, is specified in a control file.

The data is loaded into the database through the solidDB program. This enables
online operation of the database during the loading. The data to be loaded does
not have to reside in the server computer.
v The table must exist in the database in order to perform data loading.
v Catalogs are supported with the following syntax:
catalog_name.schema_name.table_name
v The following constraints are checked:
– referential
– NOT NULL
– unique
v solidDB Speed Loader does not support check constraints that are defined using
the CREATE TABLE and ALTER TABLE statement and specify data value
restrictions in columns.
However, solidDB Speed Loader always checks for unique or foreign key
constraints that are defined using the CREATE TABLE statement. For more
details on constraints, see the CREATE TABLE syntax in the Appendix: solidDB
SQL Syntax in the IBM solidDB SQL Guide.

File types
Control file
The control file provides information about the structure of the import file. It gives
the following information:
v name of the import file
v format of the import file
v table and columns to be loaded

Note: Each import file requires a separate control file. solidDB Speed Loader
loads data into one table at a time.

For more details about the control file format, read “Control file syntax” on page
106.

100 IBM solidDB: Administrator Guide

 Import file (data file)
The import file is the file that contains the data to be loaded into the solidDB
database. The solidDB Export (solexp) produces these type of data files.

The import file may contain the data either in a fixed or a delimited format:
v In fixed-length format data records have a fixed length, and the data fields
inside the records have a fixed position and length.
v In delimited format data records can be of variable length. Each data field and
data record is separated from the next with a delimiting character such as a
comma (this is what solidDB Export produces). Fields containing no data are
automatically set to NULL.

Data fields within a record may be in any order specified by the control file.
v Data in the import file must be of a suitable type. For example, numbers that are
presented in a float format cannot be loaded into a field of INTEGER or
SMALLINT type.
v Data of VARBINARY and LONG VARBINARY type must be hexadecimal
encoded in the import file.
v When using any fixed-width field, regardless of the data type, solloado or
solload expects the import file to have the specified width, even when NULL is
used.

Message log file

During loading, solidDB Speed Loader produces a log file containing the following
information:
v Date and time of the loading
v Loading statistics such as the number of rows successfully loaded, the number
of failed rows, and the load time if it has been specified with the option
v Any possible error messages. For details on solidDB Speed Loader errors, see
“solidDB Speed Loader (solloado and solload) errors” on page 307.

If the log file cannot be created, the loading process is terminated. By default the
name of the log file is generated from the name of the import file by substituting
the file extension of the import file with the file extension .log. For example,
my_table.ctr creates the log file my_table.log. To specify another file name, use
the option -l.

Starting solidDB Speed Loader (solloado and solload)

Start solidDB Speed Loader with the command solloado or solload, followed by
argument options.

If you start solidDB Speed Loader with no arguments, you will see a summary of
the arguments with a brief description of their usage.
v The syntax for starting solloado is:
solloado [options] [network_name] username [password]control_file
v The syntax for starting solload is:
solload [options] [network_name] username [password]control_file

where options can be:

6 Using solidDB data management tools 101

Table 29. solloado and solload command options

Option Syntax solloado solload Description

X X Number of insert statements to commit in one batch (number of statements after
-b statements which commit is executed)

For example, if you specify -b 10, commit is executed after 10 inserts.

-B records X Number of records to be inserted in one statement

For example, if you specify -B 3, each insert inserts three rows.

X X
-c dir Change working directory
X X
-C catalog_name Set the default catalog from where data is read from or written to
X X
-l filename Write log entries to this file
X X
-L filename Append log entries to this file
-m X v In Unicode databases (General.InternalCharEncoding=UTF8), expect the data in
character and wide character data type columns to be encoded in the console's
locale/codepage, despite the settings in the server-side and client-side character
data binding parameters.
v In partial Unicode databases (General.InternalCharEncoding=Raw), expect the data
in wide character data type columns to be encoded in the console's
locale/codepage, despite the settings in the server-side and client-side character
data binding parameters. Data in character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for more
information.
-M locale_name X v In Unicode databases (General.InternalCharEncoding=UTF8), expect the data in
character and wide character data type columns to be encoded in the specified
locale/codepage.
v In partial Unicode databases (General.InternalCharEncoding=Raw), expect the data
in wide character data type columns to be encoded in the specified
locale/codepage. Data in character data type columns is not converted.
The format of locale_name depends on the operating system.
For example, in Linux environments, the locale name for the code page GB18030
in Chinese/China is zh_CN.gb18030.
In Windows environments, the locale name for Latin1 code page in
Finnish/Finland is fin_fin.1252.
See section “Using solidDB tools with Unicode” on page 120 for more
information.
-u X v In Unicode databases (General.InternalCharEncoding=UTF8), expect the data in
character and wide character data type columns to be encoded in UTF-8.
v In partial Unicode databases (General.InternalCharEncoding=Raw), expect the data
in wide character data type columns to be encoded in UTF-8. Data in character
data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for more
information.
X X
-n records Insert array size (network version)
X X
-s Set the default schema
schema_name
X X
-t Print load time

102 IBM solidDB: Administrator Guide

Table 29. solloado and solload command options (continued)

Option Syntax solloado solload Description

-w threads X Sets the number of threads inserting data. The value cannot exceed the number of
processors

Default is 4.
X X
-h Help = Usage
X X
-x emptytable Load data only if there are no rows in the table
X X
-x errors: Maximum error count
count
X X
-x nointegrity No integrity checks during load
X X
-x pwdfile: Read password from the file
filename
X X
-x skip: Number of records to skip
records
X
-x utf8 WCHAR data is in UTF-8 format

v network_name is the network name of a solidDB server that you are connected
to.
The given network name must be enclosed in double quotation marks. Refer to
5, “Managing network connections,” on page 81 for further information.

Tip: Logical data source names can also be used with the solidDB tools.
v username is required to identify the user and to determine the user's
authorization. Without appropriate rights, command execution is denied.
v password is the user's password for accessing the database. The password is
– mandatory, if the password is not read from a file (defined with option -x
pwdfile: filename)
– optional, if the password is read from a file

For details on the control_file, see section “Control file syntax” on page 106.

Examples

The following solloado example loads data from a file specified by a control file
named DBA_TBL.ctr, reading data as UTF-8 characters and using 8 threads to insert
data with 30 records in one statement:
solloado -w 8 -B 30 -u "tcpip 1964" dba dba DBA_TBL.ctr

The following solload example loads data from a file specified by a control file
named delim.ctr:
solload "tcpip 1964" dba dba delim.ctr

Error messages

When there is an error in the command line, solload gives you a list of the
possible syntax options as a result. Check your command line entry.

6 Using solidDB data management tools 103

 Tips for speeding up loading
To ensure that loading takes place with maximum performance, consider the
following aspects:
v Connect locally if possible; it is slower to load data over the network.
v Increase the number of records committed in one batch. By default, commit is
done after each record.
v Disable transaction logging.
To disable logging, set the Logging.LogEnabled parameter to no.

Tip: After the loading has been completed, remember to enable logging again
(Logging.LogEnabled=yes). Running the server in production use with logging
disabled is strongly discouraged. If logs are not written, no recovery can be
made if an error occurs due to, for example, power failure or disk error.

Examples
Example: Loading fixed-format records
In fixed-length format import files, data records have a fixed length and the data
fields inside the records have a fixed position and length.

Example: Control File 1

EXAMPLE 1 uses multiple columns in fixed-width field:

OPTIONS(ARRAYSIZE=3)

LOAD
INFILE ’test1.dat’
INTO TABLE SLTEST
(
"NAME" POSITION(1-5),
ADDRESS POSITION(6:10),
ID POSITION(11-15)
)

Example: Control File 2

OPTIONS (SKIP = 10, ERRORS = 5)
-- Skip the first ten records. Stop if
-- errorcount reaches five.
LOAD DATA
INFILE ’sample.dat’
-- import file is named sample.dat
INTO TABLE TEST1 (
IDINTEGER POSITION(1-5),
ANOTHER_ID INTEGER POSITION(8-15),
DATE1 POSITION(20:29) DATE ’YYYY-MM-DD’,
DATE2 POSITION(40:49) DATE ’YYYY-MM-DD’ NULLIF NULL)

Example: Loading variable-length records

This section contains examples of the control file when loading data from a
variable-length import file:

Example: Control File 3

EXAMPLE 1 uses multiple columns that have separators instead of fixed-length

fields.

104 IBM solidDB: Administrator Guide

 LOAD
INFILE ’test1.dat’
INTO TABLE SLTEST
FIELDS TERMINATED BY ’,’
(
NAME,
ADDRESS,
ID
)

Example: Control File 4

LOAD DATA
INFILE ’EXAMP2.DAT’
INTO TABLE SUPPLIERS
FIELDS TERMINATED BY ’,’
(NAME VARCHAR, ADDRESS VARCHAR, ID INTEGER)
-- EXAMPLE 2
OPTIONS (SKIP=10, ERRORS=5)
-- Skip the first ten records. Stop if
-- errorcount reaches five.
LOAD
DATE ’YYYY-MM-DD HH:NN:SS’
-- The date format in the import file
INFILE ’sample.dat’
-- The import file
INTO TABLE TEST1
-- data is inserted into table named TEST1
FIELDS TERMINATED BY X’2C’
-- Field terminator is HEX ’,’ == 2C
-- This line could also be:
-- FIELDS TERMINATED BY ’,’
OPTIONALLY ENCLOSED BY ’[’ AND ’)’
-- Fields may be enclosed
-- with ’[’ and ’)’
(
ID INTEGER,
ANOTHER_ID DECIMAL(2),
DATE1 DATE(20) DATE ’YYYY-MM-DD HH:NN:SS’,
DATE2 NULLIF NULL
)
-- ID is inserted as integer
-- ANOTHER_ID is a decimal number with 2
-- digits.
-- DATE1 is inserted using the date string
-- given above
-- The default date string is used for DATE2.
-- If the column for DATE2 is ’NULL’ a NULL is
-- inserted.

Running a sample load using solidDB Speed Loader (solload)

The solidDB package contains a sample that demonstrates how to use solload to
load files. The sample is available in the samples/importexport/solload directory
in your solidDB.
1. Start solidDB.
2. Create the table by using the load.sql script and solidDB SQL Editor (solsql).
3. Start loading by entering the command below:
solload "tcpip 1964" dba dba delim.ctr
The user name and password are assumed to be 'dba'.
To use the fixed length control file, enter the command below:
solload "tcpip 1964" dba dba fixed.ctr
4. The output of a successful loading using delim.ctr or fixed.ctr is:

6 Using solidDB data management tools 105

 IBM solidDB Speed Loader - Version 6.5.0.4 Build 2011-01-20
Copyright Oy International Business Machines Ab 1993, 2011.
Load completed successfully, 19 rows loaded.

Control file syntax

The control file syntax has the following characteristics:
v keywords must be given in capital letters
v comments can be included using the standard SQL double-dash (--) comment
notation
v statements can continue from line to line with new lines beginning with any
word

solidDB Speed Loader reserved words must be enclosed in quotes if they are used
as data dictionary objects, that is, table or column names. The following list
contains all reserved words for the solidDB Speed Loader control file:
Table 30. Speed Loader reserved words

Speed Loader Reserved Words

AND ANSI APPEND BINARY

BLANKS BY CHAR CHARACTERSET

DATA DATE DECIMAL DOUBLE

ENCLOSED ERRORS FIELDS FLOAT

IBMPC INFILE INSERT INTEGER

INTO LOAD LONG MSWINDOWS

NOCNV NOCONVERT NULLIF NULLSTR

NUMERIC OPTIONALLY OPTIONS PCOEM

POSITION PRECISION PRESERVE REAL

REPLACE SCAND7BIT SKIP SMALLINT

TABLE TERMINATED TIME TIMESTAMP

TINYINT VARBIN VARCHAR WHITESPACE

The control file begins with the statement LOAD [DATA] followed by several
statements that describe the data to be loaded. Only comments or the OPTIONS
statement may optionally precede the LOAD [DATA] statement.
Table 31. Full syntax of the control file

Syntax Element Definition

::= [option_part]
control_file load_data_part
into_table_part
fields
column_list

106 IBM solidDB: Administrator Guide

Table 31. Full syntax of the control file (continued)

Syntax Element Definition

::= OPTIONS (options)

option_part

::= option [, option]

options

::= [SKIP = int_literal] [ERRORS = int_literal]

option

::= LOAD [DATA] [characterset_specification]

load_data_part [DATE date_mask]
[TIME time_mask]
[TIMESTAMP timestamp_mask]
[INFILE filename]
[PRESERVE BLANKS]

::= CHARACTERSET { NOCONVERT |

characterset_specification NOCNV |
ANSI |
MSWINDOWS |
PCOEM |
IBMPC |
SCAND7BIT }

::= INTO TABLE tablename

into_table_part

::= [FIELDS {termination | enclosure}]

fields

::= TERMINATED BY termination_char

termination [[OPTIONALLY] enclosure]

::= WHITESPACE | ’char’ | "char" | hex_literal

termination_char

::= ENCLOSED BY enclose_char [AND enclose_char]

enclosure

::=’char’ | "char" | hex_literal

enclose_char

::= X’hex_byte_string’
hex_literal

::= column [, column]

column_list

::= column_name datatype_spec

column [POSITION (int_literal {: | -} int_literal)]
[DATE date_mask]
[TIME time_mask]
[TIMESTAMP timestamp_mask]
[ NULLIF BLANKS | NULLIF NULLSTR| NULLIF ’string’ |
NULLIF ((int_literal {: | -} int_literal) = ’string’)]

::= {BINARY | CHAR [(length) ] | DATE |

datatype_spec DECIMAL [ (precision [ , scale ]) ] |
DOUBLE PRECISION | FLOAT [ (precision) ] | INTEGER |
LONG VARBINARY | LONG VARCHAR |
NUMERIC [ ( precision [ , scale ] ) ] |
REAL | SMALLINT | TIME |
TIMESTAMP [ ( timestamp precisionv ) ] |
TINYINT | VARBINARY | VARCHAR [ (length ) ] }

6 Using solidDB data management tools 107

 CHARACTERSET
The CHARACTERSET keyword is used to define the character set used in the
input file. If the CHARACTERSET keyword is not used or if it is used with the
parameter NOCONVERT or NOCNV, no conversions are made.

Use the parameter as follows:

v ANSI for the ANSI character set
v MSWINDOWS for the Windows character set
v PCOEM for the ordinary PC character set
v IBMPC for the IBM PC character set
v SCAND7BIT for the 7-bit character set containing Scandinavian characters

DATE, TIME, and TIMESTAMP

These keywords can be used in two places with different functionality:
v When one of these keywords is used as a part of the load-data-part element, it
defines the format used in the import file for inserting data into any column of
that type.
v When a keyword appears as a part of a column definition, it specifies the format
used when inserting data into that column.

Note:
1. Masks that are used as part of the load-data-part element must be in the
following order: DATE, TIME, and TIMESTAMP. Each is optional.
2. Data must be of the same type in the import-file, the mask, and the column in
the table into which the data is loaded.
Table 32. Data masks

Data Type Available Data Masks

DATE YYYY/YY-MM/M/B-DD/D

TIME HH/H:NN/N:SS/S

TIMESTAMP YYYY/YY-MM/M/B-DD/D HH/H:NN/N:SS/S

v Mask parts:
– Year masks: YYYY and YY
– Month masks: MM, M, and B (B refers to a three-letter abbreviation (case
insensitive) of the month in English)
– Day masks: DD and D
– Hour masks: HH and H
– Minute masks: NN and N
– Second masks: SS and S
v Masks within a DATE mask may be in any order; for example, the DATE mask
could be 'MM-DD-YYYY' (12-18-2010) or 'DD-B-YYYY' (18-DEC-2010).
v If the date data of the import file is formatted as 1995-01-31 13:45:00, use the
mask YYYY-MM-DD HH:NN:SS.
v The masks must be separated

108 IBM solidDB: Administrator Guide

DATE example in Control File

The following example uses the POSITION keyword. For details on this keyword,
read “POSITION” on page 113.
OPTIONS(SKIP=1)

LOAD DATA
RECLEN 12
INTO TABLE SLTEST2
(
ID POSITION(1:2) NULLIF BLANKS,
DT POSITION(3:12) DATE ’DD.MM.YYYY’ NULLIF ((4:6) = ’ ’)
)

DATE, TIME, and TIMESTAMP examples in Control File

The following example uses the FIELDS TERMINATED BY keyword. For details
on this keyword, read “FIELDS TERMINATED BY” on page 112.
LOAD
DATE ’MM/DD/YY’
TIME ’HH-NN-SS’
TIMESTAMP ’HH.NN.SS YY/MM/DD’
INTO TABLE SLTEST3
FIELDS TERMINATED BY ’,’
(
ID,
DT,
TM,
TS
)

PRESERVE BLANKS
The PRESERVE BLANKS keyword is used to preserve all blanks in text fields.

INTO_TABLE_PART
The into_table_part element is used to define the name of the table and columns
that the data is inserted into.

FIELDS ENCLOSED BY
The FIELDS ENCLOSED BY clause is used to define delimiting characters around
each field. The delimiter may be one character or two separate characters that
precede and follow each data field in the input file. You might use one character
(such as the double quote character) or a pair of characters (such as left and right
parentheses) to delimit your fields. If you use the double quote mark as the
delimiter and the comma as the terminator/separator, then your input might look
like the following:
"field1", "field2"

If you use left and right parentheses, then your input might look like the
following:
(field1),(field2)

Note that if the keyword OPTIONALLY is used, then the delimiters are optional
and do not need to appear around every single piece of data.

If you specify a character value, it must be enclosed in single or double quotes. For
example, the following examples have the same effect:
ENCLOSED BY ’(’ AND ’)’
ENCLOSED BY "(" AND ")"

6 Using solidDB data management tools 109

 You can even use the single quotes to surround one enclosing character and double
quotes to surround the other, for example:
ENCLOSED BY ’(’ AND ")"

This is potentially confusing, however, and this format is not recommended.

Instead, it is recommended that you use single quotes unless you are using single
quote itself as the enclosing character, for example:
ENCLOSED BY "’" AND "’"

Note that if you are using single quotes as the enclosing characters, you must
double the apostrophes as shown in the clause above. For example, to produce in
the database:
Didn’t I warn you?

the input must be:

’Didn’’t I warn you?’

Almost any printable characters may be used as the "enclosing" characters. The
enclosing characters may also be specified using the hexadecimal format. For
example, if a hexadecimal string is used, then the format is:
X ’hex_byte_string’

For example:

X’3a’ means 3A hexadecimal value and specifies the colon (":")

The opening and closing characters in an enclosing pair can be identical. For
example, the following is valid inside the control file:
ENCLOSED BY ’"’ AND ’"’

If both the opening and closing characters are the same, then the ENCLOSED BY
clause only needs to show the character once. For example, the following should
have the same effect:
ENCLOSED BY ’"’
ENCLOSED BY ’"’ AND ’"’

When the preceding is defined in the control file, here are some examples of input
and the corresponding values actually stored in the table.
"Hello."
Hello.

"""Ouch!"", he cried."
"Ouch!", he cried.

"""He said her last words were ""I’ll never quit!"""""

"He said her last words were "I’ll never quit!""

"""He said: ""Her last words were ""I’ll never quit!"""""""

"He said: "Her last words were "I’ll never quit!"""

Note that there may be enclosing characters used in the column data itself
(embedded field separators). If this is the case, then you can use the
TERMINATED BY clause together with the OPTIONALLY ENCLOSED BY clause
to be sure the column data is enclosed correctly as described in “FIELDS
TERMINATED BY” on page 112.

110 IBM solidDB: Administrator Guide

ENCLOSED BY input rules and examples

This section contains basic rules and examples when using enclosing characters.
Each example, unless stated otherwise, contains the following control file lines:
FIELDS TERMINATED BY X’3a’
OPTIONALLY ENCLOSED BY "(" AND ")"

This means that the enclosing characters are parentheses and the separator
(terminator) character is the colon — hexadecimal 3A specifies the colon (":").
v The data is to be loaded into a table with two columns, the first of which is of
type VARCHAR and the second of which is type INTEGER.

Treatment of enclosed characters within the data

The ENCLOSED BY characters themselves may occur within the data. However,
when occurring within the data, each of the enclosing characters should occur
twice in the input for each time that it should occur once in the database.

If the input file contains:

(David Bowie ((born David Jones)) released ’space Oddity"):1972

it produces the following format in the database:

David Bowie (born David Jones) released ’space Oddity":1972

This works for deeply nested parentheses as well. If the input file contains:
(You((can((safely((try))this))at))home.):2

it produces the following value in the first column of the table.

You(can(safely(try)this)at)home.

Treatment of final enclosing character

The final enclosing character must occur an odd number of times at the end of the
input. For example:

To get the following format in the database:

American Pie (The Day The Music Died)

the input file must contain:

(American Pie ((The Day The Music Died)))

Of the last three closing parentheses, the first two are treated as a single instance of
the character, while the last one is treated as the enclosing character.

Embedding newline characters

When enclosing characters are used, newline characters (carriage return and/or
line feed) can be embedded within a string. For example:
(This is a long line that can be split across two or more input
lines ((and keep the end-of-line characters)) if the enclosing
characters are used):1

If the field separator (the colon in the above example) is not used in the data and if
there is no need to preserve newlines in the input data, then only the field
separator (not the enclosing characters) is required in the input data.

6 Using solidDB data management tools 111

 If your data is fixed-width, then you do not need either the separator or the
enclosing characters.

FIELDS TERMINATED BY
The FIELDS TERMINATED BY clause is used to define the separator character that
distinguishes where fields end in the input file. The character must be specified in
one of the following three ways:
v Surrounded by double quotes, for example, ":"
v Surrounded by single quotes, for example, ':'
v In hexadecimal format, for example, X'3A'
When using hexadecimal format, the quotation marks must be single quotes, not
double quotes.

Note that the FIELDS TERMINATED BY clause specifies a separator, not a true
terminator; the specified character is not required after the last field. For example,
if the colon is the separator, the following two data file formats are equivalent and
valid:
1:2:3:

or
1:2:3

Note that the trailing colon is accepted, but not required, after the final field.

The OPTIONALLY ENCLOSED BY clause is used after the FIELDS TERMINATED

BY clause when the character used to enclose the column data is contained in the
column data itself. Following is a control file example:
FIELDS TERMINATED BY ’,’
OPTIONALLY ENCLOSED BY "’"

In the example above, the separator is a comma.

The single quote is defined as the character that encloses embedded field
separators (commas) in the data file. Note that the OPTIONALLY ENCLOSED BY
clause may use either single or double quotes to delimit the enclosing characters.
The following example:
OPTIONALLY ENCLOSED BY ’(’AND")"

illustrates the use of both single and double quotes for enclose_char in the syntax:
ENCLOSED BY enclose_char [AND enclose_char]

The example is unusual, but its potential for confusion makes it worth noting.

The following example summarizes the use of separators and enclosing characters.
In this example, the ":" (colon) is defined as the separator (FIELDS TERMINATED
BY) and the parentheses are used to enclose the ":" (colon), which is embedded in
the field and should not be interpreted as a separator. The example also contains
two fields, the first of which is VARCHAR and the second of which is INTEGER.

Data File Example

(This colon : is enclosed by parentheses and is not a separator):12345

Control File Example

112 IBM solidDB: Administrator Guide

LOAD DATA
CHARACTERSET MSWINDOWS
INFILE ’test6.dat’
INTO TABLE SLTEST
FIELDS TERMINATED BY X’3a’ -- X’3a’ == ’:’
OPTIONALLY ENCLOSED BY ’(’ AND ")"
(
TEXT,
ID
)

POSITION
The POSITION keyword is used to define a field's position in the logical record.
Both the start and the end position must be defined.

NULLIF
The NULLIF keyword is used to give a column a NULL value if the appropriate
field has a specified value. An additional keyword specifies the value the field
must have. The keyword BLANKS sets a NULL value if the field is empty; the
keyword NULL sets a NULL value if the field is the string 'NULL'; the definition
'string' sets a NULL value if the field matches the string 'string'; the definition
'((start : end) = 'string')' sets a NULL value if a specified part of the field matches
the string 'string'.

Using NULLIF keyword with keyword BLANKS

The following example shows the use of the NULLIF keyword with the keyword
BLANKS to set a NULL value if the field is empty. It also shows the use of the
keyword NULL to set a NULL value if the field is the string 'NULL'.
LOAD
INFILE ’test7.dat’
INTO TABLE SLTEST
FIELDS TERMINATED BY ’,’
(
NAME VARCHAR NULLIF BLANKS,
ADDRESS VARCHAR NULLIF NULL,
ID INTEGER NULLIF BLANKS
)

Using NULLIF keyword with keyword BLANKS

The following example uses the definition '((start : end) = 'string')' for the third
field in the input file. This syntax only works with fixed-width fields because the
exact position of the 'string' must be specified.
LOAD
INFILE ’7b.dat’
INTO TABLE t7
(
NAME CHAR(10) POSITION(1:10) NULLIF BLANKS,
ADDRESS CHAR(10) POSITION(11:20) NULLIF NULL,
ADDR2 CHAR(10) POSITION(21:30) NULLIF((21:30)=’MAKEMENULL’)
)

Note that in this example, the string is case sensitive. 'MAKEMENULL' and
'makemenull' are not equivalent.

6 Using solidDB data management tools 113

solidDB Export (solexp)
solidDB Export (solexp) is a tool for exporting data from a solidDB database into
files. solidDB Export produces two types of files for each table:
v data file (<tablename>.dat) that contains the exported data
v control file (<tablename>.ctr) the specifies the format of the data file

The default file name is the same as the exported table name.

solidDB Speed Loader can use the data and control files to load data into a
solidDB database.

Note:

The user name used for performing the export operation must have SELECT rights
on the table exported. Otherwise no data is exported.

Starting solidDB Export (solexp)

Start solidDB Export with the command solexp, followed by argument options.

If you start solidDB Export without any arguments, a summary of the arguments
with a brief description is displayed.

The syntax for starting solexp is:

solexp [options] [network_name] username [password] {tablename | *}

where
v options can be:
Table 33. solexp command options

Option Syntax Description

-c dir Change working directory

-C catalog_name Set the default catalog from where data is read from or written to

-e sql_string Execute SQL string for export

-f filename Execute SQL string from file for export

-l filename Write log entries to this file

-L filename Append log entries to this file

-m v In Unicode databases (General.InternalCharEncoding=UTF8),
expect the data in character and wide character data type columns
to be encoded in the console's locale/codepage, despite the settings
in the server-side and client-side character data binding
parameters.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded
in the console's locale/codepage, despite the settings in the
server-side and client-side character data binding parameters. Data
in character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for
more information.

114 IBM solidDB: Administrator Guide

Table 33. solexp command options (continued)

Option Syntax Description

-M locale_name v In Unicode databases (General.InternalCharEncoding=UTF8),
expect the data in character and wide character data type columns
to be encoded in the specified locale/codepage.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded
in the specified locale/codepage. Data in character data type
columns is not converted.
The format of locale_name depends on the operating system.
For example, in Linux environments, the locale name for the code
page GB18030 in Chinese/China is zh_CN.gb18030.
In Windows environments, the locale name for Latin1 code page in
Finnish/Finland is fin_fin.1252.
See section “Using solidDB tools with Unicode” on page 120 for
more information.

-o filename Write exported data to this file

This option can be used only when exporting the data of a single
table.

The default data and control file name is the same as the exported
table name (<tablename>.dat and <tablename>.ctr).

-p Preserve case of schema and table names

-s schema_name Use only this schema for export

-S Create SQL insert into clauses

-A Add attribute names to insert clause
-u v In Unicode databases (General.InternalCharEncoding=UTF8),
expect the data in character and wide character data type columns
to be encoded in UTF-8.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded
in UTF-8. Data in character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for
more information.

-x pwdfile: filename Read password from the file

-h, -?
Help = Usage

v network_name is the network name of a solidDB server that you are connected
to.
The given network name must be enclosed in double quotation marks. Refer to
5, “Managing network connections,” on page 81 for further information.

Tip: Logical data source names can also be used with the solidDB tools.
v username is required to identify the user and to determine the user's
authorization. Without appropriate rights, command execution is denied.
v password is the user's password for accessing the database. The password is
– mandatory, if the password is not read from a file (defined with option -x
pwdfile: filename)
– optional, if the password is read from a file

6 Using solidDB data management tools 115

 v tablename or * is mandatory.
The symbol * can be used to export all tables with one command. However, it
cannot be used as a wildcard.
In some environments you might need to escape the * with double quotation
marks ("*").

Note: The -t tablename (Export table) option is still supported in order to

keep old scripts valid.

Example
solexp -CMyCatalog -sMySchema -ofile.dat "tcp 1315" MyID My_pwd MyTable

Error messages
v When there is an error in the command line entry, solexp gives you a list of the
possible syntax options as a result. Check your entries on the command line.
v Username, password and table name are always expected:
For example, with the command
solexp "tcp 1315" dba dba
you may receive a SOLID Communication Error 21306. This is because there was
no server listening to the environment-dependent default. In this case, solexp
assumes:
– "tcp 1315" is the username
– dba is the password
– dba is the table name
In this case, the correct command is, for example:
solexp "tcp 1315" dba dba myTable
v If you omit the name of the schema, you may get a message saying that the
specified table could not be found. The solexp program cannot find the table if
it does not know which schema to look in.

solidDB Data Dictionary (soldd)

solidDB Data Dictionary (soldd) is a tool for retrieving data definition statements
from a solidDB database.

solidDB Data Dictionary produces an SQL script that contains data definition
statements describing the structure of the database. The generated script contains
definitions for tables, views, indexes, triggers, procedures, sequences, publications,
and events.

The default file name is soldd.sql.

Note:
1. User and role definitions are not listed for security reasons.
2. The user name used for performing the export operation must have select
right on the tables. Otherwise the connection is refused.
Related concepts:
“Troubleshooting solidDB Data Dictionary (soldd)” on page 153

Starting solidDB Data Dictionary (soldd)

Start solidDB Data Dictionary (soldd) with the command soldd.

116 IBM solidDB: Administrator Guide

 If you start solidDB Data Dictionary with no arguments, you will see a summary
of the arguments with a brief description of their usage.

The syntax for starting soldd is:

soldd [options] [network_name] username [password] {tablename

where
v options can be:
Table 34. soldd command line options

Option Syntax Description

-c dir Change working directory

-C catalog_name Set the default catalog from where data definitions are read from or
written to

-h, -? Help = Usage

-m v In Unicode databases (General.InternalCharEncoding=UTF8), expect the
data in character and wide character data type columns to be encoded
in the console's locale/codepage, despite the settings in the server-side
and client-side character data binding parameters.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded in
the console's locale/codepage, despite the settings in the server-side and
client-side character data binding parameters. Data in character data
type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for more
information.
-M locale_name v In Unicode databases (General.InternalCharEncoding=UTF8), expect the
data in character and wide character data type columns to be encoded
in the specified locale/codepage.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded in
the specified locale/codepage. Data in character data type columns is
not converted.
The format of locale_name depends on the operating system.
For example, in Linux environments, the locale name for the code page
GB18030 in Chinese/China is zh_CN.gb18030.
In Windows environments, the locale name for Latin1 code page in
Finnish/Finland is fin_fin.1252.
See section “Using solidDB tools with Unicode” on page 120 for more
information.

-o filename Write data definitions to this file

-O filename Append data definitions to this file

-p Preserve case of schema and table names

-s schema_name List definitions from this schema only

6 Using solidDB data management tools 117

Table 34. soldd command line options (continued)

Option Syntax Description

-u v In Unicode databases (General.InternalCharEncoding=UTF8), expect the
data in character and wide character data type columns to be encoded
in UTF-8.
v In partial Unicode databases (General.InternalCharEncoding=Raw),
expect the data in wide character data type columns to be encoded in
UTF-8. Data in character data type columns is not converted.
See section “Using solidDB tools with Unicode” on page 120 for more
information.

-x tableonly List table definitions only

-x indexonly List index definitions only

-x viewonly List view definitions only

-x sequenceonly List sequence definitions only

-x procedureonly List procedure definitions only

-x publicationonly List publication definitions only

-x eventonly List event definitions only

-x triggeronly List trigger definitions only

-x schemaonly List schema definitions only

-x hiddennames List internal constraint names only

-x pwdfile: filename Read password from the file

v network_name is the network name of a solidDB server that you are connected
to.
The given network name must be enclosed in double quotation marks. Refer to
5, “Managing network connections,” on page 81 for further information.

Tip: Logical data source names can also be used with the solidDB tools.
v username is required to identify the user and to determine the user's
authorization. Without appropriate rights, command execution is denied.
v password is the user's password for accessing the database. The password is
– mandatory, if the password is not read from a file (defined with option -x
pwdfile: filename)
– optional, if the password is read from a file

Note:
v If no table name is given, all definitions to which the user has rights are listed.
v If the objectname parameter is provided with one of the -x options, the name is
used to print only the definition of the named object.
v The -t tablename option is still supported in order to keep old scripts valid.

118 IBM solidDB: Administrator Guide

 Error messages

When there is an error in the soldd startup command line, soldd gives you a list of
the possible syntax options as a result. Check the command line you entered.

solidDB Data Dictionary examples

soldd -odatabase.sql "tcp database_server 1313" dbadmin f1q32j4

Print the definition of procedure TEST_PROC:

soldd -x procedureonly " " dba dba TEST_PROC
Related concepts:
“Troubleshooting solidDB Data Dictionary (soldd)” on page 153

Entering password from a file

User identification information is typically entered as plain text, for example in the
solidDB startup command or solidDB data management tools. However, you can
enter the password from a file. When entered in a file, the password cannot be
seen by running the UNIX command ps.

The syntax is as follows:

command -x pwdfile:filename

where
v command can be any of the following:
– solcon
– soldd
– solexp
– solid
– solload
– solloado
– solsql
v filename can be either absolute or relative to the working directory

Password file

In the file where the password is stored, the first character string ending at newline
character is read and considered as the password. Preceding space and newline
characters are ignored. If the password includes space or newline characters, it
must be enclosed in single or double quotation marks. However, using quotation
marks means that quotation mark and backslash characters that belong to the
password must be escaped by a backslash character.

Examples
solsql -x pwdfile:userpwd "tcp solsrv 1313" dba
solid -f -c soldb -x pwdfile:solpwd -U dba

Configuration file
A configuration file is not required for solidDB Speed Loader. The configuration
values for the server parameters are included in the solidDB configuration file
solid.ini.

6 Using solidDB data management tools 119

 Client copies of this file can be made to provide connection information required
for solidDB Speed Loader. If no server name is specified in the command line,
solidDB Speed Loader will choose the server name it will connect to from the
server configuration file.

For example, to connect to a server using the UNIX Pipes protocol and with the
server name solidDB, the following lines are needed in the configuration file:
[Com]
Connect=upipe SOLIDDB

Using solidDB tools with Unicode

This section contains information about how to use the solidDB tools with Unicode
and non-Unicode databases.

The following solidDB tools can be used to output and import data in the system
default locale or a specified locale in both Unicode and partial Unicode databases.
v solidDB SQL Editor (solsql)
v solidDB Data Dictionary (soldd)
v solidDB Export (solexp)
v solidDB Speed Loader (solloado)

solidDB Remote Control (solcon) does not support conversions of data to UTF-8.
For example, if an error message that is output to solcon contains Unicode
encoded data, it is not displayed correctly in the console.

The locale to be used in conversions is defined with the command line options
when starting the tool.

Important:
v The solidDB tools use the solidDB ODBC API 3.5.1; this means that if the
binding method for character data types is defined with the server-side
Srv.ODBCDefaultCharBinding or client-side Client.ODBCCharBinding parameters,
this setting also impacts the behavior of the solidDB tools.
v The Unicode and partial Unicode databases behave differently in reference to
conversions of CHAR and WCHAR data types:
– Unicode databases
Both CHAR and WCHAR data types are converted between the
UTF-8/UTF-16 format in solidDB and the locale/codepage defined with the
chosen binding method.
– partial Unicode databases
CHAR data types are not converted; instead, they are handled in the raw
(binary) format that is used to store CHAR data in partial Unicode databases.
WCHAR data types are converted between the UTF-16 format in solidDB and
the locale/codepage defined with the chosen binding method.

120 IBM solidDB: Administrator Guide

 Table 35. Command line options for solidDB tools for partial Unicode and Unicode
databases
Option Description
No option/Factory The console locale setting is used, unless overridden with the
setting server-side or client-side parameters in the solid.ini file.
Note: If the server-side Srv.ODBCDefaultCharBinding or client-side
Client.ODBCCharBinding parameter is set to UTF8, the locale of the
console must support UTF-8.
-m The console locale setting is used, despite the server-side or
client-side parameters in the solid.ini file.
-M<locale_name> The locale console setting is overridden with the locale defined
with <locale_name>. The <locale_name> depends on the operating
system.

For example, in Linux environments, the locale name for the code
page GB18030 in Chinese/China is zh_CN.gb18030.

In Windows environments, the locale name for Latin1 code page

in Finnish/Finland is fin_fin.1252.
-u Input/output is forced to UTF-8.

Note: If the server-side or client-side parameters in the solid.ini file are set to use
'Raw' binding, you should always use the -m, -M or -u option to override the
solid.ini settings.

Example: Reloading a database using solidDB tools

This example demonstrates how a solidDB database can be reloaded to a new one
using the solidDB tools.

The database reload procedure can be useful, for example, for minimizing the
database file size by removing gaps (unused space) that are created during delete
and update operations; the reload rewrites the database without gaps.

Overview:
1. Extract data definitions from the old database.
2. Extract data from the old database.
3. Replace the old database with a new one.
4. Load data definitions into a new database.
5. Load data into the new database.

Reloading the database: Walkthrough

In this example, the server name is solidDB and the protocol used for connections
is TCP/IP, using port 1964 (network name is "tcpip 1964"). The database has been
created with the user name "dbadmin" and the password "password".
1. Data definitions are extracted with solidDB Data Dictionary (soldd).
Use the following command to extract an SQL script containing definitions for
all tables, views, triggers, indexes, procedures, sequences, and events.
soldd "tcpip 1964" dbadmin password
The soldd command lists all data definitions into one SQL file; the default file
name is soldd.sql.

6 Using solidDB data management tools 121

 Note: User and role definitions are not listed for security reasons. If the
database contains users or roles, they must be appended into the extracted SQL
file.
2. All data is extracted with solidDB Export (solexp).
Use the following command to extract the control and data files for all tables.
solexp "tcpip 1964" dbadmin password *
The export creates control files (table_name.ctr) and data files
(table_name.dat) for each table. The default file name is the same as the
exported table name. In 16-bit environments, file names longer than eight
letters are concatenated.
3. A new database is created to replace the old one.
You can create a replacement database by deleting the solid.db and all
sol#####.log files from the appropriate directories. When solidDB is started for
the first time after this, a new database is created.

Note: It is recommended that a backup is created of the old database before it

is deleted. This can be done using solidDB Remote Control (solcon).

Use the following command to create a backup using solcon:

solcon -eBACKUP "tcpip 1964" dbadmin password

The option -e precedes an administration command.

4. Data definitions are imported into the new database using the solidDB SQL
Editor (solsql).
Use the following command to execute the SQL script created by solidDB Data
Dictionary (soldd).
solsql -fSOLDD.SQL "tcpip 1964" dbadmin password
This command loads the data definitions into the new, empty database.
Definitions are retrieved with the option -f from the file soldd.sql. Connection
parameters are the same as in the earlier examples.

Tip: The previous two steps can be performed together by starting solidDB
with the following command:
solid -Udbadmin -Ppassword -x execute:soldd.sql
The option -x creates a new database, executes commands from a file, and
exits. The -U and -P options define the username and password.
5. Data is loaded into the new database using the solidDB Speed Loader
(solload).
Use the following command to load data into the new database:
solload "tcpip 1964" dbadmin password table_name.ctr

Tip: In UNIX environments, the wildcard symbol * can be used.

To load several tables into the database, a batch file containing a separate
command line for each table is recommended.
The following type of batch files can be used:
v Shell scripts in UNIX environments
v .bat scripts in Windows environments

122 IBM solidDB: Administrator Guide

7 Performance tuning
This section discusses techniques that you can use to improve the performance of
solidDB.

Tip: The following parameters help you improve database performance or balance
performance against safety. These parameters are discussed in more detail in
Appendix A, “Server-side configuration parameters,” on page 165.
v IsolationLevel
v DurabilityLevel
v DefaultStoreIsMemory

For tips on optimizing solidDB advanced replication, see the IBM solidDB Advanced
Replication User Guide.

Logging and transaction durability

This chapter discusses transaction durability from a theoretical perspective. For
more information about choosing the transaction durability level and setting it,
refer to IBM solidDB SQL Guide.

Standards compliance

Transaction durability is not part of the ANSI standard for SQL-99.

Background
When a transaction is committed, the database server writes data to two locations:
the database file, and the transaction log file. However, the data is not necessarily
written to those two locations at the same time. When a transaction is committed,
the server normally writes the data to the transaction log file immediately — that
is, as soon as the server commits the transaction. The server does not necessarily
write the data to the database file immediately. The server may wait until it is less
busy, or until it has accumulated multiple changes, before writing the data to the
database file.

If the server shuts down abnormally (due to a power failure, for example) before
all data has been written to the database file, the server can recover 100% of
committed data by reading the combination of the database file and the transaction
log file. Any changes since the last write to the database file are in the transaction
log file. The server can read those changes from the log file and then use that
information to update the database file. The process of reading changes from the
log file and updating the database file is called recovery. At the end of the recovery
process, the database file is 100% up to date.

The recovery process is automatically executed always when the server restarts
after an abnormal shutdown. The process is generally invisible to the user (except
that there may be a delay before the server is ready to respond to new requests).

To have 100% recovery, you must have 100% of the transactions written to the log
file. Normally, the database server writes data to the log file at the same time that
the server commits the data. Thus committed transactions are stored on disk and

123
 will not be lost if the computer is shut down abnormally. This is called strict
durability. The data that has been committed is durable, even if the server is shut
down abnormally.

With strict durability, the user is not told that the data has been committed until
AFTER that data was successfully written to the transaction log on disk — this
ensures that the data is recoverable if the server shuts down abnormally. Strict
durability makes it almost impossible to lose committed data unless the hard disk
drive itself fails.

If durability is relaxed, the user may be told that the data has been committed even
before the data has been written to the transaction log on disk. The server may
choose to delay writing the data, for example, by waiting until there are several
transactions to write. If durability is relaxed, the server may lose a few committed
transactions if there is a power failure before the data is written to disk.

solidDB allows to control the durability level in variety of ways. For the
server-wide setting, the parameter Logging.DurabilityLevel may take three values:
3 (for 'strict"), 1 (for "relaxed") and 2 (for "adaptive").

Adaptive durability is meant for HotStandby operation. If durability is adaptive, the

server follows the rules below:
v If the server is a Primary server in a HotStandby system, and if the Secondary is
active, then the server (Primary server) uses relaxed durability;
v In all other situations, the server uses strict durability.

Note:
v The above behavior is observed only if the value of the [HotStandby] parameter
SafenessLevel is set to 2safe (default). If this parameter is set to any other value,
the server uses relaxed durability in all cases.
v If HotStandby is not enabled, the "adaptive" setting is treated as 'strict".

Balancing performance and safety

Historically, the goal of most database servers has been to maximize safety, that is,
to make sure that data is not lost due to a power failure or other problems. These
database servers use 'strict durability". This approach is appropriate for many
types of data, such as accounting data, where it is often unacceptable to lose track
of even a single transaction.

Some database servers have been designed to maximize performance, without

regard to safety. This is acceptable in situations where, for example, you only need
to sample data, or where the server can simply operate on the most recent set of
data, regardless of the size of that set. As an example, suppose that you have a
server that contains statistical data about performance — for example, which
computers experience the heaviest loads at particular times of the day. You might
use such information to balance the load on your computers. This information
changes over time, and "old" data is less valuable than "new" data. In fact, you
might completely discard any data that is more than a week old. If you were to
lose the performance and load balancing data, then your system would still
function, and within a week you would have acquired a complete set of new data
(assuming that you normally discard data older than one week). In this situation,
occasional or small data loss is acceptable, and performance may be more
important.

124 IBM solidDB: Administrator Guide

 solidDB allows you to specify whether you want logging to be 'strict" to guarantee
that all committed data can be recovered after an unexpected shutdown, or
"relaxed" to allow some recent transactions to be lost in some circumstances.

How relaxed transaction durability can improve performance

You can increase performance by telling the server that it does not necessarily have
to write to the log file at the same time that it commits data. This allows the server
to write to the log file later, perhaps when the server is less busy, or when several
transactions can be written at once. This is called " relaxed durability". It increases
performance by decreasing the I/O (Input/Output) load.

If you set the transaction durability level to "relaxed", you risk losing some data if
the server shuts down abnormally after it has committed some data but before it
has written that data to the transaction log. If you use relaxed durability, some
transactions may not have been written to the log file yet, even though those
transactions were committed. Therefore, you should use relaxed durability ONLY
when you can afford to lose a small amount of recent data.

If you want to set a maximum delay time before the server writes data, use the
Logging.RelaxedMaxDelay parameter.

Choosing transaction isolation levels

Concurrency control is based on an application's requirements. Some applications
need to execute as if they had exclusive ownership of the database. Other
applications can tolerate some degree of interference from other applications
running simultaneously. To meet the needs of different applications, the SQL-92
standard defines four levels of isolation for transactions. By principle, solidDB
cannot read uncommitted data. The reason is that it sacrifices the consistent view
and potentially also database integrity.

The three supported isolation levels are explained below.

v Read Committed
This isolation level allows a transaction to read only committed data.
Nonetheless, the view of the database may change in the middle of a transaction
when other transactions commit their changes.
v Repeatable Read
This isolation level allows a transaction to read only committed data and
guarantees that read data will not change until the transaction terminates.
solidDB additionally ensures that the transaction sees a consistent view of the
database. When using optimistic concurrency control, conflicts between
transactions are detected by using transaction write-set validation. This means
that the server validates only write operations, not read operations. For example,
if a transaction involves one read and one update, solidDB validates that no one
has updated the same row in between the read operation and the update
operation. In this way, lost updates are detected, but the read is not validated.
With transaction write-set validation, phantom updates may occur and
transactions are not serializable.
v Serializable
This isolation level allows a transaction to read only committed data with a
consistent view of the database. Additionally, no other transaction may change
the values read by the transaction before it is committed because otherwise the
execution of transactions cannot be serialized in the general case.

7 Performance tuning 125

 solidDB can provide serializable transactions by detecting conflicts between
transactions. It does this by using both write-set and read-set validations.
Because no locks are used, all concurrency control anomalies are avoided,
including the phantom updates. This feature is enabled by using the command
SET TRANSACTION ISOLATION LEVEL SERIALIZABLE, which is described in
solidDB SQL SyntaxAppendix: "solidDB SQL Syntax" in the IBM solidDB SQL
Guide.

Note: The SERIALIZABLE isolation level is available for disk-based tables only.

Setting the isolation level

To set the isolation level, use one of the following SQL commands:
SET ISOLATION LEVEL
{READ COMMITTED | REPEATABLE READ | SERIALIZABLE}
SET TRANSACTION ISOLATION LEVEL
{READ COMMITTED | REPEATABLE READ | SERIALIZABLE}

For example:
SET ISOLATION LEVEL REPEATABLE READ;
SET TRANSACTION ISOLATION LEVEL REPEATABLE READ;

Note that solidDB supports both "transaction-level" and 'session-level" isolation

level commands. For more details, see the descriptions in IBM solidDB SQL Guide,
Appendix: solidDB SQL syntax.

Controlling memory consumption

solidDB allocates main memory dynamically according to system usage and the
operating system environment. The basic element of the memory management
system is a pool of central memory buffers of equal size. You can configure the
amount and size of memory buffers to meet the demands of different application
environments.

Note: Immediately after solidDB startup, the reported process size in Windows
operating systems is significantly smaller than the actual allocated size. This is
because cache pages are allocated at this stage, but excluded them from the process
size until they are used for the first time. In UNIX operating systems, the cache
pages are included thus the reported process size is bigger than in Windows
operating systems.

Controlling process size

The process size does not directly correspond to the actual database memory
consumption, because the process size contains also non-database elements. The
process size includes the following elements:
v Cache size – The factory value is 32 Mbytes.
v The code footprint is approximately 3 Mbytes, but it initializes different libraries
and can grow up to 8 Mbytes.
v Client threads – Each client consumes a few hundred kilobytes of main memory.
v Dynamic memory reserved for command handling – The allocation deals with
execution plans, temporary data, and so on.
v Statement cache – When solidDB executes SQL statements, it parses and
optimizes them first. This can be time consuming. The server can store the
parsed and optimized statements in the virtual memory. This is called the
statement cache.

126 IBM solidDB: Administrator Guide

v The hash table for the transaction lookup table – The LockHashSize parameter
affects the memory consumption. This parameter defines the number of
elements in the lock hash table.
v Transaction and sort buffers
v The accessed tables are also buffered in the main memory.

You can control the process size by using the ADMIN COMMAND and parameters
presented in the following sections. The violations of process limits are logged in
the solmsg.out log file.

ADMIN COMMAND 'info processsize';

The ADMIN COMMAND 'info processsize'; command returns the current amount of
memory that the in-memory database process uses. The value returned is a
VARCHAR, and it indicates the number of kilobytes used by the process. Note that
this returns the amount of virtual memory used, not the amount of physical
memory used.

Srv.ProcessMemoryLimit
The Srv.ProcessMemoryLimit parameter specifies the maximum amount of virtual
memory that can be allocated to the in-memory database process.

The factory value for Srv.ProcessMemoryLimit is 0; there is no process memory

limit. If you use the parameter, set it to a value that will ensure that the in-memory
database process will fit entirely within physical memory. The following factors
impact the amount of memory needed:
v the amount of physical memory in the computer
v the amount of memory used by the operating system
v the amount of memory used by in-memory tables (including temporary tables
and transient tables) and the indexes on those in-memory tables
v the amount of memory set aside for the solidDB server's cache (the
IndexFile.CacheSize parameter)
v the amount of memory required by the connections, transactions and statements
running concurrently in the server. The more concurrent connections and active
statements there are in the server, the more working memory the server requires.
Typically, you should allocate at least 0.5 MB of memory for each client
connection in the server.
v the memory used by other processes (programs and data) that are running in the
computer

When the limit is reached, that is, when the in-memory database process uses up
100% of the memory specified by Srv.ProcessMemoryLimit, the server will accept
ADMIN COMMANDs only. You can use the Srv.ProcessMemoryWarningPercentage
and Srv.ProcessMemoryLowPercentage parameters to warn you about increasing
process memory consumption.

Note:
v The Srv.ProcessMemoryLimit and Srv.ProcessMemoryCheckInterval parameters
are interlinked; if the ProcessMemoryCheckInterval parameter is set to 0, the
ProcessMemoryLimit parameter is not effective, that is, there is no process
memory limit.
v You should not set the Srv.ProcessMemoryLimit parameter when using SMA. If
you need to limit the memory the SMA server uses, use the
SharedMemoryAccess.MaxSharedMemorySize parameter.

7 Performance tuning 127

 Srv.ProcessMemoryLowPercentage
The Srv.ProcessMemoryLowPercentage parameter sets a warning limit for the total
process size. The limit is expressed as percentage of the Srv.ProcessMemoryLimit
parameter value.

Prior to exceeding the limit, you have exceeded the warning limit defined with the
ProcessMemoryWarningPercentage parameter and received a warning. When the
Srv.ProcessMemoryLowPercentage limit is exceeded, a system event is given.

The limit set with Srv.ProcessMemoryLowPercentage must be higher than the

Srv.ProcessMemoryWarningPercentage limit. For example, if the
Srv.ProcessMemoryWarningPercentage is set to 82, the
Srv.ProcessMemoryLowPercentage value must be at least 83.

Srv.ProcessMemoryWarningPercentage
The Srv.ProcessMemoryWarningPercentage parameter sets the first warning limit for
the total process size. The warning limit is expressed as percentage of the
Srv.ProcessMemoryLimit parameter value.

When the Srv.ProcessMemoryWarningPercentage limit is exceeded, a system event

is given.

The limit set with Srv.ProcessMemoryWarningPercentage must be lower than the

Srv.ProcessMemoryLowPercentage limit.

Srv.ProcessMemoryCheckInterval
The Srv.ProcessMemoryCheckInterval parameter defines the interval for checking
the process size limits. The interval is given in milliseconds.

The minimum non-zero value for Srv.ProcessMemoryCheckInterval is 1000 (ms).

Only values 0, 1000, or above 1000 (1 second) are allowed. If the given value is
above 0 but below 1000, an error message is given.

The factory value is 0, that is, the process size checking is disabled.

The Srv.ProcessMemoryLimit and Srv.ProcessMemoryCheckInterval parameters are

interlinked; if the ProcessMemoryCheckInterval parameter is set to 0, the
ProcessMemoryLimit parameter is not effective, that is, there is no process memory
limit.

Tuning your operating system

Your operating system may store information in:
v real (physical) memory
v virtual memory
v expanded storage
v disk

Your operating system may also move information from one location to another.
Depending on your operating system, this movement is called paging or
swapping. Many operating systems page and swap to accommodate large amounts
of information that do not fit into real memory. However, this takes time. Excessive
paging or swapping can reduce the performance of your operating system and
indicates that your system's total memory may not be large enough to hold

128 IBM solidDB: Administrator Guide

 everything for which you have allocated memory. You should either increase the
amount of total memory or decrease the amount of database cache memory
allocated.

Database cache
The information managed by solidDB is stored either in memory or on disk. Since
memory access is faster than disk access, it is desirable for data requests to be
satisfied by access to memory rather than access to disk.

Defining database cache size

Database cache uses available memory to store information that is read from the
hard disk, in a disk-based database. It is also used to buffer the database pages
while the server is executing the checkpoint -- equally in a disk based and an
in-memory database. When an application next time requests this information, the
data is read from memory instead of from the hard disk. The default value of
cache depends on the platform used and can be changed through the CacheSize
parameter. Increasing the value is recommended when there are several concurrent
users.

If a database is primarily disk-based, the following estimates can be used:

v 0.5 MB per each concurrent user of the system

or
v 2-5% of the database size,

When estimating the necessary cache size by using the values above, use the larger
value. If the database is purely an in-memory database, the factory value will
suffice. When decreasing the cache size, note that in order to facilitate efficient
checkpoint activity, the size should not be less than 8 MB.

You should increase the value of CacheSize carefully. If the value is too large, it
leads to poor performance because the server process does not fit completely in
memory and therefore swapping of the server code itself occurs. If, on the other
hand, the cache size is too small, the cache hit rate remains poor. The symptoms of
poor cache performance are database queries that seem to be slower than expected
and excessive disk activity during queries.

You can verify if the server is retrieving most of the data from disk instead of from
RAM by checking the cache hit rate using the command ADMIN COMMAND ’status’
or by checking the overall cache and file ratio statistics using ADMIN COMMAND
’perfmon’. For details on these commands, read “Performance counters (perfmon)”
on page 67 and “Checking overall database status” on page 65. Note that the cache
hit rate should be better than 95%.

Dynamically changing database cache size

You can change the CacheSize value dynamically as follows:

admin command 'parameter IndexFile.CacheSize=40mb'

Note:

The cache size cannot be decreased.

solidDB uses a hash table to ease access to the cache. The hash table size equals
the number of pages in the cache. This guarantees almost collision-free access. If

7 Performance tuning 129

 the cache size is increased dynamically, the hash table is not automatically
enlarged. This results in a higher collision probability. To avoid this, you can use
the ReferenceCacheSizeForHash parameter to accommodate the enlarged cache. The
ReferenceCacheSizeForHash parameter value is used for calculating the cache hash
table size. You should only use the parameter if you know, in advance, what will
be the maximum cache size during the server lifecycle. On the other hand, if the
value is not given, hash table collisions may occur when the cache size is
increased.

Note:

The ReferenceCacheSizeForHash parameter value must not be smaller than the

CacheSize value. If it is, the ReferenceCacheSizeForHash parameter value is rejected
and the default value is used. Also, a message is printed to the solmsg.out log file.

Sorting
When the solidDB SQL Optimizer chooses an execution plan, it considers the
performance impact of sorting data. Sorting occurs if the result set is not returned
automatically in the correct order. If sorting is needed, the Optimizer chooses
whether to use the internal sorter or the external sorter. The internal sorter is used
with small result sets (hundreds of rows) while the external sorter is used with
large result sets (thousands of rows).

Sorting occurs when no index satisfies the requested ordering of fetched rows; if
the table data is accessed using the primary key or index, the result set is
automatically in the order specified by the index in use. Hence, you can improve
server performance by designing primary keys and indexes to support the
ordering requirements of frequently used, performance-critical queries.

Note: Some queries require sorting implicitly. For example, if the optimizer
chooses a JOIN operation to use the MERGE JOIN algorithm, the result sets to be
joined require sorting before the join can occur.

Internal sorter

The internal sorter performs all sorting in the main memory. The amount of
memory used for sorting is defined with the SQL.SortArraySize parameter; the
parameter value defines the size of the array (in rows) that is used for ordering the
result set of a query. For example, if you specify a value of 1000, the server will
create an array big enough to sort 1000 rows of data. If the amount of data to be
sorted does not fit into the allocated memory, increase the value of the parameter
SQL.SortArraySize.

External sorter

If the sorting task does not fit in the main memory (typically with large result
sets), the Optimizer uses the external sorter, which stores intermediate information
to disk. The external sorter is enabled by default (Sorter.SorterEnabled=yes).

The temporary files used by the external sort are created in a directory or
directories specified with the Sorter.TmpDir_N parameter. The files are deleted
automatically after sorting has finished.

130 IBM solidDB: Administrator Guide

 To achieve better performance, the external sort files can be stored to a local drive
using local disk names. This avoids network I/O and balances the I/O load to
multiple disks. For example,
[Sorter]
TmpDir_1 = c:\tmp
TmpDir_2 = d:\tmp
TmpDir_3 = e:\tmp

An external sort requires space both on disk and in memory, not just space on the
disk. You can configure the maximum amount of memory used for sorting with
the Sorter.MaxMemPerSort and Sorter.MaxCacheUsePercent parameters.

Querying and controlling Optimizer's sorter decisions

You can query the Optimizer decisions for sorting using the EXPLAIN PLAN FOR
statement.

If the Optimizer is not choosing the optimal query execution plan, you can
override the Optimizer decision by using optimizer hints. For more information,
see Hints in the IBM solidDB Programmer Guide.

Additionally, the performance counters with the prefix Sorter provide information
on the external sorter tasks. To view the Sorter performance counters, issue the
following command:
ADMIN COMMAND ’pmon sorter’

For example, high values of the Sorter start sort counter indicate excessive use of
the external sorter. If you have enough memory available, you can increase the
value of the SQL.SortArraySize parameter to avoid the use of the external sorter.

Using in-memory database

The solidDB database products use two integrated database engines: one is a
traditional disk-based engine and the other is a main memory engine allowing to
create tables that reside permanently in main memory. Also the indexes created for
those tables are stored totally in main memory. When using the in-memory
database capability you may choose, for each table, which is the storage for the
table: disk or memory. A solidDB server process running in-memory tables is
significantly larger than a purely disk-based server process. To evaluate the
amount of memory required by the in-memory tables and their indexes, refer to
IBM solidDB In-Memory Database User Guide.

Tuning network messages

You can improve solidDB performance in reading large result sets by instructing a
solidDB server to return several result set rows in one network message. To
activate this functionality, you edit one or both of the following parameters in the
[Srv] section of the solidDB server's solid.ini configuration file.
v RowsPerMessage: The default value is 10.
v ExecRowsPerMessage: The default value is 2.

For more information about these two parameters, see Appendix A, “Server-side
configuration parameters,” on page 165.

7 Performance tuning 131

Tuning I/O
The performance of many software systems is inherently limited by disk I/O.
Often CPU activity must be suspended while I/O activity completes.

Distributing I/O
Disk contention occurs when multiple processes try to access the same disk
simultaneously. To avoid this, move files from heavily accessed disks to less active
disks until they all have roughly the same amount of I/O.

Follow these guidelines:

v Use a separate disk for log files.
v Divide your database into several files and place each of these database files on
a separate disk. Read “Managing database files and caching (IndexFile section)”
on page 53.
v Consider using a separate disk for the external sorter

It is usually faster to scan a table if the disk file is contiguous on the disk, rather
than spread across many non-contiguous disk blocks. To reduce existing
fragmentation, you may want to run defragmentation software if one is available
on your system. If your database file is growing, you may be able to reduce future
file fragmentation by using the configuration parameter ExtendIncrement.
Increasing the size of this parameter tells the server to allocate larger amounts of
disk space when it runs out of space. (Note that this does not guarantee contiguity
because the operating system itself may allocate non-contiguous sectors to satisfy
even a single request for more space.) As a general rule, larger values of
ExtendIncrement improve performance slightly, while smaller values keep the
database size slightly smaller. See Appendix A, “Server-side configuration
parameters,” on page 165, for more details about ExtendIncrement.

Setting the MergeInterval parameter

solidDB's indexing system consists of two storage structures:
v the Bonsai Tree, which stores new data in central memory, and
v the main storage tree, which stores more stable data.

As the Bonsai Tree performs concurrency control, storing delete, insert, and update
operations, as well as key values, it merges new committed data to the storage tree
as a highly-optimized batch insert. This offers significant I/O optimization and
load balancing.

You can adjust the number of index inserts made in the database that causes the
merge process to start by setting the following parameter in the General section of
the solid.ini file. For example:
MergeInterval = 1000

Normally the recommended setting is the default value, which is cache size
dependent. The default is calculated dynamically from the cache size, so that only
part of the cache is used for the Bonsai Tree. If you change the merge interval, be
sure that the cache is large enough to accommodate the Bonsai Tree. The longer the
merge interval is (i.e. the more data that is stored in memory before being moved
to the main storage tree), the larger the cache needs to be.

132 IBM solidDB: Administrator Guide

 Note: If the merge interval setting is too big to allow the Bonsai Tree to fit into
cache, then it is flushed partially to the disk; this has an adverse affect on
performance. Hence, avoid setting merge intervals that are too large. On a diskless
system, the Bonsai Tree will fill the available memory and the Diskless server will
run out of memory.

Note: Although the server will have higher performance if merge intervals are
less frequent (i.e. batch inserts are larger), you may also see less consistent
response times. If your highest priority is not overall throughput, but is instead to
minimize the longest response time, then you may want to make merge intervals
more frequent rather than less frequent. More frequent merges will reduce the
worst case delays that interactive users may experience.

For details on detecting and preventing performance problems associated with

Bonsai Tree growth, read “Reducing Bonsai Tree size by committing transactions”
on page 134.

Tuning checkpoints
Checkpoints are used to store a transactionally-consistent state of the database
quickly onto the disk.

Checkpoints affect:
v runtime performance
v recovery time performance

Checkpoints cause solidDB to perform data I/O with high priority, which
momentarily reduces the runtime performance. This overhead is usually small.
Similar to merge intervals, less frequent checkpoints may mean less frequent, but
longer delays before the system responds to interactive queries. More frequent
checkpoints tend to minimize the worst case delays that an interactive user might
experience. However, such delays may be more frequent even if they are shorter.

It is possible to control the execution of checkpoints to prevent them from

occurring during, for example, periods of high user volume. You may:
v Set configuration parameters in the solid.ini file.
– Set the General.CheckpointInterval parameter. The default checkpoint
interval is every 50000 log writes.
– Set the General.MinCheckpointTime parameter.
v Force a checkpoint by using the ADMIN COMMAND ’makecp’ command.

Frequent checkpoints can reduce the recovery time in the event of a system failure.
If the checkpoint interval is small, relatively few changes to the database are made
between checkpoints and consequently, few changes need to be made during
recovery. To speed up recoveries, create checkpoints frequently; however, the server
performance is reduced during the creation of a checkpoint. Furthermore, the
speed of checkpoint creation depends on the amount of database cache used; the
more database cache is used, the longer the checkpoint creation will take. The
database cache size is controlled with the IndexFile.CacheSize parameter.

7 Performance tuning 133

 Related reference:
“General section” on page 168
Related information:
“Creating checkpoints” on page 36
“CacheSize” on page 55
“Logging and transaction durability” on page 123

Reducing Bonsai Tree size by committing transactions

solidDB provides a consistent view of data within one transaction. If a user does
not commit a transaction, solidDB keeps an image of the database as it existed at
the moment the transaction was started — even if the transaction is a read-only
transaction. This is implemented by the multiversioning solidDB Bonsai Tree,
which stores the newest data in central memory. The new data is merged to the
main storage tree as soon as currently active transactions no longer need to see the
old versions of the rows.

When other connections perform many write operations, the server must use a
large amount of memory to provide a consistent image of the database. If an open
transaction remains uncommitted for a long duration of time, solidDB requires
more memory; if the amount of memory available is insufficient, then solidDB
performs excessive paging or swapping, which slows performance.

To determine whether slow performance is caused by excessive Bonsai Tree

growth, you can monitor memory usage and Bonsai Tree size using operating
system specific and solidDB specific tools.

Preventing excessive Bonsai Tree growth

To prevent excessive Bonsai Tree growth, make sure that every database connection
commits every transaction. Even read-only transactions and transactions that
contain only SELECT statements must be committed explicitly. (In autocommit
mode, solidDB ODBC Driver version 3.50 and solidDB JDBC Driver version 2.0
perform an implicit commit after the last open cursor has been closed or dropped.
In previous versions, the implicit commit is not available.)

Note that even in autocommit mode, SELECT statements are not automatically
committed after the data is read. solidDB cannot immediately commit SELECTs
since the rows need to be retrieved by the client application first. Even in
autocommit mode, you must either explicitly commit work, or you must explicitly
close the cursor for the SELECT statement. Otherwise, the SELECT transaction is
left open until the connect timeout expires.

In order to ensure that every transaction is committed, you can:

v Determine what connections currently exist
v Determine when the connections have a committed transaction
v In the application code, ensure that every database operation gets committed
v Check for commit problems when using solidDB APIs

Each of these topics is described in the following sections.

Determining currently existing connections

The following solidDB commands and files allow you to determine the status of
existing connections.

134 IBM solidDB: Administrator Guide

Table 36. Determining command status

Command/File Information

ADMIN COMMAND 'ul' Obtain a list of existing connections.

ADMIN COMMAND 'sta' Obtain the number of existing connections.

solmsg.out Obtain the date and time when new connections are created.

ADMIN COMMAND 'trace on sql' Obtain information when new connections are started. The
results are written to the soltrace.out file.

ADMIN COMMAND 'report filename.txt' Obtain a list of internal variables containing connection and
status information.

Determining when connections have committed transactions

The following solidDB commands and files allow you to determine which
connections have committed transactions.
Table 37. Determining which connections have committed transactions

Command/File Information

ADMIN COMMAND 'trace' Shows if a transaction gets committed at the server

ADMIN COMMAND 'report filename.txt' Obtain a list of internal variables containing connection and
status information. To find out connections that have not
committed their transaction, look for the Readlevel for each
connection. If the transaction at a particular connection is
properly closed, the Readlevel should be zero (0) for that
connection.

To find those statements with active status, look under USER

SEARCHES with column 'Act' having a value of 1. If the active
status remains at the same Readlevel for a lengthy period of
time, this is an indication that the statement has not closed or
committed during this interval.

Providing commit statements in the application code

To make sure every database operation gets committed, be sure to either:
v Execute the statement COMMIT WORK.
v Call ODBC function SQLTransact or SQLEndTran.
v Call JDBC method commit.

Make sure these operations succeed by checking the return code or by properly
catching the possible exception. Be aware how many database connections your
application has, when and where they are created, and when the transactions at
these connections are committed.

Troubleshooting COMMITs when using ODBC Driver Manager

When using ODBC Driver Manager and running in autocommit mode, most
versions of ODBC Driver Manager regard calls to SQLTransact and SQLEndTran as
redundant and never actually pass them to the driver.

This means that the application program only receives return code 'SUCCESS' from
the ODBC Driver Manager, even though no transaction is committed in the

7 Performance tuning 135

 database. This situation may go unnoticed. Besides, ODBC Driver Manager and
SQL Editor, other utilities can also have an open transaction.

Make sure that you are aware of all database connections. Note that each FETCH
after COMMIT (keeping the statement handle alive) also causes a new transaction
to start.

Diagnosing poor performance

There are different areas in solidDB that can result in performance degradation. In
order to remedy performance problems, you need to determine the underlying
cause. Following is a table that lists common symptoms of poor performance,
possible causes, and directs you to the section in this chapter for the remedy.
Table 38. Diagnosing poor performance

Symptoms Diagnosis Solution

v Inefficient usage of indexes in the

Slow response time for a single query. query. If index definitions are missing, create
Other concurrent access to the database is new indices or modify existing ones to
affected. Disk may be busy. v Non-optimal decision from the match the indexing requirements of the
Optimizer. slow query. For more details, read Using
v External sorting is not defined and a indexes to improve query performance.
large internal sorting is causing
excessive swapping to disk. Run the EXPLAIN PLAN FOR statement
for the slow query and verify whether the
query optimizer is using the indices. For
more details, see EXPLAIN PLAN FOR
statement.

If the Optimizer is not choosing the

optimal query execution plan, override
the Optimizer decision by using optimizer
hints. For more details, see Using optimizer
hints.

Slow response time is experienced for all Insufficient cache size. Increase the cache size. Allocate for cache
queries. An increase in the number of at least 0.5 MB per concurrent user or
concurrent users deteriorates the 2-5% of the database size. For more
performance more than linearly. When all details, read the section Defining database
users are thrown out and then cache size in IBM solidDB Administrator
reconnected, performance still does not Guide.
improve.

Slow response time is experienced for all The Bonsai Tree is too large to fit into the Make sure that there are no
queries and write operations. When all cache. unintentionally long-running transactions.
users are thrown out and are connected, Verify that all transactions (also read-only
performance only improves temporarily. transactions) are committed in a timely
The disk is very busy. manner. For more details, read Reducing
Bonsai Tree size by committing transactions
in IBM solidDB Administrator Guide.

v The data is committed to the database

Slow performance during batch write in batches that are too small.
Make sure that the autocommit is
operation as the database size increases. switched off and the write operations are
There is an excessive amount of disk I/O. v Data is written to disk in an order that committed in batches of at least 100 rows
is not supported by the primary key of per transaction.
the table.
Modify the primary keys or batch write
processes so that write operations occur in
the primary key order. For more details,
read Optimizing batch inserts and update.

136 IBM solidDB: Administrator Guide

Table 38. Diagnosing poor performance (continued)

Symptoms Diagnosis Solution

The server process footprint grows SQL statements have not been closed and Make sure that the statements that are no
excessively and causes the operating dropped after use. longer in use by the client application are
system to swap. The disk is very busy. closed and dropped in a timely manner.
The ADMIN COMMAND 'report' output
shows a long list of currently active
statements.

7 Performance tuning 137

138 IBM solidDB: Administrator Guide
8 Troubleshooting and support
To help you understand, isolate, and resolve problems with your solidDB products,
the troubleshooting and support information contains instructions for using the
problem-determination resources that are provided with your solidDB products.

To resolve a problem on your own, you can find out how to identify the source of
a problem, how to gather diagnostic information, where to get fixes, and which
knowledge bases to search. If you need to contact IBM Software Support, you can
find out what diagnostic information the service technicians require to help you
address a problem.

Troubleshooting a problem
Troubleshooting is a systematic approach to solving a problem. The goal of
troubleshooting is to determine why something does not work as expected and
how to resolve the problem.

The first step in the troubleshooting process is to describe the problem completely.
Problem descriptions help you and your IBM Support representative know where
to start to find the cause of the problem. This step includes asking yourself basic
questions:
v What are the symptoms of the problem?
v Where does the problem occur?
v When does the problem occur?
v Under which conditions does the problem occur?
v Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem,
which can then lead you a problem resolution.

What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is the
problem?" This question might seem straightforward; however, you can break it
down into several more-focused questions that create a more descriptive picture of
the problem. These questions can include:
v Who or what is reporting the problem?
v What are the error codes and messages?
v How does the system fail? For example, is it a loop, hang, crash, performance
degradation, or incorrect result?

Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of the
most important steps in resolving a problem. Many layers of technology can exist
between the reporting and failing components. Networks, disks, and drivers are
only a few of the components to consider when you are investigating problems.

The following questions help you to focus on where the problem occurs to isolate
the problem layer:

139
 v Is the problem specific to one platform or operating system, or is it common
across multiple platforms or operating systems?
v Is the current environment and configuration supported?
v Is the application running locally on the database server or on a remote server?

If one layer reports the problem, the problem does not necessarily originate in that
layer. Part of identifying where a problem originates is understanding the
environment in which it exists. Take some time to completely describe the problem
environment, including the operating system and version, all corresponding
software and versions, and hardware information. Confirm that you are running
within an environment that is a supported configuration; many problems can be
traced back to incompatible levels of software that are not intended to run together
or have not been fully tested together.

When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for those

cases that are one-time occurrences. You can most easily develop a timeline by
working backward: Start at the time an error was reported (as precisely as possible,
even down to the millisecond), and work backward through the available logs and
information. Typically, you need to look only as far as the first suspicious event
that you find in a diagnostic log.

To develop a detailed timeline of events, answer these questions:

v Does the problem occur only at a certain time of day or night?
v How often does the problem occur?
v What sequence of events leads up to the time that the problem is reported?
v Does the problem occur after an environment change, such as upgrading or
installing software or hardware?

Responding to these types of questions can give you a frame of reference in which
to investigate the problem.

Under which conditions does the problem occur?

Knowing which systems and applications are running at the time that a problem
occurs is an important part of troubleshooting. These questions about your
environment can help you to identify the root cause of the problem:
v Does the problem always occur when the same task is being performed?
v Does a certain sequence of events need to occur for the problem to surface?
v Do any other applications fail at the same time?

Answering these types of questions can help you explain the environment in
which the problem occurs and correlate any dependencies. Remember that just
because multiple problems might have occurred around the same time, the
problems are not necessarily related.

Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can be

reproduced. Typically, when a problem can be reproduced you have a larger set of
tools or procedures at your disposal to help you investigate. Consequently,
problems that you can reproduce are often easier to debug and solve. However,
problems that you can reproduce can have a disadvantage: If the problem is of

140 IBM solidDB: Administrator Guide

 significant business impact, you do not want it to recur. If possible, re-create the
problem in a test or development environment, which typically offers you more
flexibility and control during your investigation
v Can the problem be re-created on a test system?
v Are multiple users or applications encountering the same type of problem?
v Can the problem be re-created by running a single command, a set of
commands, or a particular application?

Tools for troubleshooting

The following tools are available to help collect, format or analyze diagnostic data.
v ADMIN COMMAND 'userlist'
The ADMIN COMMAND 'userlist -l' command displays a list of users currently
logged in to the database. The output provides information about various
database operations and settings for each user.
v ADMIN COMMAND 'report'
The ADMIN COMMAND 'report' command produces a report that contains
information about the server, users, and database operations. The report also
includes the configuration file (solid.ini) settings and a list of the performance
counters.
v ADMIN COMMAND 'pmon'
The ADMIN COMMAND 'pmon' command displays the solidDB performance counters
(called perfmons or pmons) that provide information about various database
operations and performance
v ADMIN COMMAND 'status'
The ADMIN COMMAND 'status' command displays statistics information about
memory usage, process size, transaction count, cache count, user count, database
operations.
v ADMIN COMMAND 'monitor'
The ADMIN COMMAND 'monitor' command controls monitoring of user activity and
SQL calls. The information is logged into the soltrace.out file. Monitoring can
also be turned on with the command line option -m at solidDB startup.
v ADMIN COMMAND 'trace'
The ADMIN COMMAND 'trace' command controls the solidDB trace facility.
v ADMIN COMMAND 'sqllist'
The ADMIN COMMAND 'sqllist' command displays a list of the longest running
SQL statements among the currently running statements. You can limit the
number of statements shown by specifying the number of statements as an
attribute (ADMIN COMMAND 'sqllist top <no_of_statements>').
v ADMIN COMMAND 'backuplist'
The ADMIN COMMAND 'backuplist' command displays the status of the last local
backup.
v ADMIN COMMAND 'proctrace'
The ADMIN COMMAND 'proctrace' command controls tracing in stored procedures
and triggers.
v EXPLAIN PLAN FOR
The EXPLAIN PLAN FOR SQL statement shows the execution plan that the SQL
optimizer has selected for a given SQL statement.
v ODBC Driver Manager trace facility (Windows)

8 Troubleshooting and support 141

 The Windows ODBC Driver Manager has a trace facility that allows the
sequence of function calls made by an ODBC application to be recorded into a
log file.

Tracing SQL statements

You can trace SQL statements using the ADMIN COMMAND 'trace' and ADMIN
COMMAND 'monitor' commands or by using the SQL Info facility.

ADMIN COMMAND 'trace'

The ADMIN COMMAND 'trace' command controls the solidDB trace facility. The ADMIN
COMMAND 'trace on sql' enables tracing of SQL statements. The tracing
information is output by default to the soltrace.out file.

ADMIN COMMAND 'monitor'

The ADMIN COMMAND 'monitor' command controls the solidDB monitoring facility.
The ADMIN COMMAND 'monitor on' enables monitoring of user activity and SQL
calls. The monitoring logs are output to the soltrace.out file.

SQL Info facility

The SQL Info facility generates information for each SQL statement processed by
solidDB.

To generate the SQL Info, you run your application with the SQL Info facility
enabled. The SQL Info facility can be enabled in the following ways:

The tracing level (info_level) is defined as an integer between 0 (no tracing) and 8
(solidDB info from every fetched row).
Table 39. SQL Info levels

Info level Description

0 no output

1 table, index, and view info in SQL format

2 SQL execution graphs (technical support use only)

3 some SQL estimate info, solidDB selected key name

4 all SQL estimate info, solidDB selected key info

5 solidDB info also from discarded keys

6 solidDB table level info

7 SQL info from every fetched row

8 solidDB info from every fetched row

The trace information is output by default to the soltrace.out file in the solidDB
working directory. You can also specify the output file using the SQL.InfoFileName

142 IBM solidDB: Administrator Guide

parameter. This is recommended since the soltrace.out file may contain
information from several sources.

Examples
[SQL]
Info = 1
InfoFileName = solidsql_trace.txt

The following command turns on the SQL Info facility on level 3, outputting the
trace information to a my_query.txt file in the working directory. This SQL Info
facility is turned on only for the client that executes the statement.
SET SQL INFO ON LEVEL 1 FILE ’my_query.txt’

The following SQL statement turns off the SQL Info facility:
SET SQL INFO OFF

Using stack trace facility

The stack traces facility collects diagnostics information upon server failures. In
general, IBM Software Support and development teams use the stack traces facility
for troubleshooting. You can also generate stack traces to gain information about a
problem that you are investigating, but its use is rather limited without knowledge
of the solidDB source code.

About this task

The stack traces facility is controlled with the Srv.StackTraceEnabled parameter.

When set to 'yes' (default), the stack trace information is output to
ssstacktrace-<process_id>-<thread_id>.out file in the solidDB working directory.

The following signals invoke the stack traces output automatically:

v SIGSEGV
v SIGILL
v SIGBUS
v SIGTRAP
v SIGSYS
v SIGEMT
The stack traces information is produced only about the thread that received the
signal.

Additionally, you can generate the stack traces information for all currently
running threads by sending the server the SIGUSR1 signal.

Note: The stack traces facility is not supported on Windows operating systems.

Procedure
v To enable or disable the stack traces facility, set the Srv.StackTraceEnabled
parameter to 'yes' or 'no'.
v To output the stack trace information manually without shutting down the
server, send the server the SIGUSR1 signal.
For example, use the following command in Linux environments:
kill -SIGUSR1 <process_id>

8 Troubleshooting and support 143

 Tracing communication between client and server
solidDB provides the following tools for observing the communication between an
application and a database server:
v Network trace facility
Use the network trace facility when you want to know why a connection is not
established to the solidDB server.
v Ping facility
Use the ping facility to determine how fast packets are transferred between an
application and the solidDB server.

Network trace facility: Network tracing can be done on the solidDB node, on the
application node, or concurrently on both nodes. The trace information is written
to the default trace file or the file specified with the Com.TraceFile parameter.

The default name of the output file is soltrace.out. This file is created in the
current working directory of the server or client depending on which end the
tracing is started.

The file contains information about:

v loaded DLLs
v network addresses
v possible errors

You can turn the network trace facility on in the following ways:
v Use the Com.Trace and Com.TraceFile parameters.
Defining the TraceFile configuration parameter automatically turns on the
Network trace facility.
v Use the environment variables SOLTRACE and SOLTRACEFILE.
The environment variable settings override the definitions in the solid.ini file.
Defining the SOLTRACEFILE environment variable automatically turns on the
Network trace facility.
v Use the option -t and/or -ofilename as a part of the network name.
– Option -t turns on the Network trace facility.
– Option -o turns on the facility and defines the name of the trace output file.

Defining trace parameters in the client-side configuration file

[Com]
Trace ={Yes|No}
; default No
TraceFile = file_name
; default soltrace.out

Example:
[Com]
Connect = nmp SOLIDDB
Listen = nmp SOLIDDB
Trace = Yes

Defining environment variables

set SOLTRACE = Yes

or
set SOLTRACEFILE = trace.out

144 IBM solidDB: Administrator Guide

Using network name options
[Com]
Connect = nmp -t soliddb
Listen = nmp -t soliddb

or
[Com]
Connect = nmp -oclient.out soliddb
Listen = nmp -oserver.out soliddb

Network trace facility output

Following is an excerpt from a trace file:

Scanning listening keyword Listen from section Com.
No listening information found from section Com.
Generating default listening info.

Parsing address ’TCP/IP 1964’.

Address information:
fullname : ’TCP/IP 1964’
lisname : ’1964’
protocol : ’tcp’ (TCP/IP)
enabled : Yes
ping : 0
trace : No

Reading communication configuration from file D:\solid\solid.ini.

Parsing address ’TCP/IP 1964’.

Address information:
fullname : ’TCP/IP 1964’
lisname : ’1964’
protocol : ’tcp’ (TCP/IP)
enabled : Yes
ping : 0
trace : No

Initialising protocol ’tcp’ (TCP/IP).

Searching DLL ’DTCW3237’.
DLL s:\soldll\DTCW3237.DLL loaded.
SOLID version 03.70.0026, DLL interface version 4.
Build information Tue Oct 25 00:18:07 2002.
Initialization of protocol ’tcp’ succeeded.

Protocol TCP/IP using configuration :

MaxPhysMsgLen: 8192
ReadBufSize: 2048
WriteBufSize: 2048
SelectThread: Yes
Trace: Yes
MinWritePoolBuffers: 4
MaxWritePoolBuffers: -1
WritePoolIncrement: 1
SyncRead: No
SyncWrite: No

26.07 15:12:21 Initializing server. Listen info ’TCP/IP 1964’.

Starting the listening of ’TCP/IP 1964’.

Ping facility: The solidDB ping facility can be used to test the performance and
functionality of the network connection. The ping facility is built into all solidDB
client applications and is turned on with the network name option -p level .

8 Troubleshooting and support 145

 The output file will be written to the current working directory of the computer
where the parameter is given. The default name of the output file is soltrace.out.

Clients can always use the ping facility at level 1. Levels 2, 3, 4 or 5 may only be
used if the server is set to use the ping facility at least at the same level.
Table 40. Ping facility levels

Setting Function Description

0 No operation Do nothing, default

1 Check that server is alive Exchange one 100 byte message

2 Basic functional test Exchange messages of sizes 0.1K, 1K,

2K..30K, increment 1K

3 Basic speed test Exchange 100 messages of sizes 0.1K, 1K,

8K and display each sub-result and total
time

4 Heavy speed test Exchange 100 messages of sizes 0.1K, 1K,

2K, 4K, 8K, 16K and display each
sub-result and total time

5 Heavy functional test Exchange messages of sizes 1..30K,

increment 1 byte

Note:

If the solidDB client does not have an existing server connection, you can use the
SQLConnect() function with the connect string option -p1 (ping test, level 1) to
check if solidDB is listening in a certain address. Without logging into solidDB,
SQLConnect() can then check the network layer and ensure solidDB is listening.
When used in this manner, SQLConnect() generates error code 21507, which means
the server is alive.

Running ping facility at level 1

Turn on the ping facility by using the following network name syntax:
protocol_name -p level server_name

For example, to run the ping facility with solidDB SQL Editor (solsql), use the
following command
solsql "tcp -p1 -oping.out 1964"

This runs the ping facility at the level 1 and outputs the results into soltrace.out.
This test checks if the server is alive and exchanges one 100 byte message to the
server.

After the ping facility has been run, the client exits with the following message:
SOLID Communication return code xxx: Ping test successful/failed,
results are in file FFF.XX

146 IBM solidDB: Administrator Guide

 Com.Listen parameter and restrictions on the ping facility

The server-side ping level that is set with the Com.Listen parameter restricts the
available ping levels on the client side. Clients can always use the ping facility at
level 1 (0 is no operation/default). Levels 2, 3, 4 or 5 may only be used if the
server is set to use the ping facility at least at the same level.

Note: Ping clients running at level greater than 3 may cause heavy network traffic
and may slow down any application that is using the network, including any SQL
clients connected to the same solidDB.

Troubleshooting solidDB Universal Cache

This section provides instructions and guidelines on how to prevent or
troubleshoot common problems while configuring or using the solidDB Universal
Cache.
v “Initial connections are not successful”
v “Dependencies between components used in replication”
v “Making changes to replication subscriptions” on page 148
v “Subscriptions fail after performing hsb netcopy followed by a switchover” on
page 148
v “InfoSphere CDC for solidDB connection to solidDB server times out” on page
149

Initial connections are not successful

The components for the solidDB Universal Cache must be installed and configured
in the order described in section Overview of installation and configuration steps.
Review the steps below and ensure that the installation and configuration steps
were followed.

Installation and configuration order

v front-end solidDB server
v InfoSphere CDC for solidDB
v back-end data server
v InfoSphere CDC for the back-end data server
v Access Server
v Management Console

Dependencies between components used in replication

To set up replication between databases, you need define and create various
entities and components which are dependent on each other. These entities and
components must be created in the following order and modified or deleted in the
reverse order. For more details and instructions, see the InfoSphere Change Data
Capture Management Console, Administration Guide.
1. Databases
2. InfoSphere CDC instances
3. Datastores
4. Subscriptions
5. Table mappings

8 Troubleshooting and support 147

 Making changes to replication subscriptions

If you need to make changes to your replication subscriptions, you must first end
replication on your subscriptions. For more details and instructions, see section
Ending replication on a subscription in the InfoSphere Change Data Capture Management
Console, Administration Guide.

Subscriptions fail after performing hsb netcopy followed by a

switchover

In solidDB High Availability (HotStandby) configurations, subscriptions with

solidDB as a source datastore may fail if a switchover is performed shortly after
hsb netcopy.

This may happen for example in the following cases:

1. After a failure or a maintenance break, primary server (node 1) and secondary
server (node 2) are synchronized using ADMIN COMMAND ’hsb netcopy’.
2. Replication continues against the primary server (node 1) for few transactions.
3. The primary server (node 1) fails and switchover changes the secondary server
(node 2) to be the new primary server.
4. Subscriptions fail and replication against the new primary server (node 2)
cannot be restarted.

Causes

The command ADMIN COMMAND ’hsb netcopy’ does not copy any log files.
Subsequently, because InfoSphere CDC replication is asynchronous in nature,
InfoSphere CDC for solidDB might not have processed all the transactions up to
the point from which the netcopy was made. This means that the log position
InfoSphere CDC for solidDB tries to use after the switchover might not be valid –
the log entry for the last transaction on node 1 before the netcopy might not exist
on the new primary (node 2).

Workaround

To ensure that InfoSphere CDC for solidDB has access to a valid log entry in the
new primary server (node 2) after a switchover:
v Before performing netcopy, copy the log files from the primary server (node 1)
to the secondary server (node 2). This ensures that InfoSphere CDC for solidDB
has access to the log positions of the transactions that were executed before the
netcopy was made.
or
v Do not perform switchover shortly after netcopy or wait for several transactions
to be replicated to the back-end database before performing the switchover. This
ensures that log positions in the primary server (node 1) and secondary server
(node 2) are synchronized.
or
v If the switchover has already taken place (for example, due to a failure of node
1):
1. Recover the old primary server (node 1).
2. Perform a switchover to return the old primary server (node 1) back to a
primary server.
3. Restart replication on the subscription.

148 IBM solidDB: Administrator Guide

 Before performing another switchover (to make node 2 the new primary server),
wait for several transactions to be replicated. This ensures that log positions in
the primary server (node 1) and secondary server (node 2) are synchronized.

InfoSphere CDC for solidDB connection to solidDB server times

out

InfoSphere CDC for solidDB connections to solidDB server can be idle for long
periods of time, causing connection idle timeouts. By default, the solidDB server
timeout for idle connections is set to 480 minutes (specified with the
Srv.ConnectTimeOut parameter).

Workaround:

Set the connection idle timeout for the InfoSphere CDC for solidDB connection to
infinite by using the non-standard solidDB JDBC connection property
solid_idle_timeout_min=0. The InfoSphere CDC for solidDB specific connection
settings are specified with the InfoSphere CDC configuration tool (dmconfigurets),
using the Database area > Advanced button in Windows operating systems or the
Configure advanced parameters > Modify settings option in Linux and UNIX
operating systems.

Note: The timeout setting specified for the InfoSphere CDC for solidDB instance
does not impact the server setting (Srv.ConnectTimeOut) for other connections.

Troubleshooting SMA
This section provides instructions and guidelines on how to prevent or
troubleshoot common problems while configuring or using SMA.

Error: Server could not allocate shared memory segment by id -1

Symptoms
When trying to start a SMA server, the following type of error is displayed,
and the SMA server cannot be started.
IBM solidDB process has encountered an internal error and is unable to
continue normally. Report the following information to technical support.
SOLID Fatal error: Out of central memory when allocating buffer memory (size = 33554432)
Date: 2012-04-24 15:39:44
Product: IBM solidDB
Version: 7.0.0.2 Build 2012-04-20

[solid1]~ ./solidsma -f -c .
Server could not allocate shared memory segment by id -1

Causes
The SMA server startup fails because there is no memory available. This
situation can occur if:
v When a SMA application or SMA server terminates abnormally, they can
leave shared memory allocated. Even if you shut down all SMA
processes, the shared memory is still left reserved.
v You have allocated too little memory for SMA use.
This leads to a situation where all memory is used and you cannot start a
SMA server any more.
Resolving the problem
In Linux and UNIX environments, clear the hanging shared memory
segments with the ipcrm command.

8 Troubleshooting and support 149

 For example in Linux environments, use the following script to identify
and remove the unused shared memory segments.
#!/bin/sh

if [ $# -ne 1 ]
then
echo "$0 user"
exit 1
fi

for shm_id in $(ipcs -m|grep $1|awk -v owner=$1 ’ { if ( owner == $3 ) {print $2} }’)
do
ipcrm -m $shm_id
done

For more details on the ipcrm command, see your operating system
documentation.

Cannot map shared memory area

Symptoms
When trying to connect to a SMA server, the following type of error is
displayed, and the connection fails.
v Linux and UNIX operating systems
cannot map shared memory area 1288077395 to 0x2b0029800000
Cannot connect to target database.
v Windows operating systems
SQL State "08004"; Native Error Code "25215";
Error Text "SMA failed in MapViewOfFileExt,
desired addr: 0000000800000000, got addr: 000000000000000000, error: 6.
Causes
When started, the SMA starts attaching shared memory segments to an
address space that is used by another process.
Resolving the problem
In general, the earlier your application connects to the SMA server, the less
likely it is that the address space requested by solidDB is in use.
The SMA server uses the following address spaces by default:
Table 41. SMA default address spaces
Operating system Default start address space*
AIX® 0x700000010000000ul
Linux 64-bit 0x2c0000000000
Linux 32-bit 0x50000000
Solaris Intel 0x2b0000000000
Solaris Sparc 0xffffffff60000000
Windows 0x0000000080000000
*The start address space is the value of the parameter shmaddr in the shmat() system call.

1. Force the start address space for the SMA server to a different address
space using the environment variable SOLSMASTART.
v Linux and UNIX operating systems:
export SOLSMASTART=<start_address_space>
For example:
export SOLSMASTART=0x2b0000000000

150 IBM solidDB: Administrator Guide

 v Windows operating systems:
set SOLSMASTART=<start_address_space>
For example:
set SOLSMASTART=0x0000000800000000
2. Restart the SMA server.

Error 21300: Protocol 'sma' is not supported

Symptoms
When trying to connect to a SMA server, the following type of error is
displayed:
Error HY000: SOLID Communication Error 21300:
Protocol ’sma’ is not supported
SQLConnect failed
Causes
The application has been linked both to the solidDB ODBC library and the
SMA library (ssolidsmaxx).
Resolving the problem
Check your application code and remove any references to the solidDB
ODBC libraries (for example, sacl2x70.so or socw6470.dll.

Troubleshooting database file size (file write fails)

If your database has reached the maximum size specified by the
IndexFile.FileSpec parameter, you need to increase the maximum file size limit or
divide the database into multiple files.

Symptom

solidDB goes down with Error 11003 File write failed, configuration
exceeded (SU_ERR_FILE_WRITE_CFG_EXCEEDED).

Resolving the problem

1. Add a new database file by using the following command:
ADMIN COMMAND ’filespec -a "file_name max_file_size_in_bytes [device_number]"]’
For example:
ADMIN COMMAND ’filespec -a "solid2.db 2147483647"’

Note:
v You can only add new database files with the ADMIN COMMAND ’filespec -a’
command, you cannot modify the size of existing database files.
v The new database file specification is stored in the solid.ini configuration
file at next shutdown.

or
1. Shut down solidDB.
2. Modify the IndexFile.FileSpec parameter in the solid.ini file.
v Increase the maximum limit for the database file.
or
v Divide the database into multiple files by using the FileSpec_[1..n] format.
For example:

8 Troubleshooting and support 151

 [IndexFile]
FileSpec_1 = solid.db 2147483647
FileSpec_2 = solid.db2 2147483647
FileSpec_3 = solid.db3 2147483647

Important: If you have not defined the FileSpec_1 parameter earlier, use the
default file size (2147483647) as shown above.
3. Restart solidDB.
Related information:
“FileSpec_[1...n] parameter” on page 53
“ADMIN COMMAND” on page 309

Troubleshooting MME.ImdbMemoryLimit
If you get an error message indicating that the limit set with MME.ImdbMemoryLimit
has been reached, you need to take action immediately.

You must address both the immediate problems and the long term problems. The
immediate problems are to prevent users from experiencing serious errors, and to
free up some memory before shutting down the server so that your system is not
out of memory when you restart the server. For long term, you need to ensure that
you will not run out of memory in the future as tables expand.

Resolving the immediate problem

To address the immediate problem, you typically need do the following:

1. Notify users that they should disconnect from the server. This will accomplish
two things: it will minimize the number of users who will be impacted if the
situation deteriorates. Also, if any of the users who disconnect were using
temporary tables, disconnecting will free up memory. You may wish to have a
policy or error-checking code to ensure that users and/or programs will
attempt to disconnect gracefully if they see this error.
2. If there were not enough temporary tables to free memory, drop some transient
table indexes or transient tables if any exist.

If there were not enough temporary tables and transient tables to free enough
memory, do the following:
1. Drop one or more indexes on in-memory tables.
2. Shut down the server.
3. If there was absolutely nothing in memory that you could discard (for example,
you had only normal in-memory tables, none of which had indexes, and all of
which had valuable data), increase the MME.ImdbMemoryLimit slightly before
restarting the server. This may force the server to start paging virtual memory
which will greatly reduce performance, but it will allow you to continue using
the server and address the long-term problems. If you previously set the
ImdbMemoryLimit a little bit lower than the maximum, you will be able to raise
it slightly now without forcing the system to start paging virtual memory.
4. Restart the server.
5. Minimize the number of people using the system until you have had time to
address the long-term problem. Ensure that users do not create temporary
tables or transient tables until the long-term problem has been addressed.

152 IBM solidDB: Administrator Guide

 Resolving the long term problem

After you have solved the immediate problem and have ensured that the server
has at least some free memory, you are ready to address the long term problems.

For long term, reduce the amount of data stored in in-memory tables. The ways to
do this are to reduce the number or size of in-memory tables (including temporary
tables and transient tables), or reduce the number of indexes on in-memory tables.
v If the problem was caused solely by heavy usage of temporary or transient
tables, ensure that not too many sessions create too many large temporary or
transient tables at the same time.
v If the problem was caused by using too much memory for normal in-memory
tables, and if you cannot increase the amount of memory available to the server,
move one or more tables out of main memory and onto the disk.

To move a table from memory to disk, do the following:

1. Create an empty disk-based table with the same structure (but a different
name) as one of the tables in memory.
2. Copy the information from the in-memory table to an intermediate disk-based
table.
If you try to copy records of a large table to another table using a single SQL
statement (INSERT INTO ...VALUES SELECT FROM), keep in mind that the
entire operation occurs in one transaction. Such an operation is efficient only if
the entire amount of data fits in the cache memory of the server. If transaction
size outgrows the cache size, the performance degrades significantly. Therefore,
you should copy data of a large table to another table in smaller transactions
(for example, few thousands of rows per transaction) using a simple stored
procedure or application.

Note: The intermediate table does not need indices. The indices should be
re-created in the new table after the data has been successfully copied.
3. Drop the in-memory table.
4. Rename the disk-based table to have the original name of the dropped
in-memory table.

Tip:
v You should set the MME.ImdbMemoryLimit to a slightly lower value than the
maximum you really have available. If you run out of memory and have no
unnecessary in-memory tables or indexes that you can get rid of, you can
increase the MME.ImdbMemoryLimit slightly, restart the server with enough free
memory that you can address the long-term need.
v Use the MME.ImdbMemoryWarningPercentage to warn you about increasing
memory consumption.
v Not all situations require you to reduce the number of in-memory tables. In
some cases, the most practical solution may be to simply install more memory in
the computer.

Troubleshooting solidDB Data Dictionary (soldd)

soldd returns error 23007 when exporting database schema

Symptom

When exporting database schema, soldd returns error 23007.

8 Troubleshooting and support 153

 For example:
Solid Data Dictionary List fatal error: [Solid][SOLID ODBC Driver]
[SOLID]SOLID Procedure Error 23007: Procedure name
SOLDD_GET_SEQUENCE_VAL conflicts with an existing entity

Causes

The error 23007 is a generic solidDB procedure that is returned when you attempt
to create a stored procedure with a name that already exists in the database. soldd
creates system stored procedures to export the current value of a database
sequence object and drops the same once the sequence object is exported. If soldd
is interrupted during the schema export, dropping the system stored procedures
might fail. When soldd is rerun, error 23007 is returned.

Resolving the problem

1. Check the error message for the name of the system stored procedure that is
causing the error.
2. Drop the procedure with the following command:
DROP PROCEDURE <procedure name>
3. Re-export the schema with soldd.
Related information:
“solidDB Data Dictionary (soldd)” on page 116

Searching knowledge bases

You can find useful information by searching the solidDB and solidDB Universal
Cache Information Center, but sometimes you need to look beyond the Information
Center to answer your questions or resolve problems.

About this task

To search knowledge bases for information that you need, use one or more of the
following approaches:

Procedure
v Find the content that you need by using the IBM Support Portal.
The IBM Support Portal is a unified, centralized view of all technical support
tools and information for all IBM systems, software, and services. The IBM
Support Portal lets you access the IBM electronic support portfolio from one
place. You can tailor the pages to focus on the information and resources that
you need for problem prevention and faster problem resolution.
The following link provides a list of all solidDB product family TechNotes,
ordered by publication date.
– solidDB product family TechNotes
v Search for content about solidDB products in developerWorks®
developerWorks is an IBM resource for developers and IT professionals.
v Search for content by using the IBM masthead search. You can use the IBM
masthead search by typing your search string into the Search field at the top of
any ibm.com® page.
v Search for content by using any external search engine, such as Google, Yahoo,
or Bing. If you use an external search engine, your results are more likely to
include information that is outside the ibm.com domain. However, sometimes

154 IBM solidDB: Administrator Guide

 you can find useful problem-solving information about IBM products in
newsgroups, forums, and blogs that are not on ibm.com.

Tip: Include "IBM" and the name of the product in your search if you are
looking for information about an IBM product.

Getting fixes
A product fix might be available to resolve your problem.

About this task

All solidDB fix packs and interim fixes are available through Fix Central
(http://www.ibm.com/support/fixcentral/).

Procedure
1. Visit the following solidDB Support page for a list of available fix packs and
download links to the installation images: Fix packs by version for solidDB and
solidDB Universal Cache
2. Determine which fix pack you need. In general, the installation of the most
recent fix pack is recommended in order to avoid encountering problems
caused by software defects already known and corrected.
3. Download the fix pack and extract the files into a directory of your choice.
4. Apply the fix. Follow the instructions in the readme.txt file provided with the
fix.

Tip: You can view and download the readme.txt file separately using the Fix
Central HTTP download option.

IBM Software Support for solidDB and solidDB Universal Cache

For assistance with solidDB and solidDB Universal Cache product defects, collect
relevant diagnostics data and contact IBM Software Support. Before contacting IBM
Software Support, your company must have an active IBM software maintenance
contract.

Contacting IBM Support

IBM Software Support provides assistance with product defects.

Before you begin

Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. For information about the types of available support, see the Support
portfolio topic in the Software Support Handbook.

Procedure
1. Define the problem, gather background information, and determine the severity
of the problem. For more information, see the Getting IBM support topic in the
Software Support Handbook.
2. Collect diagnostic information.
See “Collecting diagnostics data” on page 157 for details.
3. Submit the problem to IBM Software Support in one of the following ways:

8 Troubleshooting and support 155

 v Online through the IBM Support Portal: You can open, update, and view all
your Service Requests from the Service Request portlet on the Service
Request page.
v By phone: For the phone number to call in your country, see the Directory of
worldwide contacts web page.

Results

If the problem that you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Report (APAR). The APAR describes the problem in detail. Whenever possible,
IBM Software Support provides a workaround that you can implement until the
APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
IBM Support Portal daily, so that other users who experience the same problem
can benefit from the same resolution.

Sending information to IBM Support

You can submit data to IBM Software Support by FTP or by using the Electronic
Service Request (ESR) tool.

Before you begin

The steps assume that you have already opened a problem management record
(PMR) with IBM Software Support.

Procedure
v To submit files (via FTP) to the Enhanced Centralized Client Data Repository
(EcuRep):
1. Package all files into ZIP or TAR format, and name the package according to
your Problem Management Record (PMR) identifier.
Your file must use the following naming convention in order to be correctly
associated with the PMR: xxxxx.bbb.ccc.yyy.yyy, where xxxxx is the PMR
number, bbb is the PMR's branch number, ccc is the PMR's territory code,
and yyy.yyy is the file name.
2. Using an FTP utility, connect to the server ftp.emea.ibm.com.
3. Log in as the userid "anonymous" and enter your e-mail address as your
password.
4. Go to the toibm directory. For example, cd toibm.
5. Go to one of the operating system-specific subdirectories. For example, the
subdirectories include: aix, linux, unix, or windows.
6. Change to binary mode. For example, enter bin at the command prompt.
7. Put your file on the server by using the put command. Use the following file
naming convention to name your file and put it on the server. Your PMR will
be updated to list where the files are stored using the format:
xxxx.bbb.ccc.yyy.yyy. (xxx is the PMR number, bbb is the branch, ccc is the
territory code, and yyy.yyy is the description of the file type such as tar.Z or
xyz.zip.) You can send files to the FTP server, but you cannot update them.
Any time that you must subsequently change the file, you must create a new
file name.
8. Enter the quit command.
v To submit files using the ESR tool:
1. Sign onto ESR.

156 IBM solidDB: Administrator Guide

 2. On the Welcome page, enter your PMR number in the Enter a report
number field, and click Go.
3. Scroll down to the Attach Relevant File field.
4. Click Browse to locate the file that you want to submit to IBM Software
Support.
5. Click Submit. Your file is transferred to IBM Software Support through FTP,
and it is associated with your PMR.

Collecting diagnostics data

Depending on your environment and set up, you can use the solidDB Support
Assistant and InfoSphere CDC Support Assistant for collecting diagnostics data. In
some cases you might need to collect the data manually.

solidDB Support Assistant

The solidDB Support Assistant (solidsupport) utility helps you collect solidDB
specific diagnostic files and system information for troubleshooting purposes.

The solidsupport utility collects diagnostic files such as solmsg, soltrace, and
ssdebug from the database instance in question and stores them in a compressed
archive file (solidsupport.zip). The utility also produces directory listings of
database, logging, and sorter directories, and collects various operating system and
environment specific information.

Execute the command solidsupport -h to display the complete list of command

options.

The solidsupport utility collects the following information by default:

Table 42. solidsupport
Content type Notes
solidDB configuration file Default file name is solid.ini. If solid.ini does not
exist or the configuration file name is not provided
with option -i, the solidDB factory values are used.
Message files For more information about message and log files,
v solmsg.out see “Viewing error messages and log files” on page
63.
v solerror.out
Network and SQL monitor trace For information about how to enable the generation
files – soltrace.out of network trace files, see “Network trace facility” on
page 144.
High Availability Controller (HAC) The location of the HAC related files must be
files specified with the option -c HAC_directory_path
v hactrace.out
v hacmsg.out
v solidhac.ini
Debug files The debug files are generated only in exceptional
v ssdebug.out cases. IBM Support will provide instructions if the
debug files are needed.
v ssdebug.log
v Stack trace files – For information about the stack traces facility, see
ssstacktrace-xxx-yyy.out “Using stack trace facility” on page 143.
Performance counter reports The performance counter reports are collected if you
v pmondiff.out have generated such reports with ADMIN COMMAND
’perfmon diff’.

8 Troubleshooting and support 157

 Table 42. solidsupport (continued)
Content type Notes
Report files (rep*) The report files are collected if you have generated
such files with ADMIN COMMAND ’report filename’.

Only file names starting with rep are collected.

Tip: You can also turn on automatic report file
generation with the Srv.ReportInterval,
Srv.MemorySizeReportInterval, and
Srv.DatabaseSizeReportInterval parameters.
Directory listings of database, This information is collected into *.list files in the
logging, backup, and sorter SOLSUPPORT directory in the solidsupport.zip
directories archive.
Operating system and environment This information is collected by default into a
information detailed_system_info.html file. You can also use the
v Operating system patch level option -f to specify that instead of HTML output,
the collected system information is written into flat
v Number of processors
text files that are archived into
v Amount of memory solidsupport_sysinfo.zip file within the main
v Swap and file cache settings solidsupport.zip archive.
v User data and file resource limits
and per user process limit
v Type of disk storage

Important: To protect the security of your data, solidsupport does not capture any
user data from tables or logs by default. To include database and log files and all
files from database working directory, use the option -a.

Note:
v The solidsupport utility only collects existing files; it does not generate any
diagnostics files, such as the trace files (soltrace.out). You need to first enable
the generations of log files, as described in the Notes column in the above table.
v The solidsupport utility does not collect any information from the client side
(ODBC/JDBC drivers). You need to collect the client-specific information
manually; for more information, see section “Collecting client and other
diagnostics data” on page 160.

Using solidDB Support Assistant (solidsupport)

Start solidDB Support Assistant (solidsupport) with the command solidsupport,

followed by argument options.
solidsupport [options]
Table 43. solidDB Support Assistant (solidsupport) options
Option Description
-a Collects all files from database, log, and working
directories, including database files and log files
-c HAC_directory_path Specifies the directory for HAC related files, default is
the solid.ini directory
-o output_file Specifies the output file name

Default is solidsupport.zip.

158 IBM solidDB: Administrator Guide

Table 43. solidDB Support Assistant (solidsupport) options (continued)
Option Description
-i configuration_file Specifies the configuration file name and path to be used

The configuration file path is used as a working

directory for solidsupport; all output files are written to
this directory.

If this option is not given, the default file name

solid.ini is used.
-f Collects system information as flat files and archives
them into solidsupport_sysinfo.zip
-m Collects system information into an HTML file
(detailed_system_info.html) – default
-p Run without pausing
-h Usage/Help information

The solidsupport utility collects data from the machine where it is run. The
configuration file path is used as a working directory for solidsupport; all output
files are written to that directory.
v In a client-server environment, database-related information are collected from
the machine where the database resides and from the location specified by
solid.ini configuration file.
v In HotStandby setups, you need to run solidsupport on both HotStandby
nodes.

Examples

Example 1

The following command

v checks solidDB file names and paths from the default configuration file
solid.ini in the current directory, or, if solid.ini does not exist, the solidDB
factory defaults are used,
v copies all files to a compressed file with the default name solidsupport.zip
solidsupport -a

Example 2

The following command

v checks solidDB file names and paths from a configuration file named
solidDB.ini in the current directory
v copies default set of files to a compressed file named 12345.678.901.zip
solidsupport -o 12345.678.901.zip -i solidDB.ini

InfoSphere CDC Support Assistant

The InfoSphere CDC Support Assistant allows you to collect diagnostic data such
as configuration, log, and runtime information for Management Console, Access
Server, and optionally for specific datastores in your environment. You can also
enable trace options for Management Console and Access Server.

8 Troubleshooting and support 159

 For instructions on how to use the InfoSphere CDC Support Assistant, see section
Support and Troubleshooting > Using Support Assistant in the InfoSphere Change
Data Capture Management Console, Administration Guide.

Collecting client and other diagnostics data

In some cases, IBM Software Support might ask you to collect diagnostics and
problem reporting data manually, for example, about your ODBC or JDBC setup.

Gathering diagnostics data on solidDB ODBC API: If the problem concerns the
performance of a specific solidDB ODBC API or SQL statement, run the SQL Info
facility at level 4.

The generated soltrace.out file contains the following information:

v CREATE TABLE statements
v CREATE VIEW statements
v CREATE INDEX statements
v SQL statements
Related concepts:
“Tracing SQL statements” on page 142
You can trace SQL statements using the ADMIN COMMAND 'trace' and ADMIN
COMMAND 'monitor' commands or by using the SQL Info facility.

Gathering diagnostics data on solidDB ODBC Driver: If the problem concerns

the performance of the solidDB ODBC Driver, collect the following information:
v solidDB ODBC Driver name and version
v ODBC Driver Manager name and version

If the problem concerns the cooperation of solidDB and any independent software
vendor (ISV) software package, include the following information:
v Full name of the software
v Version and language
v Manufacturer
v Error messages from the ISV software package

In Windows environments, you may also use the ODBC trace facility
Administrative Tools > ODBC (Data Sources) > Tracing to get a log of the ODBC
statements.

Checking solidDB ODBC Driver version

v In Linux and UNIX environments, grep the ODBC driver library file for the
string "ODBC 3.x".
For example:
[test1]~% strings /solid/bin/socl2x65.so | grep "ODBC 3.x"
@(#)IBM solidDB ODBC 3.x API Library (UNICODE) v.6.5.0.4 Build 2011-01-21
IBM solidDB ODBC 3.x API Library (UNICODE)
v In Windows environments:
– Right-click the ODBC driver library file you are using and select Properties.
By default, the ODBC driver library files are in the bin directory in your
solidDB installation directory.
– On the Version tab, select Product version.

160 IBM solidDB: Administrator Guide

Gathering diagnostics data on solidDB JDBC Driver: If the problem is related to
the solidDB JDBC Driver, include the following information in your problem
report:
v Exact version of JDK or JRE used
v Version of the solidDB JDBC Driver (SolidDriver2.0.jar)
v Contents of DriverManager.setLogStream(someOutputStream) output, if
available
v Call stack – Exception.printStackTract() output of the application, if an exception
has occurred in the application

Checking solidDB JDBC Driver version

v In solidDB V6.5 Fix Pack 2 and later:
Use the following command to query the solidDB JDBC Driver version:
java solid.jdbc.SolidDriver -version
The output shows the version information in the following format (example):
IBM solidDB JDBC driver 6.5.0.2 Build 0030
v In solidDB V6.5 Fix Pack 1 and earlier:
1. Uncompress SolidDriver2.0.jar. For example:
jar -xvf SolidDriver2.0.jar

8 Troubleshooting and support 161

 2. Open SolidDriver.class in a text editor.
3. Search for the string "SOLID Server JDBC driver".
The version information is shown in the following format (example):
SOLID Server JDBC driver 6.5.0.1 Build 0017

Collecting diagnostics data about communication problems between a client and

server: If the problem concerns the performance of the communication between a
client and server use the Network trace facility and include the generated trace
files into your problem report.

Include also the following information:

v solidDB communication DLLs used: version and size
v Other communication DLLs used: version and size
v Description of the network configuration

Subscribing to Support and other updates

To stay informed of important information about the IBM products that you use,
you can subscribe to Support and other updates.

About this task

By subscribing to receive updates, you can receive important technical information
and updates for specific Support tools and resources. You can subscribe to updates
in the following ways:
v RSS feeds and social media subscriptions
The following RSS feeds and social media subscriptions are available for solidDB
and solidDB Universal Cache:
– solidDB Support RSS
– solidDB Product Family forum RSS
v My Notifications
With My Notifications, you can subscribe to Support updates for any IBM
product. You can specify that you want to receive daily or weekly e-mail
announcements. You can specify what type of information you want to receive
(such as APARs, publications, hints and tips, product flashes (also known as
alerts), downloads, and drivers). My Notifications enables you to customize and
categorize the products about which you want to be informed and the delivery
methods that best suit your needs.
v APARs
Each APAR enables you to subscribe to receive periodic emails that alert you to
the status of the APAR, along with a link to the fix after it becomes available.
You can track APARs individually or by product.

Procedure
v To subscribe to RSS feeds, copy the RSS feed URL to your RSS reader.
– solidDB Support RSS - http://www.ibm.com/software/support/rss/db2/
3457.xml?rss=s3457&ca=rssdb2
– solidDB Product Family forum RSS - http://www.ibm.com/developerworks/
forums/rss/rssmessages.jspa?forumID=1310
For general information about RSS, including steps for getting started and a list
of RSS-enabled IBM webpages, visit the IBM Software Support RSS feeds site.

162 IBM solidDB: Administrator Guide

v To subscribe to My Notifications, go to the IBM Support Portal and click My
Notifications in the Notifications portlet.
v Create or edit your profile to add the solidDB products to your subscriptions
list: products to your subscription list.
– Software > Information Management > IBM solidDB
– Software > Information Management > solidDB product family
For more detailed information, see Subscribing to My Notifications support
content updates.

8 Troubleshooting and support 163

164 IBM solidDB: Administrator Guide
Appendix A. Server-side configuration parameters
Each section of the solid.ini file is documented in a separate table. The sections
are:
v Accelerator
v Cluster
v Com
v General
v HotStandby
v IndexFile
v Logging
v LogReader
v MME
v Passthrough
v SharedMemoryAccess
v Sorter
v SQL
v Srv
v Synchronizer

Most parameters in most sections apply to all solidDB components. The sections
that do not apply to all components are listed below:
v The MME section applies only to in-memory databases.
v The Synchronizer section applies only to solidDB advanced replication
capability.
v The HotStandby section only applies to the High Availability component.

The descriptions of a some parameters specify that those parameters (or some
specific settings of those parameters) apply only to a particular component. Each
exception is documented in the description of the parameter itself.

Note: Parameter support may vary between platforms.

Accelerator section
Table 44. Accelerator parameters

Factory Access
[Accelerator] Description Value Mode
ImplicitStart If set to yes, solidDB starts automatically as soon as the ODBC yes RW/
API function SQLConnect is called in a user application. If set to Startup
no, solidDB must be explicitly started with a call to the SSC API
function SSCStartServer.

165
Table 44. Accelerator parameters (continued)

Factory Access
[Accelerator] Description Value Mode
ReturnListenErrors If this parameter is set to yes and network listening fails, the no RW/
SSCStartServer function returns an error. Startup

If this parameter is set to no and network listening fails, the

SSCStartServer starts the LLA server but network connections
are not possible.

Cluster section
Table 45. Cluster parameters

[Cluster] Description Factory Value Access Mode

ReadMostlyLoadPercentAtPrimary Percentage of read load directed 50 RW/Startup

to the Primary

Communication section
Table 46. Communication parameters

Access
[Com] Description Factory Value Mode
Defines the network (listening) name for a server. The format of the tcp 1964
Listen network name is: RW
protocol_name [options] server_name[,protocol_name
[options] server_name, ...]

The options and server_name depend on the communication

protocol. For details, see 5, “Managing network connections,” on
page 81.

You can define several network listening names. When the solidDB
server process is started, it publishes at least one network name
that distinguishes it in the network. The server can then start to
listen to the network using the given network name.
Note: The ADMIN COMMAND ’par com.listen=value’ command does
not replace existing network listening names; it appends new
listening names to the existing list.
Defines the maximum length of a single physical network message OS dependent RW/
MaxPhysMsgLen in bytes; longer network messages will be split into smaller Startup
messages of this size.

RConnectLifetime A time period in seconds for how long the idle connections are 60 RW
kept open in the pool. Whenever the connection is used, the timer
starts from zero. Valid values range from 0-3600 Unit: 1 second

This parameter is associated with server-maintained remote

connections used to execute Remote Stored Procedures in advanced
replication.

166 IBM solidDB: Administrator Guide

Table 46. Communication parameters (continued)

Access
[Com] Description Factory Value Mode

RConnectPoolSize Number of remote connections in the connection pool. These are 10 RW

the connections that are used to execute the remote procedure calls.
For performance reasons, we can keep the connections open in the
pool for a specified time. If the pool becomes full, and there is call
for a node that doesn't exist in the pool, then that call is blocked
until there is room in the pool. Valid values range from 1-1000

This parameter is associated with server-maintained remote

connections used to execute Remote Stored Procedures in advanced
replication.

RConnectRPCTimeout RPC timeout for remote connections. Default is 0 (no timeout). 0. RW

This parameter is associated with server-maintained remote Unit 1 millisecond

connections used to execute Remote Stored Procedures in advanced
replication.

ReadBufSize Sets the buffer size in bytes for the data read from the network OS dependent RW/
Startup

SocketLinger This parameter controls the TCP socket linger (SO_LINGER) no RW/
behavior after a close on the socket connection is issued. It Startup
indicates if the system attempts to deliver any buffered data (yes),
or if the system discards it (no), when a close() is issued. The
parameter affects all server-side connections, including advanced
replication and HotStandby.

SocketLingerTime This parameter defines the length of the time interval (in seconds) 0 RW/
the socket lingers after a close is issued. If the time interval expires Startup
before the graceful shutdown sequence completes, an abortive
shutdown sequence occurs (the data is discarded). The default
value zero indicates that the system default is used (typically, 1
second).

TcpKeepAlive This parameter can only be used on Linux, HP-UX, and Solaris no RW/
platforms. On other platforms, the parameter has no effect. Startup

If the client computer is rebooted, the connection status on the

server side remains 'ESTABLISHED'. You can set the
SO_KEEPALIVE socket option with this parameter.

See also parameters TcpKeepAliveIdleTime,

TcpKeepAliveProbeCount and TcpKeepAliveProbeInterval.
This parameter can only be used on Linux, HP-UX, and Solaris
TcpKeepAliveIdleTime platforms. On other platforms, the parameter has no effect. 7200 RW/
Startup
This parameter controls the TCP_KEEPIDLE socket option. If the
SO_KEEPALIVE option is enabled with the TcpKeepAlive
parameter, TCP sends a keepalive probe to the remote system of a
connection that has been idle for a period of time. If the remote
system does not respond to the keepalive probe, TCP retransmits a
keepalive probe for a certain number of times before a connection
is considered to be broken. TCP_KEEPIDLE specifies the number of
seconds before TCP will send the initial keepalive probe.

See also parameters TcpKeepAlive, TcpKeepAliveProbeCount and

TcpKeepAliveProbeInterval.

Appendix A. Server-side configuration parameters 167

Table 46. Communication parameters (continued)

Access
[Com] Description Factory Value Mode

TcpKeepAliveProbeCount This parameter can only be used on Linux, HP-UX, and Solaris 9 RW/
platforms. On other platforms, the parameter has no effect. Startup

This parameter controls the TCP_KEEPCNT socket option. If the

SO_KEEPALIVE option is enabled with the TcpKeepAlive
parameter, TCP sends a keepalive probe to the remote system of a
connection that has been idle for a period of time. If the remote
system does not respond to the keepalive probe, TCP retransmits a
keepalive probe for a certain number of times before a connection
is considered to be broken. The TCP_KEEPCNT option specifies the
maximum number of keepalive probes to be sent.

See also parameters TcpKeepAlive, TcpKeepAliveIdleTime and

TcpKeepAliveProbeInterval.
This parameter can only be used for Linux, HP-UX, and Solaris
TcpKeepAliveProbeInterval platforms. On other platforms, the parameter has no effect. 75 RW/
Startup
This parameter controls the TCP_KEEPINTVL socket option. If the
SO_KEEPALIVE option is enabled with the TcpKeepAlive
parameter, TCP sends a keepalive probe to the remote system of a
connection that has been idle for a period of time. If the remote
system does not respond to the keepalive probe, TCP retransmits a
keepalive probe for a certain number of times before a connection
is considered to be broken. The TCP_KEEPINTVL option specifies
the number of seconds to wait before retransmitting a keepalive
probe.

See also parameters TcpKeepAlive, TcpKeepAliveIdleTime and

TcpKeepAliveProbeCount.

Trace If this parameter is set to yes, trace information about network no RW/
messages for the established network connection is written to a file Startup
specified with the TraceFile parameter. The factory value for the
TraceFile parameter is soltrace.out.
If the Trace parameter is set to yes, trace information about
TraceFile network messages is written to a file specified with this TraceFile soltrace.out RW/
parameter. (written to the Startup
current working
directory of the
server or client
depending on
which end the
tracing is started)

WriteBufSize Sets the buffer size in bytes for the data written into the network OS dependent RW/
Startup

General section
Table 47. General parameters

[General] Description Factory Value Access Mode

BackupBlockSize Block size for backup file writing 64 KB RW/Startup

Unit: 1 byte k=KB

If set to yes, solid.ini file will be copied to
BackupCopyIniFile the backup directory yes RW/Startup

168 IBM solidDB: Administrator Guide

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

BackupCopyLog If set to yes, backup operation will copy log yes RW/Startup
files to the backup directory

BackupCopySolmsgOut If set to yes, solmsg.out file is copied to the yes RW/Startup

backup directory

BackupDeleteLog If set to yes, old log files will be deleted yes RW/Startup
after backup operation

BackupDirectory Makes a backup of the database, log files, 'backup' directory RW/Startup
and the configuration file solid.ini, using
the factory value 'backup' or a given name.
For example, BackupDirectory=abc, creates a
backup on directory 'abc'.

The backup directory must exist and it must

have enough disk space for the backup files.
It can be set to any existing directory, except
the solidDB database file directory, the log
file directory, or the working directory.

All directory definitions are relative to the

solidDB working directory unless the full
path is provided.

Note that the backup directory entry must

be a valid path name in the server's
operating system. For example, if the server
runs on a UNIX operating system, path
separators must be slashes instead of
backslashes.
Specifies the maximum number of blocks 100 RW
BackupFlushInterval (pages) that can be stored in memory before
they are flushed to disk during backup
operation.
Controls how frequently netcopy and 0 (no skipping) RW/Startup
BackupStepsToSkip backup tasks are executed. The value is a
number of the tasking system steps that are
skipped between backup execution phases.
Reasonable values are in the range of 2 - 20.

With the factory value 0, the backup

proceeds with the maximum speed.

Appendix A. Server-side configuration parameters 169

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

If this parameter is set to yes, the server no RW/Startup
CheckpointDeleteLog deletes the transaction log file(s) after each
successful checkpoint. This saves disk space,
but makes it impossible to recover data by
rolling forward the logs.

The transaction logs contain a copy of the

transactions executed by the server. If the
database file is erased or corrupted, and if
you have kept the transaction log files, then
you can restore the data by restoring the
backup database file and then rolling
forward all the transaction logs that
accumulated since the last backup. If you
deleted those transaction logs, then you will
lose all transactions since the last successful
backup.

You should only set CheckpointDeleteLog to

yes if your database has data that you are
willing to risk losing (for example, test data
created during development). See also the
BackupDeleteLog parameter.
Important:
v If you are using HotStandby and if you
set CheckpointDeleteLog=yes on the
Primary server, the server deletes only the
logs that are already acknowledged by
Secondary. For example, if the Secondary
is down and the Primary is in PRIMARY
ALONE state, the Primary will keep the
logs even after the data has been
checkpointed on the Primary.
v If LogReader.LogReaderEnabled is set to
yes, the CheckpointDeleteLog parameter
is not effective: the log files are not
deleted after a checkpoint. Instead, the log
entries are removed only after the log size
defined by LogReader.MaxLogSize has
been reached.
The number of writes to the log files made 50000 log writes RW
CheckpointInterval in the database which causes automatic
checkpoint creation. A large setting can
delay checkpoints and make them larger. A
small setting will guarantee a small
checkpoint size.

See also MinCheckpointTime.

Note: CheckpointInterval and
MinCheckpointTime use different units of
measurement. CheckpointInterval is based
on the number of log writes, while
MinCheckpointTime specifies the minimum
time between consecutive checkpoints.

170 IBM solidDB: Administrator Guide

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

When a data "dictionary operation active"
DataDictionaryErrorMaxWait error for prepared statements occurs, the 0 (Disabled) RW/Startup
server automatically attempts to reprepare
the SQL statement, for the time specified Unit: 1 second
with this parameter. If the table is still
compatible with the SQL statement, the
operation can continue without any errors
reported to the user. This parameter should
only be enabled when the thread/client
mode is used (Srv.ReadThreadMode=2),
because the wait blocks the waiting thread.
If set to yes, the precision of NUMERIC is no RW/Startup
DecimalPrecAsNumeric allowed to be greater than specified.
If set to yes, new tables are created as
DefaultStoreIsMemory in-memory tables, unless they are created yes RW
without an explicit STORE clause in the
CREATE TABLE statement. If set to no, new
tables are stored on disk by default. You can
override the factory value by using the
STORE clause in the CREATE TABLE
statement.
Note: System tables are stored on disk, even
if this parameter is set to yes.

DisableIdleMerge If set to yes, database is set to disable idle no RW/Startup

merge.

FileWriteFlushMode FileWriteFlushMode=0 means no flushing 0 on most platforms. RW/Startup

after write or read operations.

FileWriteFlushMode=1 means flush before

reading from the file.

FileWriteFlushMode=2 means flush after

write operations

Appendix A. Server-side configuration parameters 171

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

Starting from version 6.5, this parameter Raw RW/Create
InternalCharEncoding defines the database mode by defining the
encoding used for character data types.

Possible values are 'raw' and 'UTF8'.

v Unicode mode
In the Unicode mode, the internal
representation for character data types is
UTF-8.
The internal representation for wide
character data types is UTF-16.
v partial Unicode mode
In the partial Unicode mode, the internal
representation for character data types
uses no particular encoding; instead, the
data is stored in byte strings with the
assumption that user applications are
aware of this and handle the conversion
as necessary.
The internal representation for wide
character data types is UTF-16.
The databases created with solidDB
version 6.3 or earlier are of the partial
Unicode type.
Important: The default database mode in
6.5 is partial Unicode.

If the value of this parameter is 'raw', the

default value of the parameter
Srv.ODBCDefaultCharBinding is also 'raw'.

If the value of this parameter is 'UTF8', the

default value of the parameter
Srv.ODBCDefaultCharBinding is 'locale:'.

IOThreads Number of helper I/O threads (per IO 5 RW/Startup

device) for read and write purposes.
Note: You can restrict the number of write
threads with the WriterIOThreads parameter.

The IOThreads must be greater than

WriterIOThreads. If this rule is violated, the
IOThreads parameter takes the precedence
(wins).

172 IBM solidDB: Administrator Guide

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

LockHashSize The server uses a hash table (array) to store 1000000 RW/Startup
lock information. If the size of the array is
remarkably underestimated the performance
degrades. Too large hash table doesn't affect
directly to the performance although it
causes memory overhead. The LockHashSize
determines the number of elements in hash
table.

This information is needed when the server

is using pessimistic concurrency control (i.e.
locking). The server uses separate arrays for
in-memory tables and disk-based tables.
This parameter applies to disk-based tables.

In general, the more locks you need, the

larger this array should be. However, it is
difficult to calculate the number of locks
that you need, so you will probably need to
experiment to find the best value for your
applications.

The value that you enter is the number of

hash table entries. Each table entry has a
size of one pointer (4 bytes in 32-bit
architectures). Thus, for example, if you
choose a hash table size of 1,000,000, then
the amount of memory required is 4,000,000
bytes (assuming 32-bit pointers).

Appendix A. Server-side configuration parameters 173

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

LockWaitTimeOut LockWaitTimeout specifies the time in 30 RW

seconds that the engine waits for a lock to
be released. When the timeout interval is Unit: seconds
reached, solidDB terminates the timed-out
transaction.

For example, if one user is querying a

specific row in a table and a second user is
updating the same row, the second user's
update will wait until either the first user's
query is completed or the second user times
out. If the first user's query is completed
before the second user times out, then the
second user is issued a lock for the update.

The maximum lock timeout is 1000 seconds.

The server will not start if the default lock
timeout in solid.ini is more than 1000
seconds.
Note: You can set the lock time out for a
single connection by using the following
SQL command:
SET LOCK TIMEOUT timeout_in_seconds

You can change the granularity of the SET

LOCK TIMEOUT command from seconds to
milliseconds by appending "MS" to the
number. For example:
SET LOCK TIMEOUT 500MS

Note: The SET LOCK TIMEOUT command

does not change the setting in the solid.ini
file.

See also TableLockWaitTimeOut.

LongSequentialSearchLimit Sets the number of sequential fetches after 500 RW/Startup

which search is treated as long sequential
search

MaxMergeParts This parameter is used to specify the 5 RW/Startup

maximum number of concurrent merge
operations, or the number of merge parts.

MaxMergeTasks The merge process can use multiple merge 5 RW/Startup

tasks to accelerate the cleaning up of Bonsai
Tree. This parameter specifies the maximum
number of merge tasks.

MaxOpenFiles Sets the maximum number of files kept OS dependent RW/Startup

concurrently open during solidDB sessions

174 IBM solidDB: Administrator Guide

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

Limits the number of concurrent row writes 0 RW/Startup
MaxWriteConcurrency (update/deletes/insert) performed at a time.

The optimal value depends on the number

of available cores (CPUs) and the scattering
of updates among different tables. The more
cores available and the more scattered the
writes are, the higher the optimal value. The
value should not be higher than the number
of available cores (CPUs).

Value 0 means there is no limit on the

number of concurrent writes.
Sets the number of index inserts made in the
MergeInterval database that causes the merge process to Cache size dependent RW
start

MinCheckpointTime Specifies the minimum time in seconds 300 RW

between two checkpoint operations.
Unit: 1 second
See also CheckpointInterval.
Note: CheckpointInterval and
MinCheckpointTime use different units of
measurement: CheckpointInterval is based
on the number of log writes, while
MinCheckpointTime specifies the minimum
time between consecutive checkpoints.
This sets a minimum time (in seconds)
MinMergeTime between two merge operations. For more 0 RW
information about merge operations, see the
sections “solidDB Bonsai Tree
multiversioning and concurrency control”
on page 6 and “Setting the MergeInterval
parameter” on page 132.
This parameter defines the number of Read from system RW/Startup
MultiprocessingLevel processing units (processors, cores) available
in the computer system. Typically, the
concurrency of write operations in the
database can be improved if the value
matches the number of physical processors
(cores) in your system.

As of V6.5 Fix Pack 4, the factory value is

read from the system as the number of
logical processing units. The auto-detected
value is output to solmsg.out at server
startup. With some processor architectures,
the number of logical processing units might
not be the same as the number of physical
cores. In such cases, the optimal value for
this parameter typically varies between the
number of the physical cores and the
number of logical processing units.

In releases prior to V6.5 Fix Pack 4, the

factory value of this parameter is 4.
Note: As of V6.5 Fix Pack 4, the value of
the MME.RestoreThreads parameter defaults
to the value of this parameter, unless set to
a different value explicitly.
This sets the connect string to the No factory value. RW/Startup
NetBackupConnect Netbackup server.

Appendix A. Server-side configuration parameters 175

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

NetBackupConnectTimeout Sets the maximum time in milliseconds that 30000 RW/Startup

a netbackup operation waits for a
connection to a NetBackup server.

For example, to set the timeout to 60

seconds use value 60000 (milliseconds).

0 (no timeout)

NetBackupCopyIniFile If set to yes, the solid.ini configuration file yes RW/Startup

is copied to the remote backup directory.

NetBackupCopyLog If set to yes, the log files are copied to the yes RW/Startup
remote backup directory.

NetBackupCopySolmsgOut If set to yes, the solmsg.out message file is yes RW/Startup

copied to the remote backup directory.

NetBackupDeleteLog If set to yes, the backed-up log files are yes RW/Startup
deleted from the source server after the
NetBackup has accomplished.

NetBackupDirectory Sets the remote backup directory. The path No factory value. RW/Startup
expression may be relative or absolute.
Non-absolute paths are related to the
working directory of the NetBackup server.

NetBackupReadTimeout Sets the maximum time in milliseconds that 30000 RW/Startup

any operation waits for the response from
the NetBackup server.

For example, to set the timeout to 60

seconds use value 60000 (milliseconds).
If set to yes, the server uses pessimistic
Pessimistic concurrency control for D-tables. With no RW/Startup
pessimistic concurrency control, the server
places locks on rows to control the level of
consistency and concurrency when users are
submitting queries or updates to rows.

The factory value is 'no'; D-tables uses

optimistic concurrency control by default.

When setting the Pessimistic parameter to

'yes', the server defaults to pessimistic
locking for any new tables that are created
and for any old tables for which the
concurrency control method was never
explicitly set with the ALTER TABLE
command.

If you set the locking mode of a table by

using the following ALTER TABLE
command, it takes precedence over this
parameter.
ALTER TABLE base_table_name SET
{OPTIMISTIC | PESSIMISTIC}

176 IBM solidDB: Administrator Guide

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

This parameter specifies in seconds how
ReadLevelMaxTime long an SQL execute can hold the 10 RW/Startup
transaction read level in the READ
COMMITTED isolation level until it is
released.

The default value is 10 seconds.

Readonly If set to yes, database is set to read-only no RW/Startup

mode

SearchBufferLimit Sets the maximum percentage of search 50 RW/Startup

buffers from the total buffered memory
reserved for open cursors.

The search buffer contains a local copy of

the last B-tree page. Because of this, active
searches do not need to go through the
index and cache manager to get to the next
row in the search. Instead, the searches read
the local copy residing in the cache
manager. Other searches can also access the
page for read-only purposes unless it has
been modified by a transaction.

When calculating the buffer limit value, take

the approximate number of active searches
in the database and multiply it by two. The
result is the need for search buffers. After
this, you can calculate the suitable
percentage from the cache size.
If this parameter is set to yes, it forces a
StartupForceMerge merge operation to run when the server is no RW/Startup
started. The server accepts no user
commands until the merge operation has
been completed.
This parameter sets the time in seconds that
TableLockWaitTimeout a transaction waits to get a lock. When 30 RW
messages are executed in the replica, it is
possible to run them in pessimistic or mixed Unit: 1 second
concurrency mode, which means table level
locks are used.

There are times when a transaction will

acquire an exclusive lock to a table. If there
is a conflict, the TableLockWaitTimeout
setting provides the transaction's wait
period until the exclusive or shared lock is
released. This parameter is used for
synchronized databases only.

Table-level locks are used when the

PESSIMISTIC keyword is explicitly provided
in the following solidDB commands:
IMPORT SUBSCRIPTION
MESSAGE message_name EXECUTE
(only with NO EXECUTE option)
MESSAGE message_name FORWARD
MESSAGE message_name GET REPLY
DROP SUBSCRIPTION

See also LockWaitTimeOut.

Appendix A. Server-side configuration parameters 177

Table 47. General parameters (continued)

[General] Description Factory Value Access Mode

When set to yes, early validation of
TransactionEarlyValidate transaction is used (transaction is validated yes RW/Startup
at the time each statement is written, not at
commit time). Early validation is applicable
with optimistic locking only.

The possible values are yes and no.

The hash table contains slots that are
TransactionHashSize occupied by incomplete (open) transactions. 1046527 RW/Startup
The transaction hash size sets the size of the
table for open transactions. Once the
number of occupied slots increases, the
operations with this table become slower.

The database offers higher performance

when the average number of transactions
per slot is lower. For example, 5 is a good
initial limit for the transaction per slot
average.
Note: You can monitor the status of this
hash table using ADMIN COMMAND ’report
filename’.

For example:
ADMIN COMMAND ’report myfile.txt’

The output contains the following related

information:

tablesize = setting

nused = slots taken from hash table

list length = sum of all transactions in the

table

Minimum value is 1000.

This parameter defines whether passwords yes RW/Startup
UseEncryption are encrypted. If set to 'no', passwords are
not encrypted.
If this parameter is enabled, pessimistic yes RW/Startup
VersionedPessimisticReadCommitted D-tables with READ COMMITTED isolation
use versioned reads. Reads with SELECT
FOR UPDATE work as before. In other
words, pessimistic D-tables work like
M-tables.
If this parameter is set to yes, pessimistic
VersionedPessimisticRepeatableRead D-tables with REPEATABLE READ isolation yes RW/Startup
use versioned reads.
Number of helper threads dedicated to
WriterIOThreads writing tasks (per IO device). 1 RW/Startup
Note:

The IOThreads must be greater than

WriterIOThreads. If this rule is violated, the
factory value is used.

If IOThreads=1 then the setting

WriterIOThrreads=0 is enforced.

178 IBM solidDB: Administrator Guide

HotStandby section
Table 48. HotStandby parameters
Parameter name Description Factory value Access mode
1SafeMaxDelay In 1-Safe replication, the maximum delay before a 5000 RW
committed transaction is sent to the Secondary (in
milliseconds).
2SafeAckPolicy This specifies the timing of the Secondary's 1 RW
acknowledgement when it receives a transaction
from the Primary.

Valid values are:

v 1 = 2-safe received. The Secondary server
acknowledges when it receives the data.
v 2 = 2-safe visible. The Secondary server
acknowledges when the data is "visible", that is,
when the Secondary has executed the transaction.
v 3 = 2-safe durable. The Secondary server
acknowledges when it has made the data durable,
that is, when it has committed the data and
written the data to the disk.

2-safe durable is the safest approach, and 2-safe

received has the fastest response time. However, in
practice, the 2-safe received mode provides in most
cases sufficient guarantees for data safety hence
providing the best compromise between safety and
speed.

This parameter applies only if the server is using

2-safe replication.
Note: Although this parameter controls the
Secondary server's behavior, this parameter is set on
the Primary. The value in the Secondary's solid.ini
value is ignored.
AutoPrimaryAlone If this parameter is set to yes, the server is no RW
automatically put in PRIMARY ALONE state (rather
than PRIMARY UNCERTAIN state) when the
connection to the Secondary is broken.

If you plan to set this to yes, read the warnings in

Network partitions and dual primaries.
CatchupSpeedRate While the server is performing catchup, it also 50 RW
continues to service database requests from clients.
You may use the CatchupSpeedRate parameter to
give greater importance to responding to application
requests and lower priority to catchup, or vice versa.

The speed rate is expressed as a percentage of the

maximum available speed dictated by the link and
Secondary throughput. Larger numbers mean more
emphasis on catchup and less on servicing client
requests. Valid values are 1-99.

Appendix A. Server-side configuration parameters 179

Table 48. HotStandby parameters (continued)
Parameter name Description Factory value Access mode
Connect The Connect parameter indicates the address of the No factory value. RW
other HotStandby server in the pair.

The format of the Connect string in the HotStandby

section is the same as the format of the Listen
parameter in the [Com] section.

If you omit this parameter in a server that you

intend for HotStandby, then you can set this
parameter dynamically by using an ADMIN
COMMAND. Until the server has a Connect string,
the server can only be in the states that do not
involve a connection, that is, PRIMARY ALONE,
SECONDARY ALONE, and STANDALONE.

The Connect parameter is ignored unless the

HSBEnabled parameter is set to yes.

For Transparent Connectivity (TC) connections, the

Connect parameter can be overridden with the
TCConnect parameter.
ConnectTimeout By specifying a connect timeout value, you can set 0 (no timeout) RW
the maximum time in seconds that a HotStandby
connect operation waits for a connection to a remote Unit: 1 ms
machine.

The ConnectTimeout parameter (which is useful only

on certain platforms) is only used with certain
administration commands. These are:
v hotstandby connect
v hotstandby switch primary
v hotstandby switch secondary

For example, to set the timeout to 30 seconds (30000

milliseconds):
[HotStandby]
ConnectTimeout=30000

See also PingTimeout.

CopyDirectory The CopyDirectory parameter in the [HotStandby] No factory value RW
section defines a name and location for the
HotStandby copy operation that is performed when
the user executes the command:
ADMIN COMMAND ’hotstandby copy’;

For example, the parameter may look like:

[HotStandby]
CopyDirectory=C:\solidDB\secondary\dbfiles

If you provide a relative path for the CopyDirectory

parameter, the path will be relative to the directory
that holds the Primary server's solid.ini file.

This parameter has no factory value, so if the

directory is not specified in the solid.ini file, it
must be provided in the copy command.

The ADMIN COMMAND 'hotstandby netcopy' is the

recommended way to copy the database because it
is a more flexible solution.

180 IBM solidDB: Administrator Guide

Table 48. HotStandby parameters (continued)
Parameter name Description Factory value Access mode
HSBEnabled If this parameter is set to yes, the server may act as no RO
a HotStandby Primary or Secondary server. If this
parameter is set to no, then the server may not act as
a HotStandby server.

Setting this parameter to yes will implicitly define

the default initial state of the server to be
SECONDARY ALONE when the server first starts.
Valid values are yesand no.

To use HotStandby, you must also specify the

Connect parameter, either by setting it in the
solid.ini file or by using an ADMIN COMMAND
to set it.
MaxLogSize Maximum size of the disk-based HSB log. The 0
factory value: unlimited
Unit: 1 byte k=KB
m=MB
MaxMemLogSize When the file-based logging is disabled 8M RO
(Logging.LogEnabled=no), the size of the in-memory
log holding transactions before they are sent to the Unit: 1 byte k=KB
Secondary. The value affects the time the server may m=MB
stay in the PRIMARY ALONE state, before the
in-memory log becomes full.
NetcopyRpcTimeout Data transmission acknowledgment timeout for 30000 RW
netcopy operation (in milliseconds)
Unit: 1 ms
PingInterval The Primary and Secondary send "ping" messages to 1000 (one second) RW
each other at regular intervals to make sure that
they are still connected. (These pings are Unit: 1 ms
independent of the transaction information that the
Primary sends to the Secondary.)

The value is equal to the interval (in milliseconds)

between two consecutive pings sent by a server.
PingTimeout The parameter specifies how long a server should 4000 (four seconds) RW
wait before concluding that the other server is down
or inaccessible. Unit: 1 ms

After the time specified (in milliseconds) has passed

the server concludes that a connection is broken and
changes the state accordingly.

See also ConnectTimeout.

PrimaryAlone This parameter is deprecated. Use the no RW
AutoPrimaryAlone parameter.
SafenessLevel This parameter sets the safeness level of the Possible values are: RW
replication protocol. 1safe, 2safe and
auto
By using the auto value, you can allow the safeness
level to dynamically change in relation to the
durability level. If you set SafenessLevel to auto
and set the durability to relaxed by using the SET
DURABILITY command or the DurabilityLevel
parameter, the safeness level is set to 1-safe, and
when you set the durability level to strict, the
safeness level is set to 2-safe. However, if
DurabilityLevel is set to 2 (Adaptive Durability),
the "auto" setting has no effect - the safeness level
will always be 2-safe.

Appendix A. Server-side configuration parameters 181

Table 48. HotStandby parameters (continued)
Parameter name Description Factory value Access mode
TCConnect This parameter overrides the connect string defined No factory value. RW
with the Connect parameter for the purposes of
Transparent Connectivity (TC) connections, where
the servers need to use different networks to connect
to each other.

By default, the secondary servers provide the

Connect connect string to the TC clients for
specifying the location of the primary server. If the
servers use different network to connect to each
other and TC clients cannot or are not supposed to
use the same network, the TCConnect parameter can
be used to override the Connect connect string.

IndexFile section
Table 49. IndexFile parameters

[IndexFile] Description Factory Value Access Mode

BlockSize Sets the block size of the database file in bytes; use multiple of 2 16 KB RO
KB: minimum 2 KB, maximum 64 KB
Unit: 1 byte
k=KB

CacheSize Sets the size of database cache memory for the server in bytes; the 32 MB RW
minimum is 512 kilobytes. Although solidDB is able to run with a
small cache size, a larger cache size speeds up the server. The Unit: 1 byte
cache size needed depends on the size of the database file, the k=KB m=MB
number of connected users, and the nature of the operations
executed against the server.

You can change the CacheSize value dynamically with the ADMIN
COMMAND. For example:
ADMIN COMMAND ’parameter IndexFile.CacheSize=40mb’

Attention: Setting the CacheSize to a value larger than the

amount of memory available may significantly degrade
performance. If your system only has a small amount of free
memory available, you should reduce the CacheSize.
DirectIO Defines if the index file uses Direct I/O. Direct I/O means that no RW/Startup
operating system buffer pool is bypassed in file I/O.

This parameter is not effective in Windows environments; in

Windows environments, database files always use Direct I/O.
Sets the number of blocks of disk space that are allocated at one
ExtendIncrement time when solidDB needs to allocate more space for the database 500 RW/Startup
file. If each block is 8 KB, the value of 500 corresponds to 4 MB of
disk space.

182 IBM solidDB: Administrator Guide

Table 49. IndexFile parameters (continued)

[IndexFile] Description Factory Value Access Mode

Defines the location, name, and the maximum size of the index
FileSpec_[1... N ] file. In solidDB, the term index file is used as a synonym for solid.db RO
database file. 2147483647
(2G-1 bytes)
The parameter accepts the following arguments:
v database file location - default is solidDB working directory
v database file name
v maximum size (in bytes)
v device number
The device number is an optional argument that defines is the
physical drive number. The number value itself is not essential,
but it is used as a hint for I/O threads, allowing the server to
perform database file I/O requests in a parallel manner if you
split the file into multiple physical disks.

For example:
FileSpec_1=c:\soldb\solid.db 200000000

The N in the parameter syntax signifies the number of the file if

the database file is divided into multiple files and onto multiple
disks. For more information, see “FileSpec_[1...n] parameter” on
page 53.

To achieve better performance, the database file must be stored to

a local drive using local disk names to avoid problems with
network I/O.

You can also have multiple files on a single disk if your physical
disk is partitioned into multiple logical disks and no single logical
disk can accommodate the size of the database file you expect to
create.

PreFlushPercent Sets the percentage of page buffer which is kept clean by the 25 RW/Startup
preflush thread.

Note that the preflush operations prepare the cache for the
allocation of new blocks. The blocks are written onto the disk from
the tail of the cache based on a Least Recently Used (LRU)
algorithm. Therefore, when the new cache blocks are needed, they
can be taken immediately without writing the old contents onto
the disk.

ReadAhead Sets the number of prefetched index reads during long sequential 4 RW/Startup
searches.

Note that when the I/O manager is handling a long sequential

search, it enters a read-ahead operation mode. This mode ensures
that the next file blocks of the search in question are read into the
cache in advance. This improves the overall performance of
sequential searches.

Appendix A. Server-side configuration parameters 183

Table 49. IndexFile parameters (continued)

[IndexFile] Description Factory Value Access Mode

ReferenceCacheSizeForHash solidDB uses a hash table to ease access to the cache. The hash 0 RW/Startup
table size equals the number of pages in the cache. This guarantees
almost collision-free access. If the cache size is increased
dynamically, the hash table is not automatically enlarged. This
results in a higher collision probability. To avoid this, you can use
the ReferenceCacheSizeForHash parameter to accommodate the
enlarged cache. The ReferenceCacheSizeForHash parameter value
is used for calculating the cache hash table size. You should only
use the parameter if you know, in advance, what will be the
maximum cache size during the server lifecycle. On the other
hand, if the value is not given, hash table collisions may occur
when the cache size is increased.
Note: The ReferenceCacheSizeForHash parameter value must not
be smaller than the CacheSize value. If it is, the
ReferenceCacheSizeForHash parameter value is rejected and the
default value is used. Also, a message is printed to the solmsg.out
log file.

SynchronizedWrite On UNIX/Linux platforms this parameter may be set to "no" to yes RW/Startup
enact asynchronous I/0. Asynchronous I/O provides, in general,
more performance but it can cause higher variance of response
latencies (lower latency determinism).

Logging section
Table 50. Logging parameters

[Logging] Description Factory Value Access Mode

Sets the block size of log files. The log block size may be changed
BlockSize between startups. Logs having block size different than the one set 16 KB RW/Startup
are accepted at recovery.
Unit: byte k=KB
The value has to be a multiplicity of 1 KB. Bigger blocks reduce
the overhead of log writing.
Specifies the template character that will be replaced in the name
DigitTemplateChar template of the log file. See the description of the # RW/Startup
FileNameTemplate for more details.
DirectIO Defines if the log file uses Direct I/O. Direct I/O means that no RW/Startup
operating system buffer pool is bypassed in file I/O.

This parameter is not effective in Windows environments; in

Windows environments, database files always use Direct I/O.

184 IBM solidDB: Administrator Guide

Table 50. Logging parameters (continued)

[Logging] Description Factory Value Access Mode

This parameter controls whether the transaction durability level is 1 RW
DurabilityLevel strict, relaxed, or adaptive.
v 1 = relaxed durability
If durability is relaxed, writes are asynchronous; there can be a
delay between the time that the transaction is committed and
the time that it is logged.
v 2 = adaptive durability
This value applies only to HSB (HotStandby) Primary servers.
v 3 = strict durability
If durability is strict, writes to the transaction log are
synchronous; as soon as a transaction has been committed, the
transaction is written to the transaction log.See “Logging and
transaction durability” on page 123 for more details.

The durability level may be set dynamically by using the

command:
ADMIN COMMAND
’parameter Logging.DurabilityLevel=n’;

where n is one of the valid values for this parameter.

Each connection may override this solid.ini parameter by using

the SET DURABILITY or SET TRANSACTION DURABILITY
command.

The DurabilityLevel parameter affects the server's behavior only

if transaction logging is turned on. If you turn off transaction
logging by setting Logging.LogEnabled to no, your data will not be
logged to disk, regardless of the setting of DurabilityLevel. If
Logging.LogEnabled is set to no and DurabilityLevel is set, the
server will briefly display a warning message at the time that it
starts.

See also Logging.LogWriteMode and HotStandby.2SafeAckPolicy

parameters.
This parameter controls log file flush behavior. This parameter is
FileFlush only valid for platforms supporting Synchronized I/O Data yes RW/Startup
Integrity Completion. These are such as Solaris, HP-UX, and
Linux.

When set to no in these platforms, the operating system, rather

than the solidDB engine, flushes the log file.

Appendix A. Server-side configuration parameters 185

Table 50. Logging parameters (continued)

[Logging] Description Factory Value Access Mode

Defines the path and naming convention used when creating log
FileNameTemplate files. These log files contain information used to recover data if the sol#####.log RW/Startup
server crashes.

This parameter defines at least the naming convention used when

creating log files, but not necessarily the path. If the path is not
defined, the Logging.LogDir parameter defines the path.

Template characters (for example, "#") are replaced with sequential

numbers; for example, the following file entry instructs solidDB to
create log files in directory C:\soliddb\log and to name them
sequentially starting from sol00001.log.
FileNameTemplate =
c:\soliddb\log\sol#####.log

Your template may use between 4 and 10 template characters. If

you do not want to use the "#" sign as a template character, you
may specify a different character by setting the parameter
Logging.DigitTemplateChar.

If the number of log files exceeds the maximum possible number

(for example, all names from sol00001.log to sol99999.log are
used up), the server will give an error message and exit. The error
message will be similar to the following:
"Error: Illegal log file name template.
Most likely the log file name
template specified in solid.ini ...
contains too few or too many sequence
number digit positions. There should
be at least 4 and at most 10 digit
positions."

To achieve better performance by avoiding problems with network

I/O, store the log files on a local drive using local disk names.
This parameter sets the directory prefix of the log file path, if it is
LogDir not specified with the Logging.FileNameTemplate parameter. By "." (the server's RW/Startup
default, Logging.FileNameTemplate specifies only the file name and working
Logging.LogDir specifies the path, which is the server's working directory)
directory.

The specified log directory has to exist prior to starting the server.
If the directory does not exist, solidDB returns the following type
of error:
SsBOpenLocal failed, file ’log/sol00001.log’,
errno = 2, retries = 0, open files = 1
Specifies whether transaction logging is enabled or not. If
LogEnabled transaction logging is disabled, you will get better performance yes RW/Startup
but lower transaction durability; (if solidDB shuts down
unexpectedly, you lose any transactions since the last checkpoint).
This parameter applies to in-memory tables and disk-based tables.
Specifies the mode in which the log will be written. The following
LogWriteMode two modes are available: 2 (Overwrite RW/Startup
v 0: ping-pong method method)

v 2: overwrite method (factory value)

The choice of logging method depends on the log file media and
the level of security required. For details on each of these methods,
read “Transaction logging” on page 35.

186 IBM solidDB: Administrator Guide

Table 50. Logging parameters (continued)

[Logging] Description Factory Value Access Mode

Defines the log file size after which logging will be continued to
MinSplitSize the following log file after the next checkpoint 10 MB RW/Startup

Unit: 1 KB k=KB
m=MB
This parameter sets the maximum time in milliseconds that the
RelaxedMaxDelay server waits until the committed transaction(s) are written to the 5000 milliseconds RW/Startup
log. This parameter applies only when the transaction durability (5 seconds)
level is set to RELAXED with the Logging.DurabilityLevel=1
parameter or the SET DURABILITY statement). Unit: 1 ms

The units are milliseconds. Minimum allowed value: 100 (100

milliseconds).
When set to yes, solidDB assumes that the platform supports
SyncWrite Synchronized I/O Data Integrity Completion. no RW/Startup

This parameter applies only to platforms, such as Solaris, HP-UX,

and Linux, which support Synchronized I/O Data Integrity
Completion. It should be set to no on all other platforms.

LogReader section
Table 51. Log Reader parameters

[LogReader] Description Factory Value Access Mode

LogReaderEnabled By using this parameter, you can no RO

enable or disable the log reader
capability.

In solidDB Universal Cache and

configurations with InfoSphere
CDC Replication, this parameter
must be set to yes.

Appendix A. Server-side configuration parameters 187

Table 51. Log Reader parameters (continued)

[LogReader] Description Factory Value Access Mode

MaxLogSize This parameter defines the size of 10240 RW

the protected portion of the
disk-based transaction log.

When the log files are removed

(for example after a backup), at
least the specified amount of the
log data is retained. The protected
portion of the log facilitates a
possible catchup after a failure case
when the replication has not been
active for some time.

The actual log size may exceed the

MaxLogSize value, if the log files
are not removed. Catchup is
possible as long as the propagator
log position is within the existing
log.

The minimum value is 5 (5 MB). If

you attempt to define a smaller log
size, it is automatically changed to
5 MB. The maximum possible log
size is practically unlimited.

Unit: megabytes.

MaxSpace This parameter defines the 100000 RW

maximum number of log records
buffered before slowdown.

The log records are buffered in an

in-memory log reader buffer. The
size of a log record is that of the
(binary) row size, plus a few bytes
of additional metadata overhead.

When the buffer fills up,

throughput throttling is applied in
solidDB: the operations are blocked
until there is room in the logreader
buffer.

The throttling only takes place

when the log reading is active. If
there is no log reader activity,
solidDB continues the processing
and log files are preserved at least
until the defined MaxLogSize limit
is reached (see above).

188 IBM solidDB: Administrator Guide

Table 51. Log Reader parameters (continued)

[LogReader] Description Factory Value Access Mode

MaxMemLogSize Maximum size of the Log Reader 1 MB RW
logfile in memory, when logging is
not enabled (Logging.LogEnabled =
no). After maximum size is
reached, logreader catchup might
not be possible anymore.

Unit: megabytes.
Silent If set to Yes, the Log Reader no RW/Startup
activities are not output to
solmsg.out.

Possible values are yes and no.

MME section
Table 52. MME parameters
[MME] Description Factory Value Access Mode

ImdbMemoryLimit This sets an upper limit on the amount of memory (virtual 0 RW

memory) that the server will allocate for in-memory tables and
indexes on in-memory tables. In-memory tables includes Unit: 1 byte
Temporary Tables and Transient Tables, as well as persistent k=KB m=MB
in-memory tables. g=GB

The limit may be specified in bytes, kilobytes (KB), megabytes

(MB), or gigabytes (GB). For example:
ImdbMemoryLimit=1073741824
ImdbMemoryLimit=1048576kb
ImdbMemoryLimit=1024MB
ImdbMemoryLimit=1GB

Value 0 means "no limit".

As a general rule, for servers with 1 GB or less memory, the

maximum amount that you should allocate to in-memory tables is
usually 30% - 70% of the system's physical memory. The more
memory the system has, the larger the percentage of it you may
use for in-memory tables.
Note: This parameter only applies only to solidDB main memory
engine tables. It does not apply to disk-based tables.

You can change this parameter with the command:

ADMIN COMMAND ’parameter
MME.ImdbMemoryLimit=n[kb|mb|gb]’;

where 'n' is a positive integer. You may only increase, not

decrease, this value while the server is running. The command
takes effect immediately. The new value is written back to the
solid.ini file at shutdown.
Important: Ensure that your in-memory tables will fit within the
available physical memory. If you exceed the amount of physical
memory available, performance will decrease significantly. If you
use up all of the available virtual memory, the server will abruptly
limit inserts, updates, and so on, and will return error codes.

Appendix A. Server-side configuration parameters 189

Table 52. MME parameters (continued)
[MME] Description Factory Value Access Mode
Once you have set ImdbMemoryLimit, you may set this additional
ImdbMemoryLowPercentage parameter to give you advance warning before you use up all of 90 RW
memory. This ImdbMemoryLowPercentage parameter allows you to
indicate what percentage of memory you may use before the
server starts limiting your ability to insert rows into in-memory
tables, and so on. For example, if ImdbMemoryLimit is 1000MB and
ImdbMemoryLowPercentage is 90 (percent), then the server will stop
accepting inserts when you've used up 900 megabytes of memory
for your in-memory tables.

Valid values are between 60 and 99 (percent).

Note: This parameter only applies to solidDB main memory
engine tables.
This parameter sets a warning limit for the IMDB memory size.
ImdbMemoryWarningPercentage The warning limit is expressed as a percentage of the 80 RW
ImdbMemoryLimit parameter value. When the
ImdbMemoryWarningPercentage limit is exceeded, a system event is
given.

The ImdbMemoryWarningPercentage parameter value is

automatically checked for consistency. It must be lower than the
ImdbMemoryLimit parameter value.
Note: This parameter only applies to solidDB main memory
engine tables. It does not apply to disk-based tables.
Typically, when the server needs to use locks to prevent
LockEscalationEnabled concurrency conflicts, the server locks individual rows. This means no RW/Startup
that each user affects only those other users who want to use the
same row(s). However, the more rows are locked, the more time
the server must spend checking for conflicting locks.

In some cases, it is worthwhile to lock an entire table rather than a

large number of the rows in that table.

When this parameter is set to yes, the lock level is escalated from
row-level to table-level after a specified number of rows (in the
same table) have been locked within the current transaction.

Lock escalation improves performance, but reduces concurrency,

because it means that other users are temporarily unable to use
the same table, even if they want to use different rows within that
table.

See also the parameter LockEscalationLimit.

Possible values are yes and no.

Note: This parameter applies to in-memory tables only.

LockEscalationLimit If LockEscalationEnabled is set to yes, this parameter indicates 1000 RW/Startup

how many rows must be locked (within a single table) before the
server will escalate lock level from row-level to table-level. See
LockEscalationEnabled for more details.

The value may be any number from 1 to 2,147,483,647 (2^32-1).

Note: This parameter applies to in-memory tables only.

190 IBM solidDB: Administrator Guide

Table 52. MME parameters (continued)
[MME] Description Factory Value Access Mode

LockHashSize The server uses a hash table (array) to store lock information. If 1000000 RW/Startup
the size of the array is remarkably underestimated the
performance degrades. Too large hash table doesn't affect directly
to the performance although it causes memory overhead. The
LockHashSize determines the number of elements in hash table.

This information is needed when the server is using pessimistic

concurrency control (locking). The server uses separate arrays for
in-memory tables and disk-based tables. This parameter applies to
in-memory tables.

In general, the more locks you need, the larger this array should
be. However, it is difficult to calculate the number of locks that
you need, so you may need to experiment to find the best value
for your applications.

The value that you enter is the number of hash table entries. Each
table entry has a size of one pointer (4 bytes in 32-bit
architectures). Thus, for example, if you choose a hash table size of
1,000,000, then the amount of memory required is 4,000,000 bytes
(assuming 32-bit pointers).
This parameter defines the maximum bytes stored into the free list 100000 RW/Startup
MaxBytesCachedInPrivateMemoryPool of MME's private memory pool (private memory pool is private
for each main-memory index). If there is more free memory in the
private pool, the extra memory is merged into global pools.

Value 0 means immediate merge to global pool, usually degrades

performance, but minimizes memory footprint. There is no
maximum value; the default value of 100000 gives good
performance with little memory overhead.

MaxCacheUsage The value of MaxCacheUsage limits the amount of D-table cache 8MB RW/Startup
used while checkpointing M-tables. The value is expected to be
given in bytes. Regardless of the value of the MaxCacheUsage at
most half of the D-table cache (IndexFile.CacheSize) is used for
checkpointing M-tables. Value MaxCacheUsage=0 sets the value
unlimited, which means that the cache usage is
IndexFile.CacheSize/2.
MaxTransactionSize This parameter defines the maximum approximate size of a 0 RW
transaction in bytes.

Some MME transactions (for example, DELETE FROM <table>)

might cause solidDB to allocate a lot of memory for the operation.
This can lead to an out-of-memory situation where solidDB cannot
allocate any more memory from the operating system, and
performs an emergency exit. To prevent this, use this parameter to
define the maximum approximate size (in bytes) for each MME
transaction; when the transaction size exceeds the value set with
this parameter, the transaction fails with the error SOLID Database
error 16509: MME transaction maximum size exceeded.

Value 0 means unlimited.

Appendix A. Server-side configuration parameters 191

Table 52. MME parameters (continued)
[MME] Description Factory Value Access Mode
MemoryPoolScope This parameter sets the memory pool scope. Possible values are Global RW/Startup
Global and Table.

When set to Table, only objects that belong to the same database
table are allocated from a single memory segment. This ensures,
for example, that dropping a whole table frees the memory
segment back to operating system. Only unused memory
segments can be returned back to system.

When set to Global, memory pools are shared between all MME
data.

When MME.MemoryPoolScope is set to Table, you can use the

DESCRIBE <table> statement to view the memory consumption
for the table. For example:
DESCRIBE tmemlimit_tab;
RESULT
------
Catalog: DBA
Schema: DBA
Table: TMEMLIMIT_TAB
Table type: in-memory

Memory usage: 7935 KB (total), 7925 KB (active),

6192 KB (rows), 1733 KB (indexes).

...
1 rows fetched.
NumberOfMemoryPools This parameter defines the number of global memory pools. 1 RW/Startup
Bigger values may give better performance on multicore systems
with certain load scenarios but they also increase memory slack
and hence server process size.

Minimum value is 1. There is no maximum value; however, the

number of cores in the system should not be exceeded.
When set to yes, at shutdown, the server releases the memory
ReleaseMemoryAtShutdown used by M-tables explicitly, rather than relying on the operating no RW/Startup
system to clean up all memory associated with this process. Some
operating systems may require you to set this to yes to ensure that
all memory is released.

The possible values are yes and no.

The factory value is no because shutting down the server is faster

that way.
RestoreThreads This parameter defines the maximum number of threads used Same as General. RW/Startup
while restoring in-memory database during database startup. If Multiprocessing
you do not set this parameter explicitly, the value of this Level
parameter is set to the same value as General.
MultiprocessingLevel.

Possible values are between 1 and 65536. Value 1 means that the
load is executed in single thread.

With invalid values, this parameter defaults to the value of

General. MultiprocessingLevel.

In-memory database restore assigns one thread per each table if

the number of tables is smaller or equal to the number of the
parameter value.

Maximal concurrency is reached when the parameter value is

smaller than the following two values: number of
cores/processors, and the number of tables in the database.

192 IBM solidDB: Administrator Guide

Passthrough section
Table 53. SQL passthrough parameters
Factory Access
[Passthrough] Description value mode
ComplexNumNonindexedConstr This parameter specifies the minimum number of non-indexed 0 RW
WHERE clause constraints in a complex statement.

If a statement has less non-indexed constraints of the following type,

the statement is not complex and it is not passed through to the back
end: the WHERE clause constraint does not resolve with index, the
index does not exist, or the optimizer chooses different index for
constraint.

Value 0 (zero) means that number of non-indexed constraints is not

used when estimating if the statement is complex.

This parameter is effective only when the passthrough mode is

CONDITIONAL.

Use the performance counter Passthrough complex by num non indexed

constraints to monitor the number of statements that are passed
through when this parameter is set.
ComplexNumOrderedRows This parameter specifies the minimum estimated number of rows 0 RW
which must be sorted in a complex statement.

If a statement has less than the estimated number of sortable rows, the
statement is not complex and it is not passed through to the back end.

Value 0 (zero) means that number of sortable rows is not used when
estimating if the statement is complex.

This parameter is effective only when the passthrough mode is

CONDITIONAL.

Use the performance counter Passthrough complex by num ordered rows

to monitor the number of statements that are passed through when
this parameter is set.
ComplexNumTables This parameter specifies the minimum number of tables in a complex 0 RW
statement.

If a statement has less tables than specified with this parameter, the
statement is not complex and it is not passed through to the back end.

Value 0 (zero) means that number of tables is not used when

estimating if the statement is complex.

This parameter is effective only when the passthrough mode is

CONDITIONAL.

Use the performance counter Passthrough complex by num tables to

monitor the number of statements that are passed through when this
parameter is set.

Appendix A. Server-side configuration parameters 193

Table 53. SQL passthrough parameters (continued)
Factory Access
[Passthrough] Description value mode
ErrorMapFileName Specifies the file path and file name for mapping backend native error No factory RW/
codes to solidDB error codes. value. Startup
<file_path><file_name>

For example:
[Passthrough]
ErrorMapFileName=myfiles/db2tosoliderrors.txt

If ErrorMapFileName is not defined or the error is not mapped, the

native backend error codes are mapped to solidDB error 13456
(Passthrough backend error: SQLState=<value>, NativeError=<back-
end error identifier>, MessageText=<back-end error description>).

The entries in the mapping file have the following format:

<backend_error> <solidDB error> ; rest of the line is comment

As in the solid.ini configuration file, semicolon can be used to add

comments.

Example:
; this file maps DB2 native errors to solidDB native errors
-207 13015 ; column not found
-407 13110 ; NULL not allowed for non NULL column
; end of errormappings

For more examples on the mapping files, see the samples/

sqlpassthrough directory in the solidDB installation directory.
Force32bitODBCHandles The Force32bitODBCHandles parameter is needed in 64-bit no RW/
environments when the back-end data server is DB2® for Linux, UNIX, Startup
and Windows and the IBM Data Server Driver for CLI and ODBC is
used with direct linking.

When set to yes, solidDB server treats the ODBC handles as 32-bit
integers instead of the 64-bit void pointers that are native on the 64-bit
platforms.
IgnoreOnDisabled The IgnoreOnDisabled parameter defines how the application program yes R/W
perceives the fact that passthrough is disabled. If the value is yes, all
the statements related to passthrough (SET PASSTHROUGH ...) are
ignored. If the value is no, an error is return on any effort to execute
those statements.

Possible values are yes and no.

PassthroughEnabled The PassthroughEnabled parameter defines whether SQL passthrough no RW/
is enabled or not. Startup
v If passthrough is enabled but it cannot be initialized (for example,
driver is not found), errors are returned on each effort to pass a
statement to the back-end.
v If the back-end server is shut down in a controlled way, the value of
the PassthroughEnabled parameter can be set dynamically to no. The
behavior exposed to the applications is then defined with the
IgnoreOnDisabled parameter.

Possible values are yes and no.

RemoteServerDriverPath The RemoteServerDriverPath parameter specifies the driver manager RW/
path or the driver path for the back-end data server specific ODBC Startup
driver that solidDB is linked to.

194 IBM solidDB: Administrator Guide

Table 53. SQL passthrough parameters (continued)
Factory Access
[Passthrough] Description value mode
RemoteServerDSN The RemoteServerDSN parameter specifies the data source name (if RW/
driver manager is used) or the connect string for the back-end data Startup
server specific ODBC driver that solidDB is linked to.

The connect string must in the format of the ODBC call SQLConnect(),
as ServerNam.
SqlPassthroughRead The SqlPassthroughRead parameter defines how read statements are none R/W
passed from the solidDB server to the back-end.

Possible values are 'None', 'Conditional', and 'Force'.

SqlPassthroughWrite The SqlPassthroughWrite parameter defines how write statements are none R/W
passed from the solidDB server to the back-end.

Possible values are none, conditional, and force.

SharedMemoryAccess section
Table 54. Shared memory access parameters
[SharedMemoryAccess] Description Factory value Startup
MaxSharedMemorySize This parameter sets the maximum total size of the 0 (automatic) RW
shared memory area used by solidDB.
Unit: 1 byte,
If the SMA server tries to allocate more, an "out of G=GB, M=MB,
memory" error occurs. With value "0", the maximum K=KB
value is set automatically to be the size of the
physical memory of the computer (platform
specific).
Note: The value set with the
SharedMemoryAccess.MaxSharedMemorySize parameter
takes precedence over the value set with any
corresponding kernel parameter (for example,
SHMALL in Linux environments). Because of this,
the value set with the
SharedMemoryAccess.MaxSharedMemorySize parameter
should never be higher than the value set with the
corresponding kernel parameter.

If you set the

SharedMemoryAccess.MaxSharedMemorySize
parameter, do not use the Srv.ProcessMemoryLimit
parameter.
SharedMemoryAccessRights This parameter sets a validation context for the user group RW
access to the shared memory area.

The validation context is modeled after a traditional

file validation mask. The possible values are:
v user – access is granted only to the same user as
the one that started the SMA server
v group – access is granted to any user belonging to
the same group as the one that started the SMA
server
v all – access is granted to all users

Appendix A. Server-side configuration parameters 195

Sorter section
Table 55. Sorter parameters

[Sorter] Description Factory Value Access Mode

BlockSize Block size of the external sorter 0 RW/Startup

files. With the factory value 0,
the database block size is used.
This parameter sets the
MaxCacheUsePercent maximum percentage of cache 25 RW/Startup
pages that can be used for
sorting. The valid values range (that is, 25 percent)
from 10% to 50%.

For example, if the

IndexFile.CacheSize
parameter is set to 20MB, and
if MaxCacheUsePercent is 25, a
maximum of 5MB of memory
is available for sorting.

If you specify both the

MaxCacheUsePercent and the
MaxMemPerSort, the values must
be compatible. You get an error
message if the following is not
true: MaxCacheUsePercent x
CacheSize >= MaxMemPerSort

MaxFilesTotal Maximum number of files used 500 RW/Startup

for sorting
This parameter sets the
MaxMemPerSort maximum memory in bytes 114688 RW/Startup
that is available for one sort
(sorting the result set of one
query).

The value of this parameter

must not exceed the amount of
memory available to the sorter
- see MaxCacheUsePercent for
more information.
This parameter enables or Yes
SorterEnabled disables the usage of the RW/Startup
external sorter. The external
sorter algorithm is used for
sorting processes that do not fit
in main memory.

196 IBM solidDB: Administrator Guide

Table 55. Sorter parameters (continued)

[Sorter] Description Factory Value Access Mode

This parameter defines the Defaults to ".",
TmpDir_[1... N ] name of the directory or RW/Startup
directories that contain (The current directory, that is,
temporary files created when the directory from which the
using the external sorter server was started.)
algorithm. The N signifies the
file directory number, if more
than one directory is used to
store the temporary file. For
example:
TmpDir_1=c:\soldb\temp1
TmpDir_2=d:\soldb\temp2

Note: When this parameter is

specified in the configuration
file, the external sorter
algorithm is enabled.

SQL section
Table 56. SQL parameters

[SQL] Description Factory Value Access Mode

AllowDuplicateIndex If set to yes, allows duplicate index no RO

definitions. This is a backward
compatibility parameter. In versions
preceding 4.5, it was possible to create
duplicate indexes.
If set to yes, audit trail is enabled. no RO
AuditTrailEnabled
Possible values are yes and no.

CharPadding When set to yes, solidDB enforces SQL no RO

standard padding of CHAR values with
blanks (right-filled) to the length defined
for the column. With the default setting
(no), the blanks are discarded. The value of
the parameter does not affect comparisons
(where blanks are always discarded).
Note:
v This parameter is effective only when
using ODBC or JDBC drivers, not when
using solidDB SQL Editor (solsql).
v This parameter affects the ODBC and
JDBC driver behaviour.
v This parameter is not effective in
Unicode databases
(General.InternalCharEncoding=UTF8).

Appendix A. Server-side configuration parameters 197

Table 56. SQL parameters (continued)

[SQL] Description Factory Value Access Mode

ConvertOrsToUnionsCount This parameter specifies the maximum 10 RO

number of OR operations that may be
converted to UNION operations.
Note: This parameter does not force the
optimizer to convert OR operations to
UNION operations; it only sets a
maximum limit on the number of OR
operations that the server may convert to
UNION operations.

CursorCloseAtTransEnd By default, the solidDB ODBC driver closes yes RO

all the cursors opened from the user
connection when a commit is called with
SqlTransact from this connection. If this
parameter is set to no, the cursors are kept
open.
DecFloatPrecision16 If set to yes, the precision of the decimal no RO
float data type is limited to 16 (same as in
solidDB 4.5 and earlier).

In storage, the decimal float type is

inflicted by the column type specification
'DECIMAL' (without scale and precision).

Also, expressions involving DECIMAL or

NUMERIC data types may produce
decimal float values.

By default (no), the precision of the decimal

float data type is 52.

Possible values are yes and no.

If included in the solid.ini file and set to
EmulateOldTimestampDiff yes, the old TIMESTAMPDIFF behavior is no RW/Startup
emulated by the server. This old behavior
returns the integer number of intervals of
type interval by which timestamp_exp2 is
greater than timestamp_exp1. Otherwise,
the default is the new behavior which
returns the integer number of interval as
the amount of full units between
timestamp_exp1 and timestamp_exp2.
If set to no, hints are disabled.
EnableHints yes RW/Startup
For details on hints, see Using Optimizer
hints in IBM solidDB SQL Guide.

Sometimes hints in queries may produce

undesirable effects. They may be disabled
by setting this parameter to no.
By default, when the execution of a
ExecuteNodataODBC3Behaviour DELETE or UPDATE statement does not no RO
affect any rows, the statement returns
SQL_SUCCESS. This is the ODBC v.2
behavior. By setting this parameter to yes,
the SQLSTATE returned in those cases is
SQL_NO_DATA, which conforms to ODBC
v.3.

198 IBM solidDB: Administrator Guide

Table 56. SQL parameters (continued)

[SQL] Description Factory Value Access Mode

Info Sets the level of informational messages 0 RW/Startup

[0-8] printed from the server (0=no info,
8=all info); information is written into the
file defined by parameter InfoFileName, or
into soltrace.out if InfoFileName is not
defined.

InfoFileFlush If set to yes, flushes info file after every yes RW/Startup
write operation

InfoFileName Default info file name. The default name is soltrace.out RW/Startup
soltrace.out. Since the soltrace.out file
may contain information from several
sources, we recommend that you explicitly
set InfoFileName to another name if you
set the Info or SQLInfo parameters to a
number larger than 0.

InfoFileSize Sets the maximum size of the info file. 1 MB RW/Startup

IsolationLevel Possible values: 1 (Read RW

Committed)
3 (SERIALIZABLE)

2 (REPEATABLE READ)

1 (READ COMMITTED)

For more information about transaction

isolation levels, see SET TRANSACTION
ISOLATION in the IBM solidDB SQL Guide
and section “Choosing transaction isolation
levels” on page 125.
Important: In-memory tables support only
the READ COMMITTED and
REPEATABLE READ isolation levels.
Latin1CaseSemantics If set to no, uppercase/lowercase yes RW/Startup
conversions are disabled for characters
with decimal value between 126 and 256.

Appendix A. Server-side configuration parameters 199

Table 56. SQL parameters (continued)

[SQL] Description Factory Value Access Mode

MaxBlobExpressionSize Certain string operations use only the first 1024KB (1MB) RW/Startup
N bytes of a character value, not the entire
value. For example, the LOCATE() Unit: 1 KB m=MB
operation checks only the first N bytes of
the string. If you want to tell the server to
check further into (or less far into) long
strings, you may set this parameter.

By default, the units are kilobytes — for

example, "64" means 64KB You may specify
"MB" if you want to express the units in
megabytes.

This parameter applies to all the character

data types, including CHAR, VARCHAR,
LONG VARCHAR, WCHAR,
WVARCHAR, and LONG WVARCHAR.
Since the Wide character data types use 2
bytes per character, the number of
characters searched is half the number of
bytes.

For example, if you set

MaxBlobExpressionSize to 64K bytes, then
the first 32K characters of Wide character
data types will be searched.

MaxNestedProcedures Sets the maximum number of allowed 16 RW/Startup

nested procedures. If this parameter is
defined too high, the server stack may
become insufficient depending on the
operating system.

MaxNestedTriggers Sets the maximum number of allowed 16 RW/Startup

nested triggers. This maximum number
includes both direct and indirect nesting,
so both A → A → A and A → B → A are
counted as three nested triggers.
If set to yes, causes output of DECIMAL no RO
NumericPadding and NUMERIC to be zero-right-padded up
to the specified scale.

ProcedureCache Specifies the number of procedures which 10 RW/Startup

set the size of cache memory for parsed
procedures.

SimpleOptimizerRules When set to yes, simple optimization rules no RO

are used instead of using full optimization
rules.

SortArraySize This parameter sets the size of the array 4000 RW

that SQL uses when ordering the result set
of a query.

The units are "rows" — for example, if you

specify a value of 1000, the server will
create an array big enough to sort 1000
rows of data.

200 IBM solidDB: Administrator Guide

Table 56. SQL parameters (continued)

[SQL] Description Factory Value Access Mode

Sets the level of informational SQL level
SQLInfo messages [0-8] (0=no info, 8=all info); 0 RW/Startup
information is written into a file defined by
parameter InfoFileName, or into
soltrace.out if InfoFileName is not
defined.

TimestampDisplaySize19 If set to yes, the precision (maximum no RO

number of digits) of data type timestamp is
set to 19. In this case, the timestamp is
presented as yyyy-mm-dd hh:mm:ss.

TriggerCache Specifies the number of triggers which set 20 RW/Startup

the size of cache memory that each user
has for triggers.

UpCaseQuotedIdentifiers If set to yes, the SQL identifiers given in yes RW/Startup

quotes are converted to upper case when
reaching the solidDB server. If set to no, the
upper/lower case distinction is preserved
whereby uniqueness of names incorporates
the case too.

Srv section
Table 57. Srv parameters

[Srv] Description Factory Value Access Mode

AbortTimeOut Specifies the time in minutes after an idle 120 RW/Startup

transaction is aborted; negative or zero value
means infinite. Unit: 1 min

AdaptiveRowsPerMessage This parameter takes the average number of yes RW/Startup

rows returned to the client as the rows per
message value. The start value grows as more
rows are fetched. If set to no, the
RowsPerMessage parameter value is used. That is
also the default value.
If set to no, only connections from solidDB
AllowConnect Remote Control (solcon) or solidDB SQL Editor yes RW/Startup
(solsql) are allowed

Appendix A. Server-side configuration parameters 201

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

This parameter can be used specify commands
At for automating administrative tasks, such as (no factory value) RW
executing operating system commands, creating
backups, checkpoints, and database status
reports.

The syntax of the value for this parameter is

the following:
At = At_string
At_string ::= timed_command
[ ,timed_command ]

timed_command ::=
[ day ] HH:MM argument
day ::= sun |
mon |
tue |
wed |
thu |
fri |
sat

For example:
At = 20:30 makecp,
21:00 backup,
sun 23:00 shutdown

If you specify a backup, the default backup

directory is the one set with the
General.BackupDirectory parameter.

If the day is not given, the command is

executed daily.

There is no factory value for this parameter.

For more information about entering time

commands, including a list of the available
commands and their arguments, see section
“Entering timed commands” on page 36.

ConnectionCheckInterval This parameter specifies the number of seconds 10 RW/Startup

between connection status checks in
thread/client mode. Unit: seconds

When the ReadThreadMode parameter is set to 2

(default), the server does not detect a broken
connection until it tries to write something back
to the client.

ConnectTimeOut Specifies the continuous idle time in minutes 480 RW/Startup

after a connection is dropped; negative or zero
value means infinite. Unit: 1 min
Note: The value set with this parameter is not
effective for the SMA handshake connection
that is used to pass the shared-memory
segment handle to the SMA driver.

202 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

DatabaseSizeReportInterval When the database size exceeds the limit 0 MB RW/Startup

defined with this parameter, the system
generates a report file. This parameter gives the
delta after which the next report is printed. The
minimum delta value is 1 MB. The report file
name is repdb<mb>MB.dbg.

This parameter is useful, for example when

tracing unexpected database size growth.

If you leave this parameter to its default value

0, no reports are generated. The minimum
non-zero value for this parameter is 1 MB.

DisableOutput Disables generation of the solmsg.out and the no RO

solerror.out files. For details on these files,
read “Viewing error messages and log files” on
page 63. To disable file generation, this
parameter must be included in the solid.ini
file and set to yes. If this parameter is set to no
or it is not included in the solid.ini file, the
log files are generated.

Echo If set to yes, contents of solmsg.out file are no RW/Startup

displayed also at the server's command
window.

ExecRowsPerMessage This parameter specifies how many result rows 2 RW/Startup

are sent (prefetched) to the client driver in
response to the SQLExecute call with a SELECT
statement. The result rows are subsequently
returned to the application with the first
SQLFetch calls issued by the application. The
default value of 2 allows for prefetching of
single-row results. If your SELECT statements
usually return larger number of rows, setting
this to an appropriate value can improve
performance significantly.

See also the RowsPerMessage parameter.

Appendix A. Server-side configuration parameters 203

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

ForceThreadsToSystemScope This parameter applies only to symmetric Solaris: yes RW/Startup

multiprocess (SMP) Solaris operating systems,
in which the default scope provided by the Other
threads of the runtime library can be set to environments: no
process scope, system scope, or light weight
process (lwp) scope. In Solaris environments,
threads are lightweight processes.

The value yes can improve the server's

performance in a multi-CPU machine
significantly. The actual performance
improvement depends on how evenly the
workload is already spread across your CPUs.
If this parameter is set to no, you should get
slightly better performance in single-CPU
systems.

When this parameter is set to yes, it forces lwp

threads to be run in system scope, instead of
process scope. It also allows Solaris to schedule
solidDB threads on any available CPU. This
reduces bottlenecks and enhances the
parallelization of operations, including I/O. For
more information on lwp, see Solaris operating
system documentation.
HealthCheckEnabled When the parameter is set to yes, a periodical no RW/Startup
check is performed to detect a stalled server
due to, for example, unexpected operating
system stalls or software errors.

The check uses a timeout-based server deadlock

detection algorithm that checks certain critical
low-level concurrent programming
synchronization objects (mutexes).

If a deadlock is detected, the server process

terminates with an error and a message is
printed to solerror.out.

For example in High Availability (HotStandby)

configurations, a failover can be enforced upon
the detection of a server deadlock.
Note: This parameter is not related to
transaction-level deadlock detection
mechanisms.
HealthCheckInterval This parameter sets the interval of the server 60 RW
deadlock check.

Unit: seconds
HealthCheckTimeout This parameter sets the deadlock detection 60 RW
timeout time.

The factory value is high enough to escape false

errors. If faster detection is needed, set the
parameter to a lower value.

Unit: seconds.

204 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

Defines whether in solid.ini configuration file yes RW/Startup
InifileLineSplitting lines that are longer than 79 characters are split
into multiple lines when server saves the file.

For example, if you create comments longer

than 79 characters, the server splits the
comments on separate lines using a backslash
(\) at the end of the line but without adding a
comment marker (;) on the new line. The server
can handle the lines that have been split in this
way; however, applications such as watchdogs
might see the file as corrupted and thus fail.

Value no means lines are never split.

If this parameter is set to yes, the solidDB
KeepAllOutFiles message log (solmsg.out) and trace files are not no RO
overwritten with new contents. Instead, when a
file limit is reached, a new file is created with
an incremented file name number postfix. The
starting value of the postfix is set by using
parameters Srv.TraceBackupFileNum and
Srv.SolmsgBackupFileNum.

LocalStartTasks Number of server's internal tasks that execute 2 RW/Startup

the local background statements that were
started with command START AFTER COMMIT
(without FOR EACH REPLICA).

Valid values range from 1 - 100.

Note:

In this context task refers to solidDB's internal

tasks, not thread or task as used in some
Real-Time Operating Systems. A task is an
operation that has to be executed, such as
checkpoint, backup, or SQL statement.

In this case, you can have 1 to N tasks that

execute the background operations. More tasks
mean that background tasks reserve more
resources and are handled faster, and that other
operations (for example, interactive ones) will
get fewer resources and be handled more
slowly.

Appendix A. Server-side configuration parameters 205

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

This parameter (MAXimum BackGround TASK
MaxBgTaskInterval INTERVAL) tells the server the maximum 2 (seconds) RW/Startup
length of time to wait before checking whether
internal administrative tasks that are "sleeping"
should be "awakened".

The units are seconds.

For example, if a connection has been broken or

disconnected, this parameter specifies the
maximum length of time that the server will
wait before noticing that the connection is gone.
This time is IN ADDITION TO whatever time
is required for the underlying communication
layer to detect that the connection is broken.
For example, if you have a Connect Timeout of
100 seconds and a MaxBgTaskInterval of 50
seconds, then you may have to wait up to 150
seconds before a broken connection is detected
and no longer counted as one of the
connections.

You may want to set or adjust this parameter if

you get errors similar to the following:
Error 08004:
[Solid][SOLID ODBC Driver]

[SOLID]SOLID Server Error 14507:

Maximum number of licensed user
connections exceeded

This parameter only applies to the server's own

internal administrative tasks. It does not affect
the scheduling of user tasks.
Note: MaxBgTaskInterval applies to all server
administration tasks, regardless of each task's
priority. Even when a high priority task is
running, the server will check the low-priority
tasks at the specified intervals.

Setting MaxBgTaskInterval to a small enough

value may reduce performance and may
reallocate some time from high-priority tasks to
low-priority tasks. This can happen in systems
where low-priority connections are not checked
often enough to notice that they have been
disconnected. However, because the parameter
only affects server administrative tasks, not user
tasks, the effect is generally small.

206 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

MaxConstraintLength This parameter controls the maximum number 254 (254 bytes = RW
of bytes that the server will search through in a 254 ASCII
string, for example in WHERE clauses such as: characters, or 127
WHERE LOCATE(sought_string, Unicode
column1) > 0; characters)

For example, if the value is 1024, ASCII

character strings are searchable up to 1024
characters and Unicode character strings are
searchable up to 512 characters (1024 bytes).

This parameter applies to strings that have the

following data types:

CHAR(#)

VARCHAR(#)

It does not apply to strings that have the data

type(s):

LONG VARCHAR

The minimum valid value is 254. If you specify

a smaller number, the server will still search the
first 254 bytes. Although you can use any value
from 254 to 2G-1, practical values are generally
in the range of a few kilobytes, like 1024, or
8192.

MaxOpenCursors The maximum number of cursors that a 1000 RW/Startup

database client can have simultaneously open.

MaxRPCDataLen This allows you to specify the maximum string 512K (524288) RW/Startup
length of a single SQL statement sent to the
server. This is particularly useful if you are
sending CREATE PROCEDURE commands that
are longer than 64K. The value should be
between 64K (65536) and 1024K (1048576). If
the value is less than 64K, the server will use a
minimum of 64K.

MaxStartStatements Maximum number of simultaneous 10000 RW/Startup

"uncommitted" START AFTER COMMIT
statements. Valid values range from 0 - 1000000.
Defines the maximum number of connections to 0 RW/Startup
MaxUsers solidDB.

When the number of maximum users has been

exceeded, error 14507 is issued and you can
connect to solidDB only with solidDB Remote
Control (solcon).

Value 0 means that the maximum number of

connections is not restricted.

MemoryReportDelta This parameter defines how much memory 20 MB RW/Startup

allocations must increase or decrease compared
to the previous message before the new
message is printed to solmsg.out.

Appendix A. Server-side configuration parameters 207

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

MemoryReportLimit This parameter defines the minimum size for 0 (no reporting) RW/Startup
memory allocations after which reporting to
solmsg.out is done.

MemorySizeReportInterval When the memory size exceeds the limit 0 MB RW/Startup

defined with this parameter, the system
generates a report file. This parameter defines
the delta after which the next report is printed.
The minimum delta value is 1 MB. The report
file name is repmem<mb>MB.dbg.

This is parameter is useful, for example when

tracing unexpected memory growth in the
server.

If you leave this parameter to its default value

0, no reports are generated. The minimum
non-zero value for this parameter is 1 MB.

MessageLogSize The maximum size of the solmsg.out file in 1 MB RW/Startup

bytes.
Unit: 1 byte k=KB
m=MB

Name Specifies the informal name of the server, RW/Startup

equivalent to the -n command line option.

NetBackupRootDir Sets the root directory for the network backups The working RW
in NetBackup Server. The path is relative to the directory
working directory.

208 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

ODBCDefaultCharBinding Defines the binding method for character data raw RW/Startup
types.
See description
The options are:
v raw — no data conversion takes place
between solidDB server and the client
The value raw can be used when you want
your database to use the binding used in the
6.3 or earlier versions of solidDB.
v locale — the current client locale setting is
used, also if set by the client system
v locale: — the current client setting are
overridden with a default locale set of the
client system
The driver calls setlocale() with an empty
string which effectively searches for the
locale setting set in the system.
For example, in Linux environments, the
environmental variable LC_CTYPE is checked
first and if that is not defined, the
environmental variable LANG is searched.
v locale:<locale name> — the current client
systems setting are overridden and the given
locale is used
The convention for <locale name> depends
on the operating system.
For example, in Linux environments, the
locale name for the code page GB18030 in
Chinese/China is zh_CN.gb18030. In
Windows environments, the locale name for
Latin1 code page in Finnish/Finland is
fin_fin.1252.
v UTF8 — UTF-8 binding is enforced regardless
of the locale set in the client-side system

The factory value depends on the value of the

parameter General.InternalCharEncoding:
v If General.InternalCharEncoding is 'raw',
ODBCDefaultCharBinding is also 'raw'.
v If General.InternalCharEncoding is 'UTF8',
ODBCDefaultCharBinding is 'locale:'.
Pessimistic table locks are used to prevent other
PessimisticTableUseNFetch sessions from adding, editing, or deleting any no RW/Startup
records or placing any record or table locks on
a given table. Table locks block other record or
table lock attempts, but do not block any reads
of the locked table.

If pessimistic tables are used, they force the

RowsPerMessage value to 1 if the query locks
any rows. You can enable the RowsPerMessage
for pessimistic tables by enabling the
PessimisticTableUseNFetch parameter. By
default, it is disabled.
Causes a unique 8-character message code to be
PrintMsgCode inserted before each status and error message in no RW/Startup
the message log files (solmsg.out and
solerr.out).

Appendix A. Server-side configuration parameters 209

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

The process size limits are checked periodically.
ProcessMemoryCheckInterval The check interval is set with the 0 RW
ProcessMemoryCheckInterval parameter. The
interval is given in milliseconds.

The minimum non-zero value is 1000 (ms).

Only values 0 or 1000 or above 1000 (1 second)
are allowed. If the given value is above 0 but
below 1000, an error message is given.

The factory value is 0, that is, process size

checking is disabled.

The ProcessMemoryLimit and

ProcessMemoryCheckInterval parameters are
interlinked; if the ProcessMemoryCheckInterval
parameter is set to 0, the ProcessMemoryLimit
parameter is not effective, that is, there is no
process memory limit.

See also parameters

ProcessMemoryLowPercentage and
ProcessMemoryWarningPercentage.
As the amount on memory used crosses
ProcessMemoryHysteresisPercentage different boundaries specified with, for 5 RW
example, the ImdbMemoryLowPercentage or the
ProcessMemoryLimit parameter, system events
are given. The event behavior expresses
hysteresis in a way that the value triggering the
BELOW event is somewhat lower than the
specified value triggering the ABOVE event. The
difference can be, for instance, 5%. As a result,
the number of system events is not too large if
the amount of memory alternates rapidly just
above and below the specified boundaries. The
ProcessMemoryHysteresisPercentage parameter
is used to set the difference as a percentage
value.
This parameter specifies the maximum amount
ProcessMemoryLimit of virtual memory that can be allocated to the 1G RW
in-memory database process.
Unit: 1 byte,
When this limit is exceeded, the server gives an G=GB, M=MB,
error message and accepts admin commands K=KB
only. The limit can be changed dynamically.

The ProcessMemoryLimit and

ProcessMemoryCheckInterval parameters are
interlinked; if the ProcessMemoryCheckInterval
parameter is set to 0, the ProcessMemoryLimit
parameter is not effective, that is, there is no
process memory limit.
Note: You should not set the
Srv.ProcessMemoryLimit and
Srv.ProcessMemoryCheckInterval parameters
when using SMA. If you need to limit the
memory the SMA uses, use the
SharedMemoryAccess.MaxSharedMemorySize
parameter.

210 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

The ProcessMemoryLowPercentage parameter
ProcessMemoryLowPercentage sets a warning limit for the total process size. 90 RW
The limit is expressed as percentage of the
ProcessMemoryLimit parameter value.

Prior to exceeding this limit, you have exceeded

the warning limit defined by using the
ProcessMemoryWarningPercentage parameter
and received a warning. When the
ProcessMemoryLowPercentage limit is exceeded,
a system event is given.

The ProcessMemoryLowPercentage parameter

value is automatically checked for consistency.
It must be higher than the
ProcessMemoryWarningPercentage parameter
value.

See also parameters ProcessMemoryLimit,

ProcessMemoryCheckInterval , and
ProcessMemoryWarningPercentage.
The ProcessMemoryWarningPercentage
ProcessMemoryWarningPercentage parameter sets the first warning limit for the 80 RW
total process size. The warning limit is
expressed as percentage of the
ProcessMemoryLimit parameter value. When the
ProcessMemoryWarningPercentage limit is
exceeded, a system event is given.

The ProcessMemoryWarningPercentage
parameter value is automatically checked for
consistency. It must be lower than the
ProcessMemoryLowPercentage parameter value.

See also parameters ProcessMemoryLimit,

ProcessMemoryCheckInterval , and
ProcessMemoryLowPercentage.
This parameter controls the number of threads 2 RW/Startup
ReadThreadMode that the server uses to service client requests. If
the value is 0, the server uses the number of
threads specified with the parameter Threads. If
the value is 2, the server creates a separate
thread for each client. Using more threads will
generally improve performance, but also
requires more memory.

This parameter only controls the number of

threads serving client requests. It does not affect
the number of threads doing other work within
the server.

Some operating systems may limit the

maximum number of threads allowed, and
setting this parameter's value to 2 may cause
the server to request more threads than the OS
allows. If you try to exceed the number of
threads allowed, you will get the following type
of error:30146 Failed to create thread
'dnet_clientthread'

Appendix A. Server-side configuration parameters 211

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

RemoteStartTasks Number of Replica server's internal tasks inside 2 RW/Startup

the server that execute the remote background
statements started at Master with command
START AFTER COMMIT... FOR EACH
REPLICA. Valid values range from 1 - 100.
Note:

In this context task refers to solidDB's internal

tasks, not thread or task as used in some
Real-Time Operating Systems. A task is an
operation that has to be executed, such as
checkpoint, backup, or SQL statement.
Enables automated generation of reports at the 0 RW
ReportInterval given interval (in seconds).

Automated reports are named

reptimestamp>.dbg and output to the solidDB
working directory.

Value 0 means that reports are not generated

automatically.
Specifies the number of rows returned from the
RowsPerMessage server in one network message when an 100 RW/Startup
SQLFetch call is executed (and there are no
prefetched rows).

See also the ExecRowsPerMessage configuration

parameter.
If set to yes, no output is generated to the
Silent server's command window. Only license no RW/Startup
information is displayed.
This parameter defines the starting digit of the 0 RW/Startup
SolmsgBackupFileNum message log file (solmsg.out) name postfix, if
the KeepAllOutFiles parameter is set to yes.

For example, if the value is set to 5, the

solmsg.out files are named as follows:
solmsg5.out
solmsg6.out
solmsg7.out
...

Valid values range from 0 to 999999.

212 IBM solidDB: Administrator Guide

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

The StackTraceEnable parameter controls the yes RW/Startup
StackTraceEnabled stack trace functionality upon an assertion
failure or a signal caused by server malfunction.
When set to yes, the stack trace information is
output to ssstacktrace-<process_id>-
<thread_id>.out file.

The following signals invoke the stack traces

output automatically:
v SIGSEGV
v SIGILL
v SIGBUS
v SIGTRAP
v SIGSYS
v SIGEMT

The stack traces information is produced only

about the thread that received the signal.

Additionally, you can generate the stack traces

information for all currently running threads by
sending the server the SIGUSR1 signal.
By default, solidDB uses the ISO/IEC/ANSI
StandardDateTimeFormat standard date representation, which is also the yes RO
standard date literal format in SQL. The date is
represented as shown in the timestamp example
below:
2008-10-15 09:29:40

When set to no, the message log files

(solmsg.out) use a date format such as 15.10
09:29:40. The solerror.out file uses a date
format such as Mon Oct 22 15:16:35 2007.
This parameter switches on tracing for
StatementMemoryTraceLimit statements that have allocated memory over the 0 MB RW/Startup
defined value. These statements are put into the
peak memory usage list. The peak memory list
is printed to report file. Statements that use
memory over the defined limit are also printed
to the solmsg.out file.
If the ReadThreadMode parameter is set to 0, this
Threads parameter specifies the number of concurrent 5 RW/Startup
threads that the server uses to process user
requests. The helper threads, such as I/O
threads, are not included in the count. If the
value of ReadThreadMode is other than 0, the
value of this parameter is insignificant, as the
server controls the number of threads
automatically.
The starting value of the trace file name postfix
TraceBackupFileNum appended to the file name if the 0 RW/Startup
KeepAllOutFiles parameter is set to yes.

Valid values range from 0 to 999999.

Appendix A. Server-side configuration parameters 213

Table 57. Srv parameters (continued)

[Srv] Description Factory Value Access Mode

TraceLogSize This parameter allows you to limit the 1 megabyte RW/Startup

maximum size of the trace log file. The size is
specified in bytes; for example, Unit: 1 byte k=KB
TraceLogSize=10000 limits the size of the trace m=MB
log file to 10000 bytes. The trace log file is the
file to which the server writes information
when you turn on monitoring.

For information about turning on monitoring,

see the description of ADMIN COMMAND
’monitor...’ in section “ADMIN COMMAND”
on page 309 and the -m command-line option in
Appendix C, “solidDB command line options,”
on page 221.

Monitoring uses the file named soltrace.out

for output. After reaching the maximum size,
the server will:
1. delete any existing file named soltrace.bak;
2. rename the current soltrace.out file to
soltrace.bak; and
3. start a new soltrace.out file.

TraceSecDecimals Number of second decimals in trace outputs. 0 RW/Startup

Allowed values are from 0 to 3.

Synchronizer section
Table 58. Synchronizer parameters

[Synchronizer] Description Factory Value Access Mode

This parameter indicates the
ConnectStrForMaster connection string that the none RW
master must use to
communicate with the replica.
This information is read when
the server is started, and sent
to the master as part of each
message from the replica to the
master.

For example,
ConnectStrForMaster=
tcp replicahost 1316
The size of the statement cache
MasterStatementCache used during one propagation 10 RO
in Master. The statement cache
is used to store prepared
statements received by Master
in one propagation from
Replica.

214 IBM solidDB: Administrator Guide

Table 58. Synchronizer parameters (continued)

[Synchronizer] Description Factory Value Access Mode

With this parameter, you can
RefreshIsolationLevel select the transaction isolation Default is the same as RW
level for refresh operations SQL.IsolationLevel
instead of using the solid.ini
default value. The possible
values are

1. READ COMMITTED

2. REPEATABLE READ

RefreshReadLevelRows With this parameter, you can 1000 RW

define the number of rows
after the read level is released
in the master if the used
isolation level is READ
COMMITTED. In other cases,
the read level is kept for the
full time of the refresh
operation. The read level
denotes a snapshot-consistent
version of the data in the
whole database. By releasing
the read level, you avoid
keeping too much data in main
memory during the refresh
operation.
Note: See also the
Srv.RemoteStartTasks
parameter.

ReplicaRefreshLoad This parameter defines the 100 RW

amount of system processing
capacity (as percentage) used
to perform a refresh in Replica.
By default, the full power is
used. If some capacity is to be
secured for local processing, in
parallel with refresh, a lower
value may be set.
This parameter controls how
RpcEventThresholdByteCount frequently the server posts 0 RO
events to indicate how many
bytes have been sent or
received in the current
synchronization message. The
units are measured in bytes;
the smaller the value (that is,
the smaller the number of
bytes), the less frequently
events are posted.
Note: You cannot use suffixes
such as "K" or "M" to indicate
Kilobytes or Megabytes

Value 0 means that no events

are posted.

Appendix A. Server-side configuration parameters 215

216 IBM solidDB: Administrator Guide
Appendix B. Client-side configuration parameters
The client-side configuration parameters are stored in the solid.ini configuration
file and are read when the client starts.

Generally, the factory value settings offer the best performance and operability, but
in some special cases modifying a parameter will improve performance. You can
change the parameters by editing the solid.ini configuration file.

The parameter values set in the client side configuration file come to effect each
time an application issues a call to the SqlConnect ODBC function. If the values are
changed in the file during the program's run time, they affect the connections
established thereafter.

Client section
Table 59. Client parameters

[Client] Description Factory Value

This parameter specifies how many result decided by the server
ExecRowsPerMessage rows are sent (pre-fetched) to the client
driver in response to the SQLExecute call
with a SELECT statement. The result rows
are subsequently returned to the
application with the first SQLFetch calls
issued by the application. The value 2
allows for prefetching of single-row
results. If your SELECT statements
usually return larger number of rows,
setting this to an appropriate value can
improve performance significantly.

See also the RowsPerMessage parameter.

If set to yes, the Windows runtime error no
NoAssertMessages dialog is not shown.

This parameter is relevant to the Windows

platform only.

217
Table 59. Client parameters (continued)

[Client] Description Factory Value

ODBCCharBinding Defines the binding method for character locale
data.

The options are:

v raw (binary)
v locale (the current client locale is used)
v locale:<locale name> (specific code
page is used)

The convention for <locale name> depends

on the operating system. For example, in
Linux environments, the locale name for
the code page GB18030 in Chinese/China
is zh_CN.gb18030. In Windows
environments, the locale name for Latin1
code page in Finnish/Finland is
fin_fin.1252.

The value raw can be used when you

want your database to use the binding
used in the 6.3 or earlier versions of
solidDB.
This parameter switches ODBC handle no
ODBCHandleValidation validation on or off.

See also section ODBC handle validation in

IBM solidDB Programmer Guide for more
information about the
SQL_ATTR_HANDLE_VALIDATION ODBC
attribute.
Specifies the number of rows returned decided by the server
RowsPerMessage from the server in one network message
when an SQLFetch call is executed and
there are no pre-fetched rows.

See also the ExecRowsPerMessage

parameter.
6
StatementCache Statement cache is an internal memory
storing a few previously prepared SQL
statements. With this parameter, you can
set the number of cached statements per
session.
This parameter defines whether yes
UseEncryption passwords are encrypted. If set to no,
passwords are not encrypted.

Communication section
Table 60. Communication parameters

[Com] Description Factory Value

This parameter defines the connection (or read) timeout in milliseconds. A 0 (infinite)
ClientReadTimeout network request fails if no response is received during the time specified.
The value 0 sets the timeout to infinite. This value can be overridden with
the connect string option -r and, further on, with the ODBC attribute
SQL_ATTR_CONNECTION_TIMEOUT.
Note: This parameter applies only to the TCP protocol.

218 IBM solidDB: Administrator Guide

Table 60. Communication parameters (continued)

[Com] Description Factory Value

The client-side Com.Connect parameter defines the default network name tcp localhost 1964
Connect (connect string) for a client to connect to when it establishes a connection (Windows)
to a server.
upipe SOLID (Linux
The format of the connect string is: and UNIX)
protocol_name [options] [host_comput
er_name] server_name

The options and server_name depend on the communication protocol. For

details, see Managing network connections in the IBM solidDB Administrator
Guide.

This value is used also when the SQLConnect() call is issued with an
empty data source name.
The client-side Com.ConnectTimeout parameter defines the login timeout in
ConnectTimeout milliseconds. OS-specific

The value of the parameter can be overridden with the connect string
option -c or the ODBC attribute SQL_ATTR_LOGIN_TIMEOUT.
Note: This parameter applies for the TCP protocol only.
This parameter controls the TCP socket linger (SO_LINGER) behavior no
SocketLinger after a close on the socket connection is issued. It indicates if the system
attempts to deliver any buffered data (yes), or if the system discards it
(no), when a close() is issued.
This parameter defines the length of the time interval (in seconds) the
SocketLingerTime socket lingers after a close is issued. If the time interval expires before the 0
graceful shutdown sequence completes, an abortive shutdown sequence
occurs (the data is discarded). The default value zero indicates that the
system default is used (typically, 1 second)

Trace If this parameter is set to yes, trace information about network messages no
for the established network connection is written to a file specified with
the TraceFile parameter.

TraceFile If the Trace parameter is set to yes, trace information about network soltrace.out
messages is written to a file specified with this TraceFile parameter. (written to the
current working
directory of the
server or client
depending on which
end the tracing is
started)

Data sources section

Table 61. Data Sources parameters

[Data Sources] Description Factory Value Access Mode

logical name = network name, These parameters can be used to give a logical name to a N/A
Description solidDB server in a solid.ini file of the client
application.

Appendix B. Client-side configuration parameters 219

SharedMemoryAccess section
Table 62. Shared memory access parameters (client-side)
[SharedMemoryAccess] Description Factory value Startup
SignalHandler The SignalHandler parameter controls the SMA signal yes NA
handler functionality.

When set to yes, the SMA driver signal handler handles

the signals defined with the Signals parameter.

The SMA driver signal handler enables the SMA system to

survive the most common application failures, such as
killing or interrupting the applications from outside, or
when one of the application threads runs within the
server code, and another thread running application code
causes application to crash.

Upon the capture of certain signals, the signal handler

closes the SMA connections safely and exits the SMA
application. This means that in most cases, the SMA
server continues to run despite abnormal application exits.

The SMA driver signal handler installs itself when the first
SMA connection is established and uninstalls itself when
the last SMA connection is closed. Previously installed
signal handlers are retained.
Signals This parameter defines the signals that can break the SMA Linux and UNIX: NA
connection and should be handled by the SMA driver. SIGINT, SIGTERM

The signals are defined as integers or with the following Windows: SIGINT
mnemonics: SIGSTOP, SIGKILL, SIGINT, SIGTERM,
SIGQUIT, SIGABORT.
Note: If the SMA application loops outside of the SMA
driver (for example, does not call any functions), the
signal can fail to terminate the application. In such a case:
1. Throw out the connections at the server.
admin command ’throwout <userid>’
2. Use SIGKILL signal to force the SMA application to
exit.
kill -SIGKILL <pid>

TransparentFailover section
Table 63. TransparentFailover parameters
[TransparentFailover] Description Factory value
ReconnectTimeout This parameter specifies how long (in milliseconds) the driver 10000
should wait until it tries to reconnect to the primary in case of
TF switchover or failover. If the driver cannot find the new
primary (reconnect), an error is returned and the TF connection
becomes broken.
WaitTimeout This parameter specifies how long (in milliseconds) the driver 10000
should wait for the server to switch state. When the driver tries
to reconnect to the servers, it might connect to the server being
in an intermediate (switching or uncertain) state.

220 IBM solidDB: Administrator Guide

Appendix C. solidDB command line options
Option Description Examples

solid -c /data/solid
-c directory Changes working directory

-f Starts the server in foreground

-m Monitors users' messages and SQL

statements

-n name Sets the server name

-s install,name,fullexepath -c The Windows version of solidDB is solid -s"install,SOLID,
directory[,autostart] by default an icon exe version. You D:\SOLID\SOLID.EXE
can allow Windows to run solidDB -cD:\SOLID"
as a service by using the option -s
install. solid -s"install,SOLID,
D:\SOLID\SOLID.EXE
Note: After the service is installed, it
-cD:\SOLID,autostart"
must be started manually using the
Windows Services dialog or
command prompt.

The [autostart] parameter sets the

Startup Type of the service to
Automatic, that is, solidDB will run
automatically as a service when
Windows is started. Note, however,
that regardless of the [autostart]
parameter, the service is not started
automatically at the time of install.
For the first time, the service has to
be started manually in the Windows
Services dialog or command prompt.

When the server is running as a

service, the server cannot interact
with the display and cannot create a
new database. The service version
writes warning and error messages
also to the Windows event log.
Removes solidDB service solid -s"remove,SOLID"
-s remove,name
-s start Specifies that solidDB will start in a sc create SOLID binPath=
services mode when, for example, "c:\soliddb\bin\solid.exe
solidDB is created as a service using -cC:\soliddb -sstart"
the Windows sc.exe utility.

In the services mode, solidDB cannot

interact with the display and cannot
create a new database.
Note: The - s start option is
included automatically when using
the -s install option.

-U username See option -x execute or -x exit. If

used without the -x option, specifies
the username for the database being
created.

221
Option Description Examples

-P password See option -x execute or -x exit. If

used without the -x option, specifies
the given password for the database
being created.

-E Encrypt the database

-S password The database file encryption

password

-x assert:s Disables emergency exit dialog

-x autoconvert Converts database format to the

current format used by solidDB and
starts the server process

-x backupserver See IBM solidDB High Availability

User Guide for information

-C catalog Specify the database catalog

-x convert Converts database format to the

current format used by solidDB and
starts the server process

solid -x decrypt -S dba

-x decrypt -S password Decrypts the database
solid -x decrypt -x keypwdfile:pwd.txt

-x disableallmessageboxes Hides all message windows

-x errormsgnostop Does not wait for user actions on

error dialogs

solid.exe -x execute:init.sql
-x execute: file_name Prompts for the database
administrator's user name and solid.exe -x execute:init.sql -Udba -Pdba
password, creates a new database,
executes SQL statements from a file,
and exits. The options -U and -P can
be used to give the database the
administrator's user name and
password.

The input file must be encoded with

a 7-bit or 8-bit character set, such as
ASCII or Latin-1.

222 IBM solidDB: Administrator Guide

Option Description Examples

solid.exe -x executeandnoexit:init.sql
-x executeandnoexit: file_name Prompts for the database
administrator's user name and solid.exe -x executeandnoexit:init.sql -Udba -Pdba
password, creates a new database,
executes SQL statements from a file,
but does not exit.

You can use this command with an

existing database provided that you
use options -U and -P to give the
database the administrator's user
name and password.

The input file must be encoded with

a 7-bit or 8-bit character set, such as
ASCII or Latin-1.

solid.exe -x exit
-x exit Prompts for the database solid.exe -x exit -Udba -Pdba
administrator's user name and
password, creates a new database,
and exits. Options -U and -P can be
used to give the database
administrator's user name and
password.

-x forcerecovery Does a forced roll-forward recovery

-x hide Hides the server icon

-x ignoreerrors Ignores index errors

-x ignorecrashed Ignores log files and reverts to

checkpoint

-x inifile:file_name Substitutes a solid.ini file

-x infodbfreefactor Informs about unused pages

The server exits after performing the

task.

See also:-x reorganize.

-x keypwdfile: file_name The database encryption password is

read from file_name instead of
command line argument. This way
the password cannot be seen by
running the UNIX command ps.

-x listen:network_name Sets a listening address

Appendix C. solidDB command line options 223

Option Description Examples

-x migratehsbg2 This command-line switch has two

effects. It instructs the server to
accept and convert the existing
database (the same effect as the -x
autoconvert parameter). Also, it
enables the new Secondary to
communicate with the old Primary
by way of the old replication
protocol.

This parameter is needed only when

upgrading a server that uses
HotStandby.

-x nologrecovery Ignores log files during recovery

-x pathprefix:directory Uses files in the specified directory

-x pwdfile: file_name The password is read from the file

name instead of command line
argument. This way the password
cannot be seen by running the UNIX
command ps.

-x recreate_noconfirm Creates a new empty database in

place of the existing one

-x reorganize Compacts the database by removing

unused pages.

The server exits after performing the

task.

-x testintegrity Performs a full database integrity test

and exits

-x testblocks Checks the disk block integrity and

produces a report in a ssdebug.out
file.

The server exits after performing the

task.

-x testindex[:size] Tests database index and exits

The optional [:size] parameter

outputs index size.

-x version Displays the server version and exits

-? Help = Usage

-h Help = Usage

224 IBM solidDB: Administrator Guide

Appendix D. Environment variables
Table 64. solidDB environment variables
Environment
variable Purpose Example
SOLAPPINFO Identifies applications running in the same computer and under export SOLAPPINFO=testapp
the same username for the purposes of tracing and management

SOLAPPINFO is set on the client node. The ADMIN COMMAND

'userlist' returns the value of SOLAPPINFO on the server side.The
value of SOLAPPINFO must not contain blanks.
Tip: In JDBC environments, the SOLAPPINFO can be set with the
connection property solid_appinfo.

Alternatively, the following Java command line may be used to

pass the value of the environmental variable to the driver:
java -Dsolid_appinfo=%SOLAPPINFO% java_program_name
SOLIDDIR Defines the default directory for solid.ini and license files export SOLIDDIR=/home/
soliddb/settings/
SOLSMASTART Forces the start address space for the SMA server to the solidDB export
default SOLSMASTART=0x2c0000000000

The value depends on the operating system; see SOLSMASTART

default address spaces in the IBM solidDB Shared Memory Access and
Linked Library Access User Guide for more details.
SOLTRACE Turns on the Network trace facility, overriding the Com.Trace export SOLTRACE=yes
setting in the solid.ini file
SOLTRACEFILE Defines the name and location of the file where trace information export SOLTRACEFILE=/home/
is output, overriding the Com.TraceFile setting in the solid.ini soliddb/settings/trace.out
file

Defining the SOLTRACEFILE environment variable automatically

turns on the Network trace facility.

225
226 IBM solidDB: Administrator Guide
Appendix E. Error codes
This appendix lists error and message codes that can be generated by the server.
This appendix lists the errors and messages according to the error class, following
the order the error descriptions appear in the ADMIN COMMAND ’errorcode all’
output.

Error classes
Table 65. solidDB error categories

Error class Description

System System errors are detected by the operating system and demand administrative actions.

For the list of errors, see “solidDB system errors” on page 229.

Database or DBE The errors in these classes are detected by the solidDB and may demand administrative actions.
(database engine) Messages typically do not require administrative actions.

For the list of errors and messages, see “solidDB database errors” on page 232 and “solidDB DBE
(database engine) errors and messages” on page 291.

Table or TAB (table) These errors and messages are caused by erroneous SQL statements detected by solidDB.
Administrative actions are not needed.

For the list of errors and messages, see “solidDB table errors” on page 241 and “solidDB TAB (table)
messages” on page 299.

Communication, COM, The communication type errors are encountered by network problems, faulty configuration of the
Session, or RPC solidDB software, or ping facility errors. These errors in these classes usually demand administrative
actions. Messages typically do not require administrative actions.

For the list of errors and messages, see

v “solidDB communication errors” on page 257
v “solidDB session errors” on page 256
v “solidDB COM (communication) messages” on page 288
v “solidDB RPC errors and messages” on page 270

Server These errors are caused by erroneous administrative actions or client requests. They may demand
administrative actions.

For the list of errors, see “solidDB server errors” on page 260

Procedure These errors are encountered when defining or executing a stored procedure. Administrative actions
are not needed.

For the list of errors, see “solidDB procedure errors” on page 266.
SA API The SA API errors are return codes for the SA function SaSQLExecDirect.

For more information, see “solidDB API errors” on page 269 and SaSQLExecDirect in the IBM solidDB
Programmer Guide.
These errors are encountered when the external sorter algorithm is solving queries that require
Sorter or XS ordering rows.

For the list of errors, see “solidDB sorter errors” on page 269 and “solidDB XS (external sorter) errors
and messages” on page 298.

227
Table 65. solidDB error categories (continued)

Error class Description

Synchronization or SNC These errors may be encountered when creating or maintaining the solidDB environment. They occur
when using certain solidDB statements that are solidDB SQL extensions.

For the list of errors, see “solidDB synchronization errors” on page 271 and “solidDB SNC
(synchronization) messages” on page 297.
HotStandby or HSB The HotStandby errors occur when using the ADMIN COMMAND ’HotStandby’ commands.

For the list of errors, see “solidDB HotStandby errors” on page 286 and “solidDB HSB (HotStandby)
errors and messages” on page 295.
SSA (solidDB SQL API) These errors are caused by erroneous use of the solidDB SQL API (SSA). solidDB ODBC and JDBC
drivers are implemented on this API.

For the list of errors, see “solidDB SSA (SQL API) errors” on page 287
CP (checkpoint) The CP messages provide information about the status or conditions of checkpoint operations.

For the list of messages, see “solidDB CP (checkpoint) messages” on page 293.
BCKP (backup) The BCKP messages provide information about the status or conditions of backup operations.

For the list of messages, see “solidDB BCKP (backup) messages” on page 293.
AT (timed commands) The AT messages provide information about the status or conditions of executing timed commands.

For the list of messages, see “solidDB AT (timed commands) messages” on page 293.
LOG (logging) The LOG messages provide information about the status or conditions of transaction logging.

For the list of messages, see “solidDB LOG (logging) messages” on page 294.
INI (configuration file) The INI messages provide information about the use of the solid.ini configuration file.

For the list of messages, see “solidDB INI (configuration file) messages” on page 294.
FILE (file system) The FILE messages provide information about file system operations, for example, for database and
log files.

For the list of messages, see “solidDB FIL (file system) messages” on page 298.
SMA (shared memory The SMA messages provide information about operations when solidDB is used with shared memory
access) access.

For the list of errors, see “solidDB SMA (shared memory access) errors” on page 299.
PT (passthrough) The PT errors provide information about operations when solidDB is used with SQL passthrough.

For the list of messages, see “solidDB PT (passthrough) errors” on page 299.
These errors are caused by erroneous SQL statements detected by the solidDB SQL Parser.
SQL errors Administrative actions are not needed.

For the list of errors, see “solidDB SQL errors” on page 300
These errors are caused by the failure of the solidDB executable or a command line argument related
Executable errors error. They enable implementing intelligent error handling logic in system startup scripts.

For the list of errors, see “solidDB executable errors” on page 306
These errors are encountered when running the solidDB Speed Loader utility (solloado or solload) to
solidDB Speed Loader load data from external files into the solidDB database.
(solloado or solload)
For the list of errors, see “solidDB Speed Loader (solloado and solload) errors” on page 307

In addition to the errors and messages described above, you might receive an
internal error. In such a case, contact solidDB Technical Support at
http://www.ibm.com/software/data/soliddb/support/.

228 IBM solidDB: Administrator Guide

solidDB system errors
Table 66. solidDB system errors

Code Class Type Description

System Error
11000 File open failure.

The server is unable to open the database file. Reason for the failure can be:
v The database file has been set to read-only.
v You do not have rights to open the database file in write mode.
v Another solidDB is using the database file.

Correct the error and try again.

System Fatal Error
11001 File write failure.

The server is unable to write to the disk. The database files may have a read-only
attribute set or you may not have rights to write to the disk. Add rights or unset
read-only attribute and try again.
System Fatal Error
11002 File write failed, disk full.

The server failed to write to the disk, because the disk is full. Free disk space or
move the database file to another disk. You can also split the database file to several
disks using the IndexFile.FileSpec parameter.
11003 System Fatal Error
File write failed, configuration exceeded.

Writing to the database file failed because the maximum database file size set in
IndexFile.FileSpec parameter has been exceeded.

See “Troubleshooting database file size (file write fails)” on page 151 for more details.
11004 System Fatal Error
File read failure.

An error occurred reading a file. This may indicate a disk error in your system.
11005 System Fatal Error File read beyond end of file.

This error is given, if the file EOF is reached during the read operation.
11006 System Fatal Error File read failed, illegal file address.

An error occurred reading a file. This may indicate a disk error in your system, or
insufficient file read or write permissions.

With this error, the following type of error message can be written to the solmsg.out
file:
SsBOpenLocal failed, file
’/home/solid/sol00001.log’,
error = 13, retries = 0, open files = 1

The error 13 refers to an operating system error code 13 which is defined as:
#define EACCES 13 /* Permission denied */

This means that the solid process does not have operating system permissions to
read or create the file.
System Fatal Error File lock failure.
11007
The server failed to lock the database file.
System Fatal Error
11008 File unlock failure.

The server failed to unlock a file.

Appendix E. Error codes 229

Table 66. solidDB system errors (continued)

Code Class Type Description

System Fatal Error
11009 File free block list corrupted.

This error is given when reading data from disk to memory, but the memory space is
already allocated for another purpose.
System Error
11010 Too long file name.

Filename specified in parameter FileSpec_[1-N] is too long. Change the name to a

proper file name.
System Error
11011 Duplicate file name specification.

Filename specified in parameter FileSpec_[1-N] is not unique. Change the name to a

proper file name.
System Fatal Error
11012 License information not found, exiting from solidDB

Check the existence of your solid.lic file.

System Fatal Error
11013 License information is corrupted.

Your solid.lic file has been corrupted.

System Fatal Error
11014 Database age limit of evaluation license expired.
System Fatal Error
11015 Evaluation license expired.
System Fatal Error
11016 License is for different CPU architecture.
System Fatal Error
11017 License is for different OS environment.
System Fatal Error
11018 License is for different version of this OS.
System Fatal Error
11019 License is not valid for this server version.
System Fatal Error
11020 License information is corrupted.
System Fatal Error
11021 Problem with Your license, please contact IBM Corporation immediately.
System Error
11022 Desktop license is only for local protocol communication, cannot use protocol for
listening.
System Error
11023 Internal binary stream error.

This error is given if read or write fails when handling a binary stream object.
System Error
11024 Desktop license is only for local communication, cannot use name for listening.
System Error
11025 License file filename is not compatible with this server executable.

The server has been started with an incompatible license file. You need to update
your license file to match the server version.
System Error
11026 Backup directory contains a file which could not be removed.

Some file could not be removed from the backup directory. The backup directory
may point to a wrong location.

230 IBM solidDB: Administrator Guide

Table 66. solidDB system errors (continued)

Code Class Type Description

System Error
11027 No such parameter section section.

Parameter was not found from the specified section in the solid.ini file.
System Error
11028 No such parameter section.name.

Parameter does not exist.

System Error
11029 Not allowed to set parameter value.

User is not allowed to set the parameter value.

System Error
11030 Cannot set values to multiple parameters.

Only one parameter can be set at one time.

System Error
11031 Illegal type for parameter.

Parameter type is illegal.

System Error
11032 Cannot set new value for parameter section.name.

A new value cannot be set for the parameter.

System Error
11033 Parameter is read-only.
System Error
11034 File remove failure.
System Error
11035 Value for parameter is smaller than minimum value.
System Error
11036 Value for parameter is bigger than maximum value.
System Error
11037 Value for parameter is invalid.
System Error
11038 File specification exceeds the database address space.
System Error
11039 File specification exceeds the database address space.

This error is given if solidDB attempts to use a file, whose given size is larger that
the size that solidDB can use.
System Error
11040 Password file cannot be opened.

This error is given if solidDB cannot find the database password file.
System Error
11041 No password found in password file.

This error is given if the database password is not in the password file.
11042 System Error Internal error: Empty diagnostic record. Contact technical support for more
information.

Appendix E. Error codes 231

solidDB database errors
Table 67. solidDB database errors

Code Class Type Description

1004 Database Warning Database headers are inconsistent
1005 Database Warning Database is crashed
1012 Database Warning BLOB size overflow
1013 Database Warning BLOB size underflow
1019 Database Return Code Operation canceled
The database you are using has been originally created with a different database block
1022 Database Warning size setting than your current
10001 Database Error
Key value is not found.

Internal error: a key value cannot be found from the database index.
10002 Database Error
Operation failed.

This is an internal error indicating that the index of the table accessed is in inconsistent
state. Try to drop and create the index again to recover from the error.

You may also receive this error if you try to SET TRANSACTION READ ONLY when the
transaction already contains some write operations.
10004 Database Error
Redefinition.

Unexpected failure occurred in the database engine.

This error may also occur during recovery: either an index or a view has been redefined
during recovery. The server is not able to do the recovery. Delete log files and start the
server again.
10005 Database Error
Unique constraint violation.

You have violated a unique constraint. This happens when you have tried to insert or
update a column which has a unique constraint and the value inserted or updated is not
unique.

This error message applies not only to user tables, but also to the system tables. For
example, if you try to create a table that has the same name as an existing table, you may
see this message. The same applies to other database object names, such as names of
users, roles, and triggers.

232 IBM solidDB: Administrator Guide

Table 67. solidDB database errors (continued)

Code Class Type Description

10006 Database Error Concurrency conflict, two transactions updated or deleted the same row.

Two separate transactions have modified a same row in the database simultaneously. This
has resulted in a concurrency conflict.

The error is returned when the tables are set with optimistic concurrency control and two
or more concurrent connections attempt to obtain a exclusive lock on the same row/or set
of rows at the same time (same row in the database is being modified simultaneously).

To diagnose the problem:

1. Enable monitoring.
2. Check soltrace.out for error 10006.

Resolving the problem:

The transaction that has been committed first is allowed to make the modifications to the
database. The latter transactions is rolled back and this error message is returned to the
application. To handle this update conflict, for example, the application could try to
re-read the data and retry the update.

You can also switch to pessimistic locking method where row-level locking is used to
avoid update conflicts. The pessimistic locking mode is suggested for tables that are
modified frequently. To turn the pessimistic locking on for a table, use the ALTER TABLE
statement.
10007 Database Error
Transaction is not serializable.

The transaction committed is not serializable.

10008 Database Error
Snapshot does not exist.
10009 Database Error
Snapshot is newest.
10010 Database Fatal Error
No checkpoint in database.

This error occurs when the server has crashed in the middle of creating a new database.
Delete the database and log files and try to create the database again.
10011 Database Fatal Error
Database headers are corrupted.

The headers in the database are corrupted. This may be caused by a disk error or other
system failure. Restore the database from the backup.
10012 Database Fatal Error
Node split failed.

This error is given if the node split of the in-memory database (B+ tree) fails.

Appendix E. Error codes 233

Table 67. solidDB database errors (continued)

Code Class Type Description

10013 Database Error
Transaction is read-only.

You tried to do one of the following:

1) Execute conflicting SET TRANSACTION statements, for example, you executed SET
TRANSACTION READ WRITE after you already SET TRANSACTION READ ONLY
within the same transaction.

2) Write on a HotStandby database server that is in a Secondary state.

3) Write inside a transaction that is set read-only. Remove the write operation or unset the
read-only mode in the transaction.

If you see this message in the first transaction that you try to execute after connecting to a
server, and if you haven't done anything to set the transaction or server to read-only
mode, then try simply executing a COMMIT WORK statement and then re-executing the
statement that caused the 10013 error.
10014 Database Error
Resource is locked.

This error occurs when you are trying to use a key value in an index which has been
concurrently dropped.
10016 Database Error
Log file is corrupted.

One of the log files of the database is corrupted. You can not use these log files. Delete
them and start the server again.
10017 Database Error
Too long key value.

The maximum length of the key value has been exceeded. The maximum value is one
third of the size of the index leaf.

If there are blobs (long varchars or long varbinaries) among the columns, the capacity
requirements for a row can be reduced by storing the blob separately in the blob storage.
However, when storing data in the blob storage, the first 254 bytes are also stored on the
actual row. Therefore, with 8K block size, only 11 varchar columns with 254 characters of
data is sufficient to exceed the key value limitation and cause this error message.

You can try to:

1. Increase the [IndexFile] block size to increase the key value limit
2. Redesign your database to reduce space requirements. Design alternatives include:
v Break columns with big VARCHAR strings to several rows in separate tables.
Implement a view to represent the data accordingly.
v Define columns with big VARCHAR strings to be concatenated inside one long
VARCHAR to be processed as a blob. Implement a view to represent the data
accordingly.
3. Define the table to be stored in the main memory. Since main memory storage uses a
different algorithm, where the row size limitation is defined the by disk block size
(minus overhead in the range of tens of bytes per row and few bytes per column), the
limit is higher than with disk based tables. If the key value limit is exceeded in main
memory tables, the error message is 16501.
Database Error
10019 Backup is active

You have tried to start a backup when a backup process is already in progress.
Database Error
10020 Checkpoint creation is active.

You have tried to start a checkpoint when a checkpoint creation is already in progress.

234 IBM solidDB: Administrator Guide

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Error
10021 Failed to delete log file <log_file> (errno = <operating_system_error_code>.

The deletion of a log file in making a backup has failed.

Reasons for the failure can be:

v The log file has already been deleted from the operating system.
v The log file has a read-only attribute.
Database Fatal Error
10023 Wrong log file, maybe the log file is from another database.

The log file in the database directory is from another solidDB database. Copy the correct
log files to the database directory.
Database Error
10024 Illegal backup directory.

The backup directory is either an empty string or a dot indicating that the backup will be
created in the current directory.
Database Error
10026 Transaction is timed out.

An idle transaction has exceeded the maximum idle transaction time. The transaction has
been aborted.

The maximum value is set in parameter AbortTimeOut in SRV section. The default value
is 120 minutes.
Database Error
10027 No active search.

This error is given during the UPDATE or DELETE operation if it is found that the active
search identifying the data in the database to be updated or deleted does not exist.
Database Error
10028 Referential integrity violation, foreign key values exist.

You tried to delete a row that is referenced from a foreign key.

Database Error
10029 Referential integrity violation, referenced column values do not exist.

The definition of a foreign key does not uniquely identify a row in the referenced table.
Database Error
10030 Backup directory 'directory name' does not exist.

Backup directory is not found. Check the name of the backup directory.
Database Error
10031 Transaction detected a deadlock or a lock wait timeout, transaction is rolled back.

To avoid lock timeouts, adjust the lock wait timeout settings.

To avoid deadlocks, adjust the data access order in concurrent transactions.

If necessary, begin transaction again.

Database Fatal Error
10032 Wrong database block size specified.

The block size of the database file differs from the block size given in the configuration
file solid.ini.
Database Error
10033 Primary key unique constraint violation.

Your primary key definition is not unique.

Appendix E. Error codes 235

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Error
10034 Sequence name sequence conflicts with an existing entity.

Choose a unique name for a sequence. The specified name is already used.
Database Error
10035 Sequence does not exist.

Check the name of the sequence.

Database Error
10036 Data dictionary operation is active for accessed sequence.

A create or drop operation is active for the accessed sequence. Finish the current
transaction and then try again.
Database Error
10037 Can not store sequence value, the target data type is illegal.

The valid target data types are BIGINT, INTEGER, and BINARY.
Database Error
10038 Illegal column value for descending index.

Corrupted data found in descending index. Drop the index and create it again.
Database Error INTERNAL: Assertion failure
10039
For more information, contact solidDB Technical Support at http://www.ibm.com/
software/data/soliddb/support/.
Database Error
10040 Log file write failure, probably the disk containing the log files is full.

Shut down the server and reserve more disk space for log files.
Database Error
10041 Database is read-only.
Database Error
10042 Database index check failed, the database file is corrupted.
Database Error
10043 Database free block list corrupted, same block twice in free list.
Database Error
10044 Primary key can not contain blob attributes.
Database Error
10045 This database is a HotStandby secondary server, the database is read only.
Database Error
10046 Operation failed, data dictionary operation is active. Wait and try again.
Database Error
10047 Replicated transaction is aborted.
Database Error
10048 Replicated transaction contains schema changes, operation failed.
Database Error
10049 Slave server not available any more, transaction aborted
Database Error
10050 Replicated row contains BLOb columns that cannot be replicated.
Database Error
10051 Log file is corrupted.
Database Fatal Error
10052 Cannot convert an abnormally closed database. Use the old solidDB database version to
recover the database first.
Database Error
10053 Table is read only.

236 IBM solidDB: Administrator Guide

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Fatal Error
10054 Opening the database file failed.

Probably another solidDB process is already running in the same directory.

Database Fatal Error
10055 Too little cache memory has been specified for the solidDB process.
Database Fatal Error
10056 Cannot open database file. Error text (number). Most likely the solidDB process does not
have correct access rights to the database file.
Database Fatal Error
10057 The database is irrevocably corrupted.

Revert to the latest backup.

Database Fatal Error
10058 The internal database file format version (number) does not match with the solidDB
version. Possible causes for this error include:
v a version of solidDB that is too old is used with this database
v the database has been corrupted
Database Fatal Error
10059 The internal header version (number) does not match with the solidDB version.

Possible causes for this error include:

v a version of solidDB that is too old is used with this database
v the database has been corrupted
Database Fatal Error
10060 Cannot perform roll-forward recovery in read-only mode.

Read-only mode can be specified in 3 ways. To restart solidDB in normal mode, verify
that:
v solidDB process is not started with command-line option -x read only
v solid.ini does not contain the following parameter setting:
[General]
ReadOnly=yes
v license file does not have read-only limitation
10061 Database Fatal Error
Out of database cache memory blocks.

solidDB process cannot continue because there is too little cache memory allocated for the
solidDB process. Typical cause for this problem is a heavy load from several concurrent
users. To allocate more cache memory, set the following solid.ini parameter to a higher
value:
[IndexFile]
CacheSize=cache_size_in_bytes

NOTE: Allocated cache memory size should not exceed the amount of physical memory.
10062 Database Fatal Error
Failed to write to log filename at offset.

Verify that the disk containing the log files is not full and is functioning properly. Also,
log files should not be stored on shared disks over the network.

Appendix E. Error codes 237

Table 67. solidDB database errors (continued)

Code Class Type Description

10063 Database Fatal Error Cannot create new logfile file_name because such a file already exists in the log file
directory.

Probably your log file directory also contains logs from some other database. solidDB
process cannot continue until invalid log files are removed from the log file directory.

To recover:
v Remove log filename and all other log files with greater sequence numbers.
v Change the value of the Logging.FileNameTemplate parameter to point to a directory
that does not contain any solidDB transaction log files.
Database Fatal Error
10064 Illegal log file name template.

Most likely, the log file name template specified in:

[Logging]
FileNameTemplate=name

contains too few or too many sequence number digit positions. There should be at least 4
and at most 10 digit positions.
Database Fatal Error
10065 Unknown log write mode. Recheck the configuration parameter.
Database Fatal Error
10066 Cannot open log filename. Check the following log file name template in solid.ini:
[Logging]
FileNameTemplate=name

and verify that:

v it can be expanded into a valid file name in this environment
v solidDB process has appropriate privileges to the log files directory.
Database Fatal Error
10067 Cannot create database because old log filename exists in the log files directory.

Possibly the database has been deleted without deleting the log files or there are log files
from some other database in the log files directory of the database to be created.
Database Fatal Error
10068 Roll-forward recovery cannot be performed because the configured log file block size
number does not match with block size number of existing filename.

To enable recovery, edit solid.ini to include parameter setting:

[Logging]
BlockSize=blocksize in bytes

and restart the solidDB process. After successful recovery, you can change the log file
block size by performing these steps:
1. Shut down the solidDB process.
2. Remove old log files.
3. Edit new block size into solid.ini.
4. Restart solidDB.
Database Fatal Error
10069 Roll-forward recovery failed because relation id number was not found. Database has been
irrevocably corrupted. Restore the database from the last backup.
Database Fatal Error
10070 Roll-forward failed because relation id number was not found. Database has been
irrevocably corrupted. Restore the database from the latest backup.
Database Fatal Error
10071 Restore the database from the latest backup.
Database Fatal Error
10072 Database operation failed because of the file I/O problem.

238 IBM solidDB: Administrator Guide

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Fatal Error
10073 Database is inconsistent. Illegal index block type size, address, routine, reachmode. Restore
the database from the latest backup.
Database Fatal Error
10074 Roll-forward recovery failed. Revert to the latest backup.
Database Fatal Error
10075 The database you are trying to use has been originally created with different database
block size settings than your current settings.

Edit the solid.ini file to contain the following parameter setting:

[IndexFile]
BlockSize=blocksize in bytes
Database Fatal Error
10076 Roll-forward recovery failed because tablename or viewname is redefined in the log
filename.

Possible causes for this error include:

v another solidDB process is using the same log file directory
v old log files are present in the log file directory

solidDB process cannot use this corrupted log file to recover. In order to continue, you
have the following alternatives:
1. Revert to the last backup
2. Revert to the last checkpoint
3. Revert to the last committed transaction within the last valid log file
Database Fatal Error
10077 No base catalog given for database conversion (use -C catalogname )

A database's base catalog must be provided when converting the database to a new
format.
10078 Database Error User rolled back the transaction.
10079 Database Error Cannot remove filespec. File is already in use.
10080 Database Error HotStandby Secondary server can not execute operation received from Primary server.

Meaning: A possible cause for this error is that the database did not originate from the
Primary server using HotStandby copy or netcopy command.
10081 Database Error The database file is incomplete or corrupt.

Meaning: If the file is on a hot standby secondary server, use the hotstandby copy or
hotstandby netcopy command to send the file from the primary server again.
10082 Database Error Backup aborted.
10083 Database Error Failed to abort HSB transaction because commit is already sent to secondary.
10084 Database Error Table is not locked.
10085 Database Error Checkpointing is disabled.
Database Error
10086 Deleted row not found.

A key value being deleted cannot be found in the b-tree. This is an internal error.
10087 Database Error HotStandby not allowed for main memory tables.
10088 Database Error Specified lock timeout is too large.
10089 Database Error Operation failed, server is in HSB primary uncertain mode.

Appendix E. Error codes 239

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Error
10090 Data dictionary operation in a newer transaction.

This error is returned when a transaction tries to access a table whose schema has been
altered by a later transaction. The recommended action is to retry the failing SQL
command in a new transaction.
Database Error
10091 Backup detected a log file with wrong block size, backup aborted.
Database Fatal Error
10092 HotStandby cannot operate when logging is disabled.
Database Fatal Error
10093 HotStandby migration is not possible if Hotstandby is not configured.
Database Fatal Error
10094 Only %d cache pages configured for M-table usage, at least %d needed.
Database Error
10095 Cursor is closed after isolation change.

The current cursor is closed, because its isolation level has been changed.
Database Fatal Error
10096 Only <kilobytes> kilobytes configured for M-table checkpointing, at least <kilobytes>KB
needed.

Not enough memory has been configured for the M-table.

Database Error
10098 Incrementing sequence sequence_name failed.
Database Fatal Error
10099 Encryption password has not been given for encrypted database.
Database Fatal Error
10100 Incorrect password has been given for encrypted database.
Database Fatal Error
10101 Unknown encryption algorithm.
Database Fatal Error
10104 Database is not created using solidDB Storage Engine for MySQL Prototype. Cannot open
database.
10105 Database Error Cache size for hash table specified with <value> parameter is smaller than actual cache
size.
Database Fatal Error
10106 Too big cache memory has been specified for the SOLID process. Edit the solid.ini file
to change this parameter value not to exceed system limit and restart the SOLID process.

This is a fatal error.

10107 Database Error Cursor is closed after logreader partition change.
10108 Database Error Search is aborted because of concurrent data dictionary operation on table.
10109 Database Error Transaction is already in prepared state, operation failed.
10110 Database Error XA transaction has not yet ended, operation failed.
10111 Database Error XA transaction has ended, operation failed.
10112 Database Error XA transaction is from a different connection, operation failed.
10113 Database Error Duplicate XID.
10114 Database Error XA transaction cannot have any DDL statements, operation failed.
10115 Database Error Operation is not supported with XA transaction.
16004 Database Message M-table operations now have enough memory for normal service.
16005 Database Message M-table operations now have enough memory for updates, inserts still disallowed.
16006 Database Message Memory for M-tables is now back below the warning level.

240 IBM solidDB: Administrator Guide

Table 67. solidDB database errors (continued)

Code Class Type Description

Database Error
16501 New row value too large for M-table.
Database Error
16502 Row size exceeds the allowed value for M-tables.
Database Error
16503 Serializable isolation level is not supported in M-tables.
Database Error
16504 Memory for M-tables is running low, inserts to M-tables disallowed.
Database Error
16505 Ran out of memory for M-tables, updates and inserts to M-tables disallowed.
Database Fatal Error
16506 Too small configured MME.ImdbMemoryLimit to start server.
16507 Database Error Memory for M-tables is above the warning level.
16509 Database Error MME transaction maximum size exceeded

The maximum transaction size is set with the MME.MaxTransactionSize parameter.

solidDB table errors

Error code Class Type Description

Table Error
13001 Illegal character constant constant.

An illegal character constant was found in the SQL statement.

Table Error
13002 Type CHAR not allowed for arithmetic.

You have entered a calculation having a character type constant. Character

constants are not supported in arithmetic.
Table Error
13003 Aggregate function not available for ordinary call.

The aggregate function, such as SUM(), is called as an ordinary function. This is

not allowed. For example, the following calls are illegal: SELECT * FROM TAB1
WHERE SUM(INT_COL) > 5; CALL SUM(1);
Table Error
13004 Illegal aggregate function parameter parameter.

An illegal parameter has been given to an aggregate function. Aggregate function

parameters can only be column names or numbers.
Table Error
13005 SUM and AVG not supported for CHAR type.

Aggregate functions SUM and AVG are not supported for character type
parameters.
Table Error
13006 SUM or AVG not supported for DATE type.

Aggregate functions SUM and AVG are not supported for date type parameters.
Table Error
13007 Function function is not defined.

The function you tried to use is not defined.

Table Error
13008 Illegal parameter to ADD function.

Appendix E. Error codes 241

Error code Class Type Description
Table Error
13009 Division by zero.

A division by zero has occurred.

Table Error
13011 Table table does not exist.

You have referenced a table which does not exist or you do not have
REFERENCES privilege on the table.
Table Error
13013 Table name table conflicts with an existing entity.

Choose a unique name for a table. The specified name is already used.
Table Error
13014 Index index does not exist.

You have referenced an index which does not exist.

Table Error
13015 Column column does not exist on table table.

You have referenced a column in a table which does not exist.

Table Error
13018 Join table is not supported

Joined tables are not supported in this version of solidDB.

Table Error
13019 Transaction savepoints are not supported.

Transaction savepoints are not supported in this version of solidDB.

Table Error
13020 Default values are not supported.

Default column values are not supported in this version of solidDB.

Table Error
13022 Descending keys are not supported.

Descending keys are not supported in this version of solidDB.

Table Error
13023 Schema is not supported.

Schema is not supported in this version of solidDB.

Table Error
13025 Update through a cursor with no current row.

You have tried to update using a cursor, but you do not have a current row in the
cursor.
Table Error
13026 Delete through a cursor with no current row

You have tried to delete using a cursor, but you do not have a current row in the
cursor.
Table Error
13028 View view_name does not exist.

You have referenced a view which does not exist.

Table Error
13029 View name view_name conflicts with an existing entity.

Choose a unique name for a view. The specified name is already used.

242 IBM solidDB: Administrator Guide

Error code Class Type Description
Table Error
13030 No value specified for NOT NULL column column.

You have not specified a value for a column which is defined NOT NULL.
Table Error
13031 Data dictionary operation is active for accessed table or key.

You can not access the table or key, because a data dictionary operation is
currently active. Try again after the data dictionary operation has completed.
Table Error
13032 Illegal type type.

You have tried to create a table with a column having an illegal type.
Table Error
13033 Illegal parameter parameter for type type.

The type of the parameter you entered is illegal in this column.

Table Error
13034 Illegal constant constant.

You have entered an illegal constant.

Table Error
13035 Illegal INTEGER constant constant.

You have entered an illegal integer type constant. Check the syntax of the
statement and try again.
Table Error
13036 Illegal DECIMAL constant constant.

You have entered an illegal decimal type constant. Check the decimal number and
try again.
Table Error
13037 Illegal DOUBLE PREC constant constant.

Typically, this is a general parse error. The SQL statement may contain a syntax
error before the constant. As a last resort, the parser has attempted to parse a
DOUBLE PREC constant, but has failed.

This error also occurs if you entered an illegal double precision type constant.

(More specifically, this error occurs when a space is placed between the asterisk
and the closing parenthesis ("*)") in an optimizer hint.)

In any of these cases, be sure to check the syntax of the statement and try again.
Table Error
13038 Illegal REAL constant constant.

You have entered an illegal real type constant. Check the real number and try
again.
Table Error
13039 Illegal assignment.

You have tried to assign an illegal value for a column. For example, you may have
tried to assign a value that was too large or was of the wrong data type.
Table Error
13040 Aggregate function function is not defined.

The aggregate function you tried to use is not supported.

Table Error
13041 Type DATE not allowed for arithmetic.

DATE type columns or constants are not allowed in arithmetic.

Appendix E. Error codes 243

Error code Class Type Description
Table Error
13042 Power arithmetic not allowed for NUMERIC and DECIMAL data type.

Decimal and numeric data types do not support power arithmetic.

Table Error
13043 Illegal date constant constant.

A date constant is illegal. The correct form for date constants is: YYYY-MM-DD.
Table Error
13046 Illegal user name user.

User name entered is not legal. A legal user name is at least 2 and at most 31
characters in length. A user name may contain characters from A to Z, numbers
from 0 to 9 and underscore character '_'.
13047 Table Error
No privileges for operation.

You have no privileges for the attempted operation. To carry out this operation,
you must be granted appropriate privileges. Alternatively, the operation can be
performed by another user who already has the appropriate privileges. See the
GRANT statement for more information.

NOTE: If you are trying to drop a catalog that you previously created, and you get
this error message, then your SYS_ADMIN_ROLE (i.e. DBA) privileges have been
revoked. Only the creator of the database or users having SYS_ADMIN_ROLE (i.e.
DBA) have privileges to create or drop a catalog. Even the creator of a catalog
cannot drop that catalog if she loses SYS_ADMIN_ROLE privileges. (Creating a
catalog, unlike creating most other objects (such as tables) does not make you the
owner; instead, the ownership of all catalogs belongs to the DBA/
SYS_ADMIN_ROLE.)
13048 Table Error
No grant option privilege for entity name.

You have no privileges to grant privileges for the entity.

13049 Table Error
Column privileges cannot be granted WITH GRANT OPTION

Granting column privileges WITH GRANT OPTION is not supported in this

version of solidDB.
13050 Table Error
Too long constraint value.

Maximum constraint length has been exceeded. Maximum constraint length is 255
characters.
13051 Table Error
Illegal column name column.

You have tried to create a table with an illegal column name.

13052 Table Error
Illegal comparison operator operator for a pseudo column column.

You have tried to use an illegal comparison operator for a pseudo column. Legal
comparison operators for pseudo columns are: equality '=' and non-equality '<>'.
13053 Table Error
Illegal data type for a pseudo column.

You have tried to use an illegal data type for a pseudo column. Data type of
pseudo columns is BINARY.

244 IBM solidDB: Administrator Guide

Error code Class Type Description
13054 Table Error
Illegal pseudo column data, maybe data is not received using pseudo column.

You have tried to compare pseudo column data with non-pseudo column data.
Pseudo column data can only be compared with data received from a pseudo
column.
13055 Table Error
Update not allowed on pseudo column.

Updates are not allowed on pseudo columns.

13056 Table Error
Insert not allowed on pseudo column.

Inserts are not allowed on pseudo columns.

13057 Table Error
Index name index already exists.

You have tried to create an index, but an index with the same name already exists.
Use another name for the index.
13058 Table Error
Constraint checks were not satisfied on column column.

Column has constraint checks which were not satisfied during an insert or update.
13059 Table Error
Reserved system name name.

You tried to use a name which is a reserved system name such as PUBLIC and
SYS_ADMIN_ROLE.
13060 Table Error
User name user not found.

You tried to reference a user name which is not created.

13061 Table Error
Role name role not found.

You tried to reference a role name which is not created.

13062 Table Error
Admin option is not supported.

Admin option is not supported in this version of solidDB.

13063 Table Error
Name name already exists.

You tried to use a role or user which already exists. User names and role names
must all be different, that is, you can not have a user named HOBBES and a role
named HOBBES.
13064 Table Error
Not a valid user name user.

You tried to create an invalid user name. A valid user name has at least 2
characters and at most 31 characters. A user name may contain characters from A
to Z, numbers from 0 to 9 and underscore character '_'.
13065 Table Error
Not a valid role name role.

You tried to create an invalid role name. A valid role name has at least 2 characters
and at most 31 characters. A role name may contain characters from A to Z,
numbers from 0 to 9 and underscore character '_'.
13066 Table Error
User user not found in role role.

You tried to revoke a role from a user and the user did not have that role.

Appendix E. Error codes 245

Error code Class Type Description
13067 Table Error
Too short password.

You have entered a too short password. Password length must be at least 3
characters.
13068 Table Error
Shutdown is in progress.

You are unable to complete this operation, because server shutdown is in progress.
13070 Table Error
Numerical overflow.

A numerical overflow has occurred. Check the values and types of numerical
variables.
13071 Table Error
Numerical underflow.

A numerical underflow has occurred. Check the values and types of numerical
variables.
13072 Table Error
Numerical value out of range.

A numerical value is out of range. Check the values and types of numerical
variables.
13073 Table Error
Math error.

A mathematical error has occurred. Check the mathematics in the statement and
try again.
13074 Table Error
Illegal password.

You have tried to enter an illegal password.

13075 Table Error
Illegal role name role.

You have tried to enter an illegal role name. A legal role name is at least 2 and at
most 31 characters in length. A user role may contain characters from A to Z,
numbers from 0 to 9 and underscore character '_'.
13077 Table Error
Last column can not be dropped.

You have tried to drop the final column in a table. This is not allowed; at least one
column must remain in the table.
13078 Table Error
Column already exist on table.

You have tried to create a column which already exists in a table.

13079 Table Error
Illegal search constraint.

Check the search engine. There may be mismatch between data types.
13080 Table Error
Incompatible types, can not modify column column fromtype type to type type.

You have tried to modify column to a data type that isincompatible with the
original definition, such as VARCHARand INTEGER
13081 Table Error
Descending keys are not supported for binary columns.

You can not define a descending key for a binary column.

246 IBM solidDB: Administrator Guide

Error code Class Type Description
13082 Table Error
Function function: parameter * not supported.

You can not use parameter star (*) with ODBC Scalar Functions.
13083 Table Error
Function function: Too few parameters.

The function expects more parameters. Check the function call.

13084 Table Error
Function function: Too many parameters.

The function expects fewer parameters. Check the function call.

13085 Table Error
Function function: Run-time failure.

An error was detected during the execution of the function. Check the parameters.
Table Error
13086 Function function: type mismatch in parameter parameter number.

An erroneous type of parameter was detected in the given position of the function
call. Check the function call.
Table Error
13087 Function function: illegal value in parameter parameter number.

An illegal value for a parameter detected in the given position of the function call.
Check the function call.
Table Error
13088 No primary key for table.
Table Error
13090 Foreign key column column data type not compatible with referenced column data
type.

References specification error. Check that the column data type are compatible
between referencing and referenced tables.
Table Error
13091 Foreign key does not match to the primary key or unique constraint of the
referenced table.

References specification error. Check that the column data types are compatible
between referencing and referenced tables and that the foreign key is unique for
the referenced table.
Table Error
13092 Event name event conflicts with an existing entity.

Choose a unique name for an event. The specified name is already used.
Table Error
13093 Event event does not exist.

You referenced a nonexistent event. Check the name of the event.

Table Error
13094 Duplicate column column in primary key definition.

Duplicate columns are not allowed in a table-constraint-definition. Remove

duplicate columns from the definition.
Table Error
13095 Duplicate column column in unique constraint definition.

Duplicate columns are not allowed in a table-constraint-definition. Remove

duplicate columns from the definition.

Appendix E. Error codes 247

Error code Class Type Description
Table Error
13096 Duplicate column column in index definition.

Duplicate columns are not allowed in CREATE INDEX statement. Remove

duplicate columns.
13097 Table Error
Primary key columns must be NOT NULL.

Error in a column_constraint_definition. Define primary key columns NOT NULL.

For example: CREATE TABLE DEPT (DEPTNO INTEGER NOT NULL, DNAME
VARCHAR, PRIMARY KEY(DEPTNO));
13098 Table Error Unique constraint columns must be NOT NULL.

Error in a column_constraint_definition. Define unique columns NOT NULL. For

example: CREATE TABLE DEPT4 (DEPTNO INTEGER NOT NULL, DNAME
VARCHAR, UNIQUE(DEPTNO));
13099 Table Error No REFERENCES privileges to referenced columns in table table.

You do not have privileges to reference to the table.

13100 Table Error Illegal table mode combination.

You have defined an illegal combination of concurrency control settings. This

message occurs, for example, if you have an in-memory table and you try to
change it from pessimistic concurrency control (locking) to optimistic concurrency
control by using the command ALTER TABLE <table_name> SET PESSIMISTIC.

In-memory tables must always use pessimistic concurrency control.

13101 Table Error Only execute privileges can be used with procedures.
13102 Table Error Execute privileges can be used only with procedures.
13103 Table Error Illegal grant or revoke operation.

This error occurs if you try to revoke privileges from yourself.

This error occurs if the DBA tries to grant privileges to herself or himself (to the
DBA).
13104 Table Error Sequence name sequence conflicts with an existing entity.

Choose a unique name for a sequence. The specified name is already used.
13105 Table Error Sequence sequence does not exist.

You referenced a nonexistent sequence. Check the name of sequence.

13106 Table Error
Foreign key reference exists to table table.
13107 Table Error
Illegal set operation.

You tried to execute a non-existent set operation.

13108 Table Error
Comparison between incompatible types datatype and datatype.
13109 Table Error
There are schema objects for this user, drop failed
13110 Table Error
NULL values given for NOT NULL column column.

248 IBM solidDB: Administrator Guide

Error code Class Type Description
13111 Table Error
Ambiguous entity name name.

This message occurs if the name of the specified database object (for example, a
table name) does not exist in the schema that you are currently in, but more than
one other schema contains an object with that name.

If the database object that you want is in a different schema than the schema you
are currently in, then change to the appropriate schema by using the SET
SCHEMA command, or specify the desired object by using a more fully qualified
object name, for example:

sales_catalog.jan_wong_schema.table.1
13112 Table Error
Foreign keys are not supported with main memory tables.
13113 Table Error
Illegal arithmetic between types datatype and datatype.
13114 Table Error
String operations are not allowed on values stored as BLOBs or CLOBs.
13115 Table Error
Function function_name: Too long value (stored as CLOB) in parameter parameter.

The parameter value was stored as CLOB and cannot be used with a function.
13116 Table Error
Column column_name specified more than once.

Column was specified more than once in the GRANT or REVOKE statement.
13117 Table Error
Wrong number of parameters

Wrong number of parameters when converting subscription parameters to base

publication parameter types.
13118 Table Error
Column privileges are supported only for base tables.

Column privileges are allowed only for base tables; they cannot be used, for
example, for views.
13119 Table Error
Types column_type and column_type are not union compatible.

Column types are not union compatible. When a UNION operation is performed,
two columns from two different tables are used to generate one column of output.
The operation is successful as long as the two columns are of the same type or
"compatible" types. Types are compatible if one type can reasonably be converted
into the other type. For example, you can UNION a column of FLOAT with a
column of INT because any integer value can also be represented as a
corresponding float value (for example, 2 can be converted to 2.0). However, if you
attempt a UNION operation on two incompatible types, such as FLOAT and
DATE, you will receive 13119.
13120 Table Error
Too long entity name 'entity_name'.

Entity name is too long, maximum entity name is 254 characters.

13121 Table Error
Too many columns, maximum number of columns per table is value.

Note that the maximum number of columns may be less if each column requires a
large number of bytes.
13122 Table Error
Operation is not supported for a table with sync history.

Operation is not supported because the table has synchronization history defined.

Appendix E. Error codes 249

Error code Class Type Description
13123 Table Error
Table 'table_name' is not empty.

Some operations are allowed only for empty tables.

Table Error
13124 User id user_id not found.

Internal user id was not found; the user may have been dropped.
Table Error
13125 Illegal LIKE pattern 'pattern'.

Illegal like pattern was given as a search constraint.

Table Error
13126 Illegal type datatype for LIKE pattern.

Only CHAR and WCHAR allowed for LIKE search constraints.

Table Error
13127 Comparison failed because at least one of the values was too long.

Comparison failed because at least one of the column values was stored as a BLOB
or CLOB.
Table Error
13128 LIKE predicate failed because value is too long.

LIKE predicate failed because the column value is stored as a CLOB.

Table Error
13129 LIKE Predicate failed because pattern is too long.

LIKE predicate failed because pattern value is stored as a CLOB.

Table Error
13130 Illegal type datatype for LIKE ESCAPE character.

Like ESCAPE character must be CHAR or WCHAR type.

Table Error
13131 Too many nested triggers.

Maximum number of nested triggers is reached. Triggers may be nested, for

example, by activating other triggers from a trigger or causing recursive cycle
when activating triggers. Default value for maximum allowed nested triggers is 16.
It can be changed using a configuration parameter:
[SQL]
MaxNestedTriggers=n

Table Error
13132 Too many nested procedures.

Maximum number of nested procedures is reached. Procedures may be nested, for

example, by activating other procedures from a procedure or causing a recursive
cycle when activating procedures. Default value for maximum allowed nested
procedures is 16. It can be changed using a configuration parameter:
[SQL]
MaxNestedProcedures=n

13133 Table Error

Not a valid license for this product.

The license file is for another solidDB product.

13134 Table Error
Operation is allowed only for base tables.

Given operation is available only for base tables.

250 IBM solidDB: Administrator Guide

Error code Class Type Description
13135 Table Error Internal error, arithmetic error in estimator

For more information, contact solidDB Technical Support at http://www.ibm.com/

software/data/soliddb/support/.
13136 Table Error Internal error, transaction is not active

For more information, contact solidDB Technical Support at http://www.ibm.com/

software/data/soliddb/support/.
13137 Table Error
Illegal grant/revoke mode

Grant or revoke mode is not allowed for given database objects.

Table Error
13138 Index index_name given in index hint does not exist.

Index name given in optimizer hint is not found for a table.

Table Error
13139 Catalog catalog_name does not exist.

Catalog name is not a valid catalog.

Table Error
13140 Catalog catalog_name already exists.

Catalog name is an existing catalog.

Table Error
13141 Schema schema_name does not exist.

Schema name is not a valid schema.

Table Error
13142 Schema schema_name already exists.

Schema name is an existing schema.

Table Error
13143 Schema schema_name is an existing user.

Schema name specifies an existing user name.

Table Error
13144 Commit and rollback are not allowed inside trigger.

Commit or rollback are not supported inside trigger execution. This error is also
given if a trigger calls a procedure that tries to execute commit or rollback
command.
Table Error
13145 Sync parameter not found.

Parameter name given in command SET SYNC PARAMETER name NONE is not
found.
Table Error
13146 There are schema objects for this catalog, drop failed.

Catalog contains schema object and cannot be dropped. Schema objects like tables
and procedures need to be dropped before catalog can be dropped.
Table Error
13147 Current catalog can not be dropped.

The catalog that you want to drop must not be the current catalog. If you get this
message, you should switch to another catalog, then re-execute the DROP
CATALOG command.
Table Error
13148 There are objects for this schema, drop failed.

Appendix E. Error codes 251

Error code Class Type Description
Table Error
13149 There are objects for this catalog, drop failed.
Table Error
13150 Index can be created only into same catalog and schema as the base table.
Table Error
13151 Cannot drop a column that is part of primary or unique key.

Table definition contains a column that is part of a primary or unique key in an

index.
Table Error
13152 There are objects for this user, drop failed.
Table Error
13153 Can not remove last administrator.
Table Error
13154 Name cannot be an empty string.
Table Error
13155 Column <column name> already exists on view <view name>

The view definition contains the same column name twice.

Table Error
13156 Column attributes already exists on view.
Table Error
13157 Current schema cannot be dropped.
Table Error
13158 Current user cannot be dropped.
Table Error
13160 Cannot alter table name because it is referenced in trigger(s).

Altering the name of the table would prevent the trigger from working properly.
Table Error
13161 An M-table is being updated with UPDATE ... WHERE CURRENT OF CURSOR
and CURSOR is not declared FOR UPDATE.

When you update an in-memory table (an "M-table") using the command UPDATE
... WHERE CURRENT OF CURSOR, you must have declared the cursor using the
FOR UDPATE clause. This is required when the table is an in-memory table; it is
strongly recommended, but not required, when the table is a disk-based table.
Table Error
13162 A record in an M-table is being deleted with DELETE ... WHERE CURRENT OF
CURSOR and CURSOR is not declared FOR UPDATE.

When you delete a record from an in-memory table (an "M-table") using the
command DELETE ... WHERE CURRENT OF CURSOR, you must have declared
the cursor using the FOR UDPATE clause. This is required when the table is an
in-memory table; it is strongly recommended, but not required, when the table is a
disk-based table.
Table Error
13163 Descending keys are not supported for bigint columns.

If you try to create a DESCending index on a column of type BIGINT, you will get
this message. Use an ASCending key instead.
Table Error
13164 Transaction is active, operation failed.
Table Error
13165 Cannot fetch previous row from an M-table.

This message can occur only when fetching rows from in in-memory table
("M-table") by using solidDB's low-level SA API.
Table Error
13166 License does not allow accessing M-tables

252 IBM solidDB: Administrator Guide

Error code Class Type Description
Table Error
13167 Only M-tables can be transient.
Table Error
13168 Transient tables can not be set temporary.
Table Error
13169 Temporary tables can not be set transient.
Table Error
13170 Only M-tables can be temporary.
Table Error
13171 Foreign key constraints between D- and M-tables are not supported.
Table Error
13172 A persistent table can not reference a transient table.

For more details, see the discussion on persistent and transient tables under the
CREATE TABLE command in the "Solid® SQL Syntax" appendix in solidDB SQL
Guide.
Table Error
13173 A persistent table can not reference a temporary table.

For more details, see the discussion on persistent and transient tables under the
CREATE TABLE command in the "Solid SQL Syntax" appendix in solidDB SQL
Guide.
Table Error
13174 A transient table can not reference a temporary table.

For more details, see the discussion on persistent and transient tables under the
CREATE TABLE command in the "Solid SQL Syntax" appendix in solidDB SQL
Guide.
Table Error
13175 A reference between temporary and non-temporary table is not allowed.
Table Error
13176 Cannot change STORE for a table with sync history.
Table Error
13177 Cannot define UNIQUE constraint with duplicated or implied restriction.
Table Error
13178 Constraint not found.
Table Error
13179 Foreign key actions other than restrict are not supported.
Table Error
13180 Constraint name already exists.
Table Error
13181 Constraint check fails on existing data.
Table Error
13182 Added column with NOT NULL must have a non-NULL default.
Table Error
13183 Index is referenced by foreign key, it cannot be dropped.
Table Error
13184 Primary key not found for table. Cannot define foreign key.
Table Error
13185 Cannot set NOT NULL on column that already has NULL value.
Table Error
13186 Cannot drop NOT NULL on column that is used as part of unique key.
Table Error
13187 The cursor cannot continue accessing M-tables after the transaction has committed
or aborted. The statement must be re-executed.
Table Error
13188 Foreign key refers to itself.

Appendix E. Error codes 253

Error code Class Type Description
Table Error
13189 Positioning is not supported for M-tables.
13190 Table Fatal Error
Definition in file is not valid.
13191 Table Fatal Error
Parameter setting in file conflicts with the setting in database.
13192 Table Fatal Error Database is in read-only state
13193 Table Fatal Error Foreign key creates update dependency loop.

A foreign key creates a dependency between one or more tables in such a way that
update to one row in one table might cause multiple updates to the same row in
the same or another table. Such update might be ambiguous and the server does
not allow creation of such dependencies.

This restriction does not apply to cascaded deletes (when deletion of one row
causes multiple deletions of another row), but it still applies when the deletion of
one row causes multiple updates (SET NULL or SET DEFAULT) to another row.
13194 Table Error
Can not drop a table that is part of a foreign key
13195 Table Error
Update failed, READ COMMITTED isolation requires FOR UPDATE
13196 Table Error
Delete failed, READ COMMITTED isolation requires FOR UPDATE
13197 Table Error
M-tables are not supported
13198 Table Error
Commit and rollback are not allowed inside function.
13199 Table Error
Duplicate index definition

This error is returned when a duplicate or redundant index is detected during

index creation.

For example, if you have created an index as follows:

CREATE UNIQUE INDEX IND_1 ON T1(C1,C2,C3);

Next, if you create this index:

CREATE INDEX IND_2 ON T1(C2,C3,C1,C4);

After this step, solidDB returns error 13199. In the example above, the second
index is a superset of the unique first index. This implies that the second index
(although it is not explicitly specified as unique) is also unique. In practice, the
second index is useless. It only affects space consumption and update
performance, not lookup performance.
13200 Table Error
Update failed.

Used isolation level requires FOR UPDATE.

13201 Table Error
Delete failed.

Used isolation level requires FOR UPDATE.

13202 Table Error
Cluster connection does not support isolation levels higher than READ
COMMITTED.
13203 Table Error License does not allow creating D-tables
13204 Table Error SET WRITE command makes sense only for TC connection
13205 Table Error Cannot change STORE for a table with foreign keys.

254 IBM solidDB: Administrator Guide

Error code Class Type Description
13400 Table Error
Alter or drop table not allowed for propagated tables.
13401 Table Error
Truncate table not allowed for propagated tables.
13402 Table Error
Propagation information loading active.
13403 Table Error
Propagation information loading not active.
Table Error
13404 Triggers not allowed for propagated tables.
Table Error
13405 Cascading foreign keys not allowed for propagated tables.
Table Error
13406 Primary key is required for propagated tables.
Table Error
13407 Propagation schema data inconsistent: Table name not found.
Table Error
13408 Logreader feature is disabled.
Table Error
13409 Log overflow, catchup is not possible.
13410 Table Error
Logreader partition not found .
13411 Table Error
No active logreader query.
Table Error
13412 Propagated tables allow only one row update when primary or unique key is
changed.
13413 Table Error Row size exceeds the allowed value for propagated tables.
13414 Table Error Given attribute value is incorrect for range partitioned table <value>.
13415 Table Error Range column <value> is not found from partitioned table <value>.
13416 Table Error Logreader partition already exists
13417 Table Error Table not found from logreader partition
13418 Table Error Table already exists in logreader partition
13451 Table Error Passthrough not configured.

Check that you have set the Passthrough.PassthroughEnabled parameter to 'Yes'.

Check that the SYS_SERVER table contains correct login data for the back-end.
13452 Table Error Passthrough backend database not available.

solidDB cannot connect to the back-end data server. Check your configuration
settings.
13453 Table Error Passthrough cursors are forward only cursors.

Appendix E. Error codes 255

Error code Class Type Description
13454 Table Error Passthrough error: <description>

This error is returned to user if the back-end data server reports a failure but
solidDB cannot read the actual error.

The following reasons cause the this error to be output to solmsg.out:

v The Passthrough.SqlPassthroughRead or Passthrough.SqlPassthroughWrite
parameter in the solid.ini has an invalid value (for example,
SqlPassthroughRead=forse)
v The Passthrough.PassthroughEnabled parameter is set to 'Yes' but
Passthrough.RemoteServerDriverPath is not defined.
v The Passthrough.PassthroughEnabled parameter is set to 'Yes' but
Passthrough.RemoteServerDSN is not defined.
v A function in a .dll cannot be found. The error description is the function name.
v A .dll cannot be found.
13455 Table Error Passthrough not allowed.

This error is caused by violation of the set isolation level. To preserve consistency
of the back-end database when using SQL passthrough, the isolation level of the
front-end must be the same (or similar) or higher than in the back-end.
13456 Table Error Passthrough backend error: SQLState=<value>, NativeError=<back-end error
identifier>, MessageText=<back-end error description>.
13457 Table Error Passthrough error: resultset mismatch.

The table definitions in the front-end and back-end database do not match (for
example, the number of columns is different).
13458 Table Error Passthrough error: parameter mismatch.

The parameters used in an SQL statements do not match when executed in the
front-end and back-end database.
13459 Table Error Passthrough error: Datatype is not supported.
13460 Table Error Server <name> already exists

The back-end login data for the specified server has been created already.
Note: The default name for the back-end data server is 'default'.
13461 Table Error Server <name> not found.

The back-end login data for the specified server does not exist.
13463 Table Error Passthrough error. Distributed transaction must be read only in back-end.
13501 Table Warning String data truncation in assignment from <value> to <value>
13502 Table Warning Numeric value right truncation in assignment from <value> to <value>

solidDB session errors

Table 68. solidDB session errors
Code Class Type Description
20001 Session Error
Illegal session class.
20002 Session Error
Dynamic link library not found.
20003 Session Error
Wrong dynamic link library version.
20004 Session Error
Illegal address info.

256 IBM solidDB: Administrator Guide

Table 68. solidDB session errors (continued)
Code Class Type Description
20005 Session Error
Listening address is in use.
20006 Session Error
Server not found.
20007 Session Error
Illegal control parameter.
20008 Session Error
Illegal size parameter.
20009 Session Error
Write operation failed.

This error is returned if the server or client is trying to write to an underlying communication
channel (socket, named pipe, shared memory) that is broken.
20010 Session Error
Read operation failed.
20011 Session Error
Accept operation failed.
20012 Session Error
Network not found.
20013 Session Error
Out of network resources.
20023 Session Error
Too many name resolver requests already in progress.
20024 Session Error
Timeout while resolving host name.
20025 Session Error
Timeout while connecting to a remote host.

solidDB communication errors

Table 69. solidDB communication errors

Code Class Type Description

21100 Communication Warning
Illegal value value for configuration parameter parameter, using default.

An illegal value was given to the parameter parameter. The server will use a
default value for this parameter.
21101 Communication Warning
Invalid protocol definition protocol in configuration file.

The protocol is defined illegally in the configuration file. Check the syntax of
the definition.
21300 Communication Error
Protocol protocol is not supported.

Protocol is not supported.

21301 Communication Error
Cannot load the dynamic link library library or one of its components.

The server was unable to load the dynamic link library or a component
needed by this library. Check the existence of necessary libraries and
components.
21302 Communication Error
Wrong version of dynamic link library library.

The version of this library is wrong. Update this library to a newer version.

Appendix E. Error codes 257

Table 69. solidDB communication errors (continued)

Code Class Type Description

21303 Communication Error
Network adapter card is missing or needed protocol software is not running.

The network adapter card is missing or not functioning.

21304 Communication Error
Out of protocol resources

The network protocol is out of resources. Increase the protocols' resources in

the operating system.
21305 Communication Error
An empty or incomplete network name was specified.

The network name specified is not legal. Check the network name.
21306 Communication Error
Server network name not found, connection failed.

The server was not found. 1) Check that the server is running. 2) Check that
the network name is valid. 3) Check that the server is listening to the given
network name.
21307 Communication Error
Invalid connect info network name.

The network name given as the connect info is not legal. Check the network
name.
21308 Communication Error
Connection is broken (protocol read/write operation failed with code internal
code).

The connection using the protocol is broken. Either a read or a write

operation has failed with an internal error internal code.
21309 Communication Error
Failed to accept a new client connection, out of protocol resources.

The server was not able to establish a new client connection. The protocol is
out of resources. Increase the protocol's resources in the operating system.
21310 Communication Error
Failed to accept a new client connection, listening of network name
interrupted.

The server was not able to establish a new client connection. The listening
has been interrupted.
21311 Communication Error
Failed to start a selecting thread for network name.

A thread selection has failed for network name.

21312 Communication Error
Listening info network name already specified for this server.

A network name has already been specified for this server. A server can not
use a same network name more than once.
21313 Communication Error
Already listening with the network name network name.

You have tried to add a network name to a server when it is already listening
with that network name. A server can not use a same network name more
than once.

258 IBM solidDB: Administrator Guide

Table 69. solidDB communication errors (continued)

Code Class Type Description

21314 Communication Error
Cannot start listening, network name network name is used by another
process.

The server can not start listening with the given network name. Another
process in this computer is using the same network name.
21315 Communication Error
Cannot start listening, invalid listening info network name.

The server can not start listening with the given listening info. The given
network name is invalid. Check the syntax of the network name.
21316 Communication Error
Cannot stop the listening of network name. There are clients connected.

You can not stop listening of this network name. There are clients connected
to this server using this network name.
21317 Communication Error
Failed to save the listen information into the configuration file.

The server failed to save this listening information to the configuration file.
Check the file access rights and format of the configuration file.
21318 Communication Error
Operation failed because of an unusual protocol return code code.

Possible network error. Create connection again.

21319 Communication Error
RPC request contained an illegal version number.

Either the message was corrupted or there may be a mismatch between

server and client versions.
21320 Communication Error
Called RPC service is not supported in the server.

There maybe a mismatch between server and client versions.

21321 Communication Error
Protocol protocol is not valid, try using switch '-a' for specifying another
adapter id instead of switch.

This is returned if the NetBIOS LAN adapter id given in listen/connect string

is not valid.
21322 Communication Error
The host machine given in connect info '%s' was not found.

This is returned in clients if the host machine name given in connect info is
not valid.
21323 Communication Error
Protocol protocol can not be used for listening in this environment.

This message is displayed if the server end communication using specified

protocol is not supported.
21324 Communication Error
The process does not have the privilege to create a mailbox.
21325 Communication Error
Only one listening name is supported in this server.
21326 Communication Error
Failed to establish an internal number socket connection code number.

solidDB uses one connect socket for internal use. Creation of this socket has
failed; the local loopback may not be working correctly.

Appendix E. Error codes 259

Table 69. solidDB communication errors (continued)

Code Class Type Description

21327 Communication Error
Too many name resolver requests already in progress.
21328 Communication Error
Timeout while resolving host name.
21329 Communication Error Timeout while connecting to host.
21330 Communication Error Failed to accept a new client connection, too many open files

solidDB server errors

Table 70. solidDB server errors
Class Type
Code Description
14003 Server Return ACTIVE
Code
ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby status switch'
v ADMIN COMMAND 'hotstandby status catchup'
v ADMIN COMMAND 'hotstandby status copy'

Meaning: The switch process, catchup process, copy or netcopy process is still active.
14007 Server Return CONNECTING
Code
ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby status connect'

Meaning: The Primary and Secondary servers are in the process of connecting.
14008 Server Return CATCHUP
Code
ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby status connect'

Meaning: The Primary server is connected to the Secondary server, but the transaction log is
not yet fully copied. This message is returned only from the Primary server.
14009 Server Return No server switch occurred before.
Code
ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby status switch'

Meaning: The switch process has never happened between the servers.
14501 Server Error
Operation failed.

This error occurs when a timed command fails. Check the arguments of timed commands.

This error number is also used for certain HotStandby errors. See IBM solidDB High
Availability User Guide for details.
14502 Server Error
RPC parameter is invalid.

A network error has occurred.

14503 Server Error
Communication error.

A communication error has occurred.

260 IBM solidDB: Administrator Guide

Table 70. solidDB server errors (continued)
Class Type
Code Description
14504 Server Error
Duplicate cursor name cursor.

You have tried to declare a cursor with a cursor name which is already in use. Use another
name.
14505 Server Error
Connect failed, illegal user name or password.

You have entered either a user name or a password that is not valid.
14506 Server Error
The server is closed, no new connections allowed.

You have tried to connect to a closed server. Connecting was aborted.

Server Error
14507 Exceeded maximum number of user connections defined with Srv.MaxUsers or limited by
license. Only connections from solcon allowed.
Note: Srv.MaxUsers can only be set by editing solid.ini and restarting the server.
14508 Server Error
The operation has timed out.

You have launched an operation that has been aborted.

14509 Server Error
Version mismatch.

A version mismatch has occurred. The client and server are different versions. Use same
versions in the client and the server.
14510 Server Error
Communication write operation failed.

A write operation failed. This indicates a network problem. Check your network settings.
14511 Server Error
Communication read operation failed.

A read operation failed. This indicates a network problem. Check your network settings.
Server Error
14512 There are users logged to the server.

You can not shutdown the server now. There are users connected to the server.
Server Error
14513 Backup process is active.

You cannot shut down the server now. The backup process is active
Server Error
14514 Checkpoint creation is active.

You cannot shut down the server now. The checkpoint creation is active.
Server Error
14515 Invalid user id.

You tried to drop a user, but the user id is not logged in to the server.
Server Error
14516 Invalid user name.

You tried to drop a user, but the user name is not logged in to the server.
Server Error
14517 Someone has updated the at commands at the same time, changes not saved.

You tried to update timed commands at the same time another user was doing the same.
Your changes will not be saved.

Appendix E. Error codes 261

Table 70. solidDB server errors (continued)
Class Type
Code Description
Server Error
14518 Connection to the server is broken, connection lost.

Possible network error. Reconnect to the server.

Server Error
14519 The user was thrown out from the server, connection lost.

Possible network error.

14520 Server Error Server is HotStandby secondary server, no connections are allowed.
Server Error
14521 Failed to create a new thread for the client.
14522 Server Error HotStandby copy directory not specified.

Meaning: No copy directory is specified.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby copy'

To solve this problem, either specify the directory as part of the command, for example:
ADMIN COMMAND ’hotstandby copy \Secondary\dbfiles\’

or else set the CopyDirectory parameter in the solid.ini configuration file.

14523 Server Error Switch process is already active.

Meaning: The switch process is already active in the HotStandby server. If you only need to
complete the current switch, then wait. If you are trying to switch a second time (that is,
switch back to the original configuration), then you must wait for the first switch to
complete before you can start the second switch.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby switch primary'
v ADMIN COMMAND 'hotstandby switch secondary'
v ADMIN COMMAND 'hotstandby status switch'
14524 Server Error HotStandby databases have a different base database, database time stamps are different.

Meaning: Databases are from a different seed database. You must synchronize databases. You
may need to perform netcopy of the Primary's database to the Secondary.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby connect'
v ADMIN COMMAND 'hotstandby status switch'
14525 Server Error HotStandby databases are not properly synchronized.

Meaning: Databases are not properly synchronized. You must synchronize the databases. You
may need to start one of the database servers (the one that you intend to become the
Secondary) with the command line parameter -x backupserver and then netcopy the
Primary's database to the Secondary.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby connect'
v ADMIN COMMAND 'hotstandby status switch'

262 IBM solidDB: Administrator Guide

Table 70. solidDB server errors (continued)
Class Type
Code Description
14526 Server Error Invalid argument.

Meaning: An argument used in the HotStandby ADMIN COMMAND is unknown or

invalid.

All HotStandby commands can return this error in the result set of the ADMIN
COMMAND.

Note: In the following HotStandby commands, the invalid argument error is a syntax error
when the specified Primary or Secondary server can not apply to the switch:
v ADMIN COMMAND 'hotstandby switch primary'
v ADMIN COMMAND 'hotstandby switch secondary'
14527 Server Error This is a non-HotStandby server.

Meaning: The command was executed on a server that is not configured for HotStandby.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby connect'
v ADMIN COMMAND 'hotstandby status switch'
v ADMIN COMMAND 'hotstandby switch primary'
v ADMIN COMMAND 'hotstandby switch secondary'
v ADMIN COMMAND 'hotstandby state'
14528 Server Error Both HotStandby databases are primary databases.

Meaning: Both databases are Primary. This is a fatal error because there may be conflicting
changes. Both databases are automatically dropped to Secondary state by the system. You
must decide which database is the real Primary database and then synchronize the
databases.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby connect'
v ADMIN COMMAND 'hotstandby status switch'
Server Error
14529 The operation timed out.
Server Error
14530 The connected client does not support UNICODE data types.

Connected client is an old version client that does not support UNICODE data types.
UNICODE data type columns cannot be used with old clients.
Server Error
14531 Too many open cursor, max limit is value.

There are too many open cursors for one client; maximum number of open cursors for one
connection is 1000. The value can be changed using the parameter Srv.MaxOpenCursors=n.
14532 Server Error Internal error: cursor synchronization between client and server failed. Contact technical
support for more information.
Server Error
14533 Operation cancelled

Operation was cancelled because client application called ODBC or JDBC cancel function.

Appendix E. Error codes 263

Table 70. solidDB server errors (continued)
Class Type
Code Description
Server Error Only administrative statements are allowed.
14534
Only administrative statements are allowed for the connection.

You get this error when the solidDB process size has exceeded the limit set with parameter
Srv.ProcessMemoryLimit. Only ADMIN COMMANDs are allowed so that you can increase
the process size limit.

Increase the value of Srv.ProcessMemoryLimit or disable the process memory size checking
by setting Srv.ProcessMemoryCheckInterval to 0.
Tip: You can modify the Srv.ProcessMemoryLimit and Srv.ProcessMemoryCheckInterval
parameters dynamically with ADMIN COMMAND 'parameter'.
14535 Server Error Server is already a primary server.

Meaning: The server you are trying to switch to Primary is already in one of the PRIMARY
states.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby switch primary'
14536 Server Error Server is already a secondary server.

Meaning: The server you are trying to switch to Secondary is already in one of the
SECONDARY states.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby switch secondary'
14537 Server Error HotStandby connection is broken.

Meaning: This command is returned from both the Primary and Secondary server.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby status connect'
v ADMIN COMMAND 'hotstandby connect'

One possible cause of this problem is an incorrect Connect string in the Secondary's
solid.ini file. If the netcopy operation succeeds but the connect command fails, check the
Connect string. (Netcopy does not require the Secondary to open a separate connection to
the Primary, and thus may succeed even if the Connect string on the Secondary is wrong.)
14538 Server Error Server is not HotStandby primary server.

Meaning: To issue this command, the server must be a HotStandby Primary server.

ADMIN COMMANDs that may return this status in the result set of the command:
v ADMIN COMMAND 'hotstandby copy copy_directory'
v ADMIN COMMAND 'hotstandby netcopy'
v ADMIN COMMAND 'hotstandby connect'
v ADMIN COMMAND 'hotstandby set primary alone'
v ADMIN COMMAND 'hotstandby set standalone'

264 IBM solidDB: Administrator Guide

Table 70. solidDB server errors (continued)
Class Type
Code Description
14539 Server Error Operation Refused.

This error code is given when one of the following situations occurs:
v The user issued a netcopy command to a Primary server, but the server that should be
Secondary is not actually in a Secondary state, or is not in "netcopy listening mode". (Both
the Primary and the "Secondary" server are probably in PRIMARY ALONE state.)
To solve the problem, restart the "Secondary" with the -x backupserver command-line
option, then try again to issue the netcopy command to the Primary.
Attention: If both servers were in PRIMARY ALONE state, and if both servers executed
transactions while those servers were in PRIMARY ALONE state, then they probably each
have data that the other one does not. This is a serious error, and doing a netcopy to put
them back in sync would result in writing over some transactions that have already been
committed in the "Secondary" server.
v This message can be generated when you use a callback function and the callback
function refuses to shut down or accept a backup or netcopy command.
When you use linked library access, you can provide "callback" functions by using the
SSCSetNotifier function. Your callback functions will be notified when the server has been
commanded to shut down or to do a netcopy operation. If for some reason your
application doesn't want the command to be followed, then your callback can return a
value that cancels the command. In this situation, you will see error 14539.
To solve the problem, wait until the client code finishes the operation that it does not
want to interrupt, then retry the command (for example, the shutdown or netcopy).
14540 Server Error Server is already a non-HotStandby server.
14541 Server Error HotStandby configuration in solid.ini conflicts with ADMIN COMMAND 'HSB SET STANDALONE'.
14542 Server Error Server in backupserver mode. Operation refused.
14543 Server Error Invalid command. The database is a HotStandby database but, HotStandby section not
found in solid.ini configuration file.
14544 Server Error Operation failed. This command is not supported on diskless server.
14545 Server Error Primary can only be set to primary alone when its role is primary broken.
14546 Server Error Switch failed. The server or the remote server cannot switch from primary alone to
secondary server. Catchup should be done first before switch.

Meaning: This command is returned when a state switch to SECONDARY is executed from a
local or remote Primary server that is in the PRIMARY ALONE state and it is detected that
the Primary and Secondary server are not in sync. You must connect the Primary server to
the Secondary server and wait for the catchup process to complete before switching the
Secondary to the Primary.

HotStandby commands that return this error:

v ADMIN COMMAND 'hotstandby switch secondary'
14547 Server Error The value for the -R option (Read Timeout) was missing or invalid.
14548 Server Error Switch failed. The server in Standalone cannot be switched to a secondary.

Meaning: This command is returned when a state switch to SECONDARY is executed from a
local or remote Primary server that is in the STANDALONE state and it is detected that the
Primary and Secondary server are not in sync. You must connect the Primary server to the
Secondary server and wait for the catchup to complete before switching the Secondary to the
Primary.

HotStandby commands that return this error:

v ADMIN COMMAND 'hotstandby switch secondary'
14549 Server Error HotStandby transaction is active.

Meaning: If the HotStandby connection is broken, Primary server must be set to alone mode
or switched to secondary mode before shutdown.
14550 Server Error Hotstandby connect parameter can be changed only when the primary is not connected to
secondary.

Appendix E. Error codes 265

Table 70. solidDB server errors (continued)
Class Type
Code Description
14551 Server Error Maximum number of START AFTER COMMIT statements reached.
14552 Server Error Server is in backup server mode, no connections are allowed.

Error 14552 is returned when a client attempts to establish a connection to a solidDB server
which is in a backup server mode (also called netcopy listening mode). The backup server
mode is a special server mode where the solidDB instance has been started with the
command line option -xbackupserver. This mode indicates that the solidDB instance is a
Secondary server that is either waiting for or in the process of receiving the database file
from the Primary server due to a netcopy command issued at the Primary server.
Server Error
14553 Backup process is not active

This error is given if ADMIN COMMAND 'abort backup' is issued and no backup is active.
Server Error
14554 The server does not support the required Transparent Failover level.

Reserved for future. This error will be reported when the server does not implement the
Transparent Failover (TF) level requested by the application. Currently, there is only one
level.
Server Error
14555 Netbackup: Conflicting usage of backup directory %s.
Server Error
14556 Netbackup: No server connection string specified.
Server Error
14557 Netbackup: A server configured for HotStandby cannot act as a netbackup server.
14558 Server Error Operation not allowed when delete capture is off.
14570 Server Error XID not found.
14571 Server Error XID has not been prepared. Cannot execute two phase commit.
14572 Server Error XID has been prepared. Cannot execute one phase commit.
14600 Server Error Command is ambiguous in cluster session.
14706 Server Error Invalid read thread mode for HotStandby, only mode 2 is supported.
30135 Server Fatal Error SMA application has failed while processing the solidDB server code. Server cannot continue
and is executing emergency shutdown.

solidDB procedure errors

Code Class Type Description

23001 Procedure Error Undefined symbol symbol
Procedure Error
23002 Undefined cursor cursor.

You have used a cursor that has not been defined in a procedure definition.
Procedure Error
23003 Illegal SQL operation operation.
Procedure Error
23004 Syntax error: parse error, line line number.

Check the syntax of your procedure.

Procedure Error
23005 Procedure procedure not found.
Procedure Error
23006 Wrong number of parameters for procedure procedure.

266 IBM solidDB: Administrator Guide

Code Class Type Description
Procedure Error Procedure name value conflicts with an existing entity.
23007
Choose a unique name for a procedure. The specified name is already used.
Procedure Error
23010 Incompatible event event parameter type, line line number.
Procedure Error
23011 Wrong number of parameter for event event, line line number.
Procedure Error
23012 Duplicate wait for event event, line line number.
Procedure Error
23013 Undefined sequence sequence.
Procedure Error
23014 Duplicate sequence name sequence.
Procedure Error
23015 Sequence sequence not found.
Procedure Error
23016 Incompatible variable type in call to sequence sequence, line line number.
Procedure Error
23017 Duplicate symbol symbol.

You have duplicate definitions for a symbol.

Procedure Error
23018 Procedure owner owner not found.
Procedure Error
23019 Duplicate cursor name 'cursor'
Procedure Error
23020 Illegal option option for WHENEVER SQLERROR ... statement.
Procedure Error
23021 RETURN ROW not allowed in procedure with no return type, line line number.
Procedure Error
23022 SQL String variable variable must be of character data type, line line number.
Procedure Error
23023 Call syntax error: syntax, line line number.
Procedure Error
23024 Trigger trigger_name not found.

Trigger name not found.

Procedure Error
23025 Trigger name trigger_name conflicts with an existing entity.

Trigger name conflicts with some other database object. Triggers share the same name
space, as for example, in table and procedures.
Procedure Error
23026 Variable variable is of character type, line line number.

A CHAR or WCHAR variable is required for the operations like RETURN SQLERROR
variable.
Procedure Error
23027 Duplicate reference to column column_name in trigger definition.

One column can be referenced only once in the trigger definition.

Procedure Error
23028 Commit and rollback are not allowed in triggers.

Trigger body may not contain commit or rollback statements.

Procedure Error
23029 Commit and rollback are not allowed in functions.

Appendix E. Error codes 267

Code Class Type Description
Procedure Error
23030 Function function_name not found
Procedure Error
23501 Cursor cursor is not open.
Procedure Error
23502 Illegal number of columns in EXECUTE ... procedure in cursor cursor.

You will see this message if the number of columns that you selected does not match
the number of variables in the INTO clause.
Procedure Error
23503 Previous SQL operation operation failed in cursor cursor.
Procedure Error
23504 Cursor cursor is not executed.
Procedure Error
23505 Cursor cursor is not a SELECT statement.
Procedure Error
23506 End of table in cursor cursor.
Procedure Error
23508 Illegal assignment, line line number.
Procedure Error
23509 In procedure line line number Stmt statement was not in error state in RETURN
SQLERROR OF ...
Procedure Error
23510 In procedure line line number Transaction cannot be set read only, because it has written
already.
Procedure Error
23511 In procedure line line number USING part is missing for dynamic parameters for
procedure.
Procedure Error
23512 In procedure line line number USING list is too short for procedure.
Procedure Error
23513 In procedure line line number Comparison between incompatible types data type and data
type.
Procedure Error
23514 In procedure line line number type data type is illegal for logical expression.
Procedure Error
23515 In procedure line line number assignment of parameter parameter in list list failed.

One possible cause of this error is trying to bind a parameter in a prepared statement
that has a clause like "...? IS NULL...". To work around this problem, we recommend
that you cast the placeholder (the question mark) to the appropriate data type. For
example, if you are binding a parameter of type TIMESTAMP, then replace
WHEN ? IS NULL

with
WHEN CAST(? AS TIMESTAMP) IS NULL
Procedure Error
23516 In CALL procedure, assignment of parameter parameter failed.
23517 Procedure Error Internal error: illegal operation code in procedure. Contact technical support for more
information.
Procedure Error
23518 User error: error_text

User generated error in a procedure or trigger. User can generate this error by using a
statement RETURN SQLERROR string or RETURN SQLERROR variable. Variable must
be of CHAR or WCHAR type.

268 IBM solidDB: Administrator Guide

Code Class Type Description
Procedure Error
23519 Fetch previous is not supported for procedures.

Fetch previous row does not work for result sets returned by a procedure.
Procedure Error
23520 Invalid link name given in remote procedure call.
Procedure Error
23521 Link name not given in remote procedure call.
Procedure Error
23522 Dynamic parameters not allowed with remote procedure call.
Procedure Error
23523 Default node not defined.
Procedure Error
23524 Could not load application.
Procedure Error
23525 Function not found from the DLL.
Procedure Error
23526 In CALL <procedure_name> assignment of default value of parameter
<parameter_number> failed.

This error message occurs if you call a procedure with too few parameters and you
have not specified default values for the missing parameters.
Procedure Error
23527 In CALL <procedure_name> parameter <parameter_number> assigned twice.

This occurs if you specify the same parameter more than once.
Procedure Error
23528 Application is already running.
Procedure Error
23529 Application is not running.

solidDB API errors

Table 71. solidDB SA API errors

Code Class Type Description

15001 API Error Syntax error: <error>, <line>.
15002 API Error Illegal column name <name>.
15003 API Error Too many parameters for string constraints.
15004 API Error Too few parameters for string constraints.

solidDB sorter errors

Table 72. solidDB sorter errors

Code Class Type Description

Sorter Error
24001 Sort failed due to insufficient configured TmpDir space
Sorter Error
24002 Sort failed due to insufficient physical TmpDir space
Sorter Error
24003 Sort failed due to insufficient sort buffer space
Sorter Error
24004 Sort failed due to too long row (internal failure)

Appendix E. Error codes 269

Table 72. solidDB sorter errors (continued)

Code Class Type Description

Sorter Error
24005 Sort failed due to I/O error
Sorter Error
30803 Illegal value specified for parameter: <parameter>=<value>(legal range is <value>)
Sorter Error
30804 Sorter temporary directory: <value> does not exist

solidDB RPC errors and messages

Table 73. solidDB RPC errors and messages

Code Class Type Description

RPC Error
21500 Illegal Ping RPC sequence number. A message was either lost or duplicated.
RPC Error
21501 Corrupted Ping message.
RPC Error
21502 Incomplete Ping message. Part of the data was lost.
RPC Error
21503 Extra bytes in Ping message or header corrupted.
RPC Error
21504 Requested Ping level is not currently allowed in server. Start listening with -p<ping
level> option.
RPC Error
21505 Illegal Ping buffer size or message corrupted.
RPC Error
21506 Ping session was disconnected abnormally because of a communication error.
21507 RPC Return Code Ping test <ping level> successful. Results are in file <filename>.
RPC Error
21508 Ping feature is not supported in the server. Update your server.
RPC Error
21509 Failed to write to file <file_name>.
RPC Error
21510 Failed to read from file <file_name>.
30600 RPC Message Received an illegal freearray size <value>
30601 RPC Message Received an illegal attribute count <value> routine <value>
30602 RPC Message Received an illegal relop <value> routine <value>
30603 RPC Message Received an illegal table name <value> routine <value>
30604 RPC Message Received an illegal selflags size <value> routine <value>
30605 RPC Message Current cursor id <value> found from free array
30606 RPC Message Illegal cursor id <value> found from free array
30607 RPC Message Received an illegal user id <value>
30608 RPC Message Received an illegal connect id <value>
30609 RPC Message Received an illegal sequence number <value> expected <value>
30610 RPC Message Received an illegal cursor id <value>
30611 RPC Message Illegal attribute id <value> in order list
30612 RPC Message Illegal attribute id <value> in constraint list
30613 RPC Message Illegal attribute id <value> in select list
30614 RPC Message Received an illegal length parameter <value> routine <value>

270 IBM solidDB: Administrator Guide

Table 73. solidDB RPC errors and messages (continued)

Code Class Type Description

30615 RPC Message Received an illegal attribute number parameter routine <value> nattrs <value>
30616 RPC Message Cannot send UNICODE string to old client version
30617 RPC Message Received an illegal type number routine <value> types <value>
30618 RPC Message Received an illegal date attribute from Java client routine <value>
30619 RPC Message Received an illegal attribute type parameter routine <value> type <value>
30620 RPC Message Received a corrupted data tuple routine <value> row length mismatch
30621 RPC Message Received an illegal SQL cursor sync array size <value>
30622 RPC Message Received an illegal SQL cursor id <value>in sync array
30623 RPC Message Illegal RPC console information
30624 RPC Message Illegal RPC session
30625 RPC Message Received an illegal done array size <value>
30626 RPC Message Received an illegal SQL statement id <value> routine <value>
30627 RPC Message Received an illegal SQL statement id <value> pos <value> routine <value>
30628 RPC Message Received an illegal read BLOB id <value> routine <value>
30629 RPC Message Received an illegal SQL read BLOB buffer size <value> routine <value>
30630 RPC Message BLOB data crc failed block count = <value> routine <value>
30631 RPC Message Received an illegal BLOB id <value> routine <value>
30632 RPC Message Received an illegal BLOB piece length <value> routine <value>
30633 RPC Message Received an illegal data length routine <value> length <value>
30634 RPC Message Illegal tuple position <value>
30635 RPC Message Hot Standby received an illegal counter data size <value> from another server
30636 RPC Message Received an illegal replication type parameter <value>
30637 RPC Message Ping client from <value> connected
30638 RPC Message Ping client from <value> disconnected
30639 RPC Message Received an illegal cursor id <value>
30640 RPC Message <Server RPC error message>

solidDB synchronization errors

Table 74. solidDB synchronization errors

Code Class Type Description

Synchronization Error
25001 Master cannot save propagated statements.

The master received propagated transaction statements from the replica,

but is not able to save the statements. (Note that the master must save the
statements before executing them). Possible causes of the error are:
v Master database has exceeded the database size limit. You can increase
the database size by changing the FileSpec parameter setting in the
solid.ini file. For details on this parameter, read “FileSpec_[1...n]
parameter” on page 53. Be sure to restart the server for the new setting
to take effect.
v An internal error exists in the database server. If error 25001 occurs
even after you have increased the database size, contact IBM
Corporation Technical support at http://www.ibm.com/software/data/
soliddb/support/.
Synchronization Error
25002 Cannot save data dictionary statements.

Appendix E. Error codes 271

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25003 Cannot save SAVE statements.

It is not possible to save a "SAVE" statement for later propagation. For

example, the following SQL statement returns an error:
SAVE CALL MYPROC(1, ’foo’)

solidDB statements that return this error:

SAVE sql_statement

Synchronization Error
25004 Dynamic parameters are not supported.

Input parameters of a subscription must be given as literals. They cannot

be dynamically bound to the statement.

solidDB statements that return this error:

DROP SUBSCRIPTION
MESSAGE message_name APPEND REFRESH publication_name

Synchronization Error
25005 Message message_name is already active.

A message of the specified name that was created appears to still be

active. A message becomes active when the following MESSAGE
command is executed:
MESSAGE message_name BEGIN

The message is automatically deleted when the reply of the message has
been successfully executed in the replica database.

solidDB statements that return this error:

MESSAGE message_name APPEND
MESSAGE message_name BEGIN
MESSAGE message_name DELETE
MESSAGE message_name EXECUTE
MESSAGE message_name FORWARD
MESSAGE GET REPLY

Synchronization Error
25006 Message message_name not active

A message has already been committed or ended using the MESSAGE

END statement. New tasks cannot be appended to the message using the
MESSAGE APPEND command. Probable cause for this error is that the
AUTOCOMMIT mode is used in the connection.

You must first remove the message with MESSAGE message_name DELETE
command. Then switch autocommit off and run the script again.

solidDB statements that return this error:

MESSAGE message_name APPEND synchronization_task

272 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25007 Master master_name not found

A replica attempts to perform an operation to a master database that

cannot be found.

solidDB statements that return this error:

SET SYNC CONNECT connect_string TO MASTER master_name
DROP MASTER master_name
IMPORT ’filename’
SAVE sql_statement

Synchronization Error
25009 Replica replica_name not found

The replica name specified in a command cannot be found.

solidDB statements that return this error:

DROP REPLICA replica_name
DROP SUBSCRIPTION publication_name(parameter_list)
[FROM REPLICA replica_name]
GRANT REFRESH ON publication_name
MESSAGE DELETE CURRENT TRANSACTION
MESSAGE message_name [FROM REPLICA replica_name] DELETE

Synchronization Error
25010 Publication publication_name not found.

The publication name of a subscription is incorrect.

solidDB statements that return this error:

MESSAGE APPEND REFRESH publication_name(parameter_list)
DROP PUBLICATION publication_name
EXPORT SUBSCRIPTION publication_name ...
REVOKE REFRESH ON publication_name...

Synchronization Error
25011 Wrong number of parameters to publication publication_name.

A subscription to a publication contains incorrect number of parameters.

The data types of the given subscription parameters must match the input
parameter definition of the publication.

solidDB statements that return this error:

DROP SUBSCRIPTION publication_name (parameter_list)
[FROM REPLICA replica_name]
MESSAGE message_name APPEND REFRESH
publication_name (parameter_list)

Synchronization Error
25012 Message reply timed out.

A reply message has not arrived to the replica database within the given
timeout period. The reason is that the reply message is not yet ready in
the master database. The message needs to be retrieved later using
"MESSAGE message_name GET REPLY" command.

solidDB statements that return this error:

MESSAGE message_name FORWARD TIMEOUT timeout_in_seconds
MESSAGE message_name GET REPLY TIMEOUT timeout_in_seconds

Appendix E. Error codes 273

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25013 Message name message_name not found.

The message with the given name does not exist. The message name is
given when the message is created with command MESSAGE
message_name BEGIN. The message name is released when the reply
message has been successfully executed in the replica database.

Message names must be unique within the replica database.

A message can be deleted from the database with command:

MESSAGE message_name [FROM REPLICA replica_name ] DELETE

solidDB statements that return this error:

MESSAGE message_name APPEND
MESSAGE message_name DELETE
MESSAGE message_name END
MESSAGE message_name EXECUTE
MESSAGE message_name FORWARD
MESSAGE message_name FROM REPLICA EXECUTE
MESSAGE message_name FROM REPLICA
replica_name DELETE CURRENT TRANSACTION
MESSAGE message_name GET REPLY
Synchronization Error
25014 More than one master name found.
Synchronization Error
25015 Syntax error: error_message, line line_number

Syntax is not correct.

solidDB statements that return this error:

MESSAGE message_name APPEND
CREATE PUBLICATION publication_name

Note: See the CREATE PUBLICATION syntax reference for correct syntax.
Synchronization Error
25016 Message not found, replica id replica_id, message id message_id

Message not found in master during processing. This can happen if the
message is explicitly deleted in master.

solidDB statements that return this error:

MESSAGE message_name FORWARD
MESSAGE message_name GET REPLY
MESSAGE message_name RESTART

Synchronization Error
25017 No unique key found for table table_name.

The primary key for the table has not been defined.

Each table that is part of an incremental publication must have a primary

key defined. The synchronization history mechanism cannot function
without explicitly defined primary keys.

solidDB statements that return this error:

ALTER TABLE table_name SET SYNCHISTORY

274 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25018 Illegal message state.

An internal error has occurred in the message processing. It is not possible

to continue executing the message after this error. Delete the message
using the following command:
MESSAGE message_name [FROM REPLICA replica_name ] DELETE

solidDB statements that return this error:

MESSAGE message_name ...

Synchronization Error
25019 Database is not a replica.

A synchronization message can only be created in a database that has

been registered to be a replica database. See the example code in IBM
solidDB Advanced Replication User Guide, which provides information about
registering a replica database.

solidDB statements that return this error:

DROP MASTER master_name
DROP PUBLICATION publication_name REGISTRATION
DROP SUBSCRIPTION publication_name ...
IMPORT ’filename’
MESSAGE message_name BEGIN
MESSAGE message_name ENDSET SYNC CONNECT
’connect_string’ TO MASTER master_name
Synchronization Error
25020 Database is not a master.

A command that can be executed only in a master database has been

attempted to execute in a non-master database.

A database can be set to be a master database of a system by entering the

following command:
SET SYNC MASTER YES

solidDB statements that return this error:

ALTER USER replica_user SET MASTER master_name USER
MESSAGE message_name FROM REPLICA replica_name RESTART
MESSAGE message_name FROM REPLICA replica_name DELETE
DROP REPLICA replica_name DROP SUBSCRIPTION
subscription_name FROM REPLICA replica_name

Synchronization Error
25021 Database is not master or replica database.

In order to create or drop publication definitions or set the

SYNCHISTORY property of a table, the database must be defined to be
either master or replica (or both).

solidDB statements that return this error:

CREATE PUBLICATION publication_name ...
DROP PUBLICATION publication_name REGISTRATION
SET SYNC MAINTENANCE MODE ...;
ALTER TABLE table_name SET SYNCHISTORY

Appendix E. Error codes 275

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25022 User generated error.

The execution of a transaction has been cancelled and rolled back in the
master database. Because of the failed transaction, the execution of the
message that contained the transaction has been stopped.

User can request solidDB to roll back a transaction by setting the

following parameters to the bulletin board of the transaction:
PutParam(’SYS_ROLLBACK’, ’YES’)
PutParam(’SYS_ERROR_CODE’, numeric_value_as_string)
PutParam(’SYS_ERROR_TEXT’, error_text_as_string)

If the SYS_ERROR_CODE parameter is not specified or it contains an

invalid value, the error number 25022 is returned.

solidDB statements that return this error:

MESSAGE message_name FORWARD TIMEOUT timeout_in_seconds
MESSAGE message_name GET REPLY TIMEOUT timeout_in_seconds

Synchronization Error
25023 Replica registration failed.

An error has occurred during replica registration.

solidDB statements that return this error:

MESSAGE message_name FORWARD TIMEOUT timeout_in_seconds
MESSAGE message_name GET REPLY TIMEOUT timeout_in_seconds

Synchronization Error
25024 Master not defined.

No definition for the master exists or the configuration changed during

message processing. solidDB was unable to properly initialize the
synchronization environment. You can check the master from the replica's
system table SYS_SYNC_MASTERS. All successfully registered replicas are
found from the master database system table SYS_SYNC_REPLICAS.

Note that this error can be produced if you use double quotes rather than
single quotes around the master_connect_string in a MESSAGE FORWARD
command. solidDB statements that return this error:
IMPORT ’filename’
MESSAGE message_name FORWARD TO ’master_connect_string’
TIMEOUT timeout_in_seconds

Note: The use of double quotes rather than single quotes around the
master_connect_string in can produce this error message.
MESSAGE message_name GET REPLY ...
MESSAGE message_name APPEND REFRESH publication_name
MESSAGE message_name EXECUTE ....

276 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25025 Node name not defined.

Before setting up a master database or registering a replica database, the

node name of the database must be set. This can be done with the
following command:
SET SYNC NODE node_name

solidDB statements that return this error:

DROP PUBLICATION publication_name REGISTRATION
MESSAGE message_name APPEND REGISTER REPLICA
MESSAGE message_name BEGIN ...

Synchronization Error
25026 A user who has not been defined in the master database, attempts to
perform a solidDB SQL command.

solidDB statements that return this error:

IMPORT ’filename’
SAVE sql_statement
MESSAGE message_name...

To resolve this problem, use the correct user ID if there is one. If there is
not already a correct user ID, then you have two options:

1) Map a master user to the replica userid you are using. (The master user
must already have been downloaded from the master to the replica.) To
map a master user to a replica user, execute the command:
ALTER USER replica_user SET MASTER master_name
USER user_specification

2) Add an appropriate user to the master database, and download it with:

MESSAGE message_name APPEND SYNC_CONFIG

Synchronization Error
25027 Too long column or parameter value; configured maximum is <value>
Synchronization Error
25028 Message message_name can include only one system subscription.

System subscriptions (REGISTER REPLICA and SYNC_CONFIG) must be

kept in separate messages. These tasks must be the only ones of their
messages.

solidDB statements that return this error:

MESSAGE message_name APPEND REFRESH publication_name
Synchronization Error
25030 Replica replica_name is already registered.

A replica attempts to register itself using a name that is already in use.

Replica names must be unique. If you know that the chosen replica name
is no longer used by any other replicas, drop it from the master database
with the command DROP REPLICA replica_name. Then register the
replica again. Otherwise, change the newly created replica's name and
register it again. Note that replica registration occurs after the registration
message is sent to the master.

solidDB statements that return this error:

MESSAGE message_name FORWARD ...
MESSAGE message_name GET REPLY ...

Appendix E. Error codes 277

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25031 Transaction is active, operation failed.

A replica attempts to process a message when having an active

transaction.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name FORWARD ...
MESSAGE message_name GET REPLY TIMEOUT ...
MESSAGE message_name EXECUTE

Synchronization Error
25032 All publication SQL statements must return rows.

The publication definition contains SQL operations that do not return

rows. Only SELECT statements are allowed in the publication.

solidDB statements that return this error:

CREATE PUBLICATION publication_name

Synchronization Error
25033 Publication publication_name already exists.

A publication has been attempted to create with a name that is already in

use.

solidDB statements that return this error:

CREATE PUBLICATION publication_name

Synchronization Error
25034 Message name message_name already exists.

Each message must have a name that is unique within the database.

solidDB statements that return this error:

MESSAGE message_name BEGIN

Synchronization Error
25035 Message message_name is in use.

A solidDB message is locked during an attempt to execute it or delete it.

A locked message cannot be re-executed or deleted. If you get this error
while attempting to create a new solidDB message, it is probably due to
an existing message with the same name. You can check existing messages
from the system table SYS_SYNC_REPLICA_MSGINFO in the replica or
from the system table SYS_SYNC_MASTER_MSGINFO in the master
database.

solidDB statements that return this error:

MESSAGE message_name BEGIN
MESSAGE message_name END
MESSAGE message_name EXECUTE ...
MESSAGE message_name FROM REPLICA replica_name DELETE
MESSAGE message_name FORWARD TIMEOUT ...
MESSAGE message_name GET REPLY TIMEOUT ...

278 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25036 Publication publication_name not found or publication version mismatch.

A publication has been dropped or redefined at master during message

processing. Recover by DROP SUBSCRIPTION at replica.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name FORWARD TIMEOUT ...
MESSAGE message_name GET REPLY TIMEOUT ...
MESSAGE message_name EXECUTE ...

Synchronization Error
25037 Publication column count mismatch in table table_name.

Database definitions at master and replica do not match.

solidDB statements that return this error:

MESSAGE message_name FORWARD TIMEOUT timeout_in_seconds
MESSAGE message_name GET REPLY TIMEOUT timeout_in_seconds
MESSAGE message_name EXECUTE

Synchronization Error
25038 Table is referenced in publication publication_name; drop or alter operations
are not allowed.

A table which is referenced in a publication can not be dropped or altered.

solidDB statements that return this error:

DROP TABLE table_name
ALTER TABLE table_name

Synchronization Error
25039 Table is referenced in subscription to publication publication_name; drop or
alter operations are not allowed.

solidDB statements that return this error:

ALTER TABLE table_name

Synchronization Error
25040 User id user_id is not found.

User information has been changed at the replica during message

execution.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name GET REPLY TIMEOUT timeout_in_seconds
MESSAGE message_name EXECUTE ...
MESSAGE message_name FORWARD ...

Appendix E. Error codes 279

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25041 Subscription to publication publication_name not found.

The subscription that is expected to be in the replica is not found. This

error occurs if the subscription is explicitly dropped at the replica.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name EXECUTE ...
MESSAGE message_name FORWARD ...
MESSAGE message_name GET REPLY ...
DROP SUBSCRIPTION subscription_name
DROP SUBSCRIPTION subscription_name REPLICA replica_name

Synchronization Error
25042 Message is too long (number bytes) to forward. Maximum is set to number
bytes.

The length of a message to be forwarded exceeds the limit for message's

length. The limit can be set by variable SYS_R_MAXBYTES_OUT.

solidDB statements that return this error:

MESSAGE message_name FORWARD

Synchronization Error
25043 Reply message is too long (number bytes). Maximum is set to number
bytes.

The length of a message to be received as a reply exceeds the limit for

message's length. The limit can be set by variable SYS_R_MAXBYTES_IN.

solidDB statements that return this error:

MESSAGE message_name GET REPLY

Synchronization Error
25044 SYNC_CONFIG system publication takes only character arguments.

In a subscription attempt, publication SYNC_CONFIG was found to have

invalid data types for the arguments.

solidDB statements that return this error:

MESSAGE message_name APPEND REFRESH SYNC_CONFIG

Synchronization Error
25045 Master/replica node support disabled.
Synchronization Error
25046 Commit and rollback are not supported in propagated transactions.

This error is caused when a transaction attempts to execute a COMMIT or

ROLLBACK command in the master database. The error is returned to the
solidDB server running the procedure. The message containing the
procedure will fail.
Synchronization Error
25047 Parameter info publication not found.

280 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25048 Publication publication_name request info not found.

A publication has been dropped while message is being executed.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name EXECUTE ...
MESSAGE message_name FORWARD ...
MESSAGE message_name GET REPLY ...

Synchronization Error
25049 Referenced table table_name not found in subscription hierarchy.

A publication has referenced a table which does not exist.

solidDB statements that return this error:

CREATE PUBLICATION publication_name ...

Synchronization Error
25050 Table has no history.
Synchronization Error
25051 Unfinished messages found.

Replica mode has been attempted to be switched off while there are
messages either waiting to be forwarded or being executed at master.

solidDB statements that return this error:

SET SYNC REPLICA NO

Synchronization Error
25052 Failed to set node name to node_name.

The node_name may be invalid.

Synchronization Error
25053 Replica not registered in master.
Synchronization Error
25054 Table table_name is not set for synchronization history.

A table in the master database has the SYNCHISTORY property set, but
the corresponding table in the replica does not.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name GET REPLY ...
MESSAGE message_name FORWARD ...

Synchronization Error
25055 Connect information is allowed only when not registered.

The connect info in MESSAGE message_name FORWARD TO connect_info

options is allowed only if the replica has not yet been registered to the
master database.

solidDB statements that return this error:

MESSAGE message_name FORWARD TO connect_info options

Appendix E. Error codes 281

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25056 Autocommit not allowed.

The solidDB statement must be executed with autocommit mode turned

off.

solidDB statements that return this error:

All MESSAGE message_name ... statements
DROP SUBSCRIPTION subscription_name
DROP SUBSCRIPTION subscription_name REPLICA replica_name
DROP REPLICA replica_name
DROP MASTER master_name
EXPORT SUBSCRIPTION
IMPORT ’filename’

Synchronization Error
25057 Already registered to master master_name.

The replica database has already been registered to a master database.

solidDB statements that return this error:

MESSAGE message_name GET REPLY ...
(when registering a replica)
MESSAGE message_name FORWARD ...
(when registering a replica)

Synchronization Error
25058 Missing connect information.
Synchronization Error
25059 After registration nodename cannot be changed.

The SYNC NODE NAME property of a database cannot be changed if the

master has any registered replicas or replica has already been registered to
a master database.

solidDB statements that return this error:

SET SYNC NODE NAME unique_node_name

Synchronization Error
25060 Column column_name does not exist on publication publication_name
resultset in table table_name.

This error occurs when a replica finds out that the master is transferring
data that does not include primary key values that the replica requires.

solidDB statements that return this error:

IMPORT ’filename’
MESSAGE message_name GET REPLY ...
MESSAGE message_name FORWARD ...

Synchronization Error
25061 Where condition for table table_name must refer to an outer table of the
publication.

If a publication contains nested SELECTs, the WHERE clause of the inner

SELECT must refer to the outer table of the outer SELECT.

solidDB statements that return this error:

CREATE PUBLICATION publication_name

282 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25062 User user_id is not mapped to master user_id.

Dropping the user mapping failed because user is not mapped to a given
master.

solidDB statements that return this error:

ALTER USER replica_user SET MASTER master_name USER

Synchronization Error
25063 User user_id is already mapped to master user_id.

User is already mapped to a given master.

solidDB statements that return this error:

ALTER USER replica_user SET MASTER master_name USER

Synchronization Error
25064 Unfinished message message_name found for replica replica_name.

Dropping the replica failed because there are unfinished messages.

solidDB statements that return this error:

DROP REPLICA replica_name

Synchronization Error
25065 Unfinished message message_name found for master master_name.

Dropping the master failed because there are unfinished messages.

solidDB statements that return this error:

DROP MASTER master_name

Synchronization Error
25066 Synchronization bookmark bookmark_name already exists.

Cannot create synchronization bookmark since the name already exists.

solidDB statements that return this error:

CREATE SYNC BOOKMARK

Synchronization Error
25067 Synchronization bookmark bookmark_name not found.

Bookmark name is not an existing bookmark.

solidDB statements that return this error:

DROP SYNC BOOKMARK

Synchronization Error
25068 Export file file_name open failure.

Failed to open export file for EXPORT SUBSCRIPTION.

solidDB statements that return this error:

EXPORT SUBSCRIPTION

Appendix E. Error codes 283

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25069 Import file file_name open failure.

Failed to open import file for IMPORT.

solidDB statements that return this error:

IMPORT ’filename’

Synchronization Error
25070 Statements can be saved only for one master in transaction.

Statements cannot be saved for multiple masters in one transaction.

solidDB statements that return this error:

SAVE sql_statement

Synchronization Error
25071 Not registered to publication publication_name.

Replica must be registered to a publication before the publication can be

refreshed to the replica.

solidDB statements that return this error:

DROP PUBLICATION publication_name REGISTRATION
MESSAGE message_name APPEND REFRESH publication_name

Synchronization Error
25072 Already registered to publication publication_name.

Replica is already registered to a publication.

solidDB statements that return this error:

MESSAGE message_name APPEND REGISTER REPLICA

Synchronization Error
25073 Export file can have data only from one master.
Synchronization Error
25074 User definition not allowed for this operation.

Master user attempts to perform synchronization operation, but is denied

access in the replica database because the registration user is still the
active user. After the registration process, the command SET SYNC
username must be set to NONE.

solidDB statements that return this error:

SAVE sql_statement
DROP SUBSCRIPTION publication_name (in replica)
MESSAGE message_name APPEND REFRESH publication_name
MESSAGE message_name APPEND PROPAGATE TRANSACTIONS
MESSAGE message_name APPEND REGISTER PUBLICATION
MESSAGE message_name APPEND UNREGISTER PUBLICATION
MESSAGE message_name EXECUTE (in replica)

Synchronization Error
25075 Transaction not found.
Synchronization Error
25076 Only REGISTER REPLICA is allowed in message.
Synchronization Error
25077 Node name is not valid.
Synchronization Error
25078 Node name already exists.

284 IBM solidDB: Administrator Guide

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25079 Catalog is master and there are registered replicas. Catalog is not dropped.
Synchronization Error
25080 Catalog is replica and it is registered to a master. Catalog is not dropped.
Synchronization Error
25081 Subqueries are not allowed in publication definition.
Synchronization Error
25082 Node name can not be removed if node is master or replica.

Node name cannot be set to NONE on a synchronized master and/or

replica catalog.

solidDB statements that return this error:

SET SYNC NODE NONE

Synchronization Error
25083 Commit block can not be used with HotStandby.
Synchronization Error
25084 Can not save ADMIN COMMAND.
Synchronization Error
25085 Failed to store blob from message.

During synchronization, reading or storing a BLOB (LONG VARCHAR or

LONG VARBINARY data) has failed because of an internal error.
Synchronization Error
25086 Cannot save START statement.
Synchronization Error
25087 Missing connect information for node node_name.

There is no connect string in the table sys_sync_replicas for the specified

replica. Registering a replica doesn't doesn't automatically add the connect
string into that table if you haven't defined it in the replica's solid.ini.
You should define it as shown below:
[Synchronizer]
ConnectStrForMaster=tcp replicahost 1316

Synchronization Error
25088 Catalog already in maintenance mode. You have set the mode on already.
Synchronization Error
25089 Not allowed to set maintenance mode off. Someone else has set the mode
on, so you cannot set it off.
Synchronization Error
25090 Catalog already in maintenance mode. Someone else has set the mode on,
so you cannot set it off.
Synchronization Error
25091 Catalog is not in maintenance mode. You tried to set the mode off when it
was not on.
Synchronization Error
25092 User version strings are not equal in master and replica, operation failed.

When the replica executes either of the following commands:

MESSAGE FORWARD
MESSAGE GET REPLY

The server checks whether the master and replica sync schema version
numbers are equal. If the version numbers are not equal, then the server
gives this error. (Note: If neither the master nor the replica has set the
version number, then you will not get the error message.)

Appendix E. Error codes 285

Table 74. solidDB synchronization errors (continued)

Code Class Type Description

Synchronization Error
25093 A master database for this replica exists, operation failed. This message is
returned when the user either tries to drop a replica catalog which is
registered to a master, or tries to execute 'SET SYNC REPLICA NO' when
the replica is registered to a master.
Synchronization Error
25094 Received illegal message part type.
Synchronization Error
25095 Message execution aborted.

solidDB HotStandby errors

Table 75. solidDB HotStandby errors
Code Class Type Description
14700 HotStandby Error Rejected connection, both servers in PRIMARY role.

Meaning: Command 'hsb connect' returns this error if both nodes are in
same role.
14701 HotStandby Error Rejected connection, both servers in SECONDARY role.

Meaning: Command 'hsb connect' returns this error if both nodes are in
same role.
14702 HotStandby Error Operation failed, catchup is active.

Meaning: While the servers are performing catchup, you will get this error if
you issue any of the following commands on the Primary: 'hsb switch
secondary', 'hsb set secondary alone', 'hsb set standalone', 'hsb
connect', 'hsb copy' or 'hsb netcopy'.

While the servers are performing catchup, you will get this error if you issue
any of the following commands on the Secondary: 'hsb switch primary', 'hsb
set secondary alone', 'hsb set primary alone', 'hsb set standalone', or
'hsb connect'.
14703 HotStandby Error Operation failed, copy is active.

Meaning: While the Primary is doing copy or netcopy, the following

commands returns this error: 'hsb switch secondary', 'hsb set secondary
alone', 'hsb set standalone', 'hsb connect', 'hsb disconnect', 'hsb copy'
or 'hsb netcopy'.
14704 HotStandby Error HotStandby copy or netcopy is only allowed when primary is in alone state.

Meaning: This error is returned if the server is in PRIMARY ACTIVE state and
the command 'hsb copy' or 'hsb netcopy' is issued.
14705 HotStandby Error Setting to STANDALONE is not allowed in this state.

Meaning: If the server is in PRIMARY ACTIVE state and you issue the
command 'hsb set standalone', then you will get this message.
14706 HotStandby Error Invalid read thread mode for HotStandby, only mode 2 is supported.
14707 HotStandby Error Operation not allowed in the STANDALONE state.
14708 HotStandby Error Catchup failed, catchup position was not found from log files.
14709 HotStandby Error Hot Standby enabled, but connection string is not defined.
14710 HotStandby Error Hot Standby admin command conflict with an incoming admin command.
14711 HotStandby Error Failed because server is shutting down.
14712 HotStandby Error Server is secondary. Use primary server for this operation.

286 IBM solidDB: Administrator Guide

solidDB SSA (SQL API) errors
Table 76. solidDB SSA (SQL API) errors

Error code Description

SSA Error
25200 Invalid application buffer type

This error is used for the ODBC driver. It is given if signals attempt to use inappropriate buffer
type for reading values (such as reading string to integer value). This error is documented into
more detail in the ODBC specifications.
SSA Error
25201 Invalid use of null pointer

This error is given, if an invalid parameter - NULL is passed as a statement handle, connection
handle, or application buffer.
SSA Error
25202 Function sequence error

This error is given, if an attempt to violate the ODBC function call sequence is made. This can
happen, for example, when trying to execute a statement that has not been prepared.
SSA Error
25203 Invalid transaction operation code

This error is given, if an attempt to use an incorrect transaction completion code with the
SQLEndTran function (SQL_COMMIT and SQL_ROLLBACK are allowed) is made.
SSA Error
25204 Invalid string or buffer length

This error is given, if 0 or any negative buffer size is passed to an ODBC function that requires an
application buffer.
SSA Error
25205 Invalid attribute/option identifier

This error is given, if an invalid operation code is passed to the SQLSetPos, SQLDriverConnect,
SQLFreeStmt and so on.
SSA Error
25206 Connection timeout expired
SSA Error
25207 Invalid cursor state

This error is given, for example, if an attempt is made to fetch with a closed cursor.
SSA Error
25208 String data, right truncated

This error is given if a string buffer was not big enough.

SSA Error
25209 Datetime field overflow

This error is given when updating a date or time column with incorrect data.
SSA Error
25210 COUNT field incorrect

This error is given, for example, when trying to pass an extra parameter to an insert statement.
SSA Error
25211 Invalid descriptor index

This error is given, for example, when using 0 or negative value as SQLBindParameter column
index.
SSA Error
25212 Client unable to establish a connection

The ODBC client cannot connect to the server.

Appendix E. Error codes 287

Table 76. solidDB SSA (SQL API) errors (continued)

Error code Description

SSA Error
25213 Connection name in use

This error is given, for example, when trying to reconnect an already connected connection.
SSA Error
25214 Connection does not exist

This error is given, for example, when trying to use a closed or not connected connection.
SSA Error
25215 Server rejected the connection

Transport layer connection to the server has been established, but the server rejects the connection
(for example, because it is shutting down).
SSA Error
25216 Connection switch, some session context may be lost

This is a TF-1 specific error. A TF-1 connection has encountered a connection switch. The
application must roll back the transaction to restore the connection.
SSA Error
25217 Client unable to establish a primary connection

This is a TF-1 specific error. The ODBC driver has not been able to establish connection to the
primary server, for example, after an application rolled back a transaction after a failover, or if
there is no primary server address in the TF-1 connection string (all the reachable servers are
secondary).
25404 SSA Error COUNT field incorrect
25406 SSA Error Invalid descriptor index
25411 SSA Error String data
25416 SSA Error Datetime field overflow
25418 SSA Error Invalid cursor state
25424 SSA Error Invalid application buffer type
25427 SSA Error Invalid use of null pointer
25428 SSA Error Function sequence error
25429 SSA Error Invalid transaction operation code
25432 SSA Error Invalid string or buffer length
25434 SSA Error Invalid attribute/option identifier
25448 SSA Error Connection timeout expired

solidDB COM (communication) messages

Table 77. solidDB COM (communication) messages

Code Class Type Description

30001 COM Message User <username> connected, user id <id>, machine id <id>
30002 COM Message User <username> connection timed out, user id <id>, machine id <id>
30003 COM Message User <username> was disconnected abnormally, user id <id>, machine id <id>
30004 COM Message User <username> disconnected, user id <id>, machine id <id>
30005 COM Message Admin user <username> connected, user id <id>, machine id <id>
30006 COM Message User <username> connected from a remote control, user id <id>, machine id <id>
30007 COM Message User <username> transaction idle timed out, user id , machine id <id>
30008 COM Message User <username> transaction timed out, user id %d machine id <id>

288 IBM solidDB: Administrator Guide

Table 77. solidDB COM (communication) messages (continued)

Code Class Type Description

30009 COM Message User <username> tried to connect from <value> with an illegal username or password.
User <username> failed to connect version mismatch. Client version <version>, server version
30010 COM Message <version>
30011 COM Message User <username> failed to connect, collation version mismatch.
30012 COM Message User <username> failed to connect, there are too many connected clients.
30013 COM Message New connections allowed.
30014 COM Message New connections can not be allowed.
30015 COM Message No new connections allowed.
30016 COM Message Listening of <connect string> started.
30017 COM Message Listening of <connect string> stopped.
30018 COM Message No valid listening name specified. Exiting from <server_name>.
30019 COM Message Cannot start listening
30020 COM Message Server is in fatal state no new connections are allowed
30021 COM Message Unknown connection recycling XECB.
30022 COM Message User <username> failed to connect database, character set is utf8, unsupported by client.
User <username> failed to connect, default char binding uses codepage <codepage>

Your client does not support the Unicode database mode; update the client to the same version
30023 COM Message as the server.

solidDB SRV (server) errors

Table 78. solidDB SRV errors

Code Class Type Description

30100 SRV Message Server shut down by the application.
30101 SRV Message Server shut down by either ALT+F4 or kill command
30102 SRV Message User <username> issued shut down server command, user id <username>
30103 SRV Message Server shut down by unknown user (sc==NULL)
30104 SRV Message Shutdown aborted; denied by user callback.
30105 SRV Message <server_name> is shut down
30106 SRV Message Some thread still active wait extra <value> seconds...
30110 SRV Message Service <service_name> installed
30111 SRV Message Service <service_name> removed
30112 SRV Message Install service <service_name> failed! Error code <error_code>
30113 SRV Message Remove service <service_name> failed! Error code <error_code>
30114 SRV Message Usage for service option: -s{start|install|remove} name exepath [autostart]
30115 SRV Message Failed to change the current working directory to <directory_name>
30116 SRV Message Current working directory changed to <directory_name>
30117 SRV Message <solidDB_version>
30118 SRV Message <copyright>
30119 SRV Message <startup_time>
30120 SRV Message Failed to start the server. Exiting from <value>
30121 SRV Message Causing intentionally an access violation...
30122 SRV Message Causing intentionally an internal error...
30123 SRV Message Exiting server with ADMIN COMMAND 'errorexit <number>'...

Appendix E. Error codes 289

Table 78. solidDB SRV errors (continued)

Code Class Type Description

30124 SRV Message Exiting server with ADMIN COMMAND 'assertexit'...
30125 SRV Message Admin command: <command>
30126 SRV Message Admin event: <command>
30127 SRV Message Invalid license file <license_file>
30128 SRV Message Using license file <license_file>
30129 SRV Message Signal <value>
30130 SRV Message solidDB process has encountered an internal error and is unable to continue normally.
30131 SRV Message Command line: <value>
30132 SRV Message SS_DEBUG=<value>
30133 SRV Message Asynch pingtest completed successfully to <value>.
30134 SRV Message Alternate inifile name is too long (>254); parameter ignored.
30140 SRV Message The argument following option -x pagedmem:[client:] must be 16 32 or 64 (default: 16)
30141 SRV Message Testing system performance.
30142 SRV Message Testing was successful.
30143 SRV Message Testing failed.
30144 SRV Message Server in backup server mode. Operation refused
30145 SRV Message Connect failed illegal user name or password
30146 SRV Message Failed to create thread <value>
HSB enabled server cannot operate without HotStandby license: set HotStandby.HSBEnabled
30147 SRV Message to No.
30148 SRV Message <value> option is activated.
30149 SRV Message Server emergency shutdown.
Server not started.

30150 SRV Fatal Error This error is given if the solidDB server cannot be started.
30151 SRV Message Database started.
Memory allocation size has exceeded <value>MB. Current size: <value> butes. Number of
30152 SRV Message allocations: <value>.
Memory allocation size has fallen below <value>MB. Current size: <value> bytes. Number
30153 SRV Message of allocations: <value>.
Statement (id: <userid> userid: <type> type: <value>) has allocated <value> bytes of
30154 SRV Message memory SQL: <value>.
30155 SRV Message Process size <virtual_size> is <above|below> the <warning_level|limit|low_level> <value>
30156 SRV Message Server health check monitoring started.
Parameter General.MultiprocessingLevel has been set automatically to <value>, the number
of logical CPUs detected.

As of V6.5 Fix Pack 4, the factory value of General.MultiprocessingLevel is read from the
system as the number of logical processing units. With some processor architectures, the
number of logical processing units might not be the same as the number of physical cores. In
such cases, the optimal value for this parameter typically varies between the number of the
30158 SRV Message physical cores and the number of logical processing units.

290 IBM solidDB: Administrator Guide

solidDB DBE (database engine) errors and messages
Table 79. solidDB DBE errors and messages

Code Class Type Description

30200 DBE Message Creating a new database.
30201 DBE Message Database converted successfully.
30202 DBE Message Database already exists.
30203 DBE Message Converting database ...
This database is from an older Solid version. To convert database for use with this version,
start server with option -x convert. Note that after conversion, the database cannot be used
30204 DBE Message with older versions of server anymore.
30205 DBE Message New database was not created.
Database does not exist. Cannot create a new database because the server is not running as a
foreground process. To create a new database, start the server as a foreground process with -f
30206 DBE Message option.
30207 DBE Message Failed to open the database. Exiting from server_name
30208 DBE Message Merge not started; denied by user callback.
30209 DBE Message Idle merge started value keys to remove
30210 DBE Message Merge started, value keys to remove
30211 DBE Message Idle quick merge started
30212 DBE Message Quick merge started
30213 DBE Message Merge stopped, all keys merged
30214 DBE Message Merge stopped, value keys merged
30215 DBE Message Merge task started, value tasks active
30216 DBE Message User merging enabled
30217 DBE Message Error when converting procedures procedure <procedure_name>
30218 DBE Message Quick merge stopped
30220 DBE Message Checking database index
30221 DBE Message Database index is ok
30222 DBE Message Database is in backup server mode. Cannot check the index.
30223 DBE Message Testing the database index.
30224 DBE Message Database index has been tested successfully. Database index is ok.
30225 DBE Message ERROR! Database index is NOT ok! Check errors from file ssdebug.log.
30226 DBE Message SOLID Fatal Error: Failed to open the database for testing.
30227 DBE Message SOLID Fatal Error: Failed to connect to the database for testing.
30228 DBE Message Database file has been reorganized successfully.
30229 DBE Message ERROR! Failed to reorganize the database file! Check errors from file ssdebug.log.
30230 DBE Message Starting roll-forward recovery, wait ...
30231 DBE Message Recovery of value transactions successfully completed
30232 DBE Message Recovery successfully completed
30233 DBE Message Writing IMDB pages to disk. Pages: value
30234 DBE Message Finished writing IMDB pages to disk. Pages: value
30235 DBE Message Loading IMDB. Pages: value
30236 DBE Message Finished loading IMDB. Pages: value
30237 DBE Message Starting to reorganize and compact the database file.
30240 DBE Message Failed to create a new database
30241 DBE Message Failed to log on to the database
30242 DBE Message Failed to connect, script not executed.

Appendix E. Error codes 291

Table 79. solidDB DBE errors and messages (continued)

Code Class Type Description

30243 DBE Message Failed to open SQL input file
30244 DBE Message Script <script_name> failed
30245 DBE Message Table <table_name> not found.
30246 DBE Message Converting table <table_name>...
30247 DBE Message Table <table_name> converted
30248 DBE Message No need to convert table <table_name>
There is a problem opening the database because not all db files defined in the solid.ini were
found. Check the configuration. Note that only the file(s) defined with the largest FileSpec_n
30249 DBE Message definition(s) should be missing.
30250 DBE Message Using SplitMerge
30251 DBE Message Starting to re-create the database (delete old database and create a new one).
30252 DBE Message Successfully deleted database and logs
30253 DBE Message Failed to delete database and/or logs check file permissions.
30254 DBE Message Database is a broken HSB copy or netcopy database.
Fatal
30255 DBE Error Exiting from server (FAKE_DBE_CRASHAFTERCPMARK).
Fatal
30256 DBE Error Database must exist!
Fatal
30257 DBE Error Database creation date is already reset!
Fatal
30258 DBE Error Database creation time can be reset only once!
Fatal
30259 DBE Error Error test in file <file_name> line <value>
30260 DBE Message Database version does not match with SOLID version.
30261 DBE Message Database file format does not match with SOLID version.
30262 DBE Message Maximum number of users reached.
30264 DBE Message Fixing bad B-tree node reference at address address.
30265 DBE Message Fixing B-tree key range errors at address address.
30266 DBE Message Running autofix.
30267 DBE Message Autofix completed successfully.
30268 DBE Message Autofix failed, check ssdebug.log for errors.
30269 DBE Message Maximum number of logreader operations reached.
30270 DBE Message Maximum number of abort operations reached.
30320 DBE Message Logreader using default transaction batch size value
30321 DBE Message Logreader transaction batch size value
30322 DBE Message Logreader read full statements
30323 DBE Message Logreader catchup init
30324 DBE Message Logreader catchup error
30325 DBE Message Logreader catchup scan open
30326 DBE Message Logreader catchup active
30327 DBE Message Logreader catchup completed
30328 DBE Message Logreader live data

292 IBM solidDB: Administrator Guide

solidDB CP (checkpoint) messages
Table 80. solidDB CP (checkpoint) messages

Code Class Type Description

30280 CP Message Checkpoint creation completed
30281 CP Message Checkpoint creation started
30282 CP Message Checkpoint creation not started because shutdown is in progress
30283 CP Message Checkpoint creation not started because checkpointing is disabled
30284 CP Message Checkpoint not started; denied by user callback.
30285 CP Message Create <value> start failed.
30286 CP Message Checkpoint DBE flushing timed out, <number> of <number> pages left.
30287 CP Message Checkpoint MME flushing timed out, <number> of <number> pages left.
30288 CP Message MME flush batch completion wait timed out, trying to proceed.
30289 CP Message Checkpoint DBE flush, <number> pages left.
30290 CP Message Checkpoint MME flush, <number> pages left.

solidDB BCKP (backup) messages

Table 81. solidDB BCKP (backup) messages

Code Class Type Description

30300 BCKP Message Backup completed successfully
30301 BCKP Message Backup started to <directory path>.
30302 BCKP Message Backup start failed. <Shutdown is in progress|Backup is already active>
30303 BCKP Message Backup aborted.
30304 BCKP Message Backup failed. <error description>
30305 BCKP Message Backup not started; denied by user callback.
30306 BCKP Message Backup not started; Backup is not supported on diskless server.
30307 BCKP Message Backup not started index check failed. Errors written to file ssdebug.log.

solidDB AT (timed commands) messages

Table 82. solidDB AT (timed commands) messages

Code Class Type Description

30350 AT Message At: backup <backup_directory>
30351 AT Message At: makecp
30352 AT Message At: throwout <user_name>
30353 AT Message At: report <report_file_name>
30354 AT Message At: shutdown
30355 AT Message At: system <operating_system_command>
30356 AT Message At: open
30357 AT Message At: close
30358 AT Message At: assert
Server noticed time inconsistency during at-command execution. If the system time has been
30359 AT Message changed, restart the server.
30360 AT Message AT command failed. <reason>

Appendix E. Error codes 293

Table 82. solidDB AT (timed commands) messages (continued)

Code Class Type Description

30361 AT Message Illegal at command <command> ignored.
30362 AT Message Illegal immediate at command <command> ignored.
30362 AT Message Deleted %d rows from SYS_BACKGROUNDJOB_INFO

solidDB LOG (logging) messages

Table 83. solidDB LOG (logging) messages

Code Class Type Description

30400 LOG Message Transaction logging is disabled roll-forward recovery is not possible
30401 LOG Message Using log write mode
30402 LOG Message Conflicting parameters General.BackupCopyLog=Yes and General.CheckpointDeleteLog=Yes
30403 LOG Message Log file write failure
30404 LOG Message Check results from file <file_name>.
30405 LOG Message Unable to open message log file <file_name>
30406 LOG Message SOLID Fatal Error: Failed to open trace file <file_name>.
30407 LOG Message The tail of log was corrupt the corrupt part was ignored.

solidDB INI (configuration file) messages

Table 84. solidDB INI (configuration file) messages

Code Class Type Description

30157 INI Message Parameter <parameter> is incompatible with SMA server and is thus ignored.
30450 INI Message Value <value> for parameter <parameter> is not multiple of 512 using default value <value>
Value for index file specification <specification> is invalid using default file <file_name> and
30451 INI Message max size <value>
Value for index file specification <specification> is invalid all following file specifications are
30452 INI Message ignored
30453 INI Message Illegal value <value> for parameter <parameter> using default value <value>
30454 INI Message Failed to save configuration file <configuration_file>
30455 INI Message Failed to set the maximum number of open files to <value> using default <value>
30456 INI Message Using configuration file <configuration_file>
30457 INI Message Configuration file <configuration_file> not found using defaults
30458 INI Message Illegal value <value> for parameter <parameter> using default value <value>
30459 INI Message Illegal value <value> for parameter <parameter> using default value <value>
30460 INI Message Illegal value <value> for parameter <parameter>using default value <value>
30461 INI Message Illegal value <value> for parameter <parameter> using default value <value>
30463 INI Message Srv.ReadThreadMode forced to <value> for parameter <parameter>
30464 INI Message Illegal value <value> for parameter <parameter> using default value <value>
Process size <value> exceeds parameter Srv.ProcessMemoryLimit value <value>

Increase the size of the value of the Srv.ProcessMemoryLimit parameter or disable the process
30465 INI Message memory size checking by setting Srv.ProcessMemoryLimit to 0.

294 IBM solidDB: Administrator Guide

solidDB HSB (HotStandby) errors and messages
Table 85. solidDB HSB errors and messages
Code Class Type Description
14007 HSB Message CONNECTING
14008 HSB Message CATCHUP
14009 HSB Message No role switches since the server startup
14010 HSB Message DISCONNECTING
14522 HSB Message HotStandby copy directory not specified.
14537 HSB Message BROKEN
14704 HSB Error HotStandby copy or netcopy is only allowed when primary is in alone state
14712 HSB Error Server is secondary. Use primary server for this operation
30500 HSB Message Started as a HotStandby primary
30501 HSB Message Started as a HotStandby secondary
The database was not shut down properly the last time that it was used starting as a HotStandby
30502 HSB Message secondary
30503 HSB Message Forcing HotStandby primary to start as a secondary
30504 HSB Message HotStandby role switched to secondary
30505 HSB Message HotStandby role switched to primary
30506 HSB Message Primary server must be set to PRIMARY ALONE or switched to the secondary role.
30507 HSB Message HotStandby server set to PRIMARY ALONE.
30508 HSB Message HotStandby server set to SECONDARY ALONE
30509 HSB Message HotStandby switch to primary failed, error error_code
30510 HSB Message HotStandby switch to secondary failed, error error_code
30511 HSB Message Failed to start HotStandby to server_name, error error_code
30512 HSB Message Failed to switch HotStandby role to primary, error error_code
30513 HSB Message Failed to switch HotStandby role to secondary, error error_code
30514 HSB Message Both databases are primary servers starting as a secondary
30515 HSB Message Both HotStandby databases are primaries
30516 HSB Message Failed to start HotStandby to server_name, other server rejected with error error_code
30517 HSB Message HotStandby role in secondary switched
30518 HSB Message HotStandby role switched to standalone
30530 HSB Message Starting to send HotStandby catchup data to secondary server
30531 HSB Message HotStandby catchup completed successfully
30532 HSB Message HotStandby catchup ended abnormally
HotStandby catchup can not be started. Secondary is not properly synchronized with primary full
30533 HSB Message synchronization is required
30534 HSB Message HotStandby catchup ended abnormally, status error_code
30535 HSB Message HotStandby catchup ended abnormally, error error_code
30536 HSB Message HotStandby catchup ended abnormally due to a communication error
30537 HSB Message HotStandby catchup ended abnormally, secondary returned error error_code
HotStandby catchup size <value> greater than configured maximum size value, stopping
30538 HSB Message HotStandby
30539 HSB Message File error in HotStandby catchup, stopping HotStandby
30540 HSB Message Starting to receive HotStandby catchup data from primary server
Secondary is not properly synchronized with primary due to a log file corruption. Restart
30541 HSB Message secondary and execute a HSB netcopy.
30550 HSB Message Connection broken to HotStandby secondary server

Appendix E. Error codes 295

Table 85. solidDB HSB errors and messages (continued)
Code Class Type Description
30551 HSB Message Connected to HotStandby
30552 HSB Message HotStandby secondary connected
30553 HSB Message HotStandby primary connected
Hot Standby connection broken to Secondary server with an open transaction waiting for the
operator to resolve transaction status. Primary server must be set to alone mode or switched to
30554 HSB Message secondary mode.
30555 HSB Message HotStandby ping timeout
30556 HSB Message Connection broken to HotStandby secondary
30557 HSB Message HotStandby databases are not properly synchronized
30558 HSB Message HotStandby connection to secondary timed out
30559 HSB Message HotStandby connection broken
30560 HSB Message HotStandby: HotStandby_error_message
30561 HSB Message Started connecting to HotStandby
30562 HSB Message Connection broken to HotStandby primary server
30570 HSB Message Network backup completed.
30571 HSB Message Started to receive network backup.
30572 HSB Message Database started using a HotStandby copy/netcopy.
30573 HSB Message Network backup failed.
30574 HSB Message Hot Standby forcing threads to 1
30575 HSB Message Hot Standby replication configured but no active license found replication not started
30577 HSB Message HotStandby connect operation failed
30579 HSB Message HotStandby connection is already active.
30581 HSB Message Invalid event event
30582 HSB Message HotStandby cannot set the server to PRIMARY ALONE.
30583 HSB Message HotStandby copy failed.
30585 HSB Message Database starts to listen for netcopy.
HotStandby catchup, catchup_phase logpos: log_position

catchup_phase can be:

v HSB waitdurable
v HSB catchup start
v HSB write catchup
30586 HSB Message v HSB write switch

30750 HSB Message HotStandby connection is already active.

30752 HSB Message Operation failed disconnect is active.
30757 HSB Message CONNECTED
30758 HSB Message Bad Hot Standby command.
30759 HSB Message HotStandby server is set to STANDALONE.
30760 HSB Message Started the process of disconnecting the servers.
30761 HSB Message Started the process of switching the role to primary.
30762 HSB Message Started the process of switching the role to secondary.
30763 HSB Message Started the process of connecting the servers.
30764 HSB Message Copy started.
30765 HSB Message Parameter AutoPrimaryAlone is set to Yes.
30766 HSB Message Parameter AutoPrimaryAlone is set to No.

296 IBM solidDB: Administrator Guide

Table 85. solidDB HSB errors and messages (continued)
Code Class Type Description
30767 HSB Message Parameter Connect is set to value.
30768 HSB Message HotStandby connection is already broken.
30769 HSB Message Operation failed because connection between the servers is active.
30772 HSB Message Hot Standby node identifier must be defined in the ini file.
30774 HSB Message Server is already STANDALONE.
30775 HSB Message Parameter CopyDirectory is set to value.
30776 HSB Message Parameter ConnectTimeout is set to value.
30777 HSB Message Parameter PingTimeout is set to value milliseconds.
30779 HSB Message Hot Standby migration is active
30782 HSB Message Server is already set to primary alone.
30783 HSB Message Server is already set to secondary alone.
30784 HSB Message Parameter parameter_name is set to value.
30785 HSB Message Parameter parameter_name is set to value.
30786 HSB Message Parameter parameter_name is set to value.
pri_dologskip:bad type, log pos, log size

This error refers to a failed operation on the HSB primary server. The error returns the failed
operation and its location in the log, and the log size. Operations in the replication log are
30787 HSB Fatal Error skipped.
pri_hsblogcopy_write:bad type, log pos, log size

This error refers to a failed operation on the HSB primary server. The write to the replication log
30788 HSB Fatal Error file fails. The error returns the failed operation and its location in the log, and the log size.
30789 HSB Fatal Error Failed to open hot standby replication log file.
Failed to allocate memory for HotStandby log. Max Log size is logsize.

This error concerns a diskless database using HotStandby. In these systems, the HotStandby log is
30790 HSB Fatal Error written to memory. This error is given if allocating more memory for the log file fails.
30791 HSB Fatal Error HotStandby:solhsby:bad type type, log pos log_pos, log size log_size
30792 HSB Message Both servers are secondary.
Maximum number of secondary tasks value reached.

The queue at the secondary server for incoming log operations is growing faster than the
operations can be executed and acknowledged to the primary server.

30793 HSB Message The queue can be monitored with the performance counter HSB secondary queues.

solidDB SNC (synchronization) messages

Table 86. solidDB SNC (synchronization) messages

Code Class Type Description

30700 SNC Message Starting parallel sync history key conversion...
30701 SNC Message Starting sync history key conversion...
30702 SNC Message Sync history key conversion done
30703 SNC Message Database is not a master database

Appendix E. Error codes 297

solidDB XS (external sorter) errors and messages
Table 87. solidDB XS (external sorter) errors

Code Class Type Description

Unable to reserve requested <number> memory blocks for external sorter. Only <number>
30800 XS Message memory blocks were available. SQL: <sql statement>
Unable to reserve requested <number> memory blocks for external sorter. Only <number>
30801 XS Message memory blocks were available.
30802 XS Fatal Failed to create a temporary file for local sorting (system errno =)
Error
The sorter cannot create a temporary file.
30805 XS Message Maximum number of files for external sorting reached

solidDB FIL (file system) messages

Table 88. solidDB FIL (file system) messages

Code Class Type Description

30900 FIL Message SsBLock failed, file <file_name>, error = <error_code>
30901 FIL Message SsBLock failed, file <file_name>, error = <error_code>, fd = <value>
SsBOpenLocal failed, file <file_name>, error = <error_code>, retries = <value>, open files =
30902 FIL Message <value>
SsBOpenLocal failed, file <file_name>, error = <error_code>, vaxc$error = <value>, fab stv =
30903 FIL Message <value>, retries = <value>, open files = <value>
SsBOpenLocal failed, file <file_name>, error = <error_code>, vaxc$error = <value>, retries =
30904 FIL Message <value>
SsBOpenLocal failed, file <file_name>, error = <error_code>, dos rc = <value>, retries =
30905 FIL Message <value>
30906 FIL Message SsBOpenLocal failed, file <file_name>, error = <error_code>, retries = <value>
30907 FIL Message SsBOpen failed, file <file_name>, error = <error_code>, retries = <value>
30908 FIL Message File flush failed, error <error_code>, file <file_name>
30909 FIL Message File flush failed, error <error_code>, vaxc$error = <value>, file <file_name>
30910 FIL Message File flush failed, error <error_code>, dos rc <value>, file <file_name>
30911 FIL Message File flush close failed, error <error_code>, file <file_name>
30912 FIL Message File flush open failed, error <error_code>, file <file_name>
30913 FIL Message File size query failed, error<error_code>, file <file_name>, retries <value>
30914 FIL Message File size query seek failed, file <file_name>
30915 FIL Message File size change failed, error <error_code>, file <file_name>, newsize <value>, retries <value>
30916 FIL Message File <file_name>size change failed, not supported by Windows mmio
30917 FIL Message File read failed, error <error_code>, file <file_name>, location <directory>, retries <value>
File read failed, error <error_code>, file <file_name>, location <directory>, retries <value>,
30918 FIL Message vaxc$error = <value>
30919 FIL Message File read seek failed, error <error_code>, file <file_name>, location <directory>, retries <value>
File read seek failed, error <error_code>, file <file_name>, location <directory>, retries <value>,
30920 FIL Message vaxc$error = <value>
30921 FIL Message File write failed, error <error_code>, file <file_name>, location <directory>, retries <value>
File write failed, error <error_code>, file <file_name>, location <directory>, retries <value>,
30922 FIL Message vaxc$error = <value>
30923 FIL Message File write seek failed, error <error_code>, file <file_name>, location <directory>, retries <value>

298 IBM solidDB: Administrator Guide

Table 88. solidDB FIL (file system) messages (continued)

Code Class Type Description

File write seek failed, error <error_code>, file <file_name>, location <directory> retries <value>,
30924 FIL Message vaxc$error = <value>
30925 FIL Message File write end failed, error <error_code>, file <file_name>, retries <value>
File write end failed, error <error_code>, file <file_name>, retries <value>, vaxc$error =
30926 FIL Message <value>
30927 FIL Message File append write failed, error <error_code>, file <file_name>, retries <value>
File append write failed, error <error_code>, file <file_name>, retries <value>, vaxc$error =
30928 FIL Message <value>
30929 FIL Message File append seek failed, error <error_code>, file <file_name>, retries <value>
File append seek failed, error <error_code>, file <file_name>, retries <value>, vaxc$error =
30930 FIL Message <value>
30931 FIL Message File seek failed, error <error_code>, file <file_name>, location <directory>, retries <value>
File seek failed, disk full, error <error_code>, file <file_name>, location <directory>, new
30932 FIL Message location <directory>, retries <value>
30933 FIL Message File seek end failed, error <error_code>, file <file_name>, retries <value>
30934 FIL Message File seek to new size failed, error <error_code>, file <file_name>, newsize <value>
30935 FIL Message File expand write failed, file <file_name>
30936 FIL Message File expand seek failed, file <file_name>
30937 FIL Message VirtualAlloc failed, error = <error_code>
File paged read failed, error <error_code>, file <file_name>, npages <value>, pagesize <value>,
30938 FIL Message page address <value>, retries <value>
File paged write failed, error <error_code>, file <file_name>, npages <value>, pagesize
30939 FIL Message <value>, page address <value>, retries <value>

solidDB TAB (table) messages

Table 89. solidDB TAB (table) messages

Code Class Type Description

31000 TAB Message Bad cursor state, function <function> state <state>
31001 TAB Message Table <table_name> created as <table_name>

solidDB SMA (shared memory access) errors

Table 90. solidDB SMA (shared memory access) errors

Code Class Type Description

Fatal Value for maximum shared memory size SharedMemoryAccess.MaxSharedMemorySize=<value> is
31100 SMA Error invalid.

solidDB PT (passthrough) errors

Table 91. solidDB passthrough errors

Class Type
Code Description
32001 PT Error Passthrough: <description>
32002 PT Error Passthrough: Error:<description>

Appendix E. Error codes 299

solidDB SQL errors
Table 92. solidDB SQL errors

Error code Description

SQL Error 1 Parsing error 'syntax error'

The SQL parser could not parse the SQL string. Check the syntax of the SQL statement and
try again.

SQL Error 2 Table table can not be opened

You may not have privileges to access the table and its data.

SQL Error 3 Table table can not be created

Table can not be created. You may not have privileges for this operation.

SQL Error 4 Illegal type definition column

A column type in your CREATE TABLE statement is illegal. Use a legal type for the
column.

SQL Error 5 Table table can not be dropped

Table can not be dropped. Only the owner (that is, the creator) can drop it.

SQL Error 6 Illegal value specified for column column

The value specified for column is invalid. Check the value for the column.

SQL Error 7 Insert failed

The server failed to do the insertion. You may not have INSERT privilege on the table or it
may be locked.

SQL Error 8 Delete failed

The server failed to do the deletion. You may not have DELETE privilege on the table or
the row may be locked.

SQL Error 9 Row fetch failed

The server failed to fetch a row. You may not have SELECT privilege on the table or there
may be an exclusive lock on the row.

SQL Error 10 View view can not be created

You cannot create this view. You may not have SELECT privilege on one or more tables in
the query-specification of your CREATE VIEW statement.

SQLError 11 View view cannot be dropped.

You cannot drop this view. Only the owner (i.e. the creator) of the view can drop it.

SQLError 12 Illegal view definition view

The view definition is illegal. Check the syntax of the definition.

SQLError 13 Illegal column name column

Column name is illegal. Check that the name is not a reserved name.

300 IBM solidDB: Administrator Guide

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 14 Call to function function failed

Function call to function failed. Check the arguments and their types.

SQL Error 15 Arithmetic error

An arithmetical error occurred. Check the operators, values and types.

SQL Error 16 Update failed

The server failed to update a row. There may a lock on a row.

SQL Error 17 View is not updatable

This view is not updatable. UPDATE, INSERT and DELETE operations are not allowed.

SQL Error 18 Inserted row does not meet check option condition

You tried to insert a row, but one or more of the column values do not meet column
constraint definition.

SQL Error 19 Updated row does not meet check option condition

You tried to update a row, but one or more of the column values do not meet column
constraint definition.

SQL Error 20 Illegal CHECK constraint

A check constraint given to the table is illegal. Check the types of the check constraint of
this table.

SQL Error 21 Insert failed because of CHECK constraint

You tried to insert a row, but the values do not meet the check option conditions.

SQL Error 22 Update failed because of CHECK constraint

You tried to update a row, but the values do not meet the check option conditions.

SQL Error 23 Illegal DEFAULT value

The DEFAULT value for the column given is illegal.

SQL Error 25 Duplicate columns in INSERT column list

You have included a column in column list twice. Remove duplicate columns.

SQL Error 26 At least one column definition required in CREATE TABLE

You need to specify at least one column definition in a CREATE TABLE statement.

SQL Error 27 Illegal REFERENCES column list

There are wrong number of columns in your REFERENCES list.

SQL Error 28 Only one PRIMARY KEY allowed in CREATE TABLE

You can use only one PRIMARY KEY in CREATE TABLE.

Appendix E. Error codes 301

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 29 GRANT failed

Granting privileges failed. You may not have privileges for this operation.

SQL Error 30 REVOKE failed

Revoking privileges failed. You may not have privileges for this operation.

SQL Error 31 Multiple instances of a privilege type

You tried to grant privileges to a role or a user. You have included multiple instances of a
privilege type in the list of privileges.

SQL Error 32 Illegal constant constant

Illegal constant was found. Check the syntax of the statement.

SQL Error 33 Column name list of illegal length

You have entered different number of columns in CREATE VIEW statement to the view
and to the table.

SQL Error 34 Conversion between types failed

An expression in UPDATE statement has illegal type for a column.

SQL Error 35 Column names not allowed in ORDER BY for UNION

You can not use column name in an ORDER BY for UNION statement.

SQL Error 36 Nested aggregate functions

Nested aggregate functions can not be used. For example: SUM(AVG(column)).

SQL Error 37 Aggregate function with no arguments

An aggregate function was entered with no arguments. For example: SUM().

SQL Error 38 Set operation between different row types

You have tried to execute a set operation of tables with incompatible row types. The row
types in a set operation must be compatible.

SQL Error 39 COMMIT WORK failed

Committing a transaction failed.

SQL Error 40 ROLLBACK WORK failed

Rolling back a transaction failed.

SQL Error 41 Savepoint could not be created

A savepoint could not be created.

302 IBM solidDB: Administrator Guide

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 42 Could not create index index

An index could not be created. You may not have privileges for this operation. You need to
be an owner of the table or have SYS_ADMIN_ROLE to have privileges to create index for
the table.

SQL Error 43 Could not drop index index

An index could not be dropped. You may not have privileges for this operation. You need
to be an owner of the table or have SYS_ADMIN_ROLE to have privileges to drop index
from the table.

SQL Error 44 Could not create schema schema

A schema could not be created.

SQL Error 45 Could not drop schema schema

A schema could not be dropped.

SQL Error 46 Illegal ORDER BY specification

You tried to use an ORDER BY column that does not exist. Refer to an existing column in
the ORDER BY specification.

SQL Error 47 Maximum length of identifier is 31

You have exceeded the maximum length for the identifier.

SQL Error 48 Subquery returns more than one row

You have used a subquery that returns more than one row. Only subqueries returning one
row may be used in this situation.

SQL Error 49 Illegal expression expression

You tried to insert or update a table using an aggregate function (SUM, MAX, MIN or
AVG) as a value. This is not allowed.

SQL Error 50 Ambiguous column name column

You have referenced a column which exists in more than one table. Use syntax table.column
to indicate which table you want to use.

SQL Error 51 Non-existent function function

You tried to use a function which does not exist.

SQL Error 52 Non-existent cursor cursor

You tried to use a cursor which is not created.

SQL Error 53 Function call sequence error

A function was called in wrong order. Check the sequence and success of the function
calls.

SQL Error 54 Illegal use of a parameter

A parameter was used illegally. For example: SELECT * FROM TEST WHERE ? < ?;

Appendix E. Error codes 303

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 55 Illegal parameter value

A parameter has an illegal value. Check the type and value of the parameter.

SQL Error 56 Only ANDs and simple condition predicates allowed in UPDATE CHECK

All search condition predicates are not supported.

SQL Error 57 Opening the cursor did not succeed

Server failed to open a cursor. You may not have cursor open at this moment.

SQL Error 58 Column column is not referenced in group-by-clause

You tried to group rows using column. All columns in group_by_clause must be listed in
your select_list. A star ('*') notation is not allowed with GROUP BY.

SQL Error 59 Comparison between incompatible types

You tried to compare values which have incompatible types. Incompatible types are for
example an integer and a date value.

SQL Error 60 Reference to the insert table not allowed in the source query

You have referenced in subquery a table where you are inserting values. This is not
allowed.

SQL Error 61 Reference to the update table not allowed in subquery

You have referenced in subquery a table where you are updating values. This is not
allowed.

SQL Error 62 Reference to the delete table not allowed in subquery

You have referenced in subquery a table where you are deleting values. This is not
allowed.

SQL Error 63 Subquery returns more than one column

You have used a subquery that returns more than one column. Only subqueries returning
one column may be used.

SQL Error 64 Cursor cursor not updatable

The cursor opened is not updatable.

SQL Error 65 Insert or update tried on pseudo column

You tried to update a pseudo column (ROWID, ROWVER). Pseudo columns are not
updatable.

SQL Error 66 Could not create user user

A user could not be created. You may not have privileges for this operation.

SQL Error 67 Could not alter user user

A user could not be altered. You may not have privileges for this operation.

304 IBM solidDB: Administrator Guide

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 68 Could not drop user user

A user could not be dropped. You may not have privileges for this operation.

SQL Error 69 Could not create role role

A role could not be created. You may not have privileges for this operation.

SQL Error 70 Could not drop role role

A role could not be dropped. You may not have privileges for this operation.

SQL Error 71 Grant role failed

Granting role failed. You may not have privileges for this operation.

SQL Error 72 Revoking role failed. You may not have privileges for this operation.

Revoke role failed

SQL Error 73 Comparison of vectors of different length

You have tried to compare row value constructors that have different number of
dimensions. For example you have compared (a,b,c) to (1,1).

SQL Error 74 Expression * not compatible with aggregate expression

The aggregate expression can not be used with * columns. Specify columns using their
names when used with this aggregate expression. This usually happens when GROUP BY
expression is used with the * columns.

SQL Error 75 Illegal reference to table table

You have tried to reference a table which is not in the FROM list. For example: SELECT
T1.* FROM T2.

SQL Error 76 Ambiguous table name table

You have used the syntax table.column_name ambiguously. For example: SELECT T1.*
FROM T1 A,T1 B WHERE A.F1=0;

SQL Error 77 Illegal use of aggregate expression

You tried to use aggregate expression illegally. For example: SELECT ID FROM TEST
WHERE SUM(ID) = 3;

SQL Error 78 Row fetch failed

The server failed to fetch a row. You may not have SELECT privilege on the table or there
may be an exclusive lock on the row.

SQL Error 79 Subqueries not allowed in CHECK constraint

You tried to use subquery in a check constraint.

SQL Error 80 Sorting failed

External sorter is out of disk space or cache memory. Modify parameters in configuration
file solid.ini.

Appendix E. Error codes 305

Table 92. solidDB SQL errors (continued)

Error code Description

SQL Error 81 SET syntax results in error

SQL Error 82 Improper type used with LIKE

SQL Error 83 Syntax error

SQL Error 84 Parser error statement

SQL Error 85 Incorrect number of values for INSERT

SQL Error 86 Illegal ROWNUM constraint

SQL Error 88 Subquery not allowed in UPDATE expression

Subqueries cannot be used with UPDATE statements.

SQL Error 90 Incorrect ALTER table

SQL Error 93 Illegal GROUP BY expression

GROUP BY expression is illegal.

SQL Error 102 Unused optimizer hint

A table name alias was used in the query, but this alias was not specified as the table name
in the optimizer hint. The alias name must be specified, not the table name.

solidDB executable errors

Table 93. solidDB executable errors

Error code Description

Executable Error 10 Failed to open database

Executable Error 11 Failed to connect to database

Executable Error 12 Database test failed

Executable Error 13 Database fix failed

Executable Error 14 License error

Executable Error 15 Database must be converted

Executable Error 16 Database does not exist

Executable Error 17 Database exists

Executable Error 18 Database not created

Executable Error 19 Database create failed

Executable Error 20 Communication init failed

306 IBM solidDB: Administrator Guide

Table 93. solidDB executable errors (continued)

Error code Description

Executable Error 21 Communication listen failed

Executable Error 22 Service operation failed

Executable Error 23 Failed to open all the defined database files.

Executable Error 24 Database is a broken netcopy database
Executable Error 50 Illegal command line argument

Executable Error 51 Failed to change directory

Executable Error 52 Input file open failed

Executable Error 53 Output file open failed

Executable Error 54 Server connect failed

Executable Error 55 Operation init failed

Executable Error 100 Assert or other fatal error.

solidDB Speed Loader (solloado and solload) errors

Table 94. solidDB Speed Loader (solloado and solload) errors

Error Code Meaning

No error code Operation was successful

No error code Operation has completed

100 Operation failed. For example, this error code is procedured when performing an
operation, such as flushing arrays and inserting records.

106 Illegal column name

This error applies to the column name used in the control file.

107 Illegal constraint

108 Invalid column data

The data type in the data file conflicts with the table definition.

109 Unique constraint violation

110 Concurrency conflict, two transactions updated or deleted the same row

112 Unsupported character set

114 Null data in NOT NULL column

NULL data value given in a NOT NULL column

Appendix E. Error codes 307

Table 94. solidDB Speed Loader (solloado and solload) errors (continued)

Error Code Meaning

116 Communication error, connection is lost

121 RPC parameter error

122 Table not found

124 Wrong number of parameters

308 IBM solidDB: Administrator Guide

Appendix F. solidDB ADMIN COMMAND syntax
This appendix describes the solidDB ADMIN COMMAND syntax. This command
set is not part of ANSI SQL; it is a solidDB-specific extension.

ADMIN COMMAND
ADMIN COMMAND ’command_name’

command_name ::= ABORT | ASSERTEXIT | BACKUP |

BACKGROUNDJOB | BACKUPLIST | CHECKPOINTING | CLEANBGJOBINFO |
CLOSE | DESCRIBE | ERRORCODE | ERROREXIT | ERRORMESSAGE | FILESPEC |
HELP | HOTSTANDBY | INDEXUSAGE | INFO | LOGMESSAGE | LOGREADER | MAKECP | MEMORY |
MESSAGES | MONITOR | NETBACKUP | NETBACKUPLIST | NETSTAT | NOTIFY |
OPEN | PARAMETER | PASSTHROUGH STATUS | PERFMON | PERFMON DIFF | PID | PROCTRACE |
PROTOCOLS | REPORT | RUNMERGE | SAVE | SHUTDOWN | SQLLIST | STARTMERGE |
STATUS | THROWOUT | TID | TRACE | TRACEMESSAGE | USERID | USERLIST |
USERTRACE | VERSION

Usage

The ADMIN COMMAND is a solidDB-specific SQL extension that executes administrative

commands.

Using ADMIN COMMAND with solidDB SQL Editor (solsql)

When used with the solidDB SQL Editor (solsql), the command_name must be
given with single quotation marks. For example:
ADMIN COMMAND ’backup’

If you use double quotation marks, the command_name is not recognized and the
command fails.

Using ADMIN COMMAND with solidDB Remote Control (solcon)

When used with the solidDB Remote Control (solcon), the ADMIN COMMAND
syntax includes the command_name only, without the single quotation marks. For
example:
backup

Abbreviations

Abbreviations for ADMIN COMMANDs are also available. For example:

ADMIN COMMAND ’bak’

To access a list of abbreviated commands, execute

ADMIN COMMAND ’help’

The result set contains two columns: RC and TEXT:

v The RC (return code) column is a command return code. If the execution of the
command was successful, value 0 is returned.
v The TEXT column is the command reply.

309
 Important usage notes
v All options of the ADMIN COMMAND are not transactional and cannot be
rolled back.
v ADMIN COMMANDs and starting transactions
Although ADMIN COMMANDs are not transactional, they will start a new
transaction if one is not already open. (They do not commit or roll back any
open transaction.) This effect is usually insignificant. However, it may affect the
'start time" of a transaction, and that may occasionally have unexpected effects.
solidDB's concurrency control is based on a versioning system; you see a
database as it was at the time that your transaction started.
For example, if you issue an ADMIN COMMAND without another commit and
then leave for an hour; when you return, your next SQL command may see the
database as it was an hour ago, that is, when you first started the transaction
with the ADMIN COMMAND.
v Error codes
Error codes in ADMIN COMMANDS return an error only if the command
syntax or parameter values are incorrect. If only the requested operation may be
started, the command returns SQLSUCCESS (0). The outcome of the operation
itself is written into a result set. The result set has two columns: RC and TEXT.
The RC (return code) column contains the return code of the operation: it is "0"
for success, and different numeric values for errors. It is thus necessary to check
both the codes of the ADMIN COMMAND statement and of the operation.

Following is a description of the syntax for each ADMIN COMMAND command

option:
Table 95. ADMIN COMMAND syntax and options

Option syntax Description

ADMIN COMMAND ’abort

[backup | netbackup]’ Aborts the active local or network backup process. The backup operation is not
guaranteed to be atomic, therefore the cancelled operation may produce an incomplete
backup file to the backup directory until the next backup takes place.

If the option is not entered, the command defaults to ADMIN COMMAND ’abort backup’.

ADMIN COMMAND ’assertexit’

Abbreviation: asex Terminates the server immediately without a proper shut down.

ADMIN COMMAND ’backgroundjob’

[LIST [-l] [user]] | Lists and possibly aborts running background jobs, that is, SQL statements that have
[ABORT {jobid | user | ALL }] | been started by using the START AFTER COMMIT statement.
[DELETE ERRORINFO v LIST option lists running jobs for all users or a specified user.
{jobid | user | ALL }]’
v -l option refers to a long list (similar to ADMIN COMMAND ’userlist -l’).
user ::= USER {username|userid} v ABORT option aborts either jobs by job identification number or all jobs by user
identification number. If you give the ABORT without arguments, it aborts all jobs
Abbreviation: bgjob from all users.
v DELETE ERRORINFO option deletes error information from the
SYS_BACKGROUNDJOB_INFO system table, where the errors encountered by
background jobs are stored. This option performs the same operation as the
deprecated ADMIN COMMAND ’CLEANBGJOBINFO’ command.

310 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’backup [-s]

[backup_directory]’ Makes a backup of the database. The operation can be performed as a synchronized
Abbreviation: bak or an asynchronic (default) manner. The synchronized operation is specified by using
the optional -s option.

The default backup directory is defined with the General.BackupDirectory. The

backup directory may also be given as an argument. For example, backup abc creates
a backup in directory abc. All directory definitions are relative to the solidDB working
directory.

ADMIN COMMAND ’backuplist’ Displays a status list of last local backups.

Abbreviation: bls

ADMIN COMMAND ’checkpointing {ON|OFF}’ Turns checkpointing on or off.

Abbreviation: cp

ADMIN COMMAND ’cleanbgjobinfo’ Note: This command has been deprecated. Use ADMIN COMMAND ’backgroundjob’
Abbreviation: cleanbgi instead.

Cleans the table SYS_BACKGROUNDJOB_INFO containing status data of background

procedures.

ADMIN COMMAND ’close’ Closes the server to new connections; no new connections are allowed.
Abbreviation: clo

ADMIN COMMAND ’describe

parameter param’ Returns a description of all parameters or a parameter specified with param.
Abbreviation: des
param must be given in the format section_name.param_name. The section and
parameter names are case-insensitive.

The following example describes parameter Com.Trace = y/n:

ADMIN COMMAND ’des parameter com.trace’ RC TEXT
-- ----
0 Trace
0 If set to ’yes’, trace information of the network messages
is written to a file
0 BOOL
0 RW/STARTUP
0
0
0 No
7 rows fetched.

ADMIN COMMAND ’errorcode Returns a description of all error codes or a specific error code.
{all | SOLID_error_code}’
Abbreviation: ec SOLID_error_code is the code number, for example 10034.
ADMIN COMMAND ’errorcode 10034’;
RC TEXT
-- ----
0 Code: DBE_ERR_SEQEXIST (10034)
0 Class: Database
0 Type: Error
0 Text: Sequence already exists
4 rows fetched.

ADMIN COMMAND ’errorexit <number>’ Forces the server into an immediate process exit with the given process exit code.
Abbreviation: erex

ADMIN COMMAND ’errormessage <string>’ Outputs the user-defined <string> to the error message log (solerror.out).
Abbreviation: errmsg

Appendix F. solidDB ADMIN COMMAND syntax 311

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’filespec

[-d | -a "<file_name> Displays or modifying database (index) file specifications defined with the
<max_file_size_in_bytes> IndexFile.FileSpec parameter as well file sizes and current fill ratios (percentage).
[<device_number>]"]’ v -d deletes the database file specified with <file_name max_file_size_in_bytes>
Abbreviation: fs [device_number]
v -a adds a new database file specification as specified with <file_name>
>max_file_size_in_bytes> [<device_number>]
For example:
ADMIN COMMAND ’fs -a "solid3.db 3000M"’;
RC TEXT
-- ----
0 Added: FileSpec_3 = solid3.db 3145728000
The database file specification changes are stored in the solid.ini configuration file at
shutdown.

ADMIN COMMAND ’help’ Displays available commands.

Abbreviation: ?

ADMIN COMMAND
’hotstandby [option]’ A HotStandby command.
Abbreviation: hsb
For a list of options, see the IBM solidDB High Availability User Guide.

For a list of options, see HotStandby ADMIN COMMANDs in the IBM solidDB High
Availability User Guide.

ADMIN COMMAND ’indexusage’ Displays the indexes, showing the number of times each index has been used.
Abbreviation: idxu

312 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’info [options]’ Returns server information.

Abbreviation: info
The output consists of 25 rows of data.

options are as follows:

v numusers - Number of current users.
v maxusers - Maximum number of users.
v sernum - Server serial number.
v dbsize - Database size (KB).
v logsize - Size of log files (KB).
v uptime - Server startup timestamp.
v bcktime - Timestamp of last successfully completed local backup.
v cptime - Timestamp of last successfully completed checkpoint.
v tracestate - Current trace state - see ADMIN COMMAND ’trace’ for information on
tracing.
v monitorstate - Current monitor state, shown as the number of users who have SQL
monitoring currently enabled (see ADMIN COMMAND ’monitor’ for information on SQL
monitoring).
If all users have SQL monitoring enabled, the value is -1.
v openstate - Current state for accepting connections. Open means that the database
server accepts new connections.
v nummerges - Number of merges.
v numlocks - Number of locks.
v numcursors - Number of open cursors.
v numtransactions - Number of open transactions.
v memtotal - Total amount of allocated memory (bytes).
v dbfreesize - Amount of free space remaining in database (KB).
v dbpagesize - Database page size (KB).
v imdbsize - Amount of space used by in-memory tables (including temporary tables
and transient tables) and the indexes on those tables. The return value is in
kilobytes (KB) and is in the form of a VARCHAR.
v name - Server name. You can set the server name with the solidDB startup option
-n name.
v primarystarttime - The time the Primary role has started.
v secondarystarttime- The time the Secondary role has started.
v dbconfigsize - The configured database size (MB), as set with the
IndexFile.FileSpec parameter.
v dbcreatetime | dbcreationtime - Database creation timestamp.
v processsize | psize - System-level virtual process size (KB).

More than one option can be used per command. Values are returned in the same
order as requested, one row for each value.

Example:
ADMIN COMMAND ’info dbsize logsize’;
RC TEXT
-- ----
0 851968
0 573440
2 rows fetched.

ADMIN COMMAND ’logmessage <string>’ Outputs the user-defined <string> to the message log (solmsg.out).
Abbreviation: logmsg

Appendix F. solidDB ADMIN COMMAND syntax 313

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’logreader stop This command stops the transmission of log records on active log reader connections.
[all|<partition_id>]’
Abbreviation: lr When this command is issued, the active log reader applications reach the end of the
result set (SQLSTATE 0200, No data found) when fetching the next row of the
SYS_LOG table.

If the form LOGREADER STOP or LOGREADER STOP ALL is used, all log record
transmissions are stopped. If a <PARTITION_ID> is given, the command affect only
the log reader operation on that partition.

To access the log again, the application needs to reconnect. The log reading may be
resumed without any loss of information if the last read position is known. If the
SYS_LOG table is accessed without specifying the log position, the reading starts from
the live data.
Important: The stopping of the log transmission is effective immediately, regardless of
the fact that there might be records in the log awaiting transmission.

If the server is running in the relaxed durability mode (default), do not execute
LOGREADER STOP before all the records are written to the log, if those records are
meant to be seen in the log reader. With the default logging settings, it is safe to wait
for 5 seconds after the last write operation.

ADMIN COMMAND ’makecp [-s]’

Abbreviation: mcp Makes a checkpoint.

Only users with SYS_ADMIN_ROLE privilege can execute this command.

By default, the checkpoint is asynchronous. With the option -s, the command returns
only after the checkpoint has completed.

ADMIN COMMAND ’memory’

Abbreviation: mem Returns the server process memory size. The reported process memory size can differ
from the process size reported by your operating system.

ADMIN COMMAND ’messages

[{ warnings | errors}] [count]’ Displays server messages. Optional severity and message numbers can also be
Abbreviation: mes defined. For example:

ADMIN COMMAND 'messages warnings 100' displays last 100 warnings.

ADMIN COMMAND ’monitor Sets server monitoring on and off.

{on | off} [ user
{username | userid}]’ When set to on, user activity and SQL calls are logged into the soltrace.out file.
Abbreviation: mon

ADMIN COMMAND ’netbackup Makes a network backup of the database. The operation can be performed as a
[options] [DELETE_LOGS | synchronized or an asynchronic (default) manner. The synchronized operation is
KEEP_LOGS] [connect specified by using the -s option.
connect str] [dir
backup dir]’ DELETE_LOGS means that backed-up log files in the source server are deleted. This is
Abbreviation: nbak sometimes referred to as full backup. This is the default value.

KEEP_LOGS means that backed-up log files are kept in the source server. This is
sometimes referred to as copy backup. Using KEEP_LOGS corresponds to setting the
General.NetbackupDeleteLog parameter to no.

The default connect string and the default netbackup directory are defined with the
General.NetBackupConnect and the General.NetBackupDirectory parameters.

The options that are entered with this command override the values specified in the
configuration file.

Directory definitions are relative to the solidDB working directory.

ADMIN COMMAND ’netbackuplist’

Abbreviation: nbls Displays a status list of the most recently made network backups of the database
server.

314 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’netstat’ Displays server settings and the network status.
Abbreviation: net

ADMIN COMMAND ’notify This command sends an event to a given user with event identifier NOTIFY. This
user {username | user id | ALL } identifier is used to cancel an event-waiting thread when the statement timeout is not
message’ long enough for a disconnect or to change the event registration.
Abbreviation: not
The following example sends a notify message to a user with user id 5 ; the event
then gets the value of the message parameter.
ADMIN COMMAND ’notify user 5 Canceled by admin’

ADMIN COMMAND ’open’ Opens server for new connections; new connections are allowed.
Abbreviation: ope

ADMIN COMMAND ’parameter Displays and sets server parameter values.

[-r] [-t] [name[=
[*|value][temporary]]’ If you run the command without any options, all parameters are displayed.
Abbreviation: par
The output can contain three columns. For example:
0 PassThrough SqlPassthroughRead Force Conditional None
v First column shows the current value (Force) that might have been changed
dynamically.
v Second column shows the value set in the .ini file at startup. (Conditional)
v Third column shows the factory value. (None)
v -r means that only the current parameter values are returned.
v -t means that the changed value is not stored in the solid.ini file (same as
temporary).
v name may be a section name or a parameter name prefaced by a section name
(section_name.parameter_name). There must be a period between the section name
and the parameter name.
v = [*|value][temporary]
– If you assign a parameter value with an asterisk (*), the parameter will be set to
its factory value.
– If value is not specified, the parameter will be set to its startup value.
– temporary means that the changed value is not stored in the solid.ini file.

For example:
v ’parameter general’ displays all parameters from section [General].
v ’parameter general.readonly’ displays the parameter Readonly in the [General]
section.
v ’parameter com.trace=yes’ sets communication trace on.
v ’parameter com.trace=’ sets communication trace to its startup value.
v ’parameter com.trace=*’ sets communication trace to its factory value.

ADMIN COMMAND ’passthrough status’ Provides the following status information about the SQL passthrough connections:
Abbreviation: pt v NO REMOTE SERVER - no remote server object defined
v NOT CONNECTED - not connected, no errors
v CONNECTED - connected
v LOGIN FAILED - failed at login
v CONNECTION BROKEN - connection broken

Appendix F. solidDB ADMIN COMMAND syntax 315

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’perfmon Returns server performance counters for the past few minutes at approximately one
[- c | - r] [print_options] minute intervals. Most values are shown as the average number of events per second.
[name_prefix_list]’ Counters that cannot be expressed as events per second (for example, database size)
Abbreviation: pmon are expressed in absolute values.
v -c - prints actual counter values for each snapshot.
v -r - prints counter values in raw mode, which includes only the latest counter
values without any formatting. The counter names are not printed. This option is
useful if actual monitoring is performed using some other external program that
retrieves the counter values from the server. You can retrieve the counter names
with the --xnames option.
v print_options
– -xtime - prints the time in seconds
– -xtimediff - prints the difference to the last pmon call in milliseconds
– -xnames - prints out the column names for the output
– -xdiff - indicates the difference to the last ADMIN COMMAND 'perfmon'
execution instead of the absolute value
v name_prefix_list - limits the output to specific counter types, as indicated by the first
word in the counter name. For example, to print all File related counters, the
name_prefix_list should be file. You can also specify multiple prefixes.

The following example returns all information:

ADMIN COMMAND 'perfmon'

The following example returns all values for counters whose name starts with prefix
File and Cache.

ADMIN COMMAND 'perfmon -c file cache'

ADMIN COMMAND ’perfmon diff Starts a server task that prints out all perfmon counters with specified intervals to a
[ start | stop ] file.
[filename][interval]’ v filename is the name of the output file. The performance data is output in
Abbreviation: pmon diff comma-separated value format; the first row contains the counter names, and each
subsequent row contains the performance data per each sampling time.
The default file name is pmondiff.out.
v interval is the interval in milliseconds at which performance data is collected.
The default interval is 1000 milliseconds.

The following command starts a task that outputs performance data to myd.csv file on
500 milliseconds interval:

ADMIN COMMAND 'pmon diff start myd.csv 500'

ADMIN COMMAND ’pid’ Returns server process id.

Abbreviation: pid

316 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’proctrace This turns on tracing in stored procedures and triggers.
{ on | off } user username
{ procedure | trigger | table } username is the name of the user whose procedure calls (or triggers) you want to trace.
entity_name’ If multiple connections are using the same username, calls from all of those
Abbreviation: ptrc connections will be traced. Furthermore, if you are using advanced replication, the
tracing will be done not only for calls on the replica, but also calls that are propagated
to the master and then executed on the master.

entity_nameis the name of the procedure, trigger, or table for which you want to turn
tracing on or off. If you specify a procedure or trigger name, then it will generate
output for every statement in the specified procedure or trigger. If you specify a table
name, then it will generate output for all triggers on that table. Trace is activated only
when the specified username calls the procedure / trigger.

For more details about proctrace, see section Tracing facilities for stored procedures
and triggers in IBM solidDB SQL Guide.

See also ADMIN COMMAND ’usertrace’.

ADMIN COMMAND ’protocols’

Abbreviation: prot Returns a list of available communication protocols, one row for each protocol.

Example (Windows environments):

ADMIN COMMAND ’protocols’;
RC TEXT
-- ----
0 NmPipe np
0 TCP/IP tc
2 rows fetched.

ADMIN COMMAND ’report filename’ Generates a report of server information to a file defined with filename.
Abbreviation: rep

ADMIN COMMAND ’runmerge’ Runs an index merge.

Abbreviation: rm

ADMIN COMMAND ’save parameters Saves the set of current configuration parameter values to a file. If no file name is
[filename]’ given, the default solid.ini file is rewritten. This operation is performed implicitly at
Abbreviation: save each checkpoint.

ADMIN COMMAND Stops solidDB.

’shutdown [force]’
Abbreviation: sd If the force option is used, the active transactions are aborted and the users are
disconnected forcefully.

ADMIN COMMAND ’sqllist This command prints out a list of the longest running SQL statements among the
top number_of_statements’ currently running statements. The list contains the selected number of statements.

ADMIN COMMAND ’startmerge’

Abbrevation: sm Starts and waits for completion of merge.

ADMIN COMMAND ’status’ Displays server statistics.

Abbreviation: sta

ADMIN COMMAND ’status Displays status of the last started local or network backup. The status can be one of
backup | netbackup’ the following:
Abbreviation: sta backup | netbackup v If the last backup was successful or no backups have been requested, the output is
0 SUCCESS.
v If the backup is in process (for example, started but not ready yet), then the output
is 14003 ACTIVE.
v If the backup is being finalized, the output is 14003 STOPPING.
v If the last backup failed, the output is: errorcode ERROR where the errorcode shows
the reason for the failure.

ADMIN COMMAND ’throwout

{username | Exits all or specific users from solidDB. To exit a specified user, give the username or
userid | all}’ user id as an argument. To throw out all users, use the keyword ALL as an argument.
Abbreviation: to

Appendix F. solidDB ADMIN COMMAND syntax 317

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’tid’

Abbreviation: tid This command returns the ID (4-digit code) of the current user thread (in the server).

ADMIN COMMAND ’trace

{ on | off } sql | est | Sets server trace on or off.
estplans | rpc |
sync | flowplans | The name of the default trace file is soltrace.out.
rexec | batch | logreader |
passthrough | xa | hac | The tracing options are:
info <level> | v sql - SQL messages
all | active’
Abbreviation: tra v est - SQL estimator information
v estplans - SQL execution plan
v rpc - Network communications
v sync - synchronization messages
v flowplans - plans of SQL statements related to advanced replication
v rexec - remote procedure call information
v batch - background job and deferred procedure call information
v logreader - logs the following information into the trace file soltrace.out.
– Logreader read started.
– Errors in logreader cursor start. Total of 14 different error conditions are printed.
– Logreader read stopped.
– Abnormal read stop after certain system changes.
– High level information of number of returned log records and read progress.

Each information is tagged with user id so operations from different users can be
separated.
v passthrough - provides tracing information about the SQL passthrough connections
and the loading of the ODBC driver as follows:
– Loading of the ODBC driver: driver name and status of the load
– Status of connections to the back-end: connect/reconnect/disconnect/broken
v xa - distributed transaction information
v hac - High Availability Controller (HAC); trace information is output to
hactrace.out in the HAC working directory
Note: To start tracing on HAC, you must issue the command on a HAC
connection. For example, connect to HAC with solsql using the port defined with
the HAController.Listen parameter in the solidhac.ini configuration file.
v info <level> - SQL execution trace (level can be 0...8)
v all - both SQL messages and network communications messages are written to the
trace file.
v active - lists all active traces

ADMIN COMMAND ’tracemessage <string>’ Outputs the user-defined <string> to the trace message log (soltrace.out).
Abbreviation: trcmsg

ADMIN COMMAND ’userid’ Returns the user identification number of the current connection.
Abbreviation: uid
The lifetime of an Id is that of the user session. After a user logs out, the number may
be reused.
ADMIN COMMAND ’userid’
RC TEXT
-- ----
0 8
1 rows fetched.

For example, the userid can be used in the ADMIN COMMAND 'throwout' command to
disconnect a specific user.

318 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’userlist [-l] This command displays a list of users that are currently logged into the database, as
[name | id]’ well as information about various database operations and settings for each user. The
Abbreviation: ul option -l (long) displays a more detailed output.

Without the -l option, the following information is displayed: User name, User Id,
Type, Machine Id, Login time, Client version, and Appinfo (if available).

With the -l option, the following information is displayed:

v Id - The user session identification number (userid) within the database. The
lifetime of the userid is that of the user session. After the user logs out, the number
can be reused.
v Type - Client type. Possible values are:
– Java, which refers to a client using JDBC
– ODBC, which refers to a client using ODBC
– SQL, which refers to solidDB SQL Editor (solsql)
v Client version - The version of the JDBC or ODBC client, as of V6.5.0.10 Fix Pack
10.
Note:
– The client version information is not available for clients prior to V6.5.0.10 or for
solidDB Remote Console (solcon) connections.
– For solidDB SQL Editor (solsql) connections, the ODBC client version is shown.
v Machine - The client computer name (host name) and its IP address, if available
v Login tile - The client computer login timestamp
v Appinfo - The value of the client computer's environmental variable SOLAPPINFO
(ODBC), or the value of JDBC connection property solid_appinfo.
v Last activity - The time when the client last time sent a request to the server.
v Autocommit - Value 0 means that the autocommit mode is switched off; the current
transaction is open until a COMMIT or ROLLBACK statement is issued.
Value 1 means that the autocommit mode is switched on; each statement is
automatically committed.
v RPC compression - Indicates whether the data transmission compression is on or off.
v Transparent failover - This field indicates if Transparent Failover (TF) is in use
(HotStandby configurations). Because solidDB tools do not support TF, you will
only see a "no" value in this field when using solsql or solcon.
v Transparent cluster - Transparent cluster indicates whether the load balancing feature
(in HSB) is enabled for this connection or not.
v Transaction active - This field indicates whether there is an open, uncommitted
transaction on the connections (value 1) or not (value 0). When the connection is set
for Autocommit, the value is, most of the time, 0.
v Transaction duration - This field indicates the duration of the currently open
transaction. After COMMIT or ROLLBACK, the value becomes 0.
v Transaction isolation - This field indicates the transaction isolation level for the
transactions. The isolation level decides how data which is a part of an ongoing
transaction is made visible to other transactions.
v Transaction durability - This field indicates the durability of the currently open
transaction.
v Transaction safeness - This field indicates the safeness of the currently open
transaction (set with HotStandby.SafenessLevel).
v Transaction autocommit - This field indicates whether the currently open transaction
is automatically committed. If the transaction autocommit for the current
transaction is switched off (value 0), the current transaction is open until a
COMMIT or ROLLBACK statement is issued. After that, a new statement starts a
new transaction.
If the autocommit mode is switched on for the current transaction (value 1), each
statement is automatically committed.

Appendix F. solidDB ADMIN COMMAND syntax 319

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

..continued.. v Current catalog - Indicates the current catalog name.
ADMIN COMMAND ’userlist [-l] v Current schema - Indicates the current schema name.
[name | id]’
Abbreviation: ul v Sortgroubby - Indicates how the GROUP BY statement is performed if explicit
information about the number of result groups is not available. There are two
possible values:
– ADAPTIVE - GROUP BY input is pre-sorted if the real number of result groups
exceeds the number of rows that fit into the central memory array for GROUP BY.
–
STATIC - GROUP BY input is pre-sorted whenever there are at least two items in
the GROUP BY list. Otherwise, the GROUP BY input is not pre-sorted.
v Simple optimizer rules - Indicates whether simple optimizer rules are in use
(SQL.SimpleOptimizerRules) Possible values are Yes/No/Default.
v Statement max time - Indicates the connection-specific statement maximum
execution time in seconds. This setting is effective until a new maximum time is
given. Zero time indicates that there is no maximum time. This is the default value.
v Lock timeout - Indicates the timeout set by using the SET LOCK TIMEOUT statement.
v Optimistic lock timeout - Indicates the timeout set by using the SET OPTIMISTIC LOCK
TIMEOUT statement.
v Idle timeout - Indicates the timeout set by using the SET IDLE TIMEOUT
statement.
v Join Path Span - Indicates the join path span value set by using the SET SQL
JOINPATHSPAN statement.
v RPC seqno - Internal protocol message sequence number.
v SQL sortarray - The size of user-specific internal sort array.
v SQL unionsfromors - The value tells how many (at most) OR operators may be
converted to UNIONs. Unions are faster but require more memory to execute.
v EVENT QUEUE LENGTH - Indicates the number of posted events in the event
queue.
v Connection idle timeout - Indicates the connection idle timeout setting
v Stmt id - The current statement identification number. The numbers are session
specific and they are assigned for each different statement.
v Stmt state - An internal statement execution state.
v Stmt rowcount - The number of rows retrieved or inserted in the current statement.
v Stmt start time - The current statement start date and time.
v Stmt last activity time -
v Stmt duration - Internal statement duration in seconds. Note: this value has no
relevance to the externally visible statement latency. Typically, the statement
duration is much longer than latency.
v Stmt SQL str - The current SQL statement string.

320 IBM solidDB: Administrator Guide

Table 95. ADMIN COMMAND syntax and options (continued)

Option syntax Description

ADMIN COMMAND ’usertrace This turns on user tracing in stored procedures and triggers. This command will
{ on | off } user username generate output for every WRITETRACE statement in the specified procedure or
{ procedure | trigger | table } trigger.
entity_name’ v username is the name of the user whose procedure calls (or triggers) you want to
Abbreviation: utrc trace. If multiple connections are using the same username, then calls from all of
those connections will be traced. Furthermore, if you are using advanced
replication, the tracing will be done not only for calls on the replica, but also calls
that are propagated to the master and then executed on the master.
v entity_name is the name of the procedure, trigger, or table for which you want to
turn tracing on or off. If you specify a table name, it will generate output for all
triggers on that table. Trace is activated only when the specified user calls the
procedure / trigger.

For more details about usertrace, see section Tracing facilities for stored procedures
and triggers in IBM solidDB SQL Guide.

See also ADMIN COMMAND 'proctrace'.

ADMIN COMMAND ’version’ Displays server version information and information related to the solidDB software
Abbreviation: ver license in use.

Appendix F. solidDB ADMIN COMMAND syntax 321

322 IBM solidDB: Administrator Guide
Index
Special characters ADMIN COMMAND (continued)
version 321
-x autoconvert (command line option) 222 ADMIN COMMAND 'perfmon'
-x convert (command line option) 222 server performance 67
@ ADMIN COMMAND 'report report_filename'
AT (@) sign 99 producing a report for troubleshooting 67
ADMIN COMMAND 'status backup'
querying last backup status 66
A ADMIN COMMAND 'status'
abnormal shutdown 35 querying database status 65
AbortTimeOut (parameter) 201 ADMIN COMMAND 'throwout' 14
AdaptiveRowsPerMessage (parameter) 201 disconnecting users 66
ADMIN COMMAND ADMIN COMMAND 'userlist'
abort 310 querying for connected users 66
assertexit 310 administering
backgroundjob 310 multiple servers manually 5
backup 311 AllowConnect (parameter) 201
backuplist 311 AllowDuplicateIndex (parameter) 197
checkpointing 311 ANSI (reserved word) 106
cleanbgjobinfo 311 architecture
close 311 multithread processing 8
commands 309 at commands 36
describe 311 AuditTrailEnabled (parameter) 27, 197
errorcode 311 autocommit 134
errorexit 311 autoconvert
filespec 312 command line option 222
help 312 automating administrative tasks 5, 36
hotstandby 312
indexusage 312
info 313 B
info processsize 127 B-tree 5
logreader 314 backup 31
makecp 314 automating 36
memory 314 configuring and automating 30
messages 314 failed 33
monitor 314 local 28
netbackup 314 manual 27
netbackuplist 314 monitoring and controlling 33
netstat 315 network backup 28
notify 315 network backup, server administration 32
open 315 querying 66
parameter 315 restoring 34
passthrough status 315 timed commands 36
perfmon 316 typical problems 34
perfmon diff 316 BackupBlockSize (parameter) 168
pid 316 BackupCopyIniFile (parameter) 168
proctrace 317 BackupCopyLog (parameter) 169
protocols 317 BackupCopySolmsgOut (parameter) 169
runmerge 317 BackupDeleteLog (parameter) 169
save parameters 317 BackupDirectory (parameter) 169
shutdown 317 BackupFlushInterval (parameter) 169
sqllist 317 BackupStepsToSkip (parameter) 169
startmerge 317 bcktime ADMIN COMMAND 313
status 317 BLANKS
syntax 309 solidDB Speed Loader 107
throwout 317 BLOBs (Binary Large Objects) 6, 20
tid 318 defining 20
trace 318 BlockSize (parameter) 19, 182, 184, 196
userid 318 Bonsai Tree 5, 132, 134
userlist 319, 320 index compression 6
usertrace 321 multiversioning 6

323
C connecting to solidDB
basics 20
cache (disk-based) 129 login 20
CacheSize (parameter) 55, 182 ConnectionCheckInterval (parameter) 202
CAST (function) 268 connections
catalogs committed transactions 135
name criteria 15 determining existing 134
CHARACTERSET keyword (solload) 108 ConnectStrForMaster (parameter) 214, 285
CharPadding (parameter) 197 ConnectTimeOut (parameter) 202, 219
checkpoint control file (solidDB Speed Loader)
'makecp' command 314 description 100
CheckpointDeleteLog (parameter) 170 syntax 106
CheckpointInterval (parameter) 133, 170 convert
checkpoints 36 command line option 222
automatic daemon 36 converting database format 222
automating 36 ConvertOrsToUnionsCount (parameter) 198
erasing automatically 36 counters 68
forcing 133 cptime ADMIN COMMAND 313
frequency 133 creating
timed commands 36 checkpoints 36
tuning 133 CursorCloseAtTransEnd (parameter) 198
client-side configuration parameters 217
ClientReadTimeout (parameter) 218
closing solidDB 14
ADMIN COMMAND 14 D
clustering D-table 6
data clustering 6 database
columns automating 36
setting LONG VARCHAR 20 backing up 27
command line options 221 block size 19
COMMIT WORK statement cache 129
application code 135 changing dynamically 129
troubleshooting 135 size 129
communication checking last backup status 66
between client and server 81 checking overall status 65
selecting a protocol 87 closing 13, 36
tracing problems 144 compacting 37
communication protocols 87 configuring 44
Named Pipes 90 converting format 222
selecting 87 creating 15
summary 91 creation time 313
supported protocols 87 currently connected users 66
TCP/IP 88 decreasing database file size 53
UNIX Pipes 89 defining objects 20
communication session layer disconnecting a user 66
description 8 file size
communication tracing 57 decreasing 53
configuration file free space in 313
description 19 in-memory 44
server-side 44 index file 53
setting 49 location 19, 53
solidDB Speed Loader 119 login 12
configuring maximum size 19
client-side configuration file 44 monitoring 67
configuration file 44 opening 36
default settings 44 performance 67
example 44 querying last backup 66
factory values 44 recovery 35
managing parameters 44, 45, 46 restoring master and replica 27
parameter settings 44 several databases on one computer 24
server-side configuration file 44 shutting down 14
setting parameters 45, 47 size 15, 53
solid.ini 44 troubleshooting 67
viewing parameter descriptions 46 using in-memory database 131
viewing parameters 44, 45 database mode
Connect (parameter) 58, 219 partial Unicode 16
connect string 58 Unicode 16
clients 84 DatabaseSizeReportInterval (parameter) 203

324 IBM solidDB: Administrator Guide

DataDictionaryErrorMaxWait (parameter) 171 error handling (continued)
DATE data type sorter errors 269
Speed Loader 108 Speed Loader errors 307
dbconfigsize ADMIN COMMAND 313 SQL API errors 287
dbcreatetime ADMIN COMMAND 313 SQL errors 300
dbfreesize ADMIN COMMAND 313 SRV errors 289
dbpagesize ADMIN COMMAND 313 synchronization errors 271
dbsize ADMIN COMMAND 313 system errors 229
DecFloatPrecision16 (parameter) 198 TAB messages 299
DecimalPrecAsNumeric (parameter) 171 table errors 241
decrypting databases 41 XS errors 298
DefaultStoreIsMemory (parameter) 171 events
DigitTemplateChar (parameter) 184 soldd and listing event definitions 118
DirectIO (parameter) 182, 184 ExecRowsPerMessage (parameter) 203, 217
DisableIdleMerge (parameter) 171 ExecuteNodataODBC3Behaviour (parameter) 198
DisableOutput (parameter) 63, 203 executing
disconnecting users 14 system commands, automated 36
durability execution graph 7
relaxed 123 ExtendIncrement (parameter) 132, 182
strict 123 external sorting 130
DurabilityLevel (parameter) 185

F
E file locations 17
Echo (parameter) 203 file system 17
EmulateOldTimestampDiff (parameter) 198 FileFlush (parameter) 185
EnableHints (parameter) 198 FileNameTemplate (parameter) 56, 186
ENCLOSURE (solidDB Speed Loader) 109 FileSpec (parameter) 19, 53
encryption FileWriteFlushMode (parameter) 171
DES ForceThreadsToSystemScope (parameter) 204
changing password 40 free space in database 313
creating 39
decrypting 41
enabling 39
password 40
H
HealthCheckEnabled (parameter) 204
starting encrypted database 40
HealthCheckInterval (parameter) 204
disabling 39
HealthCheckTimeout (parameter) 204
level 41
overview 38
entering timed commands 36
environment variables I
SOLTRACE 144 I/O
SOLTRACEFILE 144 distributing 132
error codes tuning 132
error handling 227 IBMPC (reserved word) 106
error handling IgnoreOnDisabled (parameter) 193
AT messages 293 ImdbMemoryLimit (parameter) 189
BCKP messages 293 ImdbMemoryLowPercentage (parameter) 190
COM messages 288 ImdbMemoryWarningPercentage (parameter) 190
communication errors 257 imdbsize ADMIN COMMAND 313
CP messages 293 ImplicitStart (parameter) 165
database errors 232 import file (solidDB Speed Loader) 101
DBE errors 291 index file
error codes 227 splitting to multiple disks 53
executable errors 306 Info (parameter) 199
FIL messages 298 InfoFileFlush (parameter) 199
HotStandby errors 286 InfoFileName (parameter) 199
HSB errors 295 InfoFileSize (parameter) 199
INI messages 294 InifileLineSplitting 205
LOG messages 294 intelligent join constraint transfer 7
passthrough errors 299 InternalCharEncoding (parameter) 172
procedure errors 266 INTO_TABLE_PART
RPC errors 270 solidDB Speed Loader 109
SA API errors 269 IOThreads (parameter) 172
server errors 260 isolation levels
SMA errors 299 read committed 125
SNC errors 297 repeatable read 125

Index 325
isolation levels (continued) MaxNestedProcedures (parameter) 200
serializable 125 MaxNestedtriggers (parameter) 200
IsolationLevel (parameter) 199 MaxOpencursors (parameter) 207
MaxOpenFiles (parameter) 174
MaxPhysMsgLen (parameter) 166
J MaxRPCDataLen (parameter) 207
MaxSharedMemorySize (parameter) 195
JDBC 2, 3
MaxSpace (parameter) 187, 188
MaxStartStatements (parameter) 207
MaxTransactionSize (parameter) 191
K MaxUsers (parameter) 207
KeepAllOutFiles (parameter) 205 maxusers ADMIN COMMAND 313
MaxWriteConcurrency (parameter) 175
memory
L physical 128
tuning 126
Latin1CaseSemantics (parameter) 199
virtual 128
Listen (parameter) 166
MemoryPoolScope (parameter) 192
listen name 81, 84
MemoryReportDelta (parameter) 207
listing users 320
MemoryReportLimit (parameter) 208
local backup 28
MemorySizeReportInterval (parameter) 208
LocalStartTasks (parameter) 205
memtotal ADMIN COMMAND 313
LockEscalationEnabled (parameter) 190
MergeInterval (parameter) 132, 175
LockEscalationLimit (parameter) 190
message log 63
LockHashSize (parameter) 173, 191
MessageLogSize (parameter) 208
LockWaitTimeOut (parameter) 174
MinCheckpointTime (parameter) 133, 175
log files
MinMergeTime (parameter) 175
overview 35
MinSplitSize (parameter) 187
solerror.out 63
monitoring 63
solmsg.out 63
monitorstate ADMIN COMMAND 313
Speed Loader 101
MSWINDOWS (reserved word) 106
LogDir (parameter) 186
MultiprocessingLevel (parameter) 175
LogEnabled (parameter) 186
multithread processing
logging
description 8
transaction durability 123
transactions 35
logical data source names
defining in solid.ini 86 N
login Name (parameter) 208
description 12 name ADMIN COMMAND 313
incorrect username or password 12 Named Pipes 90
LogReaderEnabled (parameter) 187 netbackup 29
logsize ADMIN COMMAND 313 NetBackupConnect (parameter) 175
LogWriteMode (parameter) 186 NetBackupConnectTimeout (parameter) 176
LongSequentialSearchLimit (parameter) 174 NetBackupCopyIniFile (parameter) 176
NetBackupCopyLog (parameter) 176
NetBackupCopySolmsgOut (parameter) 176
M NetBackupDeleteLog (parameter) 176
NetBackupDirectory (parameter) 176
M-tables 6
NetBackupDirectory (parameters) 56
makecp 133
NetBackupReadTimeout (parameter) 176
manual administration 5
NetBackupRootDir (parameter) 208
master database
network backup
backing up 27
directory 56
restoring 27
overview 28
MasterStatementCache (parameter) 214
network communication
MaxBgTaskInterval (parameter) 206
communication session layer 8
MaxBlobExpressionSize (parameter) 20, 200
network services 8
MaxBytesCachedInPrivateMemoryPool (parameter) 191
tracing 57
MaxCacheUsage (parameter) 191
troubleshooting 162
MaxCacheUsePercent (parameter) 196
network messages
MaxConstraintLength (parameter) 207
tuning 131
MaxFilesTotal (parameter) 196
network names 81, 84
MaxLogSize (parameter) 187, 188
adding 84
MaxMemLogSize (parameter) 187, 189
clients 84
MaxMemPerSort (parameter) 196
defining 53, 58
MaxMergeParts (parameter) 174
modifying 84
MaxMergeTasks (parameter) 174
Named Pipes 90

326 IBM solidDB: Administrator Guide

network names (continued) passthrough
removing 84 errors 299
TCP/IP 88 PassthroughEnabled (parameter) 193
UNIX Pipes 89 passwords
viewing 83 criteria 15
network services maximum number of characters 15
description 8 PCOEM (reserved word) 106
network trace facility 144 performance
nmp 90 counters 68
nmpipe 90 diagnosing problems 136
NoAssertMessages (parameter) 217 snapshot of 67
non-graphical user interfaces tuning 123, 136
creating new database 15 performing batch mode operations 5
NULLIF Pessimistic (parameter) 176
Speed Loader 107, 113 PessimisticTableUseNFetch (parameter) 209
NULLSTR phantom 125, 126
solidDB Speed Loader 107 updates
NumberOfMemoryPools (parameter) 192 repeatable read 125
numcursors ADMIN COMMAND 313 serializable 126
NumericPadding 200 physical memory 128
numlocks ADMIN COMMAND 313 ping facility 145
nummerges ADMIN COMMAND 313 POSITION
numtransactions ADMIN COMMAND 313 solidDB Speed Loader 113
numusers ADMIN COMMAND 313 PreFlushPercent (parameter) 183
PRESERVE BLANKS
solidDB Speed Loader 109
O primarystarttime ADMIN COMMAND 313
PrintMsgCode (parameter) 63, 209
ODBC
problem determination
Connect parameter 58
troubleshooting 139
connect string 58
procedure errors 266
overview 2
ProcedureCache (parameter) 200
ODBCCharBinding (parameter) 218
process size
ODBCDefaultCharBinding (parameter) 209
controlling 126
ODBCHandleValidation (parameter) 218
elements 126
open ADMIN COMMAND 14
ProcessMemoryCheckInterval (parameter) 127, 128, 210
openstate ADMIN COMMAND 313
ProcessMemoryHysteresisPercentage (parameter) 210
operating system
ProcessMemoryLimit (parameter) 127, 128, 210
tuning 128
ProcessMemoryLowPercentage (parameter) 128, 211
optimizer hints 8
ProcessMemoryWarningPercentage (parameter) 128, 211
processsize ADMIN COMMAND 313
programming interfaces 2
P proprietary interfaces 3
parameters 165 psize ADMIN COMMAND 313
BlockSize 19
CacheSize 55
CheckpointInterval 133
client-side 217
Q
query processing
Connect 58
description 7
ExtendIncrement 132
querying database
FileNameTemplate 56
ADMIN COMMAND 'status' 65
FileSpec 19, 53
format 52
MaxBlobExpressionSize 20
MergeInterval 132 R
MinCheckpointTime 133 RConnectLifetime (parameter) 166
NetBackupDirectory 56 RConnectPoolSize (parameter) 167
ProcessMemoryCheckInterval 127, 128 RConnectRPCTimeout (parameter) 167
ProcessMemoryLimit 127, 128 READ COMMITTED 215
ProcessMemoryLowPercentage 128 ReadAhead (parameter) 183
ProcessMemoryWarningPercentage 128 ReadBufSize (parameter) 167
setting 132 ReadLevelMaxTime (parameter) 177
SortArraySize 130 ReadMostlyLoadPercentAtPrimary (parameter) 166
Threads 57 Readonly (parameter) 177
Trace 58, 60 ReadThreadMode (parameter) 211
TraceFile 58 recovery 123
partial Unicode database mode 16 automatic roll-forward 27

Index 327
ReferenceCacheSizeForHash (parameter) 184 solidDB (continued)
RefreshIsolationLevel (parameter) 215 executable program 11
RefreshReadLevelRows (parameter) 215 processes 1
relaxed durability 123 starting 11
RelaxedMaxDelay (parameter) 187 solidDB AT messages 293
ReleaseMemoryAtShutdown (parameter) 192 solidDB BCKP messages 293
RemoteServerDriverPath (parameter) 193 solidDB Bonsai Tree 134
RemoteServerDSN (parameter) 193 concurrency 6
RemoteStartTasks (parameter) 212 multiversion 6
REPEATABLE READ 215 reducing size 134
replica databases solidDB COM (communication) messages 288
backing up 27 solidDB communication errors 257
restoring 27 solidDB CP messages 293
ReplicaRefreshLoad (parameter) 215 solidDB Data Dictionary 116
ReportInterval (parameter) 212 starting 117
reports solidDB data management tools
automating 36 overview 93
creating a continuous performance monitoring report 68 solcon 93
creating a report for troubleshooting 67 soldd 93
creating a status report 67 solexp 93
full list of perfmon counters 68 solload 93
RestoreThreads (parameter) 192 solidDB database errors 232
Restoring backups 34 solidDB DBE errors 291
roles solidDB executable
database administration 11 -x execute command line option 122
roll-forward recovery 27 command line options 221
RowsPerMessage (parameter) 212, 218 errors 306
RPC 8 solidDB Export 114
RpcEventThresholdByteCount (parameter) 215 starting 114
running several servers 24 solidDB FIL messages 298
solidDB HotStandby errors 286
solidDB HSB errors 295
S solidDB INI messages 294
solidDB JDBC Driver
SA API 3
troubleshooting 161
SCAND7BIT (reserved word) 106
solidDB LOG messages 294
scripts
solidDB ODBC Driver
calling 99
troubleshooting 160
executing SQL script from file 99
solidDB Remote Control (solcon) 93
SearchBufferLimit (parameter) 177
commands 95
secondarystarttime ADMIN COMMAND 313
starting 94
sernum ADMIN COMMAND 313
solidDB RPC errors 270
server errors 260
solidDB SA API errors 269
server names
solidDB server shortcut (Windows) 13
network names 81
solidDB session errors 256
server-side configuration parameters 165
solidDB SMA errors 299
SharedMemoryAccessRights (parameter) 195
solidDB SNC errors 297
shortcut (Windows)
solidDB Speed Loader
server 13
control file 100
solsql 13
control file syntax 106
shutdown 14
description 100
Silent (parameter) 189, 212
errors 307
SimpleOptimizerRules (parameter) 200
import file 101
SocketLinger (parameter) 167, 219
ini file 119
SocketLingerTime (parameter) 167, 219
log file 101
soldd 116, 117
solidDB SQL
solerror.out
errors 300
description 63
troubleshooting 160
solexp 114
solidDB SQL API Errors 287
solid.ini
solidDB SQL Editor 95
configuration parameters 165, 217
executing SQL statements 98
configuring solidDB 43
starting 96
description 19
solidDB SQL Editor (solsql) shortcut (Windows) 13
solidDB
solidDB SQL optimizer
administering solidDB 11
description 7
command line options 221
solidDB SRV errors 260, 289
components 1
solidDB TAB messages 299
connecting to 20

328 IBM solidDB: Administrator Guide

solidDB XS errors 298 thread 8
solload 100, 101 dedicated 9
solloado 100, 101 general purpose 9
solmsg.out 20 setting for processing 57
description 63 types of 9
SolmsgBackupFileNum (parameter) 212 Threads (parameter) 57, 213
SOLTRACE environment variable 144 throwing out users
SOLTRACEFILE environment variable 144 automating 36
SortArraySize (parameter) 130, 200 throwout 66
sorter errors 269 throwout all 14
SorterEnabled (parameter) 196 TIME
sorting 130 solidDB Speed Loader 108
space ADMIN COMMAND 313 timed commands 36
SQL trace level and backups 36
setting 57 and checkpoints 36
SQL-89 3 at 36
SQL-92 3 TIMESTAMP
SQL-99 3 solidDB Speed Loader 108
SQLInfo (parameter) 201 TimestampDisplaySize19 (parameter) 201
SqlPassthroughRead (parameter) 193 TmpDir_[1... N ] (parameter) 197
SqlPassthroughWrite (parameter) 193 Trace (parameter) 58, 60, 168, 219
SSC API (Control API) 3 trace files 64
StackTraceEnabled (parameter) 213 description 63
StandardDateTimeFormat (parameter) 213 TraceBackupFileNum (parameter) 213
starting TraceFile (parameter) 58, 168, 219
solidDB 11 TraceLogSize (parameter) 214
solidDB Remote Control 94 TraceSecDecimals (parameter) 214
solidDB SQL Editor 96 tracestate ADMIN COMMAND 313
StartupForceMerge (parameter) 177 tracing communication 144
StatementCache (parameter) 218 Tracing Failed Login Attempts 64
StatementMemoryTraceLimit (parameter) 213 Transaction Logging 35
storage tree Overwriting 35
description 6 Ping-pong 35
strict durability 123 TransactionEarlyValidate (parameter) 178
supported protocols 83 TransactionHashSize (parameter) 178
synchronization errors 271 transactions
SynchronizedWrite (parameter) 184 committing to reduce Bonsai Tree size 134
SyncWrite (parameter) 187 logging 35
syntax logs
ADMIN COMMAND 309 specifying directory 56
Syntax Analysis tries 7
description 7 TriggerCache (parameter) 201
SYS_ADMIN_ROLE troubleshooting
for database administration 11 systematic problem solving 139
SYS_AUDIT_TRAIL 27 tuning
SYS_CONSOLE_ROLE 11 checkpoints 133
SYS_R_MAXBYTES_IN (parameter) I/O 132
description 280 memory allocation 126
SYS_R_MAXBYTES_OUT (parameter) network messages 131
message length 280 operating system 128
SYS_SYNC_ADMIN_ROLE
for database administration 11
SYS_SYNC_REGISTER_ROLE
for database administration 11
U
Unicode
system errors 229
database mode 16
UNIX Pipes 89
UpCaseQuotedIdentifiers (parameter) 201
T uptime ADMIN COMMAND 313
table errors 241 UseEncryption (parameter) 178, 218
TableLockWaitTimeout (parameter) 177 userlist ADMIN COMMAND 319, 320
TCP/IP 3, 88 usernames
TcpKeepAlive (parameter) 167 criteria 15
TcpKeepAliveIdleTime (parameter) 167 default 15
TcpKeepAliveProbeCount (parameter) 168 maximum number of characters 15
TcpKeepAliveProbeInterval (parameter) 168 users
TERMINATION throwing out 36
solidDB Speed Loader 112

Index 329
V
VersionedPessimisticReadCommitted (parameter) 178
VersionedPessimisticRepeatableRead (parameter) 178
virtual memory 128

W
Windows shortcuts 13
working directory 17
WriteBufSize (parameter) 168
WriterIOThreads (parameter) 178

330 IBM solidDB: Administrator Guide

Notices
© Copyright Oy International Business Machines Ab 1993, 2012.

All rights reserved.

No portion of this product may be used in any way except as expressly authorized
in writing by Oy International Business Machines Ab.

This product is protected by U.S. patents 6144941, 7136912, 6970876, 7139775,

6978396, 7266702, 7406489, 7502796, and 7587429.

This product is assigned the U.S. Export Control Classification Number

ECCN=5D992b.

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan Ltd.
1623-14, Shimotsuruma, Yamato-shi
Kanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law: INTERNATIONAL
BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS"
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE. Some states do not allow disclaimer of express or implied warranties in
certain transactions, therefore, this statement may not apply to you.

331
 This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the publication. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it
believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact:

IBM Canada Limited

Office of the Lab Director
8200 Warden Avenue
Markham, Ontario
L6G 1C7
CANADA

Such information may be available, subject to appropriate terms and conditions,

including in some cases, payment of a fee.

The licensed program described in this document and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement or any equivalent agreement
between us.

Any performance data contained herein was determined in a controlled

environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of

those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the

332 IBM solidDB: Administrator Guide

names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which

illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. The sample
programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:

© your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs.

© Copyright IBM Corp. _enter the year or years_. All rights reserved.

If you are viewing this information softcopy, the photographs and color
illustrations may not appear.

Trademarks

IBM, the IBM logo, ibm.com, Solid, solidDB, InfoSphere, DB2, Informix®, and
WebSphere® are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and
service names might be trademarks of IBM or other companies. A current list of
IBM trademarks is available on the Web at “Copyright and trademark information”
at www.ibm.com/legal/copytrade.shtml.

Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.

Linux is a registered trademark of Linus Torvalds in the United States, other

countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United

States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Other product and service names might be trademarks of IBM or other companies.

Notices 333
334 IBM solidDB: Administrator Guide



Printed in USA

SC23-9869-05