DB2/400 Database Driver Technical Reference Manual...DB2/400 Database Driver Technical Reference Manual 1-1 The database driver plays an important role in Baan’s commitment to open

BaanERPDB2/400 Database Driver Technical ReferenceManual

A publication of:

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

Printed in the Netherlands

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

The information in this documentis subject to change withoutnotice. No part of this documentcan 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: U7162C USGroup: User DocumentationEdition: CDate: May 1999

i

DB2/400 Database Driver Technical Reference Manual

1 BaanERP database driver overview 1-1The BaanERP architecture 1-1Display tier 1-2Application tier 1-2Database tier 1-3Data flow through the BaanERP architecture 1-4BaanERP hardware configurations 1-5

2 BaanERP database organization 2-1BaanERP 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-2Database driver SQL processing 3-2Record level access API 3-2SQL processing 3-3Setting driver behavior 3-3Driver resources 3-3Environment variables 3-4Storage file 3-6

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

5 Database driver profiling and statistics 5-1Profiling 5-1To gather statistics 5-3

Table of contents

Table of contents


ii

Troubleshooting 5-5Logging database driver trace information 5-5Logging errors 5-6

6 Database driver configuration and tuning 6-1Index optimization 6-1Indexes that allow duplicate values 6-2Hash column naming convention 6-2Size of hash columns 6-2Specifying index optimization 6-3Fetch optimization 6-3Row caching 6-5Optimistic and pessimistic reference checks 6-5Locking behavior 6-5High-level lock retries 6-6

7 DB2/400 configuration and tuning 7-1

8 Appendix A: Database driver resources and environment variables 8-1Summary of DB2/400 resources and environment variables 8-1Detailed description of DB2/400 resources and environment variables 8-3Generic driver resources 8-3DB2/400 driver specific resources 8-12

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


iii

This document supplies technical reference information about the BaanERPdatabase driver for DB2/400. This document is intended for those who want toconfigure or customize the BaanERP database driver for DB2/400. Anelementary knowledge of OS/400 including DB2/400 is assumed as well as anunderstanding of database technology.

The procedure for installing the DB2/400 and BaanERP software is described inthe Installation Guide for BaanERP on AS/400.

This document describes the BaanERP database driver that forms the interfacebetween the BaanERP application server layer and DB2/400. The formal namefor this database driver is the BaanERP database driver for DB2/400. Forsimplicity, the database driver is referred to as the BaanERP DB2/400 driver.

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

Chapter 1 provides an overview of the BaanERP database driver architecture andhow the database driver fits in the BaanERP system.

Chapter 2 describes the BaanERP database organization and details the namingconventions used for data and objects in the DB2/400 database.

Chapter 3 describes some of the internal features of the BaanERP DB2/400database driver.

Chapter 4 describes several aspects of database security provided by theBaanERP DB2/400 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 BaanERP DB2/400database driver.

Chapter 7 details the configuration and tuning options for the DB2/400 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 BaanERP DB2/400 database driver.

About this document

About this document


iv


1-1

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

The following topics are covered in this chapter:

The BaanERP architecture Data flow through the BaanERP architecture BaanERP hardware configurations

The BaanERP architectureBaanERP supports a three-tier architecture that consists of a display tier, anapplication tier, and a database tier. The display tier provides presentationservices for user interaction. The application tier consists of the BaanERPapplication Virtual Machine, the application objects, and the database driver. Thedatabase tier includes the third party RDBMS product that acts as the databaseserver. Figure 1 depicts the BaanERP architecture.

The emphasis of this document is the BaanERP database driver. The databasedriver is the interface between the BaanERP applications and the RDBMS server.The database driver translates database requests from the BaanERP applicationVirtual Machine to RDBMS-specific database requests that it sends to thedatabase server. After the database server retrieves the requested information, thedatabase driver then passes the data back to the BaanERP application VirtualMachine.

1 BaanERP database driver overview

BaanERP database driver overview


1-2

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

ApplicationVirtual Machine

(bshell)

Display Tier

Application Tier

Database Tier

Database Driver

Display Driver

Application Objects

Database Server(RDBMS)

Figure 1, BaanERP three-tier architecture

Display tier

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

Application tier

The application tier includes the application objects, the BaanERP applicationVirtual Machine, and the database driver. Together, the application objects andthe application Virtual Machine provide much of the functionality of BaanERP.

The application objects include the compiled BaanERP applications and the datadictionary.



1-3

The BaanERP applications provide the functionality needed to implement theBaan Enterprise Resource Planning (ERP) system. These applications are writtenin Baan 3GL or Baan 4GL programming languages supported by BaanERPTools.

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

The BaanERP 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 required for communication withthe database server. A running database driver can support multiple connectionsto a single RDBMS instance. If a BaanERP 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 BaanERP application Virtual Machine has traditionally been called theBaanERP shell or more often simply the bshell. Throughout the remainder of thisdocument, it is referred to as the BaanERP application Virtual Machine or theapplication Virtual Machine.

Database tier

