Program: DOUGAL

Title: Catalogue Designer

Version: 3.9

• Introduction
• Running Dougal
  • Main menu
  • LEA Objects tab page
  • Attributes tab page
  • Record constraints tab page
• Editing a field definition
• Key Attributes and the Primary Index
• Setting the Layer Type
• INI file configuration settings
• Error Messages

Back to:

• Main Index
• Data Cataloguing Index

Introduction

This utility designs the file catalogues used in LEA applications. It creates an abstract definition of a catalogue which is stored in a Catalogue Description File (CDF). This CDF file is used to create and validate database tables in other programs that generate and use catalogues (see Florence, Dylan and Zebedee).

Dougal displays the available attributes for each type of LEA Object. You can select those attributes that you wish to be included in the catalogue, and also add custom fields (at the cataloguing stage these custom fields will usually have to be filled in manually).

Running Dougal

On application startup, if no CDF is specified on the command line, you can create a new CDF - select File-New - or modify an existing CDF - select File-Open or drag a CDF file icon from an Explorer window on to Dougal's main window

Select the LEA Object types that you wish to include in the CDF, then select the attributes that you wish to catalogue. Key attributes, which must be present in the data catalogue if it is to be used in other LEA applications, are displayed with an exclamation   icon. The primary index fields are displayed with a key   icon. You can change the order of fields, and add custom user-defined fields. Custom fields will not be automatically populated by the catalogue builder application (Florence).

If Dougal was launched from Florence or Zebedee (Project-New Catalogue menu option), then save the CDF using the File-Save or Save As menu options to return to Florence or Zebedee. If you exit without saving the CDF, you will be prompted to save the file. If you do not wish to save the file you will be asked if you want to discard the current CDF - click OK to return without selecting a CDF.

The catalogue description file will be saved to disk with extension .cdf. On exiting the utility you will be asked whether you wish to save changes to a new or modified file.

Command line options

Dougalcan be run with a command line similar to the following:

DOUGAL [-n] [CDFFILE]

where:
The -n flag will start Dougal with a prompt to create a new CDF (see menu option File-New).
or
CDFFILE is the file path of an existing catalogue description file to open on program startup.

Menus and Controls

Dougal has the following menu commands:

• File

  • New 
    Create a new Catalogue Description File.
    You will be prompted to specify whether you wish to:

    • Create a new blank CDF - you must select at least one LEA Object type, and then add attributes to the catalogue description. See LEA Objects Tab Page and Object Attributes Tab Page below.
    • Use a template - create a new CDF based on one of the pre-defined templates.
    • Open an existing CDF for editing - select a CDF to open from the open file dialogue.
    
    

  • Open 
    Select a catalogue description file to open from the open file dialogue.

  • Save 
    Save changes to the current CDF.
    Ensure that you have entered a Description and a Layer Type (see below) for the CDF.
    If you have not yet saved the catalogue definition to a named file, the save file dialogue will be displayed.
    If Dougal was launched from Florence or Zebedee (see the Project-New Catalogue menu option), then this option (or Save As below) will return you to Florence or Zebedee and create an empty catalogue from the definition provided in the CDF.

  • Save As
    Displays a save file dialogue - select a folder and a file name for the CDF.

  • Save As Template
    
    • User Template
    • System Template

    Displays a save file dialogue to save the CDF as a user or system template. See Catalogue Description Files - CDF Templates. You can only save a template into your user TEMPLATE folder or the LYNXSYS TEMPLATE folder.

• View

  • List 
    View the LEA Object and Attribute selection lists as small icon lists, without descriptions

  • Details 
    View the LEA Object and Attribute selection lists with a description for each item.

  • LEA Objects
    Switch to the Objects tab.

  • Object Attributes
    Switch to the Attributes tab

  • Catalogue Constraints
    Switch to the Constraints tab

• List - the options displayed on this menu reflect the available actions for the current tab page. See below for details.

There are two tabbed pages which allow selection of items from a list; these are the LEA Objects tab page, and the Object Attributes tab page.
The left-hand list displays all the available items. The right-hand list displays the selected items. Items can be added to and removed from the right-hand list either by dragging with the mouse, or by using the buttons beneath the lists:

Select a single item in a list by clicking on it with the mouse. Multiple consecutive items can be selected by clicking on the first item, and then holding down the <SHIFT> key while selecting the last consecutive item. Multiple non-consecutive items can be selected by holding down the <CTRL> key while clicking each item with the mouse.

Add all highlighted items from the left-hand list to the right-hand list. Keyboard shortcut <ENTER>

Add all items from the left-hand list to the right-hand list. Items that are already in the right-hand list will not be added again. Keyboard shortcut <CTRL> + <ENTER>

Remove highlighted fields.from the right-hand list. Keyboard shortcut <DEL>

Clear List This will remove all fields from the right-hand list. Keyboard shortcut <CTRL> + <DEL>

Move focused item up towards the top of the right-hand list. Keyboard shortcut <CTRL> + <UP ARROW>

