Information Manager and Encapsulated Scheduler Programming Guide Volume II: Reference Manual Part Number 205A172-31A Prepared by: M Aigen (607) 751-4645 Software Development Lockheed Martin Federal Systems Owego, New York February 04, 1997 © Copyright Lockheed Martin 1997 (Unpublished) All Rights Reserved Version Information: First Draft - October 11, 1996 First Release - November 11, 1996 Revision A - December 11, 1996 Revision B - February 04, 1997 incorporating STR A1720039, A1720043, A1720049, A1720053, A1720063, A1720070, A1720076 TABLE OF CONTENTS 1 Introduction . . . . . . . . . . . . . . . . . . . . . . .2 1.1 Document Identification. . . . . . . . . . . . . . .2 1.2 Scope. . . . . . . . . . . . . . . . . . . . . . . .2 1.2.1 Configurations Supported . . . . . . . . . .2 1.3 Document Overview. . . . . . . . . . . . . . . . . .3 2 Applicable Documents . . . . . . . . . . . . . . . . . . .4 2.1 Specifications . . . . . . . . . . . . . . . . . . .4 2.2 Standards. . . . . . . . . . . . . . . . . . . . . .4 2.3 Other Publications . . . . . . . . . . . . . . . . .4 3 Interface Definition Language/Object Definition Language (IDL/ODL)5 3.1 Comments . . . . . . . . . . . . . . . . . . . . . .5 3.2 Identifiers. . . . . . . . . . . . . . . . . . . . .5 3.3 Literal Values . . . . . . . . . . . . . . . . . . .5 3.4 Name Scope . . . . . . . . . . . . . . . . . . . . .6 3.5 Module Declaration . . . . . . . . . . . . . . . . .6 3.6 Interface Declaration. . . . . . . . . . . . . . . .6 3.6.1 ODL Type Property List . . . . . . . . . . .7 3.6.1.1 ODL Extent declaration . . . . . . . .7 3.6.1.2 ODL Key Declaration. . . . . . . . . .7 3.6.1.3 ODL Persistence Declaration. . . . . .8 3.7 Attribute Declaration. . . . . . . . . . . . . . . .9 3.7.1 IDL Attribute Example. . . . . . . . . . . .9 3.7.2 ODL Attribute Example. . . . . . . . . . . .9 3.8 ODL Memory Model Declaration . . . . . . . . . . . .9 3.8.1 Remote Memory Model ODL Example. . . . . . 10 3.8.2 Direct Memory Model ODL Example. . . . . . 10 3.9 IDL Exception Declaration. . . . . . . . . . . . . 10 3.10 IDL Operation Declaration . . . . . . . . . . . . 11 3.10.1 IDL Parameter Declaration . . . . . . . . 11 3.10.2 IDL Raises Expression . . . . . . . . . . 11 3.11 Type Definition . . . . . . . . . . . . . . . . . 12 3.12 Constant Declarations . . . . . . . . . . . . . . 12 4 Preprocessors. . . . . . . . . . . . . . . . . . . . . . 13 4.1 idlpp - Interface Definition Language (IDL) / Object Definition Language (ODL) Preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.1 Preprocessor Limitations . . . . . . . . . 13 4.1.1.1 Supported Features . . . . . . . . . 13 4.1.1.2 Features Not Supported . . . . . . . 14 4.1.1.3 Other Limitations. . . . . . . . . . 14 4.2 oqlpp - Object Query Language (OQL) Preprocessor. 14 4.2.1 Preprocessor Limitations . . . . . . . . . 15 5 IDL/ODL mapping to C . . . . . . . . . . . . . . . . . . 17 5.1 IDL Atomic types . . . . . . . . . . . . . . . . . 17 5.2 IDL sequence<> . . . . . . . . . . . . . . . . . . 17 5.3 ODL Collection types . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.3.1 iterator functions . . . . . . . . . . . . 18 5.3.2 collection type definition . . . . . . . . 19 5.3.3 Array functions . . . . . . . . . . . . . 19 5.3.4 ODL List<> . . . . . . . . . . . . . . . . 21 5.3.4.1 List function definitions. . . . . . 22 6 Object Database Management API's in C. . . . . . . . . . 26 6.1 Interface Database . . . . . . . . . . . . . . . . 26 6.1.1 open . . . . . . . . . . . . . . . . . . . 26 6.1.2 close. . . . . . . . . . . . . . . . . . . 26 6.1.3 bind . . . . . . . . . . . . . . . . . . . 26 6.1.4 lookup . . . . . . . . . . . . . . . . . . 27 6.1.5 open direct. . . . . . . . . . . . . . . . 27 6.1.6 close direct . . . . . . . . . . . . . . . 27 6.1.7 bind direct. . . . . . . . . . . . . . . . 28 6.1.8 lookup direct. . . . . . . . . . . . . . . 28 6.2 Interface Transaction. . . . . . . . . . . . . . . 29 6.2.1 create . . . . . . . . . . . . . . . . . . 29 6.2.2 begin. . . . . . . . . . . . . . . . . . . 29 6.2.3 commit . . . . . . . . . . . . . . . . . . 30 6.2.4 abort. . . . . . . . . . . . . . . . . . . 30 6.2.5 checkpoint . . . . . . . . . . . . . . . . 30 6.3 remote copy. . . . . . . . . . . . . . . . . . . . 31 6.4 Shared Memory. . . . . . . . . . . . . . . . . . . 32 6.4.1 create shared memory . . . . . . . . . . . 32 6.4.2 remove shared memory . . . . . . . . . . . 32 6.4.3 Allocate Shared Memory . . . . . . . . . . 32 6.4.4 Free Shared Memory . . . . . . . . . . . . 32 6.4.5 Copy to/from Shared Memory . . . . . . . . 33 7 Object Request Broker APIs in C. . . . . . . . . . . . . 34 7.1 module CORBA . . . . . . . . . . . . . . . . . . . 34 7.1.1 interface ORB. . . . . . . . . . . . . . . 34 7.1.1.1 BOA Initialization . . . . . . . . . 34 7.1.1.2 initialization . . . . . . . . . . . 34 7.1.1.3 list initial services. . . . . . . . 35 7.1.1.4 object to string . . . . . . . . . . 35 7.1.1.5 resolve initial references . . . . . 36 7.1.1.6 string to object . . . . . . . . . . 36 7.1.2 interface Object . . . . . . . . . . . . . 37 7.1.2.1 duplicate. . . . . . . . . . . . . . 37 7.1.2.2 is equivalent. . . . . . . . . . . . 37 7.1.2.3 is nil . . . . . . . . . . . . . . . 37 7.1.2.4 release. . . . . . . . . . . . . . . 38 7.1.2.5 non existent . . . . . . . . . . . . 38 7.1.2.6 hash . . . . . . . . . . . . . . . . 39 7.1.2.7 get implementation . . . . . . . . . 39 7.1.3 interface Basic Object Adapter (BOA) . . . 39 7.1.3.1 create . . . . . . . . . . . . . . . 40 7.1.3.2 dispose. . . . . . . . . . . . . . . 40 7.1.3.3 get id . . . . . . . . . . . . . . . 41 7.1.3.4 implementation is ready. . . . . . . 41 7.1.3.5 set exception. . . . . . . . . . . . 41 7.1.3.6 setsched . . . . . . . . . . . . . . 42 7.1.3.7 preempt. . . . . . . . . . . . . . . 42 7.1.3.8 create group . . . . . . . . . . . . 43 7.1.3.9 join . . . . . . . . . . . . . . . . 43 7.1.3.10 leave . . . . . . . . . . . . . . . 43 7.2 module Common Object Services - Event Communication44 7.2.1 interface Pull Consumer . . . . . . . . . . . . . . . . . . . . . . . . 45 7.2.1.1 disconnect pull consumer . . . . . . 45 7.2.2 interface Pull Supplier. . . . . . . . . . 45 7.2.2.1 disconnect pull supplier . . . . . . 45 7.2.2.2 pull . . . . . . . . . . . . . . . . 45 7.2.2.3 try pull . . . . . . . . . . . . . . 46 7.2.2.4 create . . . . . . . . . . . . . . . 46 7.2.3 interface Push Consumer. . . . . . . . . . 47 7.2.3.1 disconnect push consumer . . . . . . 47 7.2.3.2 push . . . . . . . . . . . . . . . . 47 7.2.3.3 create . . . . . . . . . . . . . . . 48 7.2.4 interface Push Supplier. . . . . . . . . . 48 7.2.4.1 disconnect push supplier . . . . . . 48 7.3 module Common Object Services - Event Channel Administration 48 7.3.1 interface Proxy Push Consumer. . . . . . . 49 7.3.1.1 push . . . . . . . . . . . . . . . . 49 7.3.1.2 disconnect push consumer . . . . . . 49 7.3.1.3 connect push supplier. . . . . . . . 50 7.3.2 interface Proxy Pull Supplier. . . . . . . 50 7.3.2.1 pull . . . . . . . . . . . . . . . . 50 7.3.2.2 try pull . . . . . . . . . . . . . . 50 7.3.2.3 disconnect pull supplier . . . . . . 51 7.3.2.4 connect pull consumer. . . . . . . . 51 7.3.3 interface Proxy Pull Consumer. . . . . . . 52 7.3.3.1 disconnect pull consumer . . . . . . 52 7.3.3.2 connect pull supplier. . . . . . . . 52 7.3.4 interface Proxy Push Supplier. . . . . . . 52 7.3.4.1 disconnect push supplier . . . . . . 52 7.3.4.2 connect push consumer. . . . . . . . 53 7.3.5 interface Consumer Administration. . . . . 53 7.3.5.1 obtain push supplier . . . . . . . . 53 7.3.5.2 obtain pull supplier . . . . . . . . 53 7.3.6 interface Supplier Administration. . . . . 54 7.3.6.1 obtain push consumer . . . . . . . . 54 7.3.6.2 obtain pull consumer . . . . . . . . 54 7.3.7 interface Event Channel. . . . . . . . . . 54 7.3.7.1 for consumers. . . . . . . . . . . . 55 7.3.7.2 for suppliers. . . . . . . . . . . . 55 7.3.7.3 destroy. . . . . . . . . . . . . . . 55 7.3.8 interface Event Channel Factory. . . . . . 56 7.3.8.1 create event channel . . . . . . . . 56 7.4 module Common Object Services - Life Cycle . . . . 56 7.4.1 interface Factory Finder . . . . . . . . . 56 7.4.1.1 find factories . . . . . . . . . . . 56 7.4.2 interface Life Cycle Object. . . . . . . . 57 7.4.2.1 copy . . . . . . . . . . . . . . . . 57 7.4.2.2 move . . . . . . . . . . . . . . . . 58 7.4.2.3 remove . . . . . . . . . . . . . . . 58 7.4.3 interface Generic Factory. . . . . . . . . 58 7.4.3.1 create object. . . . . . . . . . . . 58 7.4.3.2 supports . . . . . . . . . . . . . . 59 7.5 module Common Object Services - Naming . . . . . . 59 7.5.1 interface Naming Context . . . . . . . . . 60 7.5.1.1 bind . . . . . . . . . . . . . . . . 60 7.5.1.2 bind_context . . . . . . . . . . . . 60 7.5.1.3 bind_new_context . . . . . . . . . . 61 7.5.1.4 list . . . . . . . . . . . . . . . . 61 7.5.1.5 new_context. . . . . . . . . . . . . 62 7.5.1.6 resolve. . . . . . . . . . . . . . . 62 7.5.1.7 destroy . . . . . . . . . . . . . . 63 7.5.1.8 rebind . . . . . . . . . . . . . . . 63 7.5.1.9 rebind_context . . . . . . . . . . . 64 7.5.1.10 unbind . . . . . . . . . . . . . . 64 7.5.2 interface Binding Iterator . . . . . . . . 64 7.5.2.1 next_one . . . . . . . . . . . . . . 64 7.5.2.2 next_n . . . . . . . . . . . . . . . 65 7.5.2.3 destroy. . . . . . . . . . . . . . . 65 7.6 module Common Object Services - Stream . . . . . . 65 7.6.1 interface Streamable . . . . . . . . . . . 66 7.6.1.1 external form id . . . . . . . . . . 66 7.6.1.2 externalize to stream. . . . . . . . 66 7.6.1.3 internalize from stream. . . . . . . 66 7.6.2 interface Streamable Factory . . . . . . . 67 7.6.2.1 create uninitialized . . . . . . . . 67 7.6.3 interface StreamIO . . . . . . . . . . . . 67 7.6.3.1 write string . . . . . . . . . . . . 67 7.6.3.2 write char . . . . . . . . . . . . . 68 7.6.3.3 write octet. . . . . . . . . . . . . 68 7.6.3.4 write unsigned long. . . . . . . . . 68 7.6.3.5 write unsigned short . . . . . . . . 69 7.6.3.6 write long . . . . . . . . . . . . . 69 7.6.3.7 write short. . . . . . . . . . . . . 69 7.6.3.8 write float. . . . . . . . . . . . . 70 7.6.3.9 write double . . . . . . . . . . . . 70 7.6.3.10 write boolean . . . . . . . . . . . 71 7.6.3.11 read string . . . . . . . . . . . . 71 7.6.3.12 read char . . . . . . . . . . . . . 71 7.6.3.13 read octet. . . . . . . . . . . . . 71 7.6.3.14 read unsigned long. . . . . . . . . 72 7.6.3.15 read unsigned short . . . . . . . . 72 7.6.3.16 read long . . . . . . . . . . . . . 72 7.6.3.17 read short. . . . . . . . . . . . . 73 7.6.3.18 read float. . . . . . . . . . . . . 73 7.6.3.19 read double . . . . . . . . . . . . 73 7.6.3.20 read boolean. . . . . . . . . . . . 74 7.7 module Common Object Services - Externalization. . 74 7.7.1 interface Stream . . . . . . . . . . . . . 74 7.7.1.1 externalize. . . . . . . . . . . . . 74 7.7.1.2 internalize. . . . . . . . . . . . . 74 7.7.1.3 flush. . . . . . . . . . . . . . . . 75 7.7.2 interface Stream Factory . . . . . . . . . 75 7.7.2.1 create . . . . . . . . . . . . . . . 75 7.7.3 File Stream Factory. . . . . . . . . . . . 76 7.7.3.1 create . . . . . . . . . . . . . . . 76 8 Encapsulated Scheduler API's in C . . . . . . . . . . . 77 8.1 Register . . . . . . . . . . . . . . . . . . . . . 77 8.2 Execute. . . . . . . . . . . . . . . . . . . . . . 78 8.3 Set Priority . . . . . . . . . . . . . . . . . . . 79 8.4 Resume . . . . . . . . . . . . . . . . . . . . . . 80 8.5 Suspend. . . . . . . . . . . . . . . . . . . . . . 80 8.6 Terminate. . . . . . . . . . . . . . . . . . . . . 81 8.7 Periodic Rate Event. . . . . . . . . . . . . . . . 81 8.8 Periodic Rate End. . . . . . . . . . . . . . . . . 82 8.9 Timer. . . . . . . . . . . . . . . . . . . . . . . 82 8.10 Issue Event . . . . . . . . . . . . . . . . . . . 83 8.11 Cancel Event. . . . . . . . . . . . . . . . . . . 83 8.12 Sleep . . . . . . . . . . . . . . . . . . . . . . 84 8.13 Wait. . . . . . . . . . . . . . . . . . . . . . . 84 8.14 Poll. . . . . . . . . . . . . . . . . . . . . . . 85 8.15 Poll Event. . . . . . . . . . . . . . . . . . . . 85 8.16 Event Priority. . . . . . . . . . . . . . . . . . 86 8.17 Event ID. . . . . . . . . . . . . . . . . . . . . 86 8.18 Event Handler . . . . . . . . . . . . . . . . . . 86 8.19 Signal. . . . . . . . . . . . . . . . . . . . . . 87 8.20 Exception . . . . . . . . . . . . . . . . . . . . 87 8.21 Exception End . . . . . . . . . . . . . . . . . . 88 8.22 Semaphore Lock. . . . . . . . . . . . . . . . . . 88 8.23 Semaphore Unlock. . . . . . . . . . . . . . . . . 89 8.24 Set Time. . . . . . . . . . . . . . . . . . . . . 89 8.25 Time Scale. . . . . . . . . . . . . . . . . . . . 90 8.26 Get Time. . . . . . . . . . . . . . . . . . . . . 90 8.27 Elapsed Time. . . . . . . . . . . . . . . . . . . 91 8.28 Processing Time . . . . . . . . . . . . . . . . . 91 8.29 Date and Time . . . . . . . . . . . . . . . . . . 92 8.30 Time Synchronization. . . . . . . . . . . . . . . 92 8.31 Memory Usage. . . . . . . . . . . . . . . . . . . 93 8.32 Memory Allocate . . . . . . . . . . . . . . . . . 93 8.33 Memory Free . . . . . . . . . . . . . . . . . . . 93 8.34 Error Number. . . . . . . . . . . . . . . . . . . 94 8.35 Error Message . . . . . . . . . . . . . . . . . . 94 8.36 Select Manager Routines . . . . . . . . . . . . . 94 8.36.1 select_add_fd . . . . . . . . . . . . . . 95 8.36.2 select_delete_fd. . . . . . . . . . . . . 95 8.36.3 select_add_msg. . . . . . . . . . . . . . 95 8.36.4 select_delete_msg . . . . . . . . . . . . 96 8.36.5 select_add_upcall . . . . . . . . . . . . 96 8.36.6 select delete upcall. . . . . . . . . . . 96 8.36.7 select_wait . . . . . . . . . . . . . . . 97 8.36.8 select_wait_all . . . . . . . . . . . . . 97 8.37 File Input/Output . . . . . . . . . . . . . . . . 97 9 IDL/ODL mapping to Ada . . . . . . . . . . . . . . . . . 99 9.1 IDL Atomic types . . . . . . . . . . . . . . . . . 99 9.2 IDL sequence<> . . . . . . . . . . . . . . . . . . 99 9.3 IDL string . . . . . . . . . . . . . . . . . . . .100 9.4 ODL Collection types . . . . . . . . . . . . . . .102 9.4.1 Iterator . . . . . . . . . . . . . . . . .102 9.4.2 Array. . . . . . . . . . . . . . . . . . .104 9.4.3 List. . . . . . . . . . . . . . . . . . .105 10 Object Database Management API's in Ada . . . . . . . .108 10.1 Interface Database. . . . . . . . . . . . . . . .108 10.1.1 open. . . . . . . . . . . . . . . . . . .108 10.1.2 close . . . . . . . . . . . . . . . . . .108 10.1.3 bind. . . . . . . . . . . . . . . . . . .108 10.1.4 lookup. . . . . . . . . . . . . . . . . .109 10.1.5 open direct . . . . . . . . . . . . . . .109 10.1.6 close direct. . . . . . . . . . . . . . .109 10.1.7 bind direct . . . . . . . . . . . . . . .109 10.1.8 lookup direct . . . . . . . . . . . . . .110 10.2 Interface Transaction . . . . . . . . . . . . . .110 10.2.1 create. . . . . . . . . . . . . . . . . .110 10.2.2 begin . . . . . . . . . . . . . . . . . .111 10.2.3 commit. . . . . . . . . . . . . . . . . .111 10.2.4 abort . . . . . . . . . . . . . . . . . .111 10.2.5 create direct . . . . . . . . . . . . . .112 10.2.6 begin direct. . . . . . . . . . . . . . .112 10.2.7 commit direct . . . . . . . . . . . . . .112 10.2.8 abort direct. . . . . . . . . . . . . . .113 10.2.9 checkpoint. . . . . . . . . . . . . . . .113 11 Object Request Broker API's in Ada. . . . . . . . . . .114 11.1 module CORBA. . . . . . . . . . . . . . . . . . .114 11.1.1 interface ORB . . . . . . . . . . . . . .114 11.1.1.1 BOA Initialization. . . . . . . . .114 11.1.1.2 initialization. . . . . . . . . . .114 11.1.1.3 list initial services . . . . . . .115 11.1.1.4 object to string. . . . . . . . . .115 11.1.1.5 resolve initial references. . . . .115 11.1.1.6 string to object. . . . . . . . . .116 11.1.2 interface Object. . . . . . . . . . . . .116 11.1.2.1 duplicate . . . . . . . . . . . . .116 11.1.2.2 is equivalent . . . . . . . . . . .117 11.1.2.3 is nil (is null). . . . . . . . . .117 11.1.2.4 release . . . . . . . . . . . . . .117 11.1.2.5 non existent. . . . . . . . . . . .118 11.1.2.6 hash . . . . . . . . . . . . . . .118 11.1.2.7 get implementation . . . . . . . .118 11.1.3 interface Basic Object Adapter (BOA). . .119 11.1.3.1 create. . . . . . . . . . . . . . .119 11.1.3.2 dispose . . . . . . . . . . . . . .120 11.1.3.3 get id. . . . . . . . . . . . . . .120 11.1.3.4 implementation is ready . . . . . .120 11.1.3.5 set exception . . . . . . . . . . .120 11.1.3.6 setsched. . . . . . . . . . . . . .121 11.1.3.7 preempt . . . . . . . . . . . . . .121 11.1.3.8 create group. . . . . . . . . . . .122 11.1.3.9 join. . . . . . . . . . . . . . . .122 11.1.3.10 leave. . . . . . . . . . . . . . .122 11.2 module Common Object Services - Event Communication123 11.2.1 interface Pull Consumer . . . . . . . . . . . . . . . . . . . . . . . .123 11.2.1.1 disconnect pull consumer. . . . . .123 11.2.2 interface Pull Supplier . . . . . . . . .123 11.2.2.1 disconnect pull supplier. . . . . .123 11.2.2.2 pull. . . . . . . . . . . . . . . .124 11.2.2.3 try pull. . . . . . . . . . . . . .124 11.2.2.4 create. . . . . . . . . . . . . . .124 11.2.3 interface Push Consumer . . . . . . . . .125 11.2.3.1 disconnect push consumer. . . . . .125 11.2.3.2 push. . . . . . . . . . . . . . . .125 11.2.3.3 create. . . . . . . . . . . . . . .125 11.2.4 interface Push Supplier . . . . . . . . .125 11.2.4.1 disconnect push supplier. . . . . .126 11.3 module Common Object Services - Event Channel Administration 126 11.3.1 interface Proxy Push Consumer . . . . . .126 11.3.1.1 push. . . . . . . . . . . . . . . .126 11.3.1.2 disconnect push consumer. . . . . .127 11.3.1.3 connect push supplier . . . . . . .127 11.3.2 Proxy Pull Supplier . . . . . . . . . . .127 11.3.2.1 pull. . . . . . . . . . . . . . . .127 11.3.2.2 try pull. . . . . . . . . . . . . .128 11.3.2.3 disconnect pull supplier. . . . . .128 11.3.2.4 connect pull supplier . . . . . . .128 11.3.3 Proxy Pull Consumer . . . . . . . . . . .129 11.3.3.1 disconnect pull consumer. . . . . .129 11.3.3.2 connect pull supplier . . . . . . .129 11.3.4 Proxy Push Supplier . . . . . . . . . . .129 11.3.4.1 disconnect push supplier. . . . . .129 11.3.4.2 connect push consumer . . . . . . .130 11.3.5 interface Consumer Admin. . . . . . . . .130 11.3.5.1 obtain push supplier. . . . . . . .130 11.3.5.2 obtain pull supplier. . . . . . . .130 11.3.6 interface Supplier Admin. . . . . . . . .131 11.3.6.1 obtain push consumer. . . . . . . .131 11.3.6.2 obtain pull consumer. . . . . . . .131 11.3.7 interface Event Channel . . . . . . . . .131 11.3.7.1 for consumers . . . . . . . . . . .131 11.3.7.2 for suppliers . . . . . . . . . . .132 11.3.7.3 destroy . . . . . . . . . . . . . .132 11.3.8 interface Event Channel Factory . . . . .132 11.3.8.1 create event channel. . . . . . . .132 11.4 module Common Object Services - Life Cycle . . .133 11.4.1 interface Factory Finder. . . . . . . . .133 11.4.1.1 find factories. . . . . . . . . . .133 11.4.2 interface Life Cycle Object . . . . . . .133 11.4.2.1 copy. . . . . . . . . . . . . . . .134 11.4.2.2 move. . . . . . . . . . . . . . . .134 11.4.2.3 remove. . . . . . . . . . . . . . .134 11.4.3 interface Generic Factory . . . . . . . .135 11.4.3.1 create object . . . . . . . . . . .135 11.4.3.2 supports. . . . . . . . . . . . . .135 11.5 module Common Object Services - Naming. . . . . .135 11.5.1 interface NamingContext . . . . . . . . .136 11.5.1.1 bind. . . . . . . . . . . . . . . .136 11.5.1.2 bind context. . . . . . . . . . . .136 11.5.1.3 bind new context. . . . . . . . . .137 11.5.1.4 list. . . . . . . . . . . . . . . .137 11.5.1.5 new context . . . . . . . . . . . .138 11.5.1.6 resolve . . . . . . . . . . . . . .138 11.5.1.7 destroy . . . . . . . . . . . . . .139 11.5.1.8 rebind . . . . . . . . . . . . . .139 11.5.1.9 rebind_context . . . . . . . . . .139 11.5.1.10 unbind . . . . . . . . . . . . . .140 11.5.2 BindingIterator . . . . . . . . . . . . .140 11.5.2.1 destroy . . . . . . . . . . . . . .140 11.5.2.2 next N. . . . . . . . . . . . . . .140 11.5.2.3 next one. . . . . . . . . . . . . .140 11.6 module Common Object Services - Stream. . . . . .141 11.6.1 interface Streamable. . . . . . . . . . .141 11.6.1.1 external form id Of . . . . . . . .141 11.6.1.2 externalize to stream . . . . . . .141 11.6.1.3 internalize from stream . . . . . .142 11.6.2 interface Streamable Factory. . . . . . .142 11.6.2.1 create uninitialized. . . . . . . .142 11.6.3 interface StreamIO. . . . . . . . . . . .142 11.6.3.1 write string. . . . . . . . . . . .143 11.6.3.2 write char. . . . . . . . . . . . .143 11.6.3.3 write octet . . . . . . . . . . . .143 11.6.3.4 write unsigned long . . . . . . . .143 11.6.3.5 write unsigned short. . . . . . . .144 11.6.3.6 write long. . . . . . . . . . . . .144 11.6.3.7 write short . . . . . . . . . . . .144 11.6.3.8 write float . . . . . . . . . . . .144 11.6.3.9 write double. . . . . . . . . . . .145 11.6.3.10 write boolean. . . . . . . . . . .145 11.6.3.11 read string. . . . . . . . . . . .145 11.6.3.12 read char. . . . . . . . . . . . .145 11.6.3.13 read octet . . . . . . . . . . . .146 11.6.3.14 read unsigned long . . . . . . . .146 11.6.3.15 read unsigned short. . . . . . . .146 11.6.3.16 read long. . . . . . . . . . . . .146 11.6.3.17 read short . . . . . . . . . . . .147 11.6.3.18 read float . . . . . . . . . . . .147 11.6.3.19 read double. . . . . . . . . . . .147 11.6.3.20 read boolean . . . . . . . . . . .148 11.7 module Common Object Services - Externalization .148 11.7.1 interface Stream. . . . . . . . . . . . .148 11.7.1.1 externalize . . . . . . . . . . . .148 11.7.1.2 internalize . . . . . . . . . . . .148 11.7.1.3 flush . . . . . . . . . . . . . . .149 11.7.2 interface Stream Factory. . . . . . . . .149 11.7.2.1 create. . . . . . . . . . . . . . .149 11.7.3 interface File Stream Factory . . . . . .149 11.7.3.1 create. . . . . . . . . . . . . . .149 12 Encapsulated Scheduler API's in Ada . . . . . . . . .152 12.1 Register. . . . . . . . . . . . . . . . . . . . .152 12.2 Execute . . . . . . . . . . . . . . . . . . . . .152 12.3 Set Priority. . . . . . . . . . . . . . . . . . .153 12.4 Resume. . . . . . . . . . . . . . . . . . . . . .153 12.5 Suspend . . . . . . . . . . . . . . . . . . . . .154 12.6 Terminate . . . . . . . . . . . . . . . . . . . .154 12.7 Periodic Rate . . . . . . . . . . . . . . . . . .154 12.8 Periodic Rate End . . . . . . . . . . . . . . . .155 12.9 Timer . . . . . . . . . . . . . . . . . . . . . .155 12.10 Issue Event. . . . . . . . . . . . . . . . . . .155 12.11 Cancel Event . . . . . . . . . . . . . . . . . .155 12.12 Sleep. . . . . . . . . . . . . . . . . . . . . .156 12.13 Wait . . . . . . . . . . . . . . . . . . . . . .156 12.14 Poll . . . . . . . . . . . . . . . . . . . . . .156 12.15 Poll Event . . . . . . . . . . . . . . . . . . .157 12.16 Event Priority . . . . . . . . . . . . . . . . .157 12.17 Event ID . . . . . . . . . . . . . . . . . . . .158 12.18 Event Handler. . . . . . . . . . . . . . . . . .158 12.19 Signal . . . . . . . . . . . . . . . . . . . . .158 12.20 Semaphore Lock . . . . . . . . . . . . . . . . .159 12.21 Semaphore Unlock . . . . . . . . . . . . . . . .159 12.22 Set Time . . . . . . . . . . . . . . . . . . . .159 12.23 Time Scale . . . . . . . . . . . . . . . . . . .160 12.24 Get Time . . . . . . . . . . . . . . . . . . . .160 12.25 Elapsed Time . . . . . . . . . . . . . . . . . .161 12.26 Processing Time. . . . . . . . . . . . . . . . .161 12.27 Date and Time. . . . . . . . . . . . . . . . . .161 12.28 Time Synchronization . . . . . . . . . . . . . .162 12.29 Memory Usage . . . . . . . . . . . . . . . . . .162 12.30 Error Number . . . . . . . . . . . . . . . . . .162 12.31 Error Message. . . . . . . . . . . . . . . . . .163 12.32 Select Manager Routines. . . . . . . . . . . . .163 12.32.1 select add fd. . . . . . . . . . . . . .163 12.32.2 select_delete_fd . . . . . . . . . . . .164 12.32.3 select_add_msg . . . . . . . . . . . . .164 12.32.4 select_delete_msg. . . . . . . . . . . .165 12.32.5 select_add_upcall. . . . . . . . . . . .165 12.32.6 select delete upcall . . . . . . . . . .165 12.32.7 select_wait. . . . . . . . . . . . . . .165 12.32.8 select_wait_all. . . . . . . . . . . . .166 12.33 File Input/Output. . . . . . . . . . . . . . . .166 12.33.1 Ada types. . . . . . . . . . . . . . . .166 12.33.2 create . . . . . . . . . . . . . . . . .166 12.33.3 open . . . . . . . . . . . . . . . . . .167 12.33.4 open or create . . . . . . . . . . . . .167 12.33.5 truncate . . . . . . . . . . . . . . . .167 12.33.6 get file status. . . . . . . . . . . . .167 12.33.7 is accessible. . . . . . . . . . . . . .168 12.33.8 is file present. . . . . . . . . . . . .169 12.33.9 write. . . . . . . . . . . . . . . . . .169 12.33.10 read. . . . . . . . . . . . . . . . . .169 12.33.11 seek. . . . . . . . . . . . . . . . . .169 12.33.12 file position . . . . . . . . . . . . .169 12.33.13 close . . . . . . . . . . . . . . . . .169 12.33.14 get error code. . . . . . . . . . . . .170 13 Diagnostics . . . . . . . . . . . . . . . . . . . . . .171 Appendix A Acronyms. . . . . . . . . . . . . . . . . . . .172 APPENDIX B - CORBA API's not implemented . . . . . . . . .173 Appendix C - Legal Information. . . . . . . . . . . . . .181 Booch Components . . . . . . . . . . . . . . . . . . .181 Appendix D - Ada components. . . . . . . . . . . . . . .183 String Sequential Bounded Managed Iterator . . . . . .183 String Sequential Unbounded Managed Iterator . . . . .185 CORBA_Sequences_Basic_Bounded_Managed_Iterator . . . .187 CORBA_Sequences_Basic_Unbounded_Managed_Iterator . . .189 1 Introduction Lockheed Martin has developed a software infrastructure called Information Manager to handle data management in a distributed environment. This development is based on two industry standards: CORBA 2.0 for distributed object management and communications, and ODMG 1.2 for the database implementation. Both of these standards specify a set of application programming interfaces (API's) and a formal design language (CORBA's Interface Design Language and ODMG 1.2 Object Design Language). Also, Lockheed Martin has developed a library of software functions called Encapsulated Scheduler. The Encapsulated Scheduler provides functions for some operating system services. These functions form a standardized layer between application code and the underlying operating system. 1.1 Document Identification Volume II of this document provides the application programmer with reference information needed to develop and maintain real-time applications using the Information Manager (IM) and Encapsulated Scheduler (ES) developed by Lockheed Martin. Refer to this volume for a detailed explanation of how to use each function. Volume I of this document provides guidance on how to use the IM and ES. See volume I for examples. 1.2 Scope 1.2.1 Configurations Supported The ORB is supported for the following configurations: development system compiler target runtime system DEC Alpha / Digital UNIX 3.2 native C DEC DEC Alpha / Digital UNIX 3.2 Rational Ada Self Compiler 6.2 DEC 1 SPARC / Solaris 2.5 Rational Ada Sun Cross PowerPC LynxOS Compiler Cetia 604/601 LynxOS RS/6000 AIX 3.2 xlc Rational Ada Self Compiler 6.2 RS/6000 AIX 3.2 (no threads) RS/6000 AIX 4.1 glc LynxOS 2.3.1 RS/6000 AIX 4.1 xlc RS/6000 AIX 4.1 Cetia 604/601 LynxOS gcc Cetia 604/601 LynxOS 1.3 Document Overview Section 3 presents the IDL/ODL Section 4 presents the IDL/ODL preprocessor and the OQL preprocessor. Sections 5 through 8 form a sub-volume for the C programmer. Section 5 presents IDL/ODL mapping to C. Section 6 presents Database API's in C. Section 7 presents Object Request Broker API's in C. Section 8 presents Encapsulated Scheduler API's in C. Sections 9 through 12 form a sub-volume for the Ada programmer. Section 9 presents IDL/ODL mapping to Ada. Section 10 presents Database API's in Ada. Section 11 presents Object Request Broker API's in Ada. Section 12 presents Encapsulated Scheduler API's in Ada. Section 13 presents Diagnostics. Appendix A contains acronyms. Appendix B contains a list of CORBA functions which have not been implemented. Appendix C contains legal information. Appendix D contains COTS Ada component specs. 2 Applicable Documents The following documents are relevant: 2.1 Specifications The Common Object Request Broker Architecture and Specification, OMG Document, Revision 2.0 July, 1995 CORBAservices: Common Object Services Specification, OMG Document Number 95-3-31, Revised Edition March 31, 1995 Common Facilities Architecture, OMG Document, Revision 4.0 November 1995 2.2 Standards Reference Manual for the Ada Programming Language (ANSI/MIL-STD 1815A) United States Department of Defense 1983 The Object Database Standard: ODMG - 93, Release 1.1, 1.2 edited by R Cattell 2.3 Other Publications The Essential CORBA, by Thomas J. Mowbray and Ron Zahavi The Essential Distributed Objects Survival Guide, by Robert Orfali, Dan Harkey, Jeri Edwards Object Databases The Essentials, by Mary E. S. Loomis OMG Request for Comment Submission IDL => Ada language Mapping Specification OMG Document 95-5-16 Version 1.1 June 27,1995 Object Oriented Modeling and Design by James Rumbaugh Prentice Hall, 1991 3 Interface Definition Language/Object Definition Language (IDL/ODL) In the chapter 3 of the CORBA 2.0 specification, the Object Management Group (OMG) defines a high level language called Interface Definition Language (IDL). In the ODMG-93 document, the Object Database Management Group (ODMG) added features to IDL and called the result Object Definition Language (ODL). We support a subset of IDL and ODL which will be presented here. IDL/ODL is not intended to be a full programming language. It's purpose is to specify interface signatures. 3.1 Comments There are two forms of comments in IDL/ODL, as shown in the following example: // this is a single line comment /* <- start comment section this comment can span multiple lines end comment section -> */ 3.2 Identifiers An IDL/ODL identifier consists of alphabetic (A..Z, a..z) and numeric (0..9) characters, and may include the underscore character (__). There is no restriction on the length of an identifier. Identifiers must begin with an alphabetic character. Identifiers are case sensitive, but two identifiers that differ only in case cannot appear in the same scope. 3.3 Literal Values A value such as 1 occurring in an IDL/ODL definition is known as a literal value. A literal value has an associated type. Integer values may be specified as decimal, octal, or hexadecimal. For example, the decimal number 18 can be written as: 18 // decimal 022 // octal 0x12 // hexadecimal A floating point literal can be written in either decimal or scientific notation: 0.00012 1.2e-4 A character literal is written by enclosing a character in single quotes: `A' `$' A string literal is written by enclosing a sequence of characters in double quotes: "A quick fox jumps over the lazy brown dog.\n" Non-printable characters can be represented by escape sequences: newline \n horizontal tab \t vertical tab \v backspace \b carriage return \r form feed \f alert \a backslash \\ question mark \? single quote \' double quote \" octal number \o14 hexadecimal num \x0C 3.4 Name Scope Every IDL/ODL identifier must be unique within a scope, but an identifier may be reused in distinct scopes. The following structures represent distinct scopes: module, interface, structure, union, operation and exception. 3.5 Module Declaration A module is a logical unit containing interfaces and other type definitions. A module consists of the keyword module followed by the module name. The body of the module is contained in braces, punctuated by a semicolon: // IDL module Avionic // module header contains name { // module body follows interface Tracker { . . . }; interface Nav{ . . . }; }; // end of module body 3.6 Interface Declaration An interface describes a client's view of an object. An interface lists the object's attributes and specifies operations on the object. An interface consists of the keyword interface followed by the interface name. The body of the interface is contained in braces, punctuated by a semicolon: interface Tracker // interface header contains name { // interface body follows ... }; // end of interface body 3.6.1 ODL Type Property List ODL adds al type property list to the interface declaration. The type property list includes the following information: extent, key, persistence. 3.6.1.1 ODL Extent declaration An extent definition within the type property list provides a means of specifying the interface as an extent within a database. For example: interface Tracker ( extent "Sighting" ) // 'extent' keyword flags this as ODL. Name matches element structure. { struct Sighting // element structure { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Tracker_List; // single attribute }; Constraints Note the following constraints on ODL definitions: The name following the keyword extent must be the name of the element structure, in double quotes. An ODL interface can have no more than one attribute. The attribute will be a collection type (List or Array). The name of the attribute should be the name of the interface prepended to the collection type (List or Array). For example, in the above definition the attribute was named Tracker_List because the interface is named Tracker and the collection type is List. 3.6.1.2 ODL Key Declaration A key definition within the type property list provides a means of specifying the fields within the element structure which uniquely identify an element. Use either the word key or the word keys followed by a list of field names. Currently, the definition of key fields within the type property list is ignored by the IDL/ODL preprocessor. For example: interface Tracker ( extent "Sighting" key ID ) // 'key' keyword indicates ID is used to identify Sighting { struct Sighting // element structure { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Track_List; // single attribute }; // end of interface body 3.6.1.3 ODL Persistence Declaration Persistence is indicated in the type property list by using the keyword persistent or the keyword transient. Currently, the persistence definition within the type property list is ignored by the IDL/ODL preprocessor. For example: interface Tracker ( extent "Sighting" ) : persistent // 'persistent' keyword flags this as a persistent object { struct Sighting { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Track_List; // single attribute }; 3.7 Attribute Declaration An interface may specify a number of attributes which serve to describe the properties of an object. Attributes are declared with the keyword attribute, followed by the attribute type and attribute name. An attribute can be qualified by the readonly keyword. 3.7.1 IDL Attribute Example interface Radar // interface header contains name { // interface body follows attribute float Frequency; attribute string Operating_Mode; readonly attribute string Serial_Number; }; // end of interface body Constraints Currently IDL attributes are supported for Ada but not for C. 3.7.2 ODL Attribute Example interface Tracker ( extent "Sighting" ) { struct Sighting { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Tracker_List; // single attribute }; Constraints Note the following constraints on ODL definitions: The name following the keyword extent must be the name of the element structure, in double quotes. An ODL interface can have no more than one attribute. The attribute will be a collection type (List or Array). The name of the attribute should be the name of the interface prepended to the collection type (List or Array). For example, in the above definition the attribute was named Tracker_List because the interface is named Tracker and the collection type is List. 3.8 ODL Memory Model Declaration For an ODL interface declaration, the database memory model is declared by specifying one of two methods: void mem_model_remote(); /* client and server communicate via ORB */ /* client and server can be local or remote */ or void mem_model_direct(); /* client and server share memory */ /* client must invoke CreateSharedMemory */ The IDL preprocessor will propagate the memory model in the client code it produces. See Memory Model Overview in Volume 1. 3.8.1 Remote Memory Model ODL Example interface Tracker (extent "Sighting") { struct Sighting { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Track_List; void mem_model_remote(); }; 3.8.2 Direct Memory Model ODL Example interface Track (extent "Sighting") { struct Sighting { long ID; float Latitude; float Longitude; float Heading; float Velocity; }; attribute List Track_List; void mem_model_direct(); }; 3.9 IDL Exception Declaration An exception declaration allows a data structure to be declared which may be used to indicate an exceptional condition has occurred during the performance of a request. For example, an exception can be specified as follows: // IDL exception Reject { string Reason; }; 3.10 IDL Operation Declaration An operation is a function that may be applied to an object. Operations are part of an interface body. For example: interface Radar { // interface body void Calibrate(); // operation on a Radar object boolean Built_In_Test(); // operation on a Radar object }; // end of interface body Constraints Currently IDL operations are supported for Ada but not for C. 3.10.1 IDL Parameter Declaration An operation may specify one or more parameters, which appear within parentheses following the operation name. Parameters are separated by commas. Each parameter must specify a passing mode (in, out, or inout), a type, and a name. For example: interface Radar { // interface body void Dwell(in float Frequency, in float Duration); void Ping(in float Frequency, inout float Amplitude); void Built_In_Test (out string Result); }; // end of interface body 3.10.2 IDL Raises Expression An operation may include a raises expression which indicates which exceptions may be raised by the operation. For example: interface Radar { // interface body exception Frequency_Out_Of_Range {}; exception Equipment_Failure { string Details; } void Dwell(in float Frequency, in float Duration) raises (Frequency_Out_Of_Range, Equipment_Failure); }; // end of interface body 3.11 Type Definition An interface may include type definitions for structures, enumerations and strings. For example: interface Radar { // interface body typedef struct Range // this is a new type { float Maximum, float Minimum }; void Scan(in Range); // the new type is used here }; // end of interface body 3.12 Constant Declarations IDL constants may be declared at module or interface scope. A constant is indicated by the keyword const. For example: module Avionic { const float Lower_Limit 60.0e0; const float Upper_Limit 60.0e5; interface Radar { . . . }; interface Navigation { . . . }; }; 4 Preprocessors 4.1 idlpp - Interface Definition Language (IDL) / Object Definition Language (ODL) Preprocessor CORBA 2.0 IDL is a subset of ODMG 1.2 ODL. That is, there are keywords in ODL which do not appear in IDL. However, we have built a single preprocessor named idlpp which processes both IDL and ODL. The IDL/ODL preprocessor, idlpp, produces server skeleton and client stub code. For example, for an IDL file named rcvr.idl we would enter the following command: idlpp rcvr.idl The preprocessor then responds: Enter c or ada for output format: If you want to avoid the prompt, you can directly invoke idlpp_ada or idlpp_c in place of idlpp in the command given above. When the language is specified as c, three files are produced: a header file named rcvr.h a client stub file named rcvr_c.c a server skeleton file named rcvr_s.c When the language is specified as ada, these files are produced: a client spec file named rcvr.ads a client body stub file named rcvr.adb a server spec file named rcvr_impl.ads a server body skeleton file named rcvr_impl.adb for global definitions, if any rcvr_def.ads 4.1.1 Preprocessor Limitations The IDL/ODL preprocessor, idlpp, parses IDL and ODL files to produce C or Ada source code. The following subset of IDL is currently supported: 4.1.1.1 Supported Features Module specification Interface specification Basic Types: integer (long, short, unsigned long, and unsigned short) floating point (float and double) character (char) boolean (boolean) byte data (octet) CORBA any (any) constructed (struct) strings (string) 1-dimension arrays within a structure ([n]) List Array Typedefs work for structures, enumerations, and strings. Operation declarations using parameters of the above types are supported for Ada. Automatic generation of Set and .._Of routines for attributes is supported for Ada. (A work around for C would be to manually add get and set methods to the _c.c and _s.c files matching the functions which are generated by idlpp for the .h file.) Exception expressions (raises ...) are supported. 4.1.1.2 Features Not Supported Mappings to C++, Dynamic Invocation Interface (DII) and the Dynamic Server Skeleton production are not supported. Inheritance is not currently implemented. It can be worked around by duplicating the IDL/ODL in the receiving interface. Type checking is not performed to verify that constant expression operations are being performed on the same operand types. (i.e. CORBA 2.0 Paragraph 3.7.2 Semantics rules have not been implemented.) An array cannot be passed as an argument. A work-around is to declare the array as an element in a structure since structures are supported. Discriminated unions are not supported. Nested sequences are not supported. Sequences and structures do not support any, string, and other pointer members. The operation "oneway" attribute is not supported. Context expressions are not supported. Name specification from the naming scope of the file (i.e. ::ifname)has not been implemented. ODL keywords Set, Sequence, Bag, key, persistent. 4.1.1.3 Other Limitations IDL/ODL files that contain Preprocessor directives (#include, #pragma, ...) must be run through the C Preprocessor (cpp) prior to being passed in to the IDL/ODL Preprocessor. 4.2 oqlpp - Object Query Language (OQL) Preprocessor ODMG-93 defines an object query language (OQL) which is an extension of SQL. OQL is a superset of SQL with extensions for object-oriented concepts. OQL allows us to query interface objects. The OQL preprocessor oqlpp processes OQL definition files. 4.2.1 Preprocessor Limitations Currently, it is assumed that there will be a single OQL definition file for all named queries. All named queries are implemented in the file NamedQueryDefs.c which is completely overwritten when outputs are generated by oqlpp. Only a subset of OQL is supported in order to achieve real-time performance goals. See query examples in directory ./preprocessors/examples/oql. 5 IDL/ODL mapping to C IDL/ODL references types which map to a specific definition in C. 5.1 IDL Atomic types IDL/ODL C mapping Long CORBA_long Short CORBA_short Unsigned long CORBA_unsigned_short Unsigned short CORBA_unsigned_long Float CORBA_float Double CORBA_double Boolean CORBA_boolean Octet CORBA_octet Char CORBA_char String CORBA_string Enum<> CORBA_enum Any typedef struct CORBA_any { CORBA_TypeCode _type; void * _value; } 5.2 IDL sequence<> Refer to CORBA 2.0 chapter 14.11 'Mapping for sequence types' for a description of how IDL sequence types map to C struct types. 5.3 ODL Collection types A collection is a templated type; the elements of a collection are of a type specified by the programmer. Collections can be limited in size or unbound. The IDL/ODL preprocessor supports the following collections: Array and List. An iterator is a pointer which can be used to visit every member of a collection. A collection may or may not have an iterator, depending on the number of items in the collection. 5.3.1 iterator functions For a collection in an ODL interface named InterfaceName, the following iterator functions are generated: CORBA_boolean InterfaceName_Iterator_same_as ( CORBA_Object o, iterator * iterator_ptr_a, iterator * iterator_ptr_b, CORBA_Environment * ev ); iterator * InterfaceName_Iterator_copy ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); void InterfaceName_Iterator_delete ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_Iterator_next ( CORBA_Object o, CORBA_any * any_ptr, iterator * iterator_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_Iterator_first ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_Iterator_last( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_Iterator_not_done ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); void InterfaceName_Iterator_advance ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_Iterator_get_element ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); iterator * InterfaceName_Iterator_reset ( CORBA_Object o, iterator * iterator_ptr, CORBA_Environment * ev ); 5.3.2 collection type definition A type named collection is defined in the header file db_parms_t.h as follows: static struct pll_struct_type { int object_type; /* object type identifier */ char collection_name[33]; /* collection name string */ dblink *PCL; /* Pointer to current link */ dblink *PHEAD; /* Pointer to head of list */ dblink *PTAIL; /* Pointer to tail of list */ int LISTLENGTH; /* Number of links in list */ iterator *IT_PCL; /* iterator pointing to current link */ iterator *IT_PHEAD; /* head of iterator pointer list */ iterator *IT_PTAIL; /* tail of iterator pointer list */ int IT_LENGTH; /* Number of links in iterator list */ } pll_struct; typedef struct pll_struct_type collection; 5.3.3 Array functions The C functions generated for an ODL Array will be presented using this simple ODL excerpt: interface InterfaceName (extent "ItemType" ) { struct ItemType { int element1; int element2; }; attribute Array InterfaceName_Array; }; The ODL definition presented above will generate the following definitions in a header file: typedef struct InterfaceName_ItemType { InterfaceName_int element1; InterfaceName_int element2; } InterfaceName_ItemType; static CORBA_unsigned_long InterfaceName_num_elements = 0; CORBA_boolean InterfaceName_Array_same_as ( CORBA_Object o, collection * collection_ptr_a, collection * collection_ptr_b, CORBA_Environment * ev ); collection * InterfaceName_Array_copy ( CORBA_Object o, char * new_name, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_Array_delete ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_unsigned_long InterfaceName_Array_cardinality ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_Array_is_empty ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_Array_contains_element ( CORBA_Object o, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); iterator * InterfaceName_Array_create_iterator ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); collection * InterfaceName_Array_create ( CORBA_Object o, char * new_name, CORBA_unsigned_long num_elements, CORBA_Environment * ev ); void InterfaceName_Array_replace_element_at ( CORBA_Object o, CORBA_unsigned_long index, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_Array_remove_element_at ( CORBA_Object o, CORBA_unsigned_long index, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_Array_retrieve_element_at ( CORBA_Object o, CORBA_unsigned_long index, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_Array_resize ( CORBA_Object o, CORBA_unsigned_long new_size, collection * collection_ptr, CORBA_Environment * ev ); collection * InterfaceName_Array_remote_copy ( CORBA_Object o, COLLECTION_OP * CollOpStruct_ptr, CORBA_Environment * ev ); 5.3.4 ODL List<> The C functions generated for an ODL List will be presented using this simple ODL excerpt as an example: interface InterfaceName (extent "ItemType" keys KeyName) : persistent { struct ItemType { int element1; int element2; }; attribute List InterfaceName_List ; }; 5.3.4.1 List function definitions The ODL definition presented above will generate the following definitions in a header file: typedef struct InterfaceName_ItemType { InterfaceName_int element1; InterfaceName_int element2; } InterfaceName_ItemType; CORBA_boolean InterfaceName_List_same_as ( CORBA_Object o, collection * collection_ptr_a, collection * collection_ptr_b, CORBA_Environment * ev ); collection * InterfaceName_List_copy ( CORBA_Object o, char * new_name, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_List_delete ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_unsigned_long InterfaceName_List_cardinality ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_List_is_empty ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_boolean InterfaceName_List_contains_element ( CORBA_Object o, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); iterator * InterfaceName_List_create_iterator ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); collection * InterfaceName_List_create ( CORBA_Object o, char * new_name, CORBA_Environment * ev ); void InterfaceName_List_replace_element_at ( CORBA_Object o, CORBA_unsigned_long list_position, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_remove_element_at ( CORBA_Object o, CORBA_unsigned_long list_position, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_retrieve_element_at ( CORBA_Object o, CORBA_unsigned_long list_position, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_List_insert_element_after ( CORBA_Object o, CORBA_any * any_ptr, CORBA_unsigned_long list_position, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_List_insert_element_before ( CORBA_Object o, CORBA_any * any_ptr, CORBA_unsigned_long list_position, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_List_insert_element_first ( CORBA_Object o, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); void InterfaceName_List_insert_element_last ( CORBA_Object o, CORBA_any * any_ptr, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_remove_first_element ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_remove_last_element ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_retrieve_first_element ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); CORBA_any * InterfaceName_List_retrieve_last_element ( CORBA_Object o, collection * collection_ptr, CORBA_Environment * ev ); collection * InterfaceName_List_concat ( CORBA_Object o, char * new_name, collection * collection_ptr_a, collection * collection_ptr_b, CORBA_Environment * ev ); void InterfaceName_List_append ( CORBA_Object o, collection * collection_ptr_a, collection * collection_ptr_b, CORBA_Environment * ev ); collection * InterfaceName_List_remote_copy ( CORBA_Object o, COLLECTION_OP * CollOpStruct_ptr, CORBA_Environment * ev ); 6 Object Database Management API's in C Object Database Management API's are specified in ODMG-93 release 1.2. The C mappings are given here. See section 1 of Volume 1 of this document for a discussion of memory models. 6.1 Interface Database Database API functions are generated in the header file for ODL interface definitions. C header file: dbapisup.h 6.1.1 open Description: The open function opens access to the database for transactions. Constraint: Only a single database may be opened at a time. C specification: void Database_open ( CORBA_Object db, char *name, CORBA_Environment *env ); Argument list for C: db Database object name name of database env environment parameter used for exception data in C 6.1.2 close Description: The close function closes access to a database to complete transactions. C Specification: void Database_close ( CORBA_Object db, CORBA_Environment *env ); Argument list for C: db Database object name name of database env environment parameter used for exception data in C 6.1.3 bind Description: The bind function associates a name with an object in the database. C Specification: void Database_bind( CORBA_Object db, CORBA_any * any_ptr, collection * col_ptr, char * name, CORBA_unsigned_long str_size, CORBA_Environment * env ); Argument list for C: db Database object any_ptr pointer to value to be assigned to object in database If the value is NULL, no assignment is made. col_ptr pointer to collection (list or array) for database request name name of object in database str_size size of buffer for request env environment parameter used for exception data in C 6.1.4 lookup Description: The lookup function is used to find the object with the given name. C specification: CORBA_any * Database_lookup ( CORBA_Object db, char *name, collection *col_ptr, CORBA_unsigned_long str_size, CORBA_Environment *env); Argument list for C: db Database object name name of object in database col_ptr pointer to collection (list or array) for database request str_size size of buffer for request env environment parameter used for exception data in C Output: pointer to value of object in database. 6.1.5 open direct Description: The open_direct function opens access to the database for transactions. This function supports the direct memory model. Constraint: Only a single database may be opened at a time. C specification: void Database_open_direct ( CORBA_Object db, char *name, CORBA_Environment *env ); Argument list for C: db Database object name name of database env environment parameter used for exception data in C 6.1.6 close direct Description: The close_direct function closes access to a database to complete transactions. This function supports the direct memory model. C Specification: void Database_close_direct ( CORBA_Object db, CORBA_Environment *env ); Argument list for C: db Database object name name of database env environment parameter used for exception data in C 6.1.7 bind direct Description: The bind_direct function associates a name with an object in the database. This function supports the direct memory model. C Specification: void Database_bind_direct( CORBA_Object db, CORBA_any * any_ptr, collection * col_ptr, char * name, CORBA_unsigned_long str_size, CORBA_Environment * env ); Argument list for C: db Database object any_ptr pointer to value to be assigned to object in database If the value is NULL, no assignment is made. col_ptr pointer to collection (list or array) for database request name name of object in database str_size size of buffer for request env environment parameter used for exception data in C 6.1.8 lookup direct Description: The lookup_direct function is used to find the object with the given name. This function supports the direct memory model. C specification: CORBA_any * Database_lookup_direct ( CORBA_Object db, char *name, collection *col_ptr, CORBA_unsigned_long str_size, CORBA_Environment *env); Argument list for C: db Database object name name of object in database col_ptr pointer to collection (list or array) for database request str_size size of buffer for request env environment parameter used for exception data in C Output: pointer to value of object in database. 6.2 Interface Transaction In order to avoid deadlock, the IM limits a transaction to the modification of one collection (List or Array) at a time. Deadlock is a condition when two transactions are waiting for each other to unlock resources. 6.2.1 create Description: The create function creates a transaction object. A transaction object must be created before invoking the begin function. C specification: transaction * Transaction_create ( CORBA_Object db, char * name, CORBA_Environment * env ); Argument list for C: db Database object name name of transaction env environment parameter used for exception data in C Output: pointer to the named transaction 6.2.2 begin Description: The begin function starts a transaction. Transactions must be explicitly created and started; they are not automatically created when a database is opened. C specification: void Transaction_begin ( CORBA_Object db, transaction * trn_ptr, CORBA_Environment * env ); Argument list for C: db Database object trn_ptr pointer to transaction env environment parameter used for exception data in C 6.2.3 commit Description: The commit function causes all persistent objects created or modified during this transaction to become accessible to other transactions running against the database in other processes. The transaction instance is deleted and all locks held by that transaction are released. C specification: void Transaction_commit ( CORBA_Object db, transaction * trn_ptr, CORBA_Environment * env ); Argument list for C: db Database object trn_ptr pointer to transaction env environment parameter used for exception data in C 6.2.4 abort Description: The abort operation causes the transaction to be deleted and the database to be returned to the state it was in prior to beginning the transaction. All locks held by the transaction are released. C specification: void Transaction_abort ( CORBA_Object db, transaction * trn_ptr, CORBA_Environment * env ); Argument list for C: db Database object trn_ptr pointer to transaction env environment parameter used for exception data in C 6.2.5 checkpoint Note: Not yet implemented. Description: The checkpoint operation writes all modified objects to the database and retains all locks held by the transaction. It does not delete the transaction object. C Specification: void Transaction_checkpoint ( CORBA_Object db, transaction * trn_ptr, CORBA_Environment * env ); Argument list for C: db Database object trn_ptr pointer to transaction env environment parameter used for exception data in C 6.3 remote copy The remote_copy API has been added to IM/ES to make it easier to move data between processes. Description: Copies a collection whose address is "Source" on the Source Database Server to a collection whose address is "Target" on the Target Database Server (whose name appears in tgt_db[]). Copies a subset (the subset being defined as the elements "start_element", "end_element" and all elements in between) of a collection whose address is "Source" on the Source Database Server to a collection whose address is "Target" on the Target Database Server. Creates a collection whose address is "Target" on the Target Database Server if the operation parameter is "create". Replace elements (start_element:end_element) in the collection whose address is "Target" with the elements of the collection whose address is "Source" if the operation parameter is "replace" Appends elements to the collection whose address is "Target" on the Target Database Server from the collection whose address is "Source" on the Source Database Server if the operation parameter is "append". C specification: int remote_copy( CORBA_Object o, struct COLLECTION_OP *CollOpStruct, CORBA_Environment *ev ); INPUT struct COLLECTION_OP *CollOpStruct { collection *Target; collection *Source; char tgt_db[32]; char tgt_ws[32]; int start_element; int end_element; int operation; /* REPLACE_COLLECTION, APPEND_COLLECTION */ /* or CREATE_COLLECTION */ int size; }; OUTPUT: Returns a status indicating the outcome of the copy collection operation. A status of 0 indicates a successful completion, and non-zero status indicates an unsuccessful outcome. 6.4 Shared Memory The direct memory model optimizes time performance by providing shared memory for database client and database server communication. See Memory Management Overview in Volume 1. 6.4.1 create shared memory Description: The CreateSharedMemory function reserves a specified number of fixed-size segments as shared memory. C Specification: void CreateSharedMemory( int maxseg, int segsz, char *sm_ptr); Inputs: maxseg maximum number of segments to allocate segsz size of each segment sm_ptr address of shared memory; if this value is zero, operating system determines address. 6.4.2 remove shared memory Description: The RemoveSharedMemory function annuls the results of the CreateSharedMemory function. C Specification: void RemoveSharedMemory(); 6.4.3 Allocate Shared Memory The Allocate Shared Memory API "allocates" a block of contiguous shared memory segments (the size of which are specified by the call to the CreateSharedMemory API). The format of the call to this API is similar to that of "malloc". C Specification: struct SEGMENT * smalloc (int length); Inputs: length number of shared memory segments to allocate Output: Returns a pointer to the beginning of the allocated segment in shared memory. 6.4.4 Free Shared Memory The Free Shared Memory API "frees" a block of contiguous shared memory segments in shared memory which were allocated via the "smalloc" API. The format of the call to this API is similar to that of "free". C Specification: void sfree (struct SEGMENT * ptr); Input: ptr a pointer to the beginning of the allocated segment in shared memory Output: - none 6.4.5 Copy to/from Shared Memory The Shared Memory Copy API copies data to or from shared memory. The format of the call to this API is similar to that of "memcpy". C Specification: void smemcpy ( char * target, char * source, int n_bytes ) Inputs: target address to where the data will be copied. source address from where the data will be copied. n_bytes number of bytes (characters). Output: - none 7 Object Request Broker APIs in C This section contains definitions of the services supported by the Object Request Broker (ORB), according to the specifications of CORBA 2.0, July 1995. When an IDL/ODL file is passed through the preprocessor, references to these APIs will be generated. For each API, a brief description is followed by a mapping to C. For mappings to Ada, see section 11. 7.1 module CORBA In C, a CORBA_Environment argument is used to pass exception information. 7.1.1 interface ORB 7.1.1.1 BOA Initialization Description: The BOA_init routine will create and initialize a Basic Object Adapter to be associated with the calling thread. The upcall table will also be initialized. When the ORB invokes a server implementation, that's refered to as an upcall. Constraints: Call this routine once per thread. C header file: orb.h C specification: CORBA_BOA CORBA_ORB_BOA_init (CORBA_ORB orb, int *argc, char **argv, CORBA_ORB_OAid boa, CORBA_Environment *env); Argument list for C: orb ORB returned from CORBA_ORB_init argc number of items in argv = 0 argv character string (not used; set to null) boa object adapter identifier. The BOA is defined as "LMOA". env CORBA environment variable, used to pass exception information. Output: Basic Object Adapter reference 7.1.1.2 initialization Description: The ORB_init routine will register the caller's ASE name, port, and priority with the encapsulated scheduler. It will also create and initialize an ORB object to be associated with the calling thread. Constraints: Call this routine once per thread. ORB_init has one mandatory input argument - the ASE name: "-ORBase wwww ". The arguments port, default port, and priority are optional. C header file: orb.h C specification: CORBA_ORB CORBA_ORB_init(int *argc, char *argv[], CORBA_string orb_id, CORBA_Environment *env) Argument list for C: argc a count of the number of strings in argv argv an array of strings of the format -KEY name, as follows: " -ORBase wwww " (where wwww is the ASE name of the calling process) " -ORBport xxxx " (where xxxx is the port selected for this thread) " -ORBdefport yyyy " (where yyyy is the default port selected for this thread) " -ORBprty zzzz " (where zzzz is the priority level for this process) -ORBase is required; other -KEY arguments in argv are optional. orb_id identification of the ORB. The ORB is defined as "LMORB". env CORBA environment variable, used to pass exception information. Output: ORB object reference 7.1.1.3 list initial services Description: The list_initial_services routine will read ORB services listed in the file initref.cfg. Constraints: none C specification: CORBA_ORB_ObjectIdList * CORBA_ORB_list_initial_services ( CORBA_ORB orb, CORBA_Environment *env) Argument list for C: orb ORB returned from CORBA_ORB_init env CORBA environment variable, used to pass exception information. Output: A CORBA_ORB_ObjectIdList which is a sequence where each item on the list is a blank- delimited string containing: Identifier. 7.1.1.4 object to string Description: The object_to_string function returns a character string which represents the object passed in. This allows the application to store an object reference in an external media, such as a database. The object reference can be retrieved from the string by the string_to_object function. C specification: CORBA_string CORBA_ORB_object_to_string(CORBA_ORB orb, CORBA_Object object, CORBA_Environment *env) { Argument list for C: orb ORB returned from CORBA_ORB_init obj object reference env CORBA environment variable, used to pass exception information. Output: character string representing the Object reference. 7.1.1.5 resolve initial references Description: The resolve_initial_references routine will provide a reference object for an ORB service, such as NameService. C header file: orb.h C specification: CORBA_Object CORBA_ORB_resolve_initial_references ( CORBA_ORB orb, CORBA_ORB_ObjectId identifier, CORBA_Environment *env) Argument list for C: orb ORB returned from CORBA_ORB_init identifier character string identifying the service object env CORBA environment variable, used to pass exception information. Output: object reference 7.1.1.6 string to object Description: The string_to_object function returns an object reference for a given character string; the string must be obtained from the object_to_string function originally. If the object already exists, then its reference count is incremented. Otherwise, the object is created. If a null string is passed in, a null pointer is returned. If a parsing error occurs, a BAD_PARAM exception is raised. C specification: CORBA_Object CORBA_ORB_string_to_object(CORBA_ORB orb, CORBA_string str, CORBA_Environment *env) Argument list for C: orb ORB returned from CORBA_ORB_init str string representing the object, obtained from object_to_string env CORBA environment variable, used to pass exception information. Output: Object reference. 7.1.2 interface Object 7.1.2.1 duplicate Description: The duplicate function allows an application to obtain a copy of an object reference. If the object exists, its reference count is incremented. If the object doesn't exist, an OBJECT_NOT_EXIST exception is raised. C specification: CORBA_Object CORBA_Object_duplicate (CORBA_Object obj, CORBA_Environment *env) Argument list for C: obj object reference env CORBA environment variable, used to pass exception information. Output: Object reference. 7.1.2.2 is equivalent Description: The is_equivalent function will return TRUE if the two object references passed in are equal. Otherwise it will return FALSE. If the first object does not exist, an OBJECT_NOT_EXIST exception will be raised. C specification: CORBA_boolean CORBA_Object_is_equivalent(CORBA_Object obj, CORBA_Object other, CORBA_Environment *env) Argument list for C: obj first object reference other other object reference env CORBA environment variable, used to pass exception information. Output: TRUE or FALSE. 7.1.2.3 is nil Description: The function is_nil returns TRUE if the object passed in has a value of OBJECT_NIL. Otherwise it will return FALSE. If the object does not exist, an OBJECT_NOT_EXIST exception will be raised. C specification: CORBA_boolean CORBA_Object_is_nil(CORBA_Object obj, CORBA_Environment *env) Argument list for C: obj object reference env CORBA environment variable, used to pass exception information. Output: TRUE or FALSE 7.1.2.4 release Description: The release function is used to release a copy (from a prior duplicate) of an object descriptor. If the object does not exist, an OBJECT_NOT_EXIST exception will be raised. If it is called when the reference count is one, a BAD_INV_ORDER exception is raised since CORBA_BOA_dispose should be called in that case. C specification: void CORBA_Object_release(CORBA_Object obj. CORBA_Environment *env) Argument list for C: obj object reference env CORBA environment variable, used to pass exception information. Output: none. 7.1.2.5 non existent Description: The non_existent function tests whether an object (proxy obj) has been destroyed without invoking any application level operation on the object. So, it will never affect the object itself. If the object does not exist, it returns TRUE else it returns FALSE. C specification: CORBA_boolean CORBA_Object_non_existent (CORBA_Object obj, CORBA_Environment *env) Arguments for C: obj the object for which an implentation definition is requested. env CORBA environment variable, used to pass exception information Output: TRUE if object does not exist; FALSE if object exists. 7.1.2.6 hash Description: The hash function returns a hash value for an object. The hash value will be in the range (o.. max), where max is passed in. The hash value for an object does not change during the lifetime of the object reference. The hash value of an object is not guaranteed to be unique, but if two objects return a different hash value, they are not identical. See CORBA 7.2.6 for a more detailed explanation. C specification: CORBA_unsigned_long CORBA_Object_hash (CORBA_Object obj, CORBA_unsigned_long max, CORBA_Environment *env); Arguments for C: obj Object to be hashed max maximum hash value env CORBA environment variable, used to pass exception information Output: a hash value in the range 0..max. 7.1.2.7 get implementation Description: The get_implementation function returns the definition of the implementation of an object. See CORBA 7.2.1 for a more detailed explanation. C specification: CORBA_ImplementationDef CORBA_Object_get_implementation (CORBA_Object obj, CORBA_Environment *env) Arguments for C: obj the object for which an implentation definition is requested. env CORBA environment variable, used to pass exception information Output: pointer to a structure which describes the object implementation. ImplementationDef is defined as follows: typedef struct { CORBA_string InterfaceName; /* Interface type of object */ CORBA_Upcall_Ptr Upcall_address; /* Object's upcall routine */ } CORBA_Implementation; typedef CORBA_Implementation *CORBA_ImplementationDef; 7.1.3 interface Basic Object Adapter (BOA) An Object Adapter defines most of the services from the ORB which an object implementation (server) can depend on. CORBA's Basic Object Adapter (BOA) specifies a set of basic services; the IM implements a subset of these services. See chapter 8 of 'The Common Object Request Broker: Architecture and Specification' Revision 2.0, July 1995. 7.1.3.1 create Description: The create function generates an object reference. If the implementation has a null interface name then a BAD_PARAM exception is raised. C specification: CORBA_Object CORBA_BOA_create (CORBA_Object boa, CORBA_ReferenceData ref, CORBA_InterfaceDef int, CORBA_ImplementationDef imp, CORBA_Environment *env) Argument list for C: boa BOA object returned from CORBA_ORB_BOA_init ref reference data int interface definition - null (Interface Repository not implemented) imp implementation definition (see C definition below). Contains the interface name and the address of the upcall entry point. env CORBA environment variable, used to pass exception information. typedef struct { CORBA_string InterfaceName; /* Interface name */ CORBA_Upcall_Ptr Upcall_address; /* pointer to upcall function */ /* which is typically null on create */ } CORBA_ImplementationDef; Output: a new object reference 7.1.3.2 dispose Description: The dispose function removes an object previously generated with a call to CORBA_BOA_create. The memory is freed. C specification: void CORBA_BOA_dispose (CORBA_Object boa, CORBA_Object obj, CORBA_ImplementationDef imp, CORBA_Environment *env) Argument list for C: boa BOA object returned from CORBA_ORB_BOA_init obj object reference imp implementation definition (see CORBA_BOA_create). Not used in IM. env CORBA environment variable, used to pass exception information. Output: none 7.1.3.3 get id Description: The get_id function returns reference data. If the object passed in is NULL, a BAD_PARM exception is raised. C specification: CORBA_ReferenceData CORBA_BOA_get_id (CORBA_Object boa, CORBA_Object obj, CORBA_Environment *env) Argument list for C: boa BOA object returned from CORBA_ORB_BOA_init obj object for which we want the ID env CORBA environment variable, used to pass exception information. Output: Reference data (object ID). 7.1.3.4 implementation is ready Description: The impl_is_ready function is called by *__BOA_init server stubs. This function informs the BOA that initialization is complete. The BOA will then attempt to initialize the interface. If a socket is not available, a NO_RESOURCE exception is raised. If a timeout occurs, a COMM_FAILURE exception is raised. If socket cannot be created, an INTERNAL_ERROR exception is raised. C specification: void CORBA_BOA_impl_is_ready (CORBA_Object boa, CORBA_ImplementationDef imp, CORBA_Environment *env) Argument list for C: boa BOA object returned from CORBA_ORB_BOA_init imp implementation definition (see CORBA_BOA_create paragraph) env CORBA environment variable, used to pass exception information. Output: none 7.1.3.5 set exception Description: The set_exception function will register an exceptional condition in the environment. C specification: void CORBA_BOA_set_exception(CORBA_Object boa, enum CORBA_exception_type major, CORBA_string userid, void * param, CORBA_Environment * env) Argument list for C: boa BOA object returned from CORBA_ORB_BOA_init major one of an enumerated list of CORBA exceptions defined in orb.h. userid identifies the exception param pointer to associated data env CORBA environment variable, used to pass exception information. Output: none 7.1.3.6 setsched Description: The setsched function sets the select_wait() priority for the client/server sockets associated with this communication path. This API is an IM extension of CORBA 2.0 to support priority control within the select encapsulation (select_wait()) at the application layer. C specification: void CORBA_BOA_setsched( CORBA_BOA boa, CORBA_long pri, CORBA_long sched_mode, CORBA_Environment *env ); Argument List for C: boa BOA object pri select_wait priority for this server env CORBA environment variable, used to pass exception information. sched_mode controls preemption Valid values for Sched_Mode are: SELECT_NO_PREEMPT : will not service any sockets until the current upcall has completed. SELECT_FIFO : will service sockets with priority higher than current upcall SELECT_ROUND_ROBIN : will service sockets with priority higher or equal to current upcall Output: None 7.1.3.7 preempt Description: The preempt function will allow or disallow the nesting of server upcalls, depending on the flag.This API is an IM extension of CORBA 2.0 to control preemption. C specification: void CORBA_BOA_preempt( CORBA_Object self, CORBA_Boolean flag, CORBA_environment *env); Argument List for C: self BOA object flag TRUE to allow preemption; FALSE to disallow preemption. env CORBA environment variable, used to pass exception information. Output: None 7.1.3.8 create group Description: The create_group function creates a broadcast group object. Interface objects may join or leave a broadcast group. Only one type of interface may be associated with a group. This API is an IM extension of CORBA 2.0 to support broadcast. C specification: CORBA_Object CORBA_BOA_create_group( CORBA_BOA boa, CORBA_boolean reliable, CORBA_float timeout, CORBA_Environment *env ); Argument List for C: boa BOA object reliable if TRUE then broadcast will resend any lost packets via the TCP connection to each server. If a server does not return an acknowledge within the alotted timeout period, then broadcast will disconnect that server and return an error. timeout timeout period, in floating point milliseconds env CORBA environment variable, used to pass exception information. Output: broadcast group object 7.1.3.9 join Description: The join function joins an interface object with a broadcast group. This API is an IM extension of CORBA 2.0 to support broadcast. C specification: void CORBA_BOA_join( CORBA_BOA boa, CORBA_Object obj, CORBA_Environment *env ); Argument List for C: boa BOA object obj broadcast group object env CORBA environment variable, used to pass exception information. Output: None 7.1.3.10 leave Description: The leave function severs an interface object from a broadcast group. This API is an IM extension of CORBA 2.0 to support broadcast. C specification: void CORBA_BOA_leave( CORBA_BOA boa, CORBA_Object obj, CORBA_Environment *env ); Argument List for C: boa BOA object obj broadcast group object env CORBA environment variable, used to pass exception information. Output: None 7.2 module Common Object Services - Event Communication An event is a communication action taken by a single object. There are two types of communication: push and pull. Each type of communication has a supplier and a consumer. A supplier produces event data and a consumer processes event data. When the supplier initiates communication, you can say that the data is pushed. When the consumer initiates communication, you can say that the data is pulled. When the consumer initiates communication, CORBA calls that "consumer pull". The consumer invokes the supplier's EventComm_PullSupplier_pull operation. When the supplier initiates communication, CORBA calls that "supplier push". The supplier invokes the consumer's EventComm_PushConsumer_push operation. Arrow indicates direction of data movement. 7.2.1 register Description: The register function is called to register event communication services. Each of the services (push, pull, try_pull) described in the CosEventComm interfaces must be registered by the user-written server routine which implements the service. This API is an IM extension of CORBA 2.0 to support event communication. C specification: void CosEventComm_register( void (*push)(), CORBA_any *(*pull)(), CORBA_any *(*try_pull)() ); Argument List for C: push application-specific push function pull application-specific pull function try_pull application-specific try_pull function Output: none 7.2.2 interface Pull Consumer A Pull Consumer is a consumer who initiates communication. 7.2.2.1 disconnect pull consumer Description: The disconnect_pull_supplier function breaks off communications with a previously defined pull_supplier object. C specification: void CosEventComm_PullConsumer_disconnect_pull_consumer( CosEventComm_PullConsumer pull_consumer, CORBA_Environment *env ); Argument list for C: pull_consumer pull_consumer object env CORBA environment variable, used to pass exception information. Output: none 7.2.3 interface Pull Supplier A Pull Supplier is a supplier who waits for a consumer to initiate communication. 7.2.3.1 disconnect pull supplier Description: The disconnect_pull_supplier function breaks off communications with a previously defined pull_supplier object. C specification: void CosEventComm_PullSupplier_disconnect_pull_supplier( CosEventComm_PullSupplier pull_supplier, CORBA_Environment *env ); Argument list for C: pull_supplier pull_supplier object env CORBA environment variable, used to pass exception information. Output: none 7.2.3.2 pull Description: The pull function will return event data if event data is available. The pull function will block processing until event data is available. If event communication has already been disconnected, the Disconnect exception is raised. C specification: CORBA_any *CosEventComm_PullSupplier_pull( CosEventComm_PullSupplier pull_supplier, CORBA_Environment *env ); Argument list for C: pull_supplier pull_supplier object env CORBA environment variable, used to pass exception information. Output: event data 7.2.3.3 try pull Description: The try_pull function will return event data and set the has_event flag to TRUE if the event has occurred. The try_pull function will return an undefined value and set the has_event flag to FALSE if the event has not occurred. The try_pull function will not block processing. If event communication has already been disconnected, the Disconnect exception is raised. C specification: CORBA_any *CosEventComm_PullSupplier_try_pull( CosEventComm_PullSupplier pull_supplier, CORBA_boolean *has_event, CORBA_Environment *env ); Argument list for C: pull_supplier pull_supplier object has_event TRUE if event has occurred; FALSE if event has not occurred. env CORBA environment variable, used to pass exception information. Output: event data 7.2.3.4 create Description: The create function creates an instance of a CosEventComm_PullSupplier interface object and associate an application specific pull() and try_pull() methods to it. This API is an IM extension of CORBA 2.0 to support application-specific pull and try_pull methods within an ASE. C specification: CosEventComm_PullSupplier CosEventComm_PullSupplier_create( CORBA_Object obj, CORBA_any *(*pull)(), CORBA_any *(*try_pull)(), CORBA_Environment *env ); Argument List for C: boa BOA object pull address of application-specific pull method try_pull address of application-specific try_pull method env CORBA environment variable, used to pass exception information. Output: None 7.2.4 interface Push Consumer A Push Consumer is a consumer who waits for the supplier to initiate communication. 7.2.4.1 disconnect push consumer Description: The disconnect_push_consumer function breaks off communications with a previously defined push_consumer object. C specification: void CosEventComm_PushConsumer_disconnect_push_consumer( CosEventComm_PushConsumer push_consumer, CORBA_Environment *env ); Argument list for C: push_consumer push_consumer object env CORBA environment variable, used to pass exception information. Output: none 7.2.4.2 push Description: The push function moves data to the consumer of the data. C specification: void CosEventComm_PushConsumer_push( CosEventComm_PushConsumer push_consumer, CORBA_any *data, CORBA_Environment *env ); Argument list for C: push_consumer push_consumer object data pointer to some data env CORBA environment variable, used to pass exception information. Output: none 7.2.4.3 create Description: The create function creates an instance of a CosEventComm_PushConsumer interface object and associate an application specific push() method to it. This API is an IM extension of CORBA 2.0 to support application-specific push methods within an ASE. C specification: CosEventComm_PushConsumer CosEventComm_PushConsumer_create( CORBA_Object obj, void (*push)(), CORBA_Environment *env ); Argument List for C: boa PushConsumer object push address of application-specific push method env CORBA environment variable, used to pass exception information. Output: PushConsumer object 7.2.5 interface Push Supplier A Push Supplier is a supplier who initiates communication. 7.2.5.1 disconnect push supplier Description: The disconnect_push_supplier function breaks off communications with a previously defined push_supplier object. C specification: void CosEventComm_PushSupplier_disconnect_push_supplier( CosEventComm_PushSupplier push_supplier, CORBA_Environment *env ); Argument list for C: push_supplier push_supplier object env CORBA environment variable, used to pass exception information. Output: none 7.3 module Common Object Services - Event Channel Administration An event channel is an object which decouples communications between supplier and consumer. Suppliers produce event data and consumers process event data asynchronously while the event channel acts as an intermediate. A proxy is a legal replacement for an object. For the consumer, the event channel is a proxy supplier. For the supplier, the event channel is a proxy consumer. To Initialize an Event Channel: 1. obtain a proxy using an administrative object 2. connect self to channel using the proxy object For example: to connect a Pull_Consumer to an event channel, first we must obtain a Proxy_Pull_Supplier, and then invoke that Proxy_Pull_Supplier's connect_pull_consumer function. See chapter 4 of the OMG document 'CORBA Services: Common Object Services Specification'. Each of the Proxy interfaces inherits from a CosEventComm interface. 7.3.1 interface Proxy Push Consumer A push supplier needs to define a ProxyPushConsumer type of event channel to receive data. 7.3.1.1 push Description: The push function moves data from the supplier to the consumer of the data, a ProxyPushConsumer type of event channel. C Specification: void CosEventChannelAdmin_ProxyPushConsumer_push( CosEventChannelAdmin_ProxyPushConsumer obj, CORBA_any *data, CORBA_Environment *env ); Argument list for C: obj ProxyPushConsumer object data data to be pushed env CORBA environment variable, used to pass exception information. Output: None. 7.3.1.2 disconnect push consumer Description: The disconnect_push_consumer function breaks off communication with a previously defined ProxyPushConsumer object. C Specification: void CosEventChannelAdmin_ProxyPushConsumer_disconnect_push_consumer( CosEventChannelAdmin_ProxyPushConsumer obj, CORBA_Environment *env ); Argument list for C: obj ProxyPushConsumer object env CORBA environment variable, used to pass exception information. Output: none 7.3.1.3 connect push supplier Description: The connect_push_supplier function defines the second step for connecting a push supplier to a proxy consumer type of event channel. C Specification: void CosEventChannelAdmin_ProxyPushConsumer_connect_push_supplier( CosEventChannelAdmin_ProxyPushConsumer obj, CosEventComm_PushSupplier push_supplier, CORBA_Environment *env ); Argument list for C: obj ProxyPushConsumer object push_supplier PushSupplier type object env CORBA environment variable, used to pass exception information. Output: None 7.3.2 interface Proxy Pull Supplier A pull consumer needs to define a ProxyPullSupplier type of event channel to supply data. 7.3.2.1 pull Description: The pull function moves data from the supplier, a ProxyPullSupplier type of event channel, to the consumer of the data. The pull function will block processing until the event occurs. C Specification: CORBA_any *CosEventChannelAdmin_ProxyPullSupplier_pull( CosEventChannelAdmin_ProxyPullSupplier obj, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object env CORBA environment variable, used to pass exception information. Output: Any type of data. 7.3.2.2 try pull Description: The try_pull function moves data from the supplier, a ProxyPullSupplier type of event channel. to the consumer of the data. If the event has not occurred, the has_event flag will be set to FALSE. The try_pull function will not block processing. C Specification: CORBA_any* CosEventChannelAdmin_ProxyPullSupplier_try_pull( CosEventChannelAdmin_ProxyPullSupplier obj, CORBA_boolean *has_event, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object has_event Flag will be set to FALSE if the event has not occurred (no data). env CORBA environment variable, used to pass exception information. Output: Any type of data. 7.3.2.3 disconnect pull supplier Description: The disconnect_pull_supplier function breaks off communication with a previously defined ProxyPullSupplier object. C Specification: void CosEventChannelAdmin_ProxyPullSupplier_disconnect_pull_supplier( CosEventChannelAdmin_ProxyPullSupplier obj, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object env CORBA environment variable, used to pass exception information. Output: None. 7.3.2.4 connect pull consumer Description: The connect_pull_consumer function defines the second step for connecting a pull consumer to the event channel. C Specification: void CosEventChannelAdmin_ProxyPullSupplier_connect_pull_consumer( CosEventChannelAdmin_ProxyPullSupplier obj, CosEventComm_PullConsumer pull_consumer, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object pull_consumer PullConsumer object env CORBA environment variable, used to pass exception information. Output: none 7.3.3 interface Proxy Pull Consumer A pull supplier needs to define a ProxyPullConsumer type of event channel to consume data. 7.3.3.1 disconnect pull consumer Description: The disconnect_pull_consumer function breaks off communication with a previously defined ProxyPullConsumer object. C Specification: void CosEventChannelAdmin_ProxyPullConsumer_disconnect_pull_consumer( CosEventChannelAdmin_ProxyPullConsumer obj, CORBA_Environment *env); Argument list for C: obj ProxyPullConsumer object env CORBA environment variable, used to pass exception information. Output: None. 7.3.3.2 connect pull supplier Description: The connect_pull_supplier function defines the second step for connecting a pull supplier to the event channel. C Specification: void CosEventChannelAdmin_ProxyPullConsumer_connect_pull_supplier( CosEventChannelAdmin_ProxyPullConsumer obj, CosEventComm_PullSupplier pull_supplier, CORBA_Environment *env); Argument list for C: obj ProxyPullConsumer object pull_supplier PullSupplier object env CORBA environment variable, used to pass exception information. Output: None 7.3.4 interface Proxy Push Supplier A push consumer needs to define a ProxyPushSupplier type of event channel to supply data. 7.3.4.1 disconnect push supplier Description: The disconnect_push_supplier breaks off communication with a previously defined ProxyPushSupplier object. C Specification: void CosEventChannelAdmin_ProxyPushSupplier_disconnect_push_supplier( CosEventChannelAdmin_ProxyPushSupplier obj, CORBA_Environment *env); Argument list for C: obj ProxyPushSupplier object env CORBA environment variable, used to pass exception information. Output: None 7.3.4.2 connect push consumer Description: The connect_push_consumer function defines the second step for connecting a push consumer to the event channel. C Specification: void CosEventChannelAdmin_ProxyPushSupplier_connect_push_consumer( CosEventChannelAdmin_ProxyPushSupplier obj, CosEventComm_PushConsumer push_consumer, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object push_consumer PushConsumer object env CORBA environment variable, used to pass exception information. Output: none. 7.3.5 interface Consumer Administration The ConsumerAdmin interface is used by consumers to obtain proxy suppliers. 7.3.5.1 obtain push supplier Description: The obtain_push_supplier function defines the first step for connecting a push consumer to the event channel. It returns a proxy push supplier. C Specification: CosEventChannelAdmin_ProxyPushSupplier CosEventChannelAdmin_ConsumerAdmin_obtain_push_supplier( CosEventChannelAdmin_ConsumerAdmin obj, CORBA_Environment *env); Argument list for C: obj ConsumerAdmin object env CORBA environment variable, used to pass exception information. Output: A ProxyPushSupplier type object. 7.3.5.2 obtain pull supplier Description: The obtain_pull_supplier function defines the first step for connecting a pull consumer to the event channel. It returns a proxy pull supplier. C Specification: CosEventChannelAdmin_ProxyPullSupplier CosEventChannelAdmin_ConsumerAdmin_obtain_pull_supplier( CosEventChannelAdmin_ConsumerAdmin obj, CORBA_Environment *env ); Argument list for C: obj ProxyPullSupplier object env CORBA environment variable, used to pass exception information. Output: A ProxyPullSupplier type object. 7.3.6 interface Supplier Administration The SupplierAdmin interface is used by suppliers to obtain proxy consumers. 7.3.6.1 obtain push consumer Description: The obtain_push_consumer function defines the first step for connecting a push supplier to the event channel. It returns a proxy push consumer. C Specification: CosEventChannelAdmin_ProxyPushConsumer CosEventChannelAdmin_SupplierAdmin_obtain_push_consumer( CosEventChannelAdmin_SupplierAdmin obj, CORBA_Environment *env ); Argument list for C: obj SupplierAdmin object env CORBA environment variable, used to pass exception information. Output: A ProxyPushConsumer type object. 7.3.6.2 obtain pull consumer Description: The obtain_pull_consumer function defines the first step for connecting a pull supplier to the event channel. It returns a proxy pull consumer. C Specification: CosEventChannelAdmin_ProxyPullConsumer CosEventChannelAdmin_SupplierAdmin_obtain_pull_consumer( CosEventChannelAdmin_SupplierAdmin obj, CORBA_Environment *env); Argument list for C: obj SupplierAdmin object env CORBA environment variable, used to pass exception information. Output: A ProxyPullConsumer type object. 7.3.7 interface Event Channel The EventChannel interface has three operations: 1. It provides for the administration of consumers. 2. It provides for the administration of suppliers. 3. It has an operation to destroy the event channel. 7.3.7.1 for consumers Description: The for_consumers function returns a consumer administration object. C Specification: CosEventChannelAdmin_ConsumerAdmin CosEventChannelAdmin_EventChannel_for_consumers( CosEventChannelAdmin_EventChannel obj, CORBA_Environment *env); Argument list for C: obj EventChannel object env CORBA environment variable, used to pass exception information. Output: A ConsumerAdmin type object. 7.3.7.2 for suppliers Description: The for_suppliers function returns a supplier administration object. C Specification: CosEventChannelAdmin_SupplierAdmin CosEventChannelAdmin_EventChannel_for_suppliers( CosEventChannelAdmin_EventChannel obj, CORBA_Environment *env); Argument list for C: obj EventChannel object env CORBA environment variable, used to pass exception information. Output: A SupplierAdmin type object. 7.3.7.3 destroy Description: The destroy function removes the event channel. C Specification: void CosEventChannelAdmin_EventChannel_destroy( CosEventChannelAdmin_EventChannel obj, CORBA_Environment *env ); Argument list for C: obj EventChannel object env CORBA environment variable, used to pass exception information. Output: None. 7.3.8 interface Event Channel Factory An event channel factory is an object which can create event channels. 7.3.8.1 create event channel Description: The create_eventchannel function returns an event channel object. C Specification: CosEventChannelAdmin_EventChannel CosEventChannelAdmin_EventChannelFactory_create_eventchannel( CosEventChannelAdmin_EventChannelFactory obj, CORBA_long size, CORBA_Environment *env); Argument list for C: obj EventChannelFactory object size number of bytes for event channel buffer env CORBA environment variable, used to pass exception information. Output: An EventChannel type object. 7.4 module Common Object Services - Life Cycle Life Cycle services provide methods for creating, removing, copying and moving objects. 7.4.1 interface Factory Finder A factory is an object which creates another object. Factories are not special objects; any object can be a factory. A factory_finder is an object which will locate factories within the system. Clients pass a factory_finder to the move and copy operations, so that they can find a factory to interact with. 7.4.1.1 find factories Description: The function find_factories will return a list of factories given a factory_finder and a key. If no factory is found, the NoFactory exception will be raised. C header file: lifecycle.h C specification: CosLifeCycle_Factories CosLifeCycle_FactoryFinder_find_factories( CosLifeCycle_FactoryFinder obj, CosLifeCycle_Key *key, CORBA_Environment *env) Argument list for C: obj factory finder object key factory key, which is a CosNaming_Name. See bind_new_context. env CORBA environment variable, used to pass exception information. Output: a sequence of factories. Output type CosLifeCycle_Factories is defined as follows: typedef CORBA_Object CosLifeCycle_Factory; typedef struct { CORBA_unsigned_long _maximum; CORBA_unsigned_long _length; CosLifeCycle_Factory *_buffer; CORBA_boolean _release; } CORBA_sequence_CosLifeCycle_Factory; 7.4.2 interface Life Cycle Object An object which is of class LifeCycleObject has methods to copy, move, and remove itself. 7.4.2.1 copy Description: The function copy will produce a copy of an object, using a factory_finder provided by the application, and criteria for creating the copy. If the factory_finder provided is null, the NoFactory exception is raised. If it isn't possible to create the copy using the criteria given, the NotCopyable exception is raised. C header file: lifecycle.h C specification: CosLifeCycle_LifeCycleObject CosLifeCycle_LifeCycleObject_copy( CosLifeCycle_LifeCycleObject obj, CosLifeCycle_FactoryFinder there, CosLifeCycle_Criteria *criteria, CORBA_Environment *env) Argument list for C: obj the LifeCycleObject object there a factory finder object criteria a sequence of name/value pairs passed to the object constructor env CORBA environment variable, used to pass exception information. Output: a copy of the LifeCycleObject object 7.4.2.2 move Description: The function move will produce a new copy of an object, using a factory_finder provided by the application, and criteria for creating the new copy. The current copy of the object will cease to exist. C specification: void CosLifeCycle_LifeCycleObject_move( CosLifeCycle_LifeCycleObject obj, CosLifeCycle_FactoryFinder there, CosLifeCycle_Criteria *the_criteria, CORBA_Environment *env) Argument list for C: obj the LifeCycleObject object there a factory finder object criteria a sequence of name/value pairs passed to the object constructor env CORBA environment variable, used to pass exception information. Output: none 7.4.2.3 remove Description: The function remove instructs the LifeCycle object to cease to exist. If the object destructor fails, the NotRemovable exception is raised. C specification: void CosLifeCycle_LifeCycleObject_remove( CosLifeCycle_LifeCycleObject obj, CORBA_Environment *env) Argument list for C: obj the LifeCycleObject object env CORBA environment variable, used to pass exception information. Output: none 7.4.3 interface Generic Factory A factory is an object which creates another object. Factories are not special objects; any object can be a factory. 7.4.3.1 create object Description: The function create_object will create an object given a key and a set of criteria. C specification: CORBA_Object CosLifeCycle_GenericFactory_create_object( CosLifeCycle_GenericFactory obj, CosLifeCycle_Key *key, CosLifeCycle_Criteria *the_criteria, CORBA_Environment *env) Argument list for C: obj the generic factory object key the name of the object t