The database tier consists of the database server. The database driver provides acommon interface between the BaanERP application Virtual Machine and thedatabase server. Communication between the application Virtual Machine andthe database driver is the same, no matter which RDBMS product is used as thedatabase server. There is one database driver for each of the RDBMS productsthat BaanERP 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 six third party RDBMS products: Oracle,Informix, Sybase, DB2, Microsoft SQL Server, or DB2/400. All BaanERPapplication data is stored in a relational database managed by an RDBMS. Youcan have multiple RDBMS products in one BaanERP installation, with somedata residing in one database server and other data residing in another.

With DB2/400, you can have several installations of the BaanERP software andcorresponding databases in the same server. Each installation is given its ownSQL collections to store the database data.



1-4

Data flow through the BaanERP architectureNote that the database driver provides an interface between the BaanERPapplication Virtual Machine and the specific RDBMS server being used. Theflow of data through the system is described below.

If a user performs an operation at a GUI workstation, the display server interpretsthe input and sends the information to the BaanERP application Virtual Machine.Based on the information it receives, the application Virtual Machine causes theappropriate application object to be carried out.

If a running application object requires information that is stored in the database,the application Virtual Machine sends the request to the database driver. Datarequests from the client applications are RDBMS independent and are made byusing BaanERP SQL, an RDBMS-independent SQL language.

If the application Virtual Machine carries out 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 startsa new instance of the database driver. The application Virtual Machine parses theBaanERP SQL database query it receives from the application object and sendsan internal representation of the query to the database driver. The internalrepresentation of the query that the database driver receives is still RDBMS-independent.

The database driver translates the database query into an appropriate query byusing SQL statements or API calls compatible with the specific RDBMS beingused. Each database driver takes advantage of the design of the particularRDBMS that it supports so that the resulting SQL statements and API calls arevalid for the RDBMS and provide the best possible performance. The RDBMSspecific SQL statements and API calls are then submitted to 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 detected 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 can also send a message to thedisplay server, which displays an appropriate message on the user’s workstation.



1-5

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

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

The simplest client/server configuration is sometimes thought of as a variation ofthe standalone mode. In this configuration, the application tier, database driver,and RDBMS are on one machine, while the display drivers are distributed amongthe user workstations. An instance of the application Virtual Machine and at leastone instance of the database driver are started for each user. All users haveaccess to the same application objects and database servers. This configuration isillustrated in Figure 2.


(bshell)

Database Driver

Display Driver Display Driver

Application ObjectsApplication

Virtual Machine(bshell)

Database Driver


Figure 2, Client/Server configuration I



1-6

If 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 VirtualMachine and at least one instance of the database driver are started for each user.All users have access to the same application objects and database servers. Thisclient/server configuration is illustrated in Figure 3. This configuration uses theBaanERP method of client/server access between the application VirtualMachine and the database server.


(bshell)

Database Driver




Database Driver


Figure 3, Client/Server configuration II



1-7

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 are started for each user. All users have access tothe same application objects and database servers. This client/serverconfiguration is illustrated in Figure 4. This configuration uses the RDBMS’sability to provide client/server access.


(bshell)

Database Driver




Database Driver


Figure 4, Client/Server configuration III

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

The database driver determines the system name for the database table by usingthe DB4_HOME specified in the tabledef6.2 file. For example,

*:*:db2400(DB4_HOME=FRITE)

specified in the tabledef6.2 file would mean that all files for this BSE aremanaged by the DB2/400 driver and are stored on FRITE system.

NOTE



1-8


2-1

All of the application data used by BaanERP is stored in database tables in theRDBMS. To keep the majority of the BaanERP processing independent of theRDBMS, BaanERP 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 in tables, and indexes to data in the tables. This chapter describes thedata dictionary and the naming conventions used by the BaanERP databasedrivers to access data stored in the RDBMS. It also discusses how BaanERP datatypes are mapped to DB2/400 data types.


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

BaanERP 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 in a database table.

The BaanERP database drivers maintain a data dictionary because the data usedby the BaanERP applications can differ from the database tables defined in theRDBMS. The BaanERP data dictionary maps BaanERP 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.

BaanERP data dictionary information can be kept in shared memory where it willbe available to all running BaanERP application Virtual Machines. The datadictionary information is shared among all the sessions open in a single databasedriver.

2 BaanERP database organization

BaanERP database organization


2-2

The BaanERP data dictionary cannot be used directly by the database driver tocreate DB2/400 tables. This is because not all BaanERP data types exactly matchDB2/400 data types or limits. To create valid DB2/400 tables, the driver mustperform some mapping or translation. When mapping the BaanERP datadictionary to tables in DB2/400, conventions are used for the table names,column names, and index names.

Table naming conventionThe table name of a BaanERP table stored in DB2/400 has the following format.

t

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

n PackageThe package is a two-letter code that refers to the BaanERP package thatcreated the table. For example, a table created by the BaanERP Toolspackage has the tt.package code

n DD Table NameThe DD table name is the name of the table used in the data dictionary. Thedata dictionary table name consists of three letters followed by three digits.The letters refer to the application that uses the table and the digits indicatethe order in which the tables were created.

n Company NumberIn BaanERP, three digits company numbers are used to differentiate areas offunctionality. There must be a company with the number 000. In addition,there can be several other company numbers.

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