Move focused item down towards the bottom of the right-hand list. Keyboard shortcut <CTRL> + <DOWN ARROW>

LEA Objects Tab Page

This tab page displays the LEA Object types which are included in the current CDF.

For a description of what each button does, see above.

Object Attributes Tab Page

This tab page displays the all the attributes which you can choose to include in the CDF.
LEA Object Key Attributes (see below) are marked with an exclamation icon -  , and the fields that will make up the primary index (see below) are marked with a key icon -   . As well as manipulating the list using the buttons described above, you can add user-defined fields, edit the field descriptions, and change the fields that make up the primary index:

Add New Field Add a new (user-defined) field. Keyboard shortcut <INSERT> See Editing Field Properties.

Edit Field Description Edit the properties for the current field. Keyboard shortcut <ENTER> (or double-click on the item in the list) See Editing Field Properties.

Primary Index Toggle Add the current item to, or remove the current item from, the primary index key. Keyboard shortcut <F5> See Key Attributes and the Primary Index.

Record Constraints Tab Page

This tab page displays the record-level constraints defined in the CDF. Record-level constraints can compare the value of one field to the value of another field in the same record, or compare the value of a field to a query on another table. Record-level constraints are only implemented for Oracle databases (they will not work for dBASE catalogues).

Record-level constraints are checked before the record is saved to the database, and they are independent of the constraints defined on the table in the Oracle database. The constraints should be defined using standard Oracle SQL syntax. Field names from the current catalogue should be written as parameters (prefixed with a colon and always postfixed by at least one space).

Add new record-level constraint Enter the text of the constraint in the edit dialogue displayed. .

Edit selected constraint text Edit the text of the constraint in the edit dialogue displayed. .

Edit selected constraint error message Edit the text of the error message to be displayed when the constraint is violated. If the error message is blank, a default message will be displayed. .

Delete selected constraint Removes the constraint currently highlighted in the list. .

Editing a field definition

When you add a user-defined field (see Attribute Add New Field   button) or edit field properties (see Attribute Edit Field Description   button), a PRMEDIT wizard will be displayed, allowing you to edit the following field parameters:

• CDF Field Properties
• Field Constraint Definitions
• String Field Checks
• Integer Field Checks
• Float Field Checks
• Boolean Field Checks
• Date/Time Field Checks
• Lookup Table Options
• Lookup Filtered Lists

Parameter Page - CDF Field Properties

Field Number
This displays the number of the field within the CDF. This cannot be edited. Use the Move Up   and Move Down  buttons to change the field position.

Field Name
This shows the field name to be used in the catalogue database table. Each field in the catalogue must have a unique name. The restrictions enforced on field naming depend on settings in the program INI file. In dBASE-compatibility mode (see below), the field name is limited to 10 characters..

Primary Key Field - YES/NO
This indicates whether the current field is part of the primary index. This cannot be edited. Use the Primary Index Toggle   button to change the primary index.

Field Description
This shows the description for the field. This is used as the field heading for catalogue display in Florence.

The field name and description must be unique within the table and cannot be left blank.

User-defined - YES/NO
This indicates whether the current field is an LEA Object Attribute field, or has been added to the CDF by the user. This field cannot be edited.

Field Type
This displays the data type for the field.
Available types are STRING, INTEGER, FLOAT, BOOLEAN (true or false) and DATE/TIME.
This parameter can only be edited for user-defined fields (see above)- for fields defined as LEA Object attributes this parameter is displayed read-only.
For information about LEA Object Attribute types see The Lynx Exploration Archivist Object - Attribute Types.
For information about how CDF field types are mapped into database-specific types see Catalogue Description Files - Field type Mappings

Field Width
The field width is only applicable to STRING or FLOAT field types. If the field you are adding is not one of these types, you can ignore this property.
For string fields the field width is the maximum number of characters in the string.
For float fields the field width is the maximum number of decimal places to use.
This parameter can only be edited for user-defined fields - for fields defined as LEA Object attributes this parameter is displayed read-only.

Edit Mask
The Edit Mask specifies the appearance of field values, and valid characters to enter when editing a value. The format of the edit mask differs for the different field types:

• STRING fields
• INTEGER and FLOAT fields
• BOOLEAN fields
• DATE/TIME fields

