CONTENTS Title Page Copyright Page Information Map Information Table Preface Technical Changes and New Features 1 Writing Definitions with ADU 1.1 Starting and Stopping ADU 1.1.1 Starting ADU 1.1.2 Stopping ADU 1.1.3 Assigning a Default Text Editor 1.2 ACMS and the Data Dictionary 1.2.1 Dictionary Path Names 1.2.2 Creating CDO Directories and Establishing Directory and Entity Protection 1.2.3 Converting ACMS Definitions from CDD Format to CDD/Plus Format 1.3 Establishing Your ADU Environment 1.4 Understanding ACMS Terminology 1.4.1 Identifier 1.4.2 File Specification 1.4.3 Workspace Field Name 1.4.4 Text Strings 1.5 Creating and Processing Definitions 1.6 How ACMS Uses Definitions 1.6.1 Creating ADU Definition Files 1.6.2 ACMS Definitions: Placing in and Retrieving from CDD/Plus 1.6.3 Annotating Definitions 1.6.4 Abbreviating Commands and Keywords 1.6.5 Using Command Qualifiers 1.6.6 Using the Command Continuation Character 1.6.7 Responding to Command Prompts 1.6.8 Leaving ADU Temporarily 1.6.9 Using ADU Interactively 1.6.10 Using the VAX Language-Sensitive Editor to Create Definition Files 1.7 Getting Help 2 Defining Tasks 2.1 Structure of an ACMS Task 2.2 Defining a Data Entry Task 2.2.1 Using Workspaces to Pass Data Between Steps 2.2.2 Defining the Block Step 2.2.3 Defining Characteristics of the Task 2.2.4 Storing a Task Definition in the Dictionary 2.2.5 Additional Considerations: Error Handling and Ease of Use 2.2.5.1 Using ACMS Workspaces 2.2.5.1.1 Using the CONTROL FIELD Clause in an Exchange Step 2.2.5.1.2 Using the IF THEN ELSE Clause in a Processing Step 2.2.5.1.3 Additional Workspace Definitions 2.2.5.2 Repeating the Task Automatically 2.3 Defining an Inquiry Task 2.3.1 Getting Information from the User 2.3.2 Retrieving Information from a File 2.3.3 Displaying Information 2.3.4 Completing the Task Definition 2.3.5 Additional Considerations: Displaying Multiple Records 2.3.5.1 Getting Information from the User 2.3.5.2 Retrieving Information 2.3.5.3 Displaying Information to the User 2.3.5.4 Completing the Task Definition 2.4 Defining an Update Task 2.4.1 Getting Information from the User 2.4.2 Retrieving Information from a File 2.4.3 Letting the User Update the Information 2.4.4 Writing the New Information to the File 2.4.5 Completing the Task Definition 3 Using DECforms with ACMS 3.1 ACMS Interface to DECforms 3.1.1 Calls to External Requests 3.1.2 Processing External Requests 3.1.3 Responses to External Requests 3.2 Writing and Compiling DECforms Escape Units 3.2.1 Writing an Escape Unit 3.2.2 Calling an Escape Unit in a Form Source IFDL File 3.3 Linking DECforms Form Objects 3.4 Linking Escape Units 3.4.1 Managing Escape Unit Files 3.4.2 Replacing Form Files 3.5 Creating Forms Trace files 3.6 Naming Forms Image files 3.7 User Interface Changes with DECforms 3.8 Comparison of DECforms and TDMS 4 Defining Workspaces 4.1 Understanding the Types of ACMS Workspaces 4.2 Handling Errors with a Task Workspace 4.3 Using Data Supplied at the Menu 4.4 Using Group Workspaces 4.5 Using User Workspaces 4.6 Moving Data to a Workspace Field 4.7 Passing Data with User-Written Agents 4.8 Using External Global Symbols in Task Definitions 5 Using the Task-Call-Task Feature 5.1 Calling Another Task 5.1.1 Defining a Task Call 5.1.2 Task Call Example 5.1.3 Passing Workspaces 5.1.3.1 Using System Workspaces 5.1.3.2 Handling User and Group Workspaces 5.1.3.3 Tasks You Also Select from a Menu 5.1.3.4 Example of Updating Group and User Workspaces 5.1.4 Controlling Called Tasks 5.1.4.1 Passing Control Information in User-Defined Workspaces 5.1.4.2 Ending a Called Task 5.1.4.3 Controlling Parent Tasks 5.1.5 Defining Local Tasks 5.1.6 Mixing I/O Methods in Parent and Called Tasks 5.1.7 Form and Server Context in Task Calling 5.1.8 Using the NOT CANCELABLE BY TASK SUBMITTER Clause 5.1.9 Auditing and Operation 5.1.9.1 Task Auditing and Security 5.1.9.2 Using ACMS Operator SHOW and CANCEL Commands 6 Defining Distributed Transactions 6.1 Why Use Distributed Transactions 6.2 Including Distributed Transactions Syntax in the Task Definition 6.3 Including Multiple Resource Managers in a Distributed Transaction 6.4 Using Task Sequencing Actions in a Distributed Transaction 6.5 Including a Called Task in a Distributed Transaction 6.6 How Distributed Transactions Affect Server Context 6.7 Excluding a Processing Step from a Distributed Transaction 6.8 Handling Deadlocks and Transaction Failures 7 Handling Task Execution Errors 7.1 Why Use Exception Handling 7.2 What is an Exception 7.2.1 Step Exceptions 7.2.2 Transaction Exceptions 7.2.3 Nonrecoverable Exceptions 7.3 Using the RAISE EXCEPTION Clause 7.4 Using Exception Handler Actions 7.5 Examples of Exception Handling 7.5.1 Recovering from a DECforms Time-out Exception 7.5.2 Recovering from a Task-Call-Task Exception 7.5.3 Recovering from a Transaction Exception 7.6 How ACMS Performs Exception Handling 7.6.1 Executing a Step Exception Outside of a Distributed Transaction 7.6.2 Executing a Step Exception Within a Distributed Transaction 7.6.3 Executing a Transaction Exception 7.6.4 Executing Nonrecoverable Exceptions 7.7 How Exceptions Affect Server Cancel Procedures 7.7.1 Step Exceptions and Server Cancel Procedures 7.7.2 Nonrecoverable Exceptions Raised by Action Clauses 7.7.3 Other Nonrecoverable Exceptions and Transaction Exceptions 8 Queuing ACMS Tasks 8.1 Understanding the ACMS Queuing Facility 8.2 Using ACMS Queuing with Distributed Transactions 8.3 Steps in Using ACMS Queuing 8.4 Defining Queue Security 8.5 Using the ACMS Queue Services to Queue and Dequeue Tasks 8.5.1 Queuing Tasks Using the ACMS$QUEUE_TASK Service 8.5.2 Dequeuing Task Elements Using the ACMS$DEQUEUE_TASK Service 8.6 Using the QTI to Dequeue Tasks 8.6.1 Characteristics of Queued Tasks That are Processed by the QTI 8.6.2 Setting ACMSGEN Parameters for the QTI Process 8.6.2.1 Assigning a User Name to the QTI Process 8.6.2.2 Assigning a Priority to the QTI Process 8.6.2.3 Controlling Submitter Sign-Ins 8.6.2.4 Setting the Retry Time for Failed Tasks 8.6.3 Auditing Done by the QTI Process 8.6.4 How the QTI Handles Errors 8.7 Processing Error Queues 8.8 Debugging Queued Tasks 8.9 Online Backup of Task Queue Files 8.10 Queuing Example 8.11 Procedure Parameter Notation for Programming Services 8.12 ACMS$DEQUEUE_TASK 8.13 ACMS$QUEUE_TASK 9 Defining Task Groups 9.1 Defining a Task Group 9.2 Identifying Which Tasks Belong to the Task Group 9.3 Identifying Which Servers Are Required in the Group 9.3.1 Assigning Server Attributes 9.4 Naming Request Libraries 9.5 Identifying Which Message Files Are Used in the Group 9.6 Naming Workspaces in a Task Group Definition 9.7 Naming the Task Database for a Task Group 9.8 Changing Characteristics of Task Argument Workspaces 10 Defining Applications 10.1 Defining a Simple Application 10.2 Describing the Application Environment 10.2.1 Naming Task Groups 10.2.2 Naming a User Name for the Application Execution Controller 10.2.3 Assigning Characteristics to Tasks and Servers 10.3 Controlling Tasks 10.3.1 Controlling Access to Tasks 10.3.2 Auditing Task Events 10.3.3 Controlling What Happens When a Task Ends 10.3.4 TASK ATTRIBUTES and TASK DEFAULTS Clauses 10.3.4.1 Using the TASK ATTRIBUTES Clause 10.3.4.2 Using the TASK DEFAULTS Clause 10.3.4.3 Defaulting Task and Task Group Names 10.3.4.4 Positioning TASK ATTRIBUTES and TASK DEFAULTS Clauses 10.3.5 Enabling and Disabling Tasks in the Application Definition 10.3.6 Controlling Transaction Timeouts in the Application Definition 10.4 Controlling Servers 10.4.1 Assigning a Server User Name 10.4.2 Assigning a Dynamic or Fixed Server User Name 10.4.3 Assigning Server Default Directories 10.4.4 Assigning Server Logical Names 10.4.5 Creating Logical Name Tables for Application Servers 10.4.6 Controlling the Number of Server Processes 10.4.7 Creating and Deleting Server Processes 10.4.8 Replacing an Active Server 10.4.9 SERVER ATTRIBUTES and SERVER DEFAULTS Clauses 10.4.10 Defaulting Server and Task Group Names 10.4.11 Positioning SERVER ATTRIBUTES and SERVER DEFAULTS Clauses 10.4.12 Auditing Servers 10.4.13 Enabling Procedure Server Process Dumps 10.5 Controlling Applications 10.5.1 Assigning an Application Execution Controller User Name 10.5.2 Auditing Applications 10.5.3 Assigning Application Default Directories 10.5.4 Assigning Application Logical Names 10.5.5 Assigning Application Database Files 10.5.6 Controlling the Number of Server Processes 10.5.7 Controlling the Number of Task Instances 10.6 Modifying an Active Application 10.7 Controlling Application Failback 11 Defining Menus 11.1 Planning the Menu Structure 11.2 Defining Menus 11.2.1 Creating a Title for a Menu 11.2.2 Naming Entries on a Menu 11.2.3 Naming Menus 11.2.4 Naming Tasks on a Menu 11.2.5 Specifying WAIT or DELAY Action 11.2.6 Naming Default Application Files 11.2.7 Application Specifications and Remote Tasks 11.2.8 Naming Default Menu Files 11.2.9 Defining a Menu Forms Product 11.3 Processing the Menu Definition 12 Defining Existing Applications as ACMS Tasks 12.1 Defining Single-Step Tasks in ACMS Task Groups 12.1.1 Defining VMS Images as Tasks 12.1.2 Defining DCL Commands and Command Procedures as Tasks 12.1.3 Defining DATATRIEVE Commands and Procedures as Tasks 12.2 Defining Servers to Handle Processing 12.3 Using the Task Group in an Application 13 Using the ACMS Request Interface 13.1 Overview of the ACMS Request Interface 13.2 The Request Interface and the ACMS Run-Time System 13.3 Defining Tasks and Task Groups 13.3.1 Task Definition 13.3.2 Defining a Task Group 13.3.3 How and When to Use the ACMS$RI_LIB Logical Name 13.4 Writing User Request Procedures 13.4.1 Writing an ACMS$RI_LIB_INIT Initialization Procedure 13.4.2 Writing an ACMS$RI_LIB_CANCEL Cancellation Procedure 13.4.3 Compiling and Linking URPs 13.5 Providing an RI Agent 13.5.1 Providing a Menu Interface 13.5.2 Compiling and Linking Menu Interface URPs with the RI Agent 13.6 Debugging Applications That Call URPs 13.6.1 Using the VMS Debugger to Debug URPs Using a Running Application 13.6.2 Using the ACMS Task Debugger to Debug URPs and Their Tasks 13.7 Defining an Application That Uses the Request Interface 13.8 Running the Agent A Changing the ACMS Menu Format Using DECforms A.1 Modifying Menu Appearance Without Changing the Default Format A.2 Modifying the ACMS Menu Using DECforms A.2.1 Obtaining the ACMS DECforms Default Menu File A.2.2 How ACMS Uses Menu Form Record Definitions A.2.3 Instructions Performed by the Form File A.2.4 Modifying the Menu Appearance Only A.2.5 Changing SELECTION_STRING Field Lengths A.2.6 Changing the Number of Entries per Screen A.2.7 Changing the Size of the Command Line Recall Buffer A.2.8 Changing the DECforms Layout Size A.2.9 Using a Customized Response and Panel Definition A.2.10 Building and Installing the New Menu Form A.3 Disabling the SELECT Command in the ACMS Command Menu B Changing the ACMS Menu Format Using TDMS B.1 Modifying the Menu Format Using ACMS B.2 Modifying the ACMS Menu Using TDMS Requests B.2.1 Getting the ACMS Menu Request and Form B.2.2 Modifying the Menu Form Only B.2.3 Forms, Records, and Keypad Used by the Menu Request B.2.4 Instructions Performed by TDMS When ACMS Calls a Request B.2.5 Modifying the Menu Request B.2.6 Using the REQUEST Clause B.2.7 Changing the MENU_ENTRY_RECORD B.2.8 Modifying and Building the ACMS Menu Request Library B.3 Disabling the SELECT Command in the ACMS Command Menu C Using CDO for Pieces Tracking C.1 Overview of Dictionary Object Types C.2 Creating Relationships Between Entities D Using LSE with ACMS D.1 Using LSE with ACMS D.2 Creating ACMS Source Files with LSE D.2.1 Using Placeholders and Tokens in LSE D.2.2 Creating the Final Source File D.2.2.1 Syntax Differences D.2.2.2 Exiting Editing Mode D.3 Compiling Definitions with LSE COMPILE D.4 Examining Diagnostic Messages with LSE REVIEW D.4.1 Generating the Diagnostics File D.4.2 Examining the Diagnostics File with LSE REVIEW D.5 Using HELP in LSE E Request Interface Kit Components E.1 Application Independent Modules E.2 RI Sample Application E.2.1 RI Sample Application Source Modules E.2.2 RI Sample Application Run-Time Files E.3 FMS Sample Application E.3.1 FMS Sample Application Source Modules E.3.2 FMS Sample Application Run-Time Files F Modifying the FMS Menu Interface EXAMPLES 1-1 A Sample ADUINI.COM File 1-2 SET VERIFY Display 1-3 REPLACE Command in a Source Definition File 2-1 Definition of ADD_RESERVE_WKSP Fields 2-2 Contents of a Source Definition File 2-3 Complete Definition for the Add Car Reservation Task 2-4 Definition for RENTAL_CLASSES_WKSP 2-5 Complete Definition of the Review Car Rates Task 2-6 Record Description for REVIEW_RESERVATION_WORKSPACE 2-7 Complete Definition of Review Reservation Task 2-8 Definition for RESERVE_WKSP Workspace 2-9 Record Description for RESERVE_SHADOW_WKSP Workspace 2-10 Complete Definition of Review Update Task 3-1 Example of an Escape Unit 4-1 Record Definition for ADD_RESERVE_WKSP 4-2 Task Definition for Add Car Reservation Task 4-3 Definition for the ACMS$SELECTION_STRING Workspace 4-4 Definition for Display Basic Task 4-5 Record Definition for GROUP_WORKSPACE 4-6 Complete Definition for the Get Initial Value Task 4-7 Definition for Labor Reporting Task 4-8 Record Definition for DISPLAY_USER_WKSP 4-9 Definition for Display Basic Task with User Workspace 4-10 Moving Data to a Workspace Field 5-1 Task ENTER_ORDER 5-2 Task PROCESS_ORDER_LINE 5-3 Procedure WRITE_ORDER_LINE (in BASIC) 5-4 Updating User and Group Workspaces 5-5 Passing User Workspaces to Menu Tasks 5-6 Passing Data to a Called Task 5-7 Returning Your Own Exit and Cancel Status Values 5-8 MAIN_MENU Task 6-1 Distributed Transaction on a Nested Block Step 6-2 Multiple Database Updates in a Distributed Transaction 6-3 Calling a Task to Participate in a Distributed Transaction 6-4 Complete Definition of the VR_COMPLETE_CHECKOUT_TASK 6-5 VR_FAST_CHECKIN_TASK with Nonparticipating Processing Steps 7-1 RAISE EXCEPTION Clause in a Processing Step 7-2 Performing Exception Handling in a Task 7-3 Recovering from a DECforms Time-out Exception 7-4 Recovering from an Exception Raised in a Called Task 7-5 Recovering from a Transaction Exception 7-6 Canceling a Task without Calling Server Cancel Procedures 8-1 Sample QTI Audit Entry 8-2 A Task That Dequeues from an Error Queue 8-3 A Dequeue Procedure 8-4 An Enqueue Procedure 8-5 C Agent that Starts a Distributed Transaction 8-6 VR_FAST_CHECKIN_TASK Definition 8-7 Enqueuing Routine 8-8 VR_COMP_FAST_CHKIN_TASK Definition 9-1 Definition of VR_READ_SERVER 9-2 Definition of Department Task Group 10-1 Personnel Application Definition 10-2 Application Definition Using TASK DEFAULTS 10-3 Application Definition Using Multiple TASK DEFAULTS 10-4 Application Using TASK ATTRIBUTES and TASK DEFAULTS 10-5 Enabling and Disabling Tasks in the Application Definition 10-6 Using TRANSACTION TIMEOUT in the Application Definition 10-7 Application Definition Using Server Defaults 10-8 Application Using Multiple Server Defaults Clauses 11-1 Menu Definition for the Personnel Menu 11-2 Example of a Menu with a Remote Task 12-1 A Task Group Definition 13-1 Simple Inquiry Task 13-2 Task Group Definition 13-3 FORTRAN User Request Procedure 13-4 TDMS Request 13-5 FORTRAN Initialization Procedure 13-6 Example of Audit Trail Error Messages 13-7 FORTRAN Cancel Procedure 13-8 REQPROCS.OPT Options File 13-9 Linking Shareable Images and Using an Options File 13-10 FMS Initialization Procedure 13-11 FMS Menu Procedure 13-12 Example Application Definition A-1 Definition for ACMS Menu Header A-2 Definition for Menu Entries Record A-3 Definition for Menu Control A-4 Definition for Menu Selection Record A-5 Control Text Response Found Record A-6 Panel Definition A-7 Default Panel Field Definition A-8 Command Panel Field Definition A-9 Record Group SELECT_LINE_GROUP A-10 SELECTION_STRING Record Groups A-11 SELECTION_STRING Panel Definitions A-12 ENTRIES Record Group A-13 ENTRIES Record in Default Panel Definition A-14 Menu Definition Specifying Entries per Screen A-15 Command Line Recall Buffer Definitions A-16 Definition of Default Screen Layout A-17 Menu Definition Using CONTROL TEXT B-1 MENU_REQUEST Definition B-2 Definition for ACMS Menu Header Record B-3 Definition for Menu Entry Record B-4 Definition for Menu Control B-5 Definition for Menu Selection Record B-6 Customized Menu Request B-7 Menu Definition Using REQUEST Clause B-8 Record Definition for MENU_ENTRY_RECORD with 12 Entries B-9 MENU_LIBR Request Library Definition D-1 LSEDIT.COM File FIGURES 1-1 Creation of Definition Database Files 1-2 The Review Menu 2-1 Structure of a Task Definition 2-2 The Workspace Used to Pass Information 2-3 Retrieving Messages 4-1 A Selection Menu 7-1 Block Step Structure 8-1 Queuing, Dequeuing, and Processing Tasks 8-2 A Queuing Example 8-3 List of Workspaces Passed by ACMS$DEQUEUE_TASK 8-4 List of Workspaces Passed by ACMS$QUEUE_TASK Service 9-1 A Task Group and Its Tasks 11-1 The ACMS Menu Structure 11-2 Personnel Menu 11-3 The Review Menu 11-4 ACMS Menu Choices 13-1 Request Interface Run-Time Components 13-2 Request Interface Model 13-3 User-Written Shareable Image File 13-4 Pseudocode for an RI Agent Using an FMS Menu Interface D-1 Creating a New File with LSE D-2 Expanding a Placeholder D-3 Expanding the REPLACE TASK | CREATE TASK Placeholder D-4 Choosing REPLACE_TASK D-5 Expanded Comment Placeholders D-6 Expanding Tokens D-7 Final Source File Created with LSE D-8 Examining Diagnostic Files with LSE REVIEW F-1 Form Editor Menu TABLES 1-1 Startup Qualifiers and Their Functions 1-2 Ways to Exit from ADU 1-3 Establishing Protection for ACMS Dictionary Entities 1-4 Actions to Convert Definitions from DMU to CDO Format 1-5 ADU Commands for ADUINI.COM File 2-1 Data Entry Task 2-2 Field and Values Tested by Conditional Clauses 2-3 Inquiry Task 2-4 Update Task 3-1 DECforms and TDMS Terminology 4-1 Summary of ACMS Workspaces 7-1 Step Exceptions 7-2 Transaction Exceptions 7-3 Nonrecoverable Exceptions 8-1 ACMSGEN Parameters Associated with QTI 8-2 Errors That Result in Queued Task Retry 8-3 Errors That Result in Writing Queued Task Elements to an Error Queue 8-4 Errors That Result in Immediate Retry of Queued Task 8-5 Procedure Parameter Notation 13-1 Logical Names Used by the Request Interface 13-2 Routines Used by the Request Interface 13-3 Menu Interfaces Used by the Request Interface B-1 Definitions Copied to the CDD C-1 CDD/Plus Protocols for ACMS Entity and Relationship Objects D-1 LSE REVIEW Window Commands E-1 Request Interface Kit Components F-1 Defining the Named Data Associated with the Form