Contents IndexSoftware component return codes The Backup utility

User's Guide
   Part VI. SQL Anywhere Reference
     Chapter 39. SQL Anywhere Components
      The database engine

Syntax

     dbeng50 [engine-switches][database-file [database-switches], ...]

     rtdsk50 [engine-switches][database-file [database-switches], ...]

Windows 3.xsyntax

     dbeng50w [engine-switches][database-file [database-switches], ...]

     rtdsk50w [engine-switches][database-file [database-switches], ...]

     dbeng50s [engine-switches][database-file [database-switches], ...]

     rtdsk50s [engine-switches][database-file [database-switches], ...]

Switch Description
@filename Read in switches from configuration file
@envvar Read in switches from environment variable
-b Run in bulk operations mode
-ccache-size Set maximum cache size
-d Disable asynchronous I/O (OS/2, Windows NT, NetWare only)
-df Force direct I/O (Windows 3.1, DOS only)
-di Use direct I/O if possible (Windows 3.1, DOS only)
-ga Automatically shut down after last database closed
-gblevel Set database process priority class to level
-gcnum Set checkpoint timeout period
-gdlevel Set database starting permission
-gesize Sets the stack size for threads that run external functions
-gf Disable firing of triggers
-gklevel Set permission for stopping the engine using DBSTOP
-gnnum Set number of threads
-gpsize Set maximum page size
-grnum Set maximum recovery time
-gssize Set thread stack size
-gwnum Set the interval (in milliseconds) for background processing
-gx Disable dual threading
-m Truncate transaction log after checkpoint
-nname Use nameas the name of the database engine
-og Load the Open Server Gateway (OSG) with default settings
-ogcversion Load the OSG with release 5.5.01 data type mapping compatibility
-ogddatabase-name Load the OSG, making database-name the name of the database used for OSG connections
-ogolog_file Load the OSG, outputting messages to log_file
-ogp Load the OSG, run in non-preemptive mode
-ogsservername Load the OSG using servername for the name of the OSG
-ogt Load the OSG and truncate the log file
-ogv Load the OSG, operate in verbose operation (extended messages)
-ogw Load the OSG, react to Warnings as Errors
-q Quiet mode---suppress output
-tasec Scan time for terminated applications:---default 30 seconds
-u Use buffered disk I/O (Windows 95 and Windows NT only)
-v Log old values of all columns on UPDATE or DELETE for all databases
-y Run as a Windows 95 service

Recovery switches

Switch Description
-alog-file Apply named transaction log file
-f Force database to start without transaction log

Database switches

Switch Description
-m Truncate transaction log after checkpoint
-nname Name the database
-v Log old values of all columns on UPDATE or DELETE

Description

There are several versions of the SQL Anywhere database engine, and each version has a different executable name. The database engine for platforms other than Windows 3.x is named DBENG50.EXE, the 32-bit and 16-bit Windows 3.x executables being DBENG50W.EXE and DBENG50S.EXE respectively. The runtime database engine is named RTDSK50.EXE, with the 32-bit and 16-bit Windows 3.x executables being named RTDSK50W.EXE and RTDSK50S.EXE respectively.

The SQL Anywhere standalone database engine is completely compatible with the SQL Anywhere network server (DBSRV50.EXE). Client applications developed on one run against the other without alteration. For information about the network server and its command-line switches, see the SQL Anywhere Network Guide .

The 32-bit versions of the Windows 3.x database engine have much better performance than the 16-bit versions. They require Windows 3.x running in enhanced mode.

The database engine can be started with a number of database files or no database files. Command-line switches specified before any databases apply to the engine and all databases. Switches specified after a particular database file apply only to that database.

Client applications can load additional databases dynamically after the database engine has started. However, only databases of the same or smaller page size can be loaded dynamically.

If a database-file is specified without a file extension, SQL Anywhere first looks for database-file with extension WRT (a write file), followed by database-file with extension DB.