• STRING field edit masks

  The edit mask for string fields consists of up to three fields with semicolons separating the fields. The first part of the mask is the mask itself. The second part is the character that determines whether the literal characters of a mask are included as part of the data. The third part of the mask is the character used to represent unentered characters in the mask.

  These are the special characters used in the first field of the mask:

  Character	Meaning in mask
  !	If a ! character appears in the mask, optional characters are represented as leading blanks. If a ! character is not present, optional characters are represented as trailing blanks
  >	If a > character appears in the mask, all characters that follow are in uppercase until the end of the mask or until a < character is encountered
  <	If a < character appears in the mask, all characters that follow are in lowercase until the end of the mask or until a > character is encountered.
  <>	If these two characters appear together in a mask, no case checking is done and the data is formatted with the case the user uses to enter the data
  \	The character that follows a \ character is a literal character. Use this character when you want to allow any of the mask special characters as a literal in the data
  L	The L character requires an alphabetic character only in this position. For the US, this is A-Z, a-z
  I	The l character permits only an alphabetic character in this position, but doesn't require it.
  A	The A character requires an alphanumeric character only in this position. For the US, this is A-Z, a-z, 0-9
  a	The a character permits an alphanumeric character in this position, but doesn't require it
  C	The C character requires an arbitrary character in this position
  c	The c character permits an arbitrary character in this position, but doesn't require it
  0	The 0 character requires a numeric character only in this position
  9	The 9 character permits a numeric character in this position, but doesn't require it
  #	The # character permits a numeric character or a plus or minus sign in this position, but doesn't require it
  :	The : character is used to separate hours, minutes, and seconds in times. If the character that separates hours, minutes, and seconds is different in the regional settings of the Control Panel utility on your computer system, that character is used instead of :
  /	The / character is used to separate months, days, and years in dates. If the character that separates months, days, and years is different in the regional settings of the Control Panel utility on your computer system, that character is used instead of /
  ;	The ; character is used to separate the three fields of the mask
  _	The _ character automatically inserts spaces into the text. When the user enters characters in the field, the cursor skips the _ character.

  Any character that does not appear in the preceding table can appear in the first part of the mask as a literal character. Literal characters must be matched exactly when entering data for the field. They are inserted automatically, and the cursor skips over them during editing. The special mask characters can also appear as literal characters if preceded by a backslash character (\).

  The second field of the mask is a single character that indicates whether literal characters from the mask should be included as part of the field value. For example, the mask for a telephone number with area code could be the following string:

  (000)_000-0000;0;*

  The 0 in the second field indicates that the field value would consist of the 10 digits that were entered, rather than the 14 characters that make up the telephone number as it appears to the user. A 0 in the second field indicates that literals should not be included, any other character indicates that they should be included. The third field of the mask is the character that appears in the edit control for blanks (characters that have not been entered). By default, this is the same as the character that stands for literal spaces. The two characters appear the same in an edit window. However, when a user enters the data for the field, the cursor selects each blank character in turn, and skips over the space character.

• INTEGER and FLOAT field edit masks

  The mask for integer and float fields is a string that encodes the formatting of numeric data using the specifiers in the following table:

  Specifier	Represents
  0	Digit placeholder. If the value being formatted has a digit in the position where the "0" appears in the format string, then that digit is copied to the output string. Otherwise, a "0" is stored in that position in the output string
  #	Digit placeholder. If the value being formatted has a digit in the position where the "#" appears in the format string, then that digit is copied to the output string. Otherwise, nothing is stored in that position in the output string
  .	Decimal point. The first "." character in the format string determines the location of the decimal separator in the formatted value; any additional "." characters are ignored. The actual character used as a the decimal separator in the output string is specified in the Number Format of the Regional Settings section in the Windows Control Panel
  ,	Thousand separator. If the format string contains one or more "," characters, the output will have thousand separators inserted between each group of three digits to the left of the decimal point. The placement and number of "," characters in the format string does not affect the output, except to indicate that thousand separators are wanted. The actual character used as a the thousand separator in the output is specified in the Number Format of the Regional Settings section in the Windows Control Panel.
  E+	Scientific notation. If any of the strings "E+", "E-", "e+", or "e-" are contained in the format string, the number is formatted using scientific notation. A group of up to four "0" characters can immediately follow the "E+", "E-", "e+", or "e-" to determine the minimum number of digits in the exponent. The "E+" and "e+" formats cause a plus sign to be output for positive exponents and a minus sign to be output for negative exponents. The "E-" and "e-" formats output a sign character only for negative exponents
  'xx'/"xx"	Characters enclosed in single or double quotes are output as-is, and do not affect formatting
  ;	Separates sections for positive, negative, and zero numbers in the format string

  The locations of the leftmost "0" before the decimal point in the format string and the rightmost "0" after the decimal point in the format string determine the range of digits that are always present in the output string.

  The number being formatted is always rounded to as many decimal places as there are digit placeholders ("0" or "#") to the right of the decimal point. If the format string contains no decimal point, the value being formatted is rounded to the nearest whole number.

  If the number being formatted has more digits to the left of the decimal separator than there are digit placeholders to the left of the "." character in the format string, the extra digits are output before the first digit placeholder.

  The following table shows the effect of various format strings:

  Format String	Value	Result	Comment
  #.##	12.2	12.2	Note extra digit to left of decimal still appears
  #.00	2.5	2.50	Note extra zero: field will always show two decimal places
  00.##	.006	00.01	Note extra 0s to right of decimal point and rounding to two decimal places.

  To allow different formats for positive, negative, and zero values, the format string can contain between one and three sections separated by semicolons.

  • One section: The format string applies to all values
  • Two sections: The first section applies to positive values and zeros, and the second section applies to negative values
  • Three sections: The first section applies to positive values, the second applies to negative values, and the third applies to zeros

  If the section for negative values or the section for zero values is empty, that is, if there is nothing between the semicolons that delimit the section, the section for positive values is used instead.

  If the section for positive values is empty, or if the entire format string is empty, the value is formatted using general floating-point formatting with 15 significant digits. General floating-point formatting is also used if the value has more than 18 digits to the left of the decimal point and the format string does not specify scientific notation.

