baan iv · pdf filei db2/nt database driver technical reference manual for baan iv 1...

Baan IVDB2/NT Database Driver Technical ReferenceManual for Baan IV

A publication of:

Baan Development B.V.P.O.Box 1433770 AC BarneveldThe Netherlands

Printed in the Netherlands

© Baan Development B.V. 1998.All rights reserved.

The information in this documentis subject to change withoutnotice. No part of this documentmay be reproduced, stored ortransmitted in any form or by anymeans, electronic or mechanical,for any purpose, without theexpress written permission ofBaan Development B.V.

Baan Development B.V.assumes no liability for anydamages incurred, directly orindirectly, from any errors,omissions or discrepanciesbetween the software and theinformation contained in thisdocument.

Document Information

Code: U7184B USGroup: User DocumentationEdition: BDate: December, 1998

i

DB2/NT Database Driver Technical Reference Manual for Baan IV

1 Introduction 1-1The Baan IV architecture 1-1Display tier 1-2Application tier 1-2Database tier 1-3Data flow through the Baan IV architecture 1-4Baan IV hardware configurations 1-5

2 Baan IV database organization 2-1Baan IV data dictionary 2-1Table naming convention 2-2Column naming convention 2-3Index naming convention 2-4Data type mapping 2-5Additional constraints 2-6

3 Database driver internal processing 3-1Data integrity 3-1Referential integrity 3-1Data buffering 3-1Database driver SQL processing 3-2Call level interface 3-2SQL processing 3-3Setting driver behavior 3-4Driver resources 3-4Environment variables 3-5Storage file 3-7

4 Database security 4-1Security 4-1Groups 4-1Object security 4-2Authentication 4-4DBA module 4-5

Table of contents

Table of contents


ii

5 Database driver profiling and statistics 5-1Profiling 5-1Gathering statistics 5-3Troubleshooting 5-5Logging database driver trace information 5-5Logging errors 5-6

6 Database driver configuration and tuning 6-1Cursor management 6-1Array interface 6-1Index optimization 6-2Indexes that allow duplicate values 6-4Hash column naming convention 6-4Size of hash columns 6-5Specifying index optimization 6-5Fetch optimization 6-6Row caching 6-7Optimistic and pessimistic reference checks 6-8Locking behavior 6-8

7 DB2 configuration and tuning 7-1DB2 tuning 7-1Database manager configuration tuning 7-1Database configuration tuning 7-1Tuning for faster data loading 7-5Disk I/O configuration and data placement 7-5

8 Appendix A: Database driver resources and environment variables 8-1Summary of DB2 resources and environment variables 8-1Detailed description of DB2 resources and environment variables 8-4Generic driver resources 8-4DB2 driver specific resources 8-13DB2 environment variables 8-19

9 Appendix B: Storage file format and configuration options 9-1Storage file format 9-1Storage file field descriptions 9-2


iii

This document supplies technical reference information about the Baan IVdatabase driver for DB2. This document is intended for those who wish toconfigure or customize the Baan IV database driver for DB2. An elementaryknowledge of Windows NT and DB2 is assumed. An understanding of databasetechnology is also assumed.

The procedure for installing the DB2 and Baan IV software is described in theDB2 Guide for Baan IV on Windows NT.

This document describes the Baan IV database driver that forms the interfacebetween the Baan IV application server layer and DB2. The formal name for thisdatabase driver is the Baan IV database driver for DB2. For simplicity, thedatabase driver is referred to as the Baan IV DB2 driver.

The document is divided into the following seven chapters and two appendices:

Chapter 1 provides an overview of the Baan IV database driver architecture andhow the database driver fits within the Baan IV system.

Chapter 2 describes the Baan IV database organization and details the namingconventions used for data and objects within the DB2 database.

Chapter 3 describes some of the internal features of the Baan IV DB2 databasedriver.

Chapter 4 describes several aspects of database security provided by the Baan IVDB2 database driver.

Chapter 5 describes the facilities for profiling and gathering statistics aboutdatabase driver performance.

Chapter 6 details the configuration and tuning options for the Baan IV DB2database driver.

Chapter 7 details the configuration and tuning options for the DB2 databaseserver.

Appendix A supplies information about the variables that can be configured forthe database driver.

Appendix B contains information about the file format of the storage file and thedriver configuration options specific to the Baan IV DB2 database driver.

About this document

About this document


iv


1-1

The database driver plays an important role in Baan’s commitment to an opensystems client/server architecture. Because the Baan IV architecture includesboth the Baan IV software and a third party relational database managementsystem (RDBMS), the driver is needed to provide a seamless interface betweenthe Baan IV software and the different RDBMS products. The database driverallows the majority of the Baan IV processing to be independent of the RDBMS.This chapter provides an overview of the database driver and how it fits into theBaan IV architecture.

The following topics are covered in this chapter:

n The Baan IV architecturen Data flow through the Baan IV architecturen Baan IV hardware configurationsn Baan IV hardware configurations

The Baan IV architectureBaan IV supports a three-tier architecture consisting of a display tier, anapplication tier, and a database tier. The display tier provides presentationservices for user interaction. The application tier consists of the Baan IVapplication virtual machine and the application objects. The database tierincludes the Baan IV database driver and a third party RDBMS product that actsas the database server. Figure 1 depicts the Baan IV architecture.

The emphasis of this document is the Baan IV database driver. The databasedriver is the interface between the Baan IV applications and the RDBMS server.The database driver translates database requests from the Baan IV applicationvirtual machine to RDBMS specific SQL requests that it sends to the databaseserver. After the database server retrieves the requested information, the databasedriver then passes the data back to the Baan IV application virtual machine.

1 Introduction

Introduction


1-2

To put the functions of the database driver into perspective, each of the threetiers of the total Baan IV architecture is described briefly.

ApplicationVirtual Machine

(bshell)

Display Tier

Application Tier

Database Tier

Database Driver

Display Driver

Application Objects

Database Server(RDBMS)

Figure 1, Baan IV three-tier architecture

Display tier

The display tier consists of the display driver, the Baan IV user interface forMicrosoft Windows (BW) and for Internet browsers (BI). The display driverfacilitates the communication between the user and the application tier. Datainput from the user through BW or BI is relayed to the Baan IV applicationvirtual machine; data returned from the Baan IV application virtual machine isdisplayed to the user in graphical form by the display server.

Application tier

The application tier includes both the application objects and the Baan IVapplication virtual machine. Together, the application objects and the applicationvirtual machine provide much of the functionality of Baan IV.

Introduction


1-3

The application objects include the compiled Baan IV applications and the datadictionary. The Baan IV applications provide the functionality needed toimplement the Baan IV Enterprise Resource Planning (ERP) system. Theseapplications are written in Baan 3GL or Baan 4GL, programming languagessupported by the Baan IV Tools package.

The data dictionary defines the data models used by the applications. The datadictionary includes information about the domains, schemas, and referentialintegrity rules used by Baan IV.

The Baan IV application virtual machine schedules and runs the applicationobjects, sends and receives information to and from the display server, andinitiates an instance of the database driver as necessary for communication withthe database server. A running database driver can support multiple connectionsto a single RDBMS instance. If a Baan IV installation stores data tables inmultiple RDBMS products or instances, the application virtual machine muststart one instance of the database driver for each RDBMS product or RDBMSinstance with which it must communicate.

The Baan IV application virtual machine has traditionally been called theBaan IV shell or more often simply the bshell. Throughout the remainder of thisdocument, it is referred to as the Baan IV application virtual machine or theapplication virtual machine.

Database tier

The database tier consists of the Baan IV database driver and the database server.The database driver provides a common interface between the Baan IVapplication virtual machine and the database server. Communication between theapplication virtual machine and the database driver is the same, no matter whichRDBMS product is used as the database server. There is one database driver foreach of the RDBMS products that Baan IV supports.

Communication between the database driver and the database server is tailored tothe RDBMS being used. The database driver communicates with the RDBMSthrough structured query language (SQL) statements and the native applicationprogramming interface (API) of the RDBMS.

The database server consists of one of five third party RDBMS products: Oracle,Informix, Sybase, DB2, or Microsoft SQL Server. All Baan IV application datais stored in a relational database managed by an RDBMS. It is possible to havemultiple RDBMS products in one Baan IV installation, with some data residingin one database server and other data residing in another.

Introduction


1-4

Data flow through the Baan IV architectureNote that the database driver provides an interface between the Baan IVapplication virtual machine and the specific RDBMS server being used. The flowof data through the system is described below.

When a user performs an operation at a GUI workstation, the display serverinterprets the input and sends the information to the Baan IV application virtualmachine. Based on the information it receives, the application virtual machinecauses the appropriate application object to be executed.

When a running application object requires information that is stored in thedatabase, the application virtual machine sends the request to the database driver.Data requests from the client applications are RDBMS independent and are madeusing Baan IV SQL, an RDBMS independent SQL language.

When the application virtual machine executes a database query from anapplication object, it first determines whether or not there is a running databasedriver available to process the query. If there is no database driver running, or ifthe running database driver instances are communicating with a database serverother than the one storing the needed data, the application virtual machine starts anew instance of the database driver. The application virtual machine parses theBaan IV SQL database query it receives from the application object and sends aninternal representation of the query to the database driver. The internalrepresentation of the query that the database driver receives is still RDBMSindependent.

The database driver translates the database query into an appropriate query usingSQL statements compatible with the specific RDBMS being used. Each databasedriver takes advantage of the design of the particular RDBMS that it supports sothat the resulting SQL statements are valid for the RDBMS and provide the bestpossible performance. The RDBMS specific SQL statements are then submittedto the RDBMS server, which processes the data request.

When the RDBMS has processed the query, it returns the data to the databasedriver. Any error conditions are caught and handled by the database driver. Thedatabase driver then returns the data and status information to the applicationvirtual machine, where it provides the information to the application thatrequested it. The application virtual machine may also send a message to thedisplay server, which displays an appropriate message on the user’s workstation.

Introduction


1-5

Baan IV hardware configurationsSeveral hardware configurations are supported for a Baan IV implementation.These configurations include standalone mode and many variations ofclient/server mode. Available hardware, data storage requirements, andperformance expectations determine the most appropriate hardwareconfiguration.

Standalone mode refers to a configuration where all components of the Baan IVarchitecture run on a single machine. In standalone mode, an end user can workfrom the host machine or from a thin client machine, such as an X-Terminalrunning BI. The standalone mode configuration is illustrated in Figure 2.


(bshell)

Database Driver

Display Driver

Application Objects


Figure 2, Standalone mode configuration

In a client/server configuration, the components of the Baan IV architecture aredistributed over two or more machines. There are many client/serverconfigurations. The most common configurations are described here.

Introduction


1-6

The simplest client/server configuration is sometimes thought of as a variation ofstandalone mode. In this configuration, the application tier, database driver andRDBMS are on one machine, while the display drivers are distributed among theuser workstations. An instance of the application virtual machine and at least oneinstance of the database driver is started for each user. All users have access tothe same application objects and database servers. This configuration isillustrated in Figure 3.


(bshell)

Database Driver

Display Driver Display Driver

Application ObjectsApplication

Virtual Machine(bshell)

Database Driver


Figure 3, Client/Server configuration 1

When two machines are available to be used as servers, two configurations arecommonly used. In both configurations, the display drivers reside on the userworkstations. In the first configuration, the application tier is placed on oneserver, while the database driver and the database server are placed on another.As with the previous configuration, an instance of the application virtual machineand at least one instance of the database driver is started for each user. All usershave access to the same application objects and database servers.

Introduction


1-7

This client/server configuration is illustrated in Figure 4. This configuration usesthe Baan IV method of client/server access between the application virtualmachine and the database server.


(bshell)

Database Driver




Database Driver



