Lynx Exploration Archivist Online Help

Catalogue Description Files

CDFLIB Version: 2.9

Back to:



Introduction

Catalogue Description Files (CDFs) are used by the LEA applications Dougal (Catalogue Designer) , Florence (Catalogue Builder) and Dylan (Catalogue File Registration). CDFs describe the structure of a data catalogue, which can be used to create and manipulate database tables which store the catalogue. CDFs use the Lynx Exploration Archive Objects defined for different file categories



Field-type Mappings

Catalogue Description Files are used to map catalogues containing information about LEA Objects into database tables.

Catalogues can be stored in any database format supported by LEA Applications - currently Oracle and dBASE - see Using Databases in LEA Applications - and provide a standard mapping between the abstract attribute types defined in the LEA Object, and the field-types supported by the different database formats.

Database tables created from CDFs will use the field types listed below:

LEA Object Attribute Type  Oracle Type dBASE IV Type
STRING VARCHAR2(x)
where x is the specified maximum string length
C,x (Character)
where x is the specified maximum length,
and must be less than 254
INTEGER NUMBER(20)
Integer fields are stored with a width of 20 digits
N,20 (Number)
Integer fields are stored with a precision of 20 digits.
FLOAT NUMBER(20,x)
where x is the field precision, maximum precision is 18
N,20,x (Number)
where x is the field precision,
maximum precision is 18
DATETIME DATE C,30 (Character)
Date/time values are stored as strings in a the LEA locale-independent format (see LEA Objects - Locale Independence) since dBASE has no combined date and time field type.
TRUEFALSE CHAR(1)
Oracle has no boolean type.
Standard practice is to map boolean fields into a 1-byte CHAR field
L (Logical)

Catalogues stored as dBASE tables on disk are suitable for low-volume single-user systems. LEA Applications will load dBASE catalogues into a temporary Firebird database (see Using Databases in LEA Applications - Firebird embedded database) to enable the records to be manipulated with standard SQL. When changes are committed, the dBASE table is re-written to disk.



Layer Type

The CDF Layer Type is used to enable the Location Reconciliation and Spatial Loading functions of LEA Cataloguing. The Layer Type is used to define the type of shapes (POINT,LINE,POLYGON) and destination layer to resolve to when loading data into a spatially-enabled database or GIS project.

Multiple CDFs can share the same Layer Type, even if their underlying LEA Objects are different. For example, you could define a CDF called SEISMIC_MIGRATIONS based on the SEISMIC LEA Object, and another CDF called SEISMIC_REPORTS based on the DOCUMENT LEA Object. Both these CDFs can have a Layer Type of SEISMIC_2D because both will use the same location information, and would be linked to the same layer in a spatail database or GIS.

LYNX_LAYER_TYPES Oracle table

Layer Types are defined in the Oracle table LYNX_LAYER_TYPES. For loading to a spatially-enabled database (see Zebedee), this table must be present, must be acessible as a public synonym. This table defines all valid Layer Types for your spatial database.

The following script will create this table

