When the DBMaker database engine is started or when a user wants to connect to a database server, DBMaker must initialize several parameters to configure itself. These parameters are read from an ASCII text configuration file named dmconfig.ini. This text file contains the keywords and their corresponding values that will be used by DBMaker for configuration. Since this file is in ASCII format, a DBA can edit this file with a text editor to change these parameters if necessary.

In most cases, these keywords are required when a database starts up. If a keyword is changed after the database is started, it will not take effect until the next time the database starts. However, some of the keywords are only required when users connect to database servers. Users can change these keywords after the server is started, but before the connect command is issued if they wish the new values to be used for that session.

The configuration parameters play an important role in the performance of DBMaker. Therefore, you should be aware of the effects of each configuration parameter and estimate the best values to use to ensure DBMaker will run smoothly. It is recommended that a DBA backup the dmconfig.ini configuration file as well as the database files.

A.2 dmconfig.ini File Format

The dmconfig.ini file is an ASCII text file. It can be edited with any text editor capable of opening and saving ASCII text files. The dmconfig.ini file consists of many sections, where each section is made up of the configuration information used to start a particular database. Each section begins with the section name, followed by a list of keywords and their values. The format of dmconfig.ini is shown below:

[section_name_1]
keyword1 = value1          ; here is a comment
keyword2 = value2
.
.
[section_name_2]
keyword3 = value3 value4   ; spaces or commas may be used 
keyword4 = value5          ; as delimiters
.
.

Section Names

The name of each section corresponds to the name of the database that will use the configuration options found in that section when it starts up. The section name begins with a left square bracket ([) followed by the name of the database, and ends with a right square bracket (]). The brackets are required to enclose the section name, and the left bracket must be the first character on that line.

Keywords

Following each section name is a list of keywords and their values. These values will be used by the database that corresponds to the section heading for configuration when it starts. The statement keyword=value assigns the specified value to a keyword. The value of a keyword can be an integer or a string, depending on the keyword itself.

Comments

Any string or symbol that is written after the semi-colon (;) will be considered a comment and ignored by DBMaker. An example dmconfig.ini file is shown below:

[SDB]
DB_DbFil=SDB.DB
DB_JnFil=SDE.JNL
DB_SMode=1                    ;normal start mode
DB_UMode=0                    ;single-user
DB_BMode=1
DB_BkSvr=1
DB_BkTim=96/03/19 00:00:00
DB_BkItv=7-00:00:00
DB_NBufs=100
DB_NJnlB=200
DB_NTran=100
DB_DbfSz=50
DB_JnlSZ=20000
file1=SDE.FIL 40

[EMP]
DB_DBFIL=EMP.DB
DB_JNFIL=EMP.JNL
DB_SMode=1                    ;normal start mode
DB_UMode=1                    ;multi-user
DB_NBufs=100
DB_NJnlB=400
DB_NTran=100
DB_DbfSz=50
DB_JnlSZ=20000
file1=EMP.FL1 100
file2=EMP.FL2 200

In the example, the dmconfig.ini contains two sections-one for the SDB database and the other for the EMP database.

A.3 Search Path for dmConfig.ini

Another issue for dmconfig.ini is where to locate this file. For UNIX systems, DBMaker will search in three locations for the dmconfig.ini file. These locations and the order they are searched are:

1. the current directory

2. the directory specified in the environment variable DBMAKER

3. for UNIX systems: the subdirectory data in the home directory for the user dbmaker (~dbmaker/data)

For Microsoft Windows systems the dmconfig.ini file must be placed in the directory to which you installed Windows (usually the WINDOWS directory, unless you changed the default when installing Windows).

When starting a database, DBMaker will scan the above three directories (or the WINDOWS directory on Microsoft Windows) in the order listed above to locate a dmconfig.ini file with a section name that corresponds to the database. If a dmconfig.ini file is found and the section name is also found, the keywords defined in that section will be used. If the section name can't be found in that file, DBMaker will continue searching for a dmconfig.ini file in the next directory until the section name is found.

A.4 Default Values for Keywords

Whenever DBMaker needs a parameter, it will search the corresponding keywords in the proper section of the dmconfig.ini file. Note that the pattern matching for section names or keywords in a search is case insensitive, except for user-defined files. If a keyword cannot be found in dmconfig.ini, a default value for that keyword will be used. Most of the keywords have their own default values. Please refer to the last section of this appendix to obtain more information.

A.5 Creation of dmConfig.ini