An alternative configuration with two servers is to place the applications and thedatabase driver on one server and the database server on another. End userworkstations are again linked to the machine with the application virtualmachine. Again, an instance of the application virtual machine and at least oneinstance of the database driver is started for each user. All users have access tothe same application objects and database servers. This client/serverconfiguration is illustrated in Figure 5. This configuration uses the RDBMS’sability to provide client/server access.

Introduction


1-8


(bshell)

Database Driver




Database Driver



There are many other configurations of client/server systems, including dividingthe application logic among multiple servers or using multiple servers fordistributing the database.


2-1

All of the application data used by Baan IV is stored in database tables in theRDBMS. To keep the majority of the Baan IV processing independent of theRDBMS, Baan IV uses a data dictionary. The data dictionary includes domain,schema, and referential integrity information that is stored in a databaseindependent manner.

Because so many tables are needed, a convention is used for naming tables,columns within tables, and indexes to data within the tables. This chapterdescribes the data dictionary and the naming conventions used by the Baan IVdatabase drivers to access data stored in the RDBMS. It also discusses howBaan IV data types are mapped to DB2 data types.


n Baan IV data dictionaryn Table naming conventionn Column naming conventionn Index naming conventionn Data type mappingn Additional constraints

Baan IV data dictionaryA data dictionary is a catalog that provides information about the data in adatabase. It can be thought of as data about the data, or metadata. A datadictionary can be used to find data that resides within a database table.

The Baan IV database drivers maintain a data dictionary because the data usedby the Baan IV applications may differ from the database tables defined in theRDBMS. The Baan IV data dictionary maps Baan IV data types, domains,schemas, and referential integrity information to the appropriate information inthe RDBMS. When storing or retrieving data in the RDBMS, the database drivermaps data dictionary information to database table definitions.

Baan IV data dictionary information can be kept in shared memory where it willbe available to all running Baan IV application virtual machines. The datadictionary information is shared among all the sessions open within a singledatabase driver.

2 Baan IV database organization

Baan IV database organization


2-2

The Baan IV data dictionary cannot be used directly by the database driver tocreate DB2 tables. This is because not all Baan IV data types exactly match DB2data types or limits. To create valid DB2 tables, the driver must perform somemapping or translation. When mapping the Baan IV data dictionary to tables inDB2, conventions are used for the table names, column names, and index names.

Table naming conventionThe table name of a Baan IV table stored in DB2 has the following format:

t<Package><DD Table name><Company number>

The following describes each of the components of the table name.

Components of the table name

Component Description

Package The package is a two-letter code that refers to theBaan IV package that created the table. For example, atable created by the Baan IV Tools package has thepackage code tt.

DD Table Name The DD table name is the name of the table used in thedata dictionary. The data dictionary table name consistsof three letters followed by three digits. The letters referto the application that uses the table and the digitsindicate the order in which the tables were created.

Company Number Within Baan IV, three digit company numbers are usedto differentiate areas of functionality. There must be acompany with the number 000. In addition, there may beseveral other company numbers.

For example, the data dictionary table adv999 with company number 000 iscreated in DB2 as tttadv999000.



2-3

Column naming conventionEach column in the Baan IV data dictionary corresponds to one or more columnsin a DB2 table.

The rules for column names are as follows:

Rules for column names


General When a Baan IV column name is created in DB2, it is preceded by thestring t_. For example, the Baan IV column with the name cpac iscreated in DB2 with the name t_cpac. By preceding column names byt_, reserved words are avoided. If a column name contains a period [ .], the period is replaced by the underscore [ _ ] character.

Long string columns Baan IV columns of type string can exceed the maximum length ofcharacter columns in DB2. The DB2 data type CHAR has a limit of254 characters. When a Baan IV string column exceeds this limit, thecolumn is split into segments with up to 254 characters each. The first254 characters are placed in a column where the name of the columnis extended with _1. The next 254 characters are placed in a columnwith a name extended by _2, and so on until all the characters of thestring are placed in a column. For example, if a Baan IV string columncalled desc contains 300 characters, the following two DB2 columnsare created:

- t_desc_1: size 254

- t_desc_2: size 46

Array columns In the Baan IV data dictionary, array columns can be defined. Anarray column is a column with multiple elements in the column. Thenumber of elements is called the depth. For example, a columncontaining a date can be defined as an array of three elements—aday, a month, and a year. In DB2, the three elements of the arraycolumn are placed in separate columns. The names of these columnsinclude a suffix with the element number. For example, an arraycolumn called date will become:

- t_date_1: element 1



Note that if the element is of type string and one element typeexceeds the maximum DB2 character size of 254, it is split. Forexample:

- t_str_1_1: element 1, part 1

- t_str_1_2: element 1, part 2



2-4

Rules for column names


Array compression The maximum number of DB2 columns is 500. If the number ofBaan IV columns exceeds the maximum number of DB2 columns, thedatabase driver tries to compress (join) array columns to reduce thenumber of columns. All array elements of one array column are storedas one column in the DB2 database with the elements concatenatedin binary format. The driver starts by compressing the array columnthat yields the highest number of columns. It continues compressingarray columns until the number of columns is less than 500. Thename of the compressed column in DB2 follows the same conventionused for the other columns. For example:

- t_array: contains all elements of the compressed column

Note that when a compressed array column is longer than 254characters, is be split in segments of 254 characters or less.

Index naming conventionBaan IV indexes are identified by a sequence number for each table, with thesequence numbers starting from one. Each table has at least one index: theprimary index. DB2 requires that index names must be unique. For this reason,the table name, index number, and the index type are included in the index name.The index type refers to the order, either ascending or descending.

Index names have the following format:

i<Table name>_<Index number><Index type>

For example, the index name for a Baan IV table with name ttadv999, indexnumber 1, company number 000, and index type ascending order is:

ittadv999000_1a

If a Baan IV index is defined as a unique index, then the DB2 index is createdwith the UNIQUE clause. The UNIQUE clause prevents duplicate rows frombeing created in the table.



2-5

Data type mappingThe following table shows the mapping between Baan IV data types and theirDB2 counterparts.

Mapping between Baan IV and DB2 data types

Baan IV data types DB2 data types

CHAR CHAR(1) for bit data

ENUM CHAR(1) for bit data

INT SMALLINT

LONG INTEGER

UTC DATE DATE

UTC TIME TIMESTAMP

TEXT INTEGER

BITSET INTEGER

FLOAT DOUBLE

DOUBLE DOUBLE

STRING(N) CHAR(N)

MULTIBYTE STRING CHAR(N)

DATE DATE

Note that the Baan IV DB2 driver uses the CHAR data type when ANSI-compliant behavior is expected for character data, such as with the Baan IVstring type. This DB2 data type is used because a Baan IV string data type hascharacteristics that conform to the ANSI specification for character data. Whenthe CHAR data type is used, operations such as comparison and concatenationcan be done in a predefined manner with predictable results.



2-6

Additional constraintsIn addition to the above naming conventions and data types, the following rulesapply when mapping Baan IV data to DB2 data:

n All names generated by the database driver are in lowercase characters, andare not enclosed within double quotation marks. Since the binary sort order isselected during the installation, DB2 treats object names with case sensitivity.

n All columns created by the DB2 driver have the NOT NULL constraint.Baan IV applications do not support NULLS.

n If a Baan IV index is defined as a unique index, then the DB2 index is alsocreated with the UNIQUE clause. Otherwise indexes which allow duplicatesare not defined with the UNIQUE clause.

n The date range for the Baan IV application virtual machine is the same as therange for DB2 with the following exception. The application virtual machinedate 0 is mapped to the DB2 date 1. The application virtual machine date 1 ismarked as an invalid date.


3-1

The DB2 database driver converts RDBMS independent database requests intorequests designed specifically for DB2. This chapter describes some of theinternal processing that occurs within the Baan IV DB2 database driver. First,some of the features that ensure data integrity are discussed. Next, the internalprocessing of a SQL statement within the driver is explained. The final section ofthis chapter describes the mechanisms that allow the default behavior of thedatabase driver to be modified.

In this chapter the following Baan IV DB2 database driver internal issues arediscussed.

n Data integrityn Database driver SQL processingn Setting driver behavior

Data integritySeveral features of the Baan IV database driver help to insure data integrity.These features include locking mechanisms, methods used for insuringreferential integrity, and methods used for distributed databases. In addition, dataintegrity is maintained while minimizing network traffic by using data bufferingtechniques. This section gives an overview of the features used by the Baan IVDB2 database driver to ensure referential integrity, to work with distributeddatabases, and to apply data buffering techniques. Locking strategies arediscussed in detail Chapter 6.

Referential integrity

Referential integrity preserves the defined relationships between tables whenrecords are maintained. The Baan IV database driver has a built-in mechanismfor preserving referential integrity; it does not depend on the underlying RDBMSfor maintaining referential integrity.

Data buffering

Updates can be buffered by the application virtual machine and flushed at thetime of transaction commit, or earlier when necessary. This reduces the numberof network round trips and data volumes.

3 Database driver internal processing

Database driver internal processing


3-2

When multiple rows are returned from a query, the rows are buffered and thensent back to the Baan IV application virtual machine as one block. Datareduction and compression is applied to compact the data, minimizing theamount of data transferred between the application virtual machine and thedatabase driver

Database driver SQL processingAs discussed in Chapter 1, the application virtual machine sends RDBMSindependent database queries and update requests to the database driver. It is upto the database driver to convert these RDBMS independent database requestsinto SQL statements that are appropriate to the specific RDBMS being used. Thissection details the SQL processing performed by the Baan IV DB2 databasedriver. Because the Baan IV DB2 database driver uses the call level interface(CLI) to communicate with DB2, CLI will be described first.

Call level interface

The DB2 driver uses the call level interface (CLI) to communicate with DB2.CLI is a function library (or a set of C functions) that can be called from a Cprogram to execute SQL statements.

The functions called by the DB2 driver perform the following actions:

n Logon to DB2 (open session)n Allocate a statement handlen Parse a SQL statementn Binding of input variablesn Binding of output variablesn Execute the SQL statementn Fetch the resulting rowsn Break a query (asynchronous)n Commit/abort transactionn Close a cursorn Logoff from DB2 (close session)

The following features of CLI are also used by the DB2 driver:

n Array fetches (when enabled)n Array inserts (when enabled and possible)



3-3

SQL processing

SQL statements are dynamically generated by the database dependent layer ofthe Baan IV DB2 database driver. Because Baan IV applications are dynamic, itis not known in advance which tables will be used at run time, hence it is notpossible to prepare the queries before run time.

Within the Baan IV DB2 database driver, SQL statements are processed inseveral steps. This section describes these steps.

When the Baan IV DB2 driver receives a query from the application virtualmachine, the query is translated into a format suitable for DB2, and is passed toDB2 using CLI function calls. Within DB2, a statement handle/cursor isallocated and the query is executed by assigning to it the statement handle. TheSQL statement is parsed, input and output variables are bound and the query isexecuted using the statement handle. In some cases, DB2 opens a server cursorinternally for query execution. After the query is executed, a fetch operation isdone and the resulting column values are placed in the bound output variables.The rows returned by DB2 are passed to the database independent layer of theBaan IV DB2 database driver, which sends the results back to the applicationvirtual machine.

When a statement needs to be re-executed, the cursor from the previousexecution is closed and the resulting rows are discarded (whether the re-execution is with the same input parameters or not). If new input values arerequired, the new values are assigned to the input parameter columns, and thequery is re-executed. However, for re-execution, no re-parse of the statement orre-bind of input and output parameters is required. This improves the overallperformance.

When array fetching is enabled, multiple rows are fetched in one call to thedriver. Space is allocated within the driver to buffer multiple rows fetched in oneoperation. Multiple rows can be fetched to the buffer; and they are returned to theapplication virtual machine when requested. When no rows are left in the bufferand more rows are requested, another array fetch operation is executed.