Column Name Column Type Constraint Comments
LAYER_TYPE varchar2(30) primary key Unique name for a layer with a particular set of business attributes. This is used in DOUGAL to set the CDF LAYER TYPE
DESCRIPTION varchar2(200)    
SHAPE_TYPE varchar2(10) check (SHAPE_TYPE in ('POINT','LINE','POLYGON')) Intrinsic geometry type of this data class - POINT, LINE or POLYGON
SHAPE_PROJECTION varchar2(10)   Projection system for spatial coordinates. Must be WGS84
SHAPE_MEASURES varchar2(1) default 'N' not null check (SHAPE_MEASURES in ('Y','N')) Coordinates have measure values. Y or N
SPATIAL_TABLE varchar2(61)   Name of spatial table (SCHEMA.TABLENAME) for shapes (if applicable)
SPATIAL_GEOMETRY varchar2(30)   Name of column in spatial table which stores coordinate info
SPATIAL_FORMAT varchar2(10)   Format in which to load data into spatial table. Must be SDO or null.
SPATIAL_KEY varchar2(30)   Name of integer key field in spatial table used to link to attribute table
SPATIAL_KEY_SEQUENCE varchar2(61)   Name of Oracle sequence (SCHEMA.SEQUENCENAME) used to generate unique values for SDE-required unique integer key on spatial table. If no sequence is specified then the table is queried to retrieve the current maximum value for this column, and this value is incremented to create a new value
SPATIAL_NAME varchar2(30)   Name of column in spatial table which stores the object name
ATTRIBUTE_TABLE varchar2(61)   Name of business table (SCHEMA.TABLENAME) for shapes (if applicable)
ATTRIBUTE_X varchar2(30)   Name of column in attribute table which stores X/Longitude coordinate of POINT shape. If the shape type is a single POINT, then the coordinate value may be stored in the attribute table, with a trigger set up to synchronise the spatial table. If this field has a value, then the SPATIAL_TABLE and SPATIAL_GEOMETRY columns must be null
ATTRIBUTE_Y varchar2(30)   Name of column in attribute table which stores Y/Latitude coordinate of POINT shape. If the shape type is a single POINT, then the coordinate value may be stored in the attribute table, with a trigger set up to synchronise the spatial table. If this field has a value, then the SPATIAL_TABLE and SPATIAL_GEOMETRY columns must be null
ATTRIBUTE_NAME varchar2(30)   Name of column in attribute table which stores the object name
ATTRIBUTE_KEY varchar2(30)   Name of primary key field in attribute table
ATTRIBUTE_KEY_SEQUENCE varchar2(61)   Name of Oralce Sequence (SCHEMA.SEQUENCENAME) used to generate unique values for attribute table primary key field
ATTRIBUTE_FIELD_MAPPINGS varchar2(4000)   Not yet implemented


CDF Templates

CDF Templates are predefined catalogue descriptions. A template can be used within Dougal to create a customised CDF, or can be used directly with Florence or Zebedee to create a catalogue.

Templates can be saved as either User Templates or System Templates.
User Templates are stored in the TEMPLATE subdirectory of your network user or local directory (see LEA System Installation - System, Data and User Directories).
System Templates are stored in the TEMPLATE subdirectory of the LYNXSYS directory, and are accessible to all users on all LEA-enabled PCs.

Each Template has a unique GUID generated by Windows. CDF Templates should only be created with the Dougal - Save As Template option. Templates can be manually moved from your user TEMPLATE directory to the system TEMPLATE directory to enable a template for all users.


The CDF Template Selection dialogue is used in Dougal, Florence and Zebedee. The tabs at the top of list categorise CDF templates by their Layer Type (see above). A popup menu allows the list to be viewed as large or small icons, and in list or report mode, and the description of the template is displayed in a hint when the muse hovers over a template icon.



CDF Constraint Violations

A CDF can define field constraints which are independent of the constraints defined by the underlying database table, and are evaluated before the record is checked by the database. CDF constraints specify

  1. whether a value is required for the field
  2. minimum and maximum values for the field
  3. a set of acceptable values for the field, either from a static list, or as a distinct set of values from a named field in another table or Oracle view.

A CDF can also define record-level constraints (implemented for Oracle database tables only) which can check the value of one field compared to the value of another field in the same record or set of records from another table (similar to a table lookup, but without the drop-down list). Record-level constraints are defined using SQL syntax, and are evaluated before the record is posted to the database.

Constraint violation errors can occur when adding new records or editing existing records.
Error messages may be displayed giving you various options to respond to constraint violations.
If the application is adding records in batch-mode (eg Florence) and constraint checking is turned on, then you will have options to

If the application is adding records one at a time (eg Dylan), you will have options to



CDF File Format

A Catalogue Description File is an ASCII file that starts with the reserved string  [lynx]  in common with all LEA INI and parameter files. The program and version keys in this section are used by applications reading the CDF to check the format of the file.

