CONTENTS

  Title Page

  Copyright Page

  Information Map

  Information Table

  Preface

  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 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 Databases Using RDO
      2.1.5      Initialization Procedures for 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 Databases Using SQL
      2.2.2      Termination Procedures for Rdb Databases Using RDO
      2.2.3      Termination Procedures for 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 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
      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 Transaction Mode and Lock Mode Specifications
        4.1.3.4      Using an Rdb 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
    4.2 Using Precompiled RDO or RDML with Rdb
      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 Procedures that Use RDO
    4.3 Using DBMS
      4.3.1      Using DBMS DML Statements in Step Procedures
      4.3.2      Starting and Ending a DBMS Database Transaction
        4.3.2.1      Starting a DBMS Database Transaction that Is Part of a Distributed Transaction
        4.3.2.2      Starting and Ending an Independent DBMS Database Transaction
        4.3.2.3      Using DBMS Access and Allow Mode Specifications
        4.3.2.4      Using a 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 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 OpenVMS 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 Superseded Features
    C.1 ACMSAD$REQ_CANCEL