Guide to Writing DCE Applications

The Guide to Writing DCE Applications is a hands-on programming guide to OSF's Distributed Computing Environment (DCE) for first-time DCE application programmers. This book is designed to help new DCE users make the transition from conventional nondistributed applications programming to distributed DCE programming. Topics include the IDL and ACF files, essential RPC calls, binding methods and the name service, server initialization, memory management, object UUIDs, authentication and authorization (basic security), and other selected advanced topics. Several small, practical programming examples are included. The second edition of this book extends the step-by-step treatment to two advanced topics: object UUIDs and security. Object UUIDs let the client select resources on the server side. Security enforces access on the basis of who the client or server is. This book does not discuss Access Control Lists, a more advanced area of security. We believe the programmer writing her first DCE application will find this book the perfect resource. The Guide to Writing DCE Applications is designed to get the programmer up and running with working examples of client/server applications and to provide a comprehensive model for the development of distributed applications. Contents include: Overview of a distributed application Using a DCE RPC interface (IDL and ACF files) Developing clients Using pointers and arrays Developing a server Using a name service Resource selection through object UUIDs Security (authentication/authorization) for both client and server Using a context handle to maintain server state Using pipes for large quantities of data Quick references Complete code for seven applications, plus Makefiles and directions for building and running

Table of Contents:
Preface. Audience. Related Documentation. Conventions. Book Organization. How to Use this Book. Obtaining the Example Programs FTP. FTPMAIL. BITFTP. UUCP. PC-DCE Examples. Acknowledgments Joint Venture. Chapter 1: Overview of an RPC Application A Simple Interface Universal Unique Identifiers The Interface Definition Stub and Header Generation Using the IDL Compiler A Simple Client A Minimal Server Remote Procedure Implementation A Distributed Application Environment Server Initialization Producing the Application DCE Libraries Compile and Link the Client Code Compile and Link the Server Code Running the Application. Chapter 2: Using a DCE RPC Interface Interface Definition Language (IDL) Attributes Structure of an Interface Definition Interface Header Attributes The Inventory Application Type Definitions, Data Attributes, and Constants Procedure Declarations and Parameter Attributes Using the IDL Compiler Generating Client Files Generating Server Files Using an ACF To Customize Interface Usage Selecting a Binding Method Controlling Errors and Exceptions Excluding Unused Procedures Controlling Marshalling and Unmarshalling. Chapter 3: How to Write Clients Binding Implementing a Binding Method Automatic Binding Management Implicit Binding Management Explicit Binding Management Steps in Finding Servers Finding a Protocol Sequence Finding a Server Host Finding an Endpoint Interpreting Binding Information Finding a Server from a Name Service Database Finding a Server from Strings of Binding Data Customizing a Binding Handle Error Parameters or Exceptions Using Exception Handlers in Clients or Servers Using Remote Procedure Parameters To Handle Errors Compiling and Linking Clients Local Testing. Chapter 4: Pointers and Arrays Kinds of Pointers Pointers as Output Parameters Pointers as Input Parameters Using Pointers to Pointers for New Output Pointers as Procedure Return Values Pointer Summary Kinds of Arrays Selecting a Portion of a Varying Array Managing the Size of a Conformant Array. Chapter 5: How to Write a Server Some Background on Call Processing Initializing the Server Registering Interfaces Creating Server Binding Information Advertising the Server Managing Server Endpoints Listening for Remote Procedure Calls Writing Remote Procedures Managing Memory in Remote Procedures Allocating Memory for Conformant Arrays Compiling and Linking Servers. Chapter 6: Using a Name Service Naming Environment Variables Server Entries Creating a Server Entry and Exporting Binding Information Group Entries Creating a Group Entry and Adding a Member Profile Entries Creating a Profile and Adding Elements Accessing the Database Hierarchy with Default Elements. Chapter 7: Using Object UUIDs Servers and Resources Ways to Advertise and Locate Servers by Resource Advertising and Locating Resources by Name Only Advertising and Locating Resources by Object UUID Object UUIDs and the Binding Process Representing UUIDs An OK Usage Model for Exporting by Resource Initializing the Server Server Manager Code Server Termination Client Initialization Finding a Server Based on Interface Shortcomings A Better Usage Model for Exporting by Resource Initializing the Server Server Manager Code Server Termination Client Initialization Summary. Chapter 8: Using Authenticated RPC The Grade Server Application The DCE Security Model Principals Secret Key Authentication Authorization Authenticated RPC Writing the get_GPA Client Selecting a Protection Level Determining the Server Principal Name Running the get_GPA Client Security Setup Running the Grade Server Application. Chapter 9: Writing a Server that Uses Authenticated RPC Server Login Authenticating the Server Setting the Default Login Context Maintain Server Login Context Manage Server Key Register Principal Name with RPC The Reference Monitor Security Policy Grade Server Reference Monitor Administrative Operations Security Setup CDS set up Running the Grade Server Application. Chapter 10: Context Handles The Remote_file Application Declaring Context in an Interface Definition Using a Context Handle in a Client Binding Handles and Context Handles Managing Context in a Server Writing Procedures That Use a Context Handle Writing a Context Rundown Procedure. Chapter 11: Using Pipes for Large Quantities of Data The Transfer_data Application Defining Pipes in an Interface Definition The Pipe State Using an Input Pipe Using an Input Pipe in a Client Managing an Input Pipe in the Server Using an Output Pipe Using an Output Pipe in a Client Managing an Output Pipe in the Server Managing Multiple Pipes. Appendix A: IDL and ACF Attributes Quick Reference Appendix B: DCE RPC Runtime Routines Quick Reference Appendix C: The Arithmetic Application How To Run the Application Application Files Appendix D: The Inventory Application How To Run the Application Application Files Appendix E: The OK Banking Application How To Run the Application Appendix F: The Better Banking Application How To Run the Application Application Files Appendix G: The Grade Server Application How to Run the Application Application Files Appendix H: The Remote_file Application How To Run the Application Application Files Appendix I: The Transfer_data Application How To Run the Application Application Files. Figures. Chapter 1: Overview of an RPC Application 1-1 Client-server model 1-2 RPC mechanism 1-3 Application development 1-4 Arithmetic application: interface development 1-5 Arithmetic application: client development 1-6 Arithmetic application: server development 1-7 Binding 1-8 Binding information 1-9 Server initializing 1-10 Client finding a server 1-11 Completing a remote procedure call 1-12 Arithmetic application: complete development. Chapter 2: Using a DCE RPC Interface 2-1 Producing an interface. Chapter 3: How to Write Clients 3-1 A comparison of binding management methods 3-2 How a customized binding handle works 3-3 Producing a client. Chapter 5: How to Write a Server 5-1 How the server runtime library handles a call 5-2 Producing a server. Chapter 6: Using a Name Service 6-1 Server entries in the name service database 6-2 A simple use of a name service database 6-3 Group entries in a name service database 6-4 A simple search in a name service database 6-5 Profile entries in a name service database 6-6 Organizing entries in a name service database 6-7 Default elements in a name service database. Chapter 7: Using Object UUIDs 7-1 Inventory server with multiple databases 7-2 Multiple inventory servers 7-3 Resource-based server entries in the name service database 7-4 Object UUIDs in name service database entries 7-5 Exporting by resource 7-6 Importing by resource 7-7 Simple banking example name service database usage 7-8 Example UUID vector 7-9 Banking example using group entries as resource entries Chapter 8: Using Authenticated RPC 8-1 DCE security model for the grade server application 8-2 Kerberos authentication exchange. Chapter 9: Writing a Server that Uses Authenticated RPC 9-1 Major steps in implementing a server 9-2 Establishing the login context 9-3 DCE login 9-4 Reference monitor. Chapter 11: Using Pipes for Large Quantities of Data 11-1 Structure of pipe application code 11-2 Pipe data transfer from a client 11-3 Input pipe data transfer to a server 11-4 Pipe data transfer to a client 11-5 Output pipe data transfer from a server Examples. Chapter 1: Overview of an RPC Application 1-1 A Simple Interface Definition 1-2 A Simple Client 1-3 A Remote Procedure Implementation 1-4 A Minimal Server Initialization. Chapter 2: Using a DCE RPC Interface 2-1 Interface Header Attributes 2-2 IDL Type Definitions 2-3 Defining Strings in IDL 2-4 Defining an Enumerated Type in IDL 2-5 Defining Structures in IDL 2-6 Defining a Discriminated Union in IDL 2-7 A Discriminated Union Generated by the IDL Compiler 2-8 Using a Discriminated Union in Application Code 2-9 Procedure Declarations and Parameter Attributes 2-10 An Attribute Configuration File (ACF). Chapter 3: How to Write Clients 3-1 An ACF for the Implicit Binding Method 3-2 A Client with the Implicit Binding Method 3-3 Adding Binding Handles with an ACF 3-4 Defining a Binding Handle in the Interface Definition 3-5 A Client with the Explicit Binding Method 3-6 Interpreting Binding Information 3-7 Importing a Binding Handle 3-8 Setting a Binding Handle from Strings 3-9 Defining a Customized Binding Handle 3-10 Bind and Unbind Procedures 3-11 A Client with a Customized Binding Handle 3-12 The CHECK_STATUS Macro. Chapter 4: Pointers and Arrays 4-1 Defining an Output Parameter 4-2 Defining Optional Procedure Parameters 4-3 Defining Pointers to Pointers for Memory Allocation 4-4 Defining a Procedure that Returns a Pointer 4-5 How to Determine Kinds of Pointers 4-6 A Conformant Array in an Interface Definition. Chapter 5: How to Write a Server 5-1 Server Header Files and Data Structures 5-2 Registering an Interface with the Runtime Library 5-3 Creating Server Binding Information 5-4 Advertising the Server to Clients 5-5 Managing Endpoints in an Endpoint Map 5-6 Listening for Remote Procedure Calls 5-7 Memory Management in Remote Procedures 5-8 Conformant Array Allocation in a Remote Procedure. Chapter 7: Using Object UUIDs 7-1 Exporting by Resource: Dryer Parts Databases 7-2 Banking Server Header Files and Data Structures 7-3 Registering an Interface with the RPC Runtime Library 7-4 Creating Server Binding Handles 7-5 Advertising by Interface 7-6 Initializing the Object UUID/Resource Map 7-7 Exporting Resources to the Namespace 7-8 Creating a UUID List 7-9 Registering Resources in the Endpoint Map 7-10 Registering a Management Authorization Function 7-11 Listening for Remote Procedure Calls 7-12 Getting an Object UUID and Resource 7-13 Creating and Advertising a New Resource 7-14 Deleting and Removing a Resource 7-15 Shutting Down a Server 7-16 Locating a Server Based on Interface 7-17 Locating a Server Based on Resource 7-18 Binding Handle with an Object UUID from String 7-19 Exporting Resources to the Namespace 7-20 Deleting and Removing a Resource 7-21 Locating a Server Based on Resource. Chapter 8: Using Authenticated RPC 8-1 IDL File for Grade Server Application 8-2 Structure of Client Code 8-3 Inquiring the Server for Its Principal Name 8-4 Administrative Operations To Set Up the Grade Server 8-5 Running the Grade Server Application. Chapter 9: Writing a Server that Uses Authenticated RPC 9-1 Starting the Server from a Shell Script 9-2 Get Grade_Server's Network Credentials 9-3 Starting Up a Thread To Maintain the Login Context 9-4 Starting Up the Key Management Thread 9-5 Register Authentication Information with RPC 9-6 Remaining Server Initialization Code 9-7 Checking Authentication Parameters 9-8 A Reference Monitor 9-9 Administrative Operations Setup 9-10 Setting the Right Permissions in the Namespace 9-11 Running the Application. Chapter 10: Context Handles 10-1 Defining Context Handles 10-2 Using a Context Handle in a Client 10-3 Procedures that Use Context Handles 10-4 A Context Rundown Procedure. Chapter 11: Using Pipes for Large Quantities of Data 11-1 Defining Pipes 11-2 A Pipe Structure Generated by the IDL Compiler 11-3 A Pipe State Structure 11-4 Using an Input Pipe in a Client 11-5 A Client Alloc Procedure for a Pipe 11-6 A Client Pull Procedure for an Input Pipe 11-7 Processing an Input Pipe in a Remote Procedure 11-8 Using an Output Pipe in a Client 11-9 A Client Push Procedure for an Output Pipe 11-10 Processing an Output Pipe in a Remote Procedure 11-11 Processing Multiple Pipes in a Remote Procedure. Appendix C: The Arithmetic Application C-1 The Makefile for the Arithmetic Application C-2 The Client Shell Script for the Arithmetic Application C-3 The Server Shell Script for the Arithmetic Application C-4 The IDL File of the Arithmetic Application C-5 The Client File of the Arithmetic Application C-6 Remote Procedure of the Arithmetic Application C-7 Server Iniialization of the Arithmetic Application C-8 The Check Error Status Macro Appendix D: The Inventory Application D-1 The Makefile for the Inventory Application D-2 The Client Shell Script for the Inventory Application D-3 The IDL File of the Inventory Application D-4 Remote Procedures of the Inventory Application D-5 The Inventory Implementation D-6 Server Initialization of the Inventory Application D-7 The Automatic Client File of the Inventory Application D-8 The Implicit Client of the Inventory Application D-9 The Explicit Client of the Inventory Application D-10 The Makefile for the Implicit Client D-11 An ACF File for Implicit Binding D-12 The do_import_binding Procedure D-13 The do_interpret_binding Procedure D-14 The Makefile for the Explicit Client D-15 An ACF File for Explicit Binding Appendix E: The OK Banking Application E-1 The Makefile for the OK Banking Application E-2 The IDL File of the OK Banking Application E-3 The ACF of the OK Banking Application E-4 Check Error Status Macros E-5 The svr_support.h File E-6 Server Initialization of the OK Banking Application E-7 Remote Procedures of the OK Banking Application E-8 Supporting Functions for the OK Banking Application E-9 Shutdown Procedure for the OK Banking Application E-10 A Client File of the OK Banking Application E-11 Client Import Operations Appendix F: The Better Banking Application F-1 The Makefile for the Better Banking Application F-2 Server Initialization F-3 Remote Procedures F-4 Shutdown Procedure for the Better Banking Application F-5 A Client File of the Better Banking Application F-6 Import Operations in the Better Banking Application Appendix G: The Grade Server Application G-1 The Makefile for the Grade Server Application G-2 The IDL Fill of the Grade Server Application G-3 Client File of the Grade Server Application G-4 Server Initialization of the Grade Server Application G-5 Remote Procedure for the Grade Server Appendix H: The Remote_file Application H-1 The Makefile for the remote_file Application H-2 The IDL File of the remote_file Application H-3 A Client File of the remote_file Application H-4 The get_args Procedure H-5 The do_string_binding Procedure H-6 The Context Rundown of th remote_file Application H-7 Remote Procedures of the remote_file Application H-8 Server Initialization of the remote_file Application Appendix I: The Transfer_data Application I-1 The Makefile for the transfer_data Application I-2 The Float File Generating Utility I-3 The IDL File of the transfer_data Application I-4 A Client that Uses an Input Pipe I-5 A Client that Uses an Output Pipe I-6 Bind and Unbind Procedures I-7 The send_floats Procedure I-8 The receive_floats Procedure I-9 Server Initialization of the transfer_data Application I-10 The pipe_state Structure I-11 The client_alloc Procedure I-12 The in_pull Procedure I-13 The out_push Procedure Tables. Chapter 2: Using a DCE RPC Interface 2-1 IDL Basic Data Types 2-2 Notes on IDL Data Types. Chapter 3: How to Write Clients 3-1 Valid Protocol Sequences. Chapter 4: Pointers and Arrays 4-1 A Summary of Reference and Full Pointers. Chapter 5: How to Write a Server 5-1 Creating Binding Information with Well-known Endpoints. Chapter 10: Context Handles 10-1 Binding Handles and Context Handles in a Call Appendix A: IDL and ACF Attributes Quick Reference A-1 IDL Interface Header Attributes A-2 IDL Array Attributes A-3 IDL Pointer Type Attributes A-4 IDL Data Type Attributes A-5 IDL Structure Member Attributes A-6 IDL Union Case Attributes A-7 IDL Procedure Parameter Attributes A-8 IDL Procedure Attributes A-9 ACF Attributes

