Skip Headers

Oracle® Database Lite Administration and Deployment Guide Release 10.3 Part Number E12089-02 |
Home | Book List | Contents | Index | Contact Us

Previous | Next
| View PDF

# E POLITE.INI Parameters

You can customize Oracle Database Lite by modifying the parameter values defined in your `POLITE.INI` file, which is available in Windows under `%WINDIR%\POLITE.INI` and in Linux under `$ORACLE_HOME/bin`. You must have write permissions on the directory where this file is located to be able to modify the `POLITE.INI` file.

Note:

On the WinCE and EPOC platforms, this file is named `POLITE.TXT`, so that you can double-click on it to open the file.

The following discusses the parameters in the different sections in the `POLITE.INI` file:

- Section E.1, "POLITE.INI File Overview"

- Section E.2, "All Databases Section"

- Section E.3, "Sync Client Parameters—SYNC Section"

- Section E.4, "Synchronization Agent—SYNC_AGENT Section"

- Section E.5, "Device Management Parameters—DMC Section"

- Section E.6, "Network Parameters—NETWORK Section"

- Section E.7, "Sample POLITE.INI File"

## E.1 POLITE.INI File Overview

The `POLITE.INI` file centralizes database volume ID assignments, defines parameters for all databases on a system, and defines synchronization parameters. When you install Oracle Database Lite, the installation creates the `POLITE.INI` file in your Windows 2000, or XP home directory. On Windows CE and EPOC, the file name is `POLITE.TXT`.

The installation automatically sets the parameters in your `POLITE.INI` file, but you can modify them to customize the product behavior. To modify the `POLITE.INI` file, use an ASCII text editor.

## E.2 All Databases Section

The `[All Databases]` section of the `POLITE.INI` file contains parameters that define the behavior of the Oracle Lite database. For full details, see Appendix A, "POLITE.INI Parameters for the Oracle Lite Mobile Client" in the Oracle Database Lite Client Guide.

## E.3 Sync Client Parameters—SYNC Section

Modify the `SYNC` section in the `POLITE.INI` file to control certain synchronization (OCAPI) functions. The following sections list the OCAPI parameters with their corresponding description and an example. OCAPI provides you with the following support functions:

- Enable the caller to start the synchronization process from the client side.

- Set flags for the synchronization session.

- Save user information locally.

Note:

OCAPI is only supported on the Windows 32, Windows CE, and EPOC platforms. For more information, see the Oracle Database Lite Developer's Guide.

### E.3.1 Overview of OCAPI—msync Client API

The msync Client API (OCAPI) is a set of functions that allows programs on client devices to set synchronization parameters and start a synchronization session. You can also use this API to monitor the progress of the synchronization session. OCAPI is the interface to the client side synchronization engine.

As the Administrator, you can set the OCAPI parameters to change the default behavior of OCAPI. When you set the OCAPI parameters in the `POLITE.INI` file, then the parameter settings are implemented for the client on the first synchronization—based on the client platforms where the parameter settings need to apply.

An OCAPI function communicates with the Mobile Server through the selected transport and synchronizes the local database with the remote Mobile Server.

### E.3.2 Synchronization Parameters

The following are synchronization parameters that you can modify:

- Section E.3.2.1, "TIME_LOG"

- Section E.3.2.2, "UPDATE_LOG"

- Section E.3.2.3, "DEBUG"

- Section E.3.2.4, "AUTO_COMMIT_COUNT"

- Section E.3.2.5, "TEMP_DIR"

- Section E.3.2.6, "RESUME_CLIENT_TIMEOUT"

- Section E.3.2.7, "RESUME_CLIENT_MAXSEND"

- Section E.3.2.8, "ERROR_REPORT"

- Section E.3.2.9, "DB_ENCODING"

- Section E.3.2.10, "MEM_THRESHOLD"

- Section E.3.2.11, "VALIDATEDB"

- Section E.3.2.12, "ENCRYPTDB"

- Section E.3.2.13, "SSL_IGNORE_CERT"

#### E.3.2.1 TIME_LOG

Record the start and end time of a synchronization operation. OCAPI creates a table called `C$SYNC_TIME` in the `conscli.odb` file. This file logs the duration of every synchronization process. OCAPI inserts a record in the `C$SYNC_TIME` table which stores the start and end time of every synchronization operation. The administrator can maintain a log history of synchronization times.

Example

    TIME_LOG=TRUE

The above value creates a table called `C$SYNC_TIME` and inserts one row containing the start and end time of the synchronization process.

Default Value

FALSE

FALSE to turn off timelog feature; TRUE to enable timelog feature.

#### E.3.2.2 UPDATE_LOG