The database engines are programs that run as a separate task.

In DOS, the database engines are DOS terminate and stay resident programs (TSRs), meaning that they will load into the memory of your computer and then return control to DOS.

Runtime database engines are available with the SQL Anywhere Desktop Runtime System for DOS, Windows 3.x, OS/2 and Windows 95 or NT.

The runtime engine does not allow ALTER, CREATE, COMMENT or DROP commands. GRANT and REVOKE will allow you to add new users and change passwords but changing permissions on tables is not allowed. Also, the runtime database engine does not employ a transaction log (although it is a fully transaction-processing database engine) and does not support stored procedures and triggers.

Supplying command-line switches in a configuration file
A set of command line switches can be stored in a configuration file or in an environment variable. The database engine can be instructed to use these switches using the @ command-line switch.

Engine switches

@filename Read in command-line switches from the supplied file.

The file may contain line breaks, and may contain any set of command line switches. For example, the following command file holds a set of command line switches for an engine that starts with a cache size of 4 Mb, a name of myserver, and loads the sample database:

     -c 4096
     -n myserver
     c:\sqlany50\sademo.db

If this configuration file is saved as C:\CONFIG.TXT, it can be used in an command line as follows:

     DBENG50 @c:\config.txt

@environment-variable Read in command-line switches from the supplied environment variable. The environment variable may contain any set of command line switches. For example, the first of the following pair of statements sets an environment variable holding a set of command line switches for a database server that starts with a cache size of 4 Mb and loads the sample database. The second statement starts the database server:

     set envvar=-c 4096 c:\sqlany50\sademo.db
     DBENG50 @envvar

-b Use bulk operation mode. This is useful when loading large quantities of data into a database.

In bulk operations mode, the database server allows only one connection by one application. It does not keep a rollback log or a transaction log, and the multiuser locking mechanism is turned off. You should use a new log file when starting the database engine or server after loading data with the -b switch.

Bulk operation mode does not disable the firing of triggers.

  For more information on loading and unloading data, see "Tuning bulk operations".

-c cache-size Set the size of the cache. The database server uses extra memory for caching database pages if it is set aside in the cache. Any cache size less than 10000 is assumed to be K-bytes (1K = 1024 bytes). Any cache size 10000 or greater is assumed to be in bytes. The cache size may also be specified as nK or nM (1M = 1024K). By default, the database server usess 2 megabytes of memory for caching. The more cache that can be given the engine, the better will be its performance.

-d disable asynchronous I/O This option applies to Windows NT, OS/2 and NetWare systems only. Use synchronous rather than asynchronous I/O. Asynchronous I/O is the default for these systems and should offer performance improvements.

-df force direct I/O This option applies to DOS and Windows 3.x systems only. Use direct I/O rather than DOS I/O. DOS I/O is the default. See the -di option for a description of direct I/O.

-di use direct I/O if possible This option applies for DOS and Windows 3.x only. Analyse the disk hardware and software and use direct I/O if possible. The default is to use DOS I/O.

As databases increase in size and get more fragmented, direct I/O can provide a significant increase in performance. However, direct I/O does not work with all disks. Using the -di option causes the engine or server to attempt to determine whether direct I/O will work with the current configuration. If direct I/O cannot be used, a message will be displayed on startup.

Windows 95 I/O
Asynchronous I/O is not supported in Windows 95 environments.

-ga Applications can cause databases to be started and stopped by the engine. Specifying this switch causes the engine to shutdown when the last database is stopped.

-gb level OS/2 and Windows NT only. Sets the database process priority class to level. Level must be one of idle, normal(the default), high, or maximum. idle is provided for completeness, and maximummay interfere with the running of your computer. lowand highare the commonly used settings.

-gc num Sets the maximum desired length of time (in minutes) that the database server will run without doing a checkpoint.

When a database server is running with multiple databases, the checkpoint time specified by the first database started will be used unless overridden by this switch.