Inserts can also be buffered. When array inserting is enabled, the driver placesthe rows to be inserted in a buffer. When the buffer is full, or when some otherevent necessitates it, the rows are flushed to DB2. The rows in the buffer areinserted with a multi-row insert.

Data can be manually placed into the database using the Baan IV utility bdbpost.This utility is used to place data into a new database table or to append data to anexisting database table. Certain options can be set when using bdbpost (see theBaan IV Tools Technical Manual). When bdbpost is used with the -f option, therows are buffered by default and are flushed when the array buffer is full.

NOTE



3-4

The array size needs to be specified; otherwise buffering is not done. The arraybuffer size can be specified in the db2_storage file on a per table basis orglobally, by using an environment variable or resource variable. Theenvironment variables, resource variables, and storage file are explained in thefollowing sections.

Setting driver behaviorThere are several facilities available for configuring the Baan IV DB2 databasedriver. The most common is through driver resources. Two other facilities forconfiguring the Baan IV DB2 database driver are environment variables and thestorage file. The driver resources and environment variables are described inmore detail in Appendix A and the storage file in Appendix B.

Driver resources

The database driver resources are parameters that can be set to modify thebehavior of the Baan IV DB2 database driver. These parameters are set in a filecalled the resource file (db_resource). There is one resource file for all databasedrivers that run in a Baan IV environment; resources for all the database drivertypes can be found there. A database driver reads the parameters set in theresource file when it is first invoked.

The resource file may contain many entries, with one entry per line. Each entry isused to set a single resource parameter, with the resource name followed by acolon and then the value to which the resource is to be set. The following is anexample of the contents of a resource file containing two entries:

dbsinit:01db2_timeout:{2,2,2,2,2}

When modifying the behavior of the database driver, it is often necessary tomodify the behavior of the Baan IV application virtual machine to takeadvantage of the characteristics of the database driver. Therefore, there are twotypes of database driver resources: those that are used to modify the behavior ofthe database driver and those that are used to modify the behavior of theapplication virtual machine.

Driver resources that are used to modify database driver behavior are calledresources for the server. Driver resources that are used to modify behavior in theapplication virtual machine are called resources for the client.



3-5

The resource file, db_resource, is located in the directory%BSE%\lib\defaults, where %BSE% refers to the directory where theBaan IV software environment is installed. When both the database driver andthe application virtual machine run on the same machine, there will be only onedb_resource file containing all the necessary resources parameters. When thedatabase driver and the application virtual machine run on different machines,there must be one db_resource file located on the machine running the databasedriver that contains the server resources, and one db_resource file located on themachine running the application virtual machine that contains the clientresources.

In addition to the default resource file, db_resource, it is possible to set up analternative resource file to override resource values for specific users or groupsof users. The alternative resource file is specified with the environment variablesUSR_DBS_RES and USR_DBC_RES. USR_DBS_RES is used to specify thepath to a file containing an alternative resource file for the server and must be seton the machine running the database driver. USR_DBC_RES is used to specifythe path to a file containing an alternative resource file for the client and must beset on the machine running the application virtual machine. Any driver resourceset in the alternative resource file will override the setting of the same driverresource in db_resource. The next section describes how to set the databasedriver environment variables.

Environment variables

Environment variables can be used to override driver resources. Usually, adefault set of resource parameters is configured in the resource file. Theadministrator can override these default settings with environment variables.

For the most part, there is an environment variable corresponding to eachresource parameter. The environment variable name is usually the uppercaseequivalent of the resource parameter name. As with the database driverresources, some environment variables are used to modify the behavior of thedatabase driver (server) and some are used to modify the behavior of theapplication virtual machine (client). When a database driver environmentvariable for the server is to be used, it must be set on the machine running thedatabase driver to override the corresponding driver resource. When a databasedriver environment variable for the client is to be used, it must be set on themachine running the application virtual machine to override the correspondingdriver resource.



3-6

Server environment variables

Environment variables that affect the database driver can be used to override thedriver resources for all tables in a database or for specific tables and companynumbers within the database. There are three ways to set the database driverserver environment variables:

n By using the Baan IV sessions Database Definitions (ttaad4510m000) andTables by Database (ttaad4111m000)

n By manually modifying the Baan IV tabledef6.1 file

n By using the standard operating system mechanism for setting environmentvariables

Because Baan IV runs as a registered service in Windows NT, it is advisable toreboot the system after changing/setting values to environment variables.

The Baan IV session Database Definitions is the recommended method tomodify database driver behavior. When specific tables and companies are to beconfigured for access with a specific database driver, the session Tables byDatabase should be used. These sessions causes environment variables for aparticular database driver to override the defaults set in the resource file andallow the environment variables to be maintained centrally.

The Database Definitions session maintains database driver configurationinformation in a file called tabledef6.1. This file is stored in the directory%BSE%\lib residing on the machine where the database driver runs. While it isrecommended that the Database Definitions session be used to maintain this file,advanced users can modify this file manually. The format of the tabledef6.1 fileis as follows:

<table name>:<company number>:<driver type>(<environment variable>=<value>)

If multiple environment variables are to be specified for a single table andcompany number, they are listed within the parentheses and separated bycommas. If all tables or all companies are to be specified, the asterisk (*) is usedin place of table name or company number. For example, the following entry canbe made in the tabledef6.1 file:

tccom010:812:db2(DB2PROF=0.4)

In this example all the queries on table tccom010812 which require at least 0.4seconds are logged in the DB2PROF file. Note that this table is considered tohave a different database definition from other tables. If a DB2 driver is alreadyrunning, but is accessing a different table, a separate driver will be started for thistable.

NOTE:



3-7

Environment variables that appear in the driver specifications of the tabledef6.1file are put into the driver’s environment before it is invoked, so they areavailable to the driver at startup.

If the default database driver resources must be modified for specific users, thestandard operating system method can be used to set database driver environmentvariables for specific users. These environment variables will override thesettings created in the Database Definitions session for these users.

Client environment variables

Database driver environment variables that affect the client can be used tooverride the client resources that affect the application virtual machine. Theseenvironment variables must be set on the machine running the application virtualmachine and should be set using the standard operating system methods used forsetting environment variables. Any client environment variables that are usedoverride the equivalent resource variables set for the client in the db_resourcefile.

Storage file

The storage file provides a way to specify the distribution of table and index datain different segments. Storage parameters are used by the database driverwhenever a DDL statement such as a create table or create index statement isexecuted. The following is an example of an entry in the storage file:

T_SPACE userspace1 I_SPACE indexspace1

In this example, the database driver adds the ‘in <tablespace name> index in<index tablespace name>’ clause to the create statement during index or tablecreation.

A storage file is defined for each database driver. The storage file for theBaan IV DB2 database driver is called db2_storage and is located in thedirectory %BSE%\lib\db2. The format of the storage file is described in detailin Appendix B.



3-8


4-1

The Baan IV DB2 database driver maintains security by controlling user accessto the database and user access to database objects. The Baan IV databaseadministrator (DBA) module allows the DBA to control access to the databaseusing Baan IV sessions. Using the DBA module makes DBA tasks easier andless prone to errors than using database driver tools directly. This chapter firstdiscusses how the Baan IV DB2 database driver handles issues related todatabase security. It then briefly describes the DBA module.


n Database securityn The DBA module

SecurityThere are two aspects of database security: object security and authentication.Object security refers to the process of determining whether or not a user whohas access to the database is authorized to access particular database objects.Authentication refers to the process of determining whether or not a user isauthorized to access the database. Both object security and authentication use theconcept of groups to ensure security. This section first describes the groupconcept, then describes how the Baan IV DB2 driver provides object security andauthentication.

Groups

In any RDBMS, a group is defined as a collection of database users. All usersassigned to a group are granted the same database privileges. Once a group isdefined with a certain set of privileges, users can be assigned to that group. Usinggroups simplifies management of a large number of groups with commonrequirements.

A Baan IV group consists of a database name and methods for providing objectsecurity and authentication within the database. The Baan IV group name is thesame as the name of the database that holds the Baan IV data within theRDBMS. The Baan IV group uses the mechanisms of the RDBMS to provideobject security and authentication.

4 Database security

Database security


4-2

A Baan IV group is a superset of the usual RDBMS group in that it includes notonly the RDBMS group, but also the database name and an RDBMS login.

In DB2, a Baan IV group is made up of three components: a database, a login(for authentication) and an operating system group (for object security). The DB2database has the same name as the Baan IV group. The login userid is the samename as the Baan IV group and is assigned database owner privileges in thedatabase. An operating system group is created which becomes the target forprivileges granted on objects in the database. Users are associated with theoperating system group and, as a result, inherit the privileges granted to thegroup. The advantage of having a group table is that the members of the groupcan share and operate on the same data in a single table.

On Windows NT, the login for the Baan IV group is always set to baan. Theoperating system group will have the same name as the DB2 database and theuser baan must belong to this group.

For example, users maria and john can both be assigned to Baan IV groupbaandb. Group baandb owns the tables and grants select, insert, delete, andupdate privileges to the operating system group. As a result, users maria andjohn inherit the select, insert, delete, and update privileges granted to theoperating system group, allowing them to access and manipulate Baan IV grouptable data.

The Baan IV user is shielded from the RDBMS groups. The database driver doesall the processing that is needed to make use of the RDBMS groups. Only thedatabase administrator needs to be concerned about the RDBMS groups, and theBaan IV DBA module allows the administrator to easily maintain the RDBMSgroups.

Object security

In DB2, when a user creates an object such as a table, the user becomes theowner of that object, and only the owner can access the object. Other users canonly access the object if they have been granted privileges to do so. In a Baan IVenvironment where many users access the same tables in the DB2 database, amechanism has been developed to allow users to share these tables.

To allow different Baan IV users to share the same DB2 table, the group conceptis used. A Baan IV group maps users to a database in DB2 and ensures thatmembers of the group have sufficient privileges to access data in the Baan IVgroup’s tables.

The Baan IV DB2 driver uses an operating system group to implement theBaan IV group concept. Initially the group is granted connect and createtabprivileges to the database.

NOTE:

Database security


4-3

Whenever a new table is created by the Baan IV group user, select, insert, delete,and update privileges are granted to the operating system group.

Any user associated with the operating system group automatically inherits theseprivileges and can individually perform these operations on the Baan IV grouptable.

When new users are added, they need only be associated with the operatingsystem group; they automatically inherit all privileges currently granted to theoperating system group without need to grant privileges on every group object inthe database to the user. When the user is dropped from the operating systemgroup, these privileges are revoked. The user no longer has access to tableswithin that operating system group. If the privileges to operate on the tables areexplicitly granted to the user, then they must also be explicitly revoked when theuser is dropped from the operating system group. The overhead of adding users isgreatly reduced by granting privileges to the operating system group. This alsoprovides flexibility and ease of maintenance.

A user can define whether a table should be created as a group table or as aprivate table. When a table is identified as a private table, the user becomes theowner and no privileges are given to other users. When a table is identified as agroup table, the table is created by the group login and the privileges are grantedto the group, allowing all users in the group to access the table. A table can beconfigured as private or group via the file %BSE%\lib\db2\db2_storage.

In the DDL statements generated by the driver, object names are not qualified bythe owner name. Ownership is determined by the session (group or user) thecreate table is executed in. When creating objects identified as belonging to thegroup, the user creating the object logs into DB2 as the group user. In this casethe table will be owned by the group and permissions will be granted on it toallow all group users access. When creating objects identified as private, usersare connected to DB2 under their own login. When private objects are created,the user owns them; no other permissions are granted.

A table’s configuration is defined in the file %BSE%\lib\db2\db2_storage. Theconfiguration includes whether it was created as a private or a group table. Theformat is explained below. The keywords group or private can be specified inthe appropriate field. For example:

{maria,john}tdsfc:*:T:group:001::{anne}tdsfc:*:T:private:001::

This indicates that users maria and john create tables in module tdsfc as grouptables and user anne has her own private tables in module tdsfc.

Database security


4-4

Authentication

DB2 uses the operating system’s authentication mechanism to determine whethera user is authorized to access a database. When a database is created, anadministrator or DB2 database owner grants access permission to an operatingsystem group. Access permission can be granted for the entire database or forspecific database objects.

Baan IV users mapped to operating system users are allowed to establish aconnection to DB2 with their own user name and password. To preventunauthorized users from accessing the database, non-mapped users cannotestablish a connection to the database.

The Baan IV group user corresponds to the target database—the group name isthe same as the database name. The members belonging to this group inherit thegroup privileges and are able to establish a connection to the database using avalid password stored in encrypted form in the driver administration files. A usercan be added to or dropped from a Baan IV group using the Baan IV DBA(database administration) module or the db2v5_maint utility. Note that anyDBA module or db2v5_maint action will not affect the operating system user orgroup; it only affects the Baan IV administration files. If you want to, forexample, change a user’s password, you must change their operating systempassword and then change it in Baan IV using the DBA module ordb2v5_maint.

Users who are authorized to access the database are registered in the Baan IVdriver administration files. The user name and password each Baan IV user willuse to log on to DB2 is maintained in the file %BSE%\lib\db2_users.

All the Baan IV users and their corresponding DB2 logon names and passwordsand the name of the group they are assigned to are defined in the file%BSE%\lib\db2\db2_users. The format of each entry in this file is as follows:

<Baan IV user>:<DB2 user>:<Encrypted DB2 User password>:<Baan IV group name>

The Baan IV DB2 driver is started by the Baan IV application virtual machine onbehalf of the user. From the file %BSE%\lib\db2\db2_users the driveridentifies the DB2 user and the user’s password and establishes the connection toDB2.

The group logon procedure also includes a password, which is defined in the file%BSE%\lib\db2\db2_groups. The format is as follows:

<Group name>:<Encrypted group password>

The group name is the same as the database name.

Database security


4-5

DBA moduleThe DBA module maintains the database administration files used by the DB2database driver. This module allows an administrator to register authorized usersand to give users access to data. This tool is provided with the Baan IV DB2database driver to maintain the administration files that the database driver needsat run time. The administration files are stored in the directory %BSE%\lib\db2.

The DBA module implements the user and group administration functions for allBaan IV database drivers. The db2v5_maint utility is an executable programcalled by the DBA module that implements the functions necessary to makechanges in DB2. While it is possible to call the db2v5_maint utility from outsidethe DBA module, this is not recommended because the users and groups tablesare not modified by db2v5_maint.

Database security


4-6


5-1

The Baan IV DB2 database driver provides a facility for monitoring systemperformance. These include a profiling facility that allows the user to gathertiming information for SQL statements, and a statistics facility for gatheringdriver-wide statistics. In addition, the driver provides a facility fortroubleshooting problems. In this chapter, the profiling, statistics, and debuggingfeatures of the Baan IV DB2 database driver are discussed.


n Profilingn Gathering statisticsn Troubleshooting

ProfilingThe database driver allows users to log timing aspects and statistics. This isuseful for tuning because the information may help to identify performancebottlenecks and can give input into the tuning process.

The database driver’s profiling option provides the user with a way to gather thetiming of SQL statements that are being executed. Logging all statements withtheir timings, however, will result in a log file that is so large it cannot beproperly analyzed. It is possible to define a logging threshold where onlystatements that take more than a predefined number of seconds are logged.

With profiling, the following information is logged: the RDBMS request, theelapsed time, the user name, the date, and the time. The maximum precision thatcan be specified is 0.01 seconds.

To determine which table actions are most time consuming you can set theDB2PROF environment variable to a number of seconds. For example,DB2PROF can be set as follows:

export DB2PROF=5.0

This sets DB2PROF to five seconds, causing statements that takes more than 5.0seconds of elapsed time to be logged to the file db2prof. The file db2prof isstored in the directory where the driver was started.

5 Database driver profiling andstatistics

Database driver profiling and statistics


5-2

Note that the following two statement types are timed and can appear in the logfile:

n The execute eventThis represents the amount of time the RDBMS takes to execute an SQLstatement.

n The fetch eventThis represents the amount of time it takes to retrieve data from the buffer orthe RDBMS.

A sample DB2PROF file is shown below.

Profiling value = 0.00 secPid Table Owner I Mode Cache Exe Fetch Exe Fetch Tot<11350> tiitm001812 jim 1 FIRST : - 0.01 0.00 - - 0.04< 8024> tiitm001812 jim 1 FIRST : - 0.01 0.00 - - 0.05<11350> tiitm001812 jim 1 FIRST : 0.00 - - - - 0.00<11350> tiitm001812 jim 1 FIRST : 0.00 - - - - 0.00<11350> tiitm001812 jim 1 FIRST*: - 0.01 0.00 0.01 0.00 0.06< 8024> tiitm001812 jim 1 FIRST*: - 0.00 0.05 0.00 - 0.10<11350> tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00<11350> tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00<11350> tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00<11350> tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00<11350> tiitm001812 jim 1 NEXT : - - 0.01 - - 0.01<11350> tiitm001812 jim 1 NEXT* : - - 0.01 0.01 0.00 0.02<11350> tiitm001812 jim 1 NEXT* : - - 0.00 0.01 0.00 0.01<11350> tiitm001812 jim 1 PREV : - 0.00 1.02 - - 1.05<11350> tiitm001812 jim 1 PREV : - - 0.01 - - 0.02<11350> tiitm001812 jim 1 PREV : - - 0.00 - - 0.016

The data in the above sample file can be interpreted as follows:

n In this example, the number of seconds (profiling value) is 0.00. This meansthat all actions are written to the file.

n The asterisk [*] after some of the records indicate that the records were firstread and then locked.

n The I column lists the number of the index used.

n The Cache column lists a value when a result is retrieved from cachememory.

n For each action, two executes and two fetches are recorded. This is usefulwhen a record must be read in locked mode or when only key fields areselected first and then the other fields are retrieved.

Statement execution time can be viewed for individual tables by setting theDB2PROF environment variable in the file %BSE%\lib\tabledef6.1. Forexample, the following entry can be made in the file:

tccom010:812:db2(DB2PROF=0.4)



5-3

In this example all the queries on tccom010812 table which require more than0.4 seconds are logged in the db2prof file. Note that a separate driver is startedfor this table; the table is considered to have a different database definition.

Gathering statisticsThe database driver provides an option to gather driver-wide statistics on actionsperformed, such as:

n Number of cursors (opened, closed, current open)n Number of parses, binds, executes, fetchesn Number of logons (sessions)n Number of inserts, updates, deletesn Number of commits, rollbacks

For each action, the cumulative elapsed time spent and the average time islogged. The statistics can be enabled with the environment variable DB2STAT.When the variable is set to zero, a statistics report is generated when the driverterminates (exit from Baan IV Tools or session). When a value n greater thanzero is specified, the driver logs an incremental report every n seconds (thedriver must be active). The statistics report is written to the file DB2STAT in thecurrent directory.

The following are examples of how DB2STAT can be set:

export DB2STAT=0export DB2STAT=30

In the first example, DB2STAT is set to zero. With this value, only a final reportis generated. In the second example, DB2STAT is set to 30. This logs a reportevery 30 seconds while the driver is active. The statistics report is logged in thefile db2stat in the current directory.



5-4

The following is a sample output of DB2STAT. Since the report is generic for alldatabases, some information, such as the specific row actions, may not beappropriate for a particular database driver.

<26752> 98-03-30[13:39:14]: Statistics [interval = 10]

C U R S O R S Opened Closed Parse Bind Define Execute FetchCount 156 150 61 0 38 308 626Time(s) 0.03 0.01 0.42 0.00 0.01 0.97 1.19Avg 0.00 0.00 0.01 0.00 0.00 0.00 0.00

D A T A B A S E First Last Next Prev Curr Great Gteq Equal Less Eqle Equal*Count Read 4 0 345 160 0 20 73 36 16 43Cached Read 0 0 0 0 0 0 0 6 0 0 29Fetched Read 0 0 345 160 0 0 0 0 0 0Executed Read 4 0 0 0 0 20 73 30 16 43 65Time(s) Read 0.04 0.00 0.56 0.28 0.00 0.15 0.55 0.15 0.12 0.27Avg Read 0.01 0.00 0.00 0.00 0.00 0.01 0.01 0.00 0.01 0.01

Count Lock 0 0 0 0 0 0 0 94 0 0Time(s) Lock 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.48 0.00 0.00Avg Lock 0.00 0.00 0.00 0.00 0.00 0.00 0.00 0.01 0.00 0.00

Insert Delete UpdateCount Exe 11 29 0Time(s) Exe 0.06 0.14 0.00Avg Exe 0.01 0.00 0.00

CrIdx DrIdx ChOrd CrTbl ClTbl DrTbl LkTbl NrRowCount Exe 0 0 80 0 4 0 0 0Time(s) Exe 0.00 0.00 0.00 0.00 0.12 0.00 0.00 0.00Avg Exe 0.00 0.00 0.00 0.00 0.03 0.00 0.00 0.00

Commt Rolbk RdOnl PrCmt NotAcCount Exe 22 46 0 0 0Time(s) Exe 0.06 0.35 0.00 0.00 0.00Avg Exe 0.00 0.01 0.00 0.00 0.00

S U M M A R Y Count Time(s) AvgTotal asc read (s) 442 1.30 0.00Total desc read (s) 219 0.67 0.00Total exact read (s) 130 0.62 0.00Total all read (s) 791 2.59 0.00Total updates (s) 40 0.20 0.01

Count PercTotal cache hit (%) 35 4.42Total fetch opt (%) 505 63.84

CountForced close 0Current open cursors 6Sessions (logon/logoff) 2 / 0



5-5

The tuning options to improve performance as a result of studying the db2statfile are:

n Index optimization, 1 column (that is, single hash)n Key only optimizationn Extend refresh timen Separate data from indices in tablespaces

In addition, you can use the DB2 db2evmon utility to check I/O times andprocess information. For more information, refer to the DB2 PerformanceMonitor Guide.

The following is an example of the db2_storage file where the specification ofindex optimization for tuning is clearly shown.

tccom010:*:T:group:01:5:T_SPACE tri_space I_SPACE idxspacetccom010:*:I::01::tccom012:*:I1:group:01::T_SPACE tri_space I_SPACE idxspacetccom013:*:I1::01::tccom022:*:I1,I5::01::tccom020:*:I2::01::tiitm001:*:I1::01::tiitm050:*:T:group:01:5:T_SPACE tri_space I_SPACE idxspacetiitm050:*:I::01::*:*:T:group:01:5:T_SPACE userspace1 I_SPACE idxspace1*:*:I::01::

TroubleshootingThe Baan IV DB2 database driver provides a facility for troubleshootingproblems. The actions performed by the driver can be traced and stored in a logfile. In addition, any errors that occur are logged. The following sections explainhow to log trace information and how to find and interpret the error log.

Logging database driver trace information

The database driver provides an option to trace online information about theactions that are being performed by the driver. The resulting log file containsdebugging information that can help solve problems.

When tracing is enabled, the information stored in the log files includes:

n Table and index information (data dictionary)n The SQL statements being executedn Values of the input and output bind variablesn Other function-level debug statements



5-6

Tracing can be enabled using the environment variable DBSLOG. Debugginginformation is appended to the file dbs.log in the current directory. Tracing canbe enabled by entering the following command:

export DBSLOG=0560

Several tracing categories are defined so that tracing can be enabled for onlycategories of interest.

Logging errors

The driver logs its error messages under the Application Logs in the WindowsNT Event Viewer. You can see the messages by using:

Start, Programs, Administrative Tools (Common), Event Viewer.The followinginformation can be retrieved from the log files.

n The user name, date, time, source file, and line numbern The function calledn The error code returned by the databasen The database error descriptionn The BDB error code returned to the applicationn The failing SQL statement, in some cases

When a database error occurs, an attempt is made to map it to some known oranticipated error condition. Generally, these mapped BDB errors havecorresponding error numbers falling in the range of 1 to 1000. If a databasespecific error occurs, it is mapped to the BDB error code over 1000 with thefollowing formula:

abs(error_code) + 1000

So, if an error -1652 occurs, BDB error 2652 is returned to the application.

In most cases, the log entries from the display driver, application virtualmachine, and database driver contain enough information to determine the natureof and solution to the problem. Whenever an error is encountered with an errorcode greater than 1000, you are advised to check the log entries from thedatabase driver.


6-1

The Baan IV DB2 database driver is designed to allow tuning for optimalperformance. Several parameters used by the database driver are preset withdefault values that should provide acceptable system performance, but sinceevery environment is different, the default values of these parameters may notprovide optimal performance. This chapter discusses the Baan IV DB2 databasedriver parameters that can be set, and the changes in driver behavior that you canexpect when you adjust these parameters.


n Cursor managementn Array interfacen Index optimizationn Fetch optimizationn Row cachingn Optimistic and pessimistic reference checksn Locking behavior

Cursor managementThe Baan IV DB2 database driver has a built-in cursor management mechanismusing a least recently used (LRU) algorithm. Each cursor represents one type ofSQL statement. The resource variable db2_max_open_handles can be used toinfluence cursor management. This parameter limits the number of open cursorsthe driver maintains on a per-connection basis. A maximum of 200 and aminimum of one open statement handles are allowed per connection. The defaultis 30 open statement handles per connection.

Array interfaceThe Baan IV DB2 database driver can use the DB2 array interface for arrayfetches and array inserts. With the array interface, communication between theBaan IV DB2 database driver and DB2 is more efficient: multiple rows arefetched or inserted at a time. However, because multiple rows need to be storedin a buffer in the Baan IV DB2 database driver, more memory is consumed.Array interfacing is especially useful when you are accessing a remote database,since the number of network round-trips can be reduced.

6 Database driver configuration andtuning

Database driver configuration and tuning


6-2

To adjust the size of the buffers that hold array rows, the db2_max_array_sizeresource variable or the DB2_MAX_ARRAY_SIZE environment variable mustbe set. The array buffer size can be set on per table basis using the ARR_SIZEstorage parameter in the db2_storage file. The following is an example of anentry in the storage file to adjust the array size:

*:*:T:group:011:5: ARR_SIZE 5 T_SPACE USERSPACE1 I_SPACE IDXSPACE

If the environment variable ARR_SIZE is set, and the array size is also specifiedin the storage file, then the size specified in the storage file overrides the valueset by environment variable.

The array fetch interface can be enabled with the environment variableDB2_ARRAY_FETCH. It is necessary to set the array size, otherwise theinserts will not be buffered. There is currently no equivalent resource variable toconfigure this option.

The array insert interface can be enabled with the environment variableDB2_ARRAY_INSERT. Array inserts are enabled by default when data isplaced in the database tables using the bdbpost utility with the –f option. Thereis currently no equivalent resource variable to configure this option.

Index optimizationIndex optimization is a technique used in Level 1 drivers to obtain betterperformance for SELECT statements in relational databases. Because Baan IVLevel 1 drivers generate queries that are not very complex, the driver can takeadvantage of several attributes of Baan IV application tables to improve accesstime. The index optimization technique causes a new column (referred to as ahash column) to be created in the table for each index defined in the Baan IVdata dictionary. This hash column contains a concatenation of values from eachcolumn participating in the key for that index. Also, the first (or primary) index isalways unique, so it can be used (again concatenated) in other non-uniqueindexes to make them unique. Finally, a raw data type can be chosen as thestorage type for the hash column. The combination of key reduction(concatenation into a single column) and index uniqueness has been found togive performance gains in Level 1 drivers.

In addition, sophisticated optimizers in RDBMSs tend to overanalyze theseLevel 1 queries in an attempt to optimize their execution, so the driver exploitsany means available in the host RDBMS to reduce the effort needed for theoptimizer to arrive at an acceptable execution plan.

NOTE:



6-3

In Baan IV applications, an index can consist of multiple columns (concatenatedkeys). When you retrieve data in the order of the index, the first column in theindex is considered most significant, the last part is considered least significant.Each column has its own significance within the order. This concept is commonto all Level 1 database drivers. Baan IV also requires significance of the columnsin the WHERE clause, which means that you should treat each columndifferently.

As an example, see Table A with columns t_col1, t_col2, and t_col3, all of typeinteger, and an index on t_col1, t_col2, and t_col3. The table contains five rows.

Example table A contains the following five rows

col1 col2 col3

0 0 0

0 0 1

0 1 2

1 2 1

1 2 3

In this example, you want the rows that are greater than the first row : {0, 0, 0}.The correct query to solve this would be:

SELECT col1, col2, col3 FROM AWHERE(col1 > 0 OR col1 = 0 AND(col2 > 0 OR col2 = 0 AND(col3 > 0)))ORDER BY col1, col2, col3

This query contains a nested list of AND/OR conditions, which in general cannotbe efficiently optimized by the RDBMS. As a result, when there are multiplecolumns in an index and there are many rows in the table, the RDBMS serversspend a long time searching all the rows that meet the condition. This causesconsiderably slower performance.

The way to solve this problem is called index optimization. This means that inthe previous example, the three columns col1, col2, and col3 are concatenatedand added to the table as a separate column. This additional column is called thehash column, and it contains a sortable value of the three concatenated columnvalues. An index is created on the hash column. For the example table, thisresults in the following table. Note that the hash value is simplified for theexample.



6-4

Example table A with additional hash column

col1 col2 col3 hash1

0 0 0 “000”

0 0 1 “001”

0 1 2 “012”

1 2 1 “121”

1 2 3 “123”

When searching for rows greater than {0, 0, 0}, you can now specify thefollowing query, including the hash column:

SELECT col1, col2, col3 FROM AWHEREhash1 > “000”ORDER BY hash1

This query is much simpler and can be quickly evaluated by the optimizer. Notethat there is always just one condition in the WHERE clause.

Indexes that allow duplicate values

If a Baan IV index is created on a key that can have duplicate values, theresulting index will be unique because the primary key parts are appended to thehash column to make it unique.

Hash column naming convention

The name of the hash column in a Baan IV application table is formed using thehash keyword and the index number for which it is being created. For example:

hash1 : hash column for index 1



6-5

Size of hash columns

The size of the hash column is determined by the data types and sizes of all thecolumns in the index. The following table demonstrates the contribution of eachdata type to the size of the hash column.

Relationship between data types and size of hash column

Data type Size of hash column

CHAR 1

STRING(n) n

SHORT 3

DATE 4

LONG 5

FLOAT (digv + diga + 2) / 2

DOUBLE (digv + diga + 2) / 2

Where digv is the number of digits before the decimal point and diga the numberof digits after the decimal point.

Specifying index optimization

Index optimization can be specified per table and per index in the%BSE%\lib\db2\db2_storage file. To specify whether index optimizationshould be used, the following (octal) values are available:

0000 no optimization0001 optimization using 1 column ( single hash )0010 Index order ascending only0020 Index order descending only

You can define the default value for each table in a table [T] entry. Any value inan index [I] entry overrides the table default. If there is no entry for a specifictable, the default value is 000.

You can combine the key only optimization with hash optimization values byadding the octal values. For example:

0101 - Optimization using 1 column (single hash) and Key only optimization enabled.



6-6

Fetch optimizationIn Baan IV, it often occurs that a set of rows is retrieved from a table in thedatabase. Usually an application is doing the following sequence:

DB.FIRSTDB.NEXTDB.NEXTDB.NEXTand so on

When a query is processed after fetching the first row, the subsequent rows arefetched from the retrieved set of rows and are returned to the user. Thistechnique, combined with the isolation level or locking strategy employed,determines how current the data is during a read operation. On-demand readscombined with dirty read locking gives the most current view of the data.However, in many situations this behavior is not required. Read performance canbe improved at the expense of a less current view of the data.

Fetch optimization is described as follows. After fetching the first row of a querywith a multi-row result set, subsequent rows satisfying the query are also fetchedand returned to the client. Rows updated or deleted in other concurrentconnections between fetches may not be reflected in this set of rows. Thechanges made in other concurrent connections will only be reflected when thequery is re-executed. A user may not need to see all row changes at the exactmoment they occur, and could simply fetch the next row from the existing(buffered) row set, instead of re-executing the statement to get the most currentview. This technique is referred to as fetch optimization.

Critical to the use of this technique is the definition of a refresh time that allowsthe user to specify a time interval, in seconds, for which a fetch-optimized set ofrows is valid. As long as the set is deemed valid, data can be fetched from thebuffered row set. Changes that occurred as a result of activity in otherconnections since the query was executed are not reflected in the data. If the rowset expires (that is, refresh time is exceeded), the statement will automatically bere-executed in the driver before the next row is returned.

For example, assume that a set of rows is retrieved when DB.FIRST is issued.For a refresh time of five seconds, the DB.NEXT call will fetch the next rowfrom the fetch-optimized set of rows. All consecutive DB.NEXT calls within fiveseconds will not fetch from the database, but will be fed from the buffered rowset until the buffer is exhausted. After five seconds the set will be consideredinvalid and a subsequent DB.NEXT will cause a re-execute of the query andfetch from the database. This results in a performance improvement by reducingthe number of query executions. This translates into reduced RDBMS server loadand reduced network traffic.



6-7

You can set the refresh time for tables (T entries) in the storage file. For index (I)entries, the refresh field is ignored. The default is 0 if not specified.

For example, the db2_storage file can contain the following entries:

*:*:T:group:011:5:*:*:I:group:011::

In the above example, all tables and companies will use single hash columns forindex optimization and a refresh time period of five seconds for fetchoptimization.

The following example shows two entries that might be set in the db2_storagefile:

*:*:T:group:011::*:*:I:group:011::

In this example, all the tables have a default refresh time of 0 seconds, meaningthat fetch optimization is disabled.

Fetch optimization is useful when there are several records in the result set and afetch next action takes place within the refresh interval, or if the entire table islocked by the query.

Row cachingRow caching is based on the fact that the last retrieved result (using fetch) isstored in a single-row cache. When two consecutive database requests are exactlyidentical, the result can be copied from a single-row cache. A restriction is thatthe second action takes place within the refresh time. This situation occursfrequently when joins are processed. Every time the outer row contains the samekey value, a DB.EQ on the outer table can be cached, so the request will not bepassed to the RDBMS.

Note that caching and fetch optimization are consistent for one Baan IV user.Database changes made in any of the sessions running within a single applicationvirtual machine will always disable current sets related to the update.Consequently, additional fetches will always fetch the new result. The changesmade by other users will not be reflected within the refresh time.



6-8

Optimistic and pessimistic reference checksTo optimize concurrency, the Baan IV DB2 database driver supports optimisticand pessimistic reference checks. In lookup reference mode, when inserts areperformed in a child table, the driver checks whether the reference exists in theparent table and locks the referenced record to be sure that another user cannotdelete it within the current transaction. This approach is called the pessimisticapproach.

This approach blocks an insert of another user referencing the same parent row,thereby affecting the concurrency. To avoid this problem there, is also anapproach where a row in the parent table that is not locked is used dependingupon the choice of the user. This approach is called the optimistic approach. Asthe record is not locked, another user can still perform an insert operation, whichimproves the concurrency. Enabling of this option is configurable via the dbsinitresource variable.

