CONTENTS Title Page Copyright Page Information Map Information Table Preface 1 Introduction 1.1 Orientation to the Application Development Life Cycle 1.2 Concepts and Terminology 1.2.1 ACID Transactions 1.2.1.1 Properties of Transactions 1.2.2 Distributed Transactions 1.2.3 DECintact Components 1.2.4 Presentation Services 1.2.5 Resource Managers 1.2.6 Recovery 1.2.7 Environments and Methodologies 1.2.7.1 Environments 1.2.7.2 Methodologies 1.2.8 RMS Data and File Definitions 1.2.9 Programming Conventions 1.3 Programming Resources 1.3.1 Sample Applications 1.3.2 Programming Tools 1.3.3 Include Files 1.3.4 Status Messages Part I Application Development Process 2 Developing a DECintact Application 2.1 Application Structure 2.1.1 Referencing Include Files 2.1.2 Establishing the Environment 2.1.3 Establishing the Transaction Context 2.1.3.1 Terminal-Manager-Based Per-Process Applications 2.1.3.2 Terminal-Manager-Based Multithreaded Applications 2.1.3.3 Non-Terminal-Manager-Based Multithreaded Applications 2.1.4 Displaying a Form 2.1.5 Defining a Recovery Unit 2.2 Interpreting Condition Codes 2.2.1 Testing Whether a DECintact Routine Succeeds 2.2.2 Interpreting Degrees of Success or Failure 2.3 Testing Condition Codes for Symbolic Names 2.4 Reporting Errors to Users 2.5 Application Types 2.5.1 Multithreaded Root Module 2.5.2 Multithreaded Subprogram Module 2.5.3 Thread Context 2.5.4 Program Variables 2.5.4.1 Using INTACT_PSECTs 2.5.4.2 Using TDB and DFB PSECTs 2.5.4.3 Using Stack Data 2.5.5 Non-Terminal-Manager-Based Multithreaded Applications 2.5.6 User-Controlled Thread Switching 3 Building a DECintact Application 3.1 Compiling Source Code 3.2 Linking Object Code 4 Testing and Debugging a DECintact Application 4.1 Testing Forms 4.2 Testing an Application Before Installation 4.2.1 Testing a Per-Process Application with Two Terminals 4.2.2 Testing a Multithreaded Application with Two Terminals 4.2.3 Using TEST with One Terminal 4.3 Examining the TDB and DFB 4.4 Examining Application Crash Files 4.5 Testing an Application After Installation 5 Moving an Application from Development to Production Part II User Interface 6 Using DECforms Forms 6.1 Using DECintact DECforms Routines 6.1.1 Enabling a Form 6.1.1.1 Specifying the DECforms Form File 6.1.1.1.1 Binary Form Files 6.1.1.1.2 Shareable Image Form Files 6.1.1.2 Storing and Distributing DECforms Forms 6.1.1.3 Caching a DECforms Session 6.1.2 Sending Data to a DECforms Form 6.1.3 Receiving Data from a DECforms Form 6.1.4 Combined Sending and Receiving of Data 6.1.5 Explicitly Disabling a Form 6.2 DECforms Programming Considerations 6.2.1 Disallowed DECintact Routine Calls 6.2.2 Terminal Key Bindings 6.2.3 Escape Routines 7 Using TFE Forms 7.1 Using DECintact Terminal Manager Routines 7.1.1 Initializing a TFE Form 7.1.2 Displaying a TFE Form 7.1.3 Reading and Changing TFE Form Field Attributes 7.1.3.1 Marking TFE Field Entry Errors 7.1.3.2 Determining Whether TFE Field Edit Checking Is Needed 7.1.3.3 Modifying the Protected, Hidden, and Required TFE Form Field Attributes 7.1.3.4 Getting TFE Form Field Attributes and Field Number 7.1.4 Controlling Terminal Manager Processing 7.1.4.1 Canceling a Transaction from a TFE Form 7.2 Using UERs 7.2.1 Writing a UER 7.2.1.1 Writing Input Editing UERs 7.2.1.2 Writing Display Editing UERs 7.2.1.3 Using DECintact Routines for UERs Only 7.2.2 Implementing a UER 7.2.2.1 Incorporating a UER into the Terminal Manager 7.2.2.2 Debugging a UER 7.2.2.3 Sharing UERs with Other Groups Part III Database 8 Accessing RMS and Hash Files 8.1 File Manager Overview 8.1.1 Record Access Method 8.1.2 Record Locking 8.1.3 Record Transfer Buffer 8.2 Defining Data 8.2.1 Explicitly Coding a Record Structure 8.2.2 Storing and Retrieving a CDD Record 8.2.3 Creating Files 8.3 Recovering Data 8.3.1 Transaction Rollback 8.3.2 Transaction Rollforward 8.3.3 Recovery Example 8.4 Using DECintact File Manager Routines 8.4.1 Using File Manager File-Level Routines 8.4.2 Using File Manager Record Accessing Routines 8.5 Using Hash Files 8.5.1 Accessing Hash File Records 8.5.2 Selecting a Hashing Algorithm 8.5.3 Writing a Hashing Algorithm 8.5.4 Interpreting Hash File Access Errors 8.5.5 Hash File Performance Considerations 9 Programming Distributed Transactions 9.1 DECdtm Services 9.1.1 DECdtm Transactions 9.1.2 Resource Managers 9.1.3 Two-Phase Commit Protocol 9.2 DECintact Routines to Call DECdtm Services 9.2.1 INTACT$GET_TID Routine 9.2.2 Existing Applications 9.3 VAX RMS Journaling 9.4 Programming Considerations for Distributed Transactions 10 Accessing Databases 10.1 Client/Server Concepts 10.2 Writing Client/Server Code 10.2.1 Writing Client Calls 10.2.1.1 Declaring the Client 10.2.1.2 Starting a Session 10.2.1.3 Communicating with a Server Instance 10.2.1.4 Using INTACT$TRANSCEIVE_REQUEST 10.2.1.5 Ending a Session 10.2.2 Writing Server Instance Calls 10.2.2.1 Root Module 10.2.2.2 Initialization Routine 10.2.2.3 Main Routine 10.2.2.4 Termination Routine 10.2.2.5 Return Condition Codes 10.2.3 Organizing Client/Server Calls 10.2.4 Distributed Transactions 10.3 Using Transactions with Client/Server Sessions 10.3.1 Coordinating Transactional Sessions 10.3.2 Initiating a Transactional Session 10.3.3 Ending a Transactional Session 10.3.3.1 Defining Transactional Session Boundaries 10.3.3.2 Handling Asynchronous Aborts 10.3.4 Writing a Nontransactional Session 10.3.4.1 Local Client Transaction 10.3.4.2 Local Server Transaction 10.3.4.3 Client and Server in Separate Local Transactions 10.3.5 Initiating Multiple Session Types 10.4 Writing Server Instance Routines 10.4.1 Writing Server Initialization Routines 10.4.1.1 Initialization Routines for VAX RMS Files 10.4.2 Initialization Routines for VAX DBMS Databases 10.4.2.1 Initialization Routines for VAX Rdb/VMS Databases 10.4.2.2 Initialization Routine for VAX Rdb/VMS Databases Using COBOL and SQL 10.4.3 Writing a Server Main Routine 10.4.4 Using Record Locking 10.4.5 Writing Server Termination Routines 10.4.5.1 Termination Routines for VAX RMS Files 10.4.5.2 Termination Routines for VAX DBMS Databases 10.4.5.3 Termination Routines for VAX Rdb/VMS Databases Part IV Queues 11 Using Queues 11.1 Overview of DECintact Queuing 11.2 Sample Queue Task 11.2.1 Sample Task 11.2.2 Task Solution 11.3 Queue Sets 11.4 Remote Queues 11.5 Queue Environments 11.6 Manipulating Queues and Queue Sets 11.6.1 Defining Queue Items 11.6.1.1 Queue Item Header 11.6.1.2 Programmer-Defined Portion of a Queue Item 11.6.2 Inserting Queue Items 11.6.3 Removing Items from Queues 11.6.3.1 First-In/First-Out Removal 11.6.3.2 Random Access Item Removal 11.6.4 Removing Queue Items from Queue Sets 11.6.4.1 Drain First Algorithm 11.6.4.2 Round Robin Algorithm 11.6.4.3 Weighted Algorithm 11.6.4.4 Nested Queue Sets 11.6.5 Returning Queue Items 11.6.6 Queue Servers 11.7 Queue Recovery 11.7.1 Proof Control Part V Additional Utilities 12 Using LSE 12.1 Invoking LSE 12.2 Expanding DECintact Routine Calls 12.3 Using LSE Help 13 Managing Business Calendars 13.1 Specifying a DECintact Calendar Format 13.2 Requirements for Using Calendar Management Routines 13.3 Using DECintact Routines for Managing Calendars 13.4 Using DECintact UERs for Managing Calendars 14 Programming to Collect Event Data with DECtrace for VMS 14.1 Overview of DECtrace 14.1.1 DECtrace Concepts 14.1.1.1 Events, Items, and Collection Classes 14.1.1.2 Collecting Data and Generating Reports 14.1.1.3 DECtrace Processing Steps 14.1.1.4 DECtrace Functioning 14.1.2 DECtrace Commands 14.2 Creating a DECtrace Facility for Your DECintact Application 14.2.1 Instrumenting Your Program 14.2.1.1 Determining Events and Items 14.2.1.2 DECtrace Service Routines 14.2.1.3 EPC$INIT Routine and Registering with the Registrar Process 14.2.1.4 Event Routines and Defining Events 14.2.1.5 Context Routines and Multithreaded Applications 14.2.1.6 Linking Instrumented Programs 14.2.2 Creating a Facility Definition for Your Application 14.2.2.1 Creating a Facility Definition 14.2.2.2 Displaying Facility Definition Information 14.3 Sample DECintact Applications as DECtrace Facilities 14.3.1 Sample DECintact Per-Process Application Facility 14.3.2 Sample DECintact Multithreaded Application Facility Part VI Appendixes A Sample Personnel Application A.1 Running the Sample Application A.2 Overview A.3 Sample Per-Process Application A.3.1 Sample Per-Process Application Explanation A.3.2 Rebuilding the Sample Per-Process Application A.4 Sample Multithreaded Personnel Application A.4.1 Sample Multithreaded Application Explanation A.4.2 Building the Sample Multithreaded Application B Sample Queue Server Program C Building and Running the AVERTZ Application C.1 Requirements C.2 Preparing to Build the AVERTZ Application C.2.1 Building AVERTZ C.2.2 Running AVERTZ C.3 AVERTZ File Names C.3.1 VAX COBOL File Names EXAMPLES 2-1 Sample Definitions File Inclusion Statements 2-2 Sample INTACT$DECLARE_ENVIRONMENT Call 2-3 Sample INTACT$GET_TRANSACTION Call 2-4 Multithreaded Root Module 2-5 Creating a PSECT in C 2-6 PSECTS, Image File 2-7 INTACT_ROOT in COBOL 2-8 INTACT_DATA in FORTRAN 2-9 INTACT_THREAD_CONTEXT in BASIC 2-10 Allocating Stack Data in C 2-11 Non-Terminal-Manager-Based Multithreaded Root Module - One Subroutine 2-12 Non-Terminal-Manager-Based Multithreaded Root Module - Three Subroutines 2-13 User-Written AST Routine 6-1 Sample INTACT$ENABLE_DECFORM Call 6-2 Creating a Shareable Image Form File 6-3 Selecting a Form from a Shareable Image 6-4 Sample INTACT$SEND_DECFORM Call 6-5 Sample INTACT$RECEIVE_DECFORM Call 6-6 Sample INTACT$TRANSCEIVE_DECFORM Call 6-7 Sample INTACT$DISABLE_DECFORM Call 6-8 DECforms Code for Calling Escape Routine PE_CANCEL_REQUEST 6-9 Escape Routine Code to Cancel a DECforms Request 6-10 Application Program Response to DECforms Cancellation 7-1 Specifying a Buffer Address 7-2 Input Editing UER 7-3 Display Editing UER 7-4 Input Editing UER That Calls DECintact UER Routines 8-1 Sample Explicit Record Structure Definition 8-2 Sample CDD Record Definition 8-3 Establishing a Recovery Unit 8-4 Accessing an RMS File Outside the Known File Database 8-5 Accessing a Record Sequentially in an RMS File 8-6 Retrieving a Record from a Hash File 9-1 One-Phase Commit Transaction 9-2 Two-Phase Commit Transaction 10-1 Establishing a Client Environment 10-2 Starting a Communications Session 10-3 Ending a Session 10-4 Root Module in VAX COBOL 10-5 Root Module in VAX C 10-6 Starting a Transactional Session 10-7 Starting a Local Transaction 10-8 VAX RMS Initialization Routine 10-9 VAX DBMS Initialization Routine 10-10 SQL Initialization Routine 10-11 AVERTZ Main Routine 10-12 VAX C Main Routine 10-13 VAX RMS Termination Routine 10-14 VAX DBMS Termination Routine 10-15 SQL Termination Routine 11-1 Defining Proof Control in COBOL 14-1 Options File for Sample Multithreaded Facility 14-2 Sample DECintact Per-Process Facility in COBOL 14-3 Sample DECintact Multithreaded Facility in C A-1 Sample Per-Process Personnel Application A-2 Sample Multithreaded Personnel Application Root Module A-3 Sample Multithreaded Personnel Application Subroutine Module B-1 Sample Multithreaded Program Using ASSIGN_QUEUE_SERVER B-2 Sample Program Performing Asynchronous QIO FIGURES 1-1 Application Development Life Cycle 1-2 Per-Process Methodology 1-3 Multithreaded Methodology 9-1 Executing the Two-Phase Commit Protocol 10-1 Sample Client and Server Configuration 10-2 Server Routines 10-3 Request/Response VAX COBOL Code 10-4 Request for Different Servers 10-5 Order of Routine Calls in a Sample Session 10-6 Multiple Session Types 11-1 Processing Messages - Task 11-2 Processing Messages - Queuing Solution 11-3 Accessing Queue Items - Individual Queues 11-4 Accessing Queue Items - Queue Sets 11-5 Accessing Queue Items - Remote Queues TABLES 2-1 COBOL Include Files 2-2 DECforms Definitions Files 6-1 DECintact Routines for Using DECforms 6-2 Recommended DECforms Key Bindings 7-1 DECintact Routines for Initializing a TFE Form 7-2 DECintact Routines for Displaying a TFE Form 7-3 DECintact Routines for Modifying TFE Window and Form Attributes 7-4 DECintact Routines for Marking TFE Field Entry Errors 7-5 DECintact Routines for Determining Whether TFE Field Edit Checking Is Needed 7-6 DECintact Routines for Modifying the Protected, Hidden, and Required TFE Field Attributes 7-7 DECintact Routines for Getting TFE Form Field Attributes and Field Number 7-8 DECintact Routines for Overriding Terminal Manager Processing 7-9 DECintact Routines Called Only from UERs 8-1 File Manager File-Level Routines 8-2 File Manager Record Access Routines 8-3 Default Hashing Algorithms 8-4 Nondefault Hashing Algorithms 8-5 RMS Hash File Errors 9-1 Routine Calls to DECdtm Services 9-2 RMS Journaling 10-1 Condition Codes Returned 10-2 Pairing of Client/Server Calls 10-3 Variations of Client/Server Transactions 11-1 Queue Operation Table 11-2 Queue Item Header Fields 11-3 Comparing of FIFO Removal Types 12-1 Alternate LSE Language Specifications 13-1 Date Code Formats 13-2 DECintact Routines for Managing Calendars 13-3 DECintact UERs for Managing Calendar Dates 14-1 DECtrace Command Summary 14-2 Examples of Events Determined from Collection Goals 14-3 DECtrace Service Routine Summary 14-4 Facility Definition Option Summary C-1 AVERTZ Fields