For more information about checkpoints, see the CHECKPOINT_TIME option in "SET OPTION statement".

-gd level Set the database starting permission to level. This is the permission level required by a user to cause a new database file to be loaded by the server. The level can be one of the following:

-ge size Sets the stack size for threads running external functions, in bytes. The default is 16384 (16K). This switch is used only for OS/2, Windows NT, and NetWare.

-gf Disables firing of triggers by the server.

-gk level Sets the permission required to stop the database engine using DBSTOP to level. The level can be one of the following:

-gn num Sets the number of execution threads that will be used in the database server while running with multiple users.

For more information, see the THREAD_COUNT option in "SET OPTION statement".

When a database server is running with multiple databases, the thread count specified by the first database started will be used unless overridden by this switch.

-gp size Sets the maximum page size allowed, in bytes. The size specified must be one of: 512, 1024, 2048, or 4096. When a database server is running with multiple databases, the page size specified by the first database will be used unless overridden by this switch. Without using this option, an attempt to load a database file with a page size larger than the page size of the database first loaded will fail.

-gr num Sets the maximum desired length of time (in minutes) that the database server will take to recover from system failure.

For more information, see the RECOVERY_TIME option in "SET OPTION statement".

When a database server is running with multiple databases, the recovery time specified by the first database started will be used unless overridden by this switch.

-gs size Sets the stack size of every thread in the server. The value entered is multiplied by four to produce the stack size in bytes.

-gw num Sets the interval for background processing. At each interval, the engine carries out one I/O operation. The default setting is 500 (half a second).

-gx Disables dual threading. This option is available for the Windows 95, Windows NT, OS/2, and NetWare versions.

-m Truncate (delete) the transaction log when a checkpoint is done, either at shutdown or as a result of a checkpoint scheduled by the database engine. This provides a way to automatically limit the growth of the transaction log. Checkpoint frequency is still controlled by the CHECKPOINT_TIME and RECOVERY_TIME options (also definable on the command line).

The -m option is useful where high volume transactions requiring fast response times are being processed, and the contents of the transaction log are not being relied upon for recovery or replication. When this option is selected, there is no protection provided against media failure on the device containing the database files.

To avoid database file fragmentation, it is recommended that where this option is used, the transaction log be placed on a separate device or partition from the database itself.

Replicated databases
Do not use the -m option with databases that are being replicated as replication inherently relies on transaction log information.

-n name Set the name of the database server. By default, the database server receives the name of the database file with the path and extension removed. For example, if the server is started on C:\SQLANY50\SADEMO.DB and no -n switch is specified, then the name of the server will be sademo.

The server name can be used on the connect statement to specify to which server you wish to connect. In all environments, there is always a default database server that will be used if no server name is specified provided at least one database server or SQL Anywhere Client (DBCLIENT) is running on the computer.

Open Server Gateway DLL switches
Database engine switches beginning with -og are designed to start the Open Server Gateway (OSG) simultaneously with the database engine by loading a Windows 95/NT DLL.Functionality offered by the OSG DLL is identical to that found in the OSG client application, an executable started separately from the database engine. There is corresponding engine switch for every OSG client application switch. For more information about the Open Server Gateway client application see "The Open Server Gateway".

-og Load the Open Server Gateway (OSG) with default settings.

-ogc version The equivalent of starting the OSG client application with the -c switch.

-ogd database_name The equivalent of starting the OSG client application with the -d database_name switch.

-ogo log_file The equivalent of starting the OSG client application with the -o log_file switch.

-ogp The equivalent of starting the OSG client application with the -p switch.

-ogs servername The equivalent of starting the OSG client application using servername as the open-server-name command-line argument

-ogt The equivalent of starting the OSG client application with the -t switch.

-ogv The equivalent of starting the OSG client application with the -v switch.

-ogw The equivalent of starting the OSG client application with the -w switch.

-q Operate quietly. Suppress all output.