• BOOLEAN field edit masks

  The edit mask for boolean fields specifies strings you want used to represent Boolean values. Use any pair of phrases, separated by a semicolon.

  For example, to have the True and False values correspond to the letters T and F, respectively, set the edit mask to "T;F". Similarly, to set the values of True and False to the strings Yes and No, set the edit mask to "Yes;No" The string associated with True or False can be an empty string. To set the value for True to an empty string, set the edit mask to a string that begins with a semicolon. For example, to associate False with the string Fail, and True with an empty string, set the edit mask to ";Fail". To associate False with an empty string, set the edit mask to the string for True, with no semicolon at all.

• DATE/TIME field edit masks

  The edit mask for date/time fields specifies a formatting string that is used to format the value in a date-time field when the field’s value appears as a string, and to interpret values entered by users. If the edit mask is empty, the value is formatted according to the default specified by the Windows Control Panel.

  A date/time edit mask is constructed using these format specifiers:

  Specifier	Displays
  c	The date using the short date format followed by the time using the default time format minutes and seconds) (as specified in the Regional Settings on the Windows Control Panel)
  d	The day as a number without a leading zero (1-31)
  dd	The day as a number with a leading zero (01-31)
  ddd	The day as an abbreviation (Sun-Sat)
  dddd	The day as a full name (Sunday-Saturday)
  ddddd	The date using the short date format (from the Regional Settings section of the Windows Control Panel)
  dddddd	The date using the long date format (from the Regional Settings section of the Windows Control Panel)
  m	The month as a number without a leading zero (1-12). If the m specifier immediately follows an h or hh specifier, the minute rather than the month is displayed
  mm	The month as a number with a leading zero (01-12). If the mm specifier immediately follows an h or hh specifier, the minute rather than the month is displayed
  mmm	The month as an abbreviation (Jan-Dec)
  mmmm	The month as a full name (January-December)
  yy	The year as a two-digit number (00-99)
  yyyy	The year as a four-digit number (0000-9999)
  h	The hour without a leading zero (0-23)
  hh	The hour with a leading zero (00-23)
  n	The minute without a leading zero (0-59)
  nn	The minute with a leading zero (00-59)
  s	The second without a leading zero (0-59)
  ss	The second with a leading zero (00-59)
  t	The time using the short time format (hours and minutes)
  tt	The time using the long time format (hours, minutes and seconds)
  am/pm	The time using the 12-hour clock for the preceding h or hh specifier, followed by "am" for any hour before noon, or "pm" for any hour after noon. The am/pm specifier can use lower, upper, or mixed case, and the result is displayed accordingly
  a/p	The time using the 12-hour clock for the preceding h or hh specifier, followed by "a" for any hour before noon, or "p" for any hour after noon. The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly
  ampm	The time using the 12-hour clock for the preceding h or hh specifier, followed by the AM specifier for any hour before noon, or the PM specifier for any hour after noon (from the Regional Settings section of the Windows Control Panel)
  /	The date separator character from the Regional Settings section of the Windows Control Panel
  :	The time separator character from the Regional Settings section of the Windows Control Panel
  'xx'/"xx"	Characters enclosed in single or double quotes are displayed as-is, with no formatting changes

  Format specifiers may be written in uppercase or lowercase letters; both produce the same result. If the string given by the Format parameter is empty, the date and time value is formatted as if a c format specifier had been given.

Define Constraints - YES/NO
YES - add constraints to the field value to limit the acceptable values for this field. This enables further parameters on the following pages.
NO - all values will be accepted for this field.
Note that the validity checks specified here will be specific to LEA cataloguing applications, and will not be built into the table when created in a database. The validity checks defined in a CDF can be in addition to any constraints defined on tables in an Oracle database, or can be used to provide help to users such as lookup values on fields defined as foreign keys.

Parameter Page - Field Constraint Definitions

This page is shown if Field Properties - Define Constraints=YES

Allow Null - YES/NO
YES - null values are accepted
NO - null values are not allowed for this field (equivalent to specifying NOT NULL for a SQL CREATE TABLE statement). If a default value is specified (see below), this will be used.

Initially Null - YES/NO (default NO)
This option is enabled when Allow Null is YES, and should only be modified for User-defined fields.
YES - the value of this field for new records will be null even if the field has a default value or is defined as an autoincrement field or uses an Oracle sequence (see below).
NO - if the field has a defined default value or is an autoincrement field or uses an Oracle sequence then this value will be set for new records.
This field constraint parameter can be used in conjunction with record-level constraints defined in the CDF (see Record-level constraints above) to provide sophisticated checking of field values against one another.

