CONTENTS Title Page Copyright Page Preface 1 Introduction to the CDA Converter Architecture 1.1 Converter Overview 1.2 Converter Architecture Concepts 1.2.1 Domains 1.2.2 Aggregate Hierarchy 1.2.3 Input and Output Concepts 1.3 Converter Architecture Components 1.3.1 Input and Output Sources 1.3.2 Front Ends and Back Ends 1.3.3 The CDA Converter Kernel 1.3.4 The Domain Converter 1.3.5 User Interfaces to Converters 1.3.6 Conversion Control Flow 1.4 CDA Services 1.5 DDIS Description 2 Overview of Writing a Converter 2.1 CDA-supported Platforms 2.2 Conversion Methods 2.3 CDA-Supplied and System Components 2.4 What You Must Write to Compose a Front End 2.5 What You Must Write to Compose a Back End 2.6 Additional Routines to Write 2.7 Program Flow in Conversion 2.8 Front End Fundamentals 2.8.1 The Read_ format Entry Point Routine 2.8.2 The Get-aggregate Entry Point Routine 2.8.3 The Get-position Entry Point Routine 2.8.4 The Close Entry Point Routine 2.8.5 The Get Routine 2.9 Back End Fundamentals 2.9.1 Naming the Write_ format Entry Point Routine 2.9.2 Tasks of the Write_ format Routine 2.9.3 The Put Routine 2.10 Input and Output Sources: Files and Streams 3 Guidelines for Planning, Designing, and Coding 3.1 Making Time Estimates 3.2 Selecting a Method of Conversion 3.3 Selecting a Domain 3.4 Planning Paired Converters 3.5 Developing Base Levels 3.6 Naming Your Format 3.7 Developing a Data Map 3.7.1 Example of a Data Map 3.7.2 Creating Data Maps for Front and Back ends 3.8 Including an Aggregate Tree Diagram 3.9 Coding for File Inclusions 3.9.1 Required Files 3.9.2 Additional File Inclusions 3.9.3 Example File Inclusions 3.10 Allowing for Processing Options 3.11 Coding for Portability 3.11.1 Using Portability Conventions 3.11.2 Guidelines for the C Programming Language 3.11.3 Naming for Portability 3.11.4 Setting Up Header Files for Portability 3.11.5 OS/2 and MS-DOS Porting Hints and Common Mistakes 3.12 Avoiding Common Coding Mistakes 3.13 Planning Your Testing Procedures 4 Building Images and Invoking Conversion 4.1 Building Shareable Images on VMS Systems 4.2 Location of Images on VMS Systems 4.3 Building Executable Images on ULTRIX Systems 4.4 Location of Images on ULTRIX Systems 4.5 Building Dynamic Link Libraries on OS/2 and MS-DOS Systems 4.5.1 Including Required Files 4.5.2 Using the Callable Interface Prototypes 4.5.3 Naming the Read or Write Format 4.5.4 Function Definitions for the Text Front End 4.5.5 Function Definitions for the Text Back End 4.5.6 Building the Converter on OS/2 4.5.7 Building the Converter on MS-DOS 4.6 Location of Images on OS/2 and MS-DOS Systems 4.7 Invoking Conversion 4.7.1 The Command Line Interface on VMS Systems 4.7.2 The Command Line Interface on ULTRIX Systems 4.7.3 The Command Line Interface on OS/2 and MS-DOS Systems 4.7.4 The Callable Interface 5 Debugging and Testing Converters 5.1 Debugging on VMS Platforms 5.1.1 Implementing the Debugging Method 5.1.2 Building an Image for Debugging on VMS Systems 5.1.3 Sample VMS Debugging Session 5.2 Debugging Converters on ULTRIX Platforms 5.3 Testing 5.4 Testing Back Ends 5.4.1 Testing File Names 5.4.2 Additional Test Ideas 5.5 Testing Front Ends with the Analysis Back End 5.5.1 How to Convert with the Analysis Back End 5.5.2 Description of Analysis Output 5.5.3 Sample Analysis Output with Errors 5.5.4 Testing DTIF Files With the Analysis Back End 5.6 Testing with CDA-Supported Converters 5.7 Testing with Applications 5.7.1 DDIF Applications 5.7.2 DTIF Applications 5.8 Making a Visual Inspection 5.9 Testing Front Ends and Back Ends Together 5.9.1 Testing a Front End 5.9.2 Testing Front and Back Ends 5.10 Message Facility Routines 5.10.1 Retrieving CDA Access Routine Messages 5.10.2 Integrating Logged Messages by Common Message Log 5.10.3 Enhanced Message Reporting A MacWrite and Nested PICT Back Ends B Text Front End C Conversion Using the Document Method C.1 Modifications to a Front End C.2 Modifications to a Back End C.3 Functional View of the Document Method D Data Map Examples D.1 WK1 Front End Data Map D.2 WK1 Back End Data Map D.2.1 Cell Value Mapping D.2.2 Formula Mapping D.2.3 Format Mapping D.2.4 Miscellaneous Mappings D.3 CGM to DDIF Data Map Glossary of Terms EXAMPLES 1-1 Results of DTIF to TEXT Conversion 2-1 Example Coding for the read_ format Entry Point 2-2 Example Coding for the Write_ format Entry Point 3-1 Portion of a Data Map for the WK1 Front End 4-1 Front End Build Procedure on VMS Systems 4-2 Prototype of Front End Open Routine 4-3 Prototype Function Definition for the Text Front End 4-4 Prototype Function Definition for the Text Back End 4-5 Makefile to Build Text Converters on OS/2 4-6 Makefile to Build Text Converters on MS-DOS 4-7 Callable Interface 4-8 Sample Converter Debugging Program 5-1 Build Procedure for Debugging on VMS Systems 5-2 Analysis Output 5-3 Identification of Array Data 5-4 Analysis Output with Inheritance Enabled 5-5 Analysis Output with Errors FIGURES 1 DEC CDA Base Services Documentation Map 1-1 Relationship of Front End to a Back End 1-2 Tree Structure and Traversal 1-3 Converter Components Diagram 1-4 Domain Conversion Example 1-5 Conversion Control Flow 2-1 Program Flow in Conversion 4-1 CDAPATH Root Substructure 5-1 Circular Testing Methodology TABLES 1-1 DDIF Aggregate Types 1-2 DTIF Primary Aggregate Types 1-3 Examples of Revisable Formats 2-1 Required Front End Routines 3-1 CDA Header Files 5-1 Supported Data Formats and Converters 5-2 DECdecision Component Support of DTIF D-1 Cell value mapping D-2 Formula Mapping D-3 Format Mapping D-4 Miscellaneous Mappings