Introduction

This manual documents the following aspects of DP4:

  • What's New tells you about recent changes to this document. It is a good place to find out about new command line options for DP4 utilities.

  • Getting Started provides a quick overview of some of the most common tasks you will perform using or developing with DP4, with links into other parts of the DP4 documentation that will be of assistance to you.

  • DP4 Utilities contains information that will be of use to you when building a DP4 menu or creating scripts or batch files that run DP4 utilites. The Utility Reference lists the "core utilities" supplied as part of the DP4 base installation, together with a summary of all the command line options for each, and with links to more detailed documentation.

  • DP4 Error Messages contains a listing for the vast majority of error messages that may be generated by DP4 programs, together with their possible causes.

This manual assumes you know and understand the principles of DP4. For more detailed information refer to the Introduction to DP4 (dp4intro.chm), or the DP4 Developers' Guide (dp4dev.chm).


Access levels

Whenever you run a DP4 program your access is controlled by read and write access levels. When you log in, your access level is set up on the system. However, if you are run DP4 programs from outside the outside the DP4 login (for example from a command prompt), your read and write access levels will be set to 0 as a default. You can change this to any value up to 255 on by editing the Default User Preferences in DFSETUP.

Logging in as DP4 sets your access to 99. Higher access levels are only required for access to the DP4 base dictionary.

On a live system you may want to prevent the users acquiring access level 255 by running outside the system. You can do this by setting the Restrict DP4 from outside menu in the Console/Transaction Logging option of DFSETUP.


Analysis of Errors by Function

  • Functions which should not generate System or Fail Errors
  • Functions which generate Fail errors but not System errors
  • Other functions


AUDITOR

A utility to examine and print the records in the database log file, similar to the BROWSER utility

See Auditing the Transaction Log in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−LIVE | Opens log file and database in mode that allows other programs to update database (Introduced in 4.623).
−REMOTE | Look for the log file on the network
−CORRUPT | Enables you to see the actual log file that DBRESTOR/DBRECOV uses


AUTHOR

A utility to display or change HELP message status. You can run the utility interactively or specify one of these command tails (or both the last two).

When Author mode is ON the DP4 Author key (usually <Ctrl+O> and sometimes F9 also) will invoke the DP4 Help Message Editor, to allow you to set up context sensitive help for the current input field (edit box,button or checkbox).

When Author mode is OFF the DP4 Author key works the same as the regular Help Key (usually <Ctrl+J;> and either F1 (on Windows), or F10 (on other platforms)).

Command Tail | Description
−OFF | Turn Author and Training mode off
−ON | Turn Author mode on
−TRAINING | Turn Training mode on


AUTOQAB

Automatically generates screens and QA Build data entry programs based on the data dictionary.

See Automatic Program Generation in the QA Build Developer's Manual for further information about this program.

Command Tail | Description
−ALL | Create simple data entry and enquiry programs for all tables
−MAPS | Generate the maps, without the programs


AUXDISTR

An ADC program used with DP4 Networking to provide resilience and distributed data. Please refer to How to Load Multiple Resilience Configurations in the Guide to DP4 Networking and Resilience for information on how to use AUXDISTR. Command tails for AUXDISTR can be found here.


BROWSER

General purpose data entry and enquiry utility.

See Browsing the Database in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−ALLOW | Override integrity checking
−READONLY | Allow enquiries but no updates
−TABLE name | Restrict BROWSER to the named table


What's New in the DP4 Quick Reference Guide

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

New in 4.625

  • 28 Jan 2011 System warning 39 was not documented.

  • 1 Jun 2010 A new DP4 utility LOGCOPY is available. This utility allows a a log file for an open database to be backed up to another location, making it possible to combine the resilience of having a local log file, with the data security of having a backup on another machine.

New in 4.624

  • 23 Jul 2010 -CONFIG command tail added. This option was actually added in 2007 but was previously undocumented.

  • 26 Jun 2006 -LIVE command tail added.

New in 4.623

  • 28 May 2008 -EITHER command tail added. This command line is also accepted with the same meaning by MAKEDB since it contains COPYDB.

  • 26 Jun 2006 -LIVE command tail added.

New in 4.622

  • 27 Mar 2006 New page added on how to interpret DP4 errors reported in DP4 Error Log output.

  • 25 Nov 2005 System error 69 was not documented.

  • 31 May 2005 New command tail -full added to DBCHECK.

  • 14 Mar 2005 Information added about new FAIL error 15.

  • 11 Mar 2005 New command tails added to FIXDB23.

  • 15 Feb 2005 Information on new -copydb command tail for RECASTDB.

  • 12 Nov 2004 Information on new -xml command tail for UNLOAD.

  • 13 Aug 2004 Information on new system error 44 and on new system error 45

  • 13 Aug 2004 Information for the following utilities updated: DBBACKUP, DYNABACK, FDUMPM, PATCHER, REORGDB

New in 4.621

  • 15 Oct 2003 Information about DFPRINT added

  • 4 Oct 2003 New Getting Started section added

  • 29 Sep 2003 Most Utilities have either additional information or a link to other documents which describe how to use them.

  • 24 Sep 2003 Information added on converting Table, Field, or Role numbers to names (useful when analysing several DP4 system error messages). This information is applicable to all DP4 releases, not just 4.621

  • 6 Aug 2003 New -no_message option for PROGMAKE added

New in 4.620

  • 25 Jun 2003 Various corrections and updates to the information about error messages. Information about Fail Error 10, Fail Error 11 and NetBIOS return codes for NTBW and NTBMGR added.

  • 10 Apr 2003 The very useful -data command tail for MAKEDB is now documented (and some other previously undocumented tails)

  • 23 Dec 2002 Information about System Error 93 added

  • 17 Oct 2002 What's New Page added

  • 15 Oct 2002 Extensive information about new options in RECASTDB and how to control them using a configuration file

  • 26 Apr 2002 Information about using configuration file settings as new standard command tails for DP4 Enterprise added.

  • 08 Apr 2002 -pspc option added to USERDATA

  • 25 Feb 2002 -date option added to ROUNDER to check dates are valid

New in 4.523/4.619

  • 19 Oct 2001 Some pages rearranged to be easier to read, and information on new options in 4.523 (-server_name command tail for utilities).

  • 11 April 2001 Additional information on system error 87 and Fail Error 7

  • 9 March 2001 -silent command tail documented (for DBRECOV, DBRESTOR, SETSESSN, and SHUTDOWN).


COLLATE

Sets up a lower-to-upper case translation table in USERDATA.SYS and a collate sequence for data type U and M keys on a database.

See Changing Character Collate Sequence and Case Conversion in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−STANDARD | Sets database to use the standard collate sequence
−EXPORT | Exports current database collate sequence to file names database name.col
−IMPORT filename | Imports database collate sequence from filename to database


Configuration

After installing DP4 you may wish to run one or more of the Configuration Utilities to further configure your installation. There are sections on Configuration in both the Windows and Unix DP4 Installation notes, which give a quick overview of these programs.

For in depth documentation on configuring DP4, refer to the Guide to DP4 Configuration.


Console Log

The console log is a file called SYSLOG.PRN which records the usage of DP4 programs. As a minimum, the console log will provide a history of any System or Fail errors that occur whilst you are using DP4, so it may be useful to refer to this file if you need to find the details of an error that occurred earlier but has now been cleared from the screen. (On Windows NT you can also look in the Application Event log). The number and full error text is written to the file whether you are running DP4 from the menu or the command line. All occurrences of database recovery by DBRECOV are also recorded.

If you select the Record programs run in console log option in the Console/Transaction Logging Option of DFSETUP, the log will also record the user name, date, time and name of all DP4 programs run, and any program run via the DP4 menu.

If you keep the Console Log in a directory specified with a relative path name, and arrange for each user to run programs from a separate directory (for example their own home directory) you can keep a separate console log for each user. If you use an absolute path name then you will have one combined console log for all users.

The Console Log is normally limited in size. When the size limit is reached the current log is renamed SYSLOG.BAK (removing any previous SYSLOG.BAK at the same time) and a new console log is started.


COPYDB

Copies a database structure from one database to another.

See Copying the Database Structure in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−EXTRACT | Extract the database structure to an ASCII file
−POST | Post the database structure from an ASCII file
filenames | List of files to process when posting
−DIRECT −QUICK | Construct direct links in MAKELINK phase, (not the indirect links required by Report Writer and QAB)
−DISTANCE n | Create indirect links only up to distance n in MAKELINK phase. (The default is 4)
−BYNUMBER | Specify that number is to take precedence over name in Table/Field matching
−NOPAUSE | Do not pause on warnings while posting
−AUTODEFAULT | Copy the autoincrement field settings from source database
−EITHER | When extracting selected tables, include index information if either the child or parent table is one of the extracted tables. The default behaviour only includes indexes where both tables are extracted tables, which is usually not helpful.
−NODELETE | Prevent the existing table structure from being deleted


DBBACKUP

From release 4.526/4.622, DBBACKUP and DYNABACK are essentially the same program. The only difference between them is that DBBACKUP opens the database in exclusive mode. For a complete list of command tails supported in 4.526/4.622 refer to DYNABACK.

Backs up the database to floppy disks or tape with option to also copy the transaction log file to disks. This program is mainly retained for compatibility with older releases. DYNABACK is an enhanced backup utility which can be run without interrupting normal operation and which can also check the integrity of your database and backups.

See Backing up a Database in the DP4 Developer's Manual for further information about backing up databases.

Command Tail | Description
−DISK NAME | Specifies the disk on which the backup is held
−SPACE n | Leave n Kb (Kilo bytes) free space on target disk
−FORMAT | Specify target disk formatting (looks for a user-supplied file called FORMBKP.BAT)
−TAPE | Only available up to release 4.525/4.621) Backs up the database to tape streamer or other non-standard backup device (looks for a user-supplied file called TAPEBKP.BAT, which should contain the relevant tape software commands). The current database name will be substituted as variable %1 in this batch file
−LOGONLY | Copy Transaction Log only to disks
−VERIFY | Turn verification on
−NOVERIFY | Turn verification off
−SYSTEM | Backup the SYSTEM database
−COMMENT text | Optional comment, up to 32 characters, displayed when restoring a database


DBCHECK

Makes various consistency and integrity checks on the database including status, file usage and record count. It is important to run this program at least once during your backup cycle (the period for which you keep backup media before re-using it for a new backup). For further information on this utility see Checking a Database in the DP4 Developer's Guide.

Command Tail Description

−LOCAL

Reduces the load on the DBMS and improves performance when the database resides on the same machine as DBCHECK

−STATUS

Select status

−USAGE

Show status and file usage

−CHECK

Check database integrity

−COUNT

Select record count (can redirect to printer)

Supply any of the four command tails above to suppress the display of the DBCHECK menu

−CORRUPT

Check a database which has the corrupt flag set

−FULL

Introduced in release 4.622/4.526 this option causes additional consistency checks to be made when checking the index file. This will almost always detect corruptions that would only otherwise show up with dynachek.

−HEAP NNNN

Set heap size (used for file buffers and so on.). Default for 32-bit systems is 4096 (4 Mbytes)

−PASS

Pass on error and continue checking

−QUICK

Speed up the integrity check by omitting some tests. If you use this option inconsistencies between the data and index file will not be detected. On most machines there should be no need to use this option.

−BATCH

Checks the database in "batch mode" without user interaction. The result is recorded in one of two files:

  • DP4PASS.MSG if the database passes

  • DP4FAIL.MSG if the database fails, in which case the cause of the failure is also recorded

DBCHECK does not delete these files it initialises, so you may need to do this manually if you intend to make use of these files.

Additional tails actioned with −BATCH

−CHECKSUMFAIL

DBCHECK reports error if checksum incorrect

−CHECKSUMAUTO

DBCHECK resets checksum to correct value if necessary.

If neither tail is specified no error is reported but checksum is not reset.


DBERA

Maintains era records on the database

DBERA is designed to:

  • Make it easier for you to keep track of changes you have made to your database during QA Build system development.

  • Simplify the task of distributing changes to other developers working on the QA Build system. See Version Control in the QA Build Developer's Manual.

In future, other programs that create export files for transferring source-code or dictionary information (MAPEDIT, COPYDB, REPSETUP, IMPSETUP) may be enhanced in the same way.

Using DBERA

When you run DBERA, you see the following options in the menu bar:

File | Specifies the application database you want to use. You are presented with a menu of existing era records; none will exist initially
Insert

Allows you to create a new era record. Having selected this option, a window appears in which you must specify:

  • Your reference

    Enter the name of the era. You can use any characters, but only letters and digits are significant.

  • Internal reference

    This is calculated by the system. It is 1 to start with and then incremented by 1 for each new era.

  • Brief description

    Two lines of text describing the era. (Optionally, you can enter extended documentation - see the Details option)
View | Toggles dispaly being sorted on era name and by era time.
Delete | Deletes the currently highlighted era record
Details | Allows you to enter more extensive documentation for an era records. This option gives you access to a full screen editor, similar to the DP4ED, with text editing, box drawing and text colouring facilities.


DBRECOV

If rollback logging is enabled using DFSETUP, this utility recovers a database after a system crash. It is usual to arrange for DBRECOV to be run automatically as part of the startup for a DP4 system, so that end users do not have to run this program for themselves.

See Recovering a Database in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−CHECK | (From 4.522/4.618) Checks integrity of recovered database after fast recovery with DCHECK.
−CORRUPT | (From 4.522/4.618) Allows fast recovery of databases that have known faults - normally DBRESTOR would be forced.
−NORESTORE | (From 4.522/4.618) Disables automatic DBRESTOR in event of fast recovery failure.
−PAUSE | Pause after database recovery and displays status information.
−SILENT | Suppresses all screeen input and output.


DBRESTOR

Restores a database from backups held on disks or tape, with the option to recover roll-forward transaction logs and apply them to the database

See Restoring a Database in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−DISK name | Specify the source drive (for example A:) where the backup is held. Include a trailing slash or backslash when restoring from a specific directory on the disk.
−LOGONLY | Recover the transaction log only - omit the database restore
−NOVERIFY | Turn verification off
−SILENT | Suppresses all screen output and input. Note that this means the backup must be restorable without the need to change disks.
−SYSTEM | Restore the SYSTEM database
−TAPE | Restore the database from a Tape Streamer or other non-standard backup device, using a user-supplied batch file called TAPERST.BAT, which should contain the relevant tape software commands. The current database name is supplied as variable %1 to this batch file
−VERIFY | Turn verification on


Keyboard Interface