Set Minimum Value - YES/NO
Specify whether the field has a minimum value. The value should be specified below.
This option is ignored for STRING and BOOLEAN fields

Set Maximum Value - YES/NO
Specify whether the field has a maximum value. The value should be specified below
This option is ignored for STRING and BOOLEAN fields

Set Default Value - YES/NO
Specify whether a default value for the field will be set - see Allow Null above. The value should be specified below.

Lookup Method
This parameter is only enabled for STRING fields.
Select from:

• NONE (default) - there are no restrictions on valid values, other than those imposed by the edit mask, if set (see above)
• STATIC LIST - valid values are specified by the List Values parameter below
• TABLE/VIEW - valid values are retrieved from the field in the database table specified below. This option can be used to provide lookup help for data entry in LEA applications where the database table uses a foreign key.
• FOLDER NAME - the valid value for this field will be the name of the parent folder of the file currently being added to the catalogue. This can be useful if you are cataloguing data which has been categorised into a hierarchical directory tree.
• FILTERED LIST - different values can be selected depending on the value of another field - see the Lookup Filtered List page below
• DRIVELESS PATH - the valid value for this field will be the path of the file currently being added to the catalogue, with the drive portion and leading slash stripped off. For example, the file d:\data\file.txt would be translated into data\file.txt. This lookup method is independent of the absolute/relative path setting in Florence, and can be used for either the FILEPATH attribute field, or any user-defined custom field.

When editing catalogues with lookup fields derived either from a list or a table in LEA applications, the values will be displayed in a drop-down combo-box to allow browsing and selection of a valid value.

List Values
This is enabled for STRING fields if the Lookup Method (above) is STATIC LIST.
Click the  ... button to show a list editor dialogue. Enter values, one per line.

The rest of the parameters on this page are enabled if the Lookup Method (above) is TABLE/VIEW

Database
Enter the name of the Oracle database SID, or directory path of the dBASE table used for lookup.

Table Name
Enter the name of the Oracle table/view (you can include a schema name, or use a public synonym name), or filename of the dBASE table to use for lookup.

Field Name
Enter the name of the field from which to retrieve lookup values.

Filter Values - YES/NO
YES - This enables further parameters on the Lookup Tables Options page to dynamically filter the lookup values according to a value in another field of the catalogue.
NO - The lookup table will be static.

See further parameters for Lookup Tables on the Lookup Table Options page below.

Parameter Page - String Field Checks

This page is shown if Field Properties - Field Type is STRING, Field Properties - Define Constraints is YES, and Field Constraint Definitions - Has Default is YES

Default Value
If you specified Set Default Value - YES on the previous page, you must enter a string here to use as the default value, otherwise this parameter will be ignored. If the Lookup Method (above) is set to STATIC LIST, FILTERED LIST or TABLE, then the vale set here as the default must also be present in the lookup list.
You can also use the reserved string $USER to specify that the default entry for this field will be the current user name. For Oracle tables, this will be the current Oracle user, and for dBASE tables this will be the current Windows user.

Parameter Page - Integer Field Checks

This page is shown if Field Properties - Field Type is INTEGER, and Field Properties - Define Constraints is YES

Auto-increment - YES/NO
YES - the value of this field will be automatically generated, and will be unique for each record in the table. Auto-increment fields can be used as primary keys to create a unique identifier for each record.
NO (default) - the value of this field will not be automatically generated.

Minimum - the minimum possible value for this field. You should enter a value here if and only if Set Minimum Value is YES on the previous page, otherwise this parameter will be ignored.

Maximum - the maximum possible value for this field. You should enter a value here if and only if Set Maximum Value is YES on the previous page, otherwise this parameter will be ignored.
This parameter is disabled ifAuto-increment is YES (see above).