Note that in DB2/400, this will be the SQL name of the table (available whenyou are accessing the table using SQL). However, the system will also generate asystem name for the table. The system name will be the first 5 characters of theSQL table name followed by a sequence number. For example, the tablettadv999000 will have a system name of ttadvxxxx where xxxxx is a sequencenumber generated by the system.



2-3

Column naming conventionEach column in the BaanERP data dictionary corresponds to one or morecolumns in a DB2/400 table.

The rules for column names are as follows:

n GeneralWhen a BaanERP column name is created in DB2/400, it is preceded by thet_string. For example, the BaanERP column with the cpac name is created inDB2 with the t_cpac name. By preceding column names with t_, reservedwords are avoided. If a column name contains a period [ . ], the period isreplaced by the underscore [ _ ] character.

n Long string columnsBecause DB2/400 supports character columns up to 32,766 bytes, no specialprocessing in necessary for long string columns.

n Array columnsIn the BaanERP data dictionary, array columns can be defined. An arraycolumn is a column that contains multiple elements. The number of elementsis called the depth. For example, a column that contains a date can be definedas an array of three elements—a day, a month, and a year. In DB2/400, thethree elements of the array column are placed in separate columns. Thenames of these columns include a suffix with the element number. Forexample, an array column called date will become:

− t_date_1: element 1− t_date_2: element 2− t_date_3: element 3

n Array compressionBecause DB2/400 supports up to 8,000 columns per table, array compression(combining separate logical columns into a single database column) is notnecessary in DB2/400.



2-4

Index naming conventionA sequence number for each table, starting from one (1) identifies BaanERPindexes. Each table has at least one index: the primary index. DB2/400 requiresthat 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 theorder, either ascending or descending.

Index names have the following format:

i_

For example, the index name for BaanERP tables with the name ttadv999, indexnumber 1, company number 000, and index type ascending order is:

ittadv999000_1a

If a BaanERP index is defined as a unique index, then the DB2/400 index iscreated with the UNIQUE clause. The UNIQUE clause prevents duplicate rowsfrom being created in the table.

Again, a system name will be assigned to the index. The system name will be thefirst five characters of the index name followed by a sequence number.



2-5

Data type mappingThe following table shows the mapping between BaanERP data types and theirDB2/400 counterparts.

Mapping between BaanERP and DB2/400 data types

BaanERP data types DB2/400 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 BaanERP DB2/400 driver uses the CHAR data type when ANSI-compliant behavior is expected for character data, such as with the BaanERPstring type. This DB2/400 data type is used because a BaanERP string data typehas characteristics that conform to the ANSI specification for character data.When the CHAR data type is used, operations such as comparison andconcatenation can 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 you map BaanERP data to DB2/400 data:

n All names generated by the database driver are in lowercase characters andare not enclosed in double quotation marks. Since an ASCII sort order isselected during the installation, DB2/400 treats object names with casesensitivity.

n All columns created by the DB2/400 driver have the NOT NULL constraint.BaanERP applications do not support NULLS.

n If a BaanERP index is defined as a unique index, then the DB2/400 index isalso created with the UNIQUE clause. Otherwise, indexes which allowduplicates are not defined with the UNIQUE clause.

n The date range for the BaanERP application Virtual Machine is the same asthe range for DB2/400 with the following exception. The application VirtualMachine date 0 is mapped to the DB2/400 date 1. The application VirtualMachine date 1 is marked as an invalid date.


3-1

The DB2/400 database driver converts RDBMS-independent database requestsinto requests designed specifically for DB2/400. This chapter describes some ofthe internal processing that occurs in the BaanERP DB2/400 database driver.First, some of the features that ensure data integrity are discussed. Next, theinternal processing of a SQL statement in the driver is explained. The finalsection of this chapter describes the mechanisms that allow the default behaviorof the database driver to be modified.

In this chapter the following BaanERP DB2/400 database-driver internal issuesare discussed:

n Data integrityn Database driver SQL processingn Setting driver behavior

Data integritySeveral features of the BaanERP 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 BaanERPDB2/400 database driver to ensure referential integrity, to work with distributeddatabases, and to apply data buffering techniques. Locking strategies arediscussed in detail in Chapter 6.

Referential integrity

Referential integrity preserves the defined relationships between tables whenrecords are maintained. The BaanERP database driver has a built-in mechanismfor preserving referential integrity, and does not depend on the underlyingRDBMS for maintaining referential integrity.

3 Database-driver internal processing

Database-driver internal processing


3-2

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.

When multiple rows are returned from a query, the rows are buffered and thensent back to the BaanERP application Virtual Machine as one block. Datareduction and compression is applied to compact the data, this minimizes 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 or API calls that are appropriate to the specific RDBMSbeing used. This section details the SQL processing performed by the BaanERPDB2/400 database driver. Because the BaanERP DB2/400 database driver usesthe record level access API of DB2/400 this will be described first.

Record level access API

The DB2/400 driver uses the record level access API to communicate withDB2/400. This API is a set of C functions that can be called from a C program toretrieve records from DB2/400. The remote version of the extended dynamicSQL API is also used to distribute the API calls to the system that contains theSQL collection (the extended dynamic SQL API contains a remote program callmechanism).

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