About the Author :
John Shirley considers himself a scientist interested in educating himself and others on the use of software tools to analyze and present information. He has developed software and documentation while consulting for companies that include Digital Equipment Corporation, Concurrent Computer Corporation, Inset Systems, The National Association of Securities Dealers (NASDAQ), Tandem Computers, and the Open Software Foundation. John's work has included the development of C programs to demonstrate not only the use of DCE remote procedure calls but also multithreaded programming, an application interface for the GEM graphics environment, and storing scientific data. John earned a B.A. from Alfred University with a dual major in mathematics and geology, an M.S. in geology from Miami University with a specialty in structural geology, and an M.S. in computer science from Pace University. Prior to consulting, John's career included six years in the oil industry as a geophysicist and international explorationist. His work included the analysis of seismic data from New Zealand, Australia, Turkey, Norway, the Dominican Republic, Jamaica, and the United States. John also worked as a software engineer developing programs for scientific instrument manufacturers. John lives in Newtown, Connecticut, where he maintains a consulting business specializing in documenting and demonstrating complex software. Wei Hu was one of the original designers of DCE. At Digital, Wei was the project leader for the team that worked with HP to deliver DCE RPC to the Open Software Foundation. Wei's team developed the connection-oriented RPC protocols, authenticated RPC, and the name service interfaces to the DCE Cell Directory Service. Wei also worked with the OSF and the other DCE technology providers to integrate this software into DCE. Prior to DCE, Wei worked on the VAX Security Kernel: a virtual machine operating system designed for the A1 rating (the highest security rating defined by the U.S. government). In addition to working on various aspects of the kernel, Wei invented a new approach for eliminating a class of security flaws that were previously thought intractable; he then led the team that implemented these safeguards. Before joining Digital, Wei worked for five years at Honeywell Information Systems where he experienced firsthand the challenges involved in building heterogeneous distributed applications without the benefits of a DCE. Wei worked on a number of products including electronic mail, distributed calendars, and gateways. Wei and his wife Irene practice growth through change. Within a six-month period, they had a second child, started writing books, changed jobs, and moved across the country to Silicon Valley. Wei is now with Silicon Graphics Computer Systems, working on server technologies for multimedia and high-availability. Wei received his bachelor's and master's degrees in electrical engineering and computer science from the Massachusetts Institute of Technology in Cambridge, Mass. In addition to this book, Wei coauthored the second edition of the Guide to Writing DCE Applications and has published numerous papers in distributed applications and computer security. He also holds four patents based on his work with security and distributed computing. David Magid was one of the original members of the Digital team that worked with Hewlett Packard to develop the RPC component of DCE. He wrote the RPC Application Programming Interface specification, designed the RPC Name Service Interface (NSI), and implemented portions of the NSI. With his colleagues, David has a patent pending for a DCE namespace usage model. Prior to working on DCE, David's projects at Digital included a prototype knowledgebase system, a data management system for large VAX design and verification, and an automated memories test system. Before joining Digital, David programmed scientific applications at the Woods Hole Oceanographic Institution. He received a bachelor's degree with a dual major in geography/mathematics and a master's degree in environmental affairs from Clark University in Worcester, Massachusetts. David is an avid indoor and outdoor gardener, currently nurturing a new kind of sprout--a daughter, born in July 1993. He is married to a technical writer who's also a wonderful woman and mom. David also enjoys windsurfing and birdwatching and believes that a bad day gardening, windsurfing, or birdwatching is better than a good day at work.