Default Value - the default value for this field. This parameter is ignored unless Set Default Value is YES on the previous page. You should enter either an integer value, or the reserved string $UNIQUEMAX to specify that the default value will be the current maximum value of the field, incremented by 1 to create a unique value (note that this is not the same as defining the field as an auto-increment field - the value of an autoincrement field cannot be edited by the user, whereas a unique-max value can be changed from its default value.
This option is disabled if Auto-increment is YES (see above).

Use Oracle Sequence - YES/NO
For auto-increment fields, an Oracle sequence can be used to generate a guaranteed unique value for each record. This may help to avoid conflicts on catalogues which are being updated by multiple users. All LEA applications which add records to the catalogue will call the specified sequence to get a unique value for this field.
An Oracle sequence obviously can only be used with an Oracle catalogue, and will be ignored for dBASE catalogues.
This option is enabled if Auto-increment is YES, and disabled if Auto-increment is NO.

The following options are enabled if Use Oracle Sequence (above) is YES

Database
Enter the name of the Oracle database SID for the sequence to be used.

Sequence Name
Enter the fully qualified name of the sequence to use (eg SCHEMA.SEQUENCENAME). It is acceptable for more than one catalogue to use the same sequence.
If the sequence does not exist, it will be created when the catalogue is created (you must have the CREATE SEQUENCE oracle privilege for this), and PUBLIC access will be granted for SELECT on the sequence. If a Minimum value is set (above) the sequence will use this.

Parameter Page - Float Field Checks

This page is shown if Field Properties - Field Type is FLOAT, and Field Properties - Define Constraints is YES

Minimum - the minimum possible value for this field. You should enter a value here if and only if Set Minimum Value is YES on the previous page, otherwise this parameter will be ignored.

Maximum - the maximum possible value for this field. You should enter a value here if and only if Set Maximum Value is YES on the previous page, otherwise this parameter will be ignored.

Default Value - the default value for this field. You should enter a value here if and only if Set Default Value is YES on the previous page, otherwise this parameter will be ignored.

Parameter Page - Boolean Field Checks

This page is shown if Field Properties - Field Type is BOOLEAN, and Field Properties - Define Constraints is YES

Default Value- TRUE/FALSE - if Set Default Value is YES on the previous page you should specify a default value, otherwise this parameter will be ignored.

Parameter Page - Date/Time Field Checks

This page is shown if Field Properties - Field Type is DATE/TIME, and Field Properties - Define Constraints is YES

Date/time values for these fields should be entered in LEA locale-independent format. You can specify either just a date, just a time, or a combined date and time value.
For example:

22/05/2002 11:25	specifies 11:25 AM on 22nd May 2002
14:32:25	specifies 2:32:25 PM
4/12/1999	specifies 4th December 1999

Minimum - the minimum possible value for this field. You should enter a value here if and only if Set Minimum Value is YES on the previous page, otherwise this parameter will be ignored.

Maximum - the maximum possible value for this field. You should enter a value here if and only if Set Maximum Value is YES on the previous page, otherwise this parameter will be ignored.

Default Value - the default value for this field. You should enter a value here if and only if Set Default Value is YES on the previous page, otherwise this parameter will be ignored.
You can also use the reserved string $SYSDATE as a default value, which will be translated into the current date and time at the moment when the record is added to the catalogue.

Parameter Page - Lookup Table Options

This page is shown if Field Properties - Field Type is STRING, Field Properties - Define Constraints is YES, and Field Constraint Definitions - Lookup Method is TABLE/VIEW

Lookup Sort Order
Select from:

• ALPHA (default) - items in the lookup list will be displayed in alphabetical order
• CUSTOM - items in the lookup list will be displayed in the order defined below. This can allow you to display more popular options at the start of the drop-down list used in LEA applications. Note that custom sorting is only applicable for Oracle catalogues - this option will be ignored for dBASE catalogues.

Custom Sort Order
This option is enabled if the Lookup Sort Order (above) is CUSTOM.
You can define an SQL ORDER BY clause using any valid Oracle syntax to sort the lookup results based on the values of other fields in the lookup table/view.
For example:

1 DESC	sort the lookup list in reverse order)
LOCATION, RANKING	(will order the lookup list based on the values of the fields LOCATION and RANKING in the lookup table/view)

The following options are enabled if Field Constraint Definitions - Filter Values is YES

Table Filter Field
The values in the lookup list retrieved from a table can be filtered based on the value of another field.
Enter the name of the field in the lookup table which you want to use to filter values

CDF Value Field
A drop-down list displays the names of all fields defined in this CDF. Select the field from this CDF which you want to compare against values of the Table Filter Field above.

For example:
A CDF has another field called NATION which uses a table lookup to retrieve a list of countries for selection.
This field is called CITY in the CDF. You wish to limit the cities displayed for selection to those in the current nation, so the table or view which you use as the source for the lookup (lets call it CITY_LOOKUP) must have at least two fields - CITY and NATION.
For this field, on the Field Constraint Definition page, set Lookup Type to TABLE and set the Database Name. Table Name will be CITY_LOOKUP and Field Name will be CITY, and set Filter Values to YES
Then on this page (Lookup Table Options), set Table Filter Field to NATION, and for CDF Value Field select NATION from the drop-down list.
At run-time in Dylan and Florence, each time the value of the NATION field changes, the values available for selection for the CITY field will be re-evaluated - when using an Oracle lookup table, a query similar to the following will be issued:

SELECT CITY FROM CITY_LOOKUP WHERE NATION = :NATION

where :NATION is the new value of the NATION field in the CDF catalogue (when using dBASE, the filter is evaluated internally by comparing all records, but the effect is the same)

Parameter Page - Lookup Filtered Lists

This page is shown if Field Properties - Field Type is STRING, Field Properties - Define Constraints is YES, and Field Constraint Definitions - Lookup Method is FILTERED LIST

This parameter page enabled you to specify a different list of valid values for a field based on the current value of another field. Use the PRMEDIT Multiple Page toolbar above the wizard buttons to add, delete and scroll through instances of this page

Condition
Select from:

• MATCHES VALUE (default) - the list specified below will be used when the CDF Value Field matches the Value to Match
• ELSE - the list specified below will be used when the CDF Value Field specified in other instances of this page matches none of the Value to Match. You can only have one instance of a page with the ELSE option - all other instances must be MATCHES VALUE.