n Logon to DB2/400 (open session)n Open a tablen Fetch records (by key, next, prev)n Map input variables to key requestn Map record to requested output variablesn Fetch the resulting rowsn Commit/abort transactionn Close a cursorn Log off from DB2/400 (close session)



3-3

SQL processing

SQL statements are dynamically generated by the database-dependent layer ofthe BaanERP DB2/400 database driver. Because BaanERP applications aredynamic, it is not known in advance which tables will be used at run time. It istherefore not possible to prepare the queries before run time.

In the BaanERP DB2/400 database driver, SQL statements are processed inseveral steps. This section describes these steps.

When the BaanERP DB2/400 driver receives a query from the applicationVirtual Machine, the query is translated into suitable record level access APIcalls. This results in positioning a cursor to the record requested by the inputkeys. After the query is carried out, a fetch operation is done and the resultingcolumn values are placed in the bound output variables. The rows returned byDB2/400 are passed to the database independent layer of the BaanERP DB2/400database driver, which sends the results back to the application Virtual Machine.

Data can be manually placed into the database by using the BaanERP utilitybdbpost6.2. This utility is used to place data into a new database table or toappend data to an existing database table. Certain options can be set when usingbdbpost6.2 (see the BaanERP Tools Technical Manual). When bdbpost6.2 isused with the -f option, the rows are buffered by default and are flushed when thearray buffer is full. Array buffering is not supported in the initial version of theDB2/400 driver, however DB2/400 maintains read and write buffers to improveperformance.

Setting driver behaviorThere are several facilities available for configuring the BaanERP DB2/400database driver. The most common is through driver resources. Two otherfacilities for configuring the BaanERP DB2/400 database driver are environmentvariables and the storage file. The driver resources and environment variables aredescribed in more 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 BaanERP DB2/400 database driver. These parameters are set in afile called the resource file (db_resource). There is one resource file for alldatabase drivers that run in a BaanERP environment; resources for all thedatabase driver types can be found there. A database driver reads the parametersset in the resource file when it is first invoked.

NOTE



3-4

The resource file can 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:

dbsinit:01

When you modify the behavior of the database driver, it is often necessary tomodify the behavior of the BaanERP 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.

The resource file, db_resource, is located in the $BSE/lib/defaults, directory,$BSE refers to the directory where the BaanERP software environment isinstalled. When both the database driver and the application Virtual Machine runon the same machine, there will be only one db_resource file containing all thenecessary resources parameters. When the database driver and the applicationVirtual Machine run on different machines, there must be one db_resource filelocated on the machine running the database driver, which contains the serverresources. And another db_resource file must be located on the machine that runsthe application Virtual Machine that contains the client resources.

In addition to the default resource file, db_resource, you can set up an alternativeresource file to override resource values for specific users or groups of users. Thealternative 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 that contains an alternative resource file for the server and must beset on the machine that runs the database driver. USR_DBC_RES is used tospecify the path to a file that contains an alternative resource file for the clientand must be set on the machine that runs the application Virtual Machine. Anydriver resource set in the alternative resource file will override the setting of thesame driver resource in db_resource. The next section describes how to set thedatabase-driver 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.



3-5

For the most part, there is an environment variable that corresponds 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 that runs the application Virtual Machine to override the correspondingdriver resource.

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 in the database. There are three ways to set the database driver serverenvironment variables:

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

n By manually modifying the BaanERP tabledef6.2 file

n By using the OS/400 commands, ADDENVVAR, CHGENVVAR andWRKENVVAR

The BaanERP Database Definitions (ttaad4510m000) session is therecommended method to modify database driver behavior. When specific tablesand companies are to be configured for access with a specific database driver, theTables by Database (ttaad4111m000) session must be used. These sessions causeenvironment variables for a particular database driver to override the defaults setin the resource file and allow the environment variables to be maintainedcentrally.

The Database Definitions (ttaad4510m000) session maintains database driverconfiguration information in a file called tabledef6.2. This file is stored in the$BSE/lib directory residing on the machine where the database driver runs.While it is recommended that the Database Definitions (ttaad4510m000) sessionbe used to maintain this file, advanced users can modify this file manually.

The format of the tabledef6.2 file is as follows:

::(=)

If multiple environment variables are to be specified for a single table andcompany number, they are listed in the parentheses and separated by commas.



3-6

If all tables or all companies are to be specified, the asterisk (*) is used in placeof table name or company number. For example, the following entry can bemade in the tabledef6.2 file:

tccom010:812:db2400(DB4PROF=0.4, DB4_HOME=frite)

In this example all the queries on tccom010812 table which require at least 0.4seconds are logged in the DB4PROF file. Note that this table is considered tohave a different database definition from other tables. If a DB2/400 driver isalready running, but is accessing a different table, a separate driver will bestarted for this table. Environment variables that appear in the driverspecifications of the tabledef6.2 file are put into the driver’s environment beforeit is invoked, so that they are available 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 (ttaad4510m000) session for theseusers.

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 that runs the applicationVirtual Machine and must be set using the standard operating system methodsused for setting environment variables. Any client environment variables that areused override the equivalent resource variables set for the client in thedb_resource file.

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. This is necessary to determine into which SQL collection (OS/400library) to put the table or index.