This page tells you about the default keyboard interface used by all DP4 programs. The interface may be changed to some extent by using the Keyboard Customisation facility. The keyboard interface is also dependent on your keying convention, selected when you create userdata.sys by running USERDATA. There are three keying conventions, which differ principally in how they handle the Tab and Enter keys (or more strictly, keys designated as Tab or Cr in your userdata.sys).

  • Traditional Mode

    In this mode, in effect if userdata.sys is created without -saa or -windows, the Cr (Enter) key always has the meaning of "Accept Current Input", and the Tab key usually means "Accept Everything":

    • In a dialog, Enter accepts the current value of edit fields, and moves focus to the next field, or the next line of a multi-line edit field. On the final edit field in a dialog without OK and Cancel buttons pressing Enter will close the dialog, possibly displaying a "Save/Abandon" menu.

      Pressing the Tab key when the focus is not on a button, closes the dialog, possibly displaying a "Save/Abandon" menu first.

    • In a menu or on a button anywhere, Enter causes the associated action to be selected, and pressing Tab moves to the next button.

    • In a window that allows you to select multiple items, use Enter to toggle whether an item is selected or not, and use Tab to complete the process of selecting items.

    The Space key toggles the state of a checkboxes.In menus the Space key causes focus to move to the next option. In dialogs (especially inside PROGMAKE), the space key sometimes behaves like the Prompt key.On Microsoft Windows, when focus is on a button pressing and releasing Space without pressing any other keys causes the button action to be performed. (In text based operating systems pressing space moves focus off the button)

  • SAA Mode

    In this mode, in effect if userdata.sys is created with the -saa option, Tab usually means "Accept input and Move" and Enter usually means "Accept Everything".

    • In dialogs the Tab key usually moves to the next input field, or the next line of a multi-line input field. Pressing Tab on the last control in a dialog will usually wrap around to the first field, (or it may have no effect if the Field Tab Wrap property is not set.

      Pressing the Enter key completes the dialog, except if focus is on a button, in which case it performs the action on the button. In dialogs the Enter key usually means "Perform the action associated with the default button", because when a button has focus it automatically becomes the "default button".

    • In menus, the Tab and Enter keys both select the currently highlighted action, except if the menu is built using buttons, in which case the Tab key moves round the buttons. (So menus behave the same way in SAA and Traditional mode)

    • In a window that allows you to select multiple items, use Enter to toggle whether an item is selected or not, and use Tab to complete the process of selecting items, again the same as in Traditional mode

    In menus, the Space key works in the same way as in Traditional Mode

  • Windows Mode

    The explanation of this mode is only correct for 4.619 or later: in earlier multi-line edit fields were handled as for SAA mode.

    In this mode, in effect if userdata.sys is created with the -windows option, Tab usually means "Accept input and Move" and Enter usually, but not always, means "Accept Everything":

    • In dialogs the Tab key usually moves to the next input field, even on a multi-line input field. Pressing Tab on the last control in a dialog will usually wrap around to the first field, (or it may have no effect if the Field Tab Wrap property is not set.

      Pressing the Enter key completes the dialog, except if focus is on a button, in which case it performs the action on the button, or if focus in on a multi-line edit control, in which case it moves to the next line of the edit control (and on the last line of the edit control moevs to the next control).

    • In menus, the Tab key has no effect, unless the menu is built using buttons, in which case the Tab key moves round the buttons. The Enter key selects the currently highlighted action.

    • In a window that allows you to select multiple items, use Space to toggle whether an item is selected or not, and use Enter or Tab to complete the process of selecting items.

    In menus, the Space key selects an action. In buttons and checkboxes the space key works the same as in the other modes.

You can use whichever convention suits your tastes. However a few Help messages for standard DP4 utilities are not accurate if -windows mode is in effect. It is however, the convention that will probably best suit experienced users of Microsoft Windows.

Default Key Assignments

In the table below, entries in the Ctrl+Key column work on all keyboards unless otherwise noted, entries in the PC Keyboard column work on PC style keyboards (except under some defective terminal emulators), unless SAA or Windows keying conventions are in effect and there is a different entry in the SAA/Windows column . Entries in the third column work with SAA and Windows keying convention

Function | Ctrl + key | PC keyboard | SAA/Windows mode
Backspace | Ctrl + H | Backspace |
Block mode | Ctrl + K |  |
Char left | Ctrl + S | ← |
Char right | Ctrl + D | → |
Copy block | Ctrl + L |  |
Cr | Ctrl + M | Enter |
Delete word | Ctrl + T |  |
Delete char | Ctrl + G | Del |
Delete (rest of) line | Ctrl + Y |  |
Display keys | Ctrl + _ |  |
Draw box | Ctrl + ] |  |
Dump screen to file | Ctrl + ^ |  |
End of line | Ctrl + \ * | End |
Escape | Ctrl+[ | Esc |
Help | Ctrl + J | F10** | F1
Help Author**** | Ctrl + O | F9 | none
Insert/Split line | Ctrl + N |  |
(Toggle) Insert mode | Ctrl + V*** | Insert |
Line down | Ctrl + X*** | ↓ |
Line up | Ctrl + E | ↑ |
Page down | Ctrl + C*** | Page down |
Page up | Ctrl + R | Page up |
Prompt/Paintbrush | Ctrl + P |  | F4 (but not in Windows)
Previous field | Ctrl + @ * | Shift + Tab |
Redirect Key | Ctrl + B |  |
Scroll up | Ctrl + Z | Ctrl+↓ |
Scroll down | Ctrl + W | Ctrl+ ↑ |
Start of line | Ctrl + Q | Home |
Tab | Tab | Ctrl+I |
Undo | Ctrl + U |  |
Word right | Ctrl + F | Ctrl + → |
Word left | Ctrl + A | Ctrl + ← |

* Not supported on a PC

** The F10 key is reserved by Windows, so this key is not available

*** This Ctrl+Key combination will be interpreted as a copy/cut/paste type command in edit fields with text selected

**** Help Author is only available if you turn on help authoring mode with AUTHOR. If help authoring is turned off, the author key works like the 'Help' key. F9 is set up as the help authoring key

Notes

Ctrl+S can usually be used to pause report type programs. When a program is paused Ctrl+C will stop it, any other key will cause the program to resume. In this situation the normal function of the keys pressed is ignored. On dumb terminals Ctrl+S functionality is sometimes hard coded into the terminal itself. Ctrl+S cannot be used as an normal editing key on such terminals.

In SAA mode, but not in a Windows userdata.sys, F3 is mapped to Esc. F3 is also mapped to Esc for some terminal types, because Esc is used as a leadin for a function key sequence and is not recognised.


DFPRINT

Prints or views files created by DP4 for output devices based on the DFPRINT device group. This utility is usually invoked automatically as required by the DP4 terminal manager, but you can also invoke it manually to view or reprint a file created earlier. DFPRINT cannot open ordinary text files, or files created by DP4 for any other device group.

For more information See Printing using DFPRINT in the Guide to DP4 Configuration.

Command Tail | Description
−AUTO | File is processed according to the information written to it when first created
filename | Specify the filename to be viewed/printed


DFSETUP

Sets up the DP4 system (for further information see DFSETUP - DP4 System Setup utility in the Guide to DP4 Configuration).

Command Tail | Description
−ISSUE pathname | Produces a new blank copy of the system data file on the specified path. You must end the path with the appropriate separator, for example '\', '/' or ':'
−CLIENT name | Selects client name
−DEVELOPER nr | Selects developer number
−LOW nr | Selects low serial number
−HIGH nr | Selects high serial number
−TYPE XX | Selects client type
−ENABLE XXX | Including a 'Y' in the first, second or third positions lets you modify the developer number, serial number and client name respectively
−FROM pathname | Directs DFSETUP to use DATAFIT.SYS from pathname (for example, A:)
−ANYKEY | Reassign alphanumeric key
−KEEPTYPE | Keep current settings for new terminal type
−REMOTE os_name | Set up licence file on the server machine using directory name conventions for specified operating system (name can be MSDOS (also use this for Windows), OS2,NOVELL, FLEXOS, UNIX)
−NUMBER | For printer setup, allows device numbers to be explicitly assigned
−USER | Change user preferences only
−Q X | Re−program the 'Q' key, substitute an alternative key to exit the function key setup screen


DFTYPE

Types a file. Colour information put in the file by DP4ED is displayed. Files can be directed to the printer by using the Standard Printing Command Tails. In general you will find it better to use the VIEW program instead of DFTYPE.

Command Tail | Description
−CLEAR | Clear the screen first
−PAUSE | Pause after each screen of text
filenames | Specify the filenames to be typed


DP4

This is the DP4 Menu utility , which runs the menus set up for the user. All the standard utilities can be selected from the DP4 system main menu.

Command Tail | Description
−USER name | Automatically log on as the named user - the password is still requested unless it is blank
−SMALL | Forces every option to be invoked with the %system parameter
−HIDDEN | Allows hidden options to be selected

DP42A

(MS-DOS only) This is an auxiliary menu utility, used by DP4, and which can be used as a direct replacement for it. Used directly it uses up 6K less memory than DP4. However, 10K more memory is then used, when you specify the %SYSTEM option to run a non-DP4 program


DP4 Error Messages

The information in the following sections discuss whether or not each error is considered to be recoverable. This refers to the recommended action for a program should take when the error is reported, and does not refer to the status of DP4 databases. Recovering from DP4 errors is only possible in programs that use the DP4 interface using C or C++. Standard DP4 utilities will usually terminate when one of these errors is reported. If you are a programmer and are attempting to catch and continue execution after of one of these errors, you need to be careful to guard against the possibility of an endless succession of error messages.

Generic DP4 error messages fall into three main categories. If you want to find out more about a particular error it is important to know which category it comes from, because the same error number may exist in several categories, with a different meaning in each.

  • DP4 System errors are either displayed using maps from the SYSTEM mapset on the SYSTEM database, or, from 4.620, text held in the DP4 configuration file.

  • DP4 Fail Errors are held in and displayed by the FAIL program. Fail errors are often caused by an error reported by the operating system, and in this case the message from the operating system will be displayed as well. From 4.620 the FAIL program is not used to display these errors, and the text is held in the DP4 configuration file.

  • Loader errors, currently specific to Windows, are displayed by the DP4 loader program (srvw32 or srvwce) when there is a problem starting or stopping the DP4 service. The text is taken from the DP4 configuration file.

All standard DP4 utilities report errors using the sources of error text described above. However, programs that use DP4 might not report errors in a standard way if they attempt to handle errors. However, if DP4 error logging is turned on and the debug_error setting value is true, DP4 will always additionally report errors to the error log in numeric form. The exact format of the report will vary in this case, but you can still determine the DP4 error message. This is explained in Interpreting DP4 Error log Error Messages.

  • System Error Messages
  • Fail Errors
  • Loader Errors
  • The Console Log
  • How to Find a Table, Field or Role Name from a Number shown in a System Error Message
  • Analysis of Errors by Function


Running DP4

The easiest way to use DP4, at least until you are familiar with the various programs, is via the DP4 menu utility. For all the supported operating systems, you can run the DP4 menu by typing:

DP4

Provided that your environment is set up correctly, the DP4 menu utility will ask you to log on. On a new system, you can log in as the default user: DP4. This user has the highest Access Level available from within the DP4 menu systme. No password is initially required with this user name. (You will want to change this on a live installation to prevent unauthorised access). A DP4 System can be set up to have many different menus, each appropriate for a different type of user. Logging onto DP4 and using the DP4 menu is described in more detail in the Getting Started section of the DP4 Developers's Manual.

You can include the DP4 command in a startup file (e.g. AUTOEXEC.BAT). Make sure the menu is correctly set up before you do this, or you could become 'trapped' in a non-functional menu : in many cases DP4 will not allow you to escape from it - this is a deliberate feature as DP4 menus are often used in "turn key" systems.

If you log on as DP4 (or DATAFIT), the menu provided with the system allows access to most DP4 utilities, from building a new database to running a finished system. You can set up your own specialised menus for the users on the system using the MENUEDIT utility.

You can run non-DP4 software from within the DP4 environment, either by using the 'Run Program ' option on the DP4 menu, or by setting up a menu option that calls the non-DP4 program.


DP4 System Error 2

Message

DP4 System error 2. Origin: Program bug
Map %1 not on screen, so map %2 cannot be displayed over it


DP4 System Error 3

Message

DP4 System error 3. Origin: Program uses withdrawn DP4 functions
Illegal function number (%1) passed to terminal manager

Comment

Non-recoverable - because there is a mismatch between the libraries used to generate the program and the terminal manager being used.


DP4 System Error 4

Message

DP4 System error 4. Origin: Internal DP4 limit exceeded
Too many maps on the screen - limit is %1

Comment

This error is not used in 4.600.


DP4 System Error 5

Message

DP4 System error 5. Origin: Improper installation
Base data dictionary of database out of date. FIXDB22 required

Comment

This error ought not to be generated in 4.600 because it relates to the usage of pre-4.400 databases.


DP4 System Error 6

Message

DP4 System error 6. Origin: Probable program bug
Work file error from terminal manager
Error type %1 on table %2

Comment

Type 0 means you are calling trm_mem_find() or trm_mem_post() on a table that has not been described with trm_mem_describe() or whose typenr field has become corrupted. See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.

Type 1 means you have tried to call trm_mem_describe() on too many tables.

Type 2 means you are trying to change the length of a record in the memory work file

Type 3 means the work file is corrupted. This error used to be seen under FLEXOS due to an operating system bug in the handling of RAM-disk files. The other most likely causes are stack overflow inside TRM (seen under PM), and programs which have inadvertently written to the memory workfiles directly, by using tf_write() on a file handle which accidentally happens to be the one for the memory workfile. (Under several operating systems this file has the DP4 handle 0 so it is quite often seen).

Non-recoverable.


DP4 System Error 7

Message

DP4 System error 7. Origin: Improper installation
Keyboard generated system failure

Comment

This happens if you press <Ctrl+End> and have a USERDATA which was created with -TESTFAIL.

You might want to recover from this error to test error recovery in a simple way.


DP4 System Error 8

Message

DP4 System error 8. Origin: Probable program bug
Work file error from database manager
Error type %1 on table %2

Comment

The error types are the same as for DP4 System Error 6 .

Non-recoverable.


DP4 System Error 9

Message

DP4 System error 9. Origin: Program bug
No record for fetch_workfile() on type %1 index %2

Comment

This error is generated when you call wkf_fetch() without having previously called wkf_post(). It is only generated if you use the wkf_fetch()/fetch_workfile() function. The source code of this function is distributed so you can prevent the error by modifying the function.


DP4 System Error 10

Message

DP4 System error 10. Origin: Program bug
Database number %1 not opened for user %2

Comment

The database number and process number combination specified is invalid, probably for one of the following reasons:

  • db_nr has become invalid as a result of a failed call to db_open()
  • db_nr has become invalid due to a previously open database being closed
  • The df_process varieable is invalid.

You are unlikely to be able to recover from this error as it indicates a severe bug in your program. Most functions could return this error.


DP4 System Error 11

Message

DP4 System error 11. Origin: Improper installation
Illegal licence number - contact your installer

Comment

You can only recover from this situation by obtaining a proper licence file.


DP4 System Error 12

Message

DP4 System error 12. Origin: Operator error
Another user has exclusive access to this database

Comment

You can only recover from this error if the database you were trying to open is not needed. An example might be a program that periodically transferred data from one database to another. It might just decide to wait for a while if this error came back.


DP4 System Error 13

Message

DP4 System error 13. Origin: Operator error
Another user has access to this database

Comment

You can only recover from this error if the database you were trying to open is not needed. An example might be a program that periodically transferred data from one database to another. It might just decide to wait for a while if this error came back.


DP4 System Error 14

Message

DP4 System error 14. Origin: Operator error/Internal DP4 limit
Too many databases open (limit is %1)

Comment

You can only recover from this error if the database you were trying to open is not needed. An example might be a program that periodically transferred data from one database to another. It might just decide to wait for a while if this error came back.


DP4 System Error 15

Message

DP4 System error 15. Origin: Unknown
Database index file not found

Comment

Possible causes are that:

  • The database name was spelt wrongly
  • The DP4 licence file is corrupt or specifies the location of database files incorrectly.
  • DP4 is not able to read the correct licence file. Refer to Names and Locations of Configuration Files in the Guide to DP4 configuration for information on where to locate this file, and how to ensure DP4 can find it.
  • The software is loaded incorrectly (for example, networking components).

The best way to avoid the first cause of this error is to pass the MISSING_OK flag to db_open() and to check that the returned database number is not -1


DP4 System Error 16

Message

DP4 System error 16. Origin: Unknown
Database data file not found

Comment

Possible causes are that:

  • The database name was spelt wrongly
  • The DP4 licence file is corrupt or specifies the locataion of database files incorrectly.
  • DP4 is not able to read the correct licence file. Refer to Names and Locations of Configuration Files in the Guide to DP4 configuration for information on where to locate this file, and how to ensure DP4 can find it.
  • The software is loaded incorrectly (for example, networking components should be loaded but are not, or are pointing at the wrong server).

The best way to avoid the first cause of this error is to pass the MISSING_OK flag to db_open() and to check that the returned database number is not -1


DP4 System Error 17

Message

DP4 System Error 17. Origin: Unknown
Database not properly closed. Run DBRECOV

Comment

A program might try to recover from this error by spawning DBRECOV itself and reopening the database. However, it is our view that the user should be encouraged to do this manually, so that he is motivated to discover the cause of the database not being closed.


DP4 System Error 18

Message

DP4 System error 18. Origin: Program bug
Database number %1 cannot be reopened

Comment

This will never occur in a user program.


DP4 System Error 19

Message

DP4 System error 19. Origin: Improper Installation

Database manager and database are from incompatible versions. You 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.

The most likely cause of this error is that you have updated the database with a 4.420 or later database manager but are now using an earlier version of the database manager.

Comment

Non-recoverable.


DP4 System Error 20

Message

DP4 System error 20. Origin: Program bug, installation or database corruption
Table number %1 not found on database

Comment

If you have a program designed to cope with optional tables, you should determine whether the table is present or not first.

Non-recoverable after the event.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem. However, for this error it is unlikely that you will be able to obtain the table name.


DP4 System Error 21

Message

DP4 System error 21. Origin: Database corruption
Key extraction not implemented for data type %1

Comment

This error is extremely unlikely and you should not try to recover from it.


DP4 System Error 22

Message

DP4 System error 22. Origin: Program or dictionary bug
Role not found on database

Comment

You have called one of the following obsolete functions: copy2child(), copy2parent(), cycle(), ftch2nd(), reach(), scanftch(), scanreach() or blk_f2nd() specifying an invalid role name.


DP4 System Error 23

Message

DP4 System error 23. Origin: Program or dictionary bug
Table %1 index %2 role combination not found on database

Comment

You have tried to access a table through a non-existent secondary index.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 24

Message

DP4 System error 24. Origin: Program or dictionary bug
Index specified in FTCH2ND is not set to update

Comment

You have tried to access a table through a secondary index which is turned off. The index should be turned on and built with REORGDB.

Prior to release 4.621 there is no information given about which table and index is causing the problem, and the only way to discover this is to get the system developer to debug the application (perhaps using AUXDEBUG as described in the DP4 ADC Developer's Guide.


DP4 System Error 25

Message

DP4 System error 25. Origin: Improper Installation
Index specified in FTCH2ND is not up to date
(REORGDB is required)

Comment

You have tried to access a table through a secondary index which is turned on but requires rebuilding with REORGDB : whenever a new secondary index is created the index needs to be built before it can be used. This should normally be done before a system is installed. If an index is turned on as part of an upgrade of a live database, then the installer should provide a script that causes REORGDB to be run as part of the upgrade process.

Prior to release 4.621 there is no information given about which table and index is causing the problem, so a full REORGDB is probably the quickest way to resolve the issue. Also the error was incorrectly described as being due to a Program or Dictionary bug.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 26

Message

DP4 System error 26. Origin: Program bug
Database must be opened in exclusive mode for
SET_STATUS or SET_GENERATION

Comment

This error will not occur in user programs.


DP4 System Error 27

Message

DP4 System error 27. Origin: Corrupt database
Kill cannot find prime index for table %1

Comment

This error has never been known to occur, but if it does it indicates that there is a problem with the database.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 28

Message

DP4 System error 28. Origin: Program or dictionary bug
Table %1 specified in AUTOINC is not an autoinc table

Comment

A program is trying to get an auto-increment key value from a table that does not have the auto-increment property set. Either the program or the database needs to be changed.

Attempting to carry on after this error might cause the wrong record to be updated by a program.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 29

Message

DP4 System error 29. Origin: Database corruption or internal DP4 error
Field %1 specified in AUTOINC is not type N

Comment

This error has never been known to occur, but if it does it indicates that there is a problem with the database.


DP4 System Error 30

Message

DP4 System error 30. Origin: Program bug
Unrecognised program or database status

Comment

This error has never been known to occur, but if it does it indicates that there is a problem with the database.

Comment

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 31

Message

DP4 System error 31. Origin: Operator error
Database must be backed up

Comment

The user must run DBBACKUP or SETSESSN before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 32

Message

DP4 System error 32. Origin: Operator error
Index analysis must be run

Comment

The user must run MAKELINK before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 33

Message

DP4 System error 33. Origin: Operator error
Index analysis followed by reorganisation required

Comment

The user must run MAKELINK, then REORGDB before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 34

Message

DP4 System error 34. Origin: Operator error
Index scrutiny must be run

Comment

The user must run SETLINK before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 35

Message

DP4 System error 35. Origin: Operator error
Index scrutiny followed by reorganisation required

Comment

The user must run SETLINK, then REORGDB before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 36

Message

DP4 System error 36. Origin: Operator error
Database reorganisation required

Comment

The user must run REORGDB before running this program on the database which cannot be opened.

Programs may continue after this error, if they can do anything useful on another database.

This error may occur when calling db_open(). db_open() returns -1 if it recovers from a system or fail error.


DP4 System Error 37

Message

DP4 System error 37. Origin: Operator error/Installation
Network manager program not running

Comment

You should avoid this error by running with the correct level of resilience.


DP4 System Error 38

Message

DP4 System error 38. Origin: Improper installation
Database update not implemented by read-only version of server

Comment

Your system is not configured properly. This error only happens if you are using SRV2TINY.


DP4 System Error 40

Message

DP4 System error 40. Origin: Program bug
Output not implemented for data type %1 (%2)

Comment

You are calling show(), passing an invalid data type. If this error comes from a QA Build or Report Writer program, it may indicate a corrupt database.

Another possible cause of the problem is a mismatch between the library used to build the program and the terminal manager. For example, 4.51x supported data type X as a means of controlling colour on a character-by-character basis, but this is not supported in by the current 4.4xx or 4.6xx TRMn programs.


DP4 System Error 41

Message

DP4 System error 41. Origin: Program bug
Data entry not implemented for data type %1 (%2)

Comment

You are calling a data entry function, passing an invalid data type. If this error comes from a QA Build program, it may indicate a corrupt database.

Another possible cause of the problem is a mismatch between the library used to build the program and the terminal manager.


DP4 System Error 42

Message

DP4 System error 42. Origin: Program bug
Buffer of incorrect type or length used for bf_fetch()
Attempting to read data of length %1 and type %2

Comment

Non-recoverable.


DP4 System Error 43

Message

DP4 System error 43. Origin: Program bug
Illegal data size (%1) from function %2 passed to database manager

Comment

Non-recoverable.


DP4 System Error 44

Message

DP4 System error 44. Origin: Unknown
Database compression information file not found

Comment

The most probable cause of this error is:

  • A database using facilities introduced in release 4.525/4.626 has been copied by a script or program that has not been updated to copy .DCI files.


DP4 System Error 45

Message

DP4 System error 45. Origin: Unknown
Database data pointers file not found

Comment

The most probable cause of this error is:

  • A database using facilities introduced in release 4.525/4.626 has been copied by a script or program that has not been updated to copy .PTR files.


DP4 System Error 50

Message

DP4 System error 50. Origin: Program or dictionary bug
Posting to index-only table %1

Comment

An index only table is not allowed to contain data, and attempting to post data to such a table will cause this error. If it arises either the program or the database needs to be changed.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 59

Message

DP4 System error 59. Origin: Program bug
RETRIEVE cannot be used unless enabled when the database opened


DP4 System Error 68

Message

DP4 System error 68. Origin: Operator error
Correct transaction log file not found

Comment

A frequent cause of this problem is that a log file for a previous session of the database has not been deleted. You could attempt to recover from this error by spawning SETSESSN -DELETE. However, you would have to close the database and reopen it, and redo database access up to that point, so it is probably not worth the programming effort involved unless you trap the situation on start up: your program should perform some trivial database update when it starts so that the user is made aware of the problem before he has done any useful work.


DP4 System Error 69

Message

DP4 System error 69. Origin: Operator error
You cannot run the online backup program against this database, as another instance of it is already running.

Comment

This message was missing from dp4.ini files for releases 4.620,4.621 and 4.622, so the message "No message text available" was displayed instead, together with spurious numeric values.A frequent cause of this problem is that a log file for a previous session of the database has not been deleted. You could attempt to recover from this error by spawning SETSESSN -DELETE. However, you would have to close the database and reopen it, and redo database access up to that point, so it is probably not worth the programming effort involved unless you trap the situation on start up: your program should perform some trivial database update when it starts so that the user is made aware of the problem before he has done any useful work.


DP4 System Error 70

Message

DP4 System error 70. Origin: Program bug
Read-only program cannot update database


DP4 System Error 73

Message

DP4 System error 73. Origin: Installation limitation
Limit on number of records exceeded

Comment

This error will not occur if you have a properly licenced version of DP4.


DP4 System Error 74

Message

DP4 System error 74. Origin: Installation limitation
Limit on database file size exceeded

Comment

This error will not occur if you have a properly licenced version of DP4.


DP4 System Error 75

Message

DP4 System error 75. Origin: Unknown
Database manager lock timed out

Comment

This message can only occur when AUXDISTR is in use and a two phase commit is performed. The message may arise when the maximum time between the phases is exceeded on one or more servers, so that the commit is failed.


DP4 System Error 76

Message

DP4 System error 76. Origin: Improper installation
Rollback logging must be turned on

Comment

Non-recoverable.


DP4 System Error 77

Message

DP4 System error 77. Origin: Improper installation
Transaction logging must be turned on

Comment

Non-recoverable.


DP4 System Error 78

Message

DP4 System error 78. Origin: Program bug
No currently selected record to be updated in table %1

Comment

This error will not occur unless you have used the -EXPERT facilities of MAKEDB to enable non-unique keys.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 79

Message

DP4 System error 79. Origin: System Constraint
Program tried to update database while updates
disallowed. A database backup is required

Comment

This error will only occur after the user has already been warned that the database is in read only mode.


DP4 System Error 80

Message

DP4 System error 80. Origin: Improper installation/corrupt database
Cannot convert table %1 from generation %2.

Comment

This error will only occur if there are missing data independence records or the generation field of a record on the database has been corrupted.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 81

Message

DP4 System error 81. Origin: Corrupt database
Data independence not implemented for data type %1

Comment

This error will never occur unless your database has corrupted data independence records.

Non-recoverable.


DP4 System Error 83

Message

DP4 System error 83. Origin: Improper installation/corrupt database
Program generation %1 is greater than db generation %2

Comment

Non-recoverable.


DP4 System Error 84

Message

DP4 System error 84. Origin: Improper installation/corrupt database
Table %1 not found in swap list

Comment

This error cannot except in programs written for a Big Endian processor (i.e. certain Unix/Linux platforms).

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 85

Message

DP4 System error 85. Origin: Program bug/improper installation
Record type %1 being updated has incorrect length %2

Comment

There is a mismatch between a program and database, or the program's data area has been corrupted.

Non-recoverable.


DP4 System Error 86

Message

DP4 System error 86. Origin: Internal DP4 error
Db manager internal error %1 in table nr %2
Contact Itim Technology Solutions

Comment

This indicates that there is a bug in SRVn. Non-recoverable.


DP4 System Error 87

Message

DP4 System error 87. Origin: Database corruption
Database corruption type %1 in table nr %2

Comment

Your database is corrupt. You need to restore a back up and apply log files, or (if you do not have a back up) you can try running REORGDB -CORRUPT, provided DBCHECK does not report errors when checking the data file.

Non-recoverable.

Two numbers are displayed with this error. The first number indicates the type of corruption found. The second error is usually a record type number or length. The meaning of the various possible numbers is as follows:

Number | Meaning
2 | An index node has an invalid length, (or possibly a pointer to an index node was corrupt). Index node lengths should be between 4 and 500. The length found is displayed. If the number appears to be valid then it is not the node length that is invalid, but the length of the record containing the node.
3 | An index node in the list of free nodes has a bad length. The length found is displayed. Either the record length of the node is bad, or the node length is not 4, indicating that the node is not in fact free. This error could arise in older versions of DP4 after a DBRECOV.
4 | A linked list entry points to a record with an illegal length or the wrong type number. The type number found is displayed. Linked lists are only used when non unique primary keys are used. This feature is no longer offically supported so this error should never arise in practice.
5 | An index entry points to a record with an illegal length or the wrong type number, indicating that either the data file is corrupted or that the index contains a corrupt entry. The type number of the record that was expected is displayed. See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.
8 | When reusing an area in the data file that should contain a hole, either the hole length was wrong or the type number was non zero indicating the record is not actually a hole. The type number found is displayed. This error could arise in older versions of DP4 after a DBRECOV.
6,7,9 | Hash area corrupt. These errors could only occur if hashed indexing, which is no longer supported, is selected.
10 | An index node contains inconsistent data.
11 | The database header (at the start of the index file) is corrupt.
12 | An index record contains a corrupted key.


DP4 System Error 88

Message

DP4 System error 88. Origin: Program bug
Illegal parameter type %1 value %2 in DBMS

Comment

This is similar to error 3, but for functions in the database manager. It is extremely unlikely to arise as the set of functions in the database manager is very rarely changed.


DP4 System Error 89

Message

DP4 System error 89. Origin: Program bug
Illegal commit nesting type %1 value %2 in DBMS

Comment

This error is no longer used from version 4.521/4.617 on. It sometimes used to occur when AUXDISTR was in use, due to bugs in that program.


DP4 System Error 90

Message

DP4 System error 90. Origin: System constraint
Insufficient space on data file disk

Comment

The system believes there is less than the designated minimum amount of space on the data file disk.

This error has frequently been encountered spuriously under various versions of UNIX, but cannot easily be recovered from.


DP4 System Error 91

Message

DP4 System error 91. Origin: System constraint
Insufficient space on index file disk

Comment

The system believes there is less than the designated minimum amount of space on the index file disk.

This error has frequently been encountered spuriously under various versions of UNIX, but cannot easily be recovered from.


DP4 System Error 93

Message

DP4 System error 93. Origin: System constraint
The DP4 server denied permission for function %1
Contact your system administrator for more information

Comment

A client program is calling a DP4 remote file function or remote execute function (sf_() functions or use of the tsrun utility)), but the server is conifugred not to allow such calls.


DP4 System Error 119

Message

DP4 System error 119. Origin: Program bug
Program workfile error

Comment

This error is not used.


DP4 System Error 121

Message

DP4 System error 121. Origin: Program bug
Form number %1 not in print buffer, so cannot be used for output

Comment

This error will be suppressed for prn() operations if SKIP_MISSING_FIELD is specified in the flags parameter (so in show_flags for prn_x() calls).


DP4 System Error 122

Message

DP4 System error 122. Origin: Program bug
Attempting to print without having selected print device


DP4 System Error 123

Message

DP4 System error 123. Origin: Program bug
Form %1 not in print buffer, so form %2 cannot be printed over it


DP4 System Error 124

Message

DP4 System error 124. Origin: Program bug
Form %1 not in print buffer, so form %2
cannot be printed beside it


DP4 System Error 126

Message

DP4 System error 126. Origin: Program bug or improper installation
Logical device %1 not found


DP4 System Error 127

Message

DP4 System error 127. Origin: Program bug or improper installation
Logical device %1 is a sub device


DP4 System Error 128

Message

DP4 System error 128. Origin: Program bug or improper installation
Logical device %1 is not sub device of printer %2


DP4 System Error 129

Message

DP4 System error 129. Origin: Device driver
Error %1 while writing to printer/device %2

Comment

Consult your system documentation for more details.

This is the error generated by the default version of dvc_check(). You should suppress the error by using the pr_err_mode variable and/or rewriting the function.


DP4 System Error 130

Message

DP4 System error 130. Origin: Program bug
Map number %1 not on screen so field number %2 cannot be accessed

Comment

This error will be suppressed on show() and askf() calls if SKIP_MISSING_FIELD is specified in flags (so in show_flags or scrn_flags) for show_x() or askf_x() calls.


DP4 System Error 131

Message

DP4 System error 131. Origin: Program bug or improper installation
Map %1 of mapset %2 not found on the database

Comment

This error also sometimes occurs as a symptom of a broken network connection. You may try to recover from the error, for example, by refusing to re-enter the affected part of the program, but you may find that other errors are generated shortly afterwards unless the error was genuinely due to one missing map.


DP4 System Error 132

Message

DP4 System error 132. Origin: Program bug or improper installation
Insufficient data passed to TRM for data entry in map number %1 field number %2

Comment

Possible causes are using an inappropriate function for data entry on a non-character multi-occurrence field, or that the map being used and the program being run are for different generations of the database.


DP4 System Error 133

Message

DP4 System error 133. Origin: Program bug or improper installation
Map number %1 field number %2 not found on the database

Comment

This error also sometimes occurs as a symptom of a broken network connection. You may try to recover from the error, for example by refusing to re-enter the affected part of the program, but you may well find that other errors are generated shortly afterwards unless the error was genuinely due to one missing field.


DP4 System Error 134

Message

DP4 System error 134. Origin: Security violation
Write access is not allowed for map number %1 field number %2


DP4 System Error 135

Message

DP4 System error 135. Origin: Security violation
Read access is not allowed for map number %1 field number %2

Comment

A program is trying to read/write a field to which it does not have access because the user's security level is too low. A program could recover from this error by leaving the part of the program which the user does not have sufficient access for. However, a more satisfactory method of dealing with this situation is to check user.read.access or user.write.access (these fields are also available in QAB) in the program code rather than trying to recover from the system error.


DP4 System Error 136

Message

DP4 System error 136. Origin: Program bug
Too many nested calls to map_new_position()

Comment

The source code of map_position() is in CCMAP2.C


DP4 System Error 137

Message

DP4 System error 137. Origin: Improper installation
Map number %1 field %2 is off edge of screen

Comment

This error is never generated by programs using the 4.600 TRMn.


DP4 System Error 138

Message

DP4 System error 138. Origin: Database inconsistency
Control for map %1 of mapset %2 not found on database.

Comment

This error does not indicate a corruption, but that the 4.600 map tables have been updated in an incorrect manner. You will have to recreate the map with MAPPOST if you have a map file for it, or with MAPEDIT. The program may not function as intended if you try to recover from this fault.


DP4 System Error 139

Message

DP4 System error 139. Origin: Database inconsistency
Control for map %1 field %2 corrupt.

Comment

This error does not indicate a corruption, but that the 4.600 map tables have been updated in an incorrect manner. You will have to recreate the map with MAPPOST if you have a map file for it, or with MAPEDIT. The program may not function as intended if you try to recover from this fault.


DP4 System Error 140

Message

DP4 System error 140. Origin: Database corruption
Key extraction not implemented for number system %1

Comment

This error indicates the dictionary of your database is corrupt.

Non-recoverable.


DP4 System Error 141

Message

DP4 System error 141. Origin: Database corruption
Data independence not implemented for number system %1

Comment

Your database is claiming to use an undefined number system.

Non-recoverable.


DP4 System Error 142

Message

DP4 System error 142. Origin: Improper installation or database corruption
Program number system not supported by this database

Comment

The database manager automatically converts numbers to IEEE format from any other supported format, but not to any other system formats. Therefore, either programs must use the IEEE number system or the same number system as the database.

Non-recoverable.


DP4 System Error 143

Message

DP4 System error 143. Origin: Improper installation or database corruption
Autoincrement not implemented for number system %1

Comment

Your database is claiming to use an undefined number system.

Non-recoverable.


DP4 System Error 150

Message

DP4 System error 150. Origin: Software licence expiry/improper installation
Licence number check overrun - contact Itim Technology Solutions

Comment

You need to obtain a new licence disk from Itim Technology Solutions.

Non-recoverable.


DP4 System Error 151

Message

DP4 System error 151. Origin: Security violation
Read access is not allowed for table number %1

Comment

System errors 151 and 152 are mainly intended as a last-ditch security measure when a user has somehow gained access to a program he is not intended to run.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 152

Message

DP4 System error 152. Origin: Security violation
Write access is not allowed for table number %1

Comment

A program is trying to read/write a table to which it does not have access because the user's security level is too low. A program could recover from this error by leaving the part of the program for which the user does not have sufficient access. However, a more satisfactory method of dealing with this situation is to check user.read.access or user.write.access (these fields are also available in QA Build) in the program code rather than trying to recover from the system error.

Comment

System errors 151 and 152 are mainly intended as a last-ditch security measure when a user has somehow gained access to a program he is not intended to run.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 154

Message

DP4 System error 154. Origin: Internal DP4 limit exceeded
Trying to open to many workfiles with wkf_open(). Limit is %1

Comment

This error will never occur unless you use wkf_open() which is provided in source code CCWKFILE.C. This routine is not used by QAB or Report Writer.


DP4 System Error 155

Message

DP4 System error 155. Origin: Program bug
No workfile open for type %1

Comment

A data record passed to wkf_post() or wkf_fetch() does not match any type passed to wkf_open().


DP4 System Error 156

Message

DP4 System error 156. Origin: Unknown
Error %1 writing to printer/device driver interface (sub function |)

Comment

This error will not occur unless you have a DDI which does not work properly, or you are using a DOS DDI under Windows for Workgroups or Windows 95 without using DIPVXD.386.


DP4 System Error 157

Message

DP4 System error 157. Origin: Unknown
Error %1 reading from device driver interface

Comment

Same as for DP4 System Error 156 .


DP4 System Error 163

Message

DP4 System error 163. Origin: Unknown
Input redirection was wrong at line %1 of file %2

Comment

This error occurs if you play back a demonstration using REDx -testmode and the recorded input is not for the correct field.


DP4 System Error 173

Message

DP4 System error 173. Origin: Security violation
You do not have sufficient read authority to access this database.

Comment

Errors 173 and 174 may occur when calling db_open().


DP4 System Error 174

Message

DP4 System warning 174. Origin: Security violation
You do not have sufficient write authority to access this database.

Comment

Errors 173 and 174 may occur when calling db_open().

The program does not have app_rw_access set high enough to open the databases. You can recover from this error if you can work without the database. Alternatively, you could increase app_rw_access and retry - though obviously this defeats the security mechanism.


DP4 System Error 210

Message

DP4 System Error 210 Origin: Operator error or incorrect installation
Scientific functions are not implemented in small version of PROGRUN

Comment

You are trying to run a QA Build program with PROGRUNS or with a C Exit, linked with FORMSFNC.OBJ (using the QABLINKS batch file) that uses scientific functions, such as exp(), log(), sin() and so on.

If you ignore this error and carry on after it, your program will make incorrect calculations.


DP4 System Error 261

Message

DP4 System error 261. Origin: Improper installation
You must recompile and relink this C program as the QA Build part of it has changed.

Comment

You are trying to run a QA Build C exit program that needs to rebuilt by having its C code regenerated with PROGCOMP, and then needs to recompiled and relinked.

The best way of avoiding this error is to use the PROGCOMP −GENERIC interface between C and QA Build. This is slightly slower, but does not require you to rebuild the C program when the QA Build part changes.

Non-recoverable.


DP4 System Error 263

Message

DP4 System error 263. Origin: Operator error or program bug
QAB calling non-implemented C procedure/function type %1 number %2

Comment

A call to a QA Build C exit procedure or function is being made for which no C code has been provided, or for which the entry in the Qc_body() or Qc_func() switch statement is missing.

Non-recoverable.


DP4 System Error 300

Message

DP4 System error 300. Origin: ADC Error
Auxiliary db manager cannot find name number %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 301

Message

DP4 System error 301. Origin: ADC Error
Auxiliary db manager cannot find db %1 user %2

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 302

Message

DP4 System error 302. Origin: ADC Error
Auxiliary db manager cannot find table number %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 303

Message

DP4 System error 303. Origin: ADC Error
Auxiliary db manager cannot find field number %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 304

Message

DP4 System error 304. Origin: ADC Error
Auxiliary db manager cannot find prime index for table %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 305

Message

DP4 System error 305. Origin: ADC Error
Auxiliary db manager cannot find field in index for table %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which field/table is causing the problem.


DP4 System Error 306

Message

DP4 System error 306. Origin: ADC Error
Auxiliary db mgr cannot find index specified for table %1 (parent %2)

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.

See How to Find a Table, Field or Role Name from a Number shown in a System Error Message to find out how to obtain further information about which table is causing the problem.


DP4 System Error 308

Message

DP4 System error 308. Origin: ADC Error
Heap overflow in auxiliary db manager

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 309

Message

DP4 System error 309. Origin: ADC Error
Statement length overflow in auxiliary db manager

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 310

Message

DP4 System error 310. Origin: ADC Error
Auxiliary database manager cannot close database

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 311

Message

DP4 System error 311. Origin: SQL database
SQL database error number %1

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions. Error 311 is generated is generated when you are using a Gateway ADC, such as AUXORACL or AUXWODBC. If DP4 error logging is enabled or diagnostics are turned on the corresponding error message will be in the error log. Alternatively you can consult the documentation for your OEM database. A quick way of finding out about errors from Oracle is to enter the Oracle error code which is of the form ORA-nnnnn (e.g. for error 426 it would be ORA-00426) into an Internet search engine


DP4 System Error 320

Message

DP4 System error 320. Origin: Resilience program error
AUXDISTR cannot find process table entry %1

Comment

System error 320 occurs when AUXDISTR cannot find its internal housekeeping information associated with the process making a call to the database manager. By far the most likely cause of this error is that you have specified an invalid process number when calling the DP4 database manager (for example you have continued to use a process number after the process has logged off from the database manager). From release 4.620 system error 320 is only generated when there is genuinely a problem with AUXDISTR's internal information - if a program uses an invalid process number FAIL 11 is generated instead.


DP4 System Error 321

Message

DP4 System error 321. Origin: Resilience program error
AUXDISTR cannot find db table entry for process %1 db %2

Comment

Errors 300-329 are generated by various ADC programs. Treat them as non-recoverable and contact Itim Technology Solutions.


DP4 System Error 401

Message

DP4 System error 401. Origin: DP4 Formula error
Divide by zero error

Comment

Errors 401 to 405 are generated by QAB. They should be prevented by using the math_error_mode variable.


DP4 System Error 402

Message

DP4 System error 402. Origin: DP4 Formula error
Modulus by zero error

Comment

Errors 401 to 405 are generated by QAB. They should be prevented by using the math_error_mode varMessage


DP4 System Error 404

Message

DP4 System error 404. Origin: DP4 Formula error
Subscript out of range error

Comment

Errors 401 to 405 are generated by QAB. They should be prevented by using the math_error_mode variable


DP4 System Error 405

Message

DP4 System error 405. Origin: DP4 Formula error
Bad argument to function %1 :%2

Comment

Errors 401 to 405 are generated by QAB. They should be prevented by using the math_error_mode varMessage


DP4 System Warning 39

Message

DP4 System warning 39. Origin: System constraint.
Operating system has denied write access to the database. Requests to update the database will be ignored.

Comment

This warning is produced when a database is opened if the operating system allows the database files to be opened in read-only mode, but not for writing. The original intention behing this warning was to allow archived databases to be accessed from CDs or similar read-only media using regular DP4 application programs. However, in recent versions of Windows problems with anti-virus software, group or other security policies, and so on, can sometimes cause a database stored on a regular hard-drive to encounter this condition. In the case where the application handles important data (e.g. financial transactions), but is used by unskilled operators, it is best to treat this warning as an error. The easiest way to do this is to use the new allow_archive_mode=0 setting, available in 4.625. This enhancement to dp4srvr.w32 is compatible with 4.624.


DP4 System Warning 51

Message

DP4 System warning 51. Origin: Operator error
Updates lost because parent of record to be posted is missing

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 52

Message

DP4 System warning 52. Origin: Operator contention
Updates lost because parent of record to be posted has been updated by another user

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 53

Message

DP4 System warning 53. Origin: Operator contention
Updates lost because record to be updated has been updated by another user

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 54

Message

DP4 System warning 54. Origin: Operator error
Updates lost because record to be deleted would leave orphans

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 55

Message

DP4 System warning 55. Origin: Operator contention
Updates lost because record to be updated is locked by another user

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 56

Message

DP4 System warning 56. Origin: Hardware problem
Updates lost because of comms failure

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 System Warning 58

Message

DP4 System warning 58. Origin: Operator error
Updates lost because record to be amended has changes in foreign key fields

Comment

The best way of avoiding this system error is not to set the QUIT_ON_FAILURE flag when opening the database. If this flag is not set, the error will never be generated and the program should take appropriate action by examining the return code of calls to db_commit(), db_update() and so on.


DP4 Utilities

The following section lists the DP4 utilities provided with the core set of DP4 software. A brief description of each is given, with the command tails that can be used. It also documents the keyboard interface used by DP4 utilities.

If you are accessing the utilities from within the DP4 menu program, you will not be able to specify the command tails. However, most of the commands can be selected as options within the utilities. If necessary you can use MENUEDIT to add new menu options or modifying existing ones and specify command tails you require. (An example of this is that PROGCOMP appears twice in the menu for DP4 once with the -DEBUG option.)

There is a set of standard command tails available for all the DP4 database access utilities. For example, you can specify the -DB command tail to select the database you are working on before the program starts up. This avoids having to specify the database name after program loading.

If you are interested in the command tails available for a utility you will probably be running it from a batch file or other script file. You will probably also be interested to know the possible exit codes from the program. All DP4 programs use a set of standard exit codes.

  • Keyboard Interface
  • Standard Command Tails
  • Standard Exit Codes
  • Utility Reference


DP4ED

The DP4 Text editor. This program is provided so that you have a simple text editor that works the same on any platform.

See Editing a Text File in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
filename | Name of file to be edited
−LENGTH n | All lines are forced to at least n characters long
−NOCR n | File has fixed length records of length n without CR/LF terminators


DYNABACK

Backs up a database which may be currently in use by one or more DP4 application programs. For full details refer to Dynamic Backup in the DP4 Developer's Manual.

Prior to release 4.525/4.621 DYNABACK imposed two rather arbitrary restrictions: it could not be used unless transaction logging was enabled;it could not be used to back up the system database. Both these restrictions are removed in later releases.

Command Tail | Description
−COMMENT "text" | Optional comment, up to 32 characters, displayed when restoring database
−COPY | (Introduced in 4.522/4.618). Backs up database as renamed database files instead of in BKP format. DBCHECK is run against the backup. These files are used by DBRECOV in the event that a fast recovery fails.
−DELETE | (For use with −SETSESSN) Delete the transaction logs
−FORMAT | Format disks using a user-supplied batch file called FORMBKP
−NEWDB newname | New in 4.526/4.622 This command tail is only meaningful when −COPY is also specified. Instead of backing up the database it is copied to a new database named newname. DP4 utilities that need to do so now use this program to copy databases, in order to avoid having to know explicitly what files form part of the database. This option does not set the flags in the original database to indicate that it has been backed up.
−NODELETE | (For use with −SETSESSN) Rename the existing transaction log to a file of the same name with a .LBK extension
−NOVERIFY | Disables verification of backup, or when -COPY is in use, running of DBCHECK
−QUIET | Suppress messages, including the instructions to change a disk. (Backs up to one disk only)
−SERVER n | Server from which to back up (for multiple-resilience configurations using AUXDISTR)
−SETSESSN | Marks a database as backed up (without performing actual backup)
−SPACE amount | Set the amount of space (in Kilobytes) to leave on the backup disks
−VERIFY | Attempts to veridy backup is written correctly.

To back your database up securely you are recommended to use DYNABACK -COPY. This provides an automatic and foolproof method of backing up a database and is described in detail in the DP4 Developer's Manual here.


DYNACHEK

Checks integrity of a database without requiring exclusive access and preventing applications from running. This program may occasionally report spurious errors if a record being checked is updated. From 4.522 DYNABACK provides an enhanced method of checking the integrity of an open database.

See Checking the Database Integrity Dynamically in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−CHECK | Check database integrity
−COUNT n | Display record count every n records
−COUNTONLY | Count records without checking database integrity
−DELAY n | Delay after database calls (in hundredths of seconds). Maximum delay is 10 seconds
−SKIPBD | Skip tests on base dictionary tables
−BATCH | Suppress the pause after the integrity check
−NOBLOCK | Disable the block fetch feature
−QUICK | Speed up the integrity check by omitting some tests
−REPEAT | Do the integrity check repeatedly
−PASS | Pass on error and continue checking


Interpreting DP4 Error log Error Messages

If a system using DP4 is misbehaving but is not producing meaningful error messages then you should enable DP4 Error logging, to improve the chances of diagnosing the problem. For information on how to do this see Diagnostics in the Guide to DP4 configuration.

There are two main sources of error messages in the DP4 error log that can be produced by ordinary DP4 applications. The first is messages from DP4DBAPI, and the second is the DP4 network requester, usually TCPW

DP4DBAPI Errors

If debug_error=1 is turned on in then the error log will contain information about every error return code from DP4 that would normally cause a system error or a fail error to be displayed.

The following shows how such an error might typically be displayed:

DP4DBAPI Returning from srv_ncall on function 210 with error 3
Error codes 17 -195 0
DP4DBAPI Into error handler 3 17 -195 0
browser : DP4 System error 17.  Origin: Unknown. Database not properly closed. Run DBRECOV

The first two lines in the above output should always be produced, but the second two lines which describe the error more fully will not always be displayed. In particular C++ programs that use "raw" error handling will not usually display these two lines. Also it is possible that the DP4.INI on the system may not contain complete error text for all DP4 errors, so that the error text might not be complete. However the first two lines are sufficient to determine the DP4 error that has arisen.

  • Error 3 errors are DP4 System Errors. On the second line,the first number is the number of the system error, 17, in this case. You can find a full list of DP4 System errors in System Error Messages . The two remaining numbers may or may not be meaningful. They are the first and second parameters of the error. You can decide whether they are meaningful by seeing if the error message include plce-holders %1 and %2. The first number will often be a table number. Assuming you know the name of the database that has produced the error you can discover the table name associates with the error as described in How to Find a Table, Field or Role Name from a Number shown in a System Error Message .
  • Type 2 errors are DP4 System warnings. Some applications will treat these in the same way as system errors. They are interpreted in the same way as system errors.

  • Error 4 errors are DP4 Fail errors. The interpretation of the values on the second line is very similar to that for System errors, the first number is the DP4 error number as listed in Fail Errors, and the two remaining numbers are the error parameters. For fail errors the first parameter is usually an error return code from the operating system, and you can discover more about the error by running the FAIL program with the appropriate parameters. For example if the error line read :
    Error code 25 112 13

    you would run FAIL like this: FAIL 25 112 13. This would show that an error had occurred writing to a file, and the error code on Windows would indicate the problem was caused by lack of disk space.

You can also determine the DP4 function that was being called when the error arose. This is the first number on the first line, in this case 210. This is a hex value, and the corresponding function can be found by locating this value in the file DP4CI.H which can be found on the DP4 CD ROM in the incude subdirectory for each release.

If the DP4 program that is encountering the error is very old, or has been linked with an old DP4 library such a pre 4.620 version of NTOWN or with DP4DYN32.DLL then DP4DBAPI is not used for calls to the database manager, and you will not be able to diagnose errors this way. If your program is accessing a a database on another machine then you can use the second type, of diagnostic, described below, to determine the error. If not then you would need to use AUXDEBUG to discover more about the error. For information on how to use this component refer to Example ADCs in the ADC Developer's manual.

Network Requester Errors

If the reply from a network request includes a DP4 error code and the DP4 network requester was loaded with the -debug_connect or -debug_error command fails then the DP4 network requester will write a line to to the error log that looks like this:

NETREQ reply function 210 server 1 error 3 retcode 17

As with DP4 DP4DBAPI errors, the error code is 3 for System errors and 4 for Fail errors, and the actual error number is shown in the number after this, in the "retcode" field. The first number on the error line indicates the DP4 function that was being called and is interpreted using DP4CI.H as already described for DP4DBAPI. The server number may or may not be meaningful depending on how DP4 servers are selected: if you use the -server_name command tail to select servers, then the number is not meaningful, and will not necessarily correspond to any number that may be included in the name of the server. However if you use AUXDISTR, or select servers by the -server command tail, then the server number is meaningful.

The error parameters are not available in the Network requester diagnostics.


Error groups

Where one group includes another it is to be understood as including all the groups included in that group.

Group | Description
A | General DBMS errors: Group F, Fail 7, System errors 8, 10, 43, 87
B | Commit errors : Group A, System errors 20, 38, 51-58, 79, 89.
 | Errors 51-58 are best avoided by not using QUIT_ON_FAILURE db_open() mode
 | After any type of system error or fail error during a database update (commit() or checkpoint()) fail_code will be set to SYSTEM_FAILURE
C | DB Read errors: Group A, System errors 20, 21, 22, 23, 24, 25, 141, 151
 | Errors 22-25 should not occur on accesses through the main index
 | Note that functions which fetch records from the database are guaranteed to return with their FALSE and depth -3 or -4 if the call generated a system or fail error
D | Data input/ouput Errors: Groups C, X, System errors 40, 41, 130, 132, 133 (in 4.5xx) 134, 135, 137 (in 4.5xx) 138, 139 (in 4.6xx), 163 (if using REDn)
 | Errors 41, 134, 163 occur on input only
 | Data entry routines are guaranteed to return in the same way as if the user had pressed <Esc>. So, abort_code will typically contain ESCAPE
F | File errors: Fail errors 13-27
M | Map display errors: Groups A, C, X, System errors 131, 130 (for attached maps) 138 (in 4.6xx)
P | Prn Errors: Groups A, C, X, System errors 40, 121, 133 (in 4.5xx) 135, 137 (in 4.5xx) 138 (in 4.6xx)
U | Record update errors: Group A, System errors 20, 38, 48, 79, 141, 152
X | General terminal manager errors: Group F, System error 6.
 | If System error 6 is generated, errors from groups A, C and system error 130 may occur, resulting in a fail 10
 | In general, functions that only generate errors in group X should be treated as if they are bound to succeed. They will only fail if a corruption in a TRM work file is detected, and this situation is non-recoverable


How to Find a Table Name from a Number shown in a System Error Message

How to Find a Table, Field or Role Name from a Number shown in a System Error Message

Before you can find the name corresponding to a number, you need to know the name of the database that is causing the error. If the number is 4096 or above then the number is an application database table field or role number. Typically DP4 installations either use one application database, or two databases with the same structure, so this is unlikely to be a problem in practice.

If the number is less than 4096 then the number corresponds to something in the base dictionary, so it does not matter which database you use because this is the same on every database. A particularly important case is if the table number is 102 (this may show up as fail 6 0 20 error). This means that either your system database or your application database are 4.5xx series databases but you are using 4.6xx software to access them.

Either:

  • Inspect the list of tables on the database that PRINTDB can produce and look for the table number shown in the error message.

Or, if the database has too many tables to do this easily:

  1. From a command prompt, or using the Run command option on the DP4 menu (logging on as DP4), run browser -basedict

  2. Select the appropriate database, then press the Table button and then enter @name_table for the table name.If you cannot access the @name_table table then either you forgot to use -basedict, or you do not have the correct read and write access levels to see the @name_table table. In the latter case you need to use the User Preferences/ Colours and Miscellaneous option DFSETUP to boost your read and write access levels to 99 or above.

  3. Press the Index button, and then select the @NR_INDEX index.

  4. Press the Keys button, and enter the number shown in the error message

  5. Depending on your userdata.sys settings you may or may not need to press Enter a couple of times. Assuming the number corresponds to something on the database Browser will display "Existing Record" in the Record status field, and the name will be displayed as the first field in the list of fields.

  6. If Browser shows "No matching Record" then the number does not match anything in the data dictionary. Either:

    • You have selected the wrong database.

    • The database is corrupt. Try repeating the procedure using a known good copy of the database, and if the name should exist run a Database Integrity Check against the database reporting the problem.

    • The program is referencing something that does not exist on the database. This can happen if an application is running against a version of the database that is too old or too new for the application, or an application is running against the wrong database entirely.

    • Some memory in the application that should contain a table number is corrupted, perhaps because of a program bug. Two very common cases are when the number shown is 0 or 8224. In the first case a program has incorrectly filled an area of memory with binary 0. In the second it has incorrectly filled the area with ' ' (space) characters.


FAIL

Displays low level error messages. The program can be run from the command line to translate an error number to a text message (see DP4 Error messages for further information)

Command Tail Description

first_number

The DP4 error number

second_number

The error code returned from the operating system

third_number

The extra return code from the operating system

filename

The name of the file causing the error

−OS name

Display error message for the remote operating system. Valid names are:

  • MS-DOS
  • UNIX
  • FLEXOS
  • OS2
  • Windows

You can use the FAIL program to display any operating system error message on Windows and Unix platforms, even for errors generated by other programs. For example, suppose you are checking an event log and it contains a message with Win32 error code 5, but no text. If you run FAIL 0 5, you will see the text of this Windows, error, code - in this case "Access is Denied".


Fail Error 0

Message

0. Unable to initialise

Comment

Non-recoverable.

This message was not used prior to release 4.620. From 4.620 it is used when a program cannot connect to the DP4 interface. This is most likely to ocur if you are running a client/server configuration and the server cannot be contacted. In this case the additional error code is probably a network error code. Refer to Fail Error 7 for further information.


Fail Error 1

Message

1. Unable to terminate

Comment

Not used, Non-recoverable.


Fail Error 2

Message

2. Too many processes

Comment

This error can occur but it happens before it is possible to report errors. The most likely cause is when a system is never shut down and programs terminate abnormally from time to time without tidying up properly. The only solution is to shutdown all DP4 programs and then reload.

Not used, Non-recoverable.


Fail Error 3

Message

3. Too many open files

Comment

A program is forgetting to close files, or programs have terminated without logging off from the database manager, leaving files open.

Non-recoverable.


Fail Error 4

Message

4. Work file error

Comment

Not used since release 4.420. Non-recoverable.


Fail Error 5

Message

5. Database manager cannot initialise

Comment

Applications should treat this error as non-recoverable.

The system database cannot be opened.

When this error occurs, the additional error code is the system error number which would be generated if system errors were available. For example, fail 5 0 15 means the Index file for the system database is missing.

Action

  1. Use SYSDB to verify the name of the SYSTEM database and check that your database directory, as set in DFSETUP, contains the files SYSTEM.IND AND SYSTEM.DAT (or whatever is the correct name of your SYSTEM database). From release 4.622 the system database also uses files SYSTEM.DCI and SYSTEM.PTR

  2. Check that the SYSTEM database has not been corrupted by running a DP4 program, such as MAPEDIT against it (look for a SYSTEM.RLB file in the directory where rollback files are kept). If the SYSTEM database has been corrupted it may be necessary to restore a copy of the SYSTEM database from backup disks, but first try following the instructions for Recovering the System Database in the DP4 Developer's Manual.

  3. If you have moved your DP4 installation to a new directory, or have made changes to the drive assignments using DFSETUP, then the file locations in your DP4 licence file may no longer be correct. In this case you can use the form of the SYSDB command that includes a pathname to regain access to the system database, so that you can use DFSETUP again to correct the file locations. Remember to stop and restart DP4 after changing file locations.


Fail Error 6

Message

6. Unable to find system message.

Comment

This error is generated when a call to sys_error() cannot display the correct error message. In this case, sys_fail(6,0,sys_error_nr) is called.

Possible causes of this error are:

  • SRVn, or the network, is broken
  • Your SYSTEM DB is very out of date (for example using a 4.4xx SYSTEM DB with 4.500 TRM or a 4.500 SYSTEM DB with 4.600 TRM)
  • Your SYSTEM DB is slightly out of date and is missing a particular error message
  • Your application database is out of date.

At one time there was a bug in SRVn where if the map table was missing from the application database it would also appear to be missing from the system database. This was fixed by release 4.517

Non-recoverable.


Fail Error 7

Message

7. Network error

Comment

The additional error code is a network-specific error code, if it is less than 256 or over 280 or a DP4 network error code (listed in NETWORK.H) otherwise. Windows uses error codes above 10000 for TCP/IP errors. From version 4.620, where appropriate the network error code will be reported as an operating system error, rather than as an additional error. This allows the operating system message associated with socket related errors to be displayed, though this is only supported on Windows 2000 or later. (Other versions of Windows will display a blank or corrupt message).

Your strategy for recovering from this type of error should be to use the correct level of resilience unless you are using the named server configuration and manage your own connections.

You can attempt to carry on after this error, but will need to establish a new connection by closing the old connection and reinitialising.

Common additional error codes are:

Code | Meaning
256 | The requester believes the DP4 server is not running
259 | The application program is trying to access a server without initialising properly. This error commonly arises if a program that has encountered a network error and has been logged off as a result attempts to continue to use its "dead" connection.
264 | The network requester believes a reply from a server is invalid.
268 | The network requester and server or AUXDISTR are from incomptible releases of DP4.
10053 | Winsock - Connection aborted
10054 | Winsock - Connection reset
10060 | Winsock - Connection time-out
10061 | Winsock - Connection refused
10064 | Winsock - Host down
10065 | Winsock - Host unreachable

Other Errors in the 10000 range are documented in the Windows header file winsock.h. On Windows 2000 and Windows XP you can run FAIL 7 100nn to display the text associated with Winsock errors.
Unix socket errors will usually be found in the header file /usr/include/sys/errno.h

If you are using NetBIOS programs (NTBW and NTBMGR for example), the additional error code is a NetBIOS return code.


Fail Error 8

Message

8. Corrupt database

Comment

Not used. Non-recoverable.


Fail Error 9

Message

9. Inter process communication error.

Comment

Occurs if DP4 is shut down while a DP4 program is running. Non-recoverable. A program should always terminate if it encounters this error, as the DP4 system cannot be reloaded after this type of error until all DP4 programs have terminated.

DP4 programs should listen for the message that is broadcast when the DP4 system is shutting down, and close gracefully. This will generally happen automatically for DP4 programs that use the terminal manager.

On Windows platforms, if there is an additional error code, it will correspond to a Loader Error message, most commonly 86, which indicates that the DP4 system believes that one or other of the server components loaded as part of the DP4 service has died, or that the DP4 system has been shutdown.


Fail Error 10

Message

10. DFPRINT error.

Comment

Occurs if DFPRINT encounters an error from the operating system or printer driver when printing a file. The operating system error code should give more information. This error terminates DFPRINT but does not affect the program that called DFPRINT.


Fail Error 11

Message

11. Invalid Process Handle.

Comment

From 4.620. Occurs if AUXDISTR is called by a program using an invalid process number. In future this error may also be reported by DP4SRVR, which currently typically generates FAIL 6 0 10 if it is called with an invalid process number (it tries to generate system error 10 0, but because the system database is not open for the process a fail 6 0 10 is generated). If this error occurs there is a serious bug in your program and you should terminate.


Fail Error 13

Message

13. Corrupt file handle.

Comment

This is a program bug, caused by passing as a filenr to one of the tf_ or sf_ functions an invalid file number. Normal causes are attempting to read or write a file before it has been opened or after it has been closed. The third parameter to sys_fail() is the internal code of the function being called, so you can deduce the function being used (see Functions which generate Fail errors but not System errors ).

Non-recoverable as there is a serious bug.


Fail Error 14

Message

14. Extended memory error

Comment

This error only happens under MS-DOS when using SRV2 -EXTENDED. Check that extended memory is not being used for another purpose, for example, a disk cache

Non-recoverable.


Fail Error 15

Message

15. IPC Error on server machine

Comment

This error is introduced in release 4.622. If a call is made to a database manager on another machine via DP4 networking, and an IPC error is returned to the DP4 network requester (fail error 9), then the network requester changes the error number from 9 to 15 (DOS_RIPCERR). (Such an error might arise if the database manager on the other machine crashed or was terminated while the network manager was eaiting for it to reply) The error number is changed because fail error 9 should always be treated as non recoverable, but in this case it is possible to continue after the error.

If you encounter this error you should close your connection to the remote machine. You may encounter fail error 7 when doing so, because it is likely that the network manager on the other machine will have handled the original fail error 9 by closing the DP4 service on that machine. You can attempt to establish a new connection to the remote machine, but will probably have to wait for the DP4 service to be restarted on it.


Fail Error 16

Message

16. Error in searching for file.

Comment

This error happens when a file cannot be found.

Check that the file exists or that the disk containing the file has no physical defect.


Fail Error 17

Message

17. Unable to make file.

Comment

SRVn or TRMn are unable to create a new file, probably for one of the following reasons:

  • The filename or pathname is invalid
  • The directory or drive is full
  • You do not have the correction permissions

This error may be returned from sf_open() and tf_open(). The best way to trap it is to pass the flag VF_RET in any calls to sf_open() or tf_open() in your own code and to test the returned file handle is = 0.


Fail Error 18

Message

18. Unable to open file

Comment

SRVn or TRMn are unable to open an existing file, probably for one of the following reasons:

  • The filename or pathname is invalid
  • The directory or drive is full
  • You do not have the correction permissions

This error may be returned from sf_open() and tf_open(). The best way to trap it is to pass the flag VF_RET in any calls to sf_open() or tf_open() in your own code and to test the returned file handle is = 0.


Fail Error 19

Message

19. File open by another user.

Comment

SRVn or TRMn are unable to open an file because it has already been opened by someone else (or by you elsewhere in the program).

This error may be returned from sf_open() and tf_open(). The best way to trap it is to pass the flag VF_RET in any calls to sf_open() or tf_open() in your own code and to test the returned file handle is = 0.


Fail Error 20

Message

20. File size error

Comment

Not used. Non-recoverable.


Fail Error 21

Message

21. File position error

Comment

Not used. Non-recoverable.


Fail Error 22

Message

22. Seek Error

Comment

SRVn or TRMn are unable to position the file pointer at the appropriate point for a read or write operation.

This error is only generated as a result of an error from the operating system.

It is unwise to continue after this error, because it might originate from a database file, but you should not be able to corrupt the database by doing so.


Fail Error 23

Message

23. Error reading file

Comment

SRVn or TRMn got an error from the operating system reading/writing a file, or possibly could not read/write the number of bytes requested even though the file size indicated the read should have succeeded.

It is unwise to continue after these errors - because they might originate from a database file - but you should not be able to corrupt the database by doing so. If the errors do originate from a database file, all further attempts to update the database files will generate fail error 24 ; forcing DBRECOV to be run is the only way to guarantee database integrity after a write fail.


Fail Error 24

Message

24. Read past end of file

Comment

This is a somewhat misleading error message. It originates when code used to read a DP4 record from a file is called, and the read fails. This may happen for reasons other than an actual read past the end of the file. For example, it will happen if the file pointer is not at the start of a DP4 record.

A possible cause of this type of error would be attempting to read a damaged portion of a log file which was only partially written at the time of a system crash.

The best way to avoid this error is to use tf_read() and sf_read() rather than tf_read_record() or sf_read_record().


Fail Error 25

Message

25. Error writing file - disk may be full

Comment

This is similar to Fail Error 17 .


Fail Error 26

Message

26. Error flushing file

Comment

This is similar to Fail Error 24 .


Fail Error 27

Message

27. Cannot close file

Comment

The operating system reported an error when the file was closed.

If a program wants to carry on after this error it should behave as though the file had been closed successfully.


Fail Error 28

Message

28. Cannot delete file

Comment

Not used. Non-recoverable.


Fail Error 29

Message

29. Error in default directory

Comment

Not used. Non-recoverable.


Fail Error 30

Message

30. Error in file tracking

Comment

Not used. Non-recoverable.


Fail Error 31

Message

31. Error resetting file system

Comment

Not used. Non-recoverable.


FAIL Errors

Fail errors are generated in situations where the system database is not or may not be available for generating a system error message using a map. Requests to produce a FAIL message are handled by the terminal manager. Usually the terminal maanger executes the FAIL program, which displays messages by direct operating system calls without using any other part of the DP4 interface. The messages are displayed in the following format:

  1. DP4 Fail error number
  2. Error return from the operating system
  3. Additional error code (or 0 if not relevant)
  4. Name of the file associated with the error (if any, and if known).

The meaning of the additional code varies according to the function causing the fail.

If the system cannot run the FAIL program to produce a proper error message, or fail errors are generated recursively, the command line to FAIL is displayed as shown below:

FAIL xxxx yyyy zzzz [filename]

Here xxxx is the DP4 error code listed above, yyyy the error return from the operating system and zzzz the additional code. If this happens, you can run the FAIL program from a command prompt using the format given above to display a description of the error. For example, if the numbers x, y and z were 20, 2 and 3, enter FAIL 20 2 3 to display the message.

Under Windows NT family operating systems the FAIL message is also written to the Application Event Log. The method used to do this has changed in 4.620, so that the event log also records which program encountered the fail error.

The command line to FAIL is written to SYSLOG.PRN, so that you can run FAIL to redisplay error messages. You can either enter the complete command line, or you can run FAIL interactively - if you don't specify any command tails FAIL pops up a dialog to request the error number details for the error you want to display.

The FAIL program displays a text description of the error returned from the operating system, except on FlexOS, where it displays only the error number returned by the operating system. You can then establish the meaning by reference to listings in the appropriate system manuals.

From release 4.620 and on Windows platforms, the FAIL program is not used. FAIL error messages are extracted from the DP4 configuration file and generated in SYSLIBx.DLL. However, you can stil use FAIL to redisplay errors reported by a user, or which have been displayed by programs that do not use the DP4 user interface.

List of FAIL Error messages

The following fail errors are defined. Some are not used; see the notes for each message:

  • Fail Error 0
  • Fail Error 1
  • Fail Error 2
  • Fail Error 3
  • Fail Error 4
  • Fail Error 5
  • Fail Error 6
  • Fail Error 7
  • Fail Error 8
  • Fail Error 9
  • Fail Error 10
  • Fail Error 11
  • Fail Error 13
  • Fail Error 14
  • Fail Error 15
  • Fail Error 16
  • Fail Error 17
  • Fail Error 18
  • Fail Error 19
  • Fail Error 20
  • Fail Error 21
  • Fail Error 22
  • Fail Error 23
  • Fail Error 24
  • Fail Error 25
  • Fail Error 26
  • Fail Error 27
  • Fail Error 28
  • Fail Error 29
  • Fail Error 30
  • Fail Error 31

If you encounter an unused/undocumented error it should be treated as non-recoverable on the grounds that if it occurs the system is grossly malfunctioning.


FDUMPM

DP4 file dump program - can be used to examine low level contents of database files. This program does not work with data files of databases that use a database format introduced in release 4.622.

Command Tail | Description
−DECODE | Attempt to decompress/decrypt data


FIXDB22

Program to update databases created prior to the 4.500 release. This operation cannot be reversed and runs with rollback logging disabled, so make sure you have a copy of your database in case anything goes wrong or you want to run the 4.4xx release again.

Command Tail | Description
−SYSTEM | Supply this (with -DB SYSTEM) to run against the system database
−KEY | Makes extra checks on key fields to fix earlier bug in MAKEDB
−MAPS | Perform additional changes on database fixed with earlier FIXDB22


FIXDB23

Program to update 4.5xx databases for use with 4.6xx releases. The database remains compatible with 4.5xx. This program runs with rollback logging disabled, so make sure you ahve a copy of your database in case anything goes wrong and you need to restore your database and rerun FIXDB23.

You can also use this program against a 4.6xx database if you want to adopt a new standard form for names

Command Tail | Description
−SYSTEM | Supply this (with -DB SYSTEM) to run against the system database
−KEY | Makes extra checks on key fields to fix earlier bug in MAKEDB
−MAPS | Reconvert maps from 4.500
−FIXMAPS | Correct problems caused by bugs in MAPEDIT
−CCNAMES | Convert dictionary and QAB names to camel case (REC_NAME to recName)
−LCNAMES | Convert dictionary and QAB names to lower case (REC_NAME to rec_name)
−MCNAMES | Convert dictionary and QAB names to mixed case (REC_NAME to RecName)
−UCNAMES | Convert dictionary and QAB names to upper case (recName or rec_name or RecName to REC_NAME)
−NOEMBEDDED | Create overlapping controls instead of embedded fields
−NOAUTO | Ignore automatically generated alignment characters in 4.500 maps
−NOBOXES | (From 4.618) Remove 4.5xx box characters from converted maps
−SMARTEN | Automatically convert dialogs to 3D appearance
−SMARTENMORE | (From 4.618) Similar to -SMARTEN but works on maps that may not be dialogs - may be useful for databases designed for text based systems.
−SMARTENMORE | Similar to -SMARTEN but works on maps that may not be dialogs - may be useful for databases designed for text based systems.
−QAB | Restricts name case conversion options to working only on QAB name table.
−DD | Restricts name case conversion options to working only on database name table.

You can specify both -QAB and -DD to convert just table field and QAB names. Without either option all type S fields in the base dictionary will be converted, e.g. Report Names, Printer names etc.


FIXNET

Fixes the network control tables. Some spare fields in @NETWORK are renamed to reflect their new use and the new table @NET_STATUS is added and can then be browsed using BROWSER or QAB programs.

This program is only needed for databases originally created with a 4.4xx version of DP4


FIXREPS4

Report Writer program patcher. To be used when upgrading from a release prior to 4.400.


Functions which generate Fail errors but not System errors

The following functions can generate fail errors but not system errors. All can generate Fail Error 9 and Fail Error 13, except for sf_open() which generates only 9.

Function | Additional Error code on fail 13 | Other fail errors
sf_cksum() | 64 |
sf_close() | 27 | 27
sf_flush() | 26 | 22, 25, 26
sf_get_size() | 20 | 20
sf_get_position() | 21 | 21
sf_open() |  | 3, 17, 18, 19
sf_read() | 23 | 22, 23, 25, 26
sf_read_record() | 23 | 22, 23, 24, 25, 26
sf_seek() | 22 |
sf_track() | 30 |
sf_write() | 25 | 22, 25, 26
sf_write_record() | 25 | 22, 25, 26
sf_buff_mode() | 26 | 22, 25, 26
tf_discard() | 65 |

The tf_() versions of these functions generate the same errors, except that they cannot generate fail 9. tf_() files typically generate errors with a filename. Errors from sf_() versions never have a filename (except a spurious one in some 4.4xx releases).

The sf_() functions can also generate fail 7 errors in a network environment when the network fails.

The return codes of these functions are corrupt in the event of a fail, so that continuing execution may cause problems.


Functions which should not generate System or Fail Errors

The following functions should not generate system or fail errors when 4.600 TRMn and SRVn are loaded, (except as noted)

_swaph()
_swapl()
_cksum()
bf_close()
date_add_number()
date_compare()
date_ok()
date_subtract_date()
date_to_number()
df_make_name()
dvc_get_inp_source()
field_banned()
field_cursor() (generates sys_error(3) with pre 4.515 TRM)
field_force_colour()
field_force_range()
field_force_size()
freep()
freex()
heap_avail()
heap_init()
mallocxable()
map_old_position()
map_use()
number_to_date()
os_exec_prog()
os_scan_env()
pattern_match()
prn_abort()
srv_disable() (The library ignores any errors returned)
srv_end_process() (The library ignores any errors returned)
srv_load_srv()
srv_init_process()
str_lcase()
str_ucase()Rtail_found()
tail_read()
tail_get_option()
tf_check()
tf_default()
tf_delete()
tf_disk_reset()
tf_end_tf() (The library ignores any errors returned)
tf_get_date_time(),
tf_init_tf()
tf_read_sysdata()
tf_rename()
tf_round_number()
tf_set_date_time()
tf_space()
tf_trunc_number()
trm_beep()
trm_clr_ahead()
trm_colour()
trm_ctrls()
trm_curs_off()
trm_curs_on()
trm_cursor()
trm_end_trm() (The library ignores any errors returned)
trm_get_access()
trm_get_hwnd() (generates sys_error(3) with pre 4.515 TRM)
trm_raw_input()
trm_read_user()
trm_load_trm()
trm_lookchr()
trm_set_progname()
trm_set_training_mode()

The following functions do not generate system or fail errors. However, if you have written a mallocx_handler(), and that is called it might generate a system or fail error.

mallocp()
mallocp_fixed()
mallocx()
mallocx_fixed()
reallocx()
cache_start()
cache_describe()
cache_find()
cache_post()
cache_lock()
cache_unlock()
bf_open()

The following functions can only generate a Fail Error 9 (IPC error), or Fail Error 7 in a network environment when the network fails.

sf_get_date_time(),
sf_set_date_time()
sf_read_sysdata()
sf_check()
sf_default()
sf_disk_reset()
sf_rename()
sf_space()
sf_delete()


Getting Started

This section introduces all the following topics, and tells you where you can find more information on them:

  • Installation
  • Configuration
  • Running DP4
  • Building Databases
  • Programming
  • Maintaining Databases
  • Supporting a DP4 System


HLPI

Help message editor used as sub-program. It is not possible to call this program directly. It is not used with v 4.6xx releases except when running programs using the 4.5xx terminal manager.


IMPPOST

Imports data from an external file into a DP4 database using a program created with IMPSETUP

Command Tail | Description
−IMPORT name | Specify the file to import
−DATADB name | Post records to the named database rather than that containing the parameter sets
−PARA name | Specify the parameter set to use
−NOLIST | Suppress the listing of imported data
−TEST | Test the parameters without posting them
−COMFORT n | Display a count of records processed - the count is updated every n records
−POST | Post records from the file
−NOSUMMARY | Suppress details of successes and failures
−PAUSE | Pause after completion of import
−NOCUT | Do not remove leading spaces from delimited parameter sets
−COMMIT n | Commit every n records


IMPSETUP

Sets up Importer Programs, which IMPPOST runs to import data onto a database.

See Setting Up Importer Programs and Automatic Creation of Importer Programs in the DP4 Developer's Manual for further information about this program.

Command Tail Option Specific Tails/Description

−EXTRACT

Restricts IMPSETUP to Extract option

−ALL |  | Extract all programs
−PROG name |  | Select program to be extracted
−SCREEN -FILE name -DEVICE name -PRINTER | } | Selects target file/devices for extraction

−POST

Post one or more programs from extract files (a list of filenames may be specified)

−QUIET

Don't echo file during post

−RENAME

Rename options

−PRINT

Print programs

−ALL |  | Print all programs
−PROG name |  | Print named program
−SCREEN -FILE name -DEVICE name -PRINTER | } | Selects target file/devices for printing