Locking behaviorThe Baan IV DB2 database driver uses the dirty read isolation level to read rowsfrom the table. The queries returning more than a single row do not acquire anytype of lock (shared or exclusive), unless this is explicitly stated within thequery. Queries such as SELECT FOR UPDATE, INSERT, DELETE andUPDATE acquire exclusive locks when the SQL_TXN_REPEATABLE_READisolation level is used. Only in case of lookup references are shared locksacquired when the SQL_TXN_COMMITED_READ isolation level is used. Thelocks are retained until the transaction is committed or aborted.

The actions that relate to DML locking can be executed with a certain timeoutvalue, which cancels the statement if the timeout is reached.

The following table gives an overview of the sections related to DML locking.

Actions related to DML locking

Action Default timeout Minimum timeout

[0] Select for update 1 0

[1] Insert 5 0

[2] Update 1 0

[3] Delete 1 0

[4] Lock table 1 0



6-9

The time-outs can be specified in the environment variable DB2_TIMEOUT asfollows:

DB2_TIMEOUT=”{[ value], [value], [value], [value], [value]}”

or through the resource variable db2_timeout as follows:

db2_timeout:”{[value], [value], [value], [value], [value]}”

Where the first value stands for the timeout for the action SELECT FORUPDATE, the second value for the timeout for action INSERT, and so on. Allparameters are optional and the values can be specified to indicate the timeoutfor the particular action. If the parameter is not specified, the default value isused. The minimum timeout value is also shown in the table above.

For example, the following setting of the DB2_TIMEOUT:

DB2_TIMEOUT=”{1, 5, 6, 4, 1}”

or

db2_timeout: ”{1, 5, 6, 4, 1}”

Leads to the following actions:

n SELECT FOR UPDATE: time-out of 1 secondn INSERT: time-out of 5 secondsn UPDATE: time-out of 6 secondsn DELETE: time-out of 4 secondsn LOCK TABLE: time-out of 1 second

If any of the timeout values are set, the database configuration parameterLOCKTIMEOUT should be set to a higher value than any of the timeout values.

Because the DB2_TIMEOUT option is implemented with the ODBCquerytimeout setting, the real timeout interval is always the value of theDB2_TIMEOUT plus the setting in the CLI/ODBC initialization file db2cli.ini

When set to 1 on the client file, the timeout interval effectively matches theDB2_TIMEOUT.

[Common]

QUERYTIMEOUTINTERVAL=1

NOTE:



6-10

High-level lock retries

When a row lock cannot be acquired, high-level lock retries are initiated. Thismeans that the same action is performed after a sleep period. The retry patterncan be defined by environment variable LOCK_RETRY or resource variablelock_retry. This can contain a comma, separated list of combinations of numberof retries and sleep periods in milliseconds (ms), for example:

LOCK_RETRY=”5*100,5*500”

or

lock_retry:”5*100,5*500” (resource variable)

This is the default retry pattern, which means that the action is retried 5 timeswith a sleep period of 100 ms and then 5 times with a sleep period of 500 ms.The lock retries can also be disabled by specifying:

LOCK_RETRY=”0”

or

lock_retry:”0”

This is a feature common to all database drivers.


7-1

Configuring and tuning the DB2 server is important to avoid performancebottlenecks and to optimize the performance of the Baan IV applications using aDB2 database. This chapter discusses the DB2 configuration and tuningparameters that have the most impact on the Baan IV environment. It alsodiscusses disk I/O configuration and data placement issues.

This chapter discusses the following topics:

n DB2 tuningn Disk I/O configuration and data placement

DB2 tuningBefore starting the DB2 engine by doing a db2start, you must export theDB2_RR_TO_RS=ON environment variable. When this variable is set, theadjacent rows in the table are not locked when the current row is updated ordeleted.

To tune DB2, you can tune the database manager configuration and adjustseveral database manager configuration parameters. This section describes someof the parameters you can tune. For more information, refer to the DB2Administration Guide.

Database manager configuration tuning

For every connection established with the database server, an ‘AGENT’ is startedby the DB2 Engine. MAXAGENTS should be appropriately set to accommodateall active applications. Each session in the Baan IV application virtual machineestablishes a new connection, and on average the number of connectionsestablished by a user’s application virtual machine is 3. It is recommended to setthe MAXAGENTS to three times the total number of users supported on thesystem.

Database configuration tuning

To estimate the performance of the DB2 environment, it is recommended thatyou take a snapshot to determine the buffer pool activity, lock escalationinformation, sort activity, the Package cache lookups, and Package cache insertsinformation.

7 DB2 configuration and tuning

DB2 configuration and tuning


7-2

In Baan IV, the SQL queries for the Level 1 driver are very simple. Theoptimization level is set to 0 to use indexes for scanning the rows. There shouldnot be any sort activity for the simple Baan IV Level 1 driver queries.

There should not be any lock escalation. If this occurs then it is advisable toincrease the value of MAXLOCKS and LOCKLIST. There is a sizable degreeof interdependency between these two parameters.

The ratio of package cache lookups to package cache inserts should be 100:1 toensure a good performing environment. Modify the value of PCKCACHESZ toreach this ratio.

It is recommended that you set the NUM_IOCLEANERS parameter value to

4 + the number of containers constituting the tablespace of the database

For example, if the table data tablespace consists of 6 containers on different diskdrives and there are another 6 containers for index data on different disk drives,then NUM_IOCLEANERS should be set to

4 + 12 = 16

Since the page cleaners are activated asynchronously, they will update the dirtypages on different disks, making the pages free and available for the databasedata.

Another parameter that can be changed if you are having lock escalations on thecatalog tables is the CATALOGCACHE_SZ parameter. Setting it to a highervalue will help avoid lock escalation on the catalog tables.

In a client/server environment, increase AGENTPRI from the default to givehigher priority to the database agent processes.

You should also increase your buffer pool size to an appropriate value for yoursystem. You can increase the buffer pool size with the ALTER BUFFERPOOLstatement. See the DB2 Administration Guide for more information.

The following configuration parameters show engineering benchmark values thatmay be used as startup values. More tuning may be required depending upon thehardware capabilities. These configuration parameters are for a system with atotal of 8 GB memory.



7-3

Database configuration parameters:

Degree of parallelism (DFT_DEGREE) = 1

Database heap (4KB) (DBHEAP) = 10000Catalog cache size (4KB) (CATALOGCACHE_SZ) = 512Log buffer size (4KB) (LOGBUFSZ) = 128Utilities heap size (4KB) (UTIL_HEAP_SZ) = 4096Buffer pool size (4KB) (BUFFPAGE) = 8000Extended storage segments size (4KB) (ESTORE_SEG_SZ) = 16000Number of extended storage segments (NUM_ESTORE_SEGS) = 0Max storage for lock list (4KB) (LOCKLIST) = 2500

Max appl. control heap size (4KB) (APP_CTL_HEAP_SZ) = 128

Sort list heap (4KB) (SORTHEAP) = 4096SQL statement heap (4KB) (STMTHEAP) = 3000Default application heap (4KB) (APPLHEAPSZ) = 256Package cache size (4KB) (PCKCACHESZ) = 10000Statistics heap size (4KB) (STAT_HEAP_SZ) = 4384

Interval for checking deadlock (ms) (DLCHKTIME) = 10000Percent of lock lists per application (MAXLOCKS) = 10Lock timeout (sec) (LOCKTIMEOUT) = -1

Changed pages threshold CHNGPGS_THRESH) = 80Number of asynchronous page cleaners (NUM_IOCLEANERS) = 4Number of I/O servers (NUM_IOSERVERS) = 8Index sort flag (INDEXSORT) = YESSequential detect flag (SEQDETECT) = YESDefault prefetch size (4KB) (DFT_PREFETCH_SZ) = 32

Default number of containers = 1Default tablespace extentsize (4KB) (DFT_EXTENT_SZ) = 32

Max number of active applications (MAXAPPLS) = 1000Average number of active applications (AVG_APPLS) = 50Max DB files open per application (MAXFILOP) = 64

Log file size (4KB) (LOGFILSIZ) = 4096Number of primary log files (LOGPRIMARY) = 12Number of secondary log files (LOGSECOND) = 4

Group commit count (MINCOMMIT) = 2Percent log file reclaimed before soft chckpt (SOFTMAX) = 900



7-4

Database manager configuration parameters:

Application support layer heap size (4KB)(ASLHEAPSZ) = 15Max requester I/O block size (bytes) (RQRIOBLK) = 32767Query heap size (4KB) (QUERY_HEAP_SZ) = 1000DRDA services heap size (4KB) (DRDA_HEAP_SZ) = 128

Priority of agents (AGENTPRI) = SYSTEMMax number of existing agents (MAXAGENTS) = 3000Agent pool size (NUM_POOLAGENTS) =720 (calculated)Initial number of agents in pool (NUM_INITAGENTS) = 0Max number of coordinating agents (MAX_COORDAGENTS) = MAXAGENTSMax no. of concurrentcoordinating agents (MAXCAGENTS)=MAX_COORDAGENTS

Maximum query degree of parallelism (MAX_QUERYDEGREE) = 1Enable intra-partition parallelism (INTRA_PARALLEL) = NO

Several CLI settings should be added for lower connection overhead. In the filedb2cli.ini, set the following parameters in the [Common] section:

ConnectionPooling = 1ConnectionPoolingInterval = 180QueryTimeoutInterval=1OptimizeForNRows = 5

If running DB2 with FixPack 7 (WR09084 available Dec/1998), connectionmultiplexing capabilities are available by using the following settings in thedb2cli.ini

Patch=17CloseOpen=1MultiConnect=3

NOTE:



7-5

Tuning for faster data loading

For better performance while populating your database, you should set severalparameters. One of these parameters is a DB2 database configuration parameter;the rest are Baan IV database driver resources that are set in the resource filedb_resource. These parameters are listed below.

These settings should not be used in a production environment.

DB2 database configuration parameter:

MINCOMMIT = 1

Database driver resources that should be set in the db_resource file:

ssts_set_rows:1000rds_full:100dbsinit:01db2_max_array_ssize:20

Disk I/O configuration and data placementThe goal of successful I/O configuration is to minimize situations wheretransactions in the server must wait on disk I/O. To accomplish this, it is usefulto understand the server’s I/O activity. In general, the server manages two typesof I/O: database activity and transaction log activity.

Database activity is routed through a complex and efficient read-ahead andbuffering system. It should rarely cause transactions to wait, assuming theserver’s read-ahead and buffering subsystems are configured adequately.

Database waits usually occur on reads when the cache does not contain dataneeded to satisfy a request. Database writes are normally accomplished in anasynchronous or write-behind fashion and the transaction need not wait for thisI/O to complete. However, the transaction log is the repository for changes to thedatabase during the course of a transaction, so it is wise to optimize writethroughput for I/O of this type. This is usually one of the first arguments forisolating data and log activity onto separate devices.

Because transactions depend on log writes, it is often better to isolate the logdevice from other DB2 devices. It is also good to isolate the log device fromother applications, including the operating system, at the hardware level. Thiswill reduce resource contention that could adversely affect throughput. It is bestto allocate the hardware in such a way as to favor log file write throughput.

NOTE:



7-6

It is recommended to have Baan IV tables, index data, and the DB2 systemcatalog on separate tablespaces on different disks to improve performance. It isalso recommended that the table and index tablespaces mentioned above arecreated as database managed space (DMS) using raw devices.

After creating the raw devices, make sure that the raw devices are owned by theinstance and belong to the database administrator group db2.

For more detailed information of the configuration parameters refer to the DB2Administration Guide.

NOTE:


8-1

This appendix lists all the database driver resources and environment variablesthat can be used as configuration parameters to modify the behavior of the DB2database driver. Some of these resources are used with the client and others withthe server. In this context, the client is the Baan IV application virtual machineand the server is the Baan IV DB2 database driver. If the Baan IV applicationvirtual machine and the database driver are running on different machines, clientresources must be set on the machine running the Baan IV application virtualmachine and server resources must be set on the machine running the databasedriver. Resources for both the client and the server must be set on both machines.

