How to Use the Guide to DP4 Configuration

This guide contains detailed information on DP4 configuration.

The What's New page is a summary of recent changes to this document. This will usually be a good place to see what has changed in the latest release of DP4.

The Introduction contains information on what the DP4 configuration files are, where they live, advice on how to go about changing them, and tells you how you can specify configuration options on the command line instead of by editing the configuration file.

The Configuration Utilities section describes the DP4 utilities used to set Configuration information other than that held in the main DP4 configuration file. Much of the information there consists of links to other DP4 manuals.

You can browse the information on the DP4 configuration file itself:

  • by Section (an alpahebetic reference to the possible settings for each section)

or

  • by Subject (an outline of things you are most likely to want to configure and what settings are relevant.)

The Background Information section contains a number of pages that give an overview of complex matters such as Security and changing the appearance and position of programs from the configuration file.

You can also use the table of contents on the left or the search facility to locate information (the index is not complete).

You can also examine the example DP4 configuration file.


What's New in the Guide to DP4 Configuration

This page will tell you about recent changes to this manual. The most recent changes are mentioned first.

New in 4.625

  • 13 Aug 2010 Setting allow_archive_mode added.

New in 4.624

  • 18 Nov 2011 Setting pagedepth_bug added.
  • 14 Oct 2009 Setting prompt_width added.

New in 4.623

  • 21 May 2008 Setting hide_dead_chrome added.
  • 28 Nov 2007 Settings first_day and touch_calendar added. Information about previously undocumented settings checkbox_height and checkbox_widthadded. Information about x_factor and y_factor updated.
  • 8 Jun 2006 Setting dfprint_clip added.
  • 17 May 2006 Setting monitor added.
  • 14 Apr 2005 Setting hide_empty_buttons added.

New in 4.622

  • 17 Jan 2006 Setting defer_bug added.
  • 14 Apr 2005 Setting button_text_centred added.
  • 21 Mar 2005 Meaning of setting debug_echo has changed. (See Diagnostics for more details about changes to error logging in this release).
  • 27 Jan 2005 Setting catch_exceptions added.
  • 26 Jan 2005 Setting shutdowndelay was incorrectly documented as shutdown_delay, but only the first form currently works (except on DP4 for Linux).
  • 19 Jan 2005 New setting no_scroll_bars.
  • 17 Jan 2005 New setting for Windows CE no_auto_close.
  • The configuration options for controlling disk buffering are different in release 4.622. See the updated information in [buffers].

New in 4.621

  • 31 Mar 2004 Now includes some information on the new 4.525 release of DP4 for Unix/Linux. See the UNIX section for details of Unix/Linux specific entries.

  • 23 Mar 2004 It is now possible to change the device names used by DP4 for printing to MS-DOS style devices. See Device Names for details.

  • 11 Feb 2004 The DP4 Installer, and associated utilities now write some information into the [install] section. This is for internal purposes only, and no documentation is available on the entries as yet.

  • 25 Nov 2003 New keep_awake setting added to enable control of Windows CE auto-suspend feature.

  • 21 Nov 2003 New max_programs setting added.

  • 15 Oct 2003 Information added on controlling skinning within DFPRINT via new [DFPRINT] section.

  • 4 Oct 2003 Updated to include information about all aspects of DP4 Configuration, and not just the DP4 Configuration file itself. See Configuration Utilities. Also documented new service_description setting.

  • 14 Apr 2003 The new use_viewer and viewer settings allow you to change the way DP4 sends print output to the screen.

  • 10 Apr 2003 The new refresh_interval setting allows you to limit the frequency of comfort output from programs like DBCHECK and REORGDB, potentially speeding them up.

  • 4 Apr 2003 There are several new settings that allow you to configure various aspects of the appearance of DP4 programs:

    • A new buttonstyle value
    • flatten_dialog
    • shadow_title
    • vertical_gradient
    • DP4 now supports skinning. This is discussed in Skinning DP4.

New in 4.620

Post Beta 4

  • 17 Feb 2003 More information for icon_visible setting.

  • 29 Jan 2003 Page added for new show_im setting for Windows CE.

Beta 4

  • 06 Dec 2002 Pages added for new use_workarea setting. This affects several other pages. See also the Default Window Size and Position. Information about useframe on Windows CE added.

  • 03 Dec 2002 The contents page, and the home page have been changed to simplify navigating the guide, and some summary information is added in a few places for the same reason. Various pages added or updated to describe new options for 4.620:

    • Limiting an application to a single instance using run_once=1 setting
    • Controlling and Disabling DP4 error messages with the [dp4_error] section.
    • Translation for some messages hard coded into terminal manager with string_nn settings.
    • Changing the size of an application's fonts using x_inch and y_inch
    • Removal of interaction between x_factor,y_factor and the DFPRINT program, and using new dfprint_x_factor etc. settings.

    The information in the Coordinate System background article has also been updated.

  • 13 Nov 2002 Some documentation about encrypted entries in the DP4 Configuration file added to How the DP4 configuration file is organised

Beta 3

  • 17 Oct 2002 This What's New page added

  • 15 Oct 2002 onconnect=command line option added to [tcpmgr] section to enable running a "reverse" connection from a DP4 Server.

  • 30 Aug 2002 save_position=0 facility added to prevent updating of configuration file by terminal manager.

Beta 2

  • 26 Apr 2002 A new page bringing together information on how to configure DP4 error logging/diagnostics is added.

  • 23 Apr 2002 Updates for Windows CE version of DP4, and more information on new DP4 Enterprise features (See the WinCE and Startup sections). A new section on Security has been added.

  • 22nd Feb 2002 Information relating to DP4 Enterprise added including new [branding] and [buffers] sections.

New in 4.523/4.619