−TEST

Test the import program

−ALL |  | Test all programs
−PROG name |  | Test named program
−SCREEN -FILE name -DEVICE name -PRINTER | } | Selects target file/devices for report

−DELETE

Delete import program

−ALL | Delete all programs
−PROG name | Delete named program


Installation

Before you install DP4, make sure that you have the latest installation notes for the operating system that you are using. The installation instructions will be different according to the release of DP4, and the operating system of the computer you are installing on. You can find notes for Installing on Windows based operating systems here, and notes for Installing on Unix/Linux or AIX here. The Installation notes also cover the steps necessary to preserve information when upgrading from an earlier DP4 release. Please check these notes carefully when installing a new DP4 release, as there are often changes from release to release.

Whether or not DP4 is already installed on your system, you will usually have the option to install DP4 using an Install program. This will guide you through all the steps of installing DP4.

On any platform DP4 will only run properly on your machine when the following files are present:

  • A DP4 licence file, (DP4.SYS or DATAFIT.SYS), copied from your DP4 License Distribution disk is present. (You may be able to use a licence file copied from another DP4 installation machine, if this is not to hand, though this can cause problems).
  • A Terminal Configuration file , (USERDATA.SYS), either copied from the installation media or created by running the USERDATA utility.
  • The SYSTEM database files (SYSTEM.IND, SYSTEM.DAT, and, from release 4.622, SYSTEM.DCI and SYSTEM.PTR) are in the correct location(s).
  • The database and terminal managers (SRVn and TRMn), and other core files such as the various DP4 DLLs used on Windows installations are present.