A description of how to set the database driver resources and environmentvariables can be found in the Environment variables section.

This appendix provides the following information:

n Summary of DB2 resources and environment variablesn Detailed description of DB2 resources and environment variables

Summary of DB2 resources and environmentvariablesThere are four types of resources and environment variables that can be usedwith the Baan IV DB2 database driver:

n Client and server resources used by all Baan IV database driversn Client resources used by all Baan IV database driversn Server resources used by all Baan IV database driversn Resources used only by the Baan IV DB2 database driver

The following four tables provide a summary of each of these types of resourcesand environment variables. Detailed descriptions of each entry in the tables areincluded in this chapter.

8 Appendix A: Database driverresources and environment variables

Appendix A: Database driver resources and environment variables


8-2

Client and server resources used by all Baan IV database drivers

Resource name Environment variable Description

rds_full RDS_FULL Sets maximum number of rows transferred inone block

tt_sql_trace TT_SQL_TRACE Allows viewing of SQL query information

use_shm_info USE_SHM_INFO Enables or disables shared memory use

Client resources used by all Baan IV database drivers


bdb_debug BDB_DEBUG Sets debugging link between client and server

bdb_driver BDB_DRIVER Sets database specifications

bdb_max_server_schedule

BDB_MAX_SERVER_SCHEDULE

Defines mechanism for terminating idledatabase drivers

ssts_set_rows SSTS_SET_ROWS Sets number of rows read ahead (single tablesingle row)

USR_DBC_RES Specifies alternative resource file for client

Server resources used by all Baan IV database drivers


bdb_max_session BDB_MAX_SESSIONS Defines number of sessions per driver

bdb_max_session_schedule

BDB_MAX_SESSION_SCHEDULE

Defines mechanism for closing idle driversessions

dbslog DBSLOG Allows driver profiling

DBSLOG_LOCK_PROF Specifies lock time above which locks arelogged

DBSLOG_NAME Allows file name to be specified for logging

dbsinit Specifies optimistic or pessimistic referencechecking

enable_refmsg ENABLE_REFMSG Causes logging of denied updates of deleteactions

lock_retry LOCK_RETRY Defines the number of lock retries and thesleep period between retries

USR_DBS_RES Specifies alternative resource file for server



8-3

Resources used only by the Baan IV DB2 database driver


DB2_ARRAY_FETCH Enables array fetching

DB2_ARRAY_INSERT Defines maximum number of rows for arrayinserts

db2_ddl_timeout DB2_DDL_TIMEOUT Sets timeout value for DDL statements

DB2_DUMP_MESG Specifies location for message log

DB2_EXPLAIN Enables Explain Snapshot facility

db2_max_array_sizze

DB2_MAX_ARRAY_SIZE

Adjusts buffer size for array fetches

db2_max_conn DB2_MAX_CONN Sets maximum number of connections to DB2

db2_max_open_handles

DB2_MAX_OPEN_HANDLES

Sets number of open cursors per driverconnection

db2_max_ret_rows DB2_MAX_RET_ROWS

Sets maximum number of rows returned fromDB2

db2_minmem DB2_MINMEM Allows sqlda size to be adjusted

db2_opt_level DB2_OPT_LEVEL Sets query optimization level

db2_opt_rows DB2_OPT_ROWS Adjusts number of rows retrieved

DB2_PRINT_ERROR Allows additional debugging information to bedumped

DB2PROF Allows profiling

db2_ref_timeout DB2_REF_TIMEOUT Sets timeout value for referential integritychecks

DB2STAT Allows statistics to be gathered

db2_timeout DB2_TIMEOUT Sets locking timeout behavior



8-4

Detailed description of DB2 resources andenvironment variablesThis section provides detailed information about the Baan IV DB2 driverresources and environment variables. The driver resources are divided into twosections: those that are generic to all Baan IV database drivers and those that arespecific to the Baan IV DB2 driver. Each group of resources is listed inalphabetical order.

Generic driver resources

bdb_debug / BDB_DEBUG

Driver resource bdb_debug

Environment variable BDB_DEBUG

Client/Server resource Set for client only

Type Integer (octal)

Default 0

Description This variable is used to generate debugginginformation about the communication between theclient and the database driver. When set, the clientprints debugging information to standard error (stderr).The following categories of debugging information canbe specified:

00001 server types

00002 database actions

00004 delayed lock actions

00010 reference information

00040 TSS info from %BSE%\lib\tss_mbstore

00100 permission information

Multiple categories can be defined by adding the octalvalues. The value is compared bitwise to determine if agiven category should be logged.



8-5

bdb_driver / BDB_DRIVER

Driver resource bdb_driver

Environment variable BDB_DRIVER


Type String

Default None

Description This variable is used to set a database specification,usually found in the file tabledef6.1. When this variableis set, all tables will be accessed using the databasedriver specified and tabledef6.1 will not be read. Thedriver specified must be defined in the file%BSE%\lib\ipc_info.

bdb_max_server_schedule / BDB_MAX_SERVER_SCHEDULE

Driver resource bdb_max_server_schedule

Environment variable BDB_MAX_SERVER_SCHEDULE


Type Integer

Default 3

Description This variable defines the mechanism for terminatingidle database drivers by the application virtual machine.Whenever the database driver has no more opensessions, it can be terminated by the application virtualmachine. Closing an idle database driver is done aftera number of schedule ticks. A schedule tick isgenerated whenever a Baan IV session is ended. Atthis point, all idle database drivers will have a schedulecounter incremented. When the value of the schedulecounter reaches the value ofbdb_max_server_schedule, the database driver isterminated.



8-6

bdb_max_sessions / BDB_MAX_SESSIONS

Driver resource bdb_max_sessions

Environment variable BDB_MAX_SESSIONS

Client/Server resource Set for server only

Type Integer

Default 0 (unlimited)

Description This variable defines the number of sessions per driver.If any driver has reached this threshold, a new driverwill be started to handle any new sessions.

bdb_max_session_schedule / BDB_MAX_SESSION_SCHEDULE

Driver resource bdb_max_session_schedule

Environment variable BDB_MAX_SESSION_SCHEDULE


Type Integer

Default 3

Description This variable defines the mechanism for closing idlesessions in the driver. Whenever the client process hasno more references (cursors or queries) to the session,it can be closed by the client. Closing an idle session isdone after a number of schedule ticks. A schedule tickis generated whenever a Baan IV session is ended. Atthis point, all idle sessions will have a schedule counterincremented. When the value of the schedule counterreaches the value of bdb_max_session_schedule, thesession is closed

The default for bdb_max_session_schedule is three.Setting bdb_max_session_schedule to one wouldresult in fewer connections from the driver to theRDBMS since whenever a Baan IV session is ended,the corresponding RDBMS session (logon) is closed(logoff).



8-7

dbsinit

Driver resource dbsinit

Environment variable —



Default 0

Description This variable allows flags to be set to specify theoptimizations to be used. At this time, legal values are000 (not set) and 001. Other values are reserved andshould not be used.

A flag of 00001 specifies that an optimistic approachshould be used when checking for references in parenttables. The referenced row in the parent table is notlocked, improving the overall concurrency. If this flag isnot set, optimistic reference checking is not used.Optimistic and pessimistic reference checks aredescribed on Page 6-8.

Other values are reserved for future use and should notbe used. Multiple categories can be defined by addingthe octal values. The value is compared bitwise todetermine if a given category should be logged.



8-8

dbslog / DBSLOG

Driver resource dbslog

Environment variable DBSLOG



Default 0

Description This variable provides detailed debugging informationabout the online processing of the driver. Theinformation is logged in the file dbs.log in the driver’scurrent directory. The following debugging categoriescan be specified:

0000001 Data Dictionary info of tables within thedriver

0000002 Query info (SQL Level 1)

0000004 Query plan info (SQL Level 2)

0000010 Row action information

0000020 Table action information

0000040 Transaction action information

0000100 DBMS input/output data (SQL Level 2)

0000200 Administration file info (SQL drivers)

0000400 DBMS SQL statements

0001000 General debug statements

0002000 Query processing info (for tt_sql_trace info)

0004000 Data buffering info (communication)

0100000 Lock retries logged (includes session name)

0200000 Logs successful locks and longest lockduration in a transaction

Multiple categories can be defined by adding the octalvalues. The value is compared bitwise to determine if agiven category should be logged.



8-9

DBSLOG_LOCK_PROF

Driver resource —

Environment variable DBSLOG_LOCK_PROF


Type Floating point number

Default 0

Description Specifies the minimum duration of a lock that should belogged. Any locks of shorter duration will not be logged.This variable specifies the minimum number ofseconds, to a precision of milliseconds, that shouldelapse before a lock is logged. Lock time is calculatedas the time from when the first record in a transaction islocked to the time of the commit or abort. This is thelongest time a record remains locked during atransaction. Please note that the appropriate dbslogcategories must be set.

DBSLOG_NAME

Driver resource —

Environment variable DBSLOG_NAME


Type String

Default dbs.log

Description Allows a file name to be specified where DBS logginginformation is to be written. If there is already a file withthe same name, it will be used for logging. If the file islocked during write operations, multiple servers canuse the same log file.

enable_refmsg / ENABLE_REFMSG

Driver resource enable_refmsg

Environment variable ENABLE_REFMSG


Type Boolean

Default 0 (disabled)

Description There are two valid values for this variable: 0 and 1.When it is set to 1, a log message is generated in thedatabase driver log file when an update of a deleteaction has been denied because of existing references.When it is set to 0, no log messages are generated.



8-10

lock_retry / LOCK_RETRY

Driver resource lock_retry

Environment variable LOCK_RETRY


Type String

Default 5*100,5*500

Description This variable defines the high-level locking behaviorthat is used when an action is locked. It defines thenumber of retries and the length of the sleep periodsbetween retries in milliseconds (MS). For example, forthe default setting, the action is retried five times with asleep period after each try of 100 MS. The action isthen retried five more times with a sleep period of 500MS after each retry.

rds_full / RDS_FULL

Driver resource rds_full

Environment variable RDS_FULL

Client/Server resource Set for both client and server

Type Integer

Default 5

Description This variable defines the maximum number of rowstransferred between the Baan IV application virtualmachine and the driver as one block. Multiple blocks(and thus network round trips) are transferred if morerows are requested. This variable should be set to thesame value for both client and server.



8-11

ssts_set_rows / SSTS_SET_ROWS

Driver resource ssts_set_rows

Environment variable SSTS_SET_ROWS


Type Integer

Default 3

Description This variable defines the number of rows to be readahead for a fetch request from the client. The default isthree rows, which means that for one fetch request,three rows will be read. For the following two fetchrequests, rows will be taken from the client row bufferor fetched from the database without re-executing thequery.

tt_sql_trace / TT_SQL_TRACE

Driver resource tt_sql_trace

Environment variable TT_SQL_TRACE



Default 0

Description This variable is introduced to view the Baan IV SQLquery information being handled in client and server.When this variable is set, the client prints debuginformation to the display; the server prints informationonly if the dbslog variable allows it. The informationcontains different categories which can be enabledseparately, such as evaluation trees, SQL statements,bind variables, timings, and communication debugging.The possible values of the TT_SQL_TRACE variableand their descriptions are shown below:

000040 (c) Show queries with their QID

000200 (c) Show query execution times

002000 (c) Show calls of internal SQL functions

004000 (c+s) Show query execution tree

010000 (s) Show query evaluation plan

020000 (s) Show FullTableScan



8-12

use_shm_info / USE_SHM_INFO

Driver resource use_shm_info

Environment variable USE_SHM_INFO


Type Boolean

