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 to create criteria a sequence of name/value pairs passed to the object constructor env CORBA environment variable, used to pass exception information. Output: The object created by the generic factory. 7.4.3.2 supports Description: The function supports returns TRUE if the generic factory can create an object given a key. C specification: CORBA_boolean CosLifeCycle_GenericFactory_supports( CosLifeCycle_GenericFactory obj, CosLifeCycle_Key *key, CORBA_Environment *env) Argument list for C: obj the generic factory object key the name of the object to create env CORBA environment variable, used to pass exception information. Output: TRUE or FALSE 7.5 module Common Object Services - Naming CORBA naming services are used to manage object names. Here are some basic definitions: binding A name-to-object association is called a name binding. To bind a name is to create a name binding in a given context. A name binding is always defined relative to a naming context. There is no requirement that all objects must be named. context A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time. compound name Because a context is like any other object, it can also be bound to a name in a naming context. Binding contexts in other contexts creates a naming graph. The sequence of names in a naming graph is called a compound name. A compound name defines a path in the naming graph used to resolve an object reference. resolution To resolve a name is to determine the object associated with the name in a given context. A name is always resolved relative to a context - there are no absolute names. 7.5.1 interface Naming Context 7.5.1.1 bind Description: The function bind binds a name to an object in a naming context. This operation requires that the context is properly bound prior to invoking this function. If the name has already been used for an object in the given context the AlreadyBound exception is raised. C specification: void CosNaming_NamingContext_bind( CORBA_Object con, CosNaming_Name *nam, CORBA_Object obj, CORBA_Environment *env) Argument list for C: con naming context object (returned from bind_new_context) nam name to be bound to object; see bind_new_context. obj object to be bound to name env CORBA environment variable, used to pass exception information. Output: none 7.5.1.2 bind_context Description: The function bind_context binds a name to a context. Constraint: The client calls this method indirectly through bind_new_context. C specification: void CosNaming_NamingContext_bind_context ( CosNaming_NamingContext con, CosNaming_Name *nam, CosNaming_NamingContext nc, CORBA_Environment *env) Argument list for C: con NamingContext object reference nam name to be bound to context; see bind_new_context above. nc context object to be bound (returned from new_context) env CORBA environment variable, used to pass exception information. Output: none 7.5.1.3 bind_new_context Description: The bind_new_context function creates a new context and binds it to the name supplied as an argument. This method should be called by user to create a new context and bind a name to it. If the name has already been used for a context the AlreadyBound exception is raised. Constraint: This method calls new_context and bind_context to allocate space and record the information in the name server. C header file: naming.h C specification: CosNaming_NamingContext CosNaming_NamingContext_bind_new_context( CORBA_NamingContext con, CosNaming_Name *nam, CORBA_Environment *env) Argument list for C: con context object nam Name of object; see CosNaming_Name below: env CORBA environment variable, used to pass exception information. typedef CORBA_char* CosNaming_Istring; typedef struct { CosNaming_Istring id; CosNaming_Istring kind; } CosNaming_NameComponent; typedef struct { CORBA_unsigned_long _maximum; CORBA_unsigned_long _length; CosNaming_NameComponent * _buffer; CORBA_boolean _release; } CORBA_sequence_CosNaming_NameComponent; typedef CORBA_sequence_CosNaming_NameComponent CosNaming_Name; Output: naming context object 7.5.1.4 list Description: The list operation allows a client to iterate through a set of bindings in a naming context. The client passes in a naming context. If found and named objects are bound to this context then a binding list of not more that max (input parameter) is created and returned. If there are additional names bound to this context an object reference is created; then it is returned to the client as a binding iterator. If the input naming context is not found in the cross reference table, a NotFound exception is raised. If no objects are bound to the context, a NotFound exception is raised. If the input parameter max is less than 1, a CannotProceed exception is raised. If a binding iterator could not be created, a CannotProceed exception is raised. C specification: void CosNaming_NamingContext_list ( CORBA_Object con, CORBA_unsigned_long max, CosNaming_BindingList **lst, CosNaming_BindingIterator *ite, CORBA_Environment *env) Argument list for C: con context object max maximum name bindings to return lst a pointer to where the binding list is returned ite a pointer to where the binding iterator is returned env CORBA environment variable, used to pass exception information. Output: none 7.5.1.5 new_context Description: The new_context function returns a naming context. Constraint: This method is called indirectly when the client calls bind_new_context. C specification: CosNaming_NamingContext CosNaming_NamingContext_new_context( CORBA_Object con, CORBA_Environment *env) Argument list for C: con context object env CORBA environment variable, used to pass exception information. Output: naming context object 7.5.1.6 resolve Description: The resolve function retrieves an object bound to a given name in a given context. If the given name isn't found in the given context, a NotFound exception is raised. The given name must exactly match the bound name; the comparison is case sensitive. If the given name isn't found in any context, a CannotProceed exception is raised. C specification: CORBA_Object CosNaming_NamingContext_resolve( CORBA_Object con, CosNaming_Name *nam, CORBA_Environment *ev) Argument list for C: con context in which object is to be resolved nam name to be resolved; see bind_new_context above. env CORBA environment variable, used to pass exception information. Output: reference to resolved object The context object passed in is returned if an exception occurs. 7.5.1.7 destroy Description: The destroy function deletes a naming context. C specification: extern void CosNaming_NamingContext_destroy( CosNaming_NamingContext con, CORBA_Environment *env); Argument list for C: con NamingContext object env CORBA environment variable, used to pass exception information 7.5.1.8 rebind Description: The rebind function creates a binding of a name and an object in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind do not participate in resolution when compound names are passed to be resolved. C specification: void CosNaming_NamingContext_rebind( CosNaming_NamingContext con, CosNaming_Name *nam, CosNaming_NamingContext nc, CORBA_Environment *env); Argument list for C: con NamingContext object nam name to be bound nc existing naming context to be rebound env CORBA environment variable, used to pass exception information 7.5.1.9 rebind_context Description: The rebind_context function creates a binding of a name and a naming context even if the name is already bound in the context. Naming contexts that are bound using rebind_context participate in resolution when compound names are passed to be resolved. C specification: void CosNaming_NamingContext_rebind_context( CosNaming_NamingContext con, CosNaming_Name *nam, CosNaming_NamingContext nc, CORBA_Environment *env); Argument list for C: con NamingContext object nam name to be bound nc existing naming context to be rebound env CORBA environment variable, used to pass exception information 7.5.1.10 unbind Description: The unbind function removes a name binding from a context. C specification: extern void CosNaming_NamingContext_unbind( CosNaming_NamingContext con, CosNaming_Name *nam, CORBA_Environment *env); Argument list for C: con NamingContext object nam name to be bound env CORBA environment variable, used to pass exception information 7.5.2 interface Binding Iterator 7.5.2.1 next_one Description: The next_one function returns the next binding. If there are no bindings, FALSE is returned. If the context object is not found, the NotFound exception is raised. C specification: CORBA_boolean CosNaming_BindingIterator_next_one( CosNaming_BindingIterator obj, CosNaming_Binding *bin, CORBA_Environment *env) Argument list for C: obj BindingIterator object bin pointer to where the binding will be returned. See structure below. env CORBA environment variable, used to pass exception information. typedef CORBA_long CosNaming_BindingType; typedef struct { CosNaming_Name binding_name; CosNaming_BindingType binding_type; } CosNaming_Binding; Output: TRUE if method succeeds; FALSE if method fails. 7.5.2.2 next_n Description: The next_n function returns the next N bindings. If there are no bindings, FALSE is returned. C specification: CORBA_boolean CosNaming_BindingIterator_next_n ( CosNaming_BindingIterator obj, CORBA_unsigned_long max, CosNaming_BindingList **lst, CORBA_Environment *env) Argument list for C: obj BindingIterator object max maximum name-bindings to return lst a pointer to where the binding list is returned env CORBA environment variable, used to pass exception information. Output: TRUE if method succeeds; FALSE if method fails. 7.5.2.3 destroy Description: The destroy operation destroys a binding iterator. If the cross reference table is empty an exception is raised. If the binding iterator object is not found in the cross reference table an exception is raised. C specification: void CosNaming_BindingIterator_destroy( CORBA_Object ite, CORBA_Environment *env) Argument list for C: ite binding iterator object env CORBA environment variable, used to pass exception information. Output: none 7.6 module Common Object Services - Stream The interfaces provided by the CosStream module are: Streamable; StreamableFactory; and StreamIO. See 'CORBA Services: Common Object Services Specification' section 8.6. 7.6.1 interface Streamable In order for an object to be externalized, it must inherit from the Streamable interface. Since C is not an object-oriented language, inheritance is implemented by including the Streamable interface in the IDL which defines the client's module. See example module Helo in ./orb/external/objects.idl 7.6.1.1 external form id Description: A streamable object must have a readonly attribute named external_form_id of type CosLifeCycle_Key. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. C specification: CosLifeCycle_Key _Streamable__get_external_form_id( CosStream_Streamable obj, CORBA_Environment *env ); Argument list for C: obj Streamable object env CORBA environment variable, used to pass exception information Output: CosLifeCycle_Key to be used to find the Factory needed for internalization. 7.6.1.2 externalize to stream Description: A streamable object must have an operation which allows a client to externalize it. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. C specification: void _Streamable_externalize_to_stream( CosStream_Streamable obj, CosStream_StreamIO targetStreamIO, CORBA_Environment *env); Argument list for C: obj Streamable object targetStreamIO StreamIO object to perform write operations env CORBA environment variable, used to pass exception information Output: None 7.6.1.3 internalize from stream Description: A streamable object must have an operation which allows a client to internalize it. It will use the FactoryFinder type object named there to find a Factory which will create a new object from the externalized form of the streamable object. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. C specification: void _Streamable_internalize_from_stream( CosStream_Streamable obj, CosStream_StreamIO sourceStreamIO, CosLifeCycle_FactoryFinder there, CORBA_Environment *env ); Argument list for C: obj uninitialized Streamable object from StreamableFactory sourceStreamIO StreamIO object to perform read operations there A FactoryFinder type object env CORBA environment variable, used to pass exception information Output: None 7.6.2 interface Streamable Factory A StreamableFactory must exist for each externalizable object. 7.6.2.1 create uninitialized Description: This is the first step towards internalization. The create_uninitialized operation creates a Streamable object which can then be passed to the internalize_from_stream operation. C specification: CosStream_Streamable CosStream_StreamableFactory_create_uninitialized( CosStream_StreamableFactory obj, CORBA_Environment *env ); Argument list for C: obj StreamableFactory object env CORBA environment variable, used to pass exception information Output: Streamable object 7.6.3 interface StreamIO A StreamIO interface is performs writes for externalization and reads for internalization. 7.6.3.1 write string Description: The write_string operation writes a character string to the Stream. C specification: void CosStream_StreamIO_write_string( CosStream_StreamIO obj, CORBA_char *aString, CORBA_Environment *env ); Argument list for C: obj StreamIO object aString a character string env CORBA environment variable, used to pass exception information Output: None 7.6.3.2 write char Description: The write_char operation writes a character to the Stream. C specification: void CosStream_StreamIO_write_char( CosStream_StreamIO obj, CORBA_char aChar, CORBA_Environment *env ); Argument list for C: obj StreamIO object aChar a character env CORBA environment variable, used to pass exception information Output: None 7.6.3.3 write octet Description: The write_octet operation writes one 8-bit value to Stream. C specification: void CosStream_StreamIO_write_octet( CosStream_StreamIO obj, CORBA_octet anOctet, CORBA_Environment *env ); Argument list for C: obj StreamIO object anOctet an 8-bit value, guaranteed not to undergo any conversion env CORBA environment variable, used to pass exception information Output: none 7.6.3.4 write unsigned long Description: The write_unsigned_long operation writes an unsigned long integer to the Stream. C specification: write_unsigned_long void CosStream_StreamIO_write_unsigned_long( CosStream_StreamIO obj, CORBA_unsigned_long anUnsignedLong, CORBA_Environment *env ); Argument list for C: obj StreamIO object anUnsignedLong an unsigned integer in the range 0.. (2 ** 32)-1. env CORBA environment variable, used to pass exception information Output: None 7.6.3.5 write unsigned short Description: The write_unsigned_short operation writes an unsigned long integer to the Stream. C specification: void CosStream_StreamIO_write_unsigned_short( CosStream_StreamIO obj, CORBA_unsigned_short anUnsignedShort, CORBA_Environment *env ); Argument list for C: obj StreamIO object anUnsignedShort an unsigned integer in the range 0.. (2 ** 16)-1. env CORBA environment variable, used to pass exception information Output: None 7.6.3.6 write long Description: The write_long operation writes a signed long integer to the Stream. C specification: void CosStream_StreamIO_write_long( CosStream_StreamIO obj, CORBA_long aLong, CORBA_Environment *env ); Argument list for C: obj StreamIO object aLong an integer in the range -2 ** 31 .. (2 ** 31) - 1 env CORBA environment variable, used to pass exception information Output: None 7.6.3.7 write short Description: The write_short operation writes a signed short integer to the Stream. C specification: void CosStream_StreamIO_write_short( CosStream_StreamIO obj, CORBA_short aShort, CORBA_Environment *env ); Argument list for C: obj StreamIO object aShort an integer in the range -2 ** 15 .. (2 ** 15) - 1 env CORBA environment variable, used to pass exception information Output: None 7.6.3.8 write float Description: The write_float operation writes a floating point number to the stream. C specification: void CosStream_StreamIO_write_float( CosStream_StreamIO obj, CORBA_float aFloat, CORBA_Environment *env); Argument list for C: obj StreamIO object aFloat a single-precision floating point number env CORBA environment variable, used to pass exception information Output: None 7.6.3.9 write double Description: The write_double operation writes a double-precision floating point number to the stream. C specification: void CosStream_StreamIO_write_double( CosStream_StreamIO obj, CORBA_double aDouble, CORBA_Environment *env); Argument list for C: obj StreamIO object aDouble a double-precision floating point number env CORBA environment variable, used to pass exception information Output: None 7.6.3.10 write boolean Description: The write_boolean operation writes a value which can be either TRUE or FALSE. C specification: void CosStream_StreamIO_write_boolean( CosStream_StreamIO obj, CORBA_boolean aBoolean, CORBA_Environment *env ); Argument list for C: obj StreamIO object aBoolean a value which can be either TRUE or FALSE. env CORBA environment variable, used to pass exception information Output: None 7.6.3.11 read string Description: The read_string operation reads a character string from the Stream. C specification: CORBA_char *CosStream_StreamIO_read_string( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: a character string 7.6.3.12 read char Description: The read_char operation reads a character from the Stream. C specification: CORBA_char CosStream_StreamIO_read_char( CosStream_StreamIO obj, CORBA_Environment *env); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: a character 7.6.3.13 read octet Description: The read_octet operation reads one 8-bit value to Stream. C specification: CORBA_octet CosStream_StreamIO_read_octet( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: an 8-bit value, guaranteed not to undergo any conversion 7.6.3.14 read unsigned long Description: The read_unsigned_long operation reads an unsigned long integer from the Stream. C specification: CORBA_unsigned_long CosStream_StreamIO_read_unsigned_long( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: an unsigned integer in the range 0.. (2 ** 32)-1. 7.6.3.15 read unsigned short Description: The read_unsigned_short operation reads an unsigned long integer from the Stream. C specification: CORBA_unsigned_short CosStream_StreamIO_read_unsigned_short( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: an unsigned integer in the range 0.. (2 ** 16)-1. 7.6.3.16 read long Description: The read_long operation reads a signed long integer from the Stream. C specification: CORBA_long CosStream_StreamIO_read_long( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: an integer in the range -2 ** 31 .. (2 ** 31) - 1 7.6.3.17 read short Description: The read_short operation reads a signed short integer from the Stream. C specification: CORBA_short CosStream_StreamIO_read_short( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: an integer in the range -2 ** 15 .. (2 ** 15) - 1 7.6.3.18 read float Description: The read_float operation reads a floating point number from the Stream. C specification: CORBA_float CosStream_StreamIO_read_float( CosStream_StreamIO obj, CORBA_Environment *env); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: a single-precision floating point number 7.6.3.19 read double Description: The read_double operation reads a double-precision floating point number from the Stream. C specification: CORBA_double CosStream_StreamIO_read_double( CosStream_StreamIO obj, CORBA_Environment *env); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: a double-precision floating point number 7.6.3.20 read boolean Description: The read_boolean operation reads a value which can be either TRUE or FALSE. C specification: CORBA_boolean CosStream_StreamIO_read_boolean( CosStream_StreamIO obj, CORBA_Environment *env ); Argument list for C: obj StreamIO object env CORBA environment variable, used to pass exception information Output: A boolean value. 7.7 module Common Object Services - Externalization The externalization service provides means to externalize and internalize objects. "Externalize" means to record the object on external media as a stream of data. "Internalize" means to create an object from a stream of data on external media. See section 8.5 of 'CORBA services: Common Object Services Specification'. 7.7.1 interface Stream A client who wishes to externalize an object must first have a Stream object in which to record the stream of data. 7.7.1.1 externalize Description: The externalize operation externalizes the passed Streamable object by invoking the streamable object's externalize_to_stream operation. C specification: void CosExternalization_Stream_externalize( CosExternalization_Stream obj, CosStream_Streamable theObject, CORBA_Environment *env ); Argument list for C: obj Stream object theObject a Streamable object env CORBA environment variable, used to pass exception information Output: None 7.7.1.2 internalize Description: The internalize operation internalizes an object from the Stream by using the FactoryFinder to create a Streamable object, and then invoking the Streamable object's internalize_from_stream operation. C specification: CosStream_Streamable CosExternalization_Stream_internalize( CosExternalization_Stream obj, CosLifeCycle_FactoryFinder there, CORBA_Environment *env ); Argument list for C: obj Stream object there a Factory Finder to generate the internalized object from the stream. env CORBA environment variable, used to pass exception information Output: None 7.7.1.3 flush Description: The flush operation requests that an external representation is committed to its storage medium (file, tape, etc.). C specification: void CosExternalization_Stream_flush( CosExternalization_Stream obj, CORBA_Environment *env); Argument list for C: obj Stream object env CORBA environment variable, used to pass exception information Output: None 7.7.2 interface Stream Factory This interface can create a Stream without specifying any special characteristics. 7.7.2.1 create Description: The create function creates a Stream for externalization. C specification: CosExternalization_Stream CosExternalization_StreamFactory_create( CosExternalization_StreamFactory obj, CORBA_Environment *env); Argument list for C: obj StreamFactory object env CORBA environment variable, used to pass exception information Output: A stream object. 7.7.3 File Stream Factory This interface can create a File Stream. 7.7.3.1 create Description: The create function creates a File Stream for externalization. C specification: CosExternalization_Stream CosExternalization_FileStreamFactory_create( CosExternalization_FileStreamFactory obj, CORBA_char *theFileName, CORBA_Environment *env); Argument list for C: obj FileStreamFactory object theFileName character string specifying the file name. env CORBA environment variable, used to pass exception information Output: A stream object. 8 Encapsulated Scheduler API's in C This section provides a description of the encapsulated scheduler's Application Program Interface functions in C. The prototypes for these functions are defined in the header file es.h. 8.1 Register Description: es_register registers the ASE name, group name, and priority specifications with the encapsulated scheduler for the current ASE. This routine must be called once prior to any subsequent calls to any of the other encapsulated scheduler routines. Real-time priority ranges from 1 for the lowest real-time priority through ES_MAXPRI for the highest real-time priority. Priority 0 indicates non-real-time UNIX scheduling. The value of ES_MAXPRI is system dependent. The priority level of the ASE will be initially set to the input priority_current. Priority_min is the minimum priority that the ASE can be changed to. Priority_max is the maximum priority that the ASE can be changed to. If the minimum and current priorities are set to 0, and the maximum is set to ES_MAXPRI the ES will automatically establish the current priority when a call to es_rate is made. The calculated priority will based on the deadline, if no deadline then the period will be used, such that the higher frequency ASE's will have the higher priorities. The UNIX signals SIGINT, SIGUSR1, SIGALRM, SIGFPE, SIGSEGV, and SIGBUS are attached to the encapsulated scheduler's signal handler. SIGINT will cause the routine exit to be called, which will unregister the ASE before it terminates. SIGUSR1 is used to generate user events. SIGALRM is used for periodic scheduling (ES_RATE event). SIGFPE, SIGSEGV, and SIGBUS are used for exception processing via the es_exception call. Constraints: This routine must be called once prior to any subsequent calls to any of the other ES routines. C specification: int es_register( char * ASE_name, char * group_name, u_int priority_min, u_int priority_max, u_int priority_current ); Argument list for C: ASE_name character string naming the schedulable entity group_name character string naming the group priority_min minimum priority that the ASE can be changed to. priority_max maximum priority that the ASE can be changed to priority_current initial priority that the ASE will be assigned Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - NULL ASE_name or NULL name pointer. ES_BADPRI -Current priority is out of range of the minimum and maximum priorities or greater than ES_MAXPRI. ES_REGDUP - ASE name already registered. ES_REGFULL - Maximum number of ASE's already registered. ES_KEYCREAT - Pthread key create error. ES_GETENV - Get environment variable error. ES_GETPWNAM - Get passwd name entry error. ES_SHMCREAT - Shared memory create error. ES_SHMGET - Shared memory get error. ES_SEGSIZE - Shared memory segment size mismatch. ES_SHMAT - Shared memory attach error. ES_SEMINIT - Semaphore initialization error. ES_SEMGET - Semaphore get error. ES_RELEASE - ES release mismatch. ES_VERSION - ES version mismatch. ES_GETTHRD - Get pthread data error. EPERM - No root permissions, if current priority not zero. EACCES - Shared memory segment exists without proper permissions. ENOMEM - Insufficient physical memory to create the shared memory segment or available data space is not large enough. ENOSPC - Maximum shared memory identifiers exceeded. EMFILE - Maximum number of attached shared memory segments exceeded. EINTR - Interrupted system call. 8.2 Execute Description: es_execute executes a UNIX command in the background as a child process. The first field in the command must be an executable file located in a directory defined by the environment variable PATH or a complete path name. The input parameter sync is set to ES_SYNC or ES_ASYNC for synchronous or asynchronous execution of the command respectively. For the threads version of the ES the command string pointer may be replaced by a pointer to a routine. For synchronous execution the routine will be called directly. Upon completion of the routine control will be returned to the calling application. For asynchronous execution a thread will be created for the routine. Control will be returned to the calling application while the thread is still executing. C specification: int es_execute (int sync, void *command) Argument list for C: sync ES_SYNC for synchronous execution or ES_ASYNC for asynchronous execution command name of an executable file located in a directory defined by the environment variable PATH or a complete path name.. For the threads version of the ES the command string pointer may be replaced by a pointer to a routine. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADEXEC - NULL command pointer or NULL command string. EACCES - No search access for path name component. ELOOP - Too many symbolic links encountered. ENOENT - Executable file not found. ENOTDIR - Path name component not a directory. ESTALE - Root or current directory in stale file system. ENAMETOOLONG - Component or total path name length too long. 8.3 Set Priority Description: es_priority changes the priority of an ASE or a group of ASE's to the input priority. A null ASE name will change the priority of the current ASE. The priority level must be within the minimum/maximum range defined by the es_register call for the specified ASE. C header file: es.h C specification: int es_priority (char *ASE_name, u_int priority) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. priority priority level Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_BADPRI - Priority not in minimum/maximum range. EPERM - No root permissions. 8.4 Resume Description: es_resume resumes the execution of a suspended ASE or a group of ASE's. C header file: es.h C specification: int es_resume(char *ASE_name) Argument list for C: ASE_name an ASE or a group name. Output: Error code: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_FIFOFULL - Event FIFO for resume event priority is full. EINTR - Interrupted system call. ESRCH - Process ID for ASE is not valid. EPERM - No permission to send a signal to the ASE. 8.5 Suspend Description: es_suspend will suspend the execution of a ASE, a group of ASE's, or all ASE's other than itself. A null ASE name will suspend the current ASE. The ASE(s) will remain suspended, ignoring all events, until a resume event is received. C specification: int es_suspend(char *ASE_name) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's other than the requester. Output: Error code: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_FIFOFULL - Event FIFO for suspend event priority is full. EINTR - Interrupted system call. ESRCH - Process ID for ASE is not valid. EPERM - No permission to send a signal to the ASE. 8.6 Terminate Description: es_terminate will terminate the execution of an ASE, a group of ASE's, or all ASE's other than itself. Constraint: For threads this routine must be called to terminate the thread. Do not use exit(2). C specification: int es_terminate(char *ASE_name) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's other than the requester. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_FIFOFULL - Event FIFO for terminate event priority is full. EINTR - Interrupted system call. ESRCH - Process ID for ASE is not valid. EPERM - No permission to send a signal to the ASE. 8.7 Periodic Rate Event Description: es_rate Initiates an interval timer to cause an ES_RATE event to occur periodically based on the input time period specified in milliseconds. The deadline will be used to detect that the ASE has executed past the input time deadline specified in milliseconds. If the deadline time period is exceeded an ES_DEADLINE event will occur. A deadline value of 0.0 will disable the deadline event from occurring. The anticipated_use input is the percentage of CPU utilization which is expected for this ASE. If the total utilization for all periodic rate ASE's exceeds 100% this routine will return with an error. C specification: int es_rate(char *ASE_name, double time_period, double time_deadline, int anticipated_use) Argument list for C: ASE_name an application schedulable entity name time_period period between invocations, in milliseconds time_deadline deadline for completion of execution, in milliseconds anticipated_use estimated whole number percent of CPU utilization Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_USE100 - Anticipated processor usage for all periodic rate ASE's will exceeded 100%. ES_FIFOFULL - Event FIFO for set rate event priority is full. EINTR - Interrupted system call. ESRCH - Process ID for ASE is not valid. EPERM - No permission to send a signal to the ASE. 8.8 Periodic Rate End Description: es_rate_end will notify the encapsulated scheduler when a periodic ASE has completed. If this routine is called subsequent to the deadline defined by the call to es_rate an ES_DEADLINE event will be issued. C specification: int es_rate_end() Argument list for C: none Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_FIFOFULL - Event FIFO for deadline event priority is full. EINTR - Interrupted system call. 8.9 Timer Description: es_timer initiates a timer, defined by number, to cause an event to occur based on the input time period. C specification: int es_timer( char *ASE_name, double period, u_int number, u_int event) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's. period delta time for event, in milliseconds. Zero to disable active timer. number timer number in the range 1 .. ES_MAXTIMER event event number in the range ES_USERMIN .. ES_USERMAX. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADPROG - ASE name is not registered. ES_BADEVENT - Bad event number. ES_BADTIMER - Bad timer number. 8.10 Issue Event Description: es_issue issues a user defined event to an ASE or group of ASE's. C specification: int es_issue( char *ASE_name, u_int event) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's other than the requester. event event number in the range ES_USERMIN - ES_USERMAX. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADEVENT - Event number is out of range. ES_BADPROG - ASE name is not registered. ES_FIFOFULL - Event FIFO for issuing event priority is full. EINTR - Interrupted system call. ESRCH - Process ID for ASE is not valid. EPERM - No permission to send a signal to the ASE 8.11 Cancel Event Description: es_cancel will cancel a queued event for an ASE or group of ASE's. C specification: int es_cancel( char *ASE_name, u_int event, int number) Argument list for C: ASE_name an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's. event event number in the range 0 - ES_MAXEVENTS-1. number number of occurrences of the event in the queue to cancel. Zero for all. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADEVENT - Event number is out of range. ES_BADPROG - ASE name is not registered. 8.12 Sleep Description: es_sleep will sleep for the specified number of milliseconds. The granularity of the timeout value is system dependent. An input timeout value of 0.0 can be used to yield the processor to another ASE. The amount of time remaining in the sleep request due to being woken earlier than the specified timeout period is returned. Constraint: This call should be used instead of the POSIX sleep routine, which on some systems can corrupt the real-time process clock which is used by the ES to implement its timers. C specification: double es_sleep(double timeout) Argument list for C: timeout time to sleep, in milliseconds. Zero to yield the processor to another ASE. Output: Time remaining from an early return. A negative time value indicates an error condition. es_errno: ES_NOTREG - Not currently registered with the ES. ES_GETTHRD - Get thread data error. 8.13 Wait Description: es_wait will wait for any event to occur. C specification: int es_wait(double timeout) Argument list for C: timeout time in milliseconds to suspend the ASE before an event to occurs. A timeout value of zero will suspend forever waiting for an event to occur. A negative timeout value will return immediately. The event will be dequeued. Output: Event number or ES_NOEVENT if no event is currently active. A -1 return value indicates an error. es_errno: ES_NOTREG - Not currently registered with the ES. ES_GETTHRD - Get thread data error. 8.14 Poll Description: es_poll will poll for the existence of any event. If an event exists it will be dequeued and the event number will be returned. If no event exists a value of 0 will be returned. This is the same as calling es_wait() with a negative argument. C specification: int es_poll() Argument list for C: none Output: Event number or ES_NOEVENT if no event is currently active. A -1 return value indicates an error. es_errno: ES_NOTREG - Not currently registered with the ES. ES_GETTHRD - Get thread data error. 8.15 Poll Event Description: es_poll_event will poll for the existence of a specified event. If the event number is found on the event queue its position in the queue will be returned. Otherwise, a value of -1 will be returned. This service can be used to bypass the normal first-in-first-out priority based event scheduling which is implemented with the es_wait() and es_poll() services. If the event is handled based on a non-negative return value then the es_cancel() service should be called to remove the event from the queue. For example: if (es_poll_event(SOME_EVENT) >= 0) { handle_SOME_EVENT(); es_cancel(NULL,SOME_EVENT,1); } C specification: int es_poll_event(event) Argument list for C: event event number Output: Event queue position. -1 indicates event not on queue. 8.16 Event Priority Description: es_event_priority will set the priority level for the input event number. By default all events will have the priority ES_EPMAX / 2. The event number must be in the range 0 - ES_MAXEVENTS-1. The priority must be in the range 0 - ES_EPMAX-1. Events will be handled such that 0 is the highest priority. Events are divided into three groups, DEADLINE, signals, and user events. Events of the same priority will be handled in the order, DEADLINE, signal 1 through signal SIGMAX, and user events first in first out. C specification: int es_event_priority( u_int event, u_int priority) Argument list for C: event event number in the range 0 - ES_MAXEVENTS-1 priority priority in the range 0 - ES_EPMAX-1. Zero is the highest priority. Output: 0 - successful -1 - error, errno set to appropriate error code. errno: ES_BADEVENT - Event number is out of range. ES_BADEP - Event priority is out of range. 8.17 Event ID Description: es_event_id will return a pointer to the ASE name which originated the last event detected by the es_wait or es_poll routines. C specification: char *es_event_id() Argument list for C: none Output: ASE name pointer. If no event has been received then a pointer to a null string will be returned. 8.18 Event Handler Description: es_handler will establish an event handler for a specified event. If a handler has been established for an event which has occurred, the handler routine will be called directly from the encapsulated scheduler signal handler. This will preempt the normal execution of the ASE. Upon completion of the handler, ASE execution will commence from where it was preempted. C specification: int es_handler( u_int event, void *handler) Argument list for C: event The event number in the range 0 - ES_MAXEVENTS-1. handler Address of a routine which will handle the event. A handler has the following specification: void handler(u_int event, char *ASE_name) event is the event number which caused the handler to be invoked ASE_name is the name of the entity which originated the event. Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_BADEVENT - Event number is out of range. 8.19 Signal Description: es_signal will associate a UNIX signal with an encapsulated scheduler event. The input signal number must be in the range 1 - SIGMAX. The signals SIGINT, SIGUSR1, SIGALRM, SIGFPE, SIGSEGV, and SIGBUS are reserved by the encapsulated scheduler. The signals SIGKILL and SIGSTOP are reserved by the operating system and can not be caught. The event number associated with the signal will be same as the signal number. C specification: int es_signal(u_int signal) Argument list for C: signal signal number in the range 1 - SIGMAX. Output: 0 - successful -1 - error, errno set to appropriate error code. errno: ES_BADSIG - Signal number is out of range or is reserved. 8.20 Exception Description: es_exception is a macro which allows you to handle and recover from exceptions much the same as an Ada exception. Exception handling may be nested up to ES_MAXEL levels in depth. Exceptions are generated via the UNIX signals SIGFPE, SIGSEGV, and SIGBUS. The follow example illustrates the use of the es_exception call. int return_value; if (!(return_value = es_exception())) { /* What ever code you want to handle exceptions for. */ es_exception_end(); } else { if (return_value == -1) printf("Too many nesting levels of exception handling"); else printf("Exception signal number %d\n",return_value); } C specification: int es_exception() Argument list for C: none Output: -1 - Too many nesting levels of exception handling. 0 - Exception processing block start SIGFPE - Floating point exception occurred in the code block. SIGSEGV - Segment violation occurred in the code block. SIGBUS - Bus error occurred in the code block. 8.21 Exception End Description: es_exception end denotes the end of an exception processing code block. This routine must be called upon the completion of the block of code which has exception handling. Refer to es_exception code example above. C specification: void es_exception_end() Argument list for C: none Output: none 8.22 Semaphore Lock Description: es_lock locks a user semaphore. The sem_number must be in the range 0 - ES_SEMMAX-1. If wait_flag is TRUE, the ASE will wait for the semaphore to become unlocked before it is locked. If wait_flag is FALSE and the semaphore is locked, the routine will return immediately with the value of 1, indicating that the semaphore is in use. If the lock was locked by this call, a value of 0 will be returned. Otherwise, a value of -1 will be returned indicating an error condition. If the semaphore is locked, or was locked, then the ASE name pointer will be updated with a pointer to the name of the ASE which has locked the semaphore. C specification: int es_lock( u_int sem_number, int wait_flag, char *ASE_name) Argument list for C: sem_number semaphore number in the range 0 - ES_SEMMAX-1 wait_flag FALSE or TRUE ASE_name a pointer to pass back the ASE name for a locked semaphore. Output: 1 - semaphore in use; ASE_name will point to the ASE which has locked the semaphore. 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_SEMMAX - Semaphore number is out of range. EINTR - Interrupted system call. 8.23 Semaphore Unlock Description: es_unlock unlocks a user semaphore. This routine should only be called subsequent to a successful call to es_lock. C specification: int es_unlock(u_int sem_number) Argument list for C: sem_number semaphore number in the range 0 - ES_SEMMAX-1. Output: 0 - successful -1 - error, errno set to appropriate error code. errno: ES_SEMMAX - Semaphore number is out of range. 8.24 Set Time Description: es_settime sets the system wall clock time based on the input timeval and timezone pointer structure data. The timeval structure represents the number of seconds and microseconds since midnight January 1, 1970. The timezone structure represents the number of minutes west from Greenwich and a daylight savings time flag which applies to the locale. C specification: void es_settime( struct timeval *tv_pointer, struct timezone *tz_pointer) Argument list for C: The timeval structure is defined in sys/time.h as follows: Member Data Type Description ---------------------------------------------------------------------- tv_sec int Number of seconds since midnight 1/1/70 tv_usec int Additional number of microseconds The timezone structure is defined in sys/time.h as follows: Member Data Type Description ---------------------------------------------------------------------- tz_minuteswest int Minutes west of GMT tz_dsttime int daylight savings correction: DST_NONE - none DST_USA - USA DST_AUST - Australia DST_WET - Western Europe DST_MET - Middle Europe DST_EET - Eastern Europe DST_CAN - Canada Output: none 8.25 Time Scale Description: es_timescale will set a scaling rate for the ES timer services. All calls to es_gettime, es_elapsed, es_sleep, es_wait, es_rate, and es_timer will have their wall clock time scaled by the input rate factor specified. Any previously active timers will also be scaled by the specified rate. All ASE's active on the current system will be affected. A rate factor of 0.0, which is equivalent to 1.0, will reset the wall clock time to the normal clock rate. For example, a rate factor of 0.5 will cause the wall clock to run at half speed. Conversely, a rate factor of 2.0 will cause the wall clock to run at double speed. C specification: int es_timescale(double rate) Argument list for C: rate 0.0 will reset the clock to normal rate 0.5 will cause the clock to run at half normal speed 2.0 will cause the clock to run at normal speed Output: 0 - successful -1 - error, errno set to appropriate error code. errno: ES_NOTREG - ASE not registered with the ES. ES_BADRATE - Negative rate factor specified. 8.26 Get Time Description: es_gettime stores the current system time into the structure pointed to by the input tv_pointer. C specification: void es_gettime(struct timeval *tv_pointer) Argument list for C: The timeval structure is defined in sys/time.h as follows: Member Data Type Description ---------------------------------------------------------------------- tv_sec int Number of seconds since midnight 1/1/70 tv_usec int Additional number of microseconds Output: none 8.27 Elapsed Time Description: es_elapsed returns the elapsed system time, in milliseconds, from the current system time to the system time pointed to by the input tv_pointer. The system time pointed to by the input tv_pointer must be from a previous call to es_gettime. C specification: double es_elapsed(struct timeval *tv_pointer) Argument list for C: tv_pointer system from a previous call to es_gettime. Output: Elapsed system time in milliseconds. 8.28 Processing Time Description: es_proctime returns process accounting information. C specification: clock_t es_proctime(struct tms *tms_pointer) Argument list for C: The structure pointed to by tms_pointer will be populated with the following process accounting information. Member Data Type Description ---------------------------------------------------------------------- tms_utime clock_t User CPU time. tms_stime clock_t System CPU time. tms_cutime clock_t User CPU time of terminated child processes. tms_cstime clock_t System CPU time of terminated child processes. Values returned are defined in terms of clock ticks per second (CLK_TCK). Output: The elapsed real time, in clock ticks, since an arbitrary point in the past will be returned. 8.29 Date and Time Description: es_datetime returns date and time information. C specification: void es_datetime(int zone, struct tm *tm_pointer) Argument list for C: zone ES_LOCAL for local time ES_GMT for greenwich mean time Output: The structure pointed to by tm_pointer will be populated with the following date and time information. Member Data Type Description Range ---------------------------------------------------------------------- tm_sec int Seconds 0 - 59 tm_min int Minutes 0 - 59 tm_hour int Hours 0 - 23 tm_mday int Day of month 1 - 31 tm_mon int Month of year 0 - 11 tm_year int Year year - 1900 tm_wday int Day of week (Sunday = 0) 0 - 6 tm_yday int Day of year 0 - 365 tm_isdst int Is daylight savings time? 8.30 Time Synchronization Description: es_timesync will synchronize the host system with a remote system. C specification: int es_timesync( char *remote_name char *user_name int set_flag double adjust float *difference) Argument list for C: remote_name name of remote system user_name name of ES server task on remote system if NULL, a default user name will be used set_flag 0 = return the difference in milliseconds of the two system times 1 = synchronize current system time with system time in remote system adjust adjustment factor difference if set_flag is zero, the difference in milliseconds of the two system times is returned here Output: 0 - successful -1 - error, es_errno set to appropriate error code. es_errno: ES_RPCFAIL - Remote procedure call has failed. RPC error code is stored for use by es_errno() routine. ES_RANGE - Returned difference too big to be returned. EPERM - No root permissions. 8.31 Memory Usage Description: es_memory returns system memory used and free in 1K blocks. C specification: int es_memory(int *used, int *free) Argument list for C: used pointer to an integer free pointer to an integer Output: 0 - successful -1 - error, errno set to appropriate error code. 8.32 Memory Allocate Description: es_malloc will allocate the number of bytes of memory specified and return a pointer to the memory. The number of bytes must be greater than zero. If not enough memory is available then a NULL pointer is returned. C specification: void *es_malloc(int bytes) Argument list for C: bytes number of bytes to allocate Output: NULL - error, errno set to appropriate error code. not NULL - successful; memory has been allocated to the pointer. 8.33 Memory Free Description: es_free will free up (deallocate) an area of memory which was allocated using the es_malloc service. Unpredictable results may occur if the pointer input is not valid. C specification: void es_free(void *pointer) Argument list for C: pointer a pointer to an area of memory which was allocated using es_malloc Output: none 8.34 Error Number Description: es_error_number returns the current value of es_errno which indicates an error condition which occurred on a previous call to an ES routine. This integer number should only be referenced subsequent to an error value being returned by a call to an ES routine. C specification: int es_error_number() Argument list for C: none Output: es_errno 8.35 Error Message Description: es_errmesg returns a pointer to a null terminated string which describes an error condition which occurred in a previous call to an ES routine. This routine should only be called subsequent to an error value being returned by a call to an ES routine. C specification: char *es_errmesg() Argument list for C: none Output: Error message pointer. 8.36 Select Manager Routines The following APIs support the function select, which is part of the standard UNIX C library (libc.a). The function select_wait is a wrapper around the UNIX select function. (See UNIX man page) The select system call is used to perform I/O multiplexing. It enables the programmer to manage reading and writing to several file descriptors at once without "blocking" indefinitely on any of the operations. For example, a program can use select to poll a terminal; when characters are present to be read, it can read them in and process them. While the select waits, other processing can proceed. 8.36.1 select_add_fd Description: Add file descriptor / socket to select criteria. C specification: int select_add_fd( int id, int mode, int pri, int (*func)() int sched_mode); Arguments for C: id file descriptor mode file mode (Read or Write) pri relative priority for this file descriptor func function to be invoked (upcall) when file descriptor is available 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: 0 if okay; -1 if error. 8.36.2 select_delete_fd Description: Delete file descriptor / socket from the select criteria. C specification: int select_delete_fd(int id); Arguments for C: id file descriptor Output: 0 if okay; -1 if error. 8.36.3 select_add_msg Description: Add message queue to select criteria. C specification: int select_add_msg( int id, int mode, int pri, int (*func)() int sched_mode); Arguments for C: id message queue identifier mode file mode pri relative priority for this file descriptor func function to be invoked (upcall) when message queue is available 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: 0 if okay; -1 if error. 8.36.4 select_delete_msg Description: Delete message queue from the select criteria. C specification: int select_delete_msg(int id); Arguments for C: id message queue identifier Output: 0 if okay; -1 if error. 8.36.5 select_add_upcall Description: Add upcall which is called unconditionally. C specification: int select_add_upcall( int pri, void (*) func()); Arguments for C: pri priority func upcall function Output: 0 if okay; -1 if error. 8.36.6 select delete upcall Description: Delete upcall. C specification: int select_delete_upcall(void (*) func()) Arguments for C: func function Output: 0 if okay; -1 if error. 8.36.7 select_wait Description: The select_wait function will service the highest priority socket which has I/O active on it. C specification: int select_wait(double time_out) Arguments for C: time_out floating point milliseconds time out value Output: Upon successful completion, the select subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. If the time limit specified by the TimeOut parameter expires, the select subroutine returns a value of 0. If the select subroutine is unsuccessful, it returns a value of -1 and sets the global variable errno to indicate the error. 8.36.8 select_wait_all Description: The select_wait_all function will service all sockets which have I/O currently active. C specification: int select_wait_all(double time_out) Arguments for C: time_out floating point milliseconds time out value Output: Upon successful completion, the select subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. If the time limit specified by the TimeOut parameter expires, the select subroutine returns a value of 0. If the select subroutine is unsuccessful, it returns a value of -1 and sets the global variable errno to indicate the error. 8.37 File Input/Output The following File I/O APIs are provided as a wrapper around the corresponding UNIX functions. (See UNIX man pages) 8.37.1 create Description: The fio_creat function establishes a connection between a file named by the path parameter and a file descriptor. A file descriptor is an integer used by subsequent I/O functions, such as read and write, to access that file. C specification: int fio_creat( char *path, int mode); Arguments for C: path character string identifying a file mode access permissions for the file: O_RDONLY read only O_WRONLY write only O_RDWR read and write Output: File descriptor (integer) to be used by subsequent I/O functions. 8.37.2 open Description: The fio_creat function establishes a connection between a file named by the path parameter and a file descriptor. A file descriptor is an integer used by subsequent I/O functions, such as read and write, to access that file. C specification: int fio_open( char *path, int flags, int mode); Arguments for C: path character string identifying a file flags specifies special processing by logically ORing the following flags: O_RDONLY open to read only O_WRONLY open to write only O_RDWR open to read and write O_CREAT if the file does not exist, create it with permissions given in mode parameter. O_EXCL exclusive: if this and O_CREAT are set, the file will not be opened if it already exists. O_NSHARE not-shared: assures that no other process has this file open. (This flag is only valid on a physical file system; not valid for NFS) O_RSHARE shared for reading, not shared for writing: (This flag is only valid on a physical file system; not valid for NFS) O_DEFER deferred update: changes are not permanent until fsync(). (This flag is only valid on a physical file system; not valid for NFS) O_NOCTTY no changing of terminal type: terminal assignment is not allowed during this open. O_SYNC synchronous updates of file and writes to block device O_APPEND append: file pointer is set to the end of the file prior to write O_DELAY delay: if the function could not open with O_NSHARE or O_RSHARE, the process is blocked. O_NDELAY open with no delay O_NONBLOCK open without blocking (same as O_NDELAY) mode access permissions for the file if the O_CREAT flag is set O_RDONLY read only O_WRONLY write only O_RDWR read and write Output: File descriptor (integer) to be used by subsequent I/O functions. 8.37.3 truncate(path) Description: Change the length of a file. Either truncate to make shorter, or zero-fill to make longer. C specification: int fio_truncate( char *path, int length); Arguments for C: path character string identifying a file length new file length in bytes Output: 0 - successful -1 - error, errno set to appropriate error code. 8.37.4 truncate(file descriptor) Description: Change the length of a file. Either truncate to make shorter, or zero-fill to make longer. C specification: int fio_ftruncate( int fd, int length); Arguments for C: fd file descriptor obtained from previous open length new file length in bytes Output: 0 - successful -1 - error, errno set to appropriate error code. 8.37.5 get file status(of path) Description: Function fio_stat gets the file status for a given path. C specification: int fio_stat( char *path, struct stat *sbuf); Arguments for C: path character string identifying a file sbuf system-dependent file status buffer. See /usr/include/sys/stat.h for stat type definition. Output: sbuf status information is stored here 0 - successful -1 - error, errno set to appropriate error code. 8.37.6 get file status(of a file descriptor) Description: Function fio_stat gets the file status for a given file descriptor. C specification: int fio_fstat( int fd, struct stat *sbuf); Arguments for C: fd file descriptor sbuf system-dependent file status buffer. See /usr/include/sys/stat.h for stat type definition. Output: sbuf status information is stored here 0 - successful -1 - error, errno set to appropriate error code. 8.37.7 access Description: The function fio_access determines the accessibility of a file. C specification: int fio_access( char *path, int mode); Arguments for C: path character string identifying a file mode a bit mask specifying access modes to be checked: R_OK check read permission W_OK check write permission X_OK check execute or search permission F_OK check the existence of a file (default) Output: 0 the requested access mode is permitted -1 access not permitted or the call failed and errno is set. 8.37.8 write Description: The fio_write function writes to a file. C specification: int fio_write( int fd, void *buf, int size); Arguments for C: fd file descriptor buf buffer of data to write size number of bytes to write Output: >0 - successful; returns the number of bytes actually written. -1 - error, errno set to appropriate error code. 8.37.9 read Description: The fio_read function reads data from a file C specification: int fio_read( int fd, void *buf, int size); Arguments for C: fd file descriptor buf buffer to read data into size number of bytes to read Output: >0 - successful; returns the number of bytes actually read. -1 - error, errno set to appropriate error code. 8.37.10 seek Description: The fio_seek function moves the read-write file pointer. C specification: int fio_lseek( int fd, int offset, int whence); Arguments for C: fd file descriptor offset number of bytes (may be negative) whence specifies how to interpret the offset: SEEK_SET sets the file pointer to the value of offset SEEK_CUR sets the file pointer to current location plus offset SEEK_END sets the file pointer to the size of the file plus offset Output: >0 - successful; returns the file pointer location. -1 - error; errno set to appropriate error code. 8.37.11 tell Description: The fio_tell function reports the current location of the file pointer for a given file. C specification: int fio_tell( int fd); Arguments for C: fd file descriptor Output: >0 - successful; returns the file pointer location. -1 - error; errno set to appropriate error code. 8.37.12 close Description: The fio_close function closes a file. C specification: int fio_close( int fd); Arguments for C: fd file descriptor Output: 0 - successful -1 - error; errno set to appropriate error code. 8.37.13 error number Description: The fio_errno function returns the value of errno set by a previous file I/O call. C specification: int fio_errno(); Arguments for C: none Output: Error number with meaning defined in /usr/include/errno.h 9 IDL/ODL mapping to Ada 9.1 IDL Atomic types The Ada equivalents to the IDL atomic types are defined in package CORBA. The Ada mapping is shown here with fully specified names. IDL/ODL Ada mapping Long CORBA.Long Short CORBA.Short Unsigned long CORBA.Unsigned_Long Unsigned short CORBA.Unsigned_Short Float CORBA.Float Double CORBA.Double Boolean CORBA.Boolean Octet CORBA.Octet Char CORBA.Char String CORBA.String Any CORBA.Any enum name { list } type name is ( list ) 9.2 IDL sequence<> The Ada CORBA sequence types are implemented using these Ada packages (See Appendix D): - CORBA_Sequences_Basic_Bounded_Managed_Iterator; and - CORBA_Sequences_Basic_Unbounded_Managed_Iterator. A CORBA sequence is a one-dimensional array with an optional maximum size and a length. If the maximum size of a sequence is specified, the sequence is known as a bounded sequence. If no maximum size is specified, the sequence is an unbounded sequence. Although the CORBA standard specifies a sequence to accept any "simple_type_spec" for the sequence element type, only CORBA "Basic Types" are supported in the current implementation (i.e., the internal storage occupied by a sequence must be contiguous.) When a sequence declaration is found in an IDL file, the preproceesor will generate the appropriate Ada declaration for the sequence type. The following is an example of an IDL file and the generated Ada declaration: module Fresco { interface DrawingKit { typedef sequence Data8; typedef sequence Data32; }; }; An example of the generated Ada code may look like as follows: with CORBA; with CORBA_Sequences_Basic_Bounded_Managed_Iterator; with CORBA_Sequences_Basic_Unbounded_Managed_Iterator; package Fresco_DrawingKit is type Ref is new CORBA.Object; package Octet_Unbounded is new CORBA_Sequences_Basic_Unbounded_Managed_Iterator(CORBA.octet); type Data8 is new Octet_Unbounded.Sequence; package Long_Bounded is new CORBA_Sequences_Basic_Bounded_Managed_Iterator(CORBA.long); type Data32 is new Long_Bounded.Sequence(1024); end Fresco_DrawingKit; In the above example, Data8 and Data32 are Ada derived types, they inherit operations specified in the CORBA_Sequences_Basic_Unbounded_Managed_Iterator and CORBA_Sequences_Basic_Bounded_Managed_Iterator packages. Please refer to the package specification listings in Appendix D for a complete list of operations and the details of their interface: The following is a partial list of operations available to process a sequence: - Copy Copies a sequence or an Ada array into a CORBA sequence. - Insert Inserts additional elements into a CORBA sequence. - Replace Replaces elements in a CORBA sequence. - Set Set the current size of an unbounded CORBA sequence. - Set_Element Set the value of the element at the specified position in a sequence. - Length_Of Reports the current length of a CORBA sequence. - Slice Extracts an array from a CORBA sequence. - Clear Frees up the dynamic storage set up for a CORBA sequence. In order to properly manage the dynamic storage used by a sequence, the "Clear" procedure is provided allowing software developers to release the storage used by a sequence when that sequence is no longer needed. 9.3 IDL string For an IDL definition of type string the Ada implementation is CORBA.String. CORBA.String is implemented using these components (see Appendix D): - String_Sequential_Bounded_Managed_Iterator; and - String_Sequential_Unbounded_Managed_Iterator. A CORBA string is termed a bounded string if a maximum size of the string is specified when declared in an IDL file. If no maximum size is specified, the string is termed an unbounded string. The unbounded string type is declared in the CORBA package as a derived string type from the instantiation of the String_Sequential_Unbounded_Managed_Iterator package. The CORBA String type, therefore, inherits all string manipulation operations from the String_Sequential_Unbounded_Managed_Iterator package. The following is a partial list of operations available to process a CORBA string, please refer to the specification listing in Appendix D for a complete list of operations and the details of their interface: - Copy Copies a standard Ada string into a CORBA string. - Insert Inserts additional characters into a CORBA string. - Replace Replaces characters in a CORBA string. - Is_Equal Compares two CORBA strings. - Length_Of Reports the current length of a CORBA string. - Substring_of Extracts a standard Ada string from a CORBA string. - Clear Frees up the dynamic storage set up for a CORBA string. The following code segment provides an example of using the CORBA string: with CORBA; procedure Example1 is CORBA_Name : CORBA.String Machine_Name : constant String := "tiger"; Length : Integer; begin --Initialize the CORBA String. CORBA.Copy (From_The_Substring => Machine_Name, To_The_String => CORBA_Name); --Append a special numeric ID to the CORBA String. CORBA.Append(The_Substring => "324", To_The_String => CORBA_Name); --Get the current length of the CORBA String. Length:= CORBA.Length_Of(The_String => CORBA_Name); --Get the new machine name out from the CORBA String and put it in --a format suitable for passing to a 'C' subprogram. declare C_String : String (1..Length+1); begin C_String:= CORBA.Substring_Of(The_String => CORBA_Name) & ASCII.NUL; end; --Free up storage used by the unbounded string when the string is no --longer needed. CORBA.Clear(The_String => CORBA_Name); end Example1; The CORBA bounded string is supported in a similar fashion as the unbounded string. Only the declaration is slightly different as illustrated in Example2 below: with CORBA; procedure Example2 is --A bounded string type with a maximum length of 80 characters. type Bounded_String80 is new CORBA.Ada_Strings_Bounded.String(80); CORBA_Name : Bounded_String80; Machine_Name : constant String := "tiger"; Length : Integer; begin --Initialize the Bounded String. Copy (From_The_Substring => Machine_Name, To_The_String => CORBA_Name); --Append a special numeric ID to the Bounded String. Append(The_Substring => "324", To_The_String => CORBA_Name); --Get the current length of the Bounded String. Length:= Length_Of(The_String => CORBA_Name); --Get the new machine name out from the Bounded String and put it in --a format suitable for passing to a 'C' subprogram. declare C_String : String (1..Length+1); begin C_String:= Substring_Of(The_String => CORBA_Name) & ASCII.NUL; end; end Example2; Note that in Example2, Bounded_String80 is a new type derived from CORBA.Ada_Strings_Bounded.String, it inherits all operations (as declared in the String_Sequential_Bounded_Managed_Iterator package) available for the CORBA.Ada_Strings_Bounded.String type. Since these operations are implicitly declared in Example2 as defined by the Ada language for derived data types, the operations are directly visible within Example2. Also note that the CORBA_Name in Example2 is a bounded string, the storage required by the string is statically allocated during compilation time. There is no need to invoke the "Clear" procedure to free up the dynamically allocated storage when the string is no longer needed. 9.4 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. The interface name in the ODL will correspond to the package name in Ada. An iterator is a data item which can visit every member of a collection. Every collection has an iterator. The contents of a collection member is an object. 9.4.1 Iterator function Iterator_same_as function Iterator_Same_As ( Self: in Ref; Iterator_Ptr_A: in Iterator; Iterator_Ptr_B: in Iterator ) return CORBA.boolean ; function Iterator_Copy ( Self: in Ref; Iterator_Ptr: in Iterator ) return Iterator ; procedure Iterator_Delete ( Self: in Ref; Iterator_Ptr: in Iterator ); function Iterator_Not_Done ( Self: in Ref; Iterator_Ptr: in Iterator ) return CORBA.boolean ; procedure Iterator_Next ( Self: in Ref; next_obj: out CORBA.any; Iterator_Ptr: in Iterator; result: out CORBA.boolean ); procedure Iterator_Advance ( Self: in Ref; Iterator_Ptr: in Iterator ); function Iterator_Get_Element ( Self: in Ref; Iterator_Ptr: in Iterator ) return CORBA.any ; procedure Iterator_Reset ( Self: in Ref; Iterator_Ptr: in Iterator ); function Iterator_First ( Self: in Ref; Iterator_Ptr: in Iterator ) return CORBA.any ; function Iterator_last ( Self: in Ref; Iterator_Ptr: in Iterator ) return CORBA.any ; 9.4.2 Array -- /*************************************************************/ -- /* Database Array APIs (inherited from Database Object APIs) */ -- /*************************************************************/ function Array_Same_As ( Self: in Ref; Collection_Ptr_A: in Collection; Collection_Ptr_B: in Collection ) return CORBA.boolean ; function Array_Copy ( Self: in Ref; Collection_Ptr: in Collection ) return Collection ; procedure Array_Delete ( Self: in Ref; Collection_Ptr: in Collection ); -- /*****************************************************************/ -- /* Database Array APIs (inherited from Database Collection APIs) */ -- /*****************************************************************/ function Array_Cardinality ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.unsigned_long ; function Array_Is_Empty ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.boolean ; function Array_Contains_Element ( Self: in Ref; Element: in CORBA.any; Collection_Ptr: in Collection ) return CORBA.boolean ; function Array_Create_Iterator ( Self: in Ref; Collection_Ptr: in Collection ) return Iterator ; -- /***********************/ -- /* Database Array APIs */ -- /***********************/ function Array_Create ( Self: in Ref; New_Name: in CORBA.String; Num_Elements: in CORBA.unsigned_long ) return Collection ; procedure Array_Replace_Element_At ( Self: in Ref; Index: in CORBA.unsigned_long; Element: in CORBA.any; Collection_Ptr: in Collection ); function Array_Remove_Element_At ( Self: in Ref; Index: in CORBA.unsigned_long; Collection_Ptr: in Collection ) return CORBA.any ; function Array_Retrieve_Element_At ( Self: in Ref; Index: in CORBA.unsigned_long; Collection_Ptr: in Collection ) return CORBA.any ; procedure Array_ReSize ( Self: in Ref; New_Size: in CORBA.unsigned_long; Collection_Ptr: in Collection ); function Array_remote_copy ( self: in ref; CollOpStruct_ptr: in COLLECTION_OP ) return collection ; 9.4.3 List function List_Create ( Self: in Ref; New_Name: in CORBA.String ) return Collection ; procedure List_Replace_Element_At ( Self: in Ref; list_Position: in CORBA.unsigned_long; Element: in CORBA.any; Collection_Ptr: in Collection ); function List_Remove_Element_At ( Self: in Ref; list_Position: in CORBA.unsigned_long; Collection_Ptr: in Collection ) return CORBA.any ; function List_Retrieve_Element_At ( Self: in Ref; list_Position: in CORBA.unsigned_long; Collection_Ptr: in Collection ) return CORBA.any ; procedure List_Insert_Element_After ( Self: in Ref; obj: in CORBA.any; list_Position: in CORBA.unsigned_long; Collection_Ptr: in Collection ); procedure List_Insert_Element_Before ( Self: in Ref; obj: in CORBA.any; list_Position: in CORBA.unsigned_long; Collection_Ptr: in Collection ); procedure List_Insert_Element_First ( Self: in Ref; obj: in CORBA.any; Collection_Ptr: in Collection ); procedure List_Insert_Element_last ( Self: in Ref; obj: in CORBA.any; Collection_Ptr: in Collection ); function List_Remove_First_Element ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.any ; function List_Remove_last_Element ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.any ; function List_Retrieve_First_Element ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.any ; function List_Retrieve_last_Element ( Self: in Ref; Collection_Ptr: in Collection ) return CORBA.any ; function List_Concat ( Self: in Ref; Collection_Ptr_A: in Collection; Collection_Ptr_B: in Collection ) return Collection ; procedure List_Append ( Self: in Ref; Collection_Ptr_A: in Collection; Collection_Ptr_B: in Collection ); function List_remote_copy ( self: in ref; CollOpStruct_ptr: in COLLECTION_OP ) return collection ; 10 Object Database Management API's in Ada Object Database Management API's are specified in ODMG-93 release 1.2. The Ada-83 mappings are given here. 10.1 Interface Database Database API function references are generated by the preprocessor for ODL interface definitions. These API's are specified in a package named Database. package Database is type Ref is new Corba.Object; 10.1.1 open Description: The open function opens access to the database for transactions. This function supports the remote memory model. Constraint: Only a single database may be opened at a time. Ada specification: procedure Open( Self: Ref; Database_Name: CORBA.String); Argument list for Ada: Self Database object Database_Name name of database 10.1.2 close Description: The close function closes access to a database to complete transactions. This function supports the remote memory model. Ada specification: procedure Close( Self: Ref); Argument list for Ada: Self Database object 10.1.3 bind Description: The bind function associates a name with an object in the database. This function supports the remote memory model. Ada specification: procedure Bind( Self: Ref; An_Object: CORBA.Any; Name: CORBA.String); Argument list for Ada: Self Database object An_Object value to be assigned to object in database If the value is NULL, no assignment is made. Name name of object in database 10.1.4 lookup Description: The lookup function is used to find the object with the given name. This function supports the remote memory model. Ada specification: function Lookup( Self: Ref; Name: CORBA.String ) return CORBA.Any; Argument list for Ada: Self Database object Name name of object in database 10.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. Ada specification: procedure Open_Direct( Self: Ref; Database_Name: CORBA.String); Argument list for Ada: Self Database object Database_Name name of database 10.1.6 close direct Description: The close_direct function closes access to a database to complete transactions. This function supports the direct memory model. Ada specification: procedure Close_Direct( Self: Ref); Argument list for Ada: Self Database object 10.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. Ada specification: procedure Bind_Direct( Self: Ref; An_Object: CORBA.Any; Name: CORBA.String); Argument list for Ada: Self Database object An_Object value to be assigned to object in database If the value is NULL, no assignment is made. Name name of object in database 10.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. Ada specification: function Lookup_Direct( Self: Ref; Name: CORBA.String ) return CORBA.Any; Argument list for Ada: Self Database object Name name of object in database 10.2 Interface Transaction These API's are specified in a package named Transaction. This package is defined in file trnapisup.ads. 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. package Transaction is 10.2.1 create Description: The create function creates a transaction object. A transaction object must be created before invoking the begin function. This function supports the remote memory model. Ada specification: function create( Self: Database.Ref; Transaction_name: CORBA.String ) return db_parms_t.Transaction; Argument list for Ada: Self Database object Transaction_name name of transaction Output: a reference to the named transaction. 10.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. This function supports the remote memory model. Note: To avoid conflict with the Ada key-word begin, this function is mapped to an Ada procedure named IDL_Begin. Ada specification: procedure IDL_Begin( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction ); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.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. This function supports the remote memory model. Ada specification: procedure Commit( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction ); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.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. This function supports the remote memory model. Note: To avoid conflict with the Ada key-word abort , this function is mapped to an Ada procedure named IDL_Abort. Ada specification: procedure IDL_Abort( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.2.5 create direct Description: The create_direct function creates a transaction object. A transaction object must be created before invoking the begin function. This function supports the direct memory model. Ada specification: function Create_Direct( Self: Database.Ref; Transaction_name: CORBA.String ) return db_parms_t.Transaction; Argument list for Ada: Self Database object Transaction_name name of transaction Output: a reference to the named transaction. 10.2.6 begin direct Description: The begin_direct function starts a transaction. Transactions must be explicitly created and started; they are not automatically created when a database is opened. This function supports the direct memory model. Ada specification: procedure IDL_Begin_Direct( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction ); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.2.7 commit direct Description: The commit_direct 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. This function supports the direct memory model. Ada specification: procedure Commit_Direct( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction ); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.2.8 abort direct Description: The abort_direct 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. This function supports the direct memory model. Ada specification: procedure IDL_Abort_Direct( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 10.2.9 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. Ada specification: procedure Checkpoint( Self: Database.Ref; Transaction_Ptr: db_parms_t.Transaction); Argument list for Ada: Self Database object Transaction_Ptr reference to the transaction 11 Object Request Broker API's in Ada 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 Ada. 11.1 module CORBA In C, the CORBA_Environment argument is used to pass exception data. Since Ada has a native exception facility, the CORBA_Environment is not needed in the Ada implementation. 11.1.1 interface ORB The Ada specification of the package CORBA_ORB can be found in file orb.ads. 11.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. Ada package: CORBA_ORB Ada specification: procedure BOA_init( Argv : in out Arg_List; BOA_Identifier : in OAid; Result : out CORBA.Object); Argument list for Ada: Argv null character string (not used) Boa_Identifier object adapter identifier The BOA is defined as "LMOA". Result Basic Object Adapter (BOA) object reference 11.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. Ada package: CORBA_ORB Ada specification: procedure ORB_init (Argv : in out Arg_List; ORB_Identifier : in ORBid); Argument list for Ada: 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 requested for this process) -ORBase is a required entry; other KEYs are optional. Orb_Identifier identification of the ORB. The ORB is defined as "LMORB". 11.1.1.3 list initial services Description: The list_initial_services routine will read ORB services listed in the file initref.cfg. Ada package: CORBA_ORB Ada specification: procedure List_Initial_Services (Services_ObjectIDList : in out ObjectIDList); Argument list for Ada: Services_ObjectIDList Each item on the list is a blank-delimited string containing: Identifier IP_address ASE_Name Port_Number Interface_Name 11.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 can be retrieved from the string by the string_to_object function. Ada specification: procedure Object_To_String (Obj : in CORBA.Object; Str : in out CORBA.String); Argument list for Ada: Obj object reference Str character string representing the Object to the ORB 11.1.1.5 resolve initial references Description: The resolve_initial_references routine will provide a reference object for an ORB service, such as NameService. Ada specification: function Resolve_Initial_References (Identifier : in ObjectID) return CORBA.Object; Argument list for Ada: Identifier String identifying the object. Output: Object reference 11.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. Ada specification: function String_To_Object (Str : in CORBA.String) return CORBA.Object; Argument list for Ada: Str string representing the object, obtained from object_to_string 11.1.2 interface Object The Ada specification of package CORBA_Object can be found in file Object.ads. 11.1.2.1 duplicate Description: The duplicate function allows an application to obtain a copy of an object. If the object exists, its reference count is incremented. If the object doesn't exist, an OBJECT_NOT_EXIST exception is raised. Ada package: CORBA_Object Ada specification: function Duplicate (Self : in Corba.Object) return Corba.Object; Argument list for Ada: Self Object to be duplicated Output: duplicate object 11.1.2.2 is equivalent Description: The is_equivalent function will return TRUE if the two objects passed in are equal. Otherwise it will return FALSE. If the first object does not exist, an OBJECT_NOT_EXIST exception will be raised. Ada package: CORBA_Object Ada specification: function Is_Equivalent (Self : in Corba.Object; Other_Object : in Corba.Object) return CORBA.Boolean; Argument list for Ada: Self first object reference Other other object reference Output: TRUE or FALSE. 11.1.2.3 is nil (is null) 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. Ada package: CORBA_Object Ada specification: function Is_Nil (Self : in Corba.Object) return CORBA.Boolean; function Is_Null (Self : in Corba.Object) return CORBA.Boolean renames Is_Nil; Output: TRUE or FALSE. 11.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. Ada package: CORBA_Object Ada specification: procedure Release (Self : in out Corba.Object); Argument list for Ada: Self duplicate object to be released 11.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. Ada specification: function Non_Existent (Self : in Corba.Object) return Corba.Boolean; Arguments for Ada: Self the object being tested for existence. Output: TRUE if object does not exist; FALSE if object does exist. 11.1.2.6 hash Description: The hash function returns a hash value for an object. The hash value will be in the range (o.. Maximum), where Maximum 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. If two objects return the same hash value they may be the same object or different objects, but if two objects return a different hash value, they are definitely not identical. See CORBA 7.2.6 for a more detailed explanation. Ada specification: function Hash ( Self : in Corba.Object; Maximum : in Corba.Unsigned_Long) return Corba.Unsigned_Long; Arguments for Ada: Self Object to be hashed Maximum maximum hash value Output: a hash value in the range 0..Maximum. 11.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. Ada specification: procedure Get_Implementation (Self : in Corba.Object; ImpDef : in out CORBA.ImplementationDef); Arguments for Ada: Self the object for which an implentation definition is requested. ImpDef a structure which describes the object implementation. The type ImplementationDef is defined as follows: type ImplementationDef is record InterfaceName : CORBA.String; -- object's interface type CORBA_Upcall_Ptr : System.Address; -- object's upcall routine end record; 11.1.3 interface Basic Object Adapter (BOA) The Ada package CORBA_BOA is found in file boa.ads. In CORBA_BOA type Ref is new CORBA.Object; -- to avoid confusion between the BOA and other objects 11.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. Ada specification: function Create (Self : in Ref; Id : in ReferenceData; Intf : in Corba.InterfaceDef; Impl : in Corba.ImplementationDef) return Corba.Object; Argument list for Ada: Self the BOA object Id reference data Intf interface definition null (Interface Repository not implemented) Impl implementation definition Contains the interface name and the address of the upcall entry point. Output: a new object reference In the CORBA package, the following definitions are given: subtype InterfaceDef is System.Address; type ImplementationDef is record InterfaceName : CORBA.String; CORBA_Upcall_Ptr : System.Address; end record; 11.1.3.2 dispose Description: The dispose function removes an object previously generated with a call to CORBA_BOA.create. The memory is freed. Ada specification: procedure Dispose (Self : in Ref; Obj : in CORBA.Object); Argument list for Ada: Self the BOA object Obj the object to dispose of 11.1.3.3 get id Description: The get_id function returns ID data.If the object passed in is NULL, a BAD_PARM exception is raised. Ada specification: function Get_Id (Self : in Ref; Obj : in Corba.Object) return ReferenceData; Argument list for Ada: Self the BOA object Obj the object we want the ID of Output: ID data 11.1.3.4 implementation is ready Description: The impl_is_ready function is called by each *__BOA_init server stub. It 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. Ada specification: procedure Impl_Is_Ready (Self : in Ref; Impl : in Corba.ImplementationDef); Argument list for Ada: Self the BOA object Impl implementation definition 11.1.3.5 set exception Description: The set_exception function will register an exceptional condition in the environment. Ada specification: procedure Set_Exception (Self : in Ref; Major : in Corba.Exception_Type; Userid : in Corba.string; Param : in System.Address); Argument list for Ada: Self the BOA object Major the exception type Userid character string identifying the exception Param pointer to data associated with the exception 11.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. Ada specification: procedure setsched( self : in ref; pri : in CORBA.Long Sched_Mode : in int); Argument List for Ada: self BOA object pri select_wait priority for this server 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 11.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. Ada specification: procedure preempt( self : in ref; flag : in CORBA.Boolean); Argument List for Ada: self BOA object flag TRUE to allow preemption; FALSE to disallow preemption. Output: None 11.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. Ada specification: function create_group( self : in ref; reliable : in CORBA.Boolean; timeout : in CORBA.Float) return CORBA.Object; Argument List for Ada: self 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 allotted timeout period, then broadcast will disconnect that server and return an error. timeout timeout period, in floating point milliseconds Output: broadcast group object 11.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. Ada specification: procedure join( self : in ref; obj : in CORBA.Object); Argument List for Ada: self BOA object obj broadcast group object Output: None 11.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. Ada specification: procedure leave( self : in ref; obj : in CORBA.Object); Argument List for Ada: self BOA object obj broadcast group object 11.2 module Common Object Services - Event Communication An event is a communication action taken by a single object. CORBA 2.0 describes 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. The specification of package CosEventComm can be found in file event_def.ads. 11.2.1 register Description: The register procedure is called to register an event communication service. 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. The register procedure is specified in package CosEventComm_Impl. The specification of package CosEventComm_Impl can be found in file event_impl.ads. Ada specification: procedure register( push : system.address; pull : system.address; try_pull : system.address); Argument List for Ada: push application-specific push function pull application-specific pull function try_pull application-specific try_pull function 11.2.2 interface Pull Consumer The Ada specification of package Pull_Consumer can be found in file event.ads. 11.2.2.1 disconnect pull consumer Description: The disconnect_pull_consumer function breaks off communications with a previously defined pull_consumer object. Ada specification: procedure Disconnect_pull_Consumer( Self: in Ref); Argument list for Ada: Self pull_consumer object 11.2.3 interface Pull Supplier The Ada specification of package Pull_Supplier can be found in file event.ads. 11.2.3.1 disconnect pull supplier Description: The disconnect_pull_supplier function breaks off communications with a previously defined pull_supplier object. Ada specification: procedure Disconnect_Pull_Supplier(Self: in Ref); Argument list for Ada: Self pull_supplier object 11.2.3.2 pull Description: The pull function will return event data if event data is available. The pull function will block processing until the event occurs. If event communication has already been disconnected, the Disconnect exception is raised. Ada specification: function Pull( Self: in Ref) return CORBA.Any; Argument list for Ada: Self pull_supplier object Output: event data 11.2.3.3 try pull Description: The try_pull function will return event data and set the Has_Event flag to TRUE if event data is available. 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. Ada specification: procedure try_Pull( Self : in Ref; Has_Event : out CORBA.Boolean; Result : out CORBA.Any); Argument list for Ada: Self pull_supplier object Has_Event flag to check if event occurred Result event data will be written here 11.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. Ada specification: procedure create( self: in ref; pull: in system.address; try_pull: in system.address); Argument List for Ada: self PullSupplier object pull application specific pull function try_pull application specific try_pull function 11.2.4 interface Push Consumer The Ada specification of package Push_Consumer can be found in file event.ads. 11.2.4.1 disconnect push consumer Description: The disconnect_push_consumer function breaks off communications with a previously defined push_consumer object. Ada specification: procedure Disconnect_Push_Consumer(Self: in Ref); Argument list for Ada: Self push_consumer object 11.2.4.2 push Description: The push function moves data to the consumer of the data. Ada specification: procedure Push( Self: in Ref; Data: in CORBA.Any); Argument list for Ada: Self push_consumer object Data data to be pushed 11.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. Ada specification: procedure create( self: in ref; push: in system.address); Argument List for Ada: self PushConsumer object push application specific push function 11.2.5 interface Push Supplier The Ada specification of package Push_Supplier can be found in file event.ads. 11.2.5.1 disconnect push supplier Description: The disconnect_push_supplier function breaks off communications with a previously defined push_supplier object. Ada specification: procedure Disconnect_Push_Supplier( Self: in Ref); Argument list for Ada: Self push_supplier object 11.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 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 volume 1 for more discussion. Also, see chapter 4 of the OMG document 'CORBA Services: Common Object Services Specification'. Each of the Proxy interfaces inherits from a CosEventComm interface. 11.3.1 interface Proxy Push Consumer A push supplier needs to define a ProxyPushConsumer type of event channel to receive data. ProxyPushConsumer operations are defined in the CosEventChannelAdmin_ProxyPushConsumer package. 11.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. Ada Specification: procedure push( self: in ref; data: in CORBA.Any); Argument list for Ada: self ProxyPushConsumer object data data to be pushed Output: None. 11.3.1.2 disconnect push consumer Description: The disconnect_push_consumer function breaks off communication with a previously defined ProxyPushConsumer object. Ada Specification: procedure disconnect_push_consumer( self: in ref); Argument list for Ada: self ProxyPushConsumer object Output: none 11.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. Ada Specification: procedure connect_push_supplier( self: in ref; push_supplier: in CosEventComm_PushSupplier.ref); Argument list for Ada: self ProxyPushConsumer object push_supplier PushSupplier object Output: None 11.3.2 Proxy Pull Supplier A pull consumer needs to define a ProxyPullSupplier type of event channel to supply data. These operations are defined in package CosEventChannelAdmin_ProxyPullSupplier. 11.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. Ada Specification: function pull( self: in ref) return CORBA.Any; Argument list for Ada: self ProxyPullSupplier object Output: Any type of data. 11.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. Ada Specification: procedure try_pull( self : in ref; has_event : out CORBA.Boolean; Result : out CORBA.Any); Argument list for Ada: self ProxyPullSupplier object has_event Flag will be set to FALSE if the event has not occurred (no data). Output: Any type of data. 11.3.2.3 disconnect pull supplier Description: The disconnect_pull_supplier function breaks off communication with a previously defined ProxyPullSupplier object. Ada Specification: procedure disconnect_pull_supplier( self: in ref); Argument list for Ada: self ProxyPullSupplier object Output: None. 11.3.2.4 connect pull supplier Description: The connect_pull_consumer function defines the second step for connecting a pull consumer to the event channel. Ada Specification: procedure connect_pull_consumer( self : in ref; pull_consumer : in CosEventComm_PullConsumer.ref); Argument list for Ada: self ProxyPullSupplier object pull_consumer PullConsumer object Output: none 11.3.3 Proxy Pull Consumer A pull supplier needs to define a ProxyPullConsumer type of event channel to consume data. These operations are defined in package CosEventChannelAdmin_ProxyPullConsumer. 11.3.3.1 disconnect pull consumer Description: The disconnect_pull_consumer function breaks off communication with a previously defined ProxyPullConsumer object. Ada Specification: procedure disconnect_pull_consumer( self: in ref); Argument list for Ada: self ProxyPullConsumer object Output: None. 11.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. Ada Specification: procedure connect_pull_supplier( self : in ref; pull_supplier : in CosEventComm_PullSupplier.ref); Argument list for Ada: self ProxyPullConsumer object pull_supplier PullSupplier object Output: None 11.3.4 Proxy Push Supplier A push consumer needs to define a ProxyPushSupplier type of event channel to supply data. These operations are defined in package CosEventChannelAdmin_ProxyPushSupplier. 11.3.4.1 disconnect push supplier Description: The disconnect_push_supplier function breaks off communication with a previously defined ProxyPushSupplier object. Ada Specification: procedure disconnect_push_supplier( self: in ref); Argument list for Ada: self ProxyPullSupplier object Output: None 11.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. Ada Specification: procedure connect_push_consumer( self : in ref; push_consumer : in CosEventComm_PushConsumer.ref); Argument list for Ada: self ProxyPullSupplier object push_consumer PushConsumer object Output: none. 11.3.5 interface Consumer Admin The ConsumerAdmin interface is used by consumers to obtain proxy suppliers. These operations are defined in package CosEventChannelAdmin_ConsumerAdmin. 11.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. Ada Specification: function obtain_push_supplier( self: in ref) return CosEventChannelAdmin_ProxyPushSupplier.ref; Argument list for Ada: self ConsumerAdmin object Output: A ProxyPushSupplier type object. 11.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. Ada Specification: function obtain_pull_supplier( self: in ref) return CosEventChannelAdmin_ProxyPullSupplier.ref; Argument list for Ada: self ProxyPullSupplier object Output: A ProxyPullSupplier type object. 11.3.6 interface Supplier Admin The SupplierAdmin interface is used by suppliers to obtain proxy consumers. These operations are defined in package CosEventChannelAdmin_SupplierAdmin. 11.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. Ada Specification: function obtain_push_consumer(self: in ref) return CosEventChannelAdmin_ProxyPushConsumer.ref; Argument list for Ada: self SupplierAdmin object Output: A ProxyPushConsumer type object. 11.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. Ada Specification: function obtain_pull_consumer(self: in ref) return CosEventChannelAdmin_ProxyPullConsumer.ref; Argument list for Ada: self SupplierAdmin object Output: A ProxyPullConsumer type object. 11.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. These operations are defined in package CosEventChannelAdmin_EventChannel. 11.3.7.1 for consumers Description: The for_consumers function returns a consumer administration object. Ada Specification: function for_consumers(self: in ref) return CosEventChannelAdmin_ConsumerAdmin.ref; Argument list for Ada: self EventChannel object Output: A ConsumerAdmin type object. 11.3.7.2 for suppliers Description: The for_suppliers function returns a supplier administration object. Ada Specification: function for_suppliers(self: in ref) return CosEventChannelAdmin_SupplierAdmin.ref; Argument list for Ada: self EventChannel object Output: A SupplierAdmin type object. 11.3.7.3 destroy Description: The destroy function removes the event channel. Ada Specification: procedure destroy(self: in ref); Argument list for Ada: self EventChannel object Output: None. 11.3.8 interface Event Channel Factory An event channel factory is an object which can create event channels. These operations are defined in package CosEventChannelAdmin_EventChannelFactory. 11.3.8.1 create event channel Description: The create_eventchannel function returns an event channel object. Ada Specification: function create_eventchannel( self : in ref; size : in CORBA.Long) return CosEventChannelAdmin_EventChannel.ref; Argument list for Ada: self ProxyPullSupplier object size number of bytes for event channel buffer Output: An EventChannel type object. 11.4 module Common Object Services - Life Cycle Life Cycle services provide methods for creating, removing, copying and moving objects. 11.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. 11.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. Ada specification: procedure find_factories( self: in ref; factory_key: in CosLifeCycle.Key; Result: in out CosLifeCycle.Factories); Argument list for Ada: self factory finder object factory_key factory key, which is a CosNaming_Name. See bind_new_context. Result a sequence of factories. Sequence definition follows: package CosLifeCycle is type Factory is new Corba.Object; package Factories_Factory_unbounded is new CORBA_Sequences_Basic_Unbounded_Managed_Iterator(Factory); type Factories is new Factories_Factory_unbounded.sequence; end CosLifeCycle; See Appendix D for a listing of CORBA_Sequences_Basic_Unbounded_Managed_Iterator. 11.4.2 interface Life Cycle Object An object which is of class LifeCycleObject has methods to copy, move, and remove itself. 11.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. Ada specification: function copy( self: in ref; there: in CosLifeCycle_FactoryFinder.ref; the_criteria: in CosLifeCycle.Criteria) return CosLifeCycle_LifeCycleObject.ref; Argument list for Ada: self the LifeCycleObject object there a factory finder object the_criteria a sequence of name/value pairs passed to the object constructor Output: a copy of the LifeCycleObject object 11.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. Ada specification: procedure move( self: in ref; there: in CosLifeCycle_FactoryFinder.ref; the_criteria: in CosLifeCycle.Criteria); Argument list for Ada: self the LifeCycleObject object there a factory finder object the_criteria a sequence of name/value pairs passed to the object constructor Output: none 11.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. Ada specification: procedure remove( self: in ref); Argument list for Ada: self the LifeCycleObject object Output: none 11.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. 11.4.3.1 create object Description: The function create_object will create an object given a key and a set of criteria. Ada specification: function create_object( self: in ref; k: in CosLifeCycle.Key; the_criteria: in CosLifeCycle.Criteria) return CORBA.Object; Argument list for Ada: self the generic factory object k the name of the object to create the_criteria a sequence of name/value pairs passed to the object constructor Output: The object created by the generic factory. 11.4.3.2 supports Description: The function supports returns TRUE if the generic factory can create an object given a key. Ada specification: function supports( self: in ref; k: in CosLifeCycle.Key) return CORBA.Boolean; Argument list for Ada: self the generic factory object k the name of the object to create Output: TRUE or FALSE 11.5 module Common Object Services - Naming Corba naming services are used to manage object names. Here are some basic definitions: binding A name-to-object association is called a name binding. To bind a name is to create a name binding in a given context. A name binding is always defined relative to a naming context. There is no requirement that all objects must be named. context A naming context is an object that contains a set of name bindings in which each name is unique. Different names can be bound to an object in the same or different contexts at the same time. compound name Because a context is like any other object, it can also be bound to a name in a naming context. binding contexts in other contexts creates a naming graph. The sequence of names in a naming graph is called a compound name. A compound name defines a path in the naming graph used to resolve an object reference. resolution To resolve a name is to determine the object associated with the name in a given context. A name is always resolved relative to a context - there are no absolute names. The Ada specification of package Naming can be found in file naming_def.ads. 11.5.1 interface NamingContext The Ada specification of package NamingContext can be found in file naming.ads. 11.5.1.1 bind Description: The function bind binds a name to an object in a naming context. This operation requires that the context is properly bound prior to invoking this function. If the name has already been used for an object in the given context the AlreadyBound exception is raised. Ada specification: procedure Bind( Self : in Ref; N : in CosNaming.Name; Obj : in CORBA.Object); Argument list for Ada: Self: NamingContext object N: Name to bind Obj: object to bind 11.5.1.2 bind context Description: The function bind_context binds a name to a context. Constraint: The client calls this method indirectly through bind_new_context. Ada specification: procedure Bind_Context( Self : in Ref; N : in CosNaming.Name; NC : in CosNaming_NamingContext.Ref); Argument list for Ada: Self NamingContext object N Name to bind NC NamingContext to bind 11.5.1.3 bind new context Description: The bind_new_context function creates a new context and binds it to the name supplied as an argument. This method should be called by user to create a new context and bind an object to it. If the name has already been used for a context the AlreadyBound exception is raised. Constraint: This method calls new_context and bind_context to allocate space and record the information in the name server. Ada specification: function Bind_New_Context( Self : in Ref; N : in CosNaming.Name) return CosNaming_NamingContext.Ref; Argument list for Ada: Self: naming context object N: name to bind Output: new naming context object 11.5.1.4 list Description: The list operation allows a client to iterate through a set of bindings in a naming context. The client passes in a naming context. The naming context is resolved using a cross reference table. If found and named objects are bound to this context then a binding list of not more that max (input parameter) is created and returned. If there are additional names bound to this context an object reference is created; then it is returned to the client as a binding iterator. If the input naming context is not found in the cross reference table, a NotFound exception is raised. If no objects are bound to the context, a NotFound exception is raised. If the input parameter max is less than 1, a CannotProceed exception is raised. If a binding iterator could not be created, a CannotProceed exception is raised. Ada specification: procedure List( Self : in Ref; How_Many : in CORBA.Unsigned_Long; BL : in out CosNaming.BindingList; BI : out CosNaming_BindingIterator.Ref); Argument list for Ada: Self: NamingContext object How_Many: maximum number of bindings to return in BL BL : binding list BI : binding iterator, if more bindings than allowed by How_Many. 11.5.1.5 new context Description: The new_context function returns a naming context. Constraint: This method should not be called directly by a client. This method is called indirectly when the client calls bind_new_context. Ada specification: function New_Context(Self : in Ref) return CosNaming_NamingContext.Ref; Argument list for Ada: Self: NamingContext object Output: new naming context object 11.5.1.6 resolve Description: The resolve function retrieves an object bound to a given name in a given context. If the given name isn't found in the given context, a NotFound exception is raised. The given name must exactly match the bound name. If the given name isn't found in any context, a CannotProceed exception is raised. Ada specification: function resolve( Self : in Ref; N : in CosNaming.Name) return CORBA.Object; Argument list for Ada: Self: NamingContext object N: Name to use to resolve object Output: resolved object 11.5.1.7 destroy Description: The destroy function deletes a naming context. Ada Specification: procedure destroy( self: in ref); Argument list for Ada: self NamingContext object 11.5.1.8 rebind Description: The rebind function creates a binding of a name and an object in the naming context even if the name is already bound in the context. Naming contexts that are bound using rebind do not participate in resolution when compound names are passed to be resolved. Ada specification: procedure Rebind( Self : in Ref; N : in CosNaming.Name; Obj : in CORBA.Object); Argument list for Ada: Self: NamingContext object N: Name to bind Obj: object to bind 11.5.1.9 rebind_context Description: The rebind_context function creates a binding of a name and a naming context even if the name is already bound in the context. Naming contexts that are bound using rebind_context participate in resolution when compound names are passed to be resolved. Ada specification: procedure Rebind_Context( Self : in Ref; N : in CosNaming.Name; NC : in CosNaming_NamingContext.Ref); Argument list for Ada: Self: NamingContext object N: Name to rebind NC: Naming context to rebind 11.5.1.10 unbind Ada specification: procedure Unbind( Self : in Ref; N : in CosNaming.Name); Argument list for Ada: Self: NamingContext object N: Name to unbind 11.5.2 BindingIterator The Ada specification of package BindingIterator can be found in file naming.ads. 11.5.2.1 destroy Description: The destroy function deletes a BindingIterator. Ada specification: procedure destroy(Self: in Ref); Argument list for Ada: Self: BindingIterator object 11.5.2.2 next N Description: The next_n function returns at most the next N bindings. If there are no bindings, FALSE is returned. Ada specification: procedure next_n( Self : in Ref; How_Many : in CORBA.Unsigned_Long; BL : in out CosNaming.BindingList; Result : out CORBA.Boolean); Argument list for Ada: Self BindingIterator object How_Many maximum number of bindings to return in the binding list BL binding list returned Result TRUE if a binding list was returned in BL 11.5.2.3 next one Description: The next_one function returns the next binding. If there are no bindings, FALSE is returned. If the context object is not found, the NotFound exception is raised. Ada specification: procedure next_one( Self : in Ref; B : in out CosNaming.Binding; Result : out CORBA.Boolean); Argument list for Ada: Self: BindingIterator object B: next binding from the binding iterator Result: True if a binding is returned in B. 11.6 module Common Object Services - Stream The interfaces provided by the CosStream module are: Streamable; StreamableFactory; and StreamIO. See 'CORBA Services: Common Object Services Specification' section 8.6. 11.6.1 interface Streamable In order for an object to be externalized, it must inherit from the Streamable interface. Since Ada is not an object-oriented language, inheritance is implemented by including the Streamable interface in the IDL which defines the client's module. See example module Helo in ./orb/external/objects.idl Package name: CosStream_Streamable 11.6.1.1 external form id Of Description: A streamable object must have a readonly attribute named external_form_id of type CosLifeCycle_Key. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. Ada specification: procedure external_form_id_Of( self : in ref; Result : in out CosLifeCycle.Key); Argument list for Ada: sefl Streamable object result CosLifeCycle.Key to be used to find the Factory needed for internalization. 11.6.1.2 externalize to stream Description: A streamable object must have an operation which allows a client to externalize it. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. Ada specification: procedure externalize_to_stream( self : in ref; targetStreamIO : in CosStream_StreamIO.ref); Argument list for Ada: self Streamable object targetStreamIO StreamIO object to perform write operations 11.6.1.3 internalize from stream Description: A streamable object must have an operation which allows a client to internalize it. It will use the FactoryFinder type object named there to find a Factory which will create a new object from the externalized form of the streamable object. The stub for this function will be automatically generated by the IDL/ODL preprocessor from your IDL. Ada specification: procedure internalize_from_stream( self : in ref; sourceStreamIO : in CosStream_StreamIO.ref; there : in CosLifeCycle_FactoryFinder.ref); Argument list for Ada: self uninitialized Streamable object from StreamableFactory sourceStreamIO StreamIO object to perform read operations there A FactoryFinder type object 11.6.2 interface Streamable Factory A StreamableFactory must exist for each externalizable object. Package name: CosStream_StreamableFactory 11.6.2.1 create uninitialized Description: This is the first step towards internalization. The create_uninitialized operation creates a Streamable object which can then be passed to the internalize_from_stream operation. Ada specification: function create_uninitialized( self : in ref) return CosStream_Streamable.ref; Argument list for Ada: self StreamableFactory object Output: uninitialized Streamable object 11.6.3 interface StreamIO A StreamIO interface performs writes for externalization and reads for internalization. 11.6.3.1 write string Description: The write_string operation writes a character string to the Stream. Ada specification: procedure write_string( self : in ref; aString : in CORBA.string); Argument list for Ada: self StreamIO object aString a character string 11.6.3.2 write char Description: The write_char operation writes a character to the Stream. Ada specification: procedure write_char( self : in ref; aChar : in CORBA.Char); Argument list for Ada: self StreamIO object aChar a character Output: None 11.6.3.3 write octet Description: The write_octet operation writes one 8-bit value to Stream. Ada specification: procedure write_octet( self : in ref; anOctet : in CORBA.Octet); Argument list for Ada: self StreamIO object anOctet an 8-bit value, guaranteed not to undergo any conversion 11.6.3.4 write unsigned long Description: The write_unsigned_long operation writes an unsigned long integer to the Stream. Ada specification: write_unsigned_long procedure write_unsigned_long( self : in ref; anUnsignedLong : in CORBA.Unsigned_Long); Argument list for Ada: self StreamIO object anUnsignedLong an unsigned integer in the range 0.. (2 ** 32)-1. 11.6.3.5 write unsigned short Description: The write_unsigned_short operation writes an unsigned long integer to the Stream. Ada specification: procedure write_unsigned_short( self : in ref; anUnsignedShort : in CORBA.Unsigned_Short); Argument list for Ada: self StreamIO object anUnsignedShort an unsigned integer in the range 0.. (2 ** 16)-1. 11.6.3.6 write long Description: The write_long operation writes a signed long integer to the Stream. Ada specification: procedure write_long( self : in ref; aLong : in CORBA.Long); Argument list for Ada: self StreamIO object aLong an integer in the range -2 ** 31 .. (2 ** 31) - 1 Output: None 11.6.3.7 write short Description: The write_short operation writes a signed short integer to the Stream. Ada specification: procedure write_short( self : in ref; aShort : in CORBA.Short); Argument list for Ada: self StreamIO object aShort an integer in the range -2 ** 15 .. (2 ** 15) - 1 11.6.3.8 write float Description: The write_float operation writes a floating point number to the stream. Ada specification: procedure write_float( self : in ref; aFloat : in CORBA.Float); Argument list for Ada: self StreamIO object aFloat a single-precision floating point number 11.6.3.9 write double Description: The write_double operation writes a double-precision floating point number to the stream. Ada specification: procedure write_double( self : in ref; aDouble : in CORBA.Double); Argument list for Ada: self StreamIO object aDouble a double-precision floating point number 11.6.3.10 write boolean Description: The write_boolean operation writes a value which can be either TRUE or FALSE. Ada specification: procedure write_boolean( self : in ref; aBoolean : in CORBA.Boolean); Argument list for Ada: self StreamIO object aBoolean a value which can be either TRUE or FALSE. 11.6.3.11 read string Description: The read_string operation reads a character string from the Stream. Ada specification: procedure read_string( self : in ref; Result : in out CORBA.string); Argument list for Ada: self StreamIO object Result a character string 11.6.3.12 read char Description: The read_char operation reads a character from the Stream. Ada specification: function read_char( self : in ref) return CORBA.Char; Argument list for Ada: self StreamIO object Output: a character 11.6.3.13 read octet Description: The read_octet operation reads one 8-bit value to Stream. Ada specification: function read_octet( self : in ref) return CORBA.Octet; Argument list for Ada: self StreamIO object Output: an 8-bit value, guaranteed not to undergo any conversion 11.6.3.14 read unsigned long Description: The read_unsigned_long operation reads an unsigned long integer from the Stream. Ada specification: function read_unsigned_long( self : in ref) return CORBA.Unsigned_Long; Argument list for Ada: self StreamIO object Output: an unsigned integer in the range 0.. (2 ** 32)-1. 11.6.3.15 read unsigned short Description: The read_unsigned_short operation reads an unsigned long integer from the Stream. Ada specification: function read_unsigned_short( self : in ref) return CORBA.Unsigned_Short; Argument list for Ada: self StreamIO object Output: an unsigned integer in the range 0.. (2 ** 16)-1. 11.6.3.16 read long Description: The read_long operation reads a signed long integer from the Stream. Ada specification: function read_long( self : in ref) return CORBA.Long; Argument list for Ada: self StreamIO object Output: an integer in the range -2 ** 31 .. (2 ** 31) - 1 11.6.3.17 read short Description: The read_short operation reads a signed short integer from the Stream. Ada specification: function read_short( self : in ref) return CORBA.Short; Argument list for Ada: self StreamIO object Output: an integer in the range -2 ** 15 .. (2 ** 15) - 1 11.6.3.18 read float Description: The read_float operation reads a floating point number from the Stream. Ada specification: function read_float( self : in ref) return CORBA.Float; Argument list for Ada: self StreamIO object Output: a single-precision floating point number 11.6.3.19 read double Description: The read_double operation reads a double-precision floating point number from the Stream. Ada specification: function read_double( self : in ref) return CORBA.Double; Argument list for Ada: self StreamIO object Output: a double-precision floating point number 11.6.3.20 read boolean Description: The read_boolean operation reads a value which can be either TRUE or FALSE. Ada specification: function read_boolean( self : in ref) return CORBA.Boolean; Argument list for Ada: self StreamIO object Output: A boolean value. 11.7 module Common Object Services - Externalization The externalization service provides means to externalize and internalize objects. "Externalize" means to record the object on external media as a stream of data. "Internalize" means to create an object from a stream of data on external media. See section 8.5 of 'CORBA services: Common Object Services Specification'. 11.7.1 interface Stream A client who wishes to externalize an object must first have a Stream object in which to record the stream of data. Package name: CosExternalization_Stream 11.7.1.1 externalize Description: The externalize operation externalizes the passed Streamable object by invoking the Streamable object's externalize_to_stream operation. Ada specification: procedure externalize( self : in ref; theObject : in CosStream_Streamable.ref); Argument list for Ada: self an Externalization_Stream object theObject a Streamable object 11.7.1.2 internalize Description: The internalize operation internalizes an object from the Stream by using the FactoryFinder to create a Streamable object, and then invoking the Streamable object's internalize_from_stream operation. Ada specification: function internalize( self : in ref; there : in CosLifeCycle_FactoryFinder.ref) return CosStream_Streamable.ref; Argument list for Ada: self an Externalization_Stream object there a Factory Finder to generate the internalized object from the stream. Output: the internalized Streamable object 11.7.1.3 flush Description: The flush operation requests that an external representation is committed to its storage medium (file, tape, etc.). Ada specification: procedure flush( self: in ref); Argument list for Ada: self an Externalization_Stream object 11.7.2 interface Stream Factory This interface can create a Stream without specifying any special characteristics. Package name: CosExternalization_StreamFactory 11.7.2.1 create Description: The create function creates a Stream for externalization. Ada specification: function create( self : in ref) return CosExternalization_Stream.ref; Argument list for Ada: self an Externalization_StreamFactory object Output: An Externalization_Stream object. 11.7.3 interface File Stream Factory This interface can create a File Stream. Package name: CosExternalization_FileStreamFactory 11.7.3.1 create Description: The create function creates a File Stream for externalization. Ada specification: function create( self : in ref; theFileName : in CORBA.string) return CosExternalization_Stream.ref; Argument list for Ada: self FileStreamFactory object theFileName character string specifying the file name. Output: An Externalzation_Stream object. 12 Encapsulated Scheduler API's in Ada This section provides a description of the encapsulated scheduler's Application Program Interface functions in Ada. These functions are specified in the package named Scheduler. 12.1 Register Description: The register procedure registers the ASE name, group name, and priority specifications with the encapsulated scheduler for the current ASE. This procedure must be called once prior to any subsequent calls to any of the other encapsulated scheduler routines. Real-time priority ranges from ES_Limits.Minimum_Priority for the lowest real-time priority through ES_Limits.Maximum_Priority for the highest real-time priority. Priority 0 indicates non-real-time UNIX scheduling. The value of ES_Limits.Maximum_Priority is system dependent. The priority level of the ASE will be initially set to the input Current_Priority. Minimum_Priority passed in is the minimum priority that the ASE can be changed to. Maximum_Priority passed in is the maximum priority that the ASE can be changed to. If the minimum and current priorities are set to 0, and the maximum is set to ES_Limits.Maximum_Priority, the ES will automatically establish the current priority when a call to the rate routine is made. The calculated priority will based on the deadline. If there is no deadline then the period will be used, so that the higher frequency ASE's will have the higher priorities (rate monotonic scheduling). The UNIX signals SIGINT, SIGUSR1, SIGALRM, SIGFPE, SIGSEGV, and SIGBUS are attached to the encapsulated scheduler's signal handler. SIGINT will cause the routine exit to be called, which will unregister the ASE before it terminates. SIGUSR1 is used to generate user events. SIGALRM is used for periodic scheduling (ES_RATE event). SIGFPE, SIGSEGV, and SIGBUS are used for exception processing via the es_exception call. Constraints: This routine must be called once prior to any subsequent calls to any of the other ES routines. Ada specification: procedure Register ( As_Ase : in Ase_Name; As_Ase_Group : in Ase_Name; Minimum_Priority : in Priorities; Maximum_Priority : in Priorities; Current_Priority : in Priorities); Argument list for Ada: As_ASE character string naming the schedulable entity As_ASE_Group character string naming the group Minimum_Priority minimum priority that the ASE can be changed to. Maximum_Priority maximum priority that the ASE can be changed to Current_Priority initial priority that the ASE will be assigned 12.2 Execute Description: The execute procedure executes a UNIX command in the background as a child process. The first field in the command must be an executable file located in a directory defined by the environment variable PATH or a complete path name. The input parameter sync is set to ES_SYNC or ES_ASYNC for synchronous or asynchronous execution of the command respectively. For the threads version of the ES the command string pointer may be replaced by a pointer to a routine. For synchronous execution the routine will be called directly. Upon completion of the routine control will be returned to the calling application. For asynchronous execution a thread will be created for the routine. Control will be returned to the calling application while the thread is still executing. Ada specification: procedure Execute (Asynchronous : in Boolean; Command : in String); Argument list for Ada: Asynchronous FALSE for synchronous execution or TRUE for asynchronous execution command name of an executable file located in a directory defined by the environment variable PATH or a complete path name.. For the threads version of the ES the command string pointer may be replaced by a pointer to a routine. 12.3 Set Priority Description: The priority procedure changes the priority of an ASE or a group of ASE's to the input priority. A null ASE name will change the priority of the current ASE. The priority level must be within the minimum/maximum range defined by the register call for the specified ASE. Ada specification: procedure Priority (Of_Ase : in Ase_Name; To_Priority : in Priorities); Argument list for Ada: Of_ASE an ASE name or a group name. Null for current ASE. priority priority level 12.4 Resume Description: This procedure resumes the execution of a suspended ASE or a group of ASE's. Ada specification: procedure Resume (Ase : in Ase_Name); Argument list for Ada: ASE an ASE or a group name. 12.5 Suspend Description: This procedure will suspend the execution of an ASE, a group of ASE's, or all ASE's other than itself. A null ASE name will suspend the current ASE. The ASE(s) will remain suspended, ignoring all events, until a resume event is received. Ada specification: procedure Suspend (Ase : in Ase_Name); Argument list for Ada: ASE an ASE or a group name. Null for current ASE. "ES_BROADCAST" for all registered ASE's other than the requester. 12.6 Terminate Description: This procedure will terminate the execution of an ASE, a group of ASE's, or all ASE's other than itself. Constraint: For threads this routine must be called to terminate the thread. Ada specification: procedure Terminate_Ase (Ase : in Ase_Name); Argument list for Ada: ASE an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's other than the requester. 12.7 Periodic Rate Description: The rate procedure Initiates an interval timer to cause an ES_RATE event to occur periodically based on the input time period specified in milliseconds. The deadline will be used to detect that the ASE has executed past the input time deadline specified in milliseconds. If the deadline time period is exceeded a deadline event will occur. A deadline value of 0.0 will disable the deadline event from occurring. The anticipated_use input is the percentage of CPU utilization which is expected for this ASE. If the total utilization for all periodic rate ASE's exceeds 100% this routine will return with an error. Ada specification: procedure Rate (Ase : in Ase_Name; Timer_Rate : in Integer; --!dummy Processing_Deadline : in Integer; --!dummy Anticipated_Usage : in Percentage); Argument list for Ada: ASE an application schedulable entity name timer_rate period between invocations, in milliseconds Processing_deadline deadline for completion of execution, in milliseconds anticipated_usage estimated whole number percent of CPU utilization 12.8 Periodic Rate End Description: The rate_end procedure will notify the encapsulated scheduler when a periodic ASE has completed. If this routine is called subsequent to the deadline defined by the call to rate a deadline event will be issued. Ada specification: procedure Rate_End; Argument list for Ada: none 12.9 Timer Description: This procedure initiates a timer, defined by number, to cause an event to occur based on the input time period. Ada specification: procedure Timer (For_Ase : in Ase_Name; In_Milliseconds : in Milliseconds; On_Timer : in Timers; The_Event : in Event); Argument list for Ada: For_ASE an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's. In_Milliseconds delta time for event, in milliseconds. Zero to disable active timer. On_TImer timer number in the range 1 .. ES_Limits.Maximum_Timer The_Event event number in the range defined in ES_Limits. 12.10 Issue Event Description: This procedure issues a user defined event to an ASE or group of ASE's. Ada specification: procedure Issue (To_Ase : in Ase_Name; The_Event : in User_Event); Argument list for Ada: To_ASE an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's other than the requester. The_Event event number in the range defined in ES_Limits. 12.11 Cancel Event Description: This procedure will cancel a queued event for an ASE or group of ASE's. Ada specification: procedure Cancel (For_Ase : in Ase_Name; The_Event : in Event; Number_Of_Instances_To_Cancel : in Integer); Argument list for Ada: For_ASE an ASE or a group name. Null for current ASE. ES_BROADCAST for all registered ASE's. The_Event event number in the range defined in ES_Limits. Number_Of... number of occurrences of the event in the queue to cancel. Zero for all. 12.12 Sleep Description: This function will sleep for the specified number of milliseconds. The granularity of the timeout value is system dependent. An input timeout value of 0.0 can be used to yield the processor to another ASE. The amount of time remaining in the sleep request due to being woken earlier than the specified timeout period is returned. Ada specification: function Sleep (For_Milliseconds : in Milliseconds) return Milliseconds; Argument list for Ada: For_Milliseconds time to sleep, in milliseconds. Zero to yield the processor to another ASE. Output: Time remaining from an early return. A negative time value indicates an error condition. 12.13 Wait Description: This function will wait for any event to occur. Ada specification: function Wait (Until_Timeout : in Milliseconds) return Event; Argument list for Ada: Until_Timeout time in milliseconds to suspend the ASE before an event to occurs. A timeout value of zero will suspend forever waiting for an event to occur. A negative timeout value will return immediately. The event will be dequeued. Output: Event number or ES_NOEVENT if no event is currently active. A -1 return value indicates an error. 12.14 Poll Description: This function will poll for the existence of any event. If an event exists it will be dequeued and the event number will be returned. If no event exists a value of 0 will be returned. This is the same as calling es_wait() with a negative argument. Ada specification: function Poll_Event return Event; Argument list for Ada: none Output: Event number or ES_NOEVENT if no event is currently active. A -1 return value indicates an error. 12.15 Poll Event Description: This procedure will poll for the existence of a specified event. If the event number is found on the event queue its position in the queue will be returned. This service can be used to bypass the normal first-in-first-out priority based event scheduling which is implemented with the wait() and poll() services. If the event is handled based on a non-negative return value then the cancel() service should be called to remove the event from the queue. For example: Poll_Event(Some_Event, Queue_Pos, Event_Found); if (Event_Found) then HANDLE_SOME_EVENT(); cancel(NULL,Some_Event,1); end if; Ada specification: procedure Poll_Event (The_Event : in Event; Queue_Position : out Integer; Found_Event : out Boolean); Argument list for Ada: The_Event event to poll for Queue_Position position of event in the event queue Found_Event TRUE if event 12.16 Event Priority Description: This procedure will set the priority level for the input event number. By default all events will have the priority MAX / 2. The event number must be in the range 0 - MAX-1. The priority must be in the range 0 - MAX-1. Events will be handled such that 0 is the highest priority. Events are divided into three groups, DEADLINE, signals, and user events. Events of the same priority will be handled in the order, DEADLINE, signal 1 through signal SIGMAX, and user events first in first out. Ada specification: procedure Event_Priority (Of_Event : in Event; To_Priority : in Priorities); Argument list for Ada: Of_Event event number in the range 0 - MAX-1 To_Priority priority in the range 0 - MAX-1. Zero is the highest priority. 12.17 Event ID Description: This function will return a pointer to the ASE name which originated the last event detected by the es_wait or es_poll routines. Ada specification: function Event_Id return Ase_Name; Argument list for Ada: none Output: ASE name pointer. If no event has been received then a pointer to a null string will be returned. 12.18 Event Handler Description: This procedure will establish an event handler for a specified event. If a handler has been established for an event which has occurred, the handler routine will be called directly from the encapsulated scheduler signal handler. This will preempt the normal execution of the ASE. Upon completion of the handler, ASE execution will commence from where it was preempted. Ada specification: procedure Handler (For_Event : in Event; Handler : in System.Address); Argument list for Ada: event The event number in the range 0 - ES_MAXEVENTS-1. handler Address of a routine which will handle the event. A handler has the following specification in C: void handler(u_int event, char *ASE_name) event is the event number which caused the handler to be invoked ASE_name is the name of the entity which originated the event. 12.19 Signal Description: This procedure will associate a UNIX signal with an encapsulated scheduler event. The input signal number must be in the range 1 - SIGMAX. The signals SIGINT, SIGUSR1, SIGALRM, SIGFPE, SIGSEGV, and SIGBUS are reserved by the encapsulated scheduler. The signals SIGKILL and SIGSTOP are reserved by the operating system and can not be caught. The event number associated with the signal will be same as the signal number. Ada specification: procedure Signal (The_Signal : in Os.Unix_Signal); Argument list for Ada: The_Signal signal number in the range 1 - SIGMAX. 12.20 Semaphore Lock Description: This procedure locks a user semaphore. If the wait flag is TRUE, the ASE will wait for the semaphore to become unlocked before it is locked. If the wait flag is FALSE and the semaphore is locked, the routine will return immediately, indicating that the semaphore is in use. If the lock was locked by this call, a value of TRUE will be returned. Otherwise, a value of FALSE will be returned. The_ASE will be return the name of the ASE which has locked the semaphore. Ada specification: procedure Lock (The_Semaphore : in Semaphore; Wait_If_Locked : in Boolean; Lock_Obtained : out Boolean; The_Ase : out Ase_Name); Argument list for Ada: The_Semaphore semaphore number Wait_If_Locked FALSE or TRUE Lock_Obtained FALSE or TRUE ASE_name a pointer to pass back the ASE name for a locked semaphore. 12.21 Semaphore Unlock Description: This procedure unlocks a user semaphore. Ada specification: procedure Unlock (The_Semaphore : in Semaphore); Argument list for Ada: The_Semaphore semaphore number 12.22 Set Time Description: This procedure sets the system wall clock time based on the input timeval and timezone pointer structure data. The timeval structure represents the number of seconds and microseconds since midnight January 1, 1970. The timezone structure represents the number of minutes west from Greenwich and a daylight savings time flag which applies to the locale. Ada specification: procedure Settime (The_Time : in Delta_Time; Using_Time_Zone : in Time_Zone); Argument list for Ada: The_Time see definition of Delta_Time type below Using_Time_Zone see definition of TIme_Zone below type Delta_Time is record Seconds : Positive; Microseconds : Positive; end record; type Daylight_Savings_Correction is (None, Usa, Australia, Western_Europe, Middle_Europe, Eastern_Europe, Canada); type Time_Zone is record Minutes_West : Integer; Method : Daylight_Savings_Correction; end record; 12.23 Time Scale Description: This procedure will set a scaling rate for the ES timer services. All calls to gettime, elapsed, sleep, wait, rate, and timer will have their wall clock time scaled by the input rate factor specified. Any previously active timers will also be scaled by the specified rate. All ASE's active on the current system will be affected. A rate factor of 0.0, which is equivalent to 1.0, will reset the wall clock time to the normal clock rate. For example, a rate factor of 0.5 will cause the wall clock to run at half speed. Conversely, a rate factor of 2.0 will cause the wall clock to run at double speed. Ada specification: procedure Timescale (Rate : in Float); Argument list for Ada: rate 0.0 will reset the clock to normal rate 0.5 will cause the clock to run at half normal speed 2.0 will cause the clock to run at normal speed 12.24 Get Time Description: This procedure returns the current system clock time. Ada specification: function Gettime return Delta_Time; Argument list for Ada: none Output: See definition of Delta_Time type above. 12.25 Elapsed Time Description: This function returns the elapsed system time, in milliseconds, from the system time passed in to the current system time . Ada specification: function Elapsed (Since : in Delta_Time) return Milliseconds; Argument list for Ada: Since system time from a previous call to Gettime. Output: Elapsed system time in milliseconds. 12.26 Processing Time Description: This procedure returns process accounting information. Ada specification: procedure Proctime (Elapsed_Real_Time : out Os.Clock_Tick; Usage : out Process_Times); Argument list for Ada: Elapsed_Real_Time elapsed time expressed in clock ticks Usage see definition of Process_Times below type Process_Times is record Tms_Utime : Os.Clock_Tick; -- User CPU time Tms_Stime : Os.Clock_Tick; -- System CPU time Tms_Cutime : Os.Clock_Tick; -- Child Process User CPU time Tms_Cstime : Os.Clock_Tick; -- Child Process System CPU time end record; 12.27 Date and Time Description: This procedure returns date and time information. Ada specification: procedure Datetime (In_Zone : in Zone; The_Date : out Date); Argument list for Ada: In_Zone type Zone is (Local, Gmt); The_Date Definition of type Date follows: type Date is record Seconds : Integer range 0 .. 59; Minutes : Integer range 0 .. 59; Hour : Integer range 0 .. 23; Day : Integer range 1 .. 31; Month : Integer range 0 .. 11; Year : Integer range 0 .. 200; Week_Day : Integer range 0 .. 6; Year_Day : Integer range 0 .. 365; Is_Dst : Boolean; end record; 12.28 Time Synchronization Description: This procedure will synchronize the host system with a remote system. Ada specification: procedure Timesync (Remote_System : in String; Es_Server : in String; Set_The_Time : in Boolean; Adjust : in Long_Float; Difference : out Float); Argument list for Ada: Remote_System name of remote system ES_Server name of ES server task on remote system if NULL, a default user name will be used Set_The_Time FALSE = return the difference in milliseconds of the two system times TRUE = synchronize current system time with system time in remote system Adjust adjustment factor Difference if set_flag is FALSE, the difference in milliseconds of the two system times is returned here 12.29 Memory Usage Description: This procedure returns system memory used and free in 1K blocks. Ada specification: procedure Memory (Used : out Positive; Free : out Positive); Argument list for Ada: Used number of used 1K blocks Free number of free 1K blocks 12.30 Error Number Description: This function returns the current value of es_errno which indicates an error condition which occurred on a previous call to an ES routine. This integer number should only be referenced subsequent to an error value being returned by a call to an ES routine. Ada specification: function Errno return Error_Code; Argument list for Ada: none Output: Error codes are defined in C header file es.h. 12.31 Error Message Description: This function returns a string which describes an error condition which occurred in a previous call to an ES routine. This routine should only be called subsequent to an error value being returned by a call to an ES routine. Ada specification: function Errmesg return String; Argument list for Ada: none Output: Error message. 12.32 Select Manager Routines The following APIs support the function select, which is part of the standard UNIX C library (libc.a). The function select_wait is a wrapper around the UNIX select function. (See UNIX man page) The select system call is used to perform I/O multiplexing. It enables the programmer to manage reading and writing to several file descriptors at once without "blocking" indefinitely on any of the operations. For example, a program can use select to poll a terminal; when characters are present to be read, it can read them in and process them. While the select waits, other processing can proceed. 12.32.1 select add fd Description: Add file descriptor / socket to select criteria. Ada specification: procedure Select_Add_FD (Id : in Integer; Mode : in Integer; Pri : in Integer; Func : in System.Address; Sched_Mode : in Integer); Arguments for Ada: Id file descriptor Mode file mode (Read or Write) Pri relative priority of this file descriptor for selection Func function to be invoked (upcall) when the file descriptor becomes available 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: 0 if okay; -1 if error. 12.32.2 select_delete_fd Description: Delete file descriptor / socket from the select criteria. Ada specification: procedure Select_Delete_FD (Id : in Integer); Arguments for Ada: id file descriptor Output: 0 if okay; -1 if error. 12.32.3 select_add_msg Description: Add message queue to select criteria. Ada specification: procedure Select_Add_Msg (Id : in Integer; Mode : in Integer; Pri : in Integer; Func : in System.Address; Sched_Mode : in Integer); Arguments for Ada: id message queue identifier mode file mode pri priority of this message queue in the select criteria func function to be invoked (upcall) when the file descriptor becomes available 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: 0 if okay; -1 if error. 12.32.4 select_delete_msg Description: Delete message queue from the select criteria. Ada specification: procedure Select_Delete_Msg (Id : in Integer); Arguments for Ada: id message queue identifier Output: 0 if okay; -1 if error. 12.32.5 select_add_upcall Description: Add upcall which is called unconditionally. Ada specification: procedure Select_Add_Upcall (Pri : in Integer; Func : in System.Address); Arguments for Ada: pri priority func upcall function Output: 0 if okay; -1 if error. 12.32.6 select delete upcall Description: Delete upcall. Ada specification: procedure Select_Delete_Upcall (Func : in System.Address); Arguments for Ada: func function Output: 0 if okay; -1 if error. 12.32.7 select_wait Description: Wait for selectable I/O to become active. Ada specification: procedure Select_Wait (Time_Out : in Float); Arguments for Ada: time_out floating point milliseconds time out value Output: Upon successful completion, the select subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. If the time limit specified by the TimeOut parameter expires, the select subroutine returns a value of 0. If the select subroutine is unsuccessful, it returns a value of -1 and sets the global variable errno to indicate the error. 12.32.8 select_wait_all Description: The select_wait_all function will process all upcalls associated with sockets or file descriptors, in priority order, which have I/O currently active. Ada specification: procedure Select_Wait_All (Time_Out : in Float); Arguments for Ada: time_out floating point milliseconds time out value Output: Upon successful completion, the select subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. If the time limit specified by the TimeOut parameter expires, the select subroutine returns a value of 0. If the select subroutine is unsuccessful, it returns a value of -1 and sets the global variable errno to indicate the error. 12.33 File Input/Output The following types, functions and procedures for File I/O are provided as a wrapper around the corresponding UNIX functions. (See UNIX man pages for descriptions) 12.33.1 Ada types type File_Mode is (Read_Only, Write_Only, Read_Write); type Permission is ( Owner_Read, Owner_Write, Owner_Execute, Group_Read, Group_Write, Group_Execute, Others_Read, Others_Write, Others_Execute); type Open_Option is (Append, Truncate, Exclusive, Sync, Non_Blocking, Not_Controlling_Terminal); type Access_Mode is (Read_Ok, Write_Ok, Execute_Ok); type Position is (From_Beginning, From_Current_Position, From_End_Of_File); 12.33.2 create Description: Create a file if a file called File_Name does not exist; otherwise open existing file. Open the file in write-only mode. Create a new file with the specified permissions; but do not change the permissions of an existing file. Truncate an existing file to zero length. Raise Fio_Error on error. Ada specification: function Create (File_Name : in String; Permissions : in Permission_Set) return File_Descriptor; 12.33.3 open Description: Open an existing file with the specified read/write mode and options. Raise Fio_Error on error. Ada specification: function Open (File_Name : in String; Mode : in File_Mode; Options : in Open_Option_Set) return File_Descriptor; 12.33.4 open or create Description: Create a file if a file called File_Name does not exist, otherwise open the existing file. Open the file in read/write mode specified by Mode. Create a new file with the specified permissions; but do not change the permissions of an existing file. Raise Fio_Error on error. Ada specification: function Open_Or_Create (File_Name : in String; Mode : in File_Mode; Permissions : in Permission_Set; Options : in Open_Option_Set) return File_Descriptor; 12.33.5 truncate Description: Change the size of the file to Length bytes. If the file is shorter than Length, pad it with zeros. Raise Fio_Error on error. Ada specification: procedure Truncate (File_Name : in String; Length : in Natural); Ada specification: procedure Truncate (The_File_Descriptor : in File_Descriptor; Length : in Natural); 12.33.6 get file status Description: The following functions report file status. Get_File_Status returns a Status structure, and the remaining functions extract specific status information from the structure. The Status structure is private, and varies according to platform. The Status structure identifies a file; it is defined in fio.ads. These functions raise Fio_Status_Error if called with an invalid Status argument. function Get_File_Status (The_Name : in String) return Status; function Get_File_Status (The_File_Descriptor : in File_Descriptor) return Status; function Permission_Set_Of (The_Status : in Status) return Permission_Set; function File_Id_Of (The_Status : in Status) return Integer; function Device_Id_Of (The_Status : in Status) return Integer; function Link_Count_Of (The_Status : in Status) return Integer; function Owner_Of (The_Status : in Status) return Integer; function Group_Of (The_Status : in Status) return Integer; function Size_Of (The_Status : in Status) return Integer; function Last_Access_Time_Of (The_Status : in Status) return Integer; function Last_Modification_Time_Of (The_Status : in Status) return Integer; function Last_Status_Change_Time_Of (The_Status : in Status) return Integer; function Is_Directory (The_Status : in Status) return Boolean; function Is_Character_Special_File (The_Status : in Status) return Boolean; function Is_Block_Special_File (The_Status : in Status) return Boolean; function Is_Regular_File (The_Status : in Status) return Boolean; function Is_Fifo (The_Status : in Status) return Boolean; 12.33.7 is accessible Description: Return True if the file exists and can be accessed in the requested mode(s). Otherwise return false and set an error code, which may be obtained with Get_Error_Code. ( This function does not raise Fio_Error.) Ada specification: function Is_Accessible (File_Name : in String; The_Access_Mode_Set : in Access_Mode_Set) return Boolean; 12.33.8 is file present Description: Return True if the file exists. Otherwise return false and set an error code, which may be obtained with Get_Error_Code. ( This function does not raise Fio_Error.) Ada specification: function Is_File_Present (File_Name : in String) return Boolean; 12.33.9 write Ada specification: procedure Write (The_File_Descriptor : in File_Descriptor; Buffer : in Memory.Pointer; Nbyte_Request : in Natural; Nbyte_Written : out Natural); 12.33.10 read Description: Attempt to write Nbyte_Request bytes from Buffer to The_File_Descriptor. Set Nbyte_Written to the number of bytes written. Raise Fio_Error on error. Ada specification: procedure Read (The_File_Descriptor : in File_Descriptor; Buffer : in Memory.Pointer; Nbyte_Request : in Natural; Nbyte_Read : out Natural); 12.33.11 seek Description: Attempt to read Nbyte_Request bytes from The_File_Descriptor to Buffer. Set Nbyte_Read to the number of bytes read. Raise Fio_Error on error. Position the read/write pointer for the file opened as The_File_Descriptor. The new position is Offset bytes added to the Starting_Point. Return the new pointer position, measured from the beginning of the file, as Result. Raise Fio_Error on error. Ada specification: procedure Seek (The_File_Descriptor : in File_Descriptor; Offset : in Integer; Result : out Integer; Starting_Point : in Position); 12.33.12 file position Description: Return the position of the read/write pointer associated with The_File_Descriptor. Raise Fio_Error on error. Ada specification: function File_Position (The_File_Descriptor : in File_Descriptor) return Integer; 12.33.13 close Description: Close The_File_Descriptor. Raise Fio_Error on error. Ada specification: procedure Close (The_File_Descriptor : in File_Descriptor); 12.33.14 get error code Description: Return the integer error code (errno). Ada specification: function Get_Error_Code return Integer; 13 Diagnostics IM/ES code provides diagnostic messages to assist in your development when problems arise. Four levels of diagnostics are available, with increasingly detailed messages: Level 1 includes a one-line description of the problem, accompanied by file_name and line_number. Level 2 includes "critical data" appropriate to the diagnosis of the error condition, and a more elaborate description than produced for Level 1. Level 3 includes a stack trace, showing entry to and exit from every routine. Level 4 includes detailed debug information (i.e. memory dump of pertinent data). The level of diagnostic software included in the executable is determined at compile time by adding the compile flag -D_DEBUG=level(level = 1,2,3,4) in the makefile. Note that increasing the level of diagnostics increases the size of the executable module. Example of makefile entry: cc -D_DEBUG=2 filename.c There are four optional debug level environmental parameters: IM_ORB_DEBUG_LEVEL -- Object Request Broker debug level IM_DB_DEBUG_LEVEL -- Database debug level IM_ES_DEBUG_LEVEL -- Encapsulated Scheduler debug level IM_DEBUG_LEVEL -- General debug level for ORB, DB and ES These UNIX environment parameters can be set using an export command prior to executing the user application. Each of these parameters may specify a debug level of 0 through 4. Even with diagnostics compiled into the executable module, one or more of these environmental parameters must be set to an acceptable value for messages to be output. Example (for K-shell): export IM_ORB_DEBUG_LEVEL=2 This will write any ORB debug messages of level 2 or lower to stderr. Appendix A Acronyms ads Ada specification file (suffix) adb Ada body file (suffix) AIX IBM's UNIX ANSI American National Standards Institute API Application Programming Interface ASE Application Schedulable Entity BOA Basic Object Adapter cpp C language preprocessor CORBA Common Object Request Broker Architecture Cos Common Object Service COTS Commercial Off-The-Shelf DII Dynamic Invocation Interface DST Daylight Savings Time ES Encapsulated Scheduler gcc GNU C compiler GMT Greenwich Mean Time GNU GNU, Not UNIX (Free Software Foundation's UNIX-like project) h header file (suffix) IDL Interface Definition Language idlpp IDL/ODL preprocessor IM Information Manager IP Internet Protocol impl implementation (of interface server) MIL-STD United States Department of Defense Military Standard ODBMS Object-Oriented Database Management System ODL Object Definition Language ODMG Object Data Management Group ODMG-93 Object Database Standard OMG Object Management Group, Inc. OQL Object Query Language oqlpp OQL preprocessor ORB Object Request Broker ref data type for reference to an object by itself (like C++ "this") RPC Remote Procedure Call RS232 Standard for communication between a device and a modem SDD Software Design Document SQL Structured Query Language SRS System Requirement Specification TCP Transmission Control Protocol UDP User Datagram Protocol xlc AIX XL C Compiler/6000 1.6 APPENDIX B - CORBA API's not in IM/ES CORBA Interfaces and Operations not part of IM/ES. module CORBA interface ORB create_list create_operation_list get_default_context interface Object create_request get_interface is_a interface BOA change_implementation deactivate_implementation deactivate_obj get_principal obj_is_ready module CosCompoundExternalization interface Node externalize_node internalize_node interface Relationship externalize_propagation externalize_relationship internalize_relationship interface Role externalize_propagation externalize_role internalize_role interface PropagationCriteriaFactory create_for_externalize module CosCompoundLifeCycle interface Relationship copy_relationship move_relationship interface OperationsFactory create_compound_operations interface Operations copy destroy move remove interface Node copy_node get_life_cycle_object move_node remove_node interface Role copy_role life_cycle_propagation move_role interface PropagationCriteriaFactory create module CosConcurrencyControl interface LockCoordinator drop_locks interface LockSet change_mode get_coordinator lock try_lock unlock interface LockSetFactory create create_related create_transactional create_transactional_related interface TransactionalLockset change_mode get_coordinator lock try_lock unlock module CosContainment interface ContainedInRole interface ContainsRole interface Relationship module CosExternalization interface Stream begin_context end_context module CosExternalizationContainment interface ContainedInRole interface ContainsRole interface Relationship module CosExternalizationReference interface ReferencedByRole interface ReferencesRole interface Relationship module CosGraphs interface TraversalFactory create_traversal_on interface Traversal destroy next_n next_one interface TraversalCriteria destroy next_n next_one visit_node interface Node add_role remove_role roles_of_type interface NodeFactory create_node interface Role get_edges interface EdgeIterator destroy next_n next_one module CosLifeCycleContainment interface ContainedInRole interface ContainsRole interface Relationship module CosLifeCycleReference interface ReferencedByRole interface ReferencesRole interface Relationship module CosNaming interface LNameComponent destroy get_id get_kind set_id set_kind interface LName create_lname create_lname_component delete_component destroy equal from_idl_form get_component insert_component less_than num_components to_idl_form module CosObjectIdentity interface IdentifiableObject is_identical module CosPersistencePO interface PO connect delete disconnect restore store interface SD pre_store post_restore module CosPersistencePID interface PID get_PIDstring module CosPersistencePOM interface POM connect delete disconnect restore store module CosPersistencePDS interface PDS connect delete disconnect restore store module CosPersistencePDS_DA interface DAObject dado_free dado_oid dado_pid dado_remove dado_same interface DAObjectFactory create interface DAObjectFactoryFinder find_factory interface PDS_DA data_factories get_data get_object_pid get_pid lookup set_data interface DynamicAttributeAccess attribute_get attribute_names attribute_set interface PDS_ClusteredDA cluster_id cluster_kind clusters_of copy_cluster create_cluster open_cluster module CosPersistenceDDO interface DDO add_data add_data_property get_data get_data_count get_data_property get_data_property_count set_data set_data_property module CosPersistenceDS_CLI interface UserEnvironment get_option release set_option interface Connection get_option set_option interface ConnectionFactory create_object interface Cursor fetch_object set_position interface CursorFactory create_object interface Datastore_CLI add_object assign_PID assign_PID_relative connect delete_object disconnect execute get_connection get_object_type is_identical_PID register_mapping_schema retrieve_object select_object transact update_object module CosReference interface ReferencedByRole interface ReferencesRole interface Relationship module CosRelationships interface RelationshipFactory create interface Relationship destroy interface Role check_minimum_cardinality destroy destroy_relationships get_other_related_objects get_other_role get_relationships link unlink interface RoleFactory create_role interface RelationshipIterator destroy next_one next_n module CosTransactions interface Coordinator get_status register_resource get_parent_status get_top_level_status is_same_transaction is_related_transaction is_ancestor_transaction is_descendant_transaction is_top_level_transaction hash_transaction hash_top_level_tran register_subtran_aware rollback_only get_transaction_name create_subtransaction interface RecoveryCoordinator replay_completion interface Current begin commit get_control get_status get_transaction_name resume rollback rollback_only set_timeout suspend interface Resource commit forget prepare rollback interface TransactionFactory create interface Control get_coordinator get_terminator interface Terminator commit rollback module CosTSPortability interface Sender received_reply sending_request interface Receiver received_request sending_reply module CosTypedEventComm interface TypedPushConsumer get_typed_consumer interface TypedPullSupplier get_typed_supplier module CosTypedEventChannelAdmin interface TypedProxyPushConsumer interface TypedProxyPullSupplier interface TypedSupplierAdmin obtain_typed_pull_consumer obtain_typed_push_consumer interface TypedConsumerAdmin obtain_typed_pull_supplier obtain_typed_push_supplier interface TypedEventChannel for_consumers for_suppliers destroy ALL INTERFACE IDL-specified INTERFACES ALL INTER-ORB PROTOCOL IDL-specified INTERFACES module LifeCycleService interface LifeCycleServiceAdmin bind_generic_factory get_hint get_link_properties list_generic_factories match_service resolve_generic_factory unbind_generic_factory Appendix C - Legal Information Booch Components This is an abstract of the Booch Components License Agreement with Lockheed Martin Federal Systems (LMFS). The Booch Components are licensed commercial computer software which are owned by Wizard. All software developers who desire to use The Booch Components should become familiar with the terms of the License Agreement, the full text of which is available. The following list provides a brief summary of LMFS's rights and obligations under that License Agreement. For further details and information, check with your local Intellectual Property Law Department. You may: 1. Copy and integrate The Booch Components into software that you are developing for internal or external use. You must include the following copyright notice in all software that you develop that incorporates any of The Booch Components: "Copyright Notice: Portions of this program are copyrighted (c) 1987 by Ernest Grady Booch" The above copyright notice should be included in the actual Licensee Developed Software source CODE including The Booch Components. It is not necessary to include in every software module using any of The Booch Components, as long as it is included in a software module that is comprehensive enough to cover the scope of usage for The Booch Components within the Licensee Developed Software (ex., code corresponding to an overall software control program). Any software delivered to non-LMFS customers must be licensed pursuant to the LMFS Program License Agreement or the Agreement for LMFS Licensed Programs. 2. Deliver software to the Government which includes one or more of The Booch Components. When delivering software to the Government, the appropriate Restricted Rights notice must be included in each Component. Furthermore, you should notify the cognizant LMFS contracts representative at the earliest possible opportunity that you will be including commercial computer software in the software to be delivered to the Government. -- (C) Copyright 1986, 1987, 1988 Grady Booch -- -- "Restricted Rights Legend" -- Use, duplication, or disclosure is subject to -- restrictions as set forth in subdivision (b) (3) (ii) -- of the rights in Technical Data and Computer -- Software Clause at FAR 52.227-7013. Manufacturer: -- Wizard Software, 835 S. Moore St., Lakewood, -- Colorado 80226 3. Translate The Booch Components to other languages as long as those translated components comply with the terms of this license. You should replace the Booch copyright notice with an appropriate LMFS copyright notice. Contact your local Intellectual Property Law department for recommended wording. Any restricted rights notice should be retained by the translated software component. Any other provisions of the license (ex., subcontractor usage, CPU usage) will be applicable to the translated components. Note also that the underlying works provision of the license apply to any translated components (see 5 below). 4. Use The Booch Components on central processing units owned or operated by LMFS. 5. Use The Booch Components within Licensee Developed Software provided The Booch Components are identified as "underlying works" in any registration for the Licensee Developed Software. When the copyright in a Derivative Work is registered with the U.S. Copyright office, there is a space on the registration form for inserting the name of any "underlying work" upon which the derivative work is based. Our obligation is to put The Booch Components in that space on the form if we ever register any of our derivative works. You may NOT: 1. Provide any of The Booch Components by themselves to anyone outside LMFS, except subcontractors, who must be notified of the restrictions on their usage of The Booch Components. Reference the license agreement for the definition of "subcontractor". 2. Delete any "Copyright" or "Restricted Rights" notices in The Booch Components. 3. Take The Booch Components outside of the United States without approval of local Legal Counsel based on full compliance with export control laws. 4. Deliver the source code for any of the Booch Components that are not part of the executable software delivered to the customer. Appendix D - Ada components The CORBA string type is implemented in Ada using these commercial off-the-shelf components: String_Sequential_Bounded_Managed_Iterator (430 source lines of code) String_Sequential_Unbounded_Managed_Iterator (599 source lines of code) The CORBA sequence type is implemented in Ada using these IM components: CORBA_Sequences_Basic_Bounded_Managed_Iterator CORBA_Sequences_Basic_Unbounded_Managed_Iterator String Sequential Bounded Managed Iterator -- -- USAGE CONSTRAINT: This component is commercial software obtained -- via corporate license from Grady Booch and Wizard Corporation. The -- component should not be used unless you are completely familiar -- with the provisions and constraints of the license agreement and -- the associated Booch book agreement. As summarized in the "Legal -- Information" element of this component, these agreements are -- available through the "Booch Legal Information" software . -- component. -- generic type Item is private; type Substring is array(Positive range <>) of Item; with function "<" (Left : in Item; Right : in Item) return Boolean; package String_Sequential_Bounded_Managed_Iterator is type String(The_Size : Positive) is limited private; procedure Copy (From_The_String : in String; To_The_String : in out String); procedure Copy (From_The_Substring : in Substring; To_The_String : in out String); procedure Clear (The_String : in out String); procedure Prepend (The_String : in String; To_The_String : in out String); procedure Prepend (The_Substring : in Substring; To_The_String : in out String); procedure Append (The_String : in String; To_The_String : in out String); procedure Append (The_Substring : in Substring; To_The_String : in out String); procedure Insert (The_String : in String; In_The_String : in out String; At_The_Position : in Positive); procedure Insert (The_Substring : in Substring; In_The_String : in out String; At_The_Position : in Positive); procedure Delete (In_The_String : in out String; From_The_Position : in Positive; To_The_Position : in Positive); procedure Replace (In_The_String : in out String; At_The_Position : in Positive; With_The_String : in String); procedure Replace (In_The_String : in out String; At_The_Position : in Positive; With_The_Substring : in Substring); procedure Set_Item (In_The_String : in out String; At_The_Position : in Positive; With_The_Item : in Item); function Is_Equal (Left : in String; Right : in String) return Boolean; function Is_Equal (Left : in Substring; Right : in String) return Boolean; function Is_Equal (Left : in String; Right : in Substring) return Boolean; function Is_Less_Than (Left : in String; Right : in String) return Boolean; function Is_Less_Than (Left : in Substring; Right : in String) return Boolean; function Is_Less_Than (Left : in String; Right : in Substring) return Boolean; function Is_Greater_Than (Left : in String; Right : in String) return Boolean; function Is_Greater_Than (Left : in Substring; Right : in String) return Boolean; function Is_Greater_Than (Left : in String; Right : in Substring) return Boolean; function Length_Of (The_String : in String) return Natural; function Is_Null (The_String : in String) return Boolean; function Item_Of (The_String : in String; At_The_Position : in Positive) return Item; function Substring_Of (The_String : in String) return Substring; function Substring_Of (The_String : in String; From_The_Position : in Positive; To_The_Position : in Positive)return Substring; generic with procedure Process (The_Item : in Item; Continue : out Boolean); procedure Iterate (Over_The_String : in String); Overflow : exception; Position_Error : exception; private type String(The_Size : Positive) is record The_Length : Natural := 0; The_Items : Substring(1 .. The_Size); end record; end String_Sequential_Bounded_Managed_Iterator; String Sequential Unbounded Managed Iterator -- -- USAGE CONSTRAINT: This component is commercial software obtained -- via corporate license from Grady Booch and Wizard Corporation. The -- component should not be used unless you are completely familiar -- with the provisions and constraints of the license agreement and -- the associated Booch book agreement. As summarized in the "Legal -- Information" element of this component, these agreements are -- available through the "Booch Legal Information" software . -- component. -- generic type Item is private; type Substring is array(Positive range <>) of Item; with function "<" (Left : in Item; Right : in Item) return Boolean; package String_Sequential_Unbounded_Managed_Iterator is type String is limited private; procedure Copy (From_The_String : in String; To_The_String : in out String); procedure Copy (From_The_Substring : in Substring; To_The_String : in out String); procedure Clear (The_String : in out String); procedure Prepend (The_String : in String; To_The_String : in out String); procedure Prepend (The_Substring : in Substring; To_The_String : in out String); procedure Append (The_String : in String; To_The_String : in out String); procedure Append (The_Substring : in Substring; To_The_String : in out String); procedure Insert (The_String : in String; In_The_String : in out String; At_The_Position : in Positive); procedure Insert (The_Substring : in Substring; In_The_String : in out String; At_The_Position : in Positive); procedure Delete (In_The_String : in out String; From_The_Position : in Positive; To_The_Position : in Positive); procedure Replace (In_The_String : in out String; At_The_Position : in Positive; With_The_String : in String); procedure Replace (In_The_String : in out String; At_The_Position : in Positive; With_The_Substring : in Substring); procedure Set_Item (In_The_String : in out String; At_The_Position : in Positive; With_The_Item : in Item); function Is_Equal (Left : in String; Right : in String) return Boolean; function Is_Equal (Left : in Substring; Right : in String) return Boolean; function Is_Equal (Left : in String; Right : in Substring) return Boolean; function Is_Less_Than (Left : in String; Right : in String) return Boolean; function Is_Less_Than (Left : in Substring; Right : in String) return Boolean; function Is_Less_Than (Left : in String; Right : in Substring) return Boolean; function Is_Greater_Than (Left : in String; Right : in String) return Boolean; function Is_Greater_Than (Left : in Substring; Right : in String) return Boolean; function Is_Greater_Than (Left : in String; Right : in Substring) return Boolean; function Length_Of (The_String : in String) return Natural; function Is_Null (The_String : in String) return Boolean; function Item_Of (The_String : in String; At_The_Position : in Positive) return Item; function Substring_Of (The_String : in String) return Substring; function Substring_Of (The_String : in String; From_The_Position : in Positive; To_The_Position : in Positive)return Substring; generic with procedure Process (The_Item : in Item; Continue : out Boolean); procedure Iterate (Over_The_String : in String); Overflow : exception; Position_Error : exception; private type Structure is access Substring; type String is record The_Length : Natural := 0; The_Items : Structure; end record; end String_Sequential_Unbounded_Managed_Iterator; CORBA_Sequences_Basic_Bounded_Managed_Iterator -- @(#) (C) Copyright Lockheed Martin 1996 (Unpublished). All rights reserved. basic_bnd_seq.ads 1.5 changed 10/7/96 14:57:10 -- Copyright Notice: Portions of this software are copyrighted -- (c) 1987 by Ernest Grady Booch -- The following package is derived from the Grady Booch's -- String_Sequential_Bounded_Managed_Iterator Ada package. -- The component is commercial software obtained via corporate -- license from Grady Booch and Wizard Corporation. -- -- (C) Copyright 1986, 1987, 1988 Grady Booch -- All Rights Reserved -- -- Serial Number 0100039 -- -- Note: -- Lockheed Martin Federal Systems has a corporate license for the -- Grady Booch Components allowing the company to copy and integrate -- the components in their projects. Since the Grady Booch Components -- are commercial computer software developed at private expense, the -- Restricted Rights notice posted below is required as part of the -- license agreement. Customers and contractors may use this -- Ada package freely as part of their project without incurring -- additional licensing charges. However, a separate license agreement -- may be required if this Ada package is to be used as a standalone -- reusable component on other projects. -- -- "Restricted Rights Legend" -- Use, duplication, or disclosure is subject to -- restrictions as set forth in subdivision (b) (3) (ii) -- of the rights in Technical Data and Computer -- Software Clause at FAR 52.227-7013. Manufacturer: -- Wizard Software, 835 S. Moore St., Lakewood, -- Colorado 80226. -- -- When updating this file, record update history in this comment header. -- -- DATE INITIALS COMMENT -- 10/07/96 SLN Added buffer transfer procedures: Copy and Transfer -- with System; generic type Element is private; package CORBA_Sequences_Basic_Bounded_Managed_Iterator is type Sequence(The_Size : Positive) is limited private; type Element_Array is array (Positive range <>) of Element; procedure Copy (From_The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Copy (From_The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Copy (From_Buffer_Addr : in System.Address; To_The_Sequence : in out Sequence; Num_Of_Elements : in Integer; Bytes_Copied : out Integer); procedure Clear (The_Sequence : in out Sequence); procedure Prepend (The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Prepend (The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Prepend (The_Element : in Element; To_The_Sequence : in out Sequence); procedure Append (The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Append (The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Append (The_Element : in Element; To_The_Sequence : in out Sequence); procedure Insert (The_Sequence : in Sequence; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Insert (The_Element_Array : in Element_Array; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Insert (The_Element : in Element; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Delete (In_The_Sequence : in out Sequence; From_The_Position : in Positive; To_The_Position : in Positive); procedure Replace (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Sequence : in Sequence); procedure Replace (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Element_Array : in Element_Array); procedure Set_Element (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Element : in Element); function Is_Equal (Left : in Sequence; Right : in Sequence) return Boolean; function Is_Equal (Left : in Element_Array; Right : in Sequence) return Boolean; function Is_Equal (Left : in Sequence; Right : in Element_Array) return Boolean; function Length_Of (The_Sequence : in Sequence) return Natural; function Is_Null (The_Sequence : in Sequence) return Boolean; procedure Copy_Element (The_Sequence : in Sequence; At_The_Position : in Positive; The_Element : in out Element); procedure Slice (The_Sequence : in Sequence; The_Element_Array : in out Element_Array); procedure Slice (The_Sequence : in Sequence; From_The_Position : in Positive; To_The_Position : in Positive; The_Element_Array : in out Element_Array); procedure Transfer (From_The_Sequence : in Sequence; To_Buffer_Addr : in System.Address; Bytes_Transferred : out Integer); generic with procedure Process (The_Element : in out Element; Continue : out Boolean); procedure Iterate (Over_The_Sequence : in out Sequence); Overflow : exception; Position_Error : exception; private type Sequence(The_Size : Positive) is record The_Length : Natural := 0; The_Elements : Element_Array(1 .. The_Size); end record; end CORBA_Sequences_Basic_Bounded_Managed_Iterator; CORBA_Sequences_Basic_Unbounded_Managed_Iterator -- @(#) (C) Copyright Lockheed Martin 1996 (Unpublished). All rights reserved. basic_unb_seq.ads 1.4 changed 10/7/96 14:57:30 -- Copyright Notice: Portions of this software are copyrighted -- (c) 1987 by Ernest Grady Booch -- The following package is derived from the Grady Booch's -- String_Sequential_Bounded_Managed_Iterator Ada package. -- The component is commercial software obtained via corporate -- license from Grady Booch and Wizard Corporation. -- -- (C) Copyright 1986, 1987, 1988 Grady Booch -- All Rights Reserved -- -- Serial Number 0100039 -- -- Note: -- Lockheed Martin Federal Systems has a corporate license for the -- Grady Booch Components allowing the company to copy and integrate -- the components in their projects. Since the Grady Booch Components -- are commercial computer software developed at private expense, the -- Restricted Rights notice posted below is required as part of the -- license agreement. Customers and contractors may use this -- Ada package freely as part of their project without incurring -- additional licensing charges. However, a separate license agreement -- may be required if this Ada package is to be used as a standalone -- reusable component on other projects. -- -- "Restricted Rights Legend" -- Use, duplication, or disclosure is subject to -- restrictions as set forth in subdivision (b) (3) (ii) -- of the rights in Technical Data and Computer -- Software Clause at FAR 52.227-7013. Manufacturer: -- Wizard Software, 835 S. Moore St., Lakewood, -- Colorado 80226. -- -- When updating this file, record update history in this comment header. -- -- DATE INITIALS COMMENT -- 10/07/96 SLN Added buffer transfer procedures: Copy and Transfer -- with System; generic type Element is private; package CORBA_Sequences_Basic_Unbounded_Managed_Iterator is type Sequence is limited private; type Element_Array is array(Positive range <>) of Element; procedure Copy (From_The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Copy (From_The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Copy (From_Buffer_Addr : in System.Address; To_The_Sequence : in out Sequence; Num_Of_Elements : in Integer; Bytes_Copied : out Integer); procedure Set (The_Sequence : in out Sequence; To_The_Size : in Natural; Preserve_The_Value : in Boolean); procedure Clear (The_Sequence : in out Sequence); procedure Prepend (The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Prepend (The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Prepend (The_Element : in Element; To_The_Sequence : in out Sequence); procedure Append (The_Sequence : in Sequence; To_The_Sequence : in out Sequence); procedure Append (The_Element_Array : in Element_Array; To_The_Sequence : in out Sequence); procedure Append (The_Element : in Element; To_The_Sequence : in out Sequence); procedure Insert (The_Sequence : in Sequence; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Insert (The_Element_Array : in Element_Array; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Insert (The_Element : in Element; In_The_Sequence : in out Sequence; At_The_Position : in Positive); procedure Delete (In_The_Sequence : in out Sequence; From_The_Position : in Positive; To_The_Position : in Positive); procedure Replace (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Sequence : in Sequence); procedure Replace (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Element_Array : in Element_Array); procedure Set_Element (In_The_Sequence : in out Sequence; At_The_Position : in Positive; With_The_Element : in Element); function Is_Equal (Left : in Sequence; Right : in Sequence) return Boolean; function Is_Equal (Left : in Element_Array; Right : in Sequence) return Boolean; function Is_Equal (Left : in Sequence; Right : in Element_Array) return Boolean; function Length_Of (The_Sequence : in Sequence) return Natural; function Is_Null (The_Sequence : in Sequence) return Boolean; procedure Copy_Element (The_Sequence : in Sequence; At_The_Position : in Positive; The_Element : in out Element); procedure Slice (The_Sequence : in Sequence; The_Element_Array : in out Element_Array); procedure Slice (The_Sequence : in Sequence; From_The_Position : in Positive; To_The_Position : in Positive; The_Element_Array : in out Element_Array); procedure Transfer (From_The_Sequence : in Sequence; To_Buffer_Addr : in System.Address; Bytes_Transferred : out Integer); generic with procedure Process (The_Element : in out Element; Continue : out Boolean); procedure Iterate (Over_The_Sequence : in out Sequence); Overflow : exception; Position_Error : exception; private type Structure is access Element_Array; type Sequence is record Maximum : Integer := 0; The_Length : Natural := 0; The_Elements : Structure; Release : Boolean:= false; end record; end CORBA_Sequences_Basic_Unbounded_Managed_Iterator; Appendix E - CORBA Exceptions The exceptions listed here will be set in the major field within the CORBA_environment parameter which is passed with every call to a CORBA function in the C language. The exceptions are listed in alphabetical order. For each CORBA function, a brief description of possible interpretations is given. 13.1 AlreadyBound AlreadyBound - CosNaming_NamingContext_bind Input Naming Context already bound. AlreadyBound - CosNaming_NamingContext_bind_new_context Input Naming Context already bound. 13.2 AlreadyConnected AlreadyConnected - CosEventChannelAdmin ProxyPullSupplier connect_pull_consumer Proxy object already connected. AlreadyConnected - CosEventChannelAdmin ProxyPullConsumer connect_pull_supplier Proxy object already connected. AlreadyConnected - CosEventChannelAdmin ProxyPushSupplier connect_push_consumer Proxy object already connected. AlreadyConnected - CosEventChannelAdmin ProxyPushConsumer connect_push_supplier Proxy object already connected. 13.3 BAD_INV_ORDER BAD_INV_ORDER - CORBA_release Object reference count less than or equal to one. 13.4 BAD_OPERATION BAD_OPERATION - Array_create Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - Array_create_iterator Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - Array_copy Array with new_name already exists Array_retrieve error. Array_replace error. BAD_OPERATION - Array_delete Array is empty. BAD_OPERATION - Array_resize Unable to allocate memory for new_link. Transaction not found in transaction array. Array is empty. BAD_OPERATION - CORBA_BOA_join Attempting to join a group which has a different interface associated with it. A group object can have only one interface associated with it. BAD_OPERATION - corba_client_to_orbcore Interface name mismatch between the target object and the calling interface. Can only call those methods associated with object's interface. BAD_OPERATION - Iterator_copy Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_append Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_insert_element_after Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_insert_element_before Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_insert_element_first Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_create_iterator Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_insert_element_last Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - List_concat List with new name already exists. Can't retrieve element. Can't insert element. BAD_OPERATION - List_copy List with new name already exists. Can't retrieve element. Can't insert element. BAD_OPERATION - List_delete List is empty. BAD_OPERATION - List_remove_first_element List is empty. BAD_OPERATION - List_remove_last_element List is empty. BAD_OPERATION - List_retrieve_first_element List is empty. BAD_OPERATION - List_retrieve_last_element List is empty. BAD_OPERATION - Trans_copy Unable to allocate memory for new_link. Transaction not found in transaction array. BAD_OPERATION - Transaction_commit Process/thread ID mismatch. BAD_OPERATION - Transaction_abort Process/thread ID mismatch. 13.5 BAD_PARAM BAD_PARAM - Array_replace_element_at Invalid array position BAD_PARAM - Array_retrieve_element_at Invalid array position BAD_PARAM - Array_remove_element_at Invalid array position BAD_PARAM - CORBA_BOA_setsched Invalid socket number associated with the request. Local server, no socket associated with the request. BAD_PARAM - CORBA_BOA_create Implentation data pointer is NULL or its InterfaceName field is NULL. BAD_PARAM - CORBA_ORB_init Argument count less than one or unknown argument name or missing argument value or ASE name argument missing or call to es_register returned an error. Duplicate ASE's or too many ASE's. BAD_PARAM - CORBA_ORB_string_to_object String pointer is NULL or string parsing error. BAD_PARAM - CosEventChannelAdmin_ProxyPullConsumer_connect_pull_supplier Input Pull supplier object is NIL. BAD_PARAM - CosEventChannelAdmin_ProxyPushSupplier_connect_push_consumer Input Pull supplier object is NIL. BAD_PARAM - List_retrieve_element_at Invalid list position BAD_PARAM - List_insert_element_after Invalid list position BAD_PARAM - List_insert_element_before Invalid list position BAD_PARAM - List_remove_element_at Invalid list position BAD_PARAM - List_replace_element_at Invalid list position BAD_PARAM - Lock_collection Bad pointer. 13.6 CannotProceed CannotProceed - CosNaming_BindingIterator_destroy Error resolving bindingiterator object. CannotProceed - CosNaming_BindingIterator_next_n Invalid 'how_many' input parameter. CannotProceed - CosNaming_NamingContext_list Invalid 'how_many' input parameter. Unable to create an object reference; CORBA_BOA_create returned an error. CannotProceed - CosNaming_NamingContext_rebind_context Input NamingContext object doesn't exist. CannotProceed - CosNaming_NamingContext_resolve Not all context levels had a name match in the context linked list. CannotProceed - CosNaming_NamingContext_unbind No names bound to this context, namelist is empty. 13.7 COMM_FAILURE COMM_FAILURE - CORBA_BOA_impl_is_ready Unable to communicate with the naming server after the time-out period. Naming server not active as defined in "initref.cfg". COMM_FAILURE - corba_client_to_orbcore Maximum number of servers are already connected or unable to make a connection to the server or error writing to the server or error reading from the server or invalid response received from the server. 13.8 Disconnected Disconnected - CosEventChannelAdmin_ProxyPullSupplier_pull Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPullSupplier_try_pull Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPushConsumer_disconnect_pull_consumer Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPushConsumer_disconnect_pull_supplier Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPushConsumer_disconnect_push_consumer Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPushConsumer_push Proxy object no longer connected. Disconnected - CosEventChannelAdmin_ProxyPushSupplier_disconnect_push_supplier Proxy object no longer connected. Disconnected - CosEventComm_PullSupplier_pull Input object no longer connected. Disconnected - CosEventComm_PullSupplier_try_pull Input object no longer connected. Disconnected - CosEventComm_PushConsumer_push Input object no longer connected. 13.9 EMPTY EMPTY - Iterator_delete Iterator is empty. EMPTY - Iterator_get_element Iterator is empty. 13.10 INTERNAL INTERNAL - CORBA_BOA_join Broadcast server register error or Maximum number of servers already registered. Broadcast client connect error. Connection timeout with bc_server; bc_server task not active. INTERNAL - CORBA_BOA_leave Broadcast server unregister error or broadcast client disconnect error. (Server not registed or client Not connected.) INTERNAL - corba_client_to_orbcore Broadcast request error. bc_server send or recv error; bc_server task died. bc_server acknowledge timeout; timeout period too short. INTERNAL - CORBA_BOA_impl_is_ready Unable to create a passive socket; not enough sockets. Or, maximum number of aliases exceeded; too many aliases in /etc/hosts. 13.11 InvalidCriteria InvalidCriteria - CosLifeCycle_GenericFactory_create_object Input parameter the_criteria is invalid. 13.12 InvalidFileNameError InvalidFileNameError - CosExternalization_FileStreamFactory_create Open failed for the input stream name theFileName. Create failed for the input stream name theFileName. Write of START_STREAM_TAG failed for the input stream name theFileName. InvalidFileNameError - CosExternalization_StreamFactory_create Open failed for the input stream name theFileName. Create failed for the input stream name theFileName. Write of START_STREAM_TAG failed for the input stream name theFileName. 13.13 InvalidName InvalidName CosNaming_NamingContext_bind Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_bind_context Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_bind_new_context Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_resolve Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_rebind Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_rebind_context Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_unbind Invalid Naming Context; not valid string data. InvalidName - CosNaming_NamingContext_rebind_context Invalid input Name; not valid string data. 13.14 INV_OBJREF INV_OBJREF CORBA_BOA_join Object reference not of type group; object not created by create_group(). NULL psuedo object specified; bad input argument. INV_OBJREF CORBA_BOA_leave Object reference not of type group; object not created by create_group(). NULL psuedo object specified; bad input argument. INV_OBJREF - CORBA_BOA_preempt NULL object reference; bad input argument. INV_OBJREF - CORBA_BOA_response NULL object reference; bad input argument. INV_OBJREF - corba_client_to_orbcore NULL request pointer or NULL request object reference pointer or NULL request psuedo object reference pointer; bad input argument. INV_OBJREF - CORBA_Object_get_implementation Object reference not found; bad input argument. 13.15 NoFactory NoFactory - CosLifeCycle_FactoryFinder_find_factories Factory not found with name specified as input factory_key. NoFactory - CosLifeCycle_GenericFactory_create_object Factory not found with name specified as input key. 13.16 NO_IMPLEMENT NO_IMPLEMENT - corba_client_to_orbcore Invalid interface I.D. number or NULL interface upcall address. Bad input argument. NO_IMPLEMENT - CORBA_ORB_resolve_initial_references Object identifier not found. "initref.cfg" file not found. Bad file format. Bad input argument. NO_IMPLEMENT - service_orb_request Invalid interface ID number or NULL interface upcall address. Invalid object reference. 13.17 NO_MEMORY NO_MEMORY Array_create Attempt to allocate memory failed. NO_MEMORY Array_copy Attempt to allocate memory failed. NO_MEMORY Array_resize Attempt to allocate memory failed. NO_MEMORY - List_append Attempt to allocate memory failed. NO_MEMORY - List_insert_element_last Attempt to allocate memory failed. NO_MEMORY - List_concat Attempt to allocate memory failed. NO_MEMORY - List_copy Attempt to allocate memory failed. NO_MEMORY - List_insert_element_after Attempt to allocate memory failed. NO_MEMORY - List_insert_element_before Attempt to allocate memory failed. NO_MEMORY - List_insert_element_first Attempt to allocate memory failed. NO_MEMORY - List_replace_element_at Attempt to allocate memory failed. NO_MEMORY - Trans_copy Attempt to allocate memory failed. NO_MEMORY - Transaction_create Attempt to allocate memory failed. 13.18 NO_MORE_ELEMENTS NO_MORE_ELEMENTS - Iterator_next No more elements 13.19 NO_RESOURCES NO_RESOURCES - CosEventChannelAdmin_ProxyPushConsumer_push Data is too big for the FIFO, should increase the size of the event channel. Data will overwrite existing data in the FIFO. 13.20 NO_RESPONSE NO_RESPONSE - Transaction_commit No collections modified. NO_RESPONSE - Transaction_abort No collections modified. 13.21 NO_RESOURCES NO_RESOURCES - CORBA_BOA_impl_is_ready Unable to create a passive socket for a specific port number. Port number already in use. 13.22 NO_RESPONSE NO_RESPONSE - query_lock Collection already locked. 13.23 NotEmpty NotEmpty - CosNaming_NamingContext_destroy Names are bound to the context; it should be null. Nested contexts are bound to the context; it should be null. 13.24 NotFound NotFound - CosNaming_NamingContext_resolve Naming Context not found in cross reference table. NotFound - CosNaming_NamingContext_list Context object not found in cross reference table. No objects bound to the context. NotFound - CosNaming_BindingIterator_next_one next_one BindingIterator object not found in cross reference table. NotFound - CosNaming_BindingIterator_next_n BindingIterator object not found in cross reference table. NotFound - CosNaming_BindingIterator_destroy BindingIterator object not found in cross reference table. NotFound - CosNaming_NamingContext_unbind Binding name not bound to the context. Object not found in cross-reference table. NotFound - CosNaming_NamingContext_destroy Object not found in cross reference table. 13.25 OBJECT_NOT_EXIST OBJECT_NOT_EXIST - Bind Non existent collection OBJECT_NOT_EXIST - CORBA_BOA_join NULL object reference specified; bad input argument. OBJECT_NOT_EXIST - CORBA_BOA_leave NULL object reference specified; bad input argument. OBJECT_NOT_EXIST - CORBA_duplicate Object not found; bad input argument. OBJECT_NOT_EXIST - CORBA_is_equivalent Object not found; bad input argument. OBJECT_NOT_EXIST - CORBA_is_nil Object not found; bad input argument. OBJECT_NOT_EXIST - CORBA_release Object not found; bad input argument. OBJECT_NOT_EXIST - CORBA_ORB_string_to_object Object not found; bad input argument. 13.26 StreamDataFormatError StreamDataFormatError - CosExternalization_Stream_internalize Read error on the stream, no data returned. Missing START_STREAM_TAG in the stream. StreamDataFormatError - CosStream_StreamIO_read_xxxxx (xxxxx is some supported CORBA attribute). Read error on the stream, no data returned.. Missing START_STREAM_TAG in the stream. Missing xxxxx_STREAM_TAG in the stream Read error on the stream for expected xxxxx data type. 13.27 Transient TRANSIENT - service_orb_request Invalid request length received. Bad data received. Index adb. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 ads. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 AIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 ANSI . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 API. . . . . . . . . . . . . . . . . . . . . . . . . . . . 2, 172 Array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 ASE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 attribute. . . . . . . . . . . . . . . . . . . . . . . . . . 7, 9 constraints on ODL. . . . . . . . . . . . . . . . . . . 7, 9 declared. . . . . . . . . . . . . . . . . . . . . . . . . .9 bind . . . . . . . .26, 28, 57, 59-63, 108-110, 133, 136-139, 180 binding. . . . . . . . . . . . . . . . . . . . . . . . . . . .136 BOA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 broadcast. . . . . . . . . . . . . . . . . . . . . . . . . . . 43 group . . . . . . . . . . . . . . . . . . . . . . . . . . 43 collection . . . . . . . . . . . . . . . . . . . . . . . . . . 17 database definition of. . . . . . . . . . . . . . . . . . 19 communication. . . . . . . . . . . . . . . . . . . . . . . . . 44 compound name. . . . . . . . . . . . . . . . . . . . . . . . . 59 consumer . . . . . . . . . . . . . . . . . . . . . . . . .44, 126 CORBA. . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 Cos. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . .110 Encapsulated Scheduler . . . . . . . . . . . . . . . . . . . . .2 ES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 event. . . . . . . 44-46, 48-56, 77, 80-87, 123-133, 152, 154-159 event channel. . . . . . . . . . . . . . . . . . . . . . . . .126 externalize definition of . . . . . . . . . . . . . . . . . . . .74, 148 factory. . . . . . . . . . . . . . . . . . . . . . . 56, 133, 135 finder. . . . . . . . . . . . . . . . . . . . . . . .56, 133 IDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 attribute . . . . . . . . . . . . . . . . . . . . . . . . .9 preprocessor . . . . . . . . . . . . . . . . . . . . . . 13 idlpp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Information Manager. . . . . . . . . . . . . . . . . . . . . . .2 internalize definition of . . . . . . . . . . . . . . . . . . . .74, 148 iterator . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 lock . . . . . . . . . . . . . . . . . . . . . . 88, 89, 159, 174 memory direct model. . . . . . . . . . . . . . . . . . . . . 10, 32 model declaration . . . . . . . . . . . . . . . . . . . . 10 remote model. . . . . . . . . . . . . . . . . . . . . . . 10 naming . . . . . . . . . . . . . . . . . . . . . . . . . .59, 135 context . . . . . . . . . . . . . . . . . . . . . . . . . 59 naming services. . . . . . . . . . . . . . . . . . . . . .59, 135 ODL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 attribute . . . . . . . . . . . . . . . . . . . . . . . 7, 9 preprocessor . . . . . . . . . . . . . . . . . . . . . . 13 OQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 preprocessor. . . . . . . . . . . . . . . . . . . . . . . 15 oqlpp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 preprocessor . . . . . . . . . . . . . . . . . . . . . . . . . 13 preprocessor . . . . . . . . . . . . . . . . . . . . . . . 13, 15 Limitations . . . . . . . . . . . . . . . . . . . . . . . 13 priority . . . . . . . . . . . 34, 42, 77, 79, 114, 121, 152, 153 bypass. . . . . . . . . . . . . . . . . . . . . . . .85, 157 set priority. . . . . . . . . . . . . . . . . . . . .79, 153 proxy. . . . . . . . . . . . . . . . . . . . . . . . . . .49, 126 pull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 push . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 ref. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 resolve a name . . . . . . . . . . . . . . . . . . . . . . . . 60 select . . . . . . . . . . . . . . . 42, 94-97, 121, 163-166, 178 supplier . . . . . . . . . . . . . . . . . . . . . . . . .44, 126 transaction. . . . . . . . . . . . . . . . . . . . . . . .29, 110 upcall . . . . . . . . . . . . . . . . . . . . . . . . . .34, 114