CDF Value Field
This option is disabled if Condition(above) is ELSE
Select the field name from the drop-down list of all fields currently defined in this CDF. Note that this must be the same field for all instances of this page.

Value to Match
This option is disabled if Condition(above) is ELSE
Type the value to match. Note that the comparison is case-sensitive.

Lookup List
Click the  ... button to show a list editor dialogue. Enter values, one per line.

At run-time in Dylan and Florence, whenever the value of the CDF Value Field changes, its value will be used to find the correct lookup list.

Key Attributes and the Primary Index

LEA Object Key Attributes

LEA Object key attributes contain information that may be required by LEA Catalogue applications for location reconciliation or data manipulation. Key attributes are marked with an exclamation   icon in the "Available Fields" and "Selected Fields" lists. Deleting any of the key attributes from the Selected list may cause other LEA programs which use the data catalogue to behave erratically.

See also: The Lynx Exploration Archive Object - Key Attributes

The Primary Index

The catalogues that you design in Dougal will usually be saved as database tables. The primary index of a database table is used to sort the records and avoid duplicates. It is not essential, but usually improves the search speed, and makes the database table much more useful because of its increased integrity.

The primary index must be unique for each record. A primary index can be made up of multiple fields, as long as the combination of all the fields within the primary index is unique for each record.

The default primary index in any catalogue description created by Dougal is made up of the first two key attributes of the base LEA Object (see LEA Object base attributes) - ie by default, file name and logical file number. You can change the fields which make up the primary index using the Primary Index Toggle   Button. The primary index fields must be consecutive, starting at the first field (eg a primary index made up of fields 1, 2 and 3 is legal, but a primary index made up of fields 1 and 3, or 2, 3 and 4 is not allowed).

Alternatively you could use an auto-increment field as the primary key instead of the default fields picked by Dougal.

Dougal shows fields that are part of the primary index with a key icon   next to the field name in the right-hand list box of the Object Attributes tab page.

For more information about databases and primary indexes see Using Databases in LEA Applications.

Setting the Layer Type

The CDF Layer Type is used for Location Reconciliation and Spatial Loading, and be set in Dougal using the combo-box at the top of the main window.
See Catalogue Description Files - Layer Type for more details.

INI file configuration settings

The [startup] section of Dougal's INI file contains customisable configuration settings that affect the behaviour of the application

• dBASE compatible
  The value of this key is either 1 (true) or 0 (false). The default value if this key is not present is TRUE.
  In dBASE compatibility mode, you are advised if the field names you have chosen are incompatible with the dBASE database table format or the Firebird SQL engine (see Using Databases in LEA Applications - Database Portability). dBASE is a simple, versatile database format that is used by many applications including ARCVIEW.
  dBASE field naming restrictions are among the most limiting, so any field name that complies with dBASE restrictions will be portable to all other LEA-supported database formats.
• verify lookup table
  The value of this key is either 1 (true) or 0 (false). The default value if this key is not present is TRUE.
  Setting this flag to FALSE allows complex CDFs to be edited 'offline' without access to the Oracle database or dBASE tables specified as lookups for fields in the CDF. The names of tables and fields defined as lookups for CDF fields will not be verified when you click OK on the CDF Field Properties dialog.
• default layer types
  The value of this field is a comma-delimited list of the standard CDF Layer Types defined for Location Reconciliation and Spatial Loading. These values will be loaded at startup into the drop-down list displayed by the Layer Type combo-box, to allow users to easily select a valid Layer Type. The values in the list should match the entries defined in the LYNX_LOCATION_METADATA Oracle table used for Spatial Loading.

Error Messages

The following error messages are produced by Dougal.

Bad command line

The command used to start the program could not be interpreted. See Command-Line options.

File does not exist

The file specified on the command-line does not exist. See Command-line options.

Field definition error

An error generated by the Edit Field Properties dialogue box.
Each field name and description defined for the catalogue must be unique within the current catalogue.
By default, Dougal uses dBASE field naming restrictions, as these are the most restrictive - see INI file configuration settings and Using Databases in LEA Applications - Database Portability.

Primary key Definition error

Generated by the Primary Index Toggle button. See Primary Index for a description of the fields which can legally be added to and removed from the primary index.

No fields defined

This error may occur if you attempt to save the CDF before selecting any fields. Select the Object Attributes tab page to add a set of fields to the catalogue description.

No minimum value entered

In the Field Properties edit dialogue, you have specified that the field will use validity checks, and the field will have a minimum value, but no minimum value has been entered. See Editing a Field Definition above.

No maximum value entered

In the Field Properties edit dialogue, you have specified that the field will use validity checks, and the field will have a maximum value, but no maximum value has been entered. See Editing a Field Definition above.

No default value entered

In the Field Properties edit dialogue, you have specified that the field will use validity checks, and the field will have a default value, but no default value has been entered. See Editing a Field Definition above.

Bad default value entered