Set the update log file. If this parameter is set, OCAPI creates a table called `C$UPDATE_LOG` in the `conscli.odb` file. For every DML operation received from the server, OCAPI records each operation in the `C$UPDATE_LOG` table. Each record contains three entries namely Table Name, Client Side Row ID, and the Log Action Type. The Table Name refers to the table that the operation is performed on. The Client Side Row ID (`C$UID`) is a record pointer that points to the record's Row ID. Type refers to the type of DML operation such as update, insert, and delete.

Example

    UPDATE_LOG=TRUE

The above value creates and inserts rows in the `C$UPDATE_LOG` file. FALSE to turn off update_log feature; TRUE to enable update_log feature.

Default Value

FALSE

#### E.3.2.3 DEBUG

View debugging messages that are sent to the `debug.txt` file, which includes the database name, table names, and the DML operation.

To enable, set this parameter to 1, which writes the debug information regarding the database name, table names, and the DML operation into the `debug.txt` file. This enables OCAPI to invoke debugging messages.

Set to 0 to turn off debug feature, which is the default.

Default Value

0

#### E.3.2.4 AUTO_COMMIT_COUNT

Invoke the auto commit count feature for publication items that use manual synchronization. If this parameter is set to 0, Oracle Database Lite calls a commit at the end of processing for each publication.

When the number of records in a transaction is greater than the `AUTO_COMMIT_COUNT`, then a commit is issued at that time. This occurs only on the first synchronization, complete refresh, or a low memory condition. However, for the fast refresh option, if the auto commit is performed, then a data mismatch will happen between client and server.

During synchronization when `AUTO_COMMIT_COUNT` is set, the user should not add, update, or delete a database record.

If this parameter is set to 1000, Oracle Database Lite calls commits for every 1000 inserts. This value should be more than 100.

Default Value

The default value for `AUTO_COMMIT_COUNT` is 250 records on WINCE; this variable is not valid on WIN32 and LINUX platforms.

#### E.3.2.5 TEMP_DIR

Specify a directory for temporary files. OCAPI creates a temporary file for saving retrieved data. When a large volume of data is being synchronized, the data received in the temporary file can be written to a flash card to save system memory. This feature is beneficial for WinCE developers. The default is the current directory (C:\). This is useful for saving memory by directing temporary files to an external storage card.

Example

    TEMP_DIR=\Storage Card

OCAPI creates a temporary file on the storage card of the Windows CE application. It saves the main memory allocated for the application.

#### E.3.2.6 RESUME_CLIENT_TIMEOUT

The `RESUME_CLIENT_TIMEOUT` parameter is the number of seconds that the client should use to timeout network operations. The default is 60 seconds.

Set the total number of seconds that the client should use to resume network timeout operations.

Default Value

60 seconds

Example

    RESUME_CLIENT_TIMEOUT=120

#### E.3.2.7 RESUME_CLIENT_MAXSEND

The `RESUME_CLIENT_MAXSEND` parameter is the maximum data size, in KB, that the client should send in a single POST request. This is used in cases where there is a proxy with a small limit on the data size in one request. Specifying a reasonable value, such as 256 KB, can also help clients with limited storage space, as they can free the chunks that have already been transmitted and acknowledged. The default is 1024 KB.

Set the maximum data size in KiloBytes sent by a client in a single `POST` request. Some proxies maintain fixed limits on data size in one request.

Default Value

1024

Example

    RESUME_CLIENT_MAXSEND=2048

#### E.3.2.8 ERROR_REPORT

Set client synchronization report results for the server.

- If set to `0`, reports errors to the server during the next synchronization process.

- If set to `1`, reports errors and creates an extra connection to the server.

- If set to `2`, reports synchronization success or error cases and creates an extra connection to the server.

Default Value

0

Example

    ERROR_REPORT=2

#### E.3.2.9 DB_ENCODING

Specify client DB character encoding. This parameter value is the same as values used in Java character encoding. For more information about Java encoding, refer to the following URL:

    http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html

This character encoding affects `CHAR` and `VARCHAR` datatypes inside client snapshot tables only.

Default Value

    NULL

The default value indicates a native character set.

#### E.3.2.10 MEM_THRESHOLD

Set memory threshold value in bytes for synchronization. OCAPI stops synchronization operations when the available memory is less than the specified value. Under low memory conditions, applications can be unstable on a Windows CE device. OCAPI can prevent low memory conditions if you define the threshold correctly. If the available memory is lower than this value, OCAPI displays an error message.

Default Value

524288 (which is equivalent to 512KB)

#### E.3.2.11 VALIDATEDB

Validate the Oracle Lite database, using the `validatedb.exe` after the synchronization process. When an error is reported by the validatedb.exe, OCAPI reports the error to the server. You can set this parameter value from 0 to 100.

- If set to 100, OCAPI runs the `validatedb.exe` for every synchronization process.