-ta seconds For Windows 3.x, Windows NT, and Windows 95 only. The database engine periodically scans the connection list and disconnects any connections associated with terminated applications. The scan period can be controlled using the -ta switch, and has a default value of 30 seconds. Setting the value to zero prevents scanning.

-u Files are opened using the operating system disk cache in addition to the database cache. This option applies to the Windows 95 and Windows NT database servers only. While the operating system disk cache may improve performance in some cases, in general better performance is obtained without this switch, using the database cache only.

-v Cause the database engine to record in the appropriate transaction log the previous values of each of the columns whenever a table row is updated or deleted. By default, the engine will only record enough information to uniquely identify the row (primary key values or values from a not null unique index). This switch is useful for working on a copy of a database file.

This option does not apply to the runtime database engine, which does not support transaction logs, or database files that are not using a transaction log.

-y Runs database engine as a Windows 95 service. By registering the database engine as a Windows 95 service it continues to operate whether as users log on or off and shutdown commands are ignored.

  The database engine can also be run as an NT service. For more information, see the chapter "Running Programs as Services".

Recovery switches

-a log-file Apply the named transaction log. This is used to recover from media failure on the database file. When this option is specified, the database server will apply the log and then terminate---it will not continue to run.

This option does not apply to the runtime database engine, which does not support transaction logs, or database files that are not using a transaction log.

For more information on recovery from media failure, see the chapter "Backup and Data Recovery".

-f This option is used for recovery: either to force the database server to start after the transaction log has been lost, or to force the database server to start using a transaction log it would otherwise not find.

If there is no transaction log, the database server carries out a checkpoint recovery of the database and then terminates---it does not continue to run. You can then restart the database server without the -f option for normal operation.

If there is a transaction log in the current directory, the database server carries out a checkpoint recovery, and a recovery using the transaction log, and then terminates---it does not continue to run. You can then restart the database server without the -f option for normal operation.

This option does not apply to the runtime database engine, which does not support transaction logs.

For more information on recovery, see the chapter "Backup and Data Recovery".

Database switches

-m Truncate (delete) the transaction log when a checkpoint is done, either at shutdown or as a result of a checkpoint scheduled by the engine. This provides a way to automatically limit the growth of the transaction log. Checkpoint frequency is still controlled by the CHECKPOINT_TIME and RECOVERY_TIME options (also definable on the command line).

The -m option is useful where high volume transactions requiring fast response times are being processed, and the contents of the transaction log are not being relied upon for recovery or replication. When this option is selected, there is no protection provided against media failure on the device containing the database files.

To avoid database file fragmentation, it is recommended that where this option is used, the transaction log be placed on a separate device or partition from the database itself.

This switch is the same as the -m engine switch, but applies only to the database identified by the database-file command-line variable.

Replicated databases
Do not use the -m option with databases that are being replicated as replication inherently relies on transaction log information.

-n name Set the name of the database. Both database servers and databases can be named. Since a database server can load several databases, the database name is used to distinguish the different databases.

By default, the database receives the name of the file with the path and extension removed. For example, if the server is started on C:\SQLANY50\SADEMO.DB and no -n switch is specified, then the name of the database is sademo.

-v Causes the database engine to record in the transaction log the previous values of each of the columns whenever a row of the specified database is updated or deleted. By default, the engine will only record enough information to uniquely identify the row (primary key values or values from a not null unique index). This switch is useful for working on a copy of a database file.

This option does not apply to the runtime database engine, which does not support transaction logs, or database files that are not using a transaction log.

The backup, initialization, unload, and validation utilities automatically load the database engine if it has not been previously loaded. The SQL Anywhere Client (DBCLIENT) can also be started automatically in this way. See "Registry entries and environment variables" and the respective commands for more details. If the database engine (or client) is started automatically, it will be unloaded automatically when the software is finished executing.

Contents IndexSoftware component return codes The Backup utility