The information in this chapter is is optional for new users, because defaults are provided for all values and, in any case, the VERSANT Utilities Tool provides an easier to understand graphical environment to manage these parameters.
Operating parameters are contained in two types of files: the application process profile and the server process profile.
For the location of your profiles files, see the chapter "Directories and Files."
See also the "VERSANT Utilities Tool" chapter.
Overview
When you use the makedb or makeprofile utilities, if an application profile file does not already exist, VERSANT will create an application process profile with the same name as the database you are creating. When you start a database session and specify a database to be used as the session database, VERSANT reads the application profile for that database and uses the parameters it finds to set the operating environment for the application.
At any time, you can edit the contents of an application profile to change the operating environment for your application process. The parameters are read each time a session starts.The existence of an application process profile file is optional: if one does not exist, default values will be used.
Windows NT
osc under your home directory. This directory will contain application process profiles for the databases that you create. For example, for a database named dbname, the application process profile is:
%HOMEDRIVE%%HOMEPATH$\osc\dbname
.osc under your home directory. This directory will contain application process profile files for the databases that you create. For example, for a database named dbname, the application process profile is:
$HOME/.osc/dbname
K and megabytes with M.
To create a comment line in the profile file, you must use the pound sign # as the first character of the line.
The application process profile can understand and use the following parameters.
Functional parameters
|
|
Aliases for local and remote databases. |
|
|
Automatic connections to group databases each time a session starts. |
|
|
Turn on or off the use of the generic version object. |
|
|
Allow inconsistent class definitions. |
|
|
The maximum number of processes within the system. |
|
|
Block unwanted signals, such as Ctrl-C, that might otherwise damage shared memory. If you run your application with a single process, you may need to turn this parameter on. |
|
|
Set the maximum number of database connections that can be made in a database session. |
|
|
Set the estimated number objects that will be accessed in a session. |
|
|
A pre-allocation hint for the size of the application heap, which includes cached objects, the cached object descriptor table, and other data structures. |
|
|
Sets heap allocation granularity. |
|
|
Sets the spacing of class size states. |
|
|
Expansion increment of application heap. |
|
|
Set initial cod table size. |
|
|
Swap threshold. If less than this amount of the application heap is used, object swapping will not be attempted by the system. |
database_name refers to the application process file belonging to a database of the same name.
alias alias_name database_name[@node]
Set the alias alias_name for the database database_name.
For a remote database, append the node name to the database name using the syntax database@node.
Aliases are kept throughout a session. Each alias must be entered on a separate line. Setting aliases is optional.
Aliases have two purposes: convenience and performance tuning.
Convenience — The primary purpose of aliases is to simplify application syntax and to allow later changes of alias references without having to change applications that use the aliases.
When an application uses a remote database, you must specify the remote database name in a way that indicates that the database is on another machine. You do this with database_name@location syntax. This syntax can either be used in each reference made to the remote database in an application or by creating an alias in the Application Process parameter file for the database you are using as your session workspace.
For example, if your application uses two group databases named groupdb_1 and groupdb_2 located on machines machine_1 and machine_2, you can add the following lines to the file $HOME/.osc/personaldb:
alias gdb1 groupdb_1@machine_1
alias gdb2 groupdb_2@machine_2
After setting these aliases, you can then refer to the group databases in your application with the names gdb1 and gdb2. If you later change the location of either database or decide to use different group databases in your application, you only have to change the aliases rather than editing your program.
Performance tuning — Aliases allow the use of different database parameters for one database depending upon the application using it. For example, for one application you might want a large heap size, while for another one you might want a small heap size.
To use of several sets of database parameters for one database, first create several sets of profiles with differing names. For example, you might create profiles named "profile_one" and "profile_two".
To specify which application process file to use for a particular application, use database aliases. In each of the profiles you create, specify an alias for the database that you want to use as your session workspace.
Suppose, you have a database whose real name is db and you have two application process parameter files: $HOME/.osc/db1 and $HOME/.osc/db2. The db1 file should have the alias entry "alias db1 db", and the db2 file should have the entry "alias db2 db". Then, in your program, if you specify "beginsession(db1,..)," the database db will be started using the entries in the application profile file db1. If you specify "beginsession(db2,..)," the values in the file db2 will be used.
If there is no application process parameter file with the name specified in a "begin session" method, then a session is started in the database of the same name using default values of the parameters.
connect group_db access_mode
Automatically connect to the group database group_db when you begin a session.
Access modes are specified as:
READ_ONLY
READ_WRITE
WRITE_ONLY
connect entries to connect automatically with multiple group databases. Specify remote databases with db@node syntax.
Connections to databases made using the connect parameter can be disconnected by calling a "disconnect database" routine from within a session. Otherwise, the connections will be terminated when you end the session.
For example, if you wish to connect to a group database named groupdb1 on machine1 and groupdb2 on machine2 every time you begin a session, add the following statements to your application process parameter file:
connect group1@machine1 READ_WRITE
connect group2@machine2 READ_WRITE
genericObject on|offTurn use of the generic object off and on.
The default is off. If you are using versioning, you may want to turn this parameter on.
The default version is recorded in a "generic instance" associated with the versioned object. There is only one generic object instance for a versioned object. At runtime you can use the generic instance to find the version that has most recently been specified as the default version. See the chapter "Versioning" in the Database Fundamentals Manual for more information.
loose_schema_mapping state
Turn loose schema mapping on or off. The default state is off.
Normally, when an application accesses a class in a database, VERSANT compares the database definition of the class with the definition expected by the application. If the database and application definitions of the class differ, an exception is raised. If you turn loose schema mapping off, an application compiled with an old class definition can continue to use a database even if class definitions differ.
If loose_schema_mapping is on, the following behavior occurs.
Create object — OK.
Read object — OK.
Write object — OK.
If attribute exists in database only...
Create object — Attribute is set to zero when object is written to database.
Read object — Attribute is not seen.
Write object — Attribute is not modified when object is written to database.
If attribute exists in application only...
Create object — Attribute is not written to database.
Read object — Attribute is set to zero.
Write object — Attribute is not written to database.
If attribute type has been changed...
Create object — Exception is raised: "types do not match."
Read object — Exception is raised: "types do not match."
Write object — Exception is raised: "types do not match."
loose_schema_mapping is off, the following behavior occurs.
Create object — OK.
Read object — OK.
Write object — OK.
If attribute exists in database only...
Create object — Exception is raised: "signature mismatch" or "wrong layout."
Read object — Exception is raised: "signature mismatch" or "wrong layout."
Write object — Exception is raised: "signature mismatch" or "wrong layout."
If attribute exists in application only...
Create object — Exception is raised: "signature mismatch" or "wrong layout."
Read object — Exception is raised: "signature mismatch" or "wrong layout."
Write object — Exception is raised: "signature mismatch" or "wrong layout."
If attribute type has been changed...
Create object — Exception is raised: "types do not match."
Read object — Exception is raised: "types do not match."
Write object — Exception is raised: "types do not match."
max_processes number
The maximum number of processes allowed within a session. The default is 16.
This parameter applies only to shared sessions started with the O_SHARE option.
signal_block ON | OFF
Block unwanted signals. The default is OFF.
When signal_block is on, the following signals are blocked:
SIGHUP SIGINT SIGQUIT SIGPIPE SIGALRM SIGTERM SIGURG
SIGSTOP SIGTSTP SIGCONT SIGCHLD SIGIO SIGWINCH SIGLOST
SIGUSR1 SIGUSR2
ON if you run your application with a single process. In single process mode, an application makes calls directly to its session database, so if a user hits Control-C, for example, during a critical moment, the database could become inconsistent.
estimated_connections numberSet the maximum number of database connections that can be made in a database session.
In the current release, despite the usage of "estimated" in its name, the estimated_connections parameter sets a hard limit on the number of concurrent connections that can be made.
The default value of this parameter is 4.
This parameter is useful in reducing memory requirements.
estimated_objects numberExplicitly specify the estimated number of objects that you will access in a database session.
The default value is 32K objects. You may want to set this number higher if you will access more than 32K objects in a session.
This parameter affects the size of system information tables, such as the cached object descriptor table, that are created when you start a database session. If your application creates and uses multiple, concurrent database sessions and, in each session, accesses only a few objects, you can set this parameter low to reduce memory usage. On the other hand, if you are using a single session at a time and accessing a large number of objects in the session, you can set this parameter high to improve performance.
See also heap_size, heap_size_class and heap_size_class_spacing.
heap_size sizeA pre-allocation hint for the size in bytes of the application heap. The applications heap contains cached objects, the cached object descriptor table, and other data structures.
If your swap space is too small, you may run out of swap space while your application is running. If you know that a session will require a lot of memory, you can pre-allocate space for the application process heap by setting the initial heap size. If more memory than the initial amount specified by this parameter is needed, the heap size is dynamically increased as needed.
If your application requires more heap space than is available, an error will indicate that you have run out of swap space.
Normally you do not have to set this parameter since the application process heap is expanded dynamically as needed, and VERSANT can determine an appropriate initial value.
See also the server process heap_size parameter.
heap_size_increment sizeSet the size by which the application process heap will be expanded as needed.
The default increment is 1 megabyte.
See the description for the application process heap_size parameter for more information.
heap_size_class number state
Allows the state of an individual size class state, expressed as a number from 0 to 31, to be set to a state, either on or off. By default, all size classes are on.
This is an advanced tuning parameter that affects how space in the application heap is used. This parameter is relevant when you are accessing only a few objects of a specific size, which might be the case when, say, you are using a large number of concurrent sessions.
In any case, this parameter is only useful if you have collected performance statistics. For example, if you look at the statistics se_heap_small_population_n, for n = 0 to 31, and find that there are only a few allocations to a particular size class, then you might want to try turning that class size off.
This parameter allows even finer control over space usage than offerred by the heap_size_class_spacing parameter.
Background
To efficiently allocate space for object under 8K in size, VERSANT internally categorizes objects into 32 different sizes. By default, the first time an object smaller than the size of a heap page is accessed, its size is categorized into one of the 32 possible sizes, a page of the default or specified heap size is allocated for the object, and that page is reserved for other objects that fall into the same size category. Then, when any further objects of that size category are brought into memory, they are placed on the same page until that page is full.
The default strategy makes very efficient use of memory if you are accessing a large number of objects, because it packs objects closely in memory. However, if you are accessing only a few objects and the few objects involved vary slightly in size, the default strategy could create a large number of 8K pages that are not fully populated.
The heap_size_class parameter allows extremely fine grain control of the heap storage strategy by allowing to turn off specific categories of sizes. If you turn off a size, the the next larger one will be used instead. This has the effect of placing objects of slightly varying sizes onto the same page heap.
Another way of controlling the heap storage strategy is to use the heap_size_class_spacing parameter. In the spacing parameter, you can enable all class sizes by specifying 0, enable every other class size by specifying 1, enable every third class size by specifying 2, and so on.
For example, suppose that you want to configure a simple session that creates only a single small object so that it has minimal memory costs. Also, suppose that you know that for your application, an efficient heap page size is 64K. (To find an efficient heap size, look at the se_heap_user statistic after all other parameters have been tuned.) To set the heap size to exactly the size required, make the following entry:
heap_size 64K
Then, after much watching of statistics, you might want to make the following entries:
heap_size_class_spacing 31
heap_size_class 0 off
heap_size_class 8 on
heap_size_class 11 on
heap_size_class 20 on
heap_size_class 23 on
The "best" values for the heap_size_class and heap_size_class_spacing parameters are extremely application specific. If you want to explicitly set these parameters, you might want to repeatedly run your application and examine various heap statistics, such as se_heap_used, se_heap_free, se_heap_small_allocates_n, se_heap_small_frees_n, and se_heap_small_population_n.
See also heap_size and heap_size_class_spacing.
heap_size_class_spacing number
Specify the spacing between enabled class size categories. The default of 0 enables every size class, 1 enables every other size class, 2 enables every third size class, etc.
See the heap_size_class parameter for an explanation of what this parameter does.
The heap_size_class_spacing parameter is a quick and easy, one number alternative to the heap_size_class parameter. You can use it to manage heap memory tradeoffs in the case of either a small number of allocations or a large number of allocations. The default value of zero optimizes the case of a large number of allocations. Increasing the number parameter reduces memory usage for a small number of allocations, but increases it for a large number of allocations.
max_objects sizeSpecify a minimum initial size in bytes for the cached object descriptor table. This initial size also becomes the increment by which the size of the cached object descriptor table increases as needed.
The default value is 32K.
The cached object descriptor table is dynamically allocated and will increase in size as needed.
This parameter is relevant if you are accessing only a few objects in a session, which might be the case when, say, you are using a large number of concurrent sessions. If you are going to access only a few objects, then you might want to decrease this value in order to reduce memory costs. If you are going to access a large number of objects, you might want to increase this value in order to improve performance.
See also heap_size, heap_size_class, and heap_size_class_spacing.
swap_threshold sizeSpecify the point at which object swapping begins.
Object swapping is the process in which objects residing in an application object cache are returned to their databases. When the object cache tries to grow beyond the swap threshold size, object swapping will occur.
The default swap size is 512 megabytes. The swap threshold is a hard limit on the size of the cache, so swapping will begin as soon as the size of the cache exceeds the value of the swap threshold parameter.
An object chosen for swapping will be written to its database if it has been marked as dirty or discarded if it is clean. When objects which have been swapped out are accessed, they must be retrieved from the server.
Object swapping is not as good as keeping the objects cached in physical memory, but it is far better than virtual memory thrashing.
The optimal value of this parameter depends on your application and environment. If objects are always referenced in the same order, then objects which are used together are stored in contiguous memory addresesses, and virtual memory will perform well. In this case, swap_threshold should be set much higher than physical memory, so that virtual memory is used instead of object swapping.
If, on the other hand, objects are accessed in an unpredictable order, object swapping is preferred and the parameter should be set low enough to prevent thrashing.
In any event, you should set the swap threshold high enough so that as much of physical memory as possible is used.
The following error messages may indicate that you are running out of swap space:
0054
|
VSL_MEM_NOMEM
|
Out of process memory. |
1100
|
SM_E_NOMEM
|
Out of back-end heap memory. |
3002
|
NET_ENOMEM
|
Unable to allocate memory. |
4161
|
OM_HEAP_NOMEM
|
Out of front-end heap memory. |
|
|
|
No heap memory in schema management. |
Scenario 1 — An object is modified only once during the course of a transaction and the swap_threshold value causes it to be swapped out at some point. In this case, there is no relative impact on the logical log, because a record would be written to the logical log anyway when the transaction committed.
Scenario 2 — An object is modified several times during the course of a transaction, but is swapped only once at the end of all these modifications. In this case, there is still only one group-write operation, and one set of logical log records for the object.
Scenario 3 — This is the worst case. The object is modified several times during a transaction and also swapped several times because of the swap threshold kicking in. In this case, there is "thrashing" of the object cache. Now there would be several logical log records for the same object, with a new set of logical log records being generated each time a swap occurred. If the object is a "hot" object which needs to be referenced and updated frequently, it could cause the logical log file to grow dramatically and exceed its limits.
Scenario 3 shows that if your cache is too small as defined by the swap_threshold parameter, you may see unexpected growth in your logical log file. The fix is to either increase the size of your object cache by increasing the swap threshold value or else to increase the space available for your logical log file to grow.
As a rule of thumb, we recommended that if you have a large database application, you should allocate at least 96 megabytes of swap space.
makedb or makeprofile utilities, if a server process profile file does not already exist, VERSANT will create one for the specified database.When a database starts up, the database server process reads the server process profile for that database to determine the location of the database volumes and to set the database operating environment. If a server profile does not exist for a database, you cannot start that database.
profile.be.Windows NT
mydb and a database root directory of c:\versant\db, the location of the server profile will be:
c:\versant\db\mydb\profile.be
mydb and a database root directory of /usr/local/versant/db, the location of the server profile will be:
/usr/local/versant/db/mydb/profile.be
k or K and megabytes with m or M.
To create a comment line in the profile file, you must use the pound sign # as the first character of the line.
createdb. If you change these parameters after you create the database, the system just ignores your changes.
sysvol
|
The maximum size of the system volume. |
plogvol
|
The size of the physical log volume. |
llogvol
|
The size of the logical log volume. |
|
|
The number of pages per extent on the system volume. |
async_buffer_cleaner
|
How cache flushing is performed. |
async_logger
|
How log flushing is performed. |
commit_flush
|
Whether buffer is flushed after a commit. |
datavol
|
Location of storage volumes. |
event_daemon
|
The event message daemon |
event_message_mode
|
The event message mode |
event_msg_transient_queue_size
|
The transient event message queue size. |
event_registration_mode
|
Event registration mode. |
locking
|
Turn short locking on or off. |
logging
|
Turn logging on or off. |
|
|
Turn error logging on for a database. |
class is crucial to databases containing a large number of classes: if more than the default number of 480 classes will be accessed during the time a database is running, you will need to specify a new value for class.
bf_dirty_high_water_mark
|
When the cleaner thread starts flushing dirty pages. |
bf_dirty_low_water_mark
|
When the cleanup thread stops flushing dirty pages. |
class
|
The number of cached user defined classes. |
db_timeout
|
Database timeout. |
heap_size
|
A hint for the initial size of server heap. |
index
|
The number of cached user defined indexes. |
llog_buf_size
|
Size of the logical logging buffer in bytes. |
lock_wait_timeout
|
Time to wait for a lock. |
max_page_buffs
|
The number cache buffers. |
multi_latch
|
Database latching behavior. |
plog_buf_size
|
Size of the physical logging buffer in bytes. |
polling_optimize
|
Strategy for FTS recovery. |
transaction
|
The maximum number of concurrent transactions. |
user
|
The number of cached user names. |
|
|
The number of cached data volumes. |
stat
|
Turn collection of connection and database statistics on or off. |
|
|
Type of assertions. |
trace_components
|
Database components to be traced. |
trace_entries
|
Number of trace entries to be maintained in the trace file. |
|
|
Name of the trace file. |
|
|
Set location of user authentication program. |
event_registration_mode
|
Persistent or transient registrations. |
|
|
Persistent or transient messages. |
extent_size number_of_pages
The extent_size parameter specifies the number of pages per extent on the system volume.
The default is 2 pages:
extent_size 2
An extent is the minimum unit of allocation to segments. The number of pages per extent tunes time versus space tradeoffs.
In general, setting a low number of pages per extent causes less space to be wasted by fragmentation and decreases the initial size of an empty database. It also makes it more likely that, over time, objects will be broken up and placed in different physical locations on the disk, thus slowing down access to the data.
In general, setting a high number of pages per extent decreases the likelihood that objects will be broken up and placed in different physical locations on disk, but it also increases usage of disk space.
The default is appropriate for most applications and should be increased only if your objects are very large.
See also the sysvol parameter.
llogvol size nameThe size and location of the logical log volume used for transaction undo-redo information for logging and recovery.
Arguments are:
size
The default size is 2 megabytes. The minimum size is 256K. If you specify a value smaller than the minimum, 256K will be allocated.
If the logical log volume is a file, it will be expanded if necessary. If the logical log volume is expanded beyond the stated soft limit out of necessity, it will be shrunk back after recovery has been done.
If the logical log volume is a raw device, it will not expand. When it is out of space, you will get the message 2503 SM_LOG_CANNOT_EXTEND.
name
The default is to use the name logical.log and then search for path specifications. See the "Run Time Environment" section following in this chapter.
If you specify an absolute path, you will not be able to move the database once it has been created.
The volume path can be either a file path or a raw device path. For raw devices, you must specify an absolute path.
When a short transaction commits, a commit log record is written to the logical log file and the state of the transaction is guaranteed. In case of a system crash, the committed transaction is reconstructed by re-executing all of its actions from the log.
If logging is on, the logical log file should be at least the sum of the sizes of all objects involved in a transaction. The larger the log file, the less frequently the system needs to pack the file when it is full. The logical log file should usually be larger than the physical log file.
For raw devices, if logging is on, a guideline for setting the minimum size of llogvol is:
guideline = 32K + (2 * (max_o + 100)) * num_o_per_tr * num_tr
In the above formula, substitute for max_o the size in bytes of the largest object in the database; substitute for num_o_per_tr the largest number of objects that will be involved in a transaction; substitute for num_tr the maximum number of concurrent transactions.
plogvol size nameThe size and location of the physical log volume used for physical data information related to logging and recovery.
Arguments are:
size
The default is 2 megabytes. The minimum size is 256K. If you specify a value smaller than the minimum, 256K will be allocated.
If the physical log volume is a file, it will be expanded if necessary. If the physical log volume is expanded beyond the stated soft limit, it will be shrunk back when a checkpoint occurs.
If the physical log volume is a raw device, it will not expand. When it is out of space, you will get the message SM_LOG_CANNOT_EXTEND.
name
The default name is to use physical.log and then search for path specifications. See the "Run Time Environment" section following in this chapter.
If you specify an absolute path, you will not be able to move the database once it has been created.
The volume path can be either a file path or a raw device path. For raw devices, you must specify an absolute path.
You cannot change the name for the physical log volume once a database has been created.
plogvol is:
guideline = 2 * (max_o_size + 1K) + 32K
In the above formula, substitute the size in bytes of the largest object in the database for max_o_size.
sysvol size nameThe size and location of the system volume that contains database system catalogs and objects.
Arguments:
size
With extent_size = 2, the default size is 128 megabytes.
The absolute maximum is platform dependant.
name
The default name is to use sysvol and then search for path specifications.
If you specify an absolute path, you will not be able to move the database once it has been created. Volume paths can be either a file path or a raw device path.
addvol utility) or remove and recreate the database with a larger value specified for the sysvol parameter.
The system volume will use only as much space as needed, unless it is a raw device or the -i parameter is used with createdb.
A guideline for setting the size of sysvol is:
guideline = min_size + (1.25*(avg_o_size+40) * num_objects)
where avg_o_size is the average size of objects in the database and num_objects is the number of objects.
The minimum and maximum database volume sizes vary depending upon the value set for the extent size:
|
extent_size |
Minimum db volume size |
Maximum db volume size |
1
|
1800K
|
1023M
|
2 (default)
|
1800K
|
2047M
|
3
|
1800K
|
3071M
|
|
|
|
|
createdb and addvol utilities will raise an error if you create or add a database volume smaller than the minimum sizes.If you run out of space in the system volume, you will see the following error message during the execution of an application program:
1083 SM_E_OUT_OF_VOL_SPACE all volumes exhausted
When you get this message, you should use the addvol utility to create additional database space.
Occasionally, you may get a panic message if a database is out of space inside a critical region. The panic message may be error message 1083 (see above).
You may specify a raw device for the system volume. The path must be an absolute path.
For example:
sysvol 10M /dev/partition
async_buffer_cleaner numberIf this parameter is set to an integer greater than zero, a separate thread will be used to asynchronously flush the database server cache to disk. The default is one.
If this parameter is set to zero, the database server process itself will flush the database server cache (no separate thread will be started.)
async_logger numberIf this parameter is set to an integer greater than zero, a separate thread will be used to asynchronously flush the database logging cache to disk. The default is one.
If this parameter is set to zero, the database server process itself will flush the database logging cache (no separate thread will be started.)
commit_flush ON|OFF
If set to ON, server process buffers are flushed to disk after each commit. The default is ON.
datavol volume_name size [absolute_path | relative_path ]The location of a particular data volume.
Elements are:
volume_name
size
absolute_path
relative_path
If you use makedb to create a server profile file and then, before creating the database, create one or many datavol entries for data volumes, then running createdb will create the storage volumes as well as the system, physical log, and logical log volumes. If you run createdb with the -i option, the volumes will also be initialized. See createdb in the "Database Utilities" chapter.
If you create an entry for a data volume that does exist, then whenever the database starts, the system will look for the data volume at the specified location. See the "Move a Database" section in the "Create a Database" chapter for more information.
event_daemon code_path [parameters]
You must separately write this code, which is operating system specific. This code must be on the same machine as the database.
When a database invokes the executable at code_path, it inserts the database name as the first parameter and then follows it with your parameters. If you wish to use multiple parameters, you must enclose them in double quotes and then parse the parameters yourself.
See the "Event Notification" chapter in the Database Fundamentals manual.
event_daemon MANUAL
event_message_mode optionSpecify event message mode.
Options are:
transient
persistent
event_msg_transient_queue_size sizeThe maximum number of per-transaction event messages that can be held in the transient event queue.
The default transient event message queue size is 2048 bytes. You can set it to any value between 0 and 2^32, noninclusive.
The persistent event message queue size is 232, and it cannot be changed.
VERSANT does not use the Operating System message queue.
In UNIX, the event message size is unlimited.
event_registration_mode optionSpecify event registration mode.
Options are:
old_transient
This option is for backwards compatibility.
persistent
transient
locking ON|OFF
The locking parameter specifies whether short locking is on or off:
If locking is OFF, setting of short locks is disabled. Set locking to ON to enable the setting of short locks. This parameter does not affect persistent locks.
The default for personal databases is locking OFF. The default for group databases is locking ON.
Locking controls concurrent access to objects by different processes, and it provides data integrity at the price of performance. It is safe to turn short locking off in a personal database, if you are running only one application process. If multiple applications are accessing a group database, locking should always be on to ensure orderly concurrent access to objects.
logging ON|OFFSpecify whether logical and physical logging are enabled.
The default for both personal and group databases is logging ON.
Logging guarantees that a database can at least be restarted and accessed after a system failure. It also keeps track of the status of transactions and savepoints, and logging ensures database consistency. All recovery processes can recover from crashes that occur during recovery.
Logging must be turned on to perform transaction rollbacks and/or to use savepoints.
Using a raw device for the logical and physical log volume improves performance when logging is enabled.
Logging overhead can be substantial, which is why VERSANT implements single user personal databases where logging can be turned off. However, turning logging off means that full recovery from a system crash may not be possible even though no data is lost. For example, if a crash occurs during a checkin, long transaction information about checked out objects may no longer exist.
All short transaction commits are two-phase, which ensures the consistency of a committed transaction across a distributed database system.
Recommendations
• Logging should always be ON in group databases.
ON in group databases.
profile.be, and set the versant_be_errlog parameter to name of the file where errors should be logged. By default, error logging is off.On UNIX systems, create this parameter with its name in all lower case.
In addition to error number and error message, entries in the error log file also include context information, such as operating system error number, file name, and so on. The exact context information varies from error to error.
This error logging mechanism should not be confused with the functionality represented by the file LOGFILE, which is used to report VERSANT system errors.
The general syntax for setting this parameter is the following, where filename is the absolute or relative path (including name) of your error logging file:
versant_be_errlog filename
bf_dirty_high_water_mark numberSpecify, in number of pages, when an asynchronous page cleaner thread will start to flush to disk dirty pages in the buffer pool.
Together, the high water mark and lower water mark parameters influence when the asynchronous buffer cleaner writes dirty buffer pages to disk.
Without the lower water mark concept, pages that are repeatedly set to dirty are flushed over and over again. With no gap between the high and low water marks, a page that is repeatedly set to dirty does not get flushed in time. The range in between ensures proper flushing.
In general, pages are flushed in priority order, and pages with a numerically lower priority are flushed first. In general, root and branch pages of an index have priority 3, leaf pages of an index have priority 2, and data pages have priority 1. A time algorithm will decrement less used pages to priority 0. However, when you dirty a page, its priority is set back to its correct priority number (for example, a data page will be set to priority 1.)
The asynchronous buffer cleaner wakes up whenever the number of dirty pages in the buffer cache reaches the high water mark. When the number of dirty pages in the buffer cache reaches the high water mark, dirty pages of all priority are flushed until the number of dirty pages reaches the low water mark. The buffer cleaner then flushes all remaining dirty pages of priority 0 and then goes to sleep. Without the low water mark concept, pages that are repeatedly dirtied would otherwise get flushed over and over again, which would degrade performance. Without there being a gap between the high and low water marks, a page that is repeatedly dirtied might go for a long time without being flushed.
For example, suppose that the high water mark is 512 pages and the lower water mark is 204 pages. When the number of dirty pages reaches 512, the buffer cleaner writes dirty pages of any priority until there are only 204 dirty pages left in the buffer cache. From that point on, only pages of priority 0 are flushed.
The default value of bf_dirty_high_water_mark is 512 pages.
The default value of bf_dirty_low_water_mark is 204 pages.
bf_dirty_low_water_mark numberSpecify, in number of pages, when an asynchronous cleanup process or thread will stop clearing the buffer pool of pages containing dirty objects.
See the bf_dirty_high_water_mark parameter for an explanation.
class numberSpecify the integer number of cached user defined classes.
If not specified, the default number of cached user defined classes is 480.
If more than the specified or default number of classes are accessed during the time a database is running, you will get an error.
db_timeout delay
Specify that the database is to be automatically shut down if there have been no active transactions for delay number of minutes.
The default delay is -1, which means no timeout. All negative values also mean no timeout.
For example, to specify automatic shutdown after one hour:
db_timeout 60
heap_size sizeA pre-allocation hint for the initial size of the server process heap in shared memory.
Indicate kilobytes with a K. If you do not specify a value, VERSANT will determine a value.
The server process heap is memory from which internal data structures and server process buffers are allocated, and its size sets a limit on the maximum size of regular object instances.
If you know that a server process will require a lot of memory, you can increase this parameter in order to pre-allocate space. If more memory than the initial amount specified by this parameter is needed, the heap size will be dynamically increased as needed.
If heap_size is too large, you may not be able to allocate shared memory when the database is started.
See also the Application Process heap_size.
index numberSpecify the integer number of cached user defined indexes.
If not specified, the default number of cached user defined indexes is 480.
If more than the specified or default number of indexes are accessed during the time a database is running, you will get an error.
llog_buf_size sizeSpecify the logical log buffer size in bytes.
The default is:
llog_buf_size 161
The larger the logical log buffer, the less frequently the system needs to flush the buffer to disk. Decreasing this parameter will save some memory but increase the frequency of disk writes. Increasing this parameter will slightly reduce the frequency of disk writes but may waste memory and cause paging. The default of 161K should work well for most cases.
The logical log buffer is dynamically divided into two units. This allows use of a double buffering strategy to allow parallel execution of disk input/output and cpu execution.
lock_wait_timeout number_of_seconds
The number of seconds the server waits for a lock on an object to be released before generating an object locked error.
This parameter also affects the breaking of a soft persistent lock with a hard persistent lock. The breakage is delayed by an amount of time equal to the lock_wait_timeout parameter.
The default is to wait for 60 seconds:
lock_wait_timeout 60
Use the value -1 to specify waiting forever and use 0 to specify immediate return.
If a lock cannot be acquired in the specified number of seconds, the following error message will be returned:
2903 SM_LOCK_TIMEOUT Lock wait timed out.
max_page_buffs number_pages
Specify the maximum number of 16K buffers for caching disk pages from data volumes.
This parameter strongly influences system performance. If you set it too low, the disk input/ouput increases. If you set it too high, the physical memory becomes exhausted and virtual memory swapping to disk takes place, which defeats the purpose of chaching disk pages. If you have a large database you can sometimes increase perfomance by increasing this parameter. If you have a small database, you may want to decrease it to save memory.
The default value of 1024 should work well for most applications.
multi_latch ON|OFF
If the multi_latch parameter is set to ON, the database server process will use multiple latches. Each latch will protect a different submodule. This is the default.
If the multi_latch parameter is set to OFF, the database server process will use a single latch to protect its shared memory areas.
For a group database, the ON default improves concurrency when multiple users are accessing the database on a multiple processor machine. For single processor machines, setting multi_latch to ON may not improve your performance.
For a personal database, setting this parameter to OFF improves performance when the database is accessed by a single user.
plog_buf_size sizeSpecify the physical log buffer size in bytes.
The default is:
plog_buf_size 161
The larger the physical log buffer, the less frequently the system needs to flush the buffer to disk. Decreasing this parameter will save some memory but increase the frequency of disk writes. Increasing this parameter will slightly reduce the frequency of disk writes but may waste memory and cause paging. The default of 161K should work well for most cases.
The physical log buffer is dynamically divided into two units. This allows use of a double buffering strategy to allow parallel execution of disk input/output and cpu execution.
pooling_optimize ON|OFFSet Fault Tolerant Server recovery strategy.
Options are:
OFF
OFF, which prevents applications from getting polling induced deadlock errors.
If polling_optimize is OFF, the polling process, while resynchronizing the replica pair after a failure, applies changes one object at a time. Each object is first locked, then the update is applied, and then the lock is released. This prevents polling induced deadlock.
ON
If polling_optimize is ON, objects are group read, then changed, then released. This greatly improves performance. However, this might cause a polling induced deadlock error. If polling_optimize is ON, applications should be able to handle deadlock errors.
transaction numberThe maximum number of concurrent transactions allowed for this database.
The default value is 10.
If more than the specified or default number of transactions are used during the time a database is running, you will get an error.
user numberSpecify the integer number of cached user names.
If not specified, the default number of cached user names is 8.
If more than the specified or default number of user names are used during the time a database is running, you will get an error.
volume numberSpecify the integer number of cached data volumes.
If not specified, the default number of cached data volumes is 16.
If more than the specified or default number of data volumes are used during the time a database is running, you will get an error.
stat [ stat_name ] actionTurn collection of connection and database statistics on or off for this database.
Alternatives for action are:
on
vstats or o_collectstats().
off
By default, statistics collection is off.
stat_name parameter are:
all
all, collection of all database and connection statistics will be turned off or on per the action parameter. This is the same as supplying no value for stat_name. The default.
be_all
be_all, collection of all connection statistics will be turned off or on per the action parameter.
db_all
be_all, collection of all database statistics will be turned off or on per the action parameter.
action parameter.
The names of connection statististics have the prefix be_. The names of database statistics have the prefix db_.
For a list of connection and database statistic names, see the reference for the vstats utility in the System Manual. Statistic names must be specified without the STAT_ prefix and transposed to lower case.
stat in the server process profile to specify the various statistics that you want.Collection of database statistics begins when the database is started. Collection of connection statistics begins with the database connection.
Statistics are stored in memory where they may be viewed with the vstats utility or brought into an application with the C/VERSANT o_collectstats() function.
You cannot use stat to collect function, application, or session statistics.
Even when database replication has been turned on, statistics collection tools and mechanisms operate only on named databases and not on replica databases. To collect statistics for a replica database, you must apply statistics collection mechanisms specifically to the replica database.
For an overview of statistics collection and stastics collection usage notes, see the VERSANT Database Fundamentals Manual.
assertion_level numberType of assertions.
You can set this parameter to levels between 0 and 2. If you set it to 0, the system performs only simple assertions. The higher the level, the more expensive the checking.
The default is 0.
dbtool utility in the chapter "Database Utilities."
trace_components optionsDatabase server components to be traced.
The options parameter can contain one or all of the following elements. If multiple elements are specified, the list must be delimited by commas with no spaces.
|
|
Trace the current state of queries or cursors. |
|
|
Trace entries created, updated, and deleted in the internal AT table. |
|
|
Trace the buffer manager. |
|
|
Trace logging and recovery. |
|
|
Trace process/thread operations. |
|
|
Trace object creation, modification, and deletion. |
|
|
Trace transaction operations. |
trace_entries numberNumber of trace entries to be maintained in the trace file. The default is 10000 entries, after which entries are reused.
trace_file nameName of the trace file.
By default, the trace file will be created in the database directory. On UNIX, the default name of the trace file is .systrace. On Personal Computers, the default name of the trace file is systrace.
If the entry begins with a forward "/" (UNIX) or a backwards slash "\" (PCs,) the name parameter is treated as the full path, including the file name. Otherwise, the name parameter is assumed to be just the file name, and the file will be created in the database directory.
authentication_program program_path
To specify the location of a customized, user authentication program, on the database machine, in the database profile file, add a line containing the keyword authentication_program followed by the path to the database authentication program.
For usage notes, see the chapter "User Authentication" in the VERSANT Database Fundamentals Manual.
event_msg_mode { persistent | transient | old_transient }Specify the persistence of generated events when using event notification features.
Event notification modes are:
persistent
transient
old_transient
event_registration_mode { persistent | transient }Specify the persistence of registrations when using event notification features.
Event notification modes are:
persistent
transient
transient to maintain backward compatibility with applications using VERSANT releases prior to 5.2.
This online documentation is confidential and proprietary to Versant Corporation and is licensed to you, or to your organization, pursuant to the terms of an agreement between you and Versant that restricts the use of this documentation. Please refer to the agreement for more information or call Versant at 510-789-1500 with any questions.