Finder Database Admin

Finder Database Administrators Reference
Chapter 1: Introduction Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Organization of This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Other Recommended Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Important Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Finder Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Vector Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Data Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Enterprise Scopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 The Finder Database Schema Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Finder Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

The Software-Operating System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Setting the Default Date Format in Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using the Analyst or Projects Defaults forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Chapter 2: Account Management Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Administration of Finder accounts for Enterprise/GeoWeb . . . . . . . . . . . . . . . . . . . . . . . . . 26
Account Management Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Finder Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Database Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Security Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Using the Analyst or Projects Defaults forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Converting Two-digit Years to Four-digit Years . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
0505021550/fgs 9.4
AF
v
The Vector or N-List Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Automated Database Administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Database Security Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Modeling Invariant and Interpretative Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Cartographic Pipeline . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Data Stored in Operating System Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Copyright Schlumberger
Contents
Database Security Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Zero Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Minimal Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Normal Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Tight Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Operating System File Protections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 ORACLE Database Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Database Account Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Starting the Database Account Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Current Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Connect As . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Using the Database Account Manager Validate Function . . . . . . . . . . . . . . . . . . . . . . . . . . 40 Validating Accounts Using the schema_run_validate Utility . . . . . . . . . . . . . . . . . . . . . . . . 42 Troubleshooting Account Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Creating and Dropping Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Granting and Revoking Object Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 Granting and Revoking System Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Granting and Revoking Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Account Maintenance Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Backing-up and Restoring Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 Archiving Finder Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
The Basic Archiving Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Archiving a Project Account to Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Archiving an Analyst Account to Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Archiving ESI, CODES and DEFAULT_PROJECT Accounts . . . . . . . . . . . . . . . . . . . . . . . 69 The Quick Archive Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Creating a Project Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Creating an Analyst Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Creating a Federation DBA Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Creating a Catalog DBA Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Deleting Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
0505021550/fgs 9.4
AF
vi
Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Contents
Restoring Archived Finder Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Restore the Archived Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Restoring Quick Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Chapter 3: Analyst Account Management Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Analyst Account Database Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Finder Analyst Scope Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Analyst Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Creating New Analyst Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Introduction to Creating New Analyst Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 Creating New Analyst Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Logical Names form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Tablespace Names and Space Allocations form . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Tablespace names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Space allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Advantages/Disadvantages of Using OS Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Using OS Authenticated Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Chapter 4: Project Account Management Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Project Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Project Operating System Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Coordinate System Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Important Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Map Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Projection Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Datums and Ellipsoids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Coordinate System Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Coordinate System Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Datum Shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 Configuration Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Support for Operating System Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
0505021550/fgs 9.4
AF
vii
Translation column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 ENV column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Creating a New Finder Analyst Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Contents
Defining a Coordinate System in a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Adding a Geodetic Coordinate System to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Adding a Projection Coordinate System to a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Deleting a Coordinate System from a Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Adding User-Defined Projections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Adding User-Defined Datums and Ellipsoids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Preparing to Create Project Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Project Creation Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Choose the Project Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Project Manager Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Project Manager Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Verify the ORACLE Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Check System Resource Availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Translation column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 ENV column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Tablespace Names and Space Allocations form . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Project Data Storage Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Default Map Display Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Project Default Unit of Measure Display Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Plotting Project Default Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Set the Analyst Default Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 Define Project Codes and Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 The LOG_TRACE_DISPLAY_DEFAULTS Table . . . . . . . . . . . . . . . . . . . . . . . . . 135 The OPERATOR_ALIAS Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 SEIS_HOR_CODES/SEIS_FAULT_CODES Tables . . . . . . . . . . . . . . . . . . . . . . 137 Chapter 5: Customizing the Database Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Define the Project Default Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Tablespace names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Space allocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Table partitioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
0505021550/fgs 9.4
AF
viii
Create Project Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Logical Names form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Allocate Disk space for Project Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Allocate Space in the ORACLE Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Contents
Data Model Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Finder Meta-data Dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 The Finder Database Schema Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Project-specific Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Create a view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Create a Materialized View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 Create a REFRESH FAST Materialized View Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Notes for Production Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Modified ORACLE Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Table Synonyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Miscellaneous Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Data Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Finder Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 ORACLE-reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 N-List Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Displaying Finder Product Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 Creating or Modifying Table Default Storage Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Creating or Modifying Column Couplings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Changing the Default Color in the Lease Overlay . . . . . . . . . . . . . . . . . . . . . . . . . 180
Default ORACLE Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Foreign Key Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 Column Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Function-based Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Bitmap Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
0505021550/fgs 9.4
AF
ix
Define Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 ORACLE Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 Site-specific Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Contents
Adding User-defined Objects to the Finder Schema . . . . . . . . . . . . . . . . . . . . . . . 182

Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Process Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Customizing UOM Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Propagating Database Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 Chapter 6: Customizing Database Tools Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 Understanding the File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Key Points on Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Scripts That Access Project Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Storing Scripts Created by the Database Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . 203 Making Scripts Known to Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Troubleshooting Script Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Customizing Finder ORACLE Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Customizing Forms in Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Oracle Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Forms Provided with Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Creating New Custom Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Updating Custom Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Year 2000 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
GeoQuest Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Forms Provided with Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 Creating New Custom Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 Updating Custom Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 Year 2000 Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
ORACLE Reports File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
The New Script Does Not Appear in the List of Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 The New Script Does Not Appear in Use Default Select List . . . . . . . . . . . . . . . . . . . . . . 208
0505021550/fgs 9.4
AF
x
Overview of the Customizing Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Customizing Finder Report Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Customizing Scripts Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Contents
The Application Management Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

Introduction to the Application Management Database . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 Update the List of Available Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
ORACLE_APP_SELECTION View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 ORA_APP_MAINT Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 finder_template.fmb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 gdm_template.fmb . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 Foreign Function Interface (ffi) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Customizing Select Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Select Phrase Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 Protecting Customized Select Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Troubleshooting Select Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
License Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Registering Document Viewers and Scanners . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

EDM Administration Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 Scanner Output File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 Registering Scanner Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Utilities Used with Document Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 Chapter 7: Customizing Database Graphics Customizing Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Symbol Display Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Creating or Modifying the Symbol Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Saving Changes to an SDL File and Appropriate Directory . . . . . . . . . . . . . . . . . . . . . . . 253 Modifying the Appropriate Symbol Lookup Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Customizing GPDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Defining Document File Type Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237 Defining Document File Format Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 Scanner Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
0505021550/fgs 9.4
AF
xi
Customizing Document Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
The Table Look-up Function Does not Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 Multiple Table Look-ups Do not Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 An Error When Processing Select Phrase Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Contents
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Working With GPDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Using GPDL files in Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
GPDL Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

The Graphics Product Description Language (GPDL) . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Standard GPDL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Finder GPDL Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Finder GPDL Arithmetic and Geometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 Customizing Title Blocks, Lease Legends and Logos . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Customizing Cross Section Symbol Tracks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
How Colors are Defined . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Scripts That Alter the Color Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Examining the Color Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 Inserting a New Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Deleting an Existing Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Updating an Existing Color's RGB Value or Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Color Index List Caveats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Custom Ordering of the Color-selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Find Option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Color Ordering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Registering Patterns with Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Pattern Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Customizing Bubble Map Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Adding New Symbol GPDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 Modifying Symbol GPDL Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Default Attribute Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339 Location of Bubble or Pie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340 Data Label Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Text Font . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Customizing CPS-3 Gridding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Redirection of CPS-3 Working Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Numerical Sequence Gaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Safe Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
0505021550/fgs 9.4
AF
xii
GPDL Object Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Customizing Applications Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Customizing the Map Overlay Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 Setting the Default Plot Size Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 Customizing Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 User-defined Color Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
Contents
Color Fill Contour Palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Modifying the Color Fill Palette Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Adding New Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Chapter 8: Database Maintenance and Troubleshooting Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 Database Clean-up Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 FM_CLEANUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Expired Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 FM_CLEANUP Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 FM_CLEANUP Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 Example FM_CLEANUP Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
NL_CLEAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
NL_CLEAN Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 Preparing to Run NL_CLEAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 NL_CLEAN Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Chapter 9: System Set-up and Configuration Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 Database Access License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 Pre-conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 License Admin daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 FlexLM Log File Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 Configuring User Start-up Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 X Windows Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Important Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 The .Xdefaults File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 The XFinder Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Starting Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Configuring User Workstations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
DB_CLEANUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 Tuning ORACLE for Data Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 Periodic Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 Recovering Space Allocated by Oracle after Using DataMover . . . . . . . . . . . . 367 Improving performance When Querying OFM Views . . . . . . . . . . . . . . . . . . . . . . 367 Analyzing Tables for General Production Views . . . . . . . . . . . . . . . . . . . . . . . . . . 368 Recovering from Database File Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
0505021550/fgs 9.4
AF
xiii
Contents
Configuring Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Using the Analyst or Projects Defaults forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Inserting into tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
Configuring Peripheral Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Configuring Digitizing Tablets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Configuring Plotting Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
N-List Data Stored as BLOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 N-List Storage Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Mapping N-Lists to BLOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405
Data Store Directories and Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
Table Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412

Logical Names Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Newly Created Project Using Relational Table-Based N-Lists . . . . . . . . . . . . . . . . . . . . . 413 Changing an Existing Project to Use Relation Table-Based N-Lists (Side Grade) . . . . . . 414
Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 Migration strategies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 nlist_mover Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
nl_blob_audit Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

nl_blob_audit Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Troubleshooting N-List BLOBs Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Table Not Created During BLOB Table Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Table Created but BLOB Not Importing Correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421 Third-Party Application Cannot Read or Write to the Database . . . . . . . . . . . . . . . . . . . . 421
Chapter 10: Finder SDE Administration Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 Finder SDE overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Description of Finder SDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 Finder SDE workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Finder SDE utility reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

f2sde_extension utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 f2sde_layer utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 f2sde_transfer utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 nlist_mover Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
0505021550/fgs 9.4
AF
xiv
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413
Contents
Finder SDE data model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447

Finder SDE meta data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 Finder PROJECT_DEFAULTS table parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 Finder SDE tables for spatial data and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 Finder SDE account data model schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Well and deviation data selection methods for Shape File Unloader and f2sde_transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 SDE performance tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466 Work-arounds for known problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
D
0505021550/fgs 9.4
R
xv
AF
Contents
D
0505021550/fgs 9.4
R
xvi
AF
Chapter 1: Introduction
Chapter 1
Introduction
The Finder Database Administrators Reference has been written for the purpose of instructing the database administrator in the use of the Finder database system and supporting software.
Organization of This Manual

The Database Administrators Reference contains nine chapters, as follows. Chapter 1, Introduction, describes the documentation available and introduces the role of the database administrator. The chapter describes the overall data model used in the implementation of the Finder database, documents the database tables associated with the various types of Finder accounts and describes how the database and software interacts with the operating system. Chapter 2, Account Management, provides an overview of what is involved in creating and maintaining accounts and introduces the tools available to assist the DBA in account management. Chapter 3, Analyst Account Management, describes in detail what is required to create a new Analyst account and make it ready for running Finder. Chapter 4, Project Account Management, describes in detail what is required to create a Project account, define projections and other project default information and prepare the project for data loading.
Revised May 2, 2005
Chapter 5, Customizing the Database, covers the steps required to add tables, views, indexes and other database objects to the Finder database. Chapter 6, Customizing Database Tools, includes instructions for creating forms, reports, select phrases and other user tools and making them part of the Finder environment. Chapter 7, Customizing Database Graphics, includes instructions for modifying symbols used in Finder maps and cross sections. Included is a reference to the Graphics Product Description Language (GPDL) and examples of its use. Chapter 8, Database Maintenance and Troubleshooting, covers the Finder utilities used to maintain the database, to identify the causes of database problems and recover from them. Chapter 9, System Set-up and Configuration covers the procedures necessary to set-up a user workstation and peripheral devices for use with Finder, the on-line versions of the Finder documentation and other GeoQuest products. Chapter 10, Finder SDE Administration describes how to create a Spatial Data Engine (SDE) extension account for a Finder project. A project SDE extension allows ESRI application users to access spatial data directly from Finder without having to first export data to shapefiles. This chapter describes the Finder SDE utilities for creating and managing SDE accounts, as well as the Finder SDE data model.
Other Recommended Documentation

The database administrator should also acquire from ORACLE or GeoQuest copies of the following. SQL*Plus User's Guide and Reference ORACLE8i Administrators Guide ORACLE Forms Developer ORACLE Reports Developer ORACLE Forms Developer and Reports Developer
Revised May 2, 2005
Important Concepts
This section summarizes the concepts important to working with and maintaining Finder.
SQL Relational Database

Well Headers Well Tops Engineering Data Land Data, etc. Seismic Surveys Seismic Lines Seismic Surfaces Seismic Lines Ties, etc.
Geometry/ Vector Database

Well Logs Land Nets Seismic Line Locations
Figure 1: Finder database concept
Finder Database Overview

The Finder database structure provides the capability for managing and interpreting the large amounts of data typical of most oil and gas exploration and production applications. Because scientific theories, data acquisition techniques and technology in general are continually changing and improving, software written to access a static database will not work well, since the software must be modified each time a change is made to the database structure or each time someone thinks of a new way to evaluate the available data. The Finder database has been designed to be as flexible as possible and the Finder software gives the user the flexibility to try new ways of using the data. The Finder database is an ANSI-standard SQL database with vector extensions as shown in figure 1 on page 3.
Revised May 2, 2005
One of the most significant developments in the computer industry since the 1980s has been the emergence of SQL (commonly pronounced sequel) as the dominant industry standard. Enormous benefits are now flowing from this standardization, because true ANSI-SQL compliant software systems have the following properties. They can readily interface to RDBMS database engines offered by a variety of vendors. They connect to SQL-compliant databases on foreign hardware platforms over all popular networking standards. They can be maintained by the growing number of ANSI-SQL experienced programmers. They benefit from the rapidly growing inventory of 4GL tools, CASE tools, user interface layers (such as natural language query systems or generalized graphic query systems) and connectivity tools (such as CL/1).
The above benefits of constructing the Finder system as an ANSI-SQL compliant solution are now well understood. Finder would be a purely SQL-based system, but for the practical issue of achieving the highest levels of system performance for data classes which have more structure and texture than the pure relational model was designed to support. In geoscience and GIS applications, many of the most critical data classes have properties of order, connectivity and meaningful discontinuity that cause a pure relational DBMS to yield very unsatisfactory performance. Common examples are well logs and seismic data.
Vector Database
The Finder database architecture has been designed to retain all of the benefits of ANSI-SQL compliance and at the same time to obtain very high database performance using a proprietary vector database technology based upon N-List objects. N-Lists are multi-dimensional vector objects which are conceptually similar to an unlimited length linked list of tables, where the tables may have an unlimited number of columns of any data type and an unlimited number of rows. Just as is the case for a SQL table, the contents of a particular N-List column must be of uniform data type and uniform maximum length.
Revised May 2, 2005
N-Lists have a number of highly useful properties, some of which are shown below. Subsequent rows in a particular N-List table are ordered (unlike SQL tables where no ordering is implied by definition) and have implied continuity, which means that values within an NList table have a well defined spatial relationship that allows for interpolation of values between points. There is a discontinuity between linked tables within an N-List. This means that the break between tables are also significant in that data cannot be interpolated across the gap, as in a horizon broken across a fault. Because of the well-defined structure of N-Lists, Finder incorporates a wide variety of standard tools and services for operating on N-List objects (for example, draw an N-List, graphically edit an N-List, spatially filter an N-List, take the natural logarithm of an N-List, etc.). N-Lists may have associated methods which can greatly simplify complex operations. An N-List representing a well log may carry a method defining a particular operator to be applied whenever the N-List is sent the message Yourself. Because N-Lists are intrinsically dynamic objects, with all dynamic memory management provided by the N-List toolbox, they provide a simple vehicle for applications to achieve scaleability with respect to memory and file system usage.
A critical design requirement for the Finder database is that the user must always be able to freely browse the database with ad hoc queries. For example, highlight the wells which have density logs and sonic logs covering the JACKSAND interval and have core data over the same interval. To ensure satisfaction of this requirement, the design rules of the Finder database enforce a master/subordinate relationship between the SQL database tables and the N-List objects. This means that the navigation path to an N-List object is always via a SQL query which yields the names of the desired N-Lists (the access path to an N-List object is associative, meaning simply that an N-List is stored or retrieved by its name). This structure also allows reliable transaction management to be performed by Finder using the standard ORACLE facilities for commit and rollback.
Revised May 2, 2005
The Finder vector database has been designed and engineered to the same industrial-strength standards as the ORACLE RDBMS. There are many issues which must be addressed properly to achieve this level of reliability, requiring a significant investment in software development. Some examples are shown below. A self-describing file structure which permits recovery of the file contents and structure in the absence of the particular version of the N-List code which generated the data. Internal file consistency checks for detection of anomalies in the operating system file system or physical media. The self-describing file structure also provides the necessary underlying mechanism to provide network-transparent access to the vector data objects among computers with different representations for data types, different alignment or byte order conventions, etc. Automatic N-List data caching (only the data actually used is loaded). Concurrency control by standard operating system and network facilities.
Data Dictionary
The practical operation of large database systems places severe demands on the database administration capabilities of the system. In brief, the key issues are as follows. Data integrity. Flexible and robust security management. Practical automation of database administration tasks, including operations which involve both ORACLE RDBMS maintenance and vector database maintenance. Referential integrity support, including foreign keys, row assertions, value assertions and data type declarations. Easy customization by users at the Site level, the Project level, the Role level or the Analyst level. Reliable and automatic controls for management of updates to the database design or the Finder software, particularly in the light of the ease of customization capabilities above. Not only is it a mandatory user requirement that no data are lost when new software or a new database release is installed, but it is impractical in an operational system to require a user to unload and reload his database to accommodate new software releases.
Revised May 2, 2005
To ensure that these requirements are achieved for the Finder database, the architecture and much of the actual operation of the Finder system is controlled by the Finder data dictionary.
Analyst
Project
Codes
System Logical Privileges Indices Names
Database Domains
Automatic Management of ORACLE Data Dictionary Automatic Create Create Validate Management
ORACLE Data Dictionaries
New Analyst
New Project
OS Existing Project Directories and Files
Figure 2: The Finder meta-data dictionary.
Finders designers found that achieving their goals required an architecture which is controlled by a meta data dictionary. That is, a data dictionary which is described at a higher level of abstraction than the SQL or ORACLE data dictionary. The Finder data dictionary defines the objective standards and topology of the entire database and therefore serves as the prescription for automatic creation of the ORACLE SQL data dictionary for any required account. In addition, the Finder data dictionary supports a number of concepts and facilities that are not available in a SQL data dictionary. One such key concept is that of domains which are the abstract data types upon which the Finder data model is constructed (e.g., unique well identifier, depth down hole, porosity measurement). The Finder database domains are used to support DBA automation and to assist in data modeling.
Scopes
Figure 2 on page 7 depicts four of the key scopes of the database design. A scope is the first level of logical decomposition of the database and for security management reasons is implemented as a distinct SQL account.
Revised May 2, 2005
System Scope
The System scope defines the data meta-dictionary itself, together with a variety of system-wide information which controls the operation of Finder, such as workstation, terminal or tablet configuration information, site configuration information on system plotters, default settings for each new Finder user, the localized text of all user communications, etc.
Codes Scope
The Codes scope defines assertions that control acceptable values which attributes may assume (such as well status or log curve identification), graphics attributes, unit of measure, etc.
Analyst Scope
The schema and defaults for a user environment is defined by the Analyst scope. Aside from security issues, discussed below, the Analyst scope is comprised mainly of personality or preferences for the individual user, such as their preferred priority sequence for retrieving well or seismic interpretative data.
Project Scope
The Project scope defines the schema and defaults for an exploration and production spatial database instance. An instance of the Project scope contains the actual data for any geographic area of interest to the client. A world database is a project, as is a field study database. Associated with each instance of a project is a set of properties (referred to as project defaults) which define the standards for the data domains of that specific project. Many issues are involved, but the following are some key examples. The unit of measure for distance on the earths surface. The unit of measure for distance along a well bore. The cartographic representation of all coordinate data within the project. The default cartographic projection for mapping. The default scale and map area for a new map.
In general, such standards are used to ensure internal consistency of the data stored in a project, although there are certain data domains (e.g., associated with well logging), where it is necessary to store mixed units of measure in the database. This design rule simplifies the management of
Revised May 2, 2005
the database, since the vast majority of the data domains are required to be internally consistent and improves performance, since it is not necessary to evaluate data-type tags every time a data element is accessed. The assertion of standard cartography within a project also facilitates the implementation of the Cartographic Pipeline concept (see below) and can significantly improve system performance. System and Codes accounts are discussed in the Account Management chapter of this volume. Project accounts are discussed in the Project Account Management chapter of this volume. Analyst accounts are discussed in the Analyst Account Management chapter of this volume.
SMARTMAP Scope
The SMARTMAP scope is used to store SMARTMAP specific information, such as map definitions, map layouts etc. The SMARTMAP scope is only used when SmartMap is started with SMARTMAP as the current project. You might want to do this in order to store all map specific data in one central location.
Enterprise Scopes
Enterprise is an application that provides the infrastructure to link a set of related E&P databases into a virtual multi-domain database. Enterprise is installed along with Finder and the Finder Database Schema includes five Enterprise scopes. These scopes are described below:
EK_WH Scope
The Enterprise Warehouse (EK_WH) scope defines the schema and defaults for the Finder Enterprise warehouse account EK_WAREHOUSE. The schema definition includes object definition for the master catalog objects, the data catalog objects, and meta data objects.
EK_SYS Scope
The Enterprise System (EK_SYS) scope contains the schema and defaults for the capturing of Enterprise meta data. The EK_SYS scope consists of the Common Data Management Projection (CDMP) and the information for various applications whose repositories can be part of the federation.
EK_PUB Scope
The Enterprise Public (EK_PUB) scope contains read-access privileges to a set of objects in the EK_WAREHOUSE account.
Revised May 2, 2005
EK_FED Scope
The Enterprise Federation DBA (EK_FED) scope contains read/write access privileges to the Enterprise user information and the Enterprise repository information.
EK_CAT Scope
The Enterprise Catalog DBA (EK_CAT) scope consists of read/write access to the Enterprise master catalog and the Enterprise data catalog. The Enterprise scopes are discussed in more detail in the Finder Architecture chapter of the Finder Data Model and Dictionary.
The Finder Database Schema Report

Finder includes an ORACLE report which will produce a listing of all of the tables, their column specifications, indexes and data domains associated with each type of Finder account. This is a valuable reference listing to keep on hand. A copy of this report is included in the Finder Data Model and Dictionary, but this will not include any changes made to your the database structure since installation. To obtain a current listing of the Finder database schema report, use the Finder Report application and choose the OTHER report type, then choose Finder database schema from the list of available reports. For more information about the Finder Report application, see the Reports section in the Applications Menu chapter of the Finder Users Reference.
Automated Database Administration

Finder accounts are ORACLE accounts that are used in special ways by the Finder software. Project and Analyst scope accounts are the accounts in which the working data will be stored and accessed by users. They are created by the Finder database administrator using the automated procedures in the Database Account Manager, which are described in the following list: Creating a new user environment (an Analyst in Finder terminology). Creating a new exploration and production database (a Project in Finder terminology). Granting different levels of access to a type of user (a Role is a set of database privileges in Finder and ORACLE terminology). Adjusting the security on a project.
10
Revised May 2, 2005
Validating an existing database. This is a very critical operation and is used for a variety of purposes shown below. Performing a health-check and, if possible, repair an instance that may have been damaged by a user or DBA mistake or system failure. Publishing a revision to the schema to all or selected existing instances. Installing a new version of an instance and software.
For example, keeping project data in a separate account from the users account allows for additional levels of security and control over data input and integrity. This is accomplished by granting specific privileges on the project tables to individual Analyst accounts or to groups of Analyst accounts. It also possible to grant a particular set of privileges, or Role, to a user or group of users. Using either SQL*Plus (or the Finder Database Account Manager, which automates the process), the DBA can either GRANT or REVOKE any or all of the privileges to access and modify the project data tables, including SELECT, INSERT, UPDATE and DELETE privileges. These can be granted on a table-by-table, role-by-role or user-by-user basis on the project tables as required by the security and data management requirements of the user.
Database Security Management

The Finder facilities for management of data security are both robust and easy to use and administer. Finder is policy-neutral about security, but provides a database architecture and DBA services which permit any Finder site to dynamically establish security as tightly or loosely as management determines. One of the key reasons for the top-level decomposition of the database into analysts and projects is to obtain highly flexible control over any users ability to view, add or modify the data in a particular project.
Revised May 2, 2005
11
ANALYSTS Hans Robert
Select All Access All Update Geology
Select Seismic Select Seismic Insert Seismic Update Geology Insert Seismic
PROJECTS Netherlands Sector Norway Sector UK Sector
Figure 3: User access to Finder data.
Complex security privileges as depicted in figure 3 can be established in a few seconds using Finders automated security management user interface. To achieve such flexible and pin-point control over security requires that the exploration and production data must be managed in SQL accounts separate from the SQL accounts which serve as the login point or connect point for any user.
Modeling Invariant and Interpretative Attributes

The Finder data model defines as Invariant attributes those for which only one answer is appropriate under normal operation. In contrast, an attribute is Interpretative if different answers may be appropriate, where each different answer must be associated with its authorship. Handling this dichotomy correctly throughout the entire system is essential for geoscientists to do real work. Easy application of user preferences as to the priority sequence for retrieval of the Interpretative attributes is equally critical. Examples of Finders classification of attributes are shown in table 1.
Table 1: Classification of attributes in Finder
Invariant
Well locations Seismic locations License boundaries
Interpretative
Formation tops Horizons and faults Zone porosity
12
Revised May 2, 2005
Note:
Invariant data may actually have multiple values stored in the database for reference. For example, several different representations/sources of a well location may be modeled in the database, but only one of those variations must be selected as the official answer.
Cartographic Pipeline
Reliable and easy management of cartographic data are critical to the ease of use of spatial, mapping-oriented database systems. The concept of a cartographic pipeline is used to define a set of design rules which greatly simplify the users view and the software developers difficulty in managing cartographic projections.
Any Application
Finder Database
Figure 4: The Finder cartographic pipeline.
There are several aspects of the Finder data model and meta-data dictionary which support the implementation of this concept. As described above, the cartographic data in each Finder project must be internally consistentthe property list for the project defines the consistent cartographic representation used within the project. Geographically large projects are usually stored in spherical coordinates, while study area size projects are usually stored in the most commonly used projection. Finder always accesses cartographic data by means of the cartographic pipeline layer. Thus, whenever data flows from any application into the database or from the database to any application, the cartographic pipeline layer automatically performs a transformation if the current user preference for mapping cartography is different than the standard for the project. Since the majority of maps are displayed or plotted from study
Revised May 2, 2005
13
area databases, there is almost no overhead for cartography, because the project projection and the current mapping projection are usually the same. Note: Maps for some parts of the world are created from several projections, which does involve overhead for the cartography.
Data Stored in Operating System Files

The Finder system stores data in various types of file structures in directories on the host computer, as well as in the ORACLE relational database tables. The type and content of the host computer files depends upon the type of Finder account. For example, the Finder ESI account (System scope) is used to store and control executable versions of the Finder software and ORACLE forms provided as part of Finder and text files defining graphic symbols used by Finder. Even Finder Analyst accounts may make use of operating system files stored on the host computer for various purposes. Project accounts make use of host computer files to store scattered data files for use by gridding and contouring, project-specific ORACLE script definitions and special data structures called N-Lists. Because N-Lists are used so extensively by Finder, they are described in more detail below. The database administrator must keep in mind the fact that Finder makes extensive usage of host computer file storage, as well as the ORACLE database, in order to effectively perform the resource and security management tasks for which he or she is responsible.
The Vector or N-List Data Model

The relational data model handles discrete attribute data very well. However it handles ordered data strings or arrays, which are extremely common in exploration databases, poorly if at all. This is because the relational model is, by definition, completely insensitive to the order in which data are entered. Finder uses a special data model to store ordered data strings or arrays, for example multi-branched rivers on a map; this is the vector data or N-List data model. An N-List can be described as a linked list of arrays with headers and is flexible enough to be used with many different types of data or applications. Each N-List can have a name and can optionally contain the name of the next or previous N-List in a user-defined chain. They have one or more dimensions, each dimension being equivalent to a column described for the relational model. Statistics and null values are maintained as part of
14
Revised May 2, 2005
the header of the N-List for each dimension. Also included is a user structure in the header that allows a programmer to store important information about the N-List without having to read through all the data. They are therefore very efficient, because applications can simply check the headers and go directly to the portion of the file that contains the data of interest. The fundamental data unit of an N-List is a table. Each table contains data in each dimension as contiguous byte arrays. Each table also contains information about the next and previous tables in the sequence. Any dimension in the table can be optionally incrementing, which means that the numeric data for incrementing dimensions need not actually be stored, but can be modeled in the table header as a starting value and an increment value. Note that a constant value for every point in a table can be generated by setting the starting value to be a constant and setting the increment value to zero. Tables, too, can have optional names and user structures, similar to N-List headers and statistics are maintained for all data within each table. N-Lists can be stored in normal operating system files on the host computer. Any number of N-Lists can be contained in a single file. When an N-List is retrieved from a file, only the header data are initially retrieved. The table data are retrieved only if the actual numeric values stored in the N-List dimensions, are required. This allows the software to query the table headers to determine whether the data are actually required. The N-List files are linked to the rest of the Finder system through the relational database. Each of the various header tables related to N-List data contains a two-part pointer to the appropriate N-List in the form of the NList name and the name of the file that contains the N-List. N-List data can also be stored as Binary Large OBjects (BLOBs) inside of an Oracle database table. The advantage of storing n-List files as BLOBs in Oracle tables is that backup and restore operations are cleaner if all the files and tables are in Oracle. The disadvantage is that processing is slower and it uses a different storage allocation mechanism. For more information about storing N-List data as BLOBS, see the System Set-up and Configuration chapter of this manual. Note: Files are accessed by a network file server; N-Lists are accessed by SQL*net.
Revised May 2, 2005
15
Finder Logical Names

The Software-Operating System Interface
Finder uses the concept of a logical name in specifying operating system directory names. This means that the software uses an alias or alternate internal name for the directories accessed. The translations for these logical names are stored in the LOGICAL_NAMES table of each account and when Finder is run, the translations (directory path names) for each of the logical names for the accounts being used for the current session of Finder are read in and used for the remainder of the session for file access. This allows the system administrator or the database administrator to move a directory after creation without affecting the system. There are three places in Finder where logical names are defined. The ESI account, the current Project account and the current Analyst account. Logical names common to the entire Finder system are defined in the ESI account (whose scope is System). Logical names are defined in a set order when an analyst runs Finder. The System logical names are defined first, followed by the Project logical names and then the Analyst logical names. This order is significant because the most recent definition of a logical name is the one that is used. If the same logical name is defined for a project and for the system, the Project logical name will take precedence because it was the last defined. In the same way, logical names defined for an analyst will override any identical logical names defined for either a Project or at the System level. This allows an analyst to tailor the environment as necessary. Logical names can be managed using the Database Administration form, Finder Data Maintenance, or the Project Administration form, Logical Names. By default, there are no logical name conflicts between the System, Project and Analyst logical names; the same logical name is never defined in more than one scope. Logical names are also used for setting flags or parameters at run time that affect the users operating environment when running Finder. For example, there are a number of System scope logical names defined that are not associated with the directories described above. The following logical names reference data files used by default for various mapping functions, instead. ESI$BC_BORDER ESI$CC_NUMBER ESI$DLS_CORNERS ESI$LEASE_LEGEND
16
Revised May 2, 2005
ESI$LOGO
A summary of the directory structure for the version of Finder and the operating system you are using is included in the system administration manual for the operating system. Where the location of directories is significant to database administration, they will be referred to in the appropriate context in the chapters that follow.
Revised May 2, 2005
17
Date Formats
Introduction
In an effort to accommodate the 21st century dates: Two-digit years will be converted to four-digit years based on a default cutoff year. Date formats will default to YYYY-MM-DD
See the following sections if you want to customize the way that Finder handles date formats. Converting Two-digit Years to Four-digit Years on page 18. Setting the Default Date Format in Finder on page 20
Converting Two-digit Years to Four-digit Years

Two-digit years will be converted to four-digit years based on a default cutoff year of 20. That means that any two-digit year (YY) less than or equal to 20 is promoted to the 21st century by adding 2000+YY resulting in 20YY. Any two-digit year (YY) greater than 20 is converted to its four-digit equivalent by adding 1900+YY resulting in 19YY. You can specify a different default cutoff year within the scope of: Analyst Use the Analyst Defaults form or insert into the ANALYST_DEFAULTS table. Project Use the Project Defaults form or insert into the PROJECT_DEFAULTS table. System Use the System Defaults form or insert into the ESI.SYSTEM_DEFAULTS table.
18
Revised May 2, 2005
Using the Analyst or Projects Defaults forms

Use the Analyst Defaults form to specify your default cutoff year preference in the ANALYST scope. Use the Project Defaults form to specify your default cutoff year preference in the PROJECT scope. Use the System Defaults form to specify your default cutoff year preference in the SYSTEM scope. Notice that the values must be all uppercase.
Table 2: Default Forms Reference
Application Name
FINDER
Default Name
CUTOFF_YEAR
Default Value
2-digit integer, for example, 09 or 23
Using SQL
To set your default cutoff year preference by inserting the values directly into the tables, follow the examples below: Analyst Scope Example: This is the command you would use to set your default cutoff year preference to 23 in the ANALYST scope:
insert into <analyst>.analyst_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (CUTOFF_YEAR, 23, FINDER);
Project Scope Example: This is the command you would use to set your default cutoff year preference to 23 in the PROJECT scope:
insert into <project>.project_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (CUTOFF_YEAR, 23, FINDER);
Revised May 2, 2005
19
System Scope Example: This is the command you would use to set your default cutoff year preference to 23 in the ESI scope:
insert into esi.system_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (CUTOFF_DATE, 23, FINDER);
Setting the Default Date Format in Finder

The Oracle instance used for Finder is set up so that NLS_DATE_FORMAT in the init.ora file is set to the ISO date format YYYY-MM-DD. As a result, if the default date format is not set within one of the Finder scopes, the date format will default to the ISO date format YYYY-MM-DD. You can specify a different default date format within the scope of: Analyst Use the Analyst Defaults form or insert into the ANALYST_DEFAULTS table. Project Use the Project Defaults form or insert into the PROJECT_DEFAULTS table. System Use the System Defaults form or insert into the into the ESI.SYSTEM_DEFAULTS table.
20
Revised May 2, 2005

Use the Analyst Defaults form to specify your date format preference in the ANALYST scope. Use the Project Defaults form to specify your date format preference in the PROJECT scope. Use the System Defaults form to specify your default cutoff year preference in the SYSTEM scope. Notice that the values must be all uppercase.
Application Name
FINDER
Default Name
DISPLAY_DATE_FORMAT
Default Value
Choose one: YYYY-MM-DD YYYY-DD-MM YYYY-MON-DD YYYY-DD-MON DD-MON-YYYY MON-DD-YYYY DD-MM-YYYY MM-DD-YYYY
Using SQL
The command to use to set the view preferences by inserting the values directly into the tables is in the format:
insert into scope.scope_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (DISPLAY_DATE_FORMAT, DD-MON-YYYY, FINDER);
Analyst Scope Example: This is the command you would use set the default date format to DD-MON-YYYY in the ANALYST scope:
insert into analyst.analyst_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (DISPLAY_DATE_FORMAT, DD-MON-YYYY, FINDER);
Revised May 2, 2005
21
Project Scope Example: This is the command you would use set the default date format to DD-MON-YYYY in the PROJECT scope:
insert into project.project_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (DISPLAY_DATE_FORMAT, DD-MON-YYYY, FINDER);
System Scope Example: This is the command you would use set the default date format to DD-MON-YYYY in the ESI scope:
insert into esi.system_defaults (DEFAULT_NAME, DEFAULT_VALUE, APPLICATION_NAME) values (DISPLAY_DATE_FORMAT, DD-MON-YYYY, FINDER);
22
Revised May 2, 2005
Chapter 2: Account Management
Chapter 2
Introduction
In this chapter you will find: Security Management on page 30 - describing the various possible security options and, in general terms, how the database privileges need to be set to implement each option. Database Account Manager on page 38 - describing the use of the Database Account Manager. Account Maintenance Tools on page 64 - describing forms and reports used for account maintenance. Backing-up and Restoring Accounts on page 65 - describing how to write all of the data associated with a Finder account to one or more operating system files which can then be easily written to magnetic tape or transferred between system mass storage devices.
The database administrator must work closely with the geoscientists using Finder to ensure that the system is effectively utilized. The division of responsibilities between the system administrator, the database administrator and the users should be clearly defined, documented, and understood by all before Finder is put into use. After Finder has been installed, one of the most important tasks performed by the database administrator is the management of Finder Project and Analyst accounts.
Revised May 2, 2005
25
Account management includes: Password management Creating and dropping project and analyst accounts Creating and dropping roles Assigning object privileges to users and roles Assigning system privileges to users and roles Assigning roles to users and to other roles Validating existing accounts to propagate to them changes made to the Finder data dictionary, either by GeoQuest, during software upgrades, or by the database administrator.
All of these tasks can be performed using the Database Account Manager as described on page 38. You may want to give an analyst authority to create project and analyst accounts but no authority to connect directly to the system account, ESI. To create a new account and grant it limited database management privileges under its own name and password, use the following commands. 1. Make sure the account to which you wish to grant dba privileges has already been created. 2. Start SQL*PLus as esi.
<PROMPT>: sqlplus esi/esi
3. Grant database administration privilege to the Analyst account.

SQL> grant dba to <analyst> identified by <password>;
The selected Analyst account now has database administration privilege within Finder.
Administration of Finder accounts for Enterprise/GeoWeb

Administration and configuration of Finder accounts for use with Enterprise and GeoWeb are addressed in the Enterprise and GeoWeb documentation.
26
Revised May 2, 2005
Account Management Concepts

There are a number of aspects to ORACLE database administration that the database administrator must understand before attempting to use the various Finder account management utilities. The database administrator is encouraged to read the ORACLE8i Installation and User's Guide and ORACLE8i Distributed Database Systems.
Performance
The ORACLE relational database management system stores data which can be represented by tables in one or more database files managed by the ORACLE software. A single database can consist of more than one physical database file and can be subdivided into a number of partitions called tablespaces. Each tablespace can have one or more database files. How you set up your tablespaces for optimal performance given your hardware configuration will be an important key to keeping users happy. For performance reasons you may want to distribute the various accounts created into additional tablespaces with the database files associated with them located on different disks. For example, you might want to have a separate tablespace for each Project account so that the project databases can be taken off-line and the whole project backed up and removed from disk conveniently. Performance can be optimized even more by putting the files used for storing data, rollback segments, indexes, and temporary segments each on different disks to improve access speed. It is up to the database administrator to determine the optimum configuration for his or her installation. Some of the alternatives for managing tablespaces for different types of accounts are included in the sections of this chapter which describe account creation.
Finder Accounts
Finder accounts are simply ORACLE accounts with the tables needed to run Finder. The tables are created and seeded with default information automatically by the Finder software. Existing ORACLE accounts can be made into Finder accounts using the Finder Database Account Managers Create function. This function adds the Finder tables to that account. This chapter discusses the database administration issues of concern to the Finder database administrator. Finder accounts have a number of components in common that allow the account to be maintained properly by the Finder database maintenance utilities. These components are the tables and indexes required to control the account creation and validation process:
Revised May 2, 2005
27
ACCOUNT_TB_DEFS - The table ACCOUNT_TB_DEFS is common to all Finder project and analyst accounts. This table contains the list of tables and indexes to be created in the account and the storage parameters to be assigned to each when it is created. It also contains three special TABLE_NAME records that are used to assign tablespaces to the account. The value XXX_DEFAULT_TABLESPACE is used to assign the default tablespace for the account. The value XXX_INDEX_TABLESPACE is used to assign indexes to the specified tablespace. The value XXX_TEMPORARY_TABLESPACE is used to assign a tablespace for the account and is used by Oracle during the course of working with the database. The entries in this table are used by the validation and account creation utilities to control table creation.
ACCOUNT_TB_CNSTS - This table stores the table level check constraint definitions and the primary key definitions for the table. It also has columns named CHK_CONSTRAINT_ENABLE and PK_CONSTRAINT_ENABLE containing a value of Y or N to turn constraints on or off (the default is Y). ACCOUNT_COL_CNSTS - This table stores column level check constraint definitions. It also contains the primary key definitions of tables. The column named CHK_CONSTRAINT_ENABLE is used to turn constraints on or off. ACCOUNT_TB_FKEYS - This table stores foreign key definitions and names for tables. The column named FK_CONSTRAINT_ENABLE is used to turn constraints on or off. ACCOUNT_COL_FKEYS - This table stores the column names associated with the foreign keys defined in the ACCOUNT_TB_FKEYS table. LOGICAL_NAMES - The LOGICAL_NAMES table is used to tie the account to its associated operating system files and directories. The logical names are translated when a Finder application is run to make the assignments of the directory pathnames to the files located in the account directories.
28
Revised May 2, 2005
TEMP_TBSPACE_DEFS - This table is only used by the account creation process when the user specifies that a new tablespace is to be created. It contains the storage and file parameters for the new tablespace to be used by the automated tablespace creation utility.
All the remaining tables in an account are specific to the scope of the account being created or validated. Account tables are defined in the Finder data dictionary, and are created according to the parameters in the ACCOUNT_TB_DEFS table.
Database Security
A workable level of security must satisfy two requirements. Security must protect sensitive project data from exposure to unauthorized individuals, as well as from accidental or malicious destruction or degradation by analysts assigned to work with the data. Security must provide Finder analysts with access to all of the project data, and other Finder resources, that they need to get their work done.
The database administrator, through discussions with the exploration manager, project managers, and users, must determine what level of security is required, and establish a security system suitable for the data and user environment in which the Finder system is to be used. Finder maintains its system software and project and analyst data in both ORACLE accounts and operating system sub-directories and files. This requires that security be established in two ways. Establishing operating system account protection on directories and files. Changing passwords to provide additional security as needed. Granting or revoking privileges on ORACLE tables.
Database security is discussed more fully in Security Management on page 30.
Revised May 2, 2005
29
Security Management
Database Security Levels
The following sections describe the various possible security options and, in general terms, how the database privileges need to be set to implement each option.
Zero Security
GeoQuest does not recommend this mode of operation for production work. It may be acceptable to run in this mode during training on a noncritical database. The privilege settings for a zero security system have the following characteristics. PUBLIC is granted SELECT, INSERT, UPDATE and DELETE privileges on all ORACLE tables in all accounts. WORLD has READ, WRITE, EXECUTE, and DELETE access to all host computer project directories and files. Each Project account is also an Analyst account.
Under this scenario, the database administrator allows any analyst to perform whatever actions they wish. The benefit of this mode is that there is never any restriction on an attempted operation. This allows each analyst complete freedom to modify any table in the system, including database dictionary modification, workstation configuration, code translations, etc. This passive management style assumes that analysts always perform only correct actions. Since by definition any analyst can modify any table, it is assumed that all analysts know what they are doing, and that they realize that any errors they cause in the database are their problem. A by-product of this mode of operation is that if any data corruption occurs, it is difficult if not impossible to determine who made the change, whether maliciously or inadvertently. If analysts start seeing corrupt or suspect data in the database, faith in interpretations based on these data is reduced, and the system is not used.
30
Revised May 2, 2005
Minimal Security
The privilege settings for a minimal security system have the following characteristics. PUBLIC is granted only SELECT privileges on the tables in the CODES account. PUBLIC is granted only SELECT privileges on the tables in the ESI (System) account with the following exceptions: Analysts must have SELECT, INSERT, and UPDATE privileges on the ESI.GS_POOLMANAGER table in order to change the status of temporary projects and to run a Geoshare transfer. Analysts must have SELECT, INSERT, UPDATE and DELETE privileges on the ESI.FINDER_FORMS_SYNONYMS table in order to create an entry for current analyst and current project.
Each Project account is also an Analyst account. PUBLIC is granted SELECT, INSERT, UPDATE and DELETE privileges on all project tables. WORLD has READ, WRITE, EXECUTE, and DELETE access to all host computer project directories and files.
Under SQL, a user connected to an account can perform any action on the tables in that account. Therefore, by connecting directly to a project, any table within that Project account can be manipulated. If the passwords to all projects are available to any analyst, then this is the same as zero security with regards to project data. The fact that the ESI and CODES accounts are read-only means that the Finder environment is more secure, but the same problem with project data integrity cited in the previous section still applies. It is desirable to set up projects for easy data access during the initial data loading phase. This allows the project manager to set up and validate the project data.
Normal Security
The privilege settings for a normal security system have the following characteristics. PUBLIC is granted only SELECT privileges on the tables in the CODES account.
Revised May 2, 2005
31
PUBLIC is granted only SELECT privileges on the tables in the ESI (System) account with the following exceptions: Analysts must have SELECT, INSERT, and UPDATE privileges on the ESI.GS_POOLMANAGER table in order to change the status of temporary projects and to run a Geoshare transfer. Analysts must have SELECT, INSERT, UPDATE and DELETE privileges on the ESI.FINDER_FORMS_SYNONYMS table in order to create an entry for current analyst and current project.
PUBLIC is granted SELECT privileges on all project tables. Each project manager is granted SELECT, INSERT, UPDATE and DELETE privileges on all tables in the specific projects for which they are responsible. Each project manager may choose to grant SELECT, INSERT, and UPDATE privileges on specific tables in specific projects to allow other analysts to store interpretations in the project database. WORLD is denied access to all host computer project directories and files. GROUP has READ, WRITE, EXECUTE, and DELETE access to all host computer project directories and files.
Under this mode, all analysts can examine all projects, and are free to make maps and enter interpretations. Only designated analysts are allowed to update the primary data in given projects. This prevents novices from inadvertently deleting information, or changing raw data. Tables which should not be modified can be protected. There are privilege problems when analysts attempt to insert new information for which they have not been authorized by the project administrator. The data administrator at your site must weigh unrestricted data access and entry versus data integrity and corporate security. Remember that it takes only a few bad data entries in a table to make the entire database suspect.
Tight Security
The privilege settings for a tight security system have the following characteristics. PUBLIC is granted only SELECT privileges on the tables in the CODES account.
32
Revised May 2, 2005
PUBLIC is granted only SELECT privileges on the tables in the ESI (System) account. PUBLIC is granted no privileges on project tables. Each project manager is granted SELECT, INSERT, UPDATE and DELETE privileges on all tables in the specific projects for which they are responsible. Each project manager may choose to grant SELECT, INSERT, and UPDATE privileges on specific tables in specific projects to allow other analysts to store interpretations in the project database. WORLD is denied access to all host computer project directories and files. GROUP has rwx (read, write, execute and delete) access to all host computer project directories and files. Access control lists are further used to control privileges on specific host computer project directories and files to specific Analyst accounts.
The biggest difference between this mode and normal security is that public select access is not automatically granted to all project tables. Therefore, depending on which Analyst account is used, a different set of projects may be accessible. This may be desirable when sensitive data are being examined.
Operating System File Protections

A certain level of access to the database is required by an analyst to run Finder. But at the same time, any person who has access to the computer, through any host computer account, can also access data in any Finder analyst or project directory for which they have the required operating system privileges. If the operating system account security permits, you are able to view and possibly delete or change project data in the operating system files unless you have been denied operating system privileges to do so. It is extremely important that the installation and use of the Finder software and related utilities be planned from the beginning to minimize problems later. The basic principle is to assign all the users of a given project to the same operating system group and then, by denying world access to the project directories and files, the files are secure against casual investigation or tampering. Security is further enhanced at the operating system level by the fact that some of the data in the project directories are binary N-List files that are not directly editable or viewable. Most N-List files used by Finder are managed by the Finder File Management System, which
Revised May 2, 2005
33
assigns an arbitrary name to the actual physical file so that the name of a file cannot be used to identify sensitive data without full access from within Finder. Note: N-List can be stored in the database or on disks as BLOBs. This changes the security model and should be considered during set up.
ORACLE Database Security

Finder provides a number of tools to help the database administrator with the task of managing database security. The Database Account Manager is used to create new accounts and to grant or revoke privileges on Finder accounts. Refer to Database Account Manager on page 38 of this chapter for instructions on operating the Database Account Manager functions.
Privileges
The Finder Security form, discussed in the Customizing the Database chapter of this volume, gives you the ability to specify the default ORACLE privileges automatically granted to particular users, to roles (groups of users) or to PUBLIC (all users) when a new project is created, and when an existing project is validated. The default privileges to be granted on each Finder Project account table are stored in the FINDER_OBJECT_PRIVS table in the ESI account. After a Project account has been created or validated, you may want to use the Database Account Manager to revoke privileges on the project tables from the Analyst accounts which have no need to have access to the project tables. The access rights that can be managed using the Database Account Manager are: Object privileges to either users or roles System privileges to either users or roles Roles to either users or other roles
Roles
In ORACLE, a role is a group of privileges that can be granted to an account. This simplifies the management of privileges by allowing the granting of several privileges with a single SQL statement.
34
Revised May 2, 2005
Finder allows you to create and delete roles using the Database Account Manager. Roles may be defined on the basis of the users technical discipline or seniority. Some examples of roles are given below. Roles based on discipline or technical specialization. Geologist Geophysicist Log_Analyst Reservoir_Eng etc.
Roles based on seniority or job responsibility. Draftsperson Technician Supervisor Project_Mgr DBA etc.
Roles are useful in maintaining uniformity of privileges between accounts. When a new Analyst account is created or added to a project you may wish to grant specific privileges to that individual. You may also wish to simply grant a role to the new Analyst thus automatically granting to the new account all of the privileges assigned to that role. You may also grant roles to groups of projects and roles to roles. Example: Bob, Ted and Alice are granted the role (and privileges) of N_S_Geologist. The role N_S_Geologist is granted the role of Geologist plus other privileges. The UK_South, UK_North, Norway, Denmark, Germany and Netherlands projects are granted the role N_S_Projects.
For more information on assigning roles to an Analyst Account, see Granting and Revoking Roles on page 62 and the Analyst Account Management chapter of this volume. Figure 1 on page 36 and table 1 on page 37 summarize how the database administrator might control the security on three projects for three different types of user.
Revised May 2, 2005
35
Analyst: Hans Role: Geologist

Insert/Update All
Sele ct A ll Upd a te Geo log
Analyst: Robert Role: Technician

m ic
y
lec tS
Update Geology
Select Geology
Select Seismic
gy All olo ct le Ge Se te da Up
Se
e is
Project: Norway Sector Project: UK Sector

eo lo gy
In se rt /
Se le ct
Analyst: Judy Role: Geophysicist
Figure 1: Finder database access.
In this example, the three analysts are granted varying levels of access to the three projects. All of this control is done using SQL GRANT statements on specific groups of tables in the ORACLE database to each Analyst account as shown in table 1. The database administrator can use the Database Account Manager to create new Analyst accounts, new Roles for groups of Analyst accounts and grant privileges to each of them.
36
Revised May 2, 2005
In se r
t/U
pd
at e
ct le Se
Se
ism
ic
Select All
Project: Danish Sector
S Se ele le ct S ct G eis eo m U pd lo ic at gy e Se ism ic
ism Se
ic
Insert/Update Seismic
Select Geology
Select Seismic
Table 1: Privileges and Roles assigned to the analysts in figure 1 on page 36
Analyst/role
Hans/ geologist
Project
Norway Sector
Grant
Analyst
Privilege
Insert new data, view and modify all existing data in the project. Select and view all data in the project. Modify only his own geologic picks in the project.
Explanation
Hans is a geologist assigned to the Norwegian Sector and has full access to the data in that project. He also has the right to view any data in the neighboring UK and Danish Sector projects but to modify only his own geological picks in those projects.
UK Sector
Role
Danish Sector
Role
Select and view all data in the project. Modify only his own geologic picks in the project.
Robert/ technician
Danish Sector
Analyst
Select and view seismic data in the project. Select and view geology in the project. Modify his own geologic picks in the project.
Robert is a technician assigned to the Danish Sector. He has access to view seismic and geological data in the project but not to add or change data.
UK Sector
Analyst
Select and view seismic data in the project.
He also has access to view seismic data in the neighboring UK sector project. The database administrator has given geophysicists access to seismic data in all projects. Judy has no special privileges beyond those granted to the Geophysicist Role.
Judy/ geophysicist
UK Sector
Role
Insert new seismic data, view and modify existing seismic data in the project. Insert new seismic data, view and modify existing seismic data in the project.
Danish Sector
Role
Norway Sector
Role
Insert new seismic data, view and modify existing seismic data in the project.
Revised May 2, 2005
37
Database Account Manager

The Database Account Manager is provided to service the Finder accounts. The Database Account Manager can be accessed by any user who can run Finder. However, the database administration tasks which the user can perform depend upon the ORACLE privileges granted to the user's account. Some Database Account Manager tasks require that the user have the password to the ESI account.
Starting the Database Account Manager

To access the Database Account Manager, click Utilities >> Database Account Manager on the Finder menu. Finder displays the Database Account Manager dialog. The name of the Finder Analyst account to which you are currently connected appears in the Account Name text box. The Scope of the Finder account to which you are currently connected is displayed in the Account Type text box. If your current scope is ANALYST, you have limited privileges in the Database Account Manager dialog. If your Current Scope is SYSTEM and you have been granted DBA privileges, you have full privileges in the Database Account Manager dialog.
When you are ready to exit the Database Account Manager, click the Close button at the bottom of the dialog.
Current Account
If you know the account name and password to an Analyst or Project account, you may perform the general functions activated by the following buttons:
Connect As
Change the current account. For more information, see Connect As on page 39.
Validate
Validate the account. For more information, see Validate on page 39.
38
Revised May 2, 2005
Connect As
When you first start the Database Account Manager, you are connected to the Finder account you used when you started Finder. If you want to perform database administration functions, it is best to exit Finder and login again as the ESI account. To connect to another ANALYST account, 1. Click the Connect as button. A new login dialog is displayed. 2. In the new login dialog, enter the account name and password or click on the Externally Identified box. 3. Click OK. The scope of the account to which you are connected is shown in the Account type text box. Note: The ability to connect to another account is intended for account maintenance and must not be used in the normal course of Finder operation. If you do connect to another account, Forms and Reports may not be available. If you perform database administration functions which require connecting to a different account from your own Analyst account, you may become disconnected from your Analyst account causing problems when you try to continue running Finder. After using the Database Account Manager, you should exit Finder, by choosing Exit Finder on the Finder>>Applications menu, and re-start Finder.
Note:
Validate
You should use the Validate feature, typically, after restoring a project to validate any changes made by software upgrades or database customization since the project was last created or validated. The Finder Database Account Manager account validation procedure examines the ORACLE table definitions of the Finder account to which you are connected, and compares them to the table definitions in the Finder data dictionary in the ESI account. The validation procedure, in short, does everything the create account procedure does, except that you are not given the opportunity to change the logical names or other parameters, and it does not re-generate the forms in the account. It uses the list of tables and indexes in the ACCOUNT_TB_DEFS table to determine which tables are validated and any objects that need to be created are placed in the tablespaces indicated as the defaults for data, index, and temporary tablespaces in this table.
Revised May 2, 2005
39
It makes two passes through the connected account to perform the following functions: Verify that all tables defined in the Finder data dictionary for the scope of the connected account and listed in the account's ACCOUNT_TB_DEFS table exist. Verify that all tables and columns in the connected account are entered in the Finder data dictionary. Verify that all the indexes specified in the Finder schema and listed in the ACCOUNT_TB_DEFS table for the current scope of account have been created and if not, create them. Verify that all the views specified in the Finder schema for the current scope of account have been created and if not, create them. Verify that all sequences specified for the current scope of account are present and if not, create them. Grant all privileges specified in the Finder schema for the current scope of account on the current account.
If a table defined in the Finder data dictionary is missing from the connected account, the table is created in the connected account. If a table definition in the connected account does not match the table definition in the Finder data dictionary, the table is modified to reflect the data dictionary definition. if it is not possible for the utility to modify the table in the connected account, then a message to this effect is sent to the screen. Note: No data are modified by this utility, only table definitions. You can not harm your database by running the Database Account Manager Validate function. Missing columns are added to existing tables, and missing tables are created, but no tables or columns are removed from the connected account. No privilege grants are revoked (see Privileges on page 59).
Using the Database Account Manager Validate Function

Follow these steps to validate an account using the Database Account Manager. 1. Start Database Account Manager. For more information, see Starting the Database Account Manager on page 38. 2. Change to the account you wish to validate. See Connect As on page 39. 3. Click on Validate. A dialog is displayed that provides the interface to run schema_run_validate.
40
Revised May 2, 2005
4. Set the validation parameters. If you are familiar with the command line interface for schema_run_validate, you may want to type in the Command line text box included in the dialog. The command line text box will override any parameters set in the dialog. 5. To proceed with the validation, click the Validate button in the Validate Account dialog, Validation messages are displayed in the Validating Account dialog. Click Cancel if you do not wish to continue. 6. Verify the account validation and correct any problems. In Finders Validate Account dialog, you see messages pertaining to the validation processes. The steps that the validation process goes through are: 1. The ORACLE objects are updated. 2. The table definitions are updated. 3. The tables in the account are validated against the Finder dictionary. 4. The indexes associated with the account are created. 5. The views for the account are then created. 6. The synonyms are created. 7. The sequences are created. 8. The constraints are created. 9. If the account being validated is a Project account, the default privileges are then granted to PUBLIC. This includes users, roles, or public as defined in the schema/data dictionary. 10. Finally, the existing tables in the account are checked. If tables have been created in the account being validated that are not tables delivered as part of the Finder data dictionary, then a warning is logged. This is not an error condition, but is posted to the screen for your information.
Revised May 2, 2005
41
This completes the automated validation procedure. You may at this point want to modify the privileges granted to PUBLIC or specific analysts. You should still be connected to the Project account. The Grants utility is described in figure Account Maintenance Tools on page 64 of this chapter.
Validating Accounts Using the schema_run_validate Utility

If you wish to validate the Finder accounts from outside of Finder, you should run the schema_run_validate utility. schema_run_validate allows you to perform any or all of the account validation steps on a single account. This utility should be used after installing an update to the Finder software and after restoring the database from export backup files. It is also useful for propagating any customized tables or forms to existing accounts.
Running schema_run_validate
The schema_run_validate utility processes every table for the specified Finder account, which can take quite a while to run on an active or large database. Therefore it is recommended that it is run as a batch job. To run schema_run_validate, use the following syntax.
<PROMPT>: schema_run_validate -<options> <userid>/ <password>@<instance> [verbose] <logfile> Verbose mode displays the sytem messages to stdout and records the messages in the logfile. If you run schema_run_validate in verbose mode, you must specify a logfile. Otherwise, the logfile is optional. Table 2: Command-line options for schema_run_validate
Option
-a
Meaning
Performs all of the following operations. Typing -a is same as -cisytvgdwx.This option does not update the ACCOUNT_TB_DEFS table before performing the validation steps. This is to allow you to validate accounts created with only a sub-set of the available tables for the account. Update all constraints. Typing -c is the same as -pkr. Load initial rows from DEFAULT_PROJECT tables. Copy default information from the template Project account DEFAULT_PROJECT to the same tables in the current account, assuming it is also a project scope account.
Applicable to
All accounts
-c -d
All accounts Project scope accounts only
42
Revised May 2, 2005
Table 2: Command-line options for schema_run_validate (Continued)
Option
-f
Meaning
Force an account to be consistent with ESI in terms of constraints (primary key, foreign key, or check constraint). If a constraint definition is different than the ESI constraint definition, then the account constraint in question is dropped and a new constraint consistent with the ESI constraint is created. If this option is not specified, the account constraints are treated as a local customization and not changed and a warning is sent to the user about the constraint inconsistency.
Applicable to
All accounts
-g
Automates the granting of default privileges on the tables and views in the current account to a user or role (USER_OR_ROLE_NAME the default is PUBLIC) based on the entries in the ESI.FINDER_OBJECT_PRIVS table. Creates all kinds of indexes, including function-based indexes. The ACCOUNT_TB_DEFS table is used by schema_run_validate to determine which tables and indexes to process. This table must exist for the -i option to work. Update check constraints and default values on the tables of the current account. Updates the LOGICAL_NAMES table for the account with all available logical names in the current default project and create all the sub directories. If a new entry has been made in the DEFAULT_PROJECT.LOGICAL_NAMES table, the entry is copied to the LOGICAL_NAMES table of the account being processed, and the directory described in the LOGICAL_NAME translation is created in the account directory tree. Update the primary key constraints.on the tables of the current account. Update the foreign key (referential integrity) constraints.on the tables of the current account. Create any sequence number generators defined for the scope of the current account in the FINDER_SEQUENCES table. Sequences are generally created at the system level for such things as NODE_IDs, graphic object OBJECT_IDs and LINE_IDs, and seismic line LINE_IDs. Create tables. The ACCOUNT_TB_DEFS table is used by schema_run_validate to determine which tables and indexes to process. This table must exist for the -t option to work. If obsolete tables are found, a message is output suggesting that they may be deleted. Tables which are in the data dictionary but not included in the scope of the account being processed are reported separately.
All accounts
-i
All accounts
-k
All accounts
-l
Project scope accounts only
-p -r
All accounts All accounts
-s
All accounts
-t
All accounts
Revised May 2, 2005
43
Table 2: Command-line options for schema_run_validate (Continued)
Option
-u
Meaning
Enhance ACCOUNT_TB_DEFS, ACCOUNT_TB_CNSTS and ACCOUNT_COL_CNSTS tables with any new definitions in the current schema. (NOTE: This option will only add new entries; it will not modify any existing entries. To synchronize the project with the schema, first delete all rows in account_tb_defs using SQL*Plus. This will flush all ACCOUNT* tables (and remove all local customization). Create any views listed in the ESI.FINDER_VIEWS table for the scope of the account being validated. Views are logical tables built by using a SQL query to select the contents of existing tables. Materialized views are supported. Create database triggers on the tables of the current account.
Applicable to
All accounts
-v
All accounts
-w
All accounts
-x
Create stored procedures and packages on the tables of the current account. Create any synonyms defined for the scope of the current account in the ESI.FINDER_SYNONYMS table. Synonyms allow you to have more than one name by which to reference a given table or view. They can be used to facilitate the integration of existing ORACLE database accounts into the Finder environment without copying data between old and new tables.
All accounts
-y
All accounts
-verbose <logfile>
Output system messages to stdout and logfile. You must specify a logfile.
All accounts
Troubleshooting Account Validation

As the DBA Validate function compares the project table definitions to the Finder data dictionary, discrepancies might be identified which cannot be automatically rectified by the utility. The following conditions may require intervention by the database administrator. A column in the project table is wider than the same column defined in the ESI.FINDER_COLUMNS table. A column in a project table containing data has been assigned a different data type as the same column defined in the ESI.FINDER_COLUMNS table. The scale or precision of a column in a project table containing data is different from the scale or precision of the same column defined in the ESI.FINDER_COLUMNS table.
44
Revised May 2, 2005
A column in a project table containing data has been changed from NULL to NOT NULL and there are null values in the column.
Actions for Error Conditions

When one of the above errors is noted, the following procedure should be used to bring the offending table back into conformity: 1. Rename the project table to a temporary name using the SQL processor or SQL*Plus. Example: SQL> RENAME WELL_HDR TO OLD_WELL_HDR; 2. Rerun the Database Account Manager Validate function. This creates a new table with the correct definition. 3. Copy the data from the original table to the new table using the SQL processor or SQL*Plus. This may be a simple SQL statement if no columns have been added or deleted from the new table. Example:
SQL> INSERT INTO WELL_HDR SELECT * FROM OLD_WELL_HDR;
Or it may entail specifically naming each column to be moved. This can require a very long SQL statement. Example: SQL> INSERT INTO WELL_HDR (UWI, NAME, WELL_NO,
OPERATOR) SELECT UWI, WELL_NAME, WELL_NUMBER, OPERATOR FROM OLD_WELL_HDR;
Consult the SQL*Plus User's Guide and Reference from Oracle for more information about using this statement.
Revised May 2, 2005
45
4. Delete the old table. Example: SQL> DROP TABLE OLD_WELL_HDR;
Passwords
The Passwords tab provides the interface for you to change passwords. You must either be connected to the account whose password you wish to change, or you must be connected to an account with database administrator (DBA) privileges. Follow these steps to change account passwords. 1. Start Database Account Manager. For more information, see Starting the Database Account Manager on page 38. 2. If you want to change the password of the current account and you know the present password, go to step 3. a. If you know the present password of another account for which you want to change the password, connect to that account. For more information, see Connect As on page 39. Then go to step 3. b. If you are logged in as the ESI account and you do not know the present password of another account for which you want to change the password, then type into the Account Name text box, in the Change Password section, the name of the account for which the password is to be changed. Then go to step 3. 3. Type the new password into the Change Password text box. 4. Type the same new password into the Confirm password text box. 5. Click Change Password to change the password. Finder changes the password immediately. Note: Users and database administrators can not display a current password, but they can change known passwords as described in the steps above.
46
Revised May 2, 2005
Accounts
If your Current Account is ESI and your Current Scope is SYSTEM, the Database Account Manager dialog contains two additional functions:
Create Project
For more information, seeCreating a Project Account on page 47.

Create Analyst
For more information, seeCreating an Analyst Account on page 47. You must launch Finder as ESI to create project or analyst accounts. For example: finder esi/<password> [-proj <proj_name>] You will not be able to create new accounts if you try to connect as ESI after launching Finder.
Creating a Project Account

Creating a Project account requires numerous pieces of information about the area and the types of data to be stored in the project in order to complete the process smoothly. It is much easier to set up the project correctly initially, rather than try to add information after it has been created. You should decide how the project is to be configured beforehand with the assistance of the users and project manager in order to establish the correct default parameters for the project. Refer to the Project Account Management chapter of this volume for instructions for using the Database Account Manager dialog to create a Project account.
Creating an Analyst Account

An Analyst account must be created for anyone who wishes to run Finder. Even though this account is simpler in structure and content than a Project account, decisions such as privileges to be granted, location of operating system directories, and table spaces to be used, should be made prior to beginning the account creation process. Refer to the Analyst Account Management chapter of this volume for instructions for using the Database Account Manager dialog to create an Analyst account.
Revised May 2, 2005
47
Creating a Federation DBA Account

An account of the scope EK_FED (a Federation DBA account) is not mandatory. The EK_WAREHOUSE account can be used to perform all Enterprise DBA related tasks. Therefore, a Finder DBA may choose not to create a Federation DBA account. If a Finder DBA does choose to create a Federation DBA account, this account is created using the following procedure: 1. Start SQL PLUS as ESI:
<prompt>: sqlplus esi/<password>
2. Create an Oracle user account for the Enterprise Federation DBA:

SQL> create user <EK_FEDERATION_DBA> identified by <password>; SQL> grant connect to <EK_FEDERATION_DBA>;
3. Insert the name of the account along with the scope information in the table FINDER_ACCOUNTS:
SQL> insert into FINDER_ACCOUNTS values (upper(<EK_FEDERATION_DBA>),EK_FED,sysdate, sysdate);
4. Exit from SQL PLUS:

SQL> exit;
5. Execute the Finder Database Account Manager schema_run_validate to grant privileges to the <EK_FEDERATION_DBA> account:
<prompt>: schema_run_validate -g esi/esi
6. Execute the Finder Database Account Manager schema_run_validate to create synonyms in the <EK_FEDERATION_DBA> account for objects in the EK_WAREHOUSE account: <prompt>: schema_run_validate
<password>
-y
<EK_FEDERATION_DBA>/
48
Revised May 2, 2005
Creating a Catalog DBA Account

An account of the scope EK_CAT (a Catalog DBA account) is not mandatory. The EK_WAREHOUSE account can be used to perform all Enterprise DBA related tasks. Therefore, a Finder DBA may choose not to create a Catalog DBA account. If a Finder DBA does choose to create a Catalog DBA account, this account is created using the following procedure: 1. Start SQL PLUS as ESI:
<prompt>: sqlplus esi/<password>
2. Create an Oracle user account for the Enterprise Catalog DBA:

SQL> create user <EK_CATALOG_DBA> identified by <password>; SQL> grant connect to <EK_CATALOG_DBA>;
3. Insert the name of the account along with the scope information in the table FINDER_ACCOUNTS:
SQL> insert into FINDER_ACCOUNTS values (upper(<EK_CATALOG_DBA>),EK_CAT,sysdate,sysdate );
4. Exit from SQL PLUS:

SQL> exit;
5. Execute the Finder Database Account Manager schema_run_validate to grant privileges to the <EK_CATALOG_DBA> account:
<prompt>: schema_run_validate -g esi/<password>
6. Execute the Finder Database Account Manager schema_run_validate to create synonyms in the <EK_CATALOG_DBA> account for objects in the EK_WAREHOUSE account:
<prompt>: schema_run_validate <password>
-y
<EK_CATALOG_DBA>/
Deleting Accounts
Because deleting accounts involves deleting data, a standalone utility is provided for this function rather than automating it through the main Finder program. Before deleting a Finder account, please refer to the
Revised May 2, 2005
49
Backing-up and Restoring Accounts on page 65 of this chapter for instructions on archiving a project before deleting it. You should always make a backup of any data before deleting it.
The DB_DELETE_ACCT Utility

The DB_DELETE_ACCT utility provides an automated procedure for deleting project and Analyst accounts. It requires a Finder account having database administrator (DBA) privileges. It is recommended that you do not delete the project directories using the DB_DELETE_ACCT utility because it uses the logical name translation from the accounts LOGICAL_NAMES table to build recursive delete commands for all the directories referenced. If there is anything you want preserved in any of the referenced directories or if the translation of any of the logical names is a public or shared directory (such as the logical for your home directory as the translation for the directories referenced by your Analyst account) then data that is not related to Finder may be deleted as well. The project directories should be deleted manually. The analyst directories must not be deleted at all. For safety it is recommended that the DB_DELETE_ACCT utility never be used while logged into an operating system account with system privileges. Note: The delete account utility has the potential to delete directories completely unrelated to the account being deleted. you are strongly urged to check the translations for every directory in the account's LOGICAL_NAMES table and to click the cancel button when asked if you want to delete project directories and sub-directories if you have any question about what will be deleted. The DB_DELETE_ACCT utility performs the following functions: Drops all ORACLE tables, indexes, views, synonyms and clusters owned by the account being deleted. Deletes the ORACLE FORMS allocated to this account. Revokes connect and resource privileges from the ORACLE account. Can potentially delete all operating system files and directories, but manual deletion is recommended. Deletes the record for the account in the ESI.FINDER_ACCOUNTS table. If an Analyst account, removes the entry in the ESI.ANALYST_CONFIGURATION table.
To delete an account:
50
Revised May 2, 2005
1. Make sure you know the username and password of the account to be deleted and the password to the ESI account. 2. Start the db_delete_acct utility. 3. Enter the name and password of the account to be deleted and the password for the ESI account. 4. Confirm you want to proceed with the account deletion. 5. Choose a directory deletion option (Option c for cancel is recommended). 6. If you chose not to delete the project directories with db_delete_acct, delete the project directories manually. Do not delete the analyst directories. 7. Perform any additional deletions necessary as recommended by the program. Each of these steps is described in detail below.
DB_DELETE_ACCT Reference
1. Make sure you know the username and password of the account to be deleted and the password to the ESI account. The password is required for both these accounts because the account deletion utility connects to both at various points in the process. It connects to the account being deleted to build the SQL statements that delete the tables and other objects from the account and to look up the directory information for deleting the operating system files. 2. To start the db_delete_acct utility, type:
<PROMPT>: db_delete_acct
The program will execute and prompt you for the account names and passwords it needs. 3. Enter the name and password of the account to be deleted and the password for the ESI account.
Revised May 2, 2005
51
The following three prompt ask you for the required information. Enter the account name, password and ESI password correct for your needs and installation.
Enter Name of Finder Account to be deleted: batest Enter Passwd for BATEST Account: batest Enter Passwd for ESI Account: <password>
4. Confirm you want to proceed with the account deletion. The following prompt is displayed to give you a final chance to cancel the account deletion.
Do you really want to delete PROJECT Account BATEST ? (YES/NO): yes
52
Revised May 2, 2005
5. Choose a directory deletion option (option C is recommended). The first thing you are asked to do is verify that you want to delete the operating system directories associated with this account.
Starting Directory Deletion for PROJECT Account BATEST For each directory (Y/N/C) options are available. Choose them according to: Y: If you want to delete the directory N: If you don't want to delete the directory C: If you want to cancel the directory deletion process Delete directory '$FINDER_DATA/BATEST' ( 1 of 41) ? (Y/N/C): y Directory Deletion done for PROJECT Account BATEST
Note:
The first directory presented for deletion when deleting a project is the translation of ESI$PROJECT, the root directory for the project.
Caution: If you enter yes, you will delete everything in this directory, including all of the project sub-directories and any additional files and directories, such as raw data files, that you created under the project root directory. On UNIX systems, it even over-rides file protections if you have the privilege to do so. It is strongly recommended that you enter C for Cancel to prevent deletion of directories. Proceed with the procedure, then quit Finder and carefully delete the project directories manually. You should not delete the analyst directories if they reference SYS$LOGIN, $HOME or any other logical name or environment variable whose translation is not certain.
If you do not want the directory deletion to override the file protections for projection files, answer N to the first directory deletion, then Y to each subdirectory as you are prompted. If a protected file is present in the directory, then you will see a message similar to the one shown below:
Delete directory '$FINDER_DATA/BATEST' ( (Y/N/C): n 1 of 41) ?
Delete directory 'ESI$PROJECT/archives' ( 2 of 41) ? (Y/N/C): y Unable to delete the directory '$FINDER_DATA/BATEST/ archives': status = -50001.
Revised May 2, 2005
53
If you are unable to delete the project directories and files at this time you may do it manually using operating system commands, after execution of db_delete_acct has completed. If you are deleting a Finder Analyst account which uses the analyst's default directory to store Finder files, be sure to note the directory name in the prompt. Note: The translation of the directory names for an Analyst account created using the defaults supplied is $HOME in UNIX.
Caution: If you enter YES with this translation active, you will delete your host log in directory and all the files in it. If you see the open and closed brackets in this dialog at any time, click on the NO button unless you really want to delete the current default directory.
The above warnings are the reason we recommend the following when you create an analyst. You do create a sub-directory for the ANALYST directories and files. You do not use the SYSTEM operating system account when deleting accounts.
The potential for disaster cannot be over-emphasized! After you have canceled the directory deletion procedure, the automated procedure completes the task by dropping the ORACLE tables, views, and other objects owned by the account. A message is displayed for each object deleted. 6. If you chose not to delete the project directories with db_delete_acct, delete the project directories manually. Do not delete the analyst directories. You can use the UNIX rm command to delete the operating system directory and files for the account. Note: If you choose to delete these directories by hand, be sure that there are not any database files in the project directory tree. Projects created using the default settings will have a project tablespace database file in the db subdirectory. Removing this file with the tablespace still online can cause the database to crash and not come up again. Should this occur, copy another database file from the same instance to the location of the deleted file, start the database and take the deleted tablespace offline, then delete the database file.
54
Revised May 2, 2005
7. Perform any additional deletions necessary as recommended by the program. Project accounts may be referenced by various Analyst accounts. If these Analyst accounts were configured with the project you are deleting as the default, then you will be warned that this is the case with a message as shown below. This is so you can go in and reconfigure that analyst to a different project or remove a project specification from the analysts record in the ESI.ANALYST_CONFIGURATION table.
***************************************************** The following Analyst accounts referenced this project: BILLA
DB_DELETE_ACCT Examples
The following is an example run of db_delete_acct specifying the option to delete the directories. Note that if you indicate you want to delete the top-level directory, all the directories below it will be deleted and you will not be prompted further. Note also that this is the point at which we recommend that you enter C for cancel instead of Y to delete the directories.
<PROMPT>: db_delete_acct Enter Name of Finder Account to be deleted: batest Enter Passwd for BATEST Account: batest Enter Passwd for ESI Account: esi Do you really want to delete PROJECT Account BATEST ? (YES/NO): yes ****************************************************** Starting Directory Deletion for PROJECT Account BATEST For each directory (Y/N/C) options are available. Choose them according to: Y: If you want to delete the directory N: If you don't want to delete the directory C: If you want to cancel the directory deletion process
Delete directory '$FINDER_DATA/BATEST' (
1 of
41) ?
Revised May 2, 2005
55
(Y/N/C): y Directory Deletion done for PROJECT Account BATEST ****************************************************** Starting to drop Oracle Objects from PROJECT Account BATEST Dropping Dropping Dropping ... Dropping Dropping Dropping Dropping view 'FULL_TIE' ( 1 of 191) view 'ORACLE_APP_SELECTION' ( 2 of 191) table 'ACCOUNT_TB_DEFS' ( 3 of 191) table 'ZONE_VALUES' (188 of 191) table 'ZONE_VARIABLE_DESC' (189 of 191) synonym 'BASE_NODES' (190 of 191) table 'LOGICAL_NAMES' (191 of 191)
Oracle Objects for PROJECT Account BATEST dropped Sucessfully. ****************************************************** The following Analyst accounts referenced this project: BILLA PROJECT Account BATEST Deleted Sucessfully. ******************************************************
Roles
Creating and Dropping Roles
The database administrator can use the Privileges Management dialog to create new roles for the Finder installation and grant privileges to them. Roles are useful in maintaining uniformity of privileges among users, When a new Analyst account is created, it is granted a role and is automatically granted the appropriate privileges. Two roles are created automatically by ORACLE. DBA RESOURCE
Some roles have been created by GeoQuest and are installed with the Finder installation. Use the following procedure to create new roles, grant system and object privileges to them.
56
Revised May 2, 2005
1. In the Privileges Management dialog, click Create/Drop Role. Finder displays the Create/Drop Roles dialog. 2. Click in the Role Name text box and type the name for a role using underscores to separate words. a. To create a new role, type a new name. b. To drop a role, type an existing name. 3. Click in the Identified by text box. Then, a. to create a new role, type a password and click Create. b. to drop a role, type the password of the role you wish to drop and click Drop. If you used the correct password Finder deletes the role. 4. Repeat these steps until you have created or dropped all the necessary roles. 5. Click Done. Finder closes the Create/Drop Roles dialog and returns control to the Privileges Management dialog. In order to be useful these newly created roles must be: a. associated with Analysts accounts (users to perform the roles). See Granting and Revoking Roles on page 62 for more information. b. granted object privileges. See Granting and Revoking Object Privileges on page 60 for more information. c. granted system privileges. See Granting and Revoking System Privileges on page 61 for more information. Example: 1. Create a new role, log_trace_editor. See Creating and Dropping Roles on page 56. 2. Grant the new log_trace_editor role to the existing log_analyst and geologist roles. See Granting and Revoking Roles on page 62.
Revised May 2, 2005
57
Doing so assures that any user granted either the log_analyst role or the geologist role is automatically granted the log_trace_editor role and all of its privileges.
You have now established a hierarchical structure of users, primary and secondary roles as shown in figure 2. However, none of these users or roles have any privileges. Follow these steps to grant privileges to the roles: 3. Grant the newly created roles to Project user accounts (the dotted lines in figure 2). See Granting and Revoking Roles on page 62. 4. While connected to those projects, grant privileges to the roles.
Analysts Roles Projects
Figure 2: The hierarchical relationship between Analysts accounts, roles and Project accounts.
5. Click to display the Options menu and select Roles to users. The Privileges Management dialog displays lists of roles and users in this database. 6. Grant the newly created roles to the Project accounts in the database in which you wish these roles to have privileges. (see Granting and Revoking Roles on page 62). 7. When you have granted all needed roles to the projects in which they are needed, then click Done.
58
Revised May 2, 2005
Finder closes the Privileges Management dialog and returns control to the DBA Functions dialog. 8. Type the Account Name and Account Password of a Finder Project account into the text boxes and click Grants. Finder displays the Privileges Management dialog and, on the Options menu, the default option, Object privs. to users. 9. Click Object privs. to roles on the Options menu. Finder displays three text boxes containing lists of Object Privileges, Tables in the connected Project account and Roles which are granted to this account. Click on items to grant privileges in the Project account tables to the newly created roles (see Account Maintenance Tools on page 64). Note: Only roles which have been granted to this Project account are displayed. If you have created a new role and it is not displayed here, then you should re-connect to an account with database administrator (DBA) privileges and grant the necessary role to the desired Project account. 10. When you have granted all needed privileges to the roles, then click Done. Finder closes the Privileges Management dialog and returns control to the DBA Functions dialog.
Create/Drop Role Button

This function is only available to a user with database administrator (DBA) privileges. If you are not connected to a DBA privileged account the button is dimmed and unavailable. When you click on Create/Drop Role Finder displays the Create/Drop Roles dialog. See Creating and Dropping Roles on page 56.
Privileges
Before using the Privileges Management dialog you should be familiar with Security Management on page 30. If you are connected to an analyst account, you can use the Change grants function to: Grant object privileges to and revoke them from users. Grant object privileges to and revoke them from roles.
Revised May 2, 2005
59
See Granting and Revoking Object Privileges on page 60. If you are connected to the ESI account or and account with DBA privileges, you can also use the Change grants function to: Grant system privileges to and revoke them from users. Grant system privileges to and revoke them from roles. See Granting and Revoking System Privileges on page 61. Grant roles to and revoke them from users. Grant roles to and revoke them from other roles. See Granting and Revoking Roles on page 62. Create and drop roles. See Creating and Dropping Roles on page 56. When you want to perform any of these functions: 1. Start Database Account Manager. For more information, see Starting the Database Account Manager on page 38. 2. Click the Change grants button. The Privileges Management dialog is display. The Privileges Management dialog is described beginning on page 60.
Granting and Revoking Object Privileges

1. In the Privileges Management dialog, choose one of the following options from the Options menu button:
Object privs. to users Object privs to roles
2. Select one or more object privileges. 3. Select one or more tables. 4. Select, by clicking, all users or roles to which you wish to grant or revoke the selected privileges on the selected tables. 5. When you are satisfied with your selections of privileges, tables and users or roles, click one of these buttons to complete the process.
60
Revised May 2, 2005
a. Grant, to grant the selected privileges on the selected tables to the selected users. b. Revoke, to revoke the selected privileges on the selected tables from the selected users. 6. If you want to grant or revoke different selections of privileges to other users or roles, repeat the procedure as often as needed. 7. Click Done. Finder closes the Privileges Management dialog and returns control to the Database Account Manager dialog.
Granting and Revoking System Privileges

1. In the Privileges Management dialog, choose one of the following options from the Options menu button:
System privs. to users System privs to roles
2. Select one or more system privileges. 3. Select, by clicking, all users or roles to which you wish to grant or revoke the selected privileges. 4. When you are satisfied with your selections of privileges, and users or roles, click one of these buttons to complete the process. a. Grant, to grant the selected privileges to the selected users. b. Revoke, to revoke the selected privileges from the selected users. 5. If you want to grant or revoke different selections of privileges to other users or roles, repeat the procedure as often as needed. 6. Click Done. Finder closes the Privileges Management dialog and returns control to the Database Account Manager dialog.
Revised May 2, 2005
61
Granting and Revoking Roles

Roles are used to simplify and standardize the granting of privileges to users with different technical requirements and regional responsibilities. 1. In the Privileges Management dialog, choose one of the following options from the Options menu button:
Roles to users Roles to roles
2. Select one or more grantable roles. 3. Select, by clicking, all users or roles to which you wish to grant or revoke the selected roles. 4. When you are satisfied with your selections of grantable roles, and users or roles, click one of these buttons to complete the process. a. Grant, to grant the selected privileges to the selected users. b. Revoke, to revoke the selected privileges from the selected users. 5. If you want to grant or revoke different grantable roles to other users or roles, repeat the procedure as often as needed. 6. Click Done. Finder closes the Privileges Management dialog and returns control to the Database Account Manager dialog.
Grant Button
When you have made your selections in the list boxes, click Grant to grant the selected privileges to the selected accounts.
Revoke Button
When you have made your selections in the list boxes, click Revoke to revoke the selected privileges from the selected accounts.
62
Revised May 2, 2005
Close Button
When you have completed granting and revoking privileges, click Close. Also, if you have made selections that you do not want to apply, click Close. Finder closes the Privileges Management dialog and returns control to the Database Account Manager dialog.
Revised May 2, 2005
63
Account Maintenance Tools

There are a number of tools and scripts that the database administrator might find useful in maintaining Finder accounts. These are summarized below with reference to more complete documentation where possible.
Forms
Finder Schema Form The Finder Schema form allows a user who has system privileges to modify the Finder data dictionary. the form may also be used to change the default privileges granted to users when an account is created. Refer to the Customizing the Database chapter of this volume for instructions for using the Finder Schema form.
Reports
Finder Database Schema Report The Finder Database Schema report allows a user to obtain a listing of the Finder data dictionary. To obtain a current listing of the Finder database schema report, use the Finder Report application and choose the OTHER report type, then choose Finder database schema from the list of available reports. For more information about the Finder Report application, see the Reports section in the Applications Menu chapter of the Finder Users Reference. Schema Population Statistics Report The db_stats.sql script creates a report file which lists all of the tables in an account. For each table it lists all columns, how many rows use that column and the total number of bytes used on disk to store data in that column. These statistics are useful to determine which tables and/or columns are in use at your organization. No index statistics are included in this report. Run this report from the command line as shown below. Example: SQL> start db_stats.sql
64
Revised May 2, 2005
Backing-up and Restoring Accounts

A Finder account consists of an ORACLE database account, and the associated operating system sub-directories and files. The process of archiving a Finder account provides a way to write all of the data associated with a Finder account to one or more operating system files which can then be easily written to magnetic tape or transferred between system mass storage devices. Archiving is usually performed as a way of storing Finder account data to prevent loss due to system failure, or to put the data in a form that can be sent to and used by other Finder installations. The process of restoring a Finder account provides a way to take the archived account data stored in operating system files and use it to recreate the account for use in Finder. The archive and restore functions are performed using the ORACLE Export/Import utility and the operating system backup utility. Any Finder account, including the ESI, CODES and DEFAULT_PROJECT accounts as well as project and analyst accounts, can be archived and restored.
Archiving Finder Accounts

Archiving a Finder account refers to a process whereby all of the data associated with the account is written to an operating system directory. The archive is stored in a format that supports full restoration to this or another ORACLE instance. The archive can be used to completely restore the account at a later time at the same database. The archive can be used to add the account at a different, installation, complete with its ORACLE database and its host computer directories and files.
Archiving a Finder account might be done for any of the following reasons: Store into an operating system directory all the data associated with a Finder account. Free up space in the ORACLE database or on the host computer disks. Store old or temporary data. Move Finder account data between Finder installations. Move data from an older Finder or ORACLE database version
Revised May 2, 2005
65
to a newer version. In order to archive an account, you must have owner or database administrator (DBA) privileges on that account.
The Basic Archiving Process

The basic archiving process produces an archive that can be transported to any system and restored successfully. It is the recommended procedure for safeguarding your data. A shorter process for the temporary archiving of a project is presented later. To archive an account: 1. Change directory to the appropriate directory according to the type of account being archived. 2. Export the ORACLE database tables for the account you want to archive. This creates an operating system file containing both the ORACLE database structure and the data. 3. Copy the directories and files to tape or disk. Each of these steps is described in detail below.
66
Revised May 2, 2005
1. Change directory to the appropriate directory according to the type of account being archived. Archiving a Project account If you are archiving a Project account, change directory to the ARCHIVES subdirectory for the Project account being archived. Archiving an Analyst account If you are archiving an Analyst account, change directory to the user's home directory. Archiving the ESI, CODES and DEFAULT_PROJECT accounts If you are archiving the ESI, CODES and DEFAULT_PROJECT accounts, change directory to an appropriate directory to which you have write permissions. The ORACLE export utility creates an export file, sometimes called a dump or .DMP file. By default, the export file is written to the current directory. It is recommended that the export file for a Finder Project account be stored in the project ARCHIVES sub-directory. Be sure that your system log on account has write privileges to the current directory. Also be sure there is sufficient free space available to contain the export file. An export file can easily exceed two gigabytes in size. It is approximately the size of the tables being exported, which can be 30-50 percent of the space used in the database by the account. 2. Export the ORACLE database tables for the account you want to archive. To export a Project or Analyst account, use the ORACLE Export utility. This creates a file that contains both the structure of the data tables associated with the account, and all of the data contained in the tables. The ORACLE export and import utilities are documented in the ORACLE Utilities manual. To run the export utility, enter the following command at the operating system command line. <PROMPT>: exp <account_name>/<password> where <account_name> is the account name and <password> is the account password. Separate the account name and the password by a forward slash (/). A series of questions appears with defaults indicated in parentheses.
Revised May 2, 2005
67
You may accept all of the defaults to produce a successful export. When asked to enter the name of the export file, include the account name in the name of the export file to make it easy to recognize. It is recommended that you include in the file name the date the export file was created. In the example above, the export file has been named lc. If you do not assign a name to the export file, the export file is named expdat.dmp. When the export process has completed successfully, verify that the export file you just created is in fact located in the correct directory, as described in step 1 above. this facilitates step 3, which is to copy the files to tape or disk. c. Copy the directories and files to tape or disk. Note: It is recommended that the CODES account be backed up at the same time and kept with the project archive. For more information see Archiving ESI, CODES and DEFAULT_PROJECT Accounts on page 69.
Archiving a Project Account to Tape

You must change directory to the root directory for the project. For example, if the pathname to the project directory is /FINDER/ FINDER_PROJECT_DATA/EUREKA then you must enter:
<PROMPT>: cd /finder/finder_project_data/EUREKA
Write all the project sub-directories and files to disk or to tape. A large project may be stored on multiple disks, with links or logical names connecting the data.
Backing up an Account to Tape on a UNIX System

To back up the project directory tree on an UNIX system, mount a tape in the tape drive and use the tar command. <PROMPT>: tar cvpf /dev/<device> <directory> Example: <PROMPT>: cd /finder/finder_project_data/EUREKA <PROMPT>: tar cvpf /dev/rst0 .
68
Revised May 2, 2005
After you have completed these steps, the account is backed up onto tape, and can be restored at any time. It is good practice to include on the label affixed to the tape reel, along with the date, project name, and tape density, the total size of the project directory to assist the database administrator who restores the data in determining which disk has sufficient free space.
Archiving an Analyst Account to Tape

1. Change directory to the analyst's home directory. 2. Write all the analyst sub-directories and files to disk or to tape.
Archiving ESI, CODES and DEFAULT_PROJECT Accounts

1. Change directory to the directory which contains the export files. 2. Write all the export files to disk or to tape.
The Quick Archive Procedure

The quick archive procedure can save you time if you need to make space quickly and plan to restore the account back to the same database instance. The following must be true for this form of archiving to work effectively: The account must have all its contents in external tablespaces dedicated to this account. This would be the case if the account was created using the default settings during the account creation process. The tablespace files for the account must be in the directory tree you plan to copy to tape when you archive the project.
To archive an account using the quick option, do the following: 1. Log in to SQL*Plus using the ESI account. 2. Check the names of the tablespaces and files and identify those for the account being deleted. The following queries check the tablespace names in the current instance and those defined for a project:
SQL> SELECT TABLESPACE_NAME FROM DBA_TABLESPACES;
Revised May 2, 2005
69
SQL> SELECT TABLE_NAME, TABLESPACE_NAME FROM ACCOUNT_TB_DEFS WHERE TABLE_NAME LIKE XXX%;
Note:
The fact that a given tablespace is specified in ACCOUNT_TB_DEFS is no guarantee that the actual tables and indexes will be created in the specified tablespaces, especially if importing data from an archive. For normal projects, however, the bulk of the data should be in the specified tablespaces. 3. Alter the tablespaces offline Taking the tablespaces offline makes them inactive to the database. They can safely be temporarily removed from disk without risk to the rest of the database.
SQL> ALTER TABLESPACE <project tablespace> OFFLINE;
4. Copy the directories and database files to tape
Restoring Archived Finder Accounts

The following procedure assumes that: The account has been archived using the steps described in the Archiving Finder Accounts on page 65 of this chapter. Neither a Finder nor an ORACLE account exists on the system with the same name as the account to be restored.
The following steps outline the procedure for restoring an archived Finder account.
To Restore a Project Account

1. Login to the system as the user who has been assigned to be the project manager for the account. This user will own the directories, subdirectories and files for the account. 2. Create a root directory for the account. 3. Restore the project directory and subdirectories from tape. 4. Create the account from within ORACLE as the user ESI. 5. Import the project using the ORACLE Import utility.
70
Revised May 2, 2005
6. Start SQL*Plus as <PROJECT/PASSWORD> to drop the LOGICAL_NAMES and ACCOUNT_TB_DEFS tables. This is not always necessary, but it is a safe procedure to recreate the tables cleanly from scratch. 7. Run Finder as ESI and CREATE <PROJECT NAME> as a project. This validates the account as a Finder project. Each of the above steps are described in detail on the following pages.
Getting Started
In many ways restoring a project from archive is the same as creating a new project. A detailed plan of the system resource requirements and configuration is necessary. It is strongly recommended that the following excerpt from the Project Creation Checklist is completed before the restore process begins.
Figure 3: Project Creation Checklist.
Completion of the above checklist ensures that a workable project plan is in place. Pay particular attention to the tablespace specifications, as they are important requirements of steps 4, 5 and 7. If the original tablespace names from the archived project are available then make note of them. It is a good time to verify whether or not there is enough disk resource to meet your project plan. You should have a good estimate of the disk storage requirements for both the database and the operating system from the label on the archive tape. If the size the archive project is unknown, list out the contents of the tape and find out the original size before you begin. Remember to make any adjustment to the checklist plan before you begin the process. Refer to the Project Account Management chapter of this manual for more information regarding project creation.
Revised May 2, 2005
71
1. Log into the system as the project manager/owner account. Log into the system as the user who will be the project manager for the Finder project. Refer to the Project Account Management chapter of this volume for an explanation of the recommended design for user/project relationships. 2. Create a root directory for the account. <PROMPT>: cd $FD <PROMPT>: mkdir PFL The above commands create a top-level directory named PFL on the partition/device named /finder/ FINDER_PROJECT_DATA. It is recommended that the project root directory be a top-level directory with the same name as the project. Following this recommendation simplifies maintenance and support tasks. Note: It is important that protections on the root directory be set so that the project manager has OWNER privileges and other analysts who will use the account have GROUP privileges to the account. The easiest way to do this is to create the root directory logged on as the project manager account. If the project manager is a member of the same operating system group as the analysts who is working with the project, then the project manager will have owner privileges to the account, and the members of the same group as the project manager will have group privileges to the account.
Restore the Archived Project

1. Restore the project directory and subdirectories from tape. 2. Confirm that the project root directory was created successfully. Examples:
<PROMPT>: cd $FD/PFL <PROMPT>: pwd
You are now ready to restore the archived directories. The directories may be restored from either tape or other disks using the UNIX tar command.
72
Revised May 2, 2005
3. It is a good idea to review the contents of the archive tape before you proceed any further. Make note of the directory tree structure and the amount of disk space that will be needed. Examples:
<PROMPT>: tar tvf /dev/rst0
4. Confirm that there is sufficient space available on the disk to contain the project that you are about to restore. Example:
<PROMPT>: /bin/df ./
The following examples show the complete process required for restoring a project from tape. Example: The following example connects to the PFL directory, then places the contents of the tape in the /dev/rst0 tape drive into this directory. In some cases the archive tape may already contain the project root directory. In which case, the tar command should be launched from the $FD directory instead of the project root directory.
<PROMPT>: cd $FD/PFL <PROMPT>: mt -f /dev/rst0 <PROMPT>: tar xvpf /dev/rst0
5. Create the tablespaces from within ORACLE. Typically, each Finder project is assigned to its own set of ORACLE tablespaces. In the case of newly restored projects, it is likely that one or more new tablespaces will be required. These additional tablespaces should be created before the project's ORACLE account is created. A tablespace can be added with either the SQL create tablespace command or through the Finder project creation process with the Tablespace Allocations form. The create tablespace command is more difficult to use but, it is robust in all project restore situations. Therefore, for the purpose of restoring archived projects, the create tablespace command is the recommended method.
Revised May 2, 2005
73
For information on creating tablespaces directly from the source, refer to the ORACLE8i Administrator's Guide. a. Log into SQL*Plus as ESI.
<PROMPT>: sqlplus esi/<password>
b. Create the new tablespaces using commands similar to the following example. Example: Tablespace name: NORSEA_DEF Operating system pathname: /DATA1/FINDER/ORADB/ NORSEA_DEF.TBS File size: 25M (twenty five megabytes) SQL> create tablespace NORSEA_DEF
datafile '/data1/finder/oradb/NORSEA_DEF.DBF' size 25M default storage ( initial 10K next 50K minextents 1 maxextents 121 pctincrease 10) online;
SQL> create tablespace NORSEA_IND

datafile '/data2/finder/oradb/NORSEA_IND.DBF' size 25M default storage ( initial 10K next 50K minextents 1 maxextents 121 pctincrease 10) online;
Refer to the project creation checklist (figure 3 on page 71) that was prepared beforehand to determine the tablespace names and specifications. A tablespace should be created for each tablespace that does not already exist. Most projects will require new default and index tablespaces. The temporary tablespace is commonly shared among all projects and will normally be in existence.
74
Revised May 2, 2005
For optimum performance, the data and the index tablespaces should be larger than the export files and be located on different disks. You can set up Oracle so that it will increase the size of these data files as needed. This will prevent failures later caused by size limitations and avoids excessive waste of space. c. To review the data file of the existing tablespaces, connect to ORACLE as SYSTEM, ESI, or other DBA account and type the following command.
SQL> select * from DBA_DATA_FILES
6. Create the account from within ORACLE using a command similar to the following. Example: Account name: NORTHSEA Account password: GLENFIDDICH
SQL> create user NORTHSEA identified by GLENFIDDICH default tablespace NORSEA_DEF temporary tablespace TEMP quota unlimited on NORSEA_DEF quota unlimited on TEMP profile default;
If you already have a suitable profile set for a project, then assign the NORTHSEA project to that profile by supplying the profile name instead of default. Note: See the ORACLE8i Administrators Guide for more information on creating profiles. You may need to direct the project data into one or more EXISTING tablespaces when you import the project. If you do not actively direct the project data into a target tablespace, then import will try to first direct data into tablespaces of the same name that they were exported from, and if no such tablespace exists, it will direct the data to the SYSTEM tablespace. Indexes are treated exactly the same way as tables.
Revised May 2, 2005
75
d. To direct project data into existing tablespace, take the following steps. Decide which existing tablespace you want the data, including indexes, to reside in. Revoke resource on the system tablespace from the Project account. SQL> alter user NORTHSEA quota 0k on SYSTEM;
Caution: This is zero (0) k, not OK.

Set the default tablespace for the Project account.
ORACLE accounts may have resource privileges to several tablespaces but, each account is assigned tablespace defaults where data tables and Finders temporary tables (those which are prefixed with TEMP_) are automatically stored unless specifically instructed not to. In most cases, the tablespace defaults will need to be changed. The only exception is if the SYSTEM tablespace has been chosen for the default tablespace, the temporary tablespace or both. e. To change the tablespace defaults enter the following command. Example: SQL> alter user NORTHSEA
default tablespace NORSEA_DEF temporary tablespace TEMP;
Refer to the Account Management chapter of this volume for further discussion on the topic of tablespace allocation for projects, and to the Security: Database Access chapter of the ORACLE8i Administrators Guide for information on related SQL*Plus commands.
76
Revised May 2, 2005
7. Import the database into the new account. Now that you've created the ORACLE account for the project, you can import the database structure and data using ORACLE's import utility. This procedure is a mirror image of the EXPORT command you used to create the export file when you archived the account. The ORACLE export and import utilities are documented in the ORACLE8i Utilities manual. a. Change directory to the archives subdirectory for this project and list the archive files that are stored there. Example:
<PROMPT>: cd $FD/PFL/archives <PROMPT>: ls *.dmp
b. To initiate the ORACLE import utility, use the new account name and password and then enter the following command. Example:
<PROMPT>: IMP <project_name>/<project_password> file=export.dmp grants=N indexes=N log=<filename.txt>
The argument export.dump refers to the name you assigned to the export file during the export procedure. This command will import all data tables to the target project tablespace. The database grants and indexes will not be imported from the archived data file. Instead, they will be created anew during the project creation procedure explained on page 78. This process can take from a few minutes to over an hour, depending on the size of the database being imported and the processing resources available. 8. Use SQL*Plus as the project/password account to drop the LOGICAL_NAMES and ACCOUNT_TB_DEFS tables. This enables the creation of new clean ACCOUNT_TB_DEFS and LOGICAL_NAMES tables described on page 78, and avoids the need for clean-up by the user.
Revised May 2, 2005
77
To drop these tables enter the following commands. Example: SQL> drop table account_tb_defs; SQL> drop table logical_names;
9. Start the Database Account Manager from the Main Menu>>Utilities>>Database Account Manager. 10. Connect to an account with database administrator (DBA) privileges (see Connect As on page 39). 11. Click Create Project to start the project creation procedure. Refer to the instructions in the Project Account Management chapter of this volume for more information on creating projects. This validates the account as a Finder project and recreates the ACCOUNT_TB_DEFS and logical names tables if they are needed. Finder displays the Logical Names form. 12. Change the directory name ESI$PROJECT in the LOGICAL_NAMES table, which specifies the location of the project operating system sub-directories and files in the LOGICAL_NAMES table. The LOGICAL_NAMES table assigns logical names for the directories used for a given Finder account, to facilitate access to these directories by Finder. The form is automatically filled with default information for the project. The first line in the table is for the logical name ESI$PROJECT. This is the only entry you may need to change; however, you should review all entries, especially if the project is being restored spans several disks. The logical name translation for ESI$PROJECT should contain the pathname to the project root directory that you created in step 2 on page 70. Enter the correct pathname and then exit the Logical Names form. Finder displays the Tablespace Names and Space Allocations form. 13. Enter the tablespace names from the project creation checklist that was prepared earlier and exit the form.
78
Revised May 2, 2005
Refer to the Project Account Management chapter of this volume for more details on allocating tablespaces for Finder projects. When youve completed the Tablespace Names and Space Allocations form, the Coordinate System Manager form followed by Project Defaults form will appear. Under normal circumstances, you do not need to modify these forms. Exit the forms in succession. At the end of the Project Creation process, Finder launches schema_run_validate as a batch job. When schema_run_validate has finished, a log file is copies to the users home account labeled <account_name>.txt, which in this example would be NORTHSEA.txt. The log file should be reviewed to confirm that the job was completed successfully, then the project is ready to use.
Restoring Quick Archives

To restore archives made with the Quick Archive procedure, you need to do the following. 1. Restore the archived directories and files from tape to their original location. Note: It is critical that the original path names be preserved or ORACLE will not know how to access the database files when you bring them back on line. 2. Log into ORACLE as an account with database administrator (DBA) privileges and put the tablespace back on line. 3. Use the following SQL statement to re-activate the tablespaces from the project.
SQL> ALTER TABLESPACE <project tablespace> ONLINE;
The archived project is now available as it was before it was archived.
Revised May 2, 2005
79
80
Revised May 2, 2005
Chapter 3: Analyst Account Management
Chapter 3
Introduction
The Finder database administrator and each person who is to use Finder must have both a user account on the host computer and a Finder analyst account. It is normally the responsibility of the exploration manager or various project managers to provide the database administrator with a list of the people who are using Finder, and which analysts are authorized to work on which Finder projects. Please refer to the appropriate Finder Installation Guide for your system for instructions on how to design the analyst-project relationships to assure a trouble-free environment. As new staff are hired or reassigned, new host computer accounts may be required, or old ones may become obsolete, and the database administrator may need to enlist the assistance of the system manager to add or delete the host computer accounts. At most installations, only the system administrator has the host computer system privileges required to add or delete users. Similarly, new Finder analyst accounts must be created, and existing ones deleted. Creation or deletion of Finder Analyst accounts can only be done by someone who has Finder database administrator (DBA) privileges. When a Finder project is created, one analyst is assigned to be the project manager. The project is created under the project manager's operating system user account, making the project manager the owner of the operating system files for the project. An analyst account is a combination of ORACLE tables and host computer sub-directories and files. The analyst account ORACLE tables are designed to allow each analyst to specify individual preferences for such things as seismic map display options and the priority in which well tops are displayed on a cross section.
Revised May 2, 2005
83
Each analyst account has a unique analyst account name and password. The analyst account name is used by Finder applications to identify the analysts interpretations saved in the Finder database and control access to Finder Project accounts. For example, when an analyst saves the tops he or she has picked on a geologic cross section, the analysts account name is stored as the owner of the tops in the project WELL_SURFACE_PICK table. When the analyst wishes to post his or her tops interpretation on a map as annotation to well symbols, the analyst asks to see the tops whose OWNER is the same as the analysts account name. After a project has been created, the project manager should run the
Database Account Manager to grant and revoke privileges on the project
tables to analysts.
84
Revised May 2, 2005
Analyst Account Database Structure

When you create an Analyst account, Finder automatically creates a corresponding ORACLE account with the same account name and password. You can also use the create analyst procedure to create subdirectories in which to store operating system files that are created while the analyst is running Finder.
Finder Analyst Scope Database Tables

In addition to the bootstrap tables discussed in the Account Management Concepts section of the Accounts Management chapter of this volume, a number of additional tables are created. These are mainly used to store user preferences and temporary information needed in the course of running Finder. For a complete listing and description of the Analyst Scope tables, please refer to the Finder data dictionary or run the Finder Data Dictionary report from within Finder as described in the Applications chapter of the Finder Users Reference.
Analyst Directories
Analyst directories are the designation of two directories used for temporary files and reports. The default translation for these is the logical name or environment variable for the users operating system home directory. Note: It is strongly recommended that you change the translation of these directories to specific sub-directories under the users home directory.This reduces the danger of inadvertently deleting all the files in the users home directory if the automated account deletion utility is used to delete the account later on. There are three directories for analysts. ESI$REPORTS This is where Finder stores the temporary files generated when printing database reports from within Finder. ESI$JOURNALS This is where Finder stores log and journal files created by Finder applications. ESI$CPS3DIR This is where Finder stores files created by the CPS-3 gridding and contouring algorithms.
Revised May 2, 2005
85
Creating New Analyst Accounts

Introduction to Creating New Analyst Accounts
For all the Finder accounts there is a corresponding Oracle account as well. There are two types of Oracle accounts, one which uses database authorization where you provide an account name and a password and the other which uses Operating system authorization where the operating system is used to authorize a users access to the database. This section deals with creating the Analyst account with Database authorization. For information on how to convert this account to use OS authentication, please see Support for Operating System Authentication on page 93. The Database Account Manager utility provides automated procedures for creating Finder accounts, activated by the Create project and Create analyst buttons in the Database Account Manager dialog. The process of account creation is similar for both Analyst and Project accounts, but more information is required for creating projects. The following tasks are performed by Finder during the account creation process. Create an ORACLE account for the Analyst. Assign an Analyst Scope to the account by entering a record into the ESI.FINDER_ACCOUNTS table. Connect to the new account. Create the bootstrap tables and seed them with default data. Create the operating system directories for this account according to the specifications entered by the DBA in the Logical Names form. Create the tablespace indicated by the database administrator in the Tablespaces form, if necessary. Create all tables, views, constraints and indexes required by the new Analyst account. Grant ORACLE roles and privileges on the account tables as required.
86
Revised May 2, 2005
Briefly, the following steps are performed by the database administrator to create an Analyst account. 1. Start Finder as ESI account.
% finder esi/<password>
It is not necessary to specify a project. 2. Start the Database Account Manager from the Finder>>Utilities menu. 3. Type the new Analyst account information. 4. Choose Analyst as the type of account you wish to create. 5. Specify the locations for analyst directories. 6. Specify specify tablespaces and table storage definitions. 7. Define account level constraints if necessary. 8. Grant privileges to one or more project accounts. 9. Update the Wells.Source Search List form.
Creating New Analyst Accounts

Prerequisites
Before creating a new Analyst account, verify the following. That there is sufficient space in the ORACLE database to accommodate the new analyst tables. That there is sufficient disk space available on the host computer for the analysts current and future file storage requirements. That you know the name and password of an account with ORACLE database administrator (DBA) privileges. That the operating system account being used has sufficient privilege to create the directories required by the new Analyst account.
Revised May 2, 2005
87
You should also determine which tablespace should be used in creating the Analyst account. Since the Analyst tables are not as heavily accessed as certain Project scope tables, you might want to put all the Analyst accounts in the System tablespace or a separate Analysts tablespace to make management of these accounts more simple. By default Finder puts all new accounts in a new tablespace which is given the same name as the new account or to the tablespace name corresponding to the default name ANALYST_TBSPC as defined in ESI.SYSTEM.DEFAULTS.
Creating a New Finder Analyst Account

1. Log into the host computer. Log onto the host computer under an account which has host computer privileges to create directories at the location specified below. 2. Start Finder. Start Finder using the ESI account. If you do not know how to start Finder, see the Getting Started chapter in the Finder Users Reference. 3. Start the Database Account Manager. Click Database Account Manager on the Finder>>Utilities menu. For more detailed instructions on using the Database Account Manager, refer to the Database Account Manager section in the Account Management chapter of this volume. 4. If you are not already connected as an account with DBA privileges, you should do that now. Click the Connect As button in the Database Account Manager. 5. Click the Accounts tab. 6. Specify the new analyst account name and password. a. Type into the Account name text box the name to be used for the new Analyst account. b. Type into the Password text box the password for the new analyst account. c. Type into the Confirm password text box the same password again.
88
Revised May 2, 2005
The account name and password each must conform to the following conventions. They must use only letters and numbers. They cannot include spaces. Use the underscore (_) character to take the places of spaces between words. They must not exceed a maximum length of 30 characters.
Examples: Account Name:

SMITH ANALYST1 JOHN_JONES
Account Password:
JHWERF UKLPOI QVTHUJ
7. Click on the Create button. At this point, the automated procedure begins. As each step is performed, its name is highlighted in the list of steps in the Creating Account dialog. the ORACLE account is created the LOGICAL_NAMES table is created and seeded with default information the Logical Names form is displayed
8. In the Logical Names form, specify the locations for analyst directories. For more information, see Analyst Directories on page 85 and Logical Names form on page 90. 9. In the Tablespace Names and Space Allocations form, specify tablespaces and table storage definitions. For more information, see Tablespace Names and Space Allocations form on page 91. 10. If necessary, define new account level constraints in the Account Level constraints form. Once the tablespace has been created successfully, the Database Account Manager launches the AccountValidator to complete the generation of tables and indexes for the new account. When that finishes, the new account is ready to use. On a UNIX system, a mail message is sent to you containing a log file of the account creation. Examine the log to verify that the account was created successfully.
Revised May 2, 2005
89
11. After a new Analyst account has been created, it must be granted privileges to one or more Projects accounts using the Database Account Manager. For more information about granting privileges, see the Privileges section in the Account Management chapter of this volume. Until project privileges are granted, the Analyst account can only work on projects with privileges granted to PUBLIC. 12. After an analyst account is created, an entry is made in the SOURCE_SEARCH_LIST table with: LIST NAME = CROSS SECTION DATA CLASS = WELLS DATA SOURCE = new_analyst DATA OWNER = new_analyst DATA RANK = 1
Logical Names form

Translation column
If you want any files targeted for the analyst directories to go to a directory other than the default directory, you must to enter the complete path name for the directory in the Translation column of the form. The directories you specify are created if they do not already exist. However, the current operating system account must have sufficient privilege to create these directories. If the privilege does not exist, then this procedure will fail. It is therefore very important that, before you begin running this utility, you check that you can create the indicated directories. It is recommended that the analyst not store journals and reports file files in the home directory itself but in a set of user-created directories under the home directory so that the contents can easily be associated with Finder and so that the users home directory is not at risk of being deleted by the account deletion utility. If you choose to define logical names for the analyst directories, follow the steps below to modify the directory structure. 1. Locate in the LOGICAL_NAMES form the logical name you wish to modify. 2. Enter the actual directory specification of the target directory
90
Revised May 2, 2005
3. Change any other logical names to suit your site requirements. 4. Flag any shared directories, by entering the character Y in the Sh column of the LOGICAL_NAMES form. A shared directory is one that is shared among two or more accounts. This allows you to create central directories that contain all the scratch, report and journal files for several analysts, for example. When the directory creation routine encounters a directory flagged as shared in the Sh column, it attempts to create the directory only if it does not already exist. The account deletion utility will not delete a shared directory. 5. Click Save to commit the changes. 6. Click Exit to close the LOGICAL_NAMES form. The logical name structure is examined. Any concealed logical name is expanded and, if the directory does not exist, it is created. If a directory already exists, you still see the message that it is being created, but the procedure does not, in fact, affect the existing directory or its contents.
ENV column
Finder provides for running in a multi-platform environment. The ENV column in the LOGICAL_NAMES form indicates to which hardware platform the current record refers. This is filled in automatically along with the correct operating system specific translations according to what hardware you are using.
Tablespace Names and Space Allocations form

The Tablespace Names and Space Allocations form displays default values for the table and column level check constraints and the foreign key constraints. The parameters indicated in this form are documented in the ORACLE8i Administrator's Guide. The Tablespace Names and Space Allocations form displays the following information:
DEFAULT TABLESPACE - where the actual table data is stored. INDEX TABLESPACE - where indexes on the tables are stored.
This allows you to separate the table data from the indexes on separate disks to minimize disk access conflicts.
Revised May 2, 2005
91
TEMPORARY TABLESPACE - used by ORACLE during the
course of working with the database.

TABLE STORAGE DEFINITIONS - the storage definitions for each of the tables and indexes in the Finder data dictionary for this type of account.
Tablespace names
If you wish to use an existing tablespace, the defaults for the three tablespace name fields can be controlled using entries in the ESI.SYSTEM_DEFAULTS table. If the record which has ANALYSTS_TBSPC for the DEFAULT_NAME field is missing, then the default for all three fields on the form will be name of the analyst you are creating. Any other value entered into the DEFAULT_VALUE field for the ANALYSTS_TBSPC record will be used as the default for these three fields. Example: In this example, the ANALYSTS_TBSPC record is updated to make the default tablespace entry ANALYSTS.
SQL> UPDATE ESI.SYSTEM_DEFAULTS SET DEFAULT_VALUE = ANALYSTS WHERE DEFAULT_NAME = ANALYSTS_TBSPC;
If you wish to create a new tablespace and the pre-requisites for creating a tablespace have been met, begin by entering the name of the new tablespace in one of the fields in the upper block of the form. Regardless of the default value, you can enter new names into any or all of these fields. If you indicate that you wish to use separate tablespaces for any of the above types of data, Finder will check to see if a tablespace with the name you entered exists, and if it does not, Finder will try to create it. Note: Before you can create any additional tablespaces a secondary Rollback Segment must exist. You should be familiar with the manual process of creating tablespaces and be sure all preliminary steps have been completed before attempting to create a tablespace within Finder. Please refer to the ORACLE8i Distributed Database Systems manual for more information regarding creating tablespaces.
Space allocations
If necessary, define the tablespace storage requirements.
92
Revised May 2, 2005
The parameters in the lower Table storage definitions block control how much storage space is allocated to each table initially and how large each incremental extent is. Note that the default initial and incremental extent sizes are in bytes. If you wish you can enter sizes in megabytes by following the number with the letter M (i.e. 2M would be 2 Megabytes). The parameters indicated in this form are documented in the Oracle8i Administrator's Guide in the section on creating tablespaces. The default values included by Finder are the approximate minimum parameters for a small Finder project account. Since an analyst account generally stores very little data, it does not need its own 10 Megabyte partition. Generally it is recommended that analyst accounts simply be put into the users tablespace or that one tablespace be created to contain all of the analyst accounts. If you want to have a separate tablespace for each analyst, then you should probably reduce the size of the initial database file from 10 Megabytes to 2 or 3 Megabytes to conserve disk space as much as possible.
Support for Operating System Authentication

A user connected to an Oracle database can be authenticated by either the database or by the OS. You can choose individual accounts to be authenticated in one way or the other. Set the variable OS_AUTHENT_PREFIX in the init.ora file and use this value as a prefix to the account name. The default value of OS_AUTHENT_PREFIX is OPS$. Also, in order for the remote OS authentication to work, i.e. when using the TWO_TASK, the variable REMOTE_OS_AUTHENT should be set to true in the init.ora file. For more information, please see the Oracle8i Administrators Guide. Note: We recommend that you use NULL string for OS_AUTHENT_PREFIX. This way you can create just one account, e.g. INSTALL and you can use the same account for database as well as OS authentication as shown below. For example, if you leave the OS_AUTHENT_PREFIX to default and you want to create an account called INSTALL which can be authenticated using the OS, do the following: 1. Using Finder, create an analyst account called OPS$INSTALL as a regular Finder analyst account. 2. After you create the OPS$INSTALL account using Finder, it uses database authentication. In order to use OS authentication, issue the following SQL statement when logged in to SQLPLUS as a DBA account.
Revised May 2, 2005
93
SQL> alter user OPS$INSTALL identified externally; Now the only way to access the INSTALL account is that you log in as user INSTALL to the operating system account and connect to Oracle using / in place of user_name/passwd. e.g. you can now access Finder as follows: <PROMPT>: finder / -w color -proj eureka To switch back to database authentication, issue the following SQL statement when logged in as a DBA: SQL> alter user OPS$INSTALL identified by INSTALL_PASSWD; Now the INSTALL account can be accessed as the usual way of providing account_name/passwd without worrying about which Operating system account you are logged in as. e.g. you can now access Finder as follows: <PROMPT>: finder install/install_passwd -w color -proj eureka.
Advantages/Disadvantages of Using OS Authentication

The main advantage of using the OS authentication is that individual users do not need the password for the Oracle account. They just login to the corresponding Operating system account and use / as the Oracle account name. The main disadvantage is that the only way to access the Oracle account is to login to the OS account with the same name, thus losing the flexibility of logging to more than one account, assuming all the other accounts are created with OS authentication.
Using OS Authenticated Account

Users that are set up for OS authentication should turn on the Externally
identified button in the Login dialog.
94
Revised May 2, 2005
Chapter 4: Project Account Management
Chapter 4
Introduction
A project account is used to store all of the data associated with a particular Finder project. There can be many project accounts. The project data are stored in both the ORACLE database tables, and in a variety of operating system files contained in sub-directories under a project root directory. The database administrator manages the creation of new project accounts, archiving and restoring project accounts, and deletion of old project accounts. You must launch Finder as ESI to create a project account. Before a project account is created, 1. Determine which analyst you wish to be the project manager. 2. Create the project using the project manager's operating system user account. 3. Make the project manager the owner of the operating system files for the project. When a project is created, an ORACLE account with the project account name and password is automatically created. all of the ORACLE tables required by the project are created. a project root directory is also created on the host computer. The project root directory is normally assigned the same name as the project.
Revised May 2, 2005
97
a number of sub-directories are created that contain the project files under the project root directory. These project files contain non-ORACLE data.
After a project has been created, you should use the Database Account Manager to grant and revoke analyst privileges on the project tables.
Project Database Tables

The number and types of database tables created for a new project at a particular customer site can be altered or customized. In addition, new tables are constantly being added as new needs are identified or new functions are added to Finder. It is therefore difficult to maintain a comprehensive list of the available project database tables in this document. The Finder Data Model and Dictionary contains a listing of the database schema shipped with your release of Finder. The schema, however, may be modified on-site, so run the Finder Database Schema report to be certain that you have the most up-to-date listing for your site. You can also use SQL*Plus outside of Finder to query the System scope table FINDER_TABLES. You can also query the current schema through the HTML version of the Finder Data Dictionary. Before you perform this query, you must rebuild the HTML version to update it with the listings for your schema. For more information, see the Finder Data Model and Dictionary.
Project Operating System Directories

The project directories are created at the time the project is created. There is a root directory for each project, and below it a number of subdirectories. The root directory can be named anything, but we suggest that you use the same name as the project for easy identification. The project root directory is referenced by the logical name ESI$PROJECT. Data are stored in the project directories in a wide variety of formats including ASCII text files, N-Lists, and binary structures. After a successful project creation, the project root directory contains the sub-directories shown in table 1 on page 99.
98
Revised May 2, 2005
Table 1: Project sub-directories and logical names
Sub-directory
Archives
Contents
The destination for the project database export files created using the ORACLE export utility. This directory is used to store contour files that result from gridding and contouring operations within the Mapping application. This directory is used to store the NList files associated with graphic objects created using the Finder Mapping application, the Electronic Drafting application, the Tobin Graphic Object Loader, or the Standard Graphic Object Loader. This directory contains customized project-specific forms stored in the ORACLE Forms binary format, normally with the suffix .FMX. Store customized forms created by the database administrator which are to be available to all Finder users for a specific project in this directory. This directory is provided as a place to store customized and user-specific GPD files used to define GPD window objects such as logos and lease legends. This directory contains customized project-specific report scripts written using SQL*Plus or SQL*Reports. Store customized report scripts created by the database administrator which are to be available to all Finder users for a specific project in this directory.
Logical name
ESI$ARCHIVES
Contours
ESI$CONTOURS
Culture
ESI$CULTURE
Customized Forms
ESI$FORMS and ESI$PROJECT_CUSTOM_FORMS
Customized GPD Files
ESI$GPD and ESI$PROJECT_GPD
Customized Scripts
ESI$SCRIPTS and ESI$PROJECT_SCRIPTS
Revised May 2, 2005
99
Table 1: Project sub-directories and logical names (Continued)
Sub-directory
Customized Symbols
Contents
This directory contains customized project-specific graphic symbol definitions. Store customized graphic symbol definitions created by the database administrator which are to be available to all Finder users for a specific project in this directory. This directory contains customized project-specific reports stored in the ORACLE Forms binary format, normally with the suffix.RBX. Store customized reports created by the database administrator which are to be available to all Finder users for a specific project in this directory. This directory provides a repository for the project database files should the database administrator choose to keep a separate tablespace and database file for each project. Note: Use of this subdirectory is not recommended.
Logical name
ESI$SYMBOLS and ESI_PROJECT_SYMBOLS
Customized Reports
ESI$ORAREP2 and ESI$PROJECT_CUSTOM_ORAREP2
Database Files
ESI$FD_DB
Document Files Canadian DLS Data
This directory stores files for the loaded documents. This directory contains the compiled data for the Canadian Dominion Land Survey (DLS) land grid. This directory contains the Data Mover definition files used by the Finder Geoshare half links. This directory contains the parameter, scatter, grid and contour files used to communicate with external operations programs like the Zycor Zycntr program. These files are saved in the format native to the external operation application, not in Finder format.
ESI$DOCUMENTS ESI$DLS_GRID_COORDS
Data Mover Definitions External Parameter Files
ESI$DMD
ESI$EO_PARFILES
100
Revised May 2, 2005
Sub-directory
GPD
Contents
This directory contains the GPD files shipped with Finder which are used to define GPD window objects such as logos and lease legends. This directory is used to store the grid files generated by the gridding and contouring functions of the Mapping application. Access this directory with the logical name ESI$GRIDS. This directory contains the N-List files for log trace data. This directory contains compiled Canadian National Topographic System (NTS) land grid data. This directory is used to store plot files generated by Finder applications. This directory is used to store temporary files associated with running Finder in this project. This directory contains projectspecific ORACLE report scripts provided by GeoQuest. Note: This subdirectory exists, but is usually empty in the project tree.
Logical name
ESI$GPD and ESI$ESI_GPD
Grids
ESI$GRIDS
Logs Canadian NTS Data
ESI$LOGS ESI$NTS_GRID_COORDS.
Plots
ESI$PLOTS
Scratch
ESI$SCRATCH
Scripts
ESI$SCRIPTS and ESI$PROJECT_SCRIPTS
Seismic Faults
Used to store the N-List files containing fault information to be used in conjunction with the gridding and contouring functions. Used to store the N-Lists for the seismic line location data. Used to store the N-Lists associated with seismic line display options set using the Finder Seismic Line Editor. Used to store the N-Lists associated with seismic horizon interpretation data.
ESI$FAULT_TRACE
Seismic Headers Seismic Preferences
ESI$SEISMIC_HDR ESI$SEISMIC_PREFS
Seismic Surfaces
ESI$SEISMIC_SURFACE
Revised May 2, 2005
101
Sub-directory
Seismic 3D Surveys
Contents
This directory is used to store N-Lists containing the compiled coordinates of bin locations for mapping 3D seismic surveys. This sub-directory is used to store directional survey data. Contains the files generated by the Mapping application as input files to the gridding and contouring routines.
Logical name
ESI$SEISMIC_3D
Surveys XYZ
ESI$SURVEYS ESI$SCATTERS
102
Revised May 2, 2005
Coordinate System Transformations

Important Concepts
Most geographic coordinates within a Finder project are stored in a single coordinate system. This coordinate system is generally referred to as the project projection. Finder can convert locations between various geographic coordinate systems. The conversion is referred to as a coordinate system transformation or cartographic transformation. The geographic coordinates for most of the data loaded into a Finder project are automatically converted from the input coordinate system to the project projection or coordinate system. Similarly, when displaying or plotting a map in a projection other than the project projection, the geographic coordinate data is converted after it is retrieved from the database into the projection specified in the map definition as shown in Figure 1 below.
Finder Database
Data is stored in the projection B
Input Data
Converted to
Output Map
Converted to
Projection A Projection C Projection specified in the map definition
Projection Bthe project projection
Figure 1: Projections and transformations
Map Projections
A map projection is an orderly scheme for transforming (or mapping) between the curved surface of the earth and the flat plane of a map. All projections result in a distortion of the original surface. At any given location on the Earth, regional maps are generally produced according to some local, standard projection. This projection is chosen for its geometric characteristics and the shape of the area to be mapped.
Revised May 2, 2005
103
Projection Types
Projection type frequently refers to a general projection technique, such as Transverse Mercator. Additionally, projections are often broadly grouped by the types of distortions they attempt to prevent and the geometric means of construction. For example, some preserve angles while others preserve scale in a fixed direction. Each projection type has relative advantages and disadvantages. In particular, there are limitations as to the accuracy with which each can represent locations, distances, and angles over a given region. Be sure that you understand the properties of the projection type you choose.
Datums and Ellipsoids

Because of local variations in the Earths shape, different regions of its surface are best approximated by different ellipsoids. Further, a better approximation often requires that the ellipsoid be rotated and/or translated with respect to the Earth. A geodetic datum is defined by an ellipsoid and a set of rotations and translations. Figure 2 shows a ellipsoid that has been rotated and translated so that a portion of its surface closely approximates the surface of the Earth over an area of interest. There are many datums defined worldwide, using a variety of ellipsoids.
North Pole
Earths Axis of Revolution
Greenwich Meridian
Re g In ion te re of st
Earths Surface
Center of Ellipsoid
Earths Center
Earths Equator
Figure 2: Datum
104
Revised May 2, 2005
Coordinate System Types

There are two coordinate systems types: Geodetic and Projection. The geodetic coordinate system represents a point by latitude and longitude in angle unit (eg. degrees). The projection coordinate system represents a point by cartesian X and Y in distance unit (eg. meters). Both geodetic and projection coordinates are depend on the datum used. Therefore, it is important to know what datum (or ellipsoid) you have before you select a coordinate system.
Coordinate System Conversions

Finder uses CS-MAP (Coordinate System Mapping Library) based cartograph software to convert coordinates from one system to another. CS-MAP is third party software developed by Mentor. CS-MAP comes with dictionary (binary files) containing definitions for datums, ellipsoids and projection coordinate systems. These definitions are identified by keyname. For a given keyname, the conversion function retrieves the parameters from the binary file. CS-MAP makes datum conversions in a step-wise fashion, first converting from the source datum, then to the WGS84 datum, then finally to the target datum. Therefore, there are no theoretical limitations on pair-wise conversion. The base CS-MAP dictionary is extended by Schlumberger by adding more datums, ellipsoids, and projection coordinate systems from various products and users. The dictionary data files that come with Finder contains a rich set of pre-defined datums, ellipsoids, and projection coordinate systems.
Datum Shift
If the datum of the source coordinate system is different from the datum of the target coordinate system, datum shift will be performed automatically.
Data Model
The Finder coordinate system data model consists of: PROJECTION_HDR table - This table contains a list coordinate system used in Finder projects. This table establishes the link to PROJECTION_PARAMETERS.PROJECTION_ID and the KEYNAME in the cartograph dictionary files.
Revised May 2, 2005
105
The main attributes are listed below with their description and purpose: PROJECTION_ID - Coordinate system ID as seen and used Finder User NAME - Keyname of projection or datum or ellipsiod. It will contain the keyname that exists in the dictionary file or LOCAL for user-defined projection - Keyname type. Valid values are: DATUM, ELLIPSOID, PROJECTION. This also indicates the coordinate system type, which is: GEODETIC - if the type is DATUM or ELLIPSOID PROJECTION - if the type is PROJECTION PROJECTION_PARAMETERS table - This table is used to store the projection parameters for each projection id. For a pre-defined projection, this table contains the copy of the parameters that currently exist in the dictionary file. For a user-defined projection, this table contains user-entered parameters. Binary files - $FINDER_HOME/global_data/carto Contains datums, ellipsoids, and projection coordinate systems definitions, which are each identified by a KEYNAME.
TYPE
Configuration Rules
These rules should be followed to ensure accurate transformations. If exceptions are made to rules that indicate they must be followed, there will be portions of Finder that will fail to work properly. The result might be data corruption or just reduced functionality. There must be a projection named GEODETIC. The project projection and the projection named GEODETIC must use the same datum (and ellipsoid). It is recommended that all geodetic projections be given PROJECTION_IDs that start with GEODETIC. It is strongly recommended that there be a geodetic projection for each datum used in any projection.
106
Revised May 2, 2005
Defining a Coordinate System in a Project

Using the Coordinate System Manager, define the coordinate systems needed for the Project. 1. From the Finder Utilities menu, Select Coordinate System Manager. The Coordinate System Manager dialog appears. 2. Select the Coordinate System Type from the Coordinate System drop-down menu. There are two types of coordinate systems: Projection and Geodetic. Geodetic has two sub types, because it can be based on Datum or Ellipsoid. 3. Select datum and/or projection type in the Filter by frame. Then click Filter to narrow down the All Projections list. This only applies if the coordinate system selection is Projection. Note:
Left List below Filter by frame displays pre-defined projections. Datums or
Ellipsoids from the cartograph dictionary file. The content of this list depends on the coordinate system selected. Note:
Right List below Filter by displays the coordinate systems that are available in the project (PROJECTION_HDR).
4. Click on an item in the Left List to display its parameters in the list below. If multiple items are selected, no parameters are displayed. 5. To add a geodetic coordinate system to the project, continue with the steps in Adding a Geodetic Coordinate System to a Project on page 107. To add a projection coordinate system to the project, continue with the steps in Adding a Projection Coordinate System to a Project on page 108. To delete a coordinate system from the project, continue with the steps in Deleting a Coordinate System from a Project on page 108.
Adding a Geodetic Coordinate System to a Project

Add a Geodetic coordinate system to the project with the following steps: 1. Select Datum or Ellipsoid from Left List. 2. Press the right arrow button, to add to right list.
Revised May 2, 2005
107
3. Click on the Unique ID column of an added row and change the ID to preferred one. This goes to projection_hdr.projection_id. 4. Place the cursor in the Unit column of an added row and click the third mouse button to select a unit from the pop up menu, if required. If you did not find a unit you want in the menu, add it into the codes.UOM_CODES table. Note: Editing the Unique ID and unit is only allowed for the newly added row. Once these columns are saved you cannot edit them. 5. Click Save to save your changes to the database.
Adding a Projection Coordinate System to a Project

Add a Projection coordinate system to the project with the following steps: 1. Select one or more pre-defined projections from the Left List. 2. Press the right arrow button to add the projections to right list. 3. Click on the Unique ID column of an added row and change the ID to the preferred one. It is recommended to change this because the default value may not be meaningful. 4. Click Save to save your changes to the database. If you did not find the projection coordinate system you need in the predefined projection list, create your own using New. See Adding UserDefined Projections on page 109 for more information.
Deleting a Coordinate System from a Project

Delete a coordinate system from the project with the following steps: 1. Select one or more items from the Right List. 2. Click on the left arrow to delete from the list. 3. Click Save to save your changes to the database.
108
Revised May 2, 2005
Adding User-Defined Projections

The cartograph dictionary contains many pre-defined projection coordinate systems. A Finder user can simply select from there without entering its parameters and set up in the project. If required projection does not exist in the pre-defined list, user can define it. This is done at project level and stored in PROJECTION_PARAMETERS table. These definition are not added to dictionary. 1. From the Coordinate System Manager dialog, click New... . The User Defined Projections form appears. 2. Enter the Projection ID and Description in Projection block. 3. Select the desired Projection Type from the list of values in the Parameters block. The list contains all the supported project types. 4. Select the Projection Type Variation, if the desired projection type has variations. A list of variations appears if the projection type has variations. No list appears if the projection type does not have variations. 5. Select Datum or Ellipsoid. Datum is super set of Ellipsoid and if you select Datum, you cannot select Ellipsoid. If you do not use any Datum, leave Datum empty and select Ellipsoid. 6. Enter the applicable parameters for the selected projection type. A label below Ellipsoid displays those parameters. 7. Select the unit from the list of values. If the unit you need does not appear in the list of values, add it to codes.UOM_CODES table. 8. Click Save to add your entries to the database. 9. Click Exit to close the form and return to Coordinate System Manager dialog. The newly added projection will appear in the coordinate systems list. User-defined projection parameters can only be viewed and modified by the form. The New... button is also used to edit the user-defined projection parameters. Please note that the form queries and displays user-defined projections only.
Revised May 2, 2005
109
Adding User-Defined Datums and Ellipsoids

Cartograph Dictionary contains more than 250 datums covering the region throughout the world. Finder user can simply pick the datum name applicable to their data. However, if a datum or Ellipsoid used is not available in the pre-defined list, you can add it to the dictionary using ASCII source file provided. Refer the instruction contained in the following file
$FINDER_HOME/gloabal_data/carto_data_usage.txt
This procedure adds the user datums directly into the cartograph dictionary file. Hence the addition will be available for entire Finder installation, not specific project or instance.
110
Revised May 2, 2005
Preparing to Create Project Accounts

One of the primary responsibilities of the database administrator is working with the exploration manager or project manager to set up and maintain Finder project and analyst accounts. The Database Account Manager provides automated procedures for creating Finder accounts. The process of account creation is similar for both analyst and project accounts, but more preparation is required for creating project accounts. Before a new Project account can be created, the database administrator must perform the following steps. 1. Choose the Project Manager on page 112. 2. Verify the ORACLE Privileges on page 115. 3. Check System Resource Availability on page 115. The above steps are needed to plan the scope and use of the project and to help you gather the necessary information before it is requested of you during the process of creating a project account. Figure 3 on page 112 shows a project creation checklist. We recommend that you make a copy of this checklist and complete it for each new project. Fill in the required information as you work your way through the remainder of this section. With this checklist completed, and with the necessary system resources and privileges, you should not have any problems going through the create project process.
Revised May 2, 2005
111
Project Creation Checklist

Project account name Project root directory Security level Estimated size of project Estimated amount of database storage required for project Default tablespace Index tablespace Temporary tablespace Size if new Size if new Size if new PROJECT DEFAULTS
HORIZONTAL_UOM LOG_DEPTH_UNITS LOG_INTERVAL LOWER_LEFT_X LOWER_LEFT_Y MAP_COORDINATE_SYSTEM MAP_PROJECTION MAP_SCALE MAP_SCALE_UOM PLOTTER MKHLL_APPLICATION_1 SEISMIC_SURVEY_TYPE HILITE_SYMBOL_SIZE_2 HILITE_SYMBOL_SIZE_4 SEISMIC_SLIST_LINE_LENGTH PINCHED_POLYGON_SIZE PLOT_LAYOUT PRINCIPAL_MERIDIAN PROJECT_PROJECTION SEARCH_WINDOW ELEVATION_REFERENCE MAP_APPLICATION_1 TIME_UOM UPPER_RIGHT_X UPPER_RIGHT_Y VERTICAL_UOM PLOT_FILE_TYPE TB_BANNER HILITE_SYMBOL_SIZE_3 HILITE_SYMBOL_SIZE_5 PROJECT_NAME
Project manager Owner account Project analysis
File path name File path name File path name
Figure 3: The Project Creation Checklist
Choose the Project Manager

Project Manager Responsibilities
The project manager needs to have at least temporary access to a Finder account with ORACLE database administrator privileges during the project creation process. Such a privileged account, called ESI, is created as part of the Finder software installation. The project manager's operating
112
Revised May 2, 2005
system account needs the privileges required to create the project root directory and sub-directories. The project manager assists in collecting the following information about the project. Map projection parameters. Project default parameters. The amount of disk space required to store the project data in the ORACLE database and on the host computer. The names of other Finder analysts who will have access to the project.
Project Manager Privileges

The project manager logs on to the computer under his or her user name and password before creating the project account, and is thereby known to the system as the owner of the host computer files in the project. The project manager account must have sufficient privilege to create the project root directory. If the privilege does not exist, then this procedure will fail, and you must re-start the create project procedure. It is therefore very important that, before you create a project, you verify that the project manager user login account has privileges to create the project root directory on the disk at the location specified for ESI$PROJECT in the LOGICAL_NAMES form. Alternatively, the directory must already exist and the project manager's account must have write privileges to the directory. The Pre-installation Requirements chapter of the Finder Installation Guide, recommends that an operating system user group be created, the members of which are the project manager and all other users who are to have access to the Project account. The users who are members of the group have group privileges for the computer files in the project. With this set up, the standard computer protections are satisfactory for normal functioning of the software. Figure 4 and table 2 illustrate an example of how user groups can be designed to allow for correct functioning of the computer security facilities. .
Revised May 2, 2005
113
GROUP 1
Group Members: Susan John Phil Charles David
PROJECT PFL
Project Manager: Susan
PROJECT ROCKYCREEK
Project Manager: John
PROJECT BIGSANDY
Project Manager: Phil
Figure 4: Example of setting up a user group and several projects.
Table 2: Assignment of privileges to the group members shown in Figure 2 above
Group Name
GROUP 1
Group Members
Susan John Phil Charles David
Project Name
PFL
Project Manager
Susan
Owner Privilege
Susan
Group Privilege
John Phil Charles David
GROUP 1
ROCKYCREEK
John
John
Susan Phil Charles David
GROUP 1
BIGSANDY
Phil
Phil
Susan John Charles David
114
Revised May 2, 2005
Verify the ORACLE Privileges

The Finder system is delivered with the FINDER_OBJECT_PRIVS set to a minimum level of security, and instructions to the database administrator as to how to tighten security if required. In most cases this open access is undesirable and should be immediately changed. Refer to the Customizing the Database Tools chapter of this volume for instructions for using the Finder Database Schema form for defining the Finder ORACLE privileges which are automatically granted to PUBLIC on the project tables. The Privileges form described in the Customizing Database Tools chapter of this volume displays data stored in the FINDER_OBJECT_PRIVS table. Before you create a project, please refer to the settings in this form to verify that PUBLIC access to the project tables is set at the security level you have chosen for the project. The Account Management chapter of this volume explains how to set four different levels of security. The Finder system software installation sets the FINDER_OBJECT_PRIVS table for minimal security. If you wish to increase security on the project tables, use the Privileges form to change the settings.
Check System Resource Availability

Allocate Disk space for Project Directories
When creating a new project, you must specify the location on your computer of the project root directory, described in Project Operating System Directories on page 98. Even a fairly small project can take up 15 megabytes or more of disk space if there is a significant number of seismic locations or cultural data. Ask the Finder system administrator to specify the disk on which the new project root directory is to be created. The system administrators special knowledge of the system can ensure efficient usage of system resources and sufficient available disk space for new directories and storage of the required data. Carefully note the full path name to the location where you intend to locate the project root directory, because you will need to enter it during the project creation procedure, when you define the entry for ESI$PROJECT in the LOGICAL_NAMES table. Once you have determined where the new project root directory is located on disk, next you must ask the system administrator to provide adequate privileges to the project manager account that is the login account used to create the project. The project manager operating system account must
Revised May 2, 2005
115
have privileges to create the root directory. Alternately, the system administrator can create the directory and make the project manager's account the owner of it so there are no privilege problems. During the project creation procedure, the project directory you specify is created if it does not already exist.
Allocate Space in the ORACLE Database

ORACLE uses the concept of fixed file allocations. This means that the ORACLE system manages all tables for all projects in physical files with NO interference from the operating system. This point is important because you cannot see anything that looks like an ORACLE table using normal operating system commands. It is the responsibility of the database administrator, usually in cooperation with the system administrator, to monitor the space utilization of the system and to add additional space to the database before the need arises. Oracle allows you to set up a database file so that its size increases automatically as needed. When you create a project, the project data is by default all stored in the same system tablespace file. You should create one or more additional tablespaces for a new project, rather than use the system tablespace. The system tablespace should never be used to store non-system data. Before you can create additional tablespaces one or more secondary rollback segments must exist. You should be familiar with the manual process of creating tablespaces and rollback segments, and be sure that the required rollback segments have been created before attempting to create a tablespace as part of the project creation process within Finder. Refer to the ORACLE8i Administrators Guide for more information regarding creating tablespaces.
116
Revised May 2, 2005
Create Project Accounts

Once the necessary projections and project default information has been assembled, and the required operating system resources and privileges are made available to the project manager whose operating system user account is used to create the account, the Finder Project account creation procedure can begin. The preparations described above provide you with the information you are asked to enter when performing the create project procedure.
Overview
Creating a new Project account involves the following steps. 1. Log into the host computer under an account which has host computer privileges to create directories at the location specified below. The current operating system account must have sufficient privilege to create the project root directory. If the privilege does not exist, then this procedure will fail, and you will have to re-start the create project procedure. It is therefore very important that, before you create a project, you verify that the project manager user log in account has privileges to create the project root directory on the disk at the location specified for ESI$PROJECT in the Logical Names form. Alternatively, the directory must already exist and the project manager's account must have write privileges to the directory. 2. Start Finder using the ESI account. If you do not know how to start Finder, see the Getting Started chapter in the Finder Users Reference. 3. Start the Database Account Manager. Click Database Account Manager on the Finder >> Utilities menu. For more detailed instructions on using the Database Account Manager, refer to the Database Account Manager section in the Account Management chapter of this volume. 4. Click the Accounts tab and enter the project name in the Account name field and the password in the Password and Confirm password fields.
Revised May 2, 2005
117
The account name and password each must conform to the following conventions. They must use only letters and numbers. They cannot include spaces. Use the underscore (_) character to take the places of spaces between words. They must not exceed a maximum length of 30 characters.
5. Change the Account type to Project. 6. Click on the Create button. The following steps are performed automatically during the create account process. Grant connect and resource privileges to the new account in the ORACLE database. Assign a scope to the account. Connect to this new account. Create all tables, indexes, and views in the new account for the appropriate scope.
7. In the Logical Names form, specify the locations for project directories. For more information, see Project Operating System Directories on page 98 and Logical Names form on page 119. The default directory structure entries in this form consists of a project root directory, designated by the logical name ESI$PROJECT, and a number of sub-directories and files under that root directory. The default translation for ESI$PROJECT is $FINDER_DATA/<project name>. 8. In the Tablespace Names and Space Allocations form, specify tablespaces and table storage definitions. For more information, see Tablespace Names and Space Allocations form on page 120. 9. If necessary, define new account level constraints in the Account Level constraints form. For more information, see Defining a Coordinate System in a Project on page 107 and Define the Project Default Parameters on page 125. Once the tablespace has been created successfully, the Database Account Manager launches the AccountValidator to complete the generation of tables and indexes for the new account. When that finishes, the new account is ready to use. On a UNIX
118
Revised May 2, 2005
system, a mail message is sent to you containing a log file of the account creation. Examine the log to verify that the account was created successfully. 10. Grant or revoke privileges and roles to the required analyst accounts. The process of granting or revoking privileges on accounts is described in the Account Management chapter of this volume. Depending on the level of security desired, you may wish to grant or revoke privileges to certain accounts. If you do not need tight security and the default privileges set up during the process of creating the project are adequate for all users, then no further granting of privileges is necessary. 11. Define Project Codes and Preferences on page 135. 12. Run schema_run_validate -v to make sure all views are created. For more information on running schema_run_validate, see Running schema_run_validate on page 42 in the Account Management chapter. 13. Set the default project for the analyst. For more information, see Set the Analyst Default Project on page 133.
Logical Names form

Translation column
If you want any files targeted for the project directories to go to a directory other than the default directory, you must to enter the complete path name for the directory in the Translation column of the form. The directories you specify are created if they do not already exist. However, the current operating system account must have sufficient privilege to create these directories. If the privilege does not exist, then this procedure will fail. It is therefore very important that, before you begin running this utility, you check that you can create the indicated directories. It is recommended that the project not store journals and reports file files in the home directory itself but in a set of user-created directories under the home directory so that the contents can easily be associated with Finder and so that the users home directory is not at risk of being deleted by the project deletion utility.
Revised May 2, 2005
119
If you choose to define logical names for the project directories, follow the steps below to modify the directory structure. 1. Locate in the LOGICAL_NAMES form the logical name you wish to modify. 2. Enter the actual directory specification of the target directory 3. Change any other logical names to suit your site requirements. 4. Flag any shared directories, by entering the character Y in the Sh column of the LOGICAL_NAMES form. A shared directory is one that is shared among two or more accounts. This allows you to create central directories that contain all the scratch, report and journal files for several analysts, for example. When the directory creation routine encounters a directory flagged as shared in the Sh column, it attempts to create the directory only if it does not already exist. The account deletion utility will not delete a shared directory. 5. Click Save to commit the changes. 6. Click Exit to close the LOGICAL_NAMES form. The logical name structure is examined. Any concealed logical name is expanded and, if the directory does not exist, it is created. If a directory already exists, you still see the message that it is being created, but the procedure does not, in fact, affect the existing directory or its contents.
ENV column
Finder provides for running in a multi-platform environment. The ENV column in the LOGICAL_NAMES form indicates to which hardware platform the current record refers. This is filled in automatically along with the correct operating system specific translations according to what hardware you are using.
Tablespace Names and Space Allocations form

The Tablespace Names and Space Allocations form displays default values for the table and column level check constraints and the foreign key constraints. The parameters indicated in this form are documented in the ORACLE Administrator's Guide.
120
Revised May 2, 2005
The Tablespace Names and Space Allocations form displays the following information:
DEFAULT TABLESPACE - where the actual table data is stored. INDEX TABLESPACE - where indexes on the tables are stored
which allows you to separate the table data from the indexes on separate disks to minimize disk access conflicts.
TEMPORARY TABLESPACE - used by ORACLE during the
course of working with the database. It is recommended that the account use the system-wide temporary tablespace.
TABLE STORAGE DEFINITIONS - the storage definitions for each
of the tables and indexes in the Finder data dictionary for this type of account. The table partitioning feature is implemented in the Table Storage Definitions with the Create Partition button. See Table partitioning on page 122 for more information.
Tablespace names
If you wish to use an existing tablespace, the defaults for the three tablespace name fields can be controlled using entries in the ESI.SYSTEM_DEFAULTS table. If the record which has PROJECTS_TBSPC for the DEFAULT_NAME field is missing, then the default for all three fields on the form will be name of the project you are creating. Any other value entered into the DEFAULT_VALUE field for the PROJECTS_TBSPC record will be used as the default for these three fields. Example: In this example, the PROJECTS_TBSPC record is updated to make the default tablespace entry ALL_PROJECTS.
SQL> UPDATE ESI.SYSTEM_DEFAULTS SET DEFAULT_VALUE = ALL_PROJECTS WHERE DEFAULT_NAME = PROJECTS_TBSPC;
If you wish to create a new tablespace and the pre-requisites for creating a tablespace have been met, begin by entering the name of the new tablespace in one of the fields in the upper block of the form. Regardless of the default value, you can enter new names into any or all of these fields. If you indicate that you wish to use separate tablespaces for any of the above types of data, Finder will check to see if a tablespace with the name you entered exists, and if it does not, Finder will try to create it. Note: Before you can create any additional tablespaces a secondary Rollback Segment must exist. You should be familiar with the manual process of creating tablespaces
Revised May 2, 2005
121
and be sure all preliminary steps have been completed before attempting to create a tablespace within Finder. Please refer to the ORACLE Database Administrator's Guide for more information regarding creating tablespaces.
Space allocations
If necessary, define the tablespace storage requirements. The parameters in the lower Table storage definitions block control how much storage space is allocated to each table initially and how large each incremental extent is. Note that the default initial and incremental extent sizes are in bytes. If you wish you can enter sizes in megabytes by following the number with the letter M (i.e. 2M would be 2 Megabytes). The parameters indicated in this form are documented in the ORACLE Server Administrator's Guide in the section on creating tablespaces. Generally it is recommended that one tablespace be created to contain all of the analyst accounts.
Table partitioning
Table partitioning is supported in Finder 9.3 and later. The table partitioning feature is used when you have to support very large tables, such as found with high volume production data. It allows you to divide the tables into more manageable units - partitions. Partitions are especially useful in data warehouse applications in which large amounts of historical data are stored and analyzed. Refer to the Oracle documentation for a more comprehensive explanation of table partitioning. The following table partitioning implementation rules should be noted: The table you are partitioning must be in the PROJECT scope. The table you are partitioning must be Type Data. Tables that are defined with the TEMPORARY table type cannot be partitioned. Finders temporary tables (those which are prefixed with TEMP_) can be partitioned. All partitions of a table or index have the same logical attributes, although their physical attributes may be different. For example, all partitions in a table share the same column and constraint definitions, and all partitions in an index share the same index columns. However, storage specifications and other physical attributes such as PCTFREE, PCTUSED, INITTRANS, and MAXTRANS may vary for different partitions of the same table or index. Partitioned tables cannot have any columns with LONG or LONG RAW datatypes.
122
Revised May 2, 2005
If a table or index is partitioned on a column that has the DATE datatype and if the NLS_DATE_FORMAT does not specify the century with the year, the partition descriptions must use the TO_DATE function to specify the year completely. Otherwise you cannot create the table or index. Global indexes may not be created on partitioned tables. Bitmap indexes may be created on partitioned tables, but they must be local to the partitioned table. A single execution plan is used for all partitions of a partitioned table. Cost-based optimization is used when an SQL statement accesses partitioned tables or indexes. Rule-based optimization is not available for partitions. You must have space quota in the tablespace in which space is to be acquired if you want to use add_partition_clause, modify_partition_clause, move_partition_clause, or split_partition_clause. Duplicate partition names may be used across tables, but not within tables. The following commands are not supported in the Finder user interface and, if you are not the owner, you must have the correct privileges granted in order to perform them: drop, truncate, add, modify, move, and split.
Create partitions
If you want to create table partitions, you do so in the Tablespace Names and Space Allocations form in the Table storage definitions block. To get started, 1. In a Forms Xterm, open the ACCOUNT_TB_DEFS FORM as a project account. For example: % oform account_tb_defs <project>/<password> & 2. Select the table you want to partition. 3. If the Tablespace Name field is blank, the partition is created in the Default Tablespace. If you want to create the partition in another existing tablespace, type the name of the preferred tablespace in the Tablespace Name field. 4. Click the Create Partition button. The partition_type_form is displayed. 5. Select the partition type. Click Save, then Click Continue.
Revised May 2, 2005
123
If you choose the Range partition type, refer to "Range partitions" on page 124 for more information. If you choose the Composite partition type, refer to "Composite partitions" on page 125 for more information. If you choose the Hash partition type, refer to "Hash partitions" on page 124 for more information. 6. Enter the partition parameters as required. 7. Repeat steps 1 through 4 as required. 8. Run schema_run_validate with the -t option. The tables will be dropped and re-created with the table partition parameters.
Range partitions
The range_parameters form is displayed when you choose the Range partition type. Provide the Partition Name, Tablespace, and other parameters as necessary. The Create Subpartition button is active in the range_parameters form only when you choose to create a composite partition. You may use the ALTER TABLE MERGE PARTITIONS statement to merge the contents of two adjacent range partitions into one partition.
Hash partitions
The hash_parameters form is displayed when you choose the Hash partition type. Provide the detatils for No. of Partition or User Defined Partitions. Choose hash partitioning when: you do not know how much data will map into a given range sizes of range partitions would differ substantially partition pruning and partition-wise joins on a partitioning key are important
The concepts of splitting, dropping, and merging partitions do not apply to hash partitions. To increase the number of hash partitions, use the ALTER TABLE ADD statement. To decrease the number of hash partitions, use the ALTER TABLE COALESCE statement.
124
Revised May 2, 2005
Composite partitions
When you choose the Composite partition type, the range_parameters form is displayed. 1. Provide the Partition Name, Tablespace, and other parameters as necessary. 2. Click Save. The Create Subpartion button is enabled. 3. Click the Create Subpartition button.The subpartition_info form is displayed. 4. Enter the subpartition parameters. Click Save. 5. If you want to add another partition, click Insert and enter the next subpartition parameters. 6. When you have finished, click Save and Exit.
Define the Project Default Parameters

Using the Project Defaults form, define the project default parameters. Below is an explanation of each of the entries in the Project Defaults form. Collect this information and enter it into a copy of the Project Creation Checklist (figure 3 on page 112) so that you are prepared to make the entries as required.
Project Data Storage Parameters

PROJECT_PROJECTION - All geographic coordinates stored in the project database must be in the same cartographic projection. This project projection must be defined in the project PROJECTION_HDR table. Then the PROJECTION_ID for the project projection must be entered into the PROJECT_PROJECTION field of the PROJECT_DEFAULTS table. In many cases the PROJECT_PROJECTION is the same as the default MAP_PROJECTION. However, if you wish to store location data in geodetic coordinates (latitude and longitude), you must choose a different coordinate system for the default map projection since the geodetic system is not a true projection. The Projection Unit parameter, which must be entered when defining the project default projection, also controls the unit of measure for all horizontal coordinates stored in the database.
Revised May 2, 2005
125
Valid options are feet, meters, or decimal degrees. It is recommended that the HORIZONTAL_UOM parameter (discussed in detail below) be set equal to the Projection Unit parameter as an easily accessible reminder of the project default horizontal unit of measure, however they are not REQUIRED to be the same. Using a geodetic (latitude and longitude) coordinate system as the project projection will result in loss of performance during mapping operations because the coordinates of each data point displayed on every map must be converted to the map projection, thus slowing the map display process. It may be, however, the best choice for projects spanning large geographic areas or archival projects used as the source for many different working projects. The PROJECT_PROJECTION must not be changed once a project is created and data are loaded. Doing so will corrupt the database in so far as data loaded after the change will be in a different coordinate system than that loaded previously. LOG_DEPTH_UNITS - All log trace data digitized into the Finder database using the Finder Log Editing application or log loaders are automatically stored with depth units expressed by the LOG_DEPTH_UNITS parameter. The LOG_DEPTH_UNITS parameter can be over-ridden when the logs are loaded. The log depth unit of measure is usually feet or meters, unless otherwise specified by the log data loader DEPTH parameter. The depth unit of measure is stored in the WELL_LOG_CURVE_HDR table when a log is loaded into the database, therefore all applications which access the log data must take into account the depth unit of measure. It is recommended that the LOG_DEPTH_UNITS parameter be the same as the VERTICAL_UOM parameter, and that both parameters not be changed once a project has been created in order to minimize the possibility of inadvertently loading or using data in the wrong depth units. LOG_INTERVAL - All log trace data digitized into the database using the Finder Log Editor application is re-sampled and stored at depth intervals given by LOG_INTERVAL, expressed in a unit of measure specified by the LOG_DEPTH_UNITS parameter described above. The LOG_INTERVAL parameter can be changed at any time after a project has been created.
126
Revised May 2, 2005
An Important Note On Well Depth Unit

It is strongly recommended that the database administrator establish and communicate to all users a site specific default well depth unit of measure to help ensure consistency by specifying the depth units in which well depth data are stored (for example, measured depth to formation tops data). There is currently no mechanism in Finder to enforce this integrity. It is up to the database administrator to be sure that the well depth units are consistent regardless of the type or source of the data, or the method used to load the data into the project database.
An Important Note on Seismic Time Data

It is strongly recommended that the database administrator establish and communicate to all users a site specific default seismic time data unit of measure and seismic time type to help ensure consistency by specifying the time units in which travel time data are stored, and whether the travel time data are one-way or round-trip values. There is currently no mechanism in Finder to enforce this integrity. It is the responsibility of the database administrator to be sure that the travel time units and type that are stored with a project are consistent regardless of the type or source of the data, or the method used to load the data into the project database.
Default Map Display Parameters

The following parameters control the default display properties of new maps created in a project. All of the following parameters can be changed at any time during the life of a project, either by changing the parameters in the PROJECT_DEFAULTS table, or by interactively changing the equivalent map parameters using the Map Setup dialog. MAP_PROJECTION - This is the projection to be used as the default map projection. It may be necessary to compromise on what is considered the ideal projection for a given area in cases where the project includes areas usually described by different map projections. The MAP_PROJECTION parameter is the PROJECTION_ID of the projection. The MAP_PROJECTION parameter may be changed at any time after the project has been created. The best performance during mapping is achieved by setting the MAP_PROJECTION the same as the PROJECT_PROJECTION parameter.
Revised May 2, 2005
127
If you have set the PROJECT_PROJECTION as geodetic in order to store locations using latitude and longitude, then you must choose a different projection for the MAP_PROJECTION parameter because geodetic is an invalid choice for MAP_PROJECTION. Area of Interest - This set of parameters specify the default area of interest (extents) for maps. When a new map is created in the Finder Mapping application, the aerial extents of the map defaults to a rectangle whose lower left (southwest) and upper right (northeast) corners are defined by X-Y coordinates specified by these four parameters. LOWER_LEFT_X LOWER_LEFT_Y UPPER_RIGHT_X UPPER_RIGHT_Y
These parameters must be expressed as an X or Y coordinate in the same map projection and distance units named by the MAP_PROJECTION parameter. Thus each parameter is simply a number. If the desired default map extent information is not available at the time the project is created, these values may be modified at any time after the project is created. MAP_SCALE and MAP_SCALE_UOM - The MAP_SCALE and MAP_SCALE_UOM parameters are used to supply default values. Map scales are expressed in the number of distance units along the ground per plotter unit of distance. The MAP_SCALE parameter for the project default parameter should be expressed simply as the number of distance units per plotter unit of measure. The MAP_SCALE_UOM should consist of the distance unit of measure, a slash symbol (/) and the plotter unit of measure. For example, the following are valid pairs of values for the MAP_SCALE and MAP_SCALE_UOM parameters.
Table 3: Equivalence of Map Scales and Units of Measurement
MAP_SCALE
2000 500 1000
MAP_SCALE_UOM
FEET/INCH M/CM M/INCH
Equates to
2000 feet/inch 500 m/cm 1000 m/inch
128
Revised May 2, 2005
SEARCH_WINDOW - The search window parameter specifies how far SmartMap looks beyond the extents of a map for items which might need to be displayed on the map. There are two significant reasons for searching beyond the map extents. Objects extending into the map area - For example, SmartMap searches the database for wells with surface locations within the map area. The wellbore might extend into the map area. By specifying a SEARCH_WINDOW parameter large enough to include surface locations of deviated wells which may have been drilled beneath the map area, the map can be forced to display subsurface data points located in the map area, even if the well surface location is outside the map area. Distortions due to projection differences - When a map is made, the lower-left and upper-right corner coordinates in the map projection coordinates are transformed to project projection coordinates and these are used to search the database for candidate database objects, such as wells and seismic lines, for display. If the map projection is different from the project projection, the rectangle defined by the extents in the map projection will generally not correspond to a rectangle in the project projection. The database search will fail to find objects located in some areas of the map.
Data Search Area Based on Lower Left and Upper Right Corners
Figure 5: Search window definition (schematic).
Revised May 2, 2005
129
Specification of a search window large enough to extend the data search area can be used to ensure that all of the data which exists in the map area is included. SmartMap estimates the amount to which it should search beyond the map area by examining the coordinates of points along the edge of the map. However, the search window parameter allows further control of the searching for cases where the distortions are too great for automatic handling.
Map Area Displayed in the Map Projection
Map Area in the Default Project Projection
Data Search Area in the Default Project Projection
Data Search Area in the Map Projection
Figure 6: Importance of the search window definition (schematic).
130
Revised May 2, 2005
Search Window
Map Area and Surrounding Search Window in the Map Projection
Map Area in the Default Project Projection
Data Search Area in the Default Project Projection
Map Area and Data Search Area in the Map Projection
Figure 7: Comparison of search window and map projection definition (schematic).
PRINCIPAL_MERIDIAN - The PRINCIPAL_MERIDIAN parameter is used to provide a default value for the principal meridian parameter used when defining map corners in section-township-range coordinates. Its use is not fully implemented and its value can and should be over-ridden by entering the principal meridian as part of the section-townshiprange coordinates which must be entered into the mapping Map Setup dialog when a map is defined. If any of the State Planar coordinate systems are being used, this parameter should be set equal to minus one (-1).
Revised May 2, 2005
131
Project Default Unit of Measure Display Parameters

HORIZONTAL_UOM - Distances shown on cross sections, stratigraphic models, and other Finder horizontal displays are, by default, expressed in units specified by the HORIZONTAL_UOM parameter. The horizontal unit of measure is usually feet or meters, although other units, such as kilometers or miles can also be used. The horizontal unit of measure is also normally the unit of measure which is specified as the distance units of the PROJECT_PROJECTION. VERTICAL_UOM - All depths shown on cross sections, stratigraphic models, and other Finder displays are, by default, expressed in units given by the VERTICAL_UOM parameter. The vertical unit of measure is often the same as that specified for LOG_DEPTH_UNITS parameter. TIME_UOM - All times displayed on seismic models and timesections are expressed in units given by the TIME_UOM parameter. Valid time units are either seconds (sec) or milliseconds (ms). It is the responsibility of the database administrator to ensure that all time data is stored with the same time units since Finder does not check for internal consistency when new data is added to a project. This may not be changed after the data has been loaded to a project.
Plotting Project Default Parameters

PLOTTER - This parameter is used to define the default plotter for pre-selecting a plotter option when choosing a plotter using the Plot Manager utility. This parameter can be changed at any time to reflect your changing hardware environment. It defaults to the plotter driver CGM_CHAR. PLOT_LAYOUT - This parameter defines the name of the default plot layout to be used when maps are plotted. Any plot layout defined in the project can be used here and this parameter can be changed at any time. The default is the NA_SB_TB layout, which is normally loaded into each project when it is created. HILITE_SYMBOL_SIZE_1 through HILITE_SYMBOL_SIZE_5 These parameters define the five sizes of highlight symbol to be plotted on maps. The symbols can be set to any value which suits the needs of the user. The default values are shown in the table below.
132
Revised May 2, 2005
Table 4: Plot Highlight Symbol Size Parameters
Highlight symbol
1 2 3 4 5
Parameter
HILITE_SYMBOL_SIZE_1 HILITE_SYMBOL_SIZE_2 HILITE_SYMBOL_SIZE_3 HILITE_SYMBOL_SIZE_4 HILITE_SYMBOL_SIZE_5
Default size
0.1 inch 0.2 inch 0.4 inch 0.6 inch 0.8 inch
Set the Analyst Default Project

A default project can be associated with an analyst so that every time the analyst starts a Finder session, the project accessed is the default project. To set a default project you must insert values for the following parameters into the ANALYST_DEFAULTS table, in the ANALYST scope: DEFAULT_NAME - enter ANALYST_PROJECT DEFAULT_VALUE - enter the name of the Finder project APPLICATION_NAME - enter FINDER
You can insert these values using the Analyst Administration: Analyst Defaults form or at the command line level using SQL. To use the form: 1. Launch Finder. 2. Select Applications >> Forms >> Analyst Administration >> Analyst Defaults from the Finder menu. 3. Enter the appropriate information in the columns for Default Name, Default Value, and Application Name. To use SQL: 1. Log in as the analyst and open an Xterminal. 2. Launch SQL*Plus.
Revised May 2, 2005
133
3. Enter the following command at the SQL prompt:

SQL> insert into ANALYST_DEFAULTS values (ANALYSTS_PROJECT, FINDER,<project name>);
134
Revised May 2, 2005
Define Project Codes and Preferences

Once the project has been created, there are a number of decisions that need to be made regarding standard sets of codes for various data types. For the most part these codes are used for reference and as a means of validating data as it is loaded or entered. This information can be entered at any time, Finder runs well without it, but if it is to be used to validate data that is being entered, it is best to set them up before the data are actually loaded. The following project tables are discussed in this section. LOG_TRACE_DISPLAY_DEFAULTS table OPERATOR_ALIAS table SEIS_HOR_CODES table SEIS_FAULT_CODES
The LOG_TRACE_DISPLAY_DEFAULTS Table

Table 5: The LOG_TRACE_DISPLAY_DEFAULTS table
Field name
TRACE_TYPE TRACK_NUMBER LEFT_SCALE RIGHT_SCALE LIN_LOG_FLAG XPLOT_REVERSE_S CALE_FLAG LINE_COLOR LINE_STYLE LINE_THICKNESS SERVICE
Description
Mnemonic used for well log trace. Track number where trace belongs. Value of trace at left track margin. Value of trace at right track margin. Option to determine whether log trace is to be displayed using a logarithmic or linear scale. Value normal or reverse. Color of trace. Solid, dot-dash, etc. Fine/thin, medium/normal, bold/heavy. Name of well tool or service.
Revised May 2, 2005
135
The LOG_TRACE_DISPLAY_DEFAULTS table can be used to set up a set of project-wide log trace display defaults which is used to control log trace displays. The analyst running Finder can override these defaults as part of a geologic cross section definition. When a project is first created, there are no LOG_TRACE_DISPLAY_DEFAULTS defined. There is currently no form for entering values into the LOG_TRACE_DISPLAY_DEFAULTS table.
The OPERATOR_ALIAS Table

This table is designed to aid in ensuring consistency in the entry of well operator names into the OPERATOR field of the WELL_HDR table. It allows for the automatic conversion of an entered text string into a correct text string before the text is stored in the database. The same operator name can be, and usually is, specified in a variety of ways. For example, Houston Natural Gas and Oil Company may be indicated on well scout tickets or old database files as HNG, Hous. Nat. Gas and Oil, and HNGOC. In order to efficiently use this information in the Finder database, it is necessary to assign all of the HNG operated wells the same operator name. This can be done automatically by entering all of the variations of the HNG operator codes and their correct operator name into the OPERATOR_ALIAS table.
Table 6: The
OPERATOR_ALIAS table
Field name
ENTERED_NAME CORRECT_NAME
Description
One of the text strings used to specify the a particular operator of a well. The preferred text string used to specify the operator of same well.
To enter data into the OPERATOR_ALIAS table, select Applications >> Forms on the Finder menu and select the Operator Aliases form from the Project Administration form list (figure 8 on page 137). Enter the Entered name and Correct name, and commit the entry for each operator alias name to be entered into the OPERATOR_ALIAS table.
136
Revised May 2, 2005
Figure 8: The Operator Aliases form.
SEIS_HOR_CODES/SEIS_FAULT_CODES Tables
These tables contain all of the seismic horizon code names which have been authorized for use on this project. The purpose of the SEIS_HOR_CODES table is to provide an official set of horizon codes with clearly defined meanings so that all of the analysts working on a project can use the same codes to refer to the same horizons while performing interpretation, mapping, or other Finder applications. The purpose of the SEIS_FAULT_CODES table is to provide an official set of fault codes with clearly defined meanings so that all of the analysts working on a project can use the same codes to refer to the same faults while performing interpretation, mapping, or other Finder applications. The SEIS_HOR_CODES and SEIS_FAULT_CODES tables are described fully in the Finder Data Model and Dictionary volume of the documentation. There is currently no form for entering values into either the SEIS_HOR_CODES or the SEIS_FAULT_CODES table.
Revised May 2, 2005
137
138
Revised May 2, 2005
Chapter 5: Customizing the Database
Chapter 5
Introduction
The Finder database administrator is usually responsible for both database management and for customization of the database to meet the specific needs of his installation. You may want to familiarize yourself with the Account Management chapter of this volume before continuing with this chapter. Database customization duties include creation and/or modification of site-specific or project-specific tables, views, and indexes, and providing the users with convenient means to display, add, or modify data in the new or modified tables. Finder provides a basic set of project account database tables, views, and indexes when it is installed at a customer site to allow you to quickly start working with your data. The database administrator can, at any time, modify the project database by adding new data tables and columns, or by modifying those provided by Finder. Finder provides database customization tools. Create, delete, or modify any Finder table, view, or index in any Finder ORACLE account. Create, delete, or modify ORACLE scripts designed to display or print out reports containing information in any Finder database table in any account. Create, delete, or modify ORACLE forms designed to add, modify, or display information in any Finder database table in any account. Create, delete, or modify any Finder graphic symbol.
Revised May 2, 2005
141
Although any item in the Finder database dictionaries can, in theory, be modified by the database administrator, in practice database table or view customization usually is limited to Finder Project scope accounts, and to a lesser extent to tables in the CODE scope account. Changes made to the Finder System scope account database should be discussed with GeoQuest before the changes are made in order to insure that the changes do not adversely affect Finder functionality or database integrity, and to prevent the changes from being lost during the next update or installation of the Finder software. There are two basically different methods for adding to or modifying the Finder project ORACLE database tables: Project-specific Database Changes on page 144 - where the changes are limited to a particular project. Site-specific Database Changes on page 155 - in which case the changes can easily be made available to all projects.
Data Model Components

The Finder meta-data dictionary is a set of tables that contains the data used to generate the standard schemas in Finder. The Entity-Relationship (E-R) diagram for the Finder meta-data dictionary is shown in the Finder Data Model and Dictionary volume. You may want to refer to it during the discussion that follows.
Finder Meta-data Dictionary

Since Finder 7.0, the FINDER_TABLES table is no longer the top level driving table of the model. Because tables of the same name may appear in different scopes of account, and because each will have the same constraints, the FINDER_TABLE_CNSTS table has become the root table. On the E-R diagram, the FINDER_TABLE_CNSTS table is in the upper center portion of the diagram. The entities that surround it are the core tables most of which have always been part of the Finder meta-data dictionary. When Finder is first installed, tables are created in the ESI account, filled with the Finder database schema, and are subsequently used as a basis for creating analyst and project scope accounts. The database administrator may wish to modify existing project account tables and/or add new ones in order to accommodate additional or new data items. It is up to the database administrator, working with the project analysts, to determine what new database tables, reports, or forms are required for a specific project or for all projects. This process of adapting the Finder
142
Revised May 2, 2005
database to your specific requirements is referred to as customization. Although it is possible, GeoQuest does not recommend altering any column in a table delivered as part of the Finder product without contacting them first. Such changes may be lost when the Finder software is updated. The results of database customization can be made available for use either by all projects at a particular site (site-specific), or for use by specific projects only (project-specific). In either case, the customized database tables, reports, forms, and select phrases must be stored in such a manner that they are not affected by subsequent installations or upgrades of the Finder software. You may also wish to customize select phrases, reports, forms, and document storage to access additional data items, or to access the same data in a different manner. You can find more information about customizing these tools in the Customizing Database Tools chapter of this volume.
The Finder Database Schema Report

You may use the Finder Database Schema report to produce a listing of all of the Finder ORACLE tables, along with their column specifications, indexes, and data domains, associated with the Finder database at the time the report is generated. This is a valuable reference listing to keep on hand. To be sure you have a listing that reflects the current state of the database, you should always have a current listing available. To obtain a current listing of the Finder Database Schema report, use the Finder Report application and choose the OTHER report type, then choose Finder database schema from the list of available reports. For more information about the Finder Report application, see the Reports section in the Applications Menu chapter of the Finder Users Reference. Note: A web-based browser is also available for viewing parts of the schema. Many of the schema components are linked, facilitating the ability to follow foreign key relationships.
Revised May 2, 2005
143
Project-specific Database Changes

In making any database changes, it is usually best to start out making and testing the new table and supporting scripts and forms as project-specific changes before propagating them to all accounts. You may make projectspecific changes to a project account ORACLE database table by running SQL in the target account. You can add, modify, delete table definitions, views, indexes, database constraints and so on. The changes are limited to, and automatically applied to, the ORACLE account in which you were running when you made the changes. The changes are not automatically included in new projects when they are created, nor are the changes automatically propagated to existing projects. You may make changes to the Finder database for one or more specific projects without changing the Finder data dictionary tables. The changes you make are limited to the particular project and cannot be automatically used to modify other existing projects, or to propagate the changes to projects created in the future. In addition, there is no provision to automatically index new table columns on the basis of their data domain. The concept of data domains is limited to tables described in the Finder data dictionary, and since data domains are required to identify the data type of a table, it is not possible to make select lists directly using project-specific tables (although it can be done using a subquery retrieving from the WELL_HDR table, for example). Lastly, if it is anticipated that the table will be large and used frequently for retrievals, you must manually index the new columns to insure good performance.
Tables
Start SQL*PLUS in the project account and use one or more of the following standard SQL*PLUS commands to create new tables, or to add or change columns in existing tables. CREATE TABLE creates a new table and permits you to define its contents. Example:
SQL> CREATE TABLE MY_NEW_TABLE (COLUMN1 VARCHAR2(20) NOT NULL,COLUMN2 NUMBER(15,6) NOT NULL,COLUMN3 DATE NULL, COLUMN4 VARCHAR2(240) NULL);
ALTER TABLE permits you to enlarge the width of an existing column in an existing table, or add a new column. It also permits you to add or modify table constraints.
144
Revised May 2, 2005
Example:
SQL> ALTER TABLE WELL_HDR MODIFY (OPERATOR VARCHAR2(60) NULL);
SQL> ALTER TABLE WELL_HDR ADD (NEW_COLUMN VARCHAR2(60) NULL);
Adding columns to a Finder base table is not recommended. It is more effective to define a second custom table to hold the additional data and link this table back to the original base table via a foreign key.
Indexes
If you intend to store and retrieve a large number of records in the new table, it is recommended that you manually index the columns most likely be used as the basis for retrieving the data. Indexes are created using the CREATE INDEX command. Example:
SQL> CREATE UNIQUE INDEX MY_NEW_TABLE_UNIQUE ON MY_NEW_TABLE(COLUMN1,COLUMN2);
SQL> CREATE INDEX MY_NEW_TABLE_C4 ON MY_NEW_TABLE(COLUMN4);
Non-unique indexes are used to improve performance. If a query is not performing well, consider changing the indexing strategy you are using. If joins are involved, make sure all columns participating in the join are indexed. For more information on using the CREATE INDEX or DROP INDEX commands to add or delete indexes on one or more columns in a table, see the PL/SQL Users Guide and Reference.
Views
A view is a window on a portion of one or more tables in the database. Any listing of data that can be produced by a SQL query can be made a view which can then be queried as if it were another table in the database.
Revised May 2, 2005
145
While views have some limitations in terms of inserting and updating data under certain circumstances, they can be very useful for presenting a subset of information to the user. Materialized views are supported in Finder 9.3 and later. A materialized view contains the results of a pre-defined query. When a materialized view is available for a query, results are returned more quickly since the query accesses the small set of rows in the materialized view rather than all the rows in the tables referenced by the query. The materialized view becomes stale whenever the underlying tables are updated. More information about materialized views can be found in the Oracle Data Warehousing Guide. The following topics on views are documented below: Create a view on page 146 Create a Materialized View on page 147 Create a REFRESH FAST Materialized View Log on page 150
Create a view
There are two main reasons to use a view. You can allow users access to some of the data in the database tables, while preventing access to other data elements in the same tables which were not included in the view. You can create a view which will allow a user to execute a complex query by entering a simple query, thus minimizing the necessity for all users to be highly proficient in the SQL*Plus database language.
For example, imagine that you are working on a project with joint venture partners and you want to allow them access to all the data shared in common with you, but you do not want them to see the proprietary data in the database. A project could be created for their use consisting of views on the master project, excluding the proprietary data. The CREATE VIEW statement for the WELL_HDR table might be something like: Example:
SQL> CREATE VIEW WELL_HDR AS 2> SELECT * FROM MY_MASTER_PROJ.WELL_HDR WHERE PROPRIETARY IS NULL;
146
Revised May 2, 2005
For more information on using the CREATE VIEW or DROP VIEW commands to add or delete ORACLE views accessing data stored in one or more tables, refer to the ORACLE SQL Reference.
Create a Materialized View

Materialized views can only be created from an existing view. The steps below are the minimum required to create a materialized view. 1. Open a Finder Xterm window. 2. Run oform to launch materialized view. % oform finder_mviews <project>/<password> 3. In the Materialized View window, select from the View Name list the view you wish to change to a materialized view. 4. If the Materialized View is not checked, and you wish to make this view a materialized view, click the checkbox and proceed to Step 5. If the Materialized View checkbox is checked, that indicates that the view you selected is already a materialized view and you can click the Cancel button if you are not interested in any other views. 5. Edit the remainder of the form as required. The fields are described in Field descriptions on page 148. 6. Click Save. 7. If you opted to use the FAST Refresh Method, refer to Create a REFRESH FAST Materialized View Log on page 150. 8. Run schema_run_validate with the -v option. This will result in the original view being dropped and the materialized view being created. The schema_run_validate utility is described in the Account Management chapter of this volume. 9. Grant privileges to the new views/materialized views using the Finder_Security form. See ORACLE Privileges on page 153. 10. Run schema_run_validate with the -g option. This will propogate the new grants. The schema_run_validate utility is described in the Account Management chapter of this volume.
Revised May 2, 2005
147
11. Optionally, you may define indexes on one or more columns in a table by entering the parameters into the Finder Materialized View Indexes form. For instructions, see Define Indexes on page 151.
Field descriptions
Table Space Name - Name of the tablespace in which to store the materialized view/index. If this is left blank, the default tablespace name from ACCOUNT_TB_DEFS is used. Pct. Free - See PCTFREE in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Pct Used - See PCTUSED in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Pct. Increase - See PCTINCREASE in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Init. Trans - See INITRANS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Max. Trans - See MAXTRANS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Init Extent - See INITIAL in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Next Extent - See NEXT in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Min. Extent - See MINEXTENTS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Max. Extent - See MAXEXTENTS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Refresh Method COMPLETE - The materialized view is completely refreshed from the base tables. FAST - Oracle performs an incremental refresh applying changes that correspond to changes in the base tables since the last refresh. See Create a REFRESH FAST Materialized View Log on page 150. FORCE - Oracle performs a fast refresh if possible, otherwise a complete refresh. COMMIT - Oracle refreshes this materialized view when a transaction on one of the base tables is committed. DEMAND - Oracle refreshes this materialized view
Refresh Mode
148
Revised May 2, 2005
whenever an appropriate refresh procedure is called. NEVER - Refresh will not occur with any Oracle refresh mechanism or with any packaged procedure. NONE - Choose this option if you wish to omit the refresh mode from the materialized view create statement.
Start Refresh - Start time to refresh the materialized view (format YYYY-MM-DD HH:MI) Next Refresh - Next start time to refresh the materialized view. (format YYYY-MM-DD HH:MI) The time difference between Start Refresh and Next Refresh defines the refresh interval. Mview Type - Type of materialized view, either ROWID, PRIMARY KEY, or NONE. Select from the list of values. For usage rules, see "Indexing Selection for Materialized Views" in the Oracle Data Warehousing Guide. Select from the list of values. Use Index - Y or NONE. See USING INDEX in the Oracle SQL Reference. Y - Create materialized view with default index. NONE - Create materialized view with no default index.
The metadata used to create the indexes on the materialized views is recorded in ESI.FINDER_MVIEW_COLUMN_INDEXES.
Schema
The tables that are used with respect to materialized views are: <PROJECT>.ACCOUNT_MV_DEFS - records the metadata used to create the materialized views. ESI.FINDER_MVIEW_COLUMN_INDEXES - records the metadata used to create the indexes on the materialized views. ESI.FINDER_TABLE_SPACE - records the storage parameters for the indexes on the materialized views.
Notes
Materialized views created using this method are read only. The project/analyst must have the following privileges: CREATE MATERIALIZED VIEW CREATE TABLE or CREATE ANY TABLE SELECT
Revised May 2, 2005
149
ON COMMIT REFRESH on master tables not owned by the project/analyst
The project/analyst schema must have sufficient quota in the target tablespace to store the materialized view and index or must have the UNLIMITED TABLESPACE system privilege.
Create a REFRESH FAST Materialized View Log

You must create materialized view log before running schema_run_validate for creating REFRESH FAST materialized view. If the materialized view contains a JOIN, you must create a materialized view log for each of the tables referenced by the materialized view. The methods of creating materialized view logs are: Use SQL*Plus SQL> create materialized view log on <table>; Create an SQL script with multiple create statements and run using the executable, or_run_script
More information about materialized views can be found in the Oracle Data Warehousing Guide.
Notes for Production Data

The following materialized views are shipped with Finder: MV_REPORT_CATALOG - used by Finder components such as Production Graph and Schedule Unloader. This view reports the RESERVOIR, FLOW_STREAM_TYPE, FLOW_DIR_TYPE, and MATERIAL_TYPE attributes for a well. SV_MONTHLY_VOLUMES - used by SmartView. VOLTS_RESERVOIR_DATA_MART - used by VOLTS. OFM_MONTHLY_OWG_PROD_MV - used by OilField Manager.
Production related materialized views must be refreshed when the base tables are loaded or updated with new data. The script, $FINDER_HOME/scripts/mview_refresh.sql is provided to refresh the materialized views. If you are running on an Oracle 9i installation, the FAST Refresh Method is supported. If you are running on an Oracle 8i installation, it might be faster to drop the materialized views and then re-create rather than refresh them because the FAST Refresh Method is not supported. The following scripts are provided in
150
Revised May 2, 2005
$FINDER_HOME/scripts to drop and re-create the materialized views: mv_report_catalog.sql for MV_REPORT_CATALOG sv_production_snapshot.sql for SV_MONTHLY_VOLUMES volts_reservoir_data_mart.sql for VOLTS_RESERVOIR_DATA_MART ofm_monthly_owg_prod_mv.sql for OFM_MONTHLY_OWG_PROD_MV
The scripts need to be run on the project schema where the materialized view resides.
Define Indexes
Indexing enables ORACLE to locate rows in a large view more quickly than it otherwise could. You may define indexes on one or more columns in a materialized view by entering the parameters into the Finder Materialized View Indexes form. Function-based indexing is supported. 1. To start the Finder Materialized View Index form, start up Finder using an account with database administrator SYSTEM privileges (for example, ESI), or connect to such an account using the Database Account Manager. 2. When the Finder menu appears, choose Applications>Forms. The Forms dialog appears. 3. Choose Database Administration from the data type option menu. 4. Select Finder Materialized View Index from the list of forms and click Apply. 5. Enter all of the data required to define the materialized view indexes that you wish to add or modify. 6. Commit your changes. The new indexes will now be fully defined in the Finder data dictionary.
Field descriptions - Materialized View Index block

Index Name - Enter an index name for the index you are creating. Every index created must have a unique name.
Revised May 2, 2005
151
Mview Name - Select the List of Values button and choose the materialized view you want to index. Column Name - Enter the name of a column in the materialized view you wish to index. If you are creating a function-based index, any column name of the indexed table can be entered. Seq - More than one column may be required to specify a unique entry in a materialized view. In those cases, use the same index name for multiple columns. The sequence number identifies the most restrictive column sequence. Put the most discriminating columns first. Column Expression - Enter the column expression to be used in the function-based index.UPPER(STRAT_SCOPE_NAME) and NVL(FIELD,UNKNOWN) are examples of column expressions. Aggregate functions are not allowed in function-based indexing. For example, SUM and AVG are not allowed. Functions that return NULL will not be stored in the index.
Asc./Desc. - Obsolete, used to specify ascending (Asc.) or descending (Desc.) order. Unique - Select the List of Values button. A popup window is displayed that lists the options for classifying the index: UNIQUE, NONUNIQUE, and BITMAP. Selecting an option from this list writes the option into this column. The default classification is NONUNIQUE. If the index is classified as UNIQUE, it will prevent duplication of the indexed values within the table. (Note that this is no longer essential because primary keys are usually used to preserve uniqueness). UNIQUE is not a valid entry for a function-based index. If the index is classified as BITMAP, Finder creates a bitmap index. Refer to Bitmap Indexes on page 165 for more information.
Sec. ind. type - Enter the flag identifier on index type. F = Function-based index N = Normal index Options - (Obsolete).
Field descriptions - Tablespace Definition block

Enter or edit the metadata for the indexes in this block. Index Name - Name of the index stored in the tablespace. Initial - See INITIAL in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide.
152
Revised May 2, 2005
Next - See NEXT in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Min. Extent - See MINEXTENTS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Max. Extent - See MAXEXTENTS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Pct. Increase - See PCTINCREASE in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Pct. Free - See PCTFREE in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Pct Used - See PCTUSED in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Init. Trans - See INITRANS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide. Max. Trans - See MAXTRANS in "Guidelines for Managing Schema Objects" in the Oracle Administrators Guide.
ORACLE Privileges
Since the creator of a new table or view owns the database object, the table or view you just created is accessible only to the ORACLE project account in which it was created. It will not be available to Finder analyst accounts unless you explicitly grant privileges to it. Because the table was created independent of Finder, no default privileges are assigned, as they are when you use the FINDER_DB form to create a new table, as described below. You therefore must explicitly grant privileges for the new table to each analyst you are willing to allow to access the data in the new table or to PUBLIC. Only someone who knows the project password is able to grant privileges for the project database tables. Once the table has been created, it appears in the list of tables in the Database Account Manager Grants function, so this would be the easiest method to perform many different grants if that is necessary. To use the Database Account Manager Grants function you must connect as the project account. If you simply want to grant privileges to PUBLIC, it is easier to type the command yourself after creating the new table. Example:
SQL> GRANT SELECT,INSERT,UPDATE,DELETE ON MY_NEW_TABLE TO PUBLIC;
Revised May 2, 2005
153
If you only modified an existing table having adequate privileges already granted using the ALTER command, it is not necessary to grant privileges. The old ones are still in effect.
154
Revised May 2, 2005
Site-specific Database Changes

In order to create or modify a Finder database table in such a manner that the database changes will automatically be replicated when new projects are created, and can be propagated to existing projects, you must modify the Finder database dictionary. Once the Finder data dictionary has been modified, you may use one of several Finder database validation utilities to propagate the changes in the Finder database dictionary to one or more existing projects, and the database changes contained in the database dictionary tables will automatically be propagated to all future projects as they are created.
Schema
Modifications of, or additions to, the Finder data dictionary are most conveniently accomplished using the Finder Database Schema form. Database table changes that are project-specific should be made using the SQL*Plus CREATE TABLE or ALTER TABLE commands. 1. To start the Finder Database Schema form, start up Finder using an account with database administrator SYSTEM privileges (for example, ESI), or connect to such an account using the Database Account Manager. 2. When the Finder menu appears, choose Applications>Forms. The Forms dialog appears. 3. Choose Database Administration from the data type option menu. 4. Select Finder Schema from the list of forms and click Apply. The Finder Meta Data Dictionary form is displayed.
Revised May 2, 2005
155
This form contains four blocks: The first block accesses the FINDER_TABLE_CNSTS table in the ESI account. The second block accesses the FINDER_TABLES table in the ESI account. The third block accesses the FINDER_TABLE_DTYPES table in the ESI account. The fourth block accesses the FINDER_COLUMNS table in the ESI account.
The table name displayed at the top of this form comes from the FINDER_TABLE_CNSTS table, and is always displayed in this form.
Tables
To create a new table, the following information is the minimum required to make the table known and usable to the Finder database administration utilities. The name and description of the table must be entered in the FINDER_TABLES table. The columns for the table must be defined in the FINDER_COLUMNS table. The primary key name must be added to the FINDER_TABLE_CNSTS table and the definition to the FINDER_COLUMNS table. The check constraint name and definition for table scope must be added to the FINDER_TABLES table and for column scope to the FINDER_COLUMN table. Foreign key definitions must be added to the FINDER_TABLE_FKEYS and FINDER_COLUMN_FKEYS tables. The storage parameters for the new table must be entered in the FINDER_TABLE_SPACE table. The privileges to be granted to PUBLIC must be entered into the FINDER_TABLE_PRIVILEGES table if PUBLIC privileges are to be used to give access to the project.
156
Revised May 2, 2005
In addition, you will probably want to create indexes on the new table to improve performance when using the table. All of the above operations are discussed below.
Constraints
To add a new table entry, create a new record for your new table in the first block of the Finder Meta Data Dictionary form and enter the parameters shown in table 1 on page 157.
Table 1: Input parameters for the first block of the Finder Meta Data Dictionary
Parameter
Table Name Primary Key Name Constraint Name Constraint
Description
Choose a name for the table. You must choose a unique, valid ORACLE table name. Name of primary key for this table. Name of the check constraint for this table. Check constraint definition for this table. Use this when you need to examine two or more columns.
When you have finished entering the parameters, commit your changes. If you are running Finder from an account with DBA privileges, the message confirms completion or reports any errors. Example:
Transaction completed -- 1 records processed
If you do not have the privileges required to make changes to the Finder database dictionary table, then an ORACLE error message is displayed instead.
Revised May 2, 2005
157
Details
In the second block of the Finder Meta Data Dictionary, for your new table enter the parameters shown in table 1.
Table 2: Input parameters for the second block of the Finder Meta Data Dictionary
Parameter
Scope
Description
Enter SYSTEM, CODE, PROJECT, or ANALYST, depending upon whether the table is being created to contain Finder system parameters, codes, project data, or analyst data. Enter an identifier that indicates it is a custom table you created, such as CUSTOM or your company name or abbreviation. Enter a text description of the tables purpose Leave blank or choose TEMPORARY or PERMANENT from the list of values. Care must be taken to fully analyze the impact if you change an existing Finder table to an Oracle . Leave blank or choose SESSION or TRANSACTION from the list of values.
Product
Description Table Type
Duration
The Table Type and Duration fields are used only if you want to use the Oracle temporary tables feature. If you use this feature, be aware that there is a special procedure you must follow if you want to revert from TEMPORARY to PERMANENT or from PERMANENT to TEMPORARY. That procedure is: 1. Drop the table on which you want to change the Table Type. 2. Change the value in the TABLE_TYPE column of ESI.FINDER_TABLES. 3. Run schema_run_validate to re-create the table.
Data Types
In the third block of the Finder Meta Data Dictionary for your new table enter the parameters shown in table 3.
158
Revised May 2, 2005
Table 3: Input parameters for the third block of the Finder Meta Data Dictionary
Parameter
Data type
Description
The type of data from the CODES.FINDER_DATA_TYPES table.
Columns
Once you have created a new entry for a table, you must define the columns contained in that table. In the fourth block of the Finder Meta Data Dictionary, enter the parameters shown in table 4. Although some items are optional, we strongly recommend that you enter the items which may be required in future versions of the Finder database. When the cursor is not in the Columns block, only essential information about the columns is displayed; move the cursor back to this block to display all available information about these columns. You can also use the scroll bars to display information that doesnt immediately fit on this form. Note: There are ORACLE reserved words which should not be used as table or column names. Most of these reserved words are listed in the CODES.RESERVED_WORDS table. See also, ORACLE-reserved Words on page 176.
Table 4: Input data for the FINDER_TABLES form
Item
Column Name
Need
Required
Description
The rules for naming a column are the same as the rule for naming a table. No two columns in the same table can have the same name. A sequence number which determines the order of the columns in the table. Place most often accessed columns at the beginning of the table.
Column #
Required
Revised May 2, 2005
159
Table 4: Input data for the FINDER_TABLES form (Continued)
Item
Domain
Need
Required
Description
The Finder data domain of the column. It is especially important to correctly specify the domains of unique well identifiers (UWIs), seismic lines, and seismic surveys, since tables are assigned a data type based upon whether or not they contain column having the necessary domains. All columns in the same domain measure the same concept. They are always candidates for a join. You may advance to the Finder Data Maintenance form (page 172) to see a list of all of the data domains known to the Finder database or to create new data domains, then return to the Finder Columns block to assign data domains to the columns in your table. It is not required that all columns have domains.
Column Type Width
Required Required
Any valid ORACLE data type. The maximum width permitted for data storage for the column. Width is optional for the NUMBER data type, and must be less than or equal to 4000 for the VARCHAR2 data type. If you specify a data 'DOMAIN' type for this column, the width is reset to the value defined in the FINDER_DOMAINS table discussed on page 172. An integer which determines how many decimal places are used when a number is stored in the ORACLE database. Indicates whether this column is part of the primary key. The value used here imposes the order in which column appears in primary key. If no value, then column is not in the primary key. Put the most discriminating values first. Checked = not null; Unchecked= null. A text description of the data to be stored in this column.
Scale
Optional
Primary Key Seq
Optional
Not Null Description
Required Optional
160
Revised May 2, 2005
Table 4: Input data for the FINDER_TABLES form (Continued)
Item
Default Value Code Reference
Need
Optional Required
Description
An optional default value to be entered into the column if no data is inserted. Checked = The column is referenced directly by software and only be modified with great care. Version number of the Finder release when the column was added or last modified. Check constraint definition for this column. Use this when the values in the column can be tested for without using any other columns. Name of the check constraint for this column.
Finder Version
Optional
Chk Constraint
Optional
Chk constraint name
Optional
Foreign Key Constraints

Select Block >> Next to move to the second page of the Finder Meta Data Dictionary (figure 1).
Revised May 2, 2005
161
Figure 1: The second page of the Finder Meta Data Dictionary.
This page contains two block used to input table and column foreign key relationships. The upper block accesses the FINDER_TABLE_FKEYS table. The lower block accesses the FINDER_COLUMN_FKEYS table.
Column Indexes
Select Block >> Next to move to the third page of the Finder Meta Data Dictionary (figure 2). This page provides access to the FINDER_COLUMN_INDEXES and FINDER_TABLE_SPACE tables.
162
Revised May 2, 2005
Figure 2: The third page of the Finder Meta Data Dictionary.
The FINDER_COLUMN_INDEXES table describes the ORACLE indexes which are built when the account is created. Function-based indexing is supported. Indexing enables ORACLE to locate rows in a large table more quickly than it otherwise could. The Finder Column Indexes block lists all of the indexes created as part of the Finder database. Many indexes are already provided on key fields in the database, but you may add other indexes if you find you are performing frequent retrieval or sorting operations on fields which are not indexed. As a rule any columns that are part of a foreign key relationship should be indexes. You may define indexes on one or more columns in a table by entering the parameters described in table 5 into the Finder Column Indexes form.
Revised May 2, 2005
163
Table 5: Input data into the Finder Column Indexes form
Item
Index Name Column Name
Description
Enter an index name for the index you are creating. Every index created must have a unique name. Enter the name of a column you wish to index. If you are creating a function-based index, any column name of the indexed table can be entered. More than one column may be required to specify a unique entry in a table. In those cases, use the same index name for multiple columns. The sequence number identifies the most restrictive column sequence. Put the most discriminating columns first. Enter the column expression to be used in the function-based index.UPPER(STRAT_SCOPE_NAME) and NVL(FIELD,UNKNOWN) are examples of column expressions. Aggregate functions are not allowed in function-based indexing. For example, SUM and AVG are not allowed. Functions that return NULL will not be stored in the index.
Seq
Column Expression
Asc./Desc. Unique
Obsolete, used to specify ascending (Asc.) or descending (Desc.) order. Selecting the List of Values button displays a popup window that lists the options for classifying the index: UNIQUE, NONUNIQUE, and BITMAP. Selecting an option from this list writes the option into this column. The default classification is NONUNIQUE. If the index is classified as UNIQUE, it will prevent duplication of the indexed values within the table. (Note that this is no longer essential because primary keys are usually used to preserve uniqueness). If the index is classified as BITMAP, Finder creates a bitmap index. Refer to the following section for information about bitmap indexes.
Sec. ind. type
Enter the flag identifier on index type. F = Function-based index N = Normal index (Obsolete).
Options
164
Revised May 2, 2005
When you have entered all of the data required to define the column indexes that you wish to add or modify, commit your changes. The new indexes will now be fully defined in the Finder data dictionary.
Function-based Indexes
When using function-based indexes, performance depends upon the number of results returned and the type of query. Limitations: Function-based indexes are enabled only in the Oracle Enterprise Edition. Function-based indexes cannot be created on Large Object (LOB) columns. Function based indexes cannot be created on nested table columns. Optimizer mode must be cost-based to use function-based indexes. The rule-based optimizer will never use function-based indexes. The index can only be enabled if the signature of the function is the same as when it was created. If the signature of the function changes, then you need to revalidate the index by using the rebuild option, ALTER INDEX <index_name> REBUILD.
See the Oracle documents Server Concepts and Server Tuning for more information about the use of function-based indexes. These documents can be viewed on Oracles Internet website.
Bitmap Indexes
The purpose of an index is to provide pointers to the rows in a table that contain a given key value. In regular indexes, this is achieved by storing a list of ROWIDs for each row that contains the key value. Bitmap indexes store the ROWIDs associated with a key value as a bitmap. Each bit in the bitmap corresponds to a possible ROWID. If a bit is set, this means the row with the corresponding ROWID contains the key value. If the number of different key values is small, bitmap indexes are very space efficient, and they often dramatically improve response time. The internal representation of bitmaps is best suited for applications with low levels of concurrent transactions, such as data warehousing. See the Oracle documents Server Concepts and Server Tuning for more information about the use of bitmap indexes. These documents can be viewed on Oracles Internet website.
Revised May 2, 2005
165
Example of a Bitmap Index

To create a bitmap partitioned index on a table with four partitions, issue the following statement:
CREATE BITMAP INDEX partno_ix ON lineitem(partno) TABLESPACE tsl LOCAL (PARTITION quarter1 TABLESPACE ts2, PARTITION quarter2 STORAGE (INITIAL 10K NEXT 2K), PARTITION quarter3 TABLESPACE ts2, PARTITION quarter4);
Note:
You can create bitmap indexes on partitioned tables; however, the bitmap indexes must be local to the partitioned table they cannot be global indexes.
Default ORACLE Privileges

Select the Finder Security form from the Database Administration list in the Forms dialog. Alternatively, you can use the Database Account Manager to manage access rights and privileges. More information about the Database Account Manager can be found in the Account Management chapter of this volume. The first page of the Finder Security form (figure 3) allows the database administrator to add, modify, or delete data in the FINDER_OBJECT_PRIVS tables. The FINDER_OBJECT_PRIVS table contains data which specifies the default privileges which are automatically granted to users, roles or all ORACLE accounts (PUBLIC) on each database table when a new project is created. When a new table is added to existing projects by running one of the Finder database validation utilities, the data associated with the new table in the FINDER_OBJECT_PRIVS table is used to establish default ORACLE database privileges for the new table. To define or modify the default privileges, enter or revise the parameters shown in table 6 on page 167.
166
Revised May 2, 2005
Figure 3: The first page of the Finder Security form.
When you have entered all of the data required to specify the default privileges, commit your changes. Note: Granting ANY table access to PUBLIC is often undesirable, especially since PUBLIC may include valid ORACLE accounts which are not even associated with Finder accounts! See the Account Management chapter in this volume for a discussion of database security, which privileges should be granted on the different types of Finder accounts for different levels of security, and the trade-offs between tight security and data access.
Table 6: Input parameters for the first page of the Finder Security form
Item
Object Name Scope
Description
Enter the name of the object (table, view, sequence, etc.) whose default privileges you wish to specify. Enter the scope associated with the table: either SYSTEM, CODE, PROJECT, or ANALYST.
Revised May 2, 2005
167
Table 6: Input parameters for the first page of the Finder Security form
Item
User or role name Select Insert Update Delete Reference Alter Index
Description
The name of the user or role owning this object. The default is PUBLIC. Checked = Allow the selected ORACLE account(s) to see the data in the table. Checked = Allow the selected ORACLE account(s) to insert data in the table. Checked = Allow the selected ORACLE account(s) to update the data in the table. Checked = Allow the selected ORACLE account(s) to delete data in the table. Checked = Allow the selected ORACLE account(s) to reference the data in the table through a foreign key Checked = Allow the selected ORACLE account(s) to alter the structure of the table. Checked = Allow the selected ORACLE account(s) to alter the indexes of the table.
Note:
All analysts must have insert/update/delete privilege on a subset of the project tables for storage of objects like map definitions. Contact GeoQuest support for more details.
Modified ORACLE Privileges

If you wish to modify the default privileges for specific analyst accounts, or restrict access to the project to a subset of all ORACLE users (some of whom may not even be Finder users), use the Change grants facility in the Finder Database Account Manager as described in the Account Management chapter of this volume. To permanently modify roles and privileges in the Finder database or to create default roles for the installation, select the next block and make changes on the second page of the Finder Security form (figure 3 on page 167). This form contains three blocks: The upper block accesses the FINDER_ROLE_HDR table. The middle block accesses the FINDER_SYSTEM_PRIVILEGES table. The lower block accesses the FINDER_ROLE_ROLES table.
168
Revised May 2, 2005
These tables are only accessed when you run schema_run_validate on the esi account with the -g argument. See the Account Management chapter of this volume for a discussion of the granting of privileges and the creation of the groups of privileges called roles.
Views
Select the Finder Views and Synonyms form from the Database Administration list. Use the first block of the Finder Views and Synonyms form to add, modify, or delete ORACLE views that access Finder's tables. An ORACLE view is like a window through which you can view or change information in ORACLE tables. The concepts associated with ORACLE views are discussed on page 145. You may define a view of one or more Finder database tables, or even in terms of other Finder views, by entering the parameters described in table 7 in the FINDER_ VIEWS form.
Table 7: Input data for the first block of the Views and Synonyms form Item View name Description Enter any valid ORACLE name. Two views with the same name cannot exist in the same ORACLE account. Enter the scope (SYSTEM, CODE, PROJECT, or ANALYST) of the table(s) or view(s) accessed by the query used to define the view. Enter any valid SQL query with one exception: a view may not contain an ORDER BY clause.
Scope
View text
When you have entered all of the data required to define the view that you wish to add or modify, commit your changes. The new view is now fully defined in the Finder data dictionary.
Table Synonyms
Select Finder Views and Synonyms from the Database Administration list.
Revised May 2, 2005
169
A synonym is simply an alternate name for a database object. This is useful for integrating tables a customer might already have in Oracle, but they named their tables differently. It can also be used for making a table in one account look like a table in another account. For example, you are making a small prospect-level project by extracting data from a larger project. Rather than duplicating the data for the WELL_TOPS table, you decide you would prefer to use the table in the master project directly. This can be done with the following procedure. 1. Log into the new project account in SQL. 2. Drop the WELL_TOPS table. 3. Use the CREATE SYNONYM command to create WELL_TOPS as a synonym.
SQL> CREATE SYNONYM WELL_TOPS FOR MASTER_PROJ.WELL_TOPS;
4. If you want to have the synonym defined for all projects when created then it should be defined on the second block of the Finder Views and Synonyms form. This block contains fields for the necessary information to create a synonym. These are summarized in table 8 below.
Table 8: Input parameters for the second block of the Views and Synonyms form
Item
Synonym name
Description
This is the name of the database object as it will be created. In our example above, this is where you would enter the name WELL_TOPS for the synonym. This is the scope or type of account that will have this synonym defined. Valid entries are one of ANALYST, CODES, PROJECT, SYSTEM. This is the name of the remote account that owns the table that the synonym is referencing. In the above example, this is where you would put MASTER_PROJ. This is the name of the table that is being referenced by the synonym being created. In the example in the previous page this would be WELL_TOPS. Checked =public synonym, Unchecked=private synonym.
Scope
Table owner
Table name
Public access
170
Revised May 2, 2005
The contents of the Table Owner and the Table Name columns are combined to produce the arguments for the FOR clause of the CREATE SYNONYM command.
Miscellaneous Data
Select Finder Maintenance from the Database Administration list.
Data Domains
The Finder data domains represent column definitions for common fields in the database. They are independent of any actual tables in the database and are used to assure consistency between columns in related tables that might be used as the basis for joining the tables for retrievals, or that represent similar concepts and should have conforming definitions. The database administrator should always refer to the data domains table for column definitions of key fields (such as UWI for well data tables) if adding tables that might at some time need to be joined with the standard Finder tables. The form is set up to automatically change the definitions of all columns in a common domain. This helps enforce consistency.
Revised May 2, 2005
171
Figure 4: The first page of the Finder Data Maintenance form.
The top block of the first page of this form accesses the FINDER_DOMAINS table.
172
Revised May 2, 2005
All columns which belong to the same data domain describe the same parameter for example, the concept of depth in a well is the same regardless of whether the depth is the measured depth to a formation, the total depth of the well, or the depth to the top or bottom of a core. Thus the column describing any of these well depth columns are said to have the same domain. The data domains specified for the columns in a table are sometimes used by Finder software as the basis for determining the table data type. Therefore it is especially important that the data domains for well unique identifiers or seismic line unique identifiers be correctly specified in order for you to be able to use the tables in relational retrievals, since if the domains are specified incorrectly or not at all the new tables are considered to be of the other data type. The database administrator should always refer to the contents of the FINDER_DOMAINS table when adding column definitions of key fields (such as UWI for well data tables) that might be used as a criteria for joining the table with the other Finder tables. Examine the existing domains to determine if any of the new key columns you have added correspond to domains already known to Finder. If they do, insert the number of the Finder domain in the appropriate Domain field in the Finder Columns block.
Table 9: Input data into the first block of the Finder Data Maintenance form
Parameter
Code
Description
Enter an integer. It is important that you use a number that Finder will not inadvertently assign to a new domain in a future release or update. For that reason, we recommend that your custom domain numbers be greater than 999. Enter a valid ORACLE column name which can be used as a default column name unless you wish to enter a different one in the previous block. Any valid ORACLE data type. The maximum width permitted for data storage for the column. Width is optional for the NUMBER data type, and must be less than or equal to 4000 for the VARCHAR2 data type. If you specify a data 'DOMAIN' type for this column, the width is reset to the value defined in the FINDER_DOMAINS table discussed below. The decimal component of the Width field.
Default name
Type Width
Scale
Revised May 2, 2005
173
Table 9: Input data into the first block of the Finder Data Maintenance form
Parameter
Units
Description
The UOM_TYPE used as the value in this column should be one supported by the GeoFrame Oilfield Services Data Dictionary (OSDD). The OSDD units are shown in mixed case and the old Finder style units are shown in all uppercase. A short description of the data domain to enable you or others to associate it with other columns in other tables.
Description
If the new key columns do not correspond to existing Finder domain types, and if it is necessary, you may create your own domain for a new key field data type by assigning a number which does not correspond to any existing domain number. To define a new domain, enter the parameters show in table 9 on page 173 into the Finder Data Domains form. When you have entered all of the data required to domains you wish to add or modify, commit your changes. The new domains will now be fully defined in the Finder data dictionary.
Finder Sequences
A sequence is a unique number generator. Finder uses sequences to generate unique node identifiers, graphic object identifiers and other things. If you want to have Finder create sequences automatically for you then use the second block of the first page of the Finder Data Maintenance form (figure 4 on page 172). The minimum information required to define a sequence is the Name, Scope, Initial value for the sequencer, and the increment to be applied every time the sequencer is accessed. All the fields are described in table 10 on page 175. Each column that is driven by a sequencer should be entered into the table FINDER_COLUMN_SEQ. Note that a column described in FINDER_COLUMN_SEQ should not be the child table in a foreign key. It can be a parent table.
Using Sequences in User-defined Tables

If you intend to use Datamover, you must enter the information in FINDER_COLUMN_SEQ as described above. You can user any sequencer already defined by Finder, or create your own. You should make each
174
Revised May 2, 2005
column driven by a sequencer have its own separate domain. See the section on defining domains. If your tables use sequences for primary keys, there is no need to also add an additional, redundant unique index.
Table 10: Input parameters to the second block of the Data Maintenance form
Item
Sequence name Scope
Description
The name of the database object to be created. This is the scope or type of account that will have this synonym defined. Valid entries are one of ANALYST, CODES, PROJECT, SYSTEM. Initial value of the sequencer. This value is returned the first time the sequencer is accessed. Increment amount. This value is added to the current value of the sequencer to produce the next value the sequencer will issue. This is the optional minimum value a sequencer will generate. This is the optional maximum value a sequencer will generate. This is the number of sequence numbers to be cached in memory for rapid access. The default if left null is 20. Checked indicates that the sequencer will restart at the starting point when the last possible number has been generated. Unchecked or null results in no more numbers being generated when the last number is null. Checked indicates that sequence numbers are guaranteed to be generated in order of request. Unchecked or null indicates that it will produce numbers in the quickest possible manner.
Init Inc
Min Max Cache Cycle
Ordered
Logical Names
Access the first block of the second page of the Finder Data Maintenance form (figure 5) to modify values in the FINDER_LOGICAL_NAMES table in the CODES Finder account.
Revised May 2, 2005
175
Figure 5: The second page of the Finder Data Maintenance form.
This table is used to document default logical name assignments. It is not used at run-time to assign logical names, since that is done using information from the LOGICAL_NAMES table of the accounts involved. It should be used as a reference for which logical names are assigned and what the relationship of each is to other logical names. It is also used as a template for copying the logical names to new accounts when they are being created. Use this form to specify the storage of N-Lists in database tables. See the N-List Data Stored as BLOBs section in the System Configuration chapter of this manual for more information.
ORACLE-reserved Words
The second block of the second page of the Finder Data Maintenance form is used to reference the words and commands that make up the ORACLE command set (figure 5 on page 176).
176
Revised May 2, 2005
These words should not be used as table, view, synonym, index, or column names, or for user variables, since there is a conflict between the names you assigned and the ORACLE SQL command keywords when they are used in SQL sentences. This list is also used as a validation list for table and column name entries made in the first page of this form. If you attempt to use a reserved word improperly, you will see the following message.
This is an ORACLE reserved word. Please pick another name.
Note:
If you need to use a table or column name which is the same as an ORACLE reserved word, for example if an existing customized table or column name is the same as a reserved word in a new version of ORACLE, you must enclose the table or column name in double quotes (" ) in your applications programs and scripts. If you are satisfied with the changes you have made and committed to the Finder database dictionary, commit your changes and exit the form.
N-List Mapping
Access the first block of the third page of the Finder Data Maintenance form (figure 6) to modify values in the FINDER_NLIST_MAPPING table.
Revised May 2, 2005
177
Figure 6: The third page of the Finder Data Maintenance form.
This table is used by Data Mover to determine the mapping between tables and N-Lists. Entries in the File name and Nlist id fields which begin with the at sign (@) have a special meaning. For example, an entry @OS_PATHNAME in the File name field indicates that the actual name of the file is in the OS_PATHNAME column of the table indicated in the Table name field. This table will rarely need to be modified by site administrators.
Displaying Finder Product Information

Access the second block of the third page of the Finder Data Maintenance form (figure 6 on page 178) to modify values in the FINDER_PRODUCTS table. This table contains entries for products of interest to Finder users. There is a field for the name of the product, and a field for its description. This product information is used as the validation for the product entity of
178
Revised May 2, 2005
each table in the Finder schema. The FINDER_TABLES table contains this information. This serves as a way of categorizing the table entries by product.
Creating or Modifying Table Default Storage Data

In order for Finder to know how to create a table, the default storage values for the table must be in the FINDER_TABLE_SPACE table. This is entered on the first block of the fourth page (figure 7).
Figure 7: The fourth page of the Finder Data Maintenance form.
The only field not provided with a default value when entering a new record is the Table or Index Name column. All the others have default values that are considered to be a minimum so as to not take up excessive space if the table is created but no data are loaded. If you want to adjust these parameters, they correspond to the keywords used in the CREATE TABLE or CREATE INDEX commands and are fully documented in the ORACLE SQL Reference.
Revised May 2, 2005
179
Creating or Modifying Column Couplings

Access the second block of the fourth page of the Finder Data Maintenance form (figure 7 on page 179) to modify the values in the FINDER_COLUMN_COUPLINGS table. This table describes columns that represent complex data types, such as NODE_X, NODE_Y coordinate pair in the NODES table, or a measurement and unit of measure pair. Entries in this table that have the same ID and type are considered as a single unit. This table is used by Data Mover to determine which columns together represent an entity. For example, UPPER_X and UPPER_Y represent a single entity, while LOWER_X and LOWER_Y represent another discrete, single entity even though they are in the same table. This relationship is established in this table. If you are adding columns which you want Data Mover to process together, you must make appropriate entries in this table. Typical examples are the X, Y values of a coordinate. This information is used by the datamover.
Changing the Default Color in the Lease Overlay

You can set the lease default color for all projects at your site. The changes described below should be made only by the Finder database administrator. Leases that do not satisfy any of the Color Fill criteria for that overlay will default to a particular color. Now, a new entry in the CODES account's EXPRESSION_CODES table defines a color called LEASE DEFAULT COLOR. This color points to another color. The value, or CODE, assigned to the LEASE DEFAULT COLOR should be set to the code corresponding to the color that these default leases should be shaded. To determine the LEASE DEFAULT COLOR, start SQL*Plus using the CODES account. Example:
<PROMPT>: sqlplus codes/codes SQL > Select name, code from EXPRESSION_CODES where keyword = 'COLOR';
180
Revised May 2, 2005
NAME CODE -------------------- ---------BLACK 0 BLUE 4 CYAN 5 GREEN 3 LEASE DEFAULT COLOR 7 YELLOW 7 ORANGE 8
Note:
The full contents of this retrieval have been shortened for brevity. In this example, the leases not adhering to any of the Color/Fill Definition entries will be colored with the LEASE DEFAULT COLOR that is defined as 7, (YELLOW). To change the LEASE DEFAULT COLOR to CYAN for example, start SQL*Plus in the CODES account, and enter the following command.
SQL> update expression_codes set code=5 where name=LEASE DEFAULT COLOR; 1 row updated SQL> commit; Commit complete
Note:
If the LEASE DEFAULT COLOR code is not present in the CODES account's EXPRESSION_CODES table or is assigned the code of a color that is not present in the CODES account's EXPRESSION_CODES table, then when the lease overlay is displayed or plotted, the leases that do not adhere to any of the Color/Fill Definition entries will not be displayed on the map. For example, assume there is a Color/Fill Definition that color-codes leases based upon a LEASE ATTRIBUTE called COMPANY. In addition, assume that the LEASE DEFAULT COLOR color code has been removed from the CODES.EXPRESSION_CODES table. Now, when the overlay is displayed or plotted, any lease whose company is not specified in the Color/Fill Definition will be omitted from the overlay (meaning neither the outline nor the label will appear). Although this can be used as a method of suppressing the display of certain leases, over and above the LEASE overlay's SELECT LIST and SELECT BY PHRASE options, it should be used with extreme caution. This method of selection may be desirable for you, but undesirable to other users. Therefore it is recommended that this color should always be defined in the CODES.EXPRESSION_CODES table.
Revised May 2, 2005
181
Adding User-defined Objects to the Finder Schema

Before You Begin
For background information on the Finder schema for user-defined objects, see the GEM Data Model section in the Finder Data Model chapter of the Finder Data Model and Dictionary. Your Finder installation includes an example of how to modify the Finder schema for a pipeline user object. Go to the Finder home directory, then open and view the following: /gems_examples/readme.txt
Process Overview
To integrate user tables containing attribute data for pipelines, roads, vegetation, etc., you must register them in the Finder schema. For instance, after adding a Pipeline object, SmartMap can display a Pipeline overlay and Datamover will be able to move all Pipeline tables installed by the user. Follow this process to register your objects in the Finder Schema: 1. Update the Data Dictionary 2. Declare an Object Class for User-defined Data 3. Load Graphical Data 4. Load Attribute Data. Each of the steps in the process are described below.
Updating the Data Dictionary

To make Finder aware of your tables, you must update the Finder Data Dictionary. This may be done using the schema form (see Schema on page 155) or SQL*Plus, just as you would use for any other user-defined schema extension. To ensure proper installation of user-defined tables for new object classes, complete the following steps 1. In ESI.FINDER_DATA_TYPES, enter your object class as a new data type. The data type name is the object class and must be unique.
182
Revised May 2, 2005
2. In ESI.FINDER_TABLES, set product = USER for all your tables. 3. Populate the schema tables with appropriate values. (FINDER_COLUMNS, FINDER_TABLE_CUST, FINDER_TABLE_FKEYS, etc.) 4. Run schema_run_validate with the -ual option to verify and/or create user tables, constraints, and indexes.
Declaring an Object Class for User-defined Data

Use the Graphic Object Classes form to create a class and associate it with your attribute tables. To attach an attribute table or header table (e.g. PIPELINE_HDR) to an associated object class (PIPELINES), the table name and its natural key column name (e.g. PIPELINE_ID) is specified in the OBJECT_CLASSES table for that object class. Each graphic object that represents an individual PIPELINE_HDR record would include the natural key as a LINK_ID. The reason for declaring an object class in Finder is so you can display the data in your tables on a map. When you declare an object class, you are associating your attribute data with graphical elements (line, polygons, etc.) that Finder understands. Once the table name and link column are specified for an object class, it is treated like other Finder data types in applications such as SmartMap and List Assistant. Public privileges are required on user tables for these applications to see them. Full integration into the Finder schema is required, however, before applications such as the Select Phrase Manager and Datamover can become aware of the extensions to the database.
Loading Graphical Data

After attribute data has been loaded, you can use the Graphic Object Loader to load graphical data and establish the association of the attribute data and its graphical representation via the LINK_ID. For information about using the Graphic Object Loader, see Finder Loaders and Unloaders Reference.
Customizing UOM Codes

Adding additional UOM (Unit of Measure) Codes to the CODES.UOM_CODES table is easy, and does not compromise the operation of Finder.
Revised May 2, 2005
183
Units of measure exist for many fundamental entities, like length, volume, time. It is possible to convert from a unit on one of these domains to another in the same domain by applying a multiplication factor. The conversion of an old_value to a new_value is determined by the following equation.
old_unit_factor * (old_value - old_unit_offset) new_value = new_unit_factor + new_unit_offset
new_unit_factor and old_unit_factor are arbitrary factors that, when divided, produce the correct conversion factor to convert the old_value to the new_value. new_unit_offset and old_unit_offset are offset values used for the conversion (for example, Fahrenheit to centigrade temperature conversions). Each domain, has a single unit with the conversion factor defined as 1. For example, for length this is the millimeter. All other units in the same domain must have a conversion factor from this standard unit in the UOM_CODES table. The offset field for any unit may be NULL, in which case it is not used in the conversion (i.e., offset values are set to 0 in the equation above). Example: There are 10 millimeters in 1 centimeter, so
conversion factor = 10 millimeters / 1 centimeter = 10
Table 11 below shows the structure of the UOM_CODES table.

Table 11: The UOM_CODES table
Name
UOM_NAME UOM_DESCRIPTION UOM_CODE UOM_DEFINITION UOM_OFFSET UOM_TYPE
Null?
NOT NULL
Type
VARCHAR2(12) VARCHAR2(255)
NOT NULL NOT NULL
NUMBER(12) NUMBER NUMBER VARCHAR2(10)
184
Revised May 2, 2005
The conversion factor is stored in the column UOM_DEFINITION, the offset is stored in UOM_OFFSET, and the unit name is placed in the UOM_NAME column. The UOM_CODE is an arbitrary number that is used to link synonyms of unit names. The value chosen for the UOM_CODE is not important. We recommend that users who want to customize this table add additional values using a UOM_CODE with numbers greater than 10000. These will never conflict with GeoQuest-provided numbers. When there are multiple names for a unit of measure, you can designate one as the preferred name by setting its UOM_CODE value to a negative number. If there is only one entry in the CODES.UOM_CODES table for a unit of measure, be sure to make the UOM_CODE negative so it will display in selector lists. Note: The preferred spelling of the unit is flagged by a negative of the UOM_CODE value. Table 12 is a partial list of units from the current table. The UOM_OFFSET field for all these units is NULL. The complete set of units can be found in the UOM_CODES table.
Table 12: Contents of the UOM_CODES table
UOM_NAME
DEGREES FEET FOOT F FT MILLIMETERS MILLIMETER MM MILLIMETRES MILLIMETRE INCHES INCH IN METERS
UOM_CODE
-8 -1 1 1 1 -2 2 2 2 2 -3 3 3 -4
UOM_DEFINITION
1 304.8 304.8 304.8 304.8 1 1 1 1 1 25.4 25.4 25.4 1000
UOM_TYPE
ANGULAR DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE
Revised May 2, 2005
185
Table 12: Contents of the UOM_CODES table (Continued)
UOM_NAME
METER M METRES METRE CENTIMETERS CENTIMETRE CM CENTIMETRES CENTIMETER MILES MILE MI KILOMETERS KILOMETER KILOMETRES KM KILOMETRE YARDS YARD GM GR GRAMS G GRAM MG MILLIGRAM LBS
UOM_CODE
4 4 4 4 -7 7 7 7 7 -10 10 10 -11 11 11 11 11 -28 28 -12 12 12 12 12 -13 13 14
UOM_DEFINITION
1000 1000 1000 1000 10 10 10 10 10 1609344 1609344 1609344 1000000 1000000 1000000 1000000 1000000 914.4036 914.4036 1 1 1 1 1 0.001 0.001 453.59
UOM_TYPE
DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE DISTANCE MASS MASS MASS MASS MASS MASS MASS MASS
186
Revised May 2, 2005
UOM_NAME
POUNDS LB POUND KG KILOGRAM K KILOGRAMS DARCY MILLIDARCY PU PSI SU SECONDS SECOND S SEC MILLISECONDS MILLISECOND MS MSEC MICROSECONDS US MICROSECOND USEC MICROSEC MIN MINUTE
UOM_CODE
14 14 14 -18 18 18 18 -31 -32 -37 -33 -29 -5 5 5 5 -6 6 6 6 -9 9 9 9 9 -19 19
UOM_DEFINITION
453.59 453.59 453.59 1000 1000 1000 1000 1 .001 1 1 1 1 1 1 1 0.001 0.001 0.001 0.001 1e-6 1e-6 1e-6 1e-6 1e-6 60 60
UOM_TYPE
MASS MASS MASS MASS MASS MASS MASS PERM PERM POROSITY PRESSURE SATURATION TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME TIME
Revised May 2, 2005
187
UOM_NAME
MINUTES HOUR HR HOURS DAY DAYS C3 CC ML MILLILITERS MILLILITER MILLILITRE MILLILITRES LITER L LITERS LITRE M3 GALLON QUART QT CF FT3 MCF BBL
UOM_CODE
19 -20 20 20 -21 21 -15 15 -16 16 16 16 16 -17 17 17 17 -22 -23 -24 24 -25 25 -26 -27
UOM_DEFINITION
60 3600 3600 3600 86400 86400 0.001 0.001 0.001 0.001 0.001 0.001 0.001 1 1 1 1 1000 3.7854 .9464 .9464 28.3168 28.3168 28316.85 158.9868
UOM_TYPE
TIME TIME TIME TIME TIME TIME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME VOLUME
188
Revised May 2, 2005
Propagating Database Changes

After you have modified the Finder database dictionary files, the changes will automatically be applied for all new Finder project and analyst accounts when the accounts are created. However, the changes will not be applied to existing accounts unless the accounts are validated. This validation procedure will make two passes through an account. The first pass verifies that all tables defined in the Finder dictionary exist in the current account. The second pass verifies that all tables and columns in the current account are entered in the Finder Dictionary. If a table defined in the Finder dictionary is missing from the current account, it is created. If a table definition does not match the table definition in the Finder dictionary, the table is modified to reflect the current definition. If it is not possible for the utility to modify the table, then a message to this effect is logged to the current journal file.
Note:
No data are modified during account validation, only table, view, and index definitions. There are three different ways to validate existing Finder system, code, analyst, or project accounts. You may use the Validate function available from the Finder Database Account Manager to validate all the tables associated with any single Finder account listed in the FINDER_ACCOUNTS table. If any changes have been made to the ORACLE forms, use schema_run_validate rather than the Validate function. You may use the schema_run_validate utility outside of Finder to validate ANY Finder account listed in the FINDER_ACCOUNTS table.
The function and use of the Create and Validate functions available from the Finder Database Account Manager is discussed in the Account Management chapter of this volume. See that chapter if you wish to use the Database Account Manager to validate all of the Finder accounts. The schema_run_validate utility is also described in the Account Management chapter of this volume.
Revised May 2, 2005
189
190
Revised May 2, 2005
Chapter 6: Customizing Database Tools
Chapter 6
Introduction
The Finder database is fully defined by the Finder database dictionary tables and can be easily modified using the techniques described in the Customizing the Database chapter. That chapter shows you how to customize the database by adding new tables and views, or by modifying existing tables or views. In order to make the maximum use of these database enhancements, new or modified database access tools can and should be created. In addition to access tools, other enhancements, such as new graphic symbols, may be required to make full use of the mapping or other applications. This chapter describes the concepts and processes by which the user's entire Finder database environment can be customized. It is targeted to the Finder database administrator and organized to make it simple to go directly to the tool you would like to customize and begin working. In this chapter, general comments and background information necessary for many types of customization are presented in this Introduction. Each section discussing a different tool to be customized will be independent of the others and will present all the required information for customizing that particular tool. You should be familiar with the general concepts in this introductory section before proceeding with customizing any of the tools discussed in later sections.
Revised May 2, 2005
193
This chapter discusses the following subjects. How to create custom forms and make them available within Finder. How to create custom scripts and make them available within Finder. How to customize select phrases. How to create custom views and have them created automatically as part of creating or validating a project. How to customize the document management system.
The Customizing Database Graphics chapter, a separate chapter also in this volume, covers these subjects. How to customize existing well symbols or create new symbols to meet your needs for well mapping. How to modify GPD files associated with various Finder applications such as Mapping and Cross Section to meet your needs.
Understanding the File Structure

Most of the customizing tasks presented in this chapter involve using or customizing special files provided as part of Finder. When preparing to customize a form, report, script, symbol or GPD file, the first thing you need to do is find the correct file to use as an example or template for your work. Once you have made your modifications, you need to know where to put your new file to make it available to your users and protect it from being overwritten during a Finder upgrade. The following discussion will familiarize you with the overall file structure and the conventions used in storing files using scripts and forms as examples since these are the most common areas to customize. Once a script or form has been created or modified, it must be saved in an appropriate directory. The location where the file is stored determines who has access to the script or form, and whether or not the file is likely to be deleted or modified during the next Finder software installation or upgrade. The various directories where scripts or forms may be stored are accessed using the logical name list ESI$SCRIPTS or ESI$FORMS, respectively.
194
Revised May 2, 2005
Logical Names
The ESI$SCRIPTS, ESI$ORAREP2, ESI$FORMS, ESI$GPD and ESI$SYMBOLS logical names are constructed as logical name lists defined in the project and system LOGICAL_NAMES tables. By default, these logical names consist of a list of directories that define the search order for the specified script or form. The hierarchy is normally as follows. Project-customized Project-specific Site-specific (system level customized) Finder-provided (system level directories).
For example, when a particular script is specified, the following four directories are searched in the order in which they are listed. The first occurrence of the script is used. ESI$PROJECT/customized/scripts ESI$PROJECT/scripts $FINDER_HOME/customized/scripts $FINDER_HOME/scripts
Finder maintains the concept of logical names in the UNIX environment. The translations for such logical names as ESI$FORMS can be viewed in the logical names table of the account in question.
Files and Directories

A partial listing of the $FINDER_HOME directory structure is illustrated in figure 1 on page 196. Files shipped as part of Finder are stored in the top level directories that correspond to the type of file, such as scripts, forms, reports, symbols and gpd. Scripts (SQL*Plus report scripts), symbols and gpd files are generalized tools that can be used with any project. Oracle forms and reports files on the other-hand are divided into system and project forms depending upon their function. System forms are delivered under $FINDER_HOME/ forms/system while project forms are delivered under $FINDER_HOME/ forms/project. They are pre-compiled and ready for use. Finder-provided project forms are referred to project-specific tables or other Oracle objects using the ALTER SESSION Oracle command. Sitecustomized forms may be referred to a project in the same way, or through
Revised May 2, 2005
195
synonyms. If your site has custom forms that use synonyms to refer to tables or objects, set USE_SYNONYMS = YES. Setting USE_SYNONYMS = YES generates synonyms at the start of each Finder session.
$FINDER_HOME bin Finder-provided Files forms
gpd
project
system reports
common
scripts project symbols system
customized Installation-specific Files
bin
forms
gpd
reports
scripts
symbols
project
system
project
system
Figure 1: System scope directory structure for files that can be customized.
In addition, we provide template files in the $FINDER_HOME/forms/ common directory that you can use to create your new forms. The template files are: gdm.pal gdm_template.fmb gdm_template.mmb gdm_template.pll
196
Revised May 2, 2005
Do not modify or add forms in the $FINDER_HOME/forms/project, system, or common directories since the form definition files may be modified or deleted during the next Finder software installation or update. The files stored in these directories are subject to modification, replacement, or even deletion without notice whenever the Finder system is re-installed or updated. Any changes made to customize these scripts or forms, or new scripts or forms stored in these directories, may therefore be lost when the next Finder update is performed. Note: You may have to create any directories shown under $FINDER_HOME/customized if they do not exist and if they are required.
Key Points on Files and Directories

The following rules of thumb are useful in deciding where to put customized files in the project or system directory trees. Any file you have modified or created new for inclusion in Finder should be stored in the system-level or project-level customized directory. Files that are to be generally available in all projects or that access data in the ESI or CODES accounts should be installed in the system-level customized directory To avoid losing changes in a Finder upgrade, all changed or new files must be in a customized directory, not in the main system or project level directories.
Overview of the Customizing Process

There are four basic steps in the customizing process. 1. Identify an appropriate file to use as a template. In most cases it will be easier to use existing files as templates in order to take advantage of the fact that the basic formatting and rules are already in place in the file and all that is required is for you to modify the file to achieve the desired results. 2. Make the necessary modifications to the file. Each file type has different background knowledge required to understand what to do to customize the file. All types have text source files that can be modified with a simple text editor, but in the case of forms, using the more sophisticated ORACLE
Revised May 2, 2005
197
Forms Designer interface is necessary. The remaining sections in this chapter provide detailed instructions for customizing the different database tool files. You should also refer to the current versions of the ORACLE documentation for tutorials and reference. 3. Put the file in the correct directory if it is not already there. This has already been discussed somewhat above and the specifics will be addressed in the individual sections for each file type. 4. Make the appropriate database entries to make the new file known to Finder. This is a question of whether the customized file is intended to be used at the system or project level. Normally, the file would be implemented at the project level first and tested, then installed at the system level once it proves to work correctly. Note: There are ORACLE reserved words which should not be used as table and column names. Most of these reserved words are listed in the CODES.RESERVED_WORDS table (see the Displaying the ORACLE Reserved Words section of the Customizing the Database chapter of the Finder Database Administrators Reference).
198
Revised May 2, 2005
Customizing Finder Report Scripts

Introduction
ORACLE allows you to create and save sets of SQL*Plus commands, referred to in this document as scripts, which when executed either from within or outside of Finder, allow you to interact with the database. Scripts may be written to perform virtually any database management function, including the creation of new tables, the modification of data in the database, or generation of reports. ORACLE provides two utilities to generate reports; SQL*Plus and Oracle Reports. Either can be used, but SQL*Plus is much easier to use, and is used in the examples that follow. For detailed information on the creation and use of scripts using SQL*Plus, see the ORACLE8i SQL Reference and the SQL*Plus User's Guide and Reference. A brief description of some of the most important commands SQL*Plus provides for writing report scripts is presented in the tutorial under theOracle Forms heading in this chapter. The process of creating, testing, and saving a script for use by Finder is exactly the same as described in the SQL*Plus User's Guide and Reference. This section shows you how to customize report scripts. It assumes you are familiar with the SQL database query language. If this is not the case, you should consult the ORACLE8i SQL Reference manual for the detailed information on using SQL.
Getting Started
To customize report scripts you need to know. How to use the SQL query language. How to use a text editor. How to use the standard parameters Finder passes to the script. Where to store the script when it is finished. How to add the information to the ORACLE_SCRIPTS table to make the script known to Finder.
Revised May 2, 2005
199
Customizing Scripts Reference

Scripts That Access Project Tables
In order for a script to access project data tables, the script must include a reference to the project ORACLE account as part of the table name. Because system-wide scripts designed to reference data associated with any project, whether provided with Finder or by customization, cannot explicitly include a project name, substitution variables must be used to indicate the project when the script is executed from within Finder. In addition, it is often useful or necessary to limit the results of a query to a subset of database objects identified in a user-defined select list. This function too may be performed using substitution variables. When you execute a report script to generate a report from within Finder, the script that you are executing can be passed up to three parameters called substitution variables. The SQL concept of using substitution variable parameters in SQL commands is explained in the SQL*Plus User's Guide and Reference produced by Oracle. Finder makes available three parameters for use in a report script. &1 The project name. &2 The name of the temporary control list, if any. &3 The name of the original Finder select list, if any. Whether a report script requires none, some, all, or none of these parameters depends upon the ORACLE tables that are being accessed, whether or not a control list is to be used, and upon the script creator's individual preferences. The project name substitution variable &1 is always required for a script which accesses project tables. It is not required unless project scope tables are involved.
200
Revised May 2, 2005
Specifying a Project Name

If a report script is site-specific, meaning that it has been designed to report on data from any project, then the name of the project (parameter &1) must be included in the script. This is easily done by pre-pending the &1 parameter before the table name, as shown below. Note that two periods (. .) are required between the &1 parameter and the table name in order that the table be accessed correctly. Example:
SQL> SELECT WELL_NAME,ELEVATION,OPERATOR FROM &1..WELL_HDR;
If Finder is being run by an analyst working on a project named VALDEZ, the preceding SQL script is translated by Finder as follows.
SQL> SELECT WELL_NAME,ELEVATION,OPERATOR FROM VALDEZ.WELL_HDR;
Specifying a Temporary Control List

Select lists are lists of specific types of database objects, identified by their unique identifiers, which are created using the List Assistant application as described in the Applications chapter of the Finder Users Reference. In order for the list to be used to limit a query using SQL, the select list is used to create a temporary table referred to as a control list. A SQL*Plus or a ORACLE Reports script which is to limit its search to the items identified in a select list must refer to the temporary control list name substitution variable &2. It may also refer to the original select list name from which the temporary control list was formed, in which case the script also references the &3 substitution variable.
Revised May 2, 2005
201
Examples: A list of unique well identifiers generated by graphically picking wells from a map. A list of seismic identifiers for all seismic lines processed since 1982.
Each select list is given a default name, which can be modified by the user, and each list can be used to create a temporary table in the analyst's ORACLE account which can then be joined as part of the SQL command to help limit the database retrieval to all or some subset of the items in the temporary table. Examples of reports which cannot and do not use control lists include reports about data types other than wells and seismic, such as the Finder database schema and database authorization lists, as well as well or seismic data reports which you choose to not require a control list. Note that you should be especially careful when executing well or seismic reports which do not use select lists that the reports generated are not so lengthy as to be virtually unusable. When you execute a report script requiring a select list to produce a printed report, the currently active select list is used to create a temporary table in the analyst account of the appropriate data type and to fill the table with the list of identifiers. The name of this temporary table is then transmitted to the script for an equijoin. The name of the temporary table containing the control list for the report (parameter 2) is indicated in the script by the variable &2. The names of the columns in the temporary table is data type specific. For the wells data type, where a unique well identifier UWI is assigned to each well, the column name is UWI. Example:
TTITLE Project &1. Well Header Data Report Using Control List &2 SELECT UWI,WELL_NAME,WELL_NUMBER,OPERATOR FROM &1..WELL_HDR, &2 B WHERE A.UWI = B.UWI /
Specifying the Select List Name

The name of the original select list (parameter &3) may be included in the title by adding the variable &3 to the text in the TTITLE command.
202
Revised May 2, 2005
Example:
TTITLE CENTER '----> WELL HEADER USING LIST &3 <-----'
If the select list name was WELLS_WITH_LOGS, then the report title would appear as follows.
----> WELL HEADER USING LIST WELLS_WITH_LOGS <-----
This option has been included in the two examples shown above.
Scripts That Do Not Access Project Tables

Scripts designed to access tables other than the various project database tables do not need to use substitution variables, since the ORACLE account name can be explicitly included with the table name for tables in the ESI or CODES accounts, and the analyst tables belonging to the analyst running Finder are selected by default since the analyst is running Finder from his own analyst account.
Storing Scripts Created by the Database Administrator

To supplement the report scripts provided with Finder, the database administrator or project managers at each site are encouraged to generate their own customized sets of site-specific or project-specific scripts based upon their specific site and database needs.
Site-Specific
Project-wide and analyst-wide customized scripts or forms must be stored in the $FINDER_HOME/customized/scripts directory in order to avoid being inadvertently modified or deleted during an update to the Finder software.
Project-Specific
Project-specific customized scripts must be stored in the <project_name>/customized/scripts directory in order to avoid being inadvertently modified or deleted during an update to the Finder software.
Revised May 2, 2005
203
Analyst-Specific
Analyst-specific customized scripts should be stored in the analyst's default directory or in a subdirectory within it. In order to be included in the search path for the current session, the user must be in the directory with these scripts when they run Finder. Alternatively, analyst-level logical names can be defined with will add the users directory to the ESI$SCRIPTS logical name.
Making Scripts Known to Finder

In order to be able to access a script from within Finder, the script must have an entry in the ORACLE_SCRIPTS table. There are two levels of ORACLE_SCRIPTS tables in the Finder database.
System Scope Scripts Table

The ESI.ORACLE_SCRIPTS table in the ESI system account must contain a record for all of the system-wide and site-specific report scripts available to Finder, regardless of whether the scripts were provided with Finder or are site-specific customized scripts added or modified by the database administrator. In other words, every script provided with Finder and stored in either the $FINDER_HOME/scripts directory, or customized by the database administrator and stored in the $FINDER_HOME/customized/scripts directories, must have an entry in the ESI.ORACLE_SCRIPTS table in order to run from Finder.
204
Revised May 2, 2005
Preserving System Scope Scripts Tables During Upgrades

The fact that both the scripts provided with Finder and the customized scripts modified by the database administrator are referenced in the same ESI account table means that any changes made to this table must be saved before running an upgrade installation. The actual report script files, if stored correctly in the $FINDER_HOME or <project_name> customized/scripts directories, remains unharmed. Be sure and follow the procedure outlined in the Finder Installation Guide to prevent removal of references to customized scripts during software installation and upgrades.
Project Scope Scripts Table

Similarly, each <project_name>. ORACLE_SCRIPTS table in each project account must contain a record for each customized project-specific report script available to Finder. Therefore, each script stored in the ESI$PROJECT/customized/ scripts directory should have a record in the project ORACLE_SCRIPTS table. Anyone with insert privileges to the project or DBA privileges can modify to or add to the project ORACLE_SCRIPTS table.
Description of the ORACLE_SCRIPTS Tables

The structure and content of both the system-wide and project-specific ORACLE_SCRIPTS tables are identical. The column descriptions in the ORACLE_SCRIPTS table are shown in table 1 on page 206.
Revised May 2, 2005
205
Table 1: The ORACLE_SCRIPTS table
Column name
NAME
Null or not null

Not Null
Type
VARCHAR2(30)
Description
NAME is the name of the script file, without the .sql or .rpt suffix. DATA_TYPE refers to the data class of the data being reported on (e.g. WELLS, SEISMIC, OTHER). The SCRIPT_TYPE field contains the application that was used to produce the report. ORAREP2 (Oracle report without parameters) ORAREP2_P (Oracle report with parameters) SCOUT SQLPLUS
DATA_TYPE
Not Null
VARCHAR2(30)
SCRIPT_TYPE
Not Null
VARCHAR2(10)
CONTROL_LIST _REQUIRED
Not Null
VARCHAR2(1)
The CONTROL_LIST_ REQUIRED field is used to determine if the report script has been designed to make use of a current select list.
DESCRIPTION
Not Null
VARCHAR2(240)
The DESCRIPTION field allows for a text description of the report to elaborate on what the report produces. When accessing the report while running Finder, you select the report from the list of available report scripts based upon the information contained in the first 60 characters of the DESCRIPTION. Therefore you should limit the length and content of your DESCRIPTION accordingly.
206
Revised May 2, 2005
Accessing the Scripts Table

You may use pre-defined Finder reports or your own SQL commands to examine or print out a listing of either the system-wide, or the projectspecific scripts. If you use your own SQL commands, the descriptions of report scripts that you see depend upon whether you are accessing the ESI.ORACLE_SCRIPTS table or one of the project-specific <project_name>.ORACLE_SCRIPTS tables. If you execute the ORACLE Scripts report from Finder, you see the reports in both the ESI and the appropriate <project_name>.ORACLE_SCRIPTS tables.
Updating the ORACLE_SCRIPTS Table

This is the procedure to update or add an entry to the ORACLE_SCRIPTS table. 1. Use the oform utility to run the ORACLE_SCRIPTS form.
<PROMPT>: oform oracle_scripts <account>/<password>
Note:
To add or modify an entry in the ESI system account tables, start up the form using the ESI account. To add or modify an entry in one of the project tables, start up the form using the project account. 2. Enter the appropriate values for the parameters in the ORACLE_SCRIPTS form, and commit the changes. Regardless of which technique you use to update the appropriate ORACLE_SCRIPTS table, the result is the same. The next time you start up the Finder database, the description of the newly entered or modified report script or form should appear in the list of scripts available to you (see "Accessing the Scripts Table" on page 207).
Troubleshooting Script Customization

There are a few common problems associated with customizing scripts. These are included below.
The New Script Does Not Appear in the List of Scripts

This can arise for the following reasons.
Revised May 2, 2005
207
The file is not in one of the directories referenced by the ESI$SCRIPTS logical name in Finder. The ESI$SCRIPTS logical name is defined incorrectly. The script is not referenced in the ORACLE_SCRIPTS table of the current project or the ESI account. The script is named using upper case letters. The root file names are entered in uppercase letters in the ORACLE_SCRIPTS form.
The New Script Does Not Appear in Use Default Select List
The new script is present with All Items checked, but not when Use Default Select List is checked. Scripts that use select lists are different from scripts that do not. They need to be treated independently. "Specifying a Temporary Control List" on page 201 describes how to use the parameters passed to the script at run time to limit the retrieval to the current select list. It requires the following steps. 1. Copying the original script.
2. Adding some information to the FROM and WHERE clauses of the SQL statement. 3. Making a new entry in the ORACLE_SCRIPTS table with the Control List Reqd field set to Y.
Customizing Finder ORACLE Reports

Finder also delivers reports created with the Oracle Reports utility. This utility is used to create, compile, run, and save a new report. Although the general rules for report customization remain the same, there are differences in the procedure for report design and the location in which reports are stored. It is beyond the scope of this volume to describe in detail how to use Oracle Reports. For complete details and a tutorial on using the advanced features of Oracle Reports, you are referred to the ORACLE documentation on reports.
ORACLE Reports File Formats

The Oracle Reports utility creates and saves forms in three different file formats but only one of these is distributed with Finder. Each of the formats has a specific purpose in form creation, modification and operation. Two are shown below in table 2.
208
Revised May 2, 2005
Table 2: Oracle Reports file formats
File format
Report binary .REP Report Text .REX
Purpose
The executable version of the report. The text version of the report source file.
Example
$FINDER_HOME/reports/project/ <report_name>.REP
Not currently delivered with Finder.
The procedure for modifying or creating your own Oracle Reports is similar to that for Oracle Forms (see "Updating Custom Forms" on page 211 and the ORACLE documentation). After an Oracle Report has been created or modified, and then compiled, save it into $FINDER_HOME/customized/reports/project. From this directory it will be available for any/all projects.
Revised May 2, 2005
209
Customizing Forms in Finder

Introduction
The Finder database administrator can create custom forms and add them to the available Finder reporting facilities using methods described in this chapter. Before you begin to customize forms, please familiarize yourself with the Introduction section of this chapter. The ORACLE utility Oracle Forms is used to create, compile, run, and save a new form. Oracle Forms offers powerful (and potentially dangerous) tools which should only be used by an experienced database administrator. It is beyond the scope of this volume to describe in detail how to use Oracle Forms. For complete details and a tutorial on using the advanced features of Oracle Forms, see the ORACLE documentation about forms. You will see two different looks to the forms as we gradually implement a new look and feel. The forms can be easily distinguished by their user interfaces. Just for the purpose of distinguishing between the two types of forms, the older forms are referred to as Oracle Forms and the new forms are referred to as GeoQuest Forms. The tasks of creating new custom forms and updating custom forms are described for each type of form in their respective sections that follow.
Oracle Forms
Forms Provided with Finder
The files for project and system forms provided with Finder are stored in the $FINDER_HOME/forms/project and $FINDER_HOME/forms/ system directories, respectively, when the Finder software is installed or updated. Each form in this directory must have an entry in the ESI.ORACLE_FORMS table in order to be executed from Finder. Do not modify or add forms in these directories since the form definition files may be modified or deleted during the next Finder software installation or update. The files for customized forms added or modified by the site database administrator must be stored in the $FINDER_HOME/customized/ forms/project or $FINDER_HOME/customized/forms/system directories. Each form in these directories must have an entry in the ESI.ORACLE_FORMS table in order to be executed from Finder.
210
Revised May 2, 2005
File Formats
The ORACLE Forms Designer creates and saves forms in several file formats, each of which has a specific purpose in form creation, modification and operation. Two of these are shown below in table 3.
Table 3: Oracle Forms file formats
File format
Form Module Binary .FMB Form Module Executable .FMX
Purpose
The source file for the form. Use ORACLE Forms Designer to open this file and modify the form. The executable version of the form.
Example
Not currently delivered with Finder.
$FINDER_HOME/forms/project/ <form_name>.FMX $FINDER_HOME/forms/system/ <form_name>.FMX
Creating New Custom Forms

New custom forms should be created using the GeoQuest Form templates that are provided with Finder. Please refer to "Creating New Custom Forms" on page 214 for more information on using the GeoQuest Form templates to create new custom forms.
Updating Custom Forms

1. Change to the directory where the form file is stored. Example:
<PROMPT>: cd $FH/customized/forms/project
2. Run the ORACLE Forms Designer and edit the form. <PROMPT>: f60desm See the Oracle documentation on forms for instructions on using the Forms Designer. Site-customized forms may be referred to project-specific tables or other Oracle objects using the ALTER SESSION Oracle command, or through synonyms. If your site has custom forms that use synonyms to refer to tables or objects, set
Revised May 2, 2005
211
USE_SYNONYMS = YES. Setting USE_SYNONYMS = YES generates synonyms at the start of each Finder session. These are of the form F_<object_name>, e.g., F_WELL_HDR. 3. When you are satisfied with your changes, use the Form Designer to generate the form. This process creates and saves the executable file, <form_name>.FMX, for the form. 4. Save the source file, <form_name>.FMB, for the form and then quit the Form Designer. 5. Run Finder and test the form. If there a problems, exit Finder and repeat steps 3, 4, and 5 until the form is satisfactorily modified.
Year 2000 Updates

See "Year 2000 Updates" on page 216.
GeoQuest Forms
Forms Provided with Finder
The following forms have been updated in accordance with the GeoQuest Oracle Form Human Interface Style Guide: Well Data Forms Seismic Data Forms
The files for project and system forms provided with Finder are stored in the $FINDER_HOME/forms/project and $FINDER_HOME/forms/ system directories, respectively, when the Finder software is installed or updated. Each form in this directory must have an entry in the ESI.ORACLE_FORMS table in order to be executed from Finder.You can use these forms as examples when you create your own custom forms. In addition, we provide template files in the $FINDER_HOME/forms/ common directory that you can use to create your new forms. The template files are: gdm.pal - standard color palette file gdm_template.fmb - form template gdm_template.mmb - menu template
212
Revised May 2, 2005
Note:
gdm_template.pll - library template
Do not modify or add forms in the $FINDER_HOME/forms/project, system, or common directories since the form definition files may be modified or deleted during the next Finder software installation or update. The FMX files for customized forms added or modified by the site database administrator must be stored in the $FINDER_HOME/customized/ forms/project or $FINDER_HOME/customized/forms/system directories. Each form in these directories must have an entry in the ESI.ORACLE_FORMS table in order to be executed from Finder.
File Formats
There are several file formats associated with the GeoQuest forms. These are shown below in table 4.
Table 4: GeoQuest Forms file formats
File format
Form Module Binary .FMB Form Module Executable .FMX .PAL
Purpose
The source file for the form. Use ORACLE Forms Designer to open this file and modify the form. The executable version of the form.
Example
$FINDER_HOME/forms/common/ gdm_template.fmb See "finder_template.fmb" on page 221 for more information about this form. $FINDER_HOME/forms/project/ <form_name>.FMX $FINDER_HOME/forms/system/ <form_name>.FMX
The file containing the color palette which you can use to set the form colors. The file containing the default menu definition. The library file.
$FINDER_HOME/forms/common/ gdm.pal
.MMB .PLL
$FINDER_HOME/forms/common/ gdm_template.mmb $FINDER_HOME/forms/common/ gdm_template.pll
Revised May 2, 2005
213
Creating New Custom Forms

Example forms have been provided for the Wells and Seismic data types. You can add new forms to use in the Wells and Seismic data type or you can use the Wells and Seismic forms as examples to create forms for other data types. 1. Change to the directory where the form file is to be stored. Example:
2. Run the ORACLE Forms Designer and create the new form. <PROMPT>: f60desm See the ORACLE forms documentation for instructions on using the Forms Designer. Site-customized forms may be referred to project-specific tables or other Oracle objects using the ALTER SESSION Oracle command, or through synonyms. If your site has custom forms that use synonyms to refer to tables or objects, set USE_SYNONYMS = YES. Setting USE_SYNONYMS = YES generates synonyms at the start of each Finder session. These are of the form F_<object_name>, e.g., F_WELL_HDR. 3. When you are satisfied with your changes, use the Form Designer to generate the form. This process creates and saves the executable file, <form_name>.FMX, for the form. 4. Save the source file, <form_name>.FMB, for the form and then quit the Form Designer. 5. If you want to add the new form to the list as displayed in the Forms dialog, use SQL*Plus to add the new form to the ESI.ORACLE_FORMS table. Add the NAME, TYPE and DESCRIPTION fields for the form. 6. If you want to add the new form to the Forms menu of an existing form, edit the appropriate .mmb file. Create a new .mmb file if there is not an appropriate one to edit. See "Edit the .mmb file" on page 215 for more information. 7. Update the list of available forms. See "Update the List of Available Forms" on page 218 for more information.
214
Revised May 2, 2005
8. Run Finder and test the form. If there a problems, exit Finder and repeat steps 3, 4, 5 and 6 until the form is satisfactorily modified.
Edit the .mmb file

Edit the .mmb file when you need to add a new form to the list in the Forms menu. In the following scenario, you have created a new form that you want to add to the Forms menu in the main Well Data form. 1. Make sure that you have added the new form to the ORACLE_APPLICATION_LIST table in the project scope and make note of the sequence number. 2. Change to the directory where the custom menu file is stored. Example:
3. Run the ORACLE Forms Designer to edit the .mmb file. <PROMPT>: f60desm See the ORACLE forms documentation for instructions on using the Forms Designer. Site-customized forms may be referred to project-specific tables or other Oracle objects using the ALTER SESSION Oracle command, or through synonyms. If your site has custom forms that use synonyms to refer to tables or objects, set USE_SYNONYMS = YES. Setting USE_SYNONYMS = YES generates synonyms at the start of each Finder session. These are of the form F_<object_name>, e.g., F_WELL_HDR. 4. Add a new menu item in the WELL_DATA_MENU by copying and pasting FORM12 item. 5. Rename the new FORM12 item to FORMxx where xx is the form sequence number in the ORACLE_APPLICATION_LIST table. 6. Update the label to xx. 7. Update the COMMAND_TEXT property to use xx.
Revised May 2, 2005
215
Updating Custom Forms

1. Change to the directory where the form file is stored. Example:
2. Run the ORACLE Forms Designer and edit the form. <PROMPT>: f60desm See the ORACLE forms documentation for instructions on using the Forms Designer. Site-customized forms may be referred to project-specific tables or other Oracle objects using the ALTER SESSION Oracle command, or through synonyms. If your site has custom forms that use synonyms to refer to tables or objects, set USE_SYNONYMS = YES. Setting USE_SYNONYMS = YES generates synonyms at the start of each Finder session. These are of the form F_<object_name>, e.g., F_WELL_HDR. 3. When you are satisfied with your changes, use the Form Designer to generate the form. This process creates and saves the executable file, <form_name>.FMX, for the form. 4. Save the source file, <form_name>.FMB, for the form and then quit the Form Designer. 5. Run Finder and test the form. If there a problems, exit Finder and repeat steps 3, 4, 5 and 6 until the form is satisfactorily modified.
Year 2000 Updates

1. If your form does not already have the FINDER_GENERAL_LIB attached, you should attach it. 2. Create a parameter in your form that will be used to hold the date format string. 3. Call the foreign function fi_get_date_fmt from within the trigger, WHEN_NEW_FORM_INSTANCE. The value returned by the function should be assigned to the parameter you defined in step 2.
216
Revised May 2, 2005
Example:
:parameter:my_date_format := ffi_get_msg.fi_get_date_fmt
4. Use the date format in this parameter to set date fields to use this date format. Example:
Set_Item_Property ( block.item.name, FORMAT_MASK, :parameter:my_date_format);
If the date format for a particular field includes hours and minutes, you should concatenate the two parts of the date format. Example: If the date format is like HH24:MI YYYY-MM-DD, then:
Set_Item_Property ( block.item.name, FORMAT_MASK, HH24:MI || :parameter:my_date_format);
5. Switch off the AUTO_HINT property. You will still see your hint but it will also show the users date format as well. (See step 7.) Example:
Set_Item_Property ( block.item.name, AUTO_HINT, :parameter:my_date_format);
6. Check the item property query length and the max length. If either are set, you should add 2 to each to accommodate the extra 2 digits in the year. 7. Add a WHEN_NEW_ITEM_INSTANCE trigger or use the existing one to make the following function call:
CHECK_DATE_DATATYPE ( :system.cursor_item, :parameter.date_format );
This will display any AUTO_HINT text with the date format appended to the end of the AUTO_HINT text. If your AUTO_HINT text has a date format included, you should remove it. If there is a hard-coded format mask for any date fields, you should remove that as well.
Revised May 2, 2005
217
The Application Management Database

Introduction to the Application Management Database
The application management database is used to track the forms that are called from within other forms. This is to allow one form to be used as menu for one or more other forms and to allow for the sequencing of the forms in the menu in any order desired. There are two tables that make up the oracle application management database. These are: ORACLE_APPLICATIONS ORACLE_APPLICATION_LIST
In addition, the view, ORACLE_APP_SELECTION, is defined to facilitate the selection and updating of file names within the forms. Please refer to the Data Dictionary for more information about the ORACLE_APPLICATIONS and ORACLE_APPLICATION_LIST tables and for more information about the ORACLE_APP_SELECTION view.
Update the List of Available Forms

The ORA_APP_MAINT form is used to change lists of available forms. This form is described in "ORA_APP_MAINT Form" on page 219. To update the list of available forms, follow these steps. 1. Start the ORA_APP_MAINT form and execute a query in the upper block.
<PROMPT>: oform ora_app_maint projectname/password
2. With the cursor on the entry for the well_hdr form, select Record >> Insert from the form menu. A blank record is opened up below the well_hdr record 3. Select Field>>Duplicate on the form menu and TAB to create a second entry for the well_hdr form. Be sure to change the DISPLAY field to something different to describe the new list. 4. Select Action>>Save on the forms menu and note the new APPID.
218
Revised May 2, 2005
5. Select Block >> Next on the form menu to move to the lower block on the form. 6. Enter records for the new list of forms using the APPID of the new well_hdr record as the PRIMARY_ID.
Reference
ORACLE_APP_SELECTION View
SQL> CREATE VIEW ORACLE_APP_SELECTION AS SELECT PRIMARY_ID,DISPLAY,FILE_NAME,TABLE_NAME, WHERE_CLAUSE, SEQ FROM ORACLE_APPLICATIONS A, ORACLE_APPLICATION_LIST L WHERE L.SECONDARY_ID = A.APPID;
The main table is ORACLE_APPLICATIONS, which stores the filename to the form and a display name to use in lists of forms for the user. Both the control forms and sub-forms are listed in this table. In principle the IAP_ACTION field is used for the keyword used within forms to access the sub-form. The ORACLE_APPLICATION_LIST table is used to make the correspondence between the menu form and the data forms that make up the options in the menu. The PRIMARY_ID field is used to specify the APPID of the menu form as listed in the ORACLE_APPLICATIONS table. The SECONDARY_ID field is for the APPID of the sub-forms to be listed in the menu form. The SEQ column is used to order the items listed in the menu. The ORACLE_APP_SELECTION view is used to facilitate menu processing by putting all the elements necessary for a menu into a single access point. This allows you to define a block for a menu which accesses the view and has the display name and sequence numbers all available for maximum control over the menu.
ORA_APP_MAINT Form
The ORA_APP_MAINT form is used to change lists of available forms. The ORA_APP_MAINT form has two blocks. The upper block accesses the ORACLE_APPLICATIONS table and contains all the information required about both menu forms and data forms to execute them in the context of being run from within another application. The lower block access the ORACLE_APPLICATION_LIST table and is used to enter the information that ties a data form to a menu form.
Revised May 2, 2005
219
The APPID listed in the upper block for the menu form is used as the PRIMARY ID in the lower block for each data page that appears in the menu, whose APPID should be entered in the SECONDARY ID field. Table 5 and table 6 summarize the function of the fields in these two blocks.
Table 5: Upper block of the ORA_APP_MAINT form
Item
APPID
Description
The APPID field is simply a sequence number used to identify the forms listed in this table. It is automatically generated when you enter a new record. The path name to the executable file for the form to be run. If this file is being run from the Well Information Forms, only the root name of the form is required, the rest of the path is added by the calling form using the ADDPATH ffi. If you are not using the Finder ADDPATH ffi in the menu form calling this form, specify the full path to the form. This is the Display name to be presented to the user in the menu form. This is meant to be the command used from within a form to call this form. Menu forms should have the HOST keyword inserted and data forms called from a menu form should have either CALL, CALLQRY, or NEWFRM depending on the desired action.
FILE_NAME
DISPLAY IAP_ACTION
Table 6: Lower block of the ORA_APP_MAINT form
Item
PRIMARY_ID SECONDARY_ID
Description
The APPID of the menu form is entered here. The APPID of the data form that appears in the menu when the form indicated by the PRIMARY_ID field is executed. The sequence number used to order the data forms in the menu. If used simply for ordering, keeping the numbers in strict sequence is not important. If used also as part of the form navigation logic, as is the case for the Well Information forms, then the values of SEQ should be in an uninterrupted sequence for each PRIMARY_ID.
SEQ
220
Revised May 2, 2005
finder_template.fmb
The finder_template.fmb file is based on the gdm_template.fmb file. The finder_template.fmb file contains default building blocks that can be reused in other forms. The default building blocks can be referenced in new forms by using the following object groups: balloon_help - fly out balloon annotation control_form_parameters - default control form parameters char_item - character property classes for well forms and seismic forms map_link_items and external_parameters - default list of items required for map interaction when using ffi query_restriction - default query restriction block for map interaction used with well and seismic forms std_well_hdr - standard header for well forms well_numeric_items - numeric property classes for well forms items well_tool - the standard tool bar for Finder forms
gdm_template.fmb
If you want to build a form that is not Finder specific, you may want to use the following object groups which can be found in the gdm_template.fmb file: balloon_og - contains balloon help objects. In order to implement the default functionality provided by the gdm_template.fmb file, you also need to use the form_level_trigger_og object. form_level_trigger_og - use only with balloon_og to implement the default functionality provided by the gdm_template.fmb file. If you want to modify the triggers functionality, you will need to write your own code. property_og - contains the property classes and visual attributes property_class_og - default item property classes tool_og - contains the tool block and tool_bar canvas required if you want to reference the toolbar as a whole
Revised May 2, 2005
221
Foreign Function Interface (ffi)

Oracle Forms and Reports allow for access of external or foreign functions through the Foreign Function Interface (ffi) architecture. Such routines are typically written in languages such as C and packaged in shared libraries (.so). The ffi functionality supports access to these functions via PL/SQL wrapper routines contained in Forms, Reports, or related forms libraries (.pll). The external functions are packaged in User_Exit_Lib.pll and libora_user_exits.so. The .pll file defines a package called ue_select_item which contains all of the foreign functions. Use the following syntax to call the foreign functions:
ue_select_item.<name of ffi> (params) for ex to invoke dd_transform_point_ffi ffi_point := ue_select_item.dd_transform_point_ffi(src_proj,src_x,s rc_y,tgt_proj,tgt_x,tgt_y);
The foreign functions and their descriptions are listed below: DD_GET_FULL_PATH - This ffi expands any logical names and creates the full path for a filename. The function prototype is:
dd_get_full_path_ffi (CHAR CHAR CHAR CHAR ) *logical_name, *result_field, *project, *user
If any : exists in the input string, it is replaced with a /

result_field is the expanded logical_name
DD_GET_OS - This ffi returns a string identifying the current operating system. The function prototype is:
dd_get_os_ffi (char *result_field)
DD_CHECK_LICENSE - This ffi will reserve or release a license for a given feature. The function prototype is:
dd_check_license_ffi (char *operation, char *feature, char *result_field )
222
Revised May 2, 2005
where:
operation is REQUEST or RELEASE feature is License name result_field returns status
DD_FILE_DIALOG - This ffi will let the user select a filename from a Motif dialog. The function prototype is:
dd_file_dialog_ffi(char char char char char ) *default_path, *default_file, *default_type, *return_full, *return_type
where:
default_type is THIRD-PARTY or any file_type from
the fm_hdr table DD_SELECT_LIST - This ffi will make Finder perform one of the following operations on a supplied select list: MAKE_MAP_SELECTED - makes the select list the selected items on the map, and highlights them with the picking highlight style. APPEND_CURRENT - inserts the select list into List Assistant. REPLACE_CURRENT - replaces the current list in List Assistant. HIGHLIGHT - activates the highlight list dialog, which will let user highlight select list. SAVE - saves the given select list with the given name overwriting any previous select list with the same name. BOUNDED_BY - performs a spatial query and retrieve all objects bounded by the given objects from either the current map or the database. (Similar to the bounded by feature in List Assistant.)
The function prototype is:

dd_select_list_ffi (char *form_list_name, char *form_param )
Revised May 2, 2005
223
where:
form_list_name is the select list name output parameter. form_param is in the form of operation_name [operation_specific_params] type_name
when:
operation_name is one of the following, no [operation_specific_params] are required:
MAKE_MAP_SELECTED APPEND_CURRENT REPLACE_CURRENT HIGHLIGHT SAVE

type_name is the type of the select list
for example:
ffi_select := ue_select_item.dd_select_list_ffi (my_select_list, HIGHLIGHT wells );
OR when:
operation_name is:
BOUNDED_BY, the operation_name prototype is:

BOUNDED_BY <bounding_datatype> <datatype_to_get> [DATABASE or MAP] [MAP_SELECTED or LIST <list_name>]
type_name is the type of the select list
for example:
ffi_select := ue_select_item.dd_select_list_ffi (my_select_list, BOUNDED_BY lease wells map map_selected wells );
224
Revised May 2, 2005
DD_TVD_TO_MD - This ffi will convert TVD to MD. The function prototype is:
dd_tvd_to_md_ffi (char *uwi, float tvd, float *in_dx, float *in_dy, float *in_md )
where:
in_dx, in_dy, and in_md are output parameters
DD_MD_TO_TVD - This ffi will convert MD to TVD. The function prototype is:
dd_md_to_tvd_ffi (char *uwi, float md, float *in_dx, float *in_dy, float *in_tvd )
where:
in_dx, in_dy, and in_tvd are output parameters
DD_DIGEXIT - This ffi will get the x and y coordinates of a well. The function prototype is:
dd_digexit_ffi (CHAR CHAR CHAR CHAR CHAR ) *xfield, *yfield, *object_name, *plot_symbol, *color
where:
xfield is the name of the field which contains X yfield is the name of the field which contains Y object_name is the name of the new graphic object plot_symbol is the name of the plot symbol code color is the name of the color (as text)
Revised May 2, 2005
225
DD_WLINFO_XIT - This ffi will delete a well from the FInder well cache and force a reload. This is used when you are changing well information in a form and you want to see the updated information on the map. The function prototype is:
dd_wlinfo_xit_ffi (char *uwi)
DD_GET_MAP_SELECTED_ITEMS - This ffi will dump the selected items from the current map into the temp tables. The function prototype is:
dd_get_map_selected_items_ffi (char *list_name, char *datatype )
where:
list_name is an output parameter
DD_GET_MAP - This ffi returns the name of the map. The function prototype is:
dd_get_map_ffi (char *result_field)
DD_GET_XS - This ffi returns the name of the cross section layout. The function prototype is:
dd_get_xs_ffi (char *result_field)
DD_GET_SEIS_3D_BIN_PTY - This ffi lets the user pick a point in a survey from the map and returns the values of survey_code, inline_number, cross_line_number, x and y. The function prototype is:
dd_get_seis_3d_bin_pty_ffi (char char char char char ) *srvy_code, *inline, *xline, *x, *y
226
Revised May 2, 2005
DD_XS_ADD_MARKER - This ffi adds the specified marker to the cross section data structure to communicate between the forms and smart section. This cannot be called from standalone forms. The function prototype is:
dd_xs_add_marker_ffi (CHAR *string)
DD_SEHORLD - This ffi is used to save, load and purge seismic horizons. The function prototype is:
dd_sehorld_ffi (char char char char char char char char char ) *option, *line_id, *digital_ref, *digital_ref_volume, *version, *surface_code, *surface_type, *data_type, *source
DD_LOAD_SLIST tables.
- This ffi loads a select list to the TEMP
The function prototype is:

dd_load_slist_ffi (char *data_type, char *sl_state, char *slist )
where:
sl_state can be NAMED, MAP or CURRENT slist is the name of the select list
(applicable only if sl_state = NAMED)
Revised May 2, 2005
227
DD_TRANSFORM_POINT - This ffi transforms the given point in a given projection to corresponding point in the target projection. The function prototype is:
dd_transform_point_ffi (char char char char char char *src_projection, *src_x, *src_y, *tgt_projection, *tgt_x, *tgt_y)
if src_projection is GEODETIC, then src_x and src_y are LONGITUDE and LATITUDE
tgt_x and tgt_y are output parameters
DD_GET_APP - This ffi passes back the name of the application which calls the form. The function prototype is:
dd_get_map_ffi (char *result_field)
DD_RUN_PROCESS - This ffi can be used to launch any process.

dd_run_process_ffi (char char char char char CHAR CHAR ) *process, *pw, *type, *survey, *log_file_from_form, *project, *user
The ffi will invoke different functions based on type of the process to be run. Currently the only type supported is LCC_TYPE and the only process supported is s3_db_maint.
228
Revised May 2, 2005
Customizing Select Phrases

Introduction
The Relational Retrieval function of the List Assistant command on the Applications menu allows you to display a list of pre-defined select phrases and to select one of them for use in limiting your retrieval. Also, the data posting label position options in the Wells overlay supports predefined select phrases. The select phrases displayed are stored in a SELECT_PHRASES table in the ESI ORACLE account. To add to or modify a select phrase in this table, the database administrator uses the Select Phrase Manager. Use the Select Phrase Manager to create new select phrases or to customize existing select phrases. The Select Phrase Manager is started from the Finder >> Utilities menu and is documented in the Utilities chapter of the Finder Users Reference.
The Select Phrase Macro Language

In addition to the simple SQL select phrases, Finder provides a simple macro language that can be used to prompt the user for input and then generate the correct select phrase based on that input. The basic syntax is as follows: The macro commands are contained in double angle brackets (<< >>). The general format is <<Prompt|SUBTITUTION/LOOK-UP OPTION>>. The keywords allowed for the SUBTITUTION/LOOK-UP OPTION portion of the construct are shown in table 7 on page 230.
Revised May 2, 2005
229
Table 7: SUBSTITUTION/LOOKUP keywords in select phrase macro language
Item
PROJ ANAL TLU=<table>,<column> MARK
Description
The name of the current project is substituted here. The name of the current analyst is substituted here. Provide a look-up list by selecting the distinct values for the column from the specified table. Call the Marker Selection dialog to construct the appropriate portion of the SQL Where clause.The <prompt> string must be either Surface or Layer. Call the Marker Selection dialog to construct the appropriate portion of the SQL Where clause.The <prompt> string must be either surface or layer. Column names will be prefixed with synonym The primary key is substituted here in label select phrases. See Example 6: on page 232.
MARK=<synonym>
KEY_VALUE
Example 1:
SURFACE_CODE = '<<Horizon Code>>'
This is the simplest case. You are prompted for a horizon code to be substituted in between the single quote marks. Example 2:
SURFACE_CODE = '<<Horizon Code>>' AND SOURCE = '<<Analyst ID|ANAL>>'
In this example, you are prompted for a horizon code as in example 1, but not prompted for the Analyst ID because the prompt is satisfied by the ANAL keyword to the right of the vertical bar(|). Your Analyst ID is automatically substituted in the appropriate place. Example 3:
SURFACE_CODE = '<<Horizon Code| TLU=PROJ.SEIS_HOR_CODES,HOR_CODE>>'
230
Revised May 2, 2005
This is an example of the use of the table look-up function (TLU). Note that there are no spaces between the vertical bar(|), the TLU keyword, the equality symbol (=), and the table and column specification. Including spaces confuses the macro processor and the macro does not work. Also note the use of the PROJ keyword before the table name. This allows the same select phrase to be used in any project. Example 4:
TOP_FORM = '<<Formation Code| TLU=PROJ.LAYER_HDR,LAYER_NAME>>' AND BASE_FORM = '<<Formation Code>>'
Here you are prompted for Formation Code with a look-up list available. Your response is used for both the first substitution and for the second one too, since the spelling of the prompt is exactly the same. In this case the prompt acts as a variable which, once assigned, can be used as many time as is necessary. This is the case for all prompts in the select phrase macro language. Example 5:
UWI IN (SELECT DISTINCT T.UWI FROM <<Project|PROJ>>.WELL.SURFACE_PICK T, <<Project_name>>.WELL_CORE_HDR C WHERE T.UWI = C.UWI AND T.MD BETWEEN C.TOP AND C.BASE AND <<Surface|MARK=T>>
This is an example of a join between the WELL_SURFACE_PICK and WELL_CORE_HDR tables to select a list of UWIs. As above, the project name is prefixed onto the table names. However, the Marker Selection dialog is called so that you can choose a surface. The following substitutions are made for <<Surface|MARK=T>> by the macro processor in the resulting SQL phrase.
T.SURFACE_NAME = name AND T.STRAT_SCOPE_ID = id
These examples illustrate the key points on using the select phrase macro language. There are many more examples that show more complex select phrases and macro constructs in the SELECT_PHRASES table. Scroll through the existing select phrases and familiarize yourself with these examples for more ideas on how to construct select phrase macros.
Revised May 2, 2005
231
Example 6:
select DOCUMENT_ID || , || DOCUMENT_VERSION from <<PROJECT|PROJ>>.DOCUMENT_LINK where OBJECT_KEY={KEY_VALUE} and DATA_TYPE =WELLS
Select Phrase Variables

The select phrase macro language has been enhanced with special variables called select phrase variables. Phrase variables referenced in a select phrase have the following syntax:
$(VARIABLE)
Example:
select uwi from $(PROJECT).well_hdr where crstatus = $(STATUS)
Here $(PROJECT) and $(STATUS) represent phrase variables that are bound to specific values in the database. The same value is applied to all select phrases that use the variable. If a change is made to the value of the variable, the new value would apply to all phrases that use it. Please refer to the Select Phrase Variables section in the Introduction to the Utilities Menu chapter of the Finder User's Reference for information on how to change the value of a phrase variable and how to view/create phrase variables. Phrase variables can be used along with substitution variables, described above, in the same select phrase. For example:
select uwi from $(PROJECT).well_hdr where SURFACE_CODE = '<<Horizon Code>>'
Protecting Customized Select Phrases

Because the SELECT_PHRASES table is in the ESI account, anything in it is susceptible to deletion or modification if the select list name happens to be the same as a select list provided with Finder, or possibly added at a later Finder upgrade. Therefore, to protect your customized select phrases, adopt a naming convention which ensures that the names you assign to the select phrases you add or modify are different from the names of the select phrases provided and maintained with Finder.
232
Revised May 2, 2005
A more dependable method of isolating customized select phrases from ESI's select phrases will be implemented in a future Finder upgrade.
Troubleshooting Select Phrases

This section covers problems that might be encounter when customizing select phrases.
The Table Look-up Function Does not Work Description

A TLU command was specified in the select phrase, but the Choose From List of Options button did not activate in the SQL Query Options dialog which prompts for the value. In some cases the button appears active, but when pressed, the SQL Query Options dialog is closed and no further processing on the select phrase is done.
Solution
The problem is probably that you put spaces between the arguments in the TLU clause. From the vertical bar to the end of the statement, any spaces will cause the parser to fail and will result in the TLU function not working. Simply editing the select phrase and removing any spaces will fix the problem. This includes leading spaces in the prompt and trailing spaces between the macro function text and the right angle brackets.
Multiple Table Look-ups Do not Work Description

In select phrases with two or more TLU phrases, it appears to skip some of the prompts. It appears as though it takes the value for the first prompt and puts it in for the subsequent prompts.
Solution
The SQL Query Options dialog is not re-initialized between prompts. The prompt text is simply updated. This means that the list of values brought up for the previous prompt will still be active in the scrolling selector and the previous value will still appear in the text box. If the Enter button is clicked twice, the same value will be entered for the first and second
Revised May 2, 2005
233
prompts. Be sure you click the Enter button only once and check the prompt text for the change to be sure that the additional TLU statements are working.
An Error When Processing Select Phrase Variables

This can happen for a number of reasons: a. The phrase variables name is malformed. For example, the variable name contains illegal characters, such as: or ). b. The phrase variable is undefined. Refer to the information in the Finder Users Reference concerning how to view Select Phrase Variables and their values. c. The phrase variable is defined but could not be resolved using the search mechanism. This is described in the Troubleshooting section in the List Assistant chapter of the Finder Users Reference. d. The phrase variable has a value that is illegal or malformed when used in an SQL statement.
234
Revised May 2, 2005
Customizing Document Storage

Introduction
The Finder Document Management facility allows users to store electronic documents in the Finder database and to associate those documents with a location on a map. The format of these document files is not limited; they can be text, graphics, images, or any other information related to a project. They can be created in any third-party software application as long as the application is registered with Document Management. The information that Finder needs to be able to store the documents is entered through the document_hdr form by the users. Most of this information can also be included within the document in the document header and be read directly into Finder by a scanner program. You, as the database administrator, write and maintain the scanner programs. The details of the output format for the scanner programs are explained later in this section. Each document can have a viewing application that is registered with Document Management by the database administrator. In addition, you define the file type codes and the file format codes for the documents. The details for these tasks are described later in this section.
License Requirements
The following software licenses are required for the Document Management facility to store documents and view them: Finder_document The license for the Document overlay. This will allow you to see which locations on a map have documents associated with them. Finder_EDM The license for the document_hdr form. This will allow you to register, load, and export documents. A valid license for each third-party viewing application. This will allow the stored documents to be displayed.
Registering Document Viewers and Scanners

When a document is registered with Document Management, the user must specify the application that is used to view it. Before Document Management will accept the entry of a viewer application, you must make an entry for the viewer on the EDM Administration form. Likewise, if a scanner program will be used to read information about a document into
Revised May 2, 2005
235
Document Management, you must make an entry for the scanner on the EDM Administration form. Write access in this form is restricted to the Finder database administrator whose analyst account name is ESI. You must also define a file format code for the document before it is registered with Document Management. See "Defining Document File Format Codes" on page 239 for a description of how to define file formats.
EDM Administration Form

The EDM Administration form allows you to register: viewer applications for displaying documents scanner applications that load documents using the information in the document header third-party editor applications to edit plot files
Here are the steps for accessing the EDM Administration form to register applications: 1. Select Applications>Forms from the Finder menu bar. The Forms dialog is displayed. 2. Select Database Administration in the Datatype option menu. The dialog lists entries for the forms you can launch. 3. Select EDM Viewer/Scanner Setup; then click the Apply button. The EDM Administration form is displayed. 4. Click the Insert button. 5. Enter the appropriate information in each field. You must use the horizontal scroll bar to display all the fields. See table 8 on page 237 for a description of the fields and their valid entries. 6. Click the Save button. 7. Click the Exit button.
236
Revised May 2, 2005
Table 8: Special notes on the EDM Administration form
Field
Sort by Viewer ID Platform
Remarks
The column on which the information display is sorted, in ascending order. The default is Viewer ID. Identification number of the viewer. This field cannot be updated. The name of the operating system on which Finder is running, for example SunOS 5.8. On UNIX machines, the command uname -a will display the OS version. Previously entered platforms may be picked from a list of values. The context of the electronic document. This is the only field where the entry differs between a viewer and a scanner. If registering a viewer, enter ACCESS. If registering a scanner, enter SCANNER. If registering an editor, enter EDIT
Context
Media Format
Always ON-LINE. The format of the electronic document file, for example, ASCII. Previously entered formats may be picked from a list of values, which was created by the entries in the File Format form. The location scope of the electronic document; the highest subdirectory for which this viewer should be involved. The host command that specifies and starts the viewer application, for example, vi. Arguments to be placed before the document file name when the command is submitted; for example, -bg white -fg black. In a UNIX application this will set the background display to white and the foreground display to black. An entry in this field is optional. Arguments to be placed after the document file name when the command is submitted; for example, &. This will run a UNIX application in background. An entry in this field is optional.
Scope Command Before file name
After file name
Defining Document File Type Codes

Before you can enter a file type on the document_hdr form, you must define it on the file_type form.
Revised May 2, 2005
237
Figure 2: The file_type form
Here is how to define the file type codes for Document Management: 1. Select Database Administration data type on the Forms dialog box. 2. Select the File Types form and click the Apply button. The file_type form is displayed. 3. Click the Insert button. 4. Type the entry that will be a valid file type code in a blank Type ID field. 5. Type a brief text description of the type ID code in the Description field.
238
Revised May 2, 2005
6. Repeat steps 3-5 for each document file type code to be defined. 7. Click the Save button. 8. Click the Exit button.
Defining Document File Format Codes

Before any file format code can be a valid entry on the document_hdr form you must define it on the file_format form. A document cannot be loaded without a valid format code.
Figure 3: The file_format form
Here is how to define the file format codes for Document Management: 1. Select Database Administration data type on the Forms dialog box.
Revised May 2, 2005
239
2. Select the File Formats form and click the Apply button. The file_format form is displayed. 3. Click the Insert button. 4. Type the entry that will be a valid file format code in a blank Type ID field. 5. Type a brief text description of the type format code in the Description field. 6. Repeat steps 3-5 for each document file format code to be defined. 7. Click the Save button. 8. Click the Exit button.
Scanner Programs
Overview
When users store electronic documents in the Finder database through Document Management, they must enter information that describes the document. This information may be entered manually on the document_hdr form, or it may be extracted from the document file by a scanner program. Scanners read the document file and create one or more output files. These output files are then read by Finder and the information is loaded into Document Management. It is the responsibility of you, the database administrator, to write and maintain these scanners. This section describes the scanner, what it can do, and the format of its output file, which is input into Document Management.
Launching Scanner Programs

Scanners are launched automatically from the document_hdr form when the document is loaded. The specific scanner launched is determined by the document type that was entered on the form. The following conditions must be met for a scanner to be launched: The scanner must be registered with Document Management. The document type entered on the document_hdr form has a scanner program associated with it.
240
Revised May 2, 2005
Loading files is a two step process: The scanner is executed. The scanner always operates on a single document file. The scanner is expected to create output files (one or more), in the format specified. In case the scanner creates more than one file, the subsequent files are identified by the NEXT_SCANNER_FILE entry in each scanner file. After the scanner has finished execution, all the scanner output files created by the scanner are loaded into Document Management.
Loading Documents
Loading documents with scanners is a two-step process. First, the scanner is executed. It reads a document and creates one or more output files. A scanner always reads only one document file. The number of output files it creates depends on the contents of the document and if the scanner was written to separate those contents into individual output files. The second step occurs after the scanner has finished executing. It consists of the scanner output file(s) being loaded into Document Management. In the single output file scenario, the user enters enough information on the document_hdr form to identify the document and clicks the Load button. The system searches for a scanner written for that document type. If a scanner is found it is executed. It creates one output file and finishes execution. Then the output file is read by Finder and the information is loaded into Document Management. The multiple output file scenario begins as does the single output file scenario, but while the scanner is reading the document, it recognizes points within the document where the contents should be separated and output into different files. These different output files are linked by the NEXT_SCANNER_FILE parameter they contain, which identifies the next output file created by the scanner. The last output file created does not have an entry for the NEXT_SCANNER_FILE parameter. Once the scanner has finished execution, the output files are loaded into Document Management. It is possible to load multiple documents with scanners in a batch type operation. In this scenario a user enters information for a document on the document_hdr form and clicks the Insert button. This is repeated for all the documents to be loaded. After information for the last document is entered, the user clicks the Load button. At this point the system launches a scanner for the first document. The scanner reads the document, creates the output file(s), and finishes execution. Then the system launches a scanner for the next document. This pattern is repeated until all of the documents have been processed by an appropriate scanner. When the last scanner finishes execution, all the output files are loaded into Document Management.
Revised May 2, 2005
241
Scanner Output File Format

The scanner is launched from the document_hdr form with one parameter. This parameter is the name of the file to which the scanner should write its output. In case the scanner creates multiple output files, the first file should be written to this location. The scanner generates attributes that may be used for the entry in the DOCUMENT_HDR table and for the GEM_LINE_POINTS table. It should return a value of 0 (zero) upon successful completion. The scanner output file is of the following format:
COLUMN_NAME_IN_DOCUMENT_HDR = parameter value (until EOL) . . COLUMN_NAME_IN_DOCUMENT_HDR = parameter value (until EOL) XY = x_1 y_1(for point 1) . . XY = Xing y_n(for point n) NEXT_SCANNER_FILE = full_filename
Figure 4: Scanner output file format
The column names mentioned in figure 4 refer to the column names in table 9, shown below:
Table 9: PROJECT.document_hdr
Column Name
DOCUMENT_ID
Type
VARCHAR2(50)
Description.
Unique name of the document. Also used as GEM link ID. This entry cannot be null. A version number for this file. This entry cannot be null and it must be a positive number. Who created this document. Who loaded this document (for deletion/edit protection). Date this file was loaded. Date the file should be automatically deleted. The set this file belongs to. DOCUMENT_SET.SET_ID constraint.
VERSION SOURCE OWNER CREATION_DATE EXPIRATION_DATE SET_ID
NUMBER(10) VARCHAR2(30) VARCHAR2(30) DATE DATE VARCHAR2(50)
242
Revised May 2, 2005
Table 9: PROJECT.document_hdr
Column Name
DESCRIPTION ORIGINAL_FILENAME FILE_ID
Type
VARCHAR2(240) VARCHAR2(240) NUMBER(10)
Description.
Description of this document. The original OS filename. The Finder File Manager identifier for the Finder representation of the document. FM_HDR.FILE_ID constraint. Parameter file for document. The Finder File Manager version of the parameter file. FM_HDR.FILE_ID constraint. Application which created document. FINDER_PRODUCTS.NAME constraint. Format of the document. FILE_FORMAT.FORMAT_ID constraint. Type of document (grid, contour, etc.). FILE_TYPE.TYPE_ID constraint. The mapped attribute. MAPPED_ATTRIBUTE.NAME constraint. Projection the document originated from. PROJECTIONS.PROJECTION_ID constraint. The name of the layer this document maps. LAYER_HDR.LAYER_NAME constraint. The type of layer this document maps. LAYER_HDR.LAYER_TYPE constraint. The scope of the layer this document maps. LAYER_HDR.STRAT_SCOPE_ID constraint. Source of the layer. Owner of the layer.
PARAMETER_FILENAME PARAMETER_FILE_ID APPLICATION_ID FILE_FORMAT FILE_TYPE ATTRIBUTE_NAME PROJECTION_ID LAYER_NAME LAYER_TYPE LAYER_SCOPE LAYER_SOURCE LAYER_OWNER
VARCHAR2(240) NUMBER(10) VARCHAR2(10) VARCHAR2(20) VARCHAR2(20) VARCHAR2(20) VARCHAR2(15) VARCHAR2(30) VARCHAR2(20) VARCHAR2(10) VARCHAR(30) VARCHAR(30)
Note:
Every column in DOCUMENT_HDR (other than FILE_ID and PARAMETER_FILE_ID) can be specified in the scanner output file. The following special cases should be noted:
Revised May 2, 2005
243
Values for columns DOCUMENT_ID and VERSION must be specified in all scanner output files other than the first. These values specify the name and version of the new document to be created. For the first file, only VERSION itself may be specified. Column SOURCE_FILENAME may be specified. However, if it is not specified, then the value entered in the form is used. For this entry and all other filenames, the filename should be specified with its complete path. If no projection (column PROJECTION_ID) is specified in the scanner output file, Finder assumes the projection is the same as the project projection. The # character may be used to add comments in the file. All lines starting with # are interpreted as comments. The / character may be used as line delimiters.
The NEXT_SCANNER_FILE parameter can be used to specify another scanner output file that should be loaded also. There can only be one NEXT_SCANNER_FILE entry in each output file. This allows support for loading multiple documents from one physical file. Finder will read each scanner output file, and register each file separately.
Registering Scanner Programs

Every scanner you write and use with Document Management must be registered. This registration is done with the EDM Administration form. This process is described earlier in this section under the heading "Registering Document Viewers and Scanners" on page 235.
Utilities Used with Document Management

Document Management uses the utility DataMover to move data, similar to the way in which GEM uses the utility to move data for user objects. See the Loader Control Center Tasks and Reference for a description of this utility.
244
Revised May 2, 2005
Chapter 7: Customizing Database Graphics
Chapter 7
Customizing Symbols
Introduction
Graphic symbol definitions, such as those used to display the location and status of wells, are provided with Finder as part of the installation. There are, or can be, various types of symbols, including well symbols, fault symbols, highlight symbols, and many more. Symbols of the same type are stored in a single text file in a SYMBOLS directory which is accessed by name by any graphics software which requires the symbols. You are encouraged to modify or add new symbols as required.
Getting Started
Symbol Display Files
Symbol display files are used in a number of different places in Finder. They are ASCII files that contain coded descriptions of a symbol to be used by Finder that can be scaled or drawn as required by the application.
Revised May 2, 2005
247
The symbol files provided with Finder can be found in the $FINDER_HOME/symbols directory. Table 1 below describes the various files that are shipped with Finder and how they are used.
Table 1: Symbol display file descriptions
File name
v4_wells.sdl
Application
Well Mapping
Description
This is the main symbol file for display the status-related symbols for wells. It contains over 90 different symbols. This file contains the filled polygons used to highlight wells on a map. These are a matched set of hollow and filled polygons similar to those used for highlighting wells on a map.
highlight.sdl
List Assistant
hollow.sdl,filled.sdl
The plot symbols in the v4_wells.sdl file correspond to the values in the PLOT_SYMBOL column of the WELL_HDR table. Values in this column are required to be integer strings in the range 1 through 998 and a database constraint is applied to confirm this. If you create a new plot symbol then you must assign to it a PLOT_SYMBOL value which is an integer string, in this range and is not already assigned to an existing symbol. If all 998 PLOT_SYMBOL values are assigned, then you must relax the database constraint before assigning larger integer string values. See Chapter 5: Customizing the Database in this manual for more information on setting and removing database constraints.
Creating or Modifying the Symbol Definition

A single symbol definition file generally contains the definitions for many symbols, each symbol being identified by a numeric symbol code, and distinguished from the preceding or following symbols by SDL_START_SYMBOL and SDL_END_SYMBOL commands, as shown in figure 1 on page 249. Blank lines and indentations are optional, but helpful in making the structure of the symbol definitions apparent.
248
Revised May 2, 2005
Figure 1: A symbol definition file.
Revised May 2, 2005
249
Figure 2: Defining symbol coordinates and size.
The symbols are defined by symbol definition library (SDL) commands referenced to a coordinate system based upon a dimensionless unit circle and on angles measured in degrees in a counter-clockwise direction from the +X axis, indicated as angle A in the figure 2. The size and location of a symbol when displayed is determined by the graphic software. The symbol coordinate origin is located at the point whose X and Y coordinates are specified in the map or plotter coordinates. To optimize plotting performance, you should define customized symbols using as few line segments as possible. For example, a symbol defined using a polyline with 10 points can be rendered up to three times faster than the same symbol defined by five individual connected lines. Table 2 on page 251 explains the nine SDL commands that are used.
250
Revised May 2, 2005
Table 2: SDL Commands
Item
<N> SDL_START_SYMBOL
Description
Each symbol definition starts with this command. The <N> parameter is an integer symbol code by which the symbol is referenced by the graphic display software. Each symbol definition must end with this command. Draw a unfilled (hollow) circle centered at <X>, <Y> with a radius <R>. Keep in mind that all the SDL command <X>, <Y> coordinates refer to the location in the unit circle frame of reference - not in world or map coordinates.
SDL_END_SYMBOL <X> <Y> <R> SDL_HOLLOW_CIRCLE
For example, the SDL command which would display the circle shown above is as follows. 0.5 0.0 0.5 SDL_HOLLOW_CIRCLE <X> <Y> <R> SDL_FILLED_CIRCLE Draw a filled (solid) circle centered at <X>, <Y> with a radius <R>.
Revised May 2, 2005
251
Table 2: SDL Commands (Continued)
Item
<X> <Y> <S> <E> <A> SDL_RADIAL_SEGMENT
Description
Draw a radial segment originating at a point whose unit circle coordinates are <X>, <Y>, which starts and ends at distances <S> and <E> from the origin, and which makes an angle <A> degrees from the +X axis. In the example shown below, the dark radial segment would be drawn by the following SDL command: 0.0 0.0 1.0 1.2 45.0 SDL_RADIAL_SEGMENT
SDL_GATHER_POINTS
The SDL_GATHER_POINTS command is used to signal that the next set of SDL_ADD_POINT commands, until terminated by either a SDL_FILLED_AREA, or a SDL_POLYLINE command, are to be considered as defining either a filled polygon, or an unfilled polyline. Add a point located at <X>, <Y> to the polyline or polygon under construction. Use the coordinates of the points defined by the preceding SDL_ADD_POINT commands to define and display a closed, filled area. The software automatically closes the polygon by connecting the first and last points. Draw a line connecting the points defined by the preceding SDL_ADD_POINT commands.
<X> <Y> SDL_ADD_POINT SDL_FILLED_AREA
SDL_POLYLINE
252
Revised May 2, 2005
It is recommended that you list one or more of the SDL files delivered with Finder in the $FINDER_HOME/symbols directory and use the listing as a guide to help you add or modify symbols.
Saving Changes to an SDL File and Appropriate Directory

Any changes you make to existing SDL files located in the system level symbols directory are susceptible to being deleted or modified the next time that Finder is installed or updated. If you wish to add to, or modify symbols in an existing SDL file, and make them available to all users and all projects, you should copy the SDL file you intend to modify to the system level customized symbols directory, make the changes there, and save the modified SDL file using the same name. The Finder software uses the SDL file in the system level customized symbols directory in preference to the one with the same name in the system level symbols directory. Similarly, if you create new SDL files, they should be stored in the system level customized symbols directory. Be careful that you provide the required privileges for the new SDL file to be used by the Finder software. Project-specific changes or additions to SDL files can likewise be saved in the project ESI$PROJECT/customized/symbols directory. The Finder software uses the SDL file in the ESI$PROJECT/customized/symbols directory in preference to the one with the same name in the ESI$ROOT/ customized/symbols directory.
Modifying the Appropriate Symbol Lookup Table

The graphic software access graphic symbols by file name and by a numeric symbol code present in the SDL_START_SYMBOL command, as discussed above. Finder's software obtains the symbol code by using an appropriate lookup table maintained in the FINDER CODES account. In the case of symbols used to display well location and status, the CODES.WELL_STATUS_CODES table is used to associate a particular graphic symbol in the V4_WELLS.SDL SDL file with the well status stored in the project WELL_HDR table. If you wish to add a new well symbol to represent an existing well status, or to represent a newly defined status, you must modify or add information to the WELL_STATUS_CODES table. Similar tables exist for other graphic symbol type as well, and must be modified accordingly in order for the additions to the corresponding SDL files to take effect. If you wish to change the display symbol for a well, modifying the SDL file will change the displayed symbol with no other changes. Finder must be restarted for this change to be visible.
Revised May 2, 2005
253
Customizing GPDL Files

There are a number of different parts of Finder that use Graphics Product Description Language (GPDL) files. They are used extensively in plotting for such things as lease and well legends, logos, and title blocks. They are also used in the SmartSection application for the retrieval and posting of interval symbols for representing data such as core and test data. This chapter discusses how the different files are used and to what extent the database administrator should be able to customize them. This chapter should contain most of what you might need to know about GPDL for use in Finder. For more information about GPDL, your GeoQuest customer support representative has access to two internal GPDL reference documents. GPDL, DS and Class C Language Graphics Product Description Language (GPDL) Application Programmers Interface
These references contain more information and descriptions of functions not supported in the Finder implementation, but may be helpful in documenting the use of different functions. The function descriptions relevant to the Finder implementation are documented below in The Graphics Product Description Language (GPDL) on page 259. Note: Since version 7.0, Finder has the ability to clip both text and symbols in alpha shotpoints.
Getting Started
Working With GPDL Files GPDL Files are Case Sensitive
GPDL files are case sensitive. Thus, if you define a character variable (a cc_String variable) called CompanyName, you will not be able to refer reference it by any other name (e.g. COMPANYNAME or companyname). If a reference is made in the GPDL file to a variable that is not defined (or really called something else due to capitalization or a misspelling), you will get an error message similar to the following.
Expand Macros - macro $(companyname) not defined
254
Revised May 2, 2005
Order of Defining Objects

In the Schlumbergers original GPDL implementation (which differs from the GeoQuest implementation), the objects within the GPDL files do not need to appear in any particular order. For instance, if you want to define a numeric constant equal to the anticipated width of something, and then define another constant equal to half of this width, you would not need to define the initial width before you defined the half width (where the half width would be the result of dividing the width by two). Example:
cc_String cc_String cc_Number cc_Number NameFinal = "You: $(Name)"; Name = "Bill"; WidthHalf = Width/2; Width = 5;
In this example, the variable Name is being used in line 1 before it has been defined (in line2). Likewise, WidthHalf is being calculated from Width in line 3, before Width has been defined (in line 4). The GeoQuests implementation of GPDL works differently from this. Finder requires that all objects of the same type (that is, all cc_Number or cc_String or gpd_Context variables) be defined before they are used.
Avoiding TAB Characters

Using the <TAB> character to align GPDL files will give unpredictable results. This is because the <TAB> character is not recognized as an irrelevant character, but instead as assumed to be an alpha-numeric. Example: These fragment statements in a GPDL file, where <TAB> is actually the tab character.
X<TAB> = 12, Y = 15,
The GPDL subsystem would assume you were assigning the value 12 to a member of the current object called X<TAB> (i.e. a two-letter name consisting of capital X, followed by the <TAB> character). When this object is referenced or drawn, the X member is undefined, unless there is a later statement assigning a value to X.
Revised May 2, 2005
255
The second statement correctly assumes that the member's name is Y and assigns it the value of 15.
Naming Objects and Variables in GPDL Files

There are no naming conventions for the GPDL files, just some reserved words and some characters that are not allowed to be used as names of objects or variables. By ensuring the names of objects and variables are only comprised of alphanumeric characters and the under-score character (_), you will eliminate unpredictable results.
Defining Objects and Variables and Not Using Them

Any variable or object defined in the GPDL files, may be used. Thus you can always define as many Contexts as you wish in a Symbol Appearance GPDL File but only use one of them.
Assigning Multiple Values to Variables and Members

Almost anything in GPDL can be assigned more than one value. For example, setting the TextColor member of a gpd_Context object to two colors, will make the labels for every other symbol a different color. The same is true for all gpd_Context and gpd_Font members.
Performing Calculations Within GPDL Functions

The GPDL parser can be very sensitive to parentheses in CC_NUMBER assignments. Example:
CC_NUMBER ONE = 2 + 3/2;
is not necessarily the same as:

CC_NUMBER ONE = 2 + (3/2);
The best rule of thumb to go by is to always use parentheses whenever doing calculations to be sure the equations are processed in the correct order.
256
Revised May 2, 2005
Special Finder GPDL Variables

There are two special variables that are always defined within Finder for use with GPDL files. PROJECT is a variable that is defined to be the name of the current Finder project. This is particularly useful for building SQL queries within the GPDL environment. MAP_NAME is defined to be the name of the currently active map. This can be used with GPDL files that interact with the map window or map definitions. Also, before any GPDL code is executed within the Finder environment, a file called CC_NUMBER.GPDL is executed. This file initializes a number of standard variables which are then available by default when you execute and GPDL file. It control parameters for such things as text clipping control, standard fonts, text expansion, justification, line weights, etc. so they can be referenced as variables in other GPDL code. When customizing GPDL files, you should be familiar with the contents of this standard file. The CC_NUMBER.GPD file should not be changed or customized except for the following three variable definitions. All three variables are used to control text clipping. They will be used for alpha shot point labels, interval symbols in cross section tracks and GPDL windows placed in the plot layout. They will only be initialized during a Finder instance (much like logical names are only defined upon startup). The first is a numeric ratio of the width to height of each text character. This is just a guide that will be used to determine the extents of each label.
/* ----------------------------------------------- */ /* WIDTH TO HEIGHT RATIO FOR GPD_LABELLELINE ------- */ /* ----------------------------------------------- */ cc_Number WidthToHeightRatio = 0.90;
The second is a FLAG that determines whether or not to display a label that may be partially outside of its designated area (ie: the map boundary or the Layout Designer window).
/* ------------------------------------------------- */ /* 1 == DRAW THE TEXT IF SOME IF IT IS INSIDE THE GRATICULE */ /* 0 == DONT DISPLAY THE TEXT IF ANY OF IT LIES OUTSIDE -- */ /* ----------------------------------------------------- */ cc_Number DrawTextIfPartiallyClipped = 0;
The third can be used as a debugging tool. It will draw a line constructed to go from the lower-left to upper right corner of the label that is being clipped. This can be used to reset the WidthToHeightRatio to make
Revised May 2, 2005
257
this line more correctly represent the text that is being displayed. The thick red line represents the calculated extents of the text, and the fine black line represents the previous line after it has been clipped.
/* ---------------------------------------------------- */
/* 1 == DRAW THE EXTENTS OF THE TEXT BEFORE CLIPPING- */ /* ----------------------------------------------- */ cc_Number DrawTextExtents = 0;
Drawing Objects Using GPDL

There are a few caveats you might find helpful in defining line and text objects to be drawn using GPDL. If your company has its logo in digital form for other applications, it can usually be adapted to GPDL fairly easily. If not, then you will have to digitize it by hand by overlaying a grid on a printed copy of the logo and assigning X and Y coordinates for each point on the logo. Text in logos can also be a problem. Each installation and plotter will have a different set of fonts available. There is no guarantee that text defined by a font, width, and size will be rendered the same on screen and plot. Unless there is simply too much text in the logo, it is recommended that you define each character as a polygon that can be filled with the desired color and will always be rendered correctly regardless of scale.
Using GPDL files in Finder

The most prominent use of GPDL files is in the Finder plotting system. For more information on exactly how to reference GPDL files in the plotting system, see the Plotting chapter of the Mapping Reference. There are several types of GPDL files that the Finder can use. General GPDL files The General GPDL files are referenced by entering the file name of the GPDL file in the Window Name field and GPDL in the Window Type field of the Layout Designer window definition form. Logos Logos are referenced by entering the file name of the GPDL file in the Translation field of the Logical Names form for the logical name ESI$LOGO and in the Select Gpd... field of the GPD properties dialog in the Plot Layout Designer. Cross Section track symbol
258
Revised May 2, 2005
The Cross Section track symbol annotation function requires two GPDL files, one to control the appearance of the symbol to be drawn, and another to define what data are to be selected to control the position and extents of the symbol to be drawn. These symbol appearance and data selection files are tracked by Finder in the File Management tables. The details of entering records for these types of files are presented below in the Customizing Cross Section Symbol Tracks on page 296. Bubble and Pie symbols For more information about customizing the bubble and pie symbols, refer to Customizing Bubble Map Symbols on page 338.
GPDL Reference
The Graphics Product Description Language (GPDL)
GPDL was developed by Schlumberger as a simple graphics programming language that can be used for defining standard objects that can be accessed by other programs. GPDL was used as the basis for defining a number of standard objects in Finder. Because Finder uses GKS as the native graphics environment, the original implementation of GPDL is not used directly. A Finder-specific port of the GPDL software supports the main features within the Finder environment. The GPDL syntax is designed to be similar to the C programming language. GPDL files contain GPDL commands and definitions which can be interpreted by GPDL programs to generate graphical displays. A simple graphics element is shown in figure 3 with the GPDL template file used to generate it below.
Hello World
Figure 3: An example object to be defined by a GPDL file.
The following is the code used to generate figure 3 on page 259.
Revised May 2, 2005
259
gpd_Polyline HelloBox ( X = {0.00, 0.00, 1.50, 1.50, 0.00}, Y = {0.00, 0.25, 0.25, 0.00, 0.00} ); gpd_PolyCText HelloText ( X = 0.05, Y = 0.02, Content = Hello World ); gpd_GraphicsProduct HelloWorld ( gpd_Region = (0.0, 0.0, 1.6, 0.3), { gpd_Draw(HelloBox), gpd_Draw(HelloText) } );
In this example, the graphic and text elements defined by the gpd_Polyline and gpd_PolyCText commands have been placed within a graphical region using the gpd_GraphicsProduct command. This region acts as a viewport controlling the relative scaling and clipping of elements placed inside it. The syntax of GPDL provides the ability to define very complicated graphics together with statically or dynamically defined text elements. It builds upon a standard that is used widely within Schlumberger, and which provides Finder clients with almost unlimited capabilities for customizing the final appearance of their maps by including proprietary title blocks, logos, and almost any other graphic object that they would like. The ability to use information dynamically retrieved from the Finder data base differentiates GPDL from the facility for plotting CGM files using the Layout Designer. While either method would work for the inclusion of a company logo, only GPDL would allow this logo to be sized based upon the map scale, or placed within a title block along with text retrieved from the data base.
GPDL Utility Routines and Data Structures

The GPDL emulation developed for Finder makes use of GPDL template files and uses C programming language structures that closely resemble the various GPDL elements such as polylines or contexts.
260
Revised May 2, 2005
The GPDL classes and commands currently implemented by Finder are shown in table 3 on page 261 and table 4 on page 262.
Table 3: GPDL Classes and Commands Supported by the Finder implementation
Class or function
cc_Number cc_String gpd_BucketIndex gpd_Context gpd_Draw gpd_Font gpd_GraphicsProduct gpd_Polyline gpd_Polygon gpd_PolyCText gpd_Region gpd_RegularIndex gpd_Rotation gpd_Scaling gpd_Transform gpd_Translation
Description
Numeric constant assignments String constant assignments GPDL index array generator Graphical contexts (colors, styles, patterns) GPDL object rendering Font definitions Complete Graphics product Polylines Polygons with or without color/patterns fill Text GPDL region definition (relative plot size) GPDL index array generator Object rotation Object scaling Object transformation (scaling+rotation+translation) Object translation
Revised May 2, 2005
261
Table 4: Finder extensions to GPDL
Class or function
gpd_LabelledBox gpd_LabelledBoxz gpd_LabelledShape gpd_SQLNumber gpd_SQLString gpd_Pretty
Description
Box with text labels beside the box. Box with text labels inside the box. Generic shapes with labels. SQL retrieval of numeric data. SQL retrieval of text strings. Special function for Lease Legends. It provides the ability to join tables on Long Data type fields and processes labels to improve appearance. Functions to generate points of a circle.
arc_x, arc_y
Standard GPDL Functions

These function descriptions are taken in part from the Schlumberger Software Manual C300112, as appended to the Lease Legends, Title Blocks, and Logos Detailed Technical Design. Each function is described according to how it has been implemented in Finder, and is shown in an example of how it should be used.
cc_Number
Class { cc_String cc_Number cc_Number } cc_Number : cc_Object Units(); Min(); Max();
The cc_Number Class defines the root class for all numeric objects. A cc_Number object may only be initialized by a numeric constant. Example:
cc_Number One = 1.0; cc_Number Array = { 1, 2, 3, 4, 5, 6 }; cc_Number Expr = (ArrayMax * 2) + One;
262
Revised May 2, 2005
cc_String
Class { } cc_String : cc_Object
The cc_String Class defines an ordinary character string. A character string constant is specified as in C. Example:
cc_String Str = Simple string; cc_String CompanyName = { BOG, Oil, And, Gas, Ltd. };
gpd_BucketIndex
Class { cc_Number cc_Number cc_Number } gpd_BucketIndex : gpd_Index From To NBuckets ; ; ;
A gpd_BucketIndex defines an array with exactly NBuckets values. This format is provided for convenience in cases where you know exactly how many intervals you want. Example:
gpd_BucketIndex Exactly10 (0, 27.2333, 10);
gpd_Context
Class { gpd_Color gpd_Color gpd_Pattern gpd_Color gpd_Color cc_Number cc_Number gpd_color } gpd_Context FillBackground FillColor FillPattern LineBackground LineColor LineTexture PenTip TextColor : cc_Object = = = = = = = = BLACK; BLACK; ; BLACK; BLACK; SOLID; FINE; BLACK;
Revised May 2, 2005
263
The gpd_Context Class logically collects properties that affect the appearance of the graphics objects. The graphics objects themselves define the geometry of the picture. When the graphics objects are displayed, the context defines the drawing properties. You specify a gpd_Context as part of a gpd_Draw object which defines an arc in a GPDL graph. Each gpd_Context specified in a gpd_Draw is applied to that object before it is displayed.
Fill Attributes
The attributes FillBackground, FillColor and FillPattern define how an area is filled. The FillBackground and FillColor members are one or many names of colors. These names are identical to those used in Finder, like CYAN, YELLOW or LIGHT PINK. The FillPattern character string defines the name of the pattern. This is replicated throughout the area. The patterned area is colored with the FillBackground color; the pattern, with FillColor color. If you want transparent fill, set FillBackground attribute to transparent color (i.e. BACKGROUND in Finder). Example:
gpd_Context Fill ( FillBackground = BLUE, FillColor = RED, FillPattern = LIMESTONE, );
Line Attributes
The attributes LineBackground, LineColor, LineTexture and PenTip determine the appearance of lines. LineColor and LineBackground (like FillColor and FillBackground) are names of one or more colors. LineTexture is a number which is interpreted as line style. Possible values are (listed in the CC_NUMBER.GPD dictionary) are as follows. None Solid ShortDashed
264
Revised May 2, 2005
LongDashed Dotted
The Line is drawn with the visible line portions colored with the LineColor and the LineBackground color for the invisible portions of the line. Of course, you may specify a transparent color for either of these attributes. PenTip defines the width of a line, with the possible values listed in the CC_NUMBER.GPD dictionary are as follows. Invisible Light Medium Heavy MediumHeavy ExtraHeavy
Example:
gpd_Context YCYBLine ( LineBackground = YELLOW, LineColor = { CYAN, BLUE }, LineTexture = ShortDashed, PenTip = Heavy, ); /* This will produce a yellow, cyan, yellow, blue dashed line */ gpd_Context RedLine ( LineColor = RED, LineTexture = Dotted, PenTip = Medium, );
Text Attributes
The TextColor attribute defines the color of the text strings. It can be one or a list of many named colors. Example:
Revised May 2, 2005
265
gpd_Context TextContext ( TextColor = RED, );
gpd_Draw
Class { gpd_GraphicsObject gpd_Context gpd_Transform } gpd_Draw : cc_Object GO GC XF = NULL; = NULL; = NULL;
The gpd_Draw Class defines the arcs in the picture hierarchy. It is an association between a gpd_Plot and a gpd_GraphicsObject, along with context and image transformation attributes to be composed when rendering the target graphics object. Example:
gpd_Polyline Line(...); gpd_Context LineGC(...); gpd_Scaling LineScale(...); gpd_Draw (Line, GC=LineGC, XF=LineScale)
gpd_Font
Class { cc_String cc_Number cc_Number } gpd_Font FontFamily FontSize FontWidth : cc_Object = SIMPLEX; = 12; = 5; /* Normal */
The gpd_Font Class collects together properties which define a font to be used in rendering a gpd_PolyCText object. FontFamily is the name of a Finder font. FontSize defines the height of the characters in points (a point is 1/72 inches). This may be affected by scaling transforms.
FontWidth defines the width of the character cells. Valid values of
FontWidth are shown in table 5 on page 267.
266
Revised May 2, 2005
Table 5: Values of FontWidth
Value
1 2 3 4 5 6 7 8 9
Meaning
Ultra-Condensed Extra-Condensed Condensed Semi-Condensed Normal Semi-Wide Wide Extra-Wide Ultra-Wide
Example:
gpd_Font Triplex14 ( FontFamily = TRIPLEX, FontSize = 14, ); gpd_Font ReallySkinny ( FontWidth = Ultracondensed, );
gpd_GraphicsProduct
Class { gpd_Draw gpd_Region cc_String } gpd_GraphicsProduct : cc_object Components Region Title = NULL; = NULL; = "";
The gpd_GraphicsProduct Class defines the object used as the root of a graphics product. It defines the components of the graphics product as well as attributes used to map the graphics product to a display surface.
Revised May 2, 2005
267
Components defines the array of gpd_Draw objects that make up the
graphics product.
Region defines the size of the drawing surface to use. If you do not specify
a Region, with at least one unspecified attribute, the drawing surface is unbounded.
Title defines a string to use as the title of the graphics product. This string may be used, for example, in the title bar of a window system implementation. Its use is otherwise undefined.
Example:
gpd_GraphicsProduct HelloWorld ( gpd_Draw (HWPlot), Region = gpd_Region (-2,-2,2,2), Title = Hello World );
gpd_PolyCText
Class { cc_String cc_Number cc_Number cc_Number gpd_Font */ cc_Number cc_Number } gpd_PolyCText : gpd_GraphicsObject
Format = %f; X = 0; Y = 0; Content = 0; Font = NULL; /* system supplied default XJust YJust = CenterJust, = CenterJust
The gpd_PolyCText Class defines one or more pieces of text to be displayed. The number of strings to display is defined by the maximum cardinality of X and Y, which define the points at which each string is placed. Each of the other attributes is interpreted as an array which associates with the array of points.
Format is a C-language printf format string, which is unused at this point in time.
The X, Y and Content members are minimally required to display any gpd_PolyCText object. The Content member is a single string or list of strings or numbers, that are to be displayed.
268
Revised May 2, 2005
Example:
Content = { One, Two, Three }, Content = { 0.797, 1.235, 3.452 }, Content = My Company,
Font refers to the gpd_Font object which defines the properties of the type-face to use in displaying the text strings. XJust and YJust define which position of the bounding box of each string is to be mapped to the given X and Y location. Valid values for each are shown in table 6.
Table 6: Values of XJust and YJust
Value
0 1 2
Meaning
Minimum justification Center justification Maximum justification
Parameter in CC_NUMBER.GPD file

MinJust CenterJust MaxJust
The values are interpreted as in figure 4 below, with the pairs in parentheses representing the XJust and YJust values.
(MIN,MAX)
(CEN,MAX)
(MAX,MAX) (MAX,CEN)
(MIN,CEN)
(CEN,CEN) (CEN,MIN)
(MIN,MIN)
(MAX,MIN)
Figure 4: Illustration of text locations for different values of XJust and YJust.
Revised May 2, 2005
269
While it might appear at first glance that many of the attributes affect only the visual appearance of the text, it is actually true that each attribute affects the geometry of the text. If you modify any of these attributes, the bounding box of a text string are affected. The attributes that do affect only the visual appearance are contained in the gpd_Context TextColor. Example:
gpd_PolyCText Simple(X=5,Y=5,Content=Simple); gpd_PolyCText Complex ( X = { 0, 1 }, Y = { 0, 1 }, Content = { 4, 5 }, XJust = { 0, 2 }, YJust = { 0, 2 }, Font = MyFont, ); gpd_Font MyFont ( FontFamily = DUPLEX ROMAN, FontSize = 24, FontWidth = Condensed, );
gpd_Polygon
The gpd_Polygon Class defines a filled polygon specified by arrays of X and Y coordinates. The polygon is closed automatically. Example:
Class { cc_Number cc_Number } gpd_Polygon : gpd_GraphicsObject X Y = ABSENT; = ABSENT;
The following context attributes apply. FillBackground FillColor FillPattern
270
Revised May 2, 2005
LineBackground LineColor LineTexture PenTip
The line attributes apply to the boundary, while the fill attributes apply to the interior. If no context is attached to the polygon, the area will be filled in with black (there will be no pattern), and the outline will be a light, solid, black line. Example:
gpd_Polygon OneInchSquare ( X = { 0, 1, 1, 0 }, Y = { 0, 0, 1, 1 } );
Special functions have been added to allow arcs, circles and ellipses to be drawn using the gpd_Polygon function. See the Finder GPDL Arithmetic and Geometric Functions on page 283 for more information on using the arc_x and arc_y extensions to the gpd_Polygon function.
gpd_Polyline
Class { cc_Number cc_Number } gpd_Polyline : gpd_GraphicsObject X Y = ABSENT; = ABSENT;
The gpd_Polyline Class defines a polyline specified by arrays of X and Y coordinates. A line is drawn between all vertices. The X and Y attributes are interpreted as one dimensional arrays. The following context attributes apply: LineBackground LineColor LineTexture PenTip If no gpd_Context is attached to the polyline, the line will be displayed with a light, solid, black line.
Revised May 2, 2005
271
Example:
gpd_Polyline ZigZag ( X = { 0, 1, 0, 1, 0, 1 }, Y = { 0, 1, 2, 3, 4, 5 } ); gpd_Polyline ZigZag2 /* Same as ZigZag because the X component */ ( /* will repeat itself until the Y component */ X = { 0, 1 }, /* is exhausted */ Y = { 0, 1, 2, 3, 4, 5 } );
Special functions have been added to allow arcs, circles and ellipses to be drawn using the gpd_Polyline function. See the Finder GPDL Arithmetic and Geometric Functions on page 283 for more information on using the arc_x and arc_y extensions to the gpd_Polyline function.
gpd_Region
Class { cc_Number cc_Number cc_Number cc_Number } gpd_Region : cc_Object Left Bottom Right Top = = = = ABSENT; ABSENT; ABSENT; ABSENT;
The gpd_Region Class defines the external values in which you place the drawing. The attributes are defined so the constructor for a gpd_Region is based on the lower-left, upper-right corners of the rectangle. Anything exceeding the extremes is clipped.
272
Revised May 2, 2005
Example:
gpd_Region Q4 ( Left = 0, Top = 0, ); gpd_Region FourInchSquare (-2, -2, 2 , 2);
gpd_RegularIndex
Class { cc_Number cc_Number cc_Number } gpd_RegularIndex : gpd_Index From To Delta ; ; ;
A gpd_RegularIndex has even steps between each value of the array. All three members are required. For a gpd_RegularIndex, the nth value is computed as follows.
From + (n * Delta), if From < To, otherwise From - (n * Delta)
Revised May 2, 2005
273
Example:
gpd_RegularIndex Counter (0, 100, 1); /* { 0, 1, ..., 100} */ gpd_RegularIndex Foo(-10, 10, .25); /* { -10, -9.75, ... 9.75, 10 } */
gpd_Rotation
Class { cc_Number } gpd_Rotation : gpd_Transform XYAngle = 0;
The gpd_Rotation Class defines a transformation matrix that rotates in two dimensions by an angle in degrees from the positive X axis toward the positive Y axis. This is usually counter-clockwise. Example:
gpd_Rotation Flip(180); gpd_Rotation QuarterTurn(90);
gpd_Scaling
Class { cc_Number cc_Number } gpd_ScaleTransform : gpd_Transform XScale YScale = 1; = 1;
The gpd_Scaling Class defines a scaling transformation in which X and Y are scaled independently. A single negative scale factor produces a mirror image. Example:
gpd_Scaling ByTwo (2, 2); gpd_Scaling MirrorX (-1);
274
Revised May 2, 2005
gpd_Transform
Class { gpd_Rotation gpd_Scaling gpd_Translation cc_Number cc_Number } gpd_Transform : Rotation Scaling Translation XOrigin YOrigin cc_Object
; ; ; = 0; = 0;
The gpd_Transform Class defines the basic transformation matrix. Subclasses are defined to provide convenient constructors for special kinds of transformations, such as rotation, scaling, etc. The XOrigin and YOrigin members are provided to control the location about which the transformations are to take place. Example:
gpd_Translation MoveLeft (-3); gpd_Transform MyXF (QuarterTurn, ByTwo, MoveLeft); gpd_Polygon MyBox ( X = { 5, 5, 8, 8, 5 }, Y = { 2, 5, 5, 2, 2 } ); gpd_GraphicsProduct FinalPlot ( Region = gpd_Region (-3, 0, 12, 10), { gpd_Draw (MyBox, XF=MyXF), gpd_Draw (MyBox), } );
gpd_Translation
Class { cc_Number cc_Number } gpd_Translation : XOffset YOffset = = gpd_Transform 0; 0;
The gpd_Translation Class defines a translation transformation.
Revised May 2, 2005
275
Example:
gpd_Translation ShiftRight (1); gpd_Translation Diag(1, 1);
Finder GPDL Extensions gpd_LabelledBox

Class { cc_Number cc_Number gpd_Color cc_String cc_Number cc_Number cc_Number cc_Number cc_Number cc_Number gpd_Font } gpd_LabelledBox : gpd_GraphicsObject X Y BoxColors BoxLabels BeforeLabel BoxHeight BoxWidth BetweenBox XJust YJust Font = = = = = = = = = = = 0; 0; ""; ""; 0; 0; 0; 0; 0; 0; 0;
The gpd_LabelledBox Class is an extension to the GPDL standard developed to accommodate the manipulation of colored boxes and associated text strings. The gpd_LabelledBox Class minimally requires values for the X, Y and BoxWidth members. Example:
/* This is a simple example of a labeled box. Note that only one * value for X need be specified as GPD allows values to be repeated * intrinsically as required. * / gpd_LabelledBox TestBoxes ( X = 0.5, Y = {2.5, 2.0, 2.5, 1.0, 0.5}, BoxColors = {RED, BLUE, GREEN, CYAN, YELLOW}, BoxLabels = {Test Red, Test Blue, Test Green, Test Cyan, Test Yellow}, BeforeLabel = 0.1, BetweenBox = 0.1, XJust = MinJust, YJust = CenterJust );
276
Revised May 2, 2005
Because this object is assumed to be labelling a set of boxes, the labels are placed off the boxes, when the labels are not center justified. The XJust and YJust members control how the label will be placed with respect to that box (see figure 5 on page 278). The YJust can be assigned any one of MinJust, CenterJust or MaxJust (see the CC_NUMBER.GPD dictionary). MinJust will align the baseline of the label with the baseline of the box, CenterJust will align the center of the text with the vertical center of the box and MaxJust will align the tops of the label and boxes. Setting the XJust member to MinJust will place the label off the right edge of the box (the minimum of the label will be aligned with the maximum of the box). An XJust value of MaxJust will align the maximum edge of the label with the minimum edge of the box, and a XJust value of CenterJust will align the horizontal center of the label with the horizontal center of the box.
Revised May 2, 2005
277
XJust = MinJust Test Red Test Blue YJust = MinJust Test Green Test Cyan Test Yellow
XJust = CenterJust Test Red Test Blue Test Green Test Cyan Test Yellow
XJust = MinJust Test Red Test Blue Test Green Test Cyan Test Yellow
XJust = MinJust Test Red Test Blue YJust = CenterJust Test Green Test Cyan Test Yellow
XJust = MinJust Test Red Test Blue YJust = MaxJust Test Green Test Cyan Test Yellow
Figure 5: Examples of horizontal and vertical alignment options.
278
Revised May 2, 2005
gpd_LabelledBoxz
Class { cc_Number cc_Number gpd_Color cc_String cc_Number cc_Number cc_Number cc_Number gpd_Font } gpd_LabelledBoxz : gpd_GraphicsObject X Y BoxColors BoxLabels BoxHeight BoxWidth XJust YJust Font = = = = = = = = = 0; 0; ""; ""; 0; 0; 0; 0; 0;
The gpd_LabelledBoxz is the second generation of the gpd_LabelledBox. Like a gpd_LabelledBox, it couples boxes of particular sizes with labels and fill colors. The gpd_LabelledBoxz Class minimally requires values for the X, Y, BoxWidth and BoxHeight members. Example:
/* This is a simple example of a labeled box. Note that only one * value for X need be specified as GPD allows values to be repeated * intrinsically as required. * / gpd_LabelledBoxz TestBoxes ( X = 0.5, Y = {2.5, 2.0, 2.5, 1.0, 0.5}, BoxColors = {RED, BLUE, GREEN, CYAN, YELLOW}, BoxLabels = {Test Red, Test Blue, Test Green, Test Cyan, Test Yellow}, XJust = MinJust, YJust = CenterJust );
The labels are placed with respect to the inside of the boxes (see figure 6 on page 280).
Revised May 2, 2005
279
XJust = MinJust Test Red Test Blue YJust = MinJust Test Green Test Cyan Test Yellow XJust = MinJust Test Red Test Blue YJust = CenterJust Test Green Test Cyan Test Yellow
XJust = CenterJust Test Red Test Blue Test Green Test Cyan Test Yellow XJust = CenterJust Test Red Test Blue Test Green Test Cyan Test Yellow
XJust = MinJust Test Red Test Blue Test Green Test Cyan Test Yellow XJust = MinJust Test Red Test Blue Test Green Test Cyan Test Yellow
XJust = MinJust Test Red Test Blue YJust = MaxJust Test Green Test Cyan Test Yellow
Figure 6: Examples of horizontal and vertical centering.
280
Revised May 2, 2005
This is different from the gpd_LabelledBox. The XJust and YJust members can be assigned any one of MinJust, CenterJust or MaxJust (see the CC_NUMBER.GPD dictionary). With XJust set to MinJust, the label will be aligned with the left edge of the box and extend towards the right edge. CenterJust will align the center of the text with the vertical center of the box and MaxJust will align the right edge of the label with the right edge of the box. The YJust member reacts just as it did in the gpd_LabelledBox object, i.e. MinJust will align the baseline of the label with the baseline of the box, CenterJust will align the center of the text with the vertical center of the box and MaxJust will align the tops of the label and boxes.
gpd_LabelledShape
Class { cc_Number cc_Number cc_Number cc_Number cc_Number cc_Number cc_Number cc_Number cc_String gpd_Font } gpd_LabelledShape : gpd_GraphicsObject XLocation YLocation XShape YShape XShapeScale YShapeScale XJust YJust Labels Font = = = = = = = = = = 0; 0; 0; 0; 0; 0; 0; 0; ""; 0;
The gpd_LabelledShape was especially designed for Cross Section interval symbols. The XShape and YShape members are paired up to form coordinate points that describe a single shape. This shape is assumed to be defined in a unit square with(0,0) being the upper left corner and (-1,1) being the lower-right corner. Then the shape is placed with its first coordinate at each (XLocation, YLocation) coordinate pair. The optional XShapeScale and YShapeScale members can be used to scale the shape beyond the unit square.
Revised May 2, 2005
281
The gpd_LabelledShape Class minimally requires values for the XLocation, YLocation, XShape and YShape members. Example:
gpd_LabelledShape Diamonds ( XLocation = { 1, 3, 5, 7, 9}, YLocation = 5, XShape = { 0.0, 0.5, 1.0, 0.5, 0.0 }, YShape = { -0.5, 0.0, -0.5, -1.0, -0.5 }, Labels = {ONE, TWO, THREE, FOUR, FIVE}, ); gpd_LabelledShape BowTies ( XLocation = { 1, 3, 5, 7, 9}, YLocation = 5, XShape = { 0.0, 1.0, 0.5, 1.0, 0.0, 0.5, 0,0 }, YShape = { 0.0, 0.0, -0.5, -1.0, -1.0, -0.5, 0,0 }, Labels = {ONE, TWO, THREE, FOUR, FIVE}, XJust = CenterJust, YJust = CenterJust, );
gpd_SQLNumber
Class gpd_SQLNumber : cc_Number { cc_String sqlphrase = ""; }
The gpd_SQLNumber Class is an extension to the GPDL standard developed to accommodate the retrieval of numeric information from a SQL data base. The SQL phrase given to gpd_SQLNumber can be any valid SQL phrase that results in the retrieval of one numeric column of a relational data base. There is no restriction as to the number of rows it can retrieve, but it can only retrieve on column. SQL phrases can contain macros of previously defined values. Example:
/* * * * * * * *
This example illustrates the use of previously defined macros in an SQL phrase. In the Finder implementation the user can assume that two particular cc_String macros are pre-defined by the Finder software. These are $(PROJECT), the Finder project, and $(MAP_NAME), the current map name. In this example the proportional scale of the
282
Revised May 2, 2005
* map will be used to control text heights. The calculated text * height is in points ( 1 point = 1/72 of an inch). */ cc_String MAP_SCALE = gpd_SQLNumber( SELECT MAP_SCALE FROM $(PROJECT).MAP_DEFINITIONS WHERE MAP_NAME = $(MAP_NAME)); cc_Number text_height = MAX(0.05, 6000.0/ MAP_SCALE) * 72;
gpd_SQLString
Class { cc_String } gpd_SQLString : cc_String sqlphrase = ;
The gpd_SQLString is an extension to the GPDL standard developed to accommodate the retrieval of character information from a SQL data base. The SQL phrase given to gpd_SQLString can be any valid SQL phrase that results in the retrieval of one string column of a relational data base. SQL phrases can contain macros of previously defined values. Specific examples of how all the above functions are used for the various objects created by Finder can be found in the sections below on those objects. Example:
/* * This example illustrates the use of previously defined macros * in an SQL phrase. In this case the proportional scale of the * map will be formatted into a string for inclusion in the title block. */ cc_String MAPSCALESTR = gpd_SQLString( SELECT 1: ||TO_CHAR(MAP_SCALE) FROM $(PROJECT).MAP_DEFINITIONS WHERE MAP_NAME = $(MAP_NAME));
Finder GPDL Arithmetic and Geometric Functions
Revised May 2, 2005
283
The arc_x and arc_y functions can be used to display segmented circles and arcs via the gpd_Polyline and gpd_Polygon objects.
gpd_Polyline QuarterEllipse ( X = { arc_x (0, 2, 0, 90, 1) }, Y = { arc_y (0, 1, 0, 90, 1) } ); gpd_Polyline FilledQuarterEllipse ( X = { 0, arc_x (0, 2, 0, 90, 1), 0}, Y = { 0, arc_y (0, 1, 0, 90, 1), 0} ); /* This ellipse will be a quarter of a pie filled in with */ /* the color specified in the FillBackground member of the context */
Table 7: Explanation of the Finder arithmetic functions
Function
Max (value1, value2)
Explanation
The Max function can be used to return the largest numeric value of two values. The Min function can be used to return the smallest numeric value of two values. The Cos function can be used to return the trigonometric cosine of the radian argument. The Sin function can be used to return the trigonometric cosine of the radian argument. The ABS function can be used to return the absolute value of the argument. The AVERAGE function can be used to return the arithmetic average of a list of arguments.
Min (value1, value2) Cos (radian_argument) Sin (radian_argument) ABS (value) AVERAGE (value1, value2, ... valueN)
284
Revised May 2, 2005
Table 7: Explanation of the Finder arithmetic functions
Function
arc_x (XCenter, XRadius, StartingAngle, EndingAngle, Direction) arc_y (YCenter, YRadius, StartingAngle, EndingAngle, Direction)
Explanation
The arc_x and arc_y functions can be used to return an array of points representing an arc that will sweep from StartingAngle to Ending Angle, and centered about XCenter, YCenter. The Direction argument is 1 for a counterclock wise sweep (in the direction if increasing angle magnitude), or -1 for a clock wise sweep (decreasing angle magnitude).
The only difference between using a gpd_Polyline versus a gpd_Polygon object, is that the polygon will be filled and the polyline will not. Care must be taken when trying to display arcs as opposed to circles which are guaranteed to be closed. If the arc is supposed to be a pie slice rather than a single sweeping arc, especially for filled arcs, it is wise to start the X and Y members at the center location of the arc, followed by the appropriate calls to arc_x and arc_y, and completed with the center locations. This way you are guaranteed if the pie is to be closed, it will be filled as you would expect, rather than filling the arc by joining the first and last points of the arc (which will not pull the filled area back up to the origin to create the pie slice).
Customizing Title Blocks, Lease Legends and Logos

In order to understand how to customize title blocks, lease legends and logos, we will work through a few examples starting with a simple logo and moving on from there. Most of the GPDL functions will be shown in the examples that follow. If you are using a GPDL logo file from a previous version of Finder and find that it does not appear in the current version of Finder, first check that the old FillColor members of the gpd_Context objects are renamed as FillBackground, or the object will not be filled with the correct color. Second, if the object seems to want to join with another corner of the Region, expand the gpd_Region attached to the gpd_GraphicsProduct such that it fully encloses all graphical objects.
Revised May 2, 2005
285
Creating a Simple Logo

The logo shown below is simple and will illustrate some of the custom features of the Finder implementation of GPDL. The annotated source code follows. This logo example shows how to create polygons, polylines and text objects and draw them. Note that for the sake of simplicity, all the text in the logo are drawn as text objects. This is not generally recommended, since fonts will not necessarily be the same from one GKS device driver to the next. To be sure to maintain the desired look to the characters, you should draw the character outlines as polygons. This will also insure that scaling and aspect ratio are preserved as the object is scaled to various sizes.
Figure 7: Example logo as drawn by the example GPDL file
Example Logo GPDL File - bog.gpd

The file below is a fairly simple example of what can be done with GPDL. It seems lengthy because each step is commented as to what it is supposed to accomplish and includes some tips to keep in mind as you create a GPDL file.
286
Revised May 2, 2005
bog.gpd /* ------------------------------------------------------------------------ */ /* Example BOG LOGO -------------------------------------------------------- */ /* ------------------------------------------------------------------------ */ /* Define the text objects to be used. There are two. The big bold fancy BOG, */ /* and the smaller more modest Big Oil & Gas. These are represented by pairs */ /* of gpd_PolyCText and gpd_Font functions that define the text and its display*/ /* attributes. All objects in this logo are aligned to a XY grid with 0,0 as */ /* origin and extending up from there in both directions.*/ /*--------------------------------------------------------------------------*/ /* First text object: Big Oil & Gas */ gpd_PolyCText BOGText ( X = 0.5, Y = 0.15, Content = "Big Oil & Gas", Font = BOGFont, XJust = CenterJust, ); gpd_Font BOGFont ( FontSize = 4, FontFamily = TRIPLEX ITALIC, ); /* Second text object: BOG */ /* Note that the X and Y coordinates are the same as the center of the ellipse */ /* in which it will be displayed. This text object is tied to its display */ /* characteristics by referencing the gpd_Font definition in the gpd_PolyCText*/ /* Font member. The XJust and Yjust make sure the text is aligned in the exact*/ /* center over the assigned point. This is done because the default behaviour */ /* of CenterJust is different from the behaviour if it is explicitly specified.*/ gpd_PolyCText BOGLogoText ( X = 0.5, Y = 0.65, Content = "BOG", Font = BOGLogoFont, XJust = CenterJust, YJust = CenterJust, ); /* Note that you can look up which fonts are available for display by */ /* displaying the parameter list for the TEXT FONT option of the GRAPHIC */ /* OBJECTS overlay in the Finder Map Definition dialog.*/ gpd_Font BOGLogoFont ( FontSize = 12, FontFamily = "GOTHIC ITALIAN", FontWidth = Wide, ); /* -------------------------------------------------------------------------*/ /* This draws the elipse used as the background for the logo. It uses the arc_x*/ /* and arc_y functions to define the boundaries of the elipse. The format is: */ /* X = {arc_x(Circle Center X coordinate, X Radius, Start angle, End angle, */ /* direction)} */ /* where the start and end angles are in degrees from the positive X axis in the*/ /* direction specified, which is -1 for clockwise and 1 for counter-clockwise.*/ gpd_Polygon BOGelipse
Revised May 2, 2005
287
( X = { arc_x ( .50, .50, 0, 360, 1) }, Y = { arc_y ( .65, .35, 0, 360, 1) }, ); /* ------------------------------------------------------------------------ */ /* This section uses several polylines to draw the little oil derrick on the */ /* top of the elipse. The main difference between gpd_Polyline and gpd_Polygon */ /* is that gpd_Polygon expects to be filled. The arc_x/arc_y functions still */ /* apply and can be used if desired.*/ gpd_Polyline RigOutline ( X = { .425, .475, .525, .575 }, Y = { .950, 1.150, 1.150, .950 }, ); gpd_Polyline RigInsideX ( X = { .475, .55, .45, .525 }, Y = {1.15, 1.05, 1.05, 1.150 }, ); gpd_Polyline RigKelly ( X = { .50, .500 }, Y = { 1.0, 1.150 }, ); gpd_Polyline RigDrillString ( X = { .50, .50}, Y = { 1.00, .65}, ); /* ------------------------------------------------------------------------ */ /* Context Definitions. This section of the file sets a number of sets of */ /* display attribute definitions. You can have as many of these as you want */ /* and they do not all need to be referenced in other functions in the file.*/ /* You might want to develop a library of Graphic Contexts that are what you*/ /* commonly use and save them away in a template file that you routinely */ /* include in any GPD files you create.*/ /* Note also the values for the various Context members such as colors, fonts, */ /* and pen tips. Most of these values are defined in the cc_number.gpd file */ /* which is executed before this file is executed. Any variables defined in */ /* cc_number.gpd can be referenced as though they are locally defined.*/ gpd_Context FILLBLUE ( FillColor = DODGER BLUE, FillBackground = DODGER BLUE, LineColor = BLUE, TextColor = YELLOW ); gpd_Context BOGbw ( FillColor = BLACK, FillBackground = BLACK, LineColor = BLACK, TextColor = WHITE, PenTip = Heavy ); gpd_Context BOGText ( TextColor = BLACK
288
Revised May 2, 2005
); gpd_Context WhiteLine ( LineColor = WHITE, PenTip = Heavy ); /* ------------------------------------------------------------------------ */ /* The gpd_GraphicsProduct function pulls all the elements defined above and */ /* sets up how it is to be drawn. It usually contains a Region statement to set*/ /* the boundaries of the overall object (in the order minX, minY, maxX, maxY). */ /* In the example below, note that the Region is defined to extend slightly */ /* beyond the maximum extents of the object. This is recommended, as anything*/ /* outside the region will be clipped. It will also contain one or more */ /* gpd_Draw functions to render the objects defined earlier in the file.*/ /* Generally, you would have a gpd_Draw for each object to be drawn. Any */ /* objects that are defined in a file but are not included in a gpd_Draw */ /* function will be ignored. You can also include a Background color and Title.*/ gpd_GraphicsProduct Mine ( Region = gpd_Region (-.1, -.1, 1.1, 1.25), Title = "BOG Logo", { gpd_Draw (BOGelipse , GC=BOGbw), gpd_Draw (BOGLogoText, GC=BOGbw), gpd_Draw (BOGText, GC=BOGText), gpd_Draw (RigOutline, GC=BOGbw), gpd_Draw (RigInsideX, GC=BOGbw), gpd_Draw (RigKelly, GC=BOGbw), gpd_Draw (RigDrillString, GC=WhiteLine), } );
Customizing Title Blocks

The Finder plotting system provides a default title block for maps and cross sections that is not drawn using GPDL files. You might want to customize the title block for use on your plots by incorporating a logo or other information from the database in your title block. Finder provides a GPDL title block you can use as a template in the file finder_titleblock.gpd. This is a fairly complicated file, but here are a couple of hints about how to customize it to your needs. Continuing with our Big Oil & Gas example, lets put our new logo into this title block and change the name that appears in the header. We follow these steps. 1. Determine the extents of the title block and the position of the area in which we want to place the logo. 2. Comment out the old logo and insert the new logo. 3. Determine the scale factor and translations necessary to put the logo where we want it.
Revised May 2, 2005
289
4. Edit the boiler plate company name. Each of these steps is explained below. 1. Determine the extents of the title block and the position of the area in which we want to place the logo. Make a copy of the finder_titleblock.gpd file and open it with an editor. At the top of the file is a number of variable definitions. The variables Height and Width are used as the basis for calculating all the other dimensions in the file and both are set to a value of 5. The rendering of the original file is shown below as a reference for the discussion that will follow.
GeoQuest Data Management Division
Figure 8: The default appearance of the finder_titleblock.gpd file
The area where we want to put the new logo is in place of the old logo in the upper left corner. We can use the variables defined in the file to determine where that might be.
290
Revised May 2, 2005
The heights of the horizontal lines that subdivide the title block are calculated in the section from the file shown below.
cc_Number Border = 0; cc_Number Height = 5; cc_Number Width = 5; cc_Number cc_Number cc_Number cc_Number MaxX = Border + Width + Border; MaxY = Border + Height + Border; HeightDelta = Height / 13; HHeightDelta = HeightDelta / 2;
gpd_Context DefaultContext ( LineColor = BLACK, LineTexture = Solid, PenTip = Light, TextColor = BLACK ); /* ----------------------------------------------------- */ /* SIZE OF BOX THAT ENCLOSES LOGO ------------------------ */ /* ----------------------------------------------------- */ cc_Number Line1Y = Border + (HeightDelta ); cc_Number Line2Y = Border + (HeightDelta * 2); cc_Number Line3Y = Border + (HeightDelta * 3); cc_Number Line4Y = Border + (HeightDelta * 4); cc_Number Line5Y = Border + (HeightDelta * 10); cc_Number Line8Y = Border + (HeightDelta * 5); cc_Number LogoSQDim = (Border + Height) - Line5Y;
2. Determine the scale factor and translations necessary to put the logo where we want it. While having all these variables dynamically set, we need to know how to scale our logo to fit into the top area. We know from our previous example that the height of the logo is 1.15 and the width is 1. The last line of code shown above shows the calculation of the height of the upper box in the titleblock. Our scale factor, then, will be this dimension reduced by a small amount (.1) so the logo doesnt hit the lines, divided by 1.15. We will apply the same scale factor in both X and Y to preserve the aspect ratio.
Revised May 2, 2005
291
Moving the logo to the top of the title block involves defining a translation that shifts the logo from its 0,0 origin to the box at the top. The new baseline we want is defined by Line5Y in the definitions shown above. By adding the following lines we can define the variables we will need to set the scale and translation.
cc_Number LogoScFact = ((LogoSQDim - .1) / 1.15); gpd_Scaling LogoScale (LogoScFact,LogoScFact); gpd_Translation LogoTrans (Border + .1,Line5Y);
3. Next, to invoke all these definitions, we need to combine them in a gpd_Transform command, as shown below. Note the use of the XOrigin and YOrigin parameters. These are required so that the scaling is done in the original frame of reference before translation. If left off, each element of the logo will be drawn and scaled independently and may not retain the correct relationships to the other objects in the logo. The values to use for these are the X and Y values for the center of the object in its own frame of reference.
gpd_Transform MoveLogo { Translation = LogoTrans, Scaling = LogoScale, XOrigin = .5, YOrigin = .575, };
4. Comment out the old logo. The Finder GPDL uses the standard C notation /*...*/ to identify comments in the GPDL files. Enter these around the commands that set up the logo as shown below. Note: When using comments in GPDL, you need to be careful not to enclose comments within comments. If this happens, the parser may become confused and the drawing will not be rendered as expected.
292
Revised May 2, 2005
/* ------------------------------------------------ */ /* Comment out old logo stuff gpd_Context LogoContext ( LineColor = BLACK, LineTexture = Solid, PenTip = Medium); cc_Number XPOS = Border + (LogoSQDim / 5); cc_Number YPOS = Line5Y + (LogoSQDim / 5); . . . gpd_Translation Tran5 ( XOffset = XOff*5, YOffset = YOff*5 ); gpd_Translation Tran6 ( XOffset = XOff*6, YOffset = YOff*6 ); gpd_Translation Tran7 ( XOffset = XOff*7, YOffset = YOff*7 ); end of commented out logo stuff */
5. Insert the definitions and commands from the logo file.

/* Insert the BOG logo */ /* First text object: Big Oil & Gas */ gpd_PolyCText BOGText ( X = 0.5, Y = 0.15, Content = "Big Oil & Gas", Font = BOGFont, XJust = CenterJust, ); gpd_Font BOGFont . . . gpd_Context WhiteLine ( LineColor = WHITE, PenTip = Heavy ); /* End of BOG Logo drawable objects*/
Revised May 2, 2005
293
6. Comment out the gpd_Draw commands for the old logo from the gpd_GraphicsProduct clause and insert the gpd_Draw commands for the new logo. Note that to put the logo where we need it, we need to add the XF clause to the new logos gpd_Draw commands in order to reference the Transform we defined earlier. The revised gpd_Draw commands should appear as shown below:
gpd_Draw gpd_Draw gpd_Draw gpd_Draw gpd_Draw gpd_Draw gpd_Draw (BOGelipse, GC=BOGbw, XF=MoveLogo), (BOGLogoText, GC=BOGbw, XF=MoveLogo), (BOGText, GC=BOGText, XF=MoveLogo), (RigOutline, GC=BOGbw, XF=MoveLogo), (RigInsideX, GC=BOGbw, XF=MoveLogo), (RigKelly, GC=BOGbw, XF=MoveLogo), (RigDrillString, GC=WhiteLine, XF=MoveLogo),
7. Edit the boiler plate company name. Search for the definition of the string named CompanyString and change it to the new company name as shown below.
/* ------------------------------------------------ */ /* TEXT STRINGS ------------------------------------ */ /* ------------------------------------------------ */ cc_String ProjectString = { "Project: $(PROJECT)" }; cc_String CompanyString = { "Big Oil and Gas, Inc." };
8. Also, the default SIMPLEX font is a bit boring, so we may want to dress it up by having it use a different font. In the example below, the CompanyText object has been modified to reference a newly defined font.
gpd_PolyCText CompanyText ( X = ((Width - LogoSQDim) / 2) + LogoSQDim, Y = Line5Y + (LogoSQDim / 2), Content = CompanyString, XJust = CenterJust, YJust = CenterJust, Font = BOGcoFont, ); gpd_Font BOGcoFont ( FontFamily = TRIPLEX ROMAN, FontSize = 12, );
294
Revised May 2, 2005
9. Test the new title block by displaying it in a GPDL window in the Layout Designer. The final title block will look something like figure 9 below.
Figure 9: Final title block with new logo and company name inserted.
Customizing Lease Legends

Lease legends are very complicated and require set variables and values in order to work properly. A template file is provided that you can use to customize to fit your needs. It contains many comments to help you understand what is being done and which parameters you should and should not change. The bulk of the parameters you might want to customize are in a special section in this file titled USER DEFINED PARAMETERS START HERE. These parameters give you control over the overall dimensions and layout of the lease legend. It is best to determine what the overall appearance you desire, then copy this file and adjust the parameters according to your needs.
Revised May 2, 2005
295
Customizing Cross Section Symbol Tracks

Finder has the ability to display specific interval data about a well upon its cross section. This is done by using two GPDL files. One to describe the way the interval will be represented upon the cross section, Another to communicate to Finder how it is to retrieve the data from the database (usually the project account but actually any database table).
This linkage allows you display any predefined data type (GPDL file type #2) with any predefined representation (GPDL file type #1). The first type of file is listed in the LogPlot Track Symbol Definition dialog within the Symbol Appearance selector box. The second type of GPDL files are selected from the Data Selection selector box of the same dialog. The GPDL files contain statements that define objects that are combined together to create the final picture of what the interval will really look like. These statements are described above in the The Graphics Product Description Language (GPDL) on page 259.
The Symbol Appearance GPDL Files

Due to the fact that there are many drawable objects in Finder's implementation of GPDL, and the different parameters for these objects, describing the objects that can be used for interval symbols is extremely weighty. The GPDL files themselves are often organized into 6 parts.
The File Header

This describes the basic appearance of the symbol and the variables that the file inherits from both the data selection file and the Cross Section module
The SQL Retrieval Statements

These are the statements that assign the results of a SQL retrieval to variables that are used to create the symbol. UpperRightY The distance from the bottom of the cross section to the top of this interval.
296
Revised May 2, 2005
ANNO A list or array of labels for each interval for a single well.
MD_INT A list or array of interval depths for the intervals of a single well
The Graphical Transformation Object Statements

These will place the drawable object properly within the Finder cross section window.
The gpd_GraphicsProduct Definition.

This statement defines the gpd_GraphicsProduct object. Each object that is to be displayed or drawn must be listed here as one of the components of this product.
The Drawable Objects The Attribute Objects for the Drawable Objects.
These include the gpd_Font and the gpd_Context objects. The gpd_Font (if present) will define attributes to be used for the labels if they are to be displayed. The gpd_Context (if present) will define attributes that will be used to render the symbol and its labels. When customizing these files the only parts that should be edited are items 5 and 6.
Editing the Drawable Objects of a Symbol Appearance GPDL File

The drawable objects that are most useful for symbol appearances are. gpd_LabelledShape, gpd_LabelledBoxz, gpd_PolyCText.
Other drawable objects (like gpd_Polygon and gpd_Polyline objects) do not have the capabilities to display many times and thus, are difficult to display many intervals. These object types are not recommended!
Revised May 2, 2005
297
Each of the usable objects have their advantages. gpd_PolyCText can be used for just displaying text strings. gpd_LabelledBoxz is more sophisticated than the gpd_LabelledBox in that each box can have a different width and height and the boxes may overlap. The boxes are filled (unless the color for that box is the string BACKGROUND) and can be patterned. Labels can be assigned through the labels member, as can text justifications (XJust and YJust) and a font (Font). gpd_LabelledShape is even more sophisticated than the gpd_LabelledBoxz. These objects are defined with a basic shape. Then the shape is placed with the first point at a particular (X, Y) location and can be scaled such that the shape is the proper length of the interval it depicts (YShapeScale), and with as specified in the MaxWidth parameter (XShapeScale). This object enables the user to make symbols like triangles, arrows or almost anything that can be described by a list of X and Y pairs.
Editing Common Members of the Drawable Objects

All the gpd_PolyCText, gpd_LabelledShape and gpd_LabelledBoxz objects contain these members in common. table 12 on page 303 describes the names of these common members according to their object type.
Table 8: Common members of the symbol appearance Drawable Objects
gpd_Labelled Boxz
X Y XJust YJust Font BoxLabels BoxColors BoxWidth
gpd_LabelledShape
XLocation YLocation XJust YJust Font Labels [See Note] **XShapeScale
gpd_PolyCText
X Y XJust YJust Font Content
Type
CC_NUMBER CC_NUMBER CC_NUMBER CC_NUMBER GP_FONT CC_TCP CC_TRGBP CC_NUMBER
298
Revised May 2, 2005
Table 8: Common members of the symbol appearance Drawable Objects
gpd_Labelled Boxz
BoxHeight
gpd_LabelledShape
**YShapeScale
gpd_PolyCText
Type
CC_NUMBER
Note:
The colors for the shapes are inherited from the gpd_Context that is attached to the named gpd_LabelledShape inside the gpd_GraphicsProduct object. The FillBackground member of the gpd_Context is the list of colors that will be used to fill in the shapes. See the BoxColors Common Member on page 304.
X (or XLocation) Common Member

This is, customarily, a single number (although it may be more than one). It will define the X location of the left-edge symbol. The Finder product will compute this value and send a variable called JUSTIFY_DELTA down to the GPDL sub-system so each symbol will be properly placed in the requested track for each well. Assignment:
X = 0 + JUSTIFY_DELTA or: XLocation = 0 + JUSTIFY_DELTA (for gpd_LabelledShape)
Caution: Changing this value is not recommended. Y (or YLocation) Common Member
This is a list or array of values that defines the top of the interval that this symbol will represent. The value is retrieved from the database using the definitions from the data selection file.
cc_Number UpperRightY = gpd_SQLNumber ("Select ( $(XS_BASE) - $(TABLE_TOP_COL) ) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" );
This SQL request will assign to the variable UpperRightY, an array of numbers (gpd_SQLNumber) resulting from subtracting the top of the data's interval (TABLE_TOP_COL) from the bottom of the cross section interval (XS_BASE). Graphically, this will be the distance from the bottom of the cross section to the top of the interval.
Revised May 2, 2005
299
Assignment:
Y = UpperRightY or: YLocation = UpperRightY (for gpd_LabelledShape)
Caution: Changing this value is not recommended. XJust Common Member

This is a single value or list (i.e. array) of values that will adjust how the label (if there is one) will be placed horizontally, with respect to the X and Y members (described above). Usually assigning more than one value, although valid, will be confusing so this practice is not recommended.
Table 9: XJust valid values
Value
Description
horizontally align the label with the symbol's left edge.The text will extend to the right of the symbol. horizontally align the label with the symbol's center. horizontally align the label with the symbol's right edge.The text will extend left, beyond the edge of the symbol. horizontally give the label the same justification as that of the symbol.
XS_XJUST_DEFAULT
Note:
For gpd_LabelledShapes: The XJust defaults to CenterJust, but with a different meaning than if explicitly assigned. If both the XJust and YJust members are allowed to default to CenterJust, the label will be located in the graphical center of the object. Essentially, the label will be placed in the center of the largest area of the shape. Explicitly assigning the XJust and YJust to CenterJust will center the label at the mid-point of the shape. Assignment:
XJust = MinJust or: XJust = CenterJust or: XJust = MaxJust or: XJust = XS_XJUST_DEFAULT
This value may be changed for fine-tuning of horizontal position.
300
Revised May 2, 2005
YJust Common Member

This is a single value or list (i.e. array) of values that will adjust how the label (if there is one) will be placed vertically, with respect to the X and Y members (described above). Usually assigning more than one value, although valid, will be confusing so this practice is not recommended.
Table 10: YJust valid values
Value
Description
Vertically align the label with the symbol's bottom edge.The text will extend up from the symbol. Vertically align the label with the symbol's center. Vertically align the label with the symbol's top edge.
Note:
For gpd_LabelledShapes: The XJust defaults to CenterJust, but with a different meaning than if explicitly assigned. If both the XJust and YJust members are allowed to default to CenterJust, the label will be located in the graphical center of the object. Essentially, the label will be placed in the center of the largest area of the shape. Explicitly assigning the XJust and YJust to CenterJust will center the label at the mid-point of the shape. Assignment:
YJust = MinJust or: YJust = CenterJust or: YJust = MaxJust
This value may be changed for fine-tuning of vertical position.
Font Common Member

The gpd_Font object will only be used by the symbol labels, and gpd_PolyCText objects. It is assigned through the following substatement.
Font = <FontName>
Revised May 2, 2005
301
Valid members are shown in table 15, below.

Table 11: Valid font common members
Member
FontSize
Description
The size (height) of the text. This value needs to be in points, so if the size you wish to use is in inches, multiply the value by 72 (there are 72 points in an inch). The type of font to use (ie: DUPLEX ROMAN, FILLED ROMAN) The condensing factor for the text
Valid range
Greater than zero
Default
14 points
FontFamily
Any of the Finder fonts (all capitals) Any one of: Ultra-Condensed Extra-Condensed Condensed Semi-Condensed Normal Semi-Bold Bold Extra-Bold
SIMPLEX
FontWidth
Normal
This value may be changed for fine-tuning of label size.
302
Revised May 2, 2005
Table 12: Graphics Context valid members (more than one can be assigned.)
Member
TextColor LineColor FillColor
Description
A color or list of colors that will be used to display text and labels. A color or list of colors that will be used to display lines. A color or list of colors that will be used to display the lines of a pattern within a filled area. A color or list of colors that will be displayed beneath a non-solid line. This is the way to achieve something like a BLACK and RED dashed line (by making the LineBackground BLACK and the LineColor WHITE and the LineTexture Dashed). A color or list of colors that will be used to fill a filled area. A thickness or list of thicknesses that will be used to display lines and the lines in a pattern. A style of line to render in the LineColor. A string or list of strings identifying the pattern that will be used to fill in an area.
Valid values
Any Finder color (all capitals) Any Finder color (all capitals) Any Finder color (all capitals) Any Finder color (all capitals)
Default
BLACK BLACK BLACK
LineBackground
None. Must be specified to be activated.
FillBackground PenTip
Any Finder color (all capitals) Invisible, Light, Medium, Heavy, MediumHeavy, ExtraHeavy Solid, ShortDashed, LongDashed, Dotted, None e.g.: SHALE, DOLOMITE, LIMESTONE, 45_DEGREE_LINES, 6_POINT_CIRCLES. (See the section on patterns).
BLACK Light
LineTexture
Solid
FillPattern
None. Must be specified to be activated.
Graphics Context Common Members

The gpd_Context object is attached to the drawable object through the gpd_Draw member of the gpd_GraphicsProduct. For example, the following substatement inside the gpd_GraphicsProduct object, would display the object called MyLabelledShape according to the graphical parameters defined in the gpd_Context called MyContext.
Revised May 2, 2005
303
gpd_Draw ( MyLabelledShape, GC = MyContext )
This value may be changed for fine-tuning.
BoxLabels or Labels or Content Common Member

If this assignment is done, the object will be displayed with labels. The labels are retrieved from the database using the definitions from the data selection file.
cc_String ANNO = gpd_SQLString ("Select $(ANNO_STRING) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" );
This SQL request will assign to the variable ANNO, an array of character strings (gpd_SQLString) resulting from retrieving the formatted string defined in the data selection file (ANNO_STRING) from the appropriate tables. Assignment:
BoxLabels = UpperRightY or: Labels = CenterJust or: Content = CenterJust
Caution: Changing this value is not recommended. Instead you should change the assignment of the string that will be retrieved, in the data selection file (ANNO_STRING). BoxColors Common Member
This member is only valid for the gpd_LabelledBoxz and gpd_LabelledShape objects since they are the only ones with a filled-in area. The value is explicitly set for the gpd_LabelledBoxz, and implied by the FillBackground member of the gpd_Context object assigned to the gpd_LabelledShape object:
304
Revised May 2, 2005
gpd_LabelledBoxz ABoxz| gpd_LabelledShape AShape (| ( ...| ... BoxColors = GREEN,| ... ...| ... );| ); gpd_GraphicsProduct DoIt| gpd_GraphicsProduct DoIt (| ( ...| ... {| { gpd_Draw(ABoxz,...,GC=MyGC), | gpd_Draw (AShape,...,GC=MyGC), }| } ...| ... );| ); gpd_Context MyGC| gpd_Context MyGC (| ( ...| FillBackground = GREEN, );| );
In the event that there is a FillBackground member of the gpd_Context that is tied to the gpd_LabelledBoxz, it will be ignored unless the BoxColors member is missing.
BoxWidth or XShapeScale Common Member

This is a single value or array of values that will be used to set the width of the filled-in area. The usefulness of this parameter is especially useful if it is set by a retrieved data value whose select clause is set in the data selection file, much like the label. If it is not dynamic, it is set to the variable XS_WIDTH, sent down from the cross section module, and corresponding to the MaxWidth parameter for that symbol. Assignment:
BoxWidth = XS_WIDTH or: XShapeScale = XS_WIDTH
This value may be changed for fine-tuning.
Revised May 2, 2005
305
BoxHeight or YShapeScale Common Member

This is a single value or array of values that will be used to set the height of the filled-in area. It corresponds to the depth of the interval. These values are retrieved from the database using the definitions from the data selection file.
cc_Number MD_INT = gpd_SQLNumber ("Select GREATEST ( ( $(TABLE_BASE_COL) - $(TABLE_TOP_COL) ) , .001 ) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" );
The interval is determined by subtracting the base from the top for this interval. The actual value that will be used for the interval's depth is this depth or 0.001, whichever is greatest. The SQL GREATEST function is useful for intervals whose top and base are identical. By forcing the depth to be of some value greater than zero, you are ensured the patterning and filling of the area does not result in any GKS errors. Assignment:
BoxWidth = MD_INT or : XShapeScale = MD_INT
Changing this value is not recommended.
Editing a gpd_PolyCText Object

The basic syntax of a gpd_PolyCText is as follows.
gpd_PolyCText <NAME_OF_THE_OBJECT> ( X = 0 + JUSTIFY_DELTA, Y = UpperRightY, Content = ANNO, XJust= <SINGLE_OR_LIST_OF_JUST_VALUES>, YJust= <SINGLE_OR_LIST_OF_JUST_VALUES>, Font= <NAME_OF_A_DEFINED_FONT_OBJECT>, );
The X, Y and Content members are required. If any of the three are missing, the object will not display. Their assignments, as described above, should not be altered (see the XJust Common Member on page 300 and the YJust Common Member on page 301).
306
Revised May 2, 2005
Editing a gpd_LabelledBoxz Object

The basic syntax of a gpd_LabelledBoxz is as follows.
gpd_LabelledBoxz <NAME_OF_THE_OBJECT> ( X = 0 + JUSTIFY_DELTA, Y = UpperRightY, BoxWidth = XS_WIDTH, BoxHeight = MD_INT, BoxLabels = ANNO, BoxColors = <SINGLE_OR_LIST_OF_COLORS>, XJust = <SINGLE_OR_LIST_OF_JUST_VALUES>, YJust = <SINGLE_OR_LIST_OF_JUST_VALUES>, Font = <NAME_OF_A_DEFINED_FONT_OBJECT>, );
Revised May 2, 2005
307
The X, Y, BoxWidth and BoxHeight members are required. If any of the three are missing, the object will not display. Their assignments, as described above, should not be altered (as stated in the previous section referring to these common members), except for the BoxWidth parameter. See the Customizing Visual Attributes from the Data Selection File on page 312 for ways to alter the width of the boxes based on a column in the Data Selection. The BoxLabels member can be omitted. Doing this will cause no labels to be posted on the box, and the XJust, YJust and Font members will also be ignored. The BoxColors member can be ignored if the FillBackground member of the assigned gpd_Context is set to the colors to fill the boxes. Otherwise, it can be set to a single color or a list of colors. Examples: The following are valid.
BoxColors = GREEN, BoxColors = { GREEN, YELLOW },
In the second example every odd box (1st, 3rd, 5th, etc) will be green and every even box (2nd, 4th, 6th, etc) will be yellow. See the XJust Common Member on page 300, the YJust Common Member on page 301 and the Font Common Member on page 301.
Editing a gpd_LabelledShape Object

The basic syntax of a gpd_LabelledShape is as follows.
gpd_LabelledShape <NAME_OF_THE_OBJECT> ( XLocation = 0 + JUSTIFY_DELTA, YLocation = UpperRightY, XShape = <X_POINTS_COMPRISING_A_SHAPE> YShape = <Y_POINTS_COMPRISING_A_SHAPE> XShapeScale = XS_WIDTH, YShapeScale = MD_INT, Labels= ANNO, XJust= <SINGLE_OR_LIST_OF_JUST_VALUES>, YJust= <SINGLE_OR_LIST_OF_JUST_VALUES>, Font= <NAME_OF_A_DEFINED_FONT_OBJECT>, );
308
Revised May 2, 2005
The XLocation, YLocation, XShape and YShape members are required. If any of the three are missing, the object will not display. The assignments of the XLocation and YLocation members should not be altered from the values listed above. The XShape and YShape members are the most important ones of this object. Each is a list of points that will be combined together to create single basic shape. This offers an advantage over the gpd_LabelledBoxz in that the shape no longer needs to be a rectangle. The first point in the array should be the upper-left corner of the object. This point will be the one that will be placed at the location of the top of the interval. The range of the shape is X: 0 to 1, Y: 0 to -1 (decreasing downwards) Figure 10 on page 310 illustrates an example in which the shape is a simple clipped triangle.
Revised May 2, 2005
309
Shape
0 -0.5 Y
Apply the Grid
-1.0 0 0.5 X 1.0
0 -0.5 Y -1.0 0 0.5 X 1.0
Gridded Shape
Figure 10: Example of applying a grid to a shape to derive the XShape and YShape coordinates.
Thus you would arrive at the appropriate XShape and YShape members as follows.
XShape = { 0.0, 0.30, 1.0, 0.0, 0.0 }, YShape = { 0.0, 0.00, -1.0, -1.0, 0.0 }
310
Revised May 2, 2005
The XShapeScale and YShapeScale members, if specified, will then be applied to the shape to stretch it out wider (to expand to fit the desired maximum width) the longer to become the depth of the data's interval. If they are omitted, the shape will remain the size specified in the XShape and YShape arrays. The importance of the X range (0 to 1.0 inclusive) is that the gridded shape will be scaled such that the widest point (at 1.0) can be scaled to be identical to the XShapeScale value. Thus, if the XShapeScale is set to XS_WIDTH, the widest point of the shape will expand to be the maximum width requested for this shape (XS_WIDTH). As with the gpd_LabelledBoxz, if the Labels member is missing there will be no labels displayed on the shape (and the XJust, YJust and Font members will be ignored).
XJust and YJust Unspecified
<Label>
XJust and/or YJust set to CenterJust
<Label>
Figure 11: Example of the behavior of CenterJust as the default and as explicitly specified.
Note:
Special note about labels text justification for gpd_LabelledShape If there are labels that are to be applied to this gpd_LabelledShape, by not defining the XJust and YJust members (ie: letting them default), will force the cross section module to find the graphical center for the labels. If either the XJust or YJust members are set to CenterJust, the label will be placed at the mid-point of the shape:
Revised May 2, 2005
311
Customizing Visual Attributes from the Data Selection File

Since the data selection GPDL file knows about the data and the specific columns that can be retrieved from that table, the file can also perform other retrievals to assign more variables. These variables can be applied to the Symbol Appearance GPDL files to further customize the symbol and thus increase the sophistication and flexibility of the system. Here are some examples of this application. Example: 1. Assume we have the following table.
SQL> describe LITHOLOGIES Name ------------------------UWI TOP BASE LITHOLOGY ASSUREDNESS
Null? -------NOT NULL
NOT NULL
Type ---VARCHAR2(20) NUMBER(10,5) NUMBER(10,5) VARCHAR2(12) NUMBER
2. Then describe a list of how data values will be decoded into attributes.
LITHOLOGY COLOR ------------- -----------SANDSTONE YELLOW LIMESTONE LIGHT BLUE DOLOMITE VIOLET SHALE GREY ??? RED PATTERN ------------SANDSTONE LIMESTONE DOLOMITE SHALE UNKNOWN
(any unrecognized pattern name will cause no pattern to be displayed) 3. We can set up intermediate variables that will hold the SQL decode sub-statements to decipher the LITHOLOGY column into the desired colors.
cc_String DECODE_COLOR_STRING = "DECODE (LITHOLOGY, 'SANDSTONE', 'YELLOW' , 'LIMESTONE', 'LIGHT BLUE', 'DOLOMITE' , 'VIOLET' , 'SHALE' , 'GREY' , 'RED')";
312
Revised May 2, 2005
cc_String DECODE_PATTERN_STRING = "DECODE (LITHOLOGY, 'SANDSTONE', 'SANDSTONE', 'LIMESTONE', 'LIMESTONE', 'DOLOMITE' , 'DOLOMITE' , 'SHALE' , 'SHALE' , 'UNKNOWN')";
4. Now we can retrieve the actual values, much like the ANNO_STRING variable is used to retrieve the ANNO list that will be used for labels.
cc_String DATA_SEL_COLOR = gpd_SQLString ("SELECT $(DECODE_COLOR_STRING) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" ); cc_String DATA_SEL_PATTERN = gpd_SQLString ("SELECT $(DECODE_PATTERN_STRING) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" );
5. Now, if the appropriate Symbol Appearance GPDL file is changed to use these new variables (DATA_SEL_COLOR and DATA_SEL_PATTERN), are then assigned to these variables, the visual attributes of the symbols will change according to that interval's lithology column. 6. Likewise, if the ASSUREDNESS is a positive number between 1 and 5, indicating how valid this rows correctness is, we can scale the symbol according to that column.
cc_Number DATA_SEL_WIDTH = gpd_SQLNumber ("Select ( $(XS_WIDTH) * ABS(RANK / 5) ) $(FROM_CLAUSE) $(WHERE_CLAUSE) $(ORDER_BY_CLAUSE)" );
This will, for each interval, divide the actual width desired for the symbol by the ASSUREDNESS column. Thus, for these intervals: a. ASSUREDNESS of 1 would be 1/5th the desired width. b. ASSUREDNESS of 2 would be 2/5th the desired width. c. ASSUREDNESS of 3 would be 3/5th the desired width. d. ASSUREDNESS of 4 would be 4/5th the desired width. e. ASSUREDNESS of 5 would be exactly the desired width.
Revised May 2, 2005
313
We must retrieve this value from the database using a SQL SELECT statement because performing a simple division will not work properly in this version of the GPDL sub-system. As you can see, you can alter an object's member by applying an arithmetic function or a DECODE statement to a column and the assigning the result to the appropriate member in the symbol appearance file. of course, if a data selection file that performs some of these retrievals is coupled with a symbol appearance file that does not use these variables, the outcome will be as the symbol appearance file is specified. If the symbol appearance file is expecting one of these variables to be passed to it from the data selection file, and they are not defined, the symbol will appear with that member assuming its default value. Exercise care that the data selection and symbol appearance files that use these customized attributes are coupled properly.
Editing The Data Selection GPDL Files

The data that the symbol is to represent is retrieved from the database. The tables from which the data is retrieved, and the particular columns are all defined in the data selection GPDL files. This is the simplest of the two GPDL files required because it usually only defines basic strings that stipulate the table and columns needed by the generic symbols. These statements are required to be contained in all data selection GPDL files. If they are missing, the results will be incorrect (if any symbols are displayed at all).
cc_String cc_String cc_String cc_String TABLE = "<TABLE_NAME>"; TABLE_TOP_COL = "<COLUMN_NAME>"; TABLE_BASE_COL = "<COLUMN_NAME>"; TABLE_ORDER_COL = "<COLUMN_NAME>";
The first statement defines the table from which all the data are to be retrieved. (If data is to be retrieved from more than one table, you may define n sets of these statements defining variables like TABLE_1, TABLE_2,... TABLE_N.) The next set of statements are used as sub-variables for the SQL queries that will retrieve the interval data. They are not mandatory, as long as the SQL queries (which are found in the symbol appearance GPDL files) have all the references to these variables expanded out to their full definitions. Using these variables greatly simplifies the complexity of the symbol appearance files and increases their readability.
cc_String FROM_CLAUSE = "from $(PROJECT).$(TABLE)"; cc_String WHERE_CLAUSE = "where uwi = '$(UWI) and ( $(TABLE_TOP_COL) <= $(XS_BASE) )
314
Revised May 2, 2005
and ( $(TABLE_BASE_COL) >= $(XS_TOP) )"; cc_String ORDER_BY_CLAUSE = "order by $(TABLE_ORDER_COL)";
Finally, because the labels that may be annotated on the symbol are retrieved from the table, and because the labels may use any SQL function to format the label (as well as embedding hard-coded strings into the label), the label's SQL sub-string expression is in the data selection file.
cc_String ANNO_STRING = "RTRIM (TEST_NO)"; cc_Number NUM_LINES_OF_TEXT = 1;
The string assigned to the variable ANNO_STRING will be sent down to the symbol appearance file to be used (or not used) as the label for the symbol. As mentioned above, hard-coded strings may be embedded into the label. This is how you may break strings apart onto separate lines. For instance:
cc_String ' TEST: ' TYPE: ' DATE: ' TIME: cc_Number ANNO_STRING = " ' || RTRIM (TEST_NO) || CHR(10) || ' || TEST_TYPE || CHR(10) || ' || TEST_DATE || CHR(10) || ' || PERIOD || ' ' || PERIOD_UNIT"; NUM_LINES_OF_TEXT = 4;
These statements define a label that will be displayed on four separate lines.
TEST: TYPE: DATE: TIME: 01 ARC 1987-01-15 44 MIN
If the CHR(10) function had not been used, the statement and resulting label would be as follows.
cc_String ' TEST: ' ' TYPE: ' ' DATE: ' ' TIME: ' cc_Number ANNO_STRING = " || RTRIM (TEST_NO) || || TEST_TYPE || || TEST_DATE || || PERIOD || ' ' || PERIOD_UNIT"; NUM_LINES_OF_TEXT = 1;
Label--> TEST: 01 TYPE: ARC DATE:1987-01-15 TIME: 44 MIN
Revised May 2, 2005
315
This label would probably not fit into the track, and since there is no clipping of the text, or word-wrap feature in GPDL, the label would probably carry on across into adjacent cross section tracks. If you do not want the TEST_DATE in the ISO date format, you should use the TO_CHAR function to change the format. For example, in the above statements, TEST_DATE is replaced with TO_CHAR(TEST_DATE, DDMON-YYYY). See the Oracle8i SQL Reference for more information.
Defining New Symbol Appearance and Data Selection GPDL Files

A definition for each file is placed in the FM_HDR table of the projects account. Follow these steps to define new GPDL files to the system:. 1. Create the GPDL file. You can use an existing GPDL file as a template. 2. Determine where the file will be placed. Usually the GPDL files are placed in one of the directories listed in the ESI$GPD logical. Finder is shipped with this defined logical as shown in the following table 13 and table 14 on page 316.
Table 13: The Project Scope
Logical name
lSI$GPD ESI$GPD ESI$ESI_GPD ESI$ESI_GPD
Seq
1 2 1 2
Translation
ESI$PROJECT_GPD ESI$ESI_GPD ESI$PROJECT/customized/gpd ESI$PROJECT/gpd
Table 14: The ESI Scope
Logical name
ESI$GPD ESI$ESI_GPD ESI$ESI_GPD
Seq
Translation
ESI$ESI_GPD
1 2
ESI$ROOT/customized ESI$ROOT/gpd
316
Revised May 2, 2005
Because the new GPDL file is being defined to the system, it should have project scope. (An exception to this rule is when the new file should be inherited by all projects. In that event, treat the files as if they have project scope and are to be owned by the project DEFAULT_PROJECT. Then, after the database entries are placed into the table, schema_run_validate can be used to propagate all the entries to all the projects. The GPDL files should then be copied into the ESI scope, preferably into the ESI$ROOT/ customized/gpd directory.) 3. Copy the GPDL files to the directory decided upon in Step 2. 4. Decide up a name for the GPDL file. 5. Run the form to insert the entry into the FM_HDR table. 6. Begin a Finder session using the project to which you want the GPDL file exported. 7. Select Forms from the Applications menu item. 8. Select the Project Administration data type. 9. Select the Cross Section Symbol Appearance Definitions or Cross Section Data Selection Definitions form, and press the Apply button. The DATA SELECTION DEFINITIONS form is show in figure 12 on page 318 as an example to which you can refer during the descriptions that follow. Both forms are very similar and are used in the same fashion. 10. Insert the appropriate data entries into the form. a. FINDER FILENAME This is the name arrived at in step #4. This name will appear in the appropriate selector box in the LogPlot Track Symbol Definition dialog. b. ANALYST This is the owner of the GPDL file. Since the user can use the LogPlot Track Symbol Definition dialog to display the named file as well as the owner, this field should be used to track analyst customizations.
Revised May 2, 2005
317
c. CREATE_DATE This field defaults to the day the form was run. d. FILENAME This is the name the file was copied into one of the ESI$GPD in Step #3 (the full pathname is not required). The form will check that this file exists before allowing you to continue. e. REMARKS This is an optional field. After a valid FILENAME is entered, this field is populated with the string GPD File input by form from <full pathname>. You can see this better in the DETAILED INFORMATION FOR THE CURRENT ROW section of the form.
Figure 12: The Cross Section Data Selection Definitions form.
11. Commit your changes. 12. Run schema_run_validate if the GPDL file was inserted into the project DEFAULT_PROJECT.
318
Revised May 2, 2005
If these files are to be inherited by all projects, run schema_run_validate with the -d (load from DEFAULT_PROJECT tables) and -g (grant) options. This will copy the new entries in to the projects table.
GPDL Object Definitions

Object
An object is single statement in a GPDL file that defines an entity, assigns it a particular name and member attributes. The basic format of a statement that defines an object is (underlined text means it is required):
<ObjectType> <ObjectName> ( { [<MemberName> = ] <MemberValue> ,} * };
<ObjectType> is one of the valid Finder implemented object types like gpd_LabelledShape, gpd_LabelledBoxz or gpd_PolyCText. <ObjectName> is name that will be assigned to this object and by which this object will be referenced throughout the GPDL file. <MemberName> is the valid name of a part of the object. For instance, some valid members for the gpd_PolyCText object are: X Y Content XJust YJust Font
<MemberValue> are the values to be assigned to this member.
Example: A PolyCText object as defined in a GPDL file.
Revised May 2, 2005
319
gpd_PolyCText MyText ( X = 5, Y=11, Content = "Hello World", XJust = CenterJust ):
Drawable Object
An object that will result, when attached through the gpd_Draw member of a gpd_GraphicsProduct, in something appearing on the drawing surface. Some drawable objects include the following. gpd_LabelledShape gpd_LabelledBoxz gpd_PolyCText gpd_Polygon gpd_Polyline
The following objects are not drawable, but they can alter the appearance of a drawable object. gpd_Translation gpd_Scaling gpd_Rotation gpd_Transform gpd_Font gpd_Context cc_Number cc_String
320
Revised May 2, 2005
Customizing Applications Dialogs

Customizing the Map Overlay Lists
When selecting a new map overlay, in the Mapping application, the order of mapping overlays within each class are stored in the ORDER_WITHIN_CLASS column of the CODES.MAPPING_OVERLAYS table. In each class, the mapping overlay that has the ORDER_IN_CLASS value of 1 is displayed as the default overlay. An example listing of the contents of this table is shown below. Example:
SQL> select * from OVERLAY_CLASS_CODE -----------------10 3 4 10 10 5 10 8 8 8 8 8 8 11 11 11 10 1 6 7 2 5 5 9 24 rows selected. CODES.MAPPING_OVERLAYS; OVERLAY_NAME OVERLAY_CODE ------------ -----------CONTOURS 1 GRAPHIC OBJECTS 2 GRATICULE 3 GRID DISPLAY 4 GRID OPERATIONS 5 LAND GRID 6 PERSPECTIVE 17 SEISMIC 7 SEISMIC DEPTH 8 SEISMIC ISOCHRON 9 SEISMIC ISOPACH 10 SEISMIC MISTIE 11 SEISMIC DATA 12 WELL DEPTH 13 WELL ISOPACH 14 WELLS 15 XYZ FILE DISPLAY 16 CULTURE 19 LEASE 20 PLOTFILE 23 EXT. OPERATIONS 24 DLS 21 NTS 22 SEISMIC 3D 18 E N N N N N N N N N N N N N N N N N N N N N N N N REMARKS ORDER_WITHIN_CLASS -----------------------------------------------Contour creation and display 4 Graphic object display 1 Graticule 1 Grid file creation and display 2 Operations on grid files 3 Land grid from Lynx tables 1 Perspective creation and display 5 2D seismic 1 2D seismic with time to depth conversion 3 2D seismic with isochron calculation 4 2D seismic with isopach calculation 5 2D seismic with mistie posting 6 2D seismic with general data display 2 Wells with marker depths 2 Wells with isopach calculation 3 Wells 1 XYZ (or scatter) file display 1 Surface features stored in Lynx tables 1 Lease display 1 CGM plotfile display 1 External operations for gridding and contouring 1 Canadian Dominion Land Survey grid 2 Canadian National Topographic System grid 3 3D seismic 1
Revised May 2, 2005
321
Table 15: The default order of map overlays displayed by overlay class
Overlay class code

1 2 3 4 5 5 5 6 7 8 8 8 8 8 8 9 10 10 10 10 10 11 11 11
Overlay name
CULTURE EXT. OPERATIONS GRAPHIC OBJECTS GRATICULE LAND GRID DLS NTS LEASE PLOTFILE SEISMIC SEISMIC DATA SEISMIC DEPTH SEISMIC ISOCHRON SEISMIC ISOPACH SEISMIC MISTIE SEISMIC 3D XYZ FILE DISPLAY GRID DISPLAY GRID OPERATIONS CONTOURS PERSPECTIVE WELLS WELL DEPTH WELL ISOPACH
Overlay code
19 24 2 3 6 21 22 20 23 7 12 8 9 10 11 18 16 4 5 1 17 15 13 14
Order within class

1 1 1 1 1 2 3 1 1 1 2 3 4 5 6 1 1 2 3 4 5 1 2 3
322
Revised May 2, 2005
You can customize the appearance of overlay lists in the Mapping application dialogs by using SQL*Plus to modify the values in the CODES.MAPPING_OVERLAYS.
SQL> UPDATE CODES.MAPPING_OVERLAYS 2> SET ORDER_WITHIN_CLASS = 1 3> WHERE OVERLAY_CODE = 4;
This moves the GRID DISPLAY overlay from second to first place in its class and becomes the display default. Other overlays must be appropriately renumbered to adjust for this change. Table 15 on page 322 illustrates the default order of overlays supplied with Finder.
Setting the Default Plot Size Unit

The system ESI account maintains the default unit of measurement to be used on all output plots. This unit default will be used by the Finder dialogs used to set-up hard copy plots. The Map Setup dialog The Send to Plotter dialog The Plot Cross Section dialog
To set the unit of measurement default, you must use SQL*Plus to set the DEFAULT_VALUE of the PLOT_SIZE_UNIT in the ESI.SYSTEM_DEFAULTS table to either INCHES or CM as follows. 1. Start SQL*Plus as the ESI account.
<PROMPT>: sqlplus esi/esi
Revised May 2, 2005
323
2. To insert the default in the table for the first time following installation, use the following SQL commands. a. To set the default to inches.
SQL> INSERT INTO ESI.SYSTEM_DEFAULTS 2> VALUES (PLOT_SIZE_UNIT, PLOTTING, INCHES);
b. To set the default to centimeters.

SQL> INSERT INTO ESI.SYSTEM_DEFAULTS 2> VALUES (PLOT_SIZE_UNIT, PLOTTING, CM);
3. To change the default in the table at some later time, use the following SQL commands. a. To change the default from inches to centimeters.
SQL> UPDATE ESI.SYSTEM_DEFAULTS 2> SET DEFAULT_VALUE = CM 3>WHERE DEFAULT_NAME = PLOT_SIZE_UNIT;
b. To change the default from centimeters to inches.

SQL> UPDATE ESI.SYSTEM_DEFAULTS 2> SET DEFAULT_VALUE = INCHES 3>WHERE DEFAULT_NAME = PLOT_SIZE_UNIT;
The PLOT_SIZE_UNIT can only take a DEFAULT_VALUE of either INCHES or CM as shown above. If Finder encounters any other value or no value at all, then the units of measurement is assumed to be inches.
324
Revised May 2, 2005
Customizing Colors
User-defined Color Tables
Finder is shipped with a pre-defined color palette. You have the ability to modify the list of pre-defined colors that are used in the various on-screen displays and hard-copy plots that are produced. You can: Note: Define a new color with its own unique name and hue Modify the name and hue of an existing color Delete an existing color
RGB color values may look vastly different between terminals. Additionally, color values on terminal screens can also look vastly different upon color plotters.
Caution: Changing the names of existing colors should be done with caution, since some data identifies its color attributes within the database tables as the actual name of the color. (The LYNX and Color/Fill Definition entry tables do this.) Changing a color's namewithout changing the occurrences in these data tableswould result in these objects being displayed incorrectly.
How Colors are Defined

Colors are identified by Finder through the EXPRESSION_CODES table of the CODES account. This structure of the table is shown in Table 16 below.
Table 16: The EXPRESSION_CODES table
Column name
KEYWORD CODE NAME ENVIRONMENT
Null?
Not null Not null Not null
Type
CHAR(25) NUMBER CHAR(20) CHAR(10)
Each color is defined with two rows in this table. The first row assigns each color a color index. The second row identifies each color's hue.The KEYWORD column is what differentiates between these two types of rows.
Revised May 2, 2005
325
Each color-index row contains the word COLOR in the KEYWORD column. (This row existed in previous versions of Finder, and is required for a color to be available from Finder color selector boxes.) Rows identifying a color's hue contain RGB_COLOR in the KEYWORD column.
Example
KEYWORD CODE NAME ----------------- ------------ -------COLOR 3 GREEN COLOR 25 HOT PINK RGB_COLOR 255000 GREEN RGB_COLOR 255103178 HOT PINK ENVIRONMENT -----------
The NAME column in both cases contains the name of the color exactly as it would look in the Finder selector boxes. This column must be identical in the COLOR index row and the RGB_COLOR row to enable both rows to be joined together. By convention, all color names are in upper case, with adjacent words separated by spaces, not underscores. For example, a hot pink color would be assigned the name HOT PINK, not HOT_PINK or Hot Pink. The CODE column contains the color index or hue value of the color, depending upon whether the KEYWORD column identifies this row as a color index row or a hue (RGB_COLOR) row. In the case of a COLOR row, the maximum value of code should not exceed 255. In the case of a RGB_COLOR row, RGB combinations should not be duplicated.
The ENVIRONMENT column is null for all color index and hue rows. An additional entry from the codes.expression_codes table is LEASE DEFAULT COLOR(1).
326
Revised May 2, 2005
LEASE DEFAULT COLOR points to another entry in the table and is assigned the identical color index as the color it references, so it does not need a column identifying its hue. For example, both the colors WHITE and LEASE DEFAULT COLOR have an identical code value of eight (1), so every object assigned the color LEASE DEFAULT COLOR will appear WHITE on the final display. Finder uses the RGB (Red-Green-Blue) color model to define colors. This model identifies colors by the amount of the red, green and blue component colors required to create the color. Each hue is defined by a nine-digit number that is actually a concatenation of three component numbers. These three numbers indicate the value of each corresponding component color required to create the final color. Each red, green and blue component is assigned a value identifying the amount of each component color that is present in the final color. This amount can range from 0 to 255. For example, under the RGB color model, white contains the maximum amount of all three components. Since the maximum value of any component is 255, white would have a red value of 255, a green value of 255 and a blue value of 255. Conversely, black contains the minimum of all three components and would have a red value of 0, a green value of 0 and a blue value of 0.
Concatenated R-G-B hue
2 5 5 1 0 3 1 7 8 HOT PINK
Red Green Figure 13: Each hue is defined by a nine-digit concatenation of three component numbers. Blue
If these three component values are concatenated together, they yield a nine digit number. (Use leading zeros--if necessary--to ensure that each component is three digits in length and the final value is nine digits wide.) It is this final nine digit number that is used to define each color's RGB color representation or hue. Thus, white would have an RGB value of 255255255 and black an RGB value of 000000000. These nine digit numbers are stored in the EXPRESSION_CODES table in the CODE column of the color's hue row. See Examining the Color Table on page 328 for instructions on viewing the contents of the color table.
Revised May 2, 2005
327
Scripts That Alter the Color Table

Inside the Finder scripts directory ($FINDER_HOME/scripts on UNIX) are four scripts that you can use to maintain colors.
Table 17: Finder scripts used to maintain colors
Script
color_delete.sql color_insert.sql color_listing.sql
Description
Deletes both rows for a color from the CODES.EXPRESSION_CODES table. Inserts both rows for a color into the CODES.EXPRESSION_CODES table. Lists all the defined indices for a color and RGB values. Lists those colors with RGB values and no color indices. Lists those colors with color indices and no RGB values. Updates the RGB values in the CODES.EXPRESSION_CODES table.
color_update_rgb.sql
Note: Note:
Use these scripts to examine and edit the color table. They avoid conflicts and ensure consistency with colors currently defined. Do NOT edit the table manually! When applying color in a line, text, or symbol dialog, the user has control over the sorting order of the displayed palette colors. These colors can be sorted alphabetically by color name, or they can be sorted by color scheme. A detailed description of this feature in included in the Customizing Applications Dialogs section in the Database Administrators Reference volume.
Examining the Color Table

Use the color_listing script to verify the integrity of the color table stored in the CODES.EXPRESSION_CODES table. Following is an example of perfect output from this script--all colors are identified with both a color index row and an RGB value row. To run the script, enter these two command lines:
% cd $FH/scripts % sqlplus CODES/<codes password> @color_listing
328
Revised May 2, 2005
Missing RGB Value

If a color has a color index but no RGB value, the second section of the listing alerts you. In the following example, LIME GREEN is missing its RGB value row (shown in bold). Example
DOC> DOC>**************************************************************** DOC>********* COLORS WITH A COLOR INDEX, BUT NO RGB VALUE ********** DOC>********* ********** DOC>********* COLORS OTHER THAN "LEASE DEFAULT COLOR" ********** DOC>********* SHOULD BE CHECKED FOR VALIDITY ********** DOC>**************************************************************** DOC># COLOR NAME -------------------LEASE DEFAULT COLOR LIME GREEN STATUS ---------------THIS IS VALID FIX THIS ONE !!!
You can perform the fix with one of the following methods: 1. Delete this unpaired color index row. OR 2. Insert into the table the corresponding RGB value row for that color. Method one is preferable because you can perform it with the color_delete script. Then, to remove the offending color, you can run the color_insert script to re-insert the color's color index and the corresponding RGB value row.
Revised May 2, 2005
329
Missing Color Index

If a color has only an RGB value, the third section of the listing alerts you. In the following example, LIME GREEN is missing its color index row (shown in bold). Example
DOC> DOC>**************************************************************** DOC>********* COLORS WITH AN RGB VALUE, BUT NO COLOR INDEX ********* DOC>********* ********* DOC>********* THERE SHOULD BE "no rows selected" ********* DOC>**************************************************************** DOC># COLOR NAME CODE RED GRE BLU -------------------- ---------- --- --- --LIME GREEN 50100000 050 100 000
Similarly to the last problem, you can perform the fix with one of two methods: 1. Delete this unpaired RGB value row OR 2. Insert into the table the corresponding color index row for that color. Again, method one is preferable because you can perform it with the color_delete script. Then, to remove the offending color, you can run the color_insert script to re-insert the color's color index and the corresponding RGB value row.
Inserting a New Color

Use the color_insert script to create a new color and insert it into the color table. You will be prompted for the name of the color to be inserted and its corresponding RGB (Red-Green-Blue) value. Execute the script from the SQL*Plus command line by typing the following:
cd $FH/scripts sqlplus CODES/<codes password> @color_insert
330
Revised May 2, 2005
In the following example, the color CREAM was inserted into the color table with an RGB value of 250250250. Example
% cd $FH/scripts % sqlplus CODES/<codes password> @color_insert
SQL*Plus: Version 3.0.9.1.2 - Production on Mon Jul 27 11:20:14 1992 Copyright (c) Oracle Corporation 1979, 1989. All rights reserved.
Connected to: ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production DOC> DOC> DOC> DOC> DOC> DOC># Enter DOC> DOC> DOC> DOC> DOC> DOC> DOC> DOC># Enter old new ---------------------------------------------------------------Enter the name of color to insert. If the color's name contains more than one word, enclose the name in single quotes, like 'LIME GREEN' or 'DARK SLATE GREY'. The name will automatically be converted to upper case. value for name_of_color: cream ---------------------------------------------------------------Enter the Red-Green-Blue (RGB) value of the color to insert. It should be a 9 digit number: digits 1-3 contain the RED value (from 0 to 255, inclusive) digits 4-6 contain the GREEN value (from 0 to 255, inclusive) digits 7-9 contain the BLUE value (from 0 to 255, inclusive) i.e.: 090010000 is RED value of 090, GREEN of 010 and BLUE of 000. value for rgb_value_of_color: 250250250 2: ('RGB_COLOR', UPPER('&A_NAME_OF_COLOR'), &A_RGB_VALUE_OF_COLOR ) 2: ('RGB_COLOR', UPPER('cream'), 250250250 )
1 row created. old new 2: 2: 'COLOR', UPPER('&A_NAME_OF_COLOR'), 'COLOR', UPPER('cream'),
1 row created. Commit complete. Disconnected from ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production %
Note:
Always run this script interactively, without command line arguments. The color's name is automatically converted to upper case by the script before the color is inserted. If the name is more than one word, you must enclose it in single quotation marks (') or the color will be assigned the first word only.
Revised May 2, 2005
331
Only pre-defined colors are available from the Graphic Object Editor color palette for altering attributes of lines. Use leading zeros if necessary to make each of the three RGB component values three digits long and make the final value nine digits long. For example, if the RGB components of a specific color are R=6, G=145, and B=17, the RGB value MUST be entered as 006145017. The color Black, in which all three RGB components are zero, must be entered as 000000000.
Inserting a Color That Already Exists

If you attempt to insert a color name that already exists, then the insert commands for the color index and RGB value will fail with a duplicate key in index message. Neither insert will be performed. Example
old 2: ('RGB_COLOR', UPPER('&A_NAME_OF_COLOR'), &A_RGB_VALUE_OF_COLOR ) new 2: ('RGB_COLOR', UPPER('cream'), 200200200 ) insert into EXPRESSION_CODES (KEYWORD, NAME, CODE) values * ERROR at line 1: ORA-00001: duplicate key in index
old 2: 'COLOR', UPPER('&A_NAME_OF_COLOR'), new 2: 'COLOR', UPPER('cream'), insert into EXPRESSION_CODES (KEYWORD, NAME, CODE) SELECT * ERROR at line 1: ORA-00001: duplicate key in index
Deleting an Existing Color

Use the color_delete script to remove an existing color from the color table. You will be asked for the name of the color to be deleted. Execute the script from the SQL*Plus command line by typing the following:
% cd $FH/scripts % sqlplus CODES/<codes password> @color_delete
Example
% cd $FH/scripts % sqlplus CODES/<codes password> @color_delete
332
Revised May 2, 2005
Connected to: ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production DOC> ---------------------------------------------------------------DOC> If the color's name contains more than one word, enclose the name in DOC> single quotes, like 'LIME GREEN' or 'DARK SLATE GREY'. DOC> The name will automatically be converted to upper case. DOC># Enter value for name_of_color: cream old 2: and name = UPPER('&A_NAME_OF_COLOR') new 2: and name = UPPER('cream') 1 row deleted. old new 2: and name = UPPER('&A_NAME_OF_COLOR') 2: and name = UPPER('cream')
1 row deleted. Commit complete. Disconnected from ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production %
In the example above, both rows corresponding to the color CREAM were deleted. Note: Always run this script interactively, without command line arguments. If the name is more than one word, you must enclose it in single quotation marks (') or the color will be assigned the first word only. If the color you ask to remove is not in the table, or one of the protected colors BLACK, WHITE, or LEASE DEFAULT COLOR, the output will indicate that no rows were deleted for each delete command. Example
Enter value for name_of_color: 'KHAKI YELLOW' old 2: and name = UPPER('&A_NAME_OF_COLOR') new 2: and name = UPPER('KHAKI YELLOW') 0 rows deleted. old new 2: and name = UPPER('&A_NAME_OF_COLOR') 2: and name = UPPER('KHAKI YELLOW')
0 rows deleted. Commit complete.
Revised May 2, 2005
333
Updating an Existing Color's RGB Value or Name

Use the color_update_rgb script to assign a new RGB value to an existing color. The script requires the name of the color to update and the new RGB value to assign to the color. Execute the script from the SQL*Plus command line by typing the following:
cd $FH/scripts sqlplus CODES/<codes password> @color_update_rgb
Example In the example on the next page, the RGB value assigned to CREAM was reset to 220 red, 220 green and 220 blue.
% cd $FH/scripts % sqlplus CODES/<codes password> @color_update_rgb
Connected to: ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production DOC> DOC> DOC> DOC> DOC> DOC># Enter DOC> DOC> DOC> DOC> DOC> DOC> DOC> DOC># Enter old new old new ---------------------------------------------------------------Enter the name of color to update its RGB value. If the color's name contains more than one word, enclose the name in single quotes, like 'LIME GREEN' or 'DARK SLATE GREY'. The name will automatically be converted to upper case. value for name_of_color: cream ---------------------------------------------------------------Enter the Red-Green-Blue (RGB) value to assign the color. It should be a 9 digit number: digits 1-3 contain the RED value (from 0 to 255, inclusive) digits 4-6 contain the GREEN value (from 0 to 255, inclusive) digits 7-9 contain the BLUE value (from 0 to 255, inclusive) i.e.: 090010000 is RED value of 090, GREEN of 010 and BLUE of 000. value for rgb_value_of_color: 220220220 1: update expression_codes set code=&A_RGB_VALUE_OF_COLOR 1: update expression_codes set code=220220220 3: and name = UPPER( '&A_NAME_OF_COLOR' ) 3: and name = UPPER( 'cream' )
1 row updated.
Commit complete. Disconnected from ORACLE RDBMS V6.0.33.1.1, transaction processing option - Production PL/SQL V1.0.32.3.1 - Production
334
Revised May 2, 2005
Note:
Always run this script interactively, without command line arguments. The color's name is automatically converted to upper case by the script before the color is updated. If the name is more than one word, you must enclose it in single quotation marks (') or the color will be assigned the first word only. Use leading zeros--if necessary--to make each of the three RGB component values three digits long and make the final value nine digits long. For example, if the RGB components of a specific color are R=6, G=145, and B=17, the RGB value MUST be entered as 006145017. The color Black, in which all three RGB components are zero, must be entered as 000000000.
Color Index List Caveats

Don't get carried away customizing colors. You should be aware of potential problems that inserting and deleting colors can introduce into the color index list, such as numerical sequence gaps in the list.
Numerical Sequence Gaps

Deleting a color from the color table will produce a gap where no color is assigned to particular color index number. This is a problem only if you remove colors that are attributes used by existing data objects in map definitions. Therefore, be sure that the color you are about to delete is not being used.
Safe Modifications
The safest way to define a new color is to use the color_update_rgb script to modify the hue of an existing color.
Custom Ordering of the Color-selection Dialog

Throughout Finder, whenever a dialog provides the option to select a color (the color of lines, the fill color for a polygon, etc.), the Color Select dialog is presented. This dialog displays the colors available in the color palette currently being used. By default the displayed colors are sorted alphabetically by the color name. However, the user has the option to display the colors sorted by the color scheme (all orange hues together, all blue hues together, etc.). The string Color/Name appears in the title line
Revised May 2, 2005
335
of the dialog. Selecting Color will display the colors sorted by color scheme, and selecting Name will display the colors sorted alphabetically by the color name.
Find Option
The Color Select dialog also supports a Find option that lets the user search the list by typing in a value. By default, this feature will be turned off. It can be activated by the Database Administrator by setting XFinder*colorList.showFind to true in the XDefaults file.
Color Ordering
The order of the colors displayed in the color dialog is customizable. The default sorting order for displayed colors is defined by the UI_COLOR_ORDER entries in the ESI.SYSTEM_DEFAULTS table. The database administrator can change the sorting order of the colors using the system_defaults form. The position index stored in the defaults table supports floating-point numbers. Therefore, it is possible to change the order of one color (that is, put it at the top of the list) without having to change the order coefficient for all the other colors. Note: The sorting order for the patterns in the pattern-selection dialog is defined in the same way as the sorting order for colors except that the default name is UI_PATTERN_ORDER.
Registering Patterns with Finder

To register a pattern, you need to make two entries in the EXPRESSION_CODES table in the CODES scope. You must specify the name of the pattern and the .xpm file associated with the pattern name. This is done using statements like the ones shown below:
insert into codes.expression_codes (KEYWORD, NAME, CODE, REMARKS) values ('PATTERN', '<pattern_name>', <unique#>, ''); insert into codes.expression_codes (KEYWORD, NAME, CODE, REMARKS) ('PATTERN_FILE','<filename.xpm>', <# from prev insert>, '');
Where:
CODE
- a unique sequence number that maintains the association between the pattern name and the .xpm file that contains the pattern.
336
Revised May 2, 2005
filename.xmp
- the name of the file that actually contains the pattern.
The filename.xpm file is placed in a directory called patterns in FINDER_HOME. When the .xpm is installed in $FH/patterns, the new pattern will appear in the pattern-selection dialog. Refer to the Modifying Lines, Fill Attributes, Text, and Symbols section in The Mapping Overlay Summary chapter of Finder Mapping Overlays volume for a more information on fill attributes.
Pattern Styles
The pattern styles and attributes stored in the database are listed below: Style
SOLID HATCH
Attributes(s) color color, hatch index The hatch index identifies what hatch style (i.e., vertical lines, horizontal lines, slant lines, etc.)
PATTERN
pattern name, background color, foreground color, height
Revised May 2, 2005
337
Customizing Bubble Map Symbols

The bubble and pie symbols used in bubble mapping are defined in GPDL files. These files are ASCII files which you can edit with any text editor.
Adding New Symbol GPDL Files

GPDL files are delivered in the $FINDER_HOME/gpd directory. You should not modify these files directly. If you wish to customize a GPDL file, you should copy it to the $FINDER_HOME/customized/gpd directory and modify it there. If you wish to customize a GPDL file for use in only one project, you should copy it to the gpd directory in the project directory. (i.e. $FINDER_DATA/SPIDER/gpd). The logical name ESI$GPD controls the sequence in which FINDER will search for GPDL files. If you want to add a new or modified GPDL file, the name and location of the GPDL file must be made known to FINDER. You do this by making a new entry in the project FM_HDR table. The file_id must be unique in the table. Table 18 and on table 19 on page 339 list values that indicate the location of customized GPDL files. As described above, these values are placed in the FM_HDR table.
Table 18: Entries in the FM_HDR table for a new bubble GPDL file.
Column name
FILE_ID FINDER_PATHNAME FINDER_FILENAME FILE_TYPE OS_PATHNAME CREATOR_ANALYST CREATOR_APPLICATION CREATE_DATE EXPIRATION_DATE LAST_MOD_DATE FILE_SIZE
Value
30 ESI$GPD MY BUBBLE GPD BUBBLE ESI$GPD:my_bubble.gpd JOHN MAPPING 21-JUL-1994 01-JAN-1999 21-JUL-1994
338
Revised May 2, 2005
Table 18: Entries in the FM_HDR table for a new bubble GPDL file.
Column name
DELETE_FLAG REMARKS
Value
F
Table 19: Entries in the FM_HDR table for a new pie GPDL file.
Column name
FILE_ID FINDER_PATHNAME FINDER_FILENAME FILE_TYPE OS_PATHNAME CREATOR_ANALYST CREATOR_APPLICATION CREATE_DATE EXPIRATION_DATE LAST_MOD_DATE FILE_SIZE DELETE_FLAG REMARKS
Value
31 ESI$GPD MY PIE GPD PIE ESI$GPD:my_pie.gpd JOHN MAPPING 21-JUL-1994 01-JAN-1999 21-JUL-1994
Modifying Symbol GPDL Files

The following aspects of the appearance of a bubble map symbol that you can control by modifying the symbols GPDL file.
Default Attribute Values

The default value for each attribute that a given bubble or pie uses is listed at the top of the GPDL file. Example:
Revised May 2, 2005
339
cc_String cc_String cc_String cc_String cc_String cc_Number cc_Number cc_Number
USER_FILL_BACKGROUND USER_LINE_BACKGROUND USER_LINE_COLOR USER_PEN_TIP USER_LINE_TEXTURE USER_RADIUS USER_X_OFFSET USER_Y_OFFSET
= = = = = = = =
BROWN; BLACK; BLACK; Light; Solid; 1.000; 0.0; 0.0;
These defaults are used when the attribute has not been specified in the bubble or pie definition or when no data selections match a condition for a given attribute in a given well.
Location of Bubble or Pie

The location of the bubble or pie can be modified by changing the gpd_Translation definition. This will place the bubble or pie at the top hole location for the well.
gpd_Translation ToWell ( XOffset = WELL_TOP_LOC_X+(USER_X_OFFSET * INCHES_TO_WCS), YOffset = WELL_TOP_LOC_Y+(USER_Y_OFFSET * INCHES_TO_WCS), );
340
Revised May 2, 2005
This will place the bubble or pie at the bottom hole location for the well.
gpd_Translation ToWell ( XOffset = WELL_BOT_LOC_X+(USER_X_OFFSET * INCHES_TO_WCS), YOffset = WELL_BOT_LOC_Y+(USER_Y_OFFSET * INCHES_TO_WCS), );
Data Label Options

For pies, you can control how the data that determine the sizes of the sectors are to be annotated beside each sector. These data labels are in addition to the user labels which you may specify in the pie definition. The data labels are appended to the user labels. The SectorControl variable in the gpd_Pie definition controls these labels. In this example, the data labels will be percentages:
gpd_Pie MyPie ( StartingAngle SectorRadii SectorValues UserLabels SectorControl UserFont SectorExplode );
= = = = = = =
0, USER_RADIUS, USER_SECTOR_VALUES, USER_USER_LABELS, GP_PIE_PERCENT, MyFont, USER_SECTOR_EXPLODE,
The value of SectorControl can be set as shown in table 20 on page 342.
Revised May 2, 2005
341
Table 20: Values of SectorControl and their results
SectorControl value
GP_PIE_NO_DATA GP_PIE_RAW_DATA
Result
The label is not annotated. The actual values are annotated. The percentages of the total are annotated. The actual values and total are annotated.
Example
The data fetched is (10, 23, 47). The annotations are 10, 23 and 47. The data fetched is (10, 23, 47). The annotations are 12.5%, 28.75% and 58.75%. The data fetched is (10, 23, 47). The annotations are 10 of 80, 23 of 80 and 47 of 80 .
GP_PIE_PERCENT
GP_PIE_OF_TOTAL
Text Font
The text font for the data and user labels can be modified in the GPDL file by modifying the gpd_Font definition.
gpd_Font MyFont ( FontFamily = TRIPLEX ROMAN, FontSize = (USER_RADIUS / 4) * 72 * INCHES_TO_WCS, );
The FontFamily can be any of the fonts currently supported by Finder.
342
Revised May 2, 2005
Customizing CPS-3 Gridding

Finder uses CPS-3 for preforming gridding and contouring calculations. You may customize the Finder installation for the location of working files and the color palettes used for color fill contours.
Redirection of CPS-3 Working Files

CPS-3 creates temporary working files with following file extensions. These files are for internal use. .1cps .mcps .dcps .pcps .scps
The .dcps and .scps files are temporary. They are created only when required and quickly deleted by CPS-3. The files cpswork.1cps and cpswork.mcps persist even after Finder terminates, but are re-created for use with the next Finder session. If an Analyst needs to have multiple Finder sessions running concurrently, all CPS-3 working files can be re-directed to any directory for which an Analyst have read and write access using the ESI$CPS3DIR logical name. This should be the Analysts home directory or another convenient private directory. If multiple working files are created in the ESI$CPS3DIR directory, CPS-3 detects that the cpswork.1cps or cpswork.mcps file is already in use and generates an incremented sequential file name: cpswork2.1cps, cpswork2.mcps or cpswork3.mcps. This feature is designed to accommodate multiple sessions for a single user. Redirection of working files to the same directory should not be attempted for multiple users by having the ESI$CPS3DIR logical name pointing to the same place. Nor should multiple users attempt run Finder from the same directory or the same UNIX account. If multiple users run CPS-3 from the same directory, collisions occur because more than one Finder session is trying to share the same cpswork.rep file.
Revised May 2, 2005
343
If the system should go down while CPS-3 has files open, the working files may not be properly closed and re-created when Finder is re-started. When CPS-3 is initialized, it recognizes that working files are open and generates the next incremental file name. The existence of remnant open work files may cause problems with CPS-3 grid calculations or system color map allocation. From time to time, or following a system crash, check the ESI$CPS3DIR directory and carefully delete unneeded sequentially named files.
Color Fill Contour Palettes

When the Color Fill option is selected in the Contours Overlay Editor dialog, you may select from a list of preset color palettes. The standard list of color-fill palettes delivered with Finder are defined in the file CPS3FILE/ cpsexpl.cnf in a path specified by the environment variable CPS3FILE. An example is shown below. You can modify the standard palettes or add new ones by editing the cpsexpl.cnf file. The changes made to the file are effective for all users at the site but do not take effect until after Finder has been restarted.
Caution: Changing the cpsexpl.cnf file while Finder is running will cause problems and unpredictable results when creating maps.
Modifying the Color Fill Palette Configuration File

The cpsexpl.cnf file is a space-delimited ASCII file containing 5 columns. Columns can begin in any column and are separated by one or more blank spaces.
Palette Index Number

The first column contains the integer index of the color palette. Palette numbers 1 and 2 are reserved for internal use by the CPS-3 graphics software and should not be change. You can modify palette numbers 3, 4, 5 and so on or add any number of additional palettes.
Color Sequence Number

The second column contains the sequence number of the current color being defined. Each palette can contain as many colors as you need up to a maximum of 255 colors but, with larger palettes, the analyst may have problems allocating all the necessary colors to map overlay.
344
Revised May 2, 2005
The maximum number of colors that can be allocated in a single Finder session is 255. Finder itself requires between 50 and 60 colors, leaving less than 200 available to color fill palettes and other selections. If other applications are also running then the number of available colors may even be less.
RGB Saturation Values

Columns three, four and five are the Red, Green, Blue saturation values for the user-defined color. The saturation values must be in the range 0 to 1. Example: To define color sequence number 10 in palette index number 3 as medium red.
3 10 1.00 0.50 0.93
Note:
The maximum number of colors that a palette can actually display at one time is constrained by the number of colors already allocated in the XColorMap before and during the Finder session including the basic workstation colors, Finder colors and other applications.
Revised May 2, 2005
345
Adding New Fonts

Finder provides the user a consistent way throughout the SmartMap GIS overlays to modify the attributes of the graphic elements that appear on the overlays. One of these graphic elements is text. A set of TrueType fonts is provided as default fonts and they have been entered into the CODES table. If the users need additional fonts, you, the database administrator can add them using the procedure listed in this section. You must have permissions to write to the GKS directories and have Insert privilege to the codes.expression_codes table. The following font families along with variations such as bold and italics are provided with the system as defaults: Times Helvetica Helvetica Narrow Palatino New Century School Book Courier
Here is how to add fonts to the list of fonts the user can select for text on the SmartMap GIS overlays: 1. Copy the font TrueType or Type 1 into the $GKSHOME/ fonttastic/install directory. The $GKSHOME directory is typically the $FINDER_HOME/gks. 2. Add a row for the new font in the fonts.dir file in the fonttastic/install directory. The fonts.dir file has the following format:
<N> <font file name 1> <font name 1> <font file name 2> <font name 2> . . . <font file name N> <font name N>
346
Revised May 2, 2005
Where: <N> = The number of files in the $GKSHOME/ fonttastic/install directory. When you add a new row to the file, you must increment this number. file name = The name of the font file in this directory. font name = A character string that identifies the font. The font name describes the family and style of the font for each font in the directory. The entry should comply with the X Logical Font Description style and can contain spaces. 3. Add an entry in the codes.expression_codes table for the new font. The format for the entries is described in table 21 below.
Table 21: New font entry in codes.expression_codes table codes.expression_codes
Field
KEYWORD NAME
Value
FONT <name>
Description
Keyword identifier. A font name that Finder users will see on their list of fonts. It can be the same as the font name defined in the file. A number from -201 to -899, which uniquely identifies the font. Make sure that this number is not already used by other fonts. Environment identifier. A character string that identifies the font. It must be the same name as defined in the fonts.dir file in step 2 above.
CODE
<number>
ENVIRONMENT REMARKS
PRIOR <font name>
Revised May 2, 2005
347
348
Revised May 2, 2005
Chapter 8: Database Maintenance and Troubleshooting
Chapter 8
Introduction
This chapter documents some of the database maintenance utilities available for use with Finder. It also presents ideas, tips and database troubleshooting information for use with ORACLE databases used with Finder. Many of these recommendations come from practical experience using Finder.
Revised May 2, 2005
351
Database Clean-up Utilities

FM_CLEANUP
The file management cleanup utility, fm_cleanup, deletes expired plot, scatter, grid, contour, perspective, culture, DLS (Canadian Dominion Land Survey) and NTS (Canadian National Topographic Survey) files stored in the file management FM_HDR table in ORACLE. These N-Lists exist in files in the corresponding subdirectories of a given project directory. In addition, each of these N-Lists has a corresponding record written in the project FM_HDR table.
Expired Files
An expired file meets either of two criteria. The date in the EXPIRATION_DATE field in the FM_HDR table is 24 hours or more older than the current operating system date and time. The DELETE_FLAG field is set to T (true) regardless of contents of the EXPIRATION_DATE field in the FM_HDR table.
Table 1: N-List expiration date examples
FINDER_FILENAME
BANFF_MEGA
EXPIRATION_DATE
16-MAR-2999
Explanation
An N-List File created 16-Mar-1992. When an N-List is named by an analyst, Finder considers it to be a permanent file and assigns it a far in the future expiration date usually a date in the year 2999.
352
Revised May 2, 2005
Table 1: N-List expiration date examples
FINDER_FILENAME
ZZZ_CONTOUR 910517_083321
EXPIRATION_DATE
17-MAR-1992
Explanation
When an N-List is not named by an analyst, Finder names it. Finder considers this to be a temporary file and assigns a 24 hours later expiration date.
Permanent N-Lists are created every time an XYZ, grid or contour output file is named by an analyst from within a map definition. If the map definition is later deleted, the N-Lists remain, regardless of whether or not they are used in other map definitions. If the N-Lists from a deleted map are unwanted, then use SQL*Plus to update their expiration dates to sometime in the past or set their delete flags equal to T. When fm_cleanup is next run, these N-Lists will be deleted.
FM_CLEANUP Overview
fm_cleanup scans each project in the Finder database and determines which files have expired by examining the records kept in the FM_HDR table. If either of the above criteria are met, the file is considered expired and is deleted. It will also delete the corresponding records in the FM_HDR table. If a file identified as expired in the FM_HDR table does not exist, a warning message appears in the window from which you ran the program. You can invoke fm_cleanup interactively or on a maintenance schedule. You must have delete privileges on your Finder project files and database administrator (DBA) privileges in ORACLE to use the utility.
FM_CLEANUP Reference
1. Start fm_cleanup with the following command line.
<PROMPT>: fm_cleanup <name>/<password>
The command line argument may be either a Project account name and password or the ESI account and password. The difference is explained in table 2 on page 355.
Revised May 2, 2005
353
If you type fm_cleanup alone on a command line without arguments, the utility prompts you to provide an account name, password and database instance as follows.
FINDER Account: <Project_account_name|ESI> Password: <Account_password> Database[]: <database_instance>
354
Revised May 2, 2005
If you do not provide a valid account name and password then the utility supplies the following usage message and exits.
Usage: fm_cleanup esi/esi_passwd. To cleanup all PROJECTS. OR Usage: fm_cleanup project_name/project_passwd. To cleanup a PROJECT.
Table 2: Command line arguments for fm_cleanup
Name/password
Project_name/Project_password ESI/ESI_Password
Description
fm_cleanup deletes expired files in the named Project account. fm_cleanup deletes expired files in all Project accounts in the database. fm_cleanup displays a message explaining correct usage. fm_cleanup prompts for an account name and password.
Any argument other than a valid account/password combination No argument
2. The fm_cleanup utility processes the selected Project accounts and deletes expired files which meet the criteria in table 1. If an N-List header line exists in the FM_HDR table but the corresponding N-List is deleted or not found, then fm_cleanup sends an error message to the screen. Example:
13:41:07 -- .....Processing file "<filename>" 13:41:08 -.....Error: does not exist.
If a file exists for which there is no record in the FM_HDR table, fm_cleanup will not delete that N-List, despite the fact that the N-List is an orphan. This orphaned N-List must be deleted manually.
Revised May 2, 2005
355
Example FM_CLEANUP Run

login: johnm Password: Last login: Fri Feb 28 13:31:10 from 129.87.89.68 SunOS Release 4.1.1 (JOKER) #1: Mon May 6 16:36:21 PDT 1991 % fm_cleanup FINDER Account: johnm Password: peru Database[]: Usage: fm_cleanup esi/esi_passwd. To cleanup all PROJECTS. OR Usage: fm_cleanup project_name/project_passwd. To cleanup a PROJECT. % fm_cleanup esi/esi FM Cleanup. 09:51:12 -- Now processing project: BATEST 09:51:14 -- Now processing project: EUREKA 09:51:15 -- Now processing project: GEODETIC 09:51:16 -- Now processing project: GEODETIC1 09:51:17 -- Now processing project: GOM 09:51:18 -- .....Processing file "CASE8540_ZZZZ" 09:51:19 -- .....Processing file "ZZZ_GRID 920702_135439" 09:51:19 -- .....Processing file "ZZZ_CONTOUR 920702_135440" 09:51:19 -- Now processing project: NSEA 09:51:21 -- .....Processing file "ZZZ_CONTOUR 920202_125936" 09:51:21 -- .....Processing file "ZZZ_CONTOUR 920202_130108" 09:51:21 -- .....Processing file "ZZZ_CONTOUR 920202_130132" 09:51:22 -- .....Processing file "ZZZ_GRID 920202_221506" 09:51:22 -- .....Processing file "ZZZ_CONTOUR 920202_221507" 09:51:22 -- .....Processing file "ZZZ_CONTOUR 920202_221605" 09:51:22 -- .....Processing file "ZZZ_CONTOUR
356
Revised May 2, 2005
920202_221715" 09:51:22 -- .....Processing 920202_221805" 09:51:23 -- .....Processing 920202_221842" 09:51:23 -- .....Processing 920202_221904" 09:51:23 -- .....Processing 920202_223222" 09:51:23 -- .....Processing 920203_094549" 09:51:23 -- .....Processing 920203_094551" 09:51:23 -- .....Processing 920203_094614". . . 09:52:10 -- Done. %
file "ZZZ_CONTOUR file "ZZZ_CONTOUR file "ZZZ_CONTOUR file "ZZZ_CONTOUR file "ZZZ_GRID file "ZZZ_CONTOUR file "ZZZ_GRID
NL_CLEAN
nl_clean reclaims space in N-List files where N-List data have been deleted. The N-List deletion routines simply delete the reference in the NList header to the data to be deleted. The data remains in the file until it is either explicitly cleaned out by the code (which does not always happen) or by this utility. In particular, scatter, grid and contour data files that are named as output files in overlays in mapping will grow each time those overlays are displayed. This can lead to rapid and excessive use of disk space because these files can be quite large.
Caution: If misused, nl_clean can delete the entire file. This is particularly dangerous on the Sun-4 platform if the full pathname to the file is not included in each record in the file containing the list of files to be processed. It is very important that you follow the procedures below and back up your files before attempting to compress them with nl_clean.
NL_CLEAN Overview
nl_clean performs the following operations. It reads in the active N-Lists from the file to be compressed. It writes out a new version of the file which only contains the active N-Lists.
Revised May 2, 2005
357
Preparing to Run NL_CLEAN

Before running nl_clean, you must prepare a file containing the list of pathnames to files to be processed. The following steps should be followed to insure successful compaction of the N-List file. 1. List the directory containing the files to be cleaned to show the sizes of the files. This step is optional but recommended because it allows you to verify the correct pathname and compare before and after file sizes. Example:
<PROMPT>: ls -l $FINDER_DATA/EUREKA/xyz/*
The result would appear as follows.

total 32 -rw-rw-r--rw-rw-r--rw-rw-r--rw-rw-r--rw-rw-r--
1 1 1 1 1
install install install install install
5382 5190 7440 7056 4366
Nov Nov Nov Nov Nov
18 18 18 18 2
07:32 07:33 07:51 07:38 15:23
FM19427 FM19428 FM19429 FM19432 FM20143
2. Use the list directory command to create a file containing a list of pathnames to the files to be processed by nl_clean. Do not change directories to the directory of the files you want to process. Instead, remain in your home directory or some other directory in which you have write privileges. This will avoid cluttering the project directories with file list files and force you to specify full path names for the files to be cleaned. Use the following commands. Example:
<PROMPT>: ls $FINDER_DATA/EUREKA/xyz/* > clean_files.lis
3. Verify that the file contains a list of fully qualified pathnames. Use the following commands. Example:
<PROMPT>: more clean_files.lis
358
Revised May 2, 2005
An example output is shown below.

/finder631/finder_project_data/EUREKA/xyz/FM19427 /finder631/finder_project_data/EUREKA/xyz/FM19428 /finder631/finder_project_data/EUREKA/xyz/FM19429 /finder631/finder_project_data/EUREKA/xyz/FM19432 /finder631/finder_project_data/EUREKA/xyz/FM20143
Caution: On UNIX installations, the file names in the list must be fully qualified pathnames as shown in the example above or you risk the files being deleted instead of compressed.
NL_CLEAN Reference
1. Log onto to the system using an account name which has read and write privileges on the operating system files created by the Project account you wish to process. 2. Start nl_clean with the following command line.
<PROMPT>: nl_clean
nl_clean prompts you for the parameters as follows.

Enter filename of the list of N-Lists file. <name of file list file> Enter maximum percent of dummy space allowed: --default = .1
These parameters are explained in table 3.

Table 3: Command line arguments for the nl_clean utility
Argument
Filename of the list of N-lists file Maximum percent of dummy space allowed
Description
The path to the file containing the list of files to be processed. This is the maximum amount of free space to be left in the file. Generally you should simply accept the default of.1%.
Revised May 2, 2005
359
3. The nl_clean utility processes the selected Project accounts. Each time nl_clean processes a file, it displays a message with the following format.
Cleaning file < nlist_of_nlist > by percent = <percentage saved>
Example:
<PROMPT>:ls -l $FD/EUREKA/xyz total 32 -rw-rw-r-- 1 install 5382 Nov 18 07:32 FM19427 -rw-rw-r-- 1 install 5190 Nov 18 07:33 FM19428 -rw-rw-r-- 1 install 7440 Nov 18 07:51 FM19429 -rw-rw-r-- 1 install 7056 Nov 18 07:38 FM19432 -rw-rw-r-- 1 install 4366 Nov 2 15:23 FM20143 <PROMPT>: ls $FD/EUREKA/xyz/* > clean_files.lis <PROMPT>: more clean_files.lis /project_data/EUREKA/xyz/FM19427 /project_data/EUREKA/xyz/FM19428 /project_data/EUREKA/xyz/FM19429 /project_data/EUREKA/xyz/FM19432 /project_data/EUREKA/xyz/FM20143 <PROMPT>: nl_clean Enter filename of the list of N-lists file. clean_files.lis Enter maximum percent of dummy space allowed: --default = .1 Cleaning file < /project_data/EUREKA/xyz/FM19427 > by percent = 0.100000 Cleaning file < /project_data/EUREKA/xyz/FM19428 > by percent = 0.100000 Cleaning file < /project_data/EUREKA/xyz/FM19429 > by percent = 0.47016 Cleaning file < /project_data/EUREKA/xyz/FM19432 > by percent = 0.47109 Cleaning file < /project_data/EUREKA/xyz/FM20143 > by percent = 0.100000 <PROMPT>: ls -l $FD/EUREKA/xyz total 25 -rw-rw-r-- 1 install 5382 Nov 18 07:32 FM19427 -rw-rw-r-- 1 install 5190 Nov 18 07:33 FM19428 -rw-rw-r-- 1 allaway 3924 Nov 18 08:32 FM19429 -rw-rw-r-- 1 allaway 3732 Nov 18 08:32 FM19432 -rw-rw-r-- 1 install 4366 Nov 2 15:23 FM20143
360
Revised May 2, 2005
Notice the amount of saved space in the after file sizes.
DB_CLEANUP
When using Geoshare to move data between a Finder project to an external application, it may be necessary to remove any traces of the last such operation to ensure the success in the present transfer. Finder provides a utility, db_cleanup, to assist in cleaning up the temporary projects used in data transfers. If a project becomes backed-up as a result of a failed Geoshare transfer, you can use db_cleanup to free the locked project. The db_cleanup utility also searches all directories and deletes any operating system files associated with the temporary project, e.g. NList files for seismic data. However, when you run db_cleanup with the -l flag or the -a flag, if one or more leases are referenced by the WELL_HDR table, those referenced leases will not be deleted. You may list up to nine projects on the command line with the command line arguments explained below. As a safety measure, Finder also asks you for confirmation before proceeding to clean up each project you have listed. The command is used in the following form.
<PROMPT>: db_cleanup -a <project1/password1> <project2/ password2> etc.
If you type db_cleanup with no arguments, the program displays the following usage message.
<PROMPT>: db_cleanup Usage - db_cleanup [ -DataTypeFlags ] [-otherFlags] Account/Password Account/ Password ... [ [ -DataTypeFlags ] [-otherFlags] Account/Password ... ] ... data-type-flags : d = DOCUMENT w = WELLS s = SEISMIC l = LEASE c = CULTURE g = GRAPHIC_OBJECT including Faults u = SURFACE t = STRAT n = LAND_NET a = ALL
Revised May 2, 2005
361
other flags : noforce : (default) Do not clean the project if it is locked in GS_POOLMANAGER. force : Ignore GS_POOLMANAGER lock and force cleanup of the project. o Data type flags may be given individually or grouped into a single string. i.e. -w -s -c is equivalent to -wsc If no data type flags are given ALL data will be deleted for a project. When a new set of data type flags are encountered all previous flags are cleared and the new set stay in effect for all subsequent projects until a new set of flags are encountered.
o o
Examples: db_cleanup geoshare_scratch_1/geoshare_scratch_1 All data will be deleted from the project named geoshare_scratch_1. db_cleanup north/north -ws eureka/eureka -s -l -g south/south west/west All data will be delete from the project north. Well and Seismic data will be deleted from eureka. Seismic, Lease and Graphic Object data will be deleted from the projects named south and west. db_cleanup -w high/high low/low -s atlantic/atlantic -a -force willow/willow Well data will be deleted from the projects high and low. Seismic data will be deleted from the project atlantic. All data will be deleted from project willow. Due to the -force option, the GS_POOLMANAGER lock on this project will be ignored and a cleanup will be forced.
362
Revised May 2, 2005
Tuning ORACLE for Data Loading

This information is presented as part of the documentation for the WHCS Loader, but is generalized here for all general data loading. Ideally, the preparations for loading data begin at the time the project is created. If you know that you will be loading large quantities of data into a project, it pays to plan the project creation to accommodate the amount of data you anticipate loading. The following database and disk space configuration recommendations should be followed to the extent possible. 1. Create at least one separate data tablespace during the create project process. Performance is enhanced if the new tablespace is on a separate physical disk from the SYSTEM tablespace or other tablespace. The amount of database storage required by a typical WHCS data set can be approximated by using the following formulae.
Project space requirement (bytes) = 375 x Number of Lines in the file
or
Project space requirement (bytes) = 12,500 x Number of Wells
Add to this figure enough extra storage to accommodate any temporary storage needed for things like creating rollback segments (see step 2 below). 2. Additional Rollback segments are required for loading very large data sets (more than 5000 wells). These must be created in a tablespace other than the SYSTEM tablespace with the size parameters set as indicated in table 4.
Table 4: Rollback Segments for Large Data Sets
Number of Wells
Less than 5,000 5,000 to 50,000 Greater than 50,000
Extent Size
Finder Default 500K 1M
Revised May 2, 2005
363
3. Tailor the table creation parameters for the new project as follows for all tables whose names begin with WELL_ or LOADER_. a. For INITIAL_EXTENT use the Finder Default. b. For NEXT_EXTENT use table 5.
Table 5: Table Creation Parameters for Large Data Sets
Number of Wells
Less than 5,000 5,000 to 25,000 25,000 to 50,000 Greater than 50,000
NEXT_EXTENT
Finder Default 100K 250K 500K
c. For the following tables adjust the PCTFREE as shown in table 6. Note: The ld_whcs_alter_schema.sql script performs these operations automatically when the loader is run. You do not have to do this by hand. It is documented here for completeness.
Table 6: Percent Adjustment
Table name
LOADER_CORE_HDR WELL_FORM_TEST_HDR WELL_HDR
PCTFREE
10 10 50
The rule of thumb here is that tables that are likely to have additional data inserted as updates after the primary data load need to have a larger value of PCTFREE to leave space in the extents created for significant amounts of additional data. This prevents the fragmentation that might result if updating an existing record caused the storage capacity of the existing extent to be exceeded, causing a new extent to be allocated elsewhere in the database file. If this were to happen, then each updated record would be split between two widely separated parts of the disk and performance would suffer.
364
Revised May 2, 2005
4. After the final schema_run_validate phase of the Project creation has completed creating tables and indices, drop the indices listed below.
Table 7: Indices Dropped after schema_run_validate Phase LOADER_WELL_LOCS_UWI LOADER_WELL_TOPS_UWI NODES_NODE_X NODES_NODE_Y WELL_CMPT_ANAL_UWI WELL_CMPT_GAUGE_UWI WELL_COMPLETIONS_UWI WELL_CORE_OVERLAPS_UWI WELL_CORE_OVRLP_FORM WELL_CRD_VISCOSITY_UWI WELL_HDR_CRSTATUS WELL_HDR_NODE_ID WELL_HDR_OPERATOR WELL_HDR_SECOND_NODE_ID WELL_HDR_WELL_NAME WELL_LOG_CURVE_HDR_TRACE WELL_MISC_DATA_UWI WELL_PROD_FIELD_DATA_UWI WELL_SHOWS_UWI WELL_TEST_VO_PRESS_UWI WELL_TOPS_FORM_CODE
Note:
The ld_whcs_alter_schema.sql script performs these operations automatically when the loader is run. You do not have to do this by hand. It is documented here for completeness.
Revised May 2, 2005
365
Dropping indices is a way of improving loading performance because if they are not present, ORACLE does not have to update the indices at the time the data are loaded. It is much faster to drop and recreate the indices than it is to have to do the incremental updates with every record inserted. Care must be taken to not drop UNIQUE indices as these are what protect the integrity of the data in the database. If you drop UNIQUE indices, you might load duplicate rows and create a tremendous maintenance headache for yourself.
366
Revised May 2, 2005
Periodic Maintenance
Recovering Space Allocated by Oracle after Using DataMover
Even though DataMover cleans out the TEMP_PDB_VCHAR_LIST table as it moves data, Oracle does not release the space that was previously allocated for the table. On large data moves, this space can be substantial and can only be recovered by truncating this table. If you dont recover the space, future data moves will be adversely affected. To recover the space in projects that are being used as a source for the DataMover transfers, first run the following query to verify that no one is using the TEMP_PDB_VCHAR_LIST table:
select TEMP_PROCESS_ID from &PROJECT_NAME..TEMP_PDB_VCHAR_LIST intersect select AUDSID from v$session;
If no rows are returned, there are no active DataMover transfers running against the project and the database administrator should truncate the TEMP_PDB_VCHAR_LIST table.
Improving performance When Querying OFM Views

To process the queries related to OilField Manager (OFM), the statistics for the following tables should be analyzed whenever there is data modification in these tables or on a periodic basis: FACILITY OIL_FIELD_OPERATION PRODUCTION_HDR PRODUCTION_DATA TEST_RECOVERY_HDR
TEST_RECOVERY_DATA
Related topic: See Views on page 145 for information about creating materialized views.
Revised May 2, 2005
367
Analyzing Tables for General Production Views

Processing performance for queries on general production views can be improved by periodically analyzing the statistics of the base tables for the general production views. The Bubble and Pie views are two such views that can be analyzed. Those views and their base tables are listed below. Cumulative_production_view base tables: production_summary well_completion reservoir facility
Completion_production_view base tables: reservoir well_completion facility production_hdr production_data
Related topic: See Views on page 145 for information about creating materialized views.
368
Revised May 2, 2005
Recovering from Database File Deletion

When you create a new tablespace for a project using the defaults, a new ORACLE tablespace file with the same name as the project is created and placed into a subdirectory of the project level directory. This file should be touched only by an ORACLE database administrator. Do not edit, delete or move it. Example:
<PROMPT>: data3/f70/finder_project_data/WIM/db/WIM
/WIM is the project level directory /WIM/db is the project sub-directory /WIM/db/WIM is the tablespace file
If you delete a project tablespace file before you take the tablespace offline, you will damage your ORACLE instance. If you accidentally delete a project tablespace file, follow the instructions below to recover. These instructions will not recover the contents of the deleted file. These instructions are intended to allow you to continue to use the ORACLE instance. 1. Re-create the lost file using touch or edit. Specify the exact pathname of the deleted file. In some cases, recreating the file simply using touch does not work. If you continue to have problems, copy another database file from another tablespace or even the system tablespace file into the path instead. ORACLE will recognize it as a database file belonging to the current instance and will bring up the database.
Revised May 2, 2005
369
2. Execute the following commands. <PROMPT>: sqldba SQL> startup mount SQL> connect / as sysdba SQL> alter database <dbname> datafile <filename>
offline; SQL> alter database <dbname> open;
SQL> alter tablespace <tablespace_name> offline SQL> drop tablespace <tablespace_name>; SQL> exit In this example, <dbname> is the name of your active database, and <filename> is the full pathname of the file you recreated in step 1. At this point you should do a normal shutdown and startup to verify that recovery was complete, and that you can continue to use ORACLE.
370
Revised May 2, 2005
Chapter 9: System Set-up and Configuration
Chapter 9
Introduction
Finder installation is described in detail in the Finder Installation Guide. In this chapter, we explain procedures that are required after installation and before using the new Finder installation. Some of these procedures may also be required by the database administrator when adding new users, workstations or peripheral equipment to the Finder installation.
Revised May 2, 2005
373
Database Access License

Finder database access is licensed at the Oracle level using the Finder_DB_Access feature. The licenses are checked out based on the user/machine pair. One license is checked out for each combination of user and machine, with no limit to the number of applications connecting to the database. See the example scenarios below: One user, one machine, with one or more database connections = 1 license checked out. UserA/Machine1/one or more database connections Three different users on one machine with one or more database connections each = 3 licenses checked out. UserA/Machine1/one or more database connections UserB/Machine1/one or more database connections UserC/Machine1/one or more database connections One user, two machines, with one or more database connections on each machine = 2 licenses checked out. UserA/Machine1/one or more database connections UserA/Machine2/one or more database connections If all licenses are checked out and another license is requested, a message is displayed listing all the current user/machine combinations for which licenses are checked out.
Pre-conditions
The license feature that is checked out when a connection to the Finder database is established is Finder_DB_Access. There must be an entry in your FLEXlm license.dat file for Finder_DB_Access or you will not be able to access the Finder database. Implementation of Finder database licensing requires that the ESI password established during Finder installation is not changed outside of the Database Account Manager Utility. In the event that you must change the ESI password after Finder is installed, use the Database Account Manager Utility.
374
Revised May 2, 2005
If the ESI password is altered in SQL*Plus, run $FB/ esi_password_admin from the command line in a Finder Xterm to validate the ESI password. You will be prompted for the ESI password and $TWO_TASK. If you want to run in authenticated mode, reply to the prompt for the password with /. Example:
%$FB/esi_password_admin
The table, DB_USAGE_LOG_TABLE in ESI is utilized for logging information about Finder database connections. Make sure that there is ample tablespace allocated for this table. Periodically truncate this table to reclaim the space.
License Admin daemon

Database access licenses are validated and managed using the license administration daemon. In the event that you need to gracefully stop the License Admin daemon, run $FB/stop_la_daemon from the command line in a Finder Xterm. It will prompt you for the ESI password and $TWO_TASK before you run this utility. If you want to run in authenticated mode, reply to the prompt for the password with /. Example:
%$FB/stop_la_daemon
The daemon will be started automatically when the connection to the Finder database is re-established.
FlexLM Log File Example

The following examples show the contents of the FlexLM log file after logging in and out under different circumstances. Note that the license is checked out and checked in by Finder_DB_Access regardless of normal or abnormal logout by the user. Normal login and normal logout 12:17:26 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:17:27 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:17:28 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive
Revised May 2, 2005
375
12:17:28 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:17:29 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:17:29 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:17:30 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:17:32 (lmgrd.slb) OUT: Finder_Main_Exec dmgst3@sc-hive 12:17:50 (lmgrd.slb) IN: Finder_Main_Exec dmgst3@sc-hive 12:17:54 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive Normal login and abnormal logout (In the following example, abnormal logout means killing the -Finder process at the back end.) 12:18:12 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:18:13 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:18:13 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:18:14 (lmgrd.slb) OUT: Finder_DB_Access dmgst3@sc-hive 12:18:15 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:18:16 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:18:18 (lmgrd.slb) OUT: Finder_Main_Exec dmgst3@sc-hive 12:18:30 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive 12:18:53 (lmgrd.slb) IN: Finder_Main_Exec dmgst3@sc-hive 12:18:55 (lmgrd.slb) IN: Finder_DB_Access dmgst3@sc-hive
376
Revised May 2, 2005
Configuring User Start-up Files

Each user must have a UNIX operating system account and start-up files appropriately configured for Finder. If you are running Finder from Geonet then correct versions of these files are automatically installed and available to the user. You may also modify the resources used by X Windows in order customize Finder and FrameViewer for you location or for individual users.
X Windows Resources
When X Windows is first started, it creates an empty resource database. This database is filled, on a first come, first served basis, using values from the following locations. 1. The users /$home/.Xdefaults file. 2. When an application is started, X Windows searches for a resource file with the class name defined in the application, e.g. XFinder, following the search path defined by the environment variables. X Windows will only search the first available environment variables setting. if XUSERFILESEARCHPATH is set, $XAPPLRESDIR will not be searched.
Table 1: Search path to an application X resource file
Search order
First
Path
XUSERFILESEARCHPATH
Comment
These environment variables are not set or used by Finder. Do not set them as this will prevent X Windows from finding XFinder. You should put Xfinder here if it contains both site and user customizations. This is the preferred search path used by Finder (because it includes both resources and bitmaps). You should put Xfinder here if it contains only site customizations.
Second
XAPPLRESDIR
Third
$HOME
Fourth
XFILESEARCHPATH
Revised May 2, 2005
377
Important Note
X Windows fills its resource database on a first come, first served basis. When customizing Finder, you should remember the following. 1. When an X resource is set, it cannot be re-set. You should make sure that an X resource is the set correctly in the first location it is found by X Windows. 2. X Windows will follow the search path until it finds an appropriately named resource file and then stop searching. All of the X resources you want to set must be specified in the first copy of XFinder in the search path. The X resources used by Finder are shown in the following tables. You may customize any of these resources for the entire installation or for individual users.
Table 2: X resources for foreground and background colors
X resource
*foreground *background *highlightColor *XmPushButton.background *XmPushButtonGadget.background *XmMenuShell*background *XmText.background *XmTextField.background *XmToggleButton.selectColor *noneditText.foreground *noneditText.background *readOnly.background
Finder default
Black grey86 SteelBlue LightSteelBlue LightSteelBlue Gray78 Azure2 Azure2 red Black gray86 gray86
378
Revised May 2, 2005
Table 3: X resources for fonts for labels
X resource
*title.fontList *heading.fontList *subHeading.fontList *XmLabel.fontList *XmLabelGadget.fontList *OptionLabel.fontList:
Finder default
-adobe-helvetica-bold-r-normal--17-*-*-*-*-*-*-* -adobe-helvetica-bold-r-normal--14-*-*-*-*-*-*-* -adobe-helvetica-bold-r-normal--12-*-*-*-*-*-*-* -adobe-helvetica-medium-r-normal--12-*-*-*-*-*-*-* -adobe-helvetica-medium-r-normal--12-*-*-*-*-*-*-* -adobe-helvetica-medium-r-normal--12-*-*-*-*-*-*-*
Table 4: X resources for fonts for buttons
X resource
*XmPushButton.fontList *XmPushButtonGadget.fontList *XmCascadeButton.fontList *XmCascadeButtonGadget.fontList *OptionButton.fontList *optionsMenu.fontList *colorOptionButton.fontList *colorOptionButton.marginHeight
Finder default
-b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-12120-75-75-p-79-iso8859-1 -b&h-lucida-bold-r-normal-sans-10100-75-75-p-66-iso8859-1 1
Revised May 2, 2005
379
Table 5: X resources for fonts for toggles
X resource
*XmToggleButton.fontList *XmToggleButtonGadget.fontList
Finder default
-b&h-lucida-medium-r-normal-sans-12120-75-75-p-71-iso8859-1 -b&h-lucida-medium-r-normal-sans-12120-75-75-p-71-iso8859-1
Table 6: X resources for fonts for text boxes
X resource
XmText.fontList XmTextField.fontList readOnly.fontList
Finder default
-adobe-courier-medium-r-normal--12-120-7575-m-70-iso8859-1 -adobe-courier-medium-r-normal--12-120-7575-m-70-iso8859-1 -adobe-courier-medium-r-normal--12-120-7575-m-70-iso8859-1
Table 7: X resources for fonts for lists
X resource
*XmList.fontList
Finder default
-adobe-courier-medium-r-normal--12-120-75-75-m-70iso8859-1
380
Revised May 2, 2005
Table 8: X resources for layouts
X resource
*XmLabel.topOffset *XmLabelGadget.topOffset *optionsRowColumn.marginHeight *leftOffset *rightOffset *topOffset *bottomOffset *button.topOffset
Finder default
7 7 0 2 2 2 2 5
Table 9: X resources to control polling interval in Finder
X resource
*pollingInterval
Finder default
500 (The value is in milliseconds)
Table 10: X resources to automatically start mapping when Finder starts
X resource
*autoStartMapping
Finder default
False
Table 11: X resources to open a map definition when Finder starts
X resource
*mapDefName
Finder default
None (The name of a map is required but this resource and the *autoStartMapping resource cannot be used together)
Revised May 2, 2005
381
Table 12: X resource to automatically display a map when it is opened
X resource
*autoDisplayMap
Finder default
False
Table 13: X resources for the Map Open dialog
X resource
*mapOpenAnalyst
Finder default
None Options are: TOGGLE_ALL TOGGLE_CURRENT or Name of an analyst
*mapOpenProject
None TOGGLE_ALL TOGGLE_CURRENT or Name of a project
Note:
TOGGLE_ALL sets the all analysts or all projects toggle. TOGGLE_CURRENT sets the current analyst or current project toggle. Any other value sets the selected analysts or projects toggle and the selected list is set to the name specified. If these resources are not specified the current project and current analyst name are used. Auto-starting the Mapping Application may also be controlled by Finder command-line arguments or in a start-up script. If start-up arguments are used they will override the X resource values set in the XFinder file. See the Introduction chapter of the Finder Users Reference for more information on the Finder command line and arguments.
The .Xdefaults File

X Windows resources may be stored in the Xdefaults (or .Xdefaults.<node_name>) file using the following format.
<application_name>*<resourcename> : <value>
Example:
382
Revised May 2, 2005
XFinder*foreground : black
If resources for all X Windows applications are stored in this same file, then the entire file must be parsed for every application that is started causing a delay. A better method is to define X Windows resources in an applicationspecific resource file defined by the XFILESEARCHPATH environment variable using this format.
*<resourcename> : <value>
Example: In the file XFinder defined in XFILESEARCHPATH

*foreground : Black
Note:
X resources may only be set once in the X Windows resource database. If a resource has been set by one resource file, reading a second resource file containing a different value for the same resource will not reset the value!
The XFinder Files

A default XFinder is supplied with Finder and is stored in the $FINDER_HOME/app-defaults directory. This is a ASCII text file that you may view and modify with any text editor. We recommend that Finder X Windows resources be customized for your users and site as follows.
Site customization
1. Copy $FINDER_HOME/app-defaults/XFinder to XFinder.original and store it in a safe location in case you need to go back to an unmodified version. 2. Using a text editor, modify $FINDER_HOME/app-defaults/ XFinder file. a. Change all resources you wish to modify for the entire installation. b. Leave unchanged any resources for which you wish to accept the Finder defaults.
Revised May 2, 2005
383
User customization
1. Create a $HOME/app-defaults directory. Example:
<PROMPT>: mkdir /$HOME/app-defaults
2. Copy your site-customized $FINDER_HOME/app-defaults/XFinder file to $HOME/app-defaults/XFinder. Example:

<PROMPT>: cp $FINDER_HOME/app-defaults/XFinder /$HOME/app-defaults
3. Using a text editor, make additional changes to $HOME/app-defaults/XFinder as necessary and save it. a. Change any resources you wish to modify. b. Leave unchanged any resources for which you wish to accept the site customizations or Finder defaults. 4. Using a text editor, remove all Finder X resources that are set in your .Xdefaults file. 5. Using a text editor, set the XFILESEARCHPATH environment variable in your .cshrc file, as follows.
setenv XFILESEARCHPATH $HOME/%T/%N%S:$XFILESEARCHPATH
Make sure to place this statement at the end of the .cshrc file so that it will not be overridden by other sources.
Starting Finder
When the user starts Finder, X Windows will search and load the resources in the following order. 1. Command-line Arguments
384
Revised May 2, 2005
Options set on the Finder command-line take precedence over X resource values. 2. $HOME/.Xdefaults There should be no Finder X resources in this file. If there are they will be set and cannot be reset to the values in the XFinder files! 3. XFinder a. $HOME/app-defaults/XFinder If this file exists it should contain all of the X resources needed for both site user customization. If the file is found, X Windows will search no further. b. $FINDER_HOME/app-defaults/XFinder This file should contain all of the X resources used for site-wide customization or the Finder defaults. It will only be read if no $HOME/app-defaults/XFinder is found for the user. Note: The Loader Control Center, the dme and uiviewer utilities all use "include XFinder". If the XFinder file is modified, then copies of these utilities must be copied to the same location as XFinder if you want them to be affected by the modifications.
Revised May 2, 2005
385
Configuring User Workstations

When you start Finder, one of the required command line options is -w, which refers to workstation. For most uses of Finder, you use color for a color workstation. Note: The -w command-line argument is no longer mandatory. See the Introduction chapter of the Finder Users Reference for more information on the Finder command line.arguments. In a networked environment, the DISPLAY environment variable must be set so that your Finder session will display images on the same workstation which you wish to use. Each workstation configuration to be used for such a remote display must be defined in the table ESI.WORKSTATION_CONFIGURATION. To start the form to configure the workstations, log in as install, and enter the commands: <PROMPT>: cd $FH/forms/sun4 <PROMPT>: oform configure esi/<password> This will start up a multi-page ORACLE form, the first page of which will appear on the screen as Finder Workstation Configuration. Perform a query to display workstations that have already been configured, by depressing Enter Query, followed by Execute Query.
Figure 1: First page of the Finder Workstation Configuration form.
386
Revised May 2, 2005
An example of the contents of the form is shown in figure 1 on page 386. Enter the hardware configuration information for a workstation by making entries under the column headings, one workstation per row. Instructions for each column are on the following pages. The instructions below use examples from the GENERIC crt definition for ORACLE*Forms. 1. Enter the workstation name. In the column named Workstation Name, enter a short identifier. It is recommended that the name you assign to a workstation be somewhat descriptive, and that the workstation be clearly labeled with its name. Be sure to use uppercase letters. Note: The contents of the Workstation Name column must match the -w option that you use in the Finder command line. The same physical workstation can be assigned more than one Workstation Name in the database, depending on whether you intend to use it with or without a digitizing tablet. 2. Do not change the terminal type. You may leave this field blank or use the default value 180. 3. Do not change the host and node information. You may leave this field blank or use the default value NDNAME. 4. Enter the host and device information Enter GPX as the Host/Device. Be sure to use uppercase characters only. 5. Leave the MAC column blank. 6. Enter the number of graphic planes. This information is used to set graphic display defaults depending upon whether a workstation has a color monitor or a monochrome monitor. For a color workstation, enter the value 8. For a monochrome workstation, enter the value 1. 7. Do not change the graphic heads (HD) information You may leave this field blank or use the default value 1.
Revised May 2, 2005
387
8. Enter the digitizing tablet manufacture and model information. The list of digitizer tablet types that are currently recognized by Finder is stored in the NAME field of the CODES.GRAPHICS_TABLET_TYPES table. A digitizer type consists of a text string that includes a reference to both a manufacturer and a model, such as CALCOMP9100. In the column named Tablet Type, browse through the list of tablet types. Enter the current value in the form when you've found the desired tablet type. If no tablet is installed, enter NONE (upper case is required). If there is no entry for the tablet you wish to install, contact GeoQuest customer support. To see the digitizer tablet types currently supported by Finder, use the SQL query shown below: > sqlplus codes/codes SQL> SELECT * FROM GRAPHICS_TABLET_TYPES;
NAME CODE REMARKS -------------------- ---------- ---------------------GTCO 11X11 1 GTCO 11X17 2 GTCO 20X20 3 GTCO 36X48 UGRID 4 GTCO 42X60 UGRID 5 NONE 0 CALCOMP9100 32 CALCOMP9100UGRID 11
9. Enter the device option information. The Device Option column should contain 0 (zero), unless a large digitizing tablet is installed, in which case it might be necessary to enter 1 into this column for troubleshooting purposes. The Device Option parameter controls the X and Y offset values used with the digitizer.
388
Revised May 2, 2005
10. If necessary, use the following procedure to determine the default scale factor for GKS polymarker size. a. Create a map with a well overlay containing only one well. b. Make: Symbol Size = 1 inch c. Create a new well overlay with: Symbol Type = + Symbol Size= 1 inch Symbol Color= Red d. Display the map. If the symbol sizes match then the default scale is correct. e. If the symbol sizes do not match, quit Finder and select a new default scale factor. f. Re-start Finder and repeat (a) through (d). Continue until the symbol sizes are made to match. 11. Commit your changes. 12. Move on to the next page or exit the form. Proceed to the next block of the form to configure the workstation for a digitizer tablet, if one is to be connected to the workstation. Select Next on the Block menu.
Revised May 2, 2005
389
Configuring Preferences
As described in the Getting Started chapter of the Users Reference, analysts can use the Preferences dialog box to display graphics on a second monitor. The Alternate display area of this dialog box lists the displays that are available to the analysts machine. You can add alternate displays from which to choose within the scope of: Analyst Use the Analyst Defaults form or insert into the ANALYST_DEFAULTS table. Project Use the Project Defaults form or insert into the PROJECT_DEFAULTS table. System Use the System Defaults form or insert into the ESI.SYSTEM_DEFAULTS table

Use the Analyst Defaults form to specify the view preferences in the ANALYST scope. Use the Project Defaults form to specify the view preferences in the PROJECT scope.Notice that the values must be all uppercase.
Preference
Alternate Display List Alternate Display Default for Map
Application Name
FINDER
Default Name/ Variable Name

FINDER_ALT_DSP
Default Value
hostname:displaynumber. screennumber, ... hostname:displaynumber. screennumber or <mode>
Example
TOAD:0.0,ZIPPY:1.0
SMARTMAP or SMART_SECTION
DISPLAY
TOAD:0.0 or SPLIT or UNIFIED HORIZONTAL HORIZONTAL
Map Orientation Track Orientation Width of Display Area in pixels
SMARTMAP SMART_SECTION
MAP_ORIENTATION XS_ORIENTATION
HORIZONTAL or VERTICAL HORIZONTAL or VERTICAL
FINDER
MAX_GRAPHICS_WIDTH
390
Revised May 2, 2005
Preference
Height of Display Area in pixels Show map message area Show cross section message area Normal Color Background Color Highlight Color Graphic Object Editor Highlight Color
Application Name
FINDER
Default Name/ Variable Name

MAX_GRAPHICS_HEIGHT
Default Value
n
YES/NO
Example
SMARTMAP
SHOW_MESSAGE_AREA
YES
SMART_SECTION
SHOW_MESSAGE_AREA
YES/NO
YES
FINDER FINDER
NORMAL_COLOR BACKGROUND_COLOR
"color"1 "color"1 "color"1 "color"1
"BLACK" "WHITE"
FINDER FINDER
HIGHLIGHT_COLOR GO_EDITOR_HIGHLIGHT_COLOR
"RED" "PURPLE"
1. For more information about color definitions, see Preparing to Display and Plot in the Displaying and Plotting Maps chapter of this volume.
Inserting into tables

The command to use to set the view preferences by inserting the values directly into the tables is in the format:
insert into scope.scope_defaults default_name default_value
Analyst Scope Example: This is the command you would use to add displays from hosts toad and zippy to the list in the Alternate Display panel of the Preferences dialog box in the ANALYST scope:
insert into analyst.analyst_defaults FINDER_ALT_DSP toad:0.0,zippy:1.0
Project Scope Example: This is the command you would use to add displays from hosts toad and zippy to the list in the Alternate Display panel of the Preferences dialog box in the project scope:
insert into project.project_defaults FINDER_ALT_DSP
Revised May 2, 2005
391
toad:0.0,zippy:1.0
System Scope Example: This is the command you would use to add displays from hosts toad and zippy to the list in the Alternate Display Setup dialog box in the SYSTEM scope:
insert into esi.system_defaults FINDER_ALT_DSP toad:0.0,zippy:1.0
392
Revised May 2, 2005
Configuring Peripheral Devices

Finder workstations are often used in association with digitizing tablets and plotters. The configuration of the workstations with the digitizing tablets and plotters is managed by entering records into one or more of the following Finder database tables in the ESI account. WORKSTATION_CONFIGURATION TABLET_CONFIGURATION FINDER_PLOTTERS
An ORACLE form called CONFIGURE is provided with Finder to facilitate entering and modifying the data that describes the location and type of the various devices. Validation of certain data fields in these tables is controlled by entries in the following Finder tables in the CODES account. GRAPHICS_TABLET_TYPES GRAPHICS_TERMINAL_TYPES
Caution: Do not modify these validation tables. If you need to make changes please refer to qualified GeoQuest customer support personnel. In addition to configuring the Finder database, various operations must be performed on the host computer system by the system administrator in order to have all of the necessary devices working together. The sections that follow explain the steps required to finish the installation and prepare for the users.
Configuring Digitizing Tablets

The second page of the CONFIGURE form permits you to enter the information required to use a digitizer tablet with a specific workstation. A record containing the workstation name and tablet type that you intend to configure must have already been entered and committed using the Workstation Configuration Form displayed as the first page of the Configure Form, described in the preceding section of this section. Caution: Finder only accepts digitizer input in the point mode. Do not configure the digitizer tablet in stream mode.
Revised May 2, 2005
393
Perform a query to display workstations that have already been configured, by selecting Enter on the Query menu, followed by Execute on the Query menu. Finder displays the data (figure 2).
Figure 2: Digitizing Tablet Configuration form
To add a new tablet configuration record, select Insert on the Record menu to start a new line. Type the values into each field, using the tab or return keys to move on to the next field. When all the fields have been entered, save the information by selecting Commit on the Action menu. Detailed instructions for each field follow. 1. Enter the workstation name. With the cursor in the column named Workstation Name, enter the LIST VALUES key sequence and press the W key to browse through the list of workstations. Press the EXIT/CANCEL key to select the workstation name that corresponds to the workstation to which the tablet will be connected. 2. Verify that the tablet type code is displayed. When you specify the workstation name, a numeric Tablet Type code will be displayed, based upon the Tablet Type information you entered in the previous Workstation Configuration form.
394
Revised May 2, 2005
3. Determine the CPU port name for the digitizer and confirm that the workstation and tablet are communicating. On Sun workstations, your choices are either /dev/ttya or /dev/ ttyb, corresponding to port A or port B, and you use one of the following commands.
<PROMPT>: cat /dev/ttya <PROMPT>: cat /dev/ttyb
On IBM workstations, you may choose either /dev/tty0 or / dev/tty1. Example:

<PROMPT>: lsdev -c | grep tty tty0 Available 00-00-51-00 Asynchronous Terminal
If the tablet is configured and connected correctly, pressing a tablet button causes output to be displayed in an X terminal window. 4. Verify the tablet mode value. The Tablet Mode parameter is preset to 0 (zero) for Sun workstations. Do not change this value without consulting GeoQuest customer support. 5. Commit your changes. 6. Move on to the next page or exit the form. Proceed to the next block of the form to configure the workstation for a plotter, if one is to be connected to the workstation. Press NEXT BLOCK.
Finder and Calcomp Digitizers

This is the procedure for configuring the Calcomp 9100 and 9500 digitizer to work with Finder.
Revised May 2, 2005
395
On the Calcomp 9100 operating parameters are set on dip switches to the default Output Format 3 (see tables 1, 2 and 3 below). On the 9500, parameters are set by software to the format number that emulates the Calcomp 9100 format 3. The operating parameters are shown below. C cursor status P pen status X6 - MSD X5, X4, X3, X2 - X coordinate X1 - LSD Y6 - MSD Y5, Y4, Y3, Y2 - Y coordinate Y1 - LSD <CR> carriage return Point mode Resolution 1000LPI Baud rate 9600 8 Data bits 2 Stop bits Parity disabled Line feed on Echo on Cursor functions on Small menu on
The three banks of dip switches are located on two circuit boards inside the upper left corner of the tablet. The power switch and the power and communication cable are attached to these same boards.
1. Set the dip switches to the factory default settings shown in table 15, table 16 and table 16 on pages 21 and 22.
396
Revised May 2, 2005
Table 15: Default settings for dip switch bank SW-1 on the Calcomp 9100 digitizer
Switch position
1 2 3 4 5 6 7 8
Switch setting
Closed Closed Closed Open Open Closed Closed Open
Meaning
Parity disabled Parity disabled Parity disabled 2 Stop bits 8 Data bits 9600 Baud rate 9600 Baud rate 9600 Baud rate
Table 16: Default settings for dip switch bank SW-2 on the Calcomp 9100 digitizer
Switch position
1 2 3 4 5 6 7 8
Switch setting
Open Open Open Open Open Open Open Open
Meaning
Port B/D on
Line feed: Port A/C on Port A/C on Small menu on Cursor on Echo: Port B/D on Line feed: Port B/D on
Revised May 2, 2005
397
Table 17: Default settings for dip switch bank SB-2 on the Calcomp 9100 digitizer
Switch position
1 2 3 4 5 6 7 8
Switch setting
Closed Open Open Closed Closed Closed Open Closed
Meaning
Operating mode: Point Operating mode: Point Format 3 Format 3 Resolution: 1000 lines/inch Resolution: 1000 lines/inch Tablet size Tablet size
2. Connect the cable to port B on the tablet and to the ttya or ttyb port on a Sun workstation (or tty0 or tty1 on an IBM workstation). Note: A null modem adapter may be required. 3. Confirm that the workstation and tablet are communicating using one of the following commands.
<PROMPT>: cat /dev/ttya <PROMPT>: cat /dev/ttyb
If the digitizer is configured and connected correctly, pressing a tablet button will cause output to an X terminal window.
398
Revised May 2, 2005
Example: Format 3
FORMAT: ColumnFormat 1Button Number 2Pen Up or Down U or D 3-7X coordinate 8-12Y coordinate 13Carriage Return 1D3234453446 1D6789357890
4. Use the Finder oform utility to configure the workstation to use the Calcomp digitizer. The Calcomp is already defined as a workstation type in the Finder Workstation Configuration form. The only action needed is to verify that the Port Name is set to the port to which the digitizer is, in fact, connected. This is done in the Tablet Configuration block that is the second block in the Configure form. 5. After configuring the digitizer, start Finder with the following command line.
<PROMPT>: finder analyst/password project -w calcomp
The tablet will beep just before the Finder menu bar appears on the workstation. This confirms that Finder has recognized the digitizer and is communicating with it.
Configuring Plotting Devices

The third page of the CONFIGURE form permits you to enter the information required to use a plotter as an output device with Finder. In order to be able to enter the required information in Option 4 below, you must know the name of the plotter driver script that you intend to use. Scripts for Metafile Display Only If you wish to create and save a plot metafile, the plotter driver script can be extremely simple, in fact it can even be empty! But it must exist, be accessible to and executable by any Finder user who wishes to create and save a plot metafile.
Revised May 2, 2005
399
The map scale information saved to the file is non-metric by default. The map scale information can be saved as metric by setting METRIC_PLOT_MODE to YES in the Finder default system. For example: Application Name = FINDER Default Name = METRIC_PLOT_MODE Default Value = NO (for non-metric) or YES (for metric) Scripts for Producing Hard Copy Plots The contents of the plotter driver script that you use to produce a hard copy paper plot depends upon the plotter device, upon the plotter driver software for that device, and upon the sitespecific method your system administrator chooses to use to move the plot file to the plotter device. Please refer to the documentation received with the plotter driver software you wish to use for suggestions on how to build an appropriate script for the plotter of your choice. As was true of the simpler metafile display script described above, the plotter driver script must exist, be accessible to and executable by any Finder user who wishes to create and save a plot metafile. The Finder Plotter Definitions form appears on the third page of the
Workstation Configuration form (figure 3 on page 401).
1. To display plotters that have already been configured, select Query >> Enter, followed by Query >> Execute.
400
Revised May 2, 2005
Figure 3: Plotter Definition form.
Follow the instructions below for making correct entries to configure the plotters for your site. 2. To add a new plotter configuration record, select Record >> Insert to start a new line. Type the values into each field. 3. Enter the plotter name. In the Plotter Name field, enter the plotter name by which the plotter will be known to the user. The plotter names you enter will appear in the plotter selection dialog box for you to choose from when you send a plot to a plotter. 4. Enter the plot metafile format. For more information, refer to Scripts for Metafile Display Only on page 399. In the Meta Type field, enter the format of the intermediate plot metafile to be generated. One of the following metafile format options should be entered into this column. CGMB = CGM binary file CGMC = CGM character file CGMT = CGM clear text file
Revised May 2, 2005
401
Note:
Experience has shown that the CGM binary format provides the best quality plots. 5. Do not enter the name of the plotter queue. This information is not used on Sun workstations. You may leave this field blank or use the default value PLOT_QUE. 6. Enter the name of the plotter driver script. In the Driver field, enter the file name of the plotter driver script that will be executed when you send a plot to the plotter named in the Plotter Name column. The script file name that you enter must exist and be in the path of the Finder analysts who will be using the plotter or it can reside in $FH/ customized/bin (checked first) or $FH/bin (checked second). In addition, the users who will use the script must have execute privileges on the script.
Note:
Be sure that the case of the actual file name matches the case of the name in the Driver field. 7. Enter the plotter device status. The Status field displays ONLINE if the plotter is connected and operational. The field is empty if the plotter is OFFLINE. In the Status field, enter either ONLINE to indicate that the plotter is connected and operational or OFFLINE if it is not operational. The plotter names of plotters which are not operational will not appear as selectable in the dialog boxes that are used to initiate plotting. 8. Enter the maximum width of the plot. In the YSize field, enter the maximum height of the available plotting area, measured parallel to the long axis of the plotter paper, in inches, for the plotter device. Please note that some plotters or plot driver software may transpose the X and Y axes. If you are using a plotter device that panels, you should make the Y size parameter large enough to allow the use of the paneling option. 9. Enter the maximum length of the plot. In the XSize field, enter the maximum width of the available plotting area, measured perpendicular to the long axis of the plotter paper, in inches, for the plotter device. Please note that some plotters and/or plot driver software may transpose the X
402
Revised May 2, 2005
and Y axes. If you are using a plotter device that panels, you should make the X size parameter large enough to allow the use of the paneling option. 10. Enter the number of pens supported by the plotter device. In the No. Pens column, enter the number of pens supported by the device. (Defaults to 8). 11. Enter the integer precision value expected by the plotter. A value of 16 or 32 may be chosen; the default is 16. Note: The value selected here is only applicable to the plotting of CGM files. It has no effect on Postscript files 12. If needed, enter default scale factor for GKS polymarker size. a. Create a map with a well overlay containing only one well. b. Make: Symbol Size = 1 inch. c. Create a new well overlay with: Symbol Type = + Symbol Size= 1 inch Symbol Color= Red d. Display the map. If the symbol sizes match then the default scale is correct. e. If the symbol sizes do not match, quit Finder and select a new default scale factor. f. Re-start Finder and repeat steps (a) through (d). Continue until the symbol sizes are made to match. 13. Commit your changes and exit the form. When all the fields have been entered, save the information by selecting Action >> Commit and Action >> Exit. 14. Set up a spool queue to move the plot file to the plotter device.
Revised May 2, 2005
403
N-List Data Stored as BLOBs

Introduction
This section defines specifications and describes the procedures for managing the Finder environment to allow N-List data to be stored as Binary Large Objects (BLOBs) inside of an Oracle database table as a LONG RAW data type. Previously, N-List binary files were stored anywhere on the system as long as they can be accessed by a logical name that was stored in the LOGICAL_NAME table. The advantage of storing N-List files as BLOBs in Oracle tables is that backup and restore operations are cleaner if all the files and tables are in Oracle. The disadvantage is that processing is slower and it uses a different storage allocation mechanism.
N-List Storage Models

The decision of whether to continue using file-based or table-based NLists can be made on a per data type basis at project creation time. An advanced database administrator can even change the storage mode after project creation. Functionally there is no difference between an N-List stored in the database or in an operating system file. There is a difference in the performance and accessibility. For this reason, the project owner should assess their business needs and determine which mode is best suited to address those needs. The following table cites information that can assist you in making this decision.
Table 18: Comparison of N-List storage models
Compare:
Storage Size Access (Read) Speed Storage (Write) Speed Backup
when using table-based storage

x1.1 x5 tuned (x30-40 untuned) x5 tuned (x40-60 untuned) Can use any of Oracles utilities, including export/import; attribute and bulk data managed together. Must enlarge buffer size to about 1 megabyte on import.
when using file-based storage

x1 x1 x1 Must use operating system file backup in addition to database export/import; possible to get attribute data out of synchronization with N-List files.
404
Revised May 2, 2005
Table 18: Comparison of N-List storage models
Compare:
Space management Multi-volume support
when using table-based storage

Manual; managed through Oracles tablespace allocation mechanism. Uses Oracles tablespace management in addition to Finders logical name mechanism. Uses SQL*Net; same mechanism as all other database access. Handled by Oracle; may need to use import/export to compress. No; systems must be binary compatible (same representation of integers, floating point). No Yes, through foreign keys, including delete cascade where possible. Yes; DB_BLOCK_SIZE must be increased at database initialization (not startup) time. Yes; using normal commit, rollback. Via Oracle grants.
when using file-based storage

Dynamic; handled by the operating system. Uses Finders logical name mechanism and operating system features (such as nfs). Must be able to access remote volumes through nfs; requires cooperation of system administrator. Must be done manually using a utility like nl_clean_file. Managed on a per-file basis; files can be translated. No Manual; possible to have file store, database headers unsynchronized. No
Network accessibility
Garbage collection (space reclamation) Operating system independence of data format Use relational queries on N-List data directly Maintain integrity with header data in database Database tuning required Transaction Control Security
No Via operating system privileges.
The case for choosing the database to store N-List data is strongest in its ability to keep the integrity between the bulk data and associated data. The case for file-based N-Lists is strongest in its speed of access and freedom of database clutter from temporary files.
Mapping N-Lists to BLOBs

N-Lists have been stored in operating system directories as binary files. Each file can contain one or more N-Lists. Each system in Finder that utilizes the N-List library knows how it has organized and identified the data. Usually this involves creating an N-List file and then recording the filename and n-List identifier in a database table. Each system evolved differently (for example the seismic, well log curve, and contouring toolkits) and the choice of data organization is slightly different in each toolkit. The data mover and database cleanup utilities do not have this
specialized knowledge built-in. They rely on a database table called FINDER_NLIST_MAPPING to navigate between attribute information stored in the relational database and the bulk data stored externally in files. The existing FINDER_NLIST_MAPPING table (see table 19) describes each N-List data type persistently modeled in Finder. Each data type corresponds to a row in this table. Using this information, you can determine how to navigate from an N-List file name and N-List ID stored in a database table to the actual bulk storage. Each data type uses a logical name as its directory entry. The various parts of Finder evolved differently. Programmers defined the persistent storage models differently for each data type. The FINDER_NLIST_MAPPING table is flexible enough to accommodate these differences. Even though you will not normally need to use this mapping mechanism, it is useful to know it exists and how to use it. To locate N-List data using FINDER_NLIST_MAPPING perform the following steps: 1. For a selected data type, choose the corresponding header table name from the column TNAME. 2. In the same row as the TNAME, identify CNAME. This now provides the header table and column name that will resolve to the N-List name within a file. However, since each subsystem has modeled N-Lists a bit differently, we need to continue looking. 3. For each instance of CNAME and TNAME, identify the filename and N-List ID: If CVALUE is not empty, then the filename and N-List ID are identified by FILE_NAME and NLIST_ID. This is used by the contouring system. If CVALUE is blank, then the filename and N-List ID are identified by DIRECTORY, FILE_NAME and NLIST_ID.
The value in DIRECTORY is the logical name of the data store that contains the N-List. Logical names are like the PATH concept in Unix. They define a search list of directories or database tables that are used to locate the n-List data. This allows the physical directory structure to be changed without having to disturb the header tables. See the section "Data Store Directories and Logical Names" on page 408 for more details.
406
Revised May 2, 2005
The value in FILE_NAME and NLIST_ID corresponds to the literal file name and N-List identifier within the file, unless the entry contains a leading @. If the entry begins with @, then this entry is the column name in the header table that contains the file name or N-List identifier. The DATA_TYPE column ties the data type of the N-List to the Finder data dictionary entries in FINDER_TABLES of scope NLIST. This column may be used by the data mover.
Table 19: FINDER_NLIST_MAPPING TNAME
FM_HDR FM_HDR FM_HDR LINES
CNAME
FILE_TYPE FILE_TYPE FILE_TYPE NLIST_ID
CVALUE
CONTOUR GRID SCATTER
DIRECTORY
FILE_NAME
@OS_PATHNAME @OS_PATHNAME @OS_PATHNAME
NLIST_ID
LINES GRIDS SCATTER @NLIST_ID
DATA_ TYPE
ESI$CULTURE
@NLIST_FILE
GRAPHIC_ OBJECT GRAPHIC_ OBJECT GRAPHIC_ OBJECT GRID_3D_X Y_ DATA GRID_3D_X Y_ DATA
LYNX_ARCS
DIGITAL_REF
ESI$CULTURE
@DIGITAL_REF_ VOLUME @DIGITAL_REF_ VOLUME @NLIST_FILE
@DIGITAL_REF
LYNX_OBJECTS
DIGITAL_REF
ESI$CULTURE
@DIGITAL_REF
SEIS_3D_HDR
ESI$SEISMIC_ 3D
INLINES
SEIS_3D_HDR
ESI$SEISMIC_ 3D
@NLIST_FILE
XLINES
SEIS_ CORRECTIONS SEIS_FAULT_TR ACE SEIS_LINE_HDR
CORR_LIST_ID
ESI$SEISMIC_ HDR ESI$FAULT_ TRACE ESI$SEISMIC_ HDR ESI$SEISMIC_ PREFS ESI$SEISMIC_ HDR ESI$SEISMIC_ HDR ESI$SEISMIC_ HDR ESI$SEISMIC_ SURFACE
@NLIST_FILENLIS T_FILE @DIGITAL_REF_ VOLUME @NLIST_FILE
@CORR_LIST_ ID @DIGITAL_REF GRAPHIC_ OBJECT SHOT_XY_ DATA SHOT_ LABELS
DIGITAL_REF
SHOT_XY_ID
@SHOT_XY_ID
SEIS_LINE_HDR
SHOT_ LABELS_ID SHOT_DATUM_ ID VELOCITY_ID
@NLIST_FILE
@SHOT_ LABELS_ID @SHOT_ DATUM_ID @VELOCITY_ID
SEIS_LINE_HDR
@NLIST_FILE
SEIS_LINE_HDR
@NLIST_FILE
SEIS_LINE_HDR
SHOT_FOLD_ ID DIGITAL_REF
@NLIST_FILE
@SHOT_FOLD_ ID @DIGITAL_REF
SEIS_SURFACE
@DIGITAL_REF_ VOLUME
Revised May 2, 2005
407
Table 19: FINDER_NLIST_MAPPING TNAME

WELL_DIR_ SRVYHDR WELL_LOG_ CURVE_HDR
CNAME
DIGITAL_REF_ VOLUME DIGITAL_REF
CVALUE
DIRECTORY
ESI$SURVEYS
FILE_NAME
@DIGITAL_REF_ VOLUME @DIGITAL_REF_ VOLUME
NLIST_ID
@SURVEY_ DIGITAL_REF @DIGITAL_REF
DATA_ TYPE
ESI$LOGS
WELL_LOG_ CURVE
Data Store Directories and Logical Names

Finder uses the concept of a logical name for defining the access path to a file of a given data type. A logical name translates to a list of one or more data stores (for example, directories or database tables) that specify where to look for a file. This model is very similar to the PATH and LD_LIBRARY_PATH variables in Unix: they specify at run time where to look for files. This mechanism was originally patterned after the VMS operating system logical name concept. Each program in Finder that uses file-based storage follows the following procedure: 1. Appends the logical directory name to the front of a file name 2. Translates the name at run time 3. Accesses the file using standard operating system function calls. For reading, the search stops at the first successful access. For writing, the first entry in the logical name list is always used. You must make sure that this directory or table has the privileges set to allow modification. For directories, use the Unix function chmod. For tables, use the SQL statement GRANT. Beginning with Finder 8.0, the logical name concept is extended to include the name of an existing database table as a possible directory for NLists. The N-List library uses the file name and N-List ID in normal operating system directories to identify the database table name and value of the column NLIST_ID. Table 20 lists the current set of logical names that are used by programs to access N-Lists. The default directory setting is shown in the column Operating System Directory Name. Suggested table names for each data type are listed in the column Suggested Table/View Name. Logical names not shown in table 20 should not be set to point to database tables.
408
Revised May 2, 2005
Note:
Any valid table name could also be used, as long as the table conforms to the definition shown in table 21. The next section describes how a data type can be switched from being file-based to database table-based.
Table Definitions
Each data type that you wish to store as BLOB data needs to have a table created manually. The suggested names for the database tables/views for each data type are listed in table 20 under the column Suggested Table/View Name. For performance reasons, these tables should be assigned to separate tablespaces with large space allocations on separate disk drives. Each table is managed separately.
Revised May 2, 2005
409
Table 20: Finder logical names for N-List data
Logical Name
ESI$CONTOURS ESI$CULTURE ESI$DLS_GRID_COORDS ESI$DMD ESI$FAULT_TRACE ESI$GRIDS ESI$LOGS ESI$NTS_GRID_COORDS ESI$SCATTERS ESI$SEISMIC_3D ESI$SEISMIC_HDR ESI$SEISMIC_PREFS ESI$SEISMIC_SURFACE ESI$SURVEYS
Operating System Directory Name

ESI$PROJECT/contours ESI$PROJECT/culture ESI$PROJECT/dls ESI$PROJECT/dmd ESI$PROJECT/seismic/ ftrace ESI$PROJECT/grids ESI$PROJECT/logs ESI$PROJECT/nts ESI$PROJECT/xyz ESI$PROJECT/seismic/ 3dsurveys ESI$PROJECT/seismic/hdr ESI$PROJECT/seismic/ preferences ESI$PROJECT/seismic/ surfaces ESI$PROJECT/surveys
Suggested Table/View Name

CONTOUR_NLIST CULTURE_NLIST DLS_NLIST DMD_NLIST FTRACE_NLIST GRID_NLIST LOG_NLIST DLS_NLIST SCATTER_NLIST SEISMIC3D_NLIST SEISMIC_NLIST SEISMIC_PREF_NLIST SEISMIC_SURFACE_NLIST SURVEY_NLIST
FM Type1
CONTOUR CULTURE DLSCOORDS N/A N/A GRID N/A NTSCOORDS SCATTER N/A N/A N/A N/A N/A
1. File type used by File Manager (FM). N/A means Not Applicable.
410
Revised May 2, 2005
Each table created must conform to the definition shown in Table 21. Each table must have the following columns:
Table 21: Minimum table definition of N-List database tables or views
CNAME
NLIST_FILE NLIST_ID OFFSET NBYTES NLIST_DATA
DATA_TYPE
VARCHAR(256) VARCHAR(256) NUMBER(10,0) NUMBER(10,0) LONG RAW
NULL?
NOT NULL NOT NULL NOT NULL NOT NULL NOT NULL
Description
N-List File Name N-List identifier, unique within file name record number, unique within N-List file name and N-List ID # bytes in NLIST_DATA column raw binary data of N-List
The primary key of each table is a combination of NLIST_FILE, NLIST_ID, and OFFSET. Although it is possible to add additional columns, this is not recommended. An example script to activate LOGS as N-List BLOBs is shown below:
create table <table_name> (nlist_file varchar2(256) not null, nlist_id varchar2(256) not null, offset number(10 ,0) not null, nbytes number(10 ,0) not null, nlist_data long raw not null, constraint <table_name>_pk primary key (nlist_file, nlist_id, offset)) storage (initial 10m next 5M maxextents 121 pctincrease 0);
Note:
Replace <table_name> with the name of the database table. Primary key constraint name must be unique This is a basic tenet in database system setup: all names must be unique for a given class. There cannot be two different primary keys within the same schema that have the same name. The storage clause, which is optional, should be changed to accommodate your storage needs. After you create a table, one or more of the following privileges need to be granted to the appropriate user accounts before they can access the table: Delete Insert Select Update
Revised May 2, 2005
411
Functionality
An entry in LOGICAL_NAMES that is tied to the FINDER_NLIST_MAPPING table can be one of the following items: An operating system directory name A combination of logical names and directory names An encoded entry that specifies the table name in the database that is defined as shown in Table 20 on page 410. The encoding for a project-level table is P:TABLE_NAME, where TABLE_NAME is the name of the table defined as shown in Table 20 on page 410. The project name will be prepended to the table name by the N-List library before use. For instance, in a project called NORTH_SEA, an entry like P:LOG_NLISTS will be translated to the table name NORTH_SEA.LOG_NLISTS. The encoding for any other absolute-reference table name is T:TABLE_NAME, where TABLE_NAME is the name of the table defined as shown in Table 20 on page 410. The T: will be removed from the entry and the remaining string used by the N-List library. For instance, in a project called NORTH_SEA, an entry like T:COMMON.LOG_NLISTS will be translated to the table name COMMON.LOG_NLISTS. The following rules apply to programmers using the N-List library: 1. All N-List functions that accept a file name will accept and process logical names embedded as part of the file name. 2. File names containing logical names should not be translated by the application. The N-List function library manages the translations. 3. Reading an N-List from a data store will search each entry in a logical name list. The search will terminate when the first n-List_ID in the specified N-List file name + current directory is found. 4. Writing will always use the first entry in the logical name list.
412
Revised May 2, 2005
Logical Names Hierarchy

Data type is set by logical name. The logical names are tiered. Their hierarchy is: 1. Analyst 2. Project 3. System Overrides follow the logical name tier levels. Project overrides system. Analyst overrides project and system. This allows an analyst to have their own database that overrides the project or system database. It is helpful in testing or for privacy. The drawback is that one analyst cannot access another analysts database. This override capability should be used with caution.
Application
Newly Created Project Using Relational Table-Based N-Lists
For best performance, the database must be created or re-created using a large DB_BLOCK_SIZE setting. See the information under the heading "Performance" on page 415. Also see the Finder Installation Guide for more information. 1. Define a table for each N-List type that is to be stored in the database. This can be done by making entries in the Finder schema, or by manually creating the table using SQL*PLUS. Each table must be defined separately. 2. Review your space requirements for each N-List type and make sure you have enough free space in the tablespaces to hold the bulk data. Consider whether you will put all N-List data in a single tablespace (with many files allocated to the single tablespace), or whether you will create multiple tablespaces (for example, one tablespace per N-List type). 3. Create space allocation records in the table FINDER_TABLE_SPACE for the N-List tables and primary keys. For best performance, place the N-List table indexes in a separate tablespace, preferably on a separate device.
Revised May 2, 2005
413
4. Run the utility schema_run_validate using the project name and password, and the flags -tpig. At this point, all tables needed to hold the bulk data have been prepared. 5. Set the logical names for the project to point to the new tables. There is one logical name for each N-List type. The TRANSLATION column in the project logical names table is changed to be of the form P:TABLE_NAME, where TABLE_NAME is the name of the newly-created N-List tables appropriate to each type. Table 20 on page 410 lists the suggested table names. To propagate the names to all future projects, place these names in the DEFAULT_PROJECT.LOGICAL_NAMES table. 6. Run nl_blob_audit to verify the following: The tables exist. The appropriate keys have been defined. The structure of the tables is correct. The correct grants allowing public access to the tables has been granted. The logical names correctly point to the BLOB tables.
The project is now ready to operate.
Changing an Existing Project to Use Relation Table-Based N-Lists (Side Grade)

For each N-List type you wish to have stored in relational tables perform the following steps: 1. Define the table for each N-List type. 2. Create space allocation records in FINDER_TABLE_SPACE for use by all projects, or in ACCOUNT_TB_DEFS for a local project.
414
Revised May 2, 2005
As delivered, the space allocation for N-List tables has been set to zero. To create the space allocation records, execute the following statement while logged into the project account:
INSERT INTO ACCOUNT_TB_DEFS (ONAME, ...) SELECT TNAME, ... FROM FINDER_TABLES WHERE SCOPE=NLIST; INSERT INTO ACCOUNT_TB_DEFS (ONAME, ...) SELECT PK_CONSTRAINT_NAME, ... FROM FINDER_TABLE_CNSTS A WHERE EXISTS (SELECT 1 FROM FINDER_TABLES B WHERE A.TNAME=B.TNAME AND SCOPE=NLIST);
3. Run the utility schema_run_validate using the project name and password, and the flags -tpig. At this point, all tables needed to hold the bulk data have been prepared. 4. Run nl_blob_audit (see "nl_blob_audit Utility" on page 419) to verify the following: The tables exist. The appropriate keys have been defined. The structure of the tables is correct. The correct grants allowing public access to the tables has been granted. The logical names correctly point to the BLOB tables.
This defines the tables to receive the N-Lists. Update the project logical names table to increment, by one, each existing N-List directory sequence number.
Performance
Storing data in the Oracle database incurs more overhead than writing directly to an operating system file store. The additional tasks include formatting the Oracle data blocks, writing to the system redo log, and additional network overhead and context switching.
Revised May 2, 2005
415
In order to maximize the throughput of the LONG RAW data types in Oracle, the database instance must be configured to have a large block size. The maximum block size is operating system dependent. Setting this value requires the Oracle database administrator to edit a parameter file and add or change the parameter named DB_BLOCK_SIZE. For the Solaris 8 operating system under Oracle 8.1.6, the maximum size is 16K. After editing the parameter file, you must perform the following actions on the database: 1. Back up using exp (be careful about compressing extents in large databases. It may not be possible to create a single extent when you reload the data). 2. Shut down. 3. RE-CREATE (not simply restarted). 4. Have data restored. This is not a simple shutdown and restart. Once the database has been reinitialized, it can be restarted normally for all future operations. All tables in this database instance will now use the new blocking factor. This represents the number of blocks/bytes fetched per read operation. For actions that fetch large numbers of blocks, this may achieve higher performance. Those actions that need smaller retrievals may see their performance degraded. When using exp, you will need to allocate about 500000 to the size of the buffer. The size and number of rollback segments should be reviewed and probably increased. The more simultaneous uses you have, the more rollback segment storage you will need. The System Global Area (SGA) size is dependent on the DB_BLOCK_SIZE. Therefore, you may need to adjust other parameters that affect the size of the SGA. These include DB_BLOCK_BUFFERS and SHARED_POOL_SIZE. For maximum performance, the entire SGA should fit into the physical memory of the server. To preserve the existing SGA size, if the DB_BLOCK_SIZE is increased by a factor of 4, the DB_BLOCK_BUFFERS should be decreased by a factor of 4. You may need to alter the operating system shared memory allocation. On Solaris, this is the file /etc/system.
416
Revised May 2, 2005
Migration strategies
If you have existing projects with data already stored in files, you can choose from three different strategies for each project and data type: Status quo: Retain the existing file structures. Complete migration: Add tables for some or all of the N-List directories. Migrate all data into the database. Delete all N-List files. Remove all references of logical names to directories. Add tables and have all future N-Lists written to a database table. N-Lists already in files remain available.
Your choice depends on what performance levels you need, balanced with the amount of management and database setup you are willing to perform. The nlist_mover command line utility is provided with Finder 8.0 to facilitate the movement of N-List from one data store to another. It works on one logical name at a time. This utility is described under the heading nlist_mover Utility below.
nlist_mover Utility
This utility moves N-Lists from one data store to another. This includes transferring N-Lists: from operating system files to an Oracle database. (still in binary form, as LONG RAW values) from one operating system directory to another. from one BLOB table to another.
To use nlist_mover, first set up a logical name as a list of two or more data stores (tables, operating system directories or both). All N-List files encountered in the second entry of the logical name list are copied to the first entry in the list. No N-Lists are deleted by this utility.
Logical Names
The logical name translation service provides location transparency of n-List storage to applications. Since the logical name can translate to a list of directories or tables, applications should not attempt to translate the logical name. This is accomplished by using Finders logical_names table. Before running this utility, set the logical directory name to be a list, with the source of the N-List data being listed second, and the destination first.
Revised May 2, 2005
417
Note:
In the following discussion of the logical_names table, you should leave the CONCEALED and SHARED columns set to NULL. Make sure SEQ is not set to zero. To move N-Lists from /abc/def to /ghi/jkl, enter the following in the logical_names table of the account you normally connect to (these will be private the this analyst):
Table 22: Analyst level logical name entries
Logical_name
MY_LOGICAL MY_LOGICAL
Environment
SOLARIS SOLARIS
Translation
/ghi/jkl /abc/def
Seq
1 2
Scope
ANALYST ANALYST
To move N-Lists from /abc/def to /ghi/jkl, enter the following in the logical_names table of the project for use by all analysts:
Table 23: Project level logical name entries
Logical_name
MY_LOGICAL MY_LOGICAL
Environment
SOLARIS SOLARIS
Translation
/ghi/jkl /abc/def
Seq
1 2
Scope
PROJECT PROJECT
To move N-Lists from the file store into the database, first create a table to store the N-Lists if it has not already been created. These tables must have been created with the following definition: An entry in the translation column of the form, t:account_name.table_name, specifies the absolute table_name in the database:
Table 24: Absolute table logical name entry
Logical_name
MY_LOGICAL
Environment
SOLARIS
Translation
t:shared.nlist_log_data
Seq
1
Scope
PROJECT
An entry in the translation column of the form p:table_name specifies the project table_name in the database:
Table 25: Project table logical name entry
Logical_name
MY_LOGICAL
Environment
SOLARIS
Translation
p:nlist_log_data
Seq
1
Scope
PROJECT
418
Revised May 2, 2005
nlist_mover Reference
The nlist_mover utility is entered at the command line in the following format:
nlist_mover name/password project logical [filename] [-update] [-help] [-example]
Where:
name/password =Analyst name and password project =Name of project logical =Logical name resolving to a list of 2 or more directories and/or tables in the LOGICAL_NAMES table. Enclose any logical containing a dollar symbol with apostrophes (). filename =Existing file name in logical directory. If omitted, move all files from entry 2 in the logical name list to entry 1. -update =Replace an N-List in the target that has the name as in the source. Otherwise, the NList in the target will be left unmodified. -help =Print out additional help text -example =Print out examples
nl_blob_audit Utility
This PL/SQL utility verifies the tables are prepared correctly for storing N-Lists as BLOBs. These preparation include verifying that the tables exist, the appropriate keys have been defined, the structure of the tables is correct, the correct public access grants are set, and the logical names point to the BLOB tables.
nl_blob_audit Reference
The nl_blob_audit utility is entered in SQL*PLUS in the project account using the following format:
start $FH/scripts/nl_blob_audit
If the tables preparations are correct, nl_blob_audit will display a series of messages similar to the example shown below:
Revised May 2, 2005
419
Checking logical name ESI&GRIDS Table NLIST_DATA exists: Tablespace: SPIDER Bytes: 26218496 Extents: 4 Initial Extend: 10485760 Next Extend: 5242880 Pct Increase: 0 The following columns are part of the primary key: NLIST_FILE NLIST_ID OFFSET Primary key appears to be correct The following privileges have been granted: DELETE to PUBLIC INSERT to PUBLIC SELECT to PUBLIC UPDATE to PUBLIC PL/SQL procedure successfully completed. SQL> exit
If the table preparations are not correct, nl_blob_audit will display one or more of the following error messages:
Table 26: nl_blob_audit error messages
Message
Table <table_name> not found !!!
Explanation
The table (table_name) in the message does not exist.
Corrective Action
If the table does not exist, define it or refer to a table that does exist. If the table does exist, verify that it is being referenced correctly. If the column does not exist, define it or refer to a column that does exist. If the column exists, verify that it is being referenced correctly. If the key does not exist, define it or refer to a key that does exist. If the key exists, verify that it is being referenced correctly.
<column_name> in <table_name> not correctly defined. !!! Incorrect primary key <key> detected !!!
The column (column_name) in the message does not exist or is not defined as stated. The primary key
420
Revised May 2, 2005
Troubleshooting N-List BLOBs Integration

Table Not Created During BLOB Table Import
If N-List BLOB tables are exported with compress extents, then on import, they may be so large to allow table creation. The table will not be created on import. The solution is to create the table before importing, and during the import ignore errors caused by the object existence. Alternatively, dont request that extents be compressed.
Table Created but BLOB Not Importing Correctly

The database table is created but the BLOB table does not import correctly using the imp utility. This can occur when the buffer is too small. Increase the buffer size on import of BLOB tables to very large: 500K or more.
Third-Party Application Cannot Read or Write to the Database

Third-party external operations applications that have not been linked with the latest libraries will not be able to read or write to the database tables. They can use the existing file model. The recommendation for these is to not use table storage for them.
Revised May 2, 2005
421
422
Revised May 2, 2005
Chapter 10: Finder SDE Administration
Chapter 10
Introduction
In this chapter you will find: Finder SDE overview on page 426 - describing the SDE technology and the reasons for why it has been incorporated into Finder. This section includes the software environment requirements for running Finder SDE, and overviews of the Finder SDE architecture and utilities. The main workflows are also presented. Finder SDE utility reference on page 431 - describing the Finder SDE utilities in detail. Each description includes the system requirements for running the utility, the utility syntax, and detailed examples showing how the utilities and parameters should be used. Finder SDE data model on page 447 - describing the Finder SDE data model in detail. This section lists the meta data tables and the spatial data and views tables. The data model is also illustrated in a schema diagram. Well and deviation data selection methods for Shape File Unloader and f2sde_transfer on page 465 - describing the main differences between how these two features select wells and deviation data for export. SDE performance tuning on page 466 - describing additional administration activities. These include changing the grid size for a layer, customizing layer views, and managing Finder SDE tablespaces. Work-arounds for known problems on page 469 - discussing some technical issues associated with Finder SDE and ways for dealing with them.
Revised May 2, 2005
425
Finder SDE overview

This section includes information on Description of Finder SDE on page 426 Finder SDE workflow on page 429
Description of Finder SDE

This section covers the following: Introduction to SDE on page 426 Incorporation of SDE into Finder on page 426 Software requirements for running Finder SDE on page 427 Architectural overview of Finder SDE on page 427 Finder SDE utility functions on page 428
Introduction to SDE
Spatial Data Engine (SDE) is a technology for storing spatial data in a relational database, such as Oracle. This technology, ArcSDE, was developed by Environmental Systems Research Institute, Inc. (ESRI). It allows spatial data to be accessed by ESRI applications such as ArcView, ArcMap, and ArcIMS via SDE server.
Incorporation of SDE into Finder

ESRIs SDE technology has been incorporated into Finder to provide direct access to spatial data for ESRI applications such as ArcView and ArcIMS. To enable Finder for SDE, spatial data are copied from native Finder storage (N-lists and Oracle tables) to ArcSDE format storage called SDE extensions. One SDE extension is created for each Finder project. The Finder SDE component can be configured so that data are automatically replicated according to a regular schedule. For example, a Finder DBA can set project data to be replicated each night. The following data types are supported by SDE extensions:
WELLS LEASE SEISMIC2D GEMS (includes 3D seismic outlines)
426
Revised May 2, 2005
The Finder SDE component also incorporates Finder security features such as requiring Finder analyst account privileges, a secure password, a separate license, and Secure Data Access (SDA) compliance, ensuring users can display only those data to which they are entitled.
Finder SDE technology provides three major advantages over the export of data to shapefiles: Eliminates the requirement to export data to shapefiles before the data can be displayed in a mapping application. This reduces the effort required to display spatial data in a map. Eliminates the risk of using outdated data because the most recent data are transferred directly to the mapping application from the database. Eliminates the need to manage a potentially large volume of shapefiles.
Software requirements for running Finder SDE

To create an SDE extension for a Finder project, the following software must be installed: Finder 9.4 ArcSDE 8.2 Oracle 8.1.7.3 or 9.2.0.6 Sun Solaris 8 FLEXlm 7.2e
Architectural overview of Finder SDE

The Finder SDE data model extends the Finder project data model. The Finder SDE component creates a separate Oracle account for each SDE extension. This allows spatial data to be maintained in ArcSDE format separately from other project data. When an SDE extension is created for a project, an SDE account is created in the format <project_name>_SDE. For example, an SDE extension for a project called SPIDER would have an SDE account called SPIDER_SDE. The SDE account stores data tables and index tables, as well as views for spatial data. Figure 1 illustrates this architecture. This shows that the Finder spatial data continues to be maintained in an N-list and Oracle
Revised May 2, 2005
427
tables and, as such, can be accessed through Finder tools. These data are also copied to the project SDE extension and stored in ArcSDE format so that they can be accessed directly from ESRI applications such as ArcView. Thus, enabling Finder for SDE does NOT affect other Finder operations. For ESRI application users to access spatial data directly from Finder, Finder and ArcSDE must be installed in the same Oracle instance referenced by the TWO_TASK environment variable when the SDE server is started.
Finder Database
ESI Project Finder N-list
SDE SDE Server
ESRI Applications (ArcView ArcMap ArcIMS)
Data replication
Project_SDE
Figure 1: Finder project SDE account architecture
Finder SDE utility functions

The Finder SDE component includes three command-line utilities for creating SDE extensions for Finder projects, managing data layers, and replicating spatial data to ArcSDE format. To run these utilities, the Finder environment must be configured correctly and the SDE server must be running. This section provides a general overview of each utility. More detailed descriptions of the syntax and parameters can be found at Finder SDE utility reference on page 431.
f2sde_extension
This utility is run only once for each project to create an SDE extension account. As part of the account setup process it also runs the f2sde_layer utility to create the data layers and layer views in the SDE account. This utility can also be used to delete an SDE extension account.
f2sde_layer
428
Revised May 2, 2005
This utility manages the layers and views for an SDE account. The f2sde_extension utility runs this utility when it creates an SDE account. Once the account has been created, f2sde_layer can be run independently to manage (i.e., drop and re-create) the layers during the life of the project SDE extension account.
f2sde_transfer
This utility copies spatial data from the N-list and Oracle tables to the SDE extension for the project. The f2sde_transfer utility ensures that the spatial data in the SDE storage area are the same as those in the Finder project. This utility can transfer all data (a full transfer) at one time, or only those data that have changed or been added since the previous transfer (an incremental transfer).
Finder SDE workflow

This section describes the main Finder SDE workflows, as follows: Creating an SDE project extension on page 429 Creating and deleting layers and views on page 430 Replicating data for an SDE project extension on page 430 Deleting an SDE project extension on page 431
Creating an SDE project extension

This section lists the steps that the f2sde_extension utility goes through when it creates an SDE account for a project. The f2sde_extension utility 1. Starts from a command line. 2. Validates the parameter arguments. 3. Checks the project name is correct. 4. Validates the ESI password. 5. Creates a Finder SDE extension account for the specified project. 6. Inserts a row into the ESI.FINDER_ACCOUNTS table. 7. Grants the SDE extension account the required privileges.
Revised May 2, 2005
429
8. Stores the -minX, -minY, -maxX, -maxY, -g, and -fg values as a new entry in the <PROJECT>.PROJECT_DEFAULTS table. See Finder PROJECT_DEFAULTS table parameters (pg. 450) for a description of the parameters associated with the these values. 9. Runs the f2sde_layer utility to create all the layers and views.
Creating and deleting layers and views

This section lists the steps that the f2sde_layer utility goes through when it creates or deletes layers and views. The f2sde_layer utility 1. Starts either from a command line or is invoked by the f2sde_extension utility. 2. Checks that an SDE account exists for the specified project. 3. Validates the project account and project SDE account passwords. 4. Determines that a create or delete operation is to be performed. 5. Gets the data area and coordinate system parameters from the <PROJECT>.PROJECT_DEFAULTS table. 6. Checks whether any layers exist for the specified data types. 7. Creates or deletes the layers for the data type and stores the layer information in the ESI.FINDER_SDE_DATA_TYPES table. 8. Creates or deletes the views for the data type. When creating views, checks whether the views already exist. If they do, f2sde_layer re-creates the views.
Replicating data for an SDE project extension

This section lists the steps that the f2sde_transfer utility goes through when it transfers data in either full or incremental mode. The f2sde_transfer utility 1. Starts from a command line. 2. Validates the parameter arguments. 3. Starts either a full replication of data or an incremental replication.
430
Revised May 2, 2005
4. If a full replication, f2sde_transfer first deletes all items for the specified data type in the SDE extension. If an incremental replication, f2sde_transfer first deletes only those items in the SDE extension that are being updated. An incremental transfer will also delete items that have been deleted in the source Finder project. 5. Retrieves spatial data from the source Finder project and converts them to SDE shapes. 6. Writes the data to the SDE extension.
Deleting an SDE project extension

This section lists the steps that the f2sde_extension utility goes through when it deletes an SDE account for a project. The f2sde_extension utility 1. Starts from a command line. 2. Checks that an SDE account exists for the specified project. 3. Validates the ESI account passwords. 4. Determines that a delete operation is to be performed. 5. Deletes the layer tables and layers by calling f2se_layer for all data types. 6. Drops the <project_name>_SDE account. 7. Deletes the setup records in the ESI and project tables.
Finder SDE utility reference

This section describes the following utilities f2sde_extension utility on page 432 f2sde_layer utility on page 437 f2sde_transfer utility on page 441
NOTE: The Finder SDE utilities support environment variables for security and convenience. If the command-line argument is not specified, the corresponding environment variable value will be used. If both a
Revised May 2, 2005
431
command-line argument and environment variable is specified, the command-line argument takes precedence and will be used. Table 1 lists the environment variables supported by the Finder SDE utilities.
Table 1: Environment variables for the Finder SDE utilities
Variable Name
ESI_PASSWORD PROJECT_NAME PROJECT_PASSWORD SDE_SERVER SDE_PORT PROJECT_SDE_NAME PROJECT_SDE_PASSWORD
Description
Finder ESI account password Finder project name Finder project password Server where ArcSDE is running Port number for ArcSDE Project SDE account extension name Project SDE account extension password
These variables can be set in a Finder Xterm before executing any of the Finder SDE utilities. Example: % setenv ESI_PASSWORD esi
f2sde_extension utility
This section includes the following: f2sde_extension description on page 432 f2sde_extension syntax on page 432 Example commands for f2sde_extension on page 436
f2sde_extension description
This utility is run only once for each project to create an SDE extension account and its objects. As part of the account setup process f2sde_extension also invokes the f2sde_layer utility to create the data layers and views in the SDE extension. This utility can also be used to delete an SDE extension when it is no longer needed.
f2sde_extension syntax
The command to launch f2sde_extension follows this syntax:
432
Revised May 2, 2005
f2sde_extension <project_name>/<project_password> [-o create | delete] -e <esi_password> -s <sde_server_name> -i <sde_server_port_number> -minX <X-coord> -minY <Y-coord> maxX <X-coord> -maxY <Y-coord> [-g <esri_coordinate_system_code> -fg <finder_projection_id>] dt <default_tablespace_name> -tt <temporary_tablespace_name>
where,
f2sde_extension is the name of the utility. <project_name> is the name of the Finder project for which an SDE extension needs to be created. The maximum allowed size of the project name is 26 characters. If a Finder project is more than 26 characters, it should be renamed before the SDE extension is created. This value can also be passed by the PROJECT_NAME environment variable. <project_password> is the password for the specified Finder project. This can also be passed by the PROJECT_PASSWORD
variable.
-e <esi_password>
This parameter is required and represents the Finder ESI account password. To prevent the password from displaying at the command line, set the ESI_PASSWORD environment variable before running the f2sde_extension utility.
-o create or delete
This parameter is optional and specifies whether a create or delete operation is required. A create operation will be performed by default if this parameter is not used.
-s <sde_server_name>
This parameter is required and represents the SDE server host name or IP address. This parameter can also be passed by the SDE_SERVER environment variable.
-i <sde_server_port_number>
This parameter is required and represents the port number for the SDE server. The port number will be listed in the $SDEHOME/etc/services.sde file, next to the uncommented line for the SDE service. This parameter can also be passed by the SDE_PORT environment variable. This parameter, together with SDE_SERVER, can be set in .finder once SDE_SERVER is
Revised May 2, 2005
433
configured for the Finder instance. Once configured, there is no need to pass these variables each time the f2sde_extension utility is run.
-minX <X-coord> -minY <Y-coord>
This parameter is required and represents the minimum XY coordinate (i.e., lower left corner) of the data area. The values for these coordinates are stored in the <PROJECT>.PROJECT_DEFAULTS table under SDE_XMIN and SDE_YMIN. NOTE: These coordinates do not replace the coordinates defined for the project in Finder.
-maxX <X-coord> -maxY <Y-coord>
This parameter is required and represents the maximum XY coordinate (i.e., upper right corner) of the data area. The values for these coordinates are stored in the <PROJECT>.PROJECT_DEFAULTS table under SDE_XMAX and SDE_YMAX. NOTE: These coordinates do not replace the coordinates defined for the project in Finder. NOTE 2: Minimum and maximum values for the data area need to be specified in the same coordinate system as the SDE layers specified with the -g option. Once set, the envelope dimensions can not be changed without deleting or recreating the layers.
-g <esri_coordinate_system_code>
This parameter is optional. The default value is 4326. This represents a geodetic coordinate system based on the WGS84 datum. NOTE: To view a list of the available coordinate systems and their codes, refer to the $SDEHOME/include/pedef.h file. Valid codes are defined only in the GEOGRAPHIC COORDINATE SYSTEMS and PROJECTED COORDINATE SYSTEMS sections of the pedef.h file. The valid coordinate system names have PE_GCS and PE_PCS prefixes. If it is used, it must be used with the -fg parameter. It identifies the coordinate system used for data stored in the SDE extension. All layers in the SDE extension are set to the same
434
Revised May 2, 2005
coordinate system. The -fg parameter represents the Finder projection ID that matches the SDE projection specified with the -g parameter.
-fg <finder_projection_id>
This parameter is optional and must be used with the -g parameter. If this parameter is not used, the Finder projection ID corresponding to the geodetic coordinate system (based on the WGS84 datum) is automatically looked up and used. The Geodetic-WGS84 coordinate system must be defined in Finder. If the -g parameter is used, this parameter must also be used. This parameter identifies the coordinate system in Finder that is equivalent to the SDE storage coordinate system. The value specified here should be one of the projection IDs defined in the PROJECTION_HDR table. If there is no projection ID that is equivalent to the chosen SDE coordinate system, the Coordinate System Manager should be used to define it in Finder. The values for -g and -fg must be mapped correctly between the ESRI application and Finder and represent the same coordinate system. The cartographic transformation takes place in Finder, and uses the -fg value if it is different from the project projection to transform data to the SDE storage coordinate system. The following examples demonstrate valid coordinate system mapping between SDE and Finder.
-g 4326 -fg GEODETIC (default) -g 4267 -fg GEODETIC-NAD27 -g 26712 -fg UTM-12
These examples assume the PROJECTION_HDR table has the values shown in Table 2.
Table 2: Example projection systems in the PROJECTION_HDR table
Projection_id
GEODETIC GEODETIC-NAD27 UTM-12
Name
WGS84 NAD27 UTM27-12
Type
DATUM DATUM PROJECTION
Revised May 2, 2005
435
-dt <default_tablespace_name>
This parameter is required and represents the default tablespace where the SDE extension account will be created. This parameter does not create the tablespace, so the tablespace should already exist.
-tt <temporary_tablespace_name>
This parameter is required and represents the name of the temporary tablespace that is used by the SDE extension. This tablespace should already exist.
Example commands for f2sde_extension

The following examples illustrate correct f2sde_extension usage: Example 1:
f2sde_extension spider/admin256 -e esi -s sc-borg -i 5152 -minX -110.2 -minY 41 -maxX -109.0 -maxY 42 -dt SDE_PROJECT -tt temp
This example shows how to create an SDE extension for a Finder sample project called spider. This example does not specify the coordinate system for SDE storage. Therefore, the default, a geodetic coordinate system based on the WGS84 datum, will be used. The data area (i.e., the area specified by the XY coordinates) is specified in degrees corresponding to the SDE coordinate system. In this example, the SDE extension account will be created with a name and password of spider_sde. The password can be changed by use of the SQL*Plus alter command. Example 2:
f2sde_extension spider/admin256 -e esi -s sc-borg -i 5152 -minX -110.2 -minY 41 -maxX -109.0 -maxY 42 -g 4267 -fg GEODETIC-NAD27 -dt SDE_PROJECT -tt temp
This example shows how to create an SDE extension for a Finder sample project called spider. The SDE storage coordinate system and the equivalent Finder projection ID is specified. The SDE storage will be created with the geodetic coordinate system based on the NAD27 datum. Example 3:
f2sde_extension spider/admin256 -o delete -e esi -s sc-borg -i 5152
436
Revised May 2, 2005
This example shows how to delete an SDE extension for a sample Finder project called spider.
f2sde_layer utility
This section includes the following: f2sde_layer description on page 437 Syntax for f2sde_layer on page 438 Example commands for f2sde_layer on page 440
f2sde_layer description
This utility creates the layers and views for a projects SDE extension. One or more layers are created for each data type. For example, three layers are created for wells. If a layer already exists, f2sde_layer will not drop the layer but will recreate the views. After the layers have been created, the layer status is stored in the ESI.FINDER_SDE_DATA_TYPES table. The f2sde_layer utility also creates the views for each layer based on the view definitions in the ESI.FINDER_SDE_VIEWS table. Standard view definitions in the ESI.FINDER_SDE_VIEWS table are shipped with Finder SDE for the WELLS, LEASE, and SEISMIC2D, data types. For the GEMS data type, the f2sde_layer utility automatically adds three basic views for each GEM class if no view definition exists for that class. See Customizing layer views on page 467 for more details. Finder SDE supports the following layers:
WELLS LEASE SEISMIC2D.LINES (polylines only) SEISMIC2D.LINES_M (polylines with labels) SEISMIC2D.SP (points only) GEMS (includes 3D seismic outlines)
When a delete operation is performed, all the layers of the specified data type are deleted. After deleting the layers, the f2sde_layer utility deletes all the views for the corresponding data type and deletes the corresponding records from the ESI.FINDER_SDE_DATA_TYPES table. Finder SDE supports the following data types:
WELLS LEASE
Revised May 2, 2005
437
SEISMIC2D GEMS (includes 3D seismic outlines)
The f2sde_extension utility invokes this application when it creates an SDE account. Once the account has been created, f2sde_layer can be run independently to manage (i.e., drop and re-create) the layers during the life of the project SDE account. NOTE: If you are creating an SDE extension for a project, the
f2sde_extension utility will automatically create an appropriate SDE account before running f2sde_layer.
f2sde_layer utility requirements

To run the f2sde_layer utility the SDE account for the specified project must already exist. The parameters associated with the SDE account must be set in the Finder <PROJECT>.PROJECT_DEFAULTS table. The SDE server must also be running on the Finder instance. NOTE: If you are creating an SDE extension for a project, the
f2sde_extension utility will automatically create an appropriate SDE account before running f2sde_layer.
Syntax for f2sde_layer

The command to launch f2sde_layer follows this syntax:
f2sde_layer <project_name>/<project_password> -o create / delete [-p <sde_extension_account_password>] -d <data_type> -s <sde_server_name> -i <sde_server_port_number> [-k <tablespace_configuration_keyword>] -h|help
where,
f2sde_layer is the name of the utility. <project_name> is the name of the Finder project for which spatial data layers need to be created or deleted. This parameter can also be passed by the PROJECT_NAME environment variable. <project_password> is the password for the specified Finder
project. This value can also be passed by the

PROJECT_PASSWORD environment variable.
-o create or delete
This parameter is required and identifies the type of operations to be performed. The options are create and delete. A create operation will create the layer(s) and views for the specified data type. A delete operation will delete all the layers and all
438
Revised May 2, 2005
the views for the specified data type if the layers exist. When layers are created or deleted the records in the ESI.FINDER_SDE_DATA_TYPES table will be updated.
-p <sde_extension_account_password>
This parameter is optional and represents the password for the SDE extension account. When the SDE extension account is created this is set to the same as the account name. If this parameter is not used, f2sde_layer assumes the password is the same as the account name. This parameter can also be passed by the PROJECT_SDE_PASSWORD environment variable.
-d <data_type>,<data_type> or ALL
This parameter is required and identifies the data type(s) for which layers are to be created or deleted. ALL creates or deletes layers for all supported data types. The allowed data types are: WELL - layers for well data LEASE - layers for lease data SEISMIC2D - layers for Seismic2D data SEISMIC2D.LINES - layers for Seismic2D polyline data SEISMIC2D.LINES_M - layers for Seismic2D polyline data including labels with M-values set to shotpoint values SEISMIC2D.SP - layers for Seismic2D shotpoint data GEM - layers for GEM data
This parameter is required and represents the port number for the SDE server. The port number will be listed in the $SDEHOME/etc/services.sde file, next to the uncommented line for the SDE service. This parameter can also be passed by the SDE_PORT environment variable.
-k <tablespace_configuration_keyword>
This parameter is optional and identifies an ArcSDE keyword for the tablespace where the layers will be created. If the layers need to be created in the default tablespace for the SDE extension, this parameter does not need to be used. NOTE: The sdedbtune command should be used to create the SDE tablespace configuration. Using this command, a separate tablespace can be specified for each layer object, such as
Revised May 2, 2005
439
business tables and index and spatial data. The -k parameter can then be used to associate each of the tablespaces. The general steps for configuring tablespaces for an SDE account are as follows: a. Use sdedbtune to export the tablespace configuration information to an ASCII file. Example: sdedbtune -o export <parameters> b. Edit this ASCII file to add or modify the configuration keyword for the SDE account. c. Import the edited ASCII file to the SDE account. Example: sdedbtune -o import <parameters> See the SDE documentation under $SDE_HOME/ documentation/sdehelp.htm for more detailed information about using the sdedbtune command.
-h or -help
This parameter displays online help for the f2sde_layer utility.
Example commands for f2sde_layer

The following examples illustrate correct f2sde_layer usage: Example 1:
f2sde_layer spider/admin256 -p admin256 -o create -d WELLS -s sc-borg -i 5152
This example shows how to create the data layers for a Finder sample project called spider. The layers will be created for data type WELLS. Example 2:
f2sde_layer spider/admin256 -p admin256 -o create -d WELLS,GEMS -s sc-borg -i 5152 -k spider_layers
This example shows how to create the data layers for a Finder sample project called spider. The layers will be created for data type WELLS and GEMS in a tablespace specified by the spider_layers configuration keyword. It is assumed that this keyword already exists for the SDE account. Example 3:
440
Revised May 2, 2005
setenv PROJECT_NAME spider setenv PROJECT_PASSWORD admin256 setenv PROJECT_SDE_PASSWORD setenv SDE_SERVER myserver setenv SDE_PORT 5152 f2sde_layer -o create -d wells
This example shows how to pass the project name, password, SDE server name, and SDE port with environment variables so that the variables need not be specified from the command line. Example 4:
f2sde_layer spider/admin256 -o create -d wells
This example shows how to simplify f2sde_layer when the SDE server and port number have been passed by using the SDE_SERVER and SDE_PORT environment variables. The value for <spider_sde_password> will use the account name (i.e., spider_sde).
f2sde_transfer utility
This section includes the following: f2sde_transfer description on page 441 Description of transferred data on page 442 Syntax for f2sde_transfer on page 445 Example commands for f2sde_transfer on page 446
f2sde_transfer description
This utility transfers spatial data from the native storage for a Finder project to the SDE storage. The f2sde_transfer utility can replicate data in only one direction (i.e., from Finder to the project SDE extension). This data replication process ensures that the data stored in SDE format are synchronous with the same data in the associated Finder project. For example, when well location data are updated in Finder, the same data will be updated in the SDE storage area by the next incremental data transfer to the SDE extension. The f2sde_transfer utility is invoked from a command line. After a project SDE account has been created, f2sde_transfer can be used to transfer all the spatial data from the project to the new SDE extension account. This is a full transfer. Subsequently, f2sde_transfer can be used to transfer only those data that have changed or been added since the previous transfer. This is an incremental transfer. Any data that are deleted in the source project will also be deleted in the project SDE
Revised May 2, 2005
441
extension account during the next transfer. Data types are transferred one at a time. An incremental data transfer can be set to run periodically by cron job or whenever needed. It is recommended that a cron job is run each night. To verify when the last transfer occurred, check the ESI.FINDER_SDE_DATA_TYPES table. Each entry in this table for data type includes a date stamp and update mode. The LAST_REFRESHED column lists the date and time the data type was last transferred, and the REFRESH_ACTION column indicates whether the data were transferred in FULL or INCREMENTAL mode. See Finder SDE data model on page 447 for information about the tables used for storing spatial data in an SDE extension account.
Description of transferred data

This section describes the data transferred to a project SDE extension during data replication. The following data types can be transferred by the f2sde_transfer -d parameter:
WELLS This data type represents well top and well bottom locations, as well as deviation surveys. Well tops and bottoms are transferred as points and represent the surface locations of the well tops and bottoms. Deviation surveys are represented as 3D shape polylines that contain values for true vertical depth (TVD) and measured depth (MD). Only one deviation survey (the preferred survey) per well is transferred from data tables.
In full mode, deviations for wells are transferred only if the following conditions are met: The well is marked as deviated in the WELL_HDR table (deviation_flag = Y). Only one preferred survey exists for this well in the
WELL_DIR_SRVY_HDR table (preferred_flag = Y).
Entries for the preferred deviation survey exist in the

WELL_DIR_SRVY_PTS table.
NOTE: No deviation survey is transferred for wells that are not marked as deviated, or do not satisfy all the above conditions. The deviation survey data are transferred from data tables, not N-lists. In incremental mode, only wells that have been modified since the last transfer are moved. The following represent a modification for wells:
442
Revised May 2, 2005
The location of a well is changed (the XY values in the NODES table are changed). Any attribute of the well record is changed in the WELL_HDR table.
In addition to the above conditions for well deviation surveys, the following will result in a deviation survey to be transferred in an incremental transfer: The record for the preferred survey for the well (in the
WELL_DIR_SRVY_HDR table) is changed, or the preferred
survey is changed. Any of the deviation points for the preferred survey are changed (in the WELL_DIR_SRVY_PTS table).
LEASE This data type transfers lease information from a
project. Leases are represented as polygons in SDE. Finder is much more flexible than SDE when it comes to polygon shapes. This flexibility allows Finder to store leases that would be considered invalid polygons in SDE. Such leases would be flagged as errors during the data transfer, and will not get moved to the SDE project extension. Figure 2 provides examples of polygons that may be present in a Finder project, but will generate errors when transferred to the SDE project extension.
1) Unclosed polygon
2) Self-intersecting polygons
Donut
3) Multipoint area shapes have overlapping points
4) Two donuts or outer shell of a polygon overlap
In this case, if there is a point (XY) at the intersection, the transfer will break this shape into two polygons, and store it in the SDE extension successfully.
Figure 2: Finder project polygons that are invalid for SDE extensions
In full mode, all leases in a project will be transferred.
Revised May 2, 2005
443
In incremental mode, only the leases that have changed since the last transfer will be transferred. The following represent a modification to a lease: Any attribute of the lease is changed in the LEASE table. The location or shape of the lease is changed (e.g., through the graphic object editor).
SEISMIC2D This data type transfers 2D seismic lines and
shotpoints. SEISMIC2D - transfers data from all Seismic2D layers SEISMIC2D.LINES - transfers data from Seismic2D polyline layers SEISMIC2D.LINES_M - transfers data from the Seismic2D polyline layers including labels with M-values set to shotpoint values SEISMIC2D.SP - transfers data from the Seismic2D shotpoint layers In full mode, all the seismic 2D lines and shotpoints in the project are transferred. In incremental mode, only the lines that have been modified are transferred. The following represent a modification for seismic 2D lines: The entry for a line is changed in the SEIS_LINE_HDR table. Any shotpoint in a line is changed (e.g., the location of the shotpoint is moved).
NOTE: Seismic lines and their shotpoint are transferred as separate entities. A line may, therefore, be transferred without its shotpoints or the shotpoints may be transferred without the line in case of errors in either.
GEMS These data types are transferred by specifying the corresponding object class with the -d option (e.g., -d PIPELINE). The polygons, lines, and points associated with a
GEM object are moved. In full mode, only those GEM objects with MAPPABLE = Y set in the <PROJECT>.OBJECT_CLASSES table will be transferred. In incremental mode, modified GEM objects are transferred. Any change in the location or shape of a GEM object (e.g., modifications made through the graphic object editor) represents a modification to a GEM object.
444
Revised May 2, 2005
The GEM data views are only available if there are data in the SDE extension account. Depending on which kind of shapes were transferred, the following views may exist:
FSD_<object_class>_P_V (polygons) FSD_<object_class>_L_V (lines) FSD_<object_class>_S_V (points)
If a GEM object that contains only polygons is transferred (with no lines and no points), users will have access to only the FSD_<object_class>_P_V view.
f2sde_transfer utility requirements

To run the f2sde_transfer utility, the following system requirements must be met: The project SDE account must exist. Layers for the data type being transferred must exist in the project SDE extension account. The SDE server must be running on the Finder instance specified by the host and port number.
Syntax for f2sde_transfer

The command to launch f2sde_transfer follows this syntax:
f2sde_transfer <sde_account_name>/<sde_account_password> -o full | inc -d <data_type> -s <sde_server_name> -i <sde_server_port_number> -h | help
(NOTE: A journal file called f2sde_transfer.log is created in the users current directory when the transfer is executed.) where,
f2sde_transfer is the name of the utility. <sde_account_name> is the name of the project SDE account. This parameter can also be passed by the PROJECT_SDE_NAME
environment variable.
<sde_account_password> is the password for the project SDE
account. This parameter can also be passed by the

PROJECT_SDE_PASSWORD environment variable.
-o full or inc
Revised May 2, 2005
445
This parameter is required and determines whether f2sde_tranfer should transfer all the project spatial data (a full transfer) or only those data that have changed since the previous transfer (an incremental transfer). The last transfer time and date is stored in the ESI.FINDER_SDE_DATA_TYPES table. A full transfer deletes all the data in the SDE storage and moves all spatial data of a given data type. At least one full transfer must be performed before starting the first incremental transfer.
-d <data_type> or <GEM object class name>
This parameter is required and identifies the data type to be transferred. GEM data types are moved by object class and not the entire GEM. Therefore, a valid GEM object class name should be used. Only one data type or GEM objec class can be transferred at a time. The allowed data types are: WELLS - transfers data from well layers LEASE - transfers data from lease layers SEISMIC2D - transfers data from all Seismic2D layers SEISMIC2D.LINES - transfers data from Seismic2D polyline layers SEISMIC2D.LINES_M - transfers data from the Seismic2D polyline layers including labels with M-values set to shotpoint values SEISMIC2D.SP - transfers data from the Seismic2D shotpoint layers
This parameter is required and represents the port number for the SDE server. The port number will be listed in the $SDEHOME/etc/services.sde file, next to the uncommented line for the SDE service. This parameter can also be passed by the SDE_PORT environment variable.
Example commands for f2sde_transfer

The following examples illustrate correct fsde_transfer usage: Example 1:
446
Revised May 2, 2005
f2sde_transfer spider_SDE/admin256 -o full -d WELLS -s sc-borg -i 5152
This example shows how to conduct a full transfer of spatial data from a sample Finder project called spider to a corresponding SDE account called spider_SDE. The data type being transferred is WELLS. Example 2:
f2sde_transfer spider_SDE/admin256 -o inc -d LEASE -s sc-borg -i 5152
This example shows how to conduct an incremental transfer of spatial data from a sample Finder project called spider to a corresponding SDE account called spider_SDE. The data type being transferred is LEASE. Example 3:
f2sde_transfer spider_sde/admin256 -o full -d PIPELINE -s sc-borg -i 5152
This example shows how to transfer a GEM object class.
Finder SDE data model

This section describes the Finder SDE data model. The SDE extension data model for managing spatial data is an extension of the Finder project data model. Each project SDE account consists of tables (including geometry tables [F tables] and spatial index tables [S tables]), spatial views, triggers, and constraints. The spatial data tables store the key columns of the business table and the shape column. The spatial data views combine the attributes of the business table and shape (geometry) for each layer. The views are created by joining the spatial tables in the SDE extension and the business tables in the project and exposing them to public access. An administrator can customize each view to expose or hide additional attributes. Finder security enforced on the business table is inherited by the view. The following features of the Finder SDE data model are described: Finder SDE meta data tables on page 448 Finder PROJECT_DEFAULTS table parameters on page 450 Finder SDE tables for spatial data and views on page 451 Finder SDE account data model schema on page 464
Revised May 2, 2005
447
Finder SDE meta data tables

When the f2sde_extension utility creates an SDE account, a new record is created in the ESI.FINDER_ACCOUNTS table. New tables are created in ESI for the SDE data types and views. These tables are described below. ESI.FINDER_ACCOUNTS table on page 448 ESI.FINDER_SDE_DATA_TYPES table on page 448 ESI.FINDER_SDE_VIEWS table on page 449
ESI.FINDER_ACCOUNTS table
When the f2sde_extension utility creates an SDE account, the ESI.FINDER_ACCOUNTS table stores the information shown in Table 3.
Table 3: Information stored in ESI.FINDER_ACCOUNTS
Column Name
ACCOUNT_NAME
Description
Stores the name of the new account. An account name consists of the Finder project name with an SDE suffix, for example spider_SDE. Set to SDE. Stores the date the new account was created. This column is always set to NULL.
TYPE CREATED_DATE LAST_VALIDATED
ESI.FINDER_SDE_DATA_TYPES table
The ESI.FINDER_SDE_DATA_TYPES table stores status information for all the ArcSDE layers in Finder. This information is listed in Table 4.
Table 4: Status information stored in the ESI.FINDER_SDE_DATA_TYPES table
Column Name
PROJECT DATA_TYPE SUB_TYPE
Type
Varchar2(30) Varchar2(30) Varchar2(40)
Description
Name of the Finder project Name of the data type Name of the sub type (e.g., GEM object class) The date the layer was created
Constraints
Primary key Primary key Primary key
CREATE_DATE
Date
Not null
448
Revised May 2, 2005
Table 4: Status information stored in the ESI.FINDER_SDE_DATA_TYPES table
Column Name
LAST_REFRESHED
Type
Date
Description
The date that data were last refreshed for the layer The type of refresh performed (either full or incremental)
Constraints
None
REFRESH_ACTION
Varchar2(30)
ESI.FINDER_SDE_VIEWS table
The FINDER_SDE_VIEWS table stores the data required to create ArcSDE views. These data are listed in Table 5.
Table 5: SDE view definition data in the FINDER_SDE_VIEWS table
Column Name
VIEW_NAME DATA_TYPE SUB_TYPE
Type
Varchar2(30) Varchar2(30) Varchar2(40)
Description
The name of the view The name of the data type The sub data type or object class (e.g., GEMS). The names of attributes in the view separated by commas. For example, UWI, WELL_NAME, and TVD. (SHAPE is always required.) The source table names. The table name is prefixed with the "<<PROJ>>" string. This is replaced by the actual project name at the time of creation. For example: SPIDER.WELL_HDR, FSD_WELL_TOP
Constraints
Primary key None None
COLUMNS
Varchar2(2000)
None
TABLES
Varchar2(2000)
None
Revised May 2, 2005
449
Table 5: SDE view definition data in the FINDER_SDE_VIEWS table
Column Name
WHERE_CLAUSE
Type
Varchar2(2000)
Description
The join condition between tables and other data filtering conditions The line number of the view statement. If any of the above is more than 2000 characters, the record will be stored in more than one line.
Constraints
None
LINE_NO
Number
Primary key
Finder PROJECT_DEFAULTS table parameters

When an SDE account is created, some parameters are added to the Finder PROJECT_DEFAULTS table for later use. Table 6 lists the parameters added to the PROJECT_DEFAULTS table.
Table 6: PROJECT_DEFAULTS parameters
Column Names DEFAULT_NAME

SDE_PROJECTION SDE_FINDER_PROJECT ION
DEFAULT_VALUE
Stores the SDE projection code PROJECTION_ID from PROJECTION_HDR table corresponding to SDE_PROJECTION code. Minimum X coordinate Maximum X coordinate Minimum Y coordinate Maximum Y coordinate
DEFAULT_DOMAIN
No value No value
APPLICATION_NAME
SDE SDE
SDE_XMIN SDE_XMAX SDE_YMIN SDE_YMAX
SDE SDE SDE SDE
450
Revised May 2, 2005
Finder SDE tables for spatial data and views

This section describes the spatial data tables and views that comprise the data model for a Finder SDE project extension account. The table descriptions are organized as follows: Spatial data tables for the WELLS data type on page 451 Spatial data views for the WELLS data type on page 452 Spatial data tables for the LEASE data type on page 455 Spatial data views for the LEASE data type on page 455 Spatial data tables for the SEISMIC2D data type on page 456 Spatial data views for the SEISMIC2D data type on page 457 Spatial data tables for the GEMS data type on page 462 Spatial data views for the GEMS data type on page 462
Spatial data tables for the WELLS data type

Table 7 lists the tables containing data for the WELLS data type.
Table 7: Data tables for WELLS data
Table Name
FSD_WELL_TOP
Column Names
UWI SHAPE
Data Type
Varchar2(20) Number(38) Varchar2(20) Number(38) Varchar2(20) Varchar2(30) Varchar2(20) Number(38)
Shape Type
Point
FSD_WELL_BOTTOM
UWI SHAPE
Point
FSD_WELL_DEVIATION
UWI SOURCE DIR_SRVY_ID SHAPE
Polyline with M
Revised May 2, 2005
451
Spatial data views for the WELLS data type

Table 8 lists the views containing data for the WELLS data type.
Table 8: Views for WELLS data
View Name
FSD_WELL_TOP_V
Table Name
PROJECT_SDE.FSD_WELL _TOP PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR
Column Name
SHAPE UWI CRSTATUS WELL_NAME PLOT_SYMBOL ELEVATION ELEVATION_REF TVD DEVIATION_FLAG FIELD PARENT_UWI TIE_IN_UWI RIG_NAME DATA_STATUS LOG_TVD LEASE_NO LEASE_NAME WELL_TYPE SHAPE UWI CRSTATUS WELL_NAME PLOT_SYMBOL ELEVATION ELEVATION_REF
FSD_WELL_BOTTOM_V
PROJECT_SDE.FSD_WELL _BOTTOM PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR
452
Revised May 2, 2005
View Name
Table Name
PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR PROJECT.WELL_HDR
Column Name
TVD DEVIATION_FLAG FIELD PARENT_UWI TIE_IN_UWI RIG_NAME DATA_STATUS LOG_TVD LEASE_NO LEASE_NAME WELL_TYPE SHAPE UWI SOURCE DIR_SRVY_ID SURVEY_TYPE PROCESS_FLAG COMPILE_GROUP SURVEY_COMPANY SURVEY_DATE SURVEY_MODE
FSD_WELL_DEVIATION_V
PROJECT_SDE.FSD_WELL _DEVIATION PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR
Revised May 2, 2005
453
View Name
Table Name
PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR PROJECT.WELL_DIR_SRV Y_HDR
Column Name
SURVEY_QUALITY REMARKS NORTH_REFERENCE DECLINATION_CORRECTI ON TIE_IN_DEPTH TIE_IN_X_OFFSET TIE_IN_Y_OFFSET TIE_IN_TVD CALCULATION_METHOD PROC_DATE TIE_IN_AZIMUTH TIE_IN_DEVIATION_ANG LE CUSTOM_COMP INTERP_COMP INTERP_STATUS TOOL_TYPE ELEVATION_REF
454
Revised May 2, 2005
View Name
Table Name
PROJECT.WELL_DIR_SRV Y_HDR
Column Name
OWNER
Spatial data tables for the LEASE data type

Table 9 lists the tables containing data for the LEASE data type.
Table 9: Data tables for LEASE data
Table Name
FSD_LEASE
Column Names
LEASE_ID SHAPE
Data Type
Varchar(20) Number(38)
Shape Type
Polygon
Spatial data views for the LEASE data type

Table 10 lists the views containing data for the LEASE data type.
Table 10: Views for LEASE data
View Name
FSD_LEASE_V
Table Name
PROJECT_SDE.FSD_LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE
Column Name
SHAPE LEASE_ID REF_ID LEASE_TYPE_CD PRODUCT_RGTS PROV_CD PROJ_AREA_CD LEASE_ACQN_DTE PERSP_IND GROSS_HECTARES PRICE_HA BONUS_PRICE SALE_DATE SALE_NO
Revised May 2, 2005
455
Table 10: Views for LEASE data
View Name
Table Name
PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE PROJECT.LEASE
Column Name
SALE_ENTERED RESULT_DTE RESULT_ENTERED LEASE_EXPRTN_DTE EXPRTN_STATUS LAST_MOD_DTE PLOT_DESC POLY_DIGITAL_REF
Spatial data tables for the SEISMIC2D data type

Table 11 lists the tables containing data for the SEISMIC2D data type.
Table 11: Data tables for SEISMIC2D data
Table Name
FSD_SEISMIC2D_LINES
Column Names
LINE_ID SHAPE
Data Type
Number(10) Number(38) Number(10) Number(38) Number(10) Number(6,1) Number(10) Number(38)
Shape Type
Polyline
FSD_SEISMIC2D_LINES_M
LINE_ID SHAPE
Polyline
FSD_SEISMIC2D_SP
LINE_ID SPNO PARTNO SHAPE
Point
456
Revised May 2, 2005
Spatial data views for the SEISMIC2D data type

Table 12 lists the views containing data for the SEISMIC2D data type.
Table 12: Views for SEISMIC2D data
View Name
FSD_SEISMIC2D_LINES_V
Table Name
PROJECT_SDE.FSD_SEISMI C2D_LINES PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
Column Name
SHAPE LINE_ID LINE_NAME SURVEY CDPS_PER_SHOT_POINT INITIAL_CDP FINAL_CDP INITIAL_SHOT FINAL_SHOT LOWER_LEFT_X LOWER_LEFT_Y UPPER_RIGHT_X UPPER_RIGHT_Y OPTIM_XY_ID SHOT_XY_ID SHOT_LABELS_ID SHOT_RECEIVER_ID SHOT_FOLD_ID BULK_SHIFT DATUM_METHOD DATUM_CONSTANT SHOT_DATUM_ID SHOT_DATUM_VSD VELOCITY_ID LINE_LENGTH
Revised May 2, 2005
457
View Name
Table Name
PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
Column Name
SHOT_POINT_SPACING GROUP_SHOOT PURCHASED PROPRIETARY QUALITY PROJECT XY_ASSOC SEIS_ASSOC X1 X2 X3 X4 Y1 Y2 Y3 Y4 REGULAR LINE_TYPE SOURCE SHAPE LINE_ID LINE_NAME SURVEY CDPS_PER_SHOT_POINT INITIAL_CDP FINAL_CDP INITIAL_SHOT
FSD_SEISMIC2D_LINES_M_V
PROJECT_SDE.FSD_SEISMI C2D_LINES_M PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
458
Revised May 2, 2005
View Name
Table Name
PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
Column Name
FINAL_SHOT LOWER_LEFT_X LOWER_LEFT_Y UPPER_RIGHT_X UPPER_RIGHT_Y OPTIM_XY_ID SHOT_XY_ID SHOT_LABELS_ID SHOT_RECEIVER_ID SHOT_FOLD_ID BULK_SHIFT DATUM_METHOD DATUM_CONSTANT SHOT_DATUM_ID SHOT_DATUM_VSD VELOCITY_ID LINE_LENGTH SHOT_POINT_SPACING GROUP_SHOOT PURCHASED PROPRIETARY QUALITY PROJECT XY_ASSOC SEIS_ASSOC X1 X2 X3
Revised May 2, 2005
459
View Name
Table Name
PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
Column Name
X4 Y1 Y2 Y3 Y4 REGULAR LINE_TYPE SOURCE SHAPE SPNO PARTNO LINE_ID LINE_NAME SURVEY CDPS_PER_SHOT_POINT INITIAL_CDP FINAL_CDP INITIAL_SHOT FINAL_SHOT LOWER_LEFT_X LOWER_LEFT_Y UPPER_RIGHT_X UPPER_RIGHT_Y OPTIM_XY_ID SHOT_XY_ID SHOT_LABELS_ID
FSD_SEISMIC2D_SP_V
PROJECT_SDE.FSD_SEISMI C2D_SP PROJECT_SDE.FSD_SEISMI C2D_SP PROJECT_SDE.FSD_SEISMI C2D_SP PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
460
Revised May 2, 2005
View Name
Table Name
PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR PROJECT.SEIS_LINE_HDR
Column Name
SHOT_RECEIVER_ID SHOT_FOLD_ID BULK_SHIFT DATUM_METHOD DATUM_CONSTANT SHOT_DATUM_ID SHOT_DATUM_VSD VELOCITY_ID LINE_LENGTH SHOT_POINT_SPACING GROUP_SHOOT PURCHASED PROPRIETARY QUALITY PROJECT XY_ASSOC SEIS_ASSOC X1 X2 X3 X4 Y1 Y2 Y3 Y4 REGULAR LINE_TYPE SOURCE
Revised May 2, 2005
461
Spatial data tables for the GEMS data type

Table 13 lists the tables containing data for the GEMS data type.
Table 13: Data tables for GEMS data
Table Name
FSD_GEM_POINT
Column Names
OBJECT_ID SHAPE
Data Type
Number(10) Number(38) Number(10) Number(38) Number(10) Number(38)
Shape Type
Point
FSD_GEM_LINE
OBJECT_ID SHAPE
Polyline
FSD_GEM_POLYGON
OBJECT_ID SHAPE
Polygon
Spatial data views for the GEMS data type

Views are created for each GEM object class to expose the shape and attributes of each class. The shape for all classes is stored in a single table (FSD_GEM_POINT, FSD_GEM_LINE, or FSD_GEM_POLYGON, depending on the shape type). The views consist of two tables (FSD_GEM_POINT, FSD_GEM_LINE, or FSD_GEM_POLYGON and a GEM_OBJECTS table) or three tables (if an attributes table is also used) in the following format:
FSD_<GEM_OBJECT_CLASS_NAME>_<SHAPE_TYPE>_V
where,
FSD specifies the view is for a Finder SDE extension. <GEM_OBJECT_CLASS_NAME> identifies the type of GEM object class, such as PIPELINE. <SHAPE_TYPE> identifies the shape type. The allowed types are S (symbol data from the FSD_GEM_POINT table), L (line data from the FSD_GEM_LINE table), and P (polygon data from the FSD_GEM_POLYGON table). V identifies the Finder SDE object as a view.
NOTE: The FSD_ prefix and <SHAPE_TYPE> suffix require eight character spaces. The view names are allowed a maximum of 30 characters. This leaves a maximum of 22 character spaces for the object class name.
462
Revised May 2, 2005
Table 14 lists example formats for GEM object views.

Table 14: Views for GEMS data
View Name
FSD_<GEM_OBJECT_CLASS>_S_ V
Table
<PROJECT>_SDE.FSD_GEM_POI NT <PROJECT>.GEM_OBJECTS, GEM object class attribute table
Column
SHAPE Various required attribute columns SHAPE Various required attribute columns SHAPE Various required attribute columns
FSD_<GEM_OBJECT_CLASS>_L_ V
<PROJECT>_SDE.FSD_GEM_LIN E <PROJECT>.GEM_OBJECTS, GEM object class attribute table
FSD_<GEM_OBJECT_CLASS>_P_ V
<PROJECT>_SDE.FSD_GEM_POL YGON <PROJECT>.GEM_OBJECTS, GEM object class attribute table
Table 15 lists some example views for the GEMS data type.
Table 15: Example views for GEMS data
View Name
FSD_SEIS3D_OUTLINE_P_V
Table Name
<PROJECT>_SDE.FSD_GEM_POLYGON PROJECT.SEIS_3D_HDR
Column Name
SHAPE Various required attribute columns SHAPE Various required attribute columns SHAPE Various required attribute columns SHAPE Various required attribute columns
FSD_PIPELINE_S_V
<PROJECT>_SDE.FSD_GEM_POINT <PROJECT>.PIPELINE
FSD_PIPELINE_L_V
<PROJECT>_SDE.FSD_GEM_LINE <PROJECT>.PIPELINE
FSD_PIPELINE_P_V
<PROJECT>_SDE.FSD_GEM_POLYGON <PROJECT>.PIPELINE
NOTE: 3D seismic GEM polygons have only one view. All other GEM objects have three views.
Revised May 2, 2005
463
Finder SDE account data model schema

Figure 3 illustrates how a Finder SDE account stores spatial data. Each project SDE account consists of tables for each data type and views that consist of multiple tables. See Finder SDE tables for spatial data and views on page 451 for the column listings for each table. Project Account tables
Tables WELL_HDR FSD_WELL_TOP_V WELL_DIR_SRVY_HDR Views Project SDE Account Tables FSD_WELL_TOP
FSD_WELL_BOTTOM FSD_WELL_BOTTOM_V FSD_WELL_DEVIATION
FSD_WELL_DEVIATION_V
SEIS_LINE_HDR FSD_SEISMIC2D_LINES_V
FSD_SEISMIC2D_LINES
FSD_SEISMIC2D_SP_V
FSD_SEISMIC2D_SP
LEASE
FSD_SEISMIC2D_LINES_M_V
FSD_SEISMIC2D_LINES_M
FSD_LEASE FSD_LEASE_V NOTE: There are separate views for each GEM class. FSD_SEIS_3D_OUTLINES_P_V NOTE: The same table for all GEM classes. FSD_GEM_POLYGON Example GEM attribute table PIPELINE FSD_PIPELINE_P_V FSD_GEM_POINT
SEIS_3D_HDR
FSD_PIPELINE_S_V FSD_GEM_LINE
Other GEM object classes
FSD_PIPELINE_L_V
Figure 3: Finder ArcSDE spatial storage schema
464
Revised May 2, 2005
Well and deviation data selection methods for Shape File Unloader and f2sde_transfer
The Shape File Unloader and f2sde_transfer utility support deviation data stored in project Oracle tables. They do not support deviation data stored in Finder N-lists. However, there are differences in the way the Shape File Unloader and f2sde_transfer select wells and deviation data. One of the main differences between the two features is that the method used by the f2sde_transfer utility for selecting wells is automated by setting a parameter in the WELL_HDR table. In contrast, the method used by Shape File Unloader for selecting wells uses a more manual process.
f2sde_transfer utility data selection methods

The f2sde_transfer utility uses the following methods for selecting wells and deviation data: Selecting wells The f2sde_transfer utility does not support well selection through the Finder List Assistant. The f2sde_transfer utility transfers data from wells that are marked as deviated in the WELL_HDR table (deviation_flag = 'Y'). Selecting deviation data
f2sde_transfer transfers deviation data from only those surveys that meet the following conditions:
Only one preferred survey exists for the well in the WELL_DIR_SRVY_HDR table (preferred_flag = 'Y'). If more than one survey is marked as preferred, the well is rejected and a message is written in the journal file. Entries for the preferred deviation survey exist in the WELL_DIR_SRVY_PTS table.
Shape File Unloader data selection methods

The Shape File Unloader uses the following methods for selecting wells and deviation data: Selecting wells If the Finder List Assistant is being used to select wells, only those wells selected in the list will be exported to a shapefile. All wells in the database will be exported to a shapefile if no well list is specified in the Shape File Unloader export control file.
Revised May 2, 2005
465
Selecting deviation data The Shape File Unloader does not use deviation_flag to select directional survey data for export. The Shape File Unloader will export well deviation data in the following scenarios: Only one survey is marked as preferred in the
WELL_DIR_SRVY_HDR table and there are deviation data.
Deviation data are exported to a shapefile. The wells do not contain deviation data. Directional survey data are not stored in the Finder database. A record for wells meeting this condition is stored in the shapefile without deviation data. More than one survey is marked as preferred in the WELL_DIR_SRVY_HDR table. A straight line is drawn using the base_delta_x, base_delta_y, top_delta_x, and top_delta_y columns from the WELL_HDR table and exported to a shapefile.
SDE performance tuning

This section includes information on Setting the environment for a project on page 466 Changing the grid size of a layer on page 467 Customizing layer views on page 467 Managing Finder SDE tablespaces on page 468
Setting the environment for a project

Prior to running any of the Finder SDE utilities the environment can be set for a specific Finder project. When the environment is set from the command line you do not have to specify the project name and password when running f2sde_extension or f2sde_layer. Use the following steps to set the environment. 1. Open a Finder Xterm window. 2. Enter the following to set the project environment:
% setenv PROJECT_NAME <project_name>
3. Enter the password for the project:

% setenv PROJECT_PASSWORD <password>
466
Revised May 2, 2005
Changing the grid size of a layer

The grid size for layers that have been defined for a Finder SDE account can be changed at any time by running the ArcSDE sdelayer command. More information about this command can be found in the ESRI ArcSDE documentation. Example syntax:
sdelayer -o alter -l <layer_name> -g <grid_size1>, <grid_size2>, <grid_size3> -s <sde_server_name> -i <sde_server_port_number> -u <sde_account_name> -p <sde_account_password>
where,
sdelayer is the name of the ArcSDE command. -o alter is the parameter that specifies a change operation for
the layer.
-l <layer_name> is the parameter that specifies the name of
the layer.
-g <grid_size1>, <grid_size2>, <grid_size3> is the
parameter that specifies the grid size. Typically, only one grid size is specified (e.g., a single number such as 10), but multiple grid sizes can be listed.
-s <sde_server_name> is the parameter that specifies the SDE server host name or IP address. -i <sde_server_port_number> is the parameter that specifies
the port number for the SDE server.

-u <sde_account_name> is the parameter that specifies the name of the project SDE account. -p <sde_account_password> is the parameter that specifies the password for the project SDE account.
Customizing layer views

Finder SDE includes a set of standard view definitions, as described in Finder SDE data model on page 447, but these views can be customized for site-specific requirements. The views for the WELLS, LEASE, and SESMIC2D data types can be used with their default settings. The default views for the GEMS data type will need to be modified because during the initial view creation, the f2sde_layer utility creates a default view with a SHAPE column only. The f2sde_layer utility automatically adds three views (representing symbol/point, line, and polygon) for each GEM class in the project, if no view definition exists for that class in ESI.FINDER_SDE_VIEWS. These views can be customized to add more attributes or deleted if not needed.
Revised May 2, 2005
467
To customize a view, the view definition must be modified in the ESI.FINDER_SDE_VIEWS table. The content of this table can be displayed and modified using the Finder SDE Views form. This form can be invoked as follows:
% oform finder_sde_views esi/<esi_password>
Modify values in one or more of the following columns to customize the view settings:
Columns
Adds or removes attributes. Do not remove the SHAPE attribute. Column names should be prefixed by full table names because table aliases are not supported by SDE.
Tables
Adds or removes tables. Do not use aliases (e.g., WELL_HDR a) because table aliases are not supported by SDE.
Where_clause
Modifies a join or filter condition.

Line_no
Creates a new line and increments the line number if any of the above exceeds 2000 characters. NOTE: Specify, in a new line, the data type name and fill only columns that continue from the previous line. For example, if the value of the columns exceeds 2000 characters, add the additional characters to Columns for the next line and leave Tables and Where_clause empty. Values in Columns, Tables, and Where_clause in multi-line columns are concatenated to create the views.
Managing Finder SDE tablespaces

The tablespace for a project SDE account can be managed with the f2sde_layer -k parameter. This parameter can be used to specify the SDE configuration keyword. Configuration keywords can be created that specify the tablespace where each layer and the layer objects are to be stored. The configuration keywords can be used to specify a tablespace for the business table, and F and S tables. These keywords allow the SDE extension tablespaces to be efficiently managed. Without configuration keywords, all objects are stored in the default tablespace specified with the f2sde_extension utility when the SDE account is created. ArcSDE commands must be used to create the configuration keywords before using them with the f2sde_layer utility.
468
Revised May 2, 2005
Note that tablespaces for Finder SDE accounts must be created before an SDE account is created. See the ESRI ArcSDE documentation for detailed information on creating configuration keywords.
Work-arounds for known problems

This section discusses the following: Creating GEM class views on page 469 Using Relate in Arc Map on page 469 Viewing Finder SDE layers in SmartView on page 470 Defining a new data area for a project SDE extension on page 471
Creating GEM class views

If a GEM class name contains any invalid characters for the Oracle view name, such as "-", "&", and so forth, the automatic GEM view creation will fail. To create a GEM view, you must modify the view name, using the finder_sde_views Oracle form, to remove the invalid characters and rerun the f2sde_layer utility.
Using Relate in Arc Map

In ArcMap, Relate is used to link layers to database tables when a one-tomany relationship exists between them. For example, to find the number and types of logs for a well, the layers must be linked to a key in the WELL_LOG_CURVE_HDR table. Wells have more than one log, so Relate must be used to link layers to the WELL_LOG_CURVE_HDR table. To view related data in ArcMap 8.x from the attributes table, the table you are relating must have a NOT NULL, INDEXED, UNIQUE, or LONG-INT field. In the WELL_LOG_CURVE_HDR table, for example, and in most of the Finder tables, these fields do not exist. Hence, a relate operation to a Finder table will not work. The only work-around for this problem is to export the required table to a .dbf file and relate the data outside of SDE. For example, if you save WELL_LOG_CURVE_HDR data to a local .dbf file, the relate operation will work.
Revised May 2, 2005
469
Viewing Finder SDE layers in SmartView

The Add Data window in SmartView displays all the tables and views in the Finder database that the user has privileges to select. SmartView can take a considerable amount of time to display all these tables, whereas the user may want to display only those tables comprising the layers for a Finder SDE extension account. The tables that display in the Add Data window can be restricted by removing select privileges from the tables and views using SQL*Plus and then using the SDE sdetable command to hide or make visible selected tables. The two procedures below provide an overview of this process. For more detailed information, see the SQL*Plus and SDE documentation shipped, respectively, by Oracle and ESRI. NOTE: Before executing the SDE commands, perform the following: 1. Connect to the server where SDE is running. 2. Open a Finder Xterm. 3. Set the following environment variables:
SDEHOME ESRI_ARCSDE_LICENSE_FILE
4. Add $SDEHOME/bin to $PATH. 5. Add $SDEHOME/lib to $LD_LIBRARY_PATH. Procedure 1: Use SQL*Plus to remove the select privileges from the tables and views that you do not want to display in the SmartView Add Data window. 1. Connect to SQL*Plus using the table owner account. Example:
% sqlplus spider/spider
2. Revoke select privileges for the table or view, using the following syntax:
revoke select on <table_name> from <user_name>
Example: % revoke select on well_hdr from install
470
Revised May 2, 2005
Procedure 2: To hide a table or view, use sdetable as follows:

sdetable -o register -t <table_name> -H HIDDEN [-i <sde_port_number>] [-s <sde_server_name>] -u <DB_User_name> [-p <DB_User_password>]
The following examples illustrate sdetable usage for different accounts and tables. To hide the SPIDER.WELL_HDR table, use the following syntax:
sdetable -o register -t WELL_HDR -H HIDDEN -i 5152 -s sc-borg -u spider -p spider
To hide the CODES.BUSINESS_ASSOC table, use the following syntax:

sdetable -o register -t BUSINESS_ASSOC -H HIDDEN -i 5152 -s sc-borg -u codes -p codes
To hide the ESI.FINDER_ACCOUNTS table, use the following syntax:

sdetable -o register -t FINDER_ACCOUNTS -H HIDDEN -i 5152 -s sc-borg -u esi -p esi
NOTE: To unhide a table or view, use the following command:

sdetable -o alter_reg -t <table> -H VISIBLE [-i <sde_port_number>] [-s <sde_server_name>] -u <DB_User_name> [-p <DB_User_password>]
Defining a new data area for a project SDE extension

When an administrator executes the f2sde_transfer utility, the following error message may display:
convertToXSystem.... x = <coordinate value> Errors encountered during insert. Not all wells may have been transferred Please see logfile for details
This error message displays when the data being transferred are outside the SDE area. Some objects (wells, seismic 2D, leases, and GEMs) are out of the data area defined for the SDE projection when the SDE extension account was created. Only those objects that are out of the data area have not been copied. More details about the objects that have been rejected can be found in the f2sde_transfer log file. Using the object list provided in the utility log file, check the coordinate point values for the objects in the Finder project. If these values are correct, the SDE data area needs to be changed. However, Finder SDE does not
Revised May 2, 2005
471
allow changes to be made to the SDE data area. To resolve this problem, use the f2sde_extension utility to create a new SDE extension account for the project, as follows: 1. Drop the Finder SDE extension account. 2. Create the SDE extension account and define the new SDE data area. See f2sde_transfer utility on page 441 for detailed information about using the f2sde_extension utility.
472
Revised May 2, 2005
Finder 9.4
Database Administrators Reference
0505021547/fgs 9.4
AF
Copyright Notice
Copyright 1998-2005 Schlumberger. All rights reserved. No part of this document may be reproduced, stored in an information retrieval system, or translated or retransmitted in any form or by any means, electronic or mechanical, including photocopying and recording, without the prior written permission of the copyright owner.
Trademarks
Schlumberger marks which may appear in this document include, but are not limited to AssetDB, Charisma, Finder, GeoFrame, Geonet, LogDB, ProductionDB, SeisDB, SmartMap, SmartSection, and LiveQuest. All other company or product names mentioned are used for identification purposes only and may be trademarks of their respective owners.
0505021548/fgs 9.4
D R AF T
0505021548/fgs 9.4
D
R
AF

Finder Database Admin

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Finder Database Admin

Uploaded by

Copyright:

Available Formats

Finder Database Administrators Reference

Finder Logical Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Setting the Default Date Format in Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 2: Account Management Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Account Management Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Using the Analyst or Projects Defaults forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Using SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

The Vector or N-List Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14