COLLECTION

A storage file is defined for each database driver. The storage file for theBaanERP DB2 database driver is called db4_storage and is located in the$BSE/lib/db4 directory. The format of the storage file is described in detail inAppendix B.


4-1

The BaanERP DB2/400 database driver maintains security by controlling useraccess to the database and user access to database objects. The BaanERPdatabase administrator (DBA) module allows the DBA to control access to thedatabase using BaanERP sessions. Using the DBA module makes DBA taskseasier and less prone to errors than using database driver tools directly. Thischapter first discusses how the BaanERP DB2/400 database driver handles issuesrelated to database 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 and then describes how the BaanERP DB2/400 driver provides objectsecurity and authentication.

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 BaanERP group consists of a database name and methods for providing objectsecurity and authentication in the database. The BaanERP group name is thesame as the name of the database that holds the BaanERP data in the RDBMS.The BaanERP group uses the mechanisms of the RDBMS to provide objectsecurity and authentication.

4 Database security

Database security


4-2

A BaanERP 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 logon.

In DB2/400, a BaanERP group is made up of two components: a logon (forauthentication) and an operating system group (for object security). The logon isthe same name as the BaanERP group and is assigned database owner privilegesin the database. The logon must have authority to the SQL collection(s) that willbe used for this BaanERP installation. An OS/400 group is created whichbecomes the target for privileges granted on objects in the database. Users areassociated with the operating system group and, as a result, inherit the privilegesgranted to the group. The advantage of having a group table is that the membersof the group can share and operate on the same data in a single table.

For example, users maria and john can both be assigned to BaanERP groupbaandb. Group baandb owns the tables and grants select, insert, delete, andupdate privileges to the operating system group. As a result, users maria and johninherit the select, insert, delete, and update privileges granted to the operatingsystem group, allowing them to access and manipulate BaanERP group tabledata.

The BaanERP user is shielded from the RDBMS groups. The database driverdoes all the processing that is needed to make use of the RDBMS groups. Onlythe database administrator needs to be concerned about the RDBMS groups, andthe BaanERP DBA module allows the administrator to easily maintain theRDBMS groups.

Object security

In DB2/400, 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 aBaanERP environment where many users access the same tables in the DB2/400database, a mechanism has been developed to allow users to share these tables.

To allow different BaanERP users to share the same DB2 table, the groupconcept is used. A BaanERP group maps users to an OS/400 group that isauthorized to the collection(s) that must be shared among the users. TheBaanERP DB2/400 driver uses an operating system group to implement theBaanERP group concept. Initially the group is granted *CHANGE privileges tothe database.

Database security


4-3

Any user associated with the operating system group automatically inherits theseprivileges and can individually perform these operations on the BaanERP 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. If the user is dropped from the operating system group,these privileges are revoked. The user no longer has access to tables in thatoperating system group. If the privileges to operate on the tables are explicitlygranted to the user, then they must also be explicitly revoked when the user isdropped 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 must be created as a group table or as a privatetable. When a table is identified as a private table, the user becomes the ownerand no privileges are given to other users. When a table is identified as a grouptable, the table is created by the group logon and the privileges are granted to thegroup, allowing all users in the group to access the table. A table can beconfigured as private or group via the $BSE/lib/db4/db4_storage file.

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), wherethe create table is carried out. When creating objects identified as belonging tothe group, the user who creates the object logs into DB2/400 as the group user. Inthis case the group will own the table and permissions are granted on it to allowall group users access. When creating objects identified as private, users areconnected to DB2 under their own logon. When private objects are created, theuser owns them; no other permissions are granted.

A table’s configuration is defined in the $BSE/lib/db4/db4_storage file. 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 in theappropriate field. For example:

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

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

Database security


4-4

Authentication

DB2/400 uses the operating system’s authentication mechanism to determinewhether a user is authorized to access a database. When a database is created, anadministrator or DB2/400 database owner grants access permission to anoperating system group. Access permission can be granted for the entire databaseor for specific database objects. There is a special profile that is used to establishthe database connection. By default (from the installation), this user profile isBAANCONNDB, with password CONNDB. If the password forBAANCONNDB must be changed, or you need a different profile to establishthe connection, this can be specified in the${BSE}/etc/AS400.settings/db4connect file. The format of this file is

:

Note that this profile is only used for the initial connection; the actual databasework is done under the profile specified in the db4_users or db4_groups file.

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

The members that belong to the group authorized to the collection 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 BaanERP group using the BaanERP DBA(database administration) module or the db4_mai6.2 utility. Note that any DBAmodule or db4_mai6.2 action will affect the operating system user or group; itonly affects the BaanERP administration files. You can manage the databaseusers from the db4_mai6.2 module.

Note that there are database users and BaanERP users (which are usually thesame for a host-mode configuration). For a distributed configuration (or whendifferent users are used for the database user and the BaanERP user), BaanERPusers however must be created at the operating system. Use of the administrationmodule to create a BaanERP user only create the u or r file; youwill still need to create the operating system user and authorize the user to thecreated file.