Normally the DBA must create the corresponding section in the dmconfig.ini with a text editor before a database is created, so that those parameters will take effect when creating that database. However, if DBMaker can't find the section in dmconfig.ini while creating a database, it will automatically create the section in the first dmconfig.ini found or in a new dmconfig.ini, if not found. Therefore a section for each database should always be found at startup time. If it is not, DBMaker will return an error.

A.6 Keyword Reference

DB_AtCmt=<value>

This keyword specifies whether auto-commit mode is on or off. Setting this value to 1 turns auto-commit mode on and setting it to 0 turns auto-commit mode off. When auto-commit mode is on, DBMaker will automatically issue a COMMIT TRANSACTION after each SQL command is successfully executed. This keyword is set from the client side.

default value: 1
valid range: 0, 1
see also: DB_LTimO

DB_BbFil=<string>

This keyword specifies the name of the system BLOB file. The system BLOB file will be created with the size specified by DB_BBFSZ when the database is created. It will expand as necessary as more BLOB data is inserted into this file.

default value: database name suffixed with .BB (for example, db.BB).
valid range: string with length < 80
see also: DB_BbfSz, DB_DbDir

DB_BfrSz=<value>

This keyword specifies the size of each BLOB frame in kilobytes. This keyword is used when the database is created.

default value: 16 (KB) for UNIX, Windows 95, Windows NT
valid range: 8~256 for UNIX, Windows 95,Windows NT
see also: DB_BbFil, DB_BbfSz

DB_BkDir=<string>

This keyword specifies the directory where the backup server puts the database backup files. This directory must already exist and can be different from DB_DBDIR. See also Chapter 9 - Database Backup, Recovery and Restoration.

valid range: string with length < 80
see also: DB_BkSvr, DB_Bmode

DB_BkFul=<value>

This keyword specifies the percentage that all journal files must be filled to before the backup server is triggered to do an incremental backup. Setting this value to 0 will trigger the backup server whenever a journal file is full. Setting this value between 50-100 will trigger the backup server whenever the total space used in all of the journal files exceeds the specified percentage. For example, if there are two journal files of 500 journal blocks each and DB_BKFUL is set to 80, then after every 500 x 2 x 0.8 = 800 blocks are used, the backup server will automatically do an incremental backup. Also see Chapter 9 - Database Backup, Recovery, and Restoration.

default value: 0
valid range: 0, 50 ~ 100
see also: DB_BkSvr, DB_BkTim, DB_BkItv

DB_BkItv=<string>

This keyword specifies the backup time interval. Please refer to DB_BKTIM described later.

default value: none (no backup schedule if DB_BkItv is not set)
see also: DB_BkSvr, DB_BkTim, DB_BMode

DB_BkCmp=<value>

This keyword specifies whether the compact backup mode is used. Not every journal block in a journal file is needed to perform a backup. If this keyword is set to 1, the backup server will only back up those journal blocks that require back up to save disk space. Also see the chapter Database Backup, Recovery, and Restoration.

default value: 1
valid range: 0,1
see also: DB_BkSvr

DB_BkSvr=<value>

This keyword specifies whether or not a backup server will be started when a database is started. Setting this value to 1 will start a backup server for that database. Also see the chapter Database Backup, Recovery, and Restoration.

default value: 0
valid range: 0,1
see also: DB_BkSml, DB_BkDir, DB_BkFul, DB_BkTim, DB_BkItv

DB_BkTim=<string>

This keyword along with DB_BKITV specifies the schedule of the backup server. DB_BKTIM specifies the first time a backup server will do an incremental backup. Incremental backups will then be performed after every time interval specified in DB_BKITV. For example:

DB_BkTim = 96/05/01 00:00:00 ;backup begins from May 1, 1996.
DB_BkItv = 1-12:30:00        ;interval is every 1 day, 12 hours, 30 min.

The keywords DB_BKTIM and DB_BKITV are meaningful only when the backup server is started. Also see the chapter Database Backup, Recovery, and Restoration.

default value: none (no backup schedule if DB_BKTIM is not set)
see also: DB_BkItv, DB_BkSvr, DB_BMode

DB_BMode=<value>

This keyword specifies the backup mode of a database. Setting the value to 0 is enables NON-BACKUP mode, 1 enables BACKUP-DATA mode, and 2 enables BACKUP-DATA-AND-BLOB mode. Also see the chapter Database Backup, Recovery, and Restoration.

default value: 0
valid range: 0 ~ 2
see also: DB_BkSvr

DB_CBMod=<value>

This keyword specifies the behavior of the cursor after the end of a transaction. A value of 1 indicates all still open cursors will be closed after any transaction is committed. A value of 2 indicates all still open cursors will be kept open after a transaction is committed. In both cases, the cursor will be closed if any transaction is aborted.

