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 Objects 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 the 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 the 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 The ACAS_InvokeMethod Procedure Call 8.2 Determine the Communication Style and Flags 8.2.1 Choosing Synchronous or Asynchronous Invocation 8.3 Building an Attribute List for the ACAS_InvokeMethod Call 8.3.1 Specifying Callback Information 8.3.1.1 Specify Callback Routine Called After Asynchronous Completion 8.3.1.2 Specify ID Passed to Callback After Asynchronous Completion 8.3.2 Specifying Method Resolution Preferences 8.4 Get Context Object Handle 8.5 Determine Instance Handle Style 8.5.1 Instance Handle Fields 8.5.2 How ACA Services Evaluates Instance Handles 8.5.3 Creating Instance Handles 8.5.4 Instance Handle Unique Identifiers 8.6 Build the Argument List 8.6.1 Argument Exchange Between Client and Server 8.6.2 Using Dynamic Arguments 8.6.3 Guidelines for Specifying Arguments 8.6.4 Argument List Building Routines 8.6.5 Argument List De-allocation Routine 8.7 Asynchronous Completion 8.7.1 Asynchronous Callbacks When Replacing the Event Dispatcher and Event Notifier 8.7.2 Using the Flags Argument with the Output Application Handle 8.8 Creating a Long-Lived Instance Handle 8.9 ErrorList and AppErrorList 8.9.1 Determine Error Handling 8.10 Freeing Instance Handles 8.10.1 Releasing Resources 8.11 Coding and Debugging Considerations 8.11.1 Include ACA Services Definition Files 8.11.2 Compiling the Client Code 8.11.3 Debugging Techniques (TRACE) 8.12 Ordering of Invokes and Callbacks 8.13 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.6.1 Registering a Hidden Server 9.6.1.1 Sessionless Handles 9.6.2 Releasing Resources 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 Writing an ACA Services DDE Server 11.1 Making an ACA Services Server DDE Aware 11.1.1 Creating Method Routines 11.2 Generating a Method Dispatcher 11.3 Registering as a DDE Aware Server 11.4 Compiling and Linking the DDE Aware Server 11.4.1 The ACA Services and DDE Environment 12 Advanced Topics 12.1 Defining Your Own Attributes 12.2 Defining Storage Classes 12.3 Creating a Storage Class Definition 12.3.1 Sample Implementation of File Storage Classes 12.4 Scoping 12.5 Specifying a Script Server Class 12.6 Writing a Dispatcher 12.6.1 Writing a DECwindows Dispatcher 12.7 Getting a Context Object Handle Using ACAS_OpenCtxObject 12.8 Reading and Updating the Class Repository Using the API 12.9 Locating Fundamental Class Information 12.10 Changing Storage Class Information 13 Using the Object Request Broker Interface 13.1 Calling ORB Routines 13.1.1 Object References 13.1.2 Determining Error Conditions 13.1.2.1 Exception Routines 13.1.2.2 Exception Checking Examples 13.2 Using Named Value Lists 13.3 Using the Context Object 13.4 Writing an ORB Client 13.4.1 Creating a Request Object 13.4.2 Invoking a Request 13.4.3 Invoking Asynchronous Requests 13.4.4 Releasing Client Resources 13.4.5 Sample Client Program 13.5 Writing an ORB Server 13.5.1 Writing Methods 13.5.2 Server Main Routine 13.5.3 Request Dispatching 13.5.4 Releasing Resources 13.5.5 Sample Server Program 13.6 Linking and Compiling ORB Client and Server Code 13.7 Mapping the ACA Services Interface with the ORB Interface A Key ACA Services Files B ACA Services Attribute Locator Table B.1 Master ACA Services Attribute Table Glossary EXAMPLES 3-1 Sample COL Context Object Definition 3-2 Using Logicals for VMS Context Object Names 3-3 Using Environment Variables for ULTRIX Context Object 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 a Data Object Class Instance Handle 8-6 Format for a ACAS_GetInstanceHandleId Call 8-7 Code Fragment Using ACAS_GetInstanceHandleId 8-8 Sample Argument List 8-9 Sample Dynamic Arguments 8-10 Specifying a Callback Routine in an Attribute List 8-11 Callback Routine Form 8-12 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 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 DDE Register Server Example 12-1 Application-defined Attribute Example 12-2 VMS FILE Sample Storage Class Definition 12-3 Sample File System Storage Class 12-4 Sample ACAS_FILE_EXTENSIONS Table 12-5 Scoping: Data Object Definitions 12-6 Scoping: Application Definitions 12-7 Event Notifier and Dispatcher Sample Code 12-8 Example of DECwindows Integration Code 13-1 Handling Error Conditions 13-2 Error Handling When ORBStatus Is Not Returned 13-3 Sample Client Code 13-4 Sample Server 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 Interaction of the Control Server and Method Servers 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 12-1 Fundamental Classes and Storage Classes 12-2 Example Storage Class 12-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 ACAS_InvokeMethod Arguments 8-2 Using the ACAS_InvokeMethod Procedure Call 8-3 Using Flags on ACAS_InvokeMethod Call 8-4 API Operations for ACAS_GetCtxHandle 8-5 Instance Handle Fields 8-6 Instance Handle Referencing a Data Object Class 8-7 Instance Handle Referencing a Storage Class 8-8 Instance Handle Referencing an Application Class 8-9 Supported Datatypes 8-10 Defined Arguments 8-11 Client Argument List Contents: Example 1 8-12 Client Argument List Contents: Example 2 8-13 Client Argument List Contents: Example 3 8-14 Client Argument List Contents: Example 4 8-15 NULL Argument Behavior 8-16 Callback Routine Values 8-17 TRACE Output Flags 9-1 Writing an ACA Services Method Server 9-2 External Definitions Created by GENERATE 9-3 Server Attributes 9-4 Invocation Context Information 9-5 Valid Flags Values for Invocation Context 9-6 Errors Returned as Function Values 9-7 Rules for Method Routines 9-8 Server Flags 9-9 Server Attributes 9-10 Files Created for Server Startup Debugging 10-1 Script Convenience Commands 11-1 DDE Messages 12-1 Valid Items in the GetInstance and SetInstance Item Lists 12-2 Storage Class Messages 12-3 DECwindows Dispatcher Calls 12-4 API Operations for ACAS_OpenCtxObject 12-5 Order of API Operations 12-6 Operations for ACAS_GetCtxHandle 13-1 Standard ORB Exceptions 13-2 Flags Values for ORB_Request_invoke 13-3 Server Attributes 13-4 ORB Libraries Used for Linking ORB Programs 13-5 Mapping of Concepts 13-6 Mapping of Routines A-1 ULTRIX File Names and Directories A-2 VMS File Names and Directories B-1 ACA Services Attributes