CONTENTS

  Title Page

  Copyright Page

  Preface

  1      Introduction to ACA Services

  1.1     Integrating the Enterprise
    1.1.1      Challenge:  System Evolution
    1.1.2      Challenge:  Distributed Environments
    1.1.3      Challenge:  PCs Encourage Decentralization
    1.1.4      Challenge:  Competing Platforms
    1.1.5      Solution:  ACA Services Integrates Distributed Systems

  1.2     Analyzing a System and Planning Integration

  1.3     ACA Services CASE Example

  1.4     The Basics
    1.4.1      Object-Oriented Building Blocks
    1.4.2      ACA Services Fundamental Classes
    1.4.3      Modeling an Application
    1.4.4      ACA Services Scripting Features
    1.4.5      Recording Information About an Application
    1.4.6      Abstract Classes and Common Classes
    1.4.7      Recording Information about an Application User
    1.4.8      Clients and Servers
    1.4.9      How ACA Services Works

  1.5     ACA Services Built-Ins

  1.6     Typical ACA Services Integration Models

  1.7     Suggested Reading Paths

  2      ACA Services Operation

  2.1     Requesting a Service

  2.2     Invocation

  2.3     Method Resolution
    2.3.1      Method Selection
    2.3.2      Server Selection

  2.4     Starting and Providing a Service

  3      Context Object and Class Repository

  3.1     Contents of the Context Object
    3.1.1      Logical Structure of the Context Object
    3.1.2      Creating and Maintaining the Context Object
      3.1.2.1      Using the Command Line Interface
      3.1.2.2      Using the Application Program Interface
    3.1.3      Guidelines for Context Object
      3.1.3.1      Guidelines for Specifying a Context Object
      3.1.3.2      Guidelines for Attribute Values Using Environment Variables
      3.1.3.3      Guidelines for Adding to the Context Objects
    3.1.4      Debugging a Context Object

  3.2     Contents of the Class Repository
    3.2.1      Logical Structure of Class Repository
    3.2.2      Creating and Maintaining the Class Repository
      3.2.2.1      Using the Command Line Interface
      3.2.2.2      Using the Application Program Interface
    3.2.3      Guidelines for Class Repositories
      3.2.3.1      Guidelines for Specifying Class Repositories
      3.2.3.2      Guidelines for Naming Class Repository Objects
      3.2.3.3      Guidelines for Class Inheritance
      3.2.3.4      Guidelines for Sharing Repositories
      3.2.3.5      Guidelines for Accessing and Updating Repositories

  4      Modeling Applications

  4.1     Modeling the Interface

  4.2     Modeling the Implementation

  4.3     Joining the Interface and the Implementation

  4.4     Levels of Interface Abstraction

  4.5     Organizing the Implementation

  5      Defining an Application's Interface

  5.1     Elements of the Interface
    5.1.1      Defining Applications
    5.1.2      Defining Data Objects
    5.1.3      Defining Messages
    5.1.4      Using Abstract Classes
    5.1.5      Using Common Classes

  5.2     Creating an Application Class Definition

  5.3     Creating a Data Object Class Definition

  5.4     Defining Messages on Applications and Data Objects
    5.4.1      Scoping Classes

  5.5     Example Application and Data Objects

  6      Defining an Application's Implementation

  6.1     Elements of the Implementation
    6.1.1      Defining Method Servers
    6.1.2      Defining Methods

  6.2     Creating a Method Server Class Definition
    6.2.1      Method Server Attributes
      6.2.1.1      Matching the Method Server to an Application
      6.2.1.2      Specifying the Method Server Dispatcher
      6.2.1.3      Specifying How a Method Server Is Started
      6.2.1.4      Identifying the Method Server Image
      6.2.1.5      Identifying Attributes in the Context Object
      6.2.1.6      Identifying the Method Server Platform

  6.3     Creating a Method Class Definition
    6.3.1      Defining a Server's Startup Environment
      6.3.1.1      Optimizing Method Loading
      6.3.1.2      How Dynamic Loading Works
      6.3.1.3      Specifying a Dynamically Loaded Method

  6.4     Specifying Server Interaction
    6.4.1      Specifying Local and Remote Servers
    6.4.2      Specifying ``Startup Only'' Servers
    6.4.3      Specifying a Built-in Server
      6.4.3.1      Advantages of Built-ins
      6.4.3.2      Defining Client-Side Built-ins

  7      Joining the Interface and Implementation

  7.1     Referencing Methods
    7.1.1      Specifying an Indirect Reference

  7.2     The Method Selection Process

  7.3     The Server Selection Process

  7.4     The Server Startup Process

  7.5     Using Attributes to Control Method Resolution
    7.5.1      Method Selection:  Specifying the Attributes
    7.5.2      Method Selection:  Specifying the Context Object Tables
    7.5.3      Method Selection:  Specifying the Context Object Scope
    7.5.4      Method Selection:  Specifying the Scope
    7.5.5      Server Selection:  Specifying the Attributes
    7.5.6      Server Selection:  Specifying the Context Object Tables
    7.5.7      Server Selection:  Specifying the Context Object Scope
    7.5.8      Server Startup:  Specifying the Attributes
    7.5.9      Server Startup:  Specifying the Allowable Nodes

  7.6     Linking Storage Classes with a Method Invocation

  8      Writing a Client Program

  8.1     When an Application is Also a Client

  8.2     Overview of Creating a Client

  8.3     The ACAS_InvokeMethod Procedure Call

  8.4     Determine the Communication Style and Flags
    8.4.1      Choosing Synchronous or Asynchronous Methods

  8.5     Building an Attribute List for ACAS_InvokeMethod Call
    8.5.1      Specifying Callback Information
      8.5.1.1      Specify Callback Routine Called After Asynchronous Completion
      8.5.1.2      Specify ID Passed to Callback After Asynchronous Completion
    8.5.2      Specifying Method Resolution Preferences

  8.6     Get Context Object Handle

  8.7     Determine Instance Handle Style
    8.7.1      Instance Handle Fields
    8.7.2      How ACA Services Evaluates Instance Handles
    8.7.3      Creating Instance Handles

  8.8     Build the Argument List
    8.8.1      Argument Exchange Between Client and Server
    8.8.2      Using Dynamic Arguments
    8.8.3      Guidelines for Specifying Arguments
    8.8.4      Argument List Building Routines
    8.8.5      Argument List Deallocation Routine

  8.9     Asynchronous Completion
    8.9.1      Using the Flags Argument with the Output Application Handle

  8.10    Creating a Long-Lived Instance Handle

  8.11    ErrorList and AppErrorList
    8.11.1     Determine Error Handling

  8.12    Freeing Instance Handles

  8.13    Coding and Debugging Considerations
    8.13.1     Include ACA Services Definition Files
    8.13.2     Debugging Techniques (TRACE)

  8.14    Client Code Example

  9      Writing a Method Server

  9.1     Generating the Method Dispatcher Routine

  9.2     Specifying Server Attributes
    9.2.1      Terminating a Server

  9.3     Writing the Methods
    9.3.1      Using the Invocation Context
    9.3.2      Returning the Method Status

  9.4     Working With Method Arguments

  9.5     Developing a Server Main Routine
    9.5.1      Including the ACA Services Definition Files

  9.6     Performing a Registration Call

  9.7     Compiling and Linking the Server Code

  9.8     Example of an ACA Services Method Server
    9.8.1      Linking Without DECnet on ULTRIX

  9.9     Debugging a Method Server

  9.10    Debugging Server Startup

  9.11    Stopping a Method Server Process

  10     Scripts and Script Servers

  10.1    Integrating Applications Using Scripts

  10.2    Identifying Scripts to ACA Services
    10.2.1     Specifying the Invocation String Directly
    10.2.2     Specifying the Invocation String Indirectly

  10.3    Supplying Parameters to Scripts
    10.3.1     Specifying Substitution Directives
      10.3.1.1     Rules for Creating Substitution Directives
      10.3.1.2     Changing the Introducer Character
    10.3.2     Using Script Convenience Commands

  10.4    Defining a Script Method Class

  10.5    Script Method Completion

  10.6    Directly Invoking a Script from a Client Program

  11     Advanced Topics

  11.1    Locating Fundamental Class Information

  11.2    Changing Storage Class Information

  11.3    Defining Your Own Attributes

  11.4    Defining Storage Classes

  11.5    Creating a Storage Class Definition
    11.5.1     Sample Implementation of File Storage Classes

  11.6    Scoping

  11.7    Specifying a Script Server Class

  11.8    Writing a Dispatcher
    11.8.1     Using the Event Dispatcher
    11.8.2     Writing a DECWindows Dispatcher

  11.9    Getting a Context Object Handle Using ACAS_OpenCtxObject

  11.10  Reading and Updating the Class Repository Using the API

  A   Platform Comparison Table

  B   ACA Services Attribute Locator Table

  Glossary

  EXAMPLES

  3-1        Sample COL Context Object Definition

  3-2        Using Environment Variables for VMS Class Repository Names

  3-3        Using Environment Variables for ULTRIX Class Repository Names

  3-4        Sample CRL Class Definition

  5-1        Application Class Definition

  5-2        Data Object Class Definition

  6-1        Method Server Class Definition

  6-2        Method Class Definition

  6-3        Code Fragment Showing Method Server Startup Environment Definition

  6-4        Code Fragment Showing Context Object Server Startup Environment Definition

  6-5        Dynamic Load Example

  6-6        Using a Wildcard for an Attribute

  6-7        Sample ``Startup Only'' Definition

  6-8        Registering a Server and Server Dispatcher

  7-1        Sample Method Map:  Direct References

  7-2        Sample Method Map:  Indirect References

  7-3        Example Method Selection Attributes

  7-4        Example Context Object Selection Tables

  8-1        Code Fragment for Invoking a Method

  8-2        Code Fragment Showing ACAS_INVOKE_ASYNCH Flag

  8-3        Example of Building an Attribute List

  8-4        Code Fragment Using ACAS_GetCtxHandle

  8-5        Code Fragment for Creating an Data Object Class Instance Handle

  8-6        Sample Argument List

  8-7        Sample Dynamic Arguments

  8-8        Specifying a Callback Routine in an Attribute List

  8-9        Callback Routine Form

  8-10       Code for a Client Program

  9-1        Sample Terminate Routine

  9-2        Sample Method Routine

  9-3        CRL Code Fragment for Message

  9-4        CRL Code Fragment for Method

  9-5        Code Fragment for Method Function

  9-6        Sample Invocation Context Code

  9-7        Data Definitions for Event Dispatching and Notification

  9-8        Defining Variables for Registration

  9-9        Sample Attribute List for Registration

  9-10       Code for a Method Server Program

  9-11       Code Fragment for Non-DECnet Installations

  10-1       Identifying a Script Directly

  10-2       Identifying a Script Indirectly: CRL Sample

  10-3       Script Invocation String for VMS System in Context Object Names Registry Table

  10-4       Script Invocation String for ULTRIX System in Context Object Names Registry Table

  10-5       Defining a Different Introducer Character

  10-6       VMS Script Using Script Convenience Commands

  10-7       Script Method Class Definition

  10-8       Invoking a Script from a Client

  11-1       Application-defined Attribute Example

  11-2       Storage Class Definition

  11-3       Sample ACAS_FILE_EXTENSIONS Table

  11-4       Scoping:  Data Object Definitions

  11-5       Scoping:  Application Definitions

  11-6       Event Notifier and Dispatcher Sample Code

  11-7       Example of DECWindows Integration Code

  FIGURES

  1-1        Single Application/Single Platform Model

  1-2        Client/Server Model

  1-3        ACA Services Model

  1-4        CASE Example Tools

  1-5        CASE Tools Interactions

  1-6        Editor Classes

  1-7        Editor Messages

  1-8        Editor Messages and Methods

  1-9        Inheritance

  1-10       ACA Services Fundamental Classes

  1-11       Editor Classes Under Fundamental Classes

  1-12       Server Process, Image, and Method Server

  1-13       Control Server

  3-1        Context Object

  3-2        Context Object Overrides and Failovers

  3-3        Adding Attributes to a Context Object

  3-4        Class Repository

  4-1        Application Modeling:  Interface and Implementation

  5-1        Fundamental Classes:  Defining the Interface

  5-2        Example Application Class

  5-3        Example Data Object Class

  5-4        Example Application and Data Object Class

  6-1        Fundamental Classes:  Defining the Implementation

  6-2        Example Method and Method Server

  7-1        Example of Joined Interface and Implementation

  10-1       Script Classes Below Fundamental Classes

  11-1       Fundamental Classes and Storage Classes

  11-2       Example Storage Class

  11-3       Using Scoping

  TABLES

  1 Symbol Conventions

  2 Typeface Conventions

  1-1        Topic Readings

  2-1        Sample Selection Attributes

  2-2        Sample Context Object (User Preferences)

  2-3        Sample Method Map

  2-4        Sample Method Attributes

  2-5        Results of Method Resolution Example

  2-6        Selection Attribute Results

  3-1        ACA Services-Recognized Context Object Tables

  3-2        Default Context Object Filenames

  3-3        Default Location and Name of System Class Repository

  5-1        Datatypes Supported for Message Arguments

  5-2        Argument Passing Mechanisms

  5-3        Message Attributes

  6-1        Method Server Attributes and Values

  6-2        Method Attributes and Values

  7-1        Attributes Affecting Method Selection

  7-2        Attributes Affecting Server Selection

  7-3        Attributes Affecting Startup

  7-4        Context Object Attributes Affecting Startup

  8-1        Creating a Synchronous Client

  8-2        Creating an Asynchronous Client

  8-3 ACAS_InvokeMethod Arguments

  8-4        Using the ACAS_InvokeMethod Procedure Call

  8-5        Using Flags on ACAS_InvokeMethod Call

  8-6        API Operations for ACAS_GetCtxHandle

  8-7        Instance Handle Fields

  8-8        Instance Handle Referencing a Data Object Class

  8-9        Instance Handle Referencing a Storage Class

  8-10       Instance Handle Referencing an Application Class

  8-11       Supported Datatypes

  8-12       Defined Arguments

  8-13       Client Argument List Contents: Example 1

  8-14       Client Argument List Contents: Example 2

  8-15       Client Argument List Contents: Example 3

  8-16       Client Argument List Contents: Example 4

  8-17       NULL Argument Behavior

  8-18       Callback Routine Values

  8-19       TRACE Output Flags

  9-1        Writing an ACA Services Method Server

  9-2        External Definitions Created by GENERATE

  9-3        Sever Attributes

  9-4        Invocation Context Information

  9-5        Errors Returned as Function Values

  9-6        Rules for Method Routines

  9-7        Server Flags

  9-8        Server Attributes

  9-9        Files Created for Server Startup Debugging

  10-1       Script Convenience Commands

  11-1       Storage Class Messages

  11-2       DECWindows Dispatcher Calls

  11-3       API Operations for ACAS_OpenCtxObject

  11-4       Order of API Operations

  11-5       Operations for ACAS_GetCtxHandle

  A-1        File Names and Directories

  B-1        ACA Services Attributes