default value: 3
valid range: 1 ~ 3

DB_CTimO=<value>

This keyword specifies the connection time-out value in seconds when a client is trying to connect to the database server. If a database has not been started or the server IP address is wrong, users may be forced to wait a long time until the connection times out. Users can set the value of this keyword to shorten the waiting time. This parameter is set from the client side.

default value: 5 (seconds)
valid range: 5 ~

DB_DaiFm=<value>

This keyword specifies the date input format for SQL statements. Please refer to the ODBC Programming Guide - Appendix B for more information.

default value: none (accept all date input formats)
valid range:
mm/dd/yy
mm-dd-yy
dd/mon/yy
dd-mon-yy
mm/dd/yyyy
mm-dd-yyyy
yyyy/mm/dd
yyyy-mm-dd
dd/mon/yyyy
dd-mon-yyyy
dd.mm.yyyy
see also: DB_DaoFm

DB_DaoFm=<value>

This keyword specifies the date output format in SQL statements. Please refer to the ODBC Programmer's Guide - Appendix B for more information.

default value: yyyy-mm-dd
valid range: same as valid range of DB_DaiFm
see also: DB_DaiFm

DB_DbDir=<string>

This keyword specifies the directory that the database files reside in. The directory string can be a relative or a full path name. Basically there are five types of files in DBMaker - the system database file defined by DB_DBFIL, the system journal file defined by DB_JNFIL, the system BLOB file defined by DB_BBFIL, the system temporary file defined by DB_TPFIL, and user defined files. When defining these keywords full path names, relative path names or simple file names can be used. If a path name is used in defining these keywords, DBMaker will use that name to reference the defined file. If a simple file name is used, DBMaker will search for the DB_DBDIR keyword. If this keyword is found, DBMaker will prefix the simple file name with the string specified in DB_DBDIR to reference the file. If it is not found, DBMaker will just use the file name and assume it is located in the current directory.

Example

[DB1]
DB_DbDir = /disk1/db
DB_DbFil = mydb1
DB_JnFil = /disk2/usr/DB1.JNL

The physical file names are:

DB_DbFil -- /disk1/db/mydb1
DB_JnFil -- /disk2/usr/DB1.JNL
DB_BbFil -- /disk1/db/DB1.BB (using default file name)

Example

[DB2]
DB_DbFil = mydb2
DB_JnFil = /disk2/usr/DB2.JNL

The physical file names are:

DB_DbFil -- mydb2 ( in current directory )
DB_JnFil -- /disk2/usr/DB2.JNL
DB_BbFil -- DB2.BB ( in current directory )

default value: (current directory)
valid range: string with length < 80
see also: DB_DbFil, DB_JnFil, DB_BbFil, DB_TpFil

DB_DbFil=<string>

This keyword specifies the physical name of the system database file used by the operating system.

default value: database name suffixed with .DB. For example, db.DB.
valid range: string with length < 80
see also: DB_DbfSz, DB_DbDir

DB_DbfSz=<value>

This keyword specifies the size of the database system file in number of pages. Each page is 4KB large. Note that this file will be enlarged automatically by DBMaker if needed. This value is used when the database is created.

default value: 100 (so that the default size is 400KB)
valid range: 25 ~ 524287
see also: DB_DbFil

DB_DtClt=<value>

This keyword specifies the time interval DBMaker uses to automatically detect the existence of a client. Setting this keyword to 0 disables this feature. Sometimes when a client machine is suddenly powered off or the network is not working properly, the server can't release the resource allocated to that client. Turning this keyword on will solve this problem because the server will auto-detect the client. If the server finds a client is dead, it will release all of that client's resource.

default value: 300 (seconds)
valid range: 5 ~

DB_FoDir=<value>

This keyword specifies the path user file objects are placed in. You must specify a full path name for DB_FODIR. For example:

DB_FoDir = /usr/DBMaker/fileobj            ;for UNIX

DB_FoDir = c:\dbmaker\fileobj              ;for DOS

You can insert a user file object only when you have set DB_FODIR. This keyword is used when a database is started.

default value: null string (the user file object cannot be inserted)
valid range: string with length < 80
see also: DB_UsrFo

DB_ForcS=<value>

This keyword specifies that DBMaker should force a database to start even if an error occurs while starting the database. Setting this value to 1 enables forced startup.

default value: 0
valid range: 0,1
see also: DB_SMode

DB_JnFil=<string>

This keyword specifies the names of the system journal files in a database. It also denotes how many journal files you allocated for this database. You can specify at most eight journal files.