In the Field Properties edit dialogue, you have specified that the field will use a lookup list and have a default value. The default value must be one of the items in the lookup list. See Editing a Field Definition above.

Bad lookup list - must have at least 1 item

In the Field Properties edit dialogue, the lookup list for the field is incorrectly formatted. The list should be a series of items separated by commas. If the individual strings contain spaces, you should enclose each item in quote marks. See Editing a Field Definition above.

Bad lookup list value - longer than field length

In the Field Properties edit dialogue, the lookup list for a string field contains an item which has more characters than the field can hold. Fix this either by editing the lookup value, or by increasing the field size.

Lookup table database does not exist

In the Field Properties edit dialogue, on the Field Constraint Definitions page: when specifying an Oracle database table to be used as a lookup, the database name is the Oracle SID used for Net8 connection.
When specifying a dBASE table to be used as a lookup, the database name is the directory path of the DBF file.

Lookup table does not exist

In the Field Properties edit dialogue, on the Field Constraint Definitions page: the lookup table as defined cannot be found.

For an Oracle table or view, check that you have SELECT permission on the table, and if the table is not owned by you, or is not a public synonym, use a fully qualified table name eg SCHEMA.TABLENAME.
For a dBASE table, the table name is the DBF filename (not including the path), but including the DBF extension.

Lookup table field does not exist

In the Field Properties edit dialogue, on the Field Constraint Definitions page: the field name cannot be found.
Check the spelling, and for Oracle check that you have SELECT permission on the column.

Lookup database not defined

In the Field Properties edit dialogue, on the Field Constraint Definitions page: you have left the Database parameter blank.

To specify an Oracle database table to be used as a lookup, the database name is the Oracle SID used for Net8 connection.
To specify a dBASE table to be used as a lookup, the database name is the directory path of the DBF file.

To disable the lookup table, set the Lookup Method parameter to NONE

Lookup table not defined

In the Field Properties edit dialogue, on the Field Constraint Definitions page: you have left the Table Name parameter blank.

For an Oracle table or view, check that you have SELECT permission on the table, and if the table is not owned by you, or is not a public synonym, use a fully qualified table name eg SCHEMA.TABLENAME.
For a dBASE table, the table name is the DBF filename (not including the path), but including the DBF extension.

Lookup field not defined

In the Field Properties edit dialogue, on the Field Constraint Definitions page: you have left the Field Name parameter blank.

Autoinc error - no max or default allowed

In the Field Properties edit dialogue, an integer field has been defined as auto-increment, which means that the value for this field will be automatically determined for each record to create a unique value. Auto-increment fields cannot have maximum or default values. See Editing a Field Definition - Integer Field Checks above.

Min/max value error

In the Field Properties edit dialogue, the minimum and maximum values for validity checks are incompatible. Check that the maximum value is greater than or equal to the minimum value. See Editing a Field Definition above.

Min/default value error

In the Field Properties edit dialogue, the minimum and default values for validity checks are incompatible. Check that the default value is greater than or equal to the minimum value. See Editing a Field Definition above.

Max/default value error

In the Field Properties edit dialogue, the maximum and default values for validity checks are incompatible. Check that the maximum value is greater than or equal to the default value. See Editing a Field Definition above.

Date/time value conversion error

In the Field Properties edit dialogue, the value specified as a default, minimum or maximum date/time value could not be recognised as a date/time. You must use the LEA locale-independent format to speciy date/time values. See Editing a Field Definition - Date/Time Field Checks above.

Sequence database not defined

In the Field Properties edit dialogue on the Integer Field Check page, the Database parameter has been left blank.

Enter the name of the Oracle database SID here, or to disable using a sequence, set Use Sequence to NO

Sequence database does not exist

In the Field Properties edit dialogue on the Integer Field Check page: when specifying an Oracle sequence, the database name is the Oracle SID used for Net8 connection.

Sequence name not fully qualified

In the Field Properties edit dialogue on the Integer Field Check page: the sequence name must include the SCHEMA (the sequence name must be specified as SCHEMA.SEQUENCENAME). This is because by default no public synonym is created for a sequence, and different users must have unambiguous access to the same sequence to retrieve unique values.

Lookup fields not yet defined

In the Field Properties edit dialogue on the Field Constraint Definitions page: you cannot set the Lookup Method to FILTERED LIST, or to TABLE and Filter Values to YES until you have defined more than one field in the CDF.

Bad filter field

In the Field Properties edit dialogue on the Lookup Filtered Lists page: you have selected different CDF Value Field parameters on different instances of this page. The CDF Value Field must be the same on all instances of this page.

Circular lookup - field can't refer to itself

In the Field Properties edit dialogue on the Lookup Filtered Lists page, or the Lookup Table Options page: you have selected the current field as its own lookup value. This will not work! The valid lookup values of this field will change based on the value of another field defined in the CDF.

See also:
[Florence - Catalogue Builder]
[Zebedee - Reconciler and GIS Builder]
Dylan - Catalogue File Registration
[The Lynx Exploration Archive Object]
[Catalogue Description Files]
[Using Databases in LEA Applications]