Users who are authorized to access the database are registered in the BaanERPdriver administration files. The user name and password each BaanERP user willuses to log on to the DB2/400 is maintained in the $BSE/lib/db4_users file.

Database security


4-5

All the BaanERP users and their corresponding OS/400 (on the database server)logon names and passwords and the name of the group they are assigned to aredefined in the $BSE/lib/db4/db4_users file. The format of each entry in this fileis as follows:

:::

The BaanERP DB2/400 driver is started by the BaanERP application VirtualMachine on behalf of the user. From the $BSE/lib/db4/db4_users file the driveridentifies the OS/400 user and the user’s password, and establishes theconnection to DB2/400.

The group logon procedure also includes a password, which is defined in the$BSE/lib/db4/db4_groups file. The format is as follows:

:

The group name is the same as an OS/400 group name.

DBA moduleThe DBA module maintains the database administration files used by theDB2/400 database driver. This module allows an administrator to registerauthorized users and to give users access to data. This tool is provided with theBaanERP DB2/400 database driver to maintain the administration files that thedatabase driver needs at run time. The administration files are stored in the$BSE/lib/db4 directory.

The DBA module implements the user and group administration functions for allBaanERP database drivers. The db4_mai6.2 utility is an executable programcalled by the DBA module that implements the functions necessary to makechanges in DB2/400. While you can call the db4_mai6.2 utility from outside theDBA module, the DBA modules is easier to use.

The DBA module is described in more detail in the Installation Guide forBaanERP on AS/400.

Database security


4-6


5-1

The OS/400 function STRDBMON can be used to analyze databaseperformance. This function is described in the DB2/400 Programming Guide inthe OS/400 documentation. Note that the use of this function can significantlyaffect the performance of the database and must be used sparingly.

The BaanERP DB2/400 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 BaanERP DB2/400 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 can 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 carried out. Logging all statements withtheir timings, however, results in a log file that is so large it cannot be properlyanalyzed. You can define a logging threshold where only statements that takemore 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 theDB4PROF environment variable to a number of seconds. For example,DB4PROF can be set as follows:

export DB4PROF=5.0

5 Database driver profiling andstatistics

Database driver profiling and statistics


5-2

It sets DB4PROF to five seconds, causing statements that take more than 5.0seconds of elapsed time to be logged to the db4prof file. The db4prof file isstored in the directory where the driver was started.

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 DB4PROF file is shown below.

Profiling value = 0.00 secPid Table Owner I Mode Cache Exe Fetch Exe Fetch Tot tiitm001812 jim 1 FIRST : - 0.01 0.00 - - 0.04< 8024> tiitm001812 jim 1 FIRST : - 0.01 0.00 - - 0.05 tiitm001812 jim 1 FIRST : 0.00 - - - - 0.00 tiitm001812 jim 1 FIRST : 0.00 - - - - 0.00 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 tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00 tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00 tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00 tiitm001812 jim 1 NEXT : - - 0.00 - - 0.00 tiitm001812 jim 1 NEXT : - - 0.01 - - 0.01 tiitm001812 jim 1 NEXT* : - - 0.01 0.01 0.00 0.02 tiitm001812 jim 1 NEXT* : - - 0.00 0.01 0.00 0.01 tiitm001812 jim 1 PREV : - 0.00 1.02 - - 1.05 tiitm001812 jim 1 PREV : - - 0.01 - - 0.02 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.



5-3

Statement execution time can be viewed for individual tables by setting theDB4PROF environment variable in the $BSE/lib/tabledef6.2 file. For example,the following entry can be made in the file:

tccom010:812:db2(DB4PROF=0.4)

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

To gather 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, executes, fetchesn Number of logons (sessions)n Number of inserts, updates, deletesn Number of commits, rollbacks

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

The following are examples of how DB4STAT can be set:

export DB4STAT=0export DB4STAT=30

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



5-4

Below is a sample output of DB4STAT. Since the report is generic for alldatabases, some information, such as the specific row actions, can not beappropriate for a particular database driver.

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 db4statfile are:

n Index optimization, 1 column (that is, single hash)n Key only optimizationn Extend refresh time (this is controlled at the DB2/400 level and must be

adjusted using CHGPF)

Below an example is given of the db4_storage file where the specification ofindex optimization for tuning is clearly shown.

tccom010:*:T:group:01:5:COLLECTION BAANDATAtccom010:*:I::01::COLLECTION BAANDATAtccom012:*:I1:group:01::COLLECTION BAANDATAtccom013:*:I1::01::COLLECTION BAANDATAtccom022:*:I1,I5::01::COLLECTION BAANDATAtccom020:*:I2::01::COLLECTION BAANDATAtiitm001:*:I1::01::COLLECTION BAANDATAtiitm050:*:T:group:01:5:COLLECTION BAANDATAtiitm050:*:I::01::COLLECTION BAANDATA*:*:T:group:01:5:COLLECTION BAANDATA*:*:I::01::COLLECTION BAANDATA