Default 1 (enabled)

Description This variable can be used to enable or disable the useof shared memory to each of the database driver DDs.There are two valid values for this variable: 0 and 1.When it is set to 0, shared memory is disabled. When itis set to 1, shared memory is enabled.

USR_DBC_RES

Driver resource

Environment variable USR_DBC_RES


Type String

Default None

Description This variable contains the file specification of analternative resource file for the client. The filespecification is based on the BSE directory and iswithin double quotes. When set, any resources in thealternative resource file override the same clientresources set in db_resource.

USR_DBS_RES

Driver resource

Environment variable USR_DBS_RES


Type String

Default None

Description This variable contains the file specification of analternative resource file for the client. The filespecification is based on the BSE directory and iswithin double quotes. When set, any resources in thealternative resource file override the same serverresources set in db_resource.



8-13

DB2 driver specific resources

DB2_ARRAY_FETCH

Driver resource —

Environment variable DB2_ARRAY_FETCH


Type Boolean


Description This environment variable is used to enable or disablethe array fetch interface. The valid values are 0 and 1.When set to 0, the fetch interface is disabled. When setto 1, it is enabled. Refer to Page 6-1 for informationabout the array interface.

DB2_ARRAY_INSERT

Driver resource —

Environment variable DB2_ARRAY_INSERT


Type Boolean


Description This environment variable is used to enable or disablethe array insert interface. The valid values are 0 and 1.When set to 0, the array insert interface is disabled.When set to 1, it is enabled. Note that this optioncannot always be enabled. For example, if referencesmust be checked or updated or the application requiresimmediate response from the driver as to whether theinsert is successful, no array insert can be done. Thevalid values are 0 and 1. When set to 0, the arrayinterface is disabled. When set to 1, it is enabled. Referto Page 6-1 for information about the array interface.

db2_ddl_timeout / DB2_DDL_TIMEOUT

Driver resource db2_ddl_timeout

Environment variable DB2_DDL_TIMEOUT


Type Integer

Default 240

Description Determines the time-out value, in seconds, for DDL(create object) statements.



8-14

DB2_DUMP_MESG

Driver resource —

Environment variable DB2_DUMP_MESG


Type String

Default %BSE%\log\log.db2

Description This environment variable allows the location of thelog.db2.mesg file to be specified. By default, it is storedin the %BSE%\log directory. This variable should bethe fully qualified filename where error messages willbe written.

DB2_EXPLAIN

Driver resource —

Environment variable DB2_EXPLAIN


Type Boolean

Default 0

Description This variable is used to enable the Enable Snapshotfacility. It can be set to the following values:

0 no explain output

1 Set CURRENT EXPLAIN SNAPSHOT=yes will besent to the server to enable the Explain Snapshotfacility. The explained information is inserted in theSNAPSHOT column of theEXPLAIN_STATEMENT table.

Note that the EXPLAIN_STATEMENT table must havebeen created earlier.



8-15

db2_max_array_size / DB2_ MAX_ARRAY_SIZE

Driver resource db2_max_array_size

Environment variable DB2_MAX_ARRAY_SIZE


Type Integer

Default 1

Description If the array interface is enabled, this variable definesthe maximum number of rows fetched at once from theRDBMS. This can be set on a per-table basis using theARR_SIZE parameter in the db2_storage file. Refer toPage 6-1 for information about the array interface.

db2_max_conn / DB2_MAX_CONN

Driver resource db2_max_conn

Environment variable DB2_MAX_CONN


Type Integer

Default 0

Description Determines the maximum number of connections asingle driver can have to the RDBMS. The default is 0,which implies that there is no limit.

db2_max_open_handles / DB2_MAX_OPEN_HANDLES

Driver resource db2_max_open_handles

Environment variable DB2_MAX_OPEN_HANDLES


Type Integer

Default 30

Description Limits the number of open cursors the driver maintainson a per connection basis. Each cursor represents onetype of SQL statement. A maximum of 200 and aminimum of one open statement handles are allowedper connection.



8-16

db2_max_ret_rows / DB2_MAX_RET_ROWS

Driver resource db2_max_ret_rows

Environment variable DB2_MAX_RET_ROWS


Type Integer

Default 0

Description This variable specifies the maximum number of rows tobe returned to the driver by the DB2 engine. Thedefault is 0, which implies that all rows are returned.

db2_minmem / DB2_MINMEM

Driver resource db2_minmem

Environment variable DB2_MINMEM


Type Boolean

Default 1

Description This variable specifies that DB2 CLI is not to allocatesqlda’s of size 255 for each statement; it is to attemptto build sqlda’s closer to the size of that required for thestatement and possibly have to reallocate sqlda’s ifthey grow bigger than the one allocated. This will savememory but could result in extra network crossingsbetween the driver and database server.

db2_opt_level / DB2_OPT_LEVEL

Driver resource db2_opt_level

Environment variable DB2_OPT_LEVEL


Type Integer

Default 0

Description Sets the query optimization level for SQL queries. Thedefault and recommended value is 0, which means thatindex scans are used. Refer to DB2 documentation forpossible query optimization class values and theirrespective meaning.



8-17

db2_opt_rows / DB2_OPT_ROWS

Driver resource db2_opt_rows

Environment variable DB2_OPT_ROWS


Type Integer

Default 0

Description This option allows you to specify to DB2 that no morethan n rows will be retrieved. This will allow DB2 tooptimize the fetch request. It is assumed that thenumber of rows retrieved will not exceed n rows. Basedon this value, DB2 determines a suitablecommunication buffer size to improve performance.

DB2_PRINT_ERROR

Driver resource —

Environment variable DB2_PRINT_ERROR


Type Integer

Default Not set

Description This environment variable can be set to dumpadditional debugging information in the %BSE%\logdirectory on error conditions.

DB2PROF

Driver resource —

Environment variable DB2PROF


Type Floating point

Default Not set

Description When a value is specified in this variable, anystatement that takes more than the number of secondsspecified will be logged. The maximum precision thatcan be specified is 0.01 seconds. This variable is usedto determine which table actions are the most timeconsuming.



8-18

db2_ref_timeout / DB2_REF_TIMEOUT

Driver resource db2_ref_timeout

Environment variable DB2_REF_TIMEOUT


Type Integer

Default 1

Description Determines the time-out value, in seconds, forreferential integrity checks.

DB2STAT

Driver resource —

Environment variable DB2STAT


Type Integer

Default Not set

Description This variable allows database driver statistics to bereported. If it is set to a value n greater than 0, statisticsare logged every n seconds while the driver is active. Ifit is set to 0, a statistics report is generated when thedriver terminates.

db2_timeout / DB2_TIMEOUT

Driver resource db2_timeout

Environment variable DB2_TIMEOUT


Type String

Default {1,5,1,1,1}

Description This resource specifies the timeout intervals (inseconds) for different request types. The commaseparated list defines the timeout intervals for thefollowing requests: select for update, insert, update,delete, lock table. For more information on lockingbehavior, see the Locking behavior section.



8-19

DB2 environment variables

The following environment variables can be set to control the actions of DB2directly. These are supported by DB2 and not Baan IV but do benefit theperformance of the Baan IV application. They must be set before starting theDB2 server.

n DB2_RR_TO_RS=ONThis variable will prevent next-key index locks from being held on updates ofrecords. This improves the concurrency in the Baan IV application.

n DB2INSTANCE=instanceThis variable must be set to indicate the DB2 instance against which Baan IVwill be running.

n DB2_LOCK_TO_RB=STATEMENTWhen this variable is set as above, deadlock timeouts will result in only thestatement being rolled back and not the entire transaction.



8-20


9-1

The storage file provides a way to specify the distribution of table and index datain different segments. Storage parameters are used by the database driverwhenever a DDL statement such as a create table or create index statement isexecuted. The following is an example of an entry in the storage file:

T_SPACE userspace1 I_SPACE indexspace1

In this example, the database driver adds the “in <tablespace name> index in<index tablespace name>” clause to the create statement during index or tablecreation. If the tablespace for a table or index is not specified, the table and indexdata are created in the default segment. If index data is to be separated, it isnecessary to specify a tablespace.

A storage file is defined for each database driver. The storage file for theBaan IV DB2 database driver is called db2_storage and is located in thedirectory %BSE%\lib\db2.

The entries in the db2_storage file consists of fields that are the same for thestorage files for all database drivers and storage parameters that are specific tothe DB2 database driver. This appendix describes the fields that make up theentries in the db2_storage file.

Storage file formatThe storage file consists of one or more entries, each consisting of several fieldsseparated by colons. The format of an entry in the storage file is as follows:

[{<user list>}]<table/module specification>:<company number>:<object type>: <private |group>:<table/index optimization>:<refresh time>:<storage parameters>

The following describes each of the fields in an entry in the storage file.

9 Appendix B: Storage file format andconfiguration options

Appendix B: Storage file format and configuration options


9-2

Storage file field descriptions

user list

Description This field consists of a list of comma-separated usernames to which this entry applies. When no list isspecified, the entry applies to all users.

Example {maria,john}

table/module specification

Description This field consists of a list of comma-separated tablenames or a module name to which the entry applies.An asterisk (*) indicates all tables.

Example ttadv000,ttadv999 two specific tables

ttadv all tables in module tt and packageadv

tt all tables in module tt

* all tables

company number

Description This field consists of a list of company numbers towhich the entry applies. An asterisk (*) indicates allcompany numbers.

Example 000,999 companies 000 and 999

* all companies

object type

Description This field consists of a list of object (table or index)identifications to which the entry applies. The followingoptions can be specified:

T table only

I all indexes

I <index number> only specified index

* both table and indexes

Example I1,I2 only index 1 and 2

T only for table



9-3

private | group

Description This field identifies the owner of the table. Eitherprivate or group should be specified.

table/index optimization

Description Specific flags related to indexes and tables can bespecified. When specified on a “T” object entry, itdefines the default for all indexes.

The following octal values can be used to set the flagsfor a specific index or table:

0000 no optimization

0001 optimization using both ascending anddescending indexes

0010 index order ascending only

0020 index order descending only

Default values can be defined for each table entry.Optimizations are explained in more detail in Chapter6.

Example 0001

refresh time

Description This specifies the amount of time (in seconds) that aretrieved dataset is considered valid. No fetch from thedatabase will be made if the same request is madewithin this time.

Example 5



9-4

storage parameters

Description These are defined by the specific database driverimplementation and often map to table and indexcreation options available in the host RDBMS.

The following DB2 storage parameters are defined:

ARR_SIZESet the array size for array fetches and inserts.

T_SPACESet the tablespace in which the table is to reside.

I_SPACESet the tablespace in which the indexes for a table areto reside. Note that this goes on the T entry and not theI entry.

Example ARR_SIZE 5

The storage file is scanned from the beginning whenever a create table or createindex is performed. The first entry that matches the table or index is taken, so theorder in which the entries are specified is important. For example:

{mary,john}ttadv999,ttadv000:000:T:private: 01:5: T_SPACE userspace1 I_SPACE index1{mary,john}ttadv999,ttadv000:000:I::01:5tdsfc:505:T:group:01:5: ARR_SIZE 5*:*:T:group:01:5: T_SPACE dataspace1 I_SPACE index2*:*:I:group:01::

In the example above, the users mary and john will create tables ttadv999 andttadv000 of company 000 in tablespace userspace1. The associated indexes willbe created in tablespace index1. All users creating tables in module tdsfc willcreate tables and indexes in the default tablespace and will use array sizes of 5.Other users create tables and indexes in tablespaces dataspace1 and index2,respectively.

If the tablespace for a table or index is not specified, the table and index data arecreated in the default tablespace. If you want to separate the index data, you mustspecify a tablespace.

NOTE:

NOTE:

baan iv · pdf filei db2/nt database driver technical reference manual for baan iv 1...

Documents