KENTCURS

This utility sets up flags and version information that is stored in the header of a program file. The version information can be displayed by the PROGDATE utility, or, on most versions of Windows, using the Version tab in the Properties Dialog for the file. An example of the output from PROGDATE is shown below.

DP4 File Version Details and Verification Utility

File           CKS   Version           Date        Class      Release Status
                                       Comment
c:\dp4\WIN\SRVW32.EXE
               31322 4.620(006)500 102 11 Apr 2003 Standard   Release    WIN32

KENTCURS can be used on files containing a DP4 version stamp. Programs written in C/C++ which are linked with the DP4 C "CCOWN" library will always contain this, and you can add one to other C/C++ programs by including the verstamp.c file in the set of source files for the program.

If a Windows application or DLL contains a Windows version resource, KENTCURS will also set the information in the resource using data from the DP4 version information.

The command tails for KENTCURS are shown below:

Command Tail Description

filenames

Specify the files to be maintained

−READ filename

Take the filenames from the named file

−CLASS suffix

Set the program class as follows (specify the initial or the full suffix):

suffix | class
STD | Standard
ADDITIONAL | Additional
KOREA | Korean
JAPAN | Japanese

This is used to distinguish various special builds of DP4 from the "standard" release

−DATE

Set the issue date to the current date