TroubleshootingThe BaanERP DB2/400 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 by using the DBSLOG environment variable. Debugginginformation is appended to the dbs.log file 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 forcategories of interest only.

Logging errors

The driver logs its error messages in the log files in the $BSE/log directory. Thelog files are called log.DB4_SRV6.2 and log.db4.mesg.

The following information 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 application

If 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 database-specific 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 BaanERP DB2/40 database driver is designed to allow tuning for optimalperformance. Several parameters used by the database driver are preset withdefault values that must provide acceptable system performance, but since everyenvironment is different, the default values of these parameters can not provideoptimal performance. This chapter discusses the BaanERP DB2/400 databasedriver parameters that can be set, and the changes in driver behavior that you canexpect when you adjust these parameters.


n Index optimizationn Fetch optimizationn Row cachingn Optimistic and pessimistic reference checksn Locking behavior

Index optimizationIndex optimization is a technique used in Level 1 drivers to obtain betterperformance for SELECT statements in relational databases. Because BaanERPLevel 1 drivers generate queries that are not very complex, the driver can takeadvantage of several attributes of BaanERP 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 BaanERPdata 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 nonunique indexesto make them unique. Finally, a raw data type can be chosen as the storage typefor the hash column. The combination of key reduction (concatenation into asingle column) and index uniqueness has been found to give performance gainsin Level 1 drivers.

Note that the DB2/400 driver has no gain in performance by utilizing hashcolumns. This is due to the natural match of the low-level database interface usedby the Baan DB2/400 driver. Index optimization must not be used with theDB2/400 driver unless instructed by IBM or Baan service personnel.

6 Database driver configuration andtuning

Database driver configuration and tuning


6-2

Indexes that allow duplicate values

If a BaanERP index is created on a key that can have duplicate values, theresulting index is unique because the primary key parts are appended to the hashcolumn to make it unique.

Hash column naming convention

The name of the hash column in a BaanERP application table is formed by usingthe hash keyword and the index number for which it is being created. Forexample:

hash1 : ascending hash column for index 1

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.



6-3

Specifying index optimization

Index optimization can be specified per table and per index in the$BSE/lib/db4/db4_storage file. To specify whether index optimization must beused, the following (octal) values are available:

0000 optimization without using hash column (this is the preferred DB2/400 setting)0001 optimization using 1 column ( single hash )0010 Index order ascending only0020 Index order descending only0100 Key only optimization

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.

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

DB.FIRSTDB.NEXTDB.NEXTDB.NEXTand so on

If 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 multirow result set, subsequent rows that satisfy the query are also fetchedand returned to the client. Rows updated or deleted in other concurrentconnections between fetches can not be reflected in this set of rows. The changesmade in other concurrent connections will only be reflected when the query isreexecuted.



6-4

You may not need to see all row changes at the exact moment they occur, andcould simply fetch the next row from the existing (buffered) row set, instead ofreexecuting the statement to get the most current view. This technique is referredto as fetch optimization.

Critical to the use of this technique is the definition of a refresh time that allowsyou to specify a time interval, in seconds, for which a fetch-optimized set of rowsis valid. As long as the set is deemed valid, data can be fetched from the bufferedrow set. Changes that occurred as a result of activity in other connections sincethe query was carried out are not reflected in the data. If the row set expires (thatis, refresh time is exceeded), the statement automatically reexecutes in the driverbefore the next row is returned.

For example, let’s assume that a set of rows is retrieved when DB.FIRST isissued. For a refresh time of five seconds, the DB.NEXT call fetches the nextrow from the fetch-optimized set of rows. All consecutive DB.NEXT calls in fiveseconds are not fetched from the database, but are fed from the buffered row setuntil the buffer is exhausted. After five seconds the set is considered invalid anda subsequent DB.NEXT causes a reexecute of the query and fetch from thedatabase. This results in a performance improvement by reducing the number ofquery executions. This translates into a reduced RDBMS server load and reducednetwork traffic.

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 db4_storage file can contain the following entries:

*:*:T:group:010:5:*:*:I:group:010::

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

The following example shows two entries that can be set in the db4_storage file:

*:*:T:group:010::*:*:I:group:010::

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 in the refresh interval, or if the entire table is lockedby the query.



6-5

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 in the refresh time. This situation occurs frequentlywhen joins are processed. Every time the outer row contains the same key value,a DB.EQ on the outer table can be cached, so the request is not passed to theRDBMS.

Note that caching and fetch optimization are consistent for one BaanERP user.Database changes made in any of the sessions running in 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 in the refresh time.

Optimistic and pessimistic reference checksTo optimize concurrency, the BaanERP DB2/400 database driver supportsoptimistic and pessimistic reference checks. In lookup reference mode, wheninserts are performed in a child table, the driver checks whether the referenceexists in the parent table and locks the referenced record to be sure that anotheruser cannot delete it in the current transaction. This approach is called thepessimistic approach.

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 depending onthe choice of the user. This approach is called the optimistic approach. As therecord is not locked, another user can still perform an insert operation, whichimproves the concurrency. Enabling of this option is configurable by means ofthe dbsinit resource variable.

