IBMpublib.boulder.ibm.com/tividd/td/ADE/fsm/en_US/PDF/fsm.pdf · 2002-11-09 · Framework Services Manual i TME 10 ADE Framework Services Manual Preface

Framework Services Manual

Version 3.6

September 1998

Framework Services Manual (September 1998)Copyright NoticeCopyright © 1998 by Tivoli Systems, an IBM Company, including this documentation and all software.All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement orAddendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication maybe reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computerlanguage, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, orotherwise, without prior written permission of Tivoli Systems. The document is not intended forproduction and is furnished “as is” without warranty of any kind.All warranties on this document arehereby disclaimed including the warranties of merchantability and fitness for a particular purpose.

Note to U.S. Government Users—Documentation related to restricted rights—Use, duplication ordisclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation.

TrademarksThe following product names are trademarks of Tivoli Systems or IBM Corporation: AIX, IBM, OS/2,RS/6000, Tivoli Management Environment, and TME 10.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks ofMicrosoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively throughX/Open Company Limited.

Other company, product, and service names mentioned in this document may be trademarks orservicemarks of others.

NoticeReferences in this publication to Tivoli Systems or IBM products, programs, or services do not imply thatthey will be available in all countries in which Tivoli Systems or IBM operates. Any reference to theseproducts, programs, or services is not intended to imply that only Tivoli Systems or IBM products,programs, or services can be used. Subject to Tivoli Systems’ or IBM’s valid intellectual property or otherlegally protectable right, any functionally equivalent product, program, or service can be used instead ofthe referenced product, program, or service. The evaluation and verification of operation in conjunctionwith other products, except those expressly designated by Tivoli Systems or IBM, are the responsibilityof the user.

Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in thisdocument. The furnishing of this document does not give you any license to these patents. You can sendlicense inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue,Thornwood, New York 10594.

Framework Services Manual i

TME 10 ADE FrameworkServices Manual

Preface................................................................................................................... ix

Chapter 1—Distributed Object SystemsObject-oriented Programming Concepts.............................................................1-2

Object Communication...............................................................................1-4

Objects as Models ......................................................................................1-5

Inheritance .........................................................................................1-6

Multiple Inheritance...........................................................................1-8

Polymorphic Messages...............................................................................1-9

Interfaces ..................................................................................................1-10

Implementation.........................................................................................1-11

Object Classes...................................................................................................1-12

Objects as Instances of a Class.................................................................1-13

Class Inheritance ......................................................................................1-14

Object-oriented Distributed Systems ................................................................1-14

Common Object Request Broker .............................................................1-16

CORBA Object Model .............................................................................1-16

Object Identification ........................................................................1-16

Operation Semantics........................................................................1-17

Chapter 2—Common Object Request Broker ArchitectureHeterogeneous Networks ....................................................................................2-2

OMG-specified CORBA.....................................................................................2-2

Client and Object Implementation Relationships ...............................................2-4

TME 10 Clients and Object Implementations............................................2-5

The TME 10 ORB ......................................................................................2-6

Client Requests...........................................................................................2-6

Object Implementation Returns..................................................................2-8

ii Version 3.6

Data Marshaling and Unmarshaling........................................................... 2-8

ORB Interfaces ................................................................................................... 2-9

Client Stubs ................................................................................................ 2-9

Dynamic Invocation Interface.................................................................. 2-10

Server Skeletons....................................................................................... 2-12

Data Translation .............................................................................. 2-12

Method Presentation........................................................................ 2-12

Other ORB Interfaces............................................................................... 2-12

TME 10 Basic Object Adapter (BOA) ............................................................. 2-13

The TME 10 ORB Implementation .................................................................. 2-15

Process Boundaries .................................................................................. 2-16

Cascaded Calls ......................................................................................... 2-18

Dynamic Invocation ................................................................................. 2-22

Persistent Attribute Storage...................................................................... 2-24

Persistent Storage and Transactions......................................................... 2-26

Chapter 3—IDL-Defined InterfacesInterface and Implementation Separation ........................................................... 3-2

Introduction to OMG IDL................................................................................... 3-4

CORBA-compliant Interfaces............................................................................. 3-5

Interface Inheritance................................................................................... 3-5

IDL-defined Interfaces ............................................................................... 3-6

IDL Specification................................................................................................ 3-7

IDL Declarations........................................................................................ 3-9

IDL Type Declaration...................................................................... 3-10

IDL Constant Declaration................................................................ 3-14

IDL Exception Declaration.............................................................. 3-14

IDL Module Definition ............................................................................ 3-14

IDL Interface Definition .......................................................................... 3-16

Interface Header .............................................................................. 3-16

Interface Body ................................................................................. 3-18

IDL Operation Declarations..................................................................... 3-19

Framework Services Manual iii

Operation Parameters.......................................................................3-19

Parameter Mapping..........................................................................3-20

Raising Exceptions ..........................................................................3-21

IDL Attribute Declaration ........................................................................3-24

Attribute Mapping ...........................................................................3-25

IDL Preprocessor Directives ....................................................................3-26

IDL Naming Scopes..........................................................................................3-28

Additional IDL Information..............................................................................3-31

Chapter 4—TME 10 ADE Extended IDLTME 10 Classes ..................................................................................................4-2

Classless Objects ........................................................................................4-2

Abstract Class Objects................................................................................4-3

Instantiable Class Objects ..........................................................................4-3

Metaclasses.................................................................................................4-4

New Class Creation....................................................................................4-7

Object Creation from a Class .....................................................................4-8

Implementation ...................................................................................................4-8

Multiple Implementations of the Same Interface.......................................4-9

Implementation Inheritance......................................................................4-10

Introduction to TME 10 ADE Extended IDL ...................................................4-11

Introduction to TEIDL Implementation Specification .............................4-12

Sample Implementation Preprocessor Directive .............................4-14

Sample Class and Method Specification .........................................4-14

Introduction to TEIDL Program Specification.........................................4-15

Sample Program Preprocessor Directive .........................................4-16

Sample Program Specification ........................................................4-16

Introduction to TEIDL Installation Specification ....................................4-16

Sample Installation Preprocessor Directive.....................................4-19

Sample Installation Specification ....................................................4-20

Object Implementation.............................................................................4-22

Implementation Specification Constructs .........................................................4-23

iv Version 3.6

TEIDL Implementation Specification...................................................... 4-23

Implementation Header ................................................................... 4-23

Implementation Body ...................................................................... 4-25

Program Specification Constructs .................................................................... 4-34

TEIDL Program Specification ................................................................. 4-34

Program Header............................................................................... 4-34

Program Body.................................................................................. 4-35

Scope Resolution for Program Specifications.......................................... 4-39

Installation Specification Constructs ................................................................ 4-40

TEIDL Installation Specification ............................................................. 4-40

Installation Header........................................................................... 4-40

Installation Body ............................................................................. 4-41

Scope Resolution for Installation Specification....................................... 4-55

TEIDL Implementation Preprocessor Directives ............................................. 4-55

TEIDL Compiler Output................................................................................... 4-55

TME 10 Output ........................................................................................ 4-57

TME 10 Nested Transactions .......................................................... 4-57

TME 10 Exceptions......................................................................... 4-57

TME 10 Files................................................................................... 4-59

CORBA Output........................................................................................ 4-59

Common Output....................................................................................... 4-60

File Descriptions ...................................................................................... 4-61

TME 10 Stub Wrappers................................................................... 4-61

TME 10 Skeleton Liners ................................................................. 4-61

Method Templates ........................................................................... 4-62

Public Header Files.......................................................................... 4-64

Private Header Files ........................................................................ 4-66

Defines Header ................................................................................ 4-67

Configuration Script ........................................................................ 4-68

Building a Client-Server Program............................................................ 4-68

ANSI C Binding ............................................................................................... 4-69

Framework Services Manual v

Example Input Files..................................................................................4-69

example.idl.......................................................................................4-69

example.imp.....................................................................................4-69

example.prog ...................................................................................4-70

example.ist .......................................................................................4-70

Example Output Files...............................................................................4-70

Bourne Shell Binding........................................................................................4-75

Special Characters ....................................................................................4-75

Basic Types ..............................................................................................4-76

Constructed Types....................................................................................4-77

Bourne Shell Method Implementations....................................................4-79

Example Bourne Shell Method Implementation......................................4-81

shell_ex::test::op ..............................................................................4-81

shell_ex::test::_get_attr....................................................................4-82

shell_ex::test::_set_attr ....................................................................4-82

Command Method Binding...............................................................................4-83

TEIDL Compiler Operation..............................................................................4-83

TEIDL BNF Grammar Description ..................................................................4-84

Implementation Grammar ........................................................................4-85

Program Grammar....................................................................................4-86

Installation Grammar................................................................................4-87

Chapter 5—Object ImplementationTME 10 Objects..................................................................................................5-2

TME 10 Objects are Uniquely Identified ...................................................5-2

TME 10 Objects are Modular.....................................................................5-3

TME 10 Objects Distinguish between Attributes and Behavior ................5-4

Object Attributes................................................................................5-5

Object Methods..................................................................................5-5

TME 10 Objects are Dynamic....................................................................5-5

TME 10 Objects are Reusable....................................................................5-6

TME 10 Objects Interact with Other Objects.............................................5-7

vi Version 3.6

Concurrent Interaction....................................................................... 5-7

Dynamic Relationships among TME 10 Objects....................................... 5-8

Class Relationships............................................................................ 5-8

Inheritance Relationships .................................................................. 5-8

Reference Relationships .................................................................. 5-12

TME 10 Objects are Persistent................................................................. 5-13

TME 10 Implementation Models...................................................................... 5-13

Server Types............................................................................................. 5-13

Server Execution ...................................................................................... 5-14

Shared and Unshared Servers.......................................................... 5-14

Parallel and Non-parallel Servers.................................................... 5-15

Servers Per Method........................................................................................... 5-15

Daemon Servers................................................................................................ 5-16

Considerations for Daemon Servers......................................................... 5-17

Queuing Delays ............................................................................... 5-17

Daemon Server Deadlocks .............................................................. 5-17

Object Contexts in Daemon Servers................................................ 5-20

Parallel Servers ................................................................................................. 5-21

Advantages of Parallel Server Implementations ...................................... 5-22

Disadvantages of Parallel Server Implementations.................................. 5-22

Mutexes .................................................................................................... 5-23

Race Conditions ....................................................................................... 5-24

Thread Deadlocks..................................................................................... 5-24

Thread-safe Programming Techniques .................................................... 5-25

Parallel Server Implementation................................................................ 5-26

Spawning New Threads................................................................... 5-26

Available Semaphores ..................................................................... 5-27

Available Timer Services ................................................................ 5-27

Calling POSIX Signals .................................................................... 5-28

POSIX Thread Routines........................................................................... 5-28

Framework Services Manual vii

TME 10 Concurrence........................................................................................5-31

Protection Domains ..................................................................................5-34

State and Serialization..............................................................................5-34

Locking Mechanisms ...............................................................................5-36

Critical Section Locking ..................................................................5-37

Transaction Duration Locks ............................................................5-48

Deadlocks and Avoidance........................................................................5-51

Avoidance and Transaction Duration Locks ...................................5-51

Avoidance and Critical Section Locks ............................................5-53

A Final Word about TME 10 Class Systems ....................................................5-55

Chapter 6—TME 10 Clients and the TME 10 Run-timeTME 10 Service Requests...................................................................................6-1

Client Stubs ................................................................................................6-2

Calling a Client Stub from a C Program............................................6-2

Calling a Client Stub from a Shell Script ..........................................6-3

Dynamic Invocation Interface....................................................................6-3

Command Line Interface............................................................................6-9

idlcall .................................................................................................6-9

Examples of idlcall ..........................................................................6-10

idlattr................................................................................................6-11

CORBA Memory Management ........................................................................6-11

Available APIs ..................................................................................................6-12

TME 10 Run-time Functions....................................................................6-12

tmf_init_t tmf_init(type_repository *types[]); ................................6-12

int tmf_client_init(void); .................................................................6-13

void tmf_client_exit(void); ..............................................................6-13

int tmf_run(struct timeval *tv); .......................................................6-13

void tmf_server_exit(void); .............................................................6-13

Object tmf_locate_orb(); .................................................................6-14

Object tmf_locate_boa(); .................................................................6-14

char *exception_id(Environment *ev); ...........................................6-14

viii Version 3.6

void *exception_value(Environment *ev); ..................................... 6-14

void exception_free(Environment *ev);.......................................... 6-14

Run-time Exceptions ....................................................................... 6-14

Object Interface........................................................................................ 6-16

tmf_boolean Object_is_equal (Object obj1, Environment *env, Object object); 6-17

tmf_boolean t_Object_is_equal (Object obj1, Environment *env, Object object); 6-17

tmf_boolean Object_isa (Object _ob, Environment *_ev, TypeCode intf);6-18

tmf_boolean t_Object_isa (Object _ob, Environment *_ev, TypeCode intf);6-18

Pseudo-object Interfaces .......................................................................... 6-18

ORB................................................................................................. 6-18

BOA................................................................................................. 6-20

TypeCode ........................................................................................ 6-21

Preface

Framework Services Manual ix

PrefaceTME 10 (Tivoli Management Environment 10) is a powerfulenvironment in which to manage applications for distributed systems.The TME 10 ADE (Application Development Environment) providesthe added advantage of access to an equally powerful developmentenvironment.

TME 10 ADE is compatible with the features specified by theCommon Object Request Broker Architecture (CORBA) Version 1.1,which is provided by the Object Management Group (OMG). TheCORBA specification defines a client/server system in which the clientand server are separated. The CORBA specification stipulates the useof object encapsulation to achieve this separation, which improves thedevelopment process on distributed, heterogeneous networks.

This manual describes the way in which TME 10 ADE implements theOMG CORBA Specification.

Who Should Read This ManualThis manual explains the required concepts for developingapplications for a distributed, heterogeneous environment using TME10 ADE. You should have a knowledge of the UNIX operating systemand the C programming language before reading this manual.

Prerequisite and Related DocumentsThe information in this manual complements information presented inthree other manuals, which you should read in the following order afterreading this manual:

1. TheApplication Services Manual, which describes high-levelservices available from the TME.

2. TheDesktop Services Manual,which explains how to develop aGraphical User Interface (GUI) for your application.

3. Application Development with TME 10 ADE, which presents asample application, explains how the application was developed,and provides tips on how to efficiently develop an application.

Preface

x Version 3.6

What This Manual ContainsTheFramework Services Manual provides the following information:

■ Chapter 1, “Distributed Object Systems”Provides an introduction to distributed computer networks andobject oriented programming concepts.

■ Chapter 2, “Common Object Request Broker Architecture”Describes the Common Object Request Broker (ORB)Architecture and the TME 10 ADE implementation of thatarchitecture.

■ Chapter 3, “IDL-Defined Interfaces”Describes CORBA compliant interfaces and how to define them.

■ Chapter 4, “TME 10 ADE Extended IDL”Describes program implementation and how to specify suchimplementations.

■ Chapter 5, “Object Implementation”Describes the behavior of TME 10 objects and how to implementthose objects.

■ Chapter 6, “TME 10 Clients and the TME 10 Run-time”Describes the services and APIs associated with implementingTME 10 client programs and the TME 10 run-time.

Conventions Used in This ManualThe manual uses several typeface conventions for special terms andactions. These conventions have the following meaning:

Bold Commands, keywords, file names, or otherinformation that you must use literally appear inbold.Names of windows, dialogs, and other controls alsoappear inbold.

Italics Variables and values that you must provide appear initalics.

Bold Italics New terms appear in bold italics when they aredefined in the text.

Monospace Code examples appear in amonospace font.

Preface

Framework Services Manual xi

Many procedures in this manual include icons in the left margin. Theseicons provide context for performing a step within a procedure. Forexample, if you start a procedure by double-clicking on a policy regionicon, that icon appears in the left margin next to the first step. If thefourth step of the procedure instructs you to open another icon, thaticon appears in the left margin next to the fourth step.

Platform-specific InformationThe following table identifies text used to indicate platform-specificinformation or procedures.

Platform Supported Versions

AIX 4.x Managed Node, Endpoint:IBM RS/6000 series running AIX, Versions 4.1, 4.2,and 4.3

AS/400 Endpoint:V3R2, V3R7, V4R1, and V4R2

Digital UNIX Managed Node, Endpoint:Versions 4.0a and 4.0d.

DG/UX Endpoint:Versions 4.11 and 4.20 on the ix86 platform

HP-UX Managed Node, Endpoint:HP9000/700 and 800 series running HP-UX, Versions10.01, 10.10, 10.20 and 11.00

NCR Managed Node, Endpoint:NCR 3000 series running NCR UNIX SVR4 MP-RAS3.0.1 and 3.0.2

NetWare PC Agent or Endpoint:IBM-compatible PCs 486 or higher running NovellNetWare, Versions 3.11, 3.12, 4.01, 4.1, and 4.11

OS/2 TME 10 Desktop for Windows, PC Agent, or Endpoint:IBM-compatible PCs 486 or higher running IBM OS/2,Versions 2.0, 2.1,Warp 3.0, and Warp 4.0 withWin-OS/2

Preface

xii Version 3.6

User and Group IconsThe following icons represent the user and group profiles resources:

Pyramid Endpoint:Pyramid MIServer-ES, Version 5.4MN

Sequent Managed Node, Endpoint:Sequent DYNIX/ptx, Releases 4.2.3 and 4.4.2

SCO Managed Node, Endpoint:SCO UnixWare 7, SCO UnixWare Versions 2.1.1 and2.1.2

SGI Managed Node, Endpoint:SGI IRIX, Versions 6.2 and 6.4

Solaris Managed Node, Endpoint:Sun SPARC series running Solaris, Versions 2.4, 2.5,2.5.1, and 2.6

Solaris Intel Managed Node, Endpoint:Solaris2-ix86, Versions 2.5.1 and 2.6

SunOS Managed Node, Endpoint:Sun SPARC series running SunOS, Versions 4.1.3 and4.1.4

Windows TME 10 Desktop for Windows, PC Agent, or Endpoint:IBM-compatible PCs 486 or higher running MicrosoftWindows, Versions 3.1, 3.11, and Windows 95

Windows NT TME 10 Desktop for Windows, PC Agent, ManagedNode, or Endpoint:IBM-compatible PCs 486 or higher running MicrosoftWindows NT, Versions 3.51 SP5, 4.0, and 4.0 SP3.

Platform Supported Versions

Preface

Framework Services Manual xiii

User and group profile resources are created in the context of a profilemanager. After the initial distribution of a user or group profile, theprofile icon appears in the view dialog of subscribers. Subscribers canbe profile managers, hosts, or NIS domains.

Contacting Customer SupportIf you encounter difficulties with any Tivoli products, you can enterhttp://www.support.tivoli.com to view the Tivoli Support home page.After you link to and submit the customer registration form, you willbe able to access many customer support services on the Web.

Use the following phone numbers to contact customer support in theUnited States: the Tivoli number is 1-800-848-6548 (1-800-TIVOLI8)and the IBM number is 1-800-237-5511 (press or say 8 after you reachthis number). Both of these numbers direct your call to the TivoliCustomer Support Call Center.

We are very interested in hearing from you about your experience withTivoli products and documentation. We welcome your suggestions forimprovements. If you have comments or suggestions about thisdocumentation, please send e-mail to [email protected].

Preface

xiv Version 3.6

Framework Services Manual 1–1

Distributed O

bjectS

ystems

1Distributed Object Systems

TME 10 ADE provides a way to design applications for distributedobject systems. The tools offered by TME 10 ADE facilitate thefollowing:

■ Developing applications for distributed systems more easily thanwith traditional approaches

■ Developing applications that model familiar, real-worldrelationships

■ Developing reusable software components and extensiblelibraries of software modules

■ Modifying and extending components rather than developingnew programs

The Tivoli Management Environment (TME) and TME 10 ADE areobject-based systems. As such, they treat data and the procedures thatmanipulate it differently than traditional programming environmentsdo. This chapter explains the following topics:

■ Object-Oriented Programming Concepts

■ Object Classes

■ Object-Oriented Distributed Systems

You should read this chapter before reading the other material in thismanual if you are unfamiliar with object-oriented concepts. Thischapter introduces concepts that are used throughout this manual.

1

Object-oriented Programming Concepts

1–2 Version 3.6

The introductory material does not provide details about TME 10objects. See Chapter 5, “Object Implementation,” for details aboutTME 10 objects.

Object-oriented Programming ConceptsIn object-oriented systems, data and the procedures that manipulate itare treated as one entity, called anobject. An object is a collection ofdata similar to a database record. The data contained by the objects areknown asattributesand they define the characteristics of the object.An object of typeEMPLOYEE , for example, can have the followingattributes:

■ Name

■ Address

■ Phone Number

■ Vacation Accrued

■ Salary

All objects of typeEMPLOYEE have these attributes, although thevalue assigned to each attribute may differ amongEMPLOYEEobjects. In this way, each employee in a company can be representedas a unique object.

Furthermore, the association of attributes withEMPLOYEE objectsis similar to the way we associate such information with the employeesrepresented by the object. So an employee’s name should be the sameas the value of theName attribute for the object that represents thatemployee.

Objects also contain functions that are used to manipulate the value ofeach attribute. Such functions are known asmethods. Each object mayrequire its attributes to be manipulated in a unique way, and somethods are always executed (invoked) in the context of an object.

An object contains all the data representing a real-world object, suchas an employee, and the methods that manipulate that data. Thisconcept is calledencapsulation, and it allows you to model real-worldobjects and manipulate the data associated with them in an intuitivefashion.



Distributed O

bjectS

ystems

The following table presents a list of example attributes for an objectof typeEMPLOYEE :

In addition to these attributes, objects of typeEMPLOYEE shouldcontain the methods needed to manipulate these attribute values.The following table presents some example methods that manipulatethe attributes in anEMPLOYEE object:

Each employee in the company is represented by a separate object oftypeEMPLOYEE , and you can create as many employee objects asyou need. You can then modify the attribute values of each object tomatch the characteristics of the employee it represents.

Attribute Value

Name Jose Sanchez

Address 1001 Butterfly Lane, Austin, Texas 78730

Phone Number 512-555-1234

Accrued Vacation 6 days

Annual Salary $50,000

Method Action

get_address Returns the string representing the employee’saddress

get_phone_num Returns the string representing the employee’sphone number

calc_vacation Calculates the employee’s accrued vacation timeand returns the value

get_salary Returns the current amount of the employee’s salary

raise_salary Increases the employee’s salary by a predeterminedamount


1–4 Version 3.6

So as time passes, the values of attributes such asAccrued VacationandAnnual Salary can be changed to accurately model the employeesrepresented byEMPLOYEE objects.

Object CommunicationBecause the attributes and methods of an object are encapsulated, theyare private to the object. Objects do not allow users to manipulate theirdata, nor do they allow users to invoke their methods. You cannot,therefore, directly access the methods or attributes of an object.You must instead communicate with the object that encapsulates them.

You communicate with an object by sendingmessages. Sendingmessages is a technique that is used to invoke methods of an object.Consider the following example:

You want to increase the annual salary of an employee named Jose by$500.00 (he’s been working awfully hard lately). To do so, it is notnecessary to write a new function to increase Jose’s salary. Instead,you send aRaise Salary message to theEMPLOYEE objectrepresenting Jose.

The raise_salary method encapsulated by the object responds to themessage and performs the operation that raises Jose’s salary. You donot directly manipulate the attribute value.

Some objects react in similar ways to the same messages. If, forexample, you want to give both Jose and another employee Helenesalary raises, you send messages to the objects representing Jose andHelene. Because both objects are of typeEMPLOYEE , both objectswill respond identically to your message, and both Jose and Helenewill get well-deserved raises. This is because objects of the same typeshare similar attributes and identical methods.

If you send the sameRaise Salary message to an object that representsa non-employee, such as an object of typeCUSTOMER, it does notknow how to raise a salary. This is because it does not contain amethod to raise salaries. In such cases, a method in the object usuallyreturns an error message or anexception. See “IDL ExceptionDeclaration” on page 3-14 and theApplication Services Manual formore information about exceptions.



Distributed O

bjectS

ystems

Objects as ModelsUsing the attributes and methods of objects organized by type makesthe task of modelling real-world entities in programs much easier.Consider, for example, the following object hierarchy of employees ina software company:

Some of the employees in the company design software and others sellsoftware. Regardless of the jobs they hold, all the people working forthe company are employees, and each can be represented by an objectof typeEMPLOYEE .

To make this application model the real world, a broader category ofobjects calledPERSON can be added, which has a more fundamentalset of attributes. In this case anEMPLOYEE IS-A PERSON.This means that objects of typeEMPLOYEE receive attributes andmethods from objects of typePERSON.

MANAGER SALESPERSONPROGRAMMER

SENIORPROGRAMMER

TECHNICALMANAGER

SALESMANAGER

PERSON

EMPLOYEE


1–6 Version 3.6

Inheritance

Because objects of typeEMPLOYEE need all of the attributes andmethods encapsulated by the objects of typePERSON, you can createanEMPLOYEE object from aPERSON object. Objects of typeEMPLOYEE inherit properties from objects of typePERSON.Inheritance is the ability of objects of one type to use attributes andmethods from objects of another type.

The properties inherited fromPERSON serve as the foundation forEMPLOYEE , but they do not necessarily define it. So even though anEMPLOYEE IS-A PERSON, EMPLOYEE should be assigned itsown attributes and methods that distinguish it fromPERSON.The ability of objects to inherit from each other means that it is easy tospecialize existing objects for new applications.

Not all employees, however, do the same work. The previous diagramindicates employees in the office are divided into three groups:

■ PROGRAMMER —Designers of the software

■ MANAGER —Managers of the business

■ SALESPERSON—Sellers of the software

Each object representing such a position inherits attributes andmethods from theEMPLOYEE object, but each is slightly different.The following example describes the way these objects differ.

Mariko is a programmer. She designs software. Mariko’scompensation for her work is a salary. Karl, however, is a salesperson.He sells the software that Mariko designs.

Rather than being compensated by a salary alone, Karl is compensatedwith a base salary plus a percentage of sales he makes. Because ofthese differences, objects of typePROGRAMMER and objects oftypeSALESPERSON must have the following different attributesand methods:

PROGRAMMER SALESPERSON

Name Name

Address Address



Distributed O

bjectS

ystems

PROGRAMMER andSALESPERSON both inherit attributes fromEMPLOYEE , and they each contain some of the same methods.They also contain some attributes and methods that are different.

The methods that update accrued vacation time, for example, are thesame for bothPROGRAMMER andSALESPERSON. Regardlessof the kind of work they do, they both accrue vacation in the same way.SALESPERSON, however, has attributes and methods not needed bythePROGRAMMER .

Because Karl is a salesperson, he has a sales quota, outstanding orders,a set of businesses that are his accounts, and a commission. He alsomust have a means of adding new accounts to or deleting formeraccounts from his list of accounts. Those attributes and the methodsthat perform operations on them are encapsulated by theSALESPERSON object.

Both PROGRAMMER andSALESPERSON are derived fromEMPLOYEE ; yet they are different. This is an example ofspecialization. Specialization is the ability of objects to inheritattributes and methods from other objects and then add attributes andmethods that distinguish them from the other objects.

If, for example, you need to create a new object for a new kind ofemployee, such as a SECRETARY, you can derive a new object typefrom EMPLOYEE . To do so, you create an object of typeEMPLOYEE and then add the additional attributes and methods that

Phone Number Phone Number

Accrued Vacation Accrued Vacation

Annual Salary Annual Salary

Sales Quota

Orders

Accounts

Commissions

PROGRAMMER SALESPERSON


1–8 Version 3.6

distinguish it from other objects. BecauseSECRETARY IS-ANEMPLOYEE , objects of typeSECRETARY inherit attributes andmethods fromEMPLOYEE . They also encapsulate attributes andmethods that distinguish them from objects that are not of typeSECRETARY.

In this way, you can tailor each new object according to the specificrequirements for each kind of employee. This eliminates the need tocreate a new program each time the company hires a new kind ofemployee.

Multiple Inheritance

If you proceed further into the hierarchy, you see that there are threemore objects based on anEMPLOYEE : SENIORPROGRAMMER , TECHNICAL MANAGER , andSALESMANAGER . Each of these new objects inherit some of their attributesand methods from preceding objects.

An object of typeSENIOR PROGRAMMER , for example, inheritsfrom thePROGRAMMER object. So aSENIOR PROGRAMMERIS-A PROGRAMMER , but not all programmers are seniorprogrammers. Objects of typeSENIOR PROGRAMMER might beidentical to objects of typePROGRAMMER with only a fewexceptions. Objects of typeSENIOR PROGRAMMER might, forexample, have a different method for calculating a yearly bonus.

Objects can inherit attributes and methods from more than one object.This is calledmultiple inheritance. TECHNICAL MANAGERmight inherit from bothPROGRAMMER andMANAGER . Objectsof typeTECHNICAL MANAGER represent a person who managespeople and has technical responsibilities. This object type must inheritattributes and methods from more than one object type.

A TECHNICAL MANAGER might receive a salary like aPROGRAMMER , but might also have responsibilities reflected byobject attributes such asProjects Managed. Likewise, aSALESMANAGER might have quotas and accounts like aSALES PERSONbut might not use the same method for calculating a salaryencapsulated byMANAGER .



Distributed O

bjectS

ystems

If an object such asSALES MANAGER inherits from more than oneobject, conflicts can arise from competing methods.SALESMANAGER , for example, inherits fromMANAGER , which is asalaried position, and fromSALESPERSON, which is asalary-plus-commission position. Which salary method will objects oftypeSALES MANAGER use? You resolve the conflict when youcreateSALES MANAGER .

When you create an object, you specify theinheritance ordering.Inheritance ordering specifies the order in which a new object inheritsattributes and methods from the existing objects. To makeSALESMANAGER inherit theSALESPERSON salary method rather thanthat ofMANAGER , theSALES MANAGER object must first inheritfrom SALESPERSON and thenMANAGER . When using the salarymethod, the object will find the salary method inSALESPERSONbefore finding the salary method inMANAGER .

Polymorphic MessagesRefer to the previous example that explains thePROGRAMMERobject Mariko and theSALESPERSON object Karl. To calculate thesalaries for Mariko and Karl, you send aGet Salary message to theobjects that represent them. The appropriate methods encapsulated byeach object return theAnnual Salary data to you. The methods thatcompute theAnnual Salary data, however, are different for eachobject.

Mariko is aPROGRAMMER and as such, she receives a salary. Thesalary method for the object that represents Mariko merely returns thevalue of herAnnual Salary attribute. The salary method for the objectthat represents Karl, however, is quite different. Karl’s compensationis determined by adding a base salary to a percentage of sales,represented by a mathematical expression such as Compensation =BaseSalary + 0.05*TotalSales.

As a client, you need to know only one message—Get Salary—todetermine the value of theAnnual Salary attribute for either object.The two methods for computing salary are different, but the differenceis invisible to you. The ability of different objects to respond to thesame message with different method implementations is calledpolymorphism.


1–10 Version 3.6

Polymorphism enables you to write general-purpose programs thatdeal with any object of typeEMPLOYEE rather than a specific typeof EMPLOYEE . It thus saves you from having to modify andre-compile those programs when you create a new type ofEMPLOYEE . By using polymorphism you can focus your attentionon behaviors and relationships between objects rather than the minordetails often associated with conventional programming.

InterfacesThe methods encapsulated by objects perform operations when theobject receives a message from another program. Theraise_salarymethod encapsulated bySALESPERSON, for example, performs theoperation of increasing the value associated with theAnnual Salaryattribute encapsulated by an object of typeSALESPERSON.

The operations that can be requested of an object define theinterfaceto the object. So the interface toSALESPERSON comprisesoperations that are performed by the following methods:

■ get_address

■ get_phone_num

■ calc_vacation

■ get_salary

■ raise_salary

■ add_account

■ delete_account

The interface to an object is so called because it identifies the messagenames used to communicate with that object. This means users canonly communicate with objects by sending messages that request anoperation. Furthermore, the transmitted message must request anoperation defined by the object interface. A user in this context is anyentity, such as a program or command, that communicates with anobject.

Often the methods that perform requested operations requireparameters that provide required information about the operation.The operation that raises a salary, for example, might have a parameter



Distributed O

bjectS

ystems

that specifies how much to raise theAnnual Salary attribute of anobject. The parameters to the operations compose anoperationsignature.

The concept of operation and interface definition as it is presented hereis important because users are not concerned with the way operationsare performed. They are only concerned with the transmission of themessage, any required parameters, and any required response.The way operations are performed is the concern of the methodimplementations encapsulated by the object.

This manual defines an operation as an action requested by a user,regardless of the way the action is performed. A method is defined asa function that is private to a specific object and that determines theway an operation is performed. The provision of these functions isknown asmethod implementation.

Operations, therefore, are actions that can be requested, whereasmethods are the implementation of those operations for a specificobject.

ImplementationYou implement a method by writing a function that responds properlyto a specific message in the context of some object. For example, themethod that gets a salary for an object of typeSALESPERSON isimplemented differently than the one that gets a salary for an object oftypePROGRAMMER .

The difference in the way methods are implemented is driven by therequirements of each object type. The salary of aSALESPERSON,for example, is calculated differently than the salary of aPROGRAMMER . The methods that return the salary of the objectsthat represent these employees must therefore be implementeddifferently.

The process of defining operations is, therefore, separate from that ofimplementing methods. It is possible, in fact, to have two differentimplementations that both support the same interface. The differencesin the two implementations are driven by the desired behavior of theassociated object.

Object Classes

1–12 Version 3.6

Object ClassesThe previous explanation of objects, operations, and methods is rathergeneral. The explanation presents the notion of objects, theirattributes, and the methods that manipulate them. In order to morecompletely understand the manipulation of objects and their attributesin the TME, you must understand the notion of an objectclass.

An object class provides a common data structure and commonbehavior for objects of a given type. The example in “Object-orientedProgramming Concepts” on page 1-2 describes an object of typeEMPLOYEE . The collection of all attributes and methods of anEMPLOYEE object composes aclass, and eachEMPLOYEE objectis aninstance of theEMPLOYEE class.

Classes differ from an instance in two ways:

■ A class defines the attributes and methods for some commongroup of objects.

■ An object encapsulates its own attribute values and manipulatesthem using methods defined by the class to which it belongs.

According to Booch, an object represents some real world entity thatexists in time and space. A class, however, is an abstraction (theessence) of that object and all the objects that belong to that class.1

As a designer of software, you know in advance that a company hasmany employees. As a designer of object-oriented software, youshould design anEMPLOYEE class that contains the attributescommon to all employees and a set of methods that manipulate thevalues of those attributes.

TheEMPLOYEE class has an attribute calledName but no valueassociated with the name. An object that belongs to that class,however, has not only theName attribute but also a value such asJoseSanchez associated with it. Such an object is one instance of theEMPLOYEE class.

1. Grady Booch, “The Object Model” in Object Oriented Design withApplications, (Redwood City, CA: Benjamin/Cummings PublishingCompany, Inc., 1991), p. 93.

Object Classes


Distributed O

bjectS

ystems

Objects as Instances of a ClassBefore you create an object it is common to first define a class thatrepresents some type of object. After the class is defined, you cancreate an instance of that class. The class definition includes theattributes for each object and the methods that manipulate thoseattributes.

The previous explanation of objects presents the notion that objectsencapsulate methods, attributes, and access to attribute values. This istrue from the perspective of users, because they must communicatewith the object to manipulate the data the object encapsulates.In reality, however, objects encapsulate attribute values, andreferences to common methods.

The class encapsulates the definition of attributes and methodscommon to all members of the class. Instances of that classencapsulate two things:

■ The attribute values for that instance

■ References to the methods (defined by the object class) thatmanipulate those values

Thus, each instance has its own set of attribute values, but a shared setof methods. This concept is important for two reasons:

■ It reduces the need for storage space.

■ It ensures that all instances of a class behave in the same way.

In theEMPLOYEE class example, a company might have hundredsor even thousands of employees. Each can be represented by an objectwith its own set of attributes and values. The methods that manipulatethe data for those objects however are shared and encapsulated by theEMPLOYEE class.

In such cases, significant storage capacity would be required if objectmethods were stored by each object. It is much more efficient to allowthe class to store all the methods for all its instances.

Object-oriented Distributed Systems

1–14 Version 3.6

Furthermore, having the actual methods resident on only one object(the class object) ensures a manageable method modification scheme.If you want to modify a method, you modify only the class object, andthe changes are then automatically propagated to every instance of thatclass.

Class InheritanceIn object systems, inheritance occurs by class. Inheritance is a productof derivation, and a class inherits the attributes and methods of theclass from which it is derived (base class). A class does not, however,necessarily contain the attributes and methods of its base classes.

Objects encapsulate references to their methods. Likewise, classescontain references to the attributes and methods defined in their baseclasses. Each class contains not only the new attributes and methods itdefines, but references to attributes and methods defined in its baseclasses as well.

It is possible for an object system to contain many classes andsubclasses. In such systems, the technique of derived classes referringto base classes is much more efficient than redefining every attributeand every method for each derived class.

Thus, when an object is instantiated from a class, it can efficientlyencapsulate attributes and methods defined in many classes. This isbecause the object encapsulates not only the attributes and methods ofits own class, but those of the base classes from which its class inherits.

Object-oriented Distributed SystemsMany difficulties are inherent in distributed applications. A commonproblem for object-oriented programmers writing such applications isthat of shipping an object across a network from one process toanother.

Systems like the Distributed Computing Environment (DCE) from theOpen Systems Foundation (OSF) provide remote procedure callmechanisms. These mechanisms can ship complicated data structuresacross a network, but they do not provide explicit support for objects.



Distributed O

bjectS

ystems

Solving the problems associated with such transmissions in a remotefashion can present difficult problems.

Shipping objects across a network typically requires a violation ofobject encapsulation. Private data used for object implementation mustsomehow be accessed so that the object can be taken apart,transmitted, and then reconstructed on the receiving side. Knowinghow objects are laid out in memory can make such a task possible, butsuch knowledge is compiler-specific and is, therefore, not portable.

A cleaner approach is to make every class support functions forencoding and decoding (marshaling andunmarshaling) its own data.Such programming techniques, however, can be tedious anderror-prone. Consequently, neither this solution nor the previous one isideal.

To avoid breaking the object encapsulation, distributed object orientedapplications must be concerned with only the object interfaces. Theyshould not be concerned with whether the object implementations arein the same process or on another machine in a remote location.

This ideal requires an object model that allows applications totransparently use both local and remote objects without sacrificingefficiency. Such an object model must address issues faced by alldevelopers of distributed applications. It must provide a standardobject-oriented programming interface that is not onlysystem-independent, but language-independent as well.

In 1991, the Object Management Group (OMG) introduced revision1.1 of the Common Object Request Broker Architecture (CORBA).CORBA 1.1 is a standard that addresses the aforementioned issues.This specification describes interfaces and services that can solve theproblems associated with developing applications for distributedobject systems.


1–16 Version 3.6

Common Object Request BrokerThe Object Request Broker (ORB) specified by CORBA is so calledbecause it is a program that manages requests between users (clients)and objects (servers).

When a user makes a request, it passes the operation name and anyrequired parameters to the ORB. The ORB then locates the correctserver object and forwards the request. If the object returns data, itpasses the data back to the ORB, which locates the correct client andreturns the data.

The ORB is common because CORBA does not specify how the ORBshould be implemented. It specifies only the services and interfaces theORB must provide. Any CORBA-compliant application can operateon any CORBA-compliant ORB.

CORBA Object ModelCORBA objects are unconcerned with the request origin. Clients cancommunicate with CORBA objects whether they request serviceslocally or remotely: neither the client nor the server object are requiredto make such distinctions.

Such abstractions are possible because of the way CORBA specifiesthe design of clients and servers: it explicitly defines objectidentification and operation semantics.

Object Identification

Each object has a unique identity that is distinct from and independentof any of its characteristics. Characteristics can vary as time passes,whereas identity is constant.

CORBA objects each have an identifier that provides a reference tothat object. The reference is an attribute, which is opaque to users.This information is passed to the user as an output parameter whenrequested.



Distributed O

bjectS

ystems

Because the object reference is opaque, applications need not changeif moved to a different CORBA-compliant ORB. This is one aspect ofCORBA-compliant ORBs that makes them common.CORBA-compliant applications are unconcerned with how the objectreference is implemented; they merely follow the rules specified byCORBA when initiating a request of some object.

Operation Semantics

When a client requests an operation, some of the operation parametersrequire the server object to return data. The parameters associated withthe request compose the operation signature. This signature and theobject reference are all that is required to initiate a request.

Requests initiated by CORBA-compliant clients are unconcerned withthe details of how the operation is implemented. They are concernedonly with which operations are available (the object interface) andhow to initiate the request (the operation signature).

Just as opaque object references facilitate a common ORB, theCORBA-specified operation semantics facilitate commonapplications. This means CORBA-compliant applications need notchange among CORBA-compliant ORBs.


1–18 Version 3.6


Com

mon O

bject Request

Broker A

rchitecture

2Common Object Request BrokerArchitecture

This chapter describes the Common Object Request BrokerArchitecture (CORBA) specified by the Object Management Group(OMG). The CORBA specification proposes a common ObjectRequest Broker (ORB) to solve complex problems that are common indistributed, heterogeneous, client-server networks.

The chapter also describes the Tivoli implementation of this ORB andthe interfaces through which you access it. The material in this chapterexplains the following concepts:

■ Heterogeneous Networks

■ OMG-Specified CORBA

■ Client and Object Implementation Relationships

■ ORB Interfaces

■ TME 10 Basic Object Adapter (BOA)

■ TME 10 ORB Implementation

You should read this chapter before reading subsequent material in thismanual if you are unfamiliar with the CORBA specification.This chapter introduces concepts you must understand before you candevelop applications using the tools provided by TME 10 ADE.

2

Heterogeneous Networks

2–2 Version 3.6

Heterogeneous NetworksChapter 1, “Distributed Object Systems,” provided an introduction tothe concepts of distributed computer networks. As technology movesforward among computer hardware and software vendors, it often isdesirable to use several platforms in these distributed networks.

Distributed networks that include more than one type of platform(hardware or operating system) are described asheterogeneous.Heterogeneous networks can be advantageous, but they also createcomplex problems for software developers and system administrators.

TME 10 ADE provides a solution to these problems because it isfounded on the Tivoli Management Framework, which operates acrossmultiple computer platforms. The purpose of the framework is toallow software developers to develop applications that will operate onany platform that the framework supports.

TME 10 ADE provides CORBA-compliant features that enable theframework to support multiple platforms. See the CORBAspecification for details.

OMG-specified CORBAThe CORBA specification presents an open system of non-specificservice requestors and service providers. The system is open becausethe service requestors are isolated from the service providers. Requestscan be initiated without regard to the location or implementation of theservice provider.

The purpose of the specified architecture is to allow the integration ofa wide variety of object services. The architecture uses three conceptsto achieve this integration:

■ Object encapsulation—The notion that the object providing arequested service does so within its own context. Each object hasthe ability to respond differently to the same request.

■ Service requestor and service provider isolation—The ability toallow service requestors to make requests of a service providerregardless of the provider location or implementation. A servicerequest must include a request identifier (operation name),

OMG-specified CORBA


Com

mon O

bject Request

Broker A

rchitecture

a provider identifier (object reference), and any other parametersrequired by the service. The request should not include programsthat translate data formats, nor should it include providerlocations.

■ Interface and implementation separation—The notion thatinterfaces are defined without regard to the way they areimplemented. An interface describes a set of services that, whenimplemented, are available to service requestors.

These concepts require the CORBA specification to include severalcomponents. Review the following diagram:

The following list describes the depicted components:

■ Clients—Programs that request services.

■ Object implementations—Programs that provide services whenrequested.

■ ORB—A program that manages the transmission of requestsfrom the client to the object, and the transmission of results backto the client.

ClientObject

Implementation

DynamicInvocationInterface

DirectORBInterface

Object Request Broker

ClientStub

ServerSkeleton

BasicObjectAdaptor(BOA)

Client and Object Implementation Relationships

2–4 Version 3.6

■ ORB interfaces—Four types of interfaces that collect and passdata to and from the ORB:

• Client stub—Used by the client to request defined services

• Dynamic Invocation Interface (DII)—Used by the client todynamically request services

• Server skeleton—Used by the object implementation toreceive requests and return information

• Other ORB interfaces—Used by the client and the objectimplementation to provide a direct interface to the ORB

■ Basic Object Adapter (BOA)—A program that providesCORBA-compliant services for object implementations.

The CORBA specification defines these components and specifies howthey should be joined together. The integration of these componentsproduces a system that allows programmers to write applicationswithout regard to object location or implementation.

The CORBA specification does not describe the design of the specifiedcomponents. It specifies only how they are joined together. See “ORBInterfaces” on page 2-9 for more information about each interface.

The remainder of this chapter describes TME 10 ADE implementationof the OMG-specified CORBA. The described components are allCORBA-compliant.

Client and Object Implementation RelationshipsCORBA, as previously stated, specifies an open system that linksservice requestors to service providers. The system contains threeprimary components:

■ Client

■ Object implementation

■ ORB and BOA

The client is the requestor of some service that some objectimplementation provides. The ORB and BOA deliver the request fromthe client to the object implementation, which performs the requestedservice, and delivers any return data to the client.



Com

mon O

bject Request

Broker A

rchitecture

The client and the object implementation are isolated from each other.Neither has any knowledge of the other except through their interfacesto the ORB and BOA. Client requests are, therefore, independent ofthe object implementation location and the programming language inwhich it is implemented.

Furthermore, clients and object implementations are not required todirectly communicate—clients initiate requests, and objectimplementations provide services.

TME 10 Clients and Object ImplementationsTME 10 clients are programs that initiate requests of objects. Objectimplementations are programs that provide services when they receivea request. In many cases, a program can be a client at one time and anobject implementation at another time. The notion of a client is merelythe role of a program at a specific time. Consider the followingexample:

A program calledmanage_raises manages employee raises in salary.One part of the program sends araise salary message to a specifiedemployee object. This request is made as a client, because it requestsservices of some object implementation (the employee object).

Another part of themanage_raises program tracks the number oftimes each employee has received a raise. This part of the programprovides a service to other programs that need this information.When it receives a request, themanage_raises program retrieves theinformation for the specified employee(s) and returns a result to theclient.

When the program sends theraise salary message, it is functioning inthe role of client. When the program responds to a request bydetermining the number of raises an employee has received, it isfunctioning in the role of an object implementation.

Client requests are different from traditional request techniquesbecause the client request does not locate or accommodate the serviceprovider. It merely requests the service in the same way it would calla function. The client does not contain any code to manage the detailsof the request delivery. Request delivery is managed by the ORB.


2–6 Version 3.6

Most applications will, at some time, provide services for otherprograms. Traditional servers must maintain a knowledge base of theclient implementation and location. CORBA Object implementationsare different from traditional servers because they can provide servicesto any client, regardless of the client’s location or implementation.

The TME 10 ORBThe ORB is responsible for locating the object implementation anddelivering the request to it through the BOA and the server skeleton.The TME 10 ORB locates the correct object implementation using thefirst parameter that is passed with the request.

Client RequestsThe isolation of the client and object implementation permitsflexibility in how the object implementation provides services andwhere it is located. It is quite possible, for example, for the client andthe object implementation to reside on different platforms and bewritten in different languages.

The cost of this flexibility is that the client cannot call the objectimplementation directly. Review the following diagram:

ClientObject

Implementation(Server)


ClientStub

DirectORBInterface

ServerSkeleton BOA



Com

mon O

bject Request

Broker A

rchitecture

The client initiates a request by passing the request to the client stub.Requests are specified by an operation name, and each operation isassociated with a specific client stub. The client stub is a function thatprepares the request for delivery and then passes it to the ORB.

The parameters required by the operation are known collectively as theoperation signature. The first parameter in the signature identifies theobject implementation that provides the requested service.This parameter is known as theobject reference.

The object reference is returned to you when you create a new object.See “Object Creation from a Class” on page 4-8 for more informationabout creating objects.

Request Delivery

The ORB receives the request from the client stub and attempts tolocate the object implementation. When it does, it delivers the requestand the request parameters to the BOA. The BOA then passes therequest to the server skeleton, which prepares it for the objectimplementation. The server skeleton then passes the request to theobject implementation.

If the ORB is unable to locate the object implementation, it returns anexception. See “Raising Exceptions” on page 3-21 for moreinformation about exceptions.


2–8 Version 3.6

Object Implementation ReturnsWhen an object implementation receives a request, it frequently mustreturn data to the client. Review the following diagram:

Conceptually, this is not very different from the way a client makes arequest. The primary difference, in this context, is that information ispassed from the object implementation to the client rather than fromthe client to the object implementation.

The object implementation passes the return data back to the ORB byway of the server skeleton. The ORB then delivers the return data backto the client by way of the client stub.

Data Marshaling and UnmarshalingOn heterogeneous networks, applications must cope with the datarequirements and formats for each platform. Every time theapplication transmits data, it must be able to convert the data from thenative format to the destination format.

The TME 10 common ORB eliminates this requirement: applicationprogrammers using TME 10 ADE need not consider the detailsassociated with such conversions. One of the issues TME 10 clientstubs address is that of data formats for different platforms. When a


Direct

Client

ORBInterface

ClientStub


ServerSkeleton

BOA

ObjectImplementation

(Server)

ORB Interfaces


Com

mon O

bject Request

Broker A

rchitecture

user makes a request, the client program initiates the request throughthe provided client stub.

The client stub then collects the data associated with the request andconverts it from its current format to a common format. This process(known asdata marshaling) is performed in accordance withASN.1Data Encoding. ASN.1 specifies the conversion of data to a canonicalform for transmission to a machine of undetermined platform type.When the data conversion is complete, the client stub passes themarshaled data to the TME 10 ORB.

The BOA then presents the data to the appropriate server skeleton,which reformats the data according to the requirements of the objectimplementation. This process is known asdata unmarshaling.

The advantage is that you can now focus your efforts on the task ofapplication development, rather than requirements imposed on thedata format by each platform in a distributed system.

ORB InterfacesThe client and the object implementation access the ORB through a setof four interfaces. You can think of each interface as a separateprogram that passes requests and data among the client, objectimplementation, and ORB. This section describes these interfaces.

Client StubsThe client stub is an ORB interface responsible for four things:

■ Data collection

■ Data transmission

■ Data marshaling

■ Data unmarshaling

When the client initiates a request, it calls the client stub, whichcollects the data associated with the request and presents the operationto the client. The stub then marshals the data as described in “DataMarshaling and Unmarshaling” on page 2-8.

ORB Interfaces

2–10 Version 3.6

After data collection and marshaling, the stub transmits the requestwith the marshaled data to the ORB. If data is returned, it is passedback to the ORB in a marshaled format.

The stub then collects the return data and unmarshals it fortransmission to the client. Finally, the stub transmits the unmarshaleddata to the client, which completes the client request.

Dynamic Invocation InterfaceTo make a request, the client can use either a client stub, or theDynamic Invocation Interface (DII). Review the following diagram:

The purpose of the DII is to construct requests dynamically atrun-time. The signature of an operation is sometimes unknown duringdevelopment. In such cases, the client can request an operationdefinition at run-time and construct the request dynamically.

TME 10 ADE provides aninterface repository to accommodatedynamic invocation. The repository stores a definition of eachoperation.


lookup_id

operationdefinition

InterfaceRepositoryClient


(Server)


ClientStub

DirectORBInterface

ServerSkeleton BOA

ORB Interfaces


Com

mon O

bject Request

Broker A

rchitecture

When you request a service by way of the DII, you can either requestthe operation definition from the interface repository or build thesignature in your program. See “Dynamic Invocation Interface” onpage 6-3 for more information aboutlookup_id.

Interface Repository

The interface repository provides persistent storage for definedinterfaces and contains entries for the following:

■ Each defined interface

■ Each interface operation

■ Each operation signature

An interface definition consists of an interface name, a set ofoperations, and the signature of each operation. You can define aninterface in two ways:

■ You can statically define it in a file using the Interface DefinitionLanguage (IDL). IDL is a compiled language that provides astandard for defining interfaces.

When you run the Tivoli-supplied IDL compiler, thecompiler-generated installation script adds the appropriateentries to the interface repository. See “IDL Interface Definition”on page 3-16 for more information about using IDL to defineinterfaces.

■ You can define it dynamically and add it to the interfacerepository. See “Dynamic Invocation Interface” on page 6-3 formore information about the DII.

ORB Interfaces

2–12 Version 3.6

Server SkeletonsFor each IDL-defined operation entry, there is an interface to the objectimplementation known as the server skeleton. The server skeletontranslates the data associated with the request and presents it to themethod that the BOA invokes. Subsequent sections explain theconcept of methods.

Data Translation

When the ORB passes a client request to the server skeleton, the datais in ASN.1 format. The server skeleton unmarshals the request dataand then passes the request to the object implementation.

If the object implementation returns data, it does so in the nativeformat, and the server skeleton is responsible for marshaling the data.See “Data Marshaling and Unmarshaling” on page 2-8 for moreinformation about data marshaling and unmarshaling.

Method Presentation

When you specify an operation in an interface using IDL, you merelydeclare that the operation supports the interface. Before you canrequest the operation, however, you must implement it.

An operation in TME 10 ADE ORB structure is always implementedas a method. A method is a function that performs an operation in thecontext of an object.

When the ORB delivers a request from the client, the BOA invokes theassociated method in the context of the specified objectimplementation. See Chapter 5, “Object Implementation,” for moreinformation about methods and method implementation.

Other ORB InterfacesTME 10 ADE provides the following set of ORB interfaces:

■ Run-time library—See “Command Line Interface” on page 6-9and the associated manual pages for more information about eachfunction.

TME 10 Basic Object Adapter (BOA)


Com

mon O

bject Request

Broker A

rchitecture

■ Run-time exceptions—CORBA supports the use of exceptions asa technique for error management. Refer to the following text forconceptual information about exceptions:

• “Raising Exceptions” on page 3-21

• “IDL Exception Declaration” on page 3-14

• Application Services Manual Volume I

■ ORB—See “Pseudo-object Interfaces” on page 6-18 for moreinformation about the ORB interfaces.

■ Object—See “Pseudo-object Interfaces” on page 6-18 for moreinformation about Object interfaces.

■ BOA—See “TME 10 Basic Object Adapter (BOA)” onpage 2-13 for more information about the TME 10 BOA.

■ Request—See “Dynamic Invocation Interface” on page 6-3 formore information about the Request interface.

■ TypeCode—See “TypeCode” on page 6-21 for more informationabout theTypeCode interface.

TME 10 Basic Object Adapter (BOA)The TME 10 ADE ORB structure includes a BOA, which provides thefollowing CORBA-compliant services:

■ Generates object references.

■ Activates the process under which methods run.

■ Invokes the method associated with the request.

■ Manages the deactivation of the process under which methodsrun.

■ Provides TME 10 security. (See “Security and Performance” onpage 2-20 for more information about TME 10 security.)

TME 10 Basic Object Adapter (BOA)

2–14 Version 3.6

Although these services are invisible to developers, they are necessaryfor the purpose of providing services for clients. Review the followingdiagram:

The ORB delivers the request to the BOA, which activates the processunder which the method runs. The BOA then invokes the methodassociated with the request by way of the server skeleton presentingthe method. When the method is finished, the BOA manages thetermination of the process under which the method ran.

The BOA is a requisite interface between the server skeleton and theORB. Upon receipt of the client request, the BOA performs any of thepreviously listed services necessary to invoke the associated method.

If the object implementation detects an exceptional condition, it cannotify the client by calling the BOA. The TME 10 ADE providedfunction,BOA_set_exception, calls the BOA, which then contacts theclient as shown in the previous diagram.

In addition toBOA_set_exception, TME 10 ADE offers an extensiveclass-based exception facility with termination semantics. See theApplication Services Manual for more information about TME 10exceptions.

BOA

Client Request2

3

Results

ClientsObject

Implementation(Server)


ClientStub

DirectORBInterface

16 4

5ObjectRequestBroker

ServerSkeleton

The TME 10 ORB Implementation


Com

mon O

bject Request

Broker A

rchitecture

The TME 10 ORB ImplementationCORBA does not specify the implementation of the ORB, only thearchitecture of the model. For example, it specifies the provision of acommon ORB. It does not, however, specify whether the ORB shouldbe implemented as part of the operating system. It could instead beimplemented as a separate program that runs on the operating system.

There are a wide variety of ORB implementations possible withina common ORB system. CORBA suggests four possibilities:

■ Client and Object Implementation-resident ORB—If there is asuitable communication mechanism present, an ORB can beimplemented in routines resident in clients and implementations.The stubs in the client can either use a location-transparent IPCmechanism or directly access a location service to establishcommunication with the object implementations. Code linkedwith the object implementation is responsible for setting upappropriate databases for use by clients.

■ Server-based ORB—To centralize the management of the ORB,all clients and implementations can communicate with one ormore servers whose job it is to route requests from clients toobject implementations. The ORB is a separate program from theoperating system, and normal IPC can be used to communicatewith the ORB.

■ System-based ORB—To increase security, reliability, andperformance, the ORB can be provided as a basic service of theunderlying operating system. Such systems can prevent theforgery of object references, which reduces the expense ofauthentication on each request. Because the operating system canknow the location and structure of clients and objectimplementations, it is possible for the implementation to beoptimized in a variety of ways. It can, for example, avoid datamarshaling when both the client and the object implementationare on the same machine.


2–16 Version 3.6

■ Library-based ORB—For objects that are light-weight andwhose implementations can be shared, the implementation mightactually be in a library. In this case, the stubs could be librarymethods. This is possible only if the client program can getaccess to the object data, and if the client is trusted not to damagethe data.

TME 10 ADE provides a server-based ORB. This means the ORB is acontinually running program, separate from the operating system.The ORB communicates with both the server and the client throughseparate stubs and skeletons.

The details of this implementation are beyond the scope of thismanual, but you should be aware of the performance and securityissues associated with it. Subsequent sections detail these issues.

Process BoundariesAs a server-based implementation, the TME 10 ORB manages thecommunication details between the client and the objectimplementation. The architecture of server-based ORB systemsrequires a separate process for the ORB, the client, and the objectimplementation. Review the following diagram:

Client Program

ORB/Object Adapter


Client Requests

Return Data

ORB System Processes



Com

mon O

bject Request

Broker A

rchitecture

This diagram depicts the TME 10 ORB system from the perspective ofthe operating system. According to the diagram, the ORB systemcontains three primary components, each of which runs under aseparate process: the ORB, the client, and the object implementation.

The arrow on the left represents call sequences initiated by the client.The arrow on the right represents call sequences initiated by the objectimplementation for returning data to the client.

The diagram is simplified, but its purpose is to depict the way theseprograms interact. When a client makes a call to an objectimplementation, it passes the call to the ORB. Upon receipt of therequest, the ORB locates the correct object implementation and theobject adapter passes the request to the object implementation.

When the object implementation has acted on the request, it passes anyreturn data to the object adapter. The ORB locates the client and passesthe return data back to the client program.

Each time a call is made to another program in the system, the requestis passed to a different process. Thus, when the client program calls theORB, control of the request is transferred from the client process to theORB process.

Likewise, when the object adapter passes the request to the objectimplementation, control is passed from the object adapter process tothe object implementation process. If the object implementation mustreturn data, the transfer will cross process boundaries at least twice.Various services and mechanisms optimize the implementation ofclients and servers.

Separating processes in this way increases system security, becausethe process is the only secure boundary that cannot easily be corrupted.The separation enables the ORB to check the authority of the client andmeasure it against the specified security of the object implementation.This advantage, however, costs more time to execute each transaction.

Subsequent sections describe the security advantages of the TME 10ORB system. You should use the security available from the systemwhen designing your applications, but you should also be aware of thecost for each transaction.


2–18 Version 3.6

Cascaded CallsTo better understand the performance and security issues in an ORBsystem, it is helpful to examine a scenario ofcascaded calls. Acascaded call is one in which the requested service is performed by anobject implementation other than the one specified by the originalrequest. Review the following diagram:

This diagram simplifies the process of making a cascaded call, but itspurpose is merely to depict the concept. The diagram depicts twoORBs,ORB1 andORB2. This scenario is entirely possible on largedistributed systems and does not really affect the way clients makecalls to object implementations. Whether a system contains one ORBor several, the ORB is transparent to the client.

The client in this diagram initiates a request and passes it toORB1,which, in turn, forwards the request toObject1. To perform theoperation requested by the client,Object1 must request some serviceof Object2.

ORB 1

ORB 2

Object 2

Object 1Client

12

34



Com

mon O

bject Request

Broker A

rchitecture

Object1 then becomes a client ofObject2 and passes its request to theORB forObject2, which isORB2. ORB2 then passes the request toObject2, which performs the operation requested byObject1.

In the event thatObject2 must return data, it passes the data toORB2,which forwards the data toObject1. Object1 then performs theoriginal operation requested by the client and passes any return data toORB1. ORB1 then passes the return data to the client. This process ofreturning data is depicted in the following diagram:

Cascaded calls are so called because they cascade from object to objectbefore completion.

In a typical call from client to object implementation, the call crossesat least two process boundaries (client to ORB, and ORB to objectimplementation). In the case of a cascaded call, the call will cross atleast four process boundaries. This is exclusive of the return dataprocess.

If a call cascades to several object implementations, it can consume asignificant amount of resources. This results in a significant amount oftime for a client to make a single call. Applications should thereforeminimize the use of cascaded calls.

ORB 1

ORB 2

Object 2

Object 1Client

5

6

78


2–20 Version 3.6

Security and Performance

One of the advantages of Tivoli’s server-based ORB implementationis enhanced security. In any client-server system, security is important.In distributed client-server systems, such as that provided by the TME,security is critical.

In such systems, administrators are simultaneously making criticalchanges to many machines. Such changes include adding users,changing access to secure applications, and altering systemconfiguration files. In distributed client-server systems that do notoffer substantial security, mission-critical resources can be lost orcorrupted. Furthermore, sensitive information can be obtained byintruders.

TME 10 is therefore designed and built to ensure the security andintegrity of mission critical resources. All administrator requests, forexample, are checked by the security service to ensure that therequestor is authorized to perform the requested operation.This security of each operation can have a small negative effect onsystem performance, but this cost is both necessary and acceptable.Compromising the integrity and security of your data can carry a muchhigher price tag than the performance cost associated with the TME 10security scheme.

The small performance cost, however, cannot be disregarded; eachclient request has a cost associated with it, and application designs thatuse many client requests to perform just a few operations tend toperform poorly. You should therefore ensure that your client prudentlyinitiates requests: excessive requests will negatively affect yourapplication performance.



Com

mon O

bject Request

Broker A

rchitecture

Review the following diagram, which depicts access control for acascaded call in the TME:

This diagram depicts how the TME 10 ORB manages security forcascaded calls. The TME 10 ORB manages security in the same wayfor all calls, regardless of whether the call is cascaded. The purpose ofthe diagram is merely to depict the TME 10 security model.

TME 10 addresses two aspects of system security:authentication andauthorization. Authentication verifies that a user or service is reallywhat it says it is. Authorization ensures that the user has permission toperform a given operation.

TME 10 automatically manages authentication of application usersusing UNIX user and group IDs, and each TME 10 applicationmanages authorization using a definedrole. Roles are arbitrary namesassigned to different levels of access, and each role is recorded in anAccess Control List (ACL) for your application. An applicationenforces authorization by comparing the role of the requestor to theroles it finds in the ACL. See “Authentication and Authorization” onpage 4-45 for more information about authorization and roles.

ORB 1

ORB 2

Object 2

Object 1Client

1

4

58

2

3

6

7

AccessControlList

2

AccessControlList


2–22 Version 3.6

When the ORB receives a call from a client, it first identifies andlocates the correct object implementation. It then compares the role ofthe client request to the role found in the ACL. If the ORB finds amatching role, it forwards the request to the object implementation.If not, the request is denied.

In the case of a cascaded call, the process is repeated in the secondstage of the call. The ORB again locates the correct objectimplementation, compares the role of the client to that of the serverand forwards or denies the request.

The operation of comparing roles might or might not cross additionalprocess boundaries, depending on the location of the ACL. Whether itcrosses additional process boundaries or not, TME 10 authenticationand authorization consumes resources, which increases the timerequired to complete a request. This, however, is the only means forproviding a truly secure client-server environment.

Dynamic InvocationWhen a client initiates a request by way of the DII, it must first querythe interface repository. The interface repository provides the storage,distribution, and management of the interface definitions for acollection of related objects.

The interface repository is maintained as a collection of interfaceobjects. Refer to the CORBA specification for a list of these objects,all of which are supported by the TME. Each of the objects specifiedas part of the interface repository are TME 10 objects.



Com

mon O

bject Request

Broker A

rchitecture

This fact is significant because each time you query the interfacerepository, it is managed as a request to an object. Review thefollowing diagram:

This diagram depicts the first step in dynamic invocation. Thelookup_id method retrieves the operation signature. This request is nodifferent than any other request, and like any other request that returnsdata, it must cross process boundaries at least four times beforecompletion.

When the client obtains the operation signature, it can then initiate thedesired request by way of the DII. The DII constructs a request andforwards it to the ORB. The ORB then passes the request to the objectimplementation.

Each dynamic request is similar to a cascaded call, because the clientmust contact at least two objects: the interface repository and theobject implementation that performs the request. Like a cascaded call,dynamic invocation is quite expensive.

This expense is compounded by the tasks performed by the DII whenit constructs the request. The details of such tasks are beyond the scopeof this chapter. It is sufficient to understand that the activity associatedwith dynamic invocation consumes additional resources and is,consequently, quite expensive.

ORB 1

ClientInterfaceRepository

1 234


2–24 Version 3.6

Persistent Attribute StorageTME 10 objects are persistent. Object persistence is advantageousbecause the object does not reside in a process: it is permanently storedin a physical location. Thus, if the process in which the operationresides is destroyed, the object is not destroyed with it. See “TME 10Objects are Persistent” on page 5-13 for more information aboutpersistent storage of objects.

In addition to persistent storage for objects, TME 10 offers—as adefault—persistent storage for object attributes. In some objectsystems, object attributes exist only in the process in which the objectis active. In such object systems, if the process is destroyed, so is theobject state even though the object may survive.

As previously mentioned persistent storage is advantageous, but likeall advantages there is a cost associated with it. Review the followingdiagram:

This diagram is similar to a previous one that depicted the ORB systemfrom the perspective of the operating system. The persistent storageprogram has been added to the diagram to depict the management ofthis feature.

Client Program

Persistent Storage/


ReturnData

Set/Get Function

ORB/Object Adapter

ORB System Processes



Com

mon O

bject Request

Broker A

rchitecture

When the object is implemented, you can set the value of objectattributes using amutator function, which the TME 10 ADE IDLcompiler generates. A mutator function is a function designed to set orchange the value of an object attribute.

The request to set the value of an attribute initially resides in the clientprocess. To initiate the request, the client must pass it to the persistentstorage program, which shares the ORB process. Such requests willalways cross at least one process boundary.

If you want to retrieve the value of an object attribute, you can do soby calling anaccessor function, which the TME 10 ADE IDL compileralso generates. An accessor function is a function designed to retrievethe value of an object attribute.

Like requests to set object attributes, requests to retrieve attributesreside in the client process. When the client passes the request to thepersistent storage program, the request migrates to the persistentstorage process. The persistent storage program then retrieves theattribute value and forwards it to the client. Such requests always crossprocess boundaries at least twice.

Persistent object attributes also provide security because you canspecify a required privilege for setting or retrieving attribute values.

Persistent attribute storage is optional. You can provide your ownstorage or provide no storage for object attributes. As the developeryou should consider the following:

■ The cost of persistent storage weighed against the advantage itprovides.

■ The cost of providing your own storage compared to the cost ofusing the persistent storage provided by TME 10 ADE.


2–26 Version 3.6

Persistent Storage and TransactionsTME 10 ADE supports the concept of two-phased commit using anested transaction rollback facility. This facility enables you to specifytransactions that make changes to your database before actuallyperforming the transaction.

The client is notified of any errors that might occur as a result of thetransaction by way of an exception. The client then has the opportunityto abort the transaction before the changes are made.

A detailed explanation of TME 10 transactions is beyond the scope ofthis chapter. It is sufficient to understand that persistent changes toTME 10 objects are transaction driven, which ensures atomic updates.

See “TME 10 Nested Transactions” on page 4-57 and theApplicationServices Manual Volume I for more information about TME 10 nestedtransactions.


IDL-D

efined Interfaces

3IDL-Defined Interfaces

This chapter describes the CORBA-specified Interface DefinitionLanguage (IDL). CORBA-specified IDL provides a standard fordefining interfaces in a CORBA-compliant environment. The materialin this chapter explains the following topics:

■ Interface and Implementation Separation

■ Introduction to OMG IDL

■ CORBA-compliant Interfaces

■ IDL Specification

■ IDL Naming and Scopes

■ Additional IDL Information

You should read this chapter if you are unfamiliar with either of thefollowing:

■ The concept of separating an object interface from itsimplementation

■ OMG IDL

The information presented in this chapter complements theinformation presented in the CORBA specification. See the CORBAspecification for details about IDL.

3

Interface and Implementation Separation

3–2 Version 3.6

Interface and Implementation SeparationIn traditional programming environments, you provide the interfaceand the implementation simultaneously. You define the interface byproviding a function name andsignature. The signature consists of allthe function parameters as shown in the following C source codefragment:

void Container_add_member (member);

This one line of code is the interface to the function, because it defineshow the function is called. It does not, however, specify the functionbehavior.

To specify the function behavior, you must implement the function.You implement the function by writing a series of source codestatements that specify the function behavior. The following C sourcecode fragment depicts one possible implementation of the function:1 char Container[100][20];

2 int last_used=0;

3

4 void Container_add_member(char *member){

5 last_used++;

6 strcpy(Container[last_used], member);

7 }

In this example, the container is implemented as an array. Theinterface takes a single argument,member. The implementation thenincrementslast_used, which represents the current array element.Finally, it adds the newmember to the array. Rather than an array, thecontainer could be implemented as a linked list as shown in thefollowing code fragment:1 struct Container_rec {

2 struct Container_rec *next;

3 char *member;

4 }

5 struct Container_rec *Container_head;

6

7 void Container_add_member(char *member){

8 struct Container_rec *new_member;

9 new_member = malloc(sizeof

10 (struct Container_rec));

Interface and Implementation Separation


IDL-D

efined Interfaces

11

12 new_member->member = member;

13 new_member->next = Container_head;

14 Container_head = new_member;

15 }

As in the previous example, the interface takes a single argument,member. The implementation, however, is quite different. It firstallocates memory to accommodate a newmember, and then places themember in the new record previously allocated. Finally, theimplementation adds the new record to the head of the list.

The interface is identical in both examples, but each implementation isdifferent. As the developer, you decide how a function should beimplemented.

In a traditional environment, you provide an integrated interface andimplementation as the examples demonstrate. That is, the interface andthe implementation are contained in the same program, which worksquite well in environments that use large monolithic programs.

In distributed object-oriented systems, however, it is better to separatethe interface from the implementation. This allows clients to concernthemselves with only the operations available from the server.They can be unconcerned with the way the operation is performed, orif the implementation is changed in a future release.

TME 10 ADE provides a way to separate interfaces fromimplementations. Subsequent sections describe this technique.

CORBA-compliant Programming EnvironmentIn a CORBA-compliant environment, clients do not make functioncalls. Instead, they request operations of object implementations.Each object implementation has a defined interface consisting of allthe operations that can be requested of it. Each operation in theinterface is associated with a function (method) that provides therequested service.

To define the interface, you list all the available operations and thesignatures of those operations, then compile this list using an IDLcompiler. This process is similar to the way you define functionprototypes in a C header file.

Introduction to OMG IDL

3–4 Version 3.6

You implement the interface by implementing the methods associatedwith the operations that compose the interface. Finally, youaccommodate the installation by specifying how the ORB will find theimplemented methods.

TME 10 ADE provides an IDL compiler that supports a specificationlanguage, similar in syntax to C++, that enables you to separate themethod interfaces from the method implementation. This separationenables clients to initiate requests in the common ORB environmentspecified by CORBA.

The specification language that provides this support is the TME 10ADE Extended Interface Definition Language (TEIDL). TEIDL is afully upward-compatible extension of OMG IDL.

IDL is a declarative language that enables you to define objectinterfaces without regard to the object implementation. Subsequentsections provide important information about using IDL. See theCORBA specification for details about IDL and its syntax.

Introduction to OMG IDLIn CORBA, object interfaces are described using IDL. IDL is adeclarative language similar in syntax to C++. As a declarativelanguage, OMG IDL heightens the separation of interface andimplementation, which is emphasized in object-oriented systemsdevelopment.

The declarative nature of constructs supported by IDL facilitatesinterface definition rather than implementation. Furthermore,object-oriented systems rely on encapsulation, so clients are unawareof the object implementation; they are aware of only the services theycan request. IDL enables developers to generate client stubs, whichsupport the invocation of defined interfaces. These interfaces facilitatethe separation of interface and implementation.

The IDL compiler provided by TME 10 ADE translates IDL constructsto C programming language modules according to theCORBA-specified ANSI C language binding.

CORBA-compliant Interfaces


IDL-D

efined Interfaces

The CORBA Specification Revision 1.1 supports only C languagebindings. Subsequent versions will support other programminglanguages such as C++.

CORBA-compliant InterfacesA primary objective of the CORBA specification is to allow clientprograms to request operations from objects without concern for theimplementation of the object or the operation performed in its context.

Each object implementation must contain a set of operations, and eachoperation must be associated with specific object behavior. That is,when an object receives a request from a client program, it mustrecognize the request and know how to respond. Objects belonging todifferent classes may respond differently to the same request.Furthermore, objects belonging to different classes may each havedifferent operations available to them.

Consequently CORBA-compliant interfaces to objects are initiallydefined in IDL. The IDL definition declares which operations areavailable to an object type, the signatures for each operation, and theexceptions it can raise.

The ORB interface can then manage the request regardless of how theobject is implemented. The primary objective of IDL is to provide astandard for the way in which developers define interfaces.

Interface InheritanceThe CORBA specification is designed to enhance development inobject oriented development environments. Inherent in suchenvironments is the notion of inheritance.

The advantage of environments that support inheritance compared tothose that do not is that software development is more efficient.

When a developer writes a program, it can be used as a model for otherprograms that perform similar functions. Environments that do notprovide inheritance require developers to find the source code, copy itto a new file, and edit the new file to fit their needs.

CORBA-compliant Interfaces

3–6 Version 3.6

This process is not only error prone and time consuming, but alsoincreases future maintenance costs. Inheritance allows developers torefer to these model programs and then add new features not presentin the original program. The reference to the old program thenbecomes part of the new program.

You cannot redefine operations inherited from other interfaces (baseinterfaces) in derived interfaces. To experienced object-orientedprogrammers, this might seem to prevent CORBA objects from beingused in a polymorphic fashion.

The separation of interfaces from their implementation, however,ensures that CORBA objects can indeed be implementedpolymorphically. Object implementations are free to use anyinheritance features of their implementation languages independent ofIDL inheritance. The degree of polymorphism seen by clients dependsonly on how object references are mapped to the client implementationlanguage.

See “IDL Operation Declarations” on page 3-19 and the CORBAspecification for more details about interface inheritance.

IDL-defined InterfacesAn IDL-defined interface contains the following:

■ Interface name

■ Operations available to the interface

■ Signature of each operation

■ Interface attributes

■ Exceptions each operation can raise

IDL-defined interfaces define two things: the services that a specifictype of object can provide and a way for clients to request thoseservices—regardless of how or where the object is implemented.

The services are defined by the operations specified in the IDLdefinition. Clients request the services through either the client stub,which the IDL compiler produces, or through the DII. The request isthen delivered to the object implementation by way of the server

IDL Specification


IDL-D

efined Interfaces

skeleton associated with the requested operation. Refer to thefollowing sections for more information:

■ “Client Stubs” on page 2-9

■ “Dynamic Invocation Interface” on page 2-10

■ “Server Skeletons” on page 2-12

IDL is a declarative language, and so it does not include anyalgorithmic structures. It obeys the same lexical rules as C++, althoughit provides new keywords to support distribution concepts. It alsoprovides full support for standard ANSI C preprocessing features.

IDL SpecificationAn IDL specification is a block of information that completely definesone or more interfaces. Your IDL file should contain the followingmajor components:

■ IDL declarations

■ Module definitions

■ Interface definitions

■ Operation definitions

■ Attribute definitions

■ Preprocessor directives

The following IDL source code depicts an example IDL file thatcontains each of these components:1 // PhoneEntryGUI interface

2 interface PhoneEntryGUI : TMF_UI::UserInterfaceBase {

3 void ui_phone_props(

4 in TMF_Types::StringList argv,

5 in TMF_Types::StringList env,

6 out TMF_Types::OctetList commands);

7 };

8

9 // PhoneListIterator interface

10 interface PhoneListIterator {

11 boolean next_entries(

12 in long how_many,

IDL Specification

3–8 Version 3.6

13 out PhoneEntryInfoList entry_list)

14 raises(ExPhoneError,

15 SysAdminException::ExInvalid);

16

17 void destroy_iterator();

18 raises(SysAdminException::ExInvalid);

19 };

20 interface PhoneListProfile : TMF_CCMS::Profile,

21 PhoneEntryGUI,

22 PhoneListIterator

23 {

24 // Create an entry.

25 void create_phone_entry(

26 in PhoneEntryInfo new_entry,

27 out string key)

28 raises (ExPhoneError, ExPhoneError1);

29

30 // Create multiple records

31 void create_entries(

32 in PhoneEntryInfoList entries,

33 out TMF_CCMS::Database::add_result_list

34 results);

35

36 // Modify an existing entry.

37 void modify_phone_entry(

38 in string key,

39 in PhoneEntryInfo new_entry)

40 raises (ExPhoneError, ExPhoneError1);

41

42 // Remove an entry.

43 void delete_phone_entry(

44 in string key)

45 raises (ExPhoneError1);

46

47 // Remove several entries at a time.

48 void delete_phone_entries(

49 in TMF_Types::StringList keys)


51

52 // Get the PhoneEntryInfo for the record

53 // identified by 'key'

54 void get_phone_entry(

IDL Specification


IDL-D

efined Interfaces

55 in string key,

56 out PhoneEntryInfo entry)


58

59 // Fetch several records at once.

60 void get_phone_entries(

61 in TMF_Types::StringList keys,

62 out PhoneEntryInfoList entries)


64

65 // Return all entries in the database.

66 // Can return an iterator.

67 void get_all_entries(

68 out PhoneEntryInfoList entries,

69 out PhoneListIterator iterator);

70 raises (ExPhoneError);

71

72 // Return a list of the keys in the database

73 void list_phone_entries(

74 out TMF_Types::StringList keys);

75

76 // Given a name, returns every entry

77 // whose name field matches the string.

78 void find_by_name(

79 in string name,


81 out PhoneListIterator iterator)


83 };

Subsequent sections describe each component depicted in thisexample. Additional information is also available in the CORBAspecification.

IDL DeclarationsLike C++, IDL supports the following kinds of declarations:

■ Types

■ Constants

■ Exceptions

IDL Specification

3–10 Version 3.6

IDL Type Declaration

IDL provides constructs for naming data types. These data types aredeclarations, similar to those in C, that associate an identifier with adata type. The following table presents the type declarations supportedby IDL:

Supported Type Declarations

Basic Types

Type Definition Value

Integer Type See “Basic Types” in the CORBA specification

Floating Point Type See “Basic Types” in the CORBA specification

Char Type See “Basic Types” in the CORBA specification

Boolean Type See “Basic Types” in the CORBA specification

Octet Type See “Basic Types” in the CORBA specification

Any Type See “any” on page 3-11

Constructed Types


Structures Similar to a C languagestruct

Union See “Mapping for Union Types” in the CORBA specification

Enumerations See “enumerations” on page 3-12

Template Types


Sequence See “sequence” on page 3-12

String See “string” on page 3-12

Complex Declarator


Array See “array” on page 3-13

IDL Specification


IDL-D

efined Interfaces

any

Theany data type enables you to specify a data type at run-time.It consists of a data pointer and a type code constant. The data pointerpoints to data of the specified type.

The type code constant specifies the actual data type and takes the formTC_datatype. Data of typeshort, for example, has a data constant ofTC_short. See “TypeCode” on page 6-21 and the CORBAspecification for more information about type code constants. Use theany data type if you do not want to specify a data type at compile time.The following code fragment presents an example how to define aninterface of typeany:1 interface foo {

2 // A method that does something

3 void do_something(in any);

4 };

Thedo_something interface enables the method to take an inputparameter of any type. The method implementation fordo_somethingmight look something like the following C code fragment:1 void t_imp_foo_do_something(any *data){

2 if (t_TypeCode_equal(type, &ev, TC_Object)) {

3 /* Do something with an object reference */

4 }

5 else if (t_TypeCode_equal(type, &ev, TC_string)) {

6 /* Do something with a string */

7 }

8 else if (t_TypeCode_equal(type, &ev, TC_boolean)) {

9 /* Do something with a boolean */

10 }

11 else {

12 /* Raise an exception */

13 }

14 }

With the example implementation, the client can pass any of thefollowing data types to thedo_something method:

■ Object

■ string

■ boolean

IDL Specification

3–12 Version 3.6

The following client can therefore pass a string to thedo_somethingmethod while other clients can pass other types of data to it dependingon the requirements of their particular application:1 void foo() {

2 any x;

3 char *name;

4 /* Get a name */

5 name = get_name();

6 /* Do something with it */

7 x._type = TC_string;

8 x._value = &name;

9 do_something(&x);

10 }

enumerations

IDL Enumerated types use the keywordenum. This data type consistof ordered lists of identifiers. A maximum of 232 identifiers may bespecified in an enumeration. Consequently, the enumerated namesmust map to a data type capable of representing an enumeration of thissize. The order in which the identifiers are named in an enumerationspecification defines the relative order of the identifiers.

Enumerated types may also be named using atypedef declaration.

sequence

An IDL sequence is a one-dimensional array with two characteristics:a maximum size (which can be fixed at compile time) and a length(which is determined at run time). The second parameter in a sequencedeclaration indicates the maximum size of the sequence, and it isoptional. Sequences in which the maximum size is specified are knownasbounded sequences. Sequences in which the maximum size is notspecified are known asunbounded sequences.

string

An IDL string consists of one or more of eight-bit quantities excludingnull. A string is similar to a sequence of characters.The argument tothe string declaration is the maximum size of the string. Thespecification of maximum size is optional. String declarations thatcontain a maximum size specification are known as bounded strings.

IDL Specification


IDL-D

efined Interfaces

String declarations that do not contain a maximum size specificationare known as unbounded strings.

array

IDL supports multidimensional, fixed-size arrays. An IDL arrayincludes explicit sizes for each dimension, which is fixed at compiletime. When an array is passed as a parameter in an operationinvocation, all elements of the array are transmitted.

Data Type Mapping

The source code generated by an IDL compiler is similar inappearance to the original IDL code. In some cases, however, asignificant difference exists between defined IDL data types and thedata types the compiler produces. The following table presents themapping of basic IDL data types to the C data types the compilerproduces:

Mapping for Basic Data Types

IDL C

short short

long long

unsigned short unsigned short

unsigned long unsigned long

float float

double double

char char

boolean unsigned char

octet unsigned char

enum unsigned long

any typedef struct any {TypeCode _type; void *_value;} any;

IDL Specification

3–14 Version 3.6

Mapping for complex data types is beyond the scope of this manual.The mapping for these data types is detailed in the CORBAspecification.

IDL Constant Declaration

IDL provides constructs for declaring constants, similar in syntax andsemantics to C++ constant declarations as shown in the following codefragment:

const long L=50

IDL Exception Declaration

IDL supports the declaration of data structures that can be returned toindicate the occurrence of an exceptional condition. In such an event,anexception of a specified type is created and returned to the client.Exception types are declared in an IDL interface definition using theraises keyword:1 void find_by_name(

2 in string name,


4 out PhoneListIterator iterator)


6 };

Clients can then be notified of the exception occurrence and reactaccordingly. See “Raising Exceptions” on page 3-21 for moreinformation about raising exceptions.

IDL Module DefinitionThe module construct is used to scope IDL identifiers such asinterfaces and operations. By defining an interface within a module,you can unambiguously specialize each interface as shown in thefollowing Tivoli CCMS example:1 module TMF_CCMS {

2 typedef long time_t;

3 interface ProfileBase;

4 interface Profile;

IDL Specification


IDL-D

efined Interfaces

5 interface ProfileManager;

6 ...

7 }

TheTMF_CCMS module provides several interfaces:

■ ProfileBase

■ Profile

■ ProfileManager

The IDL code for each of these interfaces can contain multipleoperations, and IDL-defined data types. Themodule constructsimplifies the task of providing IDL naming schemes, and simplifiesthe task of using these naming schemes. It facilitates a hierarchicalapproach to IDL interfaces.

You can also use modules to make IDL-defined data types available tomultiple interfaces. Consider the following expansion of the previousexample:1 module TMF_CCMS {

2 typedef long time_t;

3 interface ProfileBase;

4 interface Profile;

5 interface ProfileManager;

6 struct push_result {

7 SysAdminTypes::ObjectLabel object;

8 TMF_Types::OctetList data;

9 any ex;

10 };

11 typedef sequence <push_result> push_result_list;

12 struct batch_result {

13 SysAdminTypes::ObjectLabel object;

14 any ex;

15 };

16 typedef sequence <batch_result> batch_result_list;

17 struct pending_action {

18 string key;

19 string action_key;

20 string name;

21 };

22 ...

23 }

IDL Specification

3–16 Version 3.6

Line 6 of this example contains an IDL-defined data type calledpush_result. This type is implicitly available to all interfaces that arespecified in that module. Such data types are also available from otherfrom external interfaces using the scope resolution operator (:: ).See “IDL Naming Scopes” on page 3-28 for more information aboutnaming scopes.

IDL modules permit the declaration of IDL interfaces, and thedefinition of new IDL data type. They do not permit the declaration ordefinition of IDL operations. IDL Operations must be defined withinan IDL interface.

IDL Interface DefinitionAn interface definition consists of an interface header and an interfacebody. The following example depicts a complete interface definition:1 // PhoneEntryGUI interface

2 interface PhoneEntryGUI : TMF_UI::UserInterfaceBase {

3 void ui_phone_props(

4 in TMF_Types::StringList argv,

5 in TMF_Types::StringList env,

6 out TMF_Types::OctetList commands);

7 };

Interface Header

The interface header consists of two elements: an interface name andan optional inheritance specification.

The identifier that names an interface defines an IDL data type.The name must be preceded by the keywordinterface as shown:1 interface PhoneEntryGUI : TMF_UI::UserInterfaceBase {

2 ...

3 }

A single colon (:) denotes inheritance from another interface, and so,in this example,PhoneEntryGUI inherits fromUserInterfaceBase.The single colon is known as the inheritance operator, and it specifiesthat the current interface (PhoneEntryGUI) is derived from theinherited interface (UserInterfaceBase).

IDL Specification


IDL-D

efined Interfaces

Notice thatUserInterfaceBase is preceded by a double colon (:: ) anda module specificationTMF_UI . The double colon (known as theresolution operator) denotes the fully scoped name of the inheritedinterface. The fully scoped name includes both the module and theinterface.

Elements of Derived Interfaces

A derived interface can declare new elements as necessary and you canrefer to the inherited elements as if they were defined in the derivedinterface. You can also redefine the following inherited elements in thederived interface:

■ Constants

■ Types

■ Exceptions

You cannot redefine inherited operations or attributes.

If you redefine inherited elements in the derived interface, you can stillrefer to them as they were originally defined. In such cases you referto the original elements using the name resolution operator.Consider the following example:1 interface foo {

2 struct s{

3 long L;

4 };

5 };

6 interface other: foo{

7 struct s{

8 char C;

9 };

10 s op();

11 foo::s op();

12 };

The example declares two structures with the names in lines 2 and 7.Each structure is locally declared for its interface.

Thes op() declaration (line 10), refers to the structures that is locallydeclared for interfaceother. Thefoo::s op() declaration (line 11)refers to the structures that is locally declared for interfacefoo.

IDL Specification

3–18 Version 3.6

References to base interface elements must be unambiguous.Ambiguity occurs when the expression refers to a constant, type, orexception in more than one base interface as shown in the followingcode fragment:1 interface foo {

2 struct s{

3 long L;

4 };

5 };

6 interface other {

7 struct s{

8 float Y;

9 };

10 };

11 interface bar: foo, other{

12 s op();

13 ::s op();

14 };

In this example, thes op() on line 13 declaration is ambiguous becauseit can refer to either thefoo or other base interfaces. To make theoperation unambiguous, the operation should be labeled as eitherfoo::s op() or other::s op().

See “IDL Naming Scopes” on page 3-28 for information about namingscopes.

Interface Body

An interface body can contain any of the following items:

■ Any of the declarations previously described

■ The operations available to the interface

■ The operation signature

■ The exceptions each operation can raise

■ Any interface declarations. See “Forward Declarations” onpage 3-19 for more information about forward declarations

Finally, IDL allowsempty interfaces, which are interfaces that containno declarations.

IDL Specification


IDL-D

efined Interfaces

Forward Declarations

A forward declaration declares the name of an interface withoutdefining it. This enables a programmer to refer to an interface beforeit has been defined.

The syntax consists simply of the keywordinterface followed by anidentifier that names the interface followed by a semicolon. You mustprovide the actual definition somewhere in either the same IDL file oran IDL file that is included using a preprocessor directive. Multipleforward declarations of the same interface name are legal.

IDL Operation DeclarationsOperation declarations in IDL are similar to C function declarations.The declaration can contain the following components:

■ The return result type, which may be any type that can be definedin IDL. Operations that do not return a result must specify typevoid.

■ An identifier, which is the name of the operation.

■ A parameter list that specifies zero or more parameterdeclarations for the operation.

■ Optional expressions to raise one or more exceptions.

Operation Parameters

A parameter declaration must have a directional attribute that informsthe object request broker of the direction in which the parameter is tobe passed. The following directional attributes are available:

■ in—The parameter is passed from client to implementation.

■ out—The parameter is passed from implementation to client.

■ inout—The parameter is passed in both directions.

Interface implementations shouldnot attempt to modify aninparameter. The effect of such an action is undefined.

If an exception is raised as a result of a method invocation, the valuesof the return result and anyout andinout parameters are undefined.

IDL Specification

3–20 Version 3.6

When an unboundedstring or sequence is passed as aninoutparameter, the returned value cannot be longer than the input value.

Parameter Mapping

When a client requests an operation in C, it must obey rules thatspecify which parameters must be passed, how to pass them, and whois responsible for allocating and freeing memory (the client or theORB).

Passing Parameters

The following table depicts how parameters of different types arepassed to and from clients:

Data Type Pass In Pass Out/Inout Return Result

short value address of variable to holdvalue

receive value

long value address of variable to holdvalue

receive value

unsigned short value address of variable to holdvalue

receive value

unsigned long value address of variable to holdvalue

receive value

float value address of variable to holdvalue

receive value

double value address of variable to holdvalue

receive value

boolean value address of variable to holdvalue

receive value

char value address of variable to holdvalue

receive value

octet value address of variable to holdvalue

receive value

IDL Specification


IDL-D

efined Interfaces

When passing data by address to the ORB, the address must point tovalid data. Thus, in the case of asequence, the client or objectimplementation must pass a valid address of a sequence structure.The fields of the sequence structure can be zero. Similarly, zero is notvalid data for an object reference. The client or object implementationmust instead use the symbolOBJECT_NIL .

See “void t_TypeCode_decode_ascii(TypeCode tc, char ** data,XSN_BUF *dbuf)” on page 6-26 and theApplication Services Manualfor information about allocation and release of memory when passingparameters.

Raising Exceptions

When you declare an operation in an interface, you must indicatewhich exceptions (if any) the operation can raise. Use the IDLraisesexpression to present the required exceptions in your interfacedefinition as shown in the following example:

raises (ExDbNotFound, ExDbKeyNotFound, ExUsage);

enumeration value address of variable to holdvalue

receive value

objectreference

Object value address of variable to holdObject

receive value ofObject

struct addr of struct addr of variable to hold struct receive value of struct

union addr of struct addr of variable to hold struct receive value of struct

string addr of firstchar

addr of (char *) variable receive char *

sequence addr of seq.struct

addr of seq. struct receive value of seq.struct

array addr of firstelem

addr of first elem receive addr of 1stelem

Data Type Pass In Pass Out/Inout Return Result

IDL Specification

3–22 Version 3.6

Exceptions can be either operation-specific (as depicted here), or theycan be system exceptions. You cannot specify system exceptions in araises expression. The specification must be limited to the following:

■ Any of the exceptions CORBA-defined run-time exceptions.

■ Any exception types you define, which can be derived from TME10 exceptions.

Operation Specific Exceptions

Each operation specific exception is characterized by the followingcomponents:

■ The keywordexception

■ The exception name

■ A return specification

A typical IDL exception definition follows:

exception ExInvalid : ExException { string resource_name;};

As shown in the presented example, your exception can be derivedfrom other exception classes. If you declare an exception with datamembers, the member values will be accessible when an exception israised. If you do not specify any members, no additional informationis accessible about the exception when it is raised; it returns aNULLpointer.

Clients that do not expect operation-specific exceptions can stillreceive a system exception.

System Exceptions

In addition to the operation-specific exceptions specified in theraisesexpression, there are a set of system exceptions that can be signalledby the request broker.

Each system exception also includes acompletion_status code, whichtakes one of the values {YES, NO, MAYBE}. These values have thefollowing meanings:

IDL Specification


IDL-D

efined Interfaces

■ YES—The object implementation has completed processingprior to the exception being raised.

■ NO—The object implementation was never initiated prior to theexception being raised.

■ MAYBE—The status of implementation completion isindeterminate.

CORBA specifies the following system exception types, which arepresented as part of theStExcep module:

System Exception Type Description

StExcep_UNKNOWN The unknown exception

StExcep_BAD_PARAM An invalid parameter was passed

StExcep_NO_MEMORY Dynamic memory allocation failure

StExcep_IMP_LIMIT Violated implementation limit

StExcep_COMM_FAILURE Communication failure

StExcep_INV_OBJREF Invalid object reference

StExcep_NO_PERMISSION No permission for attempted operation

StExcep_INTERNAL ORB internal error

StExcep_MARSHAL Error marshalling parameter/result

StExcep_INITIALIZE ORB initialization failure

StExcep_NO_IMPLEMENT Operation implementation unavailable

StExcep_BAD_TYPECODE Bad typecode

StExcep_BAD_OPERATION Invalid operation

StExcep_NO_RESOURCES Insufficient resources for request

StExcep_NO_RESPONSE Response to request not yet available

StExcep_PERSIST_STORE Persistent storage failure

IDL Specification

3–24 Version 3.6

IDL Attribute DeclarationIDL supports the definition of attributes in interfaces. Such attributesdo not define characteristics of the interface as they do on objects.Rather, they provide a way to set and retrieve object attributes.

For each declared attribute in the defined interface, you can provide anoperation to set the attribute value and an operation to retrieve it.You can then provide the object attributes and the methods thatperform the set and retrieve functions as part of your implementation.

The following code fragment shows an attribute declaration:

readonly attribute position_t position;

The optionalreadonly keyword specifies that the attribute value canonly be retrieved—it cannot be set—through the current interface.Consider the following example:1 interface foo {

2 enum material_t {rubber, glass};

3 struct position_t {

4 float x, y;

5 };

6

StExcep_BAD_INV_ORDER Routine invocations out of order

StExcep_TRANSIENT Transient failure—reissue request

StExcep_FREE_MEM Cannot free memory

StExcep_INV_IDENT Invalid identifier syntax

StExcep_INV_FLAG Invalid flag was specified

StExcep_INTF_REPOS Error accessing interface repository

StExcep_CONTEXT Error processing context object

StExcep_OBJ_ADAPTER Failure detected by object adapter

StExcep_DATA_CONVERSION Data conversion error

System Exception Type Description

IDL Specification


IDL-D

efined Interfaces

7 attribute float radius;

8 attribute material_t material;

9 readonly attribute position_t position;

10 ...

11 };

The attribute in line 9,position_t, uses thereadonly keyword.Consequently, the value ofposition_t cannot be set by the user of theapplication. The attribute declarations in the previous example areequivalent to the following pseudo-code specification:1 float foo__get_radius ();

2 void foo__set_radius (in float r);

3 material_t foo__get_material ();

4 void foo__set_material (in material_t m);

5 position_t foo__get_position ();

This example shows that the attributeposition_t has only theoperationfoo__get_position() available to it. Thefoo__get_position() function retrieves the value ofposition_t.

The following rules apply to attribute declarations:

■ Only the attribute name is subject to the IDL naming scope rules.The operations for setting and retrieving the attribute values willnot collide with any legal operation names that can be specifiedin IDL.

■ Attribute operations return errors by means of system exceptions.See “System Exceptions” on page 3-22 for a list of systemexceptions.

■ Attributes are inherited and attribute names cannot, therefore, beredefined in the inheritance chain.

Attribute Mapping

When you declare an attribute in IDL, the compiler producesoperations to retrieve and set the value of that attribute. If you specifythe attribute asreadonly, it will produce only the operation used toretrieve the attribute value. The following code fragment depicts atypical IDL attribute declaration:1 interface foo {


3 float x, y;

IDL Specification

3–26 Version 3.6

4 };



7 };

The following code fragment depicts the CORBA-specified mappingfrom the presented example to C source code, which is produced by thecompiler:1 typedef struct foo_position_t {

2 float x, y;

3 }

4 foo_position_t;

5 extern float foo__get_radius(foo o, Environment *ev);

6 extern void foo__set_radius(foo o, Environment *ev, float r);

7 extern foo_position_t foo__get_position(foo o, Environment *ev);

In this example, the compiler produces a client entry point for each ofthe declared operations:foo__get_radius(), foo__set_radius(), andfoo__get_position(). Two underscore characters (__) separate thename of the interface from the wordsget or set in the names of thefunctions. See “Attribute Specification” on page 4-28 for moreinformation about implementation attributes.

If the calling to either function fails, the operation returns one of thesystem exceptions. See “System Exceptions” on page 3-22 for acomplete list of system exceptions.

IDL Preprocessor DirectivesThe TEIDL compiler supports C preprocessor directives.These directives enable you to perform the following:

■ Include other files in your main IDL files (using the#includedirective).

■ Use symbols instead of hard-coded names and constants (usingthe#define directive).

IDL Specification


IDL-D

efined Interfaces

■ Take advantage of conditional compilation (with the#ifndefdirective). The following IDL code fragment depicts an exampleconditional include directive for a file namedfoo.idl:

1 #ifndef foo_idl

2 #define foo_idl

3 /* define the interface here */

4 #endif

■ Control the compilation of specified interface definitions.The TEIDL compiler supports the use of a singlepragmatoken—generate.

Thegenerate pragma directs the compiler not to producelanguage binding of included files. The following sectionprovides details about the#pragma generate directive.

#pragma generate

If an interface inherits from interfaces defined in other included files,then the IDL compiler sees one file that contains all the declaredinterfaces—even those that are defined externally. Unless it isotherwise instructed, it will generate source code for all the externallydefined interfaces as well as those defined internally. Such actions canproduce undesirable results.

The#pragma generate directive can be used to control source codegeneration of externally defined, but locally included interfaces.It supports the following values:

■ False

■ True

False turns off source code generation andTrue turns it back on.The following example depicts the proper syntax:1 #pragma generate False

2 #include <tivoli/SysAdminTypes.idl>

3 #pragma generate True

4 module Containment {...

All externally defined interfaces for which you do not want to generatesource code should be enclosed between a generateFalse/True pair asshown in this example.

IDL Naming Scopes

3–28 Version 3.6

IDL Naming ScopesIDL interfaces often inherit from each other. For this reason IDLsupports a name reference scheme that defines a naming scope.The naming scope for a particular interface is implicitly defined by theentire IDL file. The following kinds of identifiers are scopedidentifiers:

■ Types

■ Constants

■ Enumeration values

■ Exceptions

■ Interfaces

■ Attributes

■ Operations

The following kinds of definitions can also form nested scopes:

■ Module

■ Exception

■ Interface

■ Structure

■ Union

■ Operation

Some restrictions apply, however, to how you can nest a naming scope.You cannot, for example, nest interfaces within each other. Therefore,you cannot nest the naming scope of one interface within anotherinterface.

The following rules apply to IDL naming scopes:

■ An identifier can be defined only once in a single scope, althoughit can be redefined in nested scopes.

■ IDL identifiers are case insensitive. That is, the compilerinterprets two identifiers that differ only in the case of theircharacters as redefinitions of one another, which produces acompilation error.

IDL Naming Scopes


IDL-D

efined Interfaces

■ References to a definition are case sensitive. That is, previouslydefined identifiers must use the same case as the definingoccurrence.

■ Type names defined in a scope are available for immediate usewithin that scope.

IDL Scope ResolutionThe way an IDL compiler resolves a naming scope depends on the wayyou refer to a variable name in the IDL file. There are two possibilities,both of which are specified by CORBA: unqualified names andqualified names.

Unqualified names are those that do not refer to the scope explicitly, asshown in the following example:1 struct method_struct {

2 Object oid;

3 string label;

4 }

5

6 interface Propagation {

7 enum force_flags {

8 no_force, force, force_all,

9 initial_merge

10 };

11

12 readonly attribute oid_label_list_t

13 last_failed;

14 void merge(in string db_name, // private

15 in string_list_t keylist,

16 in Database::record_list rec_list,

17 in method_struct source,

18 in string method,

19 in force_flags flags,

20 in boolean one_step,

21 in boolean get_unchanged,

22 in any appdata)

23 raises(ExDbNotFound,

24 ExDbKeyNotFound, ExUsage,

25 ExWDenied);

26 }

IDL Naming Scopes

3–30 Version 3.6

The parameter typemethod_struct in operationmerge (lines 14through 25) does not provide a scope reference and is therefore anunqualified name. The compiler resolves the naming scope bysuccessively searching farther out in enclosing scopes, finding a matchin lines 1 through 4. Once an unqualified name is used in a scope, itcannot be redefined in the current scope.

Qualified names are those that refer to the scope explicitly, as shownin the following example:1 struct object_label {

2 Object oid;

3 string label;

4 }

5

6 interface Propagation {

7 enum force_flags {

8 no_force, force, force_all,

9 initial_merge

10 };

11

12 readonly attribute oid_label_list_t

13 last_failed;

14 void merge(in string db_name, // private

15 in string_list_t keylist,

16 in Database::record_list rec_list,

17 in object_label source,

18 in string method,



21 in boolean get_unchanged,

22 in any appdata)

23 raises(ExDbNotFound, ExDbKeyNotFound,

24 ExUsage, ExWDenied);

25 }

The reference typerecord_list in operationmerge provides a scopereference to interfaceDatabase (which is defined elsewhere), and istherefore a qualified name. The compiler begins resolving the namingscope by examining the scope of interfaceDatabase.

Additional IDL Information


IDL-D

efined Interfaces

If the indicated operation is not found in theDatabase interface, itsearches farther out in enclosing scopes until the operation is found.If the operation is not found after the naming scope is exhausted, anexception is normally thrown.

Additional IDL InformationAdditional information about OMG IDL is located in the Chapter 4 ofthe CORBA Specification Revision 1.1.

Additional IDL Information

3–32 Version 3.6


TM

E 10 A

DE

Extended ID

L

4TME 10 ADE Extended IDL

This chapter describes TME 10 classes and the TME 10 ADEExtended IDL (TEIDL). TEIDL extends OMG IDL by providing amechanism for object implementation and installation details.The material describes the following:

■ TME 10 Classes

■ Implementation

■ Introduction to TME 10 ADE Extended IDL

■ Implementation Specification Constructs

■ Program Specification Constructs

■ Installation Specification Constructs

■ TEIDL Implementation Preprocessor Directives

■ TEIDL Compiler Output

■ ANSI C Binding

■ Bourne Shell Binding

■ Command Method Binding

■ TEIDL Compiler Operation

■ TEIDL BNF Grammar Description

You should read this chapter if you plan to implement your programsusing TEIDL or if you plan to compile IDL-defined interfaces usingthe TEIDL compiler.

4

TME 10 Classes

4–2 Version 3.6

TME 10 ClassesA class provides a common structure and behavior for objects referredto as instances of that class. Classes enable you to designgeneral-purpose objects that support the implementation ofgeneral-purpose applications. You can also customize instances ofgeneral-purpose objects in ways specific to your site requirements.

When you define an interface using IDL, you can also specify a classimplementation for that interface from which an instance can becreated. The TEIDL compiler creates the class from the interfaces youdefined. A class implementation, therefore, is merely theimplementation associated with a defined interface.

All the operations defined in the interface are available to all instancesof the class, and the class is said to support the interface that defines it.Furthermore, an interface can be supported by several different classesbecause each implementation of an interface produces a new class.See “Multiple Implementations of the Same Interface” on page 4-9 formore information about multiple implementations of a singleinterface.

TME 10 ADE supports four different class implementation schemes:

■ Classless Objects—Objects that are not produced from a TME 10class

■ Abstract Class Objects—Class objects that do not support thecreation of instance objects

■ Instantiable Class Objects—Class objects that support thecreation of instance objects

■ Metaclasses—Class objects from which other class objectsinherit additional class behavior

Classless ObjectsSometimes there is a requirement for a single object that is unique.In most object-oriented systems, such objects are not unique and theymust, therefore, be instantiated from a class just like any other object.

The effort required to produce a class and then instantiate an object,however, is usually significant. In some cases, the advantages

TME 10 Classes


TM

E 10 A

DE

Extended ID

L

associated with the unique object do not merit the effort required toproduce it. TME 10 ADE therefore supports classless objects.

A classless object supports an IDL interface, but it is not associatedwith a specific class. If your resource requires a unique object, you canspecify an object implementation rather than instantiating an objectfrom a previously defined class implementation.

See “Implementation Header” on page 4-23 for more informationabout implementing classless objects.

Abstract Class ObjectsAll TME 10 classes are classified as eitherinstantiable ornon-instantiable. Instantiable classes are those from which aninstance object can be created. Non-instantiable classes are those fromwhich an instance object cannot be created. Instantiable classes areequipped with a method (create_instance) that creates an instance ofthe class when requested. Non-instantiable classes are not equippedwith thecreate_instance method.

The purpose of an abstract class is to provide a base class from whichyou can derive other classes. The derived classes can be instantiable ornon-instantiable depending on how the associated interface isimplemented.

An example of an abstract class is one that implements operations forreading and writing encryption strings. It is not appropriate to createinstance objects from such classes because the instance objects serveno real purpose.

Instantiable Class ObjectsAn instantiable class is one from which you can create an instanceobject, a process known asobject instantiation. Such classes areequipped with thecreate_instance method for creating objects.See “Object Creation from a Class” on page 4-8 for more informationon creating objects.

TME 10 Classes

4–4 Version 3.6

MetaclassesTME 10 Classes are not merely general compile time constructs;rather, they are represented as persistent objects. As such, theyencapsulate behavior. One characteristic that separates TME 10 classobjects from TME 10 instance objects is the kind of behavior theyencapsulate.

TME 10 classes encapsulate two distinct types of behavior: instancebehavior and class behavior. Instance behavior comprises the methodsthat objects inherit from the class that instantiates them. Such methodsrepresent the services that objects can provide to clients.

Class behavior comprises a separate set of methods that represent theservices provided by classes that objects cannot provide. One exampleof class behavior is the previously mentionedcreate_instancemethod. This behavior is available only to TME 10 class objects andnot to TME 10 instance objects.

When you create a new class, the class object implementationsometimes requires additional class behavior beyond the defaultbehavior provided to all TME 10 classes. For example, you might wantseveral operations that offer additional support for instance creation.

In such cases, you can instruct the new class object to inherit therequired class behavior from some other class. The class that providesthe augmented class behavior is designated as ametaclass to the newclass object.

Any existing class object can be designated as a metaclass to thecurrent class object. This designation scheme means that metaclassesare no different than other class objects. They are only metaclassesfrom the perspective of the current class object.

TME 10 Classes


TM

E 10 A

DE

Extended ID

L

Metaclasses are designated as such in the current class object using themetaclass keyword as shown:1 #include <shape.idl>

2 module imp_example{

3 implementation abstract class shape honors

4 example::shape metaclass meta_shape{

Line 4 indicates that there is a previously defined class object calledmeta_shape. Line 4 also specifies that the current class object (shape)inherits additional class behavior frommeta_shape.

Themeta_shape class in this example, is not intrinsically differentfrom any other class:

■ There are no special constraints on its behavior.

■ Other classes do not necessarily perceive its designation as ametaclass.

■ The metaclass designation is not extended to themeta_shapespecification.

TME 10 Classes

4–6 Version 3.6

The metaclass designation merely defines an augmented inheritancespecification for a particular class object as shown in the followingdiagram:

The diagram also indicates two noteworthy facts about metaclassinheritance:

■ Metaclasses can inherit additional class behavior from othermetaclasses.

Object

Object

InstantiableClass

InstantiableClass

(Metaclass)Abstract

Class

Inherits from

Instantiates

Object

Object

Object

Abstract Class

(Metaclass)Abstract Class

Metaclass Inheritance

TME 10 Classes


TM

E 10 A

DE

Extended ID

L

■ Both abstract class objects and instantiable class objects caninherit additional class behavior from metaclasses.

See “Implementation Header Keywords” on page 4-24 for moreinformation about specifying metaclasses.

New Class CreationClasses in TME 10 ADE can be created only by deriving them fromother classes. Both abstract classes and instantiable classes can bederived from each other. It is preferable, however, to establish anorderly hierarchy in which abstract classes are created first andinstantiable classes are derived from abstract classes.

Such hierarchies work well because abstract classes describe thecharacteristics of other classes. Instantiable classes describe thecharacteristics of individual objects.

The process of creating a new class begins when you define theassociated interface in IDL and ends when you run the configurationscript produced by the TEIDL compiler. The following proceduredescribes the process of class creation:

1. Define your interface in IDL. See “IDL Specification” onpage 3-7 for more information about IDL interface definition.

2. Define your implementation in TEIDL. See “ImplementationSpecification Constructs” on page 4-23 for more informationabout TEIDL implementation specification.

3. Define your program in TEIDL. See “Program SpecificationConstructs” on page 4-34 for more information about TEIDLprogram specification.

4. Define your installation specification in TEIDL. See “InstallationSpecification Constructs” on page 4-40 for more informationabout TEIDL installation specification.

5. Run the TEIDL compiler. You can invoke the compiler using thetidlc command. See “TEIDL Compiler Operation” on page 4-83for more information abouttidlc .

Implementation

4–8 Version 3.6

6. Implement the methods specified in the interface definition. Editthe method implementation files produced by the compiler andthen compile them. See “TME 10 Output” on page 4-57 fordetails about these files.

7. Link the files to produce an implementation program. See“TEIDL Compiler Output” on page 4-55 for a complete list offiles produced by the compiler.

8. Run the configuration script produced by the TEIDL compiler.See “TEIDL Compiler Output” on page 4-55 for a listing ofcompiler output files.

Running the configuration file creates the new class for you andmanages the details associated with its installation in the TME.

Object Creation from a ClassYou create an object by requesting an implementation from a class.The process of creating an object from a class is known asinstantiation. You can instantiate an object from a class after you runthe configuration script mentioned in step 8 of the previous section.

After running the configuration script, call thecreate_instancemethod on the class from which you want a new an instance.All instantiable classes contain thecreate_instance method. You canidentify the class object by using theNameRegistry. Refer to theApplication Services Manual for information about theNameRegistry.

ImplementationThe specification of the way an object performs its defined operationsis calledimplementation. Objects can often perform the sameoperation in many ways, and it is therefore possible for an interface tobe supported by multiple implementations. Consider the followingexample:

A user makes a print request of a specific printer using the UNIXlpcommand. Requests to this printer are managed by a printerqueue.The printer queue is a request manager that enables one or more clientsto make multiple requests of it.

Implementation


TM

E 10 A

DE

Extended ID

L

Users initiate their requests by enteringlp file_name. UNIX thenrecords the request in the printer queue. When the printer daemon isfree, it takes the next entry out of the queue and instructs the printer toprint the job.

Users are ignorant of the way the queue works; their immediateconcern is whether the printer eventually prints the specified file. Theymight also want to remove the request from the queue or browse thequeue to find the request status. The printer queue in this example canbe described as an interface that supports the operations add, browse,and remove.

Thelp print queue could be provided as an object implementation—aninstance of aqueue class. The operations supported by the class canbe defined in an interface that, among other things, lists (declares) theoperations add, browse, and remove.

The implementation of those operations, however, is private.Programmer A might, for example, decide to implement the queue asa circular buffer, while programmer B decides to implement the queueas a linked list. Programmer A implements the add method by fillingin elementn of the buffer, wheren is the next free slot. Programmer Bcreates a new node and appends it to the end of the list.

Multiple Implementations of the Same InterfaceIn the previous printer queue interface example, the interface wassupported by multiple implementations. TME 10 ADE supportsmultiple implementations of the same interface. Each implementationprovides a unique class from which objects can be created, yet each issaid to support the same interface.

When multiple classes support the same interfaces, objects from thoseclasses provide the same services and raise the same exceptions. Theobjects differ, however, in how they perform the requested services.

Support for multiple implementations of the same interface is one ofthe cornerstones of polymorphism. This support enables you toimplement an application that can support new resources in the future.

Implementation

4–10 Version 3.6

Implementation InheritanceLike an IDL-defined interface, an implementation can be derived froma previously specified implementation known as a baseimplementation. The derived implementation then inherits from thebase implementation.

You refer to the base implementation when you declare the derivedimplementation. The inheritance operator (:) denotes this inheritanceas shown in the following code fragment:1 implementation class PhoneListProfile :

2 imp_TMF_CCMS::Profile,

3 imp_TMF_UI::UserInterfaceBase

4 honors TPL::PhoneListProfile {

The derived implementation isPhoneListProfile, which inherits fromtwo other implementations:

■ imp_TMF_CCMS::Profile

■ imp_TMF_UI::UserInterfaceBase

This derived implementation honors (or implements) thePhoneListProfile interface declared in theTPL module. An importantpoint, which might be confusing to new users of TEIDL, is the fact thatthe interface is not affected by the implementation inheritance.Interface inheritance and implementation inheritance are completelyindependent of each other. This inheritance separation can beadvantageous as illustrated by the following example:

You want to implement a stack for a new IDL interface calledStack,using a previously defined list class implementation. The stackrequires the implementation of apush operation, and the listimplementation contains aninsert operation.

You can implement thepush operation as a call to theinsert operation.The implementation of thepush operation inherits from theimplementation of theinsert operation. This approach enables you touse theinsert code again for a separate application.

Implementation inheritance also enables you to re-implement aninherited method. The TEIDL compiler manages the namingconventions for you, which prevents collisions.

Introduction to TME 10 ADE Extended IDL


TM

E 10 A

DE

Extended ID

L

Interface inheritance and implementation inheritance differ in thefollowing ways:

■ Interface inheritance enables derived interfaces to inheritpreviously declared operations and exceptions from a baseinterface.

■ Implementation inheritance enables you to implement definedinterfaces using a previously specified implementation.

Although TEIDL supports both interface and implementationinheritance, it is not necessary for the inheritance to be parallel. Forexample, you might decide that some interfaceY should inherit fromsome other interfaceX. The implementation for interfaceY is notrequired to inherit from the implementation for interfaceX.

Interface inheritance relationships are completely independent ofimplementation inheritance relationships. In fact, good object-orientedprogram designs often contain several levels of interface derivation,with fewer levels of implementation derivation.

Introduction to TME 10 ADE Extended IDLThe purpose of IDL, according to the CORBA specification, is toprovide a standard for defining interfaces that client objects call andobject implementations provide. It does not, however, provide astandard for implementation or installation.

Thus, when you define your interface in IDL, you are still left with thetask of providing not only method implementation but a program thatgenerates and installs a class hierarchy. The details of designing andimplementing such programs are beyond the scope of this document:it is sufficient to know that the process is tedious and error prone.

TME 10 ADE therefore provides the following extensions to the OMGIDL:

■ Implementation

■ Implementation inheritance

■ Installation and initialization

■ Hierarchical exception classes


4–12 Version 3.6

These extension are provided in a parallel but separate language:Tivoli Extended IDL (TEIDL). The grammar for TEIDL follows thesame lexical and syntactic conventions as those specified by CORBAfor IDL.

When you develop your application using TEIDL, you should providethe following files that—as a set—define, implement, and install yourinterface:

■ An interface definition file, which has a name containing anextension of.idl . See Chapter 3, “IDL-defined Interfaces,” formore information about IDL interface definition.

■ An implementation specification file, which has a namecontaining an extension of.imp. See “Introduction to TEIDLImplementation Specification” on page 4-12 for moreinformation about TEIDL implementation specification.

■ A program specification file, which has a name containing anextension of.prog. See “Introduction to TEIDL ProgramSpecification” on page 4-15 for more information about TEIDLprogram specification.

■ An installation specification file, which has a name containing anextension of.ist. See “Introduction to TEIDL InstallationSpecification” on page 4-16 for more information about TEIDLinstallation specification.

Note: Each of these files must contain anewline at the end of the file.

Introduction to TEIDL Implementation SpecificationA TEIDL implementation specification is a block of information thatspecifies the implementation of a class of objects. The followingexample depicts a typical implementation specification:1 #include <TPL.idl>

2 module imp_TPL {

3 //

4 // The implementation PhoneListProfile "honors"

5 // the TPL::PhoneListProfile interface. The

6 // class inherits the implementations of

7 // TMF_CCMS::Profile and TMF_UI::UserInterfaceBase

8 //



TM

E 10 A

DE

Extended ID

L

9 implementation class PhoneListProfile :




13 ...

14 };

15 methods {

16 {

17 // PhoneListIterator methods

18 ui_phone_props,

19

20 // PhoneListProfile methods

21 create_phone_entry,

22 create_entries,

23 modify_phone_entry,

24 delete_phone_entry,

25 delete_phone_entries,

26 get_phone_entry,

27 get_phone_entries,

28 list_phone_entries,

29 find_by_name,

30 get_all_entries,

31

32 // PhoneListIterator methods

33 next_entries,

34 destroy_iterator,

35

36 //

37 // These are TMF_CCMS::Profile

38 // methods for which the app will

39 // provide implementations.

40 //

41 initializ,

42 populate,

43 validate,

44 enable_validation,

45 disable_validation,

46 _get_validation_enabled,

47 get_default_policies,

48 set_default_policies,

49 get_validation_policies,

50 set_validation_policies,


4–14 Version 3.6

51 push,

52 remove,

53 copy_records,

54 move_records,

55 } binding = ansi C;

56 };

57 };

58 };

The implementation file contains the following primary components:

■ A preprocessor directive

■ A module specification,imp_TPL

■ A class implementation specification,PhoneListProfile

■ Several method specifications

Sample Implementation Preprocessor Directive

The preprocessor directive instructs the compiler to include the filethat contains the interfaces associated with this implementation. Thisis important because the TME 10 ADE TEIDL compiler accepts onlyone input file.

When you run the compiler you should specify the installation file asthe input. The installation file should include the program files for thatinstallation and the program files should include the implementationfiles for those programs. The implementation files can then include thenecessary interface definition files.

Using thisinclude scheme enables you to easily manage the file setthat specifies your interface and implementation scheme.

Sample Class and Method Specification

The implementation is rather straight forward. The modulespecification on line 2 is just like the IDL module described in “IDLModule Definition” on page 3-14; it unambiguously scopes theimplementation name without cluttering the global name space.



TM

E 10 A

DE

Extended ID

L

ThePhoneListProfile class specification describes how thePhoneListProfile interface is to be implemented. The newly specifiedclass, will for example, provide a method calledcreate_phone_entry,which implements thecreate_phone_entry operation specified in thePhoneListProfile interface.

Introduction to TEIDL Program SpecificationA TEIDL program specification provides additional detail about theimplementation. The implementation (.imp) file describes the classimplementation, which includes the following:

■ Whether the class is instantiable

■ The class attributes

■ The class methods

The implementation file does not, however, describe the operatingsystem process characteristics of class methods. You can, for example,implement the class methods so that they start, run, and then terminate.Alternatively, you can implement them so that they start and thencontinue to run without terminating.

Such implementation details are called the methodexecution style.A TEIDL program specification describes the execution style of theclass methods. The following example depicts a typical programspecification:1 #include <TPL.imp>

2 module prog_TPL{

3 program PhoneListProfile timeout = 100 for

4 imp_TPL::PhoneListProfile{

5 executes{imp_TPL::PhoneListProfile::


7 ...

8 }

9 daemon;

10 };

11 };

This example includes two primary components: a preprocessordirective and thePhoneListProfile program specification.


4–16 Version 3.6

Sample Program Preprocessor Directive

The include directive (line 1) instructs the compiler to include theimplementation file for theTPL implementation. This means there isnow a reference from the program file to the implementation file, andfrom there to the interface definition file. The only missing file is theinstallation specification, which is addressed in the section entitled“Sample Installation Preprocessor Directive” on page 4-19.

Sample Program Specification

Line 9 specifies the program as a daemon. A daemon program is onethat does not terminate on completion, and consequently a 100 secondtime-out is specified on line 3. This means that if the program isinactive for 100 seconds without receiving a request to run anothermethod, the program terminates.

A detailed discussion of daemon programs is beyond the scope of thissection. See “TEIDL Program Specification” on page 4-34 forinformation about specifying server types such as daemon programs.

Lines 5 and 6 specify that the programPhoneListProfile contains thecreate_phone_entry methods for thePhoneListProfileimplementations and that this method runs inside a daemon processwith a 100 second time-out.

Introduction to TEIDL Installation SpecificationA TEIDL installation specification is a block of information thatdescribes the authorization, privilege, and location of the binary filesfor a specified class. The following example depicts a typical programspecification:1 #include <TPL.prog>

2 module ist_TPL {

3 installation PhoneListProfile

4 for imp_TPL::PhoneListProfile

5 with prog_TPL::Phone_prog1,

6 prog_TPL::Phone_ui_prog1,

7 prog_TPL::Phone_prog2

8 {

9 ...

10 }



TM

E 10 A

DE

Extended ID

L

11 // Define the ACLs required for the

12 // application's methods.

13 acl {

14

15 // Require the SENIOR role.

16 {

17 initializ,




21 set_validation_policies

22 } = { SENIOR_ACL };

23

24 // Require at least the ADMIN role.

25 {


27 create_entries,




31 populate,

32 validate,



35 PhoneListProfile::push,

36 PhoneListProfile::remove,

37 PhoneListProfile::move_records,

38 get_all_entries,

39 ui_phone_props,

40 copy_records

41 } = { ADMIN_ACL };

42

43 // Require the USER role.

44 {

45 get_phone_entry,



48 find_by_name,

49 next_entries,


51 destroy_iterator

52 } = { USER_ACL };


4–18 Version 3.6

53 };

54 external path {

55

56 // Location of the core-method method

57 // program.

58 {


60 create_entries,




64 get_phone_entry,


66

67 initializ,

68 populate,

69 validate,








77 push,

78 remove,

79 move_records,

80 copy_records

81 } = { "default", "/TME/PHONE/phone_core"; };

82

83 // Iterator-based method program.

84 {


86 get_all_entries,

87 find_by_name,

88 next_entries,

89 destroy_iterator

90 } = { "default", "/TME/PHONE/phone_query"; };

91

92 // Location for UI program

93 {

94 ui_phone_props



TM

E 10 A

DE

Extended ID

L

95 } = { "default", "/TME/PHONE/phone_ui"; };

96 };

97 // Define the actions taken when the class

98 // is installed in the TME. We run the

99 // phone.init script in this case.

100 initialize {

101 "$METHODPATH/phone.init

102 $imp_TPL_PhoneListProfile_CO $METHODPATH";

103 };

104 };

105 };

This installation file includes two primary components:

■ The preprocessor directive

■ ThePhoneListProfile installation specification

Sample Installation Preprocessor Directive

The include directive (line 1) instructs the compiler to include theTPL.prog program file, which completes the required file referencesfor thePhoneListProfile implementation.

The following scenario depicts a typical compile scheme for theexample shape implementation:

1. The installation file is specified as the compiler input using thefollowing CLI command:

tidlc TPL.ist

2. The compiler compiles the installation file as instructed.

3. The include directive in the installation file instructs the compilerto include the program file (TPL.prog), and so the compiler alsocompiles the program file.

4. The include directive in the program file instructs the compiler toinclude the implementation file (TPL.imp ), and the compileralso compiles this file as instructed.

5. The include directive in the implementation file instructs thecompiler to include the interface definition file (TPL.idl ), and sothe compiler also compiles this file.


4–20 Version 3.6

If there are any include directives in the interface definition file,the compiler includes and optionally compiles those files.Whether the files are compiled is dependent on your use of the#pragma generate.

6. The compiler generates (among other things) client files whichpresent the framework for the Phone List application. See“TEIDL Compiler Output” on page 4-55 for more informationabout the files produced by the TEIDL compiler.

Although you are not constrained to do so by the compiler, using thedescribed include scheme is recommended for the purpose ofsimplicity. See “TEIDL Compiler Operation” on page 4-83 for moreinformation about running the compiler.

Sample Installation Specification

The shape installation beginning on line 3 contains threesubcomponents:

■ An access control specification (lines 13 through 53)

■ A path specification (lines 54 through 96)

Sample Access Control Specification

Lines 13 through 53 of the example installation file specify the accesscontrol for the methods provided by thePhoneListProfileimplementation. The TEIDL keywordacl is an abbreviation forAccess Control List. An ACL is a list of roles that enable the systemto verify that the invoker of the method is authorized to do so. A roleis merely a string name for an authorization level; it represents therequired authorization for invoking the method.

The access control specification assigns the specified string as anauthorization role for the specified method. Each user is assigned oneor more roles, and the roles assigned to the user must match one ofroles in the ACL. If it does not, the user is denied access to the method.The ACL thus specifies the authorization level required to access themethod.



TM

E 10 A

DE

Extended ID

L

ThePhoneListProfile installation specifies, for example, a role ofSENIOR to the following methods:

■ initializ

■ get_default_policies

■ set_default_policies

■ get_validation_policies

■ set_validation_policies

This means that the invoker of any of these methods must be assignedtheSENIOR role.

See “Authentication and Authorization” on page 4-45 for moreinformation about specifying roles.

Sample Path Specification

Each method must have a location, which is specified by apath.TEIDL supports location specification with thepath or external pathkeywords.

The example code fragment specifies anexternal path, whichindicates that the path specifies the location of a method in a disk file.An external path is different than aninternal path , which specifiesthe storage location of a method in an object attribute. The examplecode fragment specifies two such locations for method storage:

■ “default”, “/TME/PHONE/phone_core”

■ “default”, “/TME/PHONE/phone_ui”

Each location specification contains a platform (default) and a path.The platform represents a machine type, and the path represents thefile location on disk. There is usually one path specification for eachplatform type. The default specification in thePhoneListProfileinstallation, which means that the installation is supposed to occur onthe default platform.

See “Installation Body” on page 4-41 for more information about pathspecification.


4–22 Version 3.6

Object ImplementationObject implementation is a process comprising multiple stages. Youbegin the process by defining an interface in IDL and specifying itsimplementation and installation in TEIDL. When you have specifiedthe interface, its implementation, and its installation, run the TEIDLcompiler. It produces several output files that are specific to yourprogram. See “TEIDL Compiler Output” on page 4-55 for a completelist of these files.

The output files of primary concern are the operation files, the methodtemplates, and the installation script.

Each method template file initially contains any required preprocessorcommands and all the method signatures for a particularimplementation.

You should edit the file and fill in the source code to implement eachmethod header. See “Method Templates” on page 4-62 for detailsabout method implementation.

Each operation file contains all the operations and their signatures fora particular IDL-defined interface. This file is important becauseclients use it to initiate requests of the object implementation. See“TME 10 Service Requests” on page 6-1 for more information aboutwriting client requests.

When you run the installation script, it completes the objectimplementation. It contains all the commands necessary to create theclass hierarchy and install the methods in the appropriate location.SeeApplication Development with TME 10 ADEfor details of theconfiguration file composition.

Running the installation script completes the implementation. You canthen create an object from an implemented class using thecreate_instance method. The newly created object is the provider ofa defined set of services that a client can request. Subsequent sectionsdescribe TME 10 objects and how to use them to provide services forclients.

Implementation Specification Constructs


TM

E 10 A

DE

Extended ID

L

Implementation Specification ConstructsAn IDL interface definition specifies the following:

■ Operations available to an object implementation

■ Operation signature

■ Exceptions the object implementation supports

Clients do not have access to the specified operations, however, untilthey are implemented. This is because the class must define the waythe operations are executed. It is not possible, for example, for anobject to provide a service without specifying how it is implementedor executed.

The TEIDL implementation and installation language provides astandard for specifying class implementation. A TEIDLimplementation specification consists of a header and a body.The header consists of an implementation name and the name of theinterface the implementation supports. The body consists of a series ofstatements, syntactically similar to IDL, that specify the namedimplementation.

The implementation constructs support comments and keywords.You identify comments in TEIDL in the same way you identify themin IDL and C. Refer to the CORBA specification for information aboutIDL comments.

TEIDL Implementation SpecificationA TEIDL implementation specification is a block of informationwritten in TEIDL that completely defines the implementation of one ormore interfaces. The specification comprises two major components:the implementation header and the implementation body.

Implementation Header

The implementation header specifies the following:

■ The implementation of a class or an object

■ The class type (in the case of a class specification)

■ Optional implementation inheritance


4–24 Version 3.6

Implementation Header Keywords

The following table lists the TEIDL implementation header keywordsand presents a brief summary of each. Review it in concert with theBNF description presented in the section entitled “TEIDL Grammar”located at the end of this chapter:

The following code fragment depicts a typical TEIDL implementationheader:1 module imp_TPL {

2 implementation class PhoneListProfile :




Line 1 specifies that the scope of the implementation is restricted to animplementation module calledimp_TPL . Line 2 specifies theimplementation ofPhoneListProfile as a class. Lines 3, 4, and 5specify the fully scoped inheritance for thePhoneListProfile class.

Keyword Description

implementation Precedes the implementation identifier in the implementation header(each interface implementation has a unique identifier)

abstract Precedes theclass keyword and denotes a non-instantiable class(optional)

class Specifies the implementation of an instantiable class rather than anobject

object Specifies the implementation of a classless object rather than a class

metaclass Specifies the metaclass to associate with the current class

honors Precedes the interface identifier in the implementation header andassociates the named implementation with the named interface



TM

E 10 A

DE

Extended ID

L

Implementation Inheritance

An implementation optionally inherits from one or more previouslydefined implementations. The following code fragment depicts suchinheritance. Interfacesa, b, andc are defined elsewhere:1 const long L = 3;

2 implementation class A honors a {

3 attribute long l[L];

4 };

5

6 implementation class B:A honors b {

7 const long L = 4;

8 };

9

10 implementation class C: B, A honors c {

11 // how many elements in l ?

12 };

The early binding of constants and types at definition guarantees thatthe inherited array attribute in C has three elements. This is becausereferences to constants and types are bound to an implementation or aninterface when it is defined. This guarantees that the semantics of animplementation do not change when it is used as a baseimplementation by some derived implementation.

See “Implementation Inheritance” on page 4-10 for more informationabout implementation inheritance.

Implementation Body

The body of the implementation specifies details such as the attributesand methods for a class, as well as the language binding for the classmethods. Specifically, the implementation body enables you to specifythe following:

■ Data types

■ Constants

■ Attributes

■ Methods


4–26 Version 3.6

Implementation Body Keywords

The following table lists the TEIDL implementation body keywordsand presents a brief summary of each. Review it in concert with theBNF description presented in the section entitled “TEIDL Grammar”located at the end of this chapter.

Keyword Description

attribute Specifies the implementation of an attribute.

methods Specifies the implementation of one or moreimplementation-defined methods—a method that you implement.

binding Precedes the binding specification and specifies whether a methodis implemented as a C program, a shell script, or a command.

ansi C Specifies the implementation of a method as a C function andcontains two tokens, which can be separated by any number ofwhite spaces.

shell Specifies the implementation of a method as a shell script.

command Specifies that the method is to be supplied with a special executionenvironment that allows the method to read fromstdin and writeto stdout andstderr.

intrinsics Specifies the implementation of an intrinsic method—a methodimplemented by the object adapter used to either set or retrieve anattribute value.

access Specifies an intrinsic method that retrieves an attribute value. Itprovides aget_attribute function. See “Attribute Specification”on page 4-28 for more information.

mutate Specifies an intrinsic method that sets an attribute value. It providesaset_attribute function. See “Attribute Specification” onpage 4-28 for more information.



TM

E 10 A

DE

Extended ID

L

Data Types and Constant Specification

Like IDL, a TEIDL implementation supports data type and constantspecifications. Furthermore, the implementation defines a namingscope.

The scope resolution described for IDL in “IDL Scope Resolution” onpage 3-29 also applies to TEIDL implementations. The scope isexpanded to include the interface supported by the implementation(the interface name that follows the keywordhonors).

Consider the following example:

Example IDL interface (foo.idl)1 interface foo {

2 struct s { long l; };

3 attribute s a;

4 void op();

5 };

6 interface bar : foo { };

Example TEIDL implementation (foo.imp)1 #include <foo.idl>

2 implementation class imp_bar honors bar {

3 methods { { op }; };

4 attribute s a; // using ‘s’ from honored interface

5 intrinsics {

6 _get_a access a;

7 _set_a mutate a;

8 };

9 };

Attribute a is defined on line 4 to be of types, which is undeclared inthe implementation. The compiler resolves this reference by searchingthe IDL file specified in line 1 by the#include directive. The attributes is defined in line 2 offoo.idl as a C structure. Thus, the scope extendsto include the honored interface.


4–28 Version 3.6

Attribute Specification

When you define an attribute in an IDL-defined interface, the compilerproduces the required operations for retrieving and setting the attributevalues. It does not, however, produce the implementation (sourcecode) for those operations. Consider the following IDL interfacedefinition:1 module example{

2 interface foo {

3 enum material_t {rubber, glass};


5 float x, y;

6 };

7




11 };

12 };

This example depicts several interface attributes. The compiler usesthe interfaceattribute construct to produce client entry points, whichtake the form ofoperation stubs. An operation stub is a file thatcontains the code for making a call to an IDL operation. The operationstubs are produced by the IDL compiler, and clients can call thesestubs to perform an operation on the attribute.

The implementation that supports the interface must containcorresponding methods to manipulate the attributes specified in theinterface. The implementation that supports the example interfaceshould thus specify methods for retrieving the value of all threeattributes:

■ radius

■ material

■ position

The radius andmaterial attributes should also have methods forsetting their values. Theposition attribute, however, does not requirea method for setting its value because theposition attribute is specifiedasreadonly in the example interface. The following example depictsone possible TEIDL implementation:



TM

E 10 A

DE

Extended ID

L

1 #include <foo.idl>

2 module imp_example{

3 implementation class foo honors example::foo{

4


6 attribute position_t position;


8

9 methods{

10 _get_material,

11 _set_material,

12 _get_position}

13 binding = ansi C;

14 }

15

16 intrinsics{

17 _get_radius access radius;

18 _set_radius mutate radius;

19 };

20 };

21 };

The methods block (lines 8 through 14), specify the required methodsfor thematerial andposition attributes. The TEIDL compilerproduces method templates for each specified method. You can thenimplement methods for retrieving the value of thematerial andposition attributes (_get_material and_get_position) and setting thevalue of thematerial attribute (_set_material).

This implementation style is necessary if the method must dosomething unusual, such as explicitly notifying some other object thatthe attribute value has changed. In many cases, however, the onlyrequired task is to set the attribute value or to retrieve it. In such casesyou can have the TEIDL compiler implement these methods for you asaccessor andmutator functions.

Accessor functions retrieve an attribute value on an object, andmutator functions set an attribute to a specified value on an object.To have the compiler produce these functions you can specify them asintrinsic methods as shown in the example code fragment (lines 16through 19). See “Intrinsic Methods” on page 4-32 for moreinformation about intrinsic methods.


4–30 Version 3.6

Method Specification

The method specification consists of two components: a methoddeclaration and a language binding. An example method specificationis shown in the following code fragment:1 methods{

2 {_get_material}

3 binding = ansi C;};

The string_get_material declares the method you want to specify.The stringansi C specifies the language binding as ANSI C.

Bourne shell and command bindings are also available.See “Implementation-Defined Methods” on page 4-30 for moreinformation about shell and command methods.

TEIDL supports two types of methods: implementation-definedmethods and intrinsic methods. Implementation-defined methods arethose that you implement in a C program or a shell script. Intrinsicmethods are implemented for you by the TEIDL compiler.

Implementation-Defined Methods

Implementation-defined methods are so called because you define themethod behavior in the source code that implements that method.The source code language determines the available behavior for themethod implementation. That is, some kinds of behavior areimplemented more easily in some languages than in others.

As the developer you must decide which is the appropriate languagefor the desired behavior. If you plan to implement the method using C,specify theansi C keyword. If you plan to implement the method as ashell script, specify theshell keyword.

In addition to the source code language, you must specify input andoutput management. A method can contain ahelper process, or it canbehelperless depending on how you want to manage the method I/O.The helper process performs the following:

■ Unmarshals the method input from the ORB

■ Supplies thestdin, stdout, andstderr environment

■ Marshals any exceptions or output from the method



TM

E 10 A

DE

Extended ID

L

Most C methods are helperless. Some methods such as daemonmethods and methods that are shared or contain concurrent multiplethreadsmust be helperless. If a method is not of this type, it can beuseful to provide a helper process for it.

The requirement for a helper process is most common in shell scripts.If you implement a method as a shell script, the Basic Object Adapter(BOA) can provide the required helper process. You specify theprovision of a helper process with thecommand keyword. Thisprovision has the following costs:

■ For every invocation of a command method, there is one helperprocess to manage its I/O. The obvious expense is theconsumption of additional resources. That is, each methodinvocation now requires at least two processes.

■ A command operation must have a fixed IDL signature as shownin the following code fragment:

1 exception command_excep {

2 long signum; //terminated on signal.

3 boolean core; // was there a core file ?

4 };

5 short acommand ( in sequence<string> argv,

6 in sequence<string> env,

7 in sequence<octet> stdin,

8 out sequence<octet> stdout,

9 out sequence<octet> stderr)

10 raises ( SysAdminException::ExCommand );

The primary advantage of specifying a command style execution is theability of the method to perform the following:

■ Read from standard in

■ Write to standard out and standard error file descriptors

This ability enables legacy programs to be used for methodimplementations. As a result any program on the system (includingutilities like /bin/who) can be used as a method implementation.

Non-command implementations must interact with the client by wayof input and output parameters and return results. Command methodsare not restricted to this behavior. They can also interact with clientsusing thestdin, stdout, andstderr file descriptors.


4–32 Version 3.6

See Chapter 5, “Object Implementation,” for more information aboutimplementing methods.

Intrinsic Methods

Intrinsic methods are so called because they are intrinsic to the ORB.If you specify a method as implementation-defined, you must providethe implementation. If you specify a method as intrinsic, the compilerimplements the method for you.

Intrinsic methods are faster than implementation-defined methods.Intrinsic methods support only attributes and, consequently, performonly two operations: one that retrieves an attribute value and one thatsets an attribute value. The following TEIDL example depicts a typicalTEIDL intrinsic method specification:1 implementation class foo honors example::foo{

2


4

5 intrinsics{

6 _get_radius access radius;

7 _set_radius mutate radius;

8 };

9 };

Theaccess keyword specifies_get_radius as a method that retrievesthe value of theradius attribute. Themutate keyword specifies the_set_radius method that sets the value of theradius attribute.

Accessor and Mutator Functions

Accessor and mutator functions are produced for you by the TEIDLcompiler for the purpose of retrieving and setting implementationattribute values. If you implement a method to manipulate attributevalues, call the appropriate function from your method to retrieve orset the attribute value.

Accessor functions have the following signature:

some_type _implname__get_attribute();



TM

E 10 A

DE

Extended ID

L

The following list describes each component:

■ some_type—Specifies the data type

■ _implname—The fully scoped implementation name

■ attribute—Specifies the attribute accessed by the function suchasradius

Mutator functions have the following signature:

void _implname__set_attribute( in some_type t);

The following list describes each component:

■ _implname—The fully scoped implementation name

■ attribute variable—Specifies the attribute modified by thefunction such asradius

■ some_type—The data type

As previously stated, the compiler produces the described accessorand mutator functions, which are specified by CORBA. A TME 10version of each compiler generated accessor and mutator function isavailable. The TME 10 functions are extensions of the CORBAfunctions.

The TEIDL compiler produces two sets of client stubs: a CORBAversion and a TME 10 version. CORBA accessor and mutatorfunctions are available in CORBA stubs, and TME 10 accessor andmutator functions are available in TME 10 stubs. See “TEIDLCompiler Output” on page 4-55 for more information about CORBAstubs and TME 10 stubs.

TME 10 accessor functions have the following signature:

some_type _t_implname__get_attribute();

TME 10 mutator functions have the following signature:

void _t_implname__set_attribute(in some_type t);

Program Specification Constructs

4–34 Version 3.6

Program Specification ConstructsIf you implement your method as a C program, you must specify theexecution style of a method. You might, for example, implement theprogram as a long running daemon rather than as a method thatterminates on completion. You may also want to specify multiplethreads of execution within the method process.

The TEIDL provides program constructs that allow you to specify theexecution styles.

TEIDL Program SpecificationA TEIDL program specification, like an implementation specification,has both a header and a body. The header consists of a program nameand a time-out specification, and its purpose is to identify the programspecification. The program body consists of a series of TEIDLkeywords that specify the program execution style and server type.

Program Header

The following table presents the TEIDL program header keywords anda brief summary of each. Review it in concert with the BNFdescription located in the section entitled “Program Grammar” onpage 4-86.

If you want the server process to wait for a specified period of time fora request and then terminate, specify atimeout value. If the serverprocess does not require a timer, then do not include thetimeoutkeyword as part of the program specification. Thetimeout keywordapplies only to daemon implementations.

Keyword Description

program Precedes the program name in a program header and is the first oftwo keywords in a program header

timeout Specifies the number of seconds the server waits for a request beforeit terminates



TM

E 10 A

DE

Extended ID

L

The following code fragment depicts a typical program header:1 #include <shape.imp>

2 module prog_example{

3 program shape timeout = 100 for

4 imp_example::shape, imp_example::circle{

Program Body

The following table presents the TEIDL program body keywords anda brief summary of each. Review it in concert with the BNFdescription located in the section entitled “Program Grammar” onpage 4-86.

The program body specifies the activation process for a specifiedimplementation. The activation process comprises the followingcomponents:

■ Method names

■ Server execution style

• threaded

• shared

Keyword Description

executes Specifies the method group to be implemented as a program

threaded Specifies that the implemented program will be multi-threaded

shared Specifies that the server process is to accommodate differentobjects

per method Specifies that the server process is to execute one method and thenterminate

daemon Specifies a server that is a daemon process

external daemon Specifies a server that is a daemon process not activated by theORB

startup Specifies one or more functions to execute when the method is firstinvoked


4–36 Version 3.6

■ Server type

• per method

• daemon

• external daemon

■ Start-up specification

Method Names

The method name specification presents the methods that compose theprogram. A TEIDL program can comprise any number of methodimplementations, possibly with different activation characteristics;and in that sense, a program is merely a repository for method binaries.This construct simply names the methods that are associated with thisprogram.

Server Execution Style

The server execution style specifies the way the server process willrun. If the server process will accommodate multiple executionthreads, specifythreaded. If the server process will not accommodatemultiple execution threads, do not include thethreaded keyword.Servers that supports multiple threads are also known asparallelservers. (See “Parallel Servers” on page 5-21 for more informationabout multi-threaded implementations.)

If the server process will accommodate multiple objects (multipleinstances of the same class for example), specifyshared. If the serverprocess will accommodate only one object implementation, do notinclude theshared keyword in the program specification. Typically, ashared implementation maintains no state between methodinvocations, and so it is safe for use by multiple objects.

The threaded andshared keywords are valid only for daemonprograms, which are described in the following section.



TM

E 10 A

DE

Extended ID

L

Server Type

The server type specifies the server process type. If the server processwill invoke a single method and then terminate, specify thepermethod keyword. If the server process will execute one or moremethods and wait for additional requests, then specify either adaemonor external daemon.

External daemons are those started by some external source. Thus youshould specify a daemon process if the TME 10 ORB starts the serverprocess. If, however, the server process is not started by the TME 10ORB, specifyexternal daemon.

Regardless of whether a daemon program is external, it represents anefficient technique for accommodating frequently called methods.Daemon programs are efficient because the time required to start a newprocess is significant. A daemon program does not waste time startinga new process every time a method in the daemon program is called.

Like any program, however, a daemon program consumes memoryand a process slot, both of which are not unlimited. You shouldtherefore use thetimeout keyword to specify a limit on the length oftime a daemon program can run. Otherwise your application mightconsume all available process slots and memory, which produces acatastrophic failure.

When specifying programs for your application, consider thefollowing costs:

■ The time required to start a process

■ The memory and processes consumed for each program

If the methods in your program are frequently called, the programshould be specified as a daemon. If they are infrequently called, youshould specify a server per method. More information is availableabout each of these server types in the following sections:

■ “Servers Per Method” on page 5-15

■ “Daemon Servers” on page 5-16


4–38 Version 3.6

Start-up Specification

Before a method is invoked, it is sometimes necessary to first executeone or more functions to initialize resources the method uses when itis first invoked. TEIDL, therefore, supports a start-up specification.

When the server is first activated, the BOA executes the functionsspecified bystartup. The functions are called in the order specified inthe start-up specification.

Program Body Example

The following code fragment depicts the body of a typical programspecification:1 #include <TPL.imp>

2 module prog_TPL{

3 program PhoneListProfile timeout = 100 for

4 imp_TPL::PhoneListProfile{

5 executes{imp_TPL::PhoneListProfile::


7 ...

8 }

9 daemon;

10 };

11 };



TM

E 10 A

DE

Extended ID

L

The following diagram summarizes the relationship of implementationspecification to program specification:

See “TME 10 Implementation Models” on page 5-13 for moreinformation about implementation models.

Scope Resolution for Program SpecificationsThe scope resolution is slightly more complex for programspecifications compared to IDL and implementation specifications.The following rules apply to program specifications:

■ The compiler first searches the enclosing scope of the programspecification.

server

daemonper method

intrinsic

external daemon

command

Implementation Models

Server Types

shared threaded

Execution Styles

shared

Installation Specification Constructs

4–40 Version 3.6

■ The compiler searches the scope of correspondingimplementations. If the program runs methods from more thanone implementation, they are searched in the order of theirappearance after thefor keyword.

Installation Specification ConstructsWhen a client initiates a request, the ORB locates the appropriateobject implementation and performs a security check. For this reason,you must address two issues regarding object installation: location andsecurity. The TEIDL installation constructs provide a convenient wayto address these two issues.

One set of installation constructs specifies the installation path to oneor more programs. Another set specifies the required authorization foreach operation.

TEIDL Installation SpecificationA TEIDL installation specification, like an implementation andprogram specification, has both a header and a body. The headerconsists of an installation name, an implementation name, and anoptional list of program names. The body consists of a series of TEIDLkeywords that specify the location and required authorization of theimplementation.

Installation Header

The following table lists the TEIDL installation header keywords andpresents a brief summary of each. Review it in concert with the BNFdescription presented in “TEIDL BNF Grammar Description” onpage 4-84.

Keyword Description

installation Precedes the installation name in the installation header

for Precedes the implementation name in the installationheader

with Precedes the program name in the installation header



TM

E 10 A

DE

Extended ID

L

An installation has a name specified by theinstallation keyword, asshown in the following TEIDL code fragment:1 module ist_TPL {





6 prog_TPL::Phone_prog2 {

1 module ist_example{

2 installation ist_circle for shape with shape{

The string following thefor keyword must denote a previously definedimplementation: it couples the specified program with the specifiedimplementation.

The string following thewith keyword must denote a previouslydefined program: it couples the specified program with the currentinstallation.

Installation Body

The following table presents the TEIDL installation body keywordsand a brief summary of each. Review it in concert with the BNFdescription located in the section entitled “Installation Grammar” onpage 4-87.

Keyword Description

acldefault Specifies the default Access Control List(ACLa) for any method that is notexplicitly listed in theacl specification

privdefault The default UNIXsetuid specification;enables method access to operating systemservices such as reading and writing to files

privilege UNIX setuid specification other than thedefault specification (privdefault )

acl Specifies an Access Control List (ACL) foran explicit method list


4–42 Version 3.6

Each implementation has an installation that specifies the following:

■ Security

■ Location

■ Object initialization

The installation characteristics are then specified as shown in thefollowing TEIDL code fragment:1 #include TPL.prog

2 module ist_TPL {





a. See “Sample Access Control Specification” on page 4-20 for moreinformation about ACLs.

roles Assigns an authorization level to thespecified method, which enables it toinvoke subsequent methods

path Specifies the program implementation path

external path Specifies the path location as a disk filerelative to the TME 10bin directory; canbe used with thedefault keyword

common external path Used only with theexternal keyword;assigns the same external path relative tothe TME 10bin directory for eachplatform

internal path Specifies the path as an object attribute

common Specifies the path for a single methodcommon to all platforms

initialize Specifies a user-defined program name andits arguments to initialize a newly createdobject

Keyword Description



TM

E 10 A

DE

Extended ID

L


8 ...

9 }



12 acl {

13


15 {

16 initializ,






22

23 // Require the ADMIN role.

24 {


26 create_entries,




30 populate,

31 validate,






37 get_all_entries,

38 ui_phone_props,

39 copy_records

40 } = { ADMIN_ACL };

41


43 {

44 get_phone_entry,



47 find_by_name,

48 next_entries,


4–44 Version 3.6


50 destroy_iterator

51 } = { USER_ACL };

52 };

53 external path {

54


56 // program.

57 {


59 create_entries,




63 get_phone_entry,


65

66 initializ,

67 populate,

68 validate,








76 push,

77 remove,

78 move_records,

79 copy_records


81


83 {


85 get_all_entries,

86 find_by_name,

87 next_entries,

88 destroy_iterator


90



TM

E 10 A

DE

Extended ID

L


92 {

93 ui_phone_props


95 };




99 initialize {



102 };

103 };

104 };

Security

TEIDL enables you to address security issues using five keywords:

■ acldefault

■ acl

■ roles

■ privdefault

■ privilege

Authentication and Authorization

A primary objective of the installation specification is security. TEIDLaddresses two aspects of security:authentication andauthorization.

Authentication verifies that a user or service is really what it says it is.Authorization ensures that the user is allowed to perform a givenoperation. TME 10 automatically manages authentication ofapplication users. Your application, however, must authorize a user’sright to invoke your application’s operations.

An application enforces authorization rules through access controllists (ACLs). An access control list defines the roles that a user musthave to invoke an operation. Roles are arbitrary names assigned todifferent levels of access and they are assigned using theroleskeyword.


4–46 Version 3.6

The roles keyword is used to define the server role. TME 10 definesthe following authorization roles:super, senior, admin, anduser.These roles are simply pre-defined names that you can use. It is up toyour application to interpret the meaning of each role. You canimplement these roles as a hierarchy (for example,senior impliessenior, admin, oruser), but it is not required. You can also define yourown custom roles to augment or replace the standard TME 10 roles.See theApplication Services Manual, Vol. II, for information aboutdefining custom roles.

Review the following code fragment:1 acl {

2


4 {

5 initializ,






In this example, the invoker of any of these methods must have anauthorization role ofSENIOR_ACL . The system administrator isresponsible for assigning that role to any users who might request anyof these operations.

The role ofSENIOR_ACL is an arbitrary string because the stringSENIOR_ACL has no special meaning. The system merely comparesthe string assigned to a method with the role assigned to the invoker ofthe method.

You can also assign multiple roles to a method, and the example codefragment can thus be changed as follows:1 acl {

2

3 // Require the SENIOR or ADMIN role.

4 {

5 initializ,






TM

E 10 A

DE

Extended ID

L


10 } = { SENIOR_ACL ADMIN_ACL};

In this case the invoker of the method can have an authorization roleof eitherSENIOR_ACL or ADMIN_ACL .

Sometimes a method must have authorization to perform requests thatyou do not want to give to the original requestor. A method might, forexample, be required to make a change to the/etc/passwd file, whichcan only be performed byroot. Theprivilege keyword is used toprovide this kind of special authorization for a server.

In the case of changing the/etc/passwd file, you must assign arole,such assuper, that providesroot authorization using theprivilegekeyword as shown in the following code fragment:1 roles{

2 {change_password} = {“super”};

3 };

4 privilege{

5 {super} = {“root”;};

6 };

After assign theroot authorization to thesuper role, you can assignthat role to the appropriate user. In this example, all those assigned therole of super have an assignedprivilege of root and can thus write tothe /etc/passwd file.

All the methods for a daemon server should have the sameprivilegevalue, otherwise, the BOA will start a separate server for each method.

Methods executed by an external daemon can be assigned a differentprivilege value, and there should be one external daemon running foreachprivilege value. The BOA will try to dispatch such methodinvocations to an external daemon that is executing with the correctprivilege. If none are available, a run-time error occurs.

acldefault and acl

It is unnecessary to explicitly specify an ACL for each method. If anACL is not found for a specific method within an installation, the ORBapplies the ACL specified by theacldefault keyword.


4–48 Version 3.6

Review the following code fragment:1 #include TPL.prog

2 module ist_TPL {

3 installation PhoneListProfile for

4 imp_TPL::PhoneListProfile




8 ...

9 }



12

13 acldefault {USER_ACL};

14

15 acl {

16


18 {

19 initializ,






25

26 // Require the ADMIN role.

27 {


29 create_entries,




33 populate,

34 validate,






40 get_all_entries,



TM

E 10 A

DE

Extended ID

L

41 ui_phone_props,

42 copy_records

43 } = { ADMIN_ACL };

44


46 {

47 get_phone_entry,



50 find_by_name,

51 next_entries,


53 destroy_iterator

54 } = { USER_ACL };

55 };

56 privdefault {“sys”;};

57

58 privilege{

59 {set_default_policies} = {“root”;};

60 };

61 external path {

62


64 // program.

65 {


67 create_entries,




71 get_phone_entry,


73

74 initializ,

75 populate,

76 validate,








4–50 Version 3.6


84 push,

85 remove,

86 move_records,

87 copy_records


89


91 {


93 get_all_entries,

94 find_by_name,

95 next_entries,

96 destroy_iterator


98


100 {

101 ui_phone_props


103 };




107 initialize {



110 };

111 };

112 };

113

Theacldefault specification (line 13) specifies a role ofUSER_ACL.This means that any method in the installation—not presented in theacl specification (lines 15 through 55)—requires the invoker to have arole ofUSER_ACL. If the invoker does not have theUSER_ACLrole, it cannot successfully invoke the method.



TM

E 10 A

DE

Extended ID

L

roles

When a method is invoked, the system verifies the role assigned to theinvoker and compares it to the ACL for that method. If the invoker hasthe proper role, then the method is invoked. Sometimes the invokedmethod invokes other methods that require a different privilege.

In such cases it is necessary to temporarily extend the role of theinvoker in the context of the executing method, so the subsequentmethod can be invoked. A typical example of such a requirement isthat of a UNIX user that wants to change his password.

The password file can only be changed by a user withrootauthorization. Yet most users are intentionally prohibited fromacquiring theroot privilege. Without some facility for temporarilyextending the user’s authority, users cannot alter their own passwords.

The roles keyword enables you to temporarily extend theauthorization of the method invoker by assigning a different role to thespecified method. In the presented example, theget_default_policiesmethod is assigned theSENIOR_ACL role (lines 20 and 24) and cantherefore invoke any method (such as view) that requires theSENIOR_ACL role. Thus, the role of any participant successfullyinvoking theget_default_policies method is temporarily extended toinclude theSENIOR_ACL role.

privdefault and privilege

It is unnecessary to specify the system privilege for each method. If amethod in the installation is not explicitly assigned a system privilege,the system assigns the privilege specified by theprivdefault keyword.

In the presented example, theprivdefault specification (line 56)specifies a privilege ofsys. Therefore any method in theinstallation—not presented in theprivilege specification (lines 58through 60)—is assignedsys privilege. Theprivilege specificationoverrides theprivdefault specification for theset_default_policiesmethod, which is assignedroot privilege.


4–52 Version 3.6

Location

TEIDL enables you to address the location of the implementation withthepath keyword. Thepath keyword specifies different platforms andpath/attribute name pairs for each supported platform. A program canbe stored in one of two ways:

■ Contained by the object—Specified by theinternal keyword,which identifies the method as an attribute of the object

■ In a disk file—Specified by theexternal keyword, whichidentifies the location of the executable file as a path

Internal Paths

Executable program files are commonly stored as disk files. In suchcases the class object contains a reference to the files, which is usuallya path.

The purpose of separating the storage of program files from the objectis efficiency. Compiled programs tend to be quite large. The storage forthe files can be managed more efficiently as a separate file, rather thanin the object database.

In the case of small shell script methods, however, it can beadvantageous to store the method as part of the object. TME 10therefore supports objects that contain the method, similar to the waythey contain attributes. To install such methods, specify theinternalkeyword as shown:1 internal path{

2 {update} = {“sunos4”, “Update”;}

3 };

In this code fragmentupdate is a shell script that updates a file whenthe object senses some specified condition. The stringUpdatespecifies a name for unique storage on the object.

Increased security is the primary advantage of storing methods on anobject. In the example, theupdate method is hidden and it is notpossible to access the file using conventional techniques. To changethe script, you must use some other interface that you provide orredefine the object to include a different program.



TM

E 10 A

DE

Extended ID

L

External Default and Common Paths

Implementations that are installed on different platforms as disk filesare frequently installed in the same path relative to theTME bindirectory. The following example depicts such a case:1 external path{

2 {update} = {“sunos4”, “/shape”;

3 “aix3-r2”, “/shape”;}

4 };

The update method will be installed in<TME bin>/shape on eachplatform (Sun OS 4.1 and AIX). Thedefault keyword eliminates therequirement for explicitly specifying the platform, as shown in thefollowing fragment:1 external path{

2 {update} = {“default”, “/shape”;}

3 };

This enforces a path specification for each method and each platform,but it requires only that you specify the method, and the path—not theplatform.

Thecommon keyword specifies that the method is common to allplatforms. Like theexternal default specification, thecommonkeyword eliminates the requirement of explicitly specifying theplatform as shown in the following code fragment:1 common external path{

2 {update} = {“/shape”;}

3 };

Thecommon external path differs, however, from theexternal pathusing thedefault specification:

■ Theexternal path with thedefault specification should be usedwhen there is a different executable file for each platform.

■ Thecommon external path specification should be used whenthere is only one executable file that is common to all platforms;for example, a shell script.


4–54 Version 3.6

Interpreter Types

Each platform supported by TME 10 can be identified in yourinstallation specification usinginterpreter types. An interpreter type isa TEIDL identifier that specifies the platform type. The following tablelists each supported platform and its interpreter type:

Object Initialization

TEIDL enables you to address object initialization using theinitializekeyword. Theinitialize keyword specifies a user-defined programname and its arguments. The compiler-generated install script callsthis program to initialize an object after the object is created. Thefollowing code fragment depicts a typicalinitialize specification:1 // Define the actions taken when the class



4 initialize {



7 };

Platform/OS Interpreter Type

Motorola 88K/SVR4 R40V4.2 sysv4-m88k

Sun SPARC/SunOS 4.1.2 or later sunos4

Sun SPARC/Solaris 2.3 and Solaris 2.4 solaris2

AT&T 3000/AT&T UNIX SVR4 MP-RAS Release 2.02 sysv4-att

HP9000/700 or 800/ HPUX 9.x hpux9

HP9000/700 or 800/ HPUX 10 hpux10

Data General Aviion/DG/UX 5.4R3.00 dgux5

IBM RS/6000/AIX 3.2.5 aix3-r2

IBM RS/6000/AIX 4.1 aix4-r1

Unixware 2.0 uw2-ix86

TEIDL Implementation Preprocessor Directives


TM

E 10 A

DE

Extended ID

L

8 };

9 };

The first argument passed to the program is the object reference of thenewly created object. This reference is produced by the configurationscript in the form of a bourne shell variable. The variable takes theform: $module_impl_CO. module presents the module if one exists.impl presents implementation (class) name. CO indicates the variableis a class object reference.

Additional arguments are passed to the program exactly as specified.If there are multiple initializing programs, they will be called in theorder specified by theinitialize keyword.

Scope Resolution for Installation SpecificationThe scope resolution is slightly more complex for installationspecifications compared to IDL and implementation specifications.The following rules apply to program specifications:

■ The compiler searches successively in the enclosing scope of theinstallation program.

■ The compiler then searches the scope of the correspondingimplementation.

TEIDL Implementation Preprocessor DirectivesThe TEIDL compiler supports C preprocessor directives for TEIDL.These preprocessing directives are identical to OMG IDL preprocessordirectives.

TEIDL Compiler OutputWhen you have defined an interface using TEIDL, you must invokethe TEIDL compiler to produce the necessary source code for yourinterface. The TEIDL compiler produces the following output:

TEIDL Compiler Output

4–56 Version 3.6

<pfx1>.h

<pfx1>_stub.c

<pfx2>_skel.c

<pfx1>__ist.tar

<pfx1>_aux.c

t_<pfx2>_skel.c

<pfx1>_defs.h

<pfx1>_aux.h

<pfx2>_meth.c

t_<pfx1>.h

t_<pfx1>_stub.c

TME stub wrapper

TME public header

TME skeleton liner

auxiliary header

defines header

auxiliary source

install tar file

skeleton src

stub src

public header

t_<pfx2>_meth.c

meth templates

TME meth templates

<pfx3>.c

main program

<pfx1>.cfg

install script

interfaceimplementationinstallationprogram

<pfx1>_imp.h

private header

t_<pfx1>_imp.h

TME private header

<pfx1>_imp.c

private src

t_<pfx1>_imp.c

TME private src

Developer

<pfx1>__ir.tar

IR tar fileTEIDL

Key:

pfx2: prefix of input file name

pfx3: program name

or program name

pfx1: prefix of input file name



TM

E 10 A

DE

Extended ID

L

The TEIDL compiler produces three sets of files:

■ TME—Used for applications that call TME 10 stubs

■ CORBA—Used for applications that call CORBA stubs

■ Common—Used to implement and install any applicationsregardless of which stubs they call

When you design your applications you have the option of providingclients that use TME 10 stubs and skeletons or CORBA stubs andskeletons. Subsequent sections describe how these files differ.

TME 10 OutputTME 10 ADE provides several services that make it easier to writedistributed applications, including distributed nested transactions andexceptions. You should use the TME 10 files generated by the TEIDLcompiler if you plan to use either of these services.

TME 10 Nested Transactions

Two of the most difficult problems in distributed applicationsdevelopment are the management of shared state and persistent data.In the event of an error, distributed systems frequently leave the objectdatabase and the system files in an inconsistent state. To cope with thisproblem, TME 10 ADE offers distributed nested transactions.

Nested transaction models provide a way to combine one transactionwith many others. It allows you to develop a hierarchy of transactionsand define an interdependency among them. In the event of an error, anested transaction hierarchy enables you to abort specificsub-transactions. This provides a more manageable environment fordistributed applications.

Refer to theApplication Services Manual for more information aboutTME 10 nested transactions.

TME 10 Exceptions

Nested transactions provide an easier way to manage distributedapplications when errors occur. They do not, however, address theproblems associated with detecting such errors.


4–58 Version 3.6

Traditional error detection techniques focus on error codes. Using thisscheme, programmers spend a significant amount of time producingsource code to detect errors and return a specific code in the event ofan error.

Furthermore, applications that use such error detection andmanagement techniques are only as reliable as the source code thatimplements them. To cope with this problem, TME 10 ADE supportsdistributed exceptions with termination semantics.

Exceptions provide a mechanism for error detection and managementthat relies less on the application programmer. In common ORBsystems, applications always comprise two parts: the client and theobject implementation.

In traditional programming environments, the object implementationmust contain the required logic to detect an error and then return anerror code. The client must then contain the logic required to processthe error. If the client does not contain the logic to detect and processthe error, the application often continues and then catastrophicallyfails. Such failures complicate the detection and debugging ofproblems.

Exceptions allow you to build error detection and management into theobject implementation. If you use TME 10 exceptions in the objectimplementation, run-time errors become easier for clients to manage.When an error occurs, the object implementation throws an exceptionand the client should then catch that exception.

If the client does not catch the exception, the TME 10 Frameworkrun-time automatically performs the following actions:

■ Manages the error

■ Takes the call out of that process

■ Returns the call to the original caller

The original caller then has the opportunity to catch the exception.If the original caller does not catch the exception, this scenario isrepeated until the outer-most calling layer is reached. If an exceptionis not caught here, the program is aborted in a controlled fashion.

See theTivoli Application Services Manual for more informationabout exceptions.



TM

E 10 A

DE

Extended ID

L

TME 10 Files

The TEIDL compiler generates the following TME 10 files:

■ TME 10 private header—Contains private APIs for TME 10applications

■ TME 10 method template—Contains templates for methods thatuse TME 10 nested transactions or TME 10 exceptions

■ TME 10 public header—Contains TME 10 APIs for client use

■ TME 10 private source—Contains definitions of accessor andmutator functions implemented in methods that use TME 10nested transactions and TME 10 exceptions

■ TME 10 skeleton liner—Contains TME 10 skeletonliners thatinterface with the TME 10 CORBA skeleton

■ TME 10 stub wrapper—Contains definitions of TME 10 stubwrappers, which are declared in the TME 10 public header

The TME 10 stub wrappers and skeleton liners contain code wrappedaround CORBA stubs and CORBA skeletons. They are thus CORBAcompatible and can call and be called from, CORBA compatible stubs.See “TME 10 Stub Wrappers” on page 4-61 for more informationabout TME 10 stub wrappers.

You should not modify the files listed in this section, except for theTME 10 method template(s). The method template files contain onlythe required preprocessor statements and empty method bodies.Use these template files to implement the methods required for yourapplication. You need to be aware of the other TME 10 files for thepurpose of compiling and linking your application.

CORBA OutputIf you do not want to use TME 10 nested transactions or TME 10exceptions, you should use the following CORBA files produced bythe TEIDL compiler:

■ Private header—Contains private APIs for CORBA applications

■ Method template—Contains templates for methods that do notuse TME 10 nested transactions or TME 10 exceptions


4–60 Version 3.6

■ Public header—Contains CORBA APIs for client use

■ Private source—Contains definitions of accessor and mutatorfunctions implemented in methods that do not use TME 10 nestedtransactions and TME 10 exceptions

■ Skeleton source—Contains the skeletons for objectimplementations that do not use TME 10 nested transactions orTME 10 exceptions

■ Stub Source—Contains definitions of stub functions declared inthe CORBA public header

You should not modify the files listed in this section, except for themethod template(s). The method template files contain only therequired preprocessor statements; you use them to implement themethods required for your application. You should be aware of theother files for the purpose of compiling and linking your application.

Common OutputThe following TEIDL compiler generated files are used by allapplications, regardless of whether they use TME 10 nestedtransactions or TME 10 exceptions:

■ Configuration script—Contains the commands necessary toinstall your application.

■ Installation tar file—Contains information for the installationscript.

■ Auxiliary header—Contains the following:

• Function declarations for compiler-generated marshalroutines

• Marshal tables for each IDL operation and attribute

■ Auxiliary source—Contains the following:

• TypeCode constant definitions

• Type repository information

• Definitions of compiler generated marshal routines

• Definitions of copy/equal functions for interface types



TM

E 10 A

DE

Extended ID

L

■ Defines header—Contains#defines for operation and attributenames used by the BOA to locate the correct entry point in animplementation.

■ Main program—The main program for the objectimplementation.

File DescriptionsThe previous description of the files produced by the TEIDL compileris very brief. This section provides more detail about some of thesefiles.

TME 10 Stub Wrappers

The purpose of a CORBA client stub, is to manage the transfer of datafrom the client program to the ORB and to pass return data back to theclient. In so doing, it performs two hidden tasks:

■ Marshals the parameters passed to it as part of request

■ Unmarshals the return data from the object implementation

If you are using TME 10 transactions and exceptions, the stub mustalso manage these items. The compiler therefore produces a TME 10wrapper for each CORBA-compliant stub, which facilitates themanagement of TME 10 transactions and exceptions.

TME 10 clients should call the wrapper to initiate an operation request,and the wrapper will then call the appropriate stub and pass therequired parameters to it. The process of passing information from thewrapper to the stub is opaque to the client.

See “ANSI C Binding” on page 4-69 for more information about thepurpose and details of this process.

TME 10 Skeleton Liners

The purpose of a CORBA server skeleton is to manage the transfer ofdata from the ORB to the object implementation and to manage returndata back to the ORB. In so doing, it performs two additional tasks:

■ Unmarshals the request from the client

■ Marshals the return data from the object implementation


4–62 Version 3.6

If you are using TME 10 transactions and exceptions, the skeletonmust also manage these items. The compiler therefore produces a TME10 liner for each CORBA-compliant skeleton, which facilitates themanagement of TME 10 transactions and exceptions.

The skeleton calls the liner, which then calls the TME 10 objectimplementation. The liner then retrieves the transaction object fromthe ORB and supplies it to the object implementation.

When the object implementation returns, the liner catches anyexceptions and converts them to a CORBA environment structure.It then passes the environment structure back to the skeleton, which iscompletely unaware of the TME 10 exception. The skeleton thenmarshals the data and passes it back to the ORB.

See “ANSI C Binding” on page 4-69 for more information about thepurpose and details of this process.

Method Templates

The TME 10 ADE extended compiler produces two C source filetemplates for each method specified in your implementation file: aTME 10 template and a CORBA template. You should implement yourmethod using only one of these two files.

Before you implement your method, choose the appropriate methodtemplate. If your method uses TME 10 exceptions or TME 10transactions, implement it using the TME 10 method template whosename has the following form: t_<pfx2>_meth.c, where<pfx2> is thename of the implementation file.

If your method does not fit into one of the presented categories,implement it using the standard CORBA method template whose namehas the following form:imp-file-name_meth.c, whereimp-file-name isthe name of the implementation file.

TME 10 Method Template

The following code fragment depicts a typical TME 10 methodtemplate:1 /*

2 * Tivoli implementation of companyDB interface. Some

3 * error checks are omitted.



TM

E 10 A

DE

Extended ID

L

4 */

5 #include <tivoli/t_companyDB.h>

6 #include <tivoli/t_companyDB_imp.h>

7 #include <tivoli/ExException.h>

8

9 void t_imp_companyDB_new_office( companyDB _companyDB,

10 Environment *_ev, transaction _transaction, char *

11 company_name, companyDB_city new_city) {

12 }

The template provides the necessary preprocessor directives and anoperation with signature, which contains a parameter that specifies thetransaction type. The compiler produces the template contents fromthe information in your IDL and TEIDL files.

The method template contains a directive to includeExException,which enables the method to catch and throw exceptions derived fromthis class. This is different from the CORBA method template, whichdoes not contain a reference to any TME 10 exception class.

After you run the TEIDL compiler, you can open the file and edit itusing a standard editor such as vi or emacs. The TEIDL compiler alsoproduces a complementary header file, but it is complete and thereforeyou need not modify it.

CORBA Method Template

The following code fragment depicts a standard CORBA methodtemplate:1 /*

2 *CORBA implementation of companyDB interface. Some

3 *error checks are omitted.

4 */

5 #include <tivoli/companyDB_imp.h>

6

7 void imp_companyDB_new_office(companyDB _companyDB,

8 Environment *_ev,

9 char * company_name,

10 companyDB_city new_city) {

11 }

Like the TME 10 method template, the CORBA template contains thenecessary preprocessor directives and an operation with signature.


4–64 Version 3.6

Unlike the TME 10 method template the CORBA template contains noreference to exceptions or transaction types.

After you run the TEIDL compiler, you can open the file and edit itusing a standard editor, such as vi or emacs. The TEIDL compiler alsoproduces a complementary header file, but it is complete and you neednot modify it.

Public Header Files

The public header file (whether CORBA or TME) contains the part ofthe C language binding that a client application must have to use theinterface. It contains the following components:

■ C language mapping of types defined in IDL source.

■ Stub function declarations for IDL operations and attributes.

■ TypeCode constants for user-defined types. A type code is avalue that describes an IDL data type. (TypeCode constants forbasic types (CORBA 7.6.2) are predefined by the run-time andare accessible by includingorb.h. Their declarations are intmf_marshall.h which is included byorb.h.)

■ Convenience functions:

• Type-specific_copy functions make adeep copy of aconstructed type (struct, union and sequence, or anytypedefalias to them) from a prototype of the same type. A deep copymeans all pointers within the prototype argument will befollowed, and memory will be allocated for them in theduplicate. Thus, the duplicate and the prototype do not shareany pointers.

• Type-specific_equal functions compare two values of thesame constructed type (a struct, union, sequence or anytypedef alias to them). The comparison semantics follow:



TM

E 10 A

DE

Extended ID

L

• _create function for each exception type. The function takesone argument for each member of the exception and returnsa pointer to a newly created exception value. The functionallocates an exception structure and makes a deep copy of thearguments. The return value can be used withBOA_set_exception or to throw an exception. See “BOA”on page 6-20 for more information aboutBOA_set_exception. See theTivoli Application ServicesManual for information about throwing exceptions.

Type Two values of this type are equal if

integer types, floating point types,boolean, char, octet, string

Their values are equal.

any The TypeCodes are equal and their values areequal.

TypeCode They refer to the same type (as determined byTypeCode_equal).

Principal It is inappropriate to compare two Principalreferences.

Object They have the same string representation.

struct All members are equal.

union The discriminators match, and the case values areequal.

enum They refer to the same member of the enum.

sequence They have the same _length field, and theelements are equal at each index.

array The elements are equal at each index.


4–66 Version 3.6

■ Type repository declarations. A type repository containsinformation on what types are available through inclusion of theheader file. Thus ifbar.idl includesfoo.idl, then all types definedin foo.idl or bar.idl are available throughbar.h.

The primary use of type repositories is in supporting the IDLanytype. By searching through the available type repositories, theTME 10 run-time discovers the real type when a value of theanydata type is transferred from machine to machine.

There is one type repository per public header file: foo.idl willhave a type repository calledfoo_type_repository in foo.h.

In addition to these components, the TME 10 public header providesdeclarations of the TME 10 stub wrappers, which support TME 10exceptions and transactions.

Private Header Files

The private header files (whether CORBA or TME) contain privateAPIs used by the implementation. The files contain the following:

■ C language mapping of types defined in the implementationconstruct including the type codes

■ Database accessor and mutator prototypes

■ Method prototypes, which are implemented by the developer

■ Convenience functions

■ Declaration of parent stubs to call overridden methods

Parent stubs are private to the method implementation. They can beused to invoke a method implementation that the currentimplementation has overridden. If you want to add behavior to amethod, you can override the method implementation by providinganother method of the same name.

In such cases, your new implementation can call the parent stubs thatare declared in the private header file along with any other code thatprovides the desired behavior. See “Example Output Files” onpage 4-70 for example parent stubs.



TM

E 10 A

DE

Extended ID

L

Clients should not include the private header using the#includedirective. The CORBA private header file and the TME 10 privateheader file differ in the following ways:

■ The convenience functions provided by the CORBA headerreturn error codes using theEnvironment* argument.

■ The convenience functions provided by the TME 10 headerthrow TME 10 defined exceptions.

Defines Header

The TEIDL compiler produces a definitions header file for you thatcontains#defines for operation and attribute names. The compilerproduces the definitions using the IDL-defined scope of the operationor attribute. Consider, for example, the following code fragmentdepicting an example IDL-defined interface:1 interface Propagation {

2

3 enum force_flags {no_force, force, force_all,

4 initial_merge};

5

6 readonly attribute object_label_list_t last_failed;

7

8 void push(in string db_name,

9 in object_list_t subscriber_list,



12 in any appdata)

13 raises(ExDbNotFound, ExUsage, ExWdenied);

14 }

The TEIDL compiler will produce the following#define in the TEIDLdefines header:

#define PROPAGATION_PUSH “push”

You should use the preprocessor definitions instead of hard-codedstring names where method or attribute names must be stored.This increases the probability that programming errors are detected atcompile-time rather than at run-time.


4–68 Version 3.6

Configuration Script

When you run the TEIDL compiler it produces a configuration script,which contains the commands for installing the classes defined in yourTEIDL files. After running the compiler you should run this scriptbefore attempting to instantiate any classes or initiate requests of anyobjects.

When you run the script, it will add the appropriate class references tothe library in theTivoli Management Region (TMR). This isnecessary so that when you request a service of a class, such ascreate_instance, the ORB can correctly identify the class and pass therequest to it. See theApplication Services Manual for informationabout TMRs.

After running the script your class is installed and initialized. You canthen create class instances and initiate requests of those instances asrequired by your program.

All TME 10 classes in each TMR are registered in thename registryfor that TMR by the configuration script. The Name Registry is theprimary means for managing object references and user-friendlynames for classes and instances of those classes. See theApplicationServices Manual for more information about the name registry.

Building a Client-Server ProgramThe following table lists the files required to build your client-serverprogram:

Header Source

CORBA Client <pfx1>.h<pfx1>_aux.h<pfx1>_defs.h

<pfx1>_stub.c<pfx1>_aux.cApplication code.

CORBA Server <pfx1>.h<pfx1>_aux.h<pfx1>_defs.h<pfx1>_imp.h

<pfx2>_skel.c<pfx1>_aux.c<pfx1>_imp.c<pfx2>_meth.c<pfx3>.c

ANSI C Binding


TM

E 10 A

DE

Extended ID

L

ANSI C BindingTEIDL supports a language binding for ANSI C. This sectiondescribes the mapping from TEIDL to ANSI C. Example input andoutput files demonstrate this mapping.

Example Input FilesThe following sections present example input files.

example.idl1 interface ex{

2 struct s { long l; };

3 exception e { short code, string reason; };

4 long op1();

5 void op2(in long l);

6 void op3(out long l);

7 };

example.imp1 #include <example.idl>

2 implementation class i_ex honors ex {

3 typedef long count;

4 struct priv { long l; };

5 methods {

TME Client <pfx1>.ht_<pfx1>.h<pfx1>_aux.h<pfx1>_defs.h

t_<pfx1>_stub.c<pfx1>_aux.cApplication code.

TME Server <pfx1>.ht_<pfx1>.h<pfx1>_aux.h<pfx1>_defs.h<pfx1>_imp.ht_<pfx1>_imp.h

<pfx2>_skel.c<pfx1>_aux.ct_<pfx2>_skel.ct_<pfx2>_meth.c<pfx1>_imp.ct_<pfx1>_imp.c<pfx3>.c

Header Source

ANSI C Binding

4–70 Version 3.6

6 { op1, op2, op3 };

7 };

8 attribute count num;

9 };

10 implementation class i_ex2 : i_ex honors ex {

11 methods {

12 { op2 };

13 };

14 };

example.prog1 #include <example.imp>

2 program prog1 for i_ex {

3 executes{ op1, op3 } daemon;

4 };

5 program prog2 for i_ex, i_ex2 {

6 executes{ i_ex::op2, i_ex2::op2 } daemon;

7 };

example.ist1 #include <example.prog>

2 installation ist_ex for i_ex with prog1, prog2{

3 // define the right stuff.

4 };

5

6 installation ist_ex2 for i_ex2 with prog2 {

7 // define the right stuff.

8 };

Example Output FilesThe compiler provides a naming scheme for the output files itproduces. The following tables depict this naming scheme.The compiler takes one input file, in this caseexample.ist.

File Name Contents

example_stub.c CORBA stub definitions: ex_op1, ex_op2, ex_op3

t_example_stub.c TME stub definitions: t_ex_op1, t_ex_op2, t_ex_op3

ANSI C Binding


TM

E 10 A

DE

Extended ID

L

example.h C type definitions: ex, ex_s, ex_eCORBA stub prototypes: ex_op1, ex_op2, ex_op3TypeCode declarations: TC_ex_s, TC_ex_e, TC_exType repository declaration: example_type_repositoryConvenience function declarations: _equal_ex_s, _copy_ex_s,_create_ex_e

t_example.h Stub wrapper prototypes: t_ex_op1, t_ex_op2, t_ex_op3Convenience function prototypes: _t_equal_ex_s, _t_copy_ex_s

File Name Contents

prog1.c Main program and skeleton entry points for i_ex::op1, i_ex::op3

prog2.c Main program and skeleton entry points for i_ex::op2, i_ex2::op2

prog1_meth.c Empty CORBA method templates: i_ex_op1, i_ex_op3

t_prog1_meth.c Empty TME method templetes: t_i_ex_op1, t_i_ex_op3

prog2_meth.c Empty CORBA method templates: i_ex_op2, i_ex2_op2

t_prog2_meth.c Empty TME method templates: t_i_ex_op2, t_i_ex2_op2

prog1_skel.c Skeletons for i_ex::op1, i_ex::op3

t_prog1_skel.c Liners for i_ex::op1, i_ex::op3

prog2_skel.c Skeletons for i_ex::op2, i_ex2::op2

t_prog2_skel.c Liners for i_ex::op2, i_ex2::op2

File Name Contents

ANSI C Binding

4–72 Version 3.6

example_imp.h Private C types: i_ex_count, i_ex_privCORBA implementation prototypes: i_ex_op1, i_ex_op2,i_ex_op3, i_ex2_op2DB accessor/mutator prototypes: _i_ex__get_num, _i_ex__set_numInherited DB accessor/mutator macros: _i_ex2__get_num,_i_ex2__set_numParent stub macro: _p_i_ex2_op2Private convenience functions: _equal_i_ex_priv, _copy_i_ex_priv.Private TypeCode declarations: TC_i_ex_count, TC_i_ex_privPrivate marshaling function prototypes for the runtime

t_example_imp.h TME method implementation prototypes: t_i_ex_op1, t_i_ex_op2,t_i_ex_op3, t_i_ex2_op2TME DB accessor/mutator prototypes: _t_i_ex__get_num,_t_i_ex__set_numInherited DB accessor/mutator macros: _t_ex2__get_num,_t_i_ex2__set_numTME parent stub macro: _t_p_i_ex2_op2TME private convenience function prototypes: _t_equal_i_ex_priv,_t_copy_i_ex_priv

example_imp.c Private TypeCode definitions: TC_i_ex_count, TC_i_ex_privDB accessor/mutator definitions: _i_ex__get_num, _i_ex__set_numPrivate convenience function definitions: _equal_i_ex_priv,_copy_i_ex_privMarshal routines for private types

t_example_imp.c Private DB accessor/mutator definitions: _t_i_ex__get_num,_t_i_ex__set_numPrivate convenience function definitions: _t_equal_i_ex_priv,_t_copy_i_ex_priv

File Name Contents

ANSI C Binding


TM

E 10 A

DE

Extended ID

L

ANSI C Function Signatures

In addition to providing a naming scheme for the output files, theTEIDL compiler also provides a naming scheme for the operations andmethods you define. The following tables depict the operation andmethod naming scheme for the presented example.

File Name Content

example_aux.h Declares marshal related items for the run-time

example_aux.c Defines marshal tables, marshal routines for the run-timeTypeCode definitions: TC_ex_s, TC_ex_e, TC_exType repository definition: example_type_repositoryConvenience function definitions: _equal_ex_s, _copy_ex_s,_create_ex_e, _t_equal_ex_s, _t_copy_ex_s

example_defs.h Contains #defines for operation/attribute names. These names areused as a method identifier by the BOA to choose the correct entrypoint in an implementation

File Name Content

example.cfg Configuration script

example_ir.tar Interface repository records

example_ist.tar Installation information

CORBA Stub CORBA Implementation

long ex_op1(ex, Environment *) long i_ex_op1(ex, Environment *)

void ex_op2(ex, Environment *, long ) void i_ex_op2(ex, Environment *, long)

void i_ex2_op2(ex, Environment *, long)

void ex_op3(ex, Environment *, long *) void i_ex_op3(ex, Environment *, long *)

ANSI C Binding

4–74 Version 3.6

TME Wrapper TME Implementation

long t_ex_op1(ex, Environment *,trans_t)

long t_i_ex_op1(ex, Environment *, transaction)

void t_ex_op2(ex, Environment *,trans_t, long)

void t_i_ex_op2(ex, Environment *, transaction,long)

void t_i_ex2_op2(ex, Environment *,transaction, long)

void t_ex_op3(ex, Environment *,trans_t, long *)

void t_i_ex_op3(ex, Environment *, transaction,long *)

CORBA Parent Stub TME Parent Stub

void _p_i_ex2_op2(ex, Environment *,long)

void _t_p_i_ex2_op2(ex, Environment *,trans_t, long)

CORBA Accessor/Mutator TME Accessor/Mutator

long _i_ex__get_num(ex, Environment *) long _t_i_ex__get_num(ex, Environment *)

void _i_ex__set_num(ex, Environment *,long)

void _t_i_ex__set_num(ex, Environment *,long)

CORBA Convenience Functions TME Convenience Functions

tmf_boolean _equal_ex_s(Environment*, const ex_s *, const ex_s *)

tmf_boolean _t_equal_ex_s(Environment *,const ex_s *, const ex_s *)

ex_s _copy_ex_s(Environment *, constex_s *)

ex_s _t_copy_ex_s(Environment *, const ex_s *)

Bourne Shell Binding


TM

E 10 A

DE

Extended ID

L

Bourne Shell BindingTEIDL supports a language binding for bourne shell script.This section describes the mapping from TEIDL to Bourne shell.

Special CharactersThe following characters are token separators:

■ Space

■ Tab

■ Newline

■ {—used to begin a constructed type

■ }—used to terminate a constructed type

The shell binding also supports three characters for expressing literals:

■ \—used to escape special characters

■ “ —used to enclose a string literal

■ ‘—used to enclose a character literal

A typical use for the \ (backslash) character is using it to include aspecial character such as a curly brace as part of a variable name asshown:

variable_na{me

ex_e *_create_ex_e(const short, constchar *)

Same as the CORBA signature

tmf_boolean_equal_i_ex_priv(Environment *, consti_ex_priv *, const i_ex_priv *)

tmf_boolean _t_equal_i_ex_priv(Environment*, const i_ex_priv *, const i_ex_priv *)

i_ex_priv _copy_i_ex_priv(Environment*, const i_ex_priv *)

i_ex_priv _t_copy_i_ex_priv(Environment *,const i_ex_priv *)

CORBA Convenience Functions TME Convenience Functions


4–76 Version 3.6

The preceding example is interpreted asvariable_na{me rather thanthe following:

variable_na { me

Avoid using a backslash to escape a special character inside singlequoted character literals and double quoted string literals. You couldfor example, replace the previous string, which uses a backslash withthe following, which uses double quotes:

“variable_na{me”

The preceding example is interpreted as a string literal.

Basic TypesBasic types (rather than constructed types) can be supplied to the ORBasinput or inout arguments in the same representation as theircorresponding literals in IDL (see section 4.1.5 in the CORBAspecification). When the ORB returns a basic type as the result,out, orinout argument, it may not choose the same representation as the shellmethod. The returned value, however, is guaranteed to preserve thecorrect value.

The following table details the way data types are passed to and fromthe ORB:

Type Send to ORB Receive from ORB

shortlongunsignedshortunsignedlong

Decimal, octal, or hexadecimalinteger literal (CORBA 4.1.5.1)optionally prefixed by + or -a;example: 12, 012, 0x12

Decimal integer literal. Octal andhexadecimal integers will be convertedto their decimal equivalent; example:12, 10 (for 012), 18 (for 0x12)

floatdouble

A floating point literal (CORBA4.1.5.3) optionally prefixed by + or-; example: 1.2, 12E3, 12E-2

A floating point literal in the style:[-]d.dddddde{+|-}dd{d}; example:1.200000e+00, 1.200000e+04,1.200000e-01



TM

E 10 A

DE

Extended ID

L

Constructed TypesAll constructed typesarray, enum, sequence, struct, union,TypeCode, Principal , andany are described by listing their membersenclosed by curly braces.

Review the following code fragment, which depicts a typical interfacedefinition that is intended to be implemented as a shell script:1 #pragma generate False

2 #include <tivoli/orb.idl>

3 #pragma generate True

4

5 module shell_ex {

6 const long SIZE = 3;

7 typedef char arr_char[SIZE];

8 typedef short arr_short[SIZE];

9 typedef float arr_float[SIZE];

10 typedef sequence<octet,SIZE> octet_seq;

11

12 enum color { red, blue, green };

13 union u switch (color) {

14 case red: Object o;

15 case blue: struct s {

16 arr_char ac;

17 arr_short as;

a. No space is allowed between the sign and the number.

char A single quoted character literal(CORBA 4.1.5.2); example: ‘A’,‘\n’, ‘\201’, ‘\x41’, ‘{‘

A single character (if printable) or theoctal value within single quotes;example: ‘A’, ‘\012’, ‘\201’, ‘A’, ‘{‘

boolean TRUE or FALSE TRUE or FALSE

string A string within double quotes(CORBA 4.1.5.4); example: “thisis a test”.

A string within double quotes.

octet Same as a char; example: ‘A’,‘\201’

Always output in octal; example:‘\101’, ‘\201’

Type Send to ORB Receive from ORB


4–78 Version 3.6

18 arr_float af;

19 octet_seq os;

20 boolean b;

21 } s;

22 default: string str;

23 };

24

25 exception ex { color c; long code; };

26 exception empty { };

27

28 interface test {

29 any op(in any a, inout any b, out any c)

30 raises (ex, empty);

31 attribute u attr;

32 };

33 };

The following table describes the way parameters are passed to theORB from the example IDL-defined interface.

Type Syntax Description Example: Input to ORBa

array List all elements starting at first index.Multi-dimensional arrays are listed inrow-major order.

shell_ex::arr_char{ ‘ A’ ‘\201’ ‘\n’ }

enum The (unscoped) enumerator name. shell_ex::colorblue

sequence The length followed by the elements.The number of elements listed must match thelength. If the length is zero, no elements arelisted.

shell_ex::octet_seq{3 ‘\v’ ‘Z’ ‘\200’ }

struct The members in order of the IDL description. shell_ex::u::s{ { ‘A’ ‘\201’ ‘\n’ } { 123 83291 } { 1.23 1.23e+2 3E-2 } {3 ‘\v’ ‘Z’ ‘\200’ } FALSE }

union The discriminator value followed by the casevalue.

shell_ex::u{ red 3001.1.1 }

objref The string representation (value returned byORB_object_to_string).

3001.1.1OBJECT_NIL



TM

E 10 A

DE

Extended ID

L

Bourne Shell Method ImplementationsFor most applications, writing a shell script to perform some task israther straightforward. Initiating requests in a common ORBenvironment, however, can become more complicated than doing so ina more traditional environment. This difficulty results from the factthat methods implemented as shell scripts must marshal and unmarshaldata just like compiled programs.

TME 10 ADE therefore supports several utilities to simplify this task:

■ idlinput —The command should callidlinput to send thein orinout parameter list to the method. The arguments are presentedin the same order as the they are listed in the IDL signature. Theargument list to theshell_ex::test::op operation can be bound toinargs by making the following call:

inargs=‘idlinput‘

A typical inargs list follows:

“{ { shell_ex::u } { red 3001.1.1 } }{ { shell_ex::u } { green \”shell binding example\” } }“

a. Output is similar except that the basic types may come out in a different (valuepreserving) form.

typecode Double-colon-separated, fully scoped name ofthe type. For predefined types, the name isone ofnull, void, short, long, ushort, ulong,float, double, boolean, char, octet,TypeCode, Principal, Object, string.

{ shell_ex::u }

any TypeCode followed by the value. { { shell_ex::u } { green“shell” } }

principal The Token Principal. Principal

Type Syntax Description Example: Input to ORBa


4–80 Version 3.6

■ idlarg—This command extracts individual arguments in anargument list returned byidlinput . This utility can also be usedto get to the members of a constructed type. Using the sameexample the idlarg command extracts the arguments as shown:

a=‘idlarg 1 “$inargs”‘b=‘idlarg 2 “$inargs”‘

These commands binda andb to the following variablesrespectively:

“{ { shell_ex::u } { red 3001.1.1 } }”

and

“{ { shell_ex::u } { green \”shell binding example\”} }“

Because the value of a (of type any) is a union, its members, (thatis, the case and the member value), can be accessed by callingidlarg again:

value=‘idlarg 2 “$a”‘case=‘idlarg 1 “$value”‘member=‘idlarg 2 “$value”‘

In this example,case andmember are bound tored and3001.1.1respectively.idlarg exits with a non-zero status on error and withzero otherwise.

■ idlresult—This utility formats theinout andout arguments orthe result, if any. Theinout andout arguments must be passed toidlresult in the same order as in the IDL signature. The result, ifany, follows theinout andout parameters.

■ idlexception—This utility is used to raise exceptions. The scriptmust exit with a non-zero exit code if it raises an exception.A zero exit code indicates a normal return.

The result ofidlresult andidlexception should be captured in astring, which should then be echoed just before the script exitswith the appropriate exit code.



TM

E 10 A

DE

Extended ID

L

■ Useful shell environment variables:

• TMF_SELF—The object reference (represented as a string)of the target object.

• TMF_BOA—The object reference (represented as a string)of the BOA pseudo object.

• TMF_ORB—The object reference (represented as a string)of the ORB pseudo object.

Example Bourne Shell Method ImplementationThe following sections present the shell script implementation for theIDL file presented in “Constructed Types” on page 4-77.

shell_ex::test::op1 #! /bin/sh

2 # Get all of the idl input arguments into a shell

3 # variable

4 inargs=‘idlinput‘

5 # get the arguments in the idl file

6 a=‘idlarg 1 “$inargs”‘

7 b=‘idlarg 2 “$inargs”‘

8 # assign to the inout/out arguments

9 b=”{

10 { shell_ex::u } { red 3001.1.1 }

11 }“

12

13 c=”{

14 {shell_ex::u} {green\”shell binding example\”}

15 }“;

16

17 # Pass the output/result from the method to the caller.

18 # Note that the order of the results is important, first

19 # the inout/out arguments and then the result. The

20 # return result, in this case, is the in argument.

21 out_args=‘idlresult <<!EOF

22 $b

23 $c

24 $a

25 !EOF

26 ‘


4–82 Version 3.6

27 echo $out_args

28 exit 0

The script can raise an exception as shown:1 #! /bin/sh

2 # Write the exception.

3 excep=‘idlexception “{USER_EXCEPTION shell_ex::ex

4 {green 99}}”‘

5 # If we wanted to raise the empty exception instead, we

6 # would say:

7 # excep=‘idl_exception “{USER_EXCEPTION

8 # shell_ex::empty {}}”‘

9 # Note that exception data is just a pair of {}.

10 echo $excep

11 # Indicate an exception by a non-zero exit code.

12 exit -1

shell_ex::test::_get_attr1 #! /bin/sh

2 # gets a hard-coded result

3 r = “{

4 blue {

5 {‘ ‘ ‘\201’ ‘\n’} {100 200 300}

6 {1.23 1.23e+2 3E-2} {3 ‘\v’ ‘Z’ ‘\200’}

7 FALSE

8 }

9 }”

10 out_args=‘idlresult <<!EOF

11 $r

12 !EOF

13 ‘

14 echo $out_args

15 exit 0

shell_ex::test::_set_attr1 #! /bin/sh

2 inargs=‘idlinput‘

3 # get the argument in

4 a=‘idlarg 1 “$inargs”‘

5 # store it in a file, along with the target object

6 # reference

Command Method Binding


TM

E 10 A

DE

Extended ID

L

7 echo $a > /tmp/db/set_attr

8 echo $TMF_SELF >> /tmp/db/set_attr

9 exit 0

This script can raise an exception as follows:1 #! /bin/sh

2 # Raise a standard exception

3 out_args=‘idlexception

4 “{SYSTEM_EXCEPTION StExcep::BAD_PARAM {999 NO }}”‘

5 echo $out_args

6 exit 1

Command Method BindingTEIDL supports a language binding for command methods, which arealways implemented as shell scripts. If you specify a commandmethod, the system provides a helper process to manage the I/O for themethod.

The following code calls the UNIXps command with the firstparameter as the option. The output produced byps is sent back to thecaller (as thestdout output). The return value is 10.1 #! /bin/sh

2 /bin/ps $1

3 exit 10

The exit code of a command method does not indicate an exception;instead, it is the return value of the method. If the command methoddied because of a signal, the ORB creates anExCommand exceptionand sends it back to the client. Thus, a command method neverexplicitly creates and returns an exception; the exception creation isimplicit when the command dies because of a signal.

See “Implementation-Defined Methods” on page 4-30 for moreinformation about command method signatures.

TEIDL Compiler OperationInvoke the TME 10 ADE IDL Compiler as shown in the following CLIcommand:

tidlc [ -I pathname][ -D name[ =def]][ -U name] source_file

TEIDL BNF Grammar Description

4–84 Version 3.6

The compiler invokes the C preprocessor (cpp) and passes thecommand line options to it. Thecpp preprocessor requires you toinclude anewline character at the end of each IDL and TEIDL file.You should therefore verify that each of your input files contains anewline character at the end of the file.

If you have multiple source files, such as interface definition andimplementation specification, you can include the additional filesusing the#include preprocessing command.

Source files (specified by thesource_file parameter) must bedesignated by file name as follows:

■ Interface definition file names must contain an extension of.idl .

■ Implementation file names must contain an extension of.imp.

■ Program file names must contain an extension of.prog.

■ Installation file names must contain an extension of.ist.

The command line options have the following meaning:

■ -Ipathname—Add pathname to the list of directories in which tosearch or#include files with relative file names (not beginningwith slash ‘/’). The preprocessor first searches for#include filesin the directory containing the source file, then in directoriesnamed with-I options (if any), and finally, in /usr/include.

■ -Dname[=def]—Define a symbol name to the C preprocessor.Equivalent to a#define directive in the source. If nodef is given,name is defined as1.

■ -Uname—Remove any initial definition of thecpp symbol name.Inverse of the-D option.

TEIDL BNF Grammar DescriptionSubsequent sections present the BNF grammar for the threecomponents of TEIDL—implementation, program, and installation.You can find some of the grammar components presented here in theCORBA 1.1 specification beginning on page 54.



TM

E 10 A

DE

Extended ID

L

Implementation Grammar

<implementation> ::= <implementation_dcl>

<implementation_dcl> ::= <implementation_header> “{“

<implementation_body> “}”

<implementation_header> ::= <class_header>

| <object_header>

<class_header> ::= “ implementation ” [ “ abstract ” ] “ class ”

<identifier> [<inheritance_spec>] “ honors ”

<scoped_name> [<metaclass_spec>]

<object_header> ::= “ implementation ” “ object ” <identifier>

[<inheritance_spec>] “ honors ” <scoped_name>

<implementation_body> ::= <implement>*

<implement> ::= <type_dcl> “;”

| <const_dcl> “;”

| <impl_attr_dcl> “;”

| <impl_meth_dcl> “;”

| <intrinsic_meth_dcl> “;”

<metaclass_spec> ::= “ metaclass ” <scoped_name>

<impl_attr_dcl> ::= “ attribute ” <simple_type_spec><declarators>

<impl_meth_dcl> ::= “ methods ” “{“ <meth_spec>+ “}”

<meth_spec> ::= <meth_group> [<impl_binding_spec>] “;”

<meth_group> ::= “{“ <scoped_name> { “,” <scoped_name> }*“}”

<impl_binding_spec> ::= “ binding ” “=” <impl_binding_token>

<impl_binding_token> ::= “ ansi C ”

| “ shell ”


4–86 Version 3.6

| “ command”

<intrinsic_meth_dcl> ::= “ intrinsics ” “{“<intrinsic_spec>+ “}”

<intrinsic_spec> ::= <scoped_name> <intrinsic_op_type>

<scoped_name> “;”

<intrinsic_op_type> ::= “ access ”

| “ mutate ”

Program Grammar

<program> ::= <program_dcl>

<program_dcl> ::= <program_header> “{“ <program_body> “}”

<program_header> ::= ” program ” <identifier>[<timeout_spec>] “ for ”

<scoped_name> { “,” <scoped_name> }*

<timeout_spec> ::= “ timeout ” “=” <positive_int_const>

<program_body> ::= <prog_defs>+

<prog_def> ::= <exec_def> “;”

| <startup_def> “;”

<exec_def> ::= “ executes ” <meth_group> <activation_def>

<activation_def> ::= <qualifiers> <server_type>

<qualifiers> ::= <qualifier> { “,” <qualifier> } *

<qualifier> ::= “ threaded ”

| “ shared ”

<server_type> ::= “ per method ”

| “ daemon”

| “ external daemon ”

<startup_def> ::= “ startup ” <startup_funcs>

<startup_funcs> ::=“{“<string_literal>{“,”<string_literal>}* “}”



TM

E 10 A

DE

Extended ID

L

Installation Grammar

<installation> ::= <installation_dcl>

<installation_dcl> ::= <installation_header> “{“

<installation_body> “}”

<installation_header> ::= “ installation ” <identifier>“ for ”

<scoped_name> [ “ with ” <scoped_name> { “,”

<scoped_name>}* ]

<installation_body> ::= <install>*

<install> ::= <acl_default> “;”

| <priv_default> “;”

| <priv_spec> “;”

| <acl_spec> “;”

| <roles_spec> “;”

| <path_spec> “;”

| <init_spec> “;”

<acl_default> ::= “ acldefault ” <acls>

<priv_default> ::= “ privdefault ” <os_priv_group>

<priv_spec> ::= “ privilege ” “{“ <meth_priv>+ “}”

<acl_spec> ::= “ acl ” “{“ <meth_acl>+ “}”

<roles_spec> ::= “ roles ” “{“ <meth_roles>+ “}”

<path_spec> ::= <path_qualifier> “ path ” “{“ <meth_path>+“}”

<init_spec> ::= “ initialize ” “{“ <init_prog>+ “}”

<meth_priv> ::= <meth_group> “=” <os_priv_group> “;”

<meth_acl> ::= <meth_group> “=” <acls> “;”

<meth_roles> ::= <meth_group> “=” <roles> “;”


4–88 Version 3.6

<meth_path> ::= <meth_group> “=” <path_group> “;”

<path_group> ::= “{“ <path>+ “}”

<path> ::= <interpreter> “,” <path_or_attr_name>

[“,”<scoped_name>] “;”

| <path_or_attr_name> [“,” <scoped_name>] “;”

<path_qualifier> ::= [“ common”] “ external

| [ “ common” ] “ internal ”

<roles> ::= “{“<string_literal>{“,”<string_literal>}*“}”

<acls> ::= “{“<string_literal>{“,”<string_literal>}*“}”

<os_priv_group> ::= “{“ <os_priv>+ “}”

<os_priv> ::= <string_literal>{“,”<string_literal>}*“;”

<interpreter> ::= <string_literal>

<path_or_attr_name> ::= <string_literal>

<init_prog> ::= <prog_name> <args> “;”

<prog_name> ::= <string_literal>

<args> ::= {“,”<string_literal>}*


Object Im

plementation

5Object Implementation

The CORBA Specification refers to an object implementation as theprovider of a service. Object implementation also describes theprocess by which service providers are created.

This chapter presents information about the characteristics of TME 10service providers and it describes the different ways they can beimplemented. The chapter explains the following material:

■ TME 10 objects

■ TME 10 Implementation Models

■ Servers per method

■ Daemon servers

■ Parallel servers

■ TME 10 concurrence

You should read this chapter before implementing TME 10 servers,because it provides important information about their behavior.

5

TME 10 Objects

5–2 Version 3.6

TME 10 ObjectsTME 10 object implementations are synonymous with the class thatimplements that service. Furthermore, TME 10 classes are representedas objects, and so they exhibit both behavior and state. TME 10objects, whether class objects or instances of those classes, have thefollowing characteristics:

■ TME 10 objects are uniquely identified.

■ TME 10 objects are modular.

■ TME 10 objects distinguish between attributes and behavior.

■ TME 10 objects are dynamic.

■ TME 10 objects are reusable.

■ TME 10 objects control access to attributes and methods.

■ TME 10 objects interact with other objects.

■ TME 10 objects maintain dynamic relationships with otherobjects.

■ TME 10 objects are persistent.

The following sections describe these characteristics in more detail.

TME 10 Objects are Uniquely IdentifiedThe sharing and reuse of object attributes and methods is commonthroughout the TME. Yet each object remains unique because itsobject reference—the identifier assigned to the object at itscreation—is unique. Think of object references as opaque data thatnames exactly one TME 10 object.

The object reference is assigned to a variable of typeObject when theobject is created. You can also translate the object reference to a stringvariable usingORB_object_to_string(). See “Pseudo-objectInterfaces” on page 6-18 for more information.

TME 10 Objects


Object Im

plementation

TME 10 Objects are ModularTME 10 objects can be combined in various ways to make new objectsof higher function. The following diagram illustrates this approach.

Employee

Manager Programmer

Object

TechnicalManagerObject

SeniorProgrammer

Object

Executive

Object

Object Object

PersonObject

Inheritance Relationship

TME 10 Objects

5–4 Version 3.6

Individual objects can be created, used, altered, and extendedindefinitely. The presented example indicates that you can designobjects to reflect all of the positions in the company, which areultimately based on (derived from) the Person object. Such derivationmeans that you need not write a newget_name function for each kindof worker or employee. Instead, this method is inherited from thePerson object.

TME 10 Objects Distinguish between Attributes andBehavior

Objects store data in two ways:

■ Variable data, such as specific characteristics, are stored ascomponents called attributes. Examples of attributes areSalaryin anEmployee object,Net Worth in aReal Estate object, andName in aPerson object.

■ Operations such asget_salary in anEmployee object are storedas methods that manipulate attributes. The total set of methodsyou can apply to an object is called object behavior.

An Employee object, for example, might have the attributes andmethods listed in the following table:

Employee Object

Attributes Methods

Name get_name

Address get_address

DateOfBirth get_dob

SocSecNumber get_ssn

Position get_position

Salary get_salary

Bonus calculate_bonus

VacationAccrued calculate_vacation

TME 10 Objects


Object Im

plementation

Object Attributes

The object attributes determine the structure of data associated with anobject. As the attribute values change, the state of the object changes.

One attribute of an object, for example, might be a list of users that areauthorized to use the object in question. Altering this list changes thestate of the object. After changing the list, some users who werepreviously authorized to use the object will no longer have access to itand new users will be able to use the object.

Object Methods

Clients cannot directly access the attributes of TME 10 objects. Whenan attribute value must change (such as when increasing a salaryvalue), the object methods perform the required operation. Regardlessof whether they are locally defined or inherited, they are the onlysoftware components that can modify the object attributes. Changes tothe attributes can modify the results of subsequent method executions.

A method consists of two components: a signature and animplementation.

Signature

The method signature defines the method parameters and the datatypes of those parameters. For example, the input arguments for amethod might be a character followed by an integer. You cannotinvoke the method by calling it with any other type of parameters.

Implementation

The method implementation is the code that you write for eachmethod. The method implementation can consist of compiled code ora Bourne shell script.

TME 10 Objects are DynamicWith dynamic objects, you can create applications that are flexible andcustom-made for your changing needs. You usebinding (the processof assigning a value) to make changes to attributes and objects.

TME 10 Objects

5–6 Version 3.6

You can alter the effect of a dynamic program at run time withoutre-compiling source code. For example, the process of binding specificvalues to variable symbols is calleddynamic binding when it takesplace at run time, and is calledstatic binding when it takes place atcompile time.

TME 10 supports the following dynamic programming features:

■ Binding variables dynamically—You can assign specific valuesto variables at run time rather than assigning them at compiletime.

■ Creating objects dynamically—You can create individual objectsand classes of objects dynamically as you need them rather thanstatically at compile time.

■ Changing objects dynamically—Once an object is created, youcan add, modify, and remove methods and attributes withoutre-compiling source code.

■ Transmitting information about objects dynamically—Objectsexchange information about attributes and methods dynamicallyby maintaining relationships with each other. See “DynamicRelationships among TME 10 Objects” on page 5-8 for moreinformation about object relationships.

TME 10 Objects are ReusableBecause they are modular and extensible, you can reuse TME 10objects for new applications. In addition, the specific attributes andmethods contained in one TME 10 object are often reused, or shared,by many objects in the same application. If, for example, object Binherits a method from object A, the inherited method is sharedbetween object A and object B. The method that originally existed inobject A is effectively reused by object B.

A specific example is offered in the office scenario presented in thesection entitled “Objects as Models” on page 1-5. The attribute andmethod for social security number is in theEmployee object and isreused by all the objects that describe various employees.

TME 10 Objects


Object Im

plementation

Reusing the attributes and methods of objects is one of the compellingadvantages of the TME. It allows you to build new components andapplications without having to start from scratch.

TME 10 Objects Interact with Other ObjectsTME 10 objects interact with other objects in several ways.The purpose of each interaction is the indirect manipulation of datawithin an object. Objects send messages to each other that invokemethods and exchange information.

This interaction, however, is always within the context of thearchitecture described in the CORBA specification. This means thatthe calling object functions in the role of client and must call theappropriate stub. It cannot call the object directly.

Furthermore, when an object responds to a call, it must respond to thecaller by way of the appropriate server skeleton. The client stub andserver skeleton represent the only facilities for communication amongobjects. The client cannot access the attributes or methods of anotherobject any other way.

As previously stated, each method has a separate signature andimplementation. The key advantage to this arrangement is the abilityto define object behavior by the response of each object to clientrequests.

Each object can behave in a different way because each applies its ownset of methods to its own attributes and then responds with appropriateresults. The requestor does not know (and does not need to know) howthe results were derived. Such behavioral details are handled by theimplementations of the object methods.

Concurrent Interaction

TME 10 objects supportconcurrent interaction. Concurrentinteraction is the notion that an object can consult other objects as aresult of a client request.

An example of such interaction is that of an object holding a list ofusers. The users are authorized to use privileged services controlled byother objects. The objects controlling the privileged services would

TME 10 Objects

5–8 Version 3.6

contact the object holding the list of users to confirm or deny access tothe services.

Concurrent interaction is possible because each TME 10 objectcontrols access to itself. Objects must control access to their data andmethods so they can maintain a consistent internal state. To do so, anobject can either use locking techniques, or it can support parallelthreads of execution to keep its data consistent.

See “Parallel Servers” on page 5-21 for more information aboutlocking techniques and execution threads.

Dynamic Relationships among TME 10 ObjectsTME 10 supports the following relationships among objects:

■ Class relationships

■ Inheritance relationships

■ Reference relationships

Class Relationships

A TME 10 class is a set of objects that have the same attributes andmethods. Individual objects of the same class are instances of thatclass. In our employee example, both Mariko and another programmer(Chuck, for instance) belong to theProgrammer class.

Inheritance Relationships

TME 10 objects support inheritance, which means objects acquireattributes and methods from predefined objects. TME 10 inheritancetypically distributes methods or attributes downward through the classhierarchy. The following diagram depicts a simple example of a classhierarchy.

TME 10 Objects


Object Im

plementation

Every class can inherit any or all of the methods and attributes madeavailable for inheritance by the classes directly above it in the classhierarchy.

An example of this inheritance is the inheritance of theEmployeeclass. It can inherit any or all of the attributes and methods of the

Employee

ManagerProgrammer

Object

TechnicalManagerObject

SeniorProgrammer

Object

Executive

Object

ObjectObject

PersonObject

TME 10 Objects

5–10 Version 3.6

Person class. This form of inheritance is known as single inheritance.This is quite different from multiple inheritance, which is depicted inthe following diagram:

Technical Manager inherits from bothProgrammer and theManager. Additionally,Sales Manager inherits from bothManagerandSalesperson. BothTechnical Manager andSales Managerexhibit multiple inheritance.

Multiple inheritance can create ambiguity about which method isinvoked when an object receives a message. TME 10 objects thereforehave a defined inheritance order to eliminate this potential ambiguity.The defined inheritance order isleft-to-right-depth-first.The following TEIDL code fragment depicts an implementationinheritance specification for theTechnical Manager class in theprevious diagram:

implementation class TechnicalManager:Programmer, Manager honors technical_manager{};

MANAGER SALESPERSONPROGRAMMER

SENIORPROGRAMMER

TECHNICALMANAGER

SALESMANAGER

PERSON

EMPLOYEE

TME 10 Objects


Object Im

plementation

In the code fragment, theTechnicalManager implementation inheritsfrom both theProgrammer and theManager implementations inaccordance with the previous diagram. Left-to-right inheritance meansthat inheritance is defined left to right in your source code. SoTechnicalManager inherits first fromProgrammer and then fromManager becauseProgrammer is presented to the left ofManager inthe TEIDL code fragment.

If both Programmer andManager have aget_salary method, theTechnicalManager implementation inheritance search resolves theget_salary method from theProgrammer implementation. Thiseliminates any ambiguity about whichget_salary method the systemwill use.

Depth-first inheritance means that theTechnicalManagerimplementation inherits from theProgrammer inheritance chainbefore it inherits from theManager inheritance chain. So if a clientinvokes aget_salary method on aTechnicalManager object, thesystem will first attempt to invoke the method on that object directly.

If the method is not found in theTechnicalManager class, the systemlooks for the method in theProgrammer class. If the method is notfound in theProgrammer class it will traverse the inheritance chainto Employee and then toPerson.

If the method is not found in theProgrammer inheritance chain, thesystem then looks for it in theManager class. If it is not found there,it will traverse the inheritance chain fromEmployee to Person. If themethod is not found when the search is exhausted, the system willthrow an exception.

Understanding the TME 10 inheritance order is important because itconstrains you as a developer to carefully consider the methods andattributes each class should contain. The system invokes the firstmethod it finds—that matches—as it searches the class inheritancehierarchy in the described left-to-right-depth-first order.

The following list describes the advantages of TME 10 inheritance:

■ It offers an efficient means of sharing different sets and subsetsof methods and attributes among many objects.

TME 10 Objects

5–12 Version 3.6

■ It enables you to provide only single copies of the definitions andimplementations of commonly used methods.

■ It enables you to reuse source code to meet expandingrequirements.

Reference Relationships

TME 10 objects can refer to one or more other objects. A reference toanother object causes the specified object reference to be stored as anattribute. References model the relationships among the real-worldentities that the objects represent.

When possible, you should use references to model relationshipsinstead of using other means to identify objects. Doing so helpsinsulate objects from changes to other objects.

For example, an object representing a particular employee might havean attribute calledSupervisor. That attribute, rather than being a placeto store the supervisor’s name, should be a reference to thesupervisor’s object. If an application needed the supervisor’s name (orphone number or e-mail address), it could query the supervisor’sobject for the current value. This technique helps ensure the use ofcurrent data by the application.

You refer to an unspecified object in your interface definition file byway of the IDL type definitionObject. You refer to a specific objecttype by using the interface name instead of theObject. Refer to theCORBA specification for more information about theObject type.

References to other objects can make your applications more efficient.It can significantly reduce the duplication of large amounts of data inlarge numbers of places. Objects representing employees, for example,need not store their own copies of information about employeesupervisors. Instead, eachEmployee object can maintain a referenceto the appropriateSupervisor object.

Finally, you can use object references to maintain information aboutarbitrary sets of objects. For example,collection objects (objects thatcan contain or collect other objects) rely on object references to createuseful object collections. Refer to theApplication Services Manual formore information about collections.

TME 10 Implementation Models


Object Im

plementation

TME 10 Objects are PersistentIn some object-oriented systems and languages, objects exist only forthe duration of program execution. When the program terminates, itsobjects become inaccessible to users and to other programs. In somesystems, the objects are destroyed when the program terminates unlessthe program has taken special steps to preserve its objects. In thesecases, the program’s execution is the only environment that allowsaccess to and manipulation of the program’s objects.

TME 10 objects arepersistent: they exist even when no program isexecuting. To get rid of an object, you must explicitly remove it usingthe remove operation from thePolicyDrivenBase interface. See themanual page on theDeletable interface for more information aboutdestroying objects.

The TME 10 preserves the object state between program executions.Persistent objects can store information indefinitely, and you can sharepersistent objects among several applications and users.

TME 10 Implementation ModelsWhen you provide your object implementation, you must specify theserver type and the execution style. You can think of these server typesas classes that instantiate objects. TEIDL program constructs specifythe characteristics of TME 10 classes and objects.

Server TypesServer types can be specified as a server per method, a daemon server,or an external daemon server. Review the program construct keywordslocated in “TEIDL Program Specification” on page 4-34.

The process under which a per method server runs will terminate whenthe method completes the last task. So if a TEIDL program executesmethods A, B, and C, each of those methods will run as separateservers and each will run under a separate process. This is importantbecause you must consider the overhead associated with starting eachserver process every time a method is called.

TME 10 Implementation Models

5–14 Version 3.6

The process under which a daemon server runs does not terminatewhen the method completes the last task. The process continues untilit is aborted or times out. A daemon server process can manage a largenumber of methods in the same process. This eliminates the overheadof starting a new process each time a method is invoked.

For daemon methods, the BOA starts a new process the first time itinvokes such a method. Subsequent invocations of that method, or anyother method within that server, will run under the same process.Thus if a program executes methods A, B, and C, they can run as asingle server under the same process.

Processes that continue to run when the methods are not active, doconsume resources. You should therefore specify a daemon server onlywhen the methods grouped within a TEIDLexecutes statement areinvoked frequently. You should also consider the specification of atime-out for each daemon server. This will prevent such servers fromconsuming resources during long periods of inactivity.

Server ExecutionServer execution styles can be specified in your TEIDL program asshared or unshared, and parallel or non-parallel. Both of these are validonly for daemon servers. The execution style of per method servers ispredefined. See “Program Body” on page 4-35 for a complete listingand summary of program specification keywords.

Shared and Unshared Servers

A shared server is one that accommodates more than one object.Consider the following example:

A program executes methods A, B, and C. The server is specified asunshared. Two different objects, object 1 and object 2, share thisprogram by way of TEIDL implementation inheritance. A clientmakes a call to object 1 and requests the operation associated withmethod A. Simultaneously, another client makes a call to object 2 andalso requests the operation associated with method A.

Servers Per Method


Object Im

plementation

In the case of an unshared server, the BOA will start a process forobject 1 and invoke method A. It will then start another process forobject 2 and then invoke method A a second time. Method A will thenconcurrently run in two separate processes, each as a daemon server.

In the case of a shared server, the BOA will start a process for object1 and invoke method A. It willnot, however, start a second process forobject 2. It will instead either queue the request for object 2 orimmediately invoke the method within the same process. The actualbehavior depends on whether the server is a parallel or non-parallelserver.

Parallel and Non-parallel Servers

A parallel server is one that allows multiple invocations of methodswithin the same process using execution threads. You specify a parallelserver with the TEIDLthreaded keyword.

In the previous example, the BOA invokes method A in the context ofobject 1 and object 2. Both invocations run under the same process.A non-parallel server will queue the second invocation, and it willbegin execution when the first invocation is complete. A parallelserver will create a new execution thread and begin executing methodA immediately.

Subsequent sections explain the implementation of each server typeand each execution style.

Servers Per MethodA per method server represents a simple implementation, and requiresno special set-up. You merely edit the method template file and writeyour method. Simplicity, however, limits your capacity to managegroups of methods and frequently invoked methods.

To determine whether the server should be of the per method type,consider the process under which the method(s) will run. A simpleexample is that of a single method that is infrequently invoked onetime and then terminates. In such cases a per method implementationis usually adequate, because there is no need to sustain the processunder which the method was running. The per method implementation

Daemon Servers

5–16 Version 3.6

is so named because the BOA starts a new process for each methodwhen the method is invoked.

Per method implementations is not limited to single methods; you canalso use it to manage groups of methods. When you do so, however,you should exercise caution. Because each method uses a separateprocess, the overhead associated with managing large groups ofmethods can become significant. See “Program SpecificationConstructs” on page 4-34 for information about specifying groups ofmethods in a TEIDL program.

Finally, consider the case of methods that are invoked frequently.In such cases, per method implementations require the BOA to spenda significant amount of time starting and terminating processes foreach method as it is invoked and terminated. Like the previous case,this can result in overhead that is unacceptably high.

In the case of multiple methods for a single program or frequentlyinvoked methods, you should consider specifying a daemon serverrather than a server per method.

Daemon ServersDaemon server implementations differ from per methodimplementations in the way method processes are managed. Theyincrease your capacity to manage groups of methods and frequentlyinvoked methods, but they are, of course, more complicated.

To determine whether the implementation should be a daemon server,consider the process under which the method(s) will run. An obviousexample is that of a frequently invoked method. The first time themethod is invoked, the BOA will start a new process just as it wouldfor a server per method implementation.

When the method is finished, however, the process under which it runsis sustained. Subsequent invocations of the method (or other methodsin the same program group) will run under the same process.

Daemon servers have three advantages compared to server per methodimplementations:

■ They use less overhead in cases that would otherwise requiremultiple processes.

Daemon Servers


Object Im

plementation

■ They allow you to re-use memory in cases where memory mustbe retained for the next method invocation.

■ They allow the use of multiple execution threads, which canfurther extend the former advantages.

Considerations for Daemon ServersAs you design and code daemon servers consider the following:

■ Daemon servers can introduce queuing delays.

■ Daemon servers can deadlock.

■ Shared daemon servers are shared by all objects on a host.

Queuing Delays

A method running under a single-threaded daemon servermonopolizes the process. This can cause unacceptable delays.Consider the following example:

Methods A and B compose program X, which is implemented as asingle-threaded daemon server. A client calls method A and waits forthe result. A second client calls method B and waits for a result.Method B cannot run until method A terminates, and the client thatcalled method B is now delayed. The server is ignorant to this delayand any others that might occur while it is busy. Obviously, thesedelays can become significant, especially if method A takes a longtime to run.

These kinds of delays are relatively simple to avoid with properplanning when you implement your methods and write your clientrequests.

Daemon Server Deadlocks

Daemon servers can create another problem called adeadlock, acondition in which two programs are each waiting for the other torespond before proceeding. Frequently, the only way to recover froma deadlock is to kill the involved processes.

Daemon Servers

5–18 Version 3.6

The kinds of deadlocks produced by poor method or client design havetwo potential causes:

■ Deadlocks caused by calling a method in the same daemon serverprocess

■ Deadlocks caused by two daemon servers calling each other

The next two sections discuss these kinds of deadlocks and how toavoid them.

Deadlocks in a Single Daemon Server Process

A deadlock will occur if a method invokes another method under bothof the following conditions:

■ Both methods are implemented in the same TEIDL program.

and

■ The TEIDL program in which they are implemented is specifiedas a single-threaded daemon server.

Consider the following example:

The two circles represent two methods—each implemented in thesame single-threaded (non-parallel) daemon server. Method A callsmethod B and waits for a result. Because both methods areimplemented in the same TEIDL daemon server, they both run underthe same daemon process.

Because the methods are single-threaded, method B cannot beginexecution until method A terminates; instead, it is queued in the BOA.Method A cannot terminate, however, until it receives a response from

Method A Method B

Single-threaded Daemon Server Process

Daemon Servers


Object Im

plementation

method B. In this scenario, the two methods are deadlocked becauseeach method is waiting for the other before continuing.

To prevent this kind of deadlock, avoid invoking methods within thesame single-threaded daemon server. Parallel daemon servers permitsuch method invocations if it is necessary. See “Parallel Servers” onpage 5-21 for more information about multi-threaded methods.

Deadlocks Among Daemon Servers

You must exercise similar care with single-threaded methods thatinvoke other methods implemented in separate daemon serverprocesses. Consider the following example:

Method A is running and invokes method X. Method X thenimmediately invokes method B. There are now two calls pending asshown in the following diagram:

Process 100 Process 200

Method A Method X

Method B

MethodA

MethodB

Process 100

MethodX

Process 200

Daemon Servers

5–20 Version 3.6

Because method A and method B are both single-threaded and rununder the same process, method B cannot run until method Aterminates. Method A, of course, cannot terminate until method Xterminates, and method X is waiting for method B. The three methodsare deadlocked.

The only way to avoid this type of deadlock is to exercise cautionwhen you cascade methods from a single-threaded daemon.Parallel daemon servers permit such cascading if it is necessary.

Object Contexts in Daemon Servers

If you specify a shared server, all objects that support the methodsimplemented by that server share the same process (as long as theseobjects are on the same host). Different invocations of a method in adaemon server process run in the context of different objects.

You should exercise caution when you use static variables in daemonservers. Such variables can pass old data pertaining to the objectcontext of a previous method invocation.

You should, therefore, manage object context data in either of thefollowing ways:

■ Pass object context sensitive data as a method argument, ratherthan the return value of these functions for objects running underthe same process.

■ Store data in an object-specific data structure, such as an indexeddata structure.

Managing object-context data in one of these prescribed way ensuresthat your method invocations receive the correct information for eachinvocation.

In many cases, sharing a daemon server process among objects is nota problem. However, there may be cases in which it is necessary toprevent this sharing.

Parallel Servers


Object Im

plementation

Parallel ServersWhen you execute a C program, it begins a thread of execution, whichends whenmain() returns. The execution thread represents thesequential execution of C program statements and it maintains the callchain as it calls nested subroutines.

Traditional C programs contain only this one thread. It is possible,however, to write a program containing multiple threads that executeconcurrently1. Concurrent execution of multiple threads is analogousto having severalmain() routines in a single program, each of whichis executed when the program begins.

All the threads within this type of parallel execution occur as part ofthe same process, and so they share all resources except the CPUinstruction pointer and stack. This includes global data.

Because concurrent execution threads share the same data, you mustcontrol access to that data. You do so by using a data variable called amutex.

The mutex variable can be in either a locked or unlocked state. If themutex is locked, it indicates some function is manipulating theassociated data. If it is unlocked, it indicates functions can access thedata safely. Mutexes can also help you to avoid the followingundesirable conditions:

■ A Race condition, which occurs when two or more threadsperform an operation and the result is dependent on the threadcompletion order. That is, the thread that completes its operationlast determines the result. See “Race Conditions” on page 5-24for more information about race conditions.

■ Thread deadlock, which occurs when the execution of one ormore threads is permanently blocked by an execution thread(either a separate thread or itself). See “Thread Deadlocks” onpage 5-24 for more information about thread deadlocks.

1. Without parallel CPUs thread execution will be staggered, muchlike processes in a time-sharing operating system.

Parallel Servers

5–22 Version 3.6

Advantages of Parallel Server ImplementationsParallel-server implementations can increase performance andconsume fewer system resources. This advantage is possible becauseparallel servers share resources and operate parallel to each other.The advantage is more applicable, however, to traditional computingenvironments than to the TME.

TME 10 method invocations are distributed operations. The overheadassociated with process creation is therefore distributed and thus smallcompared to traditional environments. TME 10 methods execute in aparallel fashion, because they can execute in separate processes onmultiple machines. Performance benefits for TME 10 parallel serversare therefore usually small.

There are, however, advantages associated with parallel servers otherthan the single advantage of improved performance:

■ Exploiting inherent parallelism—Some methods are inherentlyparallel and can be more simply structured using parallel servers.

■ Sharing data—Servers that share data can benefit from executingas separate threads rather than separate processes.

■ Reducing system resource usage—Multiple execution threadsuse fewer system resources than an equal number of individualprocesses.

■ Planning for Multiprocessor (MP) machines—MP machines canrun individual threads on different CPUs. Parallel serverimplementations can operate in a parallel fashion, which resultsin a significant performance improvement.

Disadvantages of Parallel Server ImplementationsAs indicated in the previous section, there are several advantagesassociated with parallel servers. Several disadvantages also exist:

■ Increased programming error probability—Programs that usemulti-threaded methods must be madethread-safe. Thisincreases the possibility of programming errors. See “ParallelServer Implementation” on page 5-26 for more informationabout multi-threaded programming techniques.

Parallel Servers


Object Im

plementation

■ Performance degradation—When you control data access, it canslow the execution of the process in which each of the threads areexecuting.

■ Security risks—Threads in the same process can access eachother’s memory.

■ No data barrier—Non-parallel servers use the process boundaryas a barrier that prevents other functions from accessing data.Parallel servers contain multiple execution threads within thesame process. Each thread can therefore write data that it shareswith other threads. If such a thread dies, the other threads thatshare that data will also die.

■ Debugging difficulties—Current debuggers do not understandthreads. There is therefore no easy way to view back-traces or setbreak points on threads other than the current one.

MutexesApplication developers are responsible for producing applications thatenforce the rules governing access to shared data. Mutexes canfacilitate this control by indicating whether specified data is in use.

A mutex is a data variable that provides applications with informationabout the status of data. When an execution thread attempts to accessshared data, it should first attempt to lock the mutex associated withthat data. If the mutex state is already locked, the thread should not beallowed to run until the mutex is unlocked, releasing the data.

A single mutex must exist for each piece of data, and all threads thataccess that data must use the assigned mutex to ensure thread safety.Each time an execution thread attempts to access data, it should firstlock the appropriate mutex before performing the operation. It shouldthen unlock the mutex after the operation is complete.

Parallel Servers

5–24 Version 3.6

Race ConditionsA race condition can occur among two or more threads. Consider thefollowing example:

A process comprising two execution thread—A andB—is running.Both threads executen = n + 1. A readsn first and increments it from3 to 4. WhileA is incrementingn, B also readsn, which is still 3, andincrements it to 4.A now writes the result ton, after whichB alsowrites the result ton andn retains the value of 4.

In this example, the programmer intended for each thread to incrementn sequentially first from 3 to 4 and then from 4 to 5. Instead, eachthread increased simultaneously from 3 to 4, which is incorrect.

Avoid race conditions by using a mutex for each resource. A mutex isa data variable that indicates that the data is in use. See “Mutexes” onpage 5-23 for more information about mutexes.

Thread DeadlocksA deadlock can occur among one or more threads. Consider thefollowing example:

A process comprising two threads—A andB—is running. ThreadAattempts an operation that requires it to first read resourcem and thenread resourcen. Simultaneous to this event, threadB attempts anoperation that requires it to first read resourcen and then read resourcem. In both cases a mutex is used to lock bothm andn.

In the given example threadsA andB can deadlock because threadAwill be unable to readn, which was locked by threadB. ThreadB,however, will be unable to readm, which was locked by threadA.Neither thread will be able to complete their assigned operation,because each is waiting on the other to unlock the required resource.

Avoid thread deadlocks by establishing a sequencing convention forlocking and unlocking mutexes. One possibility is to assign a sequencenumber to each mutex and then ensure all threads lock and unlockmutexes in the proper sequence. Another possibility is to provide asingle mutex for several pieces of related data, and then to lock theentire data set.

Parallel Servers


Object Im

plementation

Thread-safe Programming TechniquesPrograms that do not initially use multi-threaded methods might usemulti-threaded methods at a later time. The following programmingtechniques ensure that your program runs correctly withmulti-threaded methods:

■ Coordinate all references to global memory.

■ Use mutex locks around code that reads or writes shared data.This ensures that the data is not changed by one thread whileanother is running. You need to lock only that data shared amongmultiple threads.

■ Treat static data the same as global data.

Static data is actually scoped global data: there is only one copyto which all threads refer. In particular, never use static data asthe return value of a function.

■ Coordinate file descriptors.

All file descriptors (andFILE * ) are shared, thus unpredictablethings can happen when reading or writing the same filedescriptor from different threads (for example, two threadscalling printf at the same time). Using the TME 10 file I/Oservices will help you manage such events. Refer to theApplication Services Manual for information about TME 10 fileI/O.

■ Avoid library routines that are not thread-safe.

Routines such asstrtok(3) andctime(3) are not thread-safebecause they violate one or more of the previous rules. (strtok(3)keeps a pointer to the current string in a static variable.ctime(3)returns a pointer to a static buffer.) Routines such assprintf(3)are thread-safe since they operate only on user-supplied data.

If you must use a routine that is not thread-safe, you can protectyour program with a mutex. Use the mutex to allow only onethread to access the routine at any given time.

Parallel Servers

5–26 Version 3.6

■ Manually perform clean-up operations when each threadterminates.

When your UNIX programs exit, the operating system performsall its own clean-up operations. When a thread exits, suchclean-up operations must be performed by the program callingthe thread.

As each thread terminates, your program should perform thefollowing operations on the resources it owns:

• Free allocated memory

• Close opened files

• Unlock any locked resources

■ Use thelock() function with caution.

The lock() function is inadequate for controlling concurrentexecution among threads. Consider the use ofpthread_mutex_lock() instead. Refer to theApplicationServices Manual for more information about thelock() function.

Parallel Server ImplementationTME 10 methods require a pthreads-compatible library. The TME 10threads library is a subset of pthreads interfaces. The followingsections present TME 10 enhancements to the standard pthreadsprogramming environment described in POSIX standard910034ADraft 6.

Spawning New Threads

The following function prototype depicts the proper way to spawn anew thread:1 #include “pthreads.h”

2 int tmf_pthread_create(pthread_t *p,

3 pthread_attr_t attr,

4 pthread_startroutine_t coroutine,

5 pthread_addr_t arg);

Parallel Servers


Object Im

plementation

Available Semaphores

A rich set of semaphore operations is available. Conceptualinformation about semaphores is available in Operating SystemConcepts by Peterson and Silberschatz, Addison and Wesley 1983.

The following table describes the semaphores supported by the TME:

Available Timer Services

TME 10 ADE provides a general purpose timer service that uses thetimeout/untimeout interface familiar to UNIX kernel programmers.The TME 10 APIs to these services are thread safe and their use istherefore recommended.

Code Fragment Purpose

#include “sem.h”void PVinit(sema_t, int count);

Initialize a semaphore. Set count to zero for simplecounting semaphore. Set count to -1 for multipleproducer/consumer semaphore.

void PVdestroy(sema_t *s); Destroy a semaphore.

void P(sema_t *s); Wait for semaphore.

void V(sema_t *s); Signal semaphore.

bool_t Vtry(sema_t *s); Attempt to signal a semaphore. If lock cannot be acquiredit returns FALSE. TRUE is returned if signal issuccessful.

bool_t Ptry(sema_t *s); Attempts to get a semaphore. Does not block, returnsTRUE if semaphore is obtained, FALSE if not.

void *Pa(sema_t *s); Wait for semaphore with data.

bool_t Ptry(sema_t *s, void**data);

Attempt to get a semaphore with data. Does not block,returns TRUE if semaphore is obtained, FALSE if not.

int Va(sema_t *s, void *data); Signal a semaphore with data. The data will be returnedby the corresponding call toPa(). Data must be allocatedby malloc(3) as PVdestroy willfree(3) any items onqueue. Return -1 ifmalloc() fails, 0 otherwise.

Parallel Servers

5–28 Version 3.6

The following table depicts the available timer services:

Calling POSIX Signals

Rather than directly callingsignal(), a thread should call the followingfunction:

sigfunc_t thread_signal(int signo, sigfunc_t handler);

thread_signal() will arrange for the indicated handler to be called.SIGALRM should not be set. The timer services should be usedinstead. The appropriate thread will then be called.

POSIX Thread RoutinesThe following table presents the POSIX thread routines and indicateswhich of these are supported by TME 10 ADE:

Code Fragment Purpose

int timeout(void (*func)(), any_t arg, struct timeval*timer)

Call functionfunc() with argumentarg after the timer*timer haselapsed. The program returns an idwhich can be given tountimeout tocancel thetimeout.

int untimeout(int id) Cancel a previously set timeout.

int thread_sleep(int secs) sleep(3) replacement. Waits theindicated number of seconds beforereturning. Other threads can runin-between.

Routine ✓=supported

pthread_create 3

pthread_delay_np

pthread_detach 3

pthread_exit 3

Parallel Servers


Object Im

plementation

pthread_join 3

pthread_once 3

pthread_self 3

pthread_yield 3

pthread_attr_create 3

pthread_attr_delete 3

pthread_attr_getinheritsched

pthread_attr_getprio

pthread_attr_getsched

pthread_attr_getstacksize 3

pthread_attr_setintheritsched

pthread_attr_setprio

pthread_attr_setsched

pthread_attr_setstacksize 3

pthread_condattr_create 3

pthread_condattr_delete 3

pthread_mutexattr_create 3

pthread_mutexattr_delete 3

pthread_mutexattr_getkind_np

pthread_mutexattr_setkind_np

pthread_lock_global_np

pthread_mutex_destroy 3


Parallel Servers

5–30 Version 3.6

pthread_mutex_init 3

pthread_mutex_lock 3

pthread_mutex_trylock 3

pthread_mutex_unlock 3

pthread_unlock_global_np

pthread_cond_broadcast 3

pthread_cond_destroy 3

pthread_cond_init 3

pthread_cond_signal 3

pthread_cond_timedwait 3

pthread_cond_wait 3

pthread_get_expriation_np

pthread_getspecific 3

pthread_keycreate 3

pthread_setspecific 3

pthread_cancel

pthread_setasyncancel

pthread_setcancel

pthread_signal_to_cancel_np

pthread_testcancel

pthread_getprio

pthread_getscheduler


TME 10 Concurrence


Object Im

plementation

TME 10 ConcurrenceThe POSIX thread functions enable you to create and to managethreads. They do not, however, provide any of the context associatedwith the method that calls them. Client stub calls, for example, requirethis context.

All TEIDL methods run in the context of some object, and it is thecontext that enables them to make stub calls. Applications that createand mange threads using POSIX thread routines, cannot make clientstub calls, or perform any other task that requires method context.

TME 10 ADE therefore supports several routines that provide thecontext necessary for threads that are called by methods that run in theTME.

The following table summarizes the TME 10 thread managementfunctions:

pthread_setprio

pthread_setscheduler

pthread_cleanup_pop

pthread_cleanup_push

atfork

Routine Summary

tmf_timeout Schedules a function to be called at a specified time

tmf_untimeout Removes a scheduled time-out function

tmf_untimeout_free Removes a scheduled time-out function and provides adestructor function

tmf_untimeout_arg Removes the timer and data associated with a scheduledtime-out function


TME 10 Concurrence

5–32 Version 3.6

tmf_untimeout_arg_free Removes the timer and data associated with a scheduledtime-out function and provides a destructor function

tmf_thread_sleep Suspends the current thread for the number of secondsspecified

tmf_thread_delay Suspends the current thread for the period of timespecified

tmf_thread_create Creates a thread with the same method context as thecreating thread

tmf_thread_exit Exits a thread created bytmf_thread_create()

tmf_timers_rel2abs Converts relative time to absolute time

tmf_friendly_mutex_init Initializes a thread friendly mutex

tmf_friendly_mutex_destroy Releases any memory associated with a thread friendlymutex

tmf_friendly_mutex_trylock Tries to acquire a lock on a thread friendly mutex

tmf_friendly_condwait Causes a thread friendly mutex to wait until a conditionvariable is broadcast or signaled

tmf_PVinit Initializes a semaphore

tmf_P Waits on a semaphore until the semaphore count isgreater than or equal to zero

tmf_Ptry Determines whether the semaphore count is greater thanor equal to zero without blocking the current thread

tmf_V Signals a semaphore

tmf_Vtry Signals a semaphore without blocking the current threadfor any reason

tmf_Va Signals a message semaphore

tmf_Pa Waits on a semaphore until the counter is non-negative

Routine Summary

TME 10 Concurrence


Object Im

plementation

Managing multiple threads while retaining method context is only oneseveral issues that must be addressed when you provide distributedparallel servers. Another important issue is ensuring the consistency ofdata storage, which can become complex. The task is complex becausemultiple processes or multiple threads within a process canconcurrently modify the same data.

Your program must therefore ensure that multiple threads do notaccess data simultaneously. If your program ignores this possibility,serious errors can result.

The most commonly employed technique for addressing data integrityin concurrent multiple threads is to serialize data access. This can beaccomplished with locking mechanisms either in the program or in theunderlying subsystems.

tmf_Patry Checks a semaphore until the counter is non-negativewithout blocking

tmf_PVdestroy Frees memory associated with a semaphore

tmf_rwl_lockalloc Allocates memory for an exclusive or shared lock

tmf_rwl_lockinit Initializes a shared or exclusive lock allocated usingtmf_rwl_lockinit

tmf_rwl_lockfree Releases memory associated with a lock

tmf_rwl_readlock Attempts to acquire a shared read lock

tmf_rwl_try_readlock Attempts to acquire a shared read lock without blocking

tmf_rwl_writelock Attempts to acquire an exclusive write lock

tmf_rwl_try_writelock Attempts to acquire an exclusive write lock withoutblocking

tmf_rwl_unlock Releases a shared or exclusive lock

tmf_thread_signal Registers a handler for a signal

Routine Summary

TME 10 Concurrence

5–34 Version 3.6

TME 10 supports a variety of locking schemes, each with varyingcontrol over the method execution. This enables you to choose the bestlocking scheme for your application. Subsequent sections describewhich locking mechanisms the TME 10 supports and how to use them.

Protection DomainsIntegral to an understanding of concurrence management is theconcept ofprotection domains.A protection domain describes thebounds of an operation and the data that must be serialized or“protected” from other threads of execution. A thread of executionmay be a separate process (in the UNIX paradigm) or a separate threadin a single process (the POSIX pthreads paradigm). The TME 10supports both of these paradigms.

In many environments, using objects to gather data into a protectiondomain is adequate, but in TME 10 it is not adequate. This is becauseTME 10 objects provide coarse method control, and thus severalmethods can be simultaneously active for the same object on behalf ofdifferent administrators.

State and SerializationAll objects exhibit state. The object state is represented by attributesin the object database, which makes the state persistent. An object canalso exhibit multiple states, each of which might or might not bepersistent.

An example of persistent state might be entries in the /etc/hosts file.An example of non-persistent state might be the current list of “down”hosts. When a method changes any of these states, it must ensure thatit is the only method changing the state at that time.

The following example demonstrates the importance of serializingaccess to object state:

A husband and wife simultaneously go to two different branches of abank where they have a joint account. The husband withdraws $50from their account, which previously had a balance of $500.Simultaneously, the wife deposits $100 in the same account.

TME 10 Concurrence


Object Im

plementation

If the bank’s program does not manage the event sequence properly,the following scenario could have the undesirable result of in anincorrect balance:

1. The husband requests the balance on the account and is informedthat the balance is $500.00.

2. The wife simultaneously requests the balance of the account andis also informed that the balance is $500.00.

3. The husband withdraws $50.00 from the account which recordsthe new balance of $450.00.

4. Simultaneous to her husband’s withdrawal, the wife adds$100.00 to the account, which then records the new balance of$600.

The correct balance is $550.00, but the actual balance depends onwhich transaction is recorded last. If the wife’s transaction is recordedlast, the account balance is $600.00 and the bank loses $50.00. If thehusband’s transaction is recorded last, the account balance is $450.00and the couple loses $100.00.

In a distributed object system, the husband and wife represent twosystem administrators using withdrawal, deposit, and balance methodsfor the bank account object. To administrators, state of concern is thebalance of the account.

There are many possible implementations of such an object.The balance can be maintained in the object database or it can be insome other file or memory location. You might also choose to cachethis information in a server for performance reasons.

Instead of methods changing a common balance in an object database,you can provide functions for withdrawal, deposit, and balance. Thesefunctions can then change some global memory, such as a hash tableentry, which represents an account balance. If these functions arecalled from two different threads, your program must ensure theserialization of each request.

TME 10 Concurrence

5–36 Version 3.6

To ensure an accurate balance in the presented example, the code mustbe written to guarantee that steps 1 and 3 are performed before 2 and4 or that 2 and 4 are performed before 1 and 3. In this example, it doesnot matter which occurs first. To ensure the correct event sequence,TME 10 supports locking, which alters the scenario as follows:

1. The husband gets a lock for the account.

2. The wife attempts to get a lock for the account. Her husbandalready holds a lock for this account, and so she must wait.

3. The husband requests the account balance and is informed thatthe balance is $500.00.

4. The husband withdraws $50.00 leaving an account balance of$450.00.

5. The husband releases the lock for the account.

6. The wife receives the lock after waiting.

7. The wife requests the account balance and is informed that thebalance is $450.00.

8. The wife deposits $100.00 leaving a balance of $550.00.

9. The wife releases the lock for account.

Locking MechanismsThere are several locking mechanisms provided by the TME, whichare divided into two categories:critical section locks andtransactionduration locks.

A critical section lock is used by a program to protect access to datastructures and critical code sections within its address space. Theselocks are used by multi-threaded methods and programs to serializedata access and operations. This prevents the corruption of internalstate or mechanisms by multiple threads within the process.

The state that is being protected is frequently global in the processaddress space rather than the stack. Critical section locks are generallyheld for a very short time and are acquired and released by the samemethod.

TME 10 Concurrence


Object Im

plementation

Like critical section locks, transaction duration locks are used toserialize access to data and operations, but they differ in the followingway: transaction locks are held for the duration of the entiretransaction and across method and address space boundaries.The locks are not released until the transaction commits or aborts.An application uses transaction duration locks when trying to protectdata outside its address space (such as attributes in the object database)or to serialize a set of operations.

See theApplication Services Manual for more information about TME10 transactions.

Critical Section Locking

There are several types of critical section locks, each with distinctcharacteristics, which are presented in the following list:

■ Mutexes—The primary mechanism for protecting criticalregions in a process.

■ Friendly mutexes

■ Read-write locks

■ Semaphores

Mutexes

Mutexes are very simple mechanisms. Your program locks a mutex tostart a critical section and unlocks it to end the section so that otherthreads can enter the section. In C and C++, a mutex is a data structurethat the program allocates and initializes (using pthread functions) andthen locks and unlocks.

When one thread locks a mutex, no other thread can lock it. Mutexesare very simple and reasonably fast, and they are the basis for manyother locking mechanisms.

A thread that has locked a mutex cannot lock it a second time withoutunlocking it first. Doing so produces a deadlock condition. Anothercommon error that produces a deadlock is when two or more threadsare waiting on resources that are locked by other deadlocked threads.The following example illustrates a typical deadlock among threethreads:

TME 10 Concurrence

5–38 Version 3.6

1. Thread 1 locks mutex A.

2. Thread 2 locks mutex B.

3. Thread 3 locks mutex C.

4. Thread 1 attempts to lock mutex B, but is blocked because thread2 already owns a lock on mutex B.

5. Thread 2 attempts to lock mutex C, but is blocked because thread3 already owns a lock on mutex C.

6. Thread 3 attempts to lock mutex A, but is blocked because thread1 already owns a lock on mutex A.

In the presented scenario, thread 3 cannot release mutex C because itis waiting for mutex A, which is locked by thread 1. Thread 1 cannotrelease mutex A, because it is waiting for mutex B, which is locked bythread 2. A deadlock has occurred. You can avoid this condition byrequiring all the threads to lock the mutexes they need in the exactsame order.

Mutexes are created by defining apthread_mutex_t data structure inthe application memory. The mutex is initialized by calling thepthread_mutex_init() function and destroyed by callingpthread_mutex_destroy(). The mutex is locked by callingpthread_mutex_lock() and is unlocked by callingpthread_mutex_unlock(). See the pthreads manual pages fordescriptions of the mutex functions.

The following C code fragment depicts a typical example of using amutex to control data-access:1 pthread_mutex_t my_lock;

2

3 int mymain(void){

4 pthread_mutex_init(&my_lock);

5 do_work();

6 pthread_mutex_destroy(&my_lock);

7 return 0;

8 }

9

10 void thread_work(void) {

11 pthread_mutex_lock(&my_lock);

12 do_more_work();

TME 10 Concurrence


Object Im

plementation

13 pthread_mutex_unlock(&my_lock);

14 }

15

16 void do_work(void) {

17 int i;

18 pthread_t p[MAX_THREADS];

19 pthread_addr_t status;

20

21 for (i = 0; i < MAX_THREADS; i++) {

22 pthread_create(&p[i],

23 PTHREAD_ATTR_DEFAULT, thread_work, NULL);

24 }


26 pthread_join(&p[i], &status);

27 }

28 }

This example initializes a mutex (line 4) calls a functiondo_work()(line 5) that spawnsMAX_THREADS number of threads (lines 16through 19). Each thread callspthread_mutex_lock(), does somework, then callspthread_mutex_unlock() (lines 10 through 13).After all the threads are done, the mutex is destroyed (line 6). In thisexample, the functiondo_more_work() is the critical section of codethe mutex protects.

Friendly Mutexes

When you use mutexes, you must ensure that each thread does not lockthe same mutex more than once in the same thread because a deadlockwill result.

If you are writing a new program, you can enforce such assurances byusing good design techniques. If you are modifying an existingprogram to use concurrent multiple threads, such assurances becomedifficult to enforce. TME 10 therefore supports friendly mutexes.

Friendly mutexes are useful when you write functions that requirelocking mutexes to protect critical code sections that can be calledfrom many contexts. Such functions are quite common in modularcode.

TME 10 Concurrence

5–40 Version 3.6

Consider the following C code fragment, which uses friendly mutexesrather than pthread mutexes:1 friendly_mutex_t my_lock;

2

3 int

4 mymain(void)

5 {

6 tmf_friendly_mutex_init(&my_lock);

7 do_work();

8 do_more_work();

9 tmf_friendly_mutex_destroy(&my_lock);

10 return 0;

11 }

12

13 void

14 do_more_work(void)

15 {

16 tmf_friendly_mutex_lock(&my_lock);

17 do_even_more_work();

18 tmf_friendly_mutex_unlock(&my_lock);

19 }

20

21 void

22 thread_work(void)

23 {

24 tmf_friendly_mutex_lock(&my_lock);

25 do_more_work();

26 tmf_friendly_mutex_unlock(&my_lock);

27 }

28

29 void

30 do_work(void)

31 {

32 int i;



35



38 PTHREAD_ATTR_DEFAULT,

39 thread_work, NULL);

TME 10 Concurrence


Object Im

plementation

40 }



43 }

44 }

The example uses friendly mutexes because the functiondo_more_work() could be called bymymain() (line 8) andthread_work() (line 25). Thedo_more_work() function (lines 14through 19) protects its critical section with the same friendly mutexasthread_work() (lines 22 through 27). Themymain() function doesnot protect the critical section. In fact, it may not even know of itsexistence ifdo_more_work() was some kind of library function it wascalling.

Friendly mutexes maintain an internal counter that is used todetermine when to release the mutex so other threads may acquire it.This means that for everytmf_friendly_mutex_lock() call, there is acorrespondingtmf_friendly_mutex_unlock() call.

Read/Write Locks

Read/write locks provide the semantics of readers and writers whendetermining mutual exclusion rules. They are also referred to asshared/exclusive locks. Read/write locks allow multiple read lockholders but only a single write holder.

Read/write locks support more concurrent operations. This is becausethey enable multiple threads to view data (the predominant operation)in parallel while protecting them from threads that change the data.The following rules apply to read/write locks:

■ When a read lock is requested, the request will be granted undereither of the following conditions:

• There are no threads holding the lock in a specified mode(either read or write).

• There are only read locks held by other threads, and no otherthread is waiting for the lock in write mode.

TME 10 Concurrence

5–42 Version 3.6

■ When a write lock is requested, it will be granted if there are nothreads holding the lock in any mode (either read or write).

With these rules, writers can starve readers, but readers cannot starvewriters. In the common case where there are more readers than writers,this is not a problem. Consider the following example:

1. Thread 1 gets read lock A.

2. Thread 2 gets read lock A.

3. Thread 3 attempts to get write lock A but is blocked becausethreads 1 and 2 have read locks.

4. Thread 4 attempts to get read lock A but is blocked because awrite lock is pending.

5. Thread 1 unlocks A.

6. Thread 2 unlocks A. Thread 3 is notified and now owns a writelock on A.

7. Thread 3 unlocks A. Thread 4 is notified and now owns a readlock on A.

8. Thread 4 unlocks A.

In steps one and two, threads 1 and 2 are granted read locks becauseno thread has requested a write lock. In step 3, the write lock requestis queued because the read locks block any write lock requests.The read lock requested by thread 4 in step 4 is queued behind thewrite lock request.

Thread 3 is not granted a write lock until threads one and two releasetheir read locks. Thread 4 is not granted a read lock until thread 3 isgranted and then releases its write lock.

This scenario demonstrates the following principles:

■ Multiple read locks can be simultaneously granted to concurrentthreads.

■ Only one write lock can be granted at a time.

■ Write lock requests are queued if read or write locks are held byany thread when the request is made.

TME 10 Concurrence


Object Im

plementation

■ Read locks are queued if a write lock is requested before the readlock request.

The following C code fragment depicts an example read/write lock:1 rwl_lock_t my_lock;

2 int mymain(void){

3 tmf_rwl_lockinit(&my_lock);

4 do_work();

5 tmf_rwl_lockfree(&my_lock);

6 return 0;

7 }

8

9 void view_data(void){

10 tmf_rwl_readlock(&my_lock);

11 do_viewing_work();

12 tmf_rwl_unlock(&my_lock);

13 }

14

15 void update_data(void){

16 tmf_rwl_writelock(&my_lock);

17 do_update_work();

18 tmf_rwl_unlock(&my_lock);

19 }

20

21 void do_work(void){

22 int i;



25

26 for (i = 0; i < MAX_THREADS; i++){



29 (i & 1)? update_data : view_data, NULL);

30 }

31



34 }

35 }

TME 10 Concurrence

5–44 Version 3.6

The example first creates a read/write lock (lines 1 through 3). It thenspawns some threads (lines 26 through 27). Some of these threads arefor viewing data, and some are for updating data. The work routines(lines 9 through 19) acquire a read or write lock depending on whetherthe operation is viewing or changing the data.

Semaphores

TME 10 supports implementations of counting semaphores andmessage semaphores. Like mutexes, you can use semaphores toprovide mutual exclusion and protection, but their use is not limited tothese purposes. You can also use semaphores to provideproducer/consumer semantics.

Additionally, the TME 10 semaphore implementation can be used tosafely pass data between two or more threads and to synchronizemultiple threads.

Message Semaphores

Message semaphores can be used to transfer data or messages betweenmultiple threads in a safe manner. In most cases message semaphoresrequire two groups of threads:

■ One group called consumers that wait for data

■ One group called producers that send data or messages to otherthreads

Consumers call the wait functiontmf_Pa() to receive a message, andproducers calltmf_Va() to send a message to some consumer.

The following C code fragment depicts a typical message semaphore:1 static tmf_sema_t my_sem;

2 static int done;

3

4 int mymain(void){

5 tmf_PVinit(&my_sem, -1);

6 start_work();

7

8 /*

9 * Wait for messages.

10 */

11 do{

TME 10 Concurrence


Object Im

plementation

12 msg = (message_t *)tmf_Pa(&my_sem);

13 process_msg(msg);

14

15 }while (!done);

16 tmf_PVdestroy(&my_sem);

17 return 0;

18 }

19

20 void thread_work(void){

21 tmf_Va(&my_sem, make_some_msg());

22 }

23

24 void start_work(void){

25 int i;

26 pthread_t p;

27


29 pthread_create(&p,



32 pthread_detach(&p);

33 }

34 }

The example initializes a counting semaphore at a value of -1 (line 5).The counting semaphore waits to be signalled. It then calls a routinethat spawns several producer threads (lines 28 through 29).The fragment then waits for the messages provided by the producerthreads.

Mutual Exclusion Semaphores

Semaphores can be used to implement mutual exclusion much the waya mutex is used. Mutexes, however, are usually held for a very shorttime, whereas a semaphore can be used for a longer term exclusion.This is primarily due to the implementation details of mutexes andsemaphores.

Mutexes are frequently implemented using spin locks when they areused in an environment where multiple processors are available.The TME 10 semaphore implementation uses mutexes for a very smallcritical section when it manipulates the internal data of the semaphore.Because of the implementation, semaphores should be used when

TME 10 Concurrence

5–46 Version 3.6

protecting long running blocks of code, and mutexes should be usedwhen protecting smaller critical regions.

The length of time that constitutes a long running block of code issubjective. As a rule, however, protecting system calls that mightblock, are best protected using semaphores. This is because otherprocessors can be trapped in a spin loop as they wait for a mutex if theplatform supports a multiple processor implementation of hardwareand pthreads.

The following C code fragment depicts a typical mutual exclusionsemaphore:1 static tmf_sema_t my_sem;

2

3 int mymain(void){

4 tmf_PVinit(&my_sem, 0);

5 start_work();


7 return 0;

8 }

9


11 tmf_P(&my_sem);

12 do_lots_of_work();

13 tmf_V(&my_sem);

14 }

15

16 void start_work(void){

17 int i;



20





25 }



28 }

29 }

TME 10 Concurrence


Object Im

plementation

Synchronization Semaphores

Sometimes it is necessary for one thread to do something beforeanother thread can continue. Synchronization semaphores provide amechanism for one thread to signal another thread that it is ready orhas done the requested task. The following C code fragment presentsa typical synchronization semaphore:1 static tmf_sema_t my_sem;

2 int mymain(void){

3 pthread_t p;

4

5 tmf_PVinit(&my_sem, -1);

6 pthread_create(&p, PTHREAD_ATTR_DEFAULT,


8 pthread_detach(&p);

9 /*

10 * Wait for thread_work to be ready.

11 */

12 tmf_P(&my_sem);

13 printf(“thread_work has started\n”);

14 tmf_P(&my_sem);

15 printf(“thread_work is done\n”);


17 return 0;

18 }


20 do_some_work();

21 /*

22 * Tell mymain() we’ve started.

23 */

24 tmf_V(&my_sem);

25 do_rest_of_work();

26 /*

27 * Tell mymain() we’re done.

28 */

29 tmf_V(&my_sem);

30 }

TME 10 Concurrence

5–48 Version 3.6

Transaction Duration Locks

Transaction duration locks can be used to serialize data access andoperations for the duration of an entire transaction across method andaddress space boundaries. These locks are logically resident outsidethe method address space and are not released until the transactioncommits or aborts. If the method is not running within a transactioncontext (transaction type istrans_none), the lock is held until themethod completes.

TME 10 applications acquire transaction duration locks using apseudo-object provided when you run the TEIDL compiler.

Lock Name Space

Read and write locks are specified using a string that represents thelogical name of the lock instead of a data structure in the methodaddress space. The name space of a lock is scoped by the object inwhose context the calling method is running. The same lock nameacquired by two different objects are two different locks. Consider thefollowing example:

1. Methodfoo of objectA acquires a lock with namelock1 in writemode.

2. Methodfoo of objectB acquires a lock with namelock1 in writemode. This is a different lock than the one acquired by objectA.

3. Methodbar of objectA tries to acquirelock1 in write mode butis blocked because methodfoo still owns the lock.

The lock name space is controlled by the object implementation, andthe programmer defines the lock names and how to partition them.

Lock Duration

Transaction duration locks must be held until the top-level transactioncompletes or until some parent transaction aborts. This guaranteesconsistency of the operation.

Changes made by a transaction should not be made visible to othernon-related transactions. This is because sometimes a transactionaborts after changing only a portion of the data, in which case the datais returned to the original value. If a non-related transaction is aware

TME 10 Concurrence


Object Im

plementation

of those changes before the abort, it then has incorrect data. Considerthe following example:

Methodchange_phone calls two methods:get_employee_info andchange_employee_info. Theget_employee_info method acquires aread lock on the employee information and returns that information.Thechange_employee_info method acquires a write lock on theinformation and then changes it to reflect new data. Another method,change_pay, also callsget_employee_info andchange_employee_info to update the employee’s pay rate.

Serious problems can result in this example if the locking durationdoes not coincide with the completion of the top-level transaction asillustrated by the following scenario:

1. change_phone callsget_employee_info, gets a read lock, andreturns data.

2. change_phone callschange_employee_info, gets a write lock,and changes data.

3. change_pay callsget_employee_info and gets read lock, andreturns data.

4. change_pay callschange_employee_info, gets write lock, andchanges data.

5. change_pay completes successfully.

6. change_phone aborts due to some error (perhaps a core file).

In this example, the changes made bychange_pay are undone whenthe abortedchange_phone undoes its changes to the employeeinformation. This problem can be resolved by changing the rules sothat the locks are held until the transaction completes or aborts.The following scenario illustrates these changes:

1. change_phone callsget_employee_info, gets a read lock, andreturns data.

2. change_phone callschange_employee_info, gets a write lock,and changes data.

3. change_pay callsget_employee_info, attempts to get a readlock but is blocked becausechange_phone owns the lock.

TME 10 Concurrence

5–50 Version 3.6

4. change_phone aborts due to some error (perhaps a core file).Its changes are backed out and the locks are released.

5. change_pay is notified after acquiring its read lock and returnsthe data.

6. change_pay callschange_employee_info, gets a write lock, andchanges data.

7. change_pay completes successfully.

In this scenario, the locks keepchange_pay from altering the datawhile change_phone is doing the same. Whenchange_phone aborts(or if it had completed successfully),change_pay is allowed to makeits changes to the employee record.

Lock Rules

The employee example illustrates why the locks must be held until theentire transaction commits or aborts. It did, however, omit animportant detail: how locking primitives decide when to grant a lockrequest. The semantics must be changed to support the notion ofmultiple possession. This means that multiple methods can hold thesame write lock if they have the appropriate relationship within atransaction context.

You can think of multiple possession semantics as a lock held by asub-transaction until it commits or aborts. If it aborts, the lock isreleased and any waiting transactions acquire it. If the sub-transactionis committed, the parent transaction inherits any locks held by thatsub-transaction.

When a method requests a lock, a lock that is held by an ancestortransaction may be granted to the method if the following conditionsapply:

■ A sibling transaction does not hold the lock.

■ A method outside the transaction hierarchy does not hold thelock.

A lock can be provided if the only other methods holding the lock areancestor transactions of the requesting method.

TME 10 Concurrence


Object Im

plementation

Deadlocks and AvoidanceNeither mutexes nor transaction duration locks provide any deadlockdetection mechanisms. Protocols to detect deadlocks are complicatedand potentially expensive when they are distributed over a network.

Friendly mutexes can be used for the most common deadlock case(a mutex already locked by the calling thread) for locks acquired in thelocal address space.

Transaction duration locks are similar to friendly mutexes becausethey do not deadlock if they attempt to lock data that is already locked.Transaction duration locks are different than friendly mutexes becausethey are associated with the entire transaction rather than a specificthread.

Avoidance and Transaction Duration Locks

There are several ways to avoid deadlocks among transaction durationlocks. One technique is to use time-outs when making calls to thelock() method for the transaction object. If thelock() method timesout, the method can abort, which frees all of its locks and allows othermethods to acquire the lock. This is not always the desired solutionbecause it can cause spontaneous aborts.

Another solution is to create locking hierarchies. In the earlierexample, bothchange_phone andchange_pay know they areupdating shared information. Instead of leaving the lock acquisition toget_employee_info andchange_employee_info, they could acquiretheir own write lock for the employee information.

Whenget_employee_info attempts to get the read lock, it is grantedbecause its parent,change_phone owns a write lock for theinformation.change_employee_info also inherits the write lock fromchange_phone, so it can also acquire a read lock.

If change_pay attempts to get the write lock whilechange_phoneowns the write lock, the request is denied. If such a locking sequenceis used, there is no chance for consistency errors or dead-locks. Anexample of a lock hierarchy is provided in the following C codefragment:

TME 10 Concurrence

5–52 Version 3.6

1 transaction example_trans;

2

3 Employee_t get_employee_info(char *ename){

4 Employee_t info;

5 Environment ev;

6 transaction_lock(example_trans, &ev, EMP_LOCK,

7 lock_read, -1);

8 db_lookup(ename, &info); /*find emp in db */

9 return emp;

10 }

11

12 void change_employee_info(char *ename,

13 Employee_t info){

14 Environment ev;


16 lock_write, -1);

17 db_write(ename, &info);

18 }

19

20 void change_pay(char *ename, int new_pay){

21 Employee_t info;

22 Environment ev;


24 lock_write, -1);

25 info = get_employee_info(ename);

26 info.pay = new_pay;

27 change_employee_info(ename, &info);

28 }

29

30 void change_phone(char *ename, char *new_phone){

31 Environment ev;


33 lock_write, -1);

34 info = get_employee_info(ename);

35 info.phone = new_phone;

36 change_employee_info(ename, &info);

37 }

Other scenarios for protecting access to data may require othersolutions. One common serialization scheme follows:

TME 10 Concurrence


Object Im

plementation

■ When changing an item in a list use the following lockingscheme:

• Place a read lock on the list.

• Place a write lock on the item to be changed.

■ When adding or deleting an item on a list, place a write lock onthe list.

Such a locking scheme provides fine rather than course concurrencecontrol.

Avoidance and Critical Section Locks

Deadlocks that occur within a method address space usually occurbecause of poor design or because already existing code is beingretrofitted to a multiple thread environment. Such problems typicallysurface when a thread attempts to lock a mutex it has already locked.

The following code depicts such a deadlock:1 static pthread_mutex_t my_mutex;

2

3 int

4 mymain(void)

5 {

6 pthread_mutex_init(&my_mutex, 0);

7 some_work();

8 some_more_work();

9 pthread_mutex_destroy(&my_mutex);

10 return 0;

11 }

12

13 void

14 some_more_work(void)

15 {

16 pthread_mutex_lock(&my_mutex);

17 if (do_increment)

18 count++;

19 pthread_mutex_unlock(&my_mutex);

20 }

21

22 void

23 some_work(void)

TME 10 Concurrence

5–54 Version 3.6

24 {


26 do_increment = TRUE;

27 some_more_work();

28 do_increment = FALSE;


30 }

The example deadlocks because the code insome_more_work()(lines 14 through 20) can be called by functions that do not lock themutex or by functions that have already done so. The code should bechanged to either use friendly locks or as depicted in the followingexample:1 static pthread_mutex_t my_mutex;

2

3 int mymain(void){

4 pthread_mutex_init(&my_mutex, 0);

5 some_work();

6 some_more_work();

7 pthread_mutex_destroy(&my_mutex);

8 return 0;

9 }

10

11 void some_more_work_locked(void) {

12 if (do_increment)

13 count++;

14 }

15

16 void some_more_work(void){

17 pthread_mutex_lock(&mymutex);

18 some_more_work_locked();


20 }

21

22 void some_word(void) {


24 do_increment = TRUE;

25 some_more_work_locked();

26 do_increment = FALSE;


28 }

A Final Word about TME 10 Class Systems


Object Im

plementation

Another solution is to remove the calls topthread_mutex_lock() andpthread_mutex_unlock() in thesome_more_work() function. If youdo, you should also add them tomymain() around the call tosome_more_work().

None of the locking APIs that use mutexes, friendly mutexes,semaphores, and read/write locks help when more complex deadlocksoccur. The only solution to such deadlocks is to correct the design andcode.

You should also consider defining locking hierarchies similar to theapproach taken by transaction duration locks. Each section of codemust acquire locks in the same order to guarantee deadlocks do notoccur.

Critical section locks do not provide time-out facilities like thoseavailable with transaction duration locks, although they can beimplemented using pthread primitives. TME 10 semaphores, pthreads,and read/write locks all provide a mechanism to try or test a lock. Noneprovide a time-out (the time-out is always immediate).

More complex schemes can be implemented using the pthreadprimitives. You can build locks that detect deadlocks and throwexceptions if necessary. To do so requires a lot of bookkeeping andoverhead for a case that seldom occurs in a well designed application.Such implementations are beyond the scope of this document.

A Final Word about TME 10 Class SystemsThe text in this chapter might lead you to the conclusion that youshould spend a significant amount of time designing an elaborate classsystem for each application or suite of applications. Although suchsystems can be produced using TME 10 ADE, it is seldom necessary.

In most cases you can design your application around existing TME 10classes. In other cases you can extend existing TME 10 classes ratherthan creating new classes.

Using the existing class hierarchy will in most cases reduce the timerequired to develop your applications, and ensure better reliability andperformance.

A Final Word about TME 10 Class Systems

5–56 Version 3.6


TM

E 10 C

lients and theT

ME

10 Run-tim

e

6TME 10 Clients and the TME 10Run-time

Previously presented information focuses on TME 10 objectimplementations and the environment in which they reside.This chapter presents information about clients and their behavior.It explains the following topics:

■ TME 10 Service Requests

■ CORBA Memory Management

■ Available APIs

You should read this chapter before implementing TME 10 clientsbecause it provides important information about their behavior.

TME 10 Service RequestsIn a CORBA-compliant common ORB system, TME 10 clients caninitiate requests using the following facilities:

■ Client stubs

■ Dynamic invocation interface

■ Command line interface

This section describes how to use these interfaces. TME 10 directlysupports only the C programming language and Bourne shell script atthis time. The example code fragments in this section are therefore

6

TME 10 Service Requests

6–2 Version 3.6

presented as C source code. Applications can be written in anylanguage, however, for which C linkage is supported.

Client StubsClients pass information to the ORB using client stubs. Client stubscan be called from either a C program or a shell script, although thecall technique is different for each type of program.

Calling a Client Stub from a C Program

Client requests in C programs are identical in form to C function calls.Client stubs are, in fact, functions that contain the code necessary topass requests to the ORB for delivery to the appropriate serverskeleton. You must equip each client request with at least one inputparameter and at least one output parameter:

■ Object reference—The first parameter to each operation must bethe object reference that identifies the object that provides theservice requested by the operation. This parameter is an inputparameter.

■ Environment—The second parameter to each operation must bean (Environment * ) parameter. This output parameter facilitatesthe return of an exception. See “IDL Exception Declaration” onpage 3-14 for more information about exceptions.

The following code fragment depicts a typical client request:1 companyDBRef = ORB_string_to_object(tmf_locate_orb(),

2 &ev, argv[1]);

3

4 /* Do a query */

5 headqtr = companyDB_query(companyDBRef, &ev, name, &i);

Lines 1 and 2 retrieve the value of the string contained in argv[1] andassign it to the variablecompanyDBRef. Lines 4 and 5 then initiate arequest of thecompanyDB_query stub.

The first parameter in the request is anin parameter(companyDBRef), which contains the value of the object reference.All CORBA-compatible client requests pass an object reference as thefirst parameter in the operation signature.



TM

E 10 C

lients and theT

ME

10 Run-tim

e

The remainder of the parameters are determined by the interfacedefined in the interface definition file.

Calling a Client Stub from a Shell Script

The technique for initiating client requests from a shell script isslightly different than initiating requests from a C programs. Instead ofgetting the object id from theargv list, the script should contain it in astring in a shell variable.

The following script passes aname environment variable to a queryoperation and receives an info structure and a city name as results.1 results=ìdlcall $company companyDB::query '"$name"'`

2 info=ìdlarg 1 "$results"`

3 echo "info.phone is" ìdlarg 1 "$info"`

4 echo "info.zipcode is" ìdlarg 2 "$info"`

5 echo "city is" ìdlarg 2 "$results"`

Dynamic Invocation InterfaceAs a developer, you might occasionally encounter applicationrequirements to provide a service that cannot be fully defined untilrun-time. An example of such an application is one that initiates arequest on behalf of another client, such as a scheduler.

In such cases, you cannot predict the API requirements until run-time,and you must therefore initiate the request dynamically. There is noway, however, to link with a client stub ahead of time. The TME 10ORB supports a Dynamic Invocation Interface (DII) that dynamicallyconstructs requests for you.

The TME 10 DII comprises two sets of operations: those specified byCORBA, and TME 10 extensions to the CORBA-specified operations.The following table briefly summarizes each of the CORBA DIIoperations:

Operation Summary

Request_invoke Calls the ORB, which then invokes the appropriate method

Request_delete Deletes a request invoked; any memory associated with therequest is also released


6–4 Version 3.6

See the CORBA specification for more information about these DIIfunctions.

These request interfaces are also known aspseudo-objects.A pseudo-object is a service that does not require an object. Requestpseudo-objects are created using an operation from the CORBA objectinterface:Object_create_request(). See “Pseudo-object Interfaces”on page 6-18 for more information about pseudo-objects. See “ObjectInterface” on page 6-16 for the signature ofObject_create_request().

Given an object reference, this operation creates an ORB request.The actual invocation occurs by callingRequest_invoke orRequest_send. Many of the CORBA-specified DII functions accept aset of request flags. The TME 10 ORB supports one flag in addition tothe those specified by the CORBA:

NO_ARGUMENT_CHECK —This flag indicates that the argumentsshould not be checked against the interface repository as they areadded to a request.

Request_add_arg Incrementally adds arguments to a request

Request_send Calls the ORB, which then invokes the appropriate method;unlikeRequest_invoke, control is immediately returned tothe caller

Request_get_response Determines whether a request has completed

send_multiple_requests Initiates more than one request in parallel

get_next_response Returns the next response that completes

NVList_add_item Adds a new item to the specified list

NVList_free Releases the list structure and any associated memory

NVList_free_memory Releases any dynamically allocated out-arg memory

NVList_get_count Returns the total number of items allocated for this list

Operation Summary



TM

E 10 C

lients and theT

ME

10 Run-tim

e

For each of the operations listed in the previous table, there is a TME10 version that supports TME 10 exceptions and transactions:

■ t_Request_invoke

■ t_request_batch_invoke

■ t_Request_delete

■ t_Request_add_arg

■ t_Request_send

■ t_Request_get_response

■ t_send_multiple_requests

■ t_get_next_response

■ t_NVList_add_item

■ t_NVList_free

■ t_NVList_free_memory

■ t_NVList_get_count

Extended DII

Tivoli has also extended the CORBA-specified DII by addingsupplemental operations:

■ tmf_req_create—This operation takes avarargs list ofparameters and builds a CORBA request pseudo-object suitablefor invoking or serializing.

■ tmf_req_invoke—This operation invokes an operation using theDII instead of the compiler-generated stub: it is essentially acommon stub call. The function takes avarargs list ofparameters and performs the following tasks:

• Builds a request pseudo-object

• Invokes the newly built request

• Frees the request and the internally used memory


6–6 Version 3.6

The operation takes the following arguments:

• The target object

• ev (an environment structure)

• The operation name

• Triplet of parameters representing each operation argument.

The parameter triplet consists of a mode flag (ARG_IN ,ARG_OUT, ARG_INOUT , ARG_RESULT), aTypeCode, anda pointer to the argument. After the last argument description,enterARG_NULL to terminate the list.

■ tmf_req_batch_invoke—This operation is similar totmf_req_invoke. Rather than a single target object, however, theoperation takes anObjectList of targets. The request is issued toeach of the targets in batch mode.

Results can be retrieved usingget_next_response. A new copyof the original request is returned after each call toget_next_response, with the results of the call to one target.

■ tmf_req_serialize—This operation takes a requestpseudo-object and serializes it into an octet sequence. Thissequence may be passed across process and machine boundaries.

■ tmf_req_unserialize—This operation takes an octet sequenceand re-creates a request pseudo-object. There are four differencesbetween a restored request and the original:

• Any arguments that were passed by address will be acopy ofthe original.

• Any out arguments or method results will have new memoryallocated for the argument.

• When the request is initiated, the ORB allocates memory tohold the method-generated data and stores the pointer in thearguments allocated bytmf_unserialize_request.

• The original argument memory provided by the builder of therequest will not be used.

These extended DII operations are similar to those specified byCORBA: they do not support TME 10 exceptions or transactions.



TM

E 10 C

lients and theT

ME

10 Run-tim

e

For each of these operations, there is a TME 10 version that supportsTME 10 exceptions and transactions:

■ req_create

■ req_invoke

■ req_batch_invoke

■ req_serialize

■ req_unserialize

Refer to the individual manual pages for more information about theseoperations.

The following code fragment depicts two typical dynamic clientrequests using the TME 10 dynamic invocation operations:1 /*

2 *Invoke an operation using the DII instead of the

3 *compiler-generated stub. Arguments are target-object,

4 *ev, operation-name, followed by a triplet of

5 *parameters representing each operation argument. The

6 *triplet consists of a mode flag (ARG_IN, ARG_OUT,

7 *ARG_INOUT, ARG_RESULT), a TypeCode, and a pointer to

8 *the argument.

9 *After the last argument description, enter ARG_NULL

10 *to terminate the list.

11 */

12 Object target; char *newlabel="testlabel";

13 tmf_boolean silent=FALSE;

14 ...

15 tmf_req_invoke(target, ev, "set_label",

16 ARG_IN, TC_string, &newlabel,

17 ARG_IN, TC_boolean, &silent,

18 ARG_NULL);

19

20 if (ev->_major != NO_EXCEPTION) {

21 printf("request_invoke failure, ex=%s\n",

22 exception_id(ev));

23 return(1);

24 }

25

26 /*

27 *Create a Request pseudo-object, serialize it, pass it


6–8 Version 3.6

28 *to another process, and invoke it from there.

29 */

30

31 Request request;

32 char *result;

33 OctetList ol;

34 ORBStatus status;

35 request = tmf_req_create(target, ev, "get_label",

36 ARG_RESULT, TC_string, &result,

37 ARG_NULL);

38


40 printf("create_request failure, ex=%s\n",


42 return(1);

43 }

44

45 /*

46 *Now pass the created Request to potentially

47 *different process

48 */

49

50 ol = tmf_req_serialize(request, ev);


52 printf("serialize_request failure, ex=%s\n",


54 return(1);

55 }

56

... potentially in another process ...57

58 request = tmf_req_unserialize(ev, &ol);

59


61 printf("unserialize_request failure, ex=%s\n",


63 return(1);

64 }

65

66 /*

67 * issue request



TM

E 10 C

lients and theT

ME

10 Run-tim

e

68 */

69

70 status = Request_invoke(request, ev, 0);

71 if ( status || (ev->_major != NO_EXCEPTION) ) {

72 printf("Request_invoke failure, ex=%s\n",


74 return(1);

75 }

76

77 /*

78 *Note that we must get the result from the Request, not

79 *the 'result' variable. The original result argument

80 *passed to tmf_create_request was not used,

81 *because of the serialize/unserialize operations.

82 */

83

84 printf("get_label_old result = %s\n", *(char**)

85 request->result->argument._value);

86 status = Request_delete(request, ev);


88 printf("Request_delete failure, ex=%s\n",


90 return(1);

91 }

Command Line InterfaceTME 10 supports two Command Line Interface (CLI) calls forcommon ORB applications:idlcall andidlattr .

idlcall

TME 10 supports a single call program for initiating requests from theCLI: idlcall . This program uses ASCII to represent IDL types.The signature foridlcall follows:

idlcall [ -T transtype] target_object scoped_operation_id [in/inout args ]

The optionaltranstype argument is a transaction specification, whichcan have one of the following values:

■ top—Top-level transaction


6–10 Version 3.6

■ sub—Sub-transaction

■ revoke—A revocable transaction

■ none—No transaction

The target_objectargument is the object reference—represented as astring—of the target object. It is followed by the fully scopedoperation name, which is typically a double colon separated string(a string consisting of several smaller strings separated by the scoperesolution operator).

The last component of the operation id is the IDL operation name orthe IDL attribute name prefixed with_get_ or _set_.

Note: The ASCII argument list should always be enclosed betweena pair of single quotes.

The arguments are listed in the same order as in the IDL signature.The idlcall program writes theout or inout arguments and the result,if any, tostdout in ASCII. If the invocation results in an exception, theexception will be written tostdout.

The idlcall program exits with a non-zero status if the invocationresults in an exception (either in dispatching the call or raised by themethod implementation) and with 0 otherwise. The exit status may beused to interpret the ASCII output.

Examples of idlcall1 idlcall -T top 2001.1.1 shell_ex::test::op

2 ‘{ { shell_ex::u } { red 3001.1.1 } } { { long } 100 }’

3

4 idlcall -T top 2001.1.1 shell_ex::test::_set_attr

5 ‘{ red 3001.1.1 }’

6

7 idlcall 2001.1.1 shell_ex::test::_get_attr

For more information about constructing parameters withidlcall see“Bourne Shell Binding” on page 4-75.

CORBA Memory Management


TM

E 10 C

lients and theT

ME

10 Run-tim

e

idlattr

Useidlattr as a command line program to retrieve or setimplementation attributes. The signature foridlattr follows:

idlattr -t [ -s | -g ] target_object { attr_nametype_name [ value (if -s) ] }+

The -t option indicates that the argument list will contain the typename of the attribute. The-s and-g options specify a get or a setoperation respectively. If neither is specified, the command default iss.

Theattr_name attribute is the unscoped attribute name as in thecorresponding implementation construct. Thetype_name attribute isthe fully scoped type of the attribute.

If the operation is set, the next parameter is the desired ASCII value ofthe attribute. The value should always be enclosed between a pair ofsingle or double quotes. Any number of pairs of <attr_nametype_name>for a get operation, or triplets of <attr_name type_namevalue> for a set operation can be specified.

CORBA Memory ManagementA primary concern of clients in a common ORB environment ismemory management. Depending on the nature of the request,memory can be allocated and released by either the client or the ORB.The client must be aware of which conditions dictate the allocation andrelease of memory by the ORB, or risk the following problems:

■ Memory leaks

■ Memory corruption

■ Segmentation errors.

Integral to this awareness is the understanding of IDL-specifiedsignatures. IDL signatures contain three components: the operationname, the parameters, and a return result.

The operation name identifies the operation. The parameters areclassified asin, out, or inout. Thein parameters are those the clientpasses to the ORB with the request. Theout parameters are those

Available APIs

6–12 Version 3.6

passed back to the client.inout parameters allow the client to passinformation to the ORB and also allow the object implementation topass information back to the client.

Return results are similar in concept toout parameters, because bothreturn information to the client. The difference is in the way theinformation is returned. In the case of anout parameter, theinformation is written to an address provided by the client. In the caseof a return result, the ORB places the return data on the client stack.

See theApplication Services Manual for details about managingmemory in your application.

Available APIsTME 10 ADE supports a large number of APIs to simplify clientdevelopment. This section presents the APIs available forcommunication between clients and object implementations on theTME 10 framework.

TME 10 Run-time FunctionsWhen clients initiate requests, they must sometimes directlycommunicate with the ORB so that it can prepare for the request. Forexample, the ORB must initialize client stubs before they are called thefirst time.

TME 10 ADE provides several functions in the run-time library forthis purpose. Subsequent sections describe these functions.

tmf_init_t tmf_init(type_repository *types[]);

The tmf_init() function initializes the run-time application, and mustbe called before the application calls any client stub. The TEIDLcompiler provides this for you in your method template. See “TEIDLCompiler Output” on page 4-55 for information on method templates.

The parameter totmf_init() is an array of pointers totype_repository.By calling tmf_init() , the application and the object implementationdeclare to the ORB its intent to use any type defined in any of therepositories specified in the array.

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

The return value,tmf_init_t , is a structure that contains objectreferences for the BOA and the ORB as shown in the following codefragment:1 typedef struct{

2 Object_orb;

3 Object_boa;

4 } tmf_init_t;

This function should be called once for each process before creatingany execution threads.

int tmf_client_init(void);

A client program registers itself by calling this function, whichinitializes the client program. If the client is running in the context ofa method, any object invocations it issues are made on behalf of theobject. If it fails to register itself, all requests will fail. Thetmf_client_init() functions can also be called when the program is notrunning in the context of a method.

The function returns0 on success, and-1 if an internal error occurs.

void tmf_client_exit(void);

This function causes the client to exit, and it is useful when the last callin a client process is a one-way call. The function ensures that the callis complete before exiting.

This function takes no arguments and returns no results.

int tmf_run(struct timeval *tv);

This function starts the dispatch loop for method servers. The functionmanages method invocation requests. If a request does not arrivewithin the time specified bytimeval, the method server should exit,andtmf_run() returns. If NULL is specified, the server does not timeout, andtmf_run() returns only if there is a communication or systemerror.

void tmf_server_exit(void);

This function can be called by a method to stop the method dispatchcode from dispatching any more methods in this process. If the server

Available APIs

6–14 Version 3.6

is started by an external source,tmf_run() will return aftertmf_server_exit() is called and the method completes. If the serverprocess is started by the TME 10 ORB, the server exits after the lastthread in the process completes.

This function takes no arguments and returns no results.

Object tmf_locate_orb();

This function returns the ORB pseudo-object created bytmf_init() .

Object tmf_locate_boa();

This function returns a reference to the BOA pseudo-object created bytmf_init() .

char *exception_id(Environment *ev);

This function returns a pointer to the character string identifying theexception. If invoked on an environment that defines a non-exception(_major==NO_EXCEPTION ), aNULL is returned.

void *exception_value(Environment *ev);

This function returns a pointer to the structure corresponding to thevalue of this exception. If invoked on an environment that identifies anon-exception or an exception for which there is no associatedinformation, a NULL is returned.

void exception_free(Environment *ev);

This function releases any storage that was allocated in theconstruction of the environment. It is permissible to invokeexception_free() regardless of the value of the_major field.

Run-time Exceptions

The following CORBA-defined run-time exceptions are available:

■ StExcep_UNKNOWN

■ StExcep_BAD_PARAM

■ StExcep_NO_MEMORY

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

■ StExcep_IMP_LIMIT

■ StExcep_COMM_FAILURE

■ StExcep_INV_OBJREF

■ StExcep_NO_PERMISSION

■ StExcep_INTERNAL

■ StExcep_MARSHAL

■ StExcep_INITIALIZE

■ StExcep_NO_IMPLEMENT

■ StExcep_BAD_TYPECODE

■ StExcep_BAD_OPERATION

■ StExcep_NO_RESOURCES

■ StExcep_NO_RESPONSE

■ StExcep_PERSIST_STORE

■ StExcep_BAD_INV_ORDER

■ StExcep_TRANSIENT

■ StExcep_FREE_MEM

■ StExcep_INV_IDENT

■ StExcep_INV_FLAG

■ StExcep_INTF_REPOS

■ StExcep_CONTEXT

■ StExcep_OBJ_ADAPTOR

■ StExcep_DATA_CONVERSION

Refer to the individual manual pages entries for information abouteach exception.

Available APIs

6–16 Version 3.6

Object InterfaceBecause object references are opaque, it is not possible for clients orobject implementations to allocate storage for them. Five operationsare therefore provided to help you manage the memory allocated forobject reference:

Object Object_duplicate(Object o, Environment *ev);

Given an object reference, this operation creates a duplicate objectreference. The object implementation associated with the objectreference does not distinguish among the original reference or anyduplicates.

void Object_release(Object o, Environment *ev)

Given an object reference, this operation releases the memoryallocated for it.

Unsigned char Object_is_nil (Object o, Environment *ev)

Given an object reference, this operation discovers whether an objectassociated with the reference exists.

InterfaceDef Object_get_interface (Object o, Environment *ev)

Given an object reference, this operation returns an object from theinterface repository.

ImplementationDef Object_get_implementation (Object o, Environment *ev)

Given an object reference, this operation returns an object from theimplementation repository.

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

ORBStatus Object_create_request (Object o, Environment *ev)

Given an object reference, this operation creates an ORB request. Theactual invocation occurs by callingRequest_invoke orRequest_send.

Refer to the individual manual pages for more information about eachObject API.

For each of these operations there is a Tivoli version that supportsTME 10 exceptions:

■ t_Object_duplicate

■ t_Object_release

■ t_Object_is_nil

■ t_Object_get_interface

■ t_Object_get_implementation

■ t_Object_create_request

The signature for each of these operations is identical to the CORBAversion. In addition to these operations, TME 10 supports fouradditional operations:

tmf_boolean Object_is_equal (Object obj1, Environment *env, Object object);

Given two object references, this operation compares the references todetermine whether they refer to the same object.

tmf_boolean t_Object_is_equal (Object obj1, Environment *env, Object object);

Given two object references, this operation compares the references todetermine whether they refer to the same object. UnlikeObject_is_equal(), this operation can throw an exception.

Available APIs

6–18 Version 3.6

tmf_boolean Object_isa (Object _ob, Environment *_ev, TypeCode intf);

Given an object reference and an interface, this operation determineswhether the object supports the interface.

tmf_boolean t_Object_isa (Object _ob, Environment *_ev, TypeCode intf);

Given an object reference and an interface, this operation determineswhether the object supports the interface. UnlikeObject_isa(), thisoperation can throw an exception.

Pseudo-object InterfacesWhen a client initiates a request, the ORB delivers the request to aserver skeleton and the BOA invokes the specified method (service) inthe context of the specified object. It is possible, however, to providea service without an object. The providers of such services are calledpseudo-objects.

Pseudo-objects do not exist as instances of a class and they have noattributes. Furthermore, pseudo-objects are not accessible using theDII. Conceptually, a pseudo-object represents an objectless class. Inreality, it is nothing more than a suite of services.

TME 10 ADE provides the following CORBA pseudo-objectinterfaces:

■ ORB

■ BOA

■ TypeCode

Subsequent sections describe the operations available for theseinterfaces.

ORB

Because object references are opaque, you cannot persistently storethem. This means each time you want to perform some service youmust first request the object reference. The ORB therefore providestwo operations that allow you to persistently store the object reference

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

and recall it at will. The operations manage this by translating theobject reference to a string and back to its original form again.

■ char * ORB_object_to_string (Object orb, Environment *ev, Object obj)

This function translates an object reference to a string. You canstore and manipulate the value just as you would any string.Before initiating a request, useORB_string_to_object() toobtain the object reference.

You must pass the actual object reference with any request. Youcannot pass the string translation of the object reference.

■ Object ORB_string_to_object (Object orb, Environment *ev, char *str);

Given a string produced byORB_object_to_string(), thisfunction returns the associated object reference. If you havestored the object reference as a string, use this function beforeinitiating a request.

■ ORBStatus ORB_create_list (count, newlist);

This operation allocates a list of the specified size and clears it forinitial use.

■ ORBStatus ORB_create_operation_list (oper, newlist);

This operation creates a pseudo-object.

Refer to the individual manual pages for more information about eachinterface in theORB API.

Extended ORB

TME 10 supports extensions to the interfaces presented by the ORBpseudo-object. The extended interfaces can throw exceptions:

■ char * t_ORB_object_to_string (Object orb, Environment *ev, Object obj)

■ Object t_ORB_string_to_object (Object orb, Environment *ev, char *str)

Available APIs

6–20 Version 3.6

BOA

■ void BOA_set_exception (Object boa, Environment *ev StExcep_exception_type major, char *userid, void *param)

In this operation, theEnvironment parameter is anin that is setby BOA_set_exception. BecauseBOA_set_exception does asimple assignment, it will not raise its own exceptions, at least inthe C binding.

The BOA makes a copy of theuserid string, but it does not copytheparam field. Thus, theEnvironment structure is pointing toa user-allocated value of the exception. Typically, theparamargument returns the value of the appropriate_create function.

In such a case, the ORB’s default freeing mechanism canadequately free the exception after it has been encoded. If theimplementation manually crafts theparam argument, and doesnot separately allocate each pointer inside theparam argument,a callback function must be registered.

■ Object BOA_Create(id, intf, impl)

This operation creates a new object reference.

■ void dispose(Object obj)

Given an object reference, this operation invalidates that objectreference. Upon completion, the ORB and BOA behave as if theobject never existed.

■ Principal BOA_get_principal(Object boa, Environment *ev, Object obj)

This operation returns a reference to a Principal pseudo objectassociated with the current request on targetObject obj.The returned value can be freed by callingORBfree_result().

■ Principal t_BOA_get_principal(Object boa, Environment *ev, Object obj)

This operation returns a reference to a Principal pseudo objectassociated with the current request on targetObject obj. Thereturned value can be freed by callingORBfree_result(). UnlikeBOA_get_principal, this operation can throw an exception.

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

TypeCode

A TypeCode interface can be a general argument in an operation. If itis anout argument or a result, it can be released usingORBfree() orORBfree_result(). SinceTypeCode is not an object,Object_release() cannot be used to free it. See the CORBAspecification for more information about theTypeCode interface.The following interfaces are available:

■ tmf_boolean TypeCode_equal(TypeCode _TypeCode, Environment *ev, TypeCode tc)

■ TypeCode_Kind TypeCode_kind( TypeCode _TypeCode, Environment* ev)

■ long TypeCode_param_count(TypeCode tc, Environment *ev)

■ any TypeCode_parameter(TypeCode tc, Environment *ev, long index)

TME 10 ADE also provides an equivalent set of interfaces that supportTME 10 exceptions. The naming convention for these interfaces is tosupply a prefix oft_ to the equivalent CORBA interface.

The TME 10 equivalent ofTypeCode_parameter(), for example, ist_TypeCode_parameter(). The following list presents the set of TME10 extendedTypeCode interfaces:

■ tmf_boolean t_TypeCode_equal(TypeCode _TypeCode, Environment *ev, TypeCode tc)

■ TypeCode_Kind t_TypeCode_kind( TypeCode _TypeCode, Environment* ev)

■ long t_TypeCode_param_count(TypeCode tc, Environment *ev)

■ any t_TypeCode_parameter(TypeCode tc, Environment *ev, long index)

Available APIs

6–22 Version 3.6

Extended TypeCode

Tivoli has also extended the CORBA-specifiedTypeCode API byadding supplemental operations:

■ size_t TypeCode_size( TypeCode _TypeCode, Environment* ev)

This function gets the architecture and compiler specific size of aspecified type.

■ long TypeCode_length(TypeCode _TypeCode, Environment* ev)

This function returns the length of an array or the bound of asequence or a string. Returns zero for any other kind ofTypeCode.

■ tmf_boolean TypeCode_isa(TypeCode child, Environment* ev, TypeCode parent)

This function returnsTRUE if child and parent are equal or childis derived from parent. This is useful in checking the derivationrelationship between hierarchical exceptions. It does notcurrently recognize interface inheritance.

■ long TypeCode_value_count((TypeCode tc, Environment* ev)

This function returns the number of fields in aTypeCode. Thereturn value may be used to provide the correct offset in callingTypeCode_value(). The following table shows the return valuecount for each type passed to the function:

■ any TypeCode_value((TypeCode tc, Environment* ev, void *data, long offest)

Type Value Count

tk_struct Number of its members; example: 3 if a struct hasa long, a char, and a sequence.

tk_union 2 (discriminator and case)

anything else 1

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

This function gets the value at offset. The offset ranges from 0through (value_count - 1). Data points to the C data according tothe following table:

This function cannot be used to loop through the elements of asequence or an array. Since the application can determine the sizeof the elements and the number of elements, it can loop throughthe elements by doing pointer arithmetic. TheTypeCode_value_count also returns a1 on a sequence or anarray.

You can think of the conversion and encode and decode functionsas facilities to perform serialized I/O on arbitrary C data. If wecall C data the internal format, it can be converted to two otherexternal formats: a platform independent ASN.1/BER stream andthe ASCII representation.

■ void TypeCode_convert_to_c((TypeCode tc, Environment* ev, void *cdata, const char *adata)

This function converts ASCIIadata to Ccdata. cdata points toa block of memory of size equal to the size oftc. Internal pointersin cdata will be allocated.cdata can be freed by callingORBfree().

■ void TypeCode_convert_to_ascii(TypeCode tc, Environment* ev, char **adata, const void *cdata)

This function convertscdata to ASCII adata. adata is theaddress of a char* variable that holds the ASCII string. The stringis allocated byTypeCode_convert_to_ascii.

C Type Type of Data

Pointer types: tk_Object, tk_Principal, tk_TypeCode,tk_string

Pointer to an Object, Principal,TypeCode and string asappropriate

Array Address of first element

All other types. Pointer to the C datum; example:poiner to a long, a struct and so on

Available APIs

6–24 Version 3.6

■ XSN_BUF *TypeCode_init_encode(TypeCode_encoding encoding)

This function creates anXSN_BUF, and returns a pointer to it.TheXSN_BUF is suitable for encoding data withTypeCode_encode or TypeCode_encode_ascii. The parameterencoding is anenum data type, and its value is alwaysTypeCode_ADR.

■ XSN_BUF *TypeCode_init_decode(TypeCode_encodingencoding, char *encoded_data, int length)

This function creates anXSN_BUF, and returns a pointer to it.TheXSN_BUF is suitable for decoding data withTypeCode_decode or TypeCode_decode_ascii. The parameterencoding is anenum data type, and its value is alwaysTypeCode_ADR.

■ void TypeCode_free_buf(XSN_BUF *buffer)

This function frees anXSN_BUF when it is no longer needed.

■ char *TypeCode_buffer(XSN_BUF *)

This function returns a pointer to the data buffer that contains theencoded data in theXSN_BUF.

■ int TypeCode_buf_length(XSN_BUF *)

This function returns the length of the encoded data.

■ int TypeCode_buf_error(XSN_BUF *)

This function returns any error code which has occurred duringthe processing of this buffer.

■ void TypeCode_encode(TypeCode tc, const void *cdata, XSN_BUF *buf )

This function encodes internal data of the type represented by thetc parameter into the buffer represented by thebuf parameter.

Available APIs


TM

E 10 C

lients and theT

ME

10 Run-tim

e

■ void TypeCode_decode(TypeCode tc,void *cdata, XSN_BUF *buf )

This function decodes data of the type represented by thetcparameter that is contained in a buffer represented by thebufparameter. The data is decoded from an external format to aninternal format.

■ void TypeCode_encode_ascii(TypeCode tc,const char*adata,XSN_BUF *buf )

This function encodes ASCII data of the type represented by thetc parameter into the buffer represented by thebuf parameter.

■ void TypeCode_decode_ascii(TypeCode tc, const char **adata, XSN_BUF *buf)

This function decodes ASCII data of the type represented by thetc parameter from a buffer represented by thebuf parameter.

For most of the extendedTypeCode operation there is a Tivoli versionthat supports TME 10 exceptions and transactions. These operationshave a prefix oft_ . The TME 10 equivalent ofTypeCode_decode_ascii(), for example, ist_TypeCode_decode_ascii(). The following list presents theseoperations:

■ size_t t_TypeCode_size( TypeCode _TypeCode, Environment* ev)

■ long t_TypeCode_length(TypeCode _TypeCode, Environment* ev)

■ tmf_boolean t_TypeCode_isa(TypeCode child, Environment* ev, TypeCode paent)

■ long t_TypeCode_value_count((TypeCode tc, Environment* ev)

■ any t_TypeCode_value((TypeCode tc, Environment* ev, void *data, long offest)

■ void t_TypeCode_convert_to_c((TypeCode tc, Environment* ev, void *cdata, const char *adata)

Available APIs

6–26 Version 3.6

■ void t_TypeCode_convert_to_ascii(TypeCode tc, Environment* ev, char **adata, const void *cdata)

■ XSN_BUF *t_TypeCode_init_encode (TypeCode_encoding encoding)

■ XSN_BUF *t_TypeCode_init_decode (TypeCode_encoding encoding, char *encoded_data, int length)

■ void t_TypeCode_free_buf(XSN_BUF *buffer)

■ void t_TypeCode_encode(TypeCode tc, const void* data, XSN_BUF *ebuf)

■ void t_TypeCode_decode(TypeCode tc, void* data, XSN_BUF *dbuf)

■ void t_TypeCode_encode_ascii(TypeCode tc, const char* data, XSN_BUF *ebuf)

■ void t_TypeCode_decode_ascii(TypeCode tc, char ** data, XSN_BUF *dbuf)

Framework Services Manual Index–1

Index

Aabstract class objects4-3abstract keyword4-24access control list. See ACLaccess control lists4-45access control specification

TEIDL example of 4-20access keyword4-26accessor functions2-25, 4-29, 4-32, 4-66ACL

defined 4-20specifying 4-41

acl keyword 4-45acldefault keyword4-45, 4-47adding behavior to existing TEIDL method

implementations4-66ANSI C function signatures4-73–4-75ansi C keyword4-26ANSI C language binding

supported by TEIDL4-69–4-75any data type3-11APIs

available in TME 6-12–6-26array data type3-13attribute keyword4-26attributes

defined 1-2encapsulating in classes1-13examples1-2–1-3IDL declarations3-24–3-26IDL mapping 3-25–3-26inheritance of1-6–1-9of TME objects 5-4–5-5persistent storage of2-24–2-25

redefining inherited3-17specifying implementations of4-26specifying in TEIDL 4-28

authorizationTEIDL 4-45

Bbase class

defined 1-14base implementation4-10base interfaces

defined 3-6basic object adapter. See BOAbehaviors

in TME objects 5-4–5-5binding

defined 5-5described5-5

binding keyword4-26BNF grammar description

TEIDL 4-84–4-88BOA

defined 2-4described2-13–2-14interface to pseudo-objects6-20request delivery2-7

BOA_set_exception function6-20Bourne shell binding

basic data types4-76–4-77method implementation

example 4-81–4-83method implementations4-79–4-83supported by TEIDL4-75–4-83

CC preprocessor4-84cascaded calls2-18–2-22

Index–2 Version 3.6

class keyword4-24classes

abstract4-3classless4-2–4-3creating in TEIDL 4-7–4-8encapsulating attributes and

methods1-13encapsulating behavior of4-4hierarchy of 5-8implementing 4-2inheriting 1-14, 4-6instances of1-12, 5-8instantiable4-3metaclass4-4–4-7of objects 1-12–1-14specifying additional behavior in object

implementation4-4TME 4-2–4-8, 5-8

classless objectsdescribed4-2–4-3specifying 4-24

CLIusing to initiate client requests6-9–6-10

CLI commandsidlattr 6-11idlcall 6-9

client requests2-6–2-7client stub files4-22client stubs

defined 2-4described2-9–2-10environment paramenter6-2object reference paramenter6-2using to initiate client requests6-2–6-3

clientscommunicating with object

implementations2-16defined 1-16described2-3in CORBA environment3-3relationship to implementations2-4–2-9

collection objectsdefined 5-12

command keyword4-26, 4-31command method binding

supported by TEIDL4-83common keyword4-42, 4-53common object request broker architecture.

See CORBAconcurrent interaction

defined 5-7constants

declaring in IDL 3-14specifying in TEIDL 4-27

CORBAapplication compatibility1-16compatible interfaces3-5–3-7components2-4described1-15, 2-2–2-4interface inheritance3-5–3-6memory management6-11–??, 6-26object identification1-16–1-17object model1-16operation semantics1-17output from compiler4-59programming environment3-3–3-4required files for building clients4-68required files for building servers4-68supported language bindings3-5TME ORB implementation2-15–2-16

CORBA filesgenerated by TEIDL4-59–4-60method template4-59private header4-59private source4-60public header4-60skeleton source4-60stub source4-60

create method4-3create_instance method4-3, 4-8, 4-22critical section locks

avoiding deadlocks5-53


defined 5-36friendly mutexes5-39in TME 5-37mutexes5-37read/write locks5-41semaphores5-44

Ddaemon keyword4-35, 4-37daemon servers

advantages5-16avoiding deadlocks in5-17–5-20avoiding queuing delays in5-17execution style5-14implementing 5-16–5-20object contexts5-20special considerations5-17–5-20

datadecoding 1-15encoding 1-15marshaling1-15presenting to method2-12requesting with client stubs2-9–2-10requesting with DII2-10specifying types in TEIDL4-27supplying types to the ORB4-76–4-77type mapping in IDL3-13–3-14unmarshaling1-15

data marshaling. See marshalingdata unmarshaling. See unmarshalingdeadlocks

avoiding 5-51–5-55causes of5-18defined 5-17described5-24in daemon servers5-17–5-20in parallel servers5-21

default keyword4-53derived implementation4-10

derived interfaces3-17–3-18DII

described2-4, 2-10–2-11interface repository2-11, 2-22–2-23using to initiate client requests6-3–6-9

dynamic bindingdefined 5-6

dynamic invocation interface. See DIIdynamic objects5-5–5-6dynamic programming

supported features5-6

Eempty interfaces3-18encapsulation

defined 1-2of objects 2-2

enumerated data type3-12environment parameter6-2exception_free function6-14, 6-17, 6-18exception_id function6-14exception_value function6-14exceptions

declaring in IDL 3-14IDL system 3-23raising in IDL 3-21–3-24returning 6-2run-time 2-13, 6-14TME 4-57–4-58

executable fileslocating 4-52

executes keyword4-35execution style

defined 4-15external daemon keyword4-35, 4-37external keyword4-52external path, described4-21


Ffor keyword 4-40, 4-41friendly mutexes

deadlock mechanisms5-51using 5-39

func function 5-28functions

in CORBA environment3-3

Hheaders

in TEIDL implementations4-23in TEIDL programs4-34

helper process4-30heterogeneous networks

described2-2honors keyword4-24

IIDL

attribute declarations3-24–3-26compiler 3-4constant declarations3-14context expression3-24data type mapping3-13–3-14declarations3-9–3-14defined 3-1derived interfaces3-17–3-18described3-4–3-5exception declarations3-14forward declarations3-19interface definition3-16–3-19, 4-23module definition3-14–3-16name resolution operator3-17name scoping resolution3-29–??naming scopes3-28–3-31operation declarations3-19–3-24

operation parameters3-19–3-20parameter mapping3-20–3-21preprocessor directives3-26–3-27raising exceptions3-21, 3-21–3-24signatures6-11source code example3-7–??specification 3-7–3-27TME 10 ADE extensions4-11type declarations3-10–3-14

idlarg utility 4-80idlattr 6-11idlcall 6-9idlexception utility 4-80idlinput utility 4-79idlresult utility 4-80implementation keyword4-24implementations

and interface inheritance4-11associating with interfaces4-24defined 4-8inheritance4-10–4-11multiple, of an interface4-9of classes4-2of methods1-11of objects 4-8–4-9of objects in TEIDL 4-22relationship to clients2-4–2-9separating from

interfaces2-3, 3-2–3-31TEIDL body 4-25TEIDL header4-23TEIDL inheritance4-25TEIDL preprocessor directive

example 4-14TEIDL specification 4-12–??, 4-23TME models 5-13–5-15

inheritancedefined 1-6of classes1-14of implementations4-10–4-11of interfaces3-5–3-6


of properties1-6–1-9of TEIDL implementations4-25operator 4-10order of TME objects5-10

inheritance orderingdefined 1-9

initialize keyword 4-42, 4-54, 4-55installation

script 4-22specifying a program4-40specifying an implementation4-40TEIDL preprocessor directive

example 4-19TEIDL specification 4-16–4-21, 4-40

installation keyword4-40, 4-41instances

defined 1-12encapsulating behavior4-4

instantiable class objects4-3instantiable classes

specifying 4-24instantiation

defined 4-8interface repository

defined 2-10interfaces

and implementation inheritance4-11associating with implementations4-24class implementation of4-2CORBA-compatible3-5–3-7defined 1-10defining CORBA-compliant3-3defining in IDL 3-16–3-19derived 3-17–3-18empty 3-18forward declarations3-19IDL-defined 3-6–3-7implementing CORBA-compliant3-4inheritance3-5–3-6multiple implementations4-9separating from

implementations2-3, 3-2–3-31

to objects1-10–1-11internal keyword4-52internal path

described4-21intrinsic method

defined 4-26intrinsics keyword4-26

Kkeywords

TEIDL implementation body4-26TEIDL implementation header4-24TEIDL program body4-35TEIDL program header4-34

Lliterals

expressing in Bourne shell binding4-75lock method5-51

Mmarshaling2-8–2-9memory corruption

avoiding 6-11memory leaks

avoiding 6-11memory management

in CORBA environment6-11–??message semaphores5-44messages

identifying 1-10polymorphic 1-9–1-10

metaclass keyword4-24


metaclassesdescribed4-4–4-7specifying 4-24

method implementationdefined 1-11

method template files4-22methods

and operations1-11ANSI C signatures4-73–4-75components of5-5defined 1-2encapsulating in classes1-13example 1-3helperless4-30identifying as object attributes4-52implementing 1-11, 5-5implementing group as a program4-35in CORBA environment3-3of TME objects 5-5parameters1-11programming techniques for

multi-threaded5-25–5-26signatures5-5specifying 4-26specifying as a C function4-26specifying as a C program4-26specifying as a command4-26specifying as a shell script4-26specifying functions to execute on

invocation 4-35specifying in TEIDL 4-30specifying intrinsic4-26specifying names in TEIDL4-36specifying special execution

environment4-26specifying, to retrieve attribute4-26specifying, to set attribute4-26TEIDL implementation-defined4-30TEIDL intrinsic 4-32with helper process4-30

methods keyword4-26modelling

entities 1-5–1-11module definitions

in IDL 3-14–3-16multiple inheritance5-10

defined 1-8mutate keyword4-26mutator functions2-25, 4-29, 4-32, 4-66mutexes

deadlock mechanisms5-51defined 5-21described5-23friendly 5-39using 5-37

mutual exclusion semaphores5-45

Nname resolution operator3-17name space

locking 5-48naming scopes

in IDL 3-28–3-31NO_ARGUMENT_CHECK flag6-4non-instantiable classes

specifying 4-24non-parallel servers5-15

Oobject implementations

communicating with clients2-16defined 2-3in CORBA environment3-3relationship to TME clients2-5–2-6returning data2-8

object instantiationdefined 4-3

object interface6-16–6-17object keyword4-24


object referencedefined 2-3, 2-7

object reference parameter6-2object request broker. See ORBObject_duplicate function6-16Object_is_nil function6-16Object_release function6-16object-oriented systems

programming concepts1-2programming on distributed

systems1-14–1-17objects

abstract class4-3as models1-5–1-11attributes 5-5classes of1-12–1-14classless4-2–4-3communicating with1-4creating from a class in TEIDL4-8defined 1-2described1-2–1-4encapsulating2-2identifying for client service

requests6-2identifying methods as attributes4-52implementing 4-8–4-9implementing in TEIDL 4-22inheriting attributes1-6–1-9initializing in TEIDL 4-54instantiable class4-3interacting with TME objects5-7–5-8interfaces to1-10–1-11metaclass4-4–4-7pseudo-objects6-18specifying implemenation and

installation details4-1specifying program to initialize4-42TME implementations of5-2–5-13

operation namedefined 2-2

operation signature

defined 1-11operations

and methods1-11CORBA semantics1-17defined 1-11IDL declarations3-19–3-24IDL parameters3-19–3-20IDL parameters mapping3-20–3-21in CORBA environment3-3redefining inherited3-6, 3-17storing 5-4

operations. See also methodsORB

cascaded calls2-18–2-22crossing process boundaries2-16–2-17defined 1-16, 2-3delivering requests2-7interface to pseudo objects6-18interfaces2-4, 2-9–2-13performance issues2-20–2-22security issues2-20–2-22TME implementation2-15–2-26

ORB_object_to_string function6-19ORB_string_to_object function6-19

Pparallel servers

advantages5-22available semaphores5-27available timer services5-27calling POSIX signals5-28controlling data access5-21deadlocks5-24defined 4-36described5-15disadvantages5-22–5-23implementing 5-21–5-31mutexes5-23POSIX thread routines5-28–5-31programming with5-26


race conditions5-21, 5-24safe programming techniques5-25spawning new threads5-26thread deadlocks5-21TME concurrence5-31–5-55

parameterspassing to and from clients3-20

path keyword4-52paths

specifying single method for allplatforms 4-42

TEIDL specification example4-21per method keyword4-35, 4-37per method servers

execution style5-14implementing 5-15–5-16

persistencedefined 5-13

persistent attribute storage2-24–2-25persistent objects5-13persistent transaction storage2-26polymorphic messages1-9–1-10polymorphism

defined 1-9support of multiple implementations4-9

POSIX signalscalling 5-28

POSIX thread routines5-28–5-31preprocessor directives

define 3-26IDL 3-26–3-27include 3-26pragma generate3-27sample program4-16TEIDL implementation4-55

privdefault keyword4-45, 4-51privilege keyword4-45, 4-47, 4-51program keyword4-34programming environment

CORBA-compliant 3-3–3-4programming techniques

for multi-threaded methods5-25–5-26programs

specifying to be multi-threaded4-35TEIDL body 4-35TEIDL header4-34TEIDL specification 4-15–4-16

protection domainsdescribed5-34

pseudo-objectsBOA interface 6-20defined 6-18interfaces6-18–6-26ORB interface6-18TypeCode interface6-21

Qqueuing delays

in daemon servers5-17

Rrace conditions

described5-24on parallel servers5-21

read/write locks5-41reference relationships5-12reusable objects5-6–5-7roles 4-45roles keyword4-45, 4-51run-time exceptions2-13, 6-14run-time functions

TME 6-12–6-15run-time libraries2-12

Ssecurity


authorization4-45security issues

in TEIDL 4-45segmentation errors

avoiding 6-11semaphores

attempting to get5-27attempting to get, with data5-27attempting to signal5-27described5-44destroying 5-27enhancements5-27initializing 5-27message5-44mutual exclusion5-45signalling 5-27signalling, with data5-27synchronization5-47waiting for 5-27waiting for, with data5-27

sequence data type3-12server execution styles

in TME 5-14–5-15specifying in TEIDL 4-36

server processesaccomodating different objects4-35executing only one method4-35specifying as daemons4-35specifying as non-ORB-activated

daemons4-35server skeletons

described2-4, 2-12server types

specifying in TEIDL 4-37TME 5-13–5-14

serversdefined 1-16implementing daemon5-16–5-20implementing per method5-15–5-16

service providersisolating from requestors2-2

service requestors

isolating from providers2-2shared keyword4-35, 4-36shared servers4-36, 5-14–5-15shell keyword4-26signature

defined 3-2single inheritance

defined 5-10sleep functions

replacement for5-28special characters

including in Bourne shell binding4-75specialization

defined 1-7startup keyword4-35, 4-38static binding

defined 5-6string data type3-12synchronization semaphores5-47

TTEIDL

access control specification4-20accessor and mutator functions4-32adding behavior to existing method

implementations4-66ANSI C language binding4-69–4-75attribute specification4-28BNF grammar description4-84–4-88Bourne shell binding4-75–4-83class creation4-7–4-8command method binding4-83common output files4-60constant specification4-27CORBA files generated4-59–4-60data type specification4-27described3-4, 4-11–4-12extensions to IDL4-11file including scheme4-84


implementation-defined methods4-30inheritance support4-11intrinsic methods4-32method name specification4-36method specification4-30object creation from classes4-8object implementation4-22object initialization 4-54path specification example4-21security issues4-45server execution style specification4-36server type specification4-37specification components4-14specification keywords4-40start-up specification4-38TME files generated4-59TME output 4-57–4-59

TEIDL compiler 4-2, 4-7, 4-10operation 4-83–4-84output 4-55–4-57output files 4-55preprocessors4-84

TEIDL implementationbody 4-25body keywords4-26header4-23header keywords4-24inheritance4-25location 4-52preprocessor directives4-55scheme4-12specification 4-12–??, 4-23specification constructs4-23–??

TEIDL installationcomponents4-42constructs4-40specification 4-16–4-21, 4-40specification body4-41specification components4-19specification header4-40

TEIDL output filesauxiliary header4-60

auxiliary source4-60configuration script4-60, 4-68CORBA method template4-63defines header4-61, 4-67installation tar4-60main program4-61method templates4-62private header4-66public header4-64TME method template4-62TME skeleton liners4-61TME stub wrappers4-61

TEIDL programbody 4-35body keywords4-35constructs4-34example of body4-38–??header4-34header keywords4-34specification 4-15–4-16, 4-34

thread_signal function5-28threaded keyword4-35, 4-36threads

concurrency5-31critical section locking5-37friendly mutexes5-39mutexes5-37protection domains5-34read/write locks5-41semaphores5-44spawning new5-26

threads critical section locking5-37tidlc command4-7timeout

cancelling 5-28specifying 4-34

timeout keyword4-34, 4-37timeout/untimeout interface5-27timer services

enhancements to5-27Tivoli client


required files4-69Tivoli server

required files4-69TME

classes4-2–4-8, 5-8client-server programs4-68–4-69concurrency5-31–5-55critical section locking5-37exceptions4-57–4-58friendly mutexes5-39mutexes5-37nested transactions4-57objects and instance objects4-4read/write locks5-41run-time functions6-12–6-15semaphores5-44server execution styles5-14–5-15server types5-13–5-14TEIDL output 4-57–4-59transaction duration locks

threadstransaction duration locks5-48

TME 10 ADE extended interface definitionlanguage. See TEIDL

TME clientsrelationship to object

implementations2-5–2-6requesting services6-1–6-10

TME concurrencyavoiding deadlocks5-51–5-55protection domains5-34

TME filesgenerated by TEIDL4-59method template4-59private header4-59private source4-59public header4-59skeleton liner4-59stub wrapper4-59

TME implementation models5-13–5-15daemon servers5-13external daemon servers5-13

parallel servers4-36per method servers5-13server types and execution styles4-39shared servers4-36, 5-14

TME objectsadvantages of inheritance5-11and TME instance objects4-4attributes 5-5attributes and behaviors5-4–5-5characteristics5-2class relationships5-8concurrent interaction with other

objects 5-7data storage5-4dynamic 5-5–5-6dynamic relationships5-8exhibiting multiple states5-34identifying 5-2implementing 5-2–5-13inheritance5-8inheritance order5-10interaction with other objects5-7–5-8methods5-5modularity of 5-3–5-4persistency of5-13, 5-34reference relationships5-12reusability 5-6–5-7serializing 5-34–5-36states5-34–5-36

TME ORBdescribed2-6supported flags6-4

TMF_BOA environment variable4-81tmf_create_request operation6-5tmf_init function 6-12, 6-13tmf_locate_boa function6-14tmf_locate_orb function6-14TMF_ORB environment variable4-81tmf_request_invoke operation6-5TMF_SELF environment variable4-81tmf_serialize_request operation6-6


tmf_unserialize_request operation6-6token separators

in Bourne shell binding4-75transaction duration locks5-48

avoiding deadlocks5-51deadlock mechanisms5-51defined 5-37lock duration 5-48lock name space5-48rules 5-50

transactionslocking access during5-48persistent storage of2-26TME nested4-57

type declarationsin IDL 3-10–3-14

TypeCode interfaceextended6-22to pseudo-objects6-21

TypeCode_convert_to_ascii function6-23TypeCode_convert_to_c function6-23TypeCode_equal function6-21TypeCode_isa function6-22TypeCode_kind function6-21TypeCode_length function6-22TypeCode_param_count function6-21TypeCode_parameter function6-21TypeCode_size function6-22TypeCode_value function6-22TypeCode_value_count function6-22

Uunmarshaling2-8–2-9unshared servers5-14–5-15

Vvariable data

storing 5-4

Wwith keyword 4-40, 4-41