CONTENTS Title Page Copyright Page Preface Technical Changes and New Features 1 Introduction to Programming and Customizing 1.1 Writing Programs That Call DATATRIEVE 1.1.1 How Writing Calling Programs Extends DATATRIEVE 1.1.2 How DATATRIEVE Extends Programming Languages 1.2 Customizing DATATRIEVE 2 Writing Programs That Call VAX DATATRIEVE 2.1 Overview of DATATRIEVE Programming Calls 2.1.1 Declare the DATATRIEVE Access Block (DAB) 2.1.2 Initialize the Call Interface 2.1.3 Issue DATATRIEVE Commands and Statements 2.1.4 Closing the DATATRIEVE Interface 2.1.5 Compiling and Linking DATATRIEVE Programs 2.2 DATATRIEVE Stallpoints-Transfer of Control 2.3 The DATATRIEVE Access Block 2.3.1 DAB$L_CONDITION-Condition Codes 2.3.2 Message Buffers 2.3.2.1 Messages DATATRIEVE Stores in the Message Buffer 2.3.2.2 Messages DATATRIEVE Stores in the Auxiliary Message Buffer 2.3.3 DAB$W_STATE-Stallpoint Information 2.3.4 DAB$W_REC_LEN-Record Lengths 2.3.5 Input/Output Channels 2.3.6 DAB$L_OPTIONS-Initial Options 2.3.7 User-Defined Keyword Information 2.4 Using the DATATRIEVE Call Interface 2.4.1 Command Processing 2.4.2 Reading and Storing Records 2.4.3 Defining Your Own Keywords 2.4.4 Getting Information About DATATRIEVE Objects 2.4.5 Writing Data to a Log File 2.4.6 Handling Errors 2.4.7 Debugging Your Program 2.5 Sample Programs 3 Sample FORTRAN Programs 3.1 Creating an End-User Interface to DATATRIEVE 3.1.1 The Main Program: MENU 3.1.2 The Subroutine ESTABLISH 3.1.3 The Subroutine DISPLAY 3.1.4 The Subroutine SORT 3.1.5 The Subroutine MODIFY 3.1.6 The Subroutine REPORT 3.1.7 The Subroutine STORE 3.1.8 The Subroutine CHOOSE 3.2 Creating a User-Defined Keyword 3.2.1 The Main Program: CORRELATE 3.2.2 The Subroutine PARSE 3.2.3 The Subroutine CALCULATE 4 Sample COBOL Programs 4.1 Creating an End-User Interface to DATATRIEVE 4.2 A Sample Payroll Application 4.3 A Sample Update Application 5 Sample BASIC Programs 5.1 Formatting a Report 5.2 Calculating a Linear Regression Equation Part I Reference Section 6 DATATRIEVE Call Reference 6.1 DTR$COMMAND 6.2 DTR$CONTINUE 6.3 DTR$CREATE_UDK 6.4 DTR$DTR 6.5 DTR$END_UDK 6.6 DTR$FINISH 6.7 DTR$FINISH_WINDOWS 6.8 DTR$GET_PORT 6.9 DTR$GET_STRING 6.10 DTR$INFO 6.11 DTR$INIT 6.12 DTR$LOOKUP 6.13 DTR$PORT_EOF 6.14 DTR$PRINT_DAB 6.15 DTR$PUT_OUTPUT 6.16 DTR$PUT_PORT 6.17 DTR$PUT_VALUE 6.18 DTR$UNWIND 6.19 DTR$WINDOW_MSG 6.20 DTR$WINDOW_OUTPUT 6.21 DTR$WINDOWS 7 Adding Functions to DATATRIEVE 7.1 Using DATATRIEVE Functions 7.2 DATATRIEVE Functions and External Procedures 7.3 How to Add Functions to DATATRIEVE 7.3.1 Write and Compile Your Procedures 7.3.2 Insert the Procedure Object Files into the Object Library 7.3.3 Add the Function Definitions to DTRFND.MAR 7.3.3.1 The Format of a Function Definition 7.3.3.2 Sample Function Definitions 7.3.4 Assemble and Debug DTRFND 7.3.5 Replace DTRFNDxx.MAR in the Object Library 7.3.6 Relink the DATATRIEVE Shareable Image 8 Customizing DATATRIEVE Help Text 8.1 How to Change Help Text 8.1.1 Copy the DATATRIEVE Help Library File 8.1.2 Extract the Help Modules You Want to Change 8.1.3 Edit the Extracted Help Text 8.1.3.1 The Structure of Help Text Files 8.1.3.2 Changing a Help Text File 8.1.4 Replace the Changed Text in DTRHELP.HLB 8.1.5 Replace the Old Help Library File with the New One 8.2 How to Create New Help Text 9 Customizing DATATRIEVE Messages 9.1 DATATRIEVE Messages 9.1.1 DATATRIEVE Messages and the Call Interface 9.1.2 Messages in Interactive DATATRIEVE 9.2 How to Change DATATRIEVE Messages 9.2.1 Copy the Message Source File 9.2.2 Edit the Message Source File 9.2.2.1 Structure of the Message Source File 9.2.2.2 Changing the Message Text 9.2.2.3 Using FAO Directives to Format Message Text 9.2.3 Compile the Message Source File 9.2.4 Link the Object File 9.2.5 Replace the Old DTRMSGS.EXE File with the New One 10 Customizing ADT and Guide Mode 10.1 Customizing ADT 10.1.1 Copy the ADT Text File 10.1.2 Modify ADT Text 10.1.2.1 Ready the ADT_TEXT Domain 10.1.2.2 Modify ADT Text Strings 10.1.2.3 Add ADT Text Strings 10.1.2.4 Messages During an ADT Session 10.1.3 Replace the Old ADT Text File with the New One 10.2 Customizing Guide Mode 10.2.1 Copy the DTRGUIDE.DAT File 10.2.2 Modify the Distribution of Commands and Statements 10.2.3 Replace the Old DTRGUIDE.DAT with the New One 11 Customizing DATATRIEVE Text 11.1 DATATRIEVE Text 11.1.1 Syntax Prompt Text 11.1.2 SHOW Text 11.1.3 Date Text 11.1.4 Default Edit Strings 11.1.5 Statistical Text 11.1.6 Keywords 11.2 How to Change DATATRIEVE Text 11.2.1 Copy the DATATRIEVE Text File 11.2.2 Edit the Text File 11.2.3 Assemble the Text File 11.2.4 Replace the Text Object File in DTRLIB.OLB 11.2.5 Relink the DATATRIEVE Shareable Image 12 Translating DATATRIEVE 12.1 Planning Your Translation 12.2 How to Translate DATATRIEVE 12.2.1 Translating Keywords 12.2.2 Translating Help Text 12.2.3 Translating Messages 12.2.4 Translating ADT 12.2.5 Translating the Remaining Text Elements 12.2.6 Translating the Names of Functions 12.2.7 Relinking the DATATRIEVE Shareable Image A Definitions of the DATATRIEVE Access Block A.1 DATATRIEVE Access Block in VAX FORTRAN A.2 DATATRIEVE Access Block in VAX COBOL A.3 DATATRIEVE Access Block in VAX BASIC A.4 DATATRIEVE Access Block in VAX Pascal A.5 DATATRIEVE Access Block in VAX PL/I A.6 Defining the DATATRIEVE Access Block in Other VAX Languages A.6.1 Defining the Access Block A.6.2 Defining the Message Buffers A.6.3 Defining DATATRIEVE Constants B DATATRIEVE Message Information C Argument Data Types EXAMPLES 2-1 Sample Error Checking Routine in BASIC FIGURES 1-1 VAX DATATRIEVE Architecture 8-1 Structure of the DEFINE Help File 8-2 Structure of a Sample Help File A-1 Structure of the DATATRIEVE Access Block TABLES 2-1 DAB Definition Files in DTR$LIBRARY 2-2 Stallpoints and Calls 2-3 Useful DAB Fields 2-4 Content of Message Buffers 2-5 Stallpoint Values 2-6 DATATRIEVE-Defined Keywords 6-1 Types of Context for User-Defined Keywords 6-2 DTR$DTR Control Options 6-3 DTR$DTR Terminal Server Options 6-4 Token Types for the DTR$GET_STRING Call 6-5 Info-Code Options 6-6 DTR$WINDOWS Control Options 6-7 DTR$WINDOWS DECwindows Terminal Server Options 7-1 Common VAX Data Types 7-2 Input Argument Types and Clauses 9-1 Sample DATATRIEVE Messages 9-2 FAO Directives Used in DATATRIEVE Messages 10-1 Guide Mode Levels A-1 Fields of the DATATRIEVE Access Block A-2 DATATRIEVE Access Block Constants C-1 Atomic Data Types C-2 String Data Types C-3 Miscellaneous Data Types