Locking behaviorThe BaanERP DB2 database driver uses the *CHG to read rows from the table.The queries that return more than a single row, do not acquire any type of lock(shared or exclusive), unless this is explicitly stated in the query. Queries such asSELECT FOR UPDATE, INSERT, DELETE and UPDATE acquire exclusivelocks when *RR isolation level is used. Shared locks are acquired when the *CSisolation level is used only in case of lookup references. The locks are retaineduntil the transaction is committed or aborted.



6-6

The actions that relate to DML locking can be carried out with a certain timeoutvalue, which cancels the statement if the timeout is reached. The timeout value iscontrolled at the DB2/400 level by using the RCDWAIT keyword on the CHGPFcommand.

High-level lock retries

If a row lock cannot be acquired, high-level lock retries are initiated. This meansthat the same action is performed after a sleep period. The retry pattern can bedefined by the LOCK_RETRY environment variable or the lock_retry resourcevariable. This can contain a comma, separated list of combinations of number ofretries 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 five timeswith a sleep period of 100 ms and then five 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/400 server is important to avoid performancebottlenecks and to optimize the performance of the BaanERP applications usinga DB2/400 database. BaanERP must be tuned in the same manner as otherapplications running on the AS/400. See the Work Management Guide and thePerformance Tuning books for information on tuning an AS/400.

Each BaanERP installation has a unique set of work management objects(subsystem, class, and job description) to tune the performance of a BaanERPinstallation against the other work on the system. The name of the subsystem andlibrary are chosen at installation time. The job description and class is found inthe same library with the same name as the subsystem.

7 DB2/400 configuration and tuning

DB2/400 configuration and tuning


7-2


8-1

This appendix lists all the database driver resources and environment variablesthat can be used as configuration parameters to modify the behavior of theDB2/400 database driver. Some of these resources are used with the client andothers with the server. In this context, the client is the BaanERP applicationVirtual Machine and the server is the BaanERP DB2/400 database driver. If theBaanERP application Virtual Machine and the database driver are running ondifferent machines, client resources must be set on the machine running theBaanERP application Virtual Machine and server resources must be set on themachine that runs the database driver. Resources for both the client and theserver must be set on both machines.

A description of how to set the database driver resources and environmentvariables can be found beginning on Page 3-3.

This appendix provides the following information:

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

Summary of DB2/400 resources andenvironment variablesThere are four types of resources and environment variables that can be usedwith the BaanERP DB2/400 database driver:

n Client and server resources used by all BaanERP database driversn Client resources used by all BaanERP database driversn Server resources used by all BaanERP database driversn Resources used only by the BaanERP DB2/400 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 canbe found beginning on Page 8-3.

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 BaanERP 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 BaanERP 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 BaanERP 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 BaanERP DB2/400 database driver


DB400_DUMP_MESG Specifies location for message log

DB4PROF Allows profiling

DB4STAT Allows statistics to be gathered

Detailed description of DB2/400 resourcesand environment variablesThis section provides detailed information on the BaanERP DB2/400 driverresources and environment variables. The driver resources are divided into twosections: those that are generic to all BaanERP database drivers and those thatare specific to the BaanERP DB2/400 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 on the communication between the clientand the database driver. When set, the client printsdebugging information to standard error (stderr). Thefollowing categories of debugging information can bespecified:

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 must be logged.



8-4

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 tabledef6.2 file. When this variableis set, all tables will be accessed using the databasedriver specified and tabledef6.2 will not be read. Thedriver specified must be defined in the$BSE/lib/ipc_info file.

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 VirtualMachine. Whenever the database driver has no moreopen sessions, it can be terminated by the applicationVirtual Machine. Closing an idle database driver isdone after a number of schedule ticks. A schedule tickis generated whenever a BaanERP session is ended.At this point, all idle database drivers will have aschedule counter incremented. When the value of theschedule counter reaches the value ofbdb_max_server_schedule, the database driver isterminated.



8-5

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 driver iswill 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,the client can close it. Closing an idle session is doneafter a number of schedule ticks. A schedule tick isgenerated whenever a BaanERP 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 3.Setting bdb_max_session_schedule to 1 would resultin fewer connections from the driver to the RDBMSsince whenever a BaanERP session is ended, thecorresponding RDBMS session (logon) is closed(logoff).



8-6

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 andmust not be used.

A flag of 00001 specifies that an optimistic approachmust 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-5.

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



8-7

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 dbs.log file in the driver’scurrent directory. The following debugging categoriescan be specified:

0000001 Data Dictionary info of tables in the driver

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 must be logged.



8-8

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 must belogged. Any locks of shorter duration are not logged.This variable specifies the minimum number ofseconds, to a precision of milliseconds, must elapsebefore a lock is logged. Lock time is calculated as thetime 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. If itis set to 1, a log message is generated in the databasedriver log file when an update of a delete action hasbeen denied because of existing references. If it is setto 0, no log messages are generated.



8-9

lock_retry / LOCK_RETRY

Driver resource lock_retry

Environment variable LOCK_RETRY

Client/Server resource Set for

Documents

DB2/400 Database Driver Technical Reference Manual...DB2/400 Database Driver Technical Reference Manual 1-1 The database driver plays an important role in Baan’s commitment to open