CONTENTS

  Title Page

  Copyright Page

  Preface

  Technical Changes and New Features

  Part I   Understanding DATATRIEVE

  1      Understanding DATATRIEVE

  1.1     Starting a DATATRIEVE Session
    1.1.1      Invoking DATATRIEVE with the Symbol DTR32
    1.1.2      Using the DCL DATATRIEVE Command

  1.2     Ending Your DATATRIEVE Session

  1.3     Writing a DATATRIEVE Session to a Log File

  1.4     DATATRIEVE Concepts and Terminology
    1.4.1      Databases
    1.4.2      DATATRIEVE Domains
    1.4.3      CDD/Plus Dictionary System
    1.4.4      Commands and Statements
    1.4.5      Procedures
    1.4.6      DATATRIEVE Command Files
    1.4.7      DATATRIEVE View Domains
    1.4.8      DATATRIEVE Tables
    1.4.9      DATATRIEVE Collections
    1.4.10     Distributed Data

  1.5     What DATATRIEVE Can Do for the Programmer

  1.6     The Sample Domains, Records, and Data Files

  1.7     Using SET Commands to Control Output
    1.7.1      Changing the Columns-Page Setting
      1.7.1.1      Increasing the Columns-Page Setting
      1.7.1.2      Decreasing the Columns-Page Setting
    1.7.2      Using SET ABORT
    1.7.3      Using SET PROMPT
    1.7.4      Using SET SEARCH
    1.7.5      Using SET FORM
    1.7.6      Using SET VERIFY
    1.7.7      Using SET SEMICOLON
    1.7.8      Using SET LOCK_WAIT
    1.7.9      Using SET APPLICATION_KEYPAD

  1.8     Controlling the Input of Dates and Currency

  1.9     Issuing DATATRIEVE Commands at the DCL Level

  1.10    Using a DATATRIEVE Startup Command File

  Part II   Manipulating Data

  2      Writing Record Selection Expressions

  2.1     Displaying All the Records in a Domain

  2.2     Limiting the Number of Records in the Record Stream

  2.3     Identifying the Records That Meet a Test
    2.3.1      Comparing Records by Pattern Recognition
    2.3.2      Grouping Records When Values Fall Within a Range
    2.3.3      Grouping Records Based on a MISSING VALUE Clause
    2.3.4      Grouping Records by Reference to a Table
    2.3.5      Summary of the Relational Operators
    2.3.6      Setting Up Multiple Tests with Compound Booleans

  2.4     Joining Records from Two or More Sources
    2.4.1      Using CROSS to Combine Two Domains
    2.4.2      Joining Records from Collections Based on the Same Domain
    2.4.3      Using CROSS to Cross a Domain with Itself

  2.5     Finding the Unique Field Values in the Record Stream

  2.6     Sorting the Record Stream by Field Values

  3      Entering New Data

  3.1     Using the STORE Statement

  3.2     The Effect of TAB on Prompts from STORE Statements

  3.3     Using Direct Assignments

  3.4     Using Prompting Expressions in STORE Statements

  4      Modifying Data

  4.1     Modifying Records in the CURRENT Collection
    4.1.1      Modifying a Selected Record in the CURRENT Collection
    4.1.2      Modifying All Records in the CURRENT Collection

  4.2     Modifying All Records in a Record Selection Expression
    4.2.1      Modifying Records Controlled by a FOR Statement
    4.2.2      Including the RSE Within the MODIFY Statement

  4.3     Common Context Errors
    4.3.1      Modifying All Records Rather Than Just the Selected Record
    4.3.2      Modifying the Wrong Selected Record
    4.3.3      Modifying Records in the Wrong RSE

  4.4     Using DATATRIEVE Prompts

  4.5     Ensuring Valid Values

  5      Using View Domains

  5.1     Views Using Subsets of Records

  5.2     Views Using Subsets of Fields

  5.3     Views Using More Than One Domain

  5.4     Advantages and Disadvantages of Using Views

  6      Using Hierarchies

  6.1     Defining Records with Repeating Fields
    6.1.1      Defining Lists with a Fixed Number of Occurrences
    6.1.2      Defining Lists with a Variable Number of Occurrences
    6.1.3      Defining Sublists to Nest Lists Within Lists

  6.2     Retrieving Values from Repeating Fields
    6.2.1      Retrieving Repeating Field Values with FIND and SELECT
    6.2.2      Retrieving Repeating Field Values with Nested FOR Loops
    6.2.3      Retrieving Repeating Field Values with Inner Print Lists
    6.2.4      Retrieving Repeating Field Values with the Context Searcher
    6.2.5      Retrieving Repeating Field Values by Flattening Hierarchies
      6.2.5.1      Using the CROSS Clause to Flatten Hierarchies
      6.2.5.2      Using Inner Print Lists to Flatten Hierarchies
      6.2.5.3      Using Nested FOR Statements to Flatten Hierarchies

  6.3     Modifying Values Stored in Repeating Fields
    6.3.1      Modifying Repeating Field Values with FIND and SELECT
    6.3.2      Modifying Repeating Field Values with FOR and MODIFY
    6.3.3      Changing the Length of a Variable-Length List

  6.4     Creating Hierarchies with Multiple RSEs
    6.4.1      Creating Hierarchies with View Domains
    6.4.2      Using Inner Print Lists to Create Dynamic Hierarchies
    6.4.3      Using Nested FOR Statements to Create Dynamic Hierarchies

  Part III   Programming in DATATRIEVE

  7      Using DATATRIEVE Procedures

  7.1     Defining a Procedure

  7.2     Invoking a Procedure

  7.3     Contents of a Procedure
    7.3.1      Commands and Statements
    7.3.2      Arguments and Clauses
    7.3.3      Comments

  7.4     Editing a Procedure

  7.5     Troubleshooting Procedures

  7.6     Aborting Procedures

  7.7     Sample Procedures

  7.8     How to Nest Procedures Within Procedures

  7.9     Using a Procedure in a Compound Statement

  7.10    Generalizing Procedures

  7.11    Maintaining Procedures
    7.11.1     Displaying Procedure Names
    7.11.2     Displaying Procedures
    7.11.3     Deleting Procedures

  7.12    Protecting Procedures

  8      Using Command Files

  8.1     Using DATATRIEVE Command Files
    8.1.1      Creating a DATATRIEVE Command File
      8.1.1.1      ADT, EDIT, and SET GUIDE in Command Files
      8.1.1.2      Comments in Command Files
    8.1.2      Invoking a Command File
      8.1.2.1      Invoking a Command File from Within DATATRIEVE
      8.1.2.2      Invoking a Command File Outside of DATATRIEVE
    8.1.3      Sample DATATRIEVE Command File
    8.1.4      Invoking a Command File from a Procedure
    8.1.5      Invoking a Command File from Another Command File
    8.1.6      Aborting Command Files
    8.1.7      Maintaining Command Files
    8.1.8      Protecting Command Files

  8.2     Using VMS Command Files
    8.2.1      Reassigning SYS$INPUT in Command Files That Require Interactive Input
    8.2.2      Command Files with an Invalid CDD$DEFAULT Can Damage the Dictionary

  9      Using DATATRIEVE Variables

  9.1     Declaring Variables

  9.2     Local Variables

  9.3     Global Variables

  9.4     Using Variables to Assign Values to Fields

  9.5     Changing the Value of a Variable

  9.6     Using Context Variables

  Part IV   Optimizing DATATRIEVE

  10     Restructuring Data

  10.1    A Sample Domain

  10.2    Adding Fields to a Record Definition

  10.3    Entering Data in the New File

  10.4    Creating Record Subsets

  10.5    Combining Data from Two or More Domains

  10.6    Using the Alias Clause to Restructure a Domain

  10.7    Changing the Organization of a Data File

  10.8    Further Examples of Restructuring Domains

  10.9    Better Data Organization

  11     Designing Better Records

  11.1    Flat Records and Hierarchical Records
    11.1.1     Restructuring a Hierarchical File to a Flat File
    11.1.2     Defining Several Smaller Related Records
    11.1.3     Restructuring a Large Record into Several Smaller Records
    11.1.4     Creating a Hierarchical View of Flat Records

  11.2    Choose Keys for Optimization

  11.3    Using Tables

  11.4    Using COMPUTED BY Fields
    11.4.1     Computing Age with a COMPUTED BY Field
    11.4.2     Using COMPUTED BY Fields for Quarterly Summaries

  12     Improving DATATRIEVE Performance

  12.1    Choosing a File Organization
    12.1.1     Choosing Primary and Alternate Keys

  12.2    Designing Files
    12.2.1     Using EDIT/FDL to Design Your File
      12.2.1.1     Invoking EDIT/FDL
      12.2.1.2     Questions EDIT/FDL Asks in the Preliminary Phase
      12.2.1.3     Using the Line Graph to Select Bucket Size
      12.2.1.4     Questions EDIT/FDL Asks During Finish Design Phase
    12.2.2     Creating the Data File
    12.2.3     Redesign and Maintenance
      12.2.3.1     Calculating a Fill Factor
      12.2.3.2     Adding Data to the File

  12.3    Using the OPTIMIZE Qualifier to Improve Performance

  12.4    Choosing Optimal Queries
    12.4.1     Using EQUAL Rather Than CONTAINING
    12.4.2     Using STARTING WITH Rather Than CONTAINING
    12.4.3     Using Domains Rather Than Collections in an RSE
    12.4.4     Using the CROSS Clause and Nested FOR Loops
    12.4.5     Choosing Domains or Collections as Record Sources
    12.4.6     Choosing the Order of Domain Names in the CROSS Clause
    12.4.7     Order of Domains in Nested FOR Loops
    12.4.8     Nested FOR Loops Followed by a Conditional Statement

  12.5    Timing Procedures to Improve Efficiency

  12.6    DATATRIEVE Evaluation of Compound Boolean Expressions

  12.7    Summary of Rules

  Part V   The DATATRIEVE Interfaces

  13     Using DATATRIEVE with DECwindows

  13.1    Preparing to Use DATATRIEVE in a DECwindows Environment

  13.2    Invoking DATATRIEVE in a DECwindows Environment

  13.3    The DATATRIEVE Main Window and Menus
    13.3.1     The File Menu
      13.3.1.1     The Invoke ( @ )...  Item
      13.3.1.2     The Open Log ...  and Close Log Items
      13.3.1.3     The Exit Item
    13.3.2     The Edit Menu
    13.3.3     The Dictionary Menu
      13.3.3.1     The File Menu
      13.3.3.2     The View Menu
      13.3.3.3     The Actions Menu
    13.3.4     The Show Menu
      13.3.4.1     The Dictionary Item
      13.3.4.2     The Ready Sources Item
      13.3.4.3     The Fields Item
      13.3.4.4     The Fields For...  Item
      13.3.4.5     The Current Item
      13.3.4.6     The Collections Item
      13.3.4.7     The Collection Name...  Item
      13.3.4.8     The Variables Item
      13.3.4.9     The Sets Item
      13.3.4.10    The Dictionary Elements Item
    13.3.5     The Setup Menu
      13.3.5.1     The Abort Item
      13.3.5.2     The Lock_Wait Item
      13.3.5.3     The Prompt Item
      13.3.5.4     The Search Item
      13.3.5.5     The Verify Item
      13.3.5.6     The Columns_Page...  Item
    13.3.6     The Utilities Menu
      13.3.6.1     The DATATRIEVE Application Designer (ADT) Item
      13.3.6.2     The Guide Mode Item

  13.4    Using DATATRIEVE Help in a DECwindows Environment

  13.5    Acknowledging DATATRIEVE Messages in DECwindows

  13.6    The Work-in-Progress Box

  13.7    Editing in DATATRIEVE in a DECwindows Environment

  13.8    Storing, Modifying, or Entering Data in a DECwindows Environment

  13.9    Using DATATRIEVE Graphics in a DECwindows Environment

  13.10  Using ADT and Guide Mode in a DECwindows Environment

  13.11  Using TDMS and FMS Forms with DATATRIEVE in a DECwindows Environment

  13.12  Displaying DATATRIEVE in a DECwindows Environment on a Remote Node

  13.13  Using Callable DATATRIEVE in a DECwindows Environment

  13.14  Specifying the Size of Your DATATRIEVE Scroll Region

  13.15  Restrictions Using DATATRIEVE in a DECwindows Environment
    13.15.1    Restriction Using FN$SPAWN and FN$DCL
    13.15.2    Restriction on Customizing DECterm Windows Created by DATATRIEVE
    13.15.3    Restriction on Using SMG Keypad Definitions

  13.16  Exiting DATATRIEVE in DECwindows

  14     Using Forms with DATATRIEVE

  14.1    Associating a Form with a Domain
    14.1.1     The FORM IS Clause
    14.1.2     The DISPLAY_FORM Statement

  14.2    Defining Forms
    14.2.1     Defining Form Field Names
    14.2.2     Defining Data Type and Length of Form Fields
      14.2.2.1     Numeric Fields with Decimal Points or Signs
      14.2.2.2     Usage DATE Fields
    14.2.3     Specifying User Entry and Validation Criteria
    14.2.4     Defining Multiple Screen Forms and Forms with Scrolled Areas
    14.2.5     Using Default Values
    14.2.6     Defining Forms for Domains That Contain Repeating Fields

  14.3    Inserting Forms in Library Files
    14.3.1     Inserting Forms in TDMS Library Files
    14.3.2     Inserting Forms in an FMS Library

  14.4    Using Forms to Display and Collect Data
    14.4.1     Enabling and Disabling Form Use
    14.4.2     Displaying Data with Forms
    14.4.3     Storing Data with Forms
      14.4.3.1     Storing Data in Hierarchical Records with Forms
    14.4.4     Modifying Data with Forms
      14.4.4.1     Modifying Data in Hierarchical Records with Forms
    14.4.5     Handling Numeric Data

  14.5    Using TDMS and FMS Forms with DATATRIEVE in a DECwindows Environment

  14.6    Restrictions on Using Forms
    14.6.1     DATATRIEVE and FMS
    14.6.2     DATATRIEVE Command Files and Forms Products
    14.6.3     Modifying Data Using View Domains and FORM IS
    14.6.4     Special Graphics Characters in Forms

  15     Using DATATRIEVE with VAX DBMS

  15.1    Advantages of Using DATATRIEVE

  15.2    Defining a Database:  The DEFINE DATABASE Command

  15.3    Accessing the Database
    15.3.1     Readying an Entire Database Directly
    15.3.2     Defining and Readying VAX DBMS Domains
    15.3.3     Results of the READY Command
      15.3.3.1     The SHOW FIELDS Command
      15.3.3.2     The SHOW SETS Command

  15.4    Forming a DATATRIEVE Query

  15.5    Forming a DATATRIEVE/VAX DBMS Query
    15.5.1     Forming a DATATRIEVE Collection of VAX DBMS Records
      15.5.1.1     Using the FIND Statement
      15.5.1.2     Using the SELECT Statement
    15.5.2     Forming a Record Stream of VAX DBMS Records

  15.6    Forming a DATATRIEVE/VAX DBMS Query of Data Related by Sets
    15.6.1     Forming Collections of VAX DBMS Set Data
    15.6.2     Forming Record Streams of VAX DBMS Set Data
    15.6.3     Using OWNER and MEMBER Clauses to Identify Sets
      15.6.3.1     The MEMBER Clause
      15.6.3.2     The OWNER Clause
    15.6.4     Using the SET SEARCH Command to Access Sets

  15.7    Finding Data from Two or More Domains
    15.7.1     Walking the Sets
    15.7.2     Using the CROSS Clause
    15.7.3     Using View Domains
      15.7.3.1     Hierarchical Views
      15.7.3.2     Flat Views

  15.8    Sample Procedures Using VAX DBMS Domains

  15.9    Modifying Individual Fields in a Record

  15.10  Storing VAX DBMS Records and Modifying Sets
    15.10.1    Storing and Connecting Records
      15.10.1.1    Automatic Insertion
      15.10.1.2    Manual Insertion
    15.10.2    Erasing, Disconnecting, and Reconnecting Records with Sets
      15.10.2.1    Erasing VAX DBMS Records
      15.10.2.2    Disconnecting and Reconnecting VAX DBMS Records from Sets
      15.10.2.3    Disconnecting and Connecting VAX DBMS Records from Sets
    15.10.3    Summary of Membership Characteristics
    15.10.4    Writing Changes to the Database

  15.11  Optimizing Performance

  16     Using DATATRIEVE with Rdb/VMS, Rdb/ELN, or VIDA

  16.1    Getting Started with DATATRIEVE and Relational Databases

  16.2    Defining the Database
    16.2.1     Defining an Rdb/VMS Database in DATATRIEVE
    16.2.2     Defining an Rdb/ELN Database in DATATRIEVE
    16.2.3     Defining a VIDA Database in DATATRIEVE

  16.3    Accessing the Database
    16.3.1     Readying a Relational Database Directly
      16.3.1.1     Access Modes and Options
      16.3.1.2     Consistency Options
      16.3.1.3     Examples
    16.3.2     Defining and Readying Relational Domains

  16.4    Using Views
    16.4.1     Creating Rdb/VMS and Rdb/ELN Views
    16.4.2     Defining and Using DATATRIEVE View Domains

  16.5    Displaying Information About Readied Relations and Domains

  16.6    Ending Access to Domains, Relations, and Views

  16.7    Storing and Maintaining Data in an Rdb/VMS or Rdb/ELN Database
    16.7.1     Using the COMMIT Statement
    16.7.2     Using the ROLLBACK Statement

  16.8    Querying the Database, Writing Reports, and Using Collections

  16.9    Using the Rdb/VMS or Rdb/ELN Segmented String Data Type in DATATRIEVE
    16.9.1     Defining Segmented String Fields in Rdb/VMS or Rdb/ELN
    16.9.2     Displaying Segmented String Fields in DATATRIEVE
    16.9.3     Storing and Modifying Segmented String Fields in DATATRIEVE
    16.9.4     Restrictions and Usage Notes for Segmented String Fields

  16.10  Modifying the Structure of Relational Sources

  16.11  Ensuring Data Security

  16.12  Validating Data for Rdb/VMS or Rdb/ELN Relations and Domains

  16.13  Optimizing Performance

  17     Accessing Remote Data

  17.1    Defining Network Domains and Accessing Remote Domains
    17.1.1     Defining Network Domains
    17.1.2     Accessing Remote Domains
      17.1.2.1     Readying a Network Domain
      17.1.2.2     Readying a Remote Domain Directly
    17.1.3     Results of Accessing Remote Domains
    17.1.4     Restrictions on Using Remote Domains
    17.1.5     Accessing IBM Data from a VAX

  A   Name Recognition and Single Record Context

  A.1     Establishing the Context for Name Recognition
    A.1.1      The Right Context Stack
      A.1.1.1      The Content of a Context Block
      A.1.1.2      Global Variables
      A.1.1.3      Collections
      A.1.1.4      Record Streams
      A.1.1.5      Local Variables
      A.1.1.6      VERIFY Clause in the STORE Statement
      A.1.1.7      VALID IF Clause in a Record Definition
    A.1.2      Using Context Variables and Qualified Field Names
      A.1.2.1      Context Variables as Field Name Qualifiers
      A.1.2.2      Other Field Name Qualifiers
      A.1.2.3      The Effect of the CROSS Clause on Name Recognition
    A.1.3      The Left Context Stack for Assignment Statements

  A.2     Single Record Context
    A.2.1      The SELECT Statement and the Single Record Context
    A.2.2      The CURRENT Collection as Target Record Stream
    A.2.3      The OF rse Clause and Target Record Streams
    A.2.4      FOR Statements and Target Record Streams

  B   Sample Database Definitions and Procedures

  B.1     RMS Data Definitions and Procedures

  B.2     VAX DBMS Data Definitions and Procedures

  B.3     Rdb/VMS Data Definitions and Procedures

  C   DATATRIEVE Restrictions and Usage Notes

  C.1     VAX DATATRIEVE Usage and VMS Disk Quota Considerations

  C.2     Restriction on Concatenating Double-Precision Numbers

  C.3     Errors During STORE and MODIFY Statement Execution

  C.4     Restriction on Missing Values and Default Values

  C.5     Restriction on Modifying Facility-Specific Definitions in the Dictionary

  C.6     Spurious Divide-by-Zero Errors

  C.7     Command Files or Editing Commands in Procedures Can Execute Out of Sequence

  C.8     Interactive Users Can Set Stack Size

  C.9     Clarification About Using Prompting Value Expressions

  EXAMPLES

  6-1        The FAMILY Record Definition

  6-2        The Hierarchical Records in FAMILIES

  6-3        PRINT Statement with Inner Print List

  7-1        Sample Procedure Using the Report Writer

  8-1        Sample Command File Using the Report Writer

  FIGURES

  6-1        A Flat Record:  YACHT

  6-2        Structure of a Hierarchical Record

  11-1       Structure of a Hierarchical Record

  11-2       The Structure of a Flat Record

  11-3       Joining FOLKS and CHILDREN with CROSS

  11-4       Structure of CURRENT_REC

  12-1       Flat File Structure

  12-2       A File with Two Levels of Index

  13-1       DATATRIEVE Main Application Window

  13-2       The File Menu

  13-3       The Invoke ( @ )...  Dialog Box

  13-4       The Open Log ...  Dialog Box

  13-5       The Edit Menu

  13-6       The Dictionary Menu

  13-7       DATATRIEVE Dictionary Navigator Window

  13-8       The DATATRIEVE Dictionary Navigator File Menu

  13-9       The View Menu

  13-10      The Effect of the Expand Item

  13-11      Effect of the Expand Recursive Item

  13-12      The Effect of the Collapse Item

  13-13      The Set Root Dialog Box

  13-14      The Display Mode Submenu

  13-15      Sample of a Tree Format Display

  13-16      The Separate Navigation Window

  13-17      The Actions Menu

  13-18      DATATRIEVE Show Window

  13-19      The Ready...  Item Dialog Box

  13-20      The Extract...  Action Dialog Box

  13-21      The Show Menu

  13-22      The Fields For...  Item

  13-23      The Collection Name...  Item Dialog Box

  13-24      The Dictionary Elements Submenu

  13-25      The Setup Menu

  13-26      The Columns_Page Dialog Box

  13-27      The Utilities Menu

  13-28      Message Dialog Box

  13-29      Work-in-Progress Box

  13-30      Prompt Dialog Box

  15-1       VAX DBMS Set CONSISTS_OF

  15-2       Single Set Occurrence

  15-3       The Parts of an RSE

  15-4       Set Relationships in Sample VAX DBMS Database

  15-5       VAX DBMS Set Relating Three Domains

  15-6       VAX DBMS Set CLASS_PART

  16-1       Sample Rdb/VMS Relation

  16-2       Sample Rdb/VMS Database

  A-1        Duplicate Field Names in YACHTS and OWNERS

  TABLES

  1-1        Defining the Logical Name DTR$DATE_INPUT

  1-2        Currency Symbols

  2-1        Conditional Comparisons for an RSE

  12-1       DATATRIEVE Priority in Choosing Keys

  13-1       Text Selection Hierarchy

  14-1       Matching Form Field Definitions to Numeric Record Fields

  14-2       Corresponding Fields in a Domain and a Form

  14-3       Corresponding Fields in the Form PERSON and the Domain PERSONNEL

  14-4       Modifying Data in Some Fields of a Form and a Domain

  15-1       Effect of Insertion, Retention, and Database Operations on Target Record

  15-2       Effect of Insertion, Retention, and Database Operations on Member