−FILEDATE

Set the PROGDATE date to the file date

−VERSION n

Set version number to n (This the number displayed after 4. in PROGDATE, 620 in the example above)

−LEVEL n

Set patch level number to n (This is the number displayed in parentheses after the version by PROGDATE, (006) in the example above)

−BUILD n

Set build number to n. This is displayed after the patch level by PROGDATE, (500 in the example above). In standard DP4 utilities it is only used to indicate the "build family" of the program. The Build Number as displayed in the version resource is set using the -internal option

−INTERNAL n

Set "internal number" to n. PROGDATE displays this number immediately before the program date, (102 in the example above). For standard DP4 utilities it is the most important version number as it allows us to identify the exact set of files used to build the program.

−STATUS n

Set the status to number n or ALPHA or BETA or RELEASE

−NOPAUSE

To prevent pause at the end

The following options apply to 16 bit executables only:

−NOCONVERT | Disable operating system conversion
−MAXSTACK |
−STACK SIZE | Set stack size (hex)

The following options apply to OS2 executables only:

−OS2

Set corresponding property in OS/2 header;

−COMPAT

The following options apply to WIN32 executables only:

−WINDOWS | Program will detach from console window if started from console
−CONSOLE | Program remains attached to console if started from console windows or create a console if started from a program that does not have a console. You may need to set DP4 executables to be CONSOLE programs if you want to run via Telnet.

The following options apply to UNIX/Linux programs only:

−PATCH or −NOPATCH | No longer used
−BREAK or −NOBREAK | -nobreak causes program to ignore SIGINT, -break (default) causes program to terminate on SIGINT
−STRIP or −NOSTRIP | -strip (default except for debug versions) removes symbols and shrinks comment section. -nostrip prevents debug and comment section from being removed from executable

The following options (intended mainly for internal use) apply to "source" files only:

−DP4 | Tag as a DP4 file by adding a DP4 version stamp, which means that PROGDATE can be run against it
−COMMENT "text" | Allow the insertion of a comment (up to 32 characters) for files such as .C .OBJ .LIB .SYS .BAT


LIBMAKE

Source file Pre-processor. Makes 'include' files for application programs. For further information see Using LIBMAKE to Generate Declarations and Code in the DP4 C/C++ Programmer's Reference.

Command Tail | Description
filenames | Specify the filenames to process
−OFFSET n | Offset column number of toggles in the file
−QUIET | Suppress echo to the screen


LOAD

Loads table data from an ASCII file created by UNLOAD into the target database.

See Transferring Data with the Load and Unload Facility in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−DELETE | Deletes data from the table(s) in the file before posting the new data.
−ERROR | Causes an error to occur if a fielf does not exist on target database table. The default is that its absence is ignored.
−FILE name | Use the named file as the import file
−QUIET | Do not display the data in the import file


Loader Errors

Under Windows NT family operating systems loader errors may be written to the Application Event Log (but only if DP4 is run as a service), and the Event Log may contain considerably more information than is displayed on screen. However you may need to use DP4 error logging to find out more about the error.

Loader Error codes are normally only reported by SRVW32.EXE, though it is in theory possible for some of them to be generated by other programs, because they are mostly generated inside DLLs such as SYSLIBT.DLL that are used by almost all DP4 programs. Error codes reported by Windows as "Service Specific Errors" when you start and stop the DP4 service from the control panel or using net start are this type of error.

The error messages associated with loader errors are stored in the DP4 configuration file in the [errmsg] like this:

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_61=Dialer error: Unable to create dialup connection
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:
errmsg_99=Loader error: Unable to start Service - See Application Event log for details

Other messages of this type existed in older versions of DP4, but were seldom if ever encountered. If you encounter an error of this type not listed here it will be listed as Loader Error number retcode number. If this happens please contact Itim Technology Solutions for further information.


LOGCOPY

Copies a database log file to another location, either on a one-off basis, or at regular intervals. There is no user interaction whatever, except possibly via the -ALERT command line option. All this program's command line options can be specified as settings in the [LOGCOPY] section of DP4.INI if you prefer.

Command Tail | Description
−ALERT command | This option is only used if a non-zero value is specified for -INTERVAL, in which case it must be specified. command will be executed if the copy operation fails consecutively more than the number of times specified for the −ALLOW_FAILURES option. For example you might run a simple QAB program to alert the user that there is a problem with copying the log file, or you might generate an e-mail message to alert a techinal support team. LOGCOPY will execute this command line without adding any parameters to it, so you should include any parameters that may be needed, such as the name of the machine and database in the value given for command, which should therefore usually be given in quotes. If you wish to add information such as date and time to the command line then invoke a batch file to do this.
−ALLOW_FAILURES n | This option is only used if a non-zero value is specified for -INTERVAL, in which case it specifies the number of times the copy operation is allowed to fail before the command line given in the −ALERT option is eexecuted. If no value is specified for this option then the value is 2, which means that if the copying option fails continually that the "alert" command will be run on every third failure.
−DB database_name | Specifies the name of the database whose log file is to be copied. This option must be specified.
−FROM_SERVER server_name | Specifies the DP4 name of the server containing the database whose log file is to be copied. If not specified the default server for the installation is used. This option is only respected when DP4 is loaded in the "named connection" configuration.
−INTERVAL n | If this option is not specified, or is explicitly set to 0, then LOGCOPY will attempt to copy the log file once, and will then exit. The exit code will be 0 if the copy succeeded and 1 otherwise. If a non-zero value is specified for this option then LOGCOPY will attempt to copy the log file every n seconds, except that if the database timestamp is unchanged since the last successful copy (during the current LOGCOPY session), the copy operation will be skipped.
−TO_PATH path_name | Specifies the location on the destination server to which the database log file should be copied. This option must be specified. This might be a second hard drive, a network drive or a device such as a flash drive (USB stick). Note, that if a network drive is used, LOGCOPY must be run in an appropriate user account and not as part of the DP4 service.
−TO_SERVER server_name | Specifies the DP4 name of the server to which the log file is to be copied. If not specified the default server for the installation is used. This option is only respected when DP4 is loaded in the "named connection" configuration.

Notes

  1. LOGCOPY is intended to be used in combination with DYNABACK -COPY to provide additional data security in the event of a hard drive failure. Typically you will configure your system to run DYNABACK -COPY on a nightly basis. When the backup succeeds you will copy the database to a separate location, probably the same location as you use for storing the transaction logs copied by LOGCOPY. Then during the day you would copy the transaction log at regular intervals, for example every 10 minutes, to ensure that even in the event of a hard drive failure, you will lose very little data. For additional security you should choose to keep the regular transaction log on a separate hard drive from the data file for the database. The copy of the transaction log created by LOGCOPY is then a third line of defence against data loss which would be needed if the hard drive containing the data file, and the hard drive containing the regular transaction log both fail.

  2. If you use LOGCOPY in the suggested manner, and are copying to a "solid state" device, which typically has the characteristic that it can only be written to a finite number of times, then you should choose the frequency of the copying to give the best compromise between data security and maximising the life time of the device. Copying too frequently, say every 30 seconds, will impact performance of DP4, and reduce the life time of the device.

    LOGCOPY has been written because some customers were choosing to keep the transaction log on such devices. However, this is unwise, at least on Windows based computers, because the operating system is prone to reporting that the device has been removed when it has not. In addition the transaction log file is flushed very frequently, and this will shorten the life time of the device, and is typically quite slow compared with flushing a file on a regular hard drive.

  3. LOGCOPY copies the log file alternately as dbname.lb1 and dbname.lb2. If the log file is successfully copied the previous copy of the log file will be erased. Therefore the location where the log file is to be copied must have space for at least two copies of the largest anticipated transaction log. Note that while the naming scheme is similar to that followed by dynaback there is no logical connection with it: it is almost certain that you will sometimes have a backup using "b1" file extensions, and a transaction log using the "lb2" file extension, or vice versa

  4. There is no automated method of restoring the log files created by LOGCOPY. Typically, in the event of needing to recover a database after a hard drive failure, you will simply copy the various b1 or b2 database backup files to the corresponding "live" database filename (cb1 → dci, db1 → dat, ib1 → ind, pb1 → ptr), and the lb1 or lb2 to the log filename. To apply the log file use the −LOGONLY option of DBRESTOR


Maintaining Databases

Your DP4 databases contain valuable data, which you do not want to lose. Make sure you know how to back them up, and restore them from a backup. You also need to know how to check your database is healthy, and about the utilities you can use to recover or rebuild a database. For information on all these topics refer to Maintaining a Database in the DP4 Developer's Manual.


MAKEDB

Sets up/modifies the data dictionary.

See Creating a Database in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−DATA | Data independence is invoked for all tables as though they contained data.
−DIRECT | Prevent MAKELINK from creating new indirect index links
−DISTANCE n | Create MAKELINK links up to distance n. (The default is 4)
−EXPERT | Set up additional information (select tables for local access on a network, hashed index or non-unique keys, use the PHYS_INDEX index, store data without padding)
−LINK | Perform MAKELINK as you go along
−NOCOPY | Suppress copying of the Base Dictionary if the database does not exist (for example for use in networks)
−NONEWINDEX | Any new direct secondary indexes are created with the index disabled. SETLINK must be used to enable the new indexes that are required. This will avoid the unnecessary creation of secondary indexes.
−NOISY | Verbose Makelink phase (this slows it down a lot)
−USER | Restrict operation to cosmetic changes
For exporting database structure:
−AUTODEFAULT | Include default values of autoincrement fields in print out. Normally this is omitted so that the default is taken from the value on the target database.
−EITHER | When extracting selected tables, include index information if either the child or parent table is one of the extracted tables. The default behaviour only includes indexes where both tables are extracted tables, which is usually not helpful.
For posting database structure:
−BYNUMBER | Number to take precedence over name in Table/Field matching


MAKELINK

Sets up links in the data dictionary. This program is usually run from within MAKEDB.

See Index Link Analysis in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−DIRECT | Construct only the direct links and not the indirect links required by Report Writer and QA Build
−DISTANCE n | Create indirect links only up to distance n. The default is 4.


MAPEDIT

Sets up, edits, deletes or prints maps on a database.

4.5xx version

No online documentation is currently available for this version of the MAPEDIT program. It is described in the old (printed) version of the DP4 Developers manual.

Command Tail | Description
−MAPNAME name | Select the mapset to work on
−MAPNR n | Select the map number to work on
−LANGUAGE n | Specify the language to work on
−CHANGES | Produce change files
−DELETE | Select delete only
−PRINT | Select printing only
−ALL | Perform action (print or delete) on all mapsets
−MAPPOST | Print out in MAPPOST format
−NORMAL | Print out in documentation format, for word processing use
−HELPS | Include help messages in printout
−NOHELPS | Do not print help messages
−NOHEAD | Suppress page header information on printout
−NONUMBER | Prevent field numbers being printed in documentation format
−MULTILANGUAGE | Select multi-language operation for deleting, printing and making change file

4.6xx version

The 4.6xx Map Editor does not contain facilities for printing or exporting maps. You can use MAPMAKE as a front end into the Map Editor to gain access to these additional facilities.

See the 4.600 Map Editor User Guide for further information about this program.

Command Tail | Description
−MAPSET name | Select the mapset to work on
−MAP n | Select the map number to work on. In place of n you may specify db\mapset\map or mapset\map
−LANGUAGE n | Specify the language to work on
−USER name | Reads options from the MyUser section of MAPEDIT.INI


MAPMAKE

This is a 4.6xx only program designed to supplement MAPEDIT. Sets up, edits, deletes or prints maps used by QAB and by generated programs.

Command Tail | Description
−MAPNAME name | Select the mapset to work on
−MAPNR n | Select the map number to work on
−LANGUAGE n | Specify the language to work on
−CHANGES | Produce change files
−DELETE | Select delete only
−PRINT | Select printing only
−ALL | Perform action (print or delete) on all mapsets
−MAPPOST | Print out in MAPPOST format
−NORMAL | Print out in documentation format, for word processing use
−HELPS | Include help messages in printout
−NOHELPS | Do not print help messages
−NOHEAD | Suppress page header information on printout
−NONUMBER | Prevent field numbers being printed in documentation format
−MULTILANGUAGE | Select multi-language operation for deleting, printing and making change file
−NOSCHEMES | Stops colour information being printed when using 4.600 MAPMAKE


MAPPOST

Posts maps from text files to databases

Command Tail | Description
filenames | Specify the list of map files to be posted
−DELETE | Delete the existing mapset before posting new one
−NOHELPS | Omit the posting of HELP messages
−OFFSET n | Offset column number of the toggles in the file
−QUIET | Reduce screen output to improve speed
−SILENT | Suppress all output except error messages
−OVERWRITE | When posting device information forces overwriting where clashes occur
−RENUMBER | When posting device information, devices that clash with those already present are renumbered
−CHECKBOX | (v 4.5xx only) Attempt to convert 'Yes/No' fields to checkboxes by looking for ? characters
−NOICONS | (v 4.5xx only) Cause the icon marking characters to be ignored
−MAXWIDTH value | (v 4.5xx only) Warns when posting maps wider than value


MENUEDIT

Sets up menus and maintains language and user data. Also prints menu in documentation or MAPPOST formats.

See Managing Users in the DP4 Developer's Manual for further information about this program. In 4.6xx releases the actual editing of menus is handled within the MAPEDIT program. Editing menus directly from MAPEDIT is described in the Editing DP4 Menu Pages section of the DP4 4.600 Map Editor User Guide.

Command Tail | Description
−LANGUAGE n | Specify the Language to work on
−PRINT | Select printing only
−DELETE | Select delete only
−ALL | Perform action (print or delete) on all mapsets
−MAPPOST | Print out in MAPPOST format
−NORMAL | Print out in documentation format (for word processing use)
−HELPS | Include help messages in the printout
−NOHELPS | Do not print help messages
−USERS | Set up menu users for the system
−NOHEAD | Suppress page header information on printout
−PAGELIST | Include page cross-reference in printout

MENUEDIT provides two sets of parameters for either special commands or command tails:

Menu Option Commands (for example %PAGE)

%DB | Change to another database, specified by the command tail
%LOGOFF | Return to the logon screen
%LOGON | Prompt for user name and password
%LOCKUP | Prompt for password of the current user
%NOSTATUS | Turn off the database status map at top of menu screen
%PAGE | Go to the specified menu page without executing a command
%PASSWORD | Allow the user to change the password
%PREFERENCES | Allow the user to change the preference settings
%STATUS | Turn on database status map
%SYSTEM | Terminate the menu and return to the operating system

Option Command Tails (for example, PROGCOMP %PAUSE)

%BATCH | Look for a .BAT file if .EXE and .CMD not found
%CLOSEDB | Close database while program runs
%DB | Current database name is substituted
%LOGON | For 4680 only
%NOCLEAR | Suppress clearing the screen
%PAUSE | Pause with 'Press any key to continue' message after the program has run
%SYSTEM | Remove DP4 interface programs, SRVn and TRMn, while the program runs
%1,%2,...%9 | Prompt for the values to substitute for these variables using the map you have set up


MENUUSER

Sets up the menu users for the system. This program duplicates part of the functionality of MENUEDIT. It may be useful where you want to allow and admninistrator on the live system to be able to manage the user list on the DP4 system database, but you do not want to allow him to create his own menu structure.

See Maintaining the User List in the DP4 Developer's Manual for further information about this program.


NETBIOS return codes

     NB_ILLEGAL_BUFFER_LEN                        1
     NB_INVALID_COMMAND                           3
     NB_COMMAND_TIME_OUT                          5
     NB_MESSAGE_INCOMPLETE                        6
     NB_DATA_NOT_RECEIVED                         7
     NB_ILLEGAL_LOCAL_SESSION                     8
     NB_NO_RES_AVAILABLE                          9
     NB_SESSION_CLOSED                            10
     NB_COMMAND_CANCELLED                         11
     NB_DUPLICATE_NAME                            13
     NB_NAME_TABLE_FULL                           14
     NB_CMND_CMPL_DEREGISTERED                    15
     NB_SESSION_TABLE_FULL                        17
     NB_SES_OPEN_REJECTED                         18
     NB_ILLEGAL_NAME_NUMBER                       19
     NB_REMOTE_NAME_NOT_FOUND                     20
     NB_LOCAL_NAME_NOT_FOUND                      21
     NB_NAME_IN_USE                               22
     NB_NAME_DELETED                              23
     NB_SESSION_ENDED_ABNORMALLY                  24
     NB_NAME_CONFLICT                             25
     NB_INTERFACE_BUSY                            33
     NB_MAX_CMNDS_EXCEEDED                        34
     NB_INVALID_ADAPTER                           35
     NB_CMND_ALREADY_COMPLETED                    36
     NB_CMND_INVALID_TO_CANCEL                    38
     NB_NAME_DEFINED_BY_OTHERS                    48
     NB_ENVIRONMENT_NOT_DEFINED                   52
     NB_NO_OS_RESOURCES                           53
     NB_MAX_APPL_EXCEEDED                         54
     NB_NO_SAP_AVAILABLE                          55
     NB_INADEQUATE_RESOURCES                      56
     NB_INVALID_NCB_ADDRESS                       57
     NB_RESET_INVALID                             58
     NB_INVALID_DD_ID                             59
     NB_SEGMENT_LOCK_UNSUCCESSFUL                 60
     NB_DD_OPEN_ERROR                             63

     NB_OS_ERROR_DETECTED                         64
     NB_PERM_RING_STATUS                          79

     NB_UNEXPECTED_CCB_ERROR                      246
     NB_ADAPTER_OPEN_ERROR                        248
     NB_ADAPTER_HANDLER_ERROR                     249
     NB_ADAPTER_CHECK                             250
     NB_CODE_NOT_OPERATIONAL                      251
     NB_OPEN_FAILURES                             252
     NB_UNEXPECTED_CLOSE                          253
     NB_COMMAND_IN_PROCESS                        255


NETCOPY

Copies files across a network and times and dates from one machine to another. For full details of this utility refer to NETCOPY in the Guide to DP4 Networking and Resilience.

Command Tail | Description
−FROM filename | Specify filename to copy
-TO filename | Speicfy name of file to copy to (if not specified filename is same as -FROM name)
−TIME | Copies data and time to or from the server. For example, NETCOPY -TIME -TOSERVER sends the time to server 1
-TOSERVER | If specified file or time copying copies from client to server. Default is to copy file from server and set time from server
-SERVER n | Only relevant when AUXDISTR is in use. Specifies server number of "server" machine. In other configurations you may be able to use the -server_name standard command tail.

You can use either -from filename or -time but not both. Note that wildcard filenames are intentionally not supported.


NUMBSYS

Changes the number implementation for a database to another programming language. From 4.620 you would normally access this utility from within MAKEDB. The process of changing the number system is similar to that of selecting a number system for a new database, described in Selecting the Database Number System in the DP4 Developer's Manual. However for an existing database, changes between some number systems require the database and programs to be rebuilt. This will result in a warning message askiing you whether or not to proceed.

Make sure you have a backup of your database before running NUMBSYS, and if a system failure occurs while NUMBSYS is converting a database, restore the backup and do not attempt to carry on using the database. This is particularly important when either the old or new database number system is number system 9, because if the conversion is interrupted, the original database will remain, but will probably be in an inconsistent state.


Other functions

The following list contains all DATAFIT.H functions not already discussed.

The second column lists the errors that may arise when they are called using:

  • Groups which describe the various classes of error
  • Individual error numbers (system errors unless otherwise stated)
  • Names of functions called by this function whose errors may also therefore be generated
Function | Errors
askf() | D
askf_x() | D
askf_colour() | D, M
askf_db() | D
askf_password() | D
askf_special() | D
askm_radio() | D
askm_special() | D
bf_fetch() | C, 42
bf_reset() | C
blk_fetch() | C
blk_fetch_main() | C
db_checkpoint() | B
db_commit() | B
db_close() | B
db_decommit() | A
db_get_flag() | A
db_get_generation() | A
db_get_status() | A
db_open() | A, 11-19, 31-37, 142, 150, 173, 174
db_set_flag() | B
db_set_generation() | B, 26
db_set_status() | B, 26, 30
db_update() | B
dvc_check() | 129
dvc_choose() | M, D, 126, 127, dvc_check()
dvc_close() | X, dvc_check()
dvc_get_status() | 156, 157
dvc_open() | C, 126, 127, dvc_check()
dvc_set_inp_mask() | 156
dvc_set_subdevice() | C, X, 122, 128, dvc_check()
extract_close() | F
extract_open() | F
extract_read() | F
extract_sort() | trm_run_program()
extract_write() | F
field_ban() | D
field_char_get() | X
field_choose() | D
field_eg_choose() | D
field_eg_inner() | D
field_colour() | D
field_end() | X
field_find() | D
field_help() | C, X
field_highlight() | X
field_map_length() | C, X
field_read() | X
field_skip() | D
field_start() | D
form() | X, C, 122, 131
form_beside() | form(), 124
form_over() | form(), 123
form_test() | form(), P
inpm() | D
inpm_x() | D
inpm_ban() | D
inpm_bb() | D
inpm_xnp() | D
inpm_colour() | D, M
inpm_e() | D, M
inpm_ge() | D, M
inpm_omit() | D
inpm_special() | D
map_activate() | X
map_alter() | X
map_askf_y() | M, D
map_attach() | M
map_bar_choose() | M, D
map_change() | M, D
map_choose() | M, D
map_clear_after() | X
map_clear_all() | X
map_clear_from() | X
map_clear_remarks() | X
map_copy() | X
map_datamap() | M
map_draw() | M
map_draw_over() | M, 2
map_g_choose() | M, D
map_get_depth() | M
map_get_inputs() | X
map_get_width() | M
map_glue() | X
map_hide() | X
map_items_to_scroll() | X
map_key_meaning() | X
map_kill() | X
map_load() | X
map_menu() | M
map_new_position() | X, 136
map_new_window() | X
map_old_window() | X
map_pause() | M, D
map_predisplay() | M, D
map_remark() | M
map_reveal() | X
map_set_scroll_end() | X
map_so() | X
map_switch_language() | X
map_yes() | M, D
mem_describe() | X
mem_empty() | none (X with 4.500 DOS GUI TRM2)
mem_find() | X
mem_post() | X
open_database() | M, db_open()
pick_list() | M, D
pick_record() | M, D
prn() | P
prn_append() | X
prn_attach_form() | P, 131
prn_x() | P
prn_length() | X
prn_over() | P
prn_print() | X, dvc_check()
rec_autoinc() | A, 28, 29, 143
rec_child_copy() | C
rec_fetch() | C
rec_fetch_main() | C
rec_kill() | U, 27
rec_kill_ignore() | U, 27
rec_parent_copy() | C
rec_post() | U
rec_post_commit() | B
rec_post_with_flags() | U
rec_retrieve() | A, 59
rec_verify() | U
show() | D
show_attach() | M, D
show_bitmap() | D
show_x() | D
show_colour() | D, M
show_extra() | D, M
show_more() | D, M
show_graphic() | D
show_over() | D, M
show_resource() | D
show_special() | D
srv_enable() | F + Fail 5
srv_mem_describe() | 8 (type 1)
srv_mem_post() | F, 8
srv_mem_find() | F, 8
sys_del_confirm() | M, D
sys_message() | M
sys_request() | M
sys_upd_confirm() | M,D
tf_txt_read() | tf_read()
tf_txt_seek_end() | tf_read()
tf_txt_write() | tf_read() or tf_seek() errors.
tf_txt_close() | tf_write() or tf_close() errors.
trm_check_logged_on() | 252
trm_co() | X
trm_control_subclass() | X
trm_grabchr() | X
trm_init_trm() | X
trm_refresh() | X
trm_set_preferences() | C, X
trm_so() | X
trm_run_program() | X
trm_screen_dump() | X
trm_unset_preferences() | X
trm_write_syslog() | X
wkf_open() | X, 154
wkf_post() | X, 155
wkf_fetch() | X, 9, 155
user_auxdbms() | A


