Program: DYLAN

Title: Catalogue Editor

Version: 1.8

• Introduction
• Running Dylan
• Menus and Controls
• Query Catalogue Parameters
• Error Messages

Back to:

• Main Index
• Data Cataloguing Index

Introduction

This utility can be used to add individual files to catalogues defined and created by the LEA applications Dougal and Florence. Dylan allows the user to select the catalogue to which to add records, then select a file to add, either by dragging the file from an Explorer window, or via a browse dialogue. Dylan will open each LEA Object found in the file, as determined by the structure of the current catalogue, and display each record for editing. Dylan also provides for bulk addition of multiple objects from a single file, and inserting default values for null fields.

The structure of the available catalogues, as well as the types of files to search for (see LEA Object Types) is determined by the LEA Catalogue Designer utility Dougal.

Parameters which affect how filenames are stored in the catalogue are controlled by the Search Options which can be edited from Florence

Running Dylan

1. On application startup, if no archive project file (see LEA Catalogue Tables and Archive Project files) is specified on the command line, you will be prompted whether you wish to:

   • Create a new project (launch Florence) - new projects cannot be created in Dylan - you must use Florence. Select this option to launch Florence automatically
   • Open an Existing Project - browse for an existing archive project file.
   • Open your Last Project - reopen the last project you saved in Dylan or Florence.

2. A list of the available catalogues in the project will be displayed in the Select Catalogue combo-box at the top of the window.
   Select a catalogue from this list. If the catalogue is in an Oracle database, you may be prompted for a username and password if the current Windows username is not a valid Oracle user (or the username, password and database name supplied on the command line will be used).
   The window now displays an empty record-level view of the catalogue.
   Required fields are shown in bold text.
   You cannot edit anything until you have done one of three things:

   • Selected a file to add to the catalogue with the Add File   menu option
   • Added an empty record with the Insert New Record   menu option
   • Selected records with the Browse Catalogue Entries or Query Catalogue menu options
   
   .

3. To register a file in the catalogue, drag the file you wish to register onto the main window, or select the Catalogue - Add File menu option and browse for a file in the dialogue.
   The selected file's full path will be displayed in the Filename edit box at the top of Dylan''s main window with the file's icon. You can launch the file's associated application by clicking the icon.
   If the file has not already been registered in the catalogue, the first object read from the file will be displayed ready for editing.
   However, if the file is already present in the catalogue, you will be given three options:

   • Edit the existing records - you can browse the existing records for the current file, using the First Record, Previous Record ,  Next Record   and Last Record menu options. To edit entries you can change to Edit mode by selecting the Start Editing   menu option.
   • Delete the existing records and re-read the file - all records for this file will be deleted from the catalogue, and new record(s) created by re-reading object information from the file you have selected (see 4 below).
   • Cancel operation
   
   

4. The first object read from the file will be displayed. You can edit any of the field values. If you edit a value into a blank field, where the attribute value could not be read from the file, or is defined in the CDF as a custom field with no associated LEA Object attribute, this field will be marked as a user-default value by a tick in the check box next to the edit field. This value will then be copied into this field for subsequent records read from the file.

5. Use the Add Next Record >  menu option/button to read the next object from the file, and display the record for editing, or use the Add All Records >>  menu option/button to read all objects from the file and create a record for each one. You can also use the First Record, Previous Record  , Next Record   and Last Record menu options to scroll back through the records you have added in read-only mode. To make additional changes to records, activate edit mode with the Edit Record   menu option. When you are in Edit mode, any field marked by a tick in the user-default check box will be copied into other records that you scroll to or insert.

6. Use the Catalogue - Save Changes  menu option to commit your changes to the database (Oracle - this will attempt to reconcile the changes you have made with the changes other users may have made simultaneously to the same records) or re-write the disk file (dBASE).

Command line options

Dylan can be run with a command line similar to the following:

DYLAN [-uCONNECTSTRING] [ZEBFILE [TABLEPATH]]

where:
The optional flag -u specifies an Oracle connection string in the form USERNAME/PASSWORD@DATABASE in the same format as used by Oracle SQL*Plus and other Oracle utilities. If this flag is specified, this connection will override any database name specified in each catalogue name.
If this flag is not specified, Dylan will attempt to connect to Oracle (if necessary) as the current Windows user.

If no username and/or password is supplied on the command-line, you will be prompted with a login dialogue if user authentication is required to access a catalogue from an Oracle database.