28 Nov 2001 (4.523/4.619(3) The information relating to SQL Products has been updated to describe new options in the light of recent changes to the Gateway ADCs.

May - July 2001 The information relating to SQL Products has been updated to describe new options for version 4.523, (mainly for the Gateway ADCs)and also previously ondocumented options for ODBC have been added. Refer to the various pages linked to from the [ODBC], [ORACLE], [AUXWODBC], and [SQL] pages.


Introduction

Most aspects of DP4 installation and operation are configurable. There are three main configuration files:

  • The DP4 licence file, (named datafit.sys up to release 4.619, but now called dp4.sys), which as well as containing licence information contains many settings connected with database file locations and limits. This file is supplied separately from the CD ROM containing DP4. (Any licence files contained on that are temporary or evaluation licence files only). Unless it has multiple installations of DP4, a computer will have only one DP4 licence file. Most of the configuration information in the DP4 licence file is manipulated using the DFSETUP utility. One very important piece of information, the system database name is manipulated using the SYSDB utility.

  • The userdata.sys file, which contains user and "terminal" related information, such as security levels, key transalaction tables,color preferences etc. userdata.sys is usually created at install time using the USERDATA program, or it may be installed from the DP4 CD ROM. Depending on how it is installed there may be one or several userdata.sys files present in a DP4 installation. Once created, most of the configuration information in USERDATA.SYS is manipulated using DFSETUP, though other DP4 utilities also update this file in various circumstances.

  • An additional text-based DP4 configuration file, (named datafit.ini up to release 4.619, but now called dp4.ini. Where relevant, an initial version of this file is installed during DP4 installation.

    The DP4 configuration file is a text file. It can be read and edited using any text editor. Double-clicking on its icon in a Windows system will normally load it into NOTEPAD. There is no DP4 utility for editing the DP4 configuration file.

    Before making any changes to the DP4 configuration file, we recommend that you make a backup copy of the file in its present form and keep this in a safe place. If your changes have undesirable effects, you may find it easier and safer to delete the modified file and copy the backup to its original location than to remember and undo the changes you made.

The SYSTEM database also contains a certain amount on configuration information:

  • Where the DP4 menu system is used, or the corresponding user/menu facilities of QAB, it contains the list of users, together with user-specific information such as user preferences and passwords. This information is usually set up using MENUEDIT and DFSETUP.

  • It contains information about the printers, and any specialised hardware devices such as cash registers that your DP4 system uses. This information is usually set up using DFSETUP.

  • Your system database contains the maps and menus used by the standard DP4 utilities. You may wish to customise these, but this Guide does not contain any information on doing this.

An additional method of configuring the base DP4 utilities is via the use of command line options, often called command tails or program arguments. The command line options available with the standard DP4 utilities are described in the DP4 Quick Reference guide.In addition most of the options described in this manual can also be specified as command line options for programs. This is often very useful if you only want to change a setting temporarily or you require a different setting from normal in a particular situation.

The DFSETUP program is used to change the settings in the DP4 licence file and userdata.sys. This program has extensive help messages for most settings. In its present form this guide mainly deals with the third configuration file, henceforth called "the DP4 configuration file".

The names and locations of these files are dependent on the operating system, and also the version and release of DP4 in use. This is described in detail in the Names and Locations of DP4 Configuration Files.


Names and Locations of Configuration Files

The names of the various configuration files depends on the version and release of DP4 installed. Different releases of DP4 also have varying degrees of flexibility as to the location of these files, and there are significant changes in the DP4 Enterprise release.

The changes in DP4 Enterprise (4.620 or later) have been made for three reasons:

  1. We are obliged to stop using the Datafit name in the DP4 product.
  2. The changes make DP4 installation on different platforms more similar.
  3. The changes make it possible to run multiple installations of DP4 simultaneously on the same machine without them interfering with each other (except with legacy versions of DP4).

DP4 Enterprise Releases

  1. The name and location of the DP4 configuration file is dependent on the operating system.

    • On Windows platforms there must be a DP4 configuration file in the same directory as syslibt.dll (or syslibce.dll on Windows CE), and it must be named dp4.ini. If for the time being you wish to continue to name the "real" DP4 configuration file datafit.ini and to store it in the Windows directory then dp4.ini must contain the following two lines only:

      [branding]
      dp4.ini=datafit.ini

      If you do this make sure any other new entries you want to add to the DP4 configuration file are added to datafit.ini, not to the new dp4.ini.

      Do not add the line dp4.ini=dp4.ini to dp4.ini. This would cause dp4.ini to be located in the Windows directory and hence to potentially clash with other dp4 installations. If you want to store dp4.ini in some other directory than the directory that contains syslibt.dll make sure you specify a full pathname. Do not use relative path names, because the working directory for a program may not always be what you expect.

      If dp4.ini does not have a definition for dp4.ini then dp4.ini in the directory containing the loaded syslibt.dll/syslibce.dll is used for all DP4 configuration file information.

    • On other platforms, in particular on Unix and Linux, there is no reliable method of discovering the location of a currently executing binary component, and it is therefore not possible to determine a location for dp4.ini as for Windows. Instead dp4.ini is located as follows: if DP4HOME is defined in the environment its value is assumed to point to dp4.ini, otherwise if the current working directory contains dp4.ini then this is assumed to be the correct dp4.ini, otherwise dp4.ini is assumed to reside in /usr/dp4. To maintain compatibility with existing Unix installations of DP4 in /usr/datafit define DP4HOME=/usr/datafit/ in the environment before loading DP4 components. This initial dp4.ini can be redirected as on Windows, (except that where there is no path component in the name the current working directory is assumed) but there is no reason to do so as datafit.ini was not used in earlier releases.

  2. The DP4 licence file is called dp4.sys. The file must reside in the directory given by the dp4home entry in the [win32], [wince] or [unix] section of the DP4 configuration file. (The [unix] section is used for all Unix like variants of DP4, including Linux and AIX). If this is not specified (recommended) the directory where dp4.ini is initially located is used (i.e. the directory containing syslibt.dll or syslibce.dll on Windows/Windows CE and the DP4HOME or /usr/dp4 directories on Unix/Linux). This directory is assigned to the environment variable given by the value of the homename entry in the [branding] section. If homename is not specified DP4HOME is assumed. You can stop any environment variable being created by putting homename= in the DP4 configuration file.

    For compatibility purposes and for the release 4.620 only the licence file may continue to be called datafit.sys. dp4.sys will be used in preference to datafit.sys if both files exist. The two files are currently identical in format, and datafit.sys can just be renamed to dp4.sys. It is probable that some additional information will be added to the added to the end of dp4.sys in future. Only a few DP4 core components access this file by name, so switching to the new name should not cause any problems.

  3. The name and location of the userdata.sys file is described below.

Releases up to 4.619

  1. The DP4 configuration file is called datafit.ini The file is only used in the Windows version of DP4, and must be installed in the "Windows" directory. Depending on the version of Windows this directory is given either by the windir environment variable, or the SYSTEMROOT environment variable.

  2. The DP4 licence file is called datafit.sys. On Unix/Linux the file must reside in /usr/datafit, on other operating systems the file resides in the location given by the DATAFIT environment variable. If this variable is not defined the "current" directory is assumed, or for older versions of DP4 the "root" directory.

  3. The name and location of the userdata.sys file is described below.

userdata.sys

The name and location of the userdata.sys file is the same in all DP4 releases: programs that access userdata.sys first look for a temporary version of the file named menudata.sys in the current directory, then userdata.sys in the current directory, then userdata.sys in the same directory as dp4.sys.


The Configuration Utilities

From time to time, if you want to make changes to your DP4 configuration you may need to run one of the DP4 utilities that updates configuration information. These are briefly introduced below :

  • DFSETUP

    DFSETUP is one of the most important configuration utilities: it is used to set up the locations where DP4 files are stored, system and transaction logging options, user preferences, and to configure support for printers and other devices.

  • MENUEDIT

    MENUEDIT is used to set up menus for the DP4 program, and also the user accounts. For more information about this utility see Managing Users in the DP4 Developer's Manual.

  • SYSDB

    SYSDB is used to set the system database name in the DP4 licence file. It can usually be run even when a DP4 installation is "broken" in some way or other and can help regain access to it. It is also often useful where a machine has multiple DP4 systems installed. For more information about this utility see SYSDB in the DP4 Quick Reference

  • USERDATA

    The USERDATA utility sets up the information needed to control the screen and keyboard by allowing you to select a screen type. The information required is written to USERDATA.SYS. You can make multiple copies of USERDATA.SYS to cater for mixed terminal types and individual display preferences on a multi-user machine. You may not need to use this program under Windows as DP4 installation installs a suitable version of this file.


DFSETUP - DP4 System Setup utility

DFSETUP is the DP4 setup utility. Use this utility to customise your DP4 system. Changes made using DFSETUP affect the DP4 utilities and any applications programs. Its facilities are described below.

The information specified using the setup utility is written into one of three locations:

  • USERDATA.SYS, or a renamed USERDATA.SYS called TERMINAL.SYS
  • The DP4 licence file (DP4.SYS or DATAFIT.SYS)
  • The System database

The table below shows you which options update what:

DFSETUP Option | Location Updated
Directory Assignment | DP4 Licence File
Console/Transaction logging | DP4 Licence File
User Preferences | userdata.sys or System database (see below)
Keyboard Customisation | userdata.sys
Printer Characteristics | System Database
Serial Number | DP4 Licence File
Terminal Characteristics | terminal.sys (See below)

Please note the following points:

  • Options that update the DP4 licence file usually update the local licence file. In a networked environment you may be able to use the -remote osname, though this is disabled if the network manager is using the -rocopy or -nocopy options. You can also use the -from pathname option to update the DP4 licence file in a specific location. This may be useful if you want to prepare a licence file for a different machine on which it will be difficult to run DFSETUP locally.

  • Changes to the DP4 licence file only becoming fully effective once the DP4 system is stopped and restarted.

  • Options that update userdata.sys always write to a copy of the userdata.sys file in the current directory. Therefore you may need to move or copy the modified userdata.sys back to the directory containing the licence file, if you want to update the master userdata.sys file.

To run DFSETUP from the DP4 system menu:

  1. On the DP4 System menu, select the Configuration Options option:

  2. On the System & User Setup Options menu, select the System Configuration option:

The options in DFSETUP are briefly described below. You should make sure DP4 help messages are turned on when running DFSETUP as for most options they are quite detailed, and go into much more detail than is given here. For a complete list of command line option see DFSETUP in the DP4 Quick Reference

  • Directory assignment

    This allows you to specify the location of databases and files (for example C:\DP4\DB on Windows or /usr/dp4/db on Unix). Please note the following points:

    • If a path you specify begins with a / (or \ except on Unix like systems) then the location is absolute, otherwise it is relative (to the current directory). Relative pathnames should usually only be used for files that are not shared between users. This means that the first five locations (Data Files,Index Files,Log Files,Rollback Files,Backup Files) should usually all use absolute pathnames.

      How relative pathnames behave is depend on the operating system. For example Windows CE does not support current directories at all, and all paths are relative to the root of the system. On Windows, and other MS-DOS like operating systems each "drive" has its own current directory, and relative paths will be relative to the drive specified as the first part of the file location - if no drive is specified the path is relative to the "current drive".

    • Currently the file locations stored in DP4 are limited to 31 characters. In fact DFSETUP limits you even further because it insists on reserving two characters for the drive, and one for a trailing / or \. The limit is slightly increased in 4.621. If you need to use a longer pathname, then you will have to use relative pathnames, and ensure that all your DP4 applications start in a specific location. Alternatively you may be able to use a "subst" command and drive on MS-DOS like operating systems (including Windows).

    • If a computer has several independent hard drives DP4 performance may be improved by dividing the various classes of database file between them - in particular placing the data and index files on separate drives may be helpful, and placing the log files on a separate hard drive from the data files reduces the chance of data loss in the event of a hard drive failure. Using separate partitions on the same hard drive is very unlikely to be beneficial.

    • Using network drives, whether mapped or accessed using a UNC name, is usually a very bad idea, and usually won't work for database files (at least on Windows). You can use network drives for print,spool, and console log files if desired.

  • Console/Transaction logging

    This option allows you to specify transaction, rollback and console logging options for your system. The information is also stored in the DP4 licence file. For more information about this option see Setting Up Transaction and Roll-back Logging in the DP4 Developer's Manual, or read the help messages.

  • User preferences

    The user preferences are the display preferences for your system. These include your choice of number and date formats and your colour preferences. The information is stored in USERDATA.SYS if DFSETUP was run from the command line, or the SYSTEM database if DFSETUP was run from the DP4 system menus. See User Preferences in the DP4 Developer's Manual for further information.

  • Keyboard customisation

    This option allows you to customise the function keys (and any other keys) for use on your system. The information is stored in the key translation table in USERDATA.SYS. For further information see Keyboard Customisation in the OSDI Developer's Guide.

  • Printer and Device Setup

    This option is used to set up information about the printers and any specialised hardware controlled by an OSDI used by your DP4 system. This information is stored on the SYSTEM database, and you must be careful to preserve it when you upgrade to a new release of DP4. See Configuring a Device Group for an OSDI and Configuring a Printer in the OSDI Developers' Guide for more information on using this option.

  • Serial number

    This option allows you to change the client name and licence numbers stored in the DP4 licence file, and add a "time bomb" to create a temporary licence. This option is usually restricted in various ways depending on your licence type.

  • Terminal characteristics

    This option allows you to create a TERMINAL.SYS file that defines your terminal. The TERMINAL.SYS file must be renamed to USERDATA.SYS to be used. This option is only likely to be required if you are using Unix or Linux from an unsupported terminal or emulation. It is a good idea to start with a userdata.sys as similar as possible to what you require. If all you are doing is making a minor modification to an already working userdata.sys, specify the -keeptype command tail when you start DFSETUP.

    This option will initially read terminal.sys from the current directory, if one exists, otherwise it uses your current userdata.sys as a starting point.

    To use this option successfully you will need a document detailing the escape sequences understood by the terminal, and a terminal or emulation that you can use to test the new USERDATA.SYS file with. Using this option of DFSETUP successfully can be challenging, and you may prefer to commission Itim Technology Solutions to do the work required.


USERDATA

You use the USERDATA program to create a USERDATA.SYS file. Some reasons you might want to run this program are:

  • You want to change your keying convention. Running USERDATA is the only way to change the keying convention setting. For more information on the keying convention see Keyboard Interface in the DP4 Quick Reference
  • You will be running DP4 using a dumb terminal or terminal emulator such as Telnet

  • You want to create a suitable userdata.sys file for a Windows CE device.

Here are some notes on using this program.

  • If you are going to replace your current userdata.sys, make sure you keep a backup of the file in case you need to go back to it.

  • USERDATA usually keeps most output related settings, such as output display formats and colours. If you would prefer to revert to the default setttings (which may be a good idea if the userdata.sys file is for a screen with very different capabilities from the one you are using), specify the -reset command tail.

  • On the other hand, USERDATA, does not (by default) keep the keyboard translation table. You can use the -samekey option to keep your current keyboard translation table. However this may sometime give unexpected results (for example if the old and new terminals are for completely different dumb terminals)

  • A userdata.sys file created for a PC Windows operating system will not work well on most Windows CE devices. To create a suitable userdata.sys file for a CE device, run userdata on a Windows PC, but specify the -pspc command tail. Copy the created userdata.sys to the CE device.

  • Running userdata always resets the default security levels to 0, so if you want a userdata.sys file with a higher access level remember to use the User Preferences option of dfsetup afterwards.

  • If you want to create a userdata.sys file for a terminal, and it is not shown in the list of available terminal types, and you are unable or unwilling to make your terminal emulate one of the supported terminal types, then you will need to create a custom userdata.sys file using the Terminal Characteristics option of DFSETUP.

  • For a complete list of command line options see USERDATA in the DP4 Quick Reference.
    For information on creating a USERDATA.SYS for Windows see Creating USERDATA.SYS in the DP4 for Windows Installation Guide.

  • If you want to customise your userdata.sys file further then use the following table to find the appropriate information on what to do next.

    Customisation | Program
    Modify the Default User Preferences | Use the User Preferences option of DFSETUP as described in Changing the Default User Preferences
    Keyboard Customisation (for example configuring keys on specialised keyboards to act as function keys,or keys on regular keyboards to emulate keys on such keyboards) | Use the Keyboard Customisation option of DFSETUP
    Create a userdata.sys file for an unsupported terminal | Use the Terminal Characteristics option of DFSETUP
    Modify the lower case to upper case translate table | Use the COLLATE program as described in the DP4 Developer's Manual.


How the DP4 configuration file is organised

The DP4 configuration file is divided into sections, each relating to a particular program or type of information. The sections are identified by headings enclosed in square brackets, e.g. [TRMW].

This help document describes the contents of the DP4 configuration file, beginning with the [TRMW] section which relates to the DP4 terminal manager. The other sections follow in alphabetical order, although issued DP4 configuration files do not necessarily follow this pattern.

Warning

The entries that are described in this guide are the only ones whose values may safely be updated by a user. In some DP4 configuration files you may find sections that are not documented in this guide. You may also find undocumented entries that for sections described in this document. You are strongly advised not to delete or change the contents of these entries, especially if they are contained in the configuration file you were initially supplied with. These may relate to features that are not part of the core DP4 system, such as POS (point-of-sale) facilities, that have been added by other developers.

The dp4.ini issued on the DP4 CD ROM no longer contains any entries that refer to obsolete or not yet implemented features and should be used as the basis of any DP4 configuration files you issue.

An example DP4 configuration file file is provided for your inspection.

Encrypted Configuration File Entries

From 4.620 it is possible for encrypted information to be stored in the DP4 configuration file. An encrypted entry always begins with one of two special sequences:

  • An entry beginning with ??! is encrypted in such a way that any DP4 program can easily read the decrypted entry. However it will be next to impossible for someone without access to DP4 programming tools to decrypt the entry for themselves - keys are randomly generated, and the algorithm for encryption will not be disclosed.

  • An entry beginning with ??+ is more strongly encrypted. Entries in this form can only be written or read by programs that have had certain password information added to them with the 4.620 version of KENTCURS program. Only programs that have the same passsword encoded into them can read the entries. The password information is itself strongly encrypted, and also includes signature information from the executable file, to prevent any possibility of a malicious user succeeding in gaining unauthorised access to the information by identifying the appropriate part of the file and copying into another executable.

It is in principle safe to manually replace an encrypted entry with a plain text one should you choose to do so. However, you should be very careful before doing so. On no account should you ever modify an encrypted entry directly. Although in most cases you will simply completely invalidate the entry, there is a slight possibility (one in several tens of billions) that the corrupted entry will cause the decyption code to corrupt memory or crash the system. A program that attempts to read a strongly encrypted entry with a valid, but incorrect encoded password may suffer from the same problem.

Developers should note that a DP4 program that reads or writes encrypted entries in the DP4 configuration file cannot be debugged, or be attached to a debugger. Any attempt to do so will cause the program to terminate immediately. Unlike traditional DP4 encryption, this encryption is intended to deter even determined hackers - the encryption support is provided by a DLL that is itself encrypted and any attempt to disable or bypass the code that prevents debugging will hopelessly corrupt the DLL.


Layout of Entries

Entries within each section are described in alphabetical rather than logical order.

Entries are listed as follows:

[section]
Entry=default_value

The first line shows the the name(s) of the section(s) under consideration. Any information on the versions of DP4 the entry is applicable to is given beneath the entry this, followed by a description of the meaning of the various possible values for the entry.

The default value is the value assigned if no value is given for the entry in the DP4 configuration file, which is not necessarily the value specified in the the DP4 configuration file issued with the DP4 CD ROM. When new features are added to DP4 that are controled by entries in the DP4 configuration file the default value is usually chosen to maintain maximum compatibility with earlier releases, whereas the issued the DP4 configuration file will turn on the new feature.

Some of the sections described in this document may contain entries that are not documented here. These entries concern features that are not yet implemented. You are advised not to delete them or change their contents.


Comments

The DP4 configuration file may contain comments. These consist of text explaining the purpose of a statement. Comments are not processed. Any part of a line that follows a semicolon (;) is treated as a comment.

If you add a line to a .INI file, an explanatory comment may prove helpful to others who may edit the file and indeed to yourself if you need to edit the file some time later.

You can prevent the execution of a line by inserting a semicolon at its beginning, so that the whole line is treated as a comment. This is an easily reversible way of investigating the effect of removing a line.


Guidelines for changing the DP4 Configuration File

There are some settings in the DP4 configuration file which should not changed; only those described in this guide are suitable for adjustment.
See the Warning under How the DP4 configuration file is organised.

The DP4 configuration file is a text file. It can be read and edited using any text editor. Double-clicking on its icon in Windows will normally load it into NOTEPAD. From 4.621 DP4 includes a number of "HTML Applications", files with .HTA extensions that can help you make configuration changes of various types. At the time of writing there are applications for controlling DP4 error logging, and using the Skinnning facilities. It is likely that more of these will be available in the fairly near future.

Before making any changes to the DP4 configuration file, we recommend that you make a backup copy of the file in its present form and keep this in a safe place. If your changes have undesirable effects, you may find it easier and safer to delete the modified file and copy the backup to its original location than to remember and undo the changes you made.

If you choose to migrate the configuration file to the Windows Registry we recommend that you maintain your configuration in future by editing the text file and remigrating to the registry rather than using the Windows Registry Editor.


Subject Index

Note This subject index covers the principal subjects only and is not exhaustive

Appearance Related Settings

If you want to customise ... | go to:
3D borders in maps | 3DBorderSize 3DBorderStyle
Buttons in maps | buttonframe *Buttonheight buttonstyle *stdbuttonswanted
Default font | charset fh font forcefont fw usestdfonts weight isometric pointsize
Default Application Window size | Application Window defaults
Disabled text | disablestyle
Font Sizes | Coordinate system x_inch
Help messages | HelpBorderSize pointer help usestatus
Number overflow | OldDP4Numbers
Program window position | x y save_position
Program window size | Coordinate system cols depth detach limitsize rows width x_factor y_factor
Screen display (4.5xx) | *Colours *smooth
Title bar text and alignment | Title stdtitles
Window Styles | useframe Client Edge

* Available for 4.5xx only

System Settings

If you want to customise ... | go to:
Branding of DP4 in your system | [branding]
Diagnostics | Guide [DEBUG] [ERRLOG]
disk buffering/file caching | [buffers]
DP4 shutdown | dfshutdown
Error messages | [dp4_error] [errmsg]
Far East Language support | winime
Prompt at end of batch program | pause
Printing | Printing
Security | Secure Operation of DP4
Running 4.5xx programs with 4.6xx DP4 | use600
Running two or more instances of a DP4 program | run_once
Screen dump format | prtscr_editframe screendumpstyle screenprint
Shutdown (DP4) | dfshutdown shutdowndelay
Shutdown (Windows) | OKEndSession
Speed of DP4 programs running as background tasks | idletime
SQL,ODBC, and OEM database interfaces (Gateway ADCs) | [AUXWODBC] [ORACLE] [SYBASE] [SQL] [sql.config DP4_database_name] [sql.remote DP4_database_name] [sql.xlat DP4_database_name] [sql.xlat2 DP4_database_name]
Startup (DP4) | [PRELOAD] [STARTUP] [SYSTEM]
Support for 16 bit DP4 applications | load_win1632w


Sections

  • [AUXWODBC]
  • [branding]
  • [buffers]
  • [debug]
  • [dp4_error]
  • [dp4srvr]
  • [errlog]
  • [errmsg]
  • [ODBC]
  • [ORACLE]
  • [preload]
  • [SQL]
  • [SQLLIB]
  • [sql.config DP4_database_name]
  • [sql.remote DP4_database_name]
  • [sql.xlat DP4_database_name ]
  • [sql.xlat2 DP4_database_name ]
  • [startup]
  • [SYBASE]
  • [system]
  • [tcpmgr]
  • [trmw]
  • [unix]
  • [win32]
  • [wince]
  • [windows]
  • [WINPRIN]


[AUXWODBC]

The AUXWODBC section is used by the ODBC Gateway ADC (AUXWODBC), described in the DP4 SQL Products Guide. The following entries may be specified in the AUXWODBC section:

  • col_order
  • first_occurs
  • role_sep
  • use_checksum
  • use_long_query
  • use_subquery


col_order

[SYBASE], [AUXWODBC], [ORACLE]
col_order = 1

1 means base dictionary number order; 2 means sequence number order

This allows the user to alter the order in which the column names appear in SQL statements. The default order is to use the DP4 base dictionary number order for the names. This option allows the user to change that order so that it mirrors the sequence number order which can be modified within the DP4 utility MAKEDB when creating database tables. This option is normally used in conjunction with short_sql.


first_occurs

[AUXWODBC], [ORACLE], [SYBASE], [sql.config DP4_database_name]
first_occurs = 0

This allows the user to override the default occurs numbering scheme used to construct names on the OEM database: DP4 multi occurs fields must be mapped to a series of fields on the OEM database.

For example a C30*4 address field becomes ADDRESS_0,ADDRESS_1...

first_occurs=1 will cause the indexes to start from 1 instead of 0.

first_occurs=00 or first_occurs=01 will cause the number to use two digits instead of 1 in all cases. (e.g. address_00), which may be useful if there are fields with occurs>10.

Refer to [sql.config DP4_database_name] section for more information.


role_sep

[AUXWODBC], [ORACLE], [sql.config DP4_database_name], [SYBASE]
Role_sep = '_'

This allows the user to override the standard default setting (an underscore) as the separator between field and role names when translating DP4 database names to names on an OEM database.

Auxoracl needs to generate a name that will be valid on the SQL database that combines the DP4 role and field name. Normally this name will be <fieldname><role_sep><rolename>.

Refer to the [sql.config dbname] section for more information.


use_checksum

[AUXWODBC], [ORACLE], [SYBASE]
use_checksum=0

0 means switched off, 1 means switched on.

use_checksum is a record locking and contention control mechanism for SQL databases. The ADC takes a checksum of all the data records read from the SQL database and stores this within the timestamp field of the DP4 data record structure.

When the user subsequently attempts to update this record, the ADC sends off a 'SELECT ... FOR UPDATE' to lock the record. This also reads the record, for which another checksum is taken and compared with the original checksum to determine whether the data record has been altered since the user first read the record and hence whether there is possible data loss due to the record having been updated by another user.

Although the default for this value is 0 you are strongly recommended to set it to 1 as otherwise contention errors may well not be detected.


use_long_query

[AUXWODBC], [ORACLE], [SYBASE]
use_long_query=0 or 1

0 means switched off, 1 means switched on. The default is 1 in AUXORACL and 0 otherwise.

For tables with multiple key fields SQL does not have an elegant method of selecting the record whose key is the next key in sequence. (Actually SQL2 defines a nice syntax for this allowing comparisons of the form (field1,field2) > (value1,value2). Unfortunately existing databases do not support this syntax and it therefore is not used by the Gateway ADCs at present.)

Instead a where clause of the form WHERE field1 > value1 or (field1 = value1 and field2 > value2) must be used. Another way of expressing this condition is WHERE field1 >= value1 and (field1 > value1 or field2 > value2).

If there are more than two keys the second form of the condition is longer than the first form, because in the first form each field is mentioned at most twice, but in the second form the first key must be mentioned as many times as there are key fields, the second key one fewer times and so on.

SQL databases may behave differently given the two forms of the condition. For example with Oracle there is no difference if there are only two keys, but if there are three, the shorter form of the condition stops the use_rownum feature from optimising the fetch time effectively. If you experience performance problems accessing tables with multi-part keys it is worth experimenting with this setting to see which gives better performance.

It should be noted that this option is partially incompatible with the use_subquery option. If both options are turned on the use_subquery option will only have an effect when exactly one key can vary.


use_subquery

[AUXWODBC], [ORACLE], [SYBASE]
use_subquery=0

0 means switched off, 1 means switched on.

use_subquery controls whether an additional predicate involving a subquery is generated in SELECT statements. The purpose of the subquery is to limit the first key allowed to vary in a non-exact match fetch to have the nearest possible value to its current value. Whether or not this improves performance will depend on how efficient the SQL database is at executing a subquery to determine a MIN or MAX value, and whether the expense of this operation is offset by the saving due to a smaller result set being generated. Experiments suggest that on the whole turning on this option is beneficial.

One situation where the option is not beneficial is if this key does not in fact vary much. For example a point of service system may well have tables where the first key component of most tables is a work station ID. On a local database this key would typically be constant, so the subquery feature would not restrict the result set. In such a system using a non DP4 database would lead to poor performance with a Gateway ADC unless applications fix that key when doing fetch(NEXT) type operations. It would be best to change the key structure of the tables so that the first key does discriminate between records better, or else to alter the application so that it specifies that this key must match.

It should be noted that this option is partially incompatible with the use_long_query option. If both options are turned on the use_subquery option will only have an effect when exactly one key can vary.


[branding]

Information on Branding and DP4 configuration

This page contains all the information you require for branding your DP4 system so that it can be installed safely on any suitable machine without the risk of other DP4 systems already present, or to be installed later interfering with it, or your system with them.

The [branding] Section

The [branding] section of the DP4 configuration file contains entries that affect compatibility with existing DP4 installations. Most of them must be changed if you want to make your DP4 installation completely independent of any other DP4 installation that might be present on the machine, and most of the others you will want to change to "badge engineer" your DP4 system (this is the primary reason the various entries are included in this section rather than one of the others). If you are supplying any kind of "shrink-wrapped" application which is based on DP4 you are highly recommended to make use of this section to ensure that installing your application does not affect any other DP4 installations that might already be present on the machine. There are also a number of other things you may need to do beyond changing the [branding] entries. These are described later on.

  • dp4.ini=

    Please refer to the page Names and Locations of Configuration Files for information about the dp4.ini entry.

  • home_name=DP4HOME

    The home_name entry is the name of the environment variable that contains the location of the DP4 licence file. If this is set to an empty string no environment variable will be used or defined for this location. The old DATAFIT environment variable is no longer used by any standard DP4 components, and neither is the value of this variable, except in new releases of legacy (16 bit) versions of DP4. However your application may well contain script or batch files that expect to be able to discover the location of DP4 via some environment variable.

    On Unix and Linux you must change the value of this entry if the DP4 configuration file and the DP4 licence file are to be in different directories because DP4HOME is read initially to determine the location of dp4.ini, but otherwise there is very little reason to change the value. This variable will be defined automatically by the DP4 startup code on Windows and by the Unix terminal manager (so it will be visible to processes created by the terminal manager, including "Run another Program" programs in QAB for example.).

    In legacy versions of DP4 it is not possible to configure the name of this environment variable and DP4HOME is always checked. On legacy versions of DP4 if DP4HOME is not defined and DATAFIT it then DATAFIT is used instead. The FlexOS version of DP4 has not been updated in this respect - DATAFIT: is used as before.

    The actual value of the environment variable is specified in the [unix],[win32] or [wince] sections as the value of the dp4home entry (dp4home is used there regardless of the value of home_name). A value may be specified to over-ride the default location (refer to the page Names and Locations of Configuration Files for the default). DP4 will use this value to define the environment variable when you connect to the DP4 interface - any inherited value will always be over-ridden as a result. The value in the inifile is used directly by base DP4 components to determine the location of the DP4 licence file, and not the environment variable (if defined).

  • icon=""

    On Windows (but not Windows CE), you can also replace the icon srvw32.exe displays in the taskbar notification area by adding the line icon=filename to the [branding] section. filename must be the name of a Windows icon file, including the path.If the filename is blank the Itim Technology Solutions logo is displayed instead. See the icon_visible option for how to disable the icon when DP4 is run as a service.

  • odbc_name=DP4

    You can control the name that appears for the DP4 ODBC driver in Control panel. Change the value of the odbc_name entry in the [branding] section. e.g. odbc_name="My ODBC driver name" in the DP4 configuration file. Run instutil -odbc to install the DP4 ODBC driver under this name. You can also use instutil -odbc driveranme (e.g. instutil -odbc DATAFIT ) to migrate existing DSNs for drivername to the new name (if you don't do this existing DSNs will continue to work, but will be shown as using the Datafit or DP4 driver.)

  • prefix1=DP4
    prefix2=DP5

    The prefix1 and prefix2 entries are string values that are prefixed to various strings in various places in order to create system wide unique names. There are two different prefixes, for historical reasons only, and the same value can be used for both. The default values "DP4" and "DP5" are chosen to maintain compatibility with previous releases (but are not particulary good choices). DP4 ADCs built up to DP4 version 4.619 may have hard coded references to these prefixes. Therefore if you want to take advantage of the multiple instance feature you must rebuild your ADCs using the new version of the ADC source code components available with DP4 Enterprise. A good prefix would be your company name, or your company's Internet domain name, followed by a product name or code. The prefixes must not contain characters "\" "/" or ":".

  • service_description="DP4 Database and Network Services"
    service_name="dfSolutions"
    service_title="DP4 System"

    The service_name and service_title are used on Windows to name the DP4 service. (service_name is not actually used on Windows 9x or Windows CE, but service_title is always used to name the DP4 service in the taskbar notification area (or system tray)). The service name should be constructed in the same way as the prefix1 and prefix2 values (i.e. based on your company/product name and not containing illegal characters). The service title can be any descriptive name for the service. service_description is shown in the Control Panel Administrative Tools Services Applet on Windows 2000, XP and later. You need to run srvw32 -install after changing the service_title or service_description entries. If you change service_name, you must run srvw32 -uninstall and srvw32 -install

Other Branding Issues

The remainder of this page discusses various other aspects of configuring DP4 so that it can co-exist with other DP4 installations on the same computer system.

Networking-related branding issues

The following discussion is confined to DP4 installation using TCP/IP protocol. Multiple installations on one machine are not supported for other network protocols.

For a machine to act as a DP4 network server or client for different DP4 installations it will be necessary to ensure that DP4 messages intended for one DP4 instance are not accidentally intercepted by another DP4 service and not accidentally sent to the wrong server because of host file or DNS problems.

Port Number

DP4 uses TCP/IP port 5000 by default when creating sockets (and Windows servers use ports 5001 and 5002 also). If multiple DP4 installations use DP4 networking they should all use different port numbers. The network administrator for the system will have to decide on suitable port numbers for each application, and edit the appropriate [startup] sections in the various dp4.ini files to apply -socket command tails . Unfortunately there does not seem to be a more graceful way of doing this.

Machine Names

If possible use real machine names (specified with the -server_name command tail) to identify the location of DP4 servers. If you have to use the old server number scheme instead, for example because you are using auxdistr, then use a [tcpip_servers] section to convert the dp4servernn names into real machine names. Currently the "dp4servernn" type names remain hard-coded into the DP4 network programs when you use server numbers.

Unix Related Issues

On Unix the inter-process communication (IPC)used to communicate with the DP4 interface is built directly into application programs. Unfortunately this means that the changes to this mechanism to permit simultaneous operation of multiple DP4 systems on the same machine require you to relink your C application programs and ADCs with the DP4 Enterprise C library. Until you have done this you must continue to use one of the old IPC mechanisms supported by previous releases of DP4.

The newest and now preferred IPC mechanism is enabled for programs built with the new library if there is an accessible file named dp4ftok in the directory where the initial dp4.ini file is located. The Unix ftok() routine is then used to construct the various DP4 IPC keys based on this file. If this file does not exist but /etc/dp4ftok does that file is used instead in the same way (this requires your program to be built with 4.522 or later libraries). Finally if neither file exists the pre 4.522 scheme of hard coded IPC keys is used instead.


[buffers]

This section is used by the DP4 database manager in release 4.620 and 4.621. As of release 4.622 the [buffers] section itself is no longer used, but the entries listed here can be used in the [dp4srvr],[srv3],[reorgdb], and [dbcheck] sections to control I/O buffering for those programs.

The following entries may be specified in these sections:

  • buffers
  • bypass_cache
  • lazy_delay
  • lazy_threshold
  • lazy_writes
  • max_pending
  • max_workers
  • pagesize
  • read_ahead
  • reread_write
  • tracksize

Make sure you test a range of applications when experimenting with these settings - a change which benefits one application can sometimes be counter productive in another. You may need to repeat tests several times, before you can be sure that a change is beneficial, because timings can be dramatically changed by factors over which you have little or no control, such as where files are located on the disk, and how fragmented they are. This is especially true when your test is updating the database.


buffers

[buffers]
buffers=16384

The number of kilobytes of memory to allocate for caching files. This value can also be specified with the −buffers command tail on the database manager. There is no need for this to be an exact power of 2, but usually only quite large changes in the value will make a significant difference to performance.

The best value to use in any particular in any installation is difficult to predict, and can only be found by experiment. The following advice should be treated with caution.

  • Unless you use the 4.622 bypass_cache=2 setting, the default number of buffers will usually work well, and even lower values, such as 8192 will usually work well. If you do use the bypass_cache=2 setting, you should not use a lower value, as it will probably degrade performance, and higher values are more likely, but by no means certain, to be beneficial.
  • You should probably never specify a value greater than 50% of the available memory. Unless you are sure it is beneficial, it is suggested that you should allocate no more than 65536 buffers on machines with IDE hard drives, and 32768 buffers on machines with SCSI or hardware RAID hard drives. Allocating extra buffers is more likely to be beneficial on IDE hard drives than SCSI drives.
  • You should probably never specify a value that exceeds twice the size of all the databases that will be open at the same time.
  • If you choose to specify a large value, such as buffers=65536 and you are using 4.620 or 4.621, then make sure you set lazy_writes=0. These two releases of DP4 have a performance bug, which becomes severe when very many buffers are used.


bypass_cache

[buffers]
bypass_cache=0

If this value is set to 1 DP4 will open files in such a way as the operating system is unable to cache writes. You might want to do this if you suspect the operating system is failing to save data to disk when it should. Effectively this means all files are treated as though they were opened with the VF_SYNC flag. Write caching by DP4 is unaffected. The operating system read cache is not bypassed.

From 4.622 setting bypass_cache=2 disables all operating system caching and DP4 entirely takes over responsibility for caching database file access. If your databases are small this is unlikely to be beneficial, but on larger databases it can improve performance significantly (by 50% or even 75%). If you choose to do this you may need to tune all the [buffers] settings carefully if you want to get the best possible performance.

On Windows based operating systems, using this setting forces DP4 to write files in sector sized amounts. This means that a file may occasionally contain close to a sector of binary zeros you were not expecting at the end of the file. When the file is closed DP4 briefly re-opens the file and truncates it, removing the spurious zero bytes. However, in the event of a system crash DP4 will not have been able to do this.


lazy_delay

[buffers]
lazy_delay=20

The number of milliseconds the database manager waits for requests from applications before it begins to write to disk cached information almost due to be lost out from the cache. Because writing to disk may be a slow operation increasing this value may make a heavily loaded system slightly more responsive some of the time. However you are more likely to experience performance "glitches" where the database manager has to write a lot of information to disk.

This value is used in conjunction with lazy_threshold.

The database manager will not use any less CPU if you increase this value. The database manager always waits for ever for requests from applications once the cache has been written out.

This option has a slightly different meaning in 4.622. It represents a number of milliseconds to wait for any currently submitted lazy I/O requests to complete before submitting some more. There is probably no benefit in changing this value in 4.622.


lazy_threshold

[buffers]
lazy_threshold=system dependent value

This numeric value is used to together with lazy_delay to set an initial time-out before the database manager begins to flush its cache. The value represents the number of cache buffers considered to liable to be written out in the near future.

When the value is low only the weakest few buffers (i.e. those close to being lost) will initially be candidates for lazy writing, and the database manager will wait longer before writing out most buffers. When the value is high many more buffers will be candidates for lazy writing. If the value is too low lazy writing will be reduced in effectiveness. If it is too high the disk may be "thrashed" as the database manager attempts to write out information too quickly (especially if lazy_delay is set to a very small number). The default value is chosen so that lazy writing only starts after a second or so of inactivity (assuming lazy_delay is not changed).

This value is not used in release 4.622, which uses a completely different algorithm for deciding when to submit writes to the operating system.


lazy_writes

[buffers]
lazy_writes=system dependent value

If this value is non zero "lazy writing" is enabled, which means that during periods of relative inactivity the database manager will ensure all cached information is gradually written out to disk.

This value has DP4 release specific behaviour.

Release 4.620,4.621,4.525

On operating systems for which we support asynchronous file I/O (currently Windows NT,Windows 2000, and Windows XP) the number is the maximum number of lazy disk writes that may be simultaneously in progress, and the actual default value depends on the value of max_pending. For other operating system only one write can be in progress, so any non zero value is treated as 1.

For systems which are constantly heavily loaded (for example where there is a program that continually polls the database) it may be beneficial to completely disable "lazy writing". You should probably also set this option to 0 if you set buffers to a value of 32768 or above. With buffers=16384 lazy writing is likely to be beneficial. With buffers=65536 lazy_writing causes a severe performance degradation.

Release 4.622,4.526

On operating systems for which we support asynchronous file I/O (currently Windows NT,Windows 2000, and Windows XP) the number is the maximum number of lazy disk writes that may be simultaneously submitted, and the actual default value depends on the value of tracksize. For other operating systems only one write can be in progress, so any non zero value is treated as 1.

In release 4.622 lazy writing should not normally be disabled.


max_pending

[buffers]
max_pending=64

4.620,4.621,4.525

This value is only used on operating systems for which we support asynchronous file I/O (currently Windows NT,Windows 2000, and Windows XP).

The number is the maximum number of disk writes that may be simultaneously in progress.

4.622,4.526

This value is used on all operating systems.

DP4 puts all write operations in a "pending" internal queue, and submits writes to a "final" queue to the operating system on a least recently written basis. However the final queue of writes is re-ordered to sequentialise output as much as possible. The max_pending setting is used to determine the maximum amount of re-ordering in this final queue.

If the value is too small DP4 will be performing unnecessarily non-sequential reads and writes. If the value is too large, delays may occur because the result of a read or write is needed but the operation is still in the final queue, and because extra CPU cycles are used keeping this longer queue sorted.


max_workers

[buffers]
max_workers=16

4.622,4.526

On Windows NT familiy operating systems DP4 now creates "worker threads" to perform I/O operations that are likely to be slow and synchronous. By default it uses 16 worker threads. In fact most of the time most of these threads are idle - they exist only to ensure that disk read and write operations are asynchronous (Windows reserves the right to make disk I/O synchronous even when an asynchronous API is used, and often does so).

If your system is very heavily loaded you may find it becomes generally unresponsive, because DP4 is consuming too much of its resources. You can reduce this effect, at the cost of adversely impacting DP4 performance, by limiting the number of worker threads. The minimum permitted value of max_workers is 2.


pagesize

[buffers]
pagesize=1 or 8

This value represents the number of adjacent 512 byte disk sectors that are read and written simultaneously and kept contiguous in memory.

You must ensure that pagesize is large enough so that an index node can be contained in a single page. Currently, if your index node size exceeds the page size DP4 will crash.

At least on computers using Intel Processors, operating systems usually cache disk information in 4K chunks, and therefore all other things being equal it is a good idea for programs to do the same. Unfortunately 4K can be inconviently large for DP4. For example the index file of a DP4 database normally uses 512 byte records (though this can now be changed), so using a page size of 8 can mean that information that could usefully remain in the cache is thrown out in favour of information that is not needed but is on the same page as information that is. Once there are enough disk buffers the benefit of using the operating system's natural page size outweighs the benefit of keeping the best set of sectors. The default pagesize is 1 if less than 1 Megabyte of cache is allocated to DP4, and 8 otherwise.

In release 4.622 DP4 will force the page size to the "natural" value as indicated by the operating system if the bypass_cache=2 setting is enabled.


read_ahead

[buffers]
read_ahead=0 or 1

This value is only used in Windows at present. If it is 1 then DP4 may read data from a file before you have asked for it. It does this in two ways:

  • When a program performs a fetch(NEXT) DP4 assumes it will soon perform another fetch(NEXT) to get the record after that, and so on, and starts asynchronous reads to ensure that parts of the file that this will access will be ready for reading.
  • Whenever a file is accessed sequentially, or close to sequentially, DP4 performs read-ahead, by progressively increasing amounts so long as the file continues to be read sequentially, and only up to a maximum of two "tracksize" buffers ahead. This type of read_ahead is only performed when bypass_cache=2 - it is assumed the operating system will be capable of performing similar buffering for itself otherwise.

Read-ahead defaults to 1 if bypass_cache=2 and 0 otherwise. In our tests read_ahead was of little benefit unless the operating system file cache is disabled. However, it might still be of some benefit for a highly fragmented databased. On a large fragmented database read-ahead can reduce the time to fetch all the records in a table by 50% or more provided bypass_cache=2 is set.


reread_write

[buffers]
reread_write=0

This value is only used in Windows at present. If it is 0 then if the database manager needs to read data from a buffer that is currently being asynchronously written by the operating system the database manager waits for the write to complete before reading the data. If it is 1 then the database manager does not wait. Therefore performance is slightly improved by setting this value to 1.

The value is 0 by default in releases 4.620 and 4.621 because Microsoft documentation consulted at the time they were produced implied that not waiting for the write to complete could cause data corruption. Microsoft documentation has now changed, and implies that not waiting is safe. The value is 1 by default in 4.622.


tracksize

[buffers]
tracksize=128

This value represents the number of adjacent 512 byte disk sectors that DP4 will attempt to read and write simultaneously by coalescing pages.

Disk controllers usually have an optimum data transfer size, for which reading or writing the disk reaches a peak transfer rate. Usually this is somewhere around 64K bytes (acutally the peak may differ for read and write operations, but DP4 does not yet cater for this).

In release 4.622 DP4 may attempt to re-order disk reads and writes to enable it to access the disk using amounts of data larger than a single page of disk buffers. For example if the database manager needs to read two index nodes that are close together DP4 may allocate extra pages to allow the two index nodes to be accessed in a single operation. Most changes of this type only take place if the bypass_cache=2 setting is enabled.


DEBUG

[DEBUG]
debug_auxsql=0
debug_disk=0
debug_error=0
debug_ipc=0
debug_loader=0
debug_odbc=0
debug_sql=0
debug_version=0
debug_win1632=0

This section can be used to turn on diagnostics, by changing the values to 1, in various parts of DP4. The diagnostics are sent to the ERRLOG program. In some cases setting the value to 2, 3 or even 4, will produce additional diagnostics. Normally you will only turn on diagnostics when asked to do so by Itim Technology Solutions during problem diagnosis.

In 4.622 disk debug_disk=2 reports delays due to I/O. debug_disk=3 reports timings for all physical I/O. debug_disk=4 gives additional diagnostics showing how DP4 converted "logical" to "physical" I/O. In 4.620/4.621 debug_disk supports the same range of values, but the meanings are not so clearly defined. debug_disk=2 is intended not to impact performance too severely, and may well be of use if you are investigating performance. Some apparent delays are probably insignificant - the system clock usually has a granularity of 15ms, so delays around this length will occur from time simply because a clock interrupt has occurred while DP4 is doing I/O related work.

WARNING

If these values are set to 1, DP4 programs will use up processor time formatting diagnostics even if load_errlog is set to 0.

debug_error and debug_version are set to 1 in the issued DP4 configuration file. Prior to release 4.620 the version information reported by debug_version often refers to one of the DLLs loaded by the program, and not the program itself. From release 4.620 version information is always accurate.


errlog

[win32]
errlog=errlog.w32

[wince]
errlog=errlog.wce

This sets the name of the error logging program that SRVW32 or SRVWCE runs if load_errlog=1 is set in [SYSTEM].


[TRMW]

[DFPRINT]

From release 4.621 the [DFPRINT] section can be used to specify a value for any entry that is used by the DFPRINT program when formatting output that would normally be read from the [TRMW] section.

For example, some 4.621 user-interface features like texture may not work well with printed or file output.

Normally the hierarchy for reading [TRMW] type enries is as follows:

  • Look for explicit value in [progname] section. If a value is found use that value
  • Look for an explicit value in [trmw] section. If a value is found use that value
  • Use the default value

Inside DFPRINT this hierarchy is modified as follows:

  • Look for explicit value in [progname] section. If a value is found use that value
  • Look for an explicit value in [dfprint] section. If a value is found use that value
  • Look for an explicit value in [trmw] section. If a value is found use that value
  • Use the default value

It should also be noted that whereas in regular applications the current program name can be controlled by trm_set_progname(), and in particular is changed to the name of the QAB program by QAB, inside DFPRINT the program name is always derived from the name of the executable that created the file DFPRINT reads.

In addition there is one special [DFPRINT] value: no_texture.


no_texture

[DFPRINT]
no_texture=1

If no_texture is 1, DFPRINT will not use skinning when rendering controls.

If no_texture is 0, DFPRINT may use skinning, depending on whether or not it would be used by the application that created the report, and on the various skin-related settings in the [dfprint] section.

This value can also be specified in application ([progname]) sections to enable or disabling skinning of reports on a per-application basis.


dp4_error

[dp4_error]
use_full_name=0
write_evtlog=1
write_errlog=1
show_dp4_message=1

This section can be used to control reporting of DP4 error messages on a program by program basis. Like the [trmw] section, the entries in this section can, and usually should, be specified in a [progname] section. The [trmw] section is not used because this section also works with DP4 programs that do not use the DP4 Terminal manager to report errors.

For example, if you want to run COPYDB as part of an automatic database upgrade process and do not want it to pause in the event of a problem you run COPYDB with the -nopause command tail. However, this would not stop COPYDB stopping in the event of a DP4 System or Fail Error (for example a broken network connection). To prevent COPYDB stopping in those circumstances you would run it with the -show_dp4_message=0 command tail, or with show_dp4_message=0 added to the [copydb] section.


show_dp4_message

[dp4_error]
show_dp4_message=1

When DP4 programs generate a DP4 system error or fail message the message is usually dispalyed on screen in a message box that the user must acknowledge. If show_dp4_message=0 is set this is not done, and programs that generate such an error will normally terminate without warning. Any error message is still written to the DP4 error log or event log (depending on the settings of write_evtlog and write_errlog ). If the message was generated through a call to the DP4 Terminal Manager the error is always written to the DP4 System Log (SYSLOG.PRN). System error messages generated from C++ applications will not be written to SYSLOG.PRN in most circumstances.

This option should never be specified in the [dp4_error] section itself. You may set it in a [progname] section for programs that must be run without any user interaction (for example as part of overnight processing).


use_full_name

[dp4_error]
use_full_name=0

When DP4 programs generate a DP4 system error or fail message the title bar contains the name of the application that is reporting the error. Usually the name is shown minus the pathname and extension. If use_full_name=1 is set the full name is used. The full name is always shown in the event log.

This option should not normally be specified in the [dp4_error] section itself unless you want to force the full path name into the title bar of error messages for all DP4 applications.


write_errlog

[dp4_error]
write_errlog=1

When DP4 programs generate a DP4 system error or fail message the message is usually written to the DP4 error log program (if it is running). If write_errlog=0 is set this is not done.

You may choose to set this in the [dp4_error] section if you are not running with DP4 error logging enabled (you have load_errlog=0). If you are using DP4 error logging then this option should not normally be specified in the [dp4_error] section itself unless you want to disable error logging for DP4 errors completely.


write_evtlog

[dp4_error]
write_evtlog=1

When DP4 programs generate a DP4 system error or fail message the message is usually written to the event log on NT based operating systems. If write_evtlog=0 is set event logging is disabled.

This option should not normally be specified in the [dp4_error] section itself unless you want to disable event logging for DP4 errors completely.


[dp4srvr]

This section is used by the DP4 database manager from release 4.622. Its main use is for the settings documented in the [buffers] section.

This section can also contain the catch_exceptions and allow_archive_mode settings.


archive_mode

allow_archive_mode=1

[DP4SRVR]
allow_archive_mode=1

DP4 has long allowed programs which normally require write access to a database to degrade to read-only access if the operating system denies write access to the database files. (A warning messagem, DP4 System Warning 39, is displayed when this happens, allowing the user to abort the program if the behaviour is unexpected or undesired). This was intended as a useful feature since it allows applications to make use of archived copies of databases on CD. However, it is undesirable in systems which have financial transactions, because once the initial message has been acknowledged no further error information about lost transactions is returned to the application.

From 4.625 you can disable this behaviour by specifying allow_archive_mode=0. In this mode, if the database cannot be opened for write access then the application will fail (System warning 39 is again generated, but is now treated as a systrem error). Note that this applies even for applications which request only read-only access to the database. This setting does not prevent reports or other "read-only" programs from opening the database provided the operating system does allow write access. If you apply this setting you should change the text of sysmsg_39 in the [errmsg] section of DP4.ini


catch_exceptions

[dp4srvr]
catch_exceptions=1

0 means switched off, 1 means switched on.

This setting, introduced in release 4.622, controls whether dp4srvr.w32 should attempt to handle any exceptions (protection violations or divide by zero errors for example) that it generates. If this setting is enabled then if dp4srvr generates an exception it will shut down the DP4 service, and all DP4 programs will get IPC errors and should terminate. If DP4 error logging is enabled a diagnostic showing the address of the exception and the contents of the CPU registers is sent to the log.

If this setting is disabled the machine's default exception handler will be used. This is likely to be Dr Watson or a similar utility. On some machines Dr Watson does not work well with dp4srvr.w32, and may cause the entire DP4 system to hang. For details refer to a4000028 on the DP4 Web site.


[ERRLOG]

In WIN32 and Windows CE environments a program called ERRLOG can be loaded as part of the DP4 system. We may ask you to use this program to assist with problem diagnosis. This program is loaded by setting the load_errlog parameter in the [system] section to 1.

The following entries control the behaviour of the errlog program:

  • debug_date
  • debug_echo
  • debug_file_name
  • debug_file_flush
  • debug_file_size
  • debug_keep_file
  • ignore_shutdown


debug_date

[errlog]
debug_date=0

If 1, the date and time are printed at the start of each line in the DEBUG.OUT file.

If 0 the date and time is printed when more than one second elapses between diagnostics.

The date and time is not echoed to the screen.

You should note that the date and time are the date and time when the error message is received by the error logging program, not when it is generated. Therefore this mechanism cannot be relied on for analyzing time-critical errors.


debug_echo

[errlog]
debug_echo=0

If 0, diagnostics are not displayed but are only written to a file.

If 1 diagnostics are displayed in a special errlog window on screen.

If you require this option you must enable the 'Allow service to interact with desktop' checkbox when using Windows NT or Windows 2000 (set in the startup properties for the DP4 service).

As of release 4.622 this setting only sets the initial state of the error log window. Provided the error log is loaded you can show it at any time by selecting the "View log file" option from the popup menu of the DP4 service icon in the taskbar notification area, and you can hide the error log window by closing it.


debug_file_name

[errlog]
debug_file_name=debug.out

This specifies the filename used to contain diagnostics.

As of release 4.622, the issued DP4 configuration file for Windows platforms specifies the value debug.txt for this option, as this makes viewing the file with Notepad easier.


debug_file_flush

[errlog]
debug_file_flush=0

If 1, DEBUG.OUT is flushed to disk after every diagnostic. Otherwise DEBUG.OUT is flushed when the ERRLOG program is closed down.

There should be no reason to use this under Windows NT. Under Windows 95 it might be useful if a DP4 system causes Windows to hang completely.


debug_file_size

[errlog]
debug_file_size=128

This specifies the maximum size in Kilobytes to which the debug file can grow. If 0, it is allowed to grow indefinitely.


debug_keep_file

[errlog]
debug_keep_file=0

If 0, the current DEBUG.OUT is renamed DEBUG.BAK,deleting any old DEBUG.BAK first, when it reaches the maximum size and a new debug file is created.

If 1, the current DEBUG.OUT is renamed DEBUG.000, DEBUG.001 etc, when it reaches the maximum size, but only if a line containing the word ERROR has been printed since DP4 was loaded.


ignore_shutdown

[errlog]
ignore_shutdown=0

If 1, the errlog program is not terminated when the DP4 service is stopped. This may be useful if you are trying to diagnose a problem that is preventing DP4 from loading correctly.


[ERRMSG]

This section is used to contain text for various error messages that may be displayed by the system. If entries in the section are missing, the error messages will contain default text instead. If you intend to alter or translate these messages, you should note that they are subject to change between releases. Refer to the currently issued DP4 configuration file for the contents of this section.


[ODBC]

This section is used by the DP4 ODBC Driver. Most entries are usually specified on a per DSN (database connection) level in the [dsnname] section of the ODBC.INI file: the configuration dialog for creating DSNs sets them up.

The following entries are set in the configuration dialog. The values in the [odbc] section provide the initial defaults when setting up a new DP4 DSN. For exsiting DSNs any values missing from the [dsnname] section will take their value from the [ODBC] section also. Therefore adding values for these options to the DP4 configuration file may break existing DSNs created with an earlier version of the DP4 ODBC driver.

  • dbname
  • db_is_remote
  • no_private
  • omit_checks
  • password
  • prompt_for_user
  • rserver
  • user

The following values are not set up by the configuration dialog, but may be set in either the appropriate section of odbc.ini or the [odbc] section of the DP4 configuration file.

  • anon_logon_ok
  • curly_occurs
  • detect_crystal_reports
  • detect_ms_access
  • oracle


dbname

[ODBC]
dbname=""

Specifies the name of the database the DSN connects to. Prior to version 4.523/4.619 the database name had to match the DSN name, and the DSN name is still used if no value is specified for this value.

This option should only be specified in [dsnname] sections of odbc.ini and not in the DP4 configuration file itself.


db_is_remote

[ODBC]
db_is_remote=0

If set to 1, and DP4 is set to run in a network client configuration, the DSN will attempt to connect to the server name specified in the rserver value. You only need to use this option if you want to connect to a specified server that is not the default DP4 server.

This option should only be specified in [dsnname] sections of odbc.ini and not in the DP4 configuration file itself.


no_private

[ODBC]
no_private=0

If set to 1, the DP4 ODBC driver will access the database as though the PRIVATE_DB flag were not specified. This means a connection will not see its own uncommitted updates. This may provide a considerable performance improvement. This value corresponds to the "go faster" checkbox in the configuration dialog.


omit_checks

[ODBC]
omit_checks=0

If set to 1, the DP4 ODBC driver will access the database with all the normal referential integrity checks disabled (i.e. there will be no orphan checking/child delete on deleteions or checking for the existence of parent records on updates/inserts). This may provide a performance improvement, but is not recommended for general use.


password

[ODBC]
password=

Specifies the password for the DP4 user that the connection uses. The value is only saved by the DP4 ODBC driver if the prompt_for_user option is set to 0.


prompt_for_user

[ODBC]
prompt_for_user=1

Specifies whether the DP4 ODBC driver should prompt for a user when a client tries to make a connection using a DSN.

This option should only be specified in [dsnname] sections of odbc.ini and not in the DP4 configuration file itself.


rserver

[ODBC]
rserver=server_name

Specifies a server name that the DSN should connect to. If set this over-rides the default server that DP4 normally connects to. The value is only used if the db_is_remote option is also set to 1.

This option should only be specified in [dsnname] sections of odbc.ini and not in the DP4 configuration file itself.


user

[ODBC]
user=

Specifies the DP4 user that the connection uses. The value is only definitely used if the prompt_for_user option is set to 0, otherwise it is the default user presented in the configuration dialog.


allow_null_key

anon_logon_ok

[ODBC]
anon_logon_ok=0

If set to 1 the DP4 ODBC driver will allow a connection to be made with a blank user name. This is normally disallowed.


curly_occurs

[ODBC]
curly_occurs=0

If set to 1 the DP4 ODBC driver will report column names for multi occurs fields using { and } round the occurs. Usually [ and ] are used, but some software (notably Microsoft Access) cannot cope with these characters in column names. (Microsoft Access is normally detected automatically, and the ODBC driver will automatically use { and } in this case, regardless of the setting of this option).


detect_crystal_reports

[ODBC]
detect_crystal_reports=1

If set to 1 the DP4 ODBC driver will report time fields as having a character type if it detects the client program is Crystal Reports. Early versions of Crystal Reports could not use the DP4 time datatype.

This work-around is unnecessary from version 6 of Crystal Reports and may not work properly with version 8. You can set it to 0 if necessary. See A4000011 on the DP4 User group for further information.


detect_ms_access

[ODBC]
detect_ms_access=1

If set to 1 the DP4 ODBC driver will behave as though curly_occurs was set to 1 if it detects that the client program is Microsoft Access.

In this case it will report column names for multi occurs fields using { and } round the occurs. Usually [ and ] are used, but Microsoft Access cannot cope with these characters in column names.

Access can be detected because it attempts to read a non-existent configuration table.


oracle

[ODBC]
oracle=0

If set to 1, the DP4 ODBC driver will report column names to match those that AUXORACL would expect to see on an Oracle database. In addition the data type for type M and U fields is reported as SQL_VARCHAR instead of SQL_CHAR, and the type of boolean fields may also be changed (see the bool_as char setting below).

The following entries from the [ORACLE] section are used in the appropriate way:

  • bool_as_char
  • col_order
  • role_sep
  • first_occurs

This option is not intended for general use, but as a means of creating an Oracle Schema from a DP4 database. The column names reported by the ODBC driver when this option is in use are not understood by the DP4 SQL Engine, so you would have problems using a DSN configured like this.


[ORACLE]

This section is used by the DP4 Oracle Gateway ADC (AUXORACL.W32). This is not a standard DP4 component and must be purchsed separately. It is described in the DP4 SQL Products Guide.

The following entries may be specified in the Oracle section:

  • allow_null_key
  • array_fetch
  • bin_data
  • block_post
  • bool_as_char
  • col_order
  • first_occurs
  • ignore_time
  • max_max_cursors
  • max_statements
  • role_sep
  • schema_name
  • sequence_format
  • short_sql
  • s_as_raw
  • use_checksum
  • use_logon_dialog
  • use_long_query
  • use_rownum
  • use_subquery

  • use_serializable

  • Customer specific values


allow_null_key

[ORACLE]
allow_null_key= 0

An attempt to create a record with null primary keys on Oracle will generate a constraint violation. Normally this would cause system error 311 to be generated. You can set allow_null_key=1 for this error to be ignored.

Note that this does not actually enable you to create records with null keys - it just stops programs that do create them from terminating with a system error.


array_fetch

[ORACLE]
array_fetch=1

0 means switched off, 1 means switched on.

This allows DP4 block fetches to be translated into Oracle OCI array fetches which may improve performance.


bin_data

[ORACLE]
bin_data = 0

You need to set this to 1 if you have want to store binary data in DP4 character fields.


block_post

[ORACLE]
block_post=1

0 means switched off, 1 means switched on.

This entry controls how AUXORACL implements calls which update the database. If block_post=0 each call to update the database generates a separate SQL statement. If block_post=1, several separate updates are combined into one, and the update is done via a call to a stored procedure, the name of which is dependent on the set of updates to be performed. If the procedure does not exist on Oracle, auxoracl creates it and then executes the procedure again. In theory users could modify the stored procedure to implement additional constraints.

N.B. This option is only enabled when use_checksum is also set to 1.

Although the option currently defaults to 1 you are recommended not to use it until the DP4 database structure is finalised, as otherwise the stored procedure may be incorrect. We may change the implementation details of this feature, in future, to allow use of more sophisticated features of databases and it may also be extended to include auxsybas and auxwodbc


bool_as_char

[ORACLE]
bool_as_char=0

In AUXORACL boolean fields on the DP4 database are assumed to be implemented on the Oracle database as numbers that can only take the value 0 or 1. If this option is set to 1 they are assumed to be implemented as character fields that can take the value N or Y (N and Y are hardcoded). This may make it easier to do certain types of import/export operation.


ignore_time

[ORACLE]
ignore_time=0

0 means switched off, 1 means switched on.

This adds the TRUNC function to SQL statements on the DATE datatype for when related DP4 date/time fields are combined into one Oracle DATA datatype and the application wishes to select all the records for a particular day irrespective of time for example.

It basically truncates the DATE within Oracle to chop off the time portion making the time part of each record 00:00:00.

This option was added in the past in connection with the timestamps option and is similarly not recommended.


max_max_cursors

[ORACLE], [SYBASE]
max_max_cursors=100 (or 0)

[ORACLE]

Possible settings: 1 (or 0 after build 96) to maximum of open_cursors parameter in the Oracle database INIT<SID>.ORA file

This is the maximum number of cursors that auxoracl will attempt to open in Oracle. When this number, the limit across all connections, is reached, it begins to close cursors to make them available for reuse. The advantage of the seemingly high devault value is that it keeps cursors open. When cursors associated with SQL statements have been closed, they have to be re-parsed within Oracle. Keeping cursors open avoids this and reduces traffic across the network, speeding up processing.

As of build 96 of AUXORACL there is usually no reason to limit cursors in this way (it can result in an "unfair" division of cursors between different users), and you may specify a limit of 0, which is the default from build 97 on

[SYBASE]

The meaning of the variable is identical. However we do not have any information about the maximum value allowed, nor the effect on performance of changing it.


max_statements

[SYBASE], [ORACLE]
max_statements=64

This is the maximum number of cursors that auxoracl or auxsybas will attempt to open per connection before it begins to close cursors to free up some for reuse.

The advantage of having this reasonably high is that it may be possible to reuse existing prepared SQL statements. The amount of reuse possible varies according to the database in use.

Note that this value is not used with auxwodbc because there is a per database way to specify the number of statements to keep for this program. See statements.

Prior to build 96 of AUXORACL, this value was in fact counted up on a per table rather than per connection basis. This meant it did not work as intended and the maximum number of cursors might be exceeded. This problem has now been fixed. On Oracle, you are recommended to specify a value for max_statements that it is only slightly less than the value specified for open_cursors in the initdbname.ora file for the Oracle database (which you can edit and increase to a larger value if required) .

If the SQL database reports that the maximum number of cursors has been exceeded DP4 will silently close old cursors and reduce the value of max_statements that applies to that database.


qab_lock

This entry is no longer available as its use could cause a hang to occur.

The entry was available in previous versions of auxoracl. The behaviour in the present version is now always similar to what it would have been when qab_lock was set to 1. When an application tries to lock a record, if the record is already locked (selected for update) by another application the LOCKED variable is set to TRUE and return to the application is immediate.


schema_name

[ORACLE], [SYBASE]
schema_name=""

Table names in generated SQL statements are prefixed with this value if specified.


sequence_format

[ORACLE]
sequence_format=SEQ_%s

This option controls the name of the Oracle Sequence onject used to implement autoinc(). The name is constructed by replacing %s with the appropriate name table. For example if you specify sequence_format=%s_SEQ the sequence object used to autoincrement the CUSTOMER table would CUSTOMER_SEQ. Some third party software may expect the sequence object to have a particular name.


short_sql

[ORACLE], [SYBASE]
short_sql=0

If this is 1 select statements are generated as select * from table. For this to work you have to be absolutely certain that Oracle or Sybase will return the columns in the correct order. Auxoracl/Auxsybas do not check this.


s_as_raw

[ORACLE]
s_as_raw=0

0 means switched off; 1 means switched on

This setting determines whether or not character translation is to be performed for DP4 type S fields. This can enable the data to be stored in Oracle in a RAW column rather than as Varchar. This does however, assume that the user will only be attempting to put binary data in this column/field.


sys_on_app_name

[oracle]
sys_on_app_name=dbname

This entry is no longer available. In previous versions of auxoracl it was used as a way of holding system database entries on Oracle. However it could cause problems, and degraded performance. Now you can map the system database in the same way as other databases, i.e. specify an appropriate entry for the system database in the [sql] section.


use_logon_dialog

[ORACLE]
Use_logon_dialog=0

0 means switched off, 1 means switched on

If this is set to 1 and the connection string specified for a database in the [sql] section is just "1", then the user is requested for log on details for the database via a Windows dialog.


use_rownum

[ORACLE]
use_rownum=0

The value is the maximum number of rows to be returned by a single select.

use_rownum controls whether SQL select statements generated by AUXORACL limit the number of rows to be returned by modifying the generated select statement to be SELECT * FROM (select_statement) WHERE ROWNUM<=n". This useful facility was introduced in Oracle Version 8.1. There is no elegant means in standard SQL of limiting the number or rows to be returned by a SQL SELECT.

This facility can only be used with Oracle 8.1 (and presumably later versions). It is not supported by Oracle 8.

Using this facility can help performance when accessing a large table. For example usually a DP4 fetch(FIRST) will read the entire table. Although subsequent calls to fetch(NEXT) will be fast, in the case where only the FIRST record is required the performance hit may be unacceptable, particularly on very large databases. Using use_rownum=1 makes the fetch FIRST faster. On the other hand a subsequent sequenece of fetch(NEXT) operations will be rather slower. You need to bear in mind the following:

  • The time taken for a select statement is dependent on a combination of the number of rows that need to be examined, and the number of rows that need to be placed in the result set. Limiting the number of rows only improves the second component.
  • If you specify a value for use_rownum grater than 1 then in many cases subsequent fetches on a table can reuse an earlier result set. Such fetches are very fast compared with fetches that need to execute a select statement.

A value of use_rownum between 100 and 1000 will probably give quite good results.

It would be useful if rownum could be used as a simple additional predicate. Unfortunately testing has indicated that this does not work reliably, and that Oracle will not always return rows in the expected order.


use_serializable

[ORACLE]
use_serializable=0

0 means switched off, 1 means switched on.

This switches Oracle's serializable transaction isolation. When on transactions are executed in such a way that they appear to be processed serially, one at a time, rather than concurrently.

(See the Oracle on-line documentation, Oracle 7 Server Concepts for more details.)


Customer specific values

[ORACLE]
multiple_db=0
use_local=0
casewise=2
multi_db_name="PDBASEV6"

These values are reserved for use by Casewise with their modeler product.


[PRELOAD]

This section contains a list of programs that are executed when the DP4 service is started. It is normally used to perform such tasks as automatic DBRECOV, DBCHECK etc. It applies only to the Win32 version of DP4.

The syntax is the same as that of the [startup] section.


[SQL]

There are currently four products that may make use this section.

  • The SQL interpreter uses this section for replacement [trmw] entries in the same way as other DP4 programs

  • Three ADCs that implement the DP4 database as a client of OEM databases.

    • Auxwodbc
    • Auxoracl
    • Auxwsybas

The AUXWODBC ADC (Auxiliary Database Controller) provides seamless access to foreign ODBC compliant Databases. The necessary information for the .INI files can be created by AUXWINST, and is categorised below. Fuller installation details are contained in the SQLODBC help file.

The AUXORACL ADC provides access to Oracle databases, using native Oracle calls rather than the ODBC interface. Further information is contained in the DP4 SQL Products manual.

AUXSYBAS ADC is a similar product to AUXORACL, but for Sybase databases.

Entries in the [SQL] section

The DP4 configuration file should contain one [sql] section with one or more lines, each of which specifies a connection between a DP4 database and an OEM data source. The format of these entries is dependent on which of the above ADCs is used to access that database, and, for AUXWODBC, the type of ODBC source.

For example, an ODBC connection to a Microsoft database using auxwodbc might be specified like this:

DF7=DSN=Sample database;DBQ=MS7;UID=SCOTT;PWD=tiger

Where ;DF7 is the DP4 database name, Sample database is the ODBC data source name, MS7 is the name of the foreign database, SCOTT is the user identity for the database and tiger is the password. The DP4 database and ODBC data source names always appear as in the above example, but other details will vary depending on the ODBC server.

For Oracle and Sybase (using the native Gateway ADCs rather than the ODBC Gateway) the connect string will have the following form:

db=user/password@service

For example: df7=scott/tiger@ora

Associated entries in other general sections:

[STARTUP]

The startup section will include a command to load the appropriate ADC, for example as follows:

[startup]
1=dp4srvr.w32 -aux
2=auxoracl.w32

[DEBUG]

The debug section has an entry to allow debug output from AUXxxxxx to be displayed in the errlog program and/or to be output to a file. The format is as follows:

[debug]
debug_auxsql=n

where n is 0, 1, 2, or 3

This has the usual format for being set to 1 for on and 0 for off. If set to 2 or 3 more detailed diagnostic information is produced.

Note that turning on diagnostics should only be done during problem investigation. These diagnostics may significantly degrade performance.

Each of these ADCs may also make use of the following sections:

  • [sql.config DP4_database_name]
  • [sql.remote DP4_database_name]
  • [sql.xlat DP4_database_name]

The DP4 SQL Engine uses the following section, which may be useful when converting a system to use DP4 rather than a non DP4 database:

  • [sql.xlat2 DP4_database_name]

There are also product specific sections for each ADC:

  • auxwodbc [AUXWODBC]
  • auxoracl [ORACLE]
  • auxsybas [SYBASE]


[SQLLIB]

From release 4.523 The SQLLIB section is used by the DP4 SQL Engine, and therefore also used indirectly by the DP4 ODBC driver.

  • remote
  • table_index
  • table_sort


remote

[SQLLIB]
remote = 0

If set to 1 the SQL Engine passes requests it receives direct to the DP4 System, which must therefore be running as a simple network client. The request is then passed across the network to the DP4 network receiver, which must be the TCPSQLM program rather than the regular TCPMGR. This allows SQL commands to be executed server side, which reduces the network traffic.


table_index

[SQLLIB]
table_index = 2

This value controls the default algorithm used by the DP4 SQL Engine to select the index used for accessing the database. For more information see the Compiler Hints section of the DP4 SQL Manual.


table_sort

[SQLLIB]
table_sort = 2

This value controls the default algorithm used by the DP4 SQL Engine to select the order to access tables in a SQL statement that accesses multiple tables. Specify table_sort=0 to force tables to be accessed in the order specified in the FROM clause. For more information see the Compiler Hints section of the DP4 SQL Manual.


[sql.config DP4_database_name]

This section allows you to configure the ODBC gateway server (AUXWODBC) for specific ODBC connections.

Where DP4_database_name is the DP4 database name, not the OEM database name, should that be different.

It can have the following entries

  • first_occurs ◊
  • role_first
  • role_sep ◊
  • single_query
  • statements
  • timestamps
  • use_long_query ◊
  • use_subquery ◊

Several of the options above (marked with a ◊) are per database versions of values in the AUXOWDBC section. The defaults on a per database level are the actual values of the AUXWODBC variables. This allows you to specify these values separately for each database.

This may be useful if you have several OEM databases created in different ways or with different capabilities. For example if you create an Access database from a DP4 database and the DP4 database contained a field staff_name with a role of manager, the Access database name will contain a field called manager$staff_name. So for this database you would specify role_sep='$' and role_first=1, which will allow you to use the existing DP4 database to access the Access database. Otherwise you would need to use AUXWINST to create a new DP4 database with amended names.


role_first

[sql.config DP4_database_name]
role_first=0

role_first=1 effectively allows reversal of the field name and role order.

This may be useful if you have several SQL databases created in different ways. For example if you create an Access database from a DP4 database and the DP4 database contained a field staff_name with a role of manager, the Access database name will contain a field called manager$staff_name. So for this database you would specify role_sep='$' and role_first=1, which will allow you to use the existing DP4 database to access the Access database. Otherwise you would need to use AUXWINST to create a new DP4 database with amended names.


single_query

[sql.config DP4_database_name]
single_query=0

Some databases, notably Microsoft SQL Server, have very severe restrictions on how different cursors can be used in the same connection.

Set single_query=1 if the SQL database will not allow you to execute a new SELECT cursor while an existing query is still open.

Set single_query=2 if the SQL database will not allow you to execute any SQL statement while a fetch is open. single_query=2 is required for accessing SQL Server databases via AUXWODBC.


statements

[sql.config DP4_database_name]
statements=64

This is the maximum number of statements that AUXWODBC will attempt to open per connection before it begins to close statements to free up some for reuse.

AUXOWDBC will query the ODBC driver for this value, so you should only override this if you encounter problems. This value replaces the max_statements entry implemented for AUXORACL and AUXSYBAS, since if more than one ODBC data source is in use you may need different values for the different sources.


timestamps

[sql.config DP4_database_name]
timestamps=1

This entry is used when you want to combine DP4 date and time fields with the same role into one SQL combined datetime column. To use this you will need to edit your schema file by hand to combine these fields into one column and also make a note of any name translations that will be needed.

You are recommended not to use this option if your database contains any tables or indexes where either, the time part or date part of such a field is a key field and the date part and time part are not both keys with the time key precedence equal to the date precedence + 1


[sql.remote DP4_database_name]

The [sql.remote DP4_database_name] section is used to specify whether tables are to be accessed remotely on the SQL database, or locally on the DP4 database. By default the application data tables are all remote and the base dictionary tables are all local. This can be overridden as follows:

[sql.remote db]
@menu_user=1
customer=0

This [sql.remote <dbname>] section has overrides for the base dictionary @menu_user table to be remote, (on the OEM database), and for the customer table to be local, (on the DP4 database). In order to specify a DP4base dictionary table as remote you will need to create the schema object for this table manually. You will also need a translation table for the table name and all the field names. You should not attempt to store base dictionary tables on the SQL database unless you clear this with Itim Technology Solutions first. Some DP4 applications require correct implementation of the NO_UPDATE and NO_DATA flags, and cannot be held on non DP4 databases as a result.


[sql.xlat <DP4_database_name>]

This section is used by the Gateway ADCS, to translate names on a DP4 database to their equivalent on a non-DP4 database. The format is as follows:

[sql.xlat DP4_database_name]
dp4name=oemname

Where dp4name is a name on the DP4 database and oemname is the name on the OEM database. Normally dp4name will be an SQL reserved word, or oemname a name on the OEM database that cannot be used on a DP4 database. You may be able to use auxwinst to generate this information automatically.


[sql.xlat2

[sql.xlat2 DP4_database_name ]

This section is used by the DP4 SQL Engine to translate table and column names submitted to it into the correct DP4 name. The format is as follows:

[sql.xlat2 DP4_database_name]
oemname=dp4name

Where oemname is a name submitted to the SQL Engine and dp4name is the corresponding name on the DP4 database.

In principle, this section should not be required. Correctly written software would submit correct SQL to the DP4 SQL Engine, using the table and column names the DP4 engine would report to the catalog functions. However it has been known for third party software to make invalid assumptions about table and field names, causing it to submit an incorrect name.

A second, and more valid reason for requiring this section is that you may have a previously written SQL statement for a database which was originally a non DP4 database, but for which you have now created a DP4 database. The DP4 database may have to have changed some of the names from the original database. If this section contains the translation from the original name to the name on the new DP4 database the SQL Engine will accept a statement that uses the original name, thus saving you from having to update it for the DP4 database. In this case the AUXWINST program will probably have created the appropriate entries for you automatically.


STARTUP

This section contains the list of programs started when the DP4 service is started up.

The Win32 loader will accept two different syntaxes in this section. The two different syntaxes cannot be mixed. The old syntax is documented only because you may come across it in an existing DP4 configuration file file. It should no longer be used - the Windows CE loader and the loader for Unix (dbdaemon) only accept the new syntax.

New syntax:

1=[priority][Type]program_name_1 command tails
2=[priority][Type]program_name_2 command tails
3=[priority][Type]program_name_3 command tails
...

Old syntax:

program_name_1=command tails
program_name_2=command tails
program_name_3=command tails
...

In the old syntax, programs were loaded in the order in which their names were found in the file. In the new syntax, the loader looks in turn for the keys '1', '2', '3',... and uses the associated values as the command line to load.

The old syntax cannot handle the same program name twice; the Windows API returns the first set of command tails for the second program.

If no startup section is specified the [startup] section defaults to

1=dp4srvr.w32

or the equivalent command to load the stand-alone database manager on Unix, Windows CE etc.

The server programs such as TCPMGR and AUXDISTR are all service processes, (daemons) that run all the time. When the loader loads these, it must not wait for them to terminate. Instead it waits for them to signal or broadcast a message to indicate that they have completed initialisation. However, if the loader loads an application program such as DBRECOV or DBCHECK, it must wait until it terminates and check the return code before going on to the next program. The loader will stop the loading process if an application program returns a non-zero return code. It may also be required to load a program which does not terminate and does not signal that it has completed initialisation, or one that should not prevent DP4 from loading even if it itself fails to load.

To allow the loader to distinguish these various scenarios, the names of application programs (as distinct from TSRs) must be prefixed by various symbols.

Symbol | Meaning
* | Run to termination and check return code is 0
& | Spawn and do not wait for a return code
! | Wait for completion but ignore return code

If no type is given the program is a DP4 server program and must (on Windows) send a special message to the loader to say it is ready. (On Unix/Linux DP4 server programs are expected to terminate with a 0 exit code after forking to turn themselves into daemons). By default servers have 15 seconds to initialise (set with the startup_delay entry)

The [priority] settings are as follows:

< | Very low
- | Low
. | Normal
+ | High
> | Very high

On Unix and Linux these priorities are all relative to the priority with which dbdaemon is started. "Very High" means the process has the same priority as dbdaemon, each of the other priority levels reduces the priority of the program by increasing its nice value by one point.

Example [PRELOAD] and [STARTUP] sections

[preload]
1=dp4srvr.w32
2=*dbrecov -db dbname
3=*dbcheck -db dbname -check -batch

[startup]
1 = tcpw.w32 -multiple -server 80
2 = dp4srvr.w32 -aux
3 = tcpmgr.w32 -server 80 -aux
4 = auxdistr.w32 -server 80 -use 80

Here is an example startup section for a Windows CE device that is also accessed from one or more PCs:

[startup]
1=.dp4srvr.wce -aux
2=tcpw.wce -server_name localhost -debug_connect
3=.tcpmgr.wce -aux -debug_connect

dp4srvr.wce and tcpmgr.wce are being run with "normal" rather than high priority to prevent the CE device being unresponsive while a PC is accessing it. In some cases it may even be necessary to run tcpmgr.wce with low priority:

3=-tcpmgr.wce -aux -debug_connect

Here is a similar startup section for a Linux or Unix computer

[startup]
1=srv3 -aux
2=tcp3 -server_name localhost -debug_connect
3=tcpmgr -display_address -aux -debug_connect

Alternative [STARTUP] and [PRELOAD] sections

The loader program will look for different section names instead of [startup] and [preload] if it is started with the command tails

-startup startup_section_name

or

-preload preload_section_name

This allows the user to have multiple startup configurations in the DP4 configuration file and to select the one required without editing the file.

If you use autoloading, you can specify the -startup and -preload command tails as part of the value for loader in the [WIN32] section, or as part of the value for loader in the [WINCE] section for Windows CE, or the [UNIX] section for Unix and Linux.


[SYBASE]

This section is used only by the AUXSYBAS program, used to access data from Sybase. AUXSYBAS is not a standard DP4 component. The following entries may be specified in the Sybase section.

  • dbo_name
  • col_order
  • first_occurs
  • max_max_cursors
  • max_statements
  • role_sep
  • schema_name
  • short_sql
  • use_checksum
  • use_long_query
  • use_subquery


dbo_name

[SYBASE]
dbo_name = ””

This is like schema name, but provides an additional level of table hierarchy.


[SYSTEM]

The [system] section has the following entries:

  • autoload
  • load_dfnet
  • load_errlog
  • monitor
  • max_programs
  • shutdowndelay
  • startup, preload


autoload

[system]
autoload=1

This entry controls whether the DP4 service/database manager is started/loaded automatically when an application that uses it runs. Autoload is enabled by default (autoload=1). To disable it set autoload=0.

Win32 Version

With the Win32 version of DP4 applications can autoload DP4 in a fully configurable way. The autoload differs from that provided in other operating systems in the following ways:

  1. DP4 does not auto unload on termination (unless configured to do so).

  2. The full configuration for the machine is autoloaded, not just the standalone database manager.

The autoload runs srvw32 -start by default. You can configure the command to be run by setting loader=Command in the [win32] section.

Win16 version

Prior to 4.520/4.616 release the 16-bit version of DP4 would not autoload unless pre500=0 is set in the [WINDOWS] section. The program loaded by autoload is set using loader=Command in the [windows] section.


load_dfnet

[system]
load_dfnet=0

Do NOT change or remove this value unless you are instructed to do so by Itim Technology Solutions.


load_errlog

[system]
load_errlog=0

If 1, the ERRLOG program is loaded.


max_programs

[system]
max_programs=128

From release 4.621 determines the maximum number of programs using DP4 IPC that can be run simultaneously on the local machine. ADCs and the Network Manager are included in the total, and also the database manager if the -distributed option is in use. Also one handle is reserved for internal use.

There can be little reason to increase this value except on machines running Citrix or Terminal Services clients with a full 2 Gigabytes of RAM. Reducing the number to a smaller but reasonable value such as 32 will save a small amount of memory for each DP4 process.

This number has no bearing on the number of users that can connect to the database manager via the DP4 networking.

From release 4.525 this setting is also used on Unix/Linux platforms, but in a slightly different way: setting this to a low value will not prevent you running more programs, but will reduce the size of the cache DP4 internally uses for remembering information used for IPC between applications and DP4. Generally you should set this value to the largest number of DP4 programs you want to run simultaneously as on Windows. The amount of memory saved by specifying a low value is minuscule - only eight bytes per server per program (i.e. specifying 64 instead of 128 will save 64*8 bytes in each of srv3, tcp3, and any ADC loaded)


monitor

[system]
monitor=0

This setting is introduced for 4.623. It can also be used on 4.621 installations using 4.621a provided srvw32.exe and syslibt.dll are upgraded to the files included with 4.623. This can be done by applying the 4.621b zip file available from the DP4 FTP site.

If set to a non zero-value n, then every n seconds, srvw32.exe checks the status of the DP4 IPC channels and displays diagnostics in ERRLOG. If srvw32.exe finds that a channel has been assigned to a process that terminated without calling the required cleanup functions it clears the channel and prints a diagnostic including the offending processes process ID.

This setting has been added to assist with diagnosing problems caused by processes that do not terminate cleanly.

When this value is set, the load_errlog setting defaults to 1, and not to 0. However, if load_errlog=0 is set explicitly then the monitor function will still clean up after terminated processes.


shutdowndelay

[system]
shutdowndelay=5

If the DP4 database manager is shut down while applications are running, this specifies the delay in seconds before the shutdown actually takes place. You can arrange for terminal manager applications to respond to the shutdown messages broadcast by DP4 by setting dfshutdown in their named program section or in the [TRMW] section.


startup, preload

[system]
startup=startup
preload=preload

These set the default names of the [startup] and [PRELOAD] sections. You can change the values here as an alternative to using the -startup and -preload command tails on SRVW32. This might be useful if you want to issue a DP4.INI containing startup/preload sections for multiple configurations and want to be able to choose which sections are used with the minimum of fuss.


[tcpmgr]

The [tcpmgr] section can contain the usual [progname] section entries for controlling the appearance and screen position etc, and has the following entries:

  • onconnect
  • keep_awake


keep_awake

[TCPW],[TCPMGR],[progname]
keep_awake=1

Applies on Windows CE devices from release 4.621

Windows CE devices are typically configured to go into suspend mode automatically, after only a few minutes of user inactivity. This may be inappropriate if the device is running background processes that are communicating with another computer over a network. From release 4.621 DP4 can prevent Windows CE devices suspending while DP4 network activity is taking place. Note that this new functionality is enabled by default, but there are situations where it may be preferable to disable it.

DP4 prevents devices suspending automatically by resetting to zero the timer that measures the time since the last user activity, whenever certain types of network activity take place. DP4 does not prevent user-initiated suspends (for example the user presses an Off button), and only prevents automatic suspends while it detects significant network activity from DP4 programs.

There are currently three places where keep_awake can be specified:

  • [TCPW]

    Unless you specify keep_awake=0 in the [TCPW] section, then, whenever a DP4 program calls the database manager across the network, the inactivity timer is reset. If DP4 is loaded in the named connection configuration calls passed to tcpw.wce but destined for the local machine are ignored. However, in a multiple resilience configuration, calls destined for the local machine do also reset the timer.

  • [TCPMGR]

    Unless you specify keep_awake=0 in the [TCPMGR] section, then the inactivity timer is reset whenever TCPMGR receives a message other than a network "keepalive".

    If your application includes some kind of polling software that connects to each client machine in turn to look for new transactions, then you may find that the default keep_awake=1 setting prevents your CE devices from suspending. In this case you must either disable the keep_awake setting for [TCPMGR], or modify your polling software so that the delay between succesive polls of CE devices is long enough for them to be allowed to suspend when there is no activity. The latter solution is preferable as it will enable [TCPMGR] to stay awake when more significant network activity is taking place.

  • [progname]

    The keep_awake setting also applies to programs run using the DP4 thin client.

    Unless you specify keep_awake=0 in the [progname] section for an application, then calls received by the DP4 thin client on behalf of that application will reset the inactivity timeout. Please note the following important points about this use of the keep_awake setting:

    • This setting must be specified in the DP4 configuration file on the application server and not on the client Windows CE device.
    • An application will not be able to keep a CE device awake when it is awaiting a response from the user. If the application is waiting for a response, but the user does not provide one in time to prevent the inactivity timer from suspending the machine, then Windows CE will suspend the device. This will cause the network connection to break, and the application to terminate. For this reason it is a good idea to build logic into your application that will allow it to remember its state and resume later on.
    • The keep_awake setting for applications is not a true [TRMW] type setting. It can only be specified in a named program section, and can only be specified at the executable file level - for example you cannot specify this setting for individual QAB programs.


OnConnect

[TCPMGR]
onconnect=

Processed when TCPMGR is loaded with the -reverse command tail, and a machine establishes a new session with TCPMGR.

The value specified should be a command line for TCPMGR to execute (locally). TCPMGR appends the IP address of the incoming connection to the command line and executes the specified commmand.


[TRMW]

The [TRMW] section of the DP4 configuration file contains a large number of possible entries which can be used to configure the behaviour of the DP4 terminal manager. Unless otherwise noted, any entry for the TRMW] section may also be specified in a program specific section. For example you could force a program called MYPROG.EXE to use special values for entries in the [TRMW] section by supplying corresponding entries in the [MYPROG] section. Such entries always take precedence over values specified in the [TRMW] section itself.

Some entries in the [TRMW] section are read when an application starts, and cannot be changed afterwards. Others may be changed by calling the trm_set_progname() function, which can be used to over-ride the section used for accessing the [TRMW] entries. When a QAB program is first loaded it always calls this function, and sets the program name to the name of the QAB program. When trm_set_progname() is called the terminal manager rereads these variables, and may change the appearance, size or position of the application window as a result. Other variables are only read when they are needed and so always use the current program name. Entries marked below with an asterisk (*) are those which are either reread when QAB programs are loaded or when a C application calls the trm_set_progname() function, or which are only read as required and hence automatically use the current program name.

Many entries in the [TRMW] section are also used by the DFPRINT program. However in this case the values can, from 4.621, be overridden in the [DFPRINT] section as well as on a per-application basis.

Entries:

3DBorderSize
3DBorderStyle
buttoncheckboxes
*buttonframe
ButtonHeight
buttonstyle
*button_text_centred
charset
checkbox_height
checkbox_width
Colours
cols
defer_bug
*depth
*detach
dfprint_clip
dfprint_x_factor
dfprint_x_inch
dfprint_y_factor
dfprint_y_inch
DFPRINTForeground
dfshutdown
disablestyle
fh
*first_day
flatten_dialog
font
forcefont
HelpBorderSize
*hide_dead_chrome
*hide_empty_buttons
*idletime
isometric
keep_awake
*limitsize
*no_auto_close
*no_scroll_bars
*OkEndSession
*OldDP4Numbers
*pagedepth_bug
*pagesetup
*pause
*pointer_help
pointsize
prompt_width
*prtscr_editframe
*refresh_interval
rows
run_once
run_once_question
run_once_title
*save_position
*screendumpstyle
*screenprint
*setcommstate
shadow_title
SharePrinter
*show_im
smooth
StdButtonsWanted
*stdtitles
string_nn
*Title
*touch_calendar
*use_workarea
use600
useframe
usenonclient
*usestatus
*usestdfonts
*use_viewer
vertical_gradient
*viewer
weight
*width
winime
winprinfont
*winprint
wrapbug
*x
x_factor
x_inch
*y
y_factor
y_inch

From 4.621 there are some additional entries that can be used as part of the skinning facilities. See Configuration file entries for bitmaps for details.

Device Names

From Release 4.621(8) you can map the device names used for printing directly (i.e. not via DFPRINT) to other ports. For example if a program needs to print to a bluetooth device on a virtual COM port such as COM5, then create a print device for it using a device that you do not need, LPT3 perhaps, and add LPT3=COM5: to DP4.INI, either in the [trmw] section (if you are absolutely certain this will not cause problems for DP4 programs printing to another device), or in a [progname] section. This avoids the need for using the MODE command to redirect an LPT device to a COM port.

On Windows CE you must include the trailing : on the device name: DP4 will not add it for you, and the device will not be opened correctly without it.


3DBorderSize

[TRMW]
3DBorderSize=3

normally specified in [TRMW]only.

The number of pixels to allow for Windows 95 style 3D borders. See also 3DBorderStyle.

If you have maps that were designed using pre 4.612 versions of DP4, specifying 3dBorderSize=6 will restore maps to their original size.


3DBorderStyle

[TRMW]
3DBorderStyle=0 or 1

normally specified in [TRMW] only.

If 0 (default on Windows 3.1 and NT 3.5x) the border style used for maps with a 3D border is the same as the style normally used for DP4 help messages.

If 1 (default on Windows 95 and NT 4) 3D style maps are drawn with the Windows 95 look.


buttonframe

[TRMW]
buttonframe=1

normally specified in [TRMW] only. Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

The width of the border drawn round buttons that have focus or are currently 'Default' buttons. Some systems set this to 2 to provide a stronger visual indication of the currently active button.


buttoncheckboxes

[TRMW]
buttoncheckboxes=1

normally specified in [TRMW] only.

From 4.617 checkboxes that do not have any text associated with them are drawn to look like buttons rather than ordinary checkboxes. This is done so that there is a visible indication when they have focus. Specifying buttoncheckboxes=0 disables this behaviour.


ButtonHeight

[TRMW]
ButtonHeight=Calculated value

used in 4.51x programs only.

This value sets the size to be used for buttons. The default is 7/4 of the normal font height.


buttonstyle

[TRMW]
buttonstyle=0 or 1

Normally specified in [TRMW] only. This entry was introduced in the 4.613 release.

If 0 (default on Windows 3.1 and NT 3.5x) the border style used for buttons and VCR buttons is the same as is used by Windows 3.1.

If 1 (default on Windows 95 and NT 4) the border style used for buttons and VCR buttons is the same as is used by Windows 95.

If 2 (supported from 4.621) buttons are drawn using bitmaps called buttonup.bmp, buttondown.bmp, buttonactive.bmp, and buttondefault.bmp, stored in the dp4.sys directory. See Skinning DP4 for more information. (If none of these bitmaps is present the buttons are drawn as though buttonstyle 1 was in effect. If buttonup.bmp is present, but some other bitmaps are missing you will get a mess.)

From 4.622 four new values, 3 through 6 are available. With these values the appearance of a button will depend on whether or not there is an XP theme active or not, and possibly on the colour scheme of the button. The following table shows how the values are used.

Value | Button uses Default Colour Scheme | Windows XP Theme in effect | Appearance
3 | Yes | Yes | Windows XP Themed Button
3 | No | N/A | Windows 95 style button
3 | N/A | No | Windows 95 style button
4 | Yes | Yes | Windows XP Themed Button
4 | No | N/A | DP4 Custom button
4 | N/A | No | DP4 Custom button
5 | N/A | Yes | Windows XP Themed Button
5 | N/A | No | Windows 95 style button
6 | N/A | Yes | Windows XP Themed Button
6 | N/A | No | DP4 Custom button


button_text_centred

[TRMW]
button_text_centred=0

normally specified in [TRMW] only.

From 4.622 you can use this setting to completely over-ride the alignment flags set for buttons. This option is intended for use by a specific customer and is unlikely to be useful generally.


charset

[TRMW]
charset=0

Selects the character set to be used for the default font.

0 | selects the ANSI character set
1 | selects a font based on font name without regard to character set
128 | selects the shift JIS character set
255 | selects the OEM (MS-DOS) character set

Other values are possible for this entry. Look in the Windows header file wingdi.h for other possible values, or consult Microsoft documentation.


checkbox_height

[TRMW]
checkbox_height=calculated number

checkbox_height=n controls the height of the box part of a checkbox control or radio button. Normally these are drawn at a fixed size determined by Windows, no matter what the size of the text of the control. Setting this option allows this size to be over-ridden.

This may be useful on touch screens, for which the default checkbox size is inconveniently small. This setting was introduced into 4.623 in builds dated on or after 7 March 2007.


checkbox_width

[TRMW]
checkbox_width=calculated number

checkbox_width=n controls the height of the box part of a checkbox control or radio button. Normally these are drawn at a fixed size determined by Windows, no matter what the size of the text of the control. Setting this option allows this size to be over-ridden.

This may be useful on touch screens, for which the default checkbox size is inconveniently small. This setting was introduced into 4.623 in builds dated on or after 7 March 2007.


Colours

[TRMW]; a set of obsolete values, applying only when the 4.5xx terminal manager is in use.

In 4.5xx you can set the exact shade to be used for the various screen colours by specifying a value for one of the following entries.

Black | Blue | Green | Cyan
Red | Magenta | Brown | Lgrey
Dkgrey | Lblue | Lgreen | Lcyan
Lred | Lmgnta | Yellow | White

Entries are specified as RGB values like this:

Yellow=(255,255,0)


cols

[TRMW]
cols=user.scrn_width

applies when 4.5xx, or 4.616 and later terminal managers are in use.

This sets the screen width for the program. The default value is the screen width stored in userdata.sys, which is usually 80.In 4.5xx if the program window is reduced to have a width below character_width*cols a scroll bar is displayed.

This default value for this entry was documented incorrectly in previous versions of this manual.

It is normal to set this to 80.

See the width and default window size pages for more information.


defer_bug

[TRMW]
defer_bug=1

normally specified in [TRMW] only.

This setting, added in a patch to releases 4.621 and 4.622, controls how trmw32.dll uses of the Windows API DeferWindowPos(). In some circumstances this API fails and causes a leak, which can cause TRMW32.DLL to suffer from resource starvation and eventually crash.(It is not known exactly what triggers this failure in the API - it seems to be very sensitive to the recent history of how Windows have been created and updated on screen, and apparently similar maps can give rise to different results)

There are three possible settings:

  • If defer_bug=0 is set, DP4 expects DeferWindowPos() to work as documented. If a call to DeferWindowPos() fails DP4 does not call EndDeferWindowPos(). This is how Microsoft say you should use handle a failure from DeferWindowPos(), but on Windows XP and 2000, this causes a leak. This setting might be needed on a hypothetical future release of Windows where this bug has been fixed.

  • If defer_bug=1 is set, DP4 attempts to work around the bug in DeferWindowPos() by always calling EndDeferWindowPos() whether DeferWindowPos() succeeds or not. When DeferWindowPos() fails, the last good handle returned by DeferWindowPos() is passed to EndDeferWindowPos(). MSDN documentation states that this is the wrong thing to do, but it stops the leak from happening and does not have any known adverse consequences.

  • If defer_bug=2 is set, DP4 does not use DeferWindowPos() to change the Z-order of windows. Instead it always uses SetWindowPos(). You can use this setting if you find that you are suffering from the leak, and the work-around added does not fix the leak, or has other adverse consequences. Using this setting might cause the screen display to flicker more than when DeferWindowPos() is used.


depth

[TRMW]
depth=calculated value

Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

depth is the depth of the client area of the main program window. If this is not specified then the value is defaulted in one of two ways:

  • If use_workarea=1 (available from 4.620) then the client area depth matches that of a maximised window.
  • Prior to 4.620 or if use_workarea=0 the default depth is calculated as rows * y_factor.

This value is updated when a program terminates. To prevent updating make the DP4 configuration file read only or set save_position=0.

See the cols, y_factor, and default window size pages for more information.


detach

[TRMW]
detach=0

If set to 1, the program is created with a minimised window. It is normally specified in named program sections only.

Windows cannot be minimised on Windows CE. Prior to 4.622 this option is not supported on Windows CE. From 4.622 if a program is run with this option set the program is initially started so that it is invisible but has an icon and a context menu in the taskbar notification area. The menu allows you either to convert the program to running in the foreground or to exit the program.


dfshutdown

[TRMW]
dfshutdown=0

This entry is implemented in 4.5xx, and from 4.617.

If 1 the terminal manager will listen out for the special message which is broadcast when the DP4 service is stopped. When the terminal manager receives this message it will attempt to terminate the program.

If 0 the message is not picked up. Normally the applications will fail when they next try to access the database manager.


dfprint_clip

[TRMW]
dfprint_clip=0

Normally DFPRINT allows the text printed in controls to overflow the boundaries of the containing control. This prevents text from being truncated and therefore from possibly being misleading. However it can cause the appearance of output to be untidy.

From release 4.623, you can force DFPRINT to clip text to the boundary of controls by specifying dfprint_clip=1.

This is a regular [trmw] section setting, and may be set in a [progname] section for application that require special handling.


dfprint_x_factor, dfprint_y_factor, dfprint_x_inch, dfprint_y_inch

[TRMW]
dfprint_x_factor=calculated number
dfprint_y_factor=calculated number
dfprint_x_inch=72
dfprint_y_inch=72

From release 4.620, when an application is printing using the DFPRINT program the x_factor, y_factor, x_inch and y_inch settings are ignored. This is to avoid problems that otherwise occur during printing when an application must run on a variety of different screen resolutions. For printing these settings replace the settings used outside DFPRINT.

These are regular [trmw] section settings, and may be set in a [progname] section for applications that require special handling. Do not set them in a [DFPRINT] section


DFPRINTForeground

[TRMW]
DFPRINTForeground=0

Must be specified in this section, and not a DFPRINT section.

If set to 1 the DFPRINT program will force itself to be the foregound window and take focus if it requires user input. This option has been added because users sometimes press the Enter key too many times after requesting printing. This can case an apparent hang when the terminal manager is waiting for DFPRINT to finish, but DFPRINT is waiting for user input but is stuck behind the application. Naive users may not realise what has happened.


disablestyle

[TRMW]
disablestyle=0 or 1

Normally specified in [TRMW] only. This entry was introduced in the 4.613 release.

If 0 (default on Windows 3.1 and NT 3.5x) disabled text in checkboxes buttons and text controls is drawn in the "greyed-out" text colour, as used by Windows 3.1.

If 1 (default on Windows 95 and NT 4) disabled text in checkboxes buttons and text controls is drawn with an embossed (3D) effect using 3D border colours in the same way as Windows 95.


fh

[TRMW]
fh=0

Height of default font. If 0 is specified, Windows will select a value, but this may cause problems when printing. See default font for more information.


first_day

[TRMW]
first_day=1

first_day=n where n is a value between 0 and 6 sets the day of the week that is shown at the left of a DP4 calendar control (introduced into 4.623 versions of trmw32.dll and trmwce.dll built on or after 7th November 2007). The default value of 1 shows Monday. 0 shows Sunday at the left, and 6 shows Saturday. Oher values are also permitted.


flatten_dialog

[TRMW]
flatten_dialog=0

This setting was introduced in 4.621, but has changed considerably in 4.622.

4.621

If 1, maps that have a 3D border and a title bar are shown with a flattened border similar to the border used in Windows XP.

If 0 (maps with a 3D border and title bar are shown with a 3D effect.

4.622

  • If 0 (maps with a 3D border and title bar are shown with a 3D effect, as "normal".

  • If 1, maps that have a 3D border and a title bar are shown with an XP window border, and the borders of 3D edit controls are also changed to match those of XP, but only if a Windows XP theme is in effect.

  • If 2, maps that have a 3D border and a title bar are shown with an XP window border if there is an XP theme, or a fat flattened border (reminiscent of Windows 3.x) otherwise. The borders of 3D edit controls are also changed to match those of XP, if there is a Windows XP theme is in effect, or are flattened anyway otherwise.

You should note, that when there is an XP theme and flatten_dialog is non zero, you cannot be sure of the exact appearance of the map. For example there are various shareware programs available that provide new themes beyond the MS supplied themes.


fw

[TRMW]
fw=0

Width of default font.

If 0 Windows will select a value based on the value of fh. See default font for more information.


font

[TRMW]
font="System"

Default font to use where userdata type F is selected or forcefont is 1.


forcefont

[TRMW]
forcefont=0

Normally specified in individual program sections only.

It is possible to force a particular default font on a per application basis. This is done by setting forcefont=1 in the [progname] section of the DP4 configuration file. (If you set forcefont=1 in the [trmw] section it has the effect of completely overriding the USERDATA.SYS font setting). You can also force one of the built in fonts. For example forcefont=13 forces the system font. (The values to use for built in fonts are taken from the numeric values of the appropriate constants for GetStockObject()). If you override the default font then you will need to specify values for these entries: font, pointsize or fh, and may want to specfy values for weight, charset, and fw.

See Default font for more information.


HelpBorderSize

[TRMW]
HelpBorderSize=6

The number of pixels to allow for the border style used for help messages. The minimum value allowed is 5.


hide_dead_chrome

[TRMW]
hide_dead_chrome=0

hide_dead_chrome=1 changes the behaviour of "prompt", "spinner", and "calendar" VCRs added to edit controls when the map containing them is "glued" to another map (usually when a list of records is displayed in a window or popup). It was introduced into 4.623 versions of trmw32.dll and trmwce.dll built on or after 21st May 2008). When this setting is enabled VCRs are hidden when a map is glued to another map. They will reappear if the map is subsequently used for editing.

This setting is intended to make using the same map for both editing and displaying a line of data work slightly better, and may be convenient for QAB developers. However, this is only a partial solution: you will not be able to put a frame around such edit controls (because if you do the appearance will still be odd), and the map used for editing won't have OK and Cancel buttons. Also, typically the prompt buttons will only be usable when inserting a new line of data (because they most likely are used by keyfields), so the user may be confused when editing an existing line. On the whole it is better to use separate maps for displaying a line of data in a popup and for editing the data when the line is selected.


hide_empty_buttons

[TRMW]
hide_empty_buttons=0

normally specified in [TRMW] only.

If this option, introduced in 4.623, is set to 1, then if a button has neither a picture nor any text, then it is not drawn at all. Note that the user could in theory still click on the button, so you will normally want to ensure such buttons are also disabled. This option is intended for use by a specific customer and is unlikely to be useful generally, but may be useful where you have screens containing many buttons, which you change dynamically using show() functions.


idletime

[TRMW]
idletime=0

Applies when the 4.51x, or 4.616 and later terminal managers are in use. Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

Setting a non-zero value for this allows you to slow down DP4 programs which are intended to run as background tasks.

An alternative is to start the program in the [startup] section with a priority setting, or to use the NICE program, which we can supply, to start the program later on with a priority setting.

The idletime specifies a minimum delay in milliseconds between calls to the trm_lookchr() function (nextchar() in QAB). Programs which call this function twice, within this interval, are delayed by the appropriate number of milliseconds.

For further information on priority setting see the STARTUP section.


isometric

[TRMW]
isometric=0

If isometric=1 is set in the DP4 configuration file then the terminal manager adjusts x_factor and y_factor so that a rectangle that has an equal width and depth in internal units appears as a square on screen.

It does this by increasing one or other of x_factor and y_factor as required. If x_factor is increased controls will appear slightly larger horizontally, if y_factor is increased they will be larger vertically. Font sizes are unchanged. The default for isometric (its value if it is missing from the DP4 configuration file), is 0, however it is set to 1 in the issued the DP4 configuration file. The value of isometric will only have an effect if your default font is NOT twice as high as it is wide. Note that the System font (at least on US Windows) IS isometric anyway. Setting isometric=1 when you use another font (such as MS Sans Serif) as the default font may change the size of maps on screen. Doing so will ensure the aspect ratio of printed maps is the same as displayed maps, though this will only be necessary if there is significant difference in how Windows realises the font when printing from on screen.

From 4.616 you can specify values for x_factor and y_factor in the DP4 configuration file. The only time you would be likely to need to do this is if you wanted to use a default font that was slightly smaller than your desired x_factor and y_factor. For example if you design an application to run full screen at 640*480 you can ensure it will also run full screen at 800*600 resolution, whether the user chooses "Large" or "Small" fonts by specifying x_factor=10,y_factor=20.

See Coordinate system for more information.


limitsize

[TRMW]
limitsize=0

Normally specified in named program sections for those programs which do not require a maximised screen, such as PROGMAKE, DP4ED. Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If 1, the program window cannot be increased in width beyond the value which makes the client area width user.scrn_width*character_width. See description of width for information on how character_width is calculated.


no_scroll_bars

[TRMW]
no_scroll_bars=0

If no_scroll_bars is 1, the terminal manager will not add scroll bars to the main window if a map is wholly or partially outside the visible area of the window. The user will not be able to access the map unless they can pick it up and drag it to a visible part of the window. I

If no_scroll_bars is 0, the terminal manager will add scroll bars to the main window if any part of a map is outside the visible area of the main window. The user can use the scroll bars to change that part of the window that is visible to bring the map into view.

This option is provided for DP4 users who want to prevent scroll bars appearing because just a small and possibly unimportant part of a amp is outside the window. It also prevents users from doing things like moving one map out to the right, scrolling the map back into view, and then moving the map again.


no_auto_close

[wince] , [trmw]
no_auto_close=0

This setting is provided as a work-around for one of Windows CE's more delightful features (at least in its Pocket PC incarnation). When you click the X button on a program it is not actually closed, only minimised. As a result memory can be exhausted quite quickly. When it is, instead of asking what you want to do, Windows CE starts closing applications which it thinks you are not using. Unless you set this option Windows CE may well decide to close SRVWCE, which will result in DP4 closing down altogether.

If no_auto_close is 1 in the [wince] section, then SRVWCE will attempt to resist close commands that do not seem to come from the user. If is a good idea to use this setting in the [wince] section.

The setting can also be used as a [trmw] setting. In this case it should only be enabled for specific programs, not used in the [trmw] section itself, and you will need to provide some means, such as an "Exit" option, for the program to be closed down gracefully by the user

In both cases when no_auto_close is set the user will not be able to close the program cleanly via the Settings,System,Memory,Running Programs, Stop route. If they try to stop a program that has the no_auto_close setting turned on then they will get a "not responding" message from Windows. If the user then chooses to terminate the program it will be terminated in a way that prevents it from tidying up. In particular any databases and DP4 connections opened will be left open.


OkEndSession

[TRMW]
OkEndSession=0

Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

By default DP4 Windows programs will not allow Windows to be shut down when they are running. Set this value to 1 to allow Windows to be closed down when DP4 programs are running. If you do this in the [TRMW] section you should set OkEndSession=0 entries for critical programs such as REORGDB.


OldDP4Numbers

[TRMW]
OldDP4Numbers=0

Normally specified in [TRMW] only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If 1, numbers which need more characters than have been allowed for by a control are displayed as '?????'. The default procedure in this situation is to convert the number normally and allow Windows to 'clip' the displayed value to fit in the window.


pagedepth_bug

[TRMW]
pagedepth_bug=1

Introduced in 4.624 patch release 7 on 18 Nov 2011. When printing via DFPRINT the DP4 terminal manager computes the approximate number of lines that can be printed on a page (pagedepth), and the average number of characters that can be printed on one line (pagewidth). Unfortunately these computations are wrong if the various settings such as y_factor,y_inch or their x_ equivalents, or the corresponding dfprint_x_ or dfprint_y_ settings have been used. In the past the terminal manager has made its computation using the ordinary settings and not, as it should do, the dfprint_ settings instead. In order to have these values computed correctly DP4 users must install the appropriate patch release of DP4, and they must also add the setting pagedepth_bug=0 in the [trmw] section of dp4.ini. This setting has been introduced because existing systems may well rely on the old, buggy, computation.


pagesetup

[TRMW]
pagesetup=0

Introduced in 4.616. When a program selects to print to DFPRINT then a page set up dialog is displayed. In the 16 bit version this will only allow the user to select orientation and printer to be used. In the 32 bit version it also allows margins to be set. You can disable this dialog by setting pagesetup=0 in the [progname] or [trmw] sections of the DP4 configuration file. The print orientation will default to Landscape if only print to screen is selected, and Portrait otherwise.

See also Printing.


pause

[TRMW]
pause=1

Most batch programs such as MAPPOST, LIBMAKE display a message box and wait for it to be acknowledged on termination. To run these programs from a batch file you can turn off this message box by specifying pause=0 in the relevant program's section, or, from version 4.620,with -pause=0 on the command line for the program.


pointsize

[TRMW]
pointsize=0

You can select a custom default font by specifying a font name and size in the DP4 configuration file (in the [trmw] or [progname] sections. The fontname is specified with a string such as font="MS Sans Serif". In previous releases the size of the font had to be specified by specifying the font height (and optionally width) in pixels (fh=16 for example). From release 4.616 you can specify a point size instead (pointsize=10). This is slightly more portable in theory, in that the font size should be constant whatever the resolution of the screen. In practice point sizes on screen are unreliable as changing the resolution does not normally change the reported number of pixels per inch on which a point size calculation has to be based. However it will give you a way of specifying a font in a way consistent with other applications. If pointsize is specified fh and fw settings are ignored.

See Default font and Printing for more information.


pointer_help

[TRMW]
pointer_help=1

Applies to 4.6xx version of DP4 only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If 1 and help message display is turned on, the terminal manager will display the help message for the control containing the mouse pointer when the mouse is moved (within the current map).

If 0, any help message displayed is always for the control with input focus.


prompt_width

[TRMW]
prompt_width=calculated number

From 4.624 you can specify the width, in pixels, to be used for the control that appears within an edit control that has "prompt","calendar" or "spinner" . The default value is 2*x_factor. A larger value may be required if the control is shown on a touch screen.

Note that the size of the prompt control consumes space from the parent control rather than adding to its size. Therefore if you want to set a larger value for this setting you may need to edit some maps to ensure enough room remains for the data for the control.


prtscr_editframe

[TRMW]
prtscr_editframe=0

Applies to 4.6xx version of DP4 only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

Determines whether or not the SCREEN.PRN file attempts to insert characters to represent the frames round edit controls. Setting the value to 0 (no frames) may make the SCREEN.PRN file more readable.

This value is not used when you have screendumpstyle=2.


refresh_interval

[TRMW]
refresh_interval=0

Applies when the 4.621 and later terminal managers are in use. Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

Setting a non-zero value for this allows you to reduce the frequency at which programs such as DBCHECK and REORGDB update the screen.

The refresh_interval specifies a minimum delay in milliseconds between calls to the trm_refresh() function (nextchar() in QAB). Calls to trm_refresh() are ignored if the function was last called within the specified time limit. Using this option may speed up these programs by removing unnecessary screen output. A value of 50 or 100 still allows the screen to be updated frequently and can save quite a lot of time.


rows

[TRMW]
rows=Calculated value

Applies when the 4.5xx, or 4.616 and later terminal managers are in use.

This sets the default screen depth for the program. The default value is the depth of a maximised window divided by the font height, or from 4.616 the minimum of this value and 28. In 4.5xx if the program window is reduced below this depth a scroll bar is displayed. It sets the maxium number of "lines" on which 4.5xx maps will display without scrolling.

It is normal to set this to 27 or 28. It should not be increased beyond 28 for 4.5xx programs , or, in 4.6xx, for these standard DP4 utilities: DP4ED,TABLEPLN, PROGMAKE.

See the depth and default window size pages for more information.


run_once

[TRMW]
run_once=0

Normally specified in individual program sections only.

From 4.620 it is possible to arrange that only one instance of particular DP4 executables should be allowed to run at a time. This facility is most likely to be useful on Pocket PC 2002, where clicking on the "close" button of an application does not actually close it but only minimises it. Restoring an application is not easy for the user on Pocket PC, and many applications automatically restore a previous instance and exit when the user tries to run a second instance. DP4 tests for a previous instance of the application by making the main window class for an application the full pathname of the application. When an application starts the DP4 terminal manager looks for an existing window of the same class. This setting is available on all Win32 platforms, not just Windows CE.

The run_once setting has three possible values:

  • run_once=0 This allows multiple instances to run without warning the user.

  • run_once=1 A second instance tries to set the first instance into the foreground and then exits. Making another application the foreground application is not always possible on all versions of Windows. In case of difficulty use the "fixsf" application available from the Itim DP4 web site.

  • run_once=2 A second instance brings up a message box dialog asking the user if he wants to start a new instance. If the user answers No, the first instance is set to the foreground in the same way as for run_once=1, otherwise the second instance runs normally. The title and text of the dialog can be customised using run_once_question and run_once_title


run_once_question

[TRMW]
run_once_question="Are you sure you want to run another instance of this program?"

This setting specifies the text that used for the question that appears in the dialog used when run_once=2 is set.


run_once_title

[TRMW]
run_once_title="%s: Program Already Running"

This setting specifies the text that appears in the title bar of the dialog used when run_once=2 is set. If the string contains %s, %s is replaced by the full name of the executable including the path.


save_position

[TRMW]
save_position=1

Processed when C or QAB programs terminate, or when a C application calls the trm_set_progname() function.

When DP4 programs terminate or the name of the program is changed the current position of the program on screen is usually saved, so that when the program is run again it uses the last position. Occasionally, especially where the Window style of the program as created by the DP4 Terminal manager has been modified from C or C++, this does not work properly, and it is desirable to set a fixed position from the program. You can prevent DP4 from saving the current position of the Windows for a program by adding the line save_position=0 to a [progname] section of the DP4 configuration file.

This option should not normally be specified in the [trmw] section itself unles you want to force the initial position for all DP4 applications.


screendumpstyle

[TRMW]
screendumpstyle=1

Applies to 4.6xx version of DP4 only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

This setting affects the format of the SCREEN.PRN file produced when the 'Dmp' key is pressed.

  • If 0 the output is formatted as though the application window is sized for user.scrn_depth*user.scrn_width rows and columns of text in the default font.

  • If 1 the output is formatted using the current size of the application window.

  • If 2 (supported from 4.618) an HTML 4 Web page is created which is as similar as possible to the actual application Window. The HTML created uses CSS2 positioning and currently is only displayed correctly by Microsoft Internet Explorer 5 or later, and, from version 4.621, by Gecko browsers (Netscape 7 and Mozilla for example). Prior to release 4.621 a separate .css file is created as well as the HTML file.


screenprint

[TRMW]
screenprint=""

Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If a value is specified for this entry, it is assumed to be a command line to be invoked after the trm_screen_dump() function is called. Some systems make use of this feature to provide facilities such as a screen print to a print device supported via an OSDI rather than the Windows Screen Print facility.


setcommstate

[TRMW]
setcommstate= 0 or 1

normally specified in [TRMW] only.

The default is 1 on Windows 9x/Me, and 0 on other versions. This value enables a workaround for a bug in Windows 95. This bug also affects the 16 bit version of DP4, but unfortunately the same work around is not available.

The bug is as follows:

When DP4 prints to a printer that uses COM1 or COM2 it does not configure the port baud rate etc but assumes that this has been set up by running the mode command or some equivalent. This works perfectly well on Windows 3.x and Windows NT, but not on Windows 95. (It is documented as a valid technique by Microsoft so this is a bug in the Windows 95 OS).

The work around we have added is that if the value of SetCommState in the [trmw] section of the DP4 configuration file is 1 then trmw32.dll will initialise the port according to the values contained in the appropriate entry in the [ports] section of win.ini. The value of these entries can be configured using Control Panel.(Right click on My computer, select Properties, the Device Manager Tab,Open the Ports entry,double click on the port you want to configure and click on the Port Settings tab). SetCommState defaults to 1 on Windows 9x and 0 on other versions of Windows so there should not normally be any need to set it explicity. It would be preferable to use an appropriate entry from the registry to configure the serial port. However there does not appear to be a documented way of accessing the port information (it is stored in a different way in Windows NT from Windows 9x).


SharePrinter

[trmw]
SharePrinter=1

This can be used to force PRN: and similar ports to be opened in shared mode. This is a workaround for a system converted from MS-DOS.


shadow_title

[TRMW]
shadow_title=0

If 1, the text in an active title is shown with a drop shadow effect.

If 0,the text in an active title is drawn normally.


show_im

[TRMW]
show_im=1

Introduced in v 4.620; relevant to Windows CE (Pocket PC versions) only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If 1 then when a DP4 program is activated the terminal manager ensures the Input Panel Button is visible and the taskbar is hidden. (This is done using FindWindow() on the appropriate classes to avoid using CE version specific APIs.


smooth

[TRMW]
smooth=0

Only applies when 4.5xx terminal manager is in use.

If 1, the terminal manager updates the screen via an off-screen bitmap to reduce flicker. Performance is somewhat impaired. There should be no reason to use this option with modern hardware.


StdButtonsWanted

[TRMW]
StdButtonsWanted=1

Applies only when the 4.5xx terminal manager is in use, and is considered to be obsolete.

If 1, some buttons are displayed at the bottom of the screen to provide enhanced mouse operation. This facility is intended as a 'quick fix' for users porting a text-based system.

You are strongly recommended to set this to 0 and to add buttons to maps as appropriate.


stdtitles

[TRMW]
stdtitles=1 or 2

Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If 0, titles in title bars are centered according to whether the 'center' flag is set in the map.

If 1 (the default in Windows 3.1 and NT 3.5) titles are centered.

If 2 (the default in Windows 95 and NT 4) titles are left justified.


string_nn

[TRMW]
string_02=DP4 Information
string_03=You must close DP4 applications before exiting Windows
string_04=Cannot access clipboard memory
string_05=[XXXXXXXX]. Program running withuot login."

These settings allow you to customise or translate hard coded messages inside the DP4 terminal manager. Please note the following points:

  • string_02 is used as the title bar for the message box that is displayed when a batch mode DP4 application terminates.

  • string_05 must begin with [XXXXXXXX] characters. It is used when writing information to syslog.prn about programs run outside a DP4 login session.


Title

[TRMW]
Title=""

Normally specified in named program section only (with QAB programs); processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

If a value is specified the text replaces the default value for the title bar text of the program's main window.


touch_calendar

[TRMW]
touch_calendar=0

touch_calendar=1 changes the user interface of the DP4 calendar control (introduced into 4.623 versions of trmw32.dll and trmwce.dll built on or after 7th November 2007). With the default setting (touch_calendar=0) the user has to select a date by clicking on the day of the month, and the selection does not follow the mouse. If touch_calendar=1 is set, the selection follows the mouse (similar to the behaviour in an ordinary pull-down menu or pop-up window). The latter behaviour is probably preferable on machines with a touch-screen. Some users may prefer this behaviour in any case. However, if you use this setting on screens with an ordinary mouse attached, it is possible that the day of the month will sometimes be unintentionally changed.

For example, if the user selects a particular day of the month, and then realises that the month is wrong, and if they then use the mouse to click on one of the buttons to change the displayed month the user will very likely find that the day of the month has also changed, because the mouse has probably moved over another day field to reach the button that was used to change the month. If the change to the day is not noticed the user may enter unintended data.


use600

[TRMW]
use600=1

Normally specified in named program sections only. Applies to Win32 4.6xx installations only.

If 0, programs use the 4.5xx terminal manager instead of the 4.61x version. This may be useful if you want to run a mixed environment. For example you could copy the 4.5xx versions of MAPEDIT and MAPPOST from a 4.5xx release into a 4.6xx installation (renamed to MAPED500 and MAPP500 for example), so that you could edit and post bot 4.5xx and 4.6xx maps for the same database. You would want to add the line use600=0 in the [MAPED500] section.


use_workarea

[TRMW]
use_workarea=0 or 1

use_work_area=1 can be used to set the default window size for applications to match the size of a maximised window (one that uses all space not reserved for windows such as the taskbar).

use_workarea defaults to 1 on Windows CE and 0 on other windows platforms. Prior to release 4.620 use_workarea is ignored, and the behaviour matches the use_workarea=0 behaviour of 4.620.

See the default window size page for more information.


useframe

[TRMW]
useframe=0 or 1

From 4.616 this option controls how the terminal manager creates the main window(s) for a DP4 application. When useframe=1 the main window frame is altered by addition of a client edge, which improves the appearance of help messages and menus.

The client edge is enabled if you have useframe=1 and disabled if you have useframe=0 or useframe=-1.

On Windows CE useframe is ignored and the system behaves as though it was set to useframe=-1

See Client Edge for more information.


usenonclient

[trmw]
usenonclient=1

Introduced in 4.616. See Non client area for more information.


usestatus

[TRMW]
usestatus =1

From 4.616, whenever possible help messages are displayed as status windows. The terminal manager will automatically reformat and resize the help message and status windows to fit. Help messages containing multiple controls or with multiple lines and tabs (indicating alignment requirements) won't get reformatted but will still be displayed as a status window where possible.

Maps which are typed as #helpmap, or which are displayed with BOTTOM are treated in the same way. They are not reformatted however.

Help messages won't be displayed as status windows if this would obscure other maps unnecessarily. However maps that have been turned into status windows don't count and will be obscured.

This behaviour has been adopted for compatibility with Windows standards.

You can disable all this new behaviour by setting usestatus=0 in the DP4 configuration file.


usestdfonts

[TRMW]
usestdfonts=0 or 1

Introduced in v 4.613; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function. The details below are subject to modification.

If 0 (the only value allowed in Windows 3.1,NT 3.5x and on Windows CE), the terminal manager always uses the userdata/DP4 configuration file default font for maps for which use the 'Default' font.

If 1 (the default value in Windows 9x and NT 4 or later), the terminal manager uses the fonts specified in the 'Appearance' Tab of the Display Properties control panel item for menus, messages (remarks, warnings and error messages) and help messages (uses the tooltip font).


use_viewer

[TRMW]
use_viewer =0

Normally specified in named program section only (with QAB programs); processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

From 4.621, if use_viewer=1 then when a programs prints to the screen and is not using DFPRINT, then instead of immediately echoing all the print output to screen (as in previous versions), a temporary file is created. When the program closes the print output stream, the program specified in the viewer configuration setting is used to view the file.

Please note that the issued 4.621 dp4.ini has had this setting applied for most standard DP4 utilities that do any printing. You are recommended to make sure these new settings are applied to your own DP4 configuration file.


vertical_gradient

[TRMW]
vertical_gradient=0

If 1 the gradient on the title bar is drawn from top to bottom.

If 0 the gradient on the title bar is drawn from left to right.


viewer

[TRMW]
viewer = view

Normally specified in named program section only (with QAB programs); processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

From 4.621, if use_viewer=1 then when a programs prints to the screen and is not using DFPRINT, then instead of immediately echoing all the print output to screen (as in previous versions), a temporary file is created. When the program closes the print output stream, the program specified in the viewer configuration setting is used to view the file.

Other suitable programs you can use for viewing files are DP4ED, or the Windows Notepad program, or even Microsoft Word. The latter programs give you a Find and Replace Function, but may not display box characters correctly.

Note that you can specify different viewers according to the program being used.


weight

[TRMW]
weight=0

Selects the 'weight' of the default font. If left at 0 Windows will pick a value appropriate to the font. Other possibilities are:

  • 400 'Normal'
  • 700 'Bold'


width

[TRMW]
width=calculated value

Processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

width is the width of the client area of the main program window. If this is not specified then the value is defaulted in one of two ways:

  • If use_workarea=1 (available from 4.620) then the client area width matches that of a maximised window.

  • Prior to 4.620 or if use_workarea=0 the default width is calculated as cols * x_factor.

This value is updated when a program terminates. To prevent updating make the DP4 configuration file read only or set save_position=0.

See the cols, x_factor, and default window size pages for more information.


winime

[TRMW]
winime=1

This entry applies to Far East versions of DP4 only.

If 1, the terminal manager sends the appropriate IME messages to cause IME data entry to take place in the appropriate control.

If 0 IME data entry is performed outside the control, normally near the bottom of the Windows Desktop.


winprinfont

[TRMW]
winprinfont="System"

The name of the font used by the WINPRIN program. This value can only be specified in [TRMW] section. See [WINPRIN] for other values concerned with font selection for WINPRIN.

See printing for more information about printing from DP4.

#


winprint

[TRMW]
winprint=0

Normally specified in [TRMW] only; processed when QAB programs are loaded or when a C application calls the trm_set_progname() function.

The DP4 device number which replaces the MS DOS device when spooling to the WINPRIN program. The DP4 device numbers are the numbers in the menu of devices offered when setting up device groups.

For example, 1 = PRN. Setting WINPRIN to 1 causes devices which print to PRN to print to WINPRIN instead. In 4.5xx you normally use WINPRIN by printing to the DATAFIT device. In 4.61x you normally use WINPRIN by printing to the WINPRIN device. From 4.616 you are recommended to use the DFPRINT program for printing, and to print to the DFPRINT device, when this value is not relevant.

See Printing for more details.


wrapbug

[TRMW]
wrapbug=0 or 1

Normally specified in [TRMW] only.

Certain versions of Windows erroneously suppress a leading blank immediately following a new line when the DrawText() function is used. Set wrapbug to 1 if your version of Windows has this bug and 0 otherwise.

The terminal manager defaults the value of wrapbug to 1 on Windows 3.1 and NT 3.5x and 0 to Windows 95 and NT 4.

We are not aware of any necessity to specify a value for this variable, but it could be necessary if you use a non-standard version of Windows.


x

[TRMW]
x=CW_USEDEFAULT

Processed when C or QAB programs are loaded, or when a C application calls the trm_set_progname() function.

x is the horizontal-axis coordinate of the top left corner of a window.

If use_workarea=1 (available from 4.620) then the default value for x matches the value for a maximised window.

The x value is updated when a program terminates. To prevent updating, make the DP4 configuration file read only or set save_position=0.

See the default window size page for more information.


x_factor

[TRMW]
x_factor=calculated number

From 4.616 you can specify values for x_factor and y_factor in the DP4 configuration file. The only time you would be likely to need to do this is if you wanted to use a default font that was slightly smaller than your desired x_factor and y_factor.

The default x_factor is the maximum of the following values for the default font:

  • The average character width reported by Windows
  • The width of 'n'
  • The width of '8'

From 4.616 this deafult value may be modified if isometric=1.

See Coordinate system for full explanation of use.

Between 4.616 and 4.620 this option was also used by DFPRINT. This caused problems for users who used x_factor and y_factor to make screens designed for VGA resolution run full size on SVGA or XGA resolution screens. From 4.620 the x_factor for printing with dfprint is set separately using dfprint_x_factor.

If you use x_factor or y_factor to make your screens bigger or smaller, then controls that use a non default font may use a font that is too small or too big. From 4.620 you can control font sizes at run time using the new x_inch and y_inch settings.

In 4.623 builds dated on or after 10 July 2006 you can specify floating point values for x_factor.


x_inch

x_inch,y_inch

[TRMW]
x_inch=72
y_inch=72

DP4 stores font sizes using points (there are 72 points to an inch). In theory this should mean that DP4 scales font sizes correctly when an application is displayed on a higher resolution screen. In practice this may not be the case, because Windows fails to adjust the reported d.p.i (dots per inch) metric when the screen resolution is changed. Also map and control sizes are not stored in points but relative to the x_factor and y_factor size. For either or both of these reasons it may be desirable to scale the fonts used by a DP4 application. This can be done using the x_inch and y_inch settings.

Decreasing this value increases the size of fonts. For instance suppose you have an application that was originally designed to run full screen on a 640*480 resolution screen (using small fonts in the Display Settings), and now want to run full screen at 800*600 still using Small Fonts. One way to achieve this would be as follows:

In the [trmw] or [progname] section set:
x_factor=10 ; was 8 on VGA
y_factor=20 ; was 16 on VGA
x_inch=58 ;(integer value nearest 72*8/10)
y_inch=58 ;(integer value nearest 72*16/20)

This will increase the size of all the fonts in your application by 72/58, except for the following fonts:

  • The chosen default font (and the fonts that replace the default font in menus, remarks etc., when usestdfonts=1)

  • Raster (non scalable) fonts, where the Windows font mapper cannot find a good match to the adjusted size (for example the SYSTEM font only exists at one point size).

If your application originally used the system font as its default font you would need to change it to use a font such as 11 or 12 point Verdana.


y

[TRMW]
y=CW_USEDEFAULT

Processed when C or QAB programs are loaded, or when a C application calls the trm_set_progname() function.

y is the vertical-axis coordinate of the top left corner of window. You must specify the x value if you want to specify the y value otherwise it will be ignored.

If use_workarea=1 (available from 4.620) then the default value for y matches the value for a maximised window.

This value is updated when a program terminates. To prevent updating make the DP4 configuration file read only or set save_position=0.

See the default window size page for more information.


y_factor

[TRMW]
y_factor=calculated number

From 4.616 you can specify values for x_factor and y_factor in the DP4 configuration file. The only time you would be likely to need to do this is if you wanted to use a default font that was slightly smaller than your desired x_factor and y_factor.

The default y_factor is the height of the default font as reported by Windows, including any external leading. From 4.616 this default value may be modified if isometric=1.

See Coordinate system for full explanation of use.

Between 4.616 and 4.620 this option was also used by DFPRINT. This caused problems for users who used x_factor and y_factor to make screens designed for VGA resolution run full size on SVGA or XGA resolution screens. From 4.620 the y_factor for printing with dfprint is set separately using dfprint_y_factor.

If you use x_factor or y_factor to make your screens bigger or smaller, then controls that use a non default font may use a font that is too small or too big. From 4.620 you can control font sizes at run time using the new x_inch and y_inch settings.

In 4.623 builds dated on or after 10 July 2006 you can specify floating point values for y_factor.


UNIX

The [unix] section is used, from release 4.525, by the Unix and Linux versions of DP4, and contains the following entries:

  • errlog
  • loader
  • startup_delay

If a Unix DP4 application is multi-threaded, which is only supported using the POSIX pthreads library, you must add the line use_pthreads=1 in the [progname] section of the configuration file. For example if you have a multi-threaded application named multidp4 your dp4.ini file should contain the following:

[multidp4]
use_pthreads=1

There is no reason to add this entry for ordinary DP4 applications. Doing so will cause extra system resources to be consumed.


WINDOWS

Entries in the [windows] section are only used by the 16 bit version of DP4. The following entries are defined:

  • loader
  • pre500
  • startup_delay


loader

[windows]
loader=srvw.exe

This sets the program which 16 bit DP4 programs run to autoload the database manager. Note that 16 bit DP4 does not have an (issued) equivalent of the loader program we supply with the 32 bit version of DP4 and so you cannot easily autoload complex configurations such as multiple resilience.


pre500

[windows]
pre500=1

This entry, which applied to 16 bit Windows programs only is no longer used (from release 4.520/4.616 on) because pre 4.500 programs are no longer supported. With previous DP4 releases it forces the database manager to retain support for programs created prior to release 4.515. You had to set this value to 0 to enable autoloading of the Database manager for 16 bit programs.


startup_delay

[windows]
startup_delay=2

The Win32 version of DP4 can detect when autoloading of the database manager is complete before allowing an application to continue. This is not possible with 16 bit DP4. This value specifies the delay, in seconds, which a 16 bit application that is attempting to autoload DP4 allows for the autoload to complete successfully.


WINPRIN

WINPRIN uses the following entries to control the font used for printing.

  • dialog
  • fontset
  • fh
  • fw

See printing for more information about printing from DP4 programs.


dialog

[winprin]
dialog=1

If 0, WINPRIN prints all pages automatically.

If 1, WINPRIN brings up the standard Windows print dialog which selects pages and the number of copies to print etc.


fontset

[winprin]
fontset=1

This value selects the character set for the font to be used by WINPRIN in the same way as the charset entry in the [TRMW] section controls the font used by DP4 programs.


fh

[winprin]
fh=0

Height of WINPRIN font in pixels. If 0 is picked Windows should select a value. Unfortunately many printer drivers seem to select 0 and you may have to find an appropriate value by experiment; 30 and 40 often work well.

See Printing for more information.


fw

[winprin]
fw=0

This sets the width of the font used by WINPRIN. If 0, Windows will pick a value according to the value of fh

For more information see Printing.


WIN32

The [win32] section is used by the Win32 version of DP4, and contains the following entries:

  • debug_console
  • dp4home
  • errlog
  • icon_visible
  • load_win1632w
  • loader
  • no_close
  • startup_delay
  • win1632w

If DP4 is set up to use Windows NT security the [win32] section may also contain the follow entries,described in Secure Operation of DP4

  • user=Windows NT username
  • password=Windows NT password
  • domain=Windows NT domain name


debug_console

[WIN32]
debug_console=0

If 1, DP4 programs which contain diagnostics create a console (like a DOS box) to receive the diagnostics instead of sending them to the ERRLOG program.


dp4home

[WIN32] [WINCE] [UNIX]
dp4home=System dependent default

This value specifies the directory where the local DP4 licence file is stored. The same location is also used for the default userdata.sys file, and may be used for other files (for example the DP4 terminal server creates its temporary cache files in subdirectories of this directory.)

You only need to specify a value for this entry if you want to store dp4.sys other than in the default location for the operating system. You are recommended not to do this.

See Names and Locations of Configuration Files for details of how the default value is determined.


icon_visible

[win32]
icon_visible=0 or 1

If 1, an icon (shown in the system tray on Windows 95/NT4 or later from 4.520/4,616), is created for the SRVW32 program even when it is run as a service. The icon will not be visible unless the service can interact with the desktop.

When DP4 is run as a service you can prevent the icon being created by setting icon_visible=0 in the [win32] section of the DP4 configuration file. The default for icon_visible is 1 rather than 0, from 4.616/4.520, except on NT 3.51

From 4.620 (5) (issued 17 Feb 2003) icon_visible=0 also works when srvw32.exe or srvwce.exe is run as an application.


loader

[win32]
loader=srvw32 -start

[wince]
loader=srvwce -start

[unix]
loader=dbdaemon -start

The command line which DP4 programs run when they want to autoload the 32 bit version of DP4.

With the Win32 version of DP4, or the 4.525 Unix and Linux version, applications can autoload DP4 in a fully configurable way. You should note the following points about auto-load in these versions of DP4:

  1. DP4 does not auto unload on termination unless configured to do so through the use of the -noremain command tail on the DP4 server (e.g. dp4srvr.w32 or tcpw.w32).

  2. The full configuration for the machine is autoloaded, not just the standalone database manager.

Autoload is enabled by default. To disable it set autoload=0 in [system] . The autoload runs the commands above by default. You can configure the command to be run by setting loader=Command.

For example, if you want to run DP4 as an application rather than a service on Windows NT you would set:

loader=srvw32 -load.

Or you might want a different configuration when autoloading than that used when running as a service.

loader=srvw32 -load -startup=autostart

You would provide an [AUTOSTART] section similar to the [STARTUP] section.

Although SRVW32.EXE is primarily a loader program, you should not attempt to replace it with a batch file or anything similar. SRVW32.EXE also performs the following important functions:

  • During startup and termination it will prevent DP4 programs from attempting to access the DP4 system at critical points where it would cause problems.

  • It validates the configuration as it is loaded and reports errors.

  • When DP4 runs as a service on NT it is the service process.

  • If we require you to help us diagnose a problem using the errlog program, SRVW32.EXE is required as it is responsible for piping diagnostics into errlog.

Prior to release 4.525 there was no loader program on Unix/Linux, and running without dbdaemon is still supported. However, most of the above reasons for using the loader apply equally well to the 4.525 Unix/Linux releases of DP4, and you are recommended to use the loader program.


load_win1632w

[win32]
load_win1632w=0

If 1, this causes SRVW32 to attempt to load support for 16 bit applications. You are recommended to convert 16 bit applications to native 32 bit applications rather than relying on this facility, which can cause problems, especially on Windows NT.


no_close

[win32] [wince]
no_close=0

If 1, the close option on the SRVW32 or SRVWCE system menu (seen when SRVW32 is loaded as an application, or as a service allowed to interact with the desktop) is disabled.


startup_delay

[win32] [wince]
startup_delay=15

This sets the amount of time, in seconds, that each server program is allowed to complete initialisation. Increasing this value will not slow loading if the server programs can load more quickly. It may be necessary,very occasionally, to increase the value when loading certain ADCs or DP4 networking programs as part of the DP4 service.


win1632w

[win32]
win1632w=win1632w.exe -quiet

The command line used to load win1632w if load_win1632w is set to 1.


WINCE

The [wince] section is used by Windows CE versions of DP4, and contains the following entries:

  • dp4home
  • errlog
  • loader
  • no_auto_close
  • no_close
  • startup_delay
  • use_systray


loader

[wince]
loader=pathsrvwce

The command line which DP4 programs run when they want to autoload the Windows CE version of DP4. Because Windows CE does not have the equivalent of a path environement variable the value for the loader entry must include the full pathname. The path used in the default value is taken from the dp4home entry

With the Windows CE version of DP4 applications can autoload DP4 in a fully configurable way. You should note the following points:

  1. DP4 does not auto unload on termination unless configured to do so through the use of the -noremain command tail on the DP4 server (e.g.dp4srvr.wce or tcpw.wce).

  2. The full configuration for the machine is autoloaded, not just the standalone database manager.

Autoload is enabled by default. To disable it set autoload=0 in [system].

You can use the -startup and -preload command tails in the loader entry to control how DP4 is loaded by auto-load for example:

loader=\dp4\win\srvwce -load -startup=autostart


use_systray

[WINCE]
use_systray=1

By default the DP4 Service tries to run as a task that is displayed in the taskbar notification area (or system tray). However, on some versions of Windows CE there is no facility to actually display this area, and the DP4 service is therefore not visible as a task. If this value is set to 0 then DP4 system will appear as an ordinary task (so it will show up in the list of running programs on Pocket PC for example).


Background Information

  • Client Edge has some technical information on the windows used by the DP4 terminal manager. This may be of interest to programmers who wish to subclass the windows created by DP4 programs.

  • Coordinate system tells you how you can control the settings that determine the size of DP4 user interface components

  • Default font tells you how to configure the font used for programs using the DP4 terminal manager.

  • Default Window Size and Position describes how DP4 positions applications on the screen when no explicit position is specified in the configuration file.

  • Diagnostics tells you how to enable error logging for DP4 programs as an aid to problem diagnosis.

  • Non client area documents a change made to the DP4 user interface in Windows in 4.616.

  • Printing tells you how to use the DFPRINT program to take full advantage of the facilities available with Windows printer driver.

  • Secure Operation of DP4 tells you how to prevent malicious users from making use of DP4 to gain unauthorised access to a computer or its files.

  • Skinning DP4 descrbes new features of the DP4 user interface in 4.621 that allow you to customise the appearance of DP4.


Client Edge

From 4.616, On WIN95/NT4 a 'client edge' may be drawn round certain parts of the screen. This improves the appearance of menus and help messages, but may impact existing programs if you are running at a low resolution.

The client edge is enabled if you have useframe=1 and disabled if you have useframe=0 or useframe=−1.

In previous releases of 4.6xx all maps were created as child windows of the application main window which could be discovered by calling trm_get_hwnd(). From 4.616 this window usually has a child window of the same class. The handle of this window can (before any maps are displayed) be found by calling GetTopWindow((HWND) trm_get_hwnd()). You should first call map_clear_all() and trm_refresh() to ensure that there you are not confused by windows used for copyright messages or system messages. The window may not exist, (so 0 would be returned), as the facility is configurable. Most maps are created as child windows of this window. However the following maps are created as children of the main window instead:

  • A menu bar displayed at the top of the screen; (Pulldown menus are displayed as WS_POPUP windows, owned by the parent of the menu)
  • Maps displayed with the BOTTOM flag which are not movable.

This child window will be periodically (possibly very frequently if you have help messages) sized to fit inside any menu bar or BOTTOM maps (especially help messages). If you subclass this window and trap the WM_WINDOWPOSCHANGING message you can further control its position and size. For example you could reduce its size by an amount sufficient to display a Windows toolbar control above it or a status window below it, or indeed any other window. Unless you are running on Windows 3.x or NT 3.x the window may have a 'client edge' which will slightly reduce the area available to maps.

The client edge improves the appearance of help messages and menus. You can change the frame style of the window if you wish (from C/C++ code).

The terminal manager will only put a client edge on this child window by default if you are running Windows 95 or NT 4 or later and are running at a sufficiently high resolution: normally 800*600 with small fonts or 1024*768 with large fonts.

If, for some reason, this window causes you a problem you can force all maps to be created as child windows of the main window, and prevent creation of the child window by specifying useframe=-1. However, there may be some problems if you do this, for example a menubar at the top of the window will be able to scroll off screen.


Coordinate system

Map sizes and coordinate controls are stored in an internal coordinate system designed to ensure that maps will display satisfactorily on any device whatever the default font and resolution. From 4.616 you have some additional control over this.

The internal coordinate system is based on assigning the size of a standard character in the default font as 16 internal units horizontally and 32 units vertically. (Typically characters are usually about twice as tall as they are wide). At run time the terminal manager calculates the actual size to be used for this character based on the chosen default font.

The height is the external lead in + the actual character height. This is called the y_factor.

The width is the maximum of the following three quantities: the reported average width, the width of "n", the width of "8". This is called the x_factor.

(For narrow spaced maps the terminal manager only takes the maximum of the average width and the width of 8). (This is called narrow_factor)

From 4.616 these factors are modfied as follows: if isometric=1 is set in then the terminal manager adjusts x_factor and y_factor so that a rectangle that has an equal width and height in internal units appears as a square on screen.

It does this by increasing one or other of x_factor and y_factor as required. If x_factor is increased controls will appear slightly larger horizontally, if y_factor is increased they will be larger vertically. Font sizes are unchanged. The default for isometric (its value if it is missing from the DP4 configuration file), is 0, however it is set to 1 in the issued DP4 configuration file. The value of isometric will only have an effect if your default font is NOT twice as high as it is wide. Note that the System font (at least on US Windows) is isometric anyway. Setting isometric=1 when you use another font (such as MS Sans Serif) as the default font may change the size of maps on screen. Doing so will ensure the aspect ratio of printed maps is the same as display maps, though this will only be necessary if there is significant difference in how Windows realises the font when printing from on screen.

From 4.616 you can specify values for x_factor and y_factor in the DP4 configuration file. The only time you would be likely to need to do this is if you wanted to use a default font that was slightly smaller than your desired x_factor and y_factor. For example if you design an application to run full screen at 640*480 you can ensure it will also run full screen at 800*600 resolution, whether the user chooses "Large" or "Small" fonts by specifying x_factor=10, y_factor=20.

Changes in 4.620

If you increase (or decrease) the size of maps by changing the x_factor or y_factor explicitly, or by changing the default font you use to one that has a different x_factor or y_factor, text may not fit nicely into controls. For example, text is usually aligned to the top of controls, and if the size of controls is increased too much this can become obvious. From 4.620 you can also adjust the size of text in fonts, using the new x_inch and y_inch settings. These settings change the number of points per logical inch from the default value of 72. A smaller value makes your fonts smaller. For full details see the description of the x_inch setting.

From 4.620 DP4 ignores the x_factor and y_factor settings when printing with DFPRINT. Originally x_factor and y_factor where used to that maps would print at the same logical size as they appear on screen. However, it is frequently the case that the size of maps on screen needs to be increased, because Microsoft Windows deliberately does not report the screen resolution correctly, whereas it is very unusual for printer resolutions to change much.

If required you can control all these settings for maps printed with dfprint using dfprint_x_factor,dfprint_y_factor, dfprint_x_inch,dfprint_y_inch.


Default font

From 4.616 it is possible to specify the "default font" in a more user friendly and portable way. The default font is either one of the built in fonts such as the system font or a user specified font. You choose one of the built in fonts by selecting one of types A to E in USERDATA. You can select a custom font by specifying a font name and size in the DP4 configuration file (in the [trmw] or [progname] sections). The fontname is specified with a string such as font="MS Sans Serif". In previous releases the size of the font had to be specified by specifying the font height, and optionally width, in pixels (fh=16 for example). From release 4.616 you can specify a point size instead (pointsize=10). This is slightly more portable in theory, in that the font size should be constant whatever the resolution of the screen. In practice point sizes on screen are unreliable as changing the resolution does not normally change the reported number of pixels per inch on which a point size calculation has to be based. However it will give you a way of specifying a font in a way consistent with other applications. If pointsize is specified fh and fw settings are ignored. From 4.620 the USERDATA program allows you to choose a font from the available Windows fonts and writes the information into the DP4 configuration file automatically. Source code is also available from the DP4 user group site showing how a program can discover and set its default font.

It is possible to force a particular default font on a per application basis. This is done by setting forcefont=1 in the [progname] section of the DP4 configuration file. (If you set forcefont=1 in the [trmw] section it has the effect of completely overriding the USERDATA.SYS font setting). forcefont=1 was advertised in release 4.614 but did not actually work. With that release you actually had to set forcefont=99. You can also force one of the built in fonts. For example forcefont=13 forces the system font. (The values to use for built in fonts are taken from the numeric values of the appropriate constants for GetStockObject())

If you choose a userdata type F font or use forcefont=1, then you should now specify a value either for pointsize or fh as well as font=fontname. The technique of letting Windows choose the font size for you will prevent the new DFPRINT program from working properly. You may also specify values for weight, charset, and, if you used fh rather than pointsize, fw

From 4.616 the API used to select the default font has altered slightly. This has been done to ensure maximum WYSIWYG behaviour of the new DFPRINT print program. This will have no effect unless you specified a default font that could not be created exactly as requested. If you did specify a font like this you may find the font size or appearance is different - it will now more closely match what you have asked for. If this is not actually what you wanted then you would need to change your DP4 configuration file settings.


Default Window Size and Position

The following information will only apply when there is no size or position information in either the [trmw] section or the section for the program itself. The size and position of an application window are otherwise determined by the x, y, width, and depth values.

  • Prior to 4.620, or if use_workarea=0 is set the following scheme is used:

    The default screen size used for DP4 programs is height=y_factor*rows and width=x_factor*cols. Prior to release 4.616 x_factor and y_factor cannot be set explicitly, and always take their default values. From 4.603 to 4.614 rows and cols could not be set explicitly and the userdata screen depth and width were used instead. They can be set in all other releases.

    If the window size calculated from these initial defaults is very near the size of a maximised window that size is used instead, and the window is also positioned as a maximised window, to avoid the window contents appearing off the edge of the screen. Otherwise the initial position for the window will be chosen by the Windows operating system.

    This scheme works well for applications that display information in a fairly fixed form that cannot take advantage of a large window.

  • From 4.620 and if use_workarea=1 the default size and position is chosen so that the client area (including the client edge if present) fills the size of a maximised window. The size of a maximised window will vary depending on the taskbar size and properties. It may also be reduced if other toolbars such as the Microsoft Office toolbar is present.

    This option is suited to programs that always want to use the whole available area of the screen, regardless of how big it is.


Diagnostics

DP4 has several kinds of diagnostic messages and output. DP4 System Error and Fail Messages are normally displayed on the screen for the user to act upon. They are also written to SYSLOG.PRN file, and, on Windows NT family operating systems, to the Application Event Log. If you have a problem with DP4 that is proving difficult to isolate you may want to enable the DP4 Error logging program which can display additional diagnostics about many aspects of DP4 operation.

  • The error log program is loaded if you specify -load_errlog on the command line for the DP4 loader (e.g. srvw32.exe on Windows, or dbdaemon on Linux), or if you put load_errlog=1 in the [system] section of the DP4 configuration file. The diagnostics are normally written to the file debug.out in the current working directory.

  • There are two methods of getting the diagnostics to also display on the screen:

    • If you specify -debug_echo on the command line to the DP4 loader (or put debug_echo=1 in the [errlog] section), the error logger will display a scrollable on screen window containing the most recent diagnostic messages (on Unix output is just displayed on the console/terminal where dbdaemon was started). (If DP4 is run as a service it must be set to interact with the desktop.)

      As of release 4.622, and on Windows platforms only you can show the DP4 error log window at any time using the "View log file" command in the popup menu for the DP4 service. You can also clear the contents of the Window by pressing the Delete key, or copy/cut the contents of the visible part of the window with Ctrl+C/Ctrl+X, or the entire window with Ctrl+A.

    • For Windows only, If you specify debug_console=1 in the [win32] section of the DP4 configuration, or -debug_console on the command line to a program the error logger is bypassed. Instead each DP4 program will create a console window to display diagnostic messages. This may be useful if you want to clearly separate each program's diagnostics from that of other programs.

  • Most DP4 diagnostics are written using a slightly modified printf() function, and are in fact written to stdout - the DP4 loader ensures that stdout is a pipe into the errlog program for programs run as part of the DP4 system. On Unix and Linux this is the only output errlog catches. On Windows, for programs not run by the loader the DP4 printf() will test the stdout value. For most Windows programs it is invalid and diagnostics are written to the ERRLOG program. If stdout is valid (for example because you started the program from a DOS prompt and supplied an output redirection), then the output will be sent there instead. This may cause a problem with some third party products, for example if you want diagnostics when using DP4 ODBC drivers with Microsoft Access, because the product supplies a stdout, but does not display the information anywhere. You can force a program to output to errlog by creating a [progname] section for it in the DP4 configuration file and adding an ignore_stdout=1 entry. Unfortunately this option cannot usually be specified on the command line. For example, in the case of Microsoft Access the appropriate [progname] is [msaccess]. You can get your own C programs to output printf() to the DP4 error log by linking with the appropriate version of the DP4 syslib library before the regular C library. You can also get them to report version information, either by using the DP4 version stamping utility (bizarrely named kentcurs), to add version information or by providing a function named vs_verstring() somewhere in your code. This function is prototyped in the verstamp.h file, and should return a pointer to a null terminated string containing version information.

  • If you want to diagnose problems with starting or stopping the DP4 system you may well want to specify the ignore_shutdown=1 option in the [errlog] section, (or -ignore_shutdown on the command line to the DP4 loader).

  • The output file for DP4 diagnostics is normally only allowed to grow to a certain size. When it reaches that size the file is closed and a new file started. The exact details of when this happens and what happens to the old file depend on various other entries in the [errlog] section.

  • Just turning on errlog does not enable all the DP4 diagnostics (though most error diagnostics are turned on in the supplied DP4 configuration file). For most programs diagnostics are turned on or off by the various entries in the [debug] section. You should always remember to turn off the [debug] section entries once a problem is solved, otherwise DP4 will waste time continuing to format invisible diagnostics! For some programs, notably the DP4 network programs, diagnostics are turned on with a −debug or −debug_error command tail.


Non client area

Prior to 4.616 the entire window area of DP4 maps and controls, including frames and title bars were 'client area'. From 4.616 these areas, at least for static and edit controls, and the map frame/title itself, are optionally created as a genuine non client area. (However the area is painted entirely by the terminal manager - the windows do not have any frame or title as far as Windows itself is concerned). The primary reason this has been done is to simplify the code which is responsible for painting controls, and to make it simpler to add future 'non client' functionality such as the 'Close (X) button' or Window (system) menus. There is little or no impact on performance whether or not there is a non client area, and indeed virtually no difference in the code called by the terminal manager (there will be marginally more drawing if you disable the non client area, as it will get painted much more often, but this is partially offset by a reduction in the number of messages)

It will make it easier for an application to create its own controls in a window as the coordinates will be easier to calculate. (We've no idea what would happen if you actually tried this).

If necessary you can disable the non client area of DP4 maps by specifying usenonclient=0 in the DP4 configuration file in the [trmw] or [progname] sections.

You are recommended not to do this unless it really is necessary.


Printing with DFPRINT

Version 4.616 brought major enhancements to the printing functionality in DP4. There is full support for printing text in multiple fonts and colours and for printing bitmaps, icons etc. The appearance of printed maps will closely match the appearance on screen. To make use of the enhanced print capabilities all that is needed is to change the output device (POD) to one that uses the new DFPRINT print device. No other program changes are necessary, though it would be advisable to read through the remainder of this topic to gain a full understanding of the considerable implications resulting from this change.

Operation of DP4 when printing to DFPRINT devices

When a program selects to print to DFPRINT then a page set up dialog is displayed. In the 16 bit version this will only allow the user to select orientation and printer to be used. In the 32 bit version it also allows margins to be set. You can disable this dialog by setting pagesetup=0 in the [progname] or [trmw] sections of the DP4 configuration file. The print orientation will default to Landscape if only print to screen is selected, and Portrait otherwise. The margins selected in the 32 bit version are taken from margin_left, margin_top, margin_right, margin_bottom entries in the DP4 configuration file. The users selections are written back to the same place. Margins default to half the default value specified by Windows (usually give a value of 12.5 millimetres or half an inch), though this default will be increased if the printer's minimum margins are more than this. The margin_xxxx entries are stored in the units used by Windows, which may be thousandths of an inch or hundredths of a millimetre.

If print to file is selected then the append/delete/cancel dialog may be displayed as normal. However the append option is disabled - it is not currently possible to append to print files intended for DFPRINT. (This may prevent DFPRINT from being used in certain situations). This restriction will be removed in a future release if possible. Print files created using the DFPRINT device can only be accessed with the DFPRINT program (using a command line of the form DFPRINT filename). The files are in a private format which is different between the 16 bit and 32 bit versions of DP4 and which is subject to change in future releases. The file is analogous to a Windows meta file, though the format is much more compact. To create files readable by other applications you should set up a print device that uses the IBM file output or DP4 output devices, or from 4.621, you can use the Save option in DFPRINT to convert the file to various formats usable by other programs. You can also configure PODs that will automatically cause the file to be converted to one of these formats. For more information on these possibilities refer to Configuring DFPRINT PODs in the OSDI Developer's Guide.

As with the old WINPRIN program, which is retained for compatibility only, no printing is done until the application releases the print device. In order to ensure that programs printing to DFPRINT do not appear to hang a comfort message is displayed while the print output is being created. However this is not created until several pages have been created (as creating the file is normally very rapid).

When the program closes the DFPRINT device the output it has created is sent to the new DFPRINT program (unless only print to file was selected, and conversion to another format is not required).

Operation of DFPRINT

The behaviour of DFPRINT will vary according to whether print to screen was selected or not. If it was selected then DFPRINT will normally run interactively and display a print preview of the first page. The user can toggle between viewing the whole page, the page minus the margins or actual size output. It is possible to navigate around the document simply. If DFPRINT is running interactively no printing will take place unless the user presses the Print button, regardless of whether print to printer was selected or not initially. The standard windows print dialog is displayed when the user presses the print button.

If print to screen was not originally selected then DFPRINT runs in batch mode, and prints a single copy of the document on the printer selected in the pagesetup dialog, or the Windows default printer if this dialog was disabled. DFPRINT also runs in batch mode if the flags SCREEN+NOCTL+NO_SELECT are passed to dvc_choose().

In the 32 bit version of DFPRINT there is also a Copy button. This copies an image of the currently displayed page as a scaleable picture (metafile) to the clipboard. This allows individual pages of the document to be imported as graphics into other applications such as MS Word or Paint. It is not currently possible to import the document as text, though this is a likely future enhancement.

From 4.619, again only in the 32 bit version of DFPRINT, there is a Save button that can be used to save the output to a file or files: in versions 4.619 and 4.620 only HTML format is supported, from 4.621 you can also use RTF files which contain each page of the report embedded as a metafile. The HTML format files use CSS2 positioning and may not display correctly in older Web Browsers. Also some HTML editors will have problems with the generated pages. In the RTF files the output is essentially a picture and cannot be edited by the user.

DFPRINT can be used to view a file created on another computer, subject to the following limitations:

  • Bitmaps and icons contained in the executable used to create the file, or in files stored on that computer, will only be displayed correctly if they are present in the same location on the computer used to view the file.

  • If the printer used to create the file does not exist with the same name on the second computer, then DFPRINT will fail if a release prior to 4.621 is used. From 4.621 DFPRINT will ask the user to select another printer before continuing.

To create a file that can be viewed on any Windows computer see Creating Output for Other Applications in the OSDI Developer's Guide.

Appearance of Printed Output

The DFPRINT program is intended to be completely WYSIWYG - maps will be printed in the same colours and at the same size using the same fonts as they have on screen. However there are a few points to bear in mind:

Because Windows does not change the reported resolution of the screen in pixels per inch when the resolution is changed the size of a printed map and the display size will not always match exactly. However a map that is one "logical inch" on screen will be printed at one "logical inch" on the printer. Unfortunately MAPEDIT does not currently have a ruler to indicate the size (and in any case does not always display maps in their correct size) but the ratio of sizes will match that used by programs such as Word or WordPad. From 4.620 you can control the sizes used for printing with the settings listed here.

If maps have colour information then they will be printed grey scale on non colour printers. Depending on the colour scheme you use this may sometimes cause printing to be hard to read.

DFPRINT uses exactly the same information to create the font and convert map co-ordinates from internal units to real word units as the terminal manager (except that from release 4.621 you can use the [DFPRINT] section of dp4.ini to override settings from the [TRMW] section). Therefore at full scale in print preview the map will always look more or less identical to a map displayed on screen, unless the default font is realised differently on the printer from on screen, in which case the preview will match the printed version. Under most circumstances a map will look the same printed or displayed, but certain perverse choices of default font can cause this not to be the case.

For example, suppose you are running US Windows 95, and select userdata type F and specify the default font like this:

font="system"
pointsize=15.

Now, on screen the system font is not available in this point size - it is only available 10 point - 8 pixels wide by 16 high using small fonts, or 10*20 using large fonts. Therefore maps will be displayed by converting a 16*32 internal cell to an 8*16 display cell. However on the printer things are quite different. Windows will be able to scale the system font. Therefore the display cell of the print preview will probably be 12*24 units - and the maps will appear 50% bigger than expected. This kind of problem can only arise when a default font is specified that Windows cannot create exactly on the display. If this is encountered then change the definition of the default font to match what it actually is - in this example by changing the pointsize entry to pointsize=10.

In a few cases the font used to display the map on screen will not be the same as the font used to print the map. This will not be a problem where true type fonts are used or a font which exists in many different resolutions. However the system font and the system fixed font need to be substituted in order to print acceptably, as they only exist for the screen and when printed out would look very poor. The choice of font substitute is left up to Windows, but enough information is provided for it to choose a generally similar font. (i.e. proportional and non proportional sans serif fonts respectively)

When the print preview is displayed all fonts and outputs are scaled to fit the display. For non true type fonts, especially when the preview is resized to a very small size the display may not be accurate. At normal size it will usually be quite accurate.


Secure operation of DP4

Potential Security Problems in DP4

There are a number of security holes in DP4:

  • Malicious users with access to DP4 programs can copy their own programs onto a server running TCPMGR using NETCOPY and then start them running one way or another. On Windows NT they can also use NETCOPY to access files that are supposed to be denied to them. These problems can be addressed by making simple changes to how TCPMGR is started, or by configuring DP4 to run in an account with less privilege that the local system account that is normally used by the DP4 service.

  • A malicious program could take advantage of a security hole present in programs such as DP4SRVR.W32 and TCPMGR.W32 to bypass normal NT security features and install anything it wanted as part of the operating system. Such an infection might go unnoticed for a long time. Such a program would not need to know anything about DP4, only something about how to look for and exploit security holes, so they almost certainly exist.

    The only mitigating factors for this problem are that the malicious software would already have had to gain some access to the machine, and that quite likely it would find something other than DP4 it could use to make the infection more severe anyway. This problem is fixed by DP4 Enterprise and a fix will be issued for existing systems as well.

Basic Security

The options described in this section are easy to implement and can be used in any envionment, including Windows 9x and Unix. The command tails described are all new in version 4.620.

From 4.620 TCPMGR no longer permits commands to start programs on the server by default (this facility is required by DP4 Terminal Server). To enable the facility specify -allow_execute on the command line to for tcpmgr.

It is possible to disable support for the sf_open() command (and hence all DP4 remote file operations). DP4 remote file operations bypass NT security unless you go to the considerable trouble of implementing the NT security features described below. There are two mutually exclusive command tail options:

  • -nocopy completely disables support for remote file operations via DP4
  • -rocopy only permits file operations that open files with read only access on the server. All write operations are disabled.

Note that either of these options will prevent some DP4 programs from working over a network, notably DBBACKUP, DBCHECK, DBRECOV, DBRESTOR, DYNABACK, REORGDB, and the option to create a new database in MAKEDB (though they will work using DP4 Terminal server if enabled)

For DP4 Terminal Server you are recommended to use the -rocopy command tail to completely prevent a file being copied onto the server and then executed. -nocopy is not recommended because it will stop graphics being displayed.

NT Security Features

The contents of this section are preliminary documentation only.

DP4 Enterprise can be run in an account with less privilege than the local system account, which is the account normally used for services. With earlier versions of DP4 this did not work well because it was hard to diagnose problems.

The basic idea is that DP4SRVR.W32 and TCPMGR.W32 run some of the time using a special logon, and that permissions on the machine should be set up to limit what this logon can get to, but that the DP4 service as a whole still uses the local system account so that it can interact with the desktop, and produce diagnostics properly.

For this to work you have to be running on Windows NT 4,2000, or XP (Server or Workstation). It is advisable to use the latest service packs available, especially on Windows 2000, as it is possible to render a Windows 2000 machine non bootable through making the boot process get an access denied error! Windows 2000 SP2 appears to set default permissions to much more sensible values than used in earlier versions. To run DP4 securely it must be run as a service in the local system account, allowed to interact with the desktop (the default), otherwise you will most likely get access denied errors, especially if you use DP4 Terminal Server.

You must test on an identical machine and configuration to the live configuration if you plan to run DP4 securely. The slightest difference in the way the machines are set up or the version of Windows might mean you get an access denied error on one and not another.

  1. All hard drives should use NTFS as other file systems do not allow permissions to be set. You can use the CONVERT program to convert existing FAT/FAT32 partitions non-destructively. e.g. convert c: /fs:ntfs.

    Initially NTFS partitions may well be set with permissions that allow Full Control to Everyone (at least up to W2K SP2).

  2. Changing permissions so that things work securely is much more complex than might first appear, especially in the \windows directory. The problem is that there is a lot of badly behaved software that wants to create temporary or scratch files in critical directories such as the system32 directory, but which does not give a helpful diagnostic when given an access denied error by the operating system. For example it is difficult/impossible to get active desktop working properly for an ordinary user on a Windows NT machine after setting security, for just this reason. The built in tools for managing access control are barely adequate, though things are somewhat better on Windows 2000 than before.

    If you are serious about using NT security to control access to files you should probably invest in suitable third-party software or literature that tells you how to go about it. Roughly speaking , you need to ensure that administrators, SYSTEM, and CREATOR OWNER have full control everywhere, but that ordinary users are much more restricted, for example EVERYONE should be very restricted indeed. You can use DENY Access control entries restrict access to certain files or directories for specific users.

  3. Using DFSETUP change the layout of DP4 so that all the files are stored in one directory hierarchy such as C:\DP4 and subdirectories DB,WIN,TMP,PRNS. Change the directory for debug.out in the DP4 configuration file so that it goes to the PRNS directory:

    [errlog]
    debug_filename = ..\prns\debug.out

  4. Create a local user with a name such as DP4USER. Make it a member of the guests local group, allow it logon as a service access, and for good measure deny allow interactive logon (though this might just cause a problem, and should not really be necessary, as guest accounts can't do much damage).

  5. Give this user Full Control access to C:\DP4 and subdirectories (for folders only), and read write but not execute for files. Then change the access in C:\DP4\WIN to be Read and Execute only for files.

  6. You could use DENY permissions on some other directories to restrict DP4 further without upsetting anything else. It should be noted that having long ACLs on files can impact performance.

  7. Add the logon details for DP4USER to the [win32] section of the DP4 configuration file like this:

    user=DP4USER
    password=password
    domain=.

Once you do all this dp4srvr.w32 will run impersonating DP4USER which will mean it can only access files this user can, and any processes created by TCPMGR will be run as this user as well. TCPMGR runs as itself most of the time, as otherwise it can get WINSOCK errors, presumably because some internal file cannot be accessed.

You can use secure=0 in the [dp4srvr] or [tcpmgr] sections of the DP4 configuration file or -secure=0 on the command line to dp4srvr.w32 or tcpmgr.w32, to disable impersonation for one or other of the programs.

Security Considerations for Runnning DP4 Client Programs

As well as the security of the DP4 service itself you may be concerned about the type of account your application that uses DP4 will run in. Prior to 4.620 there were some problems running DP4 programs in a non-administrative account. However, since 4.620 there should be no problem with doing this. DP4 has been tested running like this on Windows 2000,XP and Windows Server 2003.

Nevertheless there are some points to bear in mind:

  • The account(s) you plan to use for running applications that use DP4 need read-write access to the directories where DP4 temporary files, and report/export files will be created.
  • If you plan to run DP4 as a service, then the accounts need the right to stop and start services, or at least the right to stop and start the DP4 service, otherwise they will not be able to run if DP4 is not already running. It is usually sufficient for such accounts to be members of the "Power Users" group.
  • On Windows Server 2003, and possibly on Windows XP (if you want to be able to run programs through a "remote desktop connection"), then accounts that will be used for running DP4 programs need the "Create a Global Object" privilege, othewise they will not be able to communicate with the DP4 service. This privilege is needed because it is necessary for some memory to be shared between the DP4 service and DP4 applications. Only "Global" shared memory is suitable because the DP4 service may be (or is on Windows 2003) running in a different session from the DP4 applications. This can be set through the Local Security Policy (secpol.msc) in "User Rights Assigment".


Skinning DP4

From 4.621 the appearance of DP4 programs can be customised to a much greater extent than in previous releases:

  • Buttons, headers and VCR controls can be drawn with a custom background. This is available on all Windows platforms except Windows CE versions. Buttons and VCR controls do not have to be rectangular.

  • The background parts of other controls can be coloured using a bitmap to give a texture or watermark effect. (However, this does not work well on Windows 95 because the texture is limited to an 8*8 bitmap.On other platforms, including Windows CE, there is no limit to the size of the texture bitmap). DP4 will arrange for the texture to join correctly across controls and maps, as can be seen in the screen shot below:

    Screenshot of DP4 with Texture

    • You should probably not use a texture if you plan to run applications using Windows NT Terminal Server or Windows 2000 or later Terminal Services. Using a texture may reduce the maximum number of users that can succesfully run applications simultaneously, especially if the texture bitmap file is large

    • Using a texture will slow down screen display and can cause performance problems with some graphics cards (See Problem Graphics Cards below). This is unlikely to be significant - on most modern PCs the display will still be more or less instant - but it will have some adverse effect on programs such as DBCHECK and REORGDB that update a count on screen very frequently. You can use the new refresh_interval setting to cure this problem.

Textures will not work well if the Screen is set to display 256 colours or less. Using custom buttons may also cause problems.

Both textures and custom buttons can be handled by DFPRINT. However they are disabled by default in this program, because they may cause problems with some printer drivers, and also because RTF files created by DFPRINT will be much larger if they are not.

You can enabled skinned rendering within DFPRINT by setting the no_texture option to 0

A collection of sample buttons and textures is available. However you can easily create your own versions as described below.

Texture and Button Bitmaps

The bitmaps DP4 uses to create buttons and textures are all standard Windows bitmaps. The various bitmaps should all be stored in the same directory as the DP4 licence file. The names are all configurable via DP4 configuration file entries in the [trmw] section (so that different programs can use different bitmaps if desired). However most of the time you can just use the default name. For example DP4 looks for the texture.bmp file in order to create the texture.

The only peculiarity of the bitmaps is that in order for them to be drawn in a colour that matches the current colour scheme, they should be stored as 256 color bitmaps that are predominantly pure red. At run time DP4 modifies the bitmap by removing the red component and replacing it with the appropriate colour. For this purpose "red" is considered to be the excess (if any) of red over green. For example if a pixel in the bitmap is coloured red=224,green=112,blue=56 (a dullish red-orange), and the colour to be rendered is pale blue (r=186,g=208,b=255) then the pixel will be rendered as r= 112 + 112*186/255 = 193, g = 112+112*208/255 = 203, b = 56+112*255/255=168.

Bitmaps to be used for textures should normally appear to be almost completely red. For example the texture used to create the screen shot above looks like this:

Sample Texture Bitmap

For buttons, parts that you want to be transparent should be coloured light grey (r=192,g=192,b=192). If you use transparency you should make sure that the transparent parts are the same in each of the bitmaps needed for the button. You should make the button bitmap somewhat larger than for a typical button, and it should be proportioned like a typical button.

Creating Buttons and Textures with Paint Shop Pro 7.

All the buttons and textures we supply were created with Paint Shop Pro 7.

To create a button proceed as follows:

  1. Create a new image for the button. A size of 300*100 works well.
  2. Fill the background with light grey (192,192,192) and then hide the background.
  3. Create a new raster layer and use the preset tool shape to create the button outline. You can use one of the available buttons if you like, but you will need to change the colour afterwards. One way to to this is to create a solid red layer and use the Hue or Colour blend modes. Alternatively you can fill the shape with a gradient, for example a red white red gradient.
  4. Use the inner bevel effect to create a button border. If your button is not rectangular you must make sure the background is hidden at this point, otherwise the border will not be applied correctly.
  5. You need to create four different states of the button. We found the best way to do this was always to use the same bevel type and depth and to vary the lighting and shininess to indicate whether a button is the default button or active. For the button down state reduce the bevel width. You can try a V shape bevel to indicate the button down state, but on the whole we did not think this gives good results.
  6. Reduce the colours to 256 using an Optimised Octree palette with error diffusion.
  7. Use the Edit Palette option and change the 192,192,192 entry (which you can find by clicking on the area that is supposed to be transparent) to Bright Magenta (255,0,255) or a similar colour. This will reveal any parts of the image which should be 192,192,192, but are not, because of anti-aliasing. Change all the "bad" pixels to the same Bright Magenta colour, by continuing to use the edit palette option.
  8. Increase the colour depth to true colour, and then reduce the colours to 256 using an Octree palette again. Change the Magenta palette entry to 192,192,192
  9. Save the images as a bitmap.

There are quite a number of tools available for creating buttons. However none of the ones we tried seem to make it easy to create a button down effect.

To create a texture you can use any image as a starting point. Bear in mind that large textures will substantially increase the memory used by DP4, and may impact performance. You should always test performance and appearance on the target machine - the same texture can render quite differently on different machines, even when the same Windows colour scheme is in use. Unfortunately the human eye is much more sensitive to small differences in colour near to grey or white light than it is to changes near a pure colour, therefore you may find it quite hard to judge the point at which your texture will look good when displayed by DP4. We suggest the following technique:

  1. Find a suitable image that you would like to use for a texture and open it in Paint Shop Pro
  2. Create a solid red raster layer and blend it using colour at around 90% opacity. Your original image will show through coloured red.
  3. Create two more solid red raster layers and blend them use lighten and darken modes respectively. Adjust the opacities so you can just see your original image. Alternatively put yet another solid red raster layer on top and blend it using difference mode. Adjust the opacities of the underlying lighten and darken layers so your image shows up just enough to be visible. Then delete the difference layer.
  4. Reduce the colours to 256 using Octree mode with error diffusion. Save the image as a bmp file, and test it out with DP4 by copying it over your current texture.bmp file. Don't exit Paint Shop Pro when you do this - you will most likely find that your texture is still too obtrusive and that you need to adjust the layer opacities some more to get a suitable result. You should test the texture with several different colour schemes to make sure it works well in all of them.
  5. If the edges of your texture do not join up neatly you may get an unpleasant tiled effect. You can use the Seamless Pattern from Selection option to create a texture that will tile neatly. However this can be rather frustrating and does not give very good results always. You can try using the Kaleidoscope or Pattern effects instead, or a gradient that varies the transparency to fade out the image.

Configuration file entries for bitmaps

All the entries are in the [trmw] section. None of the entries are re-read when trm_set_progname() is called, so they can only be specified on an application basis in [progname] sections that match real executable name. These entries can also be set in the [dfprint] section if desired: for example if you set no_texture=0, so that custom buttons can be displayed when printing maps (possibly useful when creating documentation for a system), you might specify texture=., so that textures were still disabled.

buttonup=buttonup
buttondown=buttondown
buttonactive=buttonactive
buttondefault=buttondefault
headerup=headerup
headerdown=headerdown
headeractive=headeractive
vcrup=vcrup
vcrdown=vcrdown
texture=texture

Problem Graphics Cards

Some graphics cards cause DP4 to update the screen very slowly when skinning is enabled. Sometimes skinned buttons are OK, but background texture renders very slowly. This is more likely to occur when running on machines intended as servers - manufacturers often assume that there is no need to supply such machines with high performance graphics cards. It may also happen that a card works well with some settings but not others - for example you may get quite difference performance when a card is set to display in true color resolutions rather than "hi-color".

In release 4.622 DP4 allows you to use true color bitmaps as well as 256 color bitmaps for background texture, as somtimes graphics cards can render true color bitmaps much more quickly than 256 color ones. However, bitmaps for buttons and other controls must still be 256 color as this is required for transparency suppport.

4.622 also has partial support for the XP "Luna" themes, and some third party themes. For details see "Support for XP Style interface"

As has already been mentioned, always test your application on the target machine. If this is not possible make sure users can easily disable texture.

Cards that are known to cause problems:

RAGE XL Pro PCI family


Example DP4 configuration file file

[branding]
home_name=DP4HOME
odbc_name="DP4 Enterprise"
prefix1=dp4
prefix2=dp5
service_name="dfSolutions"
service_title="DP4 Enterprise"

[buffers]

[debug]
debug_disk=0
debug_error=1
debug_ipc=0
debug_loader=0
debug_odbc=0
debug_sql=0
debug_version=1
dump_sql=0

[dp4_error]
write_evtlog=1
write_errlog=1
write_syslog=1
show_message=1

[errlog]
debug_date=0
debug_echo=0
debug_file_name=debug.txt
debug_file_size=1024
debug_keep_file=0
ignore_shutdown=0

[odbc]

[preload]

[sections]
debug=1
errlog=1
errmsg=1
odbc=1
preload=1
sections=1
startup=1
system=1
trmw=0
win32=1
windows=1

[sqllib]
remote=0

[system]
autoload=1
load_errlog=0
maxrec=4
ShutdownDelay=5

[trmw]
shadow_title=1
buttonstyle=2
StdButtonsWanted=0
OKEndSession=1;if 1 allows exit from Windows with DP4 programs loaded
smooth=0;set to 1 if you experience unacceptable screen flicker
pause=1
winprint=1
winprinfont="Arial"
font="System"
;stdtitles=1 ;Would force titles to be centred;2 forces left justify
;ButtonHeight=40
;Blue=(0,0,128)
;Green=(0,65,0);gives dull green ink and paper
;Cyan=(0,65,128);gives dull cyan and ink and paper
;Red=(128,63,0);gives red brown ink and background
;Magenta=(65,0,128);gives purple ink and background
;Brown=(191,191,0);gives yellow brown ink and yellow background
;LBlue=(0,0,192);gives bright blue ink and quite bright blue paper
;LGreen=(0,192,0);bright green ink and quite bright greeen paper
;LCyan=(127,255,255);gives bright cyan ink and cyan paper
;Lred=(192,0,0);gives red ink and paper
;LMgnta=(255,0,128);gives bright purple ink and red purple background
;Yellow=(255,255,127);give yellow ink and cream paper
;White=(255,255,192);give white ink and off white paper
rows=28
cols=80
dfshutdown=1

[unix]

[win32]
load_win1632w=0
loader=srvw32.exe -start
startup_delay=15

[wince]
use_systray=1

[windows]
loader=srvw.exe
pre500=0
startup_delay=2

[WINPRIN]
;fw=16; You need to set these up if printer driver does not default font sizes sensibly
;fh=30

[PROGMAKE]
limitsize=1

[HLPI]
use600=0

[MAPEDIT]
save_position=0
texture=.

[DBCHECK]
refresh_interval=100
use_viewer=1

[REORGDB]
refresh_interval=100

[DYNACHEK]
refresh_interval=100

[AUDITOR]
use_viewer=1
[COPYDB]
use_viewer=1
[DBBACKUP]
refresh_interval=100
[DFPRINT]
usestatus=0
use_workarea=1
save_position=0
[DYNABACK]
refresh_interval=100
[IMPSETUP]
use_viewer=1
[MAKEDB]
use_viewer=1
[MAKELINK]
refresh_interval=20
[MAPMAKE]
use_viewer=1
[MAPPOST]
use_viewer=1
refresh_interval=100
[MENUEDIT]
use_viewer=1
[PRINTDB]
use_viewer=1
[PROGBIND]
use_viewer=1
pause=0
[PROGCOMP]
use_viewer=1
[PROGDATE]
use_viewer=1
pause=0
[QABUTIL]
refresh_interval=100
use_viewer=1
[RECASTDB]
refresh_interval=100
[REPSETUP]
use_viewer=1
[UNLOAD]
refresh_interval=50
[VIEW]
use_viewer=0
viewer=

[dp4srvr]
buffers=262144
bypass_cache=2

[startup_debug]
1=dp4srvr.w32 -aux
2=auxdebug.w32 -name -all

[startup_client]
1=tcpw.w32 -server_name jimbo -debug_connect

[startup]
1=dp4srvr.w32 -aux
2=tcpw.w32 -server_name localhost -debug_connect
3=tcpmgr.w32 -aux -allow_execute -rocopy -debug_connect
4=tstcpw.w32

[startup_server]
1=dp4srvr.w32
2=tcpmgr.w32 -allow_execute -rocopy

[multiple]
1=dp4srvr.w32 -aux
2=tcpw.w32  -debug_error -timeout 15 -multiple -server 1
3=auxdistr.w32 -use 1 -server 1 -debug -nocrash -readlocal
4=tcpmgr.w32 -aux -debug_error -nonames -allow_execute -rocopy -server 1 -timeout 15

[multipledebug]
1=tcpw.w32  -debug_error -timeout 15 -multiple -server 1
2=dp4srvr.w32 -aux -chain 1
3=auxdebug.w32 -aux -chain 1 -all
4=auxdistr.w32 -use 1 -server 1 -nofail -debug_error
5=tcpmgr.w32 -aux -debug_error -nonames -allow_execute -rocopy -server 1

[multipledebug2]
1=tcpw.w32  -debug_error -timeout 15 -multiple -server 1
2=dp4srvr.w32 -aux -chain 2
3=auxdebug.w32 -aux -chain 2 -all
4=auxdistr.w32 -use 1 -server 1 -nofail -debug_error -aux -chain 1
5=auxdebug.w32 -all
6=tcpmgr.w32 -aux -chain 1 -debug_error -nonames -allow_execute -rocopy -server 1

[startup_localres]
1=tcpw.w32 -distributed -debug -server_name zeus
2=dp4srvr.w32 -distributed

[tcpip_servers]
dp4server01=amwh546its19
dp4server02=zeus
dp4server03=neptune
dp4server04=e318linuxamw

[client]
1=tcpw.w32 -server_name itim-ts -noremain -debug

[nolocal]
1=dp4srvr.w32 -aux
2=tcpw.w32  -debug_connect -timeout 15 -multiple
3=auxdistr.w32 -use 3 -debug_error -nofail -nolocal

[startup_auxwodbc]
1=dp4srvr.w32 -aux
2=auxwodbc.w32
[startup_auxoracl]
1=dp4srvr.w32 -aux
2=auxoracl.w32
[sql]
aimspseu=DSN=Pseuaims;DBQ=C:\MS_AccDBs\PseuAims.mdb;DriverId=25;FIL=MS
Access;MaxBufferSize=512;PageTimeout=5;UID=admin;
pubsdp4=DSN=PUBS;UID=nimas;PWD=dfxxx;APP=Itim Technology Solutions
DP4 for Windows 95 and NT;WSID=JOHNANT;DATABASE=pubs
terishl=DSN=teri; DBQ=teri; UID=Datafit; PWD=
mt=mt/mt@to-df
[sql.config aimspseu]
timestamps=1
first_occurs=1
role_first=1
role_sep='$'
[sql.config pubsdp4]
timestamps=1
single_query=1
[sql.remote aimspeu]
[sql.xlat aimspseu]
ACCT_AVG_BAL$1='ACCT_AVG_BAL{1}'
ACCT_AVG_BAL$2='ACCT_AVG_BAL{2}'
ACCT_AVG_BAL$3='ACCT_AVG_BAL{3}'
ACCT_AVG_BAL$4='ACCT_AVG_BAL{4}'
[sql.xlat pubsdp4]
[sql.xlat mt]
date=cdate
comment=coment
user=usr
initial=initials
start=cstart
default=defult
[oracle]
allow_null_key=0 ; 1 to stop null records error 1400,
    ; set for recastdb
use_checksum=1
max_statements=160
[errmsg]
0=DP4 service not running.
1=Cannot access DP4 databases
Loader=Error starting DP4
General=: Fatal Error on line
SourceTitle=%1 : %2 on line %3!d! of %4
NoSourceTitle=%1 : %2
OsError=Windows Error Code: %d
AdditionalError=Additional Error Code: %d
Unknown=DP4 Error type %1 number %2%nError parameters %3 %4%nNo message text available
errmsg_0=See Application Event Log for details
errmsg_10=Internal error: too many levels of error return nesting
errmsg_11=Internal error: too many exit functions registered
errmsg_21=Config error: configuration file not found
errmsg_31=Loader error: already loaded
errmsg_33=Loader error: WIN1632W cannot create window
errmsg_40=Server error: loader not running
errmsg_42=Server error: incorrect version
errmsg_43=Server error: cannot create window
errmsg_46=Server error: Invalid channel (check -chain value)
errmsg_47=Server error: Unable to logon to service account
errmsg_86=Problem: Server has been stopped.
errmsg_87=Problem: No server for applications loaded (check [startup])
errmsg_88=Problem: Server already loaded on this channel (check [startup])
errmsg_89=Problem: No server for ADC loaded (check [startup])
errmsg_90=Loader error: Error loading errlog
errmsg_95=Loader error: Bad exit code from program:
errmsg_96=Loader error: win32 error
errmsg_97=Win1632 error:
errmsg_98=Loader error: Error loading program:
sysmsg_1=Database not found
sysmsg_2=DP4 System error 2.  Origin: Program bug.%nMap %1 not on screen, so map %2 cannot be displayed over it.
sysmsg_3=DP4 System error 3.  Origin: Program uses withdrawn DP4 functions.%nIllegal function number (%1) passed to terminal manager.
sysmsg_4=DP4 System error 4.  Origin: Internal DP4 limit exceeded.%nToo many maps on the screen - limit is %1
sysmsg_5=DP4 System error 5.  Origin: Improper installation.%nBase data dictionary of database out of date. FIXDB21 required
sysmsg_6=DP4 System error 6.  Origin: Probable program bug.%nWork file error from terminal manager.%nError type %1 on table %2
sysmsg_7=DP4 System error 7.  Origin: Improper installation.%nKeyboard generated system failure.
sysmsg_8=DP4 System error 8.  Origin: Probable program bug.%nWork file error from database manager.%nError type %1 on table %2
sysmsg_9=DP4 System error 9.  Origin: Program bug.%nNo record for wkf_fetch() on type %1 index %2
sysmsg_10=DP4 System error 10.  Origin: Program bug.%nDatabase number %1 not opened for user %2
sysmsg_11=DP4 System error 11.  Origin: Improper installation.%nIllegal licence number - contact your installer.
sysmsg_12=DP4 System error 12.  Origin: Operator error.%nAnother user has exclusive access to this database.
sysmsg_13=DP4 System error 13.  Origin: Operator error.%nAnother user has access to this database.
sysmsg_14=DP4 System error 14.  Origin: Operator error/Internal DP4 limit.%nToo many databases open (limit is %1).
sysmsg_15=DP4 System error 15.  Origin: Unknown.%nDatabase index file not found.
sysmsg_16=DP4 System error 16.  Origin: Unknown.%nDatabase data file not found.
sysmsg_17=DP4 System error 17.  Origin: Unknown.%nDatabase not properly closed. Run DBRECOV
sysmsg_18=DP4 System error 18.  Origin: Program bug.%nDatabase number %1 cannot be reopened.
sysmsg_19=DP4 System error 19.  Origin: Improper Installation.%nDatabase manager and database are from incompatible versions.%nYou are either trying to open a database which is too old to be used with this database manager, or your database manager is too old to be used with this database.
sysmsg_20=DP4 System error 20.  Origin: Program bug,installation or database corruption.%nTable number %1 not found on database.
sysmsg_21=DP4 System error 21.  Origin: Database corruption.%nKey extraction not implemented for data type %1
sysmsg_22=DP4 System error 22.  Origin: Program or dictionary bug.%nRole not found on database.
sysmsg_23=DP4 System error 23.  Origin: Program or dictionary bug.%nTable %1 index %2 role combination not found on database.
sysmsg_24=DP4 System error 24.  Origin: Program or dictionary bug.%nIndex %2 specified in fetch on table %1 is not set to update.
sysmsg_25=DP4 System error 25.  Origin: Improper Installation.%nIndex %2 specified in fetch on table %1 is not up to date.%n(REORGDB is required)
sysmsg_26=DP4 System error 26.  Origin: Program bug.%nDatabase must be opened in exclusive mode for SET_STATUS or SET_GENERATION.
sysmsg_27=DP4 System error 27.  Origin: Corrupt database.%nKill cannot find prime index for table %1
sysmsg_28=DP4 System error 28.  Origin: Program or dictionary bug.%nTable %1 specified in AUTOINC is not an autoinc table.
sysmsg_29=DP4 System error 29.  Origin: Database corruption or internal DP4 error.%nField %1 specified in AUTOINC is not type N.
sysmsg_30=DP4 System error 30.  Origin: Program bug.%nUnrecognised program or database status.
sysmsg_31=DP4 System error 31.  Origin: Operator error.%nDatabase must be backed up.
sysmsg_32=DP4 System error 32.  Origin: Operator error.%nIndex analysis must be run.
sysmsg_33=DP4 System error 33.  Origin: Operator error.%nIndex analysis followed by reorganisation required.
sysmsg_34=DP4 System error 34.  Origin: Operator error.%nIndex scrutiny must be run.
sysmsg_35=DP4 System error 35.  Origin: Operator error.%nIndex scrutiny followed by reorganisation required.
sysmsg_36=DP4 System error 36.  Origin: Operator error.%nDatabase reorganisation required.
sysmsg_37=DP4 System error 37.  Origin: Operator error/Installation.%nNetwork manager program not running.
sysmsg_38=DP4 System error 38.  Origin: Improper installation.%nDatabase update not implemented by read-only version of server
sysmsg_39=DP4 System error 39.  Origin: Improper installation.%nDatabase update not implemented by read-only version of server
sysmsg_40=DP4 System error 40.  Origin: Program bug.%nOutput not implemented for data type %1 (%2)
sysmsg_41=DP4 System error 41.  Origin: Program bug.%nData entry not implemented for data type %1 (%2)
sysmsg_42=DP4 System error 42.  Origin: Program bug.%nBuffer of incorrect type or length used for bf_fetch().%nAttempting to read data of length %1 and type %2
sysmsg_43=DP4 System error 43.  Origin: Program bug.%nIllegal data size (%1) from function %2 passed to database manager.
sysmsg_50=DP4 System error 50.  Origin: Program or dictionary bug.%nPosting to index-only table %1
sysmsg_51=DP4 System warning 51. Origin: Operator error.%nUpdates lost because parent of record to be posted is missing.
sysmsg_52=DP4 System warning 52. Origin: Operator contention.%nUpdates lost because parent of record to be posted has been updated by another user.
sysmsg_53=DP4 System warning 53. Origin: Operator contention.%nUpdates lost because record to be updated has been updated by another user.
sysmsg_54=DP4 System warning 54. Origin: Operator error.%nUpdates lost because record to be deleted would leave orphans.
sysmsg_55=DP4 System warning 55. Origin: Operator contention.%nUpdates lost because record to be updated is locked by another user.
sysmsg_56=DP4 System warning 56. Origin: Hardware problem.%nUpdates lost because of comms failure.
sysmsg_58=DP4 System warning 58. Origin: Operator error.%nUpdates lost because record to be amended has changes in foreign key fields.
sysmsg_59=DP4 System Error 59. Origin: Program bug.%n%nRETRIEVE cannot be used unless enabled when the database opened.
sysmsg_67=DP4 System warning 67. Origin: System request.%nLog file nearly full - terminate program and back up database
sysmsg_68=DP4 System error 68. Origin: Operator error.%nCorrect transaction log file not found.%nA frequent cause of this problem is that a log file for a previous session of the database has not been deleted.
sysmsg_70=DP4 System error 70. Origin: Program bug.%nRead-only program cannot update database.
sysmsg_71=DP4 System error 71. Origin: System constraint.%nLog file size limit exceeded - back up database.
sysmsg_72=DP4 System error 72. Origin: System constraint.%nLog file date limit exceeded - back up database.
sysmsg_73=DP4 System error 73. Origin: Installation limitation.%nLimit on number of records exceeded
sysmsg_74=DP4 System error 74. Origin: Installation limitation.%nLimit on database file size exceeded
sysmsg_75=DP4 System error 75.  Origin: Unknown.%nDatabase manager lock timed out
sysmsg_76=DP4 System error 76. Origin: Improper installation.%nRollback logging must be turned on
sysmsg_77=DP4 System error 77. Origin: Improper installation.%nTransaction logging must be turned on
sysmsg_78=DP4 System error 78.  Origin: Program bug.%nNo currently selected record to be updated in table %1
sysmsg_79=DP4 System error 79. Origin: System Constraint.%nProgram tried to update database while updates disallowed. A database backup is required.
sysmsg_80=DP4 System error 80. Origin: Improper installation/corrupt database.%nCannot convert table %1 from generation %2
sysmsg_81=DP4 System error 81. Origin: Corrupt database.%nData independence not implemented for data type %1
sysmsg_83=DP4 System error 83. Origin: Improper installation/corrupt database.%nProgram generation %1 is greater than db generation %2
sysmsg_84=DP4 System error 84. Origin: Improper installation/corrupt database.%nTable %1 not found in swap list
sysmsg_85=DP4 System error 85. Origin: Program bug/improper installation.%nRecord type %1 being updated has incorrect length %2
sysmsg_86=DP4 System error 86. Origin: Internal DP4 error.%nDb manager internal error %1 in table nr %2.%nContact Itim Technology Solutions
sysmsg_87=DP4 System error 87. Origin: Database corruption.%nDatabase corruption type %1 in table nr %2
sysmsg_88=DP4 System error 88. Origin: Program bug.%nIllegal parameter type %1 value %2 in DBMS
sysmsg_89=DP4 System error 89. Origin: Program bug.%nIllegal commit nesting type %1 value %2 in DBMS
sysmsg_90=DP4 System error 90. Origin: System constraint.%nInsufficient space on data file disk.
sysmsg_91=DP4 System error 91. Origin: System constraint.%nInsufficient space on index file disk.
sysmsg_92=DP4 System error 92. Origin: Database Corruption.%nThis database has known problems, and should be restored from a backup.%nIf the previous backup is still online DBRECOV will be able to do this for you automatically.
sysmsg_93=DP4 System error 93. Origin: System Constraint.%nThe DP4 server denied permission for function %1%nContact your system administrator for more information
sysmsg_119=DP4 System error 119. Origin: Program bug.%nProgram workfile error
sysmsg_121=DP4 System error 121. Origin: Program bug.%nForm number %1 not in print buffer, so cannot be used for output.
sysmsg_122=DP4 System error 122. Origin: Program bug.%nAttempting to print without having selected print device.
sysmsg_123=DP4 System error 123. Origin: Program bug.%nForm %1 not in print buffer, so form %2 cannot be printed over it.
sysmsg_124=DP4 System error 124. Origin: Program bug.%nForm %1 not in print buffer, so form %2 cannot be printed beside it.
sysmsg_126=DP4 System error 126. Origin: Program bug or improper installation.%nLogical device %1 not found.
sysmsg_127=DP4 System error 127. Origin: Program bug or improper installation.%nLogical device %1 is a sub device.
sysmsg_128=DP4 System error 128. Origin: Program bug or improper installation.%nLogical device %1 is not sub device of printer %2
sysmsg_129=DP4 System error 129. Origin: Device driver.%nError %1 while writing to printer/device %2%nConsult your system documentation for more details
sysmsg_130=DP4 System error 130. Origin: Program bug.%nMap number %1 not on screen so field number %2 cannot be accessed
sysmsg_131=DP4 System error 131. Origin: Program bug or improper installation.%nMap %1 of mapset %2 not found on the database.
sysmsg_132=DP4 System error 132. Origin: Program bug or improper installation.%nInsufficient data passed to TRM for data entry in map number %1 field number %2
sysmsg_133=DP4 System error 133. Origin: Program bug or improper installation.%nMap number %1 field number %2 not found on the database.
sysmsg_134=DP4 System error 134. Origin: Security violation.%nWrite access is not allowed for map number %1 field number %2
sysmsg_135=DP4 System error 135. Origin: Security violation.%nRead access is not allowed for map number %1 field number %2
sysmsg_136=DP4 System error 136. Origin: Program bug.%nToo many nested calls to map_new_position()
sysmsg_137=DP4 System error 137. Origin: Improper installation.%nMap number %1 field %2 is off edge of screen
sysmsg_138=DP4 System error 138. Origin: Database inconsistency%nControl for map %1 of mapset %2 not found on database.
sysmsg_139=DP4 System error 139. Origin: Database inconsistency%nControl for map %1 field %2 corrupt.
sysmsg_140=DP4 System error 140. Origin: Database corruption.%nKey extraction not implemented for number system %1
sysmsg_141=DP4 System error 141. Origin: Database corruption.%nData independence not implemented for number system %1
sysmsg_142=DP4 System error 142. Origin: Improper installation or database corruption.%nProgram number system not supported by this database.
sysmsg_143=DP4 System error 143. Origin: Improper installation or database corruption.%nAutoincrement not implemented for number system %1
sysmsg_150=DP4 System error 150. Origin: Software licence expiry/improper installation.%nLicence number check overrun - contact Itim Technology Solutions.
sysmsg_151=DP4 System error 151. Origin: Security violation.%nRead access is not allowed for table number %1
sysmsg_152=DP4 System error 152. Origin: Security violation.%nWrite access is not allowed for table number %1
sysmsg_154=DP4 System error 154. Origin: Internal DP4 limit exceeded.%nTrying to open to many workfiles with wkf_open(). Limit is %1
sysmsg_155=DP4 System error 155. Origin: Program bug.%nNo workfile open for type %1
sysmsg_156=DP4 System error 156. Origin: Unknown.%nError %1 writing to printer/device driver interface (sub function %2)
sysmsg_157=DP4 System error 157. Origin: Unknown.%nError %1 reading from device driver interface
sysmsg_170=DP4 System warning 170. Origin: System constraint.%nWARNING: transaction log file size limit has been exceeded.%nThis program will not be allowed to update the database.
sysmsg_171=DP4 System warning 171. Origin: System constraint%nWARNING: transaction log file date limit has been exceeded.%nThis program will not be allowed to update the database.
sysmsg_172=DP4 System warning 172. Origin: System constraint.%nWARNING: The maximum period between database integrity checks has been exceeded. You should run DBCHECK.%nThis program will not be allowed to update the database.
sysmsg_173=DP4 System error 173. Origin: Security violation.%nYou do not have sufficient read authority to access this database.
sysmsg_174=DP4 System error 174. Origin: Security violation.%nYou do not have sufficient write authority to access this database.
sysmsg_210=DP4 System Error 210 Origin: Operator error or incorrect installation.%nScientific functions are not implemented in small version of PROGRUN
sysmsg_252=DP4 System error 252. Origin: System constraint%nAccess to this program has been disabled except for properly logged on users.
sysmsg_261=DP4 System error 261. Origin: Improper installation.%nYou must recompile and relink this C program as the QAB part of it has changed.
sysmsg_263=DP4 System error 263. Origin: Operator error or program bug.%nQAB calling non implemented C procedure/function type %1 number %2
sysmsg_271=DP4 System error 271. Origin: Program bug.%nUnable to allocate space for object in local heap
sysmsg_300=DP4 System error 300. Origin: ADC Error.%nAuxiliary db manager cannot find name number %1
sysmsg_301=DP4 System error 301. Origin: ADC Error.%nAuxiliary db manager cannot find db %1 user %2
sysmsg_302=DP4 System error 302. Origin: ADC Error.%nAuxiliary db manager cannot find table number %1
sysmsg_303=DP4 System error 303. Origin: ADC Error.%nAuxiliary db manager cannot find field number %1
sysmsg_304=DP4 System error 304. Origin: ADC Error.%nAuxiliary db manager cannot find prime index for table %1
sysmsg_305=DP4 System error 305. Origin: ADC Error.%nAuxiliary db manager cannot find field in index for table %1
sysmsg_306=DP4 System error 306. Origin: ADC Error.%nAuxiliary db mgr cannot find index specified for table %1 (parent %2)
sysmsg_308=DP4 System error 308. Origin: ADC Error.%nHeap overflow in auxiliary db manager
sysmsg_309=DP4 System error 309. Origin: ADC Error.%nStatement length overflow in auxiliary db manager
sysmsg_310=DP4 System error 310. Origin: ADC Error.%nAuxiliary database manager cannot close database
sysmsg_311=DP4 System error 311. Origin: SQL database.%nSQL database error number %1 on line %2
sysmsg_320=DP4 System error 320. Origin: Resilience program error.%nAUXDISTR cannot find process table entry %1
sysmsg_321=DP4 System error 321. Origin: Resilience program error.%nAUXDISTR cannot find db table entry for process %1 db %2
sysmsg_401=DP4 System error 401. Origin: DP4 Formula error.%nDivide by zero error
sysmsg_402=DP4 System error 402. Origin: DP4 Formula error.%nModulus by zero error
sysmsg_404=DP4 System error 404. Origin: DP4 Formula error.%nSubscript out of range error
sysmsg_405=DP4 System error 405. Origin: DP4 Formula error.%nBad argument to function %1 :%2
sysmsg_1000=DP4DYN Error 1000.%nUsing an invalid/closed Connection
sysmsg_1001=DP4DYN Error 1001.%nDP4_CloseDatabase() - Database not opened
sysmsg_1002=DP4DYN Error 1002.%nDP4_FetchRecord() - Database not opened
sysmsg_1003=DP4DYN Error 1003.%nDP4_PostRecord() - Database not opened
sysmsg_1004=DP4DYN Error 1004.%nDP4_DeleteRecord() - Database not opened
sysmsg_1005=DP4DYN Error 1005.%nDP4_Update() - Database not opened
sysmsg_1006=DP4DYN Error 1006.%nDP4_Commit() - Database not opened
sysmsg_1007=DP4DYN Error 1007.%nDP4_CheckPoint() - Database not opened
sysmsg_1008=DP4DYN Error 1008.%nDP4_CopyToParent/CopyToChild() - Database not opened
sysmsg_1009=DP4DYN Error 1009.%nDP4_RollBack() - Database not opened
sysmsg_1010=DP4DYN Error 1010.%nDP4_AutoInc() - Database not opened
sysmsg_1011=DP4DYN Error 1011.%nUnexpected Halt return code from database manager
failmsg_0=DP4 Fail Error 0%nUnable to initialise%1%2%n%4
failmsg_1=DP4 Fail Error 1%nUnable to terminate%1%2%n%4
failmsg_2=DP4 Fail Error 2%nToo many processes%1%2%n%4
failmsg_3=DP4 Fail Error 3%nToo many open files%1%2%n%4
failmsg_4=DP4 Fail Error 4%nWork file error%1%2%n%4
failmsg_5=DP4 Fail Error 5%nDatabase manager cannot initialise - bad system db ? (DP4 System Error %5)
failmsg_6=DP4 Fail Error 6%nUnable to find DP4 system message %2
failmsg_7=DP4 Fail Error 7%nNetwork error%1%2%n%4
failmsg_8=DP4 Fail Error 8%nCorrupt database%1%2%n%4
failmsg_9=DP4 Fail Error 9%nInter-process Communication Error%1%2%n%4
failmsg_10=DP4 Fail Error 10%nDFPRINT Error%1%2%n%4
failmsg_11=DP4 Fail Error 11%nProgram bug - using invalid DP4 Process Handle
failmsg_12=DP4 Fail Error 12%nUnable to start program %3
failmsg_13=DP4 Fail Error 13%nCorrupt file handle (from DP4 function %5)
failmsg_14=DP4 Fail Error 14%nExtended memory error
failmsg_16=DP4 Fail Error 16%nError in searching for file
failmsg_17=DP4 Fail Error 17%nUnable to create file %3%1%2%n%4
failmsg_18=DP4 Fail Error 18%nUnable to open file %3%1%2%n%4
failmsg_19=DP4 Fail Error 19%nFile %3 open by another user%1%2%n%4
failmsg_20=DP4 Fail Error 20%nFile size error%1%2%n%4
failmsg_21=DP4 Fail Error 21%nFile position error%1%2%n%4
failmsg_22=DP4 Fail Error 22%nSeek error on file %3%1%2%n%4
failmsg_23=DP4 Fail Error 23%nError in reading file %3%1%2%n%4
failmsg_24=DP4 Fail Error 24%nRead past end of file%1%2%n%4
failmsg_25=DP4 Fail Error 25%nError in writing file %3%1%2%n%4
failmsg_26=DP4 Fail Error 26%nCannot flush file %3%1%2%n%4
failmsg_27=DP4 Fail Error 27%nCannot close file %3%1%2%n%4
failmsg_28=DP4 Fail Error 28%nCannot delete file%1%2%n%4
failmsg_29=DP4 Fail Error 29%nError in default directory%1%2%n%4
failmsg_30=DP4 Fail Error 30%nError in file tracking%1%2%n%4
failmsg_31=DP4 Fail Error 31%nError in resetting file system%1%2%n%4
failmsg_32=DP4 Fail Error 32%nConnection to Network broken%1%2%n%4
sysmsg_163=DP4 System error 163. Origin: Unknown.%nInput redirection was wrong at line %1 of file %2
sysmsg_44=DP4 System error 44.  Origin: Unknown.%nDatabase Data Compression Information file not found.
sysmsg_45=DP4 System error 45.  Origin: Unknown.%nDatabase Data Pointers file not found.


trm_set_progname()

Purpose | Windows only, sets the current program
Syntax | void trm_set_progname(progname)
Parameters | char* progname | Program name to set as current program
Description | The trm_set_progname() function sets the specified program as the current program for the terminal manager (TRM<n>). This function is only relevant in Windows, where it causes the appropriate settings in the DP4 configuration file to be read.


SQL Statement Execution

The purpose of this part of the guide is to provide some information on how the DP4 SQL Engine executes SQL statements, so that developers have the best chance of writing statements in the most efficient form. You must not develop your system in such a way as to rely on the DP4 SQL Engine executing statements in a particular way: wherever possible we will seek to improve the SQL Engine by adding new optimisations, which may mean the database is accessed in a different way.

The code of the SQL Engine is very complex. When a particular statement is being compiled the Engine may transform the statement in many ways to reduce the number of accesses to the database to the minimum and to minimise the amount of extra work it has to undertake, for example to sort records. These transformations take the form of scoring the various parts of the statement in various ways, to determine which to execute first. It is very difficult to explain these transformations in simple terms, especially for the SELECT statement. In case of doubt use the AUXDEBUG ADC to discover exactly how a statement is executed.

The following explanations mention various flags from time to time:

  • The go faster flag is only ever used by SQL and SQLEXE, and is set if the -gofaster command tail is supplied. This command tail causes several statements to be executed incorrectly in some cases. It is not set by the ODBC go faster option. This flag prevents deletes from cascading - the CHILD_DELETE flag is not specified in any calls to rec_kill().
  • The omit checks flag is automatically set if the go faster flag is set. It is also set by the omit checks option in the DP4 ODBC DSN dialog. There is currently no way to set this option in SQL or SQLEXE. When this flag is set any calls to rec_post() are done without referential checks, and deletions are done without orphan checking.
  • The no private option is set by the -noprivate option in SQL and SQLEXE, and the "go faster" box in option in the DP4 ODBC DSN dialog. When this flag is in effect all reads from the database are done with the NO_UPDATE flag, which means that changes made in this transaction are not perceived. This can make a difference to whether a statement succeeds or fails, or to the values in fields that are not set explicitly by an update statement. For an example an INSERT might fail if there is an uncomitted DELETE of a record with the same key.
  • The readonly flag can be be set by the -read_only command tail for SQLEXE, -readonly for SQL. This flag causes all INSERT,UPDATE and DELETE statements to fail, and is not discussed further. For ODBC connections DP4 responds to the SQLSetConnectOption() calls that set SQL_ACCESS_MODE. For ODBC connections the best way to disable database updates is to set a non zero write access levels on the database, and to log on using a username with a zero write access level. Up to release 4.621 you must use write access levels set at a table level, (and this is still the only way to control access to individual tables). However, the DP4 SQL library has recently been updated to cope with a database wide write access level that is higher than the current access level. In this case the database is now opened read only. Previously this resulted in system error 174 and no connection.

Before considering the SELECT statement the other statements are briefly considered.

INSERT

An INSERT statement will be executed by a call to rec_fectch_main(EQUAL). If there is a matching record, then the INSERT will fail, unless the table is auto-increment. If a table is auto-increment any call to INSERT will result in a call to rec_autoinc() followed by a call to rec_post_with_flags() specifying either CHECK_PARENT, if omit_checks is not set, or NO_CHECK if it is.

If the go faster flag is set then the record is not fetched initially, and the INSERT may erroneously update an existing record. Therefore,when go faster is set, INSERT statements are only safe on auto-increment tables .

UPDATE

For an explanation of how UPDATE reads the records it will update, see the explanation of the WHERE clause for the SELECT statement.

The updating done by UPDATE statements is executed by a call to rec_post_with_flags specifying the UPDATE_ONLY flag. This will cause a commit failure at the next COMMIT WORK if the record does not exist. If the omit_checks flag is not set the CHECK_PARENT and CHECK_CHANGE flags are also specified.

If an UPDATE statement changes the primary key of the record, it works differently:

  1. First a check is done to see that there is currently no record with this primary key. If there is then the UPDATE fails
  2. Next the existing record is deleted, specifying flags to rec_kill as for a DELETE statement.
  3. The new record is posted, as though for an update, but omitting the UPDATE_ONLY flag.

DELETE

For an explanation of how DELETE reads the records it will update, see the explanation of the WHERE clause for the SELECT statement.

When deleting records the flags are specified as follows:

  • If go faster is set, then neither CHILD_DELETE or ORPHAN_CHECK is set.
  • If omit checks is set, (but not go faster) CHILD_DELETE is set, but not ORPHAN_CHECK.
  • If neither flag is set both CHILD_DELETE and ORPHAN_CHECK are set.
  • If the go faster or no private flag is set the NO_UPD_CHILD flag is set. This would prevent a subsequent select on a table that the DELETE deleted records in by virtue of CHILD_DELETE from perceiving that records have been deleted. However as reads are always done with NO_UPDATE this does not change anything, except that it makes the DELETE faster.

SELECT

The processing of the SELECT statement can be extremely complex, especially where there are several joins. The goal of the SQL Engine is to produce the correct result set for a query with the least amount of database access through query optimisation. In practice this goal is not always currently achieved, as there are some optimisations which could be performed but which are not. Queries more complicated than the optimiser can deal with may well be executed in a fairly inefficient manner.

WHERE Clause Optimisation

The remarks in this section also apply to ON clauses in SQL2 joins. ON clauses are treated as though they were ANDed with the WHERE clause.

The optimisations performed by DP4 SQL are mainly concerned with identifying the best index to use for reading a table, and reading as few records as possible from a table. For any table in a query the whole table will be read unless an index can be found with N keys for which keys 1 through M, 1 ≤ M ≤ N, there is a condition on the keyfield of the form fieldname=expression or expression=value (where expression is an arbitrary expression that evaluates to a result of the apppropriate type (perhaps even a subquery). What is more there must not be any OR which would allow these fields to take other values. It is much better to issue two queries without an OR than to this query:

select * from orderheader where ordernumber=1 or ordernumber=10000

An alternative, which is optimised, would be to use a UNION of two subqueries.

Important possible classes of optimisation are not performed. For example there is no optimisation which uses start and stop points for searching where BETWEEN, or IN clauses are used, nor of LIKE or MAX searches. Such optimisations will be added as time, resources and general usefulness permit. However many potential optimisations are extremely complex in the general case. Compared with earlier releases the current version of DP4 SQL will optimise many computer generated or modified queries better. Some software has a habit of fully parenthesising all expressions (or predicates to use the official jargon), and prior to the release 4.521/4.617 DP4 SQL gave up trying to optimise when it encountered such parentheses.

To clarify, here are some examples:

  • select * from orderheader where ordernumber=1

    This query is optimised by reading records on the primary key with ordernr=1. As there is at most one of these, only one record is read. Similarly queries using IN are not optimised.

  • select * from orderheader where ordernumber=1 or ordernumber=10000

    This query is not currently optimised. All the records in the order table are read, and the matching records are found by filtering.

  • select * from orderheader where ordernumber=1 union select * from orderheader where ordernumber=10000

    This query is optimised. Two subqueries each read one record from the order table.

  • select * from orderheader where ordernumber>10000 and ordernumber<20000

    This query is not optimised. Similary queries using BETWEEN are not optimised. This is the most important class of optimisation that is not performed, and optimisation of this type of query may be added in future.

  • select * from ordernumber where customernumber=1

    How this query is executed will depend on whether there is an active secondary index that can read the order table by customer number - if there is then it will be used.

Where there are multiple optimisable predicates in the WHERE clause, and there are several candidate indexes, the SQL Engine will pick an index according to one of various rules.

  • Prior to release 4.523 the SQL engine looked for the index that was most completely used, i.e. the one for which the fewest key components were unnaccounted for after all leading keys were matched with conditions in the WHERE clause. It did not consider further indexes if it identified an index that is completely used. Unfortunately this meant that it was not always the best index that was necessarily used. For example consider the following query

    select * from ordernumber where customernumber=1 and orderdate=12.11.1994

    The SQL Engine picked the CUSTOMER index rather than the ORDERHEADER index, because the INDEXDATETIME, which could also be used, has a time component as well. However, even if the query specifies a time as well the SQL Engine continued to use the CUSTOMER index, if it happens to come across it first (which will depend on the internal numbering of the tables), because it is completely used. This might well not be the best choice.

  • From 4.523 the default behaviour is pick the prime index, if all its keyfields are accounted for, or to pick the index that accounts for the most predicates otherwise. Compared with the previous algorithm this one may sometimes perform additional dictionary look ups, (and sometimes fewer), and will usually, but not always be more efficient. The situation where a worse index might be picked is where an index on two or more components is less discriminating than one on a single key. For example a SELECT on some kind of credit card table that sepecified a WHERE clause such as NAME='Aardvark' and YEAR_EXPIRY="01" and MONTH_EXPIRY="05" would most likely work faster if a NAME index is used than an index on the YEAR/MONTH_EXPIRY combination. Therefore in 4.523 you can use a compiler hint to specify that the old rule should be used, or that the primary index should be used.

ORDER BY and GROUP BY clauses can both affect the index used for queries, but only if the compilation of the WHERE clause had not already caused an index to be selected.

  • For an ORDER BY clause the SQL Engine will search for an index that has a leading subset of the keyfields which correspond in order, to the fields in the ORDER BY clause, i.e. the field with key precedence 1 in the index is the first field in the order by clause, the field with key precedence 2 is the second field in the order by clause, and so on. It does not matter if there are more keys in the index than fields in the ORDER BY clause. However, in the current implementation the SQL Engine only uses the ORDER BY field to select an index if all the ORDER BY fields can be matched with an index. This is because the sort algorithm used by the SQL Engine, "quick sort" does not take advantage of any existing ordering in the list. It is possible that the sort algorithm will be changes in future to natural merge sort, used by Report Writer and QAB, in which case ORDER BY will have more influence on the choice of index.

    This optimisation is only done if all the fields in the ORDER BY clause are ordered the same way, i.e. all ascending or all descending.

  • For a GROUP BY clause a similar optimisation is performed, but the SQL Engine just searches for an index that contains all the fields grouped on. The order of the fields is not relevant.

The use of DISTINCT on a column may also require the SQL Engine to sort data, and according to internal documenation also affects the choice of index. However, this does not appear to be the case currently.

Optimisation of Joins

So far we have considered only queries on a single table. A very important part of optimisation is concerned with optimising the number of fetches required to construct the result set of joins. You may find it helpful to refer to SQL Joins, which is adapted from information previously published on the DP4 User group. This explains how joins are constructed, and introduces some of the issues involved in optimising join construction.

The basic example of a join is the following:

select ordernumber,line from orderheader, orderline where order_header.ordernumber=order_line.ordernumber

which can also be written as:

select ordernumber,line from orderheader join orderline on order_header.ordernumber=order_line.ordernumber

There are two possible efficient schemes for performing this query:

  • Treating the orderheader table as the driving table:
    1. Fetch the order headers in turn,
    2. For each order header fetch all the corresponding order lines.

  • Treating the orderline table as the driving table:
    1. Fetch all the order lines in turn,

    2. For each order line fetch the order header if it is not the same as the previous order header.

Depending on other aspects of the SELECT statement the SQL Engine may use either of these strategies. In fact for the query as written here the SQL Engine will use the first strategy. If the order of the table names was interchanged it would use the second strategy.

The choice of strategy may be influenced by the type of join used, and by the WHERE clause. This will be illustrated by some examples.

  • select ordernumber,line from orderline right join orderheader on order_header.ordernumber=order_line.ordernumber

    Because a right outer join is used this query must return a row for every orderheader record whether or not there are order lines for it. This means that the second stragey above cannot be used any more. The same applies to orderheader left join orderline. The first strategy would be ruled out by orderline left join orderheader or orderheader right join orderline

  • select ordernumber,line from orderheader,orderline where order.ordernumber=orderline.ordernumber and orderline.materialcode=19949857

    This statement is in the form which would normally cause the first strategy to be used. However the WHERE clause has a condition on the orderline table which can be optimised (because there is a MATERIAL index that can be used to read the order line table. Therefore the SQL Engine uses a revised version of the second strategy:

    1. Read orderlines that have the specified material code using the material index.
    2. For each orderline fetch the order header if is not the current order header.

    It should be noted that because the material index is used, in principle the order lines may not be retrieved in order number sequence, so more order header accesses may be required, and an order by ordernumber will need a sort.

  • select ordernumber,line from orderline,orderheader where order.ordernumber=orderline.ordernumber and orderheader.customernumber=1

    This statement is the reverse case of the previous one: instead of using the second strategy as would be the case without the customer number condition, a revised version of the second stragey is used:

    1. Read orderheaders for the specified customer using the customer index for the order table.
    2. For each orderheader fetch the order lines.

    In general the SQL Engine will reorder a query so that any condition that can be evaluated without having to join all the tables is evaluated first. Then if the condition fails, the remaining records needed for the join do not have to be read from the database.

  • select ordernumber,line from orderline,orderheader where orderheader.ordernumber=orderline.ordernumber and orderheader.customernumber=1 and materialcode=19949857

    This statement raises the question of what happens when there are two conditions of this type. Now there is no perfect strategy for reading the data, as there are conflicting requirements for which query to execute first. As with the original query with no WHERE clause, the strategy used for creating the result set will depend on the order of the tables in the join.

    As written the statement uses this strategy:

    1. Fetch all the orderlines for the given material.
    2. For each orderline fetch the order header (if it is not the same as for the previous line) and see if it is for the right customer.

    If the order of reading the tables were reversed so the statement began select ordernumber,line from orderheader,orderline then this strategy would be used:

    1. Fetch all the order headers for the given customer
    2. For each orderheader read all the order lines for the selected material. List the order-lines that apply to this order.

    This is possibly not optimal - it might better to read all the order lines for the current order and select the lines that apply. On the other hand, although the order lines are read from the database repeatedly, if there are only relatively few order lined for this particular material the database manager will probably cache them efficiently, and they will be fetched in a single block fetch operation, (actually there will be at least three calls to fetch the records, but the first will only fetch one order line, and the last won't fetch any, so the reads will be cheap), whereas in the other case every order line is read at least once. In this example the strategy used when the the orderline table is listed first is almost certainly superior, as the number of reads is at most the twice the number of order lines for the material, where as in the second case the number of reads is this number multiplied by the number of orders for the customer, though the actual amount of disk access may be less if there are relatively few orders for a particular material relative to the total number of orders.

Where more than two tables are read in a single select statement the current SQL engine can occasionally make very poor decisions about the best order to read the tables in. From version 4.523 you can control the order tables are read in, and therefore force the query to be executed in a more efficient way.

Strategies for writing efficient SQL

Some implementations of SQL allow a programmer to supply hints to the SQL Engine as to how a query should be executed. It is reasonable to do this, because as the relatively simple example above shows there is sometimes no absolutely right way to execute a query. In many cases the best strategy will be different depending on the relative number of records in the tables concerned. The DP4 SQL Engine did not support hints until release 4.523. The hint syntax used by DP4 may affect portability of your SQL to some extent - it will cause problems if your SQL engine does not accept C style comments (an extension invented by Oracle). Although SQL has some powerful features, it also has many glaring gaps, of which this is one of the most prominent (another being the impossibility of simply fetching one record in a particular direction relative to one you know about already).

The most important thing to do is to keep statements simple. In many cases there is no particular reason to generate a hugely complex query. If you are accessing the DP4 SQL Engine from a C/C++ program, or indeed any sufficiently powerful language, using either ODBC or pipes to SQLEXE, then you can probably write your own code to combine results from several simpler queries in an appropriate manner.

Other than this, the only real influence you have over the execution of the statement is the order tables are listed in. The first listed table is the least likely to be read multiple times. Therefore you should put the table for which reading repeatedly would be most inefficient first in the list of tables and join other tables from that one, and whenever possible ensure that tabels are listed in an order which will allow efficient use of indexes. If you use the /*DP4SQL O0*/ compiler hint mentioned in the next section the SQL Engine will not change the order of your tables at all, and you can experiment with ordering the tables in different ways to get the best performance.

The order of predicates in a WHERE clause, and the order of expressions on either side of a comparison has no effect on the efficiency of your SQL in DP4.

Compiler Hints

From version 4.523 you can affect the optimisation behaviour of the SQL Engine to some extent, by using a compiler hint that takes the form of a C style comment. (It might be considered better to use an ANSI or ODBC escape syntax, but the comment syntax has the merit that it can be placed anywhere in the SQL statement and is syntactically independent of it). The compiler hint takes the following form:

/* DP4SQL optionvalue... */

The value will always be a single digit. Currently the only options are O to specify how to reorder the tables in a multi table SELECT, and I to specify how to choose the indexes to be used. For example the comment /* DP4SQL O0*/ will force the SQL Engine to access tables in the exact order specified in the FROM clause of a SELECT. You can specify a default value for the O and I options in the [SQLLIB] section of the DP4 Configuration file. Specify a value for the O option by adding a line of the form table_sort=n. Specify a value for the I option by adding a line of the form table_index=n.

The meanings of the various values for the options are given in the table below:

Option | Value | Meaning
O | 0 | The tables are accessed in exactly the order specified in the FROM clause
O | 1 | The tables are reordered so that where possible tables which are used for grouped or higher precedence sorted fields are accessed earliest. It is not possible to reorder tables where one or other is outer joined.
O | 2 | The tables are reordered so that tables which are mentioned most often in the WHERE clause are accessed first. Tables mentioned equally often are sorted so that where possible (not outer joined) tables which are used for grouped or higher precedence sorted fields are accessed earliest.
O | 3 | The tables are reordered so that where possible child tables are accessed before parent tables that are mentioned in a condition, and otherwise those which are mentioned most often in the WHERE clause are accessed first. Tables mentioned equally often are sorted so that where possible tables which are used for grouped or sorted fields are accessed earliest.
I | 0 | All tables are accessed using the prime index
I | 1 | Tables are accessed using the first index where the total number of keyfields minus the number of leading keys specified by a predicate is as small as possible.
I | 2 | Tables are accessed using the prime index if all its keys are specified by predicates, or the first index encountered that has the largest leading subset of its keys specified by a predicate.

There should only be at most one hint for each option in a statement. Each hint option applies on a global level to the whole statement - you cannot use multiple hints to force different behaviours on different tables.


SQL Joins

In DP4 the word join is typically used to denote the action of fetching a parent record whose primary key is available from corresponding foreign key fields in a child table. This type of join is very easy using the built in processing in QAB and other DP4 utilities such as ReportWriter. The Index analysis program (MAKELINK) analyses the data dictionary and constructs a table called @PC_RECORD (short for parent child record) which describes all the possible direct (and indirect) joins between tables. Except in the case where there is more than one instance of a foreign key in the child table (possible in DP4 through the role concept) a join is typically thought of as the unique parent record that corresponds to the child. In the DP4 API a program joins a table by copying the key fields from the child record that has already been read into the key fields of the parent and calling a DP4 fetch function to read the EQUAL record on the main index.

Typically we might do something like this to retrieve an order and the associated customer record:

askf_n(1,1,&order.order_nr); /* input order number */
rec_fetch_main(&EQUAL,&order.l);
customer.cust_nr = order.cust_nr;
rec_fetch_main(EQUAL,&customer.l);

In SQL a join is any kind of SELECT statement where columns (fields in DP4 terminology) are fetched from more than one table.

The fundamental SQL join is the cross or Cartesian product of the tables, consisting of all possible pairs of rows selecting one row from the first table , and one row from the second table . Any more useful join is expressed by restricting the rows returned through the use of a WHERE clause, or an equivalent construct (of which there are several in the SQL2 standard). In SQL the traditional way of expressing the DP4 code above would be something like:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDERHEADER,CUSTOMER WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR=ORDERHEADER.ORDER_NR

In order to return the single order and customer record the SQL engine notionally constructs a temporary table consisting of all possible pairs of orders and customers and then filters it leaving only the one row of interest. Of course you have to hope that the SQL engine does not work like this in practice. If you have a database of 10 customers and 50 orders it won't matter too much. If you have 10000 customers and 50000 orders then a SQL engine that worked like this would take all week to find one record.

A SQL engine will contain various optimisations that enable it to recognise certain kinds of query and execute them efficiently by limiting the records actually read from the database in some way.

It is important to realise that any SQL engine will have only a limited range of optimisations. When the SQL engine is unable to optimise a query, it really will construct the Cartesian product of the all the tables used in the query, and then filter it. Therefore you should satisfy yourself that any queries you construct are capable of being executed within a reasonable time on a database of the intended size, and not a "noddy" development database with just a few items of test data.

In SQL a join can be constructed using any kind of valid expression. Thus you could equally well have:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDERHEADER,CUSTOMER WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR=ORDERHEADER.ORDER_NR-10000

This obviously fetches the customer who placed the order number 10000 less than the one you are thinking of now.
More interestingly, though not especially useful is this example:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDERHEADER,CUSTOMER WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR<ORDERHEADER.CUST_NR.

This would retrieve the list of all customers with a customer number less than the customer for this order.

In SQL the parent child concept, which is central to DP4, is almost invisible.

SELECT ORDERHEADER.*,ORDERLINE.* from ORDERHEADER,ORDERLINE WHERE ORDERNUMBER=? AND ORDERLINE.ORDERNUMBER=ORDERHEADER.ORDERNUMBER

This query is syntactically identical to the first example. However, since presumably there can be many order lines in a single order, the query may return many rows.

Multi-table joins

DP4 also supports the notion of an indirect join . For example the CUSTOMER table might well have an ACCOUNT_MANAGER field which was a foreign key into an EMPLOYEE table. A program that takes orders might need to check the customer's credit rating. If the customer has a poor payment history it might want to look up the account manager and automatically send a memo to him, requesting authorisation of the order. The DP4 program has to add the following code:

employee.emp_nr = customer.account_manager.emp_nr;
rec_fetch_main(EQUAL,&employee.l);

Note that the program cannot retrieve the "correct" employee details until it has first read the appropriate customer record.
The SQL for this would be something like:

SELECT ORDERHEADER.*,CUSTOMER.*,EMPLOYEE.* FROM ORDERHEADER,CUSTOMER,EMPLOYEE WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR=ORDERHEADER.ORDER_NR AND EMPLOYEE.EMPNR=CUSTOMER.EMP_NR$ACCOUNT_MANAGER

(The details would vary according to how the ACCOUNT_MANAGER foreign key was named. Only DP4 would support CUSTOMER.ACCOUNT_MANAGER.EMP_NR as other databases lack roles)

Join failure and Outer Joins.

Consider our first example again (fetching an order and its associated customer record). Up until now we have not considered the possibility that an order record might exist for which the customer record was missing for some reason. In DP4 this situation is called join failure . It is usually up to the application to decide how to handle this situation. Note that the DP4 program will manage to retrieve the order even though the customer does not exist.

In SQL the situation is a little different. Recall that the result of a query is a subset of the Cartesian product of the rows. Now if there is no customer with a particular customer number, any query involving selecting a customer with a customer number equal to that number will necessarily return 0 rows. This could potentially cause confusion - a naive programmer might jump to the conclusion that when the

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDERHEADER,CUSTOMER WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR=ORDERHEADER.ORDER_NR

query fails it is because there is no order with that number.

One potential solution is to issue two SQL queries instead of one query with a join. However this is likely to be inefficient and if the join is complex then it may not be an option. Because of this the notion of an Outer join was added. Roughly speaking, in an outer join if there is no record that satisfies the condition on the record an imaginary "null" record is created, and this record is deemed to satisfy the condition involving that record. "Regular" joins are therefore sometimes known as Inner joins .

The notion of outer joins was not part of SQL originally. As a result outer joins have been implemented in different ways by different database products. For example in MS SQL Server outer joins are apparently specified by using a syntax using *= instead of = in where conditions. In Oracle a completely different syntax using (+) was invented. The SQL2 standard introduced many extensions allowing the specification of joins of various types. Unfortunately this standard is far from being universal as yet - Oracle 7 does not understand SQL2 joins for example, and Crystal reports does not use SQL2 syntax to specify outer joins. The SQL2 syntax has the merit of allowing multiple outer joins to be specified in a non-ambiguous way, which is not the case with the other syntaxes.

Before going any further it would be best to explain the concept of an outer join more accurately. In the example we want our query to return an order record, whether or not the corresponding customer record exists. The Oracle and Crystal reports syntax for doing this is as follows:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDERHEADER,CUSTOMER WHERE ORDERHEADER.ORDER_NR=? AND CUSTOMER.CUST_NR (+) = ORDERHEADER.CUST_NR.

The (+) directs Oracle, (or other databases that understand this syntax) to return a NULL row when there is no customer with the customer number matching the customer number in the order. All the fields in the customer record returned in this case will be NULL. (I am not quite sure what the value in the CUST_NR field itself would or should be. In the DP4 implementation this field would also be NULL, which is not perhaps ideal). It should be noted that the field the (+) follows is significant. It establishes which table has imaginary null records added. I should perhaps stress that these imaginary nulls are only hovering in the wings to be called upon when there is no other way of satisfying the condition of the join. If this were not the case the output of the query would be peppered with unwanted null records.

If we had a more general query (missing out the condition on the order number) we would end up with a list of all orders on the database, whether or not the corresponding customer record existed. Another query we might like to issue is one that lists the most recent order for any customer.

SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM CUSTOMER, ORDER WHERE ORDERHEADER.CUSTNR =CUSTOMER.CUSTNR GROUP BY CUSTNR

This query would miss out customers who had not placed an order yet. In order to get them included as well we would specify an outer join. (The GROUP BY clause is needed otherwise the query would only return the customer who had placed the most recent order of all)

SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM CUSTOMER, ORDER WHERE ORDERHEADER.CUSTNR (+) = CUSTOMER.CUSTNR GROUP BY CUSTNR

Note that now the (+) is appearing after the ORDER field, because we want imaginary nulls in the ORDER table.

This query could equally well be written:

SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM CUSTOMER, ORDER WHERE CUSTOMER.CUSTNR = ORDERHEADER.CUSTNR (+) GROUP BY CUSTNR

In SQL2, rather than using a WHERE clause, joins can be specified using various join operators and a USING or ON clause. The ON clause contains the part of the condition that is concerned with limiting which rows of the two tables being joined correspond.

Using SQL2 syntax the last two queries would probably be expressed as:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDER JOIN CUSTOMER ON CUSTOMER.CUST_NR = ORDERHEADER.CUST_NR WHERE ORDERHEADER.ORDER_NR=?
SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM CUSTOMER JOIN ORDER ON ORDERHEADER.CUSTNR=CUSTOMER.CUSTNR GROUP BY CUSTNR

However the queries can equally well be expressed the other way around:

SELECT ORDERHEADER.*,CUSTOMER.* FROM CUSTOMER JOIN ORDER ON CUSTOMER.CUST_NR = ORDERHEADER.CUST_NR WHERE ORDERHEADER.ORDER_NR=?
SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM ORDER JOIN CUSTOMER ON ORDERHEADER.CUSTNR=CUSTOMER.CUSTNR GROUP BY CUSTNR

These queries would be bound to return the same result set, though possibly in a different order. (This is an example of where optimisation of queries can cause trouble - in DP4 the "natural" form of the queries is more likely to be executed more optimally, than back to front equivalents.) In all four cases this syntax joins the tables using the inner join, so will not list the order if the customer is missing, or the customers without orders. If desired the word INNER can precede the word JOIN. (Probably this is rarely if ever done, though doubtless pedantic reference books will recommend programmers to use it "to avoid ambiguity")

The first two cases can be converted into outer joins by using the word OUTER:

SELECT ORDERHEADER.*,CUSTOMER.* FROM ORDER OUTER JOIN CUSTOMER ON CUSTOMER.CUST_NR = ORDERHEADER.CUST_NR WHERE ORDERHEADER.ORDER_NR=?
SELECT CUSTOMER.*,MAX(ORDERNUMBER) FROM CUSTOMER OUTER JOIN ORDER ON ORDERHEADER.CUSTNR=CUSTOMER.CUSTNR GROUP BY CUSTNR

However, if we consider the alternate form of these queries it should become obvious that this syntax is potentially ambiguous. In SQL2 there are both LEFT and RIGHT outer joins.

  • FROM ORDER LEFT OUTER JOIN CUSTOMER implies a join which adds imaginary nulls to the CUSTOMER table.
  • FROM ORDER RIGHT OUTER JOIN CUSTOMER implies a join which adds imaginary nulls to the ORDER table.

In some sense the table on the left of a LEFT outer join is the "main" table as is the table on the right of a RIGHT outer join. Normally the SQL engine will want to discover records in that table first before attempting to discover which if any records in the other table match.

The notions of left and right outer join are essentially completely equivalent. However, there are probably cases where one or the other (usually LEFT) is more natural than the other.

If a SQL2 join expression specifies the use of LEFT or RIGHT then the word OUTER is optional (and superfluous). If OUTER is specified on its own it implies a left outer join.

It should be noted that using the SQL2 syntax a left outer join will most naturally correspond to an Oracle statement where the (+) appeared on the right hand side of a comparison.

In DP4 SQL you should refrain from using right outer joins where possible. Internally the DP4 SQL engine generates right outer joins by interchanging the two tables and using a left join instead. In a few cases join expressions involving nested joins cannot be converted properly resulting in an internal error from the DP4 SQL engine. This will be fixed when possible if it becomes necessary.

In ODBC, outer joins are considered to be an extension, and are implemented using a so called escape syntax.

SELECT ORDERHEADER.ORDERNUMBER,CUSTOMER.NAME FROM ORDER LEFT OUTER JOIN CUSTOMER ON CUSTOMER.CUST_NR = ORDERHEADER.CUST_NR WHERE ORDERHEADER.ORDER_NR=?

becomes instead:

SELECT ORDERHEADER.ORDERNUMBER,CUSTOMER.NAME FROM {OJ ORDER LEFT OUTER JOIN CUSTOMER ON CUSTOMER.CUST_NR = ORDERHEADER.CUST_NR } WHERE ORDERHEADER.ORDER_NR=?

In the ODBC version of outer joins I believe that the word OUTER is mandatory in theory. ODBC drivers for databases such as Oracle are likely to mangle this syntax into the form expected by the database's native SQL support. This is a bit of a joker in the pack, as some drivers generate completely invalid SQL as a result. For example one early driver generated SELECT statements with two WHERE clauses if both an OUTER and an ordinary join were used.

Multiple joins

If we return to our example where we also joined the account manager record from the employee table you will see that a nested outer join may be necessary. In this case the FROM part of the query using inner joins would be something like:

ORDER JOIN (CUSTOMER JOIN EMPLOYEE ON CUSTOMER.ACCOUNT_MANAGER.EMP_NR=EMPLOYEE.EMP_NR) ON ORDERHEADER.CUSTNR=CUSTOMER.CUSTNR

Our interpretation of the syntax of nested joins is as follows:

  • All join operators are binary operators between two tables, the result of which returns a new table containing all the fields from both tables for the purposes of nesting joins. (Actually, the ON or USING clause may mean that JOIN is actually the first operator symbol in a ternary operator).

  • In an unparenthesised join expression involving multiple joins the joins must be constructed in is determined by the position of ON or USING CLAUSES: the last two tables encountered are joined when an ON or USING clause is encountered. For union or cross joins there is no ON or USING clause, so the tables on the left and right of these operators can be joined immediately. Thus A LEFT JOIN B LEFT JOIN C ON X ON Y, must first joins B and C and then joins the result with A, whereas A LEFT JOIN B ON X LEFT JOIN C ON Y first joins A and B, and then joins the result with C.

    In the DP4 SQL engine nested JOIN operations should be parenthesised. This is possibly not required by SQL2 syntax, though I could find no examples in my book which did not parenthesise them. Currently not all unparenthesised nested joins are compiled.

However inner,union or cross joins are combined with each other or a single outer join the end result will be the same. Where multiple OUTER joins are used this may not be the case since in a nested JOIN expression different ways of expressing the same join can yield differing rows with imaginary null records.