default value: database name suffixed with .JNL. For example, DB.JNL.
valid range: strings with length < 80
see also: DB_JnlSz, DB_DbDir

DB_JnlSz=<value>

This keyword specifies the journal file size of a database in number of pages (4 KB per page).

default value: 250 (default journal size is 1 MB)
valid range: 100~524287 and greater than DB_NJnlB by at least three
see also: DB_JnlSz, DB_DbDir

DB_LCode=<value>

This keyword specifies the language code. The language code will affect the result of LIKE operations in a query. A 0 indicates the language is ASCII compatible. A 1 indicates the language code is Chinese BIG5 code compatible. Please refer to the SQL Reference Manual for more information. This value is required when the database is started.

default value: 0
valid range: 0, 1

DB_LetPT=<value>

This keyword specifies the Lock Escalation Threshold for escalating a page lock to a table lock. When the number of locks on pages in the same table exceeds the lock escalation threshold, DBMaker will automatically escalate the lock to a table lock.

default value: 50
valid range: 3-32767
see also: DB_LetRP

DB_LetRP=<value>

This keyword specifies the Lock Escalation Threshold for escalating a row lock to a page lock. When the number of locks on rows in the same table exceeds the lock escalation threshold, DBMaker will automatically escalate the lock to a page lock.

default value: 15
valid range: 3-32767
see also: DB_LetPT

DB_LTimO=<value>

This keyword is an integer that specifies the lock time-out value in seconds. When you need to acquire a lock on a database object, such as a table or a tuple, and that object has been already been allocated to another transaction, you must wait until the object is released. However, if you prefer not to wait too long, you can set this keyword to a desirable value. DBMaker will wait for the object until the waiting time expires, which will return a "lock time-out" error message, or until a lock is acquired on the object before the lock time-out. To disable the time-out, set this keyword to -1. This will cause DBMaker to continue waiting until the lock is released. You can also set the keyword to 0, indicating that you don't want to wait at all. This keyword is used at connection time rather than database startup time. Each connection may have its own dmconfig.ini, especially in client/server mode, so each user can have his own lock time-out value.

default value: 5
valid range: -1~ 65535

DB_NBufs=<value>

This keyword specifies the number of data buffers. Each buffer in DBMaker is 4 KB large. Generally speaking, DBMaker will run more efficiently with more buffers. This keyword is used when the database is started.

default value: 250
valid range: 15~depends on system
see also: DB_NJnlB, DB_ScaSz

DB_NJnlB=<value>

This keyword specifies the number of journal buffers (4 KB per buffer) in shared memory. (Note that this is not the size of the journal file, but the number of 4KB journal buffers which are stored in memory.) This keyword is used when the database is started.

default value: 64 ( 128 KB )
valid range: 16~depends on system
see also: DB_JnlSz, DB_NBufs, DB_MemSz

DB_NTran=<value>

This keyword indicates the maximum number of transactions that can be simultaneously active in the database system. It also indicates the maximum number of connections that can be simultaneously established to the database system since a connection can own at most only one transaction.

default value: 20
valid range: 2~240
see also: DB_UMode

DB_PasWd=<string>

This keyword specifies the password for the default login user ID. If no default login user ID is specified, this value is ignored. This keyword is used when the database starts or at connection time.

default value: null string
valid range: string with length <= 8
see also: DB_UsrId

DB_PtNum=<value>

This keyword is an integer which specifies the TCP/IP port number which the database server is attached to. This is used at connection time on the client side and at startup time on the server side. This number must exactly match on all client and server machines for a database, or the connection will fail.

default value: 23000
valid range: 1024~65535
see also: DB_SvAdr

DB_RTime=<string>

This keyword specifies the target time that a backed up database will be restored to. When doing a database restoration, DBMaker will roll forward on the backed up files from the earliest time in the backup files to the time specified by DB_RTIME. If DB_RTIME is not given, DBMaker will restore the database to the latest time in the backup files, which is the time the backup was performed.

If the DB_RTIME is later than the backup time, the backup time will be used as the value for DB_RTIME.

The format for DB_RTIME is yy/mm/dd hh:mm:ss.

default value: 0 ( 70/1/1 00:00:00 )

DB_ScaSz=<value>

This keyword specifies the size of the System Control Area (SCA) in kilobytes. If the minimum memory required by DBMaker for the SCA is larger than the value of DB_SCASZ, DBMaker will ignore this value and allocate the minimum memory required for the SCA. This keyword is used when the database is started.