- If set to 50, OCAPI runs the `validatedb.exe` for every alternate synchronization process.

- If set to 1, OCAPI runs the `validatedb.exe`, once for every 100 synchronization processes.

Default Value

0, which means that validatedb, by default, is turned off.

#### E.3.2.12 ENCRYPTDB

By default, the Oracle Lite database used by the Mobile client is not encrypted. However, you can ask for it to be encrypted through the `ENCRYPTDB` parameter.

EncyrptDB encrypts the Oracle Lite database by using 128 bit Advanced Encryption Standard (AES) encryption. This does not encrypt the data stored within the Oracle Lite database itself; it only encrypts the database as a whole.

Note:

This parameter encrypts the database using the synchronization parameter.

- If set `ENCRYPTDB` to 0, encryption is not executed. The database is left in whatever current state it is in.

- If set `ENCRYPTDB` to 1, encryption of the database is executed only when a new Oracle Lite database (ODB) file is created. This is the preferred method if you want an encrypted database. Thus, the database is only encrypted when it is created.

- If set `ENCRYPTDB` to 2, encryption of the database runs after every synchronization process. If you already have a database that is not encrypted, then you would want to set `ENCRYPTDB` to 2, perform a synchronization—after which, the database is encrypted—and then set `ENCRYPTDB` back to 1. This way, the database is encrypted, but is not encrypted after every synchronization, which would be a performance hit.

EncryptDB may be executed in the following ways:

- The database may be encrypted by setting the `ENCRYPTDB=2` parameter under the `SYNC` category of the `polite.ini` file. This causes the execution of EncryptDB during the next synchronization. However, if you leave `ENCRYPTDB` set to 2, it executes with every following synchronization cycle that occurs. Change the value to 1 to prevent this from executing with every synchronization cycle. If you wish to decrypt the database later on, change this to 0 and execute the DecryptDB utility.

- EncrypDB may be executed from the command line, but only for Oracle Lite database not using synchronization. The `encrypdb` executable is described in Section 14.2.3, "Execute EncrypDB Command to Encrypt Database" in the Oracle Database Lite Client Guide.

Even though the utility suggests that you may use EncrypDB to change the password used to connect to the device, do not attempt to use `ENCRYPTDB` to change the password. This causes problems that commonly end with a Mobile client uninstall/re-install.

If the SDK version of the CAB file is used to install the Mobile Client, mSQL may also be utilized to run the EncryptDB utility. This is located by scrolling over in the tabs until the Tools section appears.

Default Value

0

#### E.3.2.13 SSL_IGNORE_CERT

If you install the Mobile client using `setup.exe` after you create the self-signed certificate, then a message pops up asking if you want to continue. If you click Yes, then a parameter is added to the `polite.ini` that tells Oracle Database Lite to not validate the certificate. However, if you install the Mobile client using any other method, you need to set this parameter yourself. Set the `SSL_IGNORE_CERT` parameter in the `polite.ini` file to 1.

## E.4 Synchronization Agent—SYNC_AGENT Section

The Synchronization Agent controls the automatic synchronization for the client. If you do not want automatic synchronization to occur at any time, then disable it by specifying `ENABLE=No`. The default is `Yes`.

### E.4.1 SYNC_AGENT

    [SYNC_AGENT]
     ENABLE=YES|NO
     SYNC_LOG=TRUE|FALSE

#### E.4.1.1 ENABLE

Valid values are as follows

- YES: The Sync Agent is enabled and can be started from the `syncagent.exe` UI. When launched from the command line, the Sync Agent executes as a background process

  The mSync executable starts the synchronization agent upon completion of the synchronization and if any of the client databases contain any log based snapshots.

- NO: The Sync Agent is disabled and cannot be started from the `syncagent.exe` UI. Also, if it is launched from the command line where the `-start` option is specified, then the Sync Agent terminates immediately.

  The mSync executable never starts the Sync Agent.

  Note:

  If the Sync Agent has already been started, then the disable does not take effect until the Sync Agent is stopped. You can stop the Sync Agent with the start/stop methods described in Section 2.2.2, "Enable/Disable Automatic Synchronization for the Client" in the Oracle Database Lite Developer's Guide.

#### E.4.1.2 SYNC_LOG

In order for the Sync Agent logging to be modified, the user must restart the Sync Agent or run mSync, which restarts the Sync Agent.

Valid values are as follows:

- TRUE: Sync Agent Logging is enabled to populate the `C$BG_SYNC_LOG` table with any status change or error, such as "Sync Agent Started" or "Sync Agent stopped."

- FALSE: Sync Agent Logging is disabled and the `C$BG_SYNC_LOG` table is not populated. Disable Sync Agent Logging to stop uploading log records during synchronization.

Default Value

    TRUE

