CONTENTS Title Page Copyright Page Information Map Information Table Preface Technical Changes and New Features Part I User Information 1 Introduction to Server Procedures 1.1 Procedure Server Terminology 1.2 Understanding Server Procedures 1.2.1 Initialization, Termination, and Cancel Procedures 1.2.2 Step Procedures 1.3 Naming and Structuring a Server Procedure 1.4 Programming Services and Tools 2 Writing Initialization, Termination, and Cancel Procedures 2.1 Writing Initialization Procedures 2.1.1 Guidelines for Writing Initialization Procedures 2.1.2 Binding or Attaching to Databases 2.1.3 Initialization Procedures for Rdb/VMS Databases Using SQL 2.1.3.1 Specifying the Access Mode and Relations Used by the Server 2.1.3.2 Using COBOL 2.1.4 Initialization Procedures for Rdb/VMS Databases Using RDO 2.1.5 Initialization Procedures for VAX DBMS Databases 2.1.5.1 Using COBOL 2.1.5.2 Using BASIC 2.1.6 Initialization Procedures for RMS Files 2.1.6.1 Using COBOL 2.1.6.2 Using BASIC 2.2 Writing Termination Procedures 2.2.1 Termination Procedures for Rdb/VMS Databases Using SQL 2.2.2 Termination Procedures for Rdb/VMS Databases Using RDO 2.2.3 Termination Procedures for VAX DBMS Databases 2.2.4 Termination Procedures for RMS Files 2.2.4.1 Using COBOL 2.2.4.2 Using BASIC 2.3 Server Process Rundown 2.4 Using Cancel Procedures 2.4.1 Guidelines for Avoiding Cancel Procedures 2.4.2 Situations in Which Using Cancel Procedures Is Unavoidable 2.4.3 Using $SETAST to Prevent Procedure Server Interruption 2.4.4 Conditions Under Which Cancel Procedures Are Called 2.4.5 Cancel Procedures in Distributed and Nondistributed Transactions 2.4.6 Writing a Cancel Procedure 2.4.6.1 Cancel Procedure for Rdb/VMS with RDO 2.4.6.2 Cancel Procedure for RMS Files 3 Writing Step Procedures 3.1 Using Workspaces with Step Procedures 3.1.1 Using ACMS-Supplied System Workspaces 3.1.2 Identifying Workspaces 3.2 Using Procedures in Distributed Transactions 3.2.1 Determining the Participation of a Procedure in a Distributed Transaction 3.2.2 Using Database Transactions or Recovery Units with Distributed Transactions 3.2.3 Obtaining the Transaction ID (TID) 3.2.4 Retaining Server Context in Distributed Transactions 3.2.5 Migrating Existing Step Procedures to Participate in Distributed Transactions 3.3 Returning Status to the Task Definition 3.3.1 Returning Status with a Status Return Facility 3.3.2 Returning Status in User-Defined Workspaces 3.3.2.1 COBOL Procedure for Returning Status in a User-Defined Workspace 3.3.2.2 BASIC Procedure for Returning Status in a User-Defined Workspace 3.4 Handling Error Conditions 3.4.1 Processing Error Messages 3.4.1.1 Using a Message File in the Task Definition 3.4.1.2 Using a Message File in the Step Procedure 3.4.1.3 Using Hard-Coded Messages in the Form 3.4.1.4 Using Hard-Coded Messages in the Step Procedure 3.4.2 Raising Exceptions in Step Procedures 3.4.2.1 Raising Recoverable Exceptions in Step Procedures 3.4.2.2 Raising Nonrecoverable Exceptions in Step Procedures 3.5 Performing Terminal I/O from a Procedure Server 4 Accessing Resource Managers 4.1 Using SQL with Rdb/VMS 4.1.1 Using Embedded SQL Statements in Step Procedures 4.1.2 Using SQL with Distributed Transactions 4.1.2.1 Defining an SQL Context Structure 4.1.2.2 Storing the TID in the SQL Context Structure 4.1.2.3 Passing the Context Structure to SQL 4.1.3 Starting and Ending SQL Database Transactions 4.1.3.1 Starting an SQL Database Transaction that is Part of a Distributed Transaction 4.1.3.2 Starting and Ending an Independent SQL Database Transaction 4.1.3.3 Using Rdb/VMS Transaction Mode and Lock Mode Specifications 4.1.3.4 Using an Rdb/VMS Wait Mode Specification 4.1.4 Reading from a Database 4.1.5 Writing to a Database 4.1.6 Handling Errors 4.1.7 Compiling Procedures that Use SQL 4.1.8 COBOL Step Procedure Using SQL with Rdb/VMS 4.2 Using Precompiled RDO or RDML with Rdb/VMS 4.2.1 Using RDO Statements in Step Procedures 4.2.2 Starting and Ending RDO Database Transactions 4.2.2.1 Starting an RDO Database Transaction that is Part of a Distributed Transaction 4.2.2.2 Starting and Ending an Independent RDO Database Transaction 4.2.3 Reading from a Database 4.2.4 Writing to a Database 4.2.5 Handling Errors 4.2.6 Compiling Rdb/VMS Procedures that Use RDO 4.3 Using VAX DBMS 4.3.1 Using VAX DBMS DML Statements in Step Procedures 4.3.2 Starting and Ending a VAX DBMS Database Transaction 4.3.2.1 Starting a VAX DBMS Database Transaction that Is Part of a Distributed Transaction 4.3.2.2 Starting and Ending an Independent VAX DBMS Database Transaction 4.3.2.3 Using VAX DBMS Access and Allow Mode Specifications 4.3.2.4 Using a VAX DBMS Wait Mode Specification 4.3.3 Reading from a Database 4.3.4 Writing to a Database 4.3.5 Handling Errors 4.3.6 Compiling VAX DBMS Procedures 4.4 Using RMS 4.4.1 Using Files Marked for RMS Recovery-Unit Journaling 4.4.2 Reading RMS Records 4.4.3 Writing and Updating RMS Records 4.4.4 Handling Errors 5 Using Message Files with ACMS Tasks and Procedures 5.1 Creating Source Files of Messages 5.1.1 Setting Up Message File Characteristics 5.1.2 Writing Messages 5.1.2.1 .FACILITY Statement 5.1.2.2 .SEVERITY Statements 5.1.2.3 Message Names and Text 5.2 Compiling Message Files 5.3 Displaying User-Defined Messages 6 Building Procedure Server Images 6.1 Steps in Building a Procedure Server Image 6.1.1 Writing the Source Code of the Procedure 6.1.2 Compiling the Source Code into a Procedure Object Module 6.1.3 Creating, Compiling, and Linking Message Files 6.1.4 Building the Task Group 6.1.5 Linking the Object Code of Procedures 6.2 Using an Object Library for Procedures 7 Debugging Tasks and Procedures 7.1 Using Debugging Tools 7.2 Preparing to Use the ACMS Task Debugger 7.2.1 Preparing Definitions 7.2.2 Preparing Procedures 7.2.3 Defining Logical Names 7.2.4 Preparing to Debug DECforms Escape Routines 7.2.5 Setting Up for Debugging with Two Terminals 7.2.6 Verifying that the ACMS Task Debugger Can Be Run 7.3 Using the ACMS Task Debugger 7.3.1 Starting the Task Debugger 7.3.2 Using the Task Debugger ASSIGN Command 7.3.3 Starting, Stopping, and Interrupting Servers 7.3.3.1 Starting Servers 7.3.3.2 Stopping Servers 7.3.3.3 Interrupting Servers 7.3.4 Setting and Removing Breakpoints in a Task 7.3.4.1 Setting Location and Event Breakpoints 7.3.4.2 Using a Dump File 7.3.4.3 Debugging a Task Called by Another Task 7.3.4.4 Removing Breakpoints 7.3.5 Running a Task in the ACMS Task Debugger 7.3.6 Checking Values in Workspaces 7.3.6.1 Checking Initial Values 7.3.6.2 Checking Entered Values 7.3.6.3 Checking Values in the ACMS$PROCESSING_STATUS Workspace 7.3.7 Debugging Transaction Timeout Code 7.3.8 Stopping the Task Debugger 7.4 Using the VMS Debugger 7.5 Returning to the ACMSDBG> Prompt 7.6 Debugging Tasks Called from a User-Written Agent Program 8 Debugging an Application in an ACMS Run-Time Environment 8.1 Moving from Debugging to a Run-Time Environment 8.2 Checking Files Needed to Run Tasks Under ACMS 8.3 Debugging Procedure Servers in the Run-Time Environment 8.3.1 Controlling Which Users Can Debug Servers 8.3.2 Using the ACMS/DEBUG/SERVER Command 8.3.3 Replacing a Faulty Server 8.4 Determining Why Servers Stop Unexpectedly 8.4.1 Collecting Server Information in a Dump File 8.4.2 Analyzing Server Process Dumps Part II Reference Material 9 ACMS Programming Services 9.1 ACMS$GET_TID 9.2 ACMS$RAISE_NONREC_EXCEPTION 9.3 ACMS$RAISE_STEP_EXCEPTION 9.4 ACMS$RAISE_TRANS_EXCEPTION 10 ACMS Task Debugger Commands 10.1 @ (At sign) Command 10.2 ACCEPT Command 10.3 ASSIGN Command 10.4 CANCEL BREAK Command 10.5 CANCEL TASK Command 10.6 CANCEL TRANSACTION_TIMEOUT Command 10.7 DEPOSIT Command 10.8 EXAMINE Command 10.9 EXIT Command 10.10 GO Command 10.11 HELP Command 10.12 INTERRUPT Command 10.13 SELECT Command 10.14 SET BREAK Command 10.15 SET SERVER Command 10.16 SET TRANSACTION_TIMEOUT Command 10.17 SHOW BREAK Command 10.18 SHOW SERVERS Command 10.19 SHOW TRANSACTION_TIMEOUT Command 10.20 SHOW VERSION Command 10.21 START Command 10.22 STEP Command 10.23 STOP Command A Summary of ACMS System Workspaces A.1 ACMS$PROCESSING_STATUS System Workspace A.2 ACMS$SELECTION_STRING System Workspace A.3 ACMS$TASK_INFORMATION System Workspace B Libraries Included in AVERTZ Sample Procedures B.1 VR_MESSAGES_INCLUDE.LIB B.2 VR_LITERALS_INCLUDE.LIB B.3 VR_SQL_STATUS_INCLUDE.LIB B.4 VR_CONTEXT_STRUCTURE_INCLUDE.LIB C Superceded Features C.1 ACMSAD$REQ_CANCEL EXAMPLES 1-1 Declaration of Initialization and Termination Procedures in a Task Group Definition 1-2 Declaration of a Step Procedure in a Task Group Definition 1-3 Processing Step in a Task Definition 2-1 SQL Initialization Procedure 2-2 BASIC Initialization Procedure for Rdb/VMS Server 2-3 COBOL Initialization Procedure for VAX DBMS 2-4 BASIC Initialization Procedure for VAX DBMS 2-5 COBOL Initialization Procedure for RMS Server 2-6 BASIC Initialization Procedure for RMS Server 2-7 SQL Termination Procedure 2-8 COBOL Termination Procedure for RMS Files 2-9 BASIC Termination Procedure for RMS Files 2-10 Pseudocode for Using $SETAST 2-11 Server Cancel Procedure in BASIC Using Rdb/VMS with RDO 2-12 Server Cancel Procedure in COBOL for RMS Files 2-13 Server Cancel Procedure in BASIC 3-1 Referencing a Workspace in a Task Definition 3-2 COBOL Procedure that Names a Workspace 3-3 CDD/Plus Record Definition for VR_CUSTOMERS_WKSP Workspace 3-4 Record Description for TASK_CONTROL 3-5 COBOL Procedure for Returning Status in a User-Defined Workspace 3-6 BASIC Procedure for Returning Status in a User-Defined Workspace 4-1 Task Definition that Calls Server Procedures Using SQL 4-2 Declaring the Database 4-3 Lock Specification Example 4-4 Indicator Array for Null Values 4-5 Selecting a Value from a Table 4-6 Writing to a Database 4-7 COBOL Procedure Using SQL with Rdb/VMS 4-8 Step Procedure in COBOL that Reads a VAX DBMS Record 4-9 Step Procedure in BASIC that Reads a VAX DBMS Record 4-10 Step Procedure in COBOL that Updates a VAX DBMS Record 4-11 Step Procedure in BASIC that Updates a VAX DBMS Record 4-12 Step Procedure in COBOL that Reads an FMS Record 4-13 Step Procedure in COBOL that Reads an FMS Record 4-14 Step Procedure in COBOL that Writes an FMS Record 4-15 Step Procedure in BASIC that Updates an FMS Record 5-1 Source File of Messages 6-1 LINK Command for a Procedure that Uses SQL 6-2 LINK Command for Servers Called by Tasks that Use the SQL RECOVERY Phrase 7-1 Task Definition with Breakpoint Symbols 7-2 Sample Task Group Dump File 8-1 Using the SERVER PROCESS DUMP Clause in an Application Definition FIGURES 1-1 Procedure Server Terminology 1-2 Call to a Step Procedure in a Task Definition 3-1 How ACMS Applications Use Workspaces 4-1 Calling the Procedure VR_COMPLETE_CHECKOUT_PROC 5-1 Creating Message Files 6-1 Creating a Procedure Server Image 6-2 Compiling Source Code into Object Modules 6-3 Linking Object Modules into a Procedure Server Image 7-1 Files Needed for Debugging TABLES 2-1 Server Rundown 3-1 Values for ACMS$T_STATUS_TYPE 3-2 Values for ACMS$T_SEVERITY_LEVEL 7-1 Files Needed for Debugging 7-2 Control Characters for the ACMS Task Debugger 7-3 Location Breakpoint Symbols 7-4 Event Breakpoint Symbols 9-1 Summary of the ACMS Programming Services 9-2 Procedure Parameter Notation 10-1 ACMS Task Debugger Commands A-1 Fields in the ACMS$PROCESSING_STATUS Workspace A-2 Field in the ACMS$SELECTION_STRING Workspace A-3 Fields in the ACMS$TASK_INFORMATION Workspace