In the  [table type]  section, the LEA objects key lists the LEA Object INI files used in this catalogue description as a comma-delimited string prefixed by an asterisk character to preserve quotes which can get stripped from strings when reading and writing INI files - eg::

LEA objects=*LEAOBJ.INI,BASEOBJ.INI

The description key gives a short text description of the CDF, which is displayed in LEA applications.

The database table structure is defined in the  [layout]  section of the file. The field count key is the number of fields defined in the catalogue definition. Each field of the table is then described as a separate key as a comma-delimited list of values. The format of the description is:

FieldNo=ININame,AttrNo,FieldName,FieldDescription[,FieldType,FieldLength]

where:

FieldNo
The zero-based index of the field (ie the first field has an index of 0, the second field has an index of 1, up to the last field, which has an index of (field count)-1).
ININame
For LEA Object Attribute fields, this is the name of the LEA Object INI file containing the attribute definition. User-defined fields are distinguished by using the code *****.
AttrNo
For LEA Object Attribute fields this is the numeric attribute code from the LEA Object's INI file attribute definition. User-defined fields are distinguished by using the code *****.
FieldName
The name of the field, as defined by the user.
FieldDescription
A description (stored as a quoted string) which is used as the field header when the database table is displayed by LEA applications
(The following fields are only present for user-defined fields)
FieldType
The type of the field (see LEA Object Attribute Types)
FieldLength
This is only used for string and float fields:
For string fields this is the maximum length of the text.
For float fields this is the number of significant decimal places required.

The  [index]  section describes the indexing of the catalogue. The primary key count key lists the number of fields that should be used to create the primary key; for example, primary key count=3 indicates that the first 3 fields should be used to generate the primary key. The combined values of all fields within the primary key for each record must be unique.

The  [edit mask] section lists the edit mask for each field in the form:

FieldNo=*EditMask

where:

FieldNo
The zero-based index of the field, as used in the [layout] section
EditMask
The edit mask for the field, prefixed by an asterisk character to preserve quotes which can get stripped from strings when reading and writing INI files

If there is no entry for a field number, then the field has no edit mask.

The  [validity] section describes the constraints imposed on values for each field. Validity checks for each field are described as a separate key as a comma-delimited list of values. The format of the description is:

For STRING fields

FieldNo=AllowBlank,HasMin,HasMax,HasDefault,AutoInc,MinValue,MaxValue,DefaultValue[,LookupMethod[,LookupDatabase,LookupTable, LookupField[,CustomSort[,FilterField,ValueField]]]]

if LookupMethod=1 (static lookup list) then another key,value entry is included in the section:

FieldNo LOOKUP LIST=*lookuplistvalues

if LookupMethod=4 (filtered lookup list} then another key,value entry is included in the section for each value to match:

FieldNo FILTERED LOOKUP MatchVal=*lookuplistvalues

if LookupMethod=4 then the following lookuplist will be used when no value is matched

FieldNo DEFAULT FILTERED LOOKUP=*lookuplistvalues

if CustomSort=1 (true) then another key,value entry is included in the section

FieldNo LOOKUP SORT=*customsortstring

For INTEGER fields

FieldNo=AllowBlank,HasMin,HasMax,HasDefault,AutoInc,MinValue,MaxValue,DefaultValue[,UseSeq[,SeqDB,SeqName]]

For other field types

FieldNo=AllowBlank,HasMin,HasMax,HasDefault,AutoInc,MinValue,MaxValue,DefaultValue

where:

FieldNo
The zero-based index of the field, as used in the [layout] section
AllowBlank, HasMin, HasMax, HasDefault, AutoInc, CustomSort, UseSeq
These can all be either 0 or 1 (indicating false or true). Values can be blank if not applicable to a particular field type - eg for string fields, HasMin,HasMax and AutoInc are blank.
MinValiue, MaxValue and DefaultValue
These are the constraints specified for the field. If not applicable they should be blank.
LookupMethod
This value and all subsequent values in the list are only applicable to string fields at present. LookupMethod can be one of 4 values:
0 - No lookup method
1 - Use a static lookup list
2 - Use a lookup table
3 - Use the parent folder name of the current file
4 - Use a filtered lookup list
LookupDatabase, LookupTable, LookupField
If LookupMethod is 2 then these three values must be defined.
For an Oracle lookup table, LookupDatabase is the Oracle database service name, LookupTable is the name of the table to use (including the schema if there is no public synonym), and LookupField is the name of the field from which to query all distinct values.
For a dBASE table, LookupDatabase is the path of the directory containing the dBASE table, LookupTable is the filename of the dBASE table and LookupField is the name of the field from which to select unique values.
FilterField
For lookup tables, the name of a field used to filter the results of a SELECT query (Oracle only - not applicable to dBASE lookup tables)
ValueField
For filtered lookup tables and filtered lookup lists, the name of the field in this CDF file which must be matched.
lookuplistvalues
This is a quoted/comma-delimted list of the lookup values. The string is preceded by * as Windows API INI reading functions string leading/trailing quotes from strings
customsortstring
This is a quoted string used as an ORDER BY clause in an Oracle 8i SQL SELECT statement. Custom sort strings are only valid for lookup tables from an oracle database

Custom fields may also have an additional key:

FieldNo INITIALLY BLANK=1

which specifies that although the field is defined as auto-increment, or using a Oracle sequence, or with a default value, the value of the field for new records should initially be null. LEA applications provide a mechanism to get the default/increment value on demand.

If there is no entry for a field number, then the field has no validity checks

The  [constraints]  section lists any record-level constraints defined for the CDF. The constraint count key is the number of record constraints defined in the catalogue definition. Each constraint is then listed as a separate numbered key. The format of this key is:

ConstraintNo=ConstraintText

where:

ConstraintNo
The zero-based index of the constraint.
ConstraintText
The text used to evaluate the constraint. This should use Oracle SQL syntax. Field names should be passed as SQL parameters, prefixed by a colon, and should always be followed by at least one space.

This section can also contain an additional key for each constraint:

ConstraintNo ERROR MESSAGE=ConstraintErrorMessage

where:

ConstraintErrorMessage
The text which is displayed in error messages when the constraint is violated.

If the error message key is not present for a constraint, then the default error message will be displayed.



Errors Messages

Listed below are the error messages that may be generated by applications that use CDFs

Not a LEA CDF file

The file that is specified is not a catalogue description file. CDF files contain only ASCII characters and the first line is always [lynx]. The specified file may belong to a non-Lynx application, or may have become badly corrupted.

Catalogue table does not match CDF

The database table definition of the specified catalogue does not match the one defined in the catalogue definition file.Either the number of fields is different, or the field types do not match. The application cannot interpret a catalogue table without the accompanying CDF. Make sure that you select the correct CDF for the catalogue table file you wish to open.

No CDF file defined

You have attempted to open a catalogue table file without specifying a CDF. The application cannot interpret a catalogue table without the accompanying CDF.

No version information in CDF file

or

Bad version number in CDF file

These errors mean that the CDF file is incompatible with the application that is attempting to read it. The CDF file's version number mismatches the allowed version range string in the CDFLIB.INI file. You are probably trying to use a CDF file created by an earlier (or later) version of an application, whose internal structure does not match that expected by the current application.When the parameter file's version number is missing, the file is probably seriously corrupted.
Both these errors could mean that you may have a number of conflicting versions of program INI files installed on your system.

Error in primary index in CDF file

The primary index fields read from the CDF are incompatible with the field definitions read from the same file. This probably means that the CDF has become corrupted.



See also:
[Dougal - LEA Catalogue Designer]
[Florence - LEA Catalogue Builder]
[Lynx Exploration Archive Objects]