PATCHER

DP4 Hex File Editor/Viewer - can be used to examine low level contents of files.

This program is a simple Hex editor, which you can use if you do not have access to a more powerful utility of this type. It has one sigificant advantage over many similar programs - it does not need to read the whole file into memory when it starts up. It is therefore often very fast compared to other programs if you want low level access to large DP4 database files.

In an emergency, you can unset the flag which indicates that a database requires DBRECOV to be run, by setting byte 6C in the IND file of a database to 0. Using a database in this state can cause DP4 to crash, and there can be no guarantee of the data in the database.

The only command tail for this program is the name of the file to open.


Portability

DP4 is designed to be portable across different platforms. This means that a database and application programs set up and developed under one operating system such as MS DOS may be run without change or recompilation under another operating system such as UNIX.

There are some limitations, especially in regard to Windows. For example, an upgrade procedure must be followed to convert a database and applications from MS DOS to Windows. This is described in the DP4 Windows Installation guide and the relevant Release Notes.

Further information is provided in a technical reference document available on request from DP4 support.


PRINTDB

Produces a data dictionary listing.

See Printing the Data Dictionary in the DP4 Developer's Manual for further information about this program.


PROGBIND

A utility which allows you to configure a system built using the "PlaceHolder" facilities of PROGMAKE for operation on different target systems.

Command Tail | Description
−ATTACH NNnn | Bind variant nn of group NN into system. If nn is 0, the current variant is detached
−DETACH | Resets (detaches variants from) all the PlaceHolders


PROGCOMP

The QA Build program compiler. Run after creating or amending QA Build programs.

Refer to Compiling a QA Build Program in the QA Build Developer's Manual for more information about how to use this program.

Command Tail | Description
−PROG name | Specify the program to compile
−ALIGN | Aligns data in accordance with the packing used on RISC type machines
−ALL | Compile all programs regardless of status
−CHANGED | Compile only changed (or new) programs
−COMPATIBLE | Ensures compatiblity of compiled code with versions of PROGRUN as old as 4.515
−VERSION nn | Put the version number nn into the compiled program
−NOCC | Suppress the generation of C files
−GENERIC | Produce C files for generic PROGRUN or C exits from subprograms
−HEAP nnnnn | Allows you to compile program larger than 64k. Limit of extra 56K
−NOISY | Display procedure names during compilation
−PAUSE | Pause after -ALL or -CHANGED
−PRIVATE | Increase the speed of overlay switching by not passing the value of local variables and tables beginning with @ between programs
−SHARE | Force the use of shared mode
−DEBUG | Put additional information into the program for PROGRUND (to allow the debugging of QA Build programs)
−SHRINK | Reduce the size of the compiled program
−SIZE nnnnn | Specify maximum program size in bytes. The theoretical maximum value is 64K -1 (65535) but values above 65500 may compile incorrectly. If you want to use values above 42000 on a 16 bit system, you will have to create a customised version of PROGRUN
−400 | Do not recognize "global" variables introduced since 4.400 (may be useful for compiling very old QAB programs)

Compilation errors are usually sent to the screen. You can redirect the output with the standard -FILE, -PRINTER options


PROGDATE

Reports version information for DP4 files. Use KENTCURS to add DP4 version information to programs. Some typical output from PROGDATE is shown below:

DP4 File Version Details and Verification Utility

File           CKS   Version           Date        Class      Release Status
                                       Comment
c:\dp4\WIN\SRVW32.EXE
               31322 4.620(006)500 102 11 Apr 2003 Standard   Release    WIN32

You can use the standard printing command tails with PROGDATE. For example include the command tail -FILE filename to direct the output to a file.

As well as reporting version information PROGDATE can also often detect when an executable file has been changed since its DP4 Version information was set (for example because a virus has written to it). When a change is detected PROGDATE always displays Corrupt after the Release Status.

The other command tails for PROGDATE are as follows:

Command Tail |  | Description
filenames |  | Specify the filenames, including their path if they are not in the current directory
−READ filename |  | Take the list of files from the named file
−CHECKSUM −FULL | } | Additionally give checksums for DP4 utilities
−EXPORT |  | Changes the output format to CSV, suitable for import into a spread sheet or database
−NOHEAD |  | Suppress the page header

If you ever find a standard DP4 component for which the version information has not been set up (typically indicated by a version number of 4.000 and a Null build date), then the file has not been correctly issued, and should never be used in a live site.

You are recommended always to use the -full command tail when checking the version of standard DP4 utilities with PROGDATE. The number immediately before the date, 102, in the example above is an internal build number which allows us to retrieve the exact set of components used to build that version of the program. -full also causes the file's checksum to be displayed, and a comment in some cases.

See also Viewing DP4 Version Informaion


PROGMAKE

The QA Build program setup/amend program.

Refer to Using the Program Editor in the QA Build Developer's Manual for more information about how to use this program.

Command Tail | Description
−PROG name | Specify the program to process
−ID initials | Automatically enter the initials for recording in edited programs and procedures
−NO_MESSAGE | Stops automatic generation of messages. Messages will only be generated when you choose to do so explicitly.
−SHARE | Permit several users to work on the same database


PROGPRN

Prints out QA Build program details

Command Tail | Description
−PROG name | Specify the program to print
−ALL | Print all programs
−CHANGED | Print only changed programs
−NOISY | Display printer names during printing
−SHARE | Permit several users to work on the same database
−NOHEAD | Suppress page header information on printout
−MULTILANGUAGE | Print out maps for all languages
−NONUMBER | Suppress the printing of field numbers in maps
−400 | Suppress the printing of standard variables introduced since 4.400


Programming

There are several ways you can create programs that use your DP4 databases. For an overview see DP4 Programming Tools in the Introduction to DP4.

  • To learn about programming using C and C++ refer to the DP4 C/C++ Programmer's Reference.

  • To learn about programming using QA Build, or QA Build with C refer to the QAB Developer's Manual

  • To learn about using Report Writer to create Reports refer to the Report Writer Developer's Manual

  • To learn how to export information from your DP4 database so that it can be imported by other programs/systems and how to write Importer programs to import data from other systems refer to Copying Data between Databases in the DP4 Developer's Manual.

  • To learn about using SQL, or connecting to DP4 databases from other products via ODBC, or connecting to other databases from DP4 programs refer to the DP4 SQL Products Guide.


PROGRUN

Runs compiled QA Build programs

Refer to Running a QA Build Program in the QA Build Developer's Manual for more information about how to use this program.

Command Tail | Description
−DATADB dbname | Specify the database to run the program against
−DB dbname | Specify the database to load the program from. Unless the −datadb command tail is specified this is also the database the program is run against.
−DUMMYC | Allow the test running of a program which includes C exits, without those exits being linked
−PROG name | Specify the QA Build program to run
−QXE path | Specifies the location to use for QXE files and QA Builds own workfile
−VERSION | Display the version number and run the program

QA Build programs can also read command tails, and programs that print use the standard DP4 command tails for selecting the print device.


PROGRUND

A special version of PROGRUN with debugging output. You must run PROGCOMP -DEBUG before PROGRUND. See Debugging Programs in the QA Build Developer's Manual for further information.

Command Tail | Description
−PROG name | Specify the QA Build program to run
−VERSION | Display the version number before running the program
−DUMMYC | Allow the test running of a program which includes C exits, without those exits being linked
−DATADB name | Runs program using data from the specified database instead of the database from which the program was loaded
−QXE | As for PROGRUN


PROGRUNS

A version of PROGRUN for use in low memory environments. It takes up around 10K less memory than PROGRUN, by dropping support for rarely used functions in QAB formulas (i.e. trigonometric and other scientific functions). Not available for 32-bit Windows

See PROGRUN for information on command tails.


QABUTIL

QA Build utilities, including transfer of QA Build programs from one database to another, program and procedure renaming, consistency reporting, and deletion of unused maps, formulas and programs.

Refer to QABUTIL in the QA Build Developer's Manual for more information about how to use this program.

Command Tail Option Specific Tails/Description

−PROGUTIL

Restrict QABUTIL to the transfer option

−ALL |  | Extract all the QA Build programs
−PROG name |  | Select the program to be extracted
−TREE name |  | Select the procedure tree to be extracted
−PROC name |  | Select the procedure to be extracted
−BODY name |  | Select the procedure body to be extracted
−MACRO name |  | Select the macro or C function to be extracted
−EVERY |  | Extract every macro and C function
−NOMACROS |  | Suppress the extraction of macros
−NOMAPS |  | Suppress the extraction of maps
−MULTILANGUAGE |  | Print out maps for all languages
−SCREEN -FILE name -device name -printer | } | Selects target devices for extraction

For posting files:

−POST | Post programs (and supply list of filenames if desired)
−QUIET | Don't echo file during post
−NOICONS | Don't post icons in file (4.5xx only)
−CHECKBOX | Attempt to convert 'Yes/No' fields to checkbox fields (4.5xx only)
filenames | List the files to be posted

−RENAME

Restrict QABUTIL to the rename option

−WEED

Restrict QABUTIL to the weed option

−ALL |  | Process all the unused QA Build data
−MAPNAME name |  | Process unused maps in this mapset
−PROC name |  | Process unused entry conditions for procedures
−BODY name |  | Process unused formulas for procedure body
−DELETE |  | Delete data
−REPORT |  | Produce a report without deleting
−QUERY |  | Delete formulas, query map deletion
−SCREEN -FILE name -device name -printer | } | Selects report device

−IMPACT
−CORRECT
−MISSING

Runs the appropriate option from the Analysis (or Impact prior to 4.620) menu. −missing is new in 4.620. Prior to 4.620 both −impact and −correct are required to select the corrections option.

−SCREEN
-FILE name
-device name
-printer

}

Selects report device

−DELETE

Restrict QABUTIL to the deletion option

−ALL | Delete all QA Build programs
−HIDE | Hide all programs, without deletion
−PROG name | Delete the named program
−DELMAPS | Delete programs and maps
−NOMAPS | Keep maps from deleted programs
−ORPHAN | Delete orphaned data
−QUERY | Query map deletion
−REPAIR | Fix problems caused by deleting programs

−FIND

Restrict QABUTIL to Find option

−PROC name | Specify the QA Build procedure to be searched
−BODY name | Specify the procedure body to be searched
−PROG name | Specify the QA Build program to be searched

−HELP

Popup menu of help topics


RECASTDB

RECASTDB is used to copy structure information and data in selected tables from one database to another.

See Transferring the Database Structure in the DP4 Developer's Manual for further information about using this program to transfer database structure, and Transferring Data for information on using it to transfer ordinary database data.

From 4.620 RECASTDB can also be used to synchronise a "local" or "satellite" database (for example one stored on a Windows CE PDA) with a "master" database (for example one stored on a Web Server accessed via a Dial up internet connection). The term "satellite" is preferred to "local" because in some modes of operation, the "local" database will actually be remote! With synchronisation data transfer may be two way. In what follows "upload" refers to data transfer from the "satellite" to the "master" database, and "download" refers to the reverse operation. The "source" database is the database from which data is currently being copied, and the "target" database the one to which this data is copied, or from which it is deleted. The terms "upload" and "download" are used regardless of the actual method of data transfer − both uploads and downloads can be achieved by running RECASTDB at either side of a network connection - in one case end the data will be pushed to the other,in the other it will be pulled from the other. Wherever possible you should choose to push data as this will generally be much faster and consume less network resource.

Synchronisation can be controlled using information contained in a configuration file, the name of which is specified as a command line option when RECASTDB is started. It is envisaged that several different configuration files might be created to synchronise databases in different ways.

The synchronisation facilities of RECASTDB are not currently intended to cope with the situation where both databases may contain inconsistent updates to the same table.

Principles of Operation

Prior to release 4.620 the method used to reconcile two databases is as follows:

  • The method for deleting from a table is to read all the records from the table on the database to be updated. For each record read RECASTDB attempts to read the corresponding record on the source database. If the record is not found the record is deleted from the target database.

  • The method for updating a table is to read all the records from the source database. For each record read RECASTDB attempts to read the corresponding record on the target database. If the record is not found, or is different in any way the record is posted to the target database.

If RECASTDB is being used to synchronise databases held on different machines accessed via a slow network these methods can cause RECASTDB to run very slowly. In 4.620 there are options that cause RECASTDB to use alternate algorithms that may well result in its running much faster.

  • In 4.620 RECASTDB may be able to use timestamp information to "filter" the records in the tables being processed. For example after a "download" table has intially been synchronised with the satellite database, RECASTDB will optionally record the timestamp of the master database at the start of synchronisation on the satellite database. Next time RECASTDB is run it will optionally fetch this information again and automatically exclude from consideration records on the source (master) database whose timestamp indicates they have not changed since the last synchronisation. A similar facility is available for "upload" tables. In this case RECASTDB records the timestamp of the satellite database. During upload records unchanged on the satellite database since the last synchronisation are excluded from consideration.

    Unfortunately, the need to maintain compatibility with previous releases of DP4 means that the same field has to be used for remembering both the "upload" and "download" timestamp. This means that for each table timestamp information can only be used for one of "upload" and "download". Also you cannot use the timestamp option for download tables if there is more than one "master" database. The timestamp option will not work properly if ADCs that do not pass fetch() operations on to the DP4 database manager are loaded.

    In the unlikely event of a catastrophic database loss on the master machine the timestamp information on the satellites will be useless until it is reset from a new copy of the master database. In this case you will need to run a special configuration file that ignores the timestamp information when synchronising but sets it once synchronisation is completed. You should rigorously enforce a secure backup strategy to ensure the master database cannnot be lost.

  • For processing of deletions you can specify an algorithm that works by reading data from the source database. Records that match a specific condition are unconditionally deleted from the target database. Note that for this algorithm to be useful your DP4 application must initially avoid deleting data on the source database. Typically, instead of deleting you would update the record on the source database setting a boolean field such as "deleted" to TRUE. The condition to delete would simply be "deleted" (the syntax used is the same as for QAB and Report Writer). RECASTDB will then delete all the records that have the "deleted" flag TRUE from the target database. If the target database is a "master" database RECASTDB will optionally delete the records from the source "satellite" database as well once they have been deleted from the target "master" database. If the source database is a "master" database RECASTDB will not delete the data from it, because it is assumed that there will be many "satellite" databases requiring updating. (You would need to keep track of which "satellite" databases have been updated yourself and only delete the records from the "master" database once all the satellites have been updated.)

  • For processing of updates there are several new possibilities:

    • You can specify that data transfer should take place unconditionally using a "−copyall" option. This avoids the requirement for RECASTDB to test the record on the target database. In any case the DP4 database manager would perform a similar test prior to actually making the update. In the case where the target database is initially empty, or nearly so, or where a large proportion of the records have changed this option may reduce the time needed to transfer the table by 50%. If the test would have eliminated most transfers using this option will not necessarily be beneficial. However, it will probably still save time if the database being updated is accessed over a slow network.

    • You can specify that data transfer should take place based on a condition (again using QAB syntax). In this mode of operation, which can be combined with timestamp filtering, no test is done on the target database - if the condition is satisfied the record will be transferred. A typical use of conditions might be to place additional limits on the data to be transferred. For example if RECASTDB is being used to synchronise a PLU table with handheld devices it might be desirable only to transfer a subset of the price information to each handheld, perhaps based on a department code. This information would have to be recorded in the [settings] section of a configuration file. This is read automatically by the formula processor built into RECASTDB. For example if you specified a condition such as DEP_CODE=CFG_DEP_CODE, where DEP_CODE is a name of a field in the table being transferred and CFG_DEP_CODE is not, the formula processor will look for a string of the form CFG_DEP_CODE=xxxx in the [settings] section. Currently [settings] variables are always strings; they can be converted to numbers using the numtochar() function in the formula processor. Normally the configuration file is read from the machine where RECASTDB is being run. If you want to download data from the master to the satellite using information from the satellite configuration file you need to use the −remote_config option instead of the −config option. You could obtain the name of a configuration file to use by creating a remote connection from a C or QAB program and querying the database.

    • You can specify a field, and a formula for it. If a record is succesfully transferred to the target database the records is also posted back to the source database with the field set to the new value. You might use this to exclude the record from consideration at the next synchronisation (supposing that you had specified a condition on the transfer that involved this field).

  • For both update and delete operations you can specify that RECASTDB should read he table on a specified index instead of the main index. In this case you must provide a formula for the first keyfield in the selected index. Only records with this key value will be fetched from the source database. This option may allow you to make a futher improvement in performance by reducing the number of records to be read from the source database. For example rather than using the "deleted" field in a condition as in the example above you might choose to set up a secondary index on the "deleted" field. However, this should only be done if absolutely necessary - in general even quite large tables can be transferred very quickly, and the overhead of maintaining extra indexes may offset any saving in search time.

Command Tails for RECASTDB

Command Tail Description

−APPL

This option omits the structure change part of synchronisation when the −distributed or −synchronise options are in use. This command line option is not available if a configuration file is used and the corresponding option must be specified in the configuration file instead.

−BYNAME

Transfer data where fields or tables have different internal numbers. Compatibility test by name only. This option should not be used when synchronising databases (in theory it ought to work, but it has not been tested except for making changes to two local databases)

−CONFIG filename

Specifies the name of a configuration file that describes how RECASTDB is to run. The configuration file is read from the local machine. If no path is specified it is assumed to be in the same direction as the other DP4 configuration files. This option is only intended for use with the −synchronise and −distributed options. 4.62x only

−COPYALL

When copying tables this option suppresses the test for whether the record is already present. This option is not used if a configuration file is used, and is currently only implemented in the 4.62x RECASTDB.

−COPYDB

This command tail causes recastdb to do a structure transfer from the from database to the to database. The transfer is purely a dictionary transfer - no maps, QAB or Report Writer programs etc. are transferred. In addition there is no warning if REORGDB will be required afterwards. This option, introduced in release 4.622/4.526, is intended to simplify the upgrade process for systems using the "split database" facility. Typically when upgrading you issue a new "program" database, and need to apply the structure of this database to the existing "data" database. You will usually want also to specify the −quiet option when using this option.

−DB name

Specify the database to use with the −synchronise or −distributed options

−DELETEALL

When deleting tables this suppresses the test for whether the record is present on the source database. All data is deleted from the target database. This option is not used if a configuration file is used, and is currently only implemented in the 4.62x RECASTDB.

−DISTRIBUTED