default value: 100 (KB)
valid range: 1~2,147,483,648
see also: DB_NBufS, DB_NJnlB

DB_SeCur=<value>

This keyword indicates whether the database has security control or not. A 1 indicates the database has security control and a 0 indicates the database has no security control. This keyword is used when the database is created. Once a database is created, there is no way to change the security control unless you recreate the database.

default value: 1
valid range: 0, 1

DB_SMode=<value>

This keyword indicates the database start-up mode. A value of 1 is used for "normal startup", 2 for "startup with new journal" and 3 for "startup with rollover".

normal startup - Starts up a system normally. If the database crashed last time, DBMaker will perform crash recovery automatically to bring the database to a consistent and stable state.

startup with new journal - Starts up a system normally, but creates a new journal file whose name is given by the value for the DB_JNFIL keyword. If a file with the same name already exists, it will be overwritten.

startup with rollover - Uses the backed up database files ( including the journal file) to start the database. DBMaker will roll over the operations up to the point in time specified by DB_RTIME. This mode is used for database restoration.

See the chapter Advanced Database Administration for more detailed information.

default value: 1
valid range: 1 (normal startup)
2 (startup with new journal)
3 (startup with rollover)
see also: DB_Forcs

DB_SvAdr=<string>

This keyword can be a string that specifies the TCP/IP address of the server machine or the host name of that machine. If DNS (Domain Name Service) has been set up properly on the client machine, you can even specify the domain name in this keyword. This keyword is required at connection time on all client machines. If this address is not correct, the connection will fail. Please see to your network administrator or any manual about TCP/IP networking for further information.

default value: none
valid range: a.b.c.d or host (domain) name (1<=a,b,c,d <=254)
see also: DB_PtNum

DB_TmiFm=<string>

This keyword specifies the time input format for SQL statements. Please refer to the ODBC Programmer's Guide, Appendix B for more information.

default value: none (accept all input time formats)
valid range:
hh:mm:ss.fff
hh:mm:ss
hh:mm
hh
hh:mm:ss.fff tt
hh:mm tt
hh tt
tt hh:mm:ss.fff
tt hh:mm:ss
tt hh:mm
tt hh
see also: DB_TmoFm

DB_TmoFm=<string>

This keyword specifies the time output format of SQL statements. Please refer to the ODBC Programmer's Guide for more information.

default value: hh:mm:ss
valid range: same as valid range of DB_TmiFm
see also: DB_TmiFm

DB_TpFil=<string>

This keyword specifies the name of the system temporary file.

default value: database name suffixed with .TMP.
valid range: string with length < 80
see also: DB_DbFil, DB_BbFil

DB_Turbo=<value>

This keyword indicates that DBMaker will run with normal catalog cache operation. If your applications rarely modify the structure of a database, you can use DB_TURBO mode to speed up data access. See Performance Tuning for more information. This keyword is used when the database is started.

default value: 0
valid range: 0, 1

DB_UMode=<value>

This keyword indicates the user mode. A value of 1 indicates multi-user mode and a value of 0 indicates single-user mode. This keyword has no effect on DBMaker single-user programs such as dmsqls, because such programs can only start a database in single-user mode. For multi-user programs you can set this keyword to start a database in single-user or multi-user modes. This value is required when starting a database.

default value: 1
valid range: 1 (multi-user mode)
0 (single-user mode)
see also: DB_SMode, DB_NTran

DB_UsrFo=<string>

This keyword indicates whether user file objects can be inserted into a database. Setting this value to 1 enables the user file object function. Please refer to the chapter Large Object Management for more information. This value is required when starting a database.

default value: 0
valid range: 0, 1
see also: DB_FoDir

DB_UsrId=<string>

This keyword specifies the default user ID that will be used to log in at database startup or connection time.

default value: null string
valid range: string with length < 8
see also: DB_PasWd

User-defined filename=<physical filename>, <pages>

DBMaker allows users to create data files or BLOB files and add them to a tablespace when the original tablespace is filled. Basically users specify a logical file name (without full path name) when creating a file. However, users can map this logical file name to a physical file name which is used by the operating system to access the file.

For example, in dmconfig.ini:

FILE1 = /disk1/usr/datafile 100

Although you specify FILE1 in DBMaker, DBMaker will create a file /disk1/usr/datafile with 100 pages (4KB per page). If this file has to be moved to another directory, just change the physical file name in dmconfig.ini. There should be no need for modification to your programs or SQL scripts. Note that the rule for DB_DBDIR also applies to user-defined files.

valid range: file name - string with length < 80
size - 2 ~ 524287
see also: DB_DbDir