## E.5 Device Management Parameters—DMC Section

This section describes parameters in the Device Management section: `DMC`. For full details on device management parameters that can be modified before installing the client, see Section 7.2, "Configuring Mobile Clients Before Installation".

The Device Management parameters are as follows:

- Section E.5.1, "DISABLE_PROMPT"

- Section E.5.2, "PUSH_PORT"

- Section E.5.3, "UPDATE_DAY and UPDATE_TIME"

- Section E.5.4, "MAX_RETRY"

- Section E.5.5, "FREQUENCY"

- Section E.5.6, "DEBUG"

### E.5.1 DISABLE_PROMPT

The `DISABLE_PROMPT` parameter accepts a `TRUE` or `FALSE` value, which causes the following action:

- `TRUE`: The device checks for software updates available on the server. If updates are available, these are brought down to the client and installed.

- `FALSE`: The device checks for software updates available on the server. If updates are available, the option to bring down the updates and install them is displayed to the user, who decides what action to take. If the client chooses to update, then these are brought down to the client and installed.

### E.5.2 PUSH_PORT

T he port number on the Mobile device that accepts device management commands from the Mobile Server. By default, the port number is 8521. Do not modify on the client. Even though it is described here, you should only modify the `PUSH_PORT` variable in the INF file BEFORE the Mobile client is installed. For full details, see Section 7.2, "Configuring Mobile Clients Before Installation".

### E.5.3 UPDATE_DAY and UPDATE_TIME

The day and time to check for software updates for the client. Yo u can modify day and time here or within the DMAgent UI. For details on the DMAgent UI, see Section 7.8, "Using the Device Manager Agent (dmagent) on the Client". If you do want to modify them here, the values are as follows:

Day when the Mobiledevice checks for software updates. Used in combination with `UPDATE_TIME`. UPDATE_DAY takes 0 - 8 which translates to the following days:

- Never = 0

- Daily = 1

- Sunday = 2

- Monday = 3

- Tuesday = 4

- Wednesday = 5

- Thursday = 6

- Friday = 7

- Saturday = 8

Time of day that the Mobile device checks for software updates from the Mobile Server. Used in combination with `UPDATE_DAY`. `UPDATE_TIME` can take values 0 - 23 which translates to the following time:

- 00:00 = 0

- 01:00 = 1

- 12:00 = 12

- 13:00 = 13

- 23:00 = 23

### E.5.4 MAX_RETRY

Integer value that configures the maximum number of retry attempts before abandoning a server command.

### E.5.5 FREQUENCY

The frequency of how many seconds between the client polls. The DMAGENT connects to the Mobile Server checking for new commands at the defined `FREQUENCY` interval.

### E.5.6 DEBUG

If you turn on the `DEBUG` parameter in the `[DMC]` section, then this turns on the debugging for the device manager. All device manager debug messages are written to the `_dmdebug.txt` file.

To enable, set the `DEBUG` parameter in the `[DMC]` section to 1. Set to 0 to turn off debug feature, which is the default.

Default Value

0

## E.6 Network Parameters—NETWORK Section

The following parameter configures how the client interacts over the network:

- Section E.6.1, "DISABLE_SSL_CHECK"

- Section E.6.2, "HTTP_PROXY"

### E.6.1 DISABLE_SSL_CHECK

You can use certificates that are not signed by a trusted authority on the Mobile Server. A Web-to-Go client will use any certificate for encryption without any configuration modifications. However, for all other clients, if you are using a certificate that is not signed by a trusted authority, such as a self-signed certificate, then set the following parameter in the `NETWORK` section in the `polite.ini` (`polite.txt`) file on the client device:

    [NETWORK]
    DISABLE_SSL_CHECK=YES

This parameter enables the client to use the self-signed certificate for SSL encryption, but not to perform SSL authentication.

### E.6.2 HTTP_PROXY

If user has a proxy between the Mobile client and Mobile Server, then in order for the Device Manager (dmagent) to access the Mobile Server to poll for command, then configure this parameter to the proxy server URL, including port number.

Format is `<hostname>:<port>`, as follows:

    [NETWORK]
    HTTP_PROXY=proxy.foo.com:8080

## E.7 Sample POLITE.INI File

The following content is displayed from a sample `POLITE.INI` file.

    [All Databases]
    DATABASE_ID=128
    DB_CHAR_ENCODING=NATIVE
    CACHE_SIZE=4096
    MAX_INDEX_COLUMNS=5
    SQLCOMPATIBILITY=SQL92
    NLS_DATE_FORMAT=RR/MM/DD H24,MI,SS
    NLS_LOCALE=ENGLISH
    TEMP_DB=c:\temp\olite_
    TEMP_DIR=D:\TMP

    [SYNC]
    TIME_LOG=1
    UPDATE_LOG=0