Selects a special mode of operation that transfers structure and data between a local and a remote copy of the same database. You must be running either a local resilience or multiple resilience network configuration for this option to work. Normally, this option will be used in conjunction with a configuration file. If no configuration file is specified tables marked as "local table only" (when viewed with makedb −expert) are downloaded, and tables not so marked are uploaded. (This may well seem to be back to front,the rationale is that a "local table" is usually used to store fairly static data to reduce the need to access a remote database, and a not "local only" table is only updated locally when the "master" database is offline. The "local table only" settings are ignored when a configuration file is used, and if you are not using them already you are recommended to ignore them.

−FROMDB name

Specify the database to transfer from (not used with the −synchronise or −distributed options)

−LOCALMASTER

Informs the −synchronise option that the server specified in the −synchronise option is a "satellite" database, and that the default server is the "master" database (by default the opposite is assumed).

−NODD

When transferring structure information, omits dictionary tables. This is only safe if the data dictionaries are already identical.

−NODOWNLOAD

Omits the transfer of changes from the "master" to the "local" database. This command line option is not available if a configuration file is used and the corresponding option must be specified in the configuration file instead.

−NOMESSAGE

Suppresses the message about REORGDB being required which may be generated when doing a structure transfer. Added in 4.526/4.622

−NOUPLOAD

Omits the transfer of changes from the "local" to the "master" database. This command line option is not available if a configuration file is used and the corresponding option must be specified in the configuration file instead.

−QUIET

Reduces screen output to a minimum during the MAKELINK phase of structure transfer. This may improve performance significantly, especially on Microsoft Windows (running RECASTDB minimised will also speed things up.)

−REMOTECONFIG filename

This option is only available with the −synchronise option and specifies the name of a configuration file that describes how RECASTDB is to run. The configuration file is read from the machine specified in the servername value specified with −synchronise. If no path is specified it is assumed to be in the same direction as the other DP4 configuration files. This option will not work if TCPMGR is loaded with the −nocopy option.

−RUNONLY

Restrict copying of QA Build tables to those required by PROGRUN

−SYNCHRONISE servername

Selects a special mode of operation that transfers structure and data between a local and a remote copy of the same database. You must be running with a networked configuration of DP4 that supports named connections, i.e. using a TCP/IP network requester in in one of the following configurations:

  • a simple client
  • a local resilence client
  • a named connection configuration
The last of these is probably the best option to use as it becomes possible to organise for upload and download to be done simultaneously with RECASTDB being run with an upload only configuration at the satellite machine and a download only configuration at the master. Normally, this option will be used in conjunction with a configuration file. If no configuration file is specified tables are copied in the same way as is described for the −distributed option.

−TODB name

Specify the database to transfer to (not used with the −synchronise or −distributed options)

RECASTDB configuration files

A RECASTDB configuration file allows you to gain a very high degree of control over the operation of RECASTDB. In many cases using a configuration file will allow you to synchronise data between two different copies of a database without the need for writing special programs.

The configuration files are formatted like a Windows INI file. There are a number of sections, demoted by headings in square brackets, and each section contains entries in the form key=value.

Global options are specified in the [defaults] section. For each table that is copied RECASTDB also looks in the [tablename.download] or [tablename.upload] sections for table specific settings. Default values for several of these options are taken from the [upload] and [download] sections.

[defaults] section

appl=1 | Omits the structure transfer phase of synchronisation. If appl=0 is specified explicitly, a partial structure transfer is performed. However the dictionary tables are not transferred − i.e. the −NODD option is always in effect for synchronisation.
check_structure=1 | Before transferring data RECASTDB normally checks the structure of tables is compatible on both databases. If the check_strucure=0 option is specified this check is omitted. This option should only be used where you are absolutely certain the databases have identical dictionaries, and the structure check will take too long, for instance if you are running over a very slow WAN or internet connection.
download=1 | If the value is 1 the download phase of synchronisation is performed. If it is 0 it is not. Ideally download should be performed by running RECASTDB on the "master" machine using the −synchronise and −local master options. This will significantly reduce the amount of data transfer over the network and hence gives improved performance. The −reverse option of tcpmgr can be used to automatically launch a script or other program that can then call RECASTDB like this to transfer data (you may even launch RECASTDB directly, but you may want to run another program that will decide whether or not to run RECASTDB based on the date or time or information held on the master database.).
upload=0 | If the value is 1 the upload phase of synchronisation is performed. If it is 0 it is not. Ideally download upload be performed by running RECASTDB on the "local" machine using the −synchronise option. This will significantly reduce the amount of data transfer over the network and hence gives improved performance.

[upload] and [download] sections

These sections contain entries that set default values for the table specific options. These values will be used for tables for which no values is specified for the corresponding entry in the table specific section.
copy=1 | If copy=1 tables are uploaded or downloaded by default, even if they are not referred to in the configuration file.
delete=download | If delete=1 tables are processed for deletion by default, even if they are not referred to in the configuration file. This option defaults to 1 for the [download] section and 0 for the [upload] section.
mode=0 | If mode=0 is specified all records selected from tables on the source database are copied. If mode=1 is specified then only records matching specified table specific conditions are processed. The condition defaults to "all", so it does not matter if you don't specify a condition for a particular table.
use_timestamp=download | If use_timestamp=0 is specified all records selected from tables on the source database are copied, subject to the other conditions, if any, specified for the table. If use_timestamp=1 is specified then in addition to the other conditions, records for upload are excluded unless their timestamp indicates that they have been created/updated on the satellite since the last synchronisation, and records for download are excluded unless their timestamp (on the master) indicates that they have been created/updated on the master.

[tablename.upload] and [tablename.download] sections

Most settings in these sections have the same format in both cases. Settings in the [tablename.upload] section are used when copying a table from the "local" to the "master" database. Settings in the download section are used in the reverse case.

condition=boolean formula | This entry, only used when mode=1, specifies the condition used to decide whether to copy a record from the source to the target database.
copy=default_copy | If copy=1 the table is uploaded or downloaded in acoordance with the other settings. If copy=0 the table is not copied.
delete=default_delete | If delete=1 records are processed for deletion in accordance with the other settings for the table. If delete=0 the table is not processed for deletion.
delete_both=0 | This entry, only used when delete=1, causes data that is to be deleted from the target database also to be deleted from the source database.
delete_condition=boolean formula | This entry, only used when mode=1, specifies the condition used to decide whether to delete a record from the target database.
index=index_table.index_role delete_index=index_table.index_role | Normally RECASTDB will search through an entire table when looking for records that should be copied/deleted. You can use this option, together with the index_value/delete_index_value entries to limit the amount of data searched.
index_value=formula delete_index_value=formula | This specifies the formula to be used for the first keyfield when the index or delete_index entries are used.
mode=default_mode | If mode=0 is specified all records selected from the table on the source database are copied. If mode=1 is specified then the condition or delete_condition specified is used to filter records.
set_timestamp=use_timestamp | If set_timestamp=0 is specified (or implied) the timestamp associated with synchronisation for this table is not updated. If set_timestamp=1 is specified (or implied because use_timetamp=1) then after a successful synchronisation the timestamp associated with the table on the satellite databases is updated.
update_field=field_name.field_role | This specifies a field to be updated on the source database for records that are transferred during an upload (or download, though this is unlikely to be useful). Records are only updated when the transfer succeeds. Unfortunately, it is impossible to absolutely guarantee that the update will be made, though it will only fail in exceptional circumstances.
update_value=formula | This specifies a formula that assigns a new value to update_field.
use_timestamp=default_use_timestamp | If use_timestamp=0 is specified all records selected from the table on the source database are copied, subject to the other conditions, if any, specified for the table. If use_timestamp=1 is specified then in addition to the other conditions, records for upload are excluded unless their timestamp indicates that they have been created/updated on the satellite since the last synchronisation, and records for download are excluded unless their timestamp indicates that they have been created/updated on the master.


REDn or REDW (in Windows)

Enables DP4 programs to take input from a text file instead of the keyboard, or to record keyboard input into such a file for later use.

This utility must be used in conjunction with a DP4 program, for example:

RED2 DP4 -READ PROGFILE

See Creating an Automatic Demonstration with Redirect in the DP4 Developer's Manual for further information about this program.

Command Tail |  | Description
−AUTHOR filename −WRITE filename | } | Create file for future use with -READ option
−APPEND filename |  | Append any new data to existing file
−READ filename |  | Read specified file for program input /Note that there is NO default directory or extension for 'filename'
−SAFEMODE |  | Alters ESC key behaviour to display a menu, that allows you to interrupt a demonstration and continue running the program manually, rather than exiting immediately
−TESTMODE |  | If an error occurs, produce message and quit without operator input


REORGDB

Reorganises/rebuilds a database. See Reorganising the Database in the DP4 Developer's Manual for further information about this program. It is intended to replace the -HOLES option, little used in the past, and withdrawn as of release 4.622, with an improved "Defragment Database" Option.

Command Tail | Description
−ADVANCED | Updates database structure to use new 4.622 features. Only effective if -DATA is also specified.
−BUILD table index role | Rebuild individual indexes
−CORRUPT | Allow the reorganisation of the index of a database which has the corrupt flag set. This option will fail if the data file contains corruptions. If you intend to use option 1 to rebuild the database it is advisable also to specify the −NOSQUEEZE command tail to prevent the data file from being altered.
−DATA | Rebuild the data and index files and bring all data up to the current database generation. For databases with enahnced data compression this option calculates the optimal compression strategy for the database.
−DEFRAGMENT | New option for 4.622, only available for databases using "Two File Index". Quick reorganisation that optimises index and sorts data file for faster database access.
−DELETE | Allows option 7 (data deletion) to be selected so that you can delete data from selected or all tables. Normally option 7 is hidden and disabled.
−DELETION −TABLE a −TABLE b... | Selects option 7, and deletes data from selected or all tables. Using this option (which rebuilds the database completely) may be faster than deleting data using normal deletion operations if all or most of the data on the database will be deleted.
−FILE name | Reads tables to delete from file
−HEAP n | Allocates the heap size; n is heap size in kilobytes. Default is 4096 up to release 4.621 and 16384 from release 4.622. Values in excess of 32878 are unlikely to improve performance significantly.
−INDEX | Rebuild the index file (option 1) and combine unused space on the data file. The -DATA option will usually give better results and is only marginally slower than this option.
−LOCAL | Allow speed optimisation where database is on the same machine as REORGDB. This command tail is not needed from release 4.525/4.621 onwards
−NOSPACE | Omit the disk space check. There is no need to use this command tail as of release 4.622
−NOSQUEEZE | Causes option 1 only to build a new index, and to suppress all non vital data file changes.
−OPTIMISE | Rearrange the index to improve performance. From release 4.622 this may also reduce the size of the index file significantly
−RESET | Causes all timestamps to be set back to 0. May be needed if database timestamp has reached its maximum value.
−ROLLBACK | Enable rollback recovery for database reorganisations using -HOLES or -BUILD command tails
−RESET | Enables the database timestamp reset to 0. Stops DBERA and SRDD from working properly.
−ALTSORT −SORT | When the data file is rebuilt using option 3 or option 7, both these command tails attempt to reorder the database data file to improve performance by sorting data into primary key sequence. The −ALTSORT option sorts each table separately, the −SORT options groups related tables together (so that order_line records stay near the corresponding order header record for example). From release 4.622 these command tails are only relevant when the -corrupt option is used, because normally the data file is built by fetching all the data from the old database in primary key sequence, thus sorting the data perfectly.In release 4.621, the −ALTSORT option significantly improves performance, both of REORGDB, and of the reorganised database.
−SORTSIZE n | The number of bytes of key information used for sorting. The default is the entire key. 0 reorders the data by table numbers ignoring the key information
The command tails below are obsolete from release 4.622
−400 | Build a database compatible with release 4.230 or 4.400.
−FAST | Speed up options that build a new index, at the expense of building less efficient and larger index. This option is unlikely to speed up REORGDB except on medium sized databases.
−HOLES | Combine all unused space in the data file
−PINDEX | Turn on physical indexing for all tables. Physical indexing is not supported from release 4.622, because it normally offers no advantage over using the primary index
−REUSE | Re-use the space occupied by deleted records. This option is only relevant on databases where the "keep deleted" records flag is set for one or more tables, usually as a result of having used SRDD against the database. This flag is ignored by release 4.622.
−SHUTDOWN hh:mm (24 hour clock) | Force holes option to terminate at specified time


REPPRINT

Runs Report Writer programs created using REPSETUP

Refer to the Report Writer Manual for information on this program.

Command Tail |  | Description
−DATADB database name |  | specifies database with data; default is to use database containing program
−PARA name −PROG name | } | Specify the Report Writer program name
−COMFORT n |  | Display a count of records processed - count is updated every n records
−START pagenumber |  | Page to start/restart printing
−PAUSE |  | Pause at end of each page
−RANGE |  | Extract only within range of values. The operator will be prompted for the values for the key fields of the driving table
−SUBTOTAL |  | Force sub-total only report
−GRANDTOTS |  | Force grand totals only report
−DELETE |  | Confirm deletions for Delete programs
−EXHEADS |  | Include headings on EXPORT output
−NOTRAIL |  | Suppress report trailer
−NOCOPY |  | Suppress DP4/REPORTER/DELETER message on page headings
−NOERROR |  | Do not produce an error report
−SCREEN |  | Direct print to screen
−PRINTER |  | Direct print to printer
−KIND |  | Allow re-selection of print device
−FILE filename |  | direct print to specified file
−NEW |  | Delete the existing file when sending output to a file
−DEVICE |  | Select attributes for printer or file output
−EXTRACT filename |  | Force the creation of extract file
−REPRINT filename |  | Reprint from the specified extract file
−ERRSCREEN |  | Direct errors to screen
−ERRPRINTER number |  | Direct errors to printer
−ERRFILE filename |  | Direct errors to specified .PRN filename
−ERRDEVICE name |  | Use the named device for formatting errors
−JOINFAIL IGNORE |  | Ignore error and use default values
−JOINFAIL SKIP |  | Omit items with join failure
−JOINFAIL QUIT |  | Terminate on join failure
−JOINFAIL ASK |  | Prompt run-time for the join failure action to take
−DIVFAIL IGNORE |  | Ignore divide by 0 error, uses default values
−DIVFAIL SKIP |  | Omit items with divide by 0
−DIVFAIL QUIT |  | Terminate on divide by 0
−DIVFAIL ASK |  | Prompt run-time for the divide by 0 action to take
−ARGS filename |  | Specify the REPPRINT command tails in a file


REPSETUP

Sets up Report, Export and Deletion Report Writer programs to be run by REPPRINT.

Refer to the Report Writer Manual for information on this program.

Command Tail Option Specific Tails/Description

−MAXWIDTH width

Over-rides default absolute maximum width for report programs of 500. If you use this option you should print to a print device with a suitably wide page width, otherwise the output will be truncated.

−EXTRACT

Restricts REPSETUP to extracting Report Writer programs to ASCII files

−ALL |  | Extract all programs
−PROG name |  | Specify program to be extracted
−SCREEN -FILE name -DEVICE name -PRINTER | } | Select target file/device for extraction

−POST name

Post the Report Writer program from the named ASCII file

−QUIET

Don't echo file during post

−PRINT

Print programs

−ALL |  | Print all programs
−PROG name |  | Specify program to be printed
−SCREEN -FILE name -DEVICE name -PRINTER | } | Select target file/device for report
−DETAIL |  | Select detailed format

−RENAME

Restrict REPSETUP to renaming Report Writer programs

−TEST

Test a Report Writer program (and upgrade from an earlier release)

−ALL |  | Test all programs
−PROG name |  | Specify program to be tested
−SCREEN -FILE name -DEVICE name -PRINTER | } | Select target file/device for report

−DELETE

Restrict REPSETUP to deletion

−ALL | Delete all programs
−PROG name | Specify program to be deleted


RESWORDS

Posts reserved words to BD (use -DB dbname to post to another database). For further information about this program see Reserved Words in the DP4 Developer's Manual.

Command Tail | Description
filename... | Name of one or more text files containing reserved words
−DELETE | Delete existing words
−QUIET | Stops files being echoed to screen as they are posted


Programmers/Testers developing DP4 applications are strongly encouraged to run this utility as part of the process of testing their applications, as rounding errors in floating pointer numbers can cause problems (for example inaccurate totals).

ROUNDER

Analyses the data in the tables in an application database, reporting on and optionally correcting any invalid data such as inexact floating point numbers, invalid dates or times etc. Unless you specify various command line options the program only checks floating point values for fields that are not keyfields anywhere.

Command Tail | Description
−ALL | Turns on all checks (same as -null -keys -date)
−DATE | Also check date and time fields
−KEYS | Also check type N fields that are keyfields. Combining -keys and -post options can cause duplicate records to be created, as ROUNDER does not attempt to delete any data.
−NULL | Also check that character fields using a 0 as their first character, contain all character 0, and for character fields that are not keyfields ensure any characters after a character 0 are all 0.
−PAD | Also checks that all padding bytes are set to zero
−PAD | Also checks that all padding bytes are set to zero
−POST | Report on and correct errors
−REPORT | Report on errors but do not correct them


SETDATE

Allows user to set the system date and time. This utility will fail to set the date and time without warning if the user does not have the right to set the system time. It is provided so that you can give the user a common method of setting the system date and time regardless of operating system.

Command Tail | Description
−SERVER | Set the above on network servers as well


SETLINK

Sets the flag settings on table link records. From 4.620 you will usually run this utility from withing MAKEDB. Using this utility is described in Index LLink Scrutiny in the DP4 Developer's Manual.


SETSESSN

Performs a dummy backup by incrementing the session number without backing up the database. You can use DYNABACK to perform a dummy backup of a database while it is in use.

See Performing a Dummy Backup in the DP4 Developer's Manual for further information about dummy backups.

Command Tail | Description
−DBCHECK | Perform a dummy DBCHECK
−DELETE | Delete the log file
−NODELETE | Do not delete the log file
−NOINCSEQ | Do not increment the database session number.
−NOINCLOGSEQ | Do not increment the transaction log sequence number.
−SILENT | Suppresses all screen output


SHUTDOWN

Provides options to close a database or remove the database manager (SRVn) from memory

See Shutting Down a Database in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−NOREMAIN | Reset the memory-resident option in the database manager SRVn (specified as -REMAIN when loaded)
−NOWAIT | Closes down a database immediately. Programs using the database will crash
−SILENT | Suppresses all screen output. It is a good idea to specify this command tail when using the −STOP option as otherwise the shutdown might not succeed if the system was in an unstable state (for example the system database is corrupt or missing).
−STOP | Unloads DP4
−WAIT | Wait for all users to log off from the database before closing.


SORTEXTR

Sorts a DP4 format extract file. Runs automatically when a program calls the extract_sort() function

Command Tail | Description
filename | Specify the file to sort


SRVn

Database Manager program. In the 32/64 bit Windows version of DP4 the actual database manager is called DP4SRVR.W32 or .W64 (.WCE on Windows CE) and it is not loaded directly but by the DP4 loader program, which is called SRVW32.EXE. DP4SRVR accepts the command tails listed here, but SRVW32 has its own completely different set of command tails.

Command Tail | Description
−REMAIN | Except on Windows platforms when the database manager is auto-loaded it is loaded in such a way that it will terminate once at least one DP4 program has run against it, and there are no DP4 programs running any more. On these platforms if you want the DP4 database manager to stay loaded you should load it manually and supply the −remain command tail.
−NOREMAIN | Allows the database manager to unload when a DP4 program terminates (Windows versions only). On Windows platforms the database manager is loaded permanently by default.
−BUFFERS n | Sets the disk buffer to n Kb
−SMALL | Uses the least amount of memory possible, probably at the cost of impaired performance
−SHARELOG | Opens transaction log in shared mode
−EXTENDED | MS-DOS only. Puts buffers in extended memory
−EXPANDED | MS-DOS only. Puts buffers in expanded memory
−LOGIN name | For SRV9 only, forces the database manager to log on as a user to the file server. This limits DP4 to about 240 processes
−NODISABLE | For local resilience: application runs without server using local database if server is unavailable when program starts, but if server terminates while application is running, application will terminate.
−NOCRASH | For local resilience: application runs without server using local database, but if server terminates with current transaction, there will be a checkpoint failure
−NOFAIL | For local resilience: application runs without server on local database, and if server terminates during a transaction, there will not be a checkpoint failure
−READLOCAL | For local resilience: when used on requester, DBBACKUP and DBRESTOR work on the remote database
−AUX | Notifies Database manager that an Auxilary Database Controller (ADC) is being used. Refer to the ADC Developers' Manual for further information.
−230 | Turns new features added since 4.420 to retain compatibility with older releases. In particular this makes the reuse of space occurpied by deleted records less efficient but speeds up deletion to some extent.

*32-bit Windows is loaded with the command SRVW32 -START or SRVW32 -LOAD. The [startup] section of the DP4 Configuration File specifies how DP4SRVR.W32 is loaded.


SRVW32/SRVWCE/SRVW64

SRVW32/SRVW64/SRVWCE

The DP4 System loader program for Win32 platforms. For historical reasons the name is different on each platform. It would be better if this were not the case, because the program is essentially the same on all platforms. This program accepts as a command tail anything that can be specified in the DP4 configuration file that is relevant to it, or to the error log program. The list of command tails below is therefore not exhaustive and only includes options that are frequently useful. Command tails that are options that can only take values 0 or 1 can be specified two ways:

  • −tail=n where n is 0 or 1, or simply
  • −tail which corresponds to setting the option to 1

Values specified on the command line over−ride the settings in the DP4 configuration file.

The behaviour of srvw32 is rather different on Windows NT based operating systems (NT and Windows 2000) from Windows 9x based systems, and some command tails behave differently. In particular if SRVW32 is started without a command tail that selects how it should run (−load, −unload, −start, −stop, −install, −uninstall), then on Windows NT it asks if the DP4 System should be installed as a service (usually after an annoyingly long delay while it tries and fails to become a service process), whereas on Windows 9x it behaves as though srvw32 −load was specified.

Generally speaking there is no need to start the DP4 system by running SRVW32. The auto-load mechanism can usually start the DP4 system in the correct configuration if a DP4 program is run when the DP4 System is not running.

The DP4 loader starts DP4 by executing programs listed in the [preload] and [startup] sections of the DP4 configuration file.

Command Tail | Description
−debug_echo | Causes the error log program, if loaded, to display a viewable window contain the diagnostics.
−install | On Windows NT SRVW32 creates the registry information required for running the DP4 system as a Windows NT Service, and also defines the DATAFIT environment variable. This facility is not available on Windows 9x machines. Local administrator rights will be necessary to be able to do this.
−load | Attempts to start the DP4 System as an application.
−load_errlog | Causes SRVW32.EXE to load the DP4 error log program. This command tail is a useful alternative to having to edit the DP4 configuration file to load error logging.
−preload=section | Causes SRVW32.EXE to process the named section of the DP4 configuration file as a replacement [preload] section. This can be useful where DP4 must be run in a variety of configurations on the same machine.
−start | On Windows NT srvw32 attempts to start the DP4 System as a Windows NT Service (which usually requires local administrator or Server Operator rights on Windows NT, or "Power Users" on Windows 2000 or later rights). On Windows 9x −start is synonymous with −load.
−startup=section | Causes SRVW32.EXE to process the named section of the DP4 configuration file as a replacement [startup] section. This can be useful where DP4 must be run in a variety of configurations on the same machine.
−stop | On Windows NT platforms causes SRVW32.EXE to attempt to stop the DP4 System service. This is how you should stop DP4 on Windows NT/2000 where DP4 is run as a service (for example by running srvw32 −start). On Windows 9x platforms −stop and −unload are synonymous. On Windows NT family operating systems you will usually need the same user rights as described for the -start option above.
−uninstall | On Windows NT SRVW32 removes the registry information required for running the DP4 system as a Windows NT Service. Local administrator rights will be necessary to be able to do this.
−unload | Unloads the DP4 system when it is running as an application. This is how you should stop DP4 on Windows NT/2000 where DP4 is not run as a service (for example by running srvw32 −load). On Windows 9x platforms −stop and −unload are synonymous.

Please refer to the Guide to DP4 Configuration for information on how to configure the DP4 System for Windows.

Notes on 64-bit Windows

On 64-bit versions of Windows srvw64 and srvw32 are almost interchangable. For example, if your startup section specifies that you should use dp4srvr.w64 as the database manager, both srvw32.exe and srvw64.exe will happily load it. Furthermore if you run srvw32 -start it is not necessarily the case that the DP4 service will be run by srvw32.exe. The service process is determined by the registry, so if you have previously run srvw64 -install, it is that program that will run the DP4 service, no matter whether you use srvw32 -start or srvw64 -start. By contrast, if you run DP4 as an application then, the program that you start with -load is the program that will control the background DP4 applications. Therefore, when installing 64 bit DP4 on 64-bit Windows it is important to make sure your dp4.ini is set up correctly. For example, you should make sure that the loader section in the [win32] section is set to use srvw64.exe and not srvw32.exe. Note that there is no [win64] section in dp4.ini. Both 32-bit and 64-bit DP4 use the [win32] section for Windows specific configuration options.


Standard Command Tails

The following command tails are common across all DP4 utilities:

Command Tail Description

−DB DBNAME

Override the default database name for utilities that use a database

−DB pathname/dbname

To open a database on a different location to that specified in DFSETUP. For example:
BROWSER -DB A:\MYDATA
which will access the mydata database on the disk in drive a:

Only use this form of the -DB command tail when absolutely necessary, and please note the following restrictions:

  • DP4 will not allow you to open two databases with the same name in different locations. If a second program opens a database with the same name as a database that is already open it will be opened in the location the first program is using.

  • On Windows platforms, if DP4 is running as a service in the local system account you will not be able to access databases on a network drive using this technique.

−BASEDICT

Provide access to the base dictionary tables (for expert users of DP4)

−SERVER_NAME machine_name

From version 4.523/4.619 this command tail can be used when running DP4 on client machines that use the DP4 TCP/IP network requester to select the DP4 server to run against. See -server_name Command Tail for Applications in Guide to DP4 Networking and Resilience for further information.

−HELP

Popup the help message for the utility - this will usually be similar to the Quick Reference information for the program

Command Tails for Printing

The following command tails used to control the destination of "printed" output are especially useful:

Command Tail | Description
−SCREEN | Send device output to the screen
−PRINTER | Send device output to the printer port
−FILE filename | Send device output to a file
−DEVICE device_name | Select the device to determine the characteristics for print or file output

To suppress interactive questions about which device to use for output, specify at least one of -SCREEN, -PRINTER or -FILE.

The -NOSPACE Command Tail

Several database utilities have a -NOSPACE command tail, which instructs the utility to suppress checks for sufficient disk space. Over recent years the use of this has frequently become necessary, because the DP4 function for reporting free disk space originally returned a signed 32 bit number, which meant it could never report more than 2GB free. As of release 4.622 DP4 database utilities use 64 bit file handling functions, meaning they can handle files larger than any PC operating system currently supports, and therefore there should be no need to use this command tail any more. One possible exception to this arises if you are running DP4 on a Windows 9x machine: on such machines the operating system itself may lie about the amount of space available.

Configuration File Settings as Command Tails

From version 4.620 almost any option that can be specified in the DP4 configuration file, can also be specified as a command line option. This can be very useful if you sometimes need to run a program one way, and sometimes another. For example, many batch type DP4 utilities complete they display a message box and wait for the user to press the OK button before exiting, so that the user can examine the output screen. However, if the utilitiy is run as part of a script this may not be what you want. You can use the pause=0 setting in the DP4 configuration file to suppress the pause, but then the user can no longer see the output screen. Instead you should use -pause=0 on the command line. The = is currently optional, but you are recommended always to use it.-pause on its own is equivalent to -pause=1 and the same holds for other numeric configuration file entries.