ZEBFILE specifies the path of an existing archive project file (with a .zeb extension) to open.
TABLEPATH specifies the catalogue within the ZEBFILE above to open. This should be the complete path of a dBASE table, or a string of the form ;DATABASE;TABLENAME for Oracle database tables.
Remember that all arguments containing spaces should be quoted on the command line with double-quote(") characters.

Menus and Controls

Dylan has the following menu commands:

• File

  • Open Project
    Select an Archive Project File to open from the open file dialogue. The project file must have been previously created in Florence. A list of the catalogues from the project will be displayed in the Select Catalogue combo box beneath the main menu.

  • Connect to Oracle
    Display a login dialogue box to make an explicit connection to Oracle. Dylan will attempt to connect to an Oracle database if necessary, using the current Windows user-name. The current Oracle username and database are displayed in the status bar at the bottom of Dylan's main window. This menu option can be used to enter a user-name, password and database SID name to connect to Oracle.
    It may be necessary to connect to Oracle with an explicit user-name if the current Windows user does not have sufficient Oracle privileges on the required table

  • Disconnect from Oracle
    Close the current Oracle session. You must disconnect before reconnecting with a different user-name.

  • Print
    Print the current record from the current catalogue.

• View

  • Field Names
    Toggle display of the catalogue field names, as defined in the CDF and the database table.

  • Field Descriptions
    Toggle display of the catalogue field descriptions, as defined in the CDF.

• Options

  • Copy On Scroll
    This menu option can be checked or unchecked.
    In checked mode, field values marked in the   column will overwrite existing values when the record is scrolled using the First/Previous/Next/Last menu options (see below) while in Edit Mode (see Start Editing below).
    In unchecked mode, the behaviour is disabled. Field values will not be overwritten when you scroll from one record to another.

• Catalogue

  • Browse Catalogue Entries
    Browse existing entries in the current catalogue. You can scroll through all entries in the catalogue which match a selected value.
    First, a dialogue box is displayed listing the fields from the catalogue. Select the field for which you wish to show all values (the default selection is the FILEPATH field).
    Next, another dialogue box will be displayed listing all distinct values for this field. Select the value you wish to match and click OK. The first matching record will be displayed. You can scroll through each record using the First/Previous/Next/Last menu options (see below), edit individual records using the Edit Record menu option, or delete records using the Delete Record menu option.

  • Query Catalogue
    Select records from the current catalogue based on one or more criteria using an SQL query.
    A PRMEDIT dialogue is displayed allowing you to build the query. See Query Catalogue Parameters (below) for details of how to use this dialogue.
    The first matching record will be displayed. You can scroll through each record using the First/Previous/Next/Last menu options (see below), edit individual records using the Edit Record menu option, or delete records using the Delete Record menu option.

  • Load All Records
    Load all records from the current catalogue. The first record in the catalogue will be displayed. You can scroll through each record using the First/Previous/Next/Last menu options (see below), edit individual records using the Edit Record menu option, or delete records using the Delete Record menu option.

  • Add File 
    Select the file to add to the current catalogue from the browse file dialogue. Alternatively you can drag a file from an Explorer window.
    Dylan uses the same parameter settings as Florence to determine whether the catalogue stores absolute or relative file paths. The catalogue is queried to check whether entries already exist for this file. If they do, you will be prompted to either edit the existing records for this file, or delete the existing records and re-read the file to create new records.
    If you choose to edit the existing records, they will be displayed, allowing you to scroll through each record using the First/Previous/Next/Last menu options (see below), edit individual records using the Edit Record menu option, or delete records using the Delete Record menu option.
    If you choose to delete the existing records and re-read the file, the object information for the first object found in the file will be displayed, and can be edited in the record display. You can add this record to the catalogue, and read the next object from the file with the Add Next Record menu, or add all objects from the file at once using the Add All Records menu.

  • Add Next Record >
    Read the next object from the current file, and create a new record in the catalogue containing this information. You can edit the record, adding values for fields which cannot be read from the file or alter the values displayed.
    For blank fields, you can copy the value from the previous field by ticking the check box before selecting Add Next or Add All.

  • Add All Records >>
    Read all remaining objects from the current file, and create a new record in the catalogue for each object read.
    Before selecting this option, you can enter default values into blank fields and tick the check box for these fields to ensure that a value is automatically entered for each new record

  • Save All Changes (Commit) 
    Changes made to the local record cache (ie record inserts, updates and deletes) will be written back to the server and committed to the database (Oracle), or re-written to the disk file (dBASE).
    When editing Oracle catalogues, if other users have been editing the table simulataneously there may be reconciliation errors to deal with. An error box will be displayed with two options:

    • Abort - discard all changes
    • Ignore - skip the record that caused the error, and continue with the rest of the operation.
    
    

  • First Record
    Jump to the first record in the catalogue for the current file. Select the Edit Record menu option to alter any of the field values.

  • Previous Record 
    Move to the previous record in the catalogue for the current file. Select the Edit Record menu option to alter any of the field values.

  • Next Record 
    Move to the next record in the catalogue for the current file. Select the Edit Record menu option to alter any of the field values.

  • Last Record
    Jump to the last record in the catalogue for the current file. Select the Edit Record menu option to alter any of the field values.

  • Insert New Record 
    Manually insert a new record into the catalogue. This option can be used to add multiple records for a file which cannot be read automatically by the current LEA Object.
    If there is a currently open LEA Object, attribute values from this object will be copied into the new record (in other words, if you have selected a file to add to the catalogue, selecting this menu option will create a new record containing the same attribute information as the current record). You can use the check boxes to specify user-default values for fields (or click the header button marked   to tick all fields) before selecting this option to insert default values for fields.

  • Start Editing 
    Enables edit mode. you can modify the values of fields in the current record, and any record you scroll to. Field values for the current record will be posted before you scroll to another record, but will not be committed/saved to disk until you select the Save All Changes   option. You can tick the check box next to the field value to mark the field value as a user-default value to be copied to this field in other records. This value will be copied into other records when any of the First/Previous/Next/Last options, or the Add Next Record, Add All Records or Insert New Record options are used.
    Fields defined in the CDF with the Initially Null constraint (see Dougal - Editing a field definition - Field Constraint Definitions) will have a 'Get Default Value' button   next to the edit box for the field value. Click this button to get the current default value for the field.
    After editing values, use the Stop Editing option to write the changes back to the current record.

  • Stop Editing 
    Write the changes you have made to the current record after editing field values with the Start Editing option. This sets the display of the record back to read-only mode.
    Note: this option does not save the changes back to the catalogue - use the Save All Changes option to commit your changes to the database or save the changes to disk.

  • Revert Record
    Undo changes to the current record, restoring it to the state read from the catalogue.

  • Delete Record 
    Delete the current record.

  • Undo All Changes
    Discard all modifications to the catalogue, restoring it to the state it was in before the last Add File, Browse or Save All Changes operation.

Query Catalogue Parameters

You can build a query to select records from the catalogue for browsing and editing.
The first record matching your query will be displayed. You can scroll through subsequent records with the First/Next/Previous/Last Record menu options, and edit entries by selecting the Start Editing menu option.

The parameters displayed are used to build a series of SQL SELECT WHERE clauses.
To build a query select theCatalogue-Query Catalogue menu option. A PRMEDIT dialogue will be displayed with the following options:

Condition - AND/OR (default AND)
This option is only enabled for the second and subsequent instances of this page.
The condition is a logical operator which combines the results of two component conditions. You can use this to build up complex queries using multiple instances of this page. See below for details.

Field
Select the field to search from a drop-down list of all fields in the catalogue.

Operation
The type of comparison to use. Different operations are valid for different field types.
Select from:

• EQUALS - valid for all field types.
  Searches for records where the specified Value exactly matches the selected Field.
  Note that for float and date/time fields this option is not always reliable because of rounding/display errors.
  To search for empty strings use the IS NULL operation below.
  To ignore the case of string values, ensure that the Case Sensitive option below is NO.

• STARTS WITH - only valid for string field types.
  Searches for records where the selected Field begins with the Value entered below.
  For more complex searches you can include wildcards within Value:
  % matches any string of zero or more characters
  _ matches any single character.
  
  If no extra wildcards are included in the Value string, the result set will include those records which would be returned by the EQUALS operation.
  There is no need to include a trailing % - this will be added to the end of Value to generate a LIKE clause similar to fieldname LIKE 'value%'.
  To ignore the case of string values, ensure that the Case Sensitive option below is NO, which will change the clause to UPPER(fieldname) LIKE 'VALUE%' (the value parameter will be converted to uppercase before being included in the query).
  For example, enter the value SM will to retrieve SM and SMITH, or enter the value SM%TH to retrieve SMITH and SMYTHE.
  If an index is defined on the selected field in the oracle table, then this search will use that index, which may appreciably speed up data retrieval.

• CONTAINS - only valid for string field types.
  Search for records where the selected Field contains the text entered as the Value below.
  For more complex searches you can include wildcards within Value:
  % matches any string of zero or more characters
  _ matches any single character.
  
  If no extra wildcards are included in the Value string, the result set will include thoise records that would be returned by the EQUALS or STARTS WITH operations..
  There is no need to include a leading or trailing % - these will be added to Value to generate a LIKE clause similar to fieldname LIKE '%value%'.
  To ignore the case of string values, ensure that the Case Sensitive option below is NO, which will change the clause to UPPER(fieldname) LIKE '%VALUE%' (the value parameter will be converted to uppercase before being included in the query).
  For example, enter the value B%T to retrieve records where the specified Field contains the strings ROBOT, BRITISH,....
  For catalogues with a large number of records this search may be slow because indexes defined on the selected field cannot be used.

• BETWEEN - valid for integer, float and date/time field types.
  Searches for records where the selected Field is greater than or equal to Value and less than or equal to Value 2.

• > - valid for integer, float and date/time field types.
  Searches for records where the selected Field is greater than Value.

• < - valid for integer, float and date/time field types.
  Searches for records where the selected Field is less than Value

• >= - valid for integer, float and date/time field types.
  Searches for records where the selected Field is greater than or equal toValue

• <= - valid for integer, float and date/time field types.
  Searches for records where the selected Field is less than or equal toValue

• IS NULL - valid for all field types.
  Searches for records where the selected Field is null (empty).
  

• IS NOT NULL - valid for all field types.
  Searches for records where the selected Field contains any value and is not empty.

Value
The value to search for in the specified Field for the Operation above.
For BETWEEN operations, this is the minimum value for the range to select.
For IS NULL and IS NOT NULL this field is ignored.

Ensure that the value you enter matches the type of the selected Field.
To enter floating point values use the decimal separator as defined on your PC (usually either a dot/period (UK and US settings) or a comma (European settings).
To enter date/time values use the date and time format specified for your PC

Value 2
This option is only enabled for BETWEEN operations (valid for integer, float and date/time fields), where it is the maximum value for the range to select.

Case Sensitive - YES/NO (default NO)
For search operations on string fields, this determines whether the search is case-sensitive. For other field types, this option is ignored.

You can build complex queries by adding more search conditions.
Use the Insert New Page    button at the bottom of the PRMEDIT window to add a search and set the Condition. You can use the Delete Current Page    button to remove the current search, and the Previous    and Next    buttons to scroll through each search definition.

When you have defined your query click OK to retrieve matching records from the database. The first matching record will be displayed. You can scroll through each record using the First/Previous/Next/Last menu options (see below), edit individual records using the Edit Record menu option, or delete records using the Delete Record menu option.

Error Messages

The following error messages are produced by Dylan.

Catalogue not found

The catalogue specified on the command line is not part of the current project file. For dBASE catalogues, you must specify the complete path of the catalogue file. For Oracle catalogues, specify the catalogue as a string in the form ;DATABASENAME;TABLENAME.

No records for selected field

This message is displayed after selecting a field to browse from the Catalogue - Browse Catalogue Entries menu option.
There are no values to display for the field you selected, either because the catalogue is empty, or because the value of this field is null for all records.

The following error messages are displayed when you attempt to register a file in a catalogue, either by dragging it on to Dylan's main window or via the Catalogue - Add File menu option.

File cannot be added to catalogue - path not in root directory

The file which you have attempted to register in a catalogue is not within the root folder specified in the project (this is set in Florence).
This is always enforced when storing relative path names in the catalogues. When using absolute paths, this error will only be displayed when the enforce root dir key in DYLAN.INI's [startup] section is set to 1 (true).

File could not be opened as the specified type.
Add to the catalogue anyway?

The error message is displayed when attempting to open a file of a format unknown to the LEA Object which defines the catalogue. Under normal operation, attribute values will automatically be read from the file into the catalogue fields, but when the format of the file is not recognised by the LEA Object, attribute values cannot be read from the file, and you will have to manually enter the attribute values into the catalogue.

The following error messages are displayed by the Query Catalogue PRMEDIT dialogue, accessed via the Catalogue - Query Catalogue menu option.

Invalid operation for string field

Invalid operation for integer field

Invalid operation for boolean field

Invalid operation for float field

Invalid operation for date/time field

Different field-types can have different search operations. For example, a 'GREATER THAN' search makes no sense on a string field.
The field you select (Query Catalogue Parameters - Field) will determine which operations are valid.
See Query Catalogue Parameters - Operation for help with each operation and the field types on which it can be performed.

Invalid integer value

You have selected an integer-type field for your query (Query Catalogue Parameters - Field), so you must enter an integer (numeric) value for the Value parameter (and Value 2 if applicable).
Integer values must be whole numbers in the range -2147483648 to 2147483647.

Invalid boolean value

You have selected a boolean-type field for your query (Query Catalogue Parameters - Field), so you must enter a boolean (logical) value for the Value parameter .
Boolean values should be '0' (false) or '1' (true)

Invalid float value

You have selected a float-type field for your query (Query Catalogue Parameters - Field), so you must enter a floating-point value for the Value parameter (and Value 2 if applicable).
Floating-point values should be specified using the decimal-separator as defined on your PC (usually either a dot/period (UK and US settings) or a comma (European settings)). Values must be within the range 5x10^-324 to 1.7x10³⁰⁸.
You can also specify values using scientific notation (for example 1.23E25, -1.23E25 or 1.23E-25) using your current decimal-separator.

Invalid date/time value

You have selected a date/time-type field for your query (Query Catalogue Parameters - Field), so you must enter a date/time value for the Value parameter (and Value 2 if applicable).
To enter date/time values use the date and time format specified for your PC

See also errors listed in LEA Catalogue Tables and Archive Project Files and Catalogue Description Files.

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