Standard Exit Codes.

DP4 programs have a common standard for exit codes across operating systems. All programs use these exit codes unless otherwise noted. In operating systems which support batch files and testing of error levels these can be tested in the normal way. [Note that under Windows 95 an MS-DOS batch file cannot test the error level of a Windows program as the program is run aynchronously. To run a Windows program synchronously from an MS-DOS batch file under Windows 95 specify start /w before the name of the program. Under Windows NT programs are only run asynchronously if start is specified explicitly]

It should be noted that trm_run_program() does NOT return exit code information. Nor is it available in QAB.

Exit Code Meaning
0 Normal completion

The program ran to completion successfully.

For example in MAPPOST,QABUTIL and COPYDB it would mean that no fatal errors occured when posting the file.

In DBBACKUP,DBRESTOR,DBCHECK it would mean the database was successfully backed up/restored/checked.
1 Abnormal completion

The program encountered a program specific error during processing, or the user aborted it by escaping when asked for a database name.

For example in MAPPOST,QABUTIL and COPYDB it would mean that an error occured when posting a file to the database.

In DBBACKUP,DBRESTOR,DBCHECK it would mean the database was not successfully backed up/restored/checked.
2 User termination

The user terminated the program by pressing Ctrl+S,Ctrl+C or Alt+F4, or by pressing Esc when prompted to load a log disk, or when warned that the program could not update the database.
3 System error

The program terminated when a call to sys_error() was generated.
4 Fail error

The program terminated when a call to sys_fail() was generated.
5 DP4 Interface error

The program could not communicate with or could not load the database manager or terminal manager.
7 Special Exit Code

  • If REDn is unable to run the program specified on its command line, it returns this error code. Any other return code from REDn is the return code of the application it invoked.

  • On Windows platforms if you attempt to attach a debugger to the DP4 database manager, or to DFSETUP, or to a program that has DP4CRYPT.DLL or NODEBUGT.DLL in its address space, then the attempt to attach the debugger will fail and the program will exit immmediately with this error code.
All other values Unused

No other return codes are used by standard DP4 utilities.

A user written program can terminate with any exit code by calling dp4_halt(n).

Notes

When DBRECOV is run it writes a message to SYSLOG.PRN specifiying a return code.

This return code is NOT the program exit code. It is 00 if DBRECOV ran succesfully. Otherwise it is the number of the message which DBRECOV displayed (or would display if -silent was not specified). In particular retcode 03 means DBRECOV was run against a database which did not require DBRECOV. retcode 05 means the rollback log was missing.

You can check the meaning of the return code by using MAPEDIT/MAPMAKE to examine the DBRECOV map set on the system database.

DBCHECK behaves in a similar manner and the return code in SYSLOG.PRN represents a map number from the DBCHECK mapset on the system database.


Building Databases

The Base DP4 does not come with any very useful example databases, and you will need to create your own databases when building a DP4 system. A SYSTEM database must also be present on any DP4 system with local databases.

When you create a new database (for which you use MAKEDB), the Base Dictionary (BD) is copied automatically to your chosen database name. This produces a 'skeleton' database to which you add tables and fields.

Ensure that the SYSTEM and BD databases are located on your machine in the location specified for data and index files in your DP4 licence file. You can check this using the Directory Assignment option of DFSETUP.


Supporting a DP4 System

In order to support a DP4 System you will need the following knowledge:

  • How to to install and configure the system. The Installation and Configuration information here may be some help, but you will typically need documentation supplied by whoever has built your complete DP4 system.

  • How to maintain DP4 databases. You will almost certainly find it equally useful to become familiar with the BROWSER and AUDITOR utilities.

  • Become familiar with the structure of the DP4 databases used by your application. See Understanding the Database Structure for more information.

  • How to find the version numbers of the DP4 components on the system. See Viewing DP4 Version Information for more information on ways to do this.

  • How to interpret Error Messages reported by DP4, and how to find out exactly what error has arisen if a user has only a confused idea of what went wrong.

  • How to enable diagnostic logging for key DP4 components in order to find out more about a problem. See the Troubleshooting section in the Guide to DP4 Networking and Resilience, and the information on Diagnostics in the Guide to DP4 Configuration.

  • Two ADCs provided on the DP4 CD-ROM can help in diagnosing problems:

    • AUXDEBUG allows you to obtain detailed diagnostics about calls to the DP4 database interface.
    • AUXDUPE allows a small database to be constructed from another much larger database, containing just the original state of data accessed while it is loaded. This can be very helpful where a problem is occuring using a large live database too big (or with sensitive data) to send to a developer in its entirety.

    For information on how to use these components refer to Example ADCs in the ADC Developer's manual.

  • How to contact Itim for support issues you are unable to resolve yourself. (Depending on your relationship with us, you may need to do this via an intermediary). In case of doubt consult the Contact Us page on the DP4 web site for up to date contact information.

For the latest information on all aspects of DP4 you are recommended to become familiar with the DP4 web site.


SYSDB

Displays the name of the current SYSTEM database (as stored in the DP4 licence file), and allows the name and path of an alternative system database to be selected and stored in the licence file. You may find using a different name for the system database convenient if you need to run multiple releases of DP4 on a single machine, or develop DP4 systems for more than one customer.

Command Tail | Description
dbname | For example: NEWSYS
drive:\dir\name | For example: C:\DB\SYSTEM

Specifying a full path name with the system database should be a temporary measure only as it can cause problems in utilities that need to update the system database or generate filenames based on the system database name. It is sometimes useful to specify a full path name on a temporary basis, for example if you have unintentionally managed to set the database locations recorded in the licence file to invalid values.

You may wonder why SYSDB is a separate utility, and its functionality is not built into one of the other utilities, such as DFSETUP. The reason is, that without SYSDB there would be no way to repair a DP4 installation where the database locations stored in the licence file were invalid, since DFSETUP itself needs acces to the system database to display its dialogs. Because SYSDB allows you to specify a full path to your system database, you can "bootstrap" DP4 by installing a new copy of the system database, and then run DFSETUP to correct the file locations.

You should note the following important points about SYSDB and the system database:

  • The DP4 database manager only reads the DP4 licence file when it starts up, so after running SYSDB you need to stop and restart the DP4 database manager for the new setting to become effective.

  • The DP4 install program installs the system database as though it were an application database named SYSTEM,i.e. it pays no attention to your SYSDB settings. On the other hand DBRESTOR and DBBACKUP do respect the SYSDB setting when run with the -system command tail.


System Error Messages

Under Windows NT family operating systems the message is also written to the Application Event Log. The method used to do this has changed in 4.620, so that the event log also records which program encountered the error.

System error messages are produced if an error condition arises inside the DP4 libraries or interfaces while running a DP4 program. The text is taken from the SYSTEM mapset on the system database, or, from 4.620, the DP4 configuration file.

The message is written to SYSLOG.PRN, so that you can check the details of system errors at a later time.

List of all DP4 System Errors

Only the error numbers that are genuinely used as system errors are included in this information; other error numbers are associated with advisory or warning messages (displayed by sys_message() and sys_request()). sys_message() messages are merely advisory. sys_request() messages usually require the user to take some action to allow the program to continue to run. If the user chooses not to take the action the program will terminate cleanly. Messages associated with database contention errors may be used as either as system errors or as sys_request() messages, depending on the mode used by the program to access the database.

Programmers who want to handle system errors for themselves can assume that, unless otherwise noted, if the origin of a system error is classified as a program bug, it is possible to continue execution after the error. A better strategy is make sure that the error condition never arises by fixing the bug!.

  • DP4 System Error 2
  • DP4 System Error 3
  • DP4 System Error 4
  • DP4 System Error 5
  • DP4 System Error 6
  • DP4 System Error 7
  • DP4 System Error 8
  • DP4 System Error 9
  • DP4 System Error 10
  • DP4 System Error 11
  • DP4 System Error 12
  • DP4 System Error 13
  • DP4 System Error 14
  • DP4 System Error 15
  • DP4 System Error 16
  • DP4 System Error 17
  • DP4 System Error 18
  • DP4 System Error 19
  • DP4 System Error 20
  • DP4 System Error 21
  • DP4 System Error 22
  • DP4 System Error 23
  • DP4 System Error 24
  • DP4 System Error 25
  • DP4 System Error 26
  • DP4 System Error 27
  • DP4 System Error 28
  • DP4 System Error 29
  • DP4 System Error 30
  • DP4 System Error 31
  • DP4 System Error 32
  • DP4 System Error 33
  • DP4 System Error 34
  • DP4 System Error 35
  • DP4 System Error 36
  • DP4 System Error 37
  • DP4 System Error 38
  • DP4 System Warning/Error 39
  • DP4 System Error 40
  • DP4 System Error 41
  • DP4 System Error 42
  • DP4 System Error 43
  • DP4 System Error 44
  • DP4 System Error 45
  • DP4 System Error 50
  • DP4 System Warning 51
  • DP4 System Warning 52
  • DP4 System Warning 53
  • DP4 System Warning 54
  • DP4 System Warning 55
  • DP4 System Warning 56
  • DP4 System Warning 58
  • DP4 System Error 59
  • DP4 System Error 68
  • DP4 System Error 69
  • DP4 System Error 70
  • DP4 System Error 73
  • DP4 System Error 74
  • DP4 System Error 75
  • DP4 System Error 76
  • DP4 System Error 77
  • DP4 System Error 78
  • DP4 System Error 79
  • DP4 System Error 80
  • DP4 System Error 81
  • DP4 System Error 83
  • DP4 System Error 84
  • DP4 System Error 85
  • DP4 System Error 86
  • DP4 System Error 87
  • DP4 System Error 88
  • DP4 System Error 89
  • DP4 System Error 90
  • DP4 System Error 91
  • DP4 System Error 93
  • DP4 System Error 119
  • DP4 System Error 121
  • DP4 System Error 122
  • DP4 System Error 123
  • DP4 System Error 124
  • DP4 System Error 126
  • DP4 System Error 127
  • DP4 System Error 128
  • DP4 System Error 129
  • DP4 System Error 130
  • DP4 System Error 131
  • DP4 System Error 132
  • DP4 System Error 133
  • DP4 System Error 134
  • DP4 System Error 135
  • DP4 System Error 136
  • DP4 System Error 137
  • DP4 System Error 138
  • DP4 System Error 139
  • DP4 System Error 140
  • DP4 System Error 141
  • DP4 System Error 142
  • DP4 System Error 143
  • DP4 System Error 150
  • DP4 System Error 151
  • DP4 System Error 152
  • DP4 System Error 154
  • DP4 System Error 155
  • DP4 System Error 156
  • DP4 System Error 157
  • DP4 System Error 173
  • DP4 System Error 174
  • DP4 System Error 210
  • DP4 System Error 261
  • DP4 System Error 263
  • DP4 System Error 300
  • DP4 System Error 301
  • DP4 System Error 302
  • DP4 System Error 303
  • DP4 System Error 304
  • DP4 System Error 305
  • DP4 System Error 306
  • DP4 System Error 308
  • DP4 System Error 309
  • DP4 System Error 310
  • DP4 System Error 311
  • DP4 System Error 320
  • DP4 System Error 321
  • DP4 System Error 401
  • DP4 System Error 402
  • DP4 System Error 404
  • DP4 System Error 405


TABLEPLN

Creates and edits the table plan for a database, in either layout or detail form.

See Using the Table Planner in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−LAYOUT filename | Read in previously saved layout file
−READ filename | Read in an expanded file (or any other text file) for further editing
−ALL | Print all tables in one long column


TRMn

Terminal Manager program, which also includes operating system interface. Except on MS-DOS this program is always loaded automatically. On MS-DOS you can preload TRM2 in the same way as the database manager.

Command Tail | Description
−REMAIN | (MS-DOS only) Remains in memory

TRM2S and special versions of TRM2

TRM2S is a slightly smaller version of TRM2 for specialised use. This restricts use of some utilities, in particular the options of REDn needed to create demo files. (The read option still works). This version of the terminal manager has special support for 40 column display. Other specialised versions of TRM2 are available, for example with graphics support that emulates Windows.


Understanding the Database Structure

You will probably find it useful to have some knowledge of the structure of the DP4 databases used by the applications you are supporting. The system development team should normally supply appropriate documentation to you. If they do not, you can use the DP4 Table Planner to print out a create a schematic diagram of the database.

Even more useful will be a list of the tables on the database, together with their internal reference numbers. Knowing what table number. You can quickly create such a list by using the PRINTDB utility, available as Print Data Dictionary on the Database Management option of the DP4 menu, and just selecting the List of Tables option.

For more information on using these programs refer to Printing the Database Structure in the DP4 Developers' manual.


UNLOAD

Exports database tables to an ASCII format file which can be loaded into the target database using the LOAD utility

See Transferring Data with the Load and Unload Facility in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
−ALL | Exports all tables
-APPEND | By default UNLOAD overwrites any existing file of the same name. This option has been added because a user wished to be able to concatenate the output from several runs of UNLOAD. This option is disallowed if the -xml option is selected.
−CONFIG name | Reads the list of tables to export from a configuration file. If this option is used it is possible to use a per-table condition to limit which records are exported.
-QUIET | Do not display the exported lines
−CSV | Causes UNLOAD to dump data in a different format from usual. It uses a format which the Micorosoft Internet Explorer Tabular Data Control can understand. You could use data in this format to indirectly access data from DP4 databases via web pages.
−FILE name | Exports the data to the named file. The default is the DB_NAME.TXT (or .XML if -xml option specified)
-QUIET | Do not display the exported lines
−TABLE name | Export data from the named table
−TABLES t1,t2,... | Export data from the table list given
−TABLES @filename | Take the table list from the contents of file filename. This must be specified after all the other command tails.
−XML | Causes UNLOAD to dump data in XML format. The data is dumped to a file with .XML extension, and an XML schema which describes the data is created with extension .XSD. .

UNLOAD using a configuration file

As with the -tables @filename option The -config filename option allows the list of tables to be exported to be specified in a file, but more importantly it allows a table to be exported selectively. When this option is used then a table is only exported if the configuration file contains a section for that table and the option unload=1 is specified. In this case the table is exported normally unless the mode=1 option is also specified, when a condition must also be specified, using the same syntax as is used for formulas by BROWSER, AUDITOR, and RECASTDB.

Below an example of a configuration file is given. This exports selected records from a table named CUSTOMER and all records from a table named EMPLOYEE.

[customer]
unload=1
mode=1
condition="cust_acc_nr>=10001  and cust_acc_nr <= 10005"
[employee]
unload=1

XML Export using UNLOAD

File Format

The root of the XML document is an element named DP4.unload which has a single attribute - the database name. The data for table tablename is contained in an element tablename-data in multiple tablename elements. Each tablename-data element appears once. If a table to be exported is empty then the tag appears as an empty tag.

Each field in the table appears as an attribute of the tablename element. An alternative would have been to use a separate element for each field, and make the field value either a value attribute of its element, or else text content. The format used has been chosen because it is relatively easy to generate an XML schema for it, and because it is far more compact than either of the other formats would be.

Multi-occurs are treated as separate fields. The attribute name for a field is generated as follows:

  • For a single occurrence field, the name is fieldname.rolename or just fieldname if the role is blank

  • For a multi-occurs field multiple fields name fieldname.rolename-1,fieldname.rolename-2 etc. , or fieldname-1, fieldname-2 etc. are generated.

    If a field is NULL then the corresponding attribute is omitted from that record.

Note that DP4 currently has no facilities for importing these or any other XML files. XML files are much larger than traditional CSV style files and should only be used when absolutely necessary.

Configuration Options

There are a number of configuration options that can be used to modify the XML produced

  • The xml_encoding entry in the [win32] or [unix] sections of the DP4 configuration file are used to specify how the file is encoded. This setting defaults to windows-1252 and UNLOAD makes no attempt to discover a name by querying the operating system. Note that without this setting XML files would be rejected by the Microsoft XML parser if they contain accented characters. Note also that this setting does not alter how DP4 creates the file - it is up to you to ensure the setting matches the character set that you are actually using.

  • Names of elements and attributes generated by UNLOAD can be changed by specifying an entry in an [xml.xlat dbname] section. These sections are modelled on the [sql.xlat dbname] sections and work in the same way. For example suppose the first line of an address is normally exported as address.jobs-1, but you wish it to be exported as job_address_1. Then you simply add the line
    address.jobs-1=jobs_address_1
    to your DP4 Configuration file in the appropriate [xml.xlat dbname] section. The only exception to this is that whatever name you choose to replace a tablename element by, its enclosing element will use the same element name followed by -data.

Limitations

Conforming XML parsers will reject files containing characters that do not belong to the character set including most control characters. The only way DP4 could work around this would be to export data using Base64 binary encoding, which would defeat the whole object of XML. DP4 converts control characters to "entities", but this will not make an invalid character valid. Therefore if you have stored binary data in character fields, you will probably not be able to export those tables using XML format.

Schema File

The Schema file generated by UNLOAD does not fully describe the data for a field. For example no attempt is made to limit the length of character fields, or the valid range of numeric fields. We intend to enhance LIBMAKE or provide a new utility which generates a more complete XML Schema for a DP4 database.


USERDATA

Creates a USERDATA.SYS file.

Command Tail Description

−AUTOWRAP

Support terminals that are configured to wrap to a new line after the last column

−BLINK nnnn

Increase this number to slow the cursor. The default is 1000 (for MS-DOS Graphics version only)

−CURS

Allow the selection of the cursor shape for Overtype/Insert (certain dumb terminals, MS-DOS and OS/2 only)

−DEBUG

Create a special version of USERDATA.SYS for debugging program output (not Windows)

−GRAPHICS

When using the MS-DOS graphical terminal manager, enables improved boxes (MS-DOS only)

−NOBREAK

<Ctrl+S> pauses, but the user cannot use <Ctrl+C> to terminate the program

−NODELAY

If the computer and terminal perform handshaking, no delay is required after actioning control sequences and improves performance (only relevant for dumb terminals)

−OLDDRIVE

Create a USERDATA.SYS for use with the 4.400 OSDI architecture

−OS name

Create USERDATA as though running on the named operating system. Valid names are: MSDOS, FLEXOS, UNIX, OS2, WINDOWS, PM

−PSPC

(4.620 or later) Create a hard coded color table based on the current Windows color scheme. This option is required to create userdata.sys files for use on versions of Windows CE that do not support the usual APIs for determining suitable colors, including Pocket PC and Pocket PC 2002.

−RESET

Replace the current user preferences with the initial defaults

−SAA

Selects the SAA keying convention, and in particular:

  • Tab selects the next field
  • Enter selects a whole screen
  • F1 is the Help key

Also, except for a Windows userdata.sys:

  • F3 acts as Escape
  • F4 requests prompt

−SAMEKEY

Retain the keyboard translation values (set up with DFSETUP)

−STANDARD

Create USERDATA for use with Standard DP4 OSDI architecture

−TESTFAIL

Make the <Ctrl+End> key combination generate a program fail (for testing a resilient application on a PC running MS-DOS or OS2)

−TYPE x

Creates a USERDATA.SYS file of the specified type

−WINDOWS

Choose Windows-like keying conventions. This option may cause minor problems in a few standard DP4 utilities and make some of their help messages inaccurate, but will probably suit experiened Windows users.

For more information on Keying convention refer to Keyboard Interface.


Utility Reference

The following utilities form the DP4 core software set. The command tails specific to each utility are listed in that utility's section. In the listing for each utility, command tails that are inset are for use in conjunction with the last non-inset command tail.

In most cases running the utility with the -help command tail will display information about the available command tails for the utility. This may be useful where you are using an older or new version of DP4 than is covered by this manual.

Consult the Release Notes to check which utilities are provided for your operating system.

  • AUDITOR
  • AUTHOR
  • AUTOQAB
  • AUXDISTR
  • BROWSER
  • COLLATE
  • COPYDB
  • DBBACKUP
  • DBCHECK
  • DBERA
  • DBRECOV
  • DBRESTOR
  • DFPRINT
  • DFSETUP
  • DFTYPE
  • DP4
  • DP4ED
  • DP4SRVR
  • DYNABACK
  • DYNACHEK
  • FAIL
  • FDUMPM
  • FIXDB22
  • FIXDB23
  • FIXNET
  • FIXREPS4
  • HLPI
  • IMPPOST
  • IMPSETUP
  • KENTCURS
  • LIBMAKE
  • LOAD
  • LOGCOPY
  • MAKEDB
  • MAKELINK
  • MAPEDIT
  • MAPMAKE
  • MAPPOST
  • MENUEDIT
  • MENUUSER
  • NETCOPY
  • NUMBSYS
  • PATCHER
  • PRINTDB
  • PROGBIND
  • PROGCOMP
  • PROGDATE
  • PROGMAKE
  • PROGPRN
  • PROGRUN
  • PROGRUND
  • PROGRUNS
  • QABUTIL
  • RECASTDB
  • REDn/REDW
  • REORGDB
  • REPPRINT
  • REPSETUP
  • RESWORDS
  • ROUNDER
  • SETDATE
  • SETLINK
  • SETSESSN
  • SHUTDOWN
  • SORTEXTR
  • SRVn
  • SRVW32
  • SRVW64
  • SRVWCE
  • SYSDB
  • TABLEPLN
  • TRMn
  • UNLOAD
  • USERDATA
  • VIEW

Operating System Numbers

DP4 programs are designed to be highly portable across different operating systems. Most DP4 programs behave identically on all platforms and take the same options. This is achieved thought the the use of interface or manager programs that handle direction interaction with the operating system. These programs usually have a different name on each platform based on a common prefix followed by an operating system number or code.

The operating systems are coded as follows:

2 | MS-DOS or PC-DOS
3 | UNIX or Linux
5 | FlexOS
7 | OS/2
9 | NLM
W | 16-bit Windows
W32 or t | 32-bit Windows.
WCE or t | Windows CE.
W64 or t | 64-bit Windows.

Thus TRM3 and SRV3 are for UNIX, TRM2 and SRV2 are for MS-DOS, and so on.


VIEW

Allows you to view, but not to edit, text files. This program can be convenient for inspecting printed output from DP4 programs. From version 4.621 you can use View, or a program of your choice to view reports that the user has asked to print on screen.

See Viewing a Text File in the DP4 Developer's Manual for further information about this program.

Command Tail | Description
filename | The file to view
−ESCAPE | Allows Escape to quit from program
−NOCR n | Use on files that consist of fixed length records of length n without CR/LF terminators


Viewing DP4 Version Information

For the purposes of obtaining support from ITIM Technology solutions it is important that you can readily identify the version all the DP4 files issued as part of an application.

Systems developed over a period of time may often use components from several different releases of DP4. Don't assume that because one particular file has a certain version number, that all the other DP4 files will be from the same version - DP4 is usually very forgiving when files from different releases are used in the same system. Always get as much version information as you can from the machine where a problem is occurring (and from both client and server machines where networking is involved).

DP4 provides several facilities that allow you to view version information in a consistent way across all the standard DP4 components:

  • You can use the PROGDATE utility to view and save to file program version information.

  • From release 4.621 DP4 includes a batch file named DP4VER.BAT that will quickly display the version information for all installed DP4 executable files. The information is saved in a file named version.prn. If you require support from Itim Technology Solutions on a DP4 related problem, sending this file as part of the problem report will often help get your problem resolved more quickly. The contents of DP4VER.BAT are shown below:

    dir /a-d /b >xx *.exe *.dll *.w32
del version.prn
progdate -full -read xx -file .\version.prn
view version.prn

  • From 4.620, if DP4 error logging is turned on, and the debug_version is 1, the DP4 version of all components in use is written to the errog log window and the debug.out file. Earlier releases of DP4 also report some version information, but this is not always reliable.

  • On most version of Microsoft Windows, you can check the version information of Windows DP4 Executables by right clicking on the file in Explorer and choosing Properties. The Version Tab will display the DP4 version information.