home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / help / cppwsomr.inf (.txt) < prev    next >
Encoding:
OS/2 Help File  |  1996-02-21  |  491.7 KB  |  22,660 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. About This Book ΓòÉΓòÉΓòÉ
  3.  
  4. Before you begin to use this information, it would be helpful to understand how 
  5. to navigate through it. You can use the Table of Contents and Index facility to 
  6. locate topics and the Search facility to search the text of this document. You 
  7. can use hypertext links to acquire related information on the current topic. 
  8. Hypertext links appear in a different color. For example, here is a link to 
  9. another panel: Communicating Your Comments to IBM. By double-clicking on the 
  10. text of the link or by pressing Enter on a highlighted link, you will open a 
  11. panel of related information. When you open a panel, the first link has the 
  12. focus; to shift the focus to other links, use the Tab key. 
  13.  
  14. You should also understand: 
  15.  
  16.      How to Use the Contents 
  17.      How to Obtain Additional Information 
  18.      How to Use Menu Bar Choices 
  19.      How to Cut and Paste Examples 
  20.  
  21.  
  22. ΓòÉΓòÉΓòÉ 1.1. Notices ΓòÉΓòÉΓòÉ
  23.  
  24. (C) Copyright International Business Machines Corporation, 1995, 1996. All 
  25. rights reserved. 
  26.  
  27. Note to U.S. Government Users - Documentation related to restricted rights - 
  28. Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP 
  29. Schedule Contract with IBM Corp. 
  30.  
  31. This edition applies to Version 3.5 of IBM VisualAge for C++ for Windows 
  32. (33H4979, 33H4980) and to all subsequent releases and modifications until 
  33. otherwise indicated in new editions.  Make sure you are using the correct 
  34. edition for the level of the product. 
  35.  
  36. This publication could include technical inaccuracies or typographical errors. 
  37. Changes are periodically made to the information herein; any such changes will 
  38. be reported in subsequent revisions. 
  39.  
  40. Requests for publications and for technical information about IBM products 
  41. should be made to your IBM Authorized Dealer or your IBM Marketing 
  42. Representative. 
  43.  
  44. When you send information to IBM, you grant IBM a nonexclusive right to use or 
  45. distribute the information in any ways it believes appropriate without 
  46. incurring any obligation to you. 
  47.  
  48. Any reference to an IBM licensed program in this publication is not intended to 
  49. state or imply that only IBM's licensed program may be used. Any functionally 
  50. equivalent product, program, or service that does not infringe any of IBM's 
  51. intellectual property rights may be used instead of the IBM product, program, 
  52. or service. Evaluation and verification of operation in conjunction with other 
  53. products, except  those expressly designated by IBM, is the user's 
  54. responsibility. 
  55.  
  56. IBM may have patents or pending patent applications covering subject matter in 
  57. this document.  The furnishing of this document does not give you any license 
  58. to these patents.  You can send license inquiries, in writing, to the IBM 
  59. Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY, 
  60. 10594, USA. 
  61.  
  62. Licensees of this program who wish to have information about it for the purpose 
  63. of enabling: (i) the exchange of information between independent created 
  64. programs and other programs (including this one) and (ii) the mutual use of the 
  65. information which has been exchanged, should contact IBM Canada Ltd., 
  66. Department 071, 1150 Eglinton Avenue East, North York, Ontario M3C 1H7, Canada. 
  67. Such information may be available, subject to appropriate terms and conditions, 
  68. including in some cases payment of a fee. 
  69.  
  70. This publication contains examples of data and reports used in daily business 
  71. operations. To illustrate them as completely as possible, the examples include 
  72. the names of individuals, companies, brands, and products. All of these names 
  73. are fictitious and any similarity to the names and addresses used by an actual 
  74. business enterprise is entirely coincidental. 
  75.  
  76.  
  77. ΓòÉΓòÉΓòÉ 1.2. Trademarks and Service Marks ΓòÉΓòÉΓòÉ
  78.  
  79. The following terms used in this publication are trademarks or service marks of 
  80. IBM Corporation in the United States or other countries: 
  81.  
  82.       AIX 
  83.       IBM 
  84.       IBMLink 
  85.       OS/2 
  86.       SOMobjects 
  87.       System Object Model 
  88.       VisualAge 
  89.  
  90.  Windows is a trademark of Microsoft Corporation. 
  91.  
  92.  Other company, product, and service names, which may be denoted by a double 
  93.  asterisk(**), may be trademarks or service marks of others. 
  94.  
  95.  IBM's VisualAge products and services are not associated with or sponsored by 
  96.  Visual Edge Software, Ltd.. 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 1.3. How to Use the Contents ΓòÉΓòÉΓòÉ
  100.  
  101. When the Contents window first appears, some topics have a plus (+) sign beside 
  102. them. The plus sign indicates that additional topics are available. 
  103.  
  104. To expand the Contents if you are using a mouse, click on the plus sign. If you 
  105. are using the keyboard, use the Up or Down Arrow key to highlight the topic, 
  106. and press the Plus (+) key. For example, How to Use the Contents has a plus 
  107. sign beside it.  To see additional topics for that heading, click on the plus 
  108. sign or highlight that topic and press the Plus (+) key. 
  109.  
  110. To view a topic, double-click on the topic (or press the Up or Down Arrow key 
  111. to highlight the topic, and then press the Enter key). 
  112.  
  113.  
  114. ΓòÉΓòÉΓòÉ 1.4. How to Obtain Additional Information ΓòÉΓòÉΓòÉ
  115.  
  116. After you select a topic, the information for that topic appears in a window. 
  117. Highlighted words or phrases indicate that additional information is available. 
  118. Certain words and phrases are highlighted in a different color from the 
  119. surrounding text. These are called hypertext terms. 
  120.  
  121. If you are using a mouse, double-click on the highlighted word.  If you are 
  122. using a keyboard, press the Tab key to move to the highlighted word, and then 
  123. press the Enter key.  Additional information then appears in a window. 
  124.  
  125.  
  126. ΓòÉΓòÉΓòÉ 1.5. How to Use Menu Bar Choices ΓòÉΓòÉΓòÉ
  127.  
  128. Several choices are available for managing the information presented in this 
  129. document. There are three choices on the menu bar: the Services menu, the 
  130. Options menu, and the Help menu. 
  131.  
  132. Use the Services menu to operate the active window currently displayed on the 
  133. screen. Available actions include the following: 
  134.  
  135.  Placing Bookmarks 
  136.    You can set a placeholder so you can retrieve information of interest to 
  137.    you. 
  138.  
  139.  Searching for Information 
  140.    You can find occurrences of a word or phrase in the current topic, selected 
  141.    topics, or all topics. 
  142.  
  143.  Printing Information 
  144.    You can print one or more topics. You can also print a set of topics by 
  145.    first marking the topics in the Contents list. 
  146.  
  147.  Copying Information to a File 
  148.    You can copy a topic that you are viewing to the System Clipboard or to a 
  149.    file that you can edit. This method is particularly useful for copying 
  150.    syntax definitions and program samples into the application that you are 
  151.    developing. This copy function does not apply if you are viewing the 
  152.    document from the CD-ROM. 
  153.  
  154.  Select actions from the Options menu, to change the way your Contents list is 
  155.  displayed. To expand the Contents and show all levels for all topics, choose 
  156.  Expand all from the Options pull-down. You can also press the Ctrl, Shift, and 
  157.  * keys together. 
  158.  
  159.  You can select various types of help information from the Help menu. 
  160.  
  161.  For information about any of the menu choices, highlight the choice in the 
  162.  menu and press F1. 
  163.  
  164.  
  165. ΓòÉΓòÉΓòÉ 1.5.1. Placing Bookmarks ΓòÉΓòÉΓòÉ
  166.  
  167. When you place a bookmark on a topic, it is added to a list of bookmarks you 
  168. have previously set.  You can view the list, and you can remove one or all 
  169. bookmarks from the list.  If you have not set any bookmarks, the list is empty. 
  170.  
  171. To set a bookmark, do the following: 
  172.  
  173.    1. Select a topic from the Contents. 
  174.    2. When that topic appears, select the Bookmark option from the Services 
  175.       menu. 
  176.    3. If you want to change the name used for the bookmark, type the new name 
  177.       in the field. 
  178.    4. Click on the Place radio button (or press the Up or Down Arrow key to 
  179.       select it). 
  180.    5. Click on OK (or select it and press Enter). The bookmark is then added to 
  181.       the bookmark list. 
  182.  
  183.  
  184. ΓòÉΓòÉΓòÉ 1.5.2. Searching for Information ΓòÉΓòÉΓòÉ
  185.  
  186. You can specify a word or phrase to be searched.  You can also limit the search 
  187. to a set of topics by first marking the topics in the Contents list. 
  188.  
  189. To search for a word or phrase in all topics, do the following: 
  190.  
  191.    1. Select the Search option from the Services menu. 
  192.    2. Type the word or words to be searched for. 
  193.    3. Click on All sections (or press the Up or Down Arrow keys to select it). 
  194.    4. Click on Search (or select it and press Enter) to begin the search. 
  195.    5. The list of topics where the word or phrase appears is displayed. 
  196.  
  197.  
  198. ΓòÉΓòÉΓòÉ 1.5.3. Printing Information ΓòÉΓòÉΓòÉ
  199.  
  200. You can print one or more topics, the index, or the table of contents.  Make 
  201. sure that your printer is connected to the serial port, configured correctly, 
  202. and ready for input. To print: 
  203.  
  204.    1. Select Print from the Services pull-down menu. 
  205.    2. Select what you want to print. Note that the This section and Marked 
  206.       sections choices are only available if you are viewing a topic or if you 
  207.       have marked topics, respectively.  To mark topics in the table of 
  208.       contents, press the Ctrl key and click on the topics, or use the arrow 
  209.       keys. 
  210.    3. Select Print to print what you've chosen. 
  211.  
  212.  
  213. ΓòÉΓòÉΓòÉ 1.5.4. Copying Information to a File ΓòÉΓòÉΓòÉ
  214.  
  215. You can copy a topic that you are viewing in two ways: 
  216.  
  217.      Copy copies the topic that you are viewing into the System Clipboard. 
  218.  
  219.      Copy to file copies the topic that you are viewing into a temporary file 
  220.       named text.tmp.  You can later edit that file by using any editor. The 
  221.       text.tmp file is placed in the directory where your viewable document 
  222.       resides. This copy function does not apply if you are viewing the 
  223.       document from the CD-ROM. 
  224.  
  225.  To copy a topic, do the following: 
  226.  
  227.    1. Expand the Contents list and select a topic. 
  228.    2. When the topic appears, select Copy to file from the Services menu. 
  229.    3. The system puts the text pertaining to that topic into the temporary file 
  230.       text.tmp. 
  231.  
  232.  
  233. ΓòÉΓòÉΓòÉ 1.6. How to Cut and Paste Examples ΓòÉΓòÉΓòÉ
  234.  
  235. You can copy examples (or information) from this reference/guide/book to 
  236. compile, link, and run them, or to paste them into your own code. 
  237.  
  238. To copy an example or information: 
  239.  
  240.    1. Make the topic you want to copy the active window. 
  241.  
  242.    2. From the Services menu, select Copy to file. The text in that topic is 
  243.       placed in the temporary file text.tmp, in the same directory as this 
  244.       reference. This copy function does not apply if you are viewing the 
  245.       document from the CD-ROM. 
  246.  
  247.    3. You can then modify or use text.tmp as you want. 
  248.  
  249.  Note:  Because the system copies the entire contents of the topic to the file, 
  250.  you may need to edit it to remove additional text. Most examples in this 
  251.  reference are ready to compile, link, and run as they appear, and do not 
  252.  require any editing. 
  253.  
  254.  
  255. ΓòÉΓòÉΓòÉ 1.7. Other Information You Might Find Helpful ΓòÉΓòÉΓòÉ
  256.  
  257. This product provides a number of online guides and references that we hope 
  258. you'll find helpful as you develop applications. This information includes 
  259. User's Guides, References, and How Do I help that gives you specific 
  260. instructions for performing common tasks. You can get to this online 
  261. information from the Information folder inside the main product folder.  You 
  262. can also get to it from the Help menu in any of the components of the product. 
  263.  
  264.  
  265. ΓòÉΓòÉΓòÉ 1.8. Communicating Your Comments to IBM ΓòÉΓòÉΓòÉ
  266.  
  267. If there is something you like, or dislike, about this book, please let us 
  268. know.  You can use one of the methods listed below to send your comments to 
  269. IBM.  Please be sure to include the complete title of the publication that you 
  270. are commenting on. 
  271.  
  272. The comments you send should only pertain to the information in this document 
  273. and its presentation.  To request additional publications or to ask questions 
  274. or make comments about the functions of IBM products or systems, you should 
  275. talk to your IBM representative or your authorized IBM remarketer. 
  276.  
  277. When you send comments to IBM, you grant IBM a nonexclusive right to use or 
  278. distribute your comments in any way it believes appropriate without incurring 
  279. any obligation to you. 
  280.  
  281. You can send your comments to IBM in the following ways: 
  282.  
  283.      By mail to the following address: 
  284.  
  285.             IBM Canada Ltd. Laboratory
  286.             Information Development
  287.             2G/345/1150/TOR
  288.             1150 EGLINTON AVENUE EAST
  289.             NORTH YORK, ONTARIO
  290.             CANADA M3C 1H7
  291.  
  292.      By FAX to the following number: 
  293.  
  294.         -  United States and Canada: (416) 448-6161 
  295.         -  Other countries (+1) 416-448-6161 
  296.  
  297.      By electronic mail to one of the following IDs.  Be sure to include your 
  298.       entire network address if you wish to get a reply. 
  299.  
  300.         -  Internet: torrcf@vnet.ibm.com 
  301.         -  IBMLink: toribm(torrcf) 
  302.         -  IBM/PROFS: torolab4(torrcf) 
  303.         -  IBMMAIL: ibmmail(caibmwt9) 
  304.  
  305.  
  306. ΓòÉΓòÉΓòÉ 2. SOM Kernel Reference ΓòÉΓòÉΓòÉ
  307.  
  308.  
  309. SOM Kernel Class Organization
  310.  
  311.  
  312. ΓòÉΓòÉΓòÉ 2.1. somApply ΓòÉΓòÉΓòÉ
  313.  
  314. somApply 
  315.  
  316. This function invokes an apply stub. Apply stubs are never invoked directly by 
  317. SOM users. The somApply function must be used instead. 
  318.  
  319.  Syntax 
  320.  
  321.                     boolean somApply (SOMObject objPtr, somToken *retVal, somMethodDataPtr mdPtr,
  322.                                va_list args)
  323.  
  324.  Parameters 
  325.  
  326.           objPtr (SOMObject) 
  327.                     A pointer to the object on which the method procedure is to 
  328.                     be invoked. 
  329.  
  330.           retVal (somToken *) 
  331.                     A pointer to the memory region into which the result 
  332.                     returned by the method procedure is to be copied. This 
  333.                     pointer cannot be null (even in the case of method 
  334.                     procedures whose returned result is void). 
  335.  
  336.           mdPtr (somMethodDataPtr) 
  337.                     A pointer to the somMethodData structure that describes the 
  338.                     method whose procedure is to be executed by the apply stub. 
  339.  
  340.           args (va_list) 
  341.                     A va_list that contains the arguments for the method 
  342.                     procedure. The first entry of the va_list must be objPtr. 
  343.                     Furthermore, all arguments on the va_list must appear in 
  344.                     widened form, as defined by ANSI C. For example, a float 
  345.                     must appear as a double, and a char and a short must appear 
  346.                     as the int data type. The SOM API for va_list construction 
  347.                     ensures this. 
  348.  
  349.  Returns 
  350.  
  351.           rc (boolean) 
  352.  
  353.  Remarks 
  354.  
  355.           This function provides a single uniform interface through which it is 
  356.           possible to call any method procedure. The interface is based on the 
  357.           caller passing: the object to which the method procedure is to be 
  358.           applied; a return address for the method result; a somMethodDataPtr 
  359.           indicating the desired method procedure; and an ANSI standard va_list 
  360.           structure containing the method procedure arguments. Different method 
  361.           procedures expect different argument types and return different 
  362.           result types, so the purpose of this function is to select an apply 
  363.           stub appropriate for the specific method involved, according to the 
  364.           supplied method data, and then call this apply stub. The apply stub 
  365.           removes the arguments from the va_list, calls the method procedure 
  366.           with these arguments, accepts the returned result, and then copies 
  367.           this result to the location pointed to by retVal. 
  368.  
  369.           The method procedure used by the apply stub is determined by the 
  370.           content of the somMethodData structure pointed to by mdPtr. The class 
  371.           methods somGetMethodData and somGetNthMethodData are used to load a 
  372.           somMethodData structure. These methods resolve static method 
  373.           procedures based on the receiving class's instance method table. 
  374.  
  375.           The SOM API requires that information necessary for selecting an 
  376.           apply stub be provided when a new method is registered with its 
  377.           introducing class (via the methods somAddStaticMethod or 
  378.           somAddDynamicMethod). This is required because SOM itself needs apply 
  379.           stubs when dispatch method resolution is used. C and C++ 
  380.           implementation bindings for SOM classes support this requirement, but 
  381.           SOM does not terminate execution if this requirement is not met by a 
  382.           class implementor. Thus, it is possible that there may be methods for 
  383.           which this function cannot select an appropriate apply stub. If an 
  384.           apply stub can be selected, then somApply performs as described 
  385.           above, and a TRUE value is returned; otherwise FALSE is returned. 
  386.  
  387.  Related Information 
  388.  
  389.           Data Structures 
  390.  
  391.               SOMObject (somobj.idl) 
  392.               somMethodData (somapi.h) 
  393.               somToken (sombtype.h) 
  394.               somMethodPtr (sombtype.h) 
  395.               va_list (stdarg.h) 
  396.  
  397.           Methods 
  398.  
  399.               somGetMethodData 
  400.               somGetNthMethodData 
  401.               somAddDynamicMethod (somcls.idl) 
  402.  
  403.  Example Code 
  404.  
  405.                     #include <somcls.xh>
  406.                     #include <string.h>
  407.                     #include <stdarg.h>
  408.                     main()
  409.                     {
  410.                         somVaBuf vb;
  411.                         va_list args;
  412.                         string result;
  413.                         SOMClass *scObj;
  414.                         somMethodData md;
  415.  
  416.                         somEnvironmentNew();    /* Init environment */
  417.                         scObj = _SOMClass;   /* The SOMClass object */
  418.  
  419.                         scObj->somGetMethodData(somIdFromString("somGetName"), &md);
  420.                         vb = (somVaBuf)somVaBuf_create(NULL, 0);
  421.                         somVaBuf_add(vb, (char *)&scObj, tk_ulong);
  422.                         somVaBuf_get_valist(vb, &args);
  423.  
  424.                         somApply(scObj, (somToken*)&result, &md, args);
  425.                         SOM_Assert(!strcmp(result, "SOMClass"), SOM_Fatal);
  426.                         /* result is "SOMClass" */
  427.                     }
  428.  
  429.  
  430. ΓòÉΓòÉΓòÉ 2.2. somBuildClass ΓòÉΓòÉΓòÉ
  431.  
  432. somBuildClass 
  433.  
  434. This function automates the process of building a new SOM class object. 
  435.  
  436.  Syntax 
  437.  
  438.                     SOMClass somBuildClass (unsigned long inheritVars, somStaticClassInfoPtr sciPtr,
  439.                                   long majorVersion, long minorVersion)
  440.  
  441.  Parameters 
  442.  
  443.           inheritVars (unsigned long) 
  444.                     A bit mask that determines inheritance from parent classes. 
  445.                     A mask containing all ones is an appropriate default. 
  446.  
  447.           sciPtr (somStaticClassInfoPtr) 
  448.                     A pointer to a structure holding static class information. 
  449.  
  450.           majorVersion (long) 
  451.                     The major version number for the class. 
  452.  
  453.           minorVersion (long) 
  454.                     The minor version number for the class. 
  455.  
  456.  Returns 
  457.  
  458.           rc (SOMClass) 
  459.                     A pointer to a class object. 
  460.  
  461.  Remarks 
  462.  
  463.           This function accepts declarative information defining a new class 
  464.           that is be built, and performs the activities required to build and 
  465.           register a correctly functioning class object. The C and C++ 
  466.           implementation bindings use this function to create class objects. 
  467.  
  468.  Related Information 
  469.  
  470.           Data Structures 
  471.  
  472.               somStaticClassInfo (somapi.h) 
  473.  
  474.  Example Code 
  475.  
  476.                     See any .ih or .xih implementation binding file for
  477.                     details on construction of the required data
  478.                     structures.
  479.  
  480.  
  481. ΓòÉΓòÉΓòÉ 2.3. somCheckId ΓòÉΓòÉΓòÉ
  482.  
  483. somCheckId 
  484.  
  485. This function registers a som ID. 
  486.  
  487.  Syntax 
  488.  
  489.                     somId somCheckId (somId id)
  490.  
  491.  Parameters 
  492.  
  493.           id (somId) 
  494.                     The somId to be registered. 
  495.  
  496.  Returns 
  497.  
  498.           rc (somId) 
  499.  
  500.                     The registered somId. 
  501.  
  502.  Remarks 
  503.  
  504.           This function registers a SOM ID and converts it into an internal 
  505.           representation. The input SOM ID is returned. If the ID is already 
  506.           registered, this function has no effect. 
  507.  
  508.  Related Information 
  509.  
  510.           Data Structures 
  511.  
  512.               somId (sombtype.h) 
  513.  
  514.           Methods 
  515.  
  516.               somRegisterId 
  517.               somFromString 
  518.               somStringFromId 
  519.               comCompareIds 
  520.               somTotalRegIds 
  521.               somSetExpectedIds 
  522.               somUniqueKey 
  523.  
  524.  
  525. ΓòÉΓòÉΓòÉ 2.4. somClassResolve ΓòÉΓòÉΓòÉ
  526.  
  527. somClassResolve 
  528.  
  529. This function obtains a pointer to the procedure that implements a static 
  530. method for instances of a particular SOM class. 
  531.  
  532.  Syntax 
  533.  
  534.                     somMethodPtr somClassResolve (SOMClass cls, somMToken mToken)
  535.  
  536.  Parameters 
  537.  
  538.           cls (SOMClass) 
  539.                     A pointer to the class object whose instance method 
  540.                     procedure is required. 
  541.  
  542.           mToken (somMToken) 
  543.                     The method token for the method to be resolved. The SOM API 
  544.                     requires that if the class "XYZ" introduces the static 
  545.                     method "foo", then the method token for "foo" is found in 
  546.                     the class data structure for "XYZ" (called XYZClassData) in 
  547.                     the structure member named "foo" (i.e., at 
  548.                     XYZClassData.foo). Method tokens can also be obtained using 
  549.                     the somGetMethodToken method. A pointer to the class object 
  550.                     whose instance method procedure is required. 
  551.  
  552.  Returns 
  553.  
  554.           rc (somMethodPtr) 
  555.  
  556.                     A pointer to the somMethodProc (procedure) that implements 
  557.                     the specified method for the specified class of SOM object. 
  558.  
  559.  Remarks 
  560.  
  561.           This function is used to obtain a pointer to the procedure that 
  562.           implements the specified method for instances of the specified SOM 
  563.           class. The returned procedure pointer can then be used to invoke the 
  564.           method. The somClassResolve function is used to support "casted" 
  565.           method calls, in which a method is resolved with respect to a 
  566.           specified class rather than the class of which an object is a direct 
  567.           instance. The somClassResolve function can only be used to obtain a 
  568.           method procedure for a static method (a method declared in an IDL 
  569.           specification for a class); dynamic methods do not have method 
  570.           tokens. 
  571.  
  572.           The SOM language usage bindings for C and C++ do not support casted 
  573.           method calls, so this function must be used directly to achieve this 
  574.           functionality. Whenever using SOM method procedure pointers, it is 
  575.           necessary to indicate the use of system linkage to the compiler. The 
  576.           way this is done depends on the compiler and the system being used. 
  577.           However, C and C++ usage bindings provide an appropriate typedef for 
  578.           this purpose. The name of the typedef is based on the name of the 
  579.           class that introduces the method, as illustrated in the example 
  580.           below. 
  581.  
  582.  Related Information 
  583.  
  584.           Data Structures 
  585.  
  586.               somMethodPtr (sombtype.h) 
  587.               SOMClass (somcls.idl) 
  588.               somMToken (somapi.h) 
  589.  
  590.           Functions 
  591.  
  592.               somResolveByName 
  593.               somParentResolve 
  594.               somParentNumResolve 
  595.               somResolve 
  596.  
  597.           Methods 
  598.  
  599.               somDispatch 
  600.               somClassDispatch 
  601.               somFindMethod 
  602.               somFindMethodOk 
  603.               somGetMethodToken 
  604.  
  605.           Macros 
  606.  
  607.               SOM_Resolve 
  608.               SOM_ResolveNoCheck 
  609.  
  610.  Example Code 
  611.  
  612.                     // SOM IDL for class A and class B
  613.                     #include <somobj.idl>
  614.                     module scrExample {
  615.                       interface A : SOMObject { void foo(); implementation
  616.                     { callstyle=oidl;};};
  617.                       interface B : A  {  implementation { foo: override;};};
  618.                     };
  619.  
  620.                     // Example C++ program to implement and test module scrExample
  621.                     #define SOM_Module_screxample_Source
  622.                     #include <scrExample.xih>
  623.                     #include <stdio.h>
  624.  
  625.                     SOM_Scope void SOMLINK scrExample_Afoo(scrExample_A *somSelf);
  626.                     {  printf("1\n");}
  627.  
  628.                     SOM_Scope void SOMLINK scrExample_Bfoo(scrExample_B *somSelf);
  629.                     { printf("2\n");}
  630.  
  631.                     main()
  632.                     {
  633.                       scrExample_B  *objPtr = new scrExample_B;
  634.  
  635.                     // This prints 2
  636.                     objPtr->foo();
  637.  
  638.                     // This prints 1
  639.                        ((somTD_scrExample_A_foo) /* A necessary method procedure cast */
  640.                          somClassResolve(
  641.                                   ,_scrExample_A, // the A class object
  642.                                   scrExample_AClassData.foo) // the foo method token
  643.                          ) /* end of method procedure expression */
  644.                          (objPtr); /* method arguments */
  645.  
  646.                     // This prints 2
  647.                        ((somTD_scrExample_A_foo) /* A necessary method procedure cast */
  648.                          somClassResolve(
  649.                                   ,_scrExample_B, // the B class object
  650.                                   scrExample_AClassData.foo) // the foo method token
  651.                          ) /* end of method procedure expression */
  652.                          (objPtr); /* method arguments */
  653.  
  654.                     }
  655.  
  656.  
  657. ΓòÉΓòÉΓòÉ 2.5. somCompareIds ΓòÉΓòÉΓòÉ
  658.  
  659. somCompareIds This function determines whether two SOM IDs represent the same 
  660. string. 
  661.  
  662.  Syntax 
  663.  
  664.                     int somCompareIds (somId id1, somId id2)
  665.  
  666.  Parameters 
  667.  
  668.           id1 (somId) 
  669.                     The first SOM ID to be compared. 
  670.  
  671.           id2 (somId) 
  672.                     The second SOM ID to be compared. 
  673.  
  674.  Returns 
  675.  
  676.           rc (int) 
  677.  
  678.                     1        Returns 1 if the two input IDs represent strings 
  679.                              that are equal. 
  680.                     0        Returns 0 if the two input IDs represent strings 
  681.                              that are not equal. 
  682.  
  683.  Remarks 
  684.  
  685.           This function returns 1 if the two input IDs represent strings that 
  686.           are equal; otherwise, it returns 0. 
  687.  
  688.  Related Information 
  689.  
  690.           Data Structures 
  691.  
  692.               somId (sombtype.h) 
  693.  
  694.           Functions 
  695.  
  696.               somCheckId 
  697.               somRegisterId 
  698.               somIdFromString 
  699.               somStringFromId 
  700.               somTotalRegIds 
  701.               somSetExpectedIds 
  702.               somUniqueKey 
  703.  
  704.  Example Code 
  705.  
  706.                     #include <som.h>
  707.                     main()
  708.                     {
  709.                        somId id1, id2, id3;
  710.  
  711.                        somEnvironmentNew();
  712.                        id1 = somIdFromString("this");
  713.                        id2 = somIdFromString("that");
  714.                        id3 = somIdFromString("this");
  715.  
  716.                        SOM_Test(somCompareIds(id1, id3));
  717.                        SOM_Test(!somCompareIds(id1, id2));
  718.                     }
  719.  
  720.  
  721. ΓòÉΓòÉΓòÉ 2.6. somDataResolve ΓòÉΓòÉΓòÉ
  722.  
  723. somDataResolve 
  724.  
  725. This function accesses instance data within an object. 
  726.  
  727.  Syntax 
  728.  
  729.                     somToken somDataResolve (SOMObject obj, somDToken dToken)
  730.  
  731.  Parameters 
  732.  
  733.           obj (SOMObject) 
  734.                     A pointer to the object whose instance data is required. 
  735.  
  736.           dToken (somDToken) 
  737.                     A data token for the required instance data. The SOM API 
  738.                     specifies that the data token for accessing the instance 
  739.                     data introduced by a class is found in the 
  740.                     instanceDataToken component of the auxiliary class data 
  741.                     structure for that class. The example below illustrates 
  742.                     this. 
  743.  
  744.  Returns 
  745.  
  746.           rc (somToken) 
  747.  
  748.                     A somToken (that is, a pointer) that points to the data in 
  749.                     obj identified by the dToken. If obj does not contain the 
  750.                     requested data identified by dToken, somDataResolve 
  751.                     generates a runtime error. 
  752.  
  753.  Remarks 
  754.  
  755.           The somDataResolve function is used to access instance data within an 
  756.           object. This function is of use primarily to class implementors 
  757.           (rather than class clients) who are not using the SOM C or C++ 
  758.           language bindings. 
  759.  
  760.           For C or C++ programmers with access to the C or C++ implementation 
  761.           bindings for a class, instance data can be accessed using the GetData 
  762.           macro (which expands to a usage of somDataResolve). 
  763.  
  764.  Related Information 
  765.  
  766.           Data Structures 
  767.  
  768.               somToken (sombtype.h) 
  769.               SOMObject (somobj.idl) 
  770.               somDToken (somapi.h) 
  771.  
  772.  Example Code 
  773.  
  774.           The following C/C++ expression evaluates to the address of the 
  775.           instance data introduced by class "XYZ" within the object "obj". This 
  776.           assumes that obj points to an instance of "XYZ" or a subclass of 
  777.           "XYZ". 
  778.  
  779.                     #include <som.h>
  780.                     somDataResolve(obj, XYZCClassData.instanceDataToken);
  781.  
  782.  
  783. ΓòÉΓòÉΓòÉ 2.7. somDataResolveChk ΓòÉΓòÉΓòÉ
  784.  
  785. somDataResolveChk 
  786.  
  787. This function accesses instance data within an object. 
  788.  
  789.  Syntax 
  790.  
  791.                     somToken somDataResolveChk (SOMObject obj, somDToken dToken)
  792.  
  793.  Parameters 
  794.  
  795.           obj (SOMObject) 
  796.                     A pointer to the object whose instance data is required. 
  797.  
  798.           dToken (somDToken) 
  799.                     A data token for the required instance data. The SOM API 
  800.                     specifies that the data token for accessing the instance 
  801.                     data introduced by a class is found in the 
  802.                     instanceDataToken component of the auxiliary class data 
  803.                     structure for that class. The example below illustrates 
  804.                     this. 
  805.  
  806.  Returns 
  807.  
  808.           rc (somToken) 
  809.  
  810.                     A somToken (that is, a pointer) that points to the data in 
  811.                     obj identified by the dToken. If obj does not contain the 
  812.                     requested data identified by dToken, somDataResolveChk 
  813.                     returns NULL. 
  814.  
  815.  Remarks 
  816.  
  817.           The somDataResolveChk function is used to access instance data within 
  818.           an object. This function is of use primarily to class implementors 
  819.           (rather than class clients) who are not using the SOM C or C++ 
  820.           language bindings. 
  821.  
  822.           For C or C++ programmers with access to the C or C++ implementation 
  823.           bindings for a class, instance data can be accessed using the GetData 
  824.           macro (which expands to a usage of somDataResolve). 
  825.  
  826.  Related Information 
  827.  
  828.           Data Structures 
  829.  
  830.               somToken (sombtype.h) 
  831.               SOMObject (somobj.idl) 
  832.               somDToken (somapi.h) 
  833.  
  834.  Example Code 
  835.  
  836.           The following C/C++ expression evaluates to the address of the 
  837.           instance data introduced by class "XYZ" within the object "obj". This 
  838.           assumes that obj points to an instance of "XYZ" or a subclass of 
  839.           "XYZ". 
  840.  
  841.                     #include <som.h>
  842.                     somDataResolveChk(obj, XYZCClassData.instanceDataToken);
  843.  
  844.  
  845. ΓòÉΓòÉΓòÉ 2.8. somEnvironmentEnd ΓòÉΓòÉΓòÉ
  846.  
  847. somEnvironmentEnd This function provides general cleanup for applications. 
  848.  
  849.  Syntax 
  850.  
  851.                     void somEnvironmentEnd ()
  852.  
  853.  Parameters 
  854.  
  855.                     None. 
  856.  
  857.  Returns 
  858.  
  859.           rc (void) 
  860.  
  861.  Remarks 
  862.  
  863.           This function is a general cleanup function that must be called by 
  864.           all Windows applications before exiting. AIX and OS/2 programs may 
  865.           also invoke this function, but it is not required on these systems 
  866.           because all necessary SOM cleanup is performed by the operating 
  867.           system during program termination. 
  868.  
  869.           A convenience macro, SOM_MainProgram, which usually appears at the 
  870.           beginning of each application, adds this function to the "atexit" 
  871.           list. If the "atexit" mechanism does not work reliably with your 
  872.           compiler, or if you know that your program bypasses the normal 
  873.           program termination sequence, you should insert an explicit call to 
  874.           this function at the point where your main program exits. (All main 
  875.           programs for Windows must begin either with the SOM_MainProgram macro 
  876.           or with a call to the somMainProgram function.) 
  877.  
  878.  Related Information 
  879.  
  880.           Macros 
  881.  
  882.               SOM_MainProgram 
  883.  
  884.  
  885. ΓòÉΓòÉΓòÉ 2.9. somEnvironmentNew ΓòÉΓòÉΓòÉ
  886.  
  887. somEnvironmentNew 
  888.  
  889. This function initializes the SOM runtime environment. 
  890.  
  891.  Syntax 
  892.  
  893.                     SOMClassMgr somEnvironmentNew ()
  894.  
  895.  Parameters 
  896.  
  897.                     None. 
  898.  
  899.  Returns 
  900.  
  901.           rc (SOMClassMgr) 
  902.  
  903.                     A pointer to the single class manager object active at run 
  904.                     time. This class manager can be referred by the global 
  905.                     variable SOMClassMgrObject. 
  906.  
  907.  Remarks 
  908.  
  909.           This function creates the four primitive SOM objects (SOMObject, 
  910.           SOMClass, SOMClassMgr, and SOMClassMgrObject) and initializes global 
  911.           variables used by the SOM run-time environment. This function must be 
  912.           called before using any other SOM functions or methods (with the 
  913.           exception of somSetExpectedIds). If the SOM run-time environment has 
  914.           already been initialized, calling this function has no harmful 
  915.           effect. 
  916.  
  917.           Although this function must be called before using other SOM 
  918.           functions or methods, it needn't always be called explicitly, because 
  919.           the New macros, the  Renew macros, the new operator, and the NewClass 
  920.           procedures defined by the SOM C and C++ language bindings call 
  921.           somEnvironmentNew  if needed. 
  922.  
  923.  Related Information 
  924.  
  925.           Functions 
  926.  
  927.               somExceptionId 
  928.               somExceptionValue 
  929.               somSetException 
  930.               somGetGlobalEnvironment 
  931.  
  932.  Example Code 
  933.  
  934.                     somEnvironmentNew();
  935.  
  936.  
  937. ΓòÉΓòÉΓòÉ 2.10. somExceptionFree ΓòÉΓòÉΓòÉ
  938.  
  939. somExceptionFree 
  940.  
  941. This function frees the memory held by the exception structure within an 
  942. Environment structure. 
  943.  
  944.  Syntax 
  945.  
  946.                     void somExceptionFree (Environment *env)
  947.  
  948.  Parameters 
  949.  
  950.           env (Environment *) 
  951.                     A pointer to the Environment whose exception information is 
  952.                     to be freed. 
  953.  
  954.  Returns 
  955.  
  956.           rc (void) 
  957.  
  958.  Remarks 
  959.  
  960.           This function frees the memory held by the exception structure within 
  961.           an Environment structure. 
  962.  
  963.  Related Information 
  964.  
  965.           Data Structures 
  966.  
  967.               Environment (somcorba.h) 
  968.  
  969.           Functions 
  970.  
  971.               somExceptionld 
  972.               somExceptionValue 
  973.               somSetException 
  974.               somGetGlobalEnvironment 
  975.               somdExceptionFree (DSOM function) 
  976.  
  977.  Example Code 
  978.  
  979.                     See function somSetException.
  980.  
  981.  
  982. ΓòÉΓòÉΓòÉ 2.11. somExceptionId ΓòÉΓòÉΓòÉ
  983.  
  984. somExceptionId 
  985.  
  986. This function gets the name of the exception contained in an Environment 
  987. structure. 
  988.  
  989.  Syntax 
  990.  
  991.                     string somExceptionId (Environment *env)
  992.  
  993.  Parameters 
  994.  
  995.           env (Environment *) 
  996.                     A pointer to an Environment structure containing an 
  997.                     exception. 
  998.  
  999.  Returns 
  1000.  
  1001.           rc (string) 
  1002.  
  1003.                     string 
  1004.  
  1005.                                     Returns the name of the exception contained 
  1006.                                     in the specified Environment structure, as 
  1007.                                     a string. 
  1008.  
  1009.  Remarks 
  1010.  
  1011.           This function returns the name of the exception contained in the 
  1012.           specified Environment structure. 
  1013.  
  1014.  Related Information 
  1015.  
  1016.           Data Structures 
  1017.  
  1018.               string (somcorba.h) 
  1019.               Environment (somcorba.h) 
  1020.  
  1021.           Functions 
  1022.  
  1023.               somExceptionValue 
  1024.               somExceptionFree 
  1025.               somSetException 
  1026.               somGetGlobalEnvironment 
  1027.  
  1028.  Example Code 
  1029.  
  1030.                     See function somSetException.
  1031.  
  1032.  
  1033. ΓòÉΓòÉΓòÉ 2.12. somExceptionValue ΓòÉΓòÉΓòÉ
  1034.  
  1035. somExceptionValue 
  1036.  
  1037. This function gets the value of the exception contained in an Environment 
  1038. structure. 
  1039.  
  1040.  Syntax 
  1041.  
  1042.                     somToken somExceptionValue (Environment *env)
  1043.  
  1044.  Parameters 
  1045.  
  1046.           env (Environment *) 
  1047.                     A pointer to an Environment structure containing an 
  1048.                     exception. 
  1049.  
  1050.  Returns 
  1051.  
  1052.           rc (somToken) 
  1053.                     Returns a pointer to the value of the exception contained 
  1054.                     in the specified Environment structure. 
  1055.  
  1056.  Remarks 
  1057.  
  1058.           This function returns the value of the exception contained in the 
  1059.           specified Environment structure. 
  1060.  
  1061.  Related Information 
  1062.  
  1063.           Data Structures 
  1064.  
  1065.               somToken (sombtype.h) 
  1066.               Environment (somcorba.h) 
  1067.  
  1068.           Functions 
  1069.  
  1070.               somExceptionId 
  1071.               somExceptionFree 
  1072.               somSetException 
  1073.               somGetGlobalEnvironment 
  1074.               somSetGlobalEnvironment 
  1075.  
  1076.  Example Code 
  1077.  
  1078.                     See function somSetException.
  1079.  
  1080.  
  1081. ΓòÉΓòÉΓòÉ 2.13. somGetGlobalEnvironment ΓòÉΓòÉΓòÉ
  1082.  
  1083. somGetGlobalEnvironment 
  1084.  
  1085. This function returns a pointer to the current global Environment structure. 
  1086.  
  1087.  Syntax 
  1088.  
  1089.                     Environment * somGetGlobalEnvironment ()
  1090.  
  1091.  Parameters 
  1092.  
  1093.                     None. 
  1094.  
  1095.  Returns 
  1096.  
  1097.           rc (Environment *) 
  1098.  
  1099.                     A pointer to the current global Environment structure. 
  1100.  
  1101.  Remarks 
  1102.  
  1103.           This function returns a pointer to the current global Environment 
  1104.           structure. This structure can be passed to methods that require an 
  1105.           (Environment *) argument. The caller can determine if the called 
  1106.           method has raised an exception by testing whether 
  1107.  
  1108.                     ev->exception._major != NO_EXCEPTION
  1109.  
  1110.           If an exception has been raised, the caller can retrieve the name and 
  1111.           value of the exception using the somExceptionId and somExceptionValue 
  1112.           methods. 
  1113.  
  1114.  Related Information 
  1115.  
  1116.           Data Structures 
  1117.  
  1118.               Environment (somcorba.h) 
  1119.  
  1120.           Functions 
  1121.  
  1122.               somExceptionId 
  1123.               somExceptionValue 
  1124.               somExceptionFree 
  1125.               somSetException 
  1126.  
  1127.  Example Code 
  1128.  
  1129.                     See function somSetException.
  1130.  
  1131.  
  1132. ΓòÉΓòÉΓòÉ 2.14. somIdFromString ΓòÉΓòÉΓòÉ
  1133.  
  1134. somIdFromString 
  1135.  
  1136. This function returns the SOM ID corresponding to a given text string. 
  1137.  
  1138.  Syntax 
  1139.  
  1140.                     somId somIdFromString (string aString)
  1141.  
  1142.  Parameters 
  1143.  
  1144.           aString (string) 
  1145.                     The string to be converted to a SOM ID. 
  1146.  
  1147.  Returns 
  1148.  
  1149.           rc (somId) 
  1150.  
  1151.                     Returns the SOM ID corresponding to the given text string. 
  1152.  
  1153.  
  1154.  Remarks 
  1155.  
  1156.           This function returns the SOM ID that corresponds to a given text 
  1157.           string. 
  1158.  
  1159.           Ownership of the somId returned by this function passes to the 
  1160.           caller, which has the responsibility to subsequently free the somId 
  1161.           using SOMFree. 
  1162.  
  1163.  Related Information 
  1164.  
  1165.           Data Structures 
  1166.  
  1167.               somId (sombtype.h) 
  1168.               string (somcorba.h) 
  1169.  
  1170.           Functions 
  1171.  
  1172.               somCheckId 
  1173.               somRegisterId 
  1174.               somStringFromId 
  1175.               somCompareIds 
  1176.               somTotalRegIds 
  1177.               somSetExpectedIds 
  1178.               somUniqueKey 
  1179.  
  1180.  
  1181. ΓòÉΓòÉΓòÉ 2.15. somIsObj ΓòÉΓòÉΓòÉ
  1182.  
  1183. somIsObj 
  1184.  
  1185. This function is a failsafe routine to determine whether a pointer references a 
  1186. valid SOM object. 
  1187.  
  1188.  Syntax 
  1189.  
  1190.                     boolean somIsObj (somToken memPtr)
  1191.  
  1192.  Parameters 
  1193.  
  1194.           memPtr (somToken) 
  1195.                     A somToken (a pointer) to be checked. 
  1196.  
  1197.  Returns 
  1198.  
  1199.           rc (boolean) 
  1200.  
  1201.                     1        Returns 1 if obj is a pointer to a valid SOM 
  1202.                              object. 
  1203.                     0        Returns 0 if obj is not a pointer to an valid SOM 
  1204.                              object. 
  1205.  
  1206.  Remarks 
  1207.  
  1208.           This function returns 1 if its argument is a pointer to a valid SOM 
  1209.           object, or returns 0 otherwise. The function handles address faults, 
  1210.           and does extensive consistency checking to guarantee a correct 
  1211.           result. 
  1212.  
  1213.  Related Information 
  1214.  
  1215.           Data Structures 
  1216.  
  1217.               boolean (somcorba.h) 
  1218.               somToken (sombtype.h) 
  1219.  
  1220.  Example Code 
  1221.  
  1222.                     #include <stdio.h>
  1223.                     #include <som.xh>
  1224.  
  1225.                     void example(void *memPtr)
  1226.                     {
  1227.                        if (!somIsObj(memPtr))
  1228.                          printf("memPtr is not a valid SOM object.\n");
  1229.                        else
  1230.                          printf("memPtr points to an object of class %s\n",
  1231.                                  ((SOMObject *)memPtr)->somGetClassName());
  1232.                     }
  1233.  
  1234.  
  1235. ΓòÉΓòÉΓòÉ 2.16. somLPrintf ΓòÉΓòÉΓòÉ
  1236.  
  1237. somLPrintf 
  1238.  
  1239. This function prints a formatted string in the manner of the C printf function, 
  1240. at the specified indentation level. 
  1241.  
  1242.  Syntax 
  1243.  
  1244.                     long somLPrintf (long level, string fmt, . . .)
  1245.  
  1246.  Parameters 
  1247.  
  1248.           level (long) 
  1249.                     The level at which output is to be placed. 
  1250.  
  1251.           fmt (string) 
  1252.                     The format string to be output. 
  1253.  
  1254.           . . . 
  1255.                     The values to be substituted into the format string. 
  1256.  
  1257.  Returns 
  1258.  
  1259.           rc (long) 
  1260.                     Returns the number of characters written. 
  1261.  
  1262.  Remarks 
  1263.  
  1264.           This function prints a formatted string using SOMOutCharRoutine, in 
  1265.           the same manner as the C printf function. The implementation of 
  1266.           SOMOutCharRoutine determines the destination of the output, while the 
  1267.           C printf function is always directed to stdout. (The default output 
  1268.           destination for SOMOutCharRoutine is stdout also, but this can be 
  1269.           modified by the user.) The output is prefixed at the indicated level, 
  1270.           by preceding it with 2*level spaces. 
  1271.  
  1272.  Related Information 
  1273.  
  1274.           Data Structures 
  1275.  
  1276.               string (somcorba.h) 
  1277.  
  1278.           Functions 
  1279.  
  1280.               somVprintf 
  1281.               somPrefixLevel 
  1282.               somPrintf 
  1283.               SOMOutCharRoutine 
  1284.  
  1285.  Example Code 
  1286.  
  1287.                     #include <somobj.h>
  1288.                     somLPrintf(5, "The class name is %s.\n", _somGetClassName(obj));
  1289.  
  1290.  
  1291. ΓòÉΓòÉΓòÉ 2.17. somMainProgram ΓòÉΓòÉΓòÉ
  1292.  
  1293. somMainProgram This function performs SOM initialization on behalf of a new 
  1294. program. 
  1295.  
  1296.  Syntax 
  1297.  
  1298.                     SOMClassMgr * somMainProgram ()
  1299.  
  1300.  Parameters 
  1301.  
  1302.                     None. 
  1303.  
  1304.  Returns 
  1305.  
  1306.           rc (SOMClassMgr *) 
  1307.                     A pointer to the SOMClassMgr object. 
  1308.  
  1309.  Remarks 
  1310.  
  1311.           This function informs SOM about the beginning of a new thread of 
  1312.           execution (called a task on Windows). The SOM Kernel then performs 
  1313.           any needed initialization, including the deferred execution of the 
  1314.           SOMInitModule functions found in statically-loaded class libraries. 
  1315.           This function must appear near the beginning of all Windows main 
  1316.           programs, and may also be used in AIX or OS/2 programs. When used, it 
  1317.           supersedes any need to call the somEnvironmentNew function. 
  1318.  
  1319.           A convenience macro, SOM_MainProgram, which combines the execution of 
  1320.           this function with the scheduling of the somEnvironmentEnd function 
  1321.           during normal program termination, is available for C and C++ 
  1322.           programmers. 
  1323.  
  1324.  Related Information 
  1325.  
  1326.           Functions 
  1327.  
  1328.               somEnvironmentNew 
  1329.               somEnvironmentEnd 
  1330.  
  1331.           Macros 
  1332.  
  1333.               SOM_MainProgram 
  1334.               SOM_ClassLibrary 
  1335.  
  1336.  
  1337. ΓòÉΓòÉΓòÉ 2.18. somParentNumResolve ΓòÉΓòÉΓòÉ
  1338.  
  1339. somParentNumResolve 
  1340.  
  1341. This function obtains a pointer to a procedure that implements a method, given 
  1342. a list of method tables. 
  1343.  
  1344.  Syntax 
  1345.  
  1346.                     somMethodPtr somParentNumResolve (somMethodTabs parentMtab, int parentNum,
  1347.                                         somMToken mToken)
  1348.  
  1349.  Parameters 
  1350.  
  1351.           parentMtab (somMethodTabs) 
  1352.                     A list of method tables for the parents of the class being 
  1353.                     implemented. The SOM API specifies that the list of parent 
  1354.                     method tables for a given class be stored in the auxiliary 
  1355.                     class data structure of the class, in the parentMtab 
  1356.                     component. Thus, for the class "XYZ", the parent method 
  1357.                     table list is found in location XYZCClassData.parentMtab. 
  1358.                     Parent method table lists are available from class objects 
  1359.                     via the method call somGetPClsMtabs. 
  1360.  
  1361.           parentNum (int) 
  1362.                     The position of the parent for which the method is to be 
  1363.                     resolved. The order of a class's parents is determined by 
  1364.                     the order in which they are specified in the interface 
  1365.                     statement for the class. (The first parent is number 1.) 
  1366.  
  1367.           mToken (somMToken) 
  1368.                     The method token for the method to be resolved. The SOM API 
  1369.                     requires that if the class "XYZ" introduces the static 
  1370.                     method "foo", then the method token for "foo" is found in 
  1371.                     the class data structure for "XYZ" (called XYZClassData) in 
  1372.                     the structure member named "foo" (i.e., at 
  1373.                     XYZClassData.foo). Method tokens can also be obtained using 
  1374.                     the somGetMethodToken method. 
  1375.  
  1376.  Returns 
  1377.  
  1378.           rc (somMethodPtr) 
  1379.  
  1380.                     A pointer to a somMethodProc (procedure) that implements 
  1381.                     the specified method, selected from the specified method 
  1382.                     table. 
  1383.  
  1384.  Remarks 
  1385.  
  1386.           This function is used to make parent method calls by the C and C++ 
  1387.           language implementation bindings. The somParentNumResolve function 
  1388.           returns a pointer to a procedure for performing the specified method. 
  1389.           This pointer is selected from the specified method table, which is 
  1390.           intended to be the method table corresponding to a parent class. 
  1391.  
  1392.           For C and C++ programmers, the implementation bindings for SOM 
  1393.           classes provide convenient macros for making parent method calls (the 
  1394.           "parent_" macros). 
  1395.  
  1396.  Related Information 
  1397.  
  1398.           Data Structures 
  1399.  
  1400.               Data Structures 
  1401.               somMethodPtr(sombtype.h) 
  1402.               somMethodTabs(somapi.h) 
  1403.               somMToken (somapi.h) 
  1404.  
  1405.           Functions 
  1406.  
  1407.               somResolveByName 
  1408.               somResolve 
  1409.               somParentNumResolve 
  1410.               somClassResolve 
  1411.  
  1412.           Methods 
  1413.  
  1414.               somGetPClsMtab 
  1415.               somGetPClsMtabs 
  1416.               somGetMethodToken 
  1417.  
  1418.           Macros 
  1419.  
  1420.               SOM_ParentNumResolve 
  1421.               SOM_Resolve 
  1422.               SOM_ResolveNoCheck 
  1423.  
  1424.  Example Code 
  1425.  
  1426.                     // SOM IDL for class A and class B
  1427.                     #include <somobj.h>
  1428.                     module spnrExample {
  1429.                       interface A : SOMObject  { void foo();
  1430.                     implementation {callstyle=oidl; }; };
  1431.                       interface B : A  {  implementation { foo: override; }; };
  1432.                     };
  1433.  
  1434.                     // Example C++ program to implement and test  module scrExample
  1435.                     #define SOM_Module_spnrexample_Source
  1436.                     #include <spnrExample.xih>
  1437.                     #include <stdio.h>
  1438.  
  1439.                     SOM_Scope void SOMLINK spnrExample_Afoo(spnrExample_A *somSelf);
  1440.                     {  printf("1\n"); }
  1441.  
  1442.                     SOM_Scope void SOMLINK spnrExample_Bfoo(spnrExample_B *somSelf);
  1443.                     { printf("2\n"); }
  1444.  
  1445.                     main()
  1446.                     {
  1447.                       spnrExample_B  *objPtr = new spnrExample_B;
  1448.  
  1449.                     // This prints  2
  1450.                     objPtr->foo();
  1451.  
  1452.                     // This prints 1
  1453.                        ((somTD_spnrExample_A_foo)
  1454.                     /* This method procedure expression cast is necessary */
  1455.                                somParentNumResolve(
  1456.                                         ,objPtr->somGetClass()->somGetPClsMtabs(),
  1457.                                         "1"
  1458.                                         spnrExample_AClassData.foo) // the foo method token
  1459.                                ) /* end of method procedure expression */
  1460.                                (objPtr); /* method arguments */
  1461.                     }
  1462.  
  1463.  
  1464. ΓòÉΓòÉΓòÉ 2.19. somParentResolve ΓòÉΓòÉΓòÉ
  1465.  
  1466. somParentResolve 
  1467.  
  1468. This function obtains a pointer to a procedure that implements a method, given 
  1469. a list of method tables. Obsolete but still supported. 
  1470.  
  1471.  Syntax 
  1472.  
  1473.                     somMethodPtr somParentResolve (somMethodTabs parentMtab,
  1474.                                       somToken mToken)
  1475.  
  1476.  Parameters 
  1477.  
  1478.           parentMtab (somMethodTabs) 
  1479.                     A list of parent method tables, the first of which is the 
  1480.                     method table for the parent class for which the method is 
  1481.                     to be resolved. The SOM API specifies that the list of 
  1482.                     parent method tables for a given class be stored in the 
  1483.                     auxiliary class data structure of the class, in the 
  1484.                     parentMtab component. Thus, for the class "XYZ", the parent 
  1485.                     method table list is found in location 
  1486.                     XYZCClassData.parentMtab. Parent method table lists are 
  1487.                     available from class objects via the method call 
  1488.                     somGetPClsMtabs. 
  1489.  
  1490.           mToken (somToken) 
  1491.                     The method token for the method to be resolved. The SOM API 
  1492.                     requires that if the class "XYZ" introduces the static 
  1493.                     method "foo", then the method token for "foo" is found in 
  1494.                     the class data structure for "XYZ" (called XYZClassData) in 
  1495.                     the structure member named "foo" (i.e., at 
  1496.                     XYZClassData.foo). Method tokens can also be obtained using 
  1497.                     the somGetMethodToken method. 
  1498.  
  1499.  Returns 
  1500.  
  1501.           rc (somMethodPtr) 
  1502.                     A pointer to the somMethodProc (procedure) that implements 
  1503.                     the specified method, selected from the first method table. 
  1504.  
  1505.  Remarks 
  1506.  
  1507.           This function is used by old, single-parent class binaries to make 
  1508.           parent method calls. The function is obsolete, but is still 
  1509.           supported. This function returns a pointer to the procedure that 
  1510.           implements the specified method. This pointer is selected from the 
  1511.           first method table in the parentMtab list. 
  1512.  
  1513.  Related Information 
  1514.  
  1515.           Data Structures somMethodPtr(sombtype.h) somMethodTabs (somapi.h) 
  1516.           somMToken(somapi.h) 
  1517.  
  1518.           Functions 
  1519.  
  1520.               somResolveByName 
  1521.               somResolve 
  1522.               somParentNumResolve 
  1523.               somClassResolve 
  1524.  
  1525.           Methods 
  1526.  
  1527.               somDispatch 
  1528.               somClassDispatch 
  1529.               somFindMethod 
  1530.               somFindMethodOk 
  1531.               somGetMethodToken 
  1532.  
  1533.           Macros 
  1534.  
  1535.               SOM_Resolve 
  1536.               SOM_ResolveNoCheck 
  1537.  
  1538.  
  1539. ΓòÉΓòÉΓòÉ 2.20. somPrefixLevel ΓòÉΓòÉΓòÉ
  1540.  
  1541. somPrefixLevel 
  1542.  
  1543. This function outputs blanks to prefix a line at the indicated level. 
  1544.  
  1545.  Syntax 
  1546.  
  1547.                     void somPrefixLevel (long level)
  1548.  
  1549.  Parameters 
  1550.  
  1551.           level (long) 
  1552.                     The level at which the next line of output is to start. 
  1553.  
  1554.  Returns 
  1555.  
  1556.           rc (void) 
  1557.  
  1558.  Remarks 
  1559.  
  1560.           This function outputs blanks (via the somPrintf function) to prefix 
  1561.           the next line of output at the indicated level. (The number of blanks 
  1562.           produces is 2*level.) This function is useful when overriding the 
  1563.           somDumpSelfInt method, which takes the level as an argument. 
  1564.  
  1565.  Related Information 
  1566.  
  1567.           Functions 
  1568.  
  1569.               somPrintf 
  1570.               somVprintf 
  1571.               somLPrintf 
  1572.               SOMOutCharRoutine 
  1573.  
  1574.  Example Code 
  1575.  
  1576.                     #include <somcls.h>
  1577.                     somPrefixLevel(5);
  1578.  
  1579.  
  1580. ΓòÉΓòÉΓòÉ 2.21. somPrintf ΓòÉΓòÉΓòÉ
  1581.  
  1582. somPrintf 
  1583.  
  1584. This function prints a formatted string in the manner of the C printf function. 
  1585.  
  1586.  Syntax 
  1587.  
  1588.                     long somPrintf (string fmt, . . .)
  1589.  
  1590.  Parameters 
  1591.  
  1592.           fmt (string) 
  1593.                     The format string to be output. 
  1594.  
  1595.           . . . 
  1596.                     The values to be substituted into the format string. 
  1597.  
  1598.  Returns 
  1599.  
  1600.           rc (long) 
  1601.  
  1602.                     Returns the number of characters written. 
  1603.  
  1604.  Remarks 
  1605.  
  1606.           This function prints a formatted string using function 
  1607.           SOMOutCharRoutine, in the same manner as the C printf function. The 
  1608.           implementation of SOMOutCharRoutine determines the destination of the 
  1609.           output, while the C printf function is always directed to stdout. 
  1610.           (The default output destination for SOMOutCharRoutine is stdout also, 
  1611.           but this can be modified by the user.) 
  1612.  
  1613.  Related Information 
  1614.  
  1615.           Functions 
  1616.  
  1617.               somVprintf 
  1618.               somPrefixLevel 
  1619.               somLPrintf 
  1620.               SOMOutCharRoutine 
  1621.  
  1622.  Example Code 
  1623.  
  1624.                     #include <somcls.h>
  1625.                     somPrintf("The class name is %s.\n", _somGetClassName(obj));
  1626.  
  1627.  
  1628. ΓòÉΓòÉΓòÉ 2.22. somRegisterId ΓòÉΓòÉΓòÉ
  1629.  
  1630. somRegisterId 
  1631.  
  1632. This function registers a SOM ID and determines whether or not it was 
  1633. previously registered. 
  1634.  
  1635.  Syntax 
  1636.  
  1637.                     int somRegisterId (somId id)
  1638.  
  1639.  Parameters 
  1640.  
  1641.           id (somId) 
  1642.  
  1643.  Returns 
  1644.  
  1645.           rc (int) 
  1646.  
  1647.                     0        Returns 0 if the ID is already registered. 
  1648.                     1        Returns 1 if the ID is not already registered. 
  1649.  
  1650.  Remarks 
  1651.  
  1652.           This function registers a SOM ID and converts it into an internal 
  1653.           representation. If the ID is already registered, this function 
  1654.           returns 0 and has no effect. Otherwise, this function returns 1. 
  1655.  
  1656.  Related Information 
  1657.  
  1658.           Data Structures 
  1659.  
  1660.               somId (sombtype.h). 
  1661.  
  1662.           Functions 
  1663.  
  1664.               somCheckId 
  1665.               somIdFromString 
  1666.               somStringFromId 
  1667.               somCompareIds 
  1668.               somTotalRegIds 
  1669.               somSetExpectedIds 
  1670.               somUniqueKey 
  1671.  
  1672.  Example Code 
  1673.  
  1674.                     #include <som.h>
  1675.                     static string s = "unregistered";
  1676.                     static somId sid = &s;
  1677.                     main()
  1678.                     {
  1679.                        somEnvironmentNew();
  1680.                        SOM_Test(somRegisterId(sid) == 1);
  1681.                        SOM_Test(somRegisterId(somIdFromString("registered")) == 0);
  1682.                     }
  1683.  
  1684.  
  1685. ΓòÉΓòÉΓòÉ 2.23. somResolve ΓòÉΓòÉΓòÉ
  1686.  
  1687. somResolve 
  1688.  
  1689. This function obtains a pointer to the procedure that implements a method for a 
  1690. particular SOM object. 
  1691.  
  1692.  Syntax 
  1693.  
  1694.                     somMethodPtr somResolve (SOMObject obj, somMToken mToken)
  1695.  
  1696.  Parameters 
  1697.  
  1698.           obj (SOMObject) 
  1699.                     A pointer to the object whose method procedure is required. 
  1700.  
  1701.           mToken (somMToken) 
  1702.                     The method token for the method to be resolved. The SOM API 
  1703.                     requires that if the class "XYZ" introduces the static 
  1704.                     method "foo", then the method token for "foo" is found in 
  1705.                     the class data structure for "XYZ" (called XYZClassData) in 
  1706.                     the structure member named "foo" (i.e., at 
  1707.                     XYZClassData.foo). Method tokens can also be obtained using 
  1708.                     the somGetMethodToken method. 
  1709.  
  1710.  Returns 
  1711.  
  1712.           rc (somMethodPtr) 
  1713.                     A pointer to the somMethodProc (procedure) that implements 
  1714.                     the specified method for the specified SOM object. 
  1715.  
  1716.  Remarks 
  1717.  
  1718.           This function returns a pointer to the procedure that implements the 
  1719.           specified method for the specified SOM object. This pointer can then 
  1720.           be used to invoke the method. The somResolve function can only be 
  1721.           used to obtain a method procedure for a static method (one declared 
  1722.           in an IDL or OIDL specification for a class); dynamic methods are not 
  1723.           supported by method tokens. 
  1724.  
  1725.           For C and C++ programmers, the SOM usage bindings for SOM classes 
  1726.           provide more convenient mechanisms for invoking methods. These 
  1727.           bindings use the SOM_Resolve and SOM_ResolveNoCheck macros, which 
  1728.           construct a method token expression from the class name and method 
  1729.           name, and call somResolve. 
  1730.  
  1731.  Related Information 
  1732.  
  1733.           Data Structures 
  1734.  
  1735.               somMethodPtr (sombtype.h) 
  1736.               somMToken (somapi.h) 
  1737.  
  1738.           Functions 
  1739.  
  1740.               somResolveByName 
  1741.               somParentResolve, 
  1742.               somParentNumResolve 
  1743.               somClassResolve 
  1744.  
  1745.           Methods 
  1746.  
  1747.               somDispatch 
  1748.               somClassDispatch 
  1749.               somFindMethod 
  1750.               somFindMethodOk 
  1751.               somGetMethodToken 
  1752.  
  1753.           Macros 
  1754.  
  1755.               SOM_Resolve 
  1756.               SOM_ResolveNoCheck 
  1757.  
  1758.  Example Code 
  1759.  
  1760.                     // SOM IDL for class A and class B
  1761.                     #include <somobj.idl>
  1762.                     module srExample {
  1763.                       interface A : SOMObject  { void foo();  implementation
  1764.                     { callstyle=oidl; }; };
  1765.                       interface B : A  {  implementation { foo: override; }; };
  1766.                     };
  1767.  
  1768.                     // Example C++ program to implement and test  module scrExample
  1769.                     #define SOM_Module_srexample_Source
  1770.                     #include <srExample.ih>
  1771.                     #include <stdio.h>
  1772.  
  1773.                     SOM_Scope void SOMLINK srExample_Afoo(srExample_A *somSelf);
  1774.                     {  printf("1\n"); }
  1775.  
  1776.                     SOM_Scope void SOMLINK srExample_Bfoo(srExample_B *somSelf);
  1777.                     { printf("2\n"); }
  1778.  
  1779.                     main()
  1780.                     {
  1781.                       srExample_B  objPtr = srExample_BNew();
  1782.  
  1783.                     /* This prints  2 */
  1784.                        ((somTD_srExample_A_foo)
  1785.                     /* this method procedure expression cast is necessary */
  1786.                        somResolve(objPtr, srExample_AClassData.foo)
  1787.                        )     /* end of method procedure expression */
  1788.                         (objPtr);
  1789.                     }
  1790.  
  1791.  
  1792. ΓòÉΓòÉΓòÉ 2.24. somResolveByName ΓòÉΓòÉΓòÉ
  1793.  
  1794. somResolveByName 
  1795.  
  1796. This function obtains a pointer to the procedure that implements a method for a 
  1797. particular SOM object. 
  1798.  
  1799.  Syntax 
  1800.  
  1801.                     somMethodPtr somResolveByName (SOMObject obj, string methodName)
  1802.  
  1803.  Parameters 
  1804.  
  1805.           obj (SOMObject) 
  1806.                     A pointer to the object whose method procedure is required. 
  1807.  
  1808.           methodName (string) 
  1809.                     A character string representing the name of the method to 
  1810.                     be resolved. 
  1811.  
  1812.  Returns 
  1813.  
  1814.           rc (somMethodPtr) 
  1815.  
  1816.                     A pointer to the somMethodProc (procedure) that implements 
  1817.                     the specified method for the specified SOM object. 
  1818.  
  1819.  Remarks 
  1820.  
  1821.           This function is used to obtain a pointer to the procedure that 
  1822.           implements the specified method for the specified SOM object. The 
  1823.           returned procedure pointer can then be used to invoke the method. The 
  1824.           C and C++ usage bindings use this function to support name-lookup 
  1825.           methods. 
  1826.  
  1827.           This function can be used for invoking dynamic methods. However, the 
  1828.           C and C++ usage bindings for SOM classes do not support dynamic 
  1829.           methods, thus typedefs necessary for the use of dynamic methods are 
  1830.           not available as with static methods. The function somApply provides 
  1831.           an alternative mechanism for invoking dynamic methods that avoids the 
  1832.           need for casting procedure pointers. 
  1833.  
  1834.           Assuming the static method "setSound," is introduced by the class 
  1835.           "Animal", the following example will correctly invoke this method on 
  1836.           an instance of "Animal" or one of its descendent classes. 
  1837.  
  1838.  Related Information 
  1839.  
  1840.           Data Structures 
  1841.  
  1842.               somMethodPtr (sombtype.h) 
  1843.               SOMObject (somobj.idl) 
  1844.               string (somcorba.h) 
  1845.  
  1846.           Functions 
  1847.  
  1848.               somResolve 
  1849.               somParentResolve 
  1850.               somParentNumResolve 
  1851.               somClassResolve 
  1852.  
  1853.           Methods 
  1854.  
  1855.               somDispatch 
  1856.               somClassDispatch 
  1857.               somFindMethod 
  1858.               somFindMethodOk 
  1859.  
  1860.           Macros 
  1861.  
  1862.               SOM_Resolve 
  1863.               SOM_ResolveNoCheck 
  1864.  
  1865.  Example Code 
  1866.  
  1867.                     #include <animal.h>
  1868.                     example(Animal myAnimal)
  1869.                     {
  1870.                     somTD_Animal_setSound
  1871.                        setSoundProc = somResolveByName(myAnimal, "setSound");
  1872.                     setSoundProc(myAnimal, "Roar!");
  1873.                     }
  1874.  
  1875.  
  1876. ΓòÉΓòÉΓòÉ 2.25. somSetException ΓòÉΓòÉΓòÉ
  1877.  
  1878. somSetException This function sets an exception value in an Environment 
  1879. structure. 
  1880.  
  1881.  Syntax 
  1882.  
  1883.                     void somSetException (Environment *env, exception_type major,
  1884.                                  string exceptionName, somToken params)
  1885.  
  1886.  Parameters 
  1887.  
  1888.           env (Environment *) 
  1889.                     A pointer to the Environment structure in which to set the 
  1890.                     exception. This value must be either NULL or a value 
  1891.                     formerly obtained from the function 
  1892.                     somGetGlobalEnvironment. 
  1893.  
  1894.           major (exception_type) 
  1895.                     major An integer representing the type of exception to set. 
  1896.  
  1897.           exceptionName (string) 
  1898.                     The qualified name of the exception to set. The SOM 
  1899.                     Compiler defines, in the header files it generates for an 
  1900.                     interface, a constant whose value is the qualified name of 
  1901.                     each exception defined within the interface. This constant 
  1902.                     has the name "ex_<exceptionName>", where <exceptionName> is 
  1903.                     the qualified (scoped) exception name. Where unambiguous, 
  1904.                     the usage bindings also define the short form 
  1905.                     "ex_<exceptionName>", where <exceptionName> is unqualified. 
  1906.  
  1907.           params (somToken) 
  1908.                     A pointer to an initialized exception structure value. No 
  1909.                     copy is made of this structure; hence, the caller cannot 
  1910.                     free it. The somExceptionFree function should be used to 
  1911.                     free the Environment structure that contains it. 
  1912.  
  1913.  Returns 
  1914.  
  1915.           rc (void) 
  1916.  
  1917.  Remarks 
  1918.  
  1919.           This function sets an exception value in an Environment structure. 
  1920.  
  1921.  Related Information 
  1922.  
  1923.           Data Structures 
  1924.  
  1925.               Environment 
  1926.               exception_type 
  1927.               string (somcorba.h) 
  1928.  
  1929.           Methods 
  1930.  
  1931.               somExceptionId 
  1932.               somExceptionValue 
  1933.               somExceptionFree 
  1934.               somGetGlobalEnvironment 
  1935.  
  1936.  Example Code 
  1937.  
  1938.                     /* IDL declaration of class X:  */
  1939.                     interface X : SOMObject {
  1940.                     exception OUCH {long code1; long code2; };
  1941.                     void foo(in long arg) raises (OUCH);
  1942.                     };
  1943.                     /* implementation of foo method */
  1944.                     SOM_Scope void SOMLINK foo(X somSelf, Environment *ev, long arg)
  1945.                     {
  1946.                     X_OUCH *exception_params; /* X_OUCH struct is defined
  1947.                                                         in X's usage bindings    */
  1948.  
  1949.                        if (arg > 5) /* then this is a very bad error */
  1950.                        {
  1951.                           exception_params = (X_OUCH*)SOM_Malloc(sizeof(X_OUCH));
  1952.                           exception_params->code1 = arg;
  1953.                           exception_params->code2 = arg-5;
  1954.                           somSetException(ev, USER_EXCEPTION, ex_X_OUCH,
  1955.                                               exception_params);
  1956.                           /* the Environment ev now contains an X_OUCH exception, with
  1957.                           * the specified exception_params struct. The constant
  1958.                           * ex_X_OUCH is defined in foo.h. Note that exception_params
  1959.                           *  must be malloced.
  1960.                           */
  1961.                           return;
  1962.                        }
  1963.                     ...
  1964.                     }
  1965.  
  1966.                     main()
  1967.                     {
  1968.                        Environment *ev;
  1969.                        X x;
  1970.  
  1971.                        somEnvironmentNew();
  1972.                        x = Xnew();
  1973.                        ev = somGetGlobalEnvironment();
  1974.                        X_foo(x, ev, 23);
  1975.                        if (ev->_major != NO_EXCEPTION) {
  1976.                        printf("foo exception = %s\n", somExceptionId(ev));
  1977.                        printf("code1 = %d\n",
  1978.                        ((X_OUCH*) somExceptionValue(ev))->code1);
  1979.                        /* finished handling exception. */
  1980.                        /* free the copied id and the original X_OUCH structure: */
  1981.                        somExceptionFree(ev);
  1982.                        }
  1983.                     ...
  1984.                     }
  1985.  
  1986.  
  1987. ΓòÉΓòÉΓòÉ 2.26. somSetExpectedIds ΓòÉΓòÉΓòÉ
  1988.  
  1989. somSetExpectedIds 
  1990.  
  1991. This function tells SOM how many unique SOM IDs a client program expects to 
  1992. use. 
  1993.  
  1994.  Syntax 
  1995.  
  1996.                     void somSetExpectedIds (unsigned long numIds)
  1997.  
  1998.  Parameters 
  1999.  
  2000.           numIds (unsigned long) 
  2001.                     The number of SOM IDs the client program expects to use. 
  2002.  
  2003.  Returns 
  2004.  
  2005.           rc (void) 
  2006.  
  2007.  Remarks 
  2008.  
  2009.           This function informs the SOM run-time environment how many unique 
  2010.           SOM IDs a client program expects to use during its execution. This 
  2011.           has the potential of slightly improving the program's space and time 
  2012.           efficiency, if the value specified is accurate. This function, if 
  2013.           used, must be called prior to any explicit or implicit invocation of 
  2014.           the somEnvironmentNew function to have any effect. 
  2015.  
  2016.  Related Information 
  2017.  
  2018.           Functions 
  2019.  
  2020.               somCheckId 
  2021.               somRegisterId 
  2022.               somIdFromString 
  2023.               somStringFromId 
  2024.               somCompareIds 
  2025.               somTotalRegIds 
  2026.               somUniqueKey 
  2027.  
  2028.  Example Code 
  2029.  
  2030.                     #include <som.h>
  2031.                     somSetExpectedIds(1000);
  2032.  
  2033.  
  2034. ΓòÉΓòÉΓòÉ 2.27. somSetOutChar ΓòÉΓòÉΓòÉ
  2035.  
  2036. somSetOutChar This function changes the behavior of the somPrintf function. 
  2037.  
  2038.  Syntax 
  2039.  
  2040.                     void somSetOutChar (somTD_SOMOutCharRoutine *outCharRtn)
  2041.  
  2042.  Parameters 
  2043.  
  2044.           outCharRtn (somTD_SOMOutCharRoutine *) 
  2045.                     A pointer to your routine that outputs a character in the 
  2046.                     way you want. 
  2047.  
  2048.  Returns 
  2049.  
  2050.           rc (void) 
  2051.  
  2052.  Remarks 
  2053.  
  2054.           This function is called to change the output character routine that 
  2055.           somPrintf invokes. By default, somPrintf invokes a character output 
  2056.           routine that goes to "stdout." 
  2057.  
  2058.           The execution of this function affects only the application (or 
  2059.           thread) in which it occurs. Thus, this function is normally preferred 
  2060.           over SOMOutCharRoutine for changing the output routine called by 
  2061.           somPrintf, since SOMOutCharRoutine remains in effect for subsequent 
  2062.           threads as well. 
  2063.  
  2064.           Some samples of this function can be found in the "somapi.h" header 
  2065.           file. 
  2066.  
  2067.  Related Information 
  2068.  
  2069.           Functions 
  2070.  
  2071.               somPrintf 
  2072.               SOMOutCharRoutine 
  2073.  
  2074.  
  2075. ΓòÉΓòÉΓòÉ 2.28. somStringFromId ΓòÉΓòÉΓòÉ
  2076.  
  2077. somStringFromId 
  2078.  
  2079. This function returns the string that a SOM ID represents. 
  2080.  
  2081.  Syntax 
  2082.  
  2083.                     string somStringFromId (somId id)
  2084.  
  2085.  Parameters 
  2086.  
  2087.           id (somId) 
  2088.                     The SOM ID for which the corresponding string is needed. 
  2089.  
  2090.  Returns 
  2091.  
  2092.           rc (string) 
  2093.  
  2094.                     Returns the string that the given SOM ID represents. 
  2095.  
  2096.  Remarks 
  2097.  
  2098.           This function returns the string that a given SOM ID represents. 
  2099.  
  2100.  Related Information 
  2101.  
  2102.           Data Structures 
  2103.  
  2104.               string (somcorba.h) 
  2105.               somid (sombtype.h) 
  2106.  
  2107.           Functions 
  2108.  
  2109.               somCheckId 
  2110.               somRegisterId 
  2111.               somIdFromString, 
  2112.               somCompareIds, 
  2113.               somTotalRegIds 
  2114.               somSetExpectedIds 
  2115.               somUniqueKey 
  2116.  
  2117.  
  2118. ΓòÉΓòÉΓòÉ 2.29. somTotalRegIds ΓòÉΓòÉΓòÉ
  2119.  
  2120. somTotalRegIds 
  2121.  
  2122. This function returns the total number of SOM IDs that have been registered. 
  2123.  
  2124.  Syntax 
  2125.  
  2126.                     unsigned long somTotalRegIds ()
  2127.  
  2128.  Parameters 
  2129.  
  2130.                     None. 
  2131.  
  2132.  Returns 
  2133.  
  2134.           rc (unsigned long) 
  2135.  
  2136.                     Returns the total number of SOM IDs that have been 
  2137.                     registered. 
  2138.  
  2139.  Remarks 
  2140.  
  2141.           This function returns the total number of SOM IDs that have been 
  2142.           registered so far. This value can be used as a parameter to the 
  2143.           somSetExpectedIds function to advise SOM about expected ID usage in 
  2144.           later executions of a client program. 
  2145.  
  2146.  Related Information 
  2147.  
  2148.           Functions 
  2149.  
  2150.               somCheckId 
  2151.               somRegisterId 
  2152.               somIdFromString 
  2153.               somStringFromId 
  2154.               somCompareIds 
  2155.               somSetExpectedIds 
  2156.               somUniqueKey 
  2157.  
  2158.  
  2159.  Example Code 
  2160.  
  2161.                     #include <som.h>
  2162.                     main()
  2163.                     { int i;
  2164.                       somId id;
  2165.                       somEnvironmentNew();
  2166.                       id = somIdFromString("abc")
  2167.                       i = somTotalRegIds();
  2168.                       id = somIdFromString("abc");
  2169.                       SOM_Test(i == somTotalRegIds);
  2170.                     }
  2171.  
  2172.  
  2173. ΓòÉΓòÉΓòÉ 2.30. somUniqueKey ΓòÉΓòÉΓòÉ
  2174.  
  2175. somUniqueKey 
  2176.  
  2177. This function returns the unique key associated with a SOM ID. 
  2178.  
  2179.  Syntax 
  2180.  
  2181.                     unsigned long somUniqueKey (somID id)
  2182.  
  2183.  Parameters 
  2184.  
  2185.           id (somID) 
  2186.                     The SOM ID for which the unique key is needed. An unsigned 
  2187.                     long representing the unique key of the specified SOM ID. 
  2188.  
  2189.  Returns 
  2190.  
  2191.           rc (unsigned long) 
  2192.                     An unsigned long representing the unique key of the 
  2193.                     specified SOM ID. 
  2194.  
  2195.  Remarks 
  2196.  
  2197.           This function returns the unique key associated with a SOM ID. The 
  2198.           unique key for a SOM ID is a number that uniquely represents the 
  2199.           string that the SOM ID represents. The unique key for a SOM ID is the 
  2200.           same as the unique key for another SOM ID only if the two SOM IDs 
  2201.           represent the same string. 
  2202.  
  2203.  Related Information 
  2204.  
  2205.           Data Structures 
  2206.  
  2207.               somId (sombtype.h) 
  2208.  
  2209.           Functions 
  2210.  
  2211.               somCheckId 
  2212.               somRegisterId 
  2213.               somIdFromString 
  2214.               somStringFromId 
  2215.               somCompareIds 
  2216.               somTotalRegIds 
  2217.               somSetExpectedIds 
  2218.  
  2219.  Example Code 
  2220.  
  2221.                     #include <som.h>
  2222.                     main()
  2223.                     {
  2224.                        unsigned long k1, k2;
  2225.                        k1 = somUniqueKey(somIdFromString("abc"));
  2226.                        k2 = somUniqueKey(somIdFromString("abc"));
  2227.                        SOM_Test(k1 == k2);
  2228.                     }
  2229.  
  2230.  
  2231. ΓòÉΓòÉΓòÉ 2.31. somVaBuf_add ΓòÉΓòÉΓòÉ
  2232.  
  2233. somVaBuf_add 
  2234.  
  2235. Adds an argument to the SOM buffer (somVaBuf) for variable arguments. 
  2236.  
  2237.  Syntax 
  2238.  
  2239.                     long somVaBuf_add (somVaBuf vb, char *arg, int type)
  2240.  
  2241.  Parameters 
  2242.  
  2243.           vb (somVaBuf) 
  2244.                     Value (somVaBuf) returned from somVaBuf_create function. 
  2245.  
  2246.           arg (char *) 
  2247.                     Pointer to the argument to be added to the va_list. 
  2248.  
  2249.           type (int) 
  2250.                     Argument type (TCKind). 
  2251.  
  2252.                     The following are the supported TCKind types: 
  2253.  
  2254.                         tk_short 
  2255.                         tk_ushort 
  2256.                         tk_long 
  2257.                         tk_ulong 
  2258.                         tk_float 
  2259.                         tk_double 
  2260.                         tk_char 
  2261.                         tk_boolean 
  2262.                         tk_octet 
  2263.                         tk_Typecode 
  2264.                         tk_enum 
  2265.                         tk_string 
  2266.                         tk_pointer 
  2267.  
  2268.  Returns 
  2269.  
  2270.           rc (long) 
  2271.  
  2272.                     If successful, a value of one is returned; otherwise, a 
  2273.                     value of zero is returned. 
  2274.  
  2275.  Remarks 
  2276.  
  2277.           This function adds the argument pointed to by arg to the va_list by 
  2278.           using type for the size. 
  2279.  
  2280.  Related Information 
  2281.  
  2282.           Functions 
  2283.  
  2284.               somVaBuf_create 
  2285.               somVaBuf_get_valist 
  2286.               somVaBuf_destroy 
  2287.               somvalistGetTarget 
  2288.               somvalistSetTarget 
  2289.  
  2290.  Example Code 
  2291.  
  2292.                     See function somVaBuf_create.
  2293.  
  2294.  
  2295. ΓòÉΓòÉΓòÉ 2.32. somVaBuf_create ΓòÉΓòÉΓòÉ
  2296.  
  2297. somVaBuf_create 
  2298.  
  2299. Creates a SOM buffer (somVaBuf) for variable arguments from which the va_list 
  2300. will be built. 
  2301.  
  2302.  Syntax 
  2303.  
  2304.                     somVaBuf somVaBuf_create (char *vb, int size)
  2305.  
  2306.  Parameters 
  2307.  
  2308.           vb (char *) 
  2309.                     Pointer to user-allocated memory or NULL. 
  2310.  
  2311.           size (int) 
  2312.                     Size of memory pointed at by vb, or else zero. 
  2313.  
  2314.  Returns 
  2315.  
  2316.           rc (somVaBuf) 
  2317.  
  2318.                     If successful, somVaBuf is returned; otherwise, a NULL 
  2319.                     value is returned. 
  2320.  
  2321.  Remarks 
  2322.  
  2323.           This function allocates, if necessary, and initializes a somVaBuf 
  2324.           data structure. Memory is allocated if: 
  2325.  
  2326.               The size parameter is less than the size of the somVaBuf 
  2327.                structure, 
  2328.  
  2329.               The size parameter is zero, or 
  2330.  
  2331.               The vb parameter is NULL. 
  2332.  
  2333.           Note:  Because the somVaBuf data structure is opaque, users cannot 
  2334.                  determine its size. Although this function accepts a 
  2335.                  user-allocated buffer, it is recommended that a NULL value be 
  2336.                  passed as the first argument. 
  2337.  
  2338.  Related Information 
  2339.  
  2340.           Functions 
  2341.  
  2342.               somVaBuf_add 
  2343.               somVaBuf_get_valist 
  2344.               somVaBuf_destroy 
  2345.               somvalistGetTarget 
  2346.               somvalistSetTarget 
  2347.  
  2348.  Example Code 
  2349.  
  2350.           C Example 
  2351.  
  2352.                     #include <somobj.h>
  2353.  
  2354.                     void f1(SOMObject obj, Environment *ev)
  2355.                     {
  2356.                             char *msg;
  2357.                             va_list start_val;
  2358.                             somVaBuf vb;
  2359.                             char *msg1 = "Good Morning";
  2360.  
  2361.                             vb = (somVaBuf)somVaBuf_create(NULL, 0);
  2362.                             somVaBuf_add(vb, (char *)&obj, tk_pointer);
  2363.                                                                 /* target for _set_msg */
  2364.                             somVaBuf_add(vb, (char *)&ev, tk_pointer);
  2365.                                                                       /* next argument */
  2366.                             somVaBuf_add(vb, (char *)&msg1, tk_pointer);
  2367.                                                                      /* final argument */
  2368.                             somVaBuf_get_valist(vb, &start_val);
  2369.  
  2370.                             /* dispatch _set_msg on object */
  2371.                             SOMObject_somDispatch(
  2372.                                     obj,       /* target for somDispatch */
  2373.                                     0,         /* says ignore dispatched method result */
  2374.                                     somIdFromString("_set_msg"), /* the somId for _set_msg */
  2375.                                     start_val); /* target and args for _set_msg */
  2376.  
  2377.                             /* dispatch _get_msg on obj:   */
  2378.                             /* Get a fresh copy of the va_list    */
  2379.                             somVaBuf_get_valist(vb, &start_val);
  2380.                             SOMObject_somDispatch(
  2381.                                     obj,
  2382.                                     (somToken *)&msg,
  2383.                                                /* address to store dispatched result */
  2384.                                     somIdFromString("_get_msg"),
  2385.                                     start_val); /* target and arguments for _get_msg */
  2386.                             printf("%s\n", msg);
  2387.                             somVaBuf_destroy(vb);
  2388.                     }
  2389.  
  2390.           C++ Example 
  2391.  
  2392.                     #include <somobj.h>
  2393.  
  2394.                     void f1(SOMObject obj, Environment *ev)
  2395.                     {
  2396.                             char *msg;
  2397.                             va_list start_val;
  2398.                             somVaBuf vb;
  2399.                             char *msg1 = "Good Morning";
  2400.  
  2401.                             vb = (somVaBuf)somVaBuf_create(NULL, 0);
  2402.                             somVaBuf_add(vb, (char *)&obj, tk_pointer);
  2403.                                                                     /* target for _set_msg */
  2404.                             somVaBuf_add(vb, (char *)&ev, tk_pointer);
  2405.                                                                           /* next argument */
  2406.                             somVaBuf_add(vb, (char *)&msg1, tk_pointer);
  2407.                                                                          /* final argument */
  2408.                             somVaBuf_get_valist(vb, &start_val);
  2409.  
  2410.                             /* dispatch _set_msg on obj: */
  2411.                             obj->SOMObject_somDispatch(
  2412.                                     0,         /* says ignore the dispatched method result */
  2413.                                     somIdFromString("_set_msg"), /* the somId for _set_msg */
  2414.                                     start_val);   /* the target and arguments for _set_msg */
  2415.  
  2416.                             /* dispatch _get_msg on obj:   */
  2417.                             /* Get a fresh copy of the va_list    */
  2418.                             somVaBuf_get_valist(vb, &start_val);
  2419.                             obj->SOMObject_somDispatch(
  2420.                                     (somToken *)&msg,
  2421.                                                /* address to hold dispatched method result */
  2422.                                     somIdFromString("_get_msg"),
  2423.                                     start_val);   /* the target and arguments for _get_msg */
  2424.                             printf("%s\n", msg);
  2425.                             somVaBuf_destroy(vb);
  2426.                     }
  2427.  
  2428.  
  2429. ΓòÉΓòÉΓòÉ 2.33. somVaBuf_destroy ΓòÉΓòÉΓòÉ
  2430.  
  2431. somVaBuf_destroy 
  2432.  
  2433. Releases the SOM buffer (somVaBuf) and its associated va_list. 
  2434.  
  2435.  Syntax 
  2436.  
  2437.                     void somVaBuf_destroy (somVaBuf vb)
  2438.  
  2439.  Parameters 
  2440.  
  2441.           vb (somVaBuf) 
  2442.                     Value (somVaBuf) returned from somVaBuf_create function. 
  2443.  
  2444.  Returns 
  2445.  
  2446.           rc (void) 
  2447.  
  2448.  Remarks 
  2449.  
  2450.           If somVaBuf was allocated by the somVaBuf_create function, the memory 
  2451.           will be deallocated. 
  2452.  
  2453.  Related Information 
  2454.  
  2455.           Functions 
  2456.  
  2457.               somVaBuf_create 
  2458.               somVaBuf_add 
  2459.               somVaBuf_get_valist 
  2460.               somvalistGetTarget 
  2461.               somvalistSetTarget 
  2462.  
  2463.  Example Code 
  2464.  
  2465.                     See function somVaBuf_create.
  2466.  
  2467.  
  2468. ΓòÉΓòÉΓòÉ 2.34. somVaBuf_get_valist ΓòÉΓòÉΓòÉ
  2469.  
  2470. somVaBuf_get_valist 
  2471.  
  2472. Initializes a va_list from the SOM buffer (somVaBuf). 
  2473.  
  2474.  Syntax 
  2475.  
  2476.                     void somVaBuf_get_valist (somVaBuf vb, va_list *ap)
  2477.  
  2478.  Parameters 
  2479.  
  2480.           vb (somVaBuf) 
  2481.                     Value (somVaBuf) returned from somVaBuf_create function. 
  2482.  
  2483.           ap (va_list *) 
  2484.                     Pointer to a va_list. 
  2485.  
  2486.  Returns 
  2487.  
  2488.           rc (void) 
  2489.  
  2490.                     None. The user's va_list has been initialized from the 
  2491.                     va_list in somVaBuf. 
  2492.  
  2493.  Remarks 
  2494.  
  2495.           This function copies the va_list in the somVaBuf structure to the 
  2496.           passed va_list. 
  2497.  
  2498.  Related Information 
  2499.  
  2500.           Functions 
  2501.  
  2502.               somVaBuf_create 
  2503.               somVaBuf_add 
  2504.               somVaBuf_destroy 
  2505.               somvalistGetTarget 
  2506.               somvalistSetTarget 
  2507.  
  2508.  Example Code 
  2509.  
  2510.                     See function somVaBuf_create.
  2511.  
  2512.  
  2513. ΓòÉΓòÉΓòÉ 2.35. somvalistGetTarget ΓòÉΓòÉΓòÉ
  2514.  
  2515. somvalistGetTarget 
  2516.  
  2517. Gets the first scalar value from a va_list without other side effects. 
  2518.  
  2519.  Syntax 
  2520.  
  2521.                     unsigned long somvalistGetTarget (va_list ap)
  2522.  
  2523.  Parameters 
  2524.  
  2525.           ap (va_list) 
  2526.                     The va_list from which to get the value. 
  2527.  
  2528.  Returns 
  2529.  
  2530.           rc (unsigned long) 
  2531.  
  2532.                     Scalar value from the va_list. 
  2533.  
  2534.  Remarks 
  2535.  
  2536.           Returns the first scalar value from the va_list without other side 
  2537.           effects. 
  2538.  
  2539.  Related Information 
  2540.  
  2541.           Functions 
  2542.  
  2543.               somVaBuf_create 
  2544.               somVaBuf_add 
  2545.               somVaBuf_get_valist 
  2546.               somVaBuf_destroy 
  2547.               somvalistSetTarget 
  2548.  
  2549.  Example Code 
  2550.  
  2551.                     va_list start_val;
  2552.                     somVaBuf vb;
  2553.                     unsigned long first;
  2554.  
  2555.                     vb = (somVaBuf)somVaBuf_create(NULL, 0);
  2556.                     ...
  2557.                     first = somvalistGetTarget(start_val);
  2558.                     ...
  2559.                     somvalistSetTarget(start_val, first);
  2560.  
  2561.  
  2562. ΓòÉΓòÉΓòÉ 2.36. somvalistSetTarget ΓòÉΓòÉΓòÉ
  2563.  
  2564. somvalistSetTarget 
  2565.  
  2566. Modifies the va_list without other side effects. 
  2567.  
  2568.  Syntax 
  2569.  
  2570.                     unsigned long somvalistSetTarget (va_list ap, unsigned long val)
  2571.  
  2572.  Parameters 
  2573.  
  2574.           ap (va_list) 
  2575.                     The va_list to modify. 
  2576.  
  2577.           val (unsigned long) 
  2578.                     Value to set in the first scalar slot. 
  2579.  
  2580.  Returns 
  2581.  
  2582.           rc (unsigned long) 
  2583.  
  2584.                     None. 
  2585.  
  2586.  Remarks 
  2587.  
  2588.           The somvalistSetTarget function replaces the first scalar value on 
  2589.           the va_list with the value val that is passed in the call without any 
  2590.           other side effects. 
  2591.  
  2592.  Related Information 
  2593.  
  2594.           Functions 
  2595.  
  2596.               somVaBuf_create 
  2597.               somVaBuf_add 
  2598.               somVaBuf_get_valist 
  2599.               somVaBuf_destroy 
  2600.               somvalistGetTarget 
  2601.  
  2602.  Example Code 
  2603.  
  2604.                     va_list start_val;
  2605.                     somVaBuf vb;
  2606.                     unsigned long first;
  2607.  
  2608.                     vb = (somVaBuf)somVaBuf_create(NULL, 0);
  2609.                     ...
  2610.                     first = somvalistGetTarget(start_val);
  2611.                     ...
  2612.                     somvalistSetTarget(start_val, first);
  2613.  
  2614.  
  2615. ΓòÉΓòÉΓòÉ 2.37. somVprintf ΓòÉΓòÉΓòÉ
  2616.  
  2617. somVprintf 
  2618.  
  2619. This function prints a formatted string in the manner of the C vprintf 
  2620. function. 
  2621.  
  2622.  Syntax 
  2623.  
  2624.                     long somVprintf (string fmt, va_list ap)
  2625.  
  2626.  Parameters 
  2627.  
  2628.           fmt (string) 
  2629.                     The format string to be output. 
  2630.  
  2631.           ap (va_list) 
  2632.                     A va_list representing the values to be substituted into 
  2633.                     the format string. 
  2634.  
  2635.  Returns 
  2636.  
  2637.           rc (long) 
  2638.  
  2639.                     Returns the number of characters written. 
  2640.  
  2641.  Remarks 
  2642.  
  2643.           This function prints a formatted string using SOMOutCharRoutine, in 
  2644.           the same manner as the C vprintf function. The implementation of 
  2645.           SOMOutCharRoutine determines the destination of the output, while the 
  2646.           C printf function is always directed to stdout. (The default output 
  2647.           destination for SOMOutCharRoutine is stdout also, but this can be 
  2648.           modified by the user.) 
  2649.  
  2650.  Related Information 
  2651.  
  2652.           Data Structures 
  2653.  
  2654.               string (somcorba.h) 
  2655.               va_list (stdarg.h) 
  2656.  
  2657.           Functions 
  2658.  
  2659.               somPrintf 
  2660.               somPrefixLevel 
  2661.               somLPrintf 
  2662.               SOMOutCharRoutine 
  2663.  
  2664.  Example Code 
  2665.  
  2666.                     #include <som.h>
  2667.                     main()
  2668.                     {
  2669.                        va_list args;
  2670.                        somVaBuf vb;
  2671.                        float f = 3.1415;
  2672.                        char c = 'a';
  2673.                        int one = 1;
  2674.                        char *msg = "This is a test";
  2675.  
  2676.                       somEnvironmentNew();  /* Init environment */
  2677.                        vb = (somVaBuf)somVaBuf_create(NULL, 0);
  2678.                        somVaBuf_add(vb, (char *)&one, tk_long);
  2679.                        somVaBuf_add(vb, (char *)&f, tk_float);
  2680.                        somVaBuf_add(vb, (char *)&c, tk_char);
  2681.                        somVaBuf_add(vb, (char *)&msg, tk_pointer);
  2682.                        somVaBuf_get_valist(vb, &args);
  2683.  
  2684.                        somVprintf("%d, %f, %c, %s\n", args);
  2685.                     }
  2686.  
  2687.  
  2688. ΓòÉΓòÉΓòÉ 2.38. SOMCalloc ΓòÉΓòÉΓòÉ
  2689.  
  2690. SOMCalloc 
  2691.  
  2692. This function allocates sufficient memory for an array of objects of a 
  2693. specified size. 
  2694.  
  2695.  Syntax 
  2696.  
  2697.                     somToken (*SomCalloc) (size_t num, size_t size)
  2698.  
  2699.  Parameters 
  2700.  
  2701.           num (size_t) 
  2702.                     The number of objects for which space is to be allocated. 
  2703.  
  2704.           size (size_t) 
  2705.                     The size of the objects for which space to is to be 
  2706.                     allocated. 
  2707.  
  2708.  Returns 
  2709.  
  2710.           rc (somToken) 
  2711.  
  2712.                     A pointer to the first byte of the allocated space. 
  2713.  
  2714.  Remarks 
  2715.  
  2716.           This function allocates an amount of memory equal to num*size 
  2717.           (sufficient memory for an array of num objects of size size). This 
  2718.           function has the same interface as the C calloc function. It performs 
  2719.           the same basic function as calloc with some supplemental error 
  2720.           checking. If an error occurs, the SOMError function is called. This 
  2721.           routine is replaceable by changing the value of the global variable 
  2722.           SOMCalloc. 
  2723.  
  2724.  Related Information 
  2725.  
  2726.           Data Structures 
  2727.  
  2728.               somToken (sombtype.h) 
  2729.  
  2730.           Functions 
  2731.  
  2732.               SOMMalloc 
  2733.               SOMRealloc 
  2734.               SOMFree 
  2735.  
  2736.  Example Code 
  2737.  
  2738.                     See function somVprintf.
  2739.  
  2740.  
  2741. ΓòÉΓòÉΓòÉ 2.39. somClassInitFuncName ΓòÉΓòÉΓòÉ
  2742.  
  2743. somClassInitFuncName 
  2744.  
  2745. This function returns the name of the function used to initialize classes in a 
  2746. DLL. 
  2747.  
  2748.  Syntax 
  2749.  
  2750.                     string (*somClassInitFuncName) ()
  2751.  
  2752.  Parameters 
  2753.  
  2754.                     None. 
  2755.  
  2756.  Returns 
  2757.  
  2758.           rc (string) 
  2759.  
  2760.                     Returns the name of the function that should be used to 
  2761.                     initialize classes in a DLL. 
  2762.  
  2763.  Remarks 
  2764.  
  2765.           This function is called by the SOM Class Manager to determine what 
  2766.           function to call to initialize the classes in a DLL. The default 
  2767.           version returns the string "SOMInitModule."  The function can be 
  2768.           replaced (so that the Class Manager will invoke a different function 
  2769.           to initialize classes in a DLL) by changing the value of the global 
  2770.           variable SOMClassInitFuncName. 
  2771.  
  2772.  Related Information 
  2773.  
  2774.           Data Structures 
  2775.  
  2776.               string (somcorba.h) 
  2777.  
  2778.           Functions 
  2779.  
  2780.               SOMLoadModule 
  2781.               SOMDeleteModule 
  2782.  
  2783.  Example Code 
  2784.  
  2785.                     #include <som.h>
  2786.                     string XYZFuncName() { return "XYZ"; }
  2787.                     main()
  2788.                     {
  2789.                        SOMClassInitFuncName = XYZFuncName;
  2790.                        ...
  2791.                     }
  2792.  
  2793.  
  2794. ΓòÉΓòÉΓòÉ 2.40. SOMDeleteModule ΓòÉΓòÉΓòÉ
  2795.  
  2796. SOMDeleteModule 
  2797.  
  2798. This function unloads a dynamically linked library (DLL). 
  2799.  
  2800.  Syntax 
  2801.  
  2802.                     int (*SOMDeleteModule) (somToken modHandle)
  2803.  
  2804.  Parameters 
  2805.  
  2806.           modHandle (somToken) 
  2807.                     The somToken for the DLL to be unloaded. This token is 
  2808.                     supplied by the SOMLoadModule function when it loads the 
  2809.                     DLL. 
  2810.  
  2811.  Returns 
  2812.  
  2813.           rc (int) 
  2814.  
  2815.                     0            Returns 0 if successful. 
  2816.                     code         Returns a non-zero system-specific error code 
  2817.                                  if not successful. 
  2818.  
  2819.  Remarks 
  2820.  
  2821.           This function unloads the specified dynamically linked library (DLL). 
  2822.           This routine is called by the SOM Class Manager to unload DLLs. This 
  2823.           function can be replaced (thus changing the way the Class Manager 
  2824.           unloads DLLS) by changing the value of the global variable 
  2825.           SOMDeleteModule. 
  2826.  
  2827.  Related Information 
  2828.  
  2829.           Data Structures 
  2830.  
  2831.               somToken (sombtype.h) 
  2832.  
  2833.           Functions 
  2834.  
  2835.               SOMLoadModule 
  2836.               SOMClassInitFuncName 
  2837.  
  2838.  
  2839. ΓòÉΓòÉΓòÉ 2.41. SOMError ΓòÉΓòÉΓòÉ
  2840.  
  2841. SOMError 
  2842.  
  2843. This functions handles an error condition. 
  2844.  
  2845.  Syntax 
  2846.  
  2847.                     void (*SOMError) (int errorCode, string fileName, int lineNum)
  2848.  
  2849.  Parameters 
  2850.  
  2851.           errorCode (int) 
  2852.                     An integer representing the error code of the error. 
  2853.  
  2854.           fileName (string) 
  2855.                     The name of the file in which the error occurred. 
  2856.  
  2857.           lineNum (int) 
  2858.                     The line number where the error occurred. 
  2859.  
  2860.  Returns 
  2861.  
  2862.           rc (void) 
  2863.  
  2864.  Remarks 
  2865.  
  2866.           This function inspects the specified error code and takes appropriate 
  2867.           action, depending on the severity of the error. The last digit of the 
  2868.           error code indicates whether the error is classified as SOM_Fatal 
  2869.           (9), SOM_Warn (2), or SOM_Ignore (1). The default implementation of 
  2870.           this function prints a message that includes the specified error 
  2871.           code, filename, and line number, and terminates the current process 
  2872.           if the error is classified as SOM_Fatal. The fileName and lineNum 
  2873.           arguments specify where the error occurred. This routine can be 
  2874.           replaced by changing the value of the global variable SOMError. 
  2875.  
  2876.           For C and C++ programmers, SOM defines a convenience macro, 
  2877.           SOM_Error, which invokes this function and supplies the last two 
  2878.           arguments. 
  2879.  
  2880.  Related Information 
  2881.  
  2882.           Macros 
  2883.  
  2884.               SOM_Test 
  2885.               SOM_TestC 
  2886.               SOM_WarnMsg 
  2887.               SOM_Assert 
  2888.               SOM_Expect 
  2889.               SOM_Error 
  2890.  
  2891.  
  2892. ΓòÉΓòÉΓòÉ 2.42. somFree ΓòÉΓòÉΓòÉ
  2893.  
  2894. somFree 
  2895.  
  2896. This function frees the specified block of memory. 
  2897.  
  2898.  Syntax 
  2899.  
  2900.                     void (*somFree) (somToken ptr)
  2901.  
  2902.  Parameters 
  2903.  
  2904.           ptr (somToken) 
  2905.                     A pointer to the block of storage to be freed. 
  2906.  
  2907.  Returns 
  2908.  
  2909.           rc (void) 
  2910.  
  2911.  Remarks 
  2912.  
  2913.           This function frees the block of memory pointed to by ptr. This 
  2914.           function should only be called with a pointer previously allocated by 
  2915.           SOMMalloc or SOMCalloc. This function has the same interface as the C 
  2916.           free function. It performs the same basic function as free with some 
  2917.           supplemental error checking. If an error occurs, the SOMError 
  2918.           function is called. This routine is replaceable by changing the value 
  2919.           of the global variable SOMFree. 
  2920.  
  2921.           To free an object (rather than a block of memory), use the somFree 
  2922.           method, rather than this function. 
  2923.  
  2924.  Related Information 
  2925.  
  2926.           Functions 
  2927.  
  2928.               SOMCalloc 
  2929.               SOMRealloc 
  2930.               SOMMalloc 
  2931.  
  2932.           Methods 
  2933.  
  2934.               somFree 
  2935.  
  2936.  Example Code 
  2937.  
  2938.                     #include <som.h>
  2939.                     main()
  2940.                     {
  2941.                        somToken ptr = SOMMalloc(20);
  2942.                        SOMFree(ptr);
  2943.                     }
  2944.  
  2945.  
  2946. ΓòÉΓòÉΓòÉ 2.43. SOMInitModule ΓòÉΓòÉΓòÉ
  2947.  
  2948. SOMInitModule This function invokes the class creation routines for the classes 
  2949. contained in an OS/2 or Windows class library (DLL). 
  2950.  
  2951.  Syntax 
  2952.  
  2953.                     void (*SOMInitModule) (long majorVersion, long minorVersion,
  2954.                                  string className)
  2955.  
  2956.  Parameters 
  2957.  
  2958.           majorVersion (long) 
  2959.                     The major version number of the class that was requested 
  2960.                     when the library was loaded. 
  2961.  
  2962.           minorVersion (long) 
  2963.                     The minor version number of the class that was requested 
  2964.                     when the library was loaded. 
  2965.  
  2966.           className (string) 
  2967.                     The name of the class that was requested when the library 
  2968.                     was loaded. 
  2969.  
  2970.  Returns 
  2971.  
  2972.           rc (void) 
  2973.  
  2974.  Remarks 
  2975.  
  2976.           On OS/2 or Windows, a class library (DLL) can contain the 
  2977.           implementations for multiple classes, all of which should be created 
  2978.           when the DLL is loaded. On OS/2, when loading a DLL, the SOM class 
  2979.           manager determines the name of a DLL initialization function, and if 
  2980.           the DLL exports a function of this name, the class manager invokes 
  2981.           that function (whose purpose is to create the classes in the DLL). 
  2982.           SOMInitModule is the default name for this DLL initialization 
  2983.           function. 
  2984.  
  2985.           On Windows, the SOM class manager does not call this function. It 
  2986.           must be called from the default Windows DLL initialization function, 
  2987.           LibMain. This call is made indirectly through the SOM_ClassLibrary 
  2988.           macro (see the Example). 
  2989.  
  2990.  Related Information 
  2991.  
  2992.           Functions 
  2993.  
  2994.               SOMClassInitFuncName 
  2995.  
  2996.           Methods 
  2997.  
  2998.               somGetInitFunction 
  2999.  
  3000.           Macros 
  3001.  
  3002.               SOM_ClassLibrary 
  3003.  
  3004.  Example Code 
  3005.  
  3006.                        #include "xyz.h"
  3007.                        #ifdef __IBMC__
  3008.                          #pragma linkage (SOMInitModule, system)
  3009.                        #endif
  3010.  
  3011.                        SOMEXTERN void  SOMLINK SOMInitModule (long majorVersion,
  3012.                                                  long minorVersion, string className)
  3013.                        {
  3014.                            SOM_IgnoreWarning (majorVersion);  /* This function makes  */
  3015.                            SOM_IgnoreWarning (minorVersion);  /* no use of the passed */
  3016.                            SOM_IgnoreWarning (className);     /* arguments.   */
  3017.                            xyzNewClass, (A_MajorVersion, A_MinorVersion);
  3018.                        }
  3019.  
  3020.           For Windows, also include the following function: 
  3021.  
  3022.                         #include <windows.h>
  3023.                         int CALLBACK LibMain (HINSTANCE inst,
  3024.                                               WORD ds,
  3025.                                               WORD Heapsize,
  3026.                                               LPSTR cmdLine)
  3027.                         {
  3028.                             SOM_IgnoreWarning (inst);
  3029.                             SOM_ignoreWarning (ds);
  3030.                             SOM_IgnoreWarning (heapSize);
  3031.                             SOM_IgnoreWarning (cmdLine);
  3032.  
  3033.                             SOM_ClassLibrary ("xyz.dll");
  3034.                             return 1;  /* Indicate success to loader */
  3035.                         }
  3036.  
  3037.  
  3038. ΓòÉΓòÉΓòÉ 2.44. SOMLoadModule ΓòÉΓòÉΓòÉ
  3039.  
  3040. SOMLoadModule 
  3041.  
  3042. This function loads the dynamically linked library (DLL) containing a SOM 
  3043. class. 
  3044.  
  3045.  Syntax 
  3046.  
  3047.                     int (*SOMLoadModule) (string className, string fileName, string functionName,
  3048.                                  int majorVersion, long minorVersion, somToken *modHandle)
  3049.  
  3050.  Parameters 
  3051.  
  3052.           className (string) 
  3053.                     The name of the class whose DLL is to be loaded. 
  3054.  
  3055.           fileName (string) 
  3056.                     The name of the DLL library file. This can be either a 
  3057.                     simple name or a fully-qualified pathname. 
  3058.  
  3059.           functionName (string) 
  3060.                     The name of the routine to be called after the DLL is 
  3061.                     loaded. The routine is responsible for creating a class 
  3062.                     object for each class in the DLL. Typically, this argument 
  3063.                     will have the value SOMInitModule, obtained from the 
  3064.                     SOMClassInitFuncName function. If no SOMInitModule entry 
  3065.                     exists in the DLL, the default version of this function 
  3066.                     looks for a routine named NewClass instead. If neither 
  3067.                     entry point is found, the default version of this function 
  3068.                     fails. 
  3069.  
  3070.           majorVersion (int) 
  3071.                     The expected major version number of the class, to be 
  3072.                     passed to the initialization routine of the DLL. 
  3073.  
  3074.           minorVersion (long) 
  3075.                     The expected minor version number of the class, to be 
  3076.                     passed to the initialization routine of the DLL. 
  3077.  
  3078.           modHandle (somToken *) 
  3079.                     The address where this function should place a token that 
  3080.                     can be subsequently used by the SOMDeleteModule routine to 
  3081.                     unload the DLL. 
  3082.  
  3083.  Returns 
  3084.  
  3085.           rc (int) 
  3086.  
  3087.                     0            Returns 0 if successful. 
  3088.                     code         Returns a non-zero system-specific error code 
  3089.                                  if not successful. 
  3090.  
  3091.  Remarks 
  3092.  
  3093.           This function loads the dynamically linked library (DLL) containing a 
  3094.           SOM class. This routine is called by the SOM Class Manager to load 
  3095.           DLLs. This function can be replaced (thus changing the way the Class 
  3096.           Manager loads DLLS) by changing the value of the global variable 
  3097.           SOMLoadModule. 
  3098.  
  3099.  Related Information 
  3100.  
  3101.           Functions 
  3102.  
  3103.               SOMDeleteModule 
  3104.               SOMClassInitFuncName 
  3105.  
  3106.  
  3107. ΓòÉΓòÉΓòÉ 2.45. SOMMalloc ΓòÉΓòÉΓòÉ
  3108.  
  3109. SOMMalloc 
  3110.  
  3111. This function allocates the specified amount of memory. 
  3112.  
  3113.  Syntax 
  3114.  
  3115.                     somToken (*SOMMalloc) (size_t size)
  3116.  
  3117.  Parameters 
  3118.  
  3119.           size (size_t) 
  3120.                     The amount of memory to be allocated, in bytes. 
  3121.  
  3122.  Returns 
  3123.  
  3124.           rc (somToken) 
  3125.                     A pointer to the first byte of the allocated space. 
  3126.  
  3127.  Remarks 
  3128.  
  3129.           This function allocates size bytes of memory. This function has the 
  3130.           same interface as the C malloc function. It performs the same basic 
  3131.           function as malloc with some supplemental error checking. If an error 
  3132.           occurs, the SOMError  function is called. This routine is replaceable 
  3133.           by changing the value of the global variable SOMMalloc. 
  3134.  
  3135.  Related Information 
  3136.  
  3137.           Functions 
  3138.  
  3139.               SOMCalloc 
  3140.               SOMRealloc 
  3141.               SOMFree 
  3142.  
  3143.  Example Code 
  3144.  
  3145.                     See function SOMFree.
  3146.  
  3147.  
  3148. ΓòÉΓòÉΓòÉ 2.46. SOMOutCharRoutine ΓòÉΓòÉΓòÉ
  3149.  
  3150. SOMOutCharRoutine 
  3151.  
  3152. This function prints a character. This function is replaceable. 
  3153.  
  3154.  Syntax 
  3155.  
  3156.                     int (*SOMOutCharRoutine) (char c)
  3157.  
  3158.  Parameters 
  3159.  
  3160.           c (char) 
  3161.                     The character to be output. 
  3162.  
  3163.  Returns 
  3164.  
  3165.           rc (int) 
  3166.  
  3167.                     0        Returns 0 if an error occurs. 
  3168.                     1        Returns 1 if no error occurs. 
  3169.  
  3170.  Remarks 
  3171.  
  3172.           This function is a replaceable character output routine. It is 
  3173.           invoked by SOM whenever a character is generated by one of the SOM 
  3174.           error-handling or debugging macros. The default implementation 
  3175.           outputs the specified character to stdout. To change the destination 
  3176.           of character output, store the address of a user-written character 
  3177.           output routine in global variable SOMOutCharRoutine. 
  3178.  
  3179.           Another function, somSetOutChar, may be preferred over the 
  3180.           SOMOutCharRoutine function. The somSetOutChar function enables each 
  3181.           application (or thread) to have a customized character output 
  3182.           routine. 
  3183.  
  3184.  Related Information 
  3185.  
  3186.           Functions 
  3187.  
  3188.               somVprintf 
  3189.               somPrefixLevel 
  3190.               somLPrintf 
  3191.               somPrinf 
  3192.               somSetOutChar 
  3193.  
  3194.  Example Code 
  3195.  
  3196.                     #include <som.h>
  3197.                     #pragma linkage(myCharacterOutputRoutine, system)
  3198.                     /* Define a replacement routine: */
  3199.                     int SOMLINK myCharacterOutputRoutine (char c)
  3200.                     {
  3201.                         (Customized code goes here)
  3202.                     }
  3203.                     ...
  3204.                     /* After the next stmt all output */
  3205.                     /* will be sent to the new routine */
  3206.                     SOMOutCharRoutine = myCharacterOutputRoutine;
  3207.  
  3208.  
  3209. ΓòÉΓòÉΓòÉ 2.47. SOMRealloc ΓòÉΓòÉΓòÉ
  3210.  
  3211. SOMRealloc This function changes the size of a previously allocated region of 
  3212. memory. 
  3213.  
  3214.  Syntax 
  3215.  
  3216.                     somToken (*SOMRealloc) (somToken ptr, size_t size)
  3217.  
  3218.  Parameters 
  3219.  
  3220.           ptr (somToken) 
  3221.                     A pointer to the previously allocated region of memory. If 
  3222.                     NULL, a new region of memory of size bytes is allocated. 
  3223.  
  3224.           size (size_t) 
  3225.                     The size in bytes for the re-allocated storage. If zero, 
  3226.                     the memory pointed to by ptr is freed. 
  3227.  
  3228.  Returns 
  3229.  
  3230.           rc (somToken) 
  3231.                     A pointer to the first byte of the re-allocated space. (A 
  3232.                     pointer is returned because the block of storage may need 
  3233.                     to be moved to increase its size.) 
  3234.  
  3235.  Remarks 
  3236.  
  3237.           The SOMRealloc function changes the size of the previously allocated 
  3238.           region of memory pointed to by ptr so that it contains size bytes. 
  3239.           The new size may be greater or less than the original size. The 
  3240.           SOMRealloc function has the same interface as the C realloc function. 
  3241.           It performs the same basic function as realloc with some supplemental 
  3242.           error checking. If an error occurs, the SOMError function is called. 
  3243.           This routine is replaceable by changing the value of the global 
  3244.           variable SOMRealloc. 
  3245.  
  3246.  Related Information 
  3247.  
  3248.           Functions: 
  3249.  
  3250.               SOMCalloc 
  3251.               SOMMalloc 
  3252.               SOMFree 
  3253.  
  3254.  
  3255. ΓòÉΓòÉΓòÉ 2.48. SOM_Assert ΓòÉΓòÉΓòÉ
  3256.  
  3257. SOM_Assert This macro asserts that a boolean condition is true. 
  3258.  
  3259.  Syntax 
  3260.  
  3261.                     void SOM_Assert (boolean condition, long errorCode)
  3262.  
  3263.  Parameters 
  3264.  
  3265.           condition (boolean) 
  3266.                     A boolean expression that is expected to be TRUE (nonzero). 
  3267.  
  3268.           errorCode (long) 
  3269.                     The integer error code for the error to be raised if 
  3270.                     condition is FALSE. 
  3271.  
  3272.  Returns 
  3273.  
  3274.           rc (void) 
  3275.  
  3276.  Remarks 
  3277.  
  3278.           The SOM_Assert macro is used to place boolean assertions in a 
  3279.           program: 
  3280.  
  3281.               If condition is FALSE, and errorCode  indicates a warning-level 
  3282.                error and SOM_WarnLevel is set to be greater than zero, then a 
  3283.                warning message is output. 
  3284.               If condition is FALSE and errorCode indicates a fatal error, an 
  3285.                error message is output and the process is terminated. 
  3286.               If condition is TRUE and SOM_AssertLevel is set to be greater 
  3287.                than zero, then an informational message is output. 
  3288.  
  3289.           External (Global) Data 
  3290.  
  3291.                        long SOM_WarnLevel;   /* default = 0 */
  3292.                        long SOM_AssertLevel; /* default 0 */
  3293.  
  3294.  Expansion 
  3295.  
  3296.           If condition is FALSE, and errorCode  indicates a warning-level error 
  3297.           and SOM_WarnLevel is set to be greater than zero, then a warning 
  3298.           message is output. If condition is FALSE and  errorCode indicates a 
  3299.           fatal error, an error message is output and the process is 
  3300.           terminated. If  condition is TRUE and SOM_AssertLevel is set to be 
  3301.           greater than zero, then an information message is output. 
  3302.  
  3303.  Related Information 
  3304.  
  3305.           Macros: 
  3306.  
  3307.               SOM_Expect 
  3308.               SOM_Test 
  3309.               SOM_TestC 
  3310.  
  3311.  Example Code 
  3312.  
  3313.                     #include <som.h>
  3314.                     main()
  3315.                     {
  3316.                        SOM_WarnLevel = 1;
  3317.                        SOM_Assert(2==2, 29);
  3318.                     {
  3319.  
  3320.  
  3321. ΓòÉΓòÉΓòÉ 2.49. SOM_ClassLibrary ΓòÉΓòÉΓòÉ
  3322.  
  3323. SOM_ClassLibrary This macro identifies the file name of the DLL for a SOM class 
  3324. library in a Windows LibMain function. 
  3325.  
  3326.  Syntax 
  3327.  
  3328.                     void SOM_ClassLibrary (string libname.dll)
  3329.  
  3330.  Parameters 
  3331.  
  3332.           libname.dll (string) 
  3333.                     The name of the file containing the DLL (as the name would 
  3334.                     appear in a Windows LoadLibrary call). 
  3335.  
  3336.  Returns 
  3337.  
  3338.           rc (void) 
  3339.                     None. 
  3340.  
  3341.  Remarks 
  3342.  
  3343.           Each Windows SOM class library must supply a Windows LibMain 
  3344.           function. In LibMain, this macro identifies both the actual file name 
  3345.           of the library as it would appear in a Windows LoadLibrary call and 
  3346.           the location of the library's SOMInitModule function. This 
  3347.           information is passed to the SOM Kernel, which in turn registers the 
  3348.           library and schedules the execution of the SOMInitModule function. 
  3349.           This macro can also be used in OS/2 class libraries within the 
  3350.           context of a DLL "init/term" function. 
  3351.  
  3352.           Typically, the SOM Kernel invokes the SOMInitModule function of each 
  3353.           statically loaded class library during the execution of the 
  3354.           somMainProgram function in the using application. For dynamically 
  3355.           loaded class libraries, SOMInitModule is invoked immediately upon 
  3356.           completion of the library's LibMain (or an OS/2 DLL "init/term") 
  3357.           function. 
  3358.  
  3359.           Because this macro expands to reference the SOMInitModule function, 
  3360.           either a declaration of the SOMInitModule function, or the function 
  3361.           itself, should precede the appearance of SOM_ClassLibrary in the 
  3362.           current compilation unit, as shown in the Example below). 
  3363.  
  3364.           The Example illustrates the use of the SOM_ClassLibrary macro in a 
  3365.           Windows LibMain function. 
  3366.  
  3367.  Related Information 
  3368.  
  3369.           Macros 
  3370.  
  3371.               SOM_MainProgram 
  3372.  
  3373.           Functions 
  3374.  
  3375.               somMainProgram 
  3376.  
  3377.  Example Code 
  3378.  
  3379.                     #include <som.h>
  3380.                     SOMEXTERN void SOMLINK SOMInitModule (long majorVersion,
  3381.                                                           long minorVersion,
  3382.                                                           string className);
  3383.  
  3384.                     #include <windows.h>
  3385.                     int CALLBACK LibMain (HINSTANCE inst,
  3386.                                           WORD ds,
  3387.                                           WORD Heapsize,
  3388.                                           LPSTR cmdLine)
  3389.                     {
  3390.                         SOM_IgnoreWarning (inst);
  3391.                         SOM_ignoreWarning (ds);
  3392.                         SOM_IgnoreWarning (heapSize);
  3393.                         SOM_IgnoreWarning (cmdLine);
  3394.  
  3395.                         SOM_ClassLibrary ("xyz.dll");
  3396.                         return 1;  /* Indicate success to loader */
  3397.                     }
  3398.  
  3399.  
  3400. ΓòÉΓòÉΓòÉ 2.50. SOM_CreateLocalEnvironment Macro ΓòÉΓòÉΓòÉ
  3401.  
  3402. SOM_CreateLocalEnvironment Macro 
  3403.  
  3404. This macro creates and initializes a local Environment structure. 
  3405.  
  3406.  Syntax 
  3407.  
  3408.                     Environment * SOM_CreateLocalEnvironment Macro ()
  3409.  
  3410.  Parameters 
  3411.  
  3412.                     None. 
  3413.  
  3414.  Returns 
  3415.  
  3416.           rc (Environment *) 
  3417.  
  3418.  Remarks 
  3419.  
  3420.           The SOM_CreateLocalEnvironment macro creates a local Environment 
  3421.           structure. This Environment structure can be passed to methods as the 
  3422.           Environment argument so that exception information can be returned 
  3423.           without affecting the global environment. 
  3424.  
  3425.  Expansion 
  3426.  
  3427.           The SOM_CreateLocalEnvironment expands to an expression of type 
  3428.           (Environment *). 
  3429.  
  3430.  Related Information 
  3431.  
  3432.           Data Structures: 
  3433.  
  3434.               Environment (somcorba.h) 
  3435.  
  3436.           Macros: 
  3437.  
  3438.               SOM_DestroyLocalEnvironment 
  3439.               SOM_InitEnvironment 
  3440.               SOM_UninitEnvironment 
  3441.  
  3442.           Functions: 
  3443.  
  3444.               somGetGlobalEnvironment 
  3445.  
  3446.  Example Code 
  3447.  
  3448.                     Environment *ev;
  3449.                     ev = SOM_CreateLocalEnvironment();
  3450.                     _myMethod(obj, ev);
  3451.                     ...
  3452.                     SOM_DestroyLocalEnvironment(ev);
  3453.  
  3454.  
  3455. ΓòÉΓòÉΓòÉ 2.51. SOM_DestroyLocalEnvironment ΓòÉΓòÉΓòÉ
  3456.  
  3457. SOM_DestroyLocalEnvironment 
  3458.  
  3459. This macro destroys a local Environment structure. 
  3460.  
  3461.  Syntax 
  3462.  
  3463.                     void SOM_DestroyLocalEnvironment (Environment *env)
  3464.  
  3465.  Parameters 
  3466.  
  3467.           env (Environment *) 
  3468.                     A pointer to the Environment structure to be discarded. 
  3469.  
  3470.  Returns 
  3471.  
  3472.           rc (void) 
  3473.  
  3474.  Remarks 
  3475.  
  3476.           The SOM_DestroyLocalEnvironment macro destroys a local Environment 
  3477.           structure, such as one created using the SOM_CreateLocalEnvironment 
  3478.           macro. 
  3479.  
  3480.  Related Information 
  3481.  
  3482.           Macros: 
  3483.  
  3484.               SOM_CreateLocalEnvironment 
  3485.               SOM_UninitEnvironment 
  3486.  
  3487.           Functions: 
  3488.  
  3489.               somExceptionFree 
  3490.  
  3491.  Example Code 
  3492.  
  3493.                     Environment *ev;
  3494.                     ev = SOM_CreateLocalEnvironment();
  3495.                     _myMethod(obj, ev);
  3496.                     ...
  3497.                     SOM_DestroyLocalEnvironment(ev);
  3498.  
  3499.  
  3500. ΓòÉΓòÉΓòÉ 2.52. SOM_Error ΓòÉΓòÉΓòÉ
  3501.  
  3502. SOM_Error 
  3503.  
  3504. This macro reports an error condition. 
  3505.  
  3506.  Syntax 
  3507.  
  3508.                     void SOM_Error (long errorCode)
  3509.  
  3510.  Parameters 
  3511.  
  3512.           errorCode (long) 
  3513.                     The integer error code for the error to be reported. 
  3514.  
  3515.  Returns 
  3516.  
  3517.           void (void) 
  3518.  
  3519.  Remarks 
  3520.  
  3521.           The SOM_Error macro invokes the SOMError error handling procedure 
  3522.           with the specified error code, supplying the filename and line number 
  3523.           where the macro was invoked. The default implementation of SOMError 
  3524.           outputs a message containing the error code, filename, and line 
  3525.           number. Additionally, if the last digit of the error code indicates a 
  3526.           serious error (that is, value SOM_Fatal), the process is terminated. 
  3527.  
  3528.  Related Information 
  3529.  
  3530.           Functions: 
  3531.  
  3532.               SOMError 
  3533.  
  3534.  
  3535. ΓòÉΓòÉΓòÉ 2.53. SOM_Expect ΓòÉΓòÉΓòÉ
  3536.  
  3537. SOM_Expect This macro asserts that a boolean condition is expected to be true. 
  3538.  
  3539.  Syntax 
  3540.  
  3541.                     void SOM_Expect (boolean condition)
  3542.  
  3543.  Parameters 
  3544.  
  3545.           condition (boolean) 
  3546.                     A boolean expression that is expected to be TRUE (nonzero). 
  3547.  
  3548.  Returns 
  3549.  
  3550.           rc (void) 
  3551.  
  3552.  Remarks 
  3553.  
  3554.           The SOM_Expect macro is used to place boolean assertions that are 
  3555.           expected to be true into a program: 
  3556.  
  3557.               If condition is FALSE and SOM_WarnLevel is set to be greater 
  3558.                than zero, then a warning message is output. 
  3559.  
  3560.               If condition is TRUE and SOM_AssertLevel is set to be greater 
  3561.                than zero, then an informational message is output. 
  3562.  
  3563.  Expansion 
  3564.  
  3565.           If condition is FALSE and SOM_WarnLevel is set to be greater than 
  3566.           zero, then a warning message is output. If condition is TRUE and 
  3567.           SOM_AssertLevel is set to be greater than zero, then an information 
  3568.           message is output. 
  3569.  
  3570.  Related Information 
  3571.  
  3572.           Macros: 
  3573.  
  3574.               SOM_Assert 
  3575.               SOM_Test 
  3576.               SOM_TestC 
  3577.  
  3578.  Example Code 
  3579.  
  3580.                     SOM_Expect(2==2);
  3581.  
  3582.  
  3583. ΓòÉΓòÉΓòÉ 2.54. SOM_GetClass ΓòÉΓòÉΓòÉ
  3584.  
  3585. SOM_GetClass This macro returns the class object of which a SOM object is an 
  3586. instance. 
  3587.  
  3588.  Syntax 
  3589.  
  3590.                     SOMClass SOM_GetClass (SOMObject objPtr)
  3591.  
  3592.  Parameters 
  3593.  
  3594.           objPtr (SOMObject) 
  3595.                     A pointer to the object whose class is needed. 
  3596.  
  3597.  Returns 
  3598.  
  3599.           rc (SOMClass) 
  3600.  
  3601.  Remarks 
  3602.  
  3603.           The SOM_GetClass macro returns the class object of which obj is an 
  3604.           instance. This is done without recourse to a method call on the 
  3605.           object. The somGetClass method introduced by SOMObject is also 
  3606.           intended to return the class of which an object is an instance, and 
  3607.           the default implementation provided for this method by SOMObject uses 
  3608.           the macro. 
  3609.  
  3610.           Important Note: It is generally recommended that the somGetClass 
  3611.           method call be used, since it cannot be known whether the class of an 
  3612.           object wishes to provide special handling when its address is 
  3613.           requested from an instance. But, there are (rare) situations where a 
  3614.           method call cannot be made, and this macro can then be used. If you 
  3615.           are unsure as to whether to use the method or the macro, you should 
  3616.           use the method. 
  3617.  
  3618.  Related Information 
  3619.  
  3620.           Methods: 
  3621.  
  3622.               somGetClass 
  3623.  
  3624.  Example Code 
  3625.  
  3626.                     #include <somcls.xh>
  3627.                     #include <animal.xh>
  3628.                     main()
  3629.                     {
  3630.                        Animal *a = new Animal;
  3631.                        SOMClass cls1 = SOM_GetClass(a);
  3632.                        SOMClass cls2 = a->somGetClass();
  3633.                        if (cls1 == cls2)
  3634.                           printf("macro and method for getClass the same for Animal\n");
  3635.                        else
  3636.                           printf("macro and method for getClass not same for Animal\n");
  3637.                     }
  3638.  
  3639.  
  3640. ΓòÉΓòÉΓòÉ 2.55. SOM_InitEnvironment ΓòÉΓòÉΓòÉ
  3641.  
  3642. SOM_InitEnvironment This macro initializes a local Environment structure. 
  3643.  
  3644.  Syntax 
  3645.  
  3646.                     void SOM_InitEnvironment (Environment *env)
  3647.  
  3648.  Parameters 
  3649.  
  3650.           env (Environment *) 
  3651.                     A pointer to the Environment structure to be initialized. 
  3652.  
  3653.  Returns 
  3654.  
  3655.           rc (void) 
  3656.  
  3657.  Remarks 
  3658.  
  3659.           The SOM_InitEnvironment macro initializes a locally declared 
  3660.           Environment structure. This Environment structure can then be passed 
  3661.           to methods as the Environment argument so that exception information 
  3662.           can be returned without affecting the global environment. 
  3663.  
  3664.  Expansion 
  3665.  
  3666.           The SOM_InitEnvironment initializes an Environment structure to zero. 
  3667.  
  3668.  Related Information 
  3669.  
  3670.           Macros: 
  3671.  
  3672.               SOM_DestroyLocalEnvironment 
  3673.               SOM_CreateLocalEnvironment 
  3674.               SOM_UninitEnvironment 
  3675.  
  3676.           Functions: 
  3677.  
  3678.               somGetGlobalEnvironment 
  3679.  
  3680.  Example Code 
  3681.  
  3682.                     Environment ev;
  3683.                     SOM_InitEnvironment(&ev);
  3684.                     _myMethod(obj, &ev);
  3685.                     ...
  3686.                     SOM_UninitEnvironment(&ev);
  3687.  
  3688.  
  3689. ΓòÉΓòÉΓòÉ 2.56. SOM_MainProgram ΓòÉΓòÉΓòÉ
  3690.  
  3691. SOM_MainProgram This macro identifies an application as a SOM program and 
  3692. registers an end-of-program exit procedure to release SOM resources when the 
  3693. application terminates. 
  3694.  
  3695.  Syntax 
  3696.  
  3697.                     SOM_MainProgram ()
  3698.  
  3699.  Parameters 
  3700.  
  3701.           None 
  3702.  
  3703.  Remarks 
  3704.  
  3705.           This macro should appear near the beginning of each Windows 
  3706.           application program that uses SOM or a SOM class library. It can also 
  3707.           be used in OS/2 or AIX programs but is not generally required on 
  3708.           these platforms. Any statically referenced SOM class libraries are 
  3709.           initialized during the execution of this macro, and an end-of-program 
  3710.           exit procedure is established to release SOM resources during normal 
  3711.           program termination. (This macro combines the execution of the C/C++ 
  3712.           "atexit" function with the SOM somMainProgram function and returns a 
  3713.           reference to the global SOMClassMgr object.) 
  3714.  
  3715.  Related Information 
  3716.  
  3717.           Functions 
  3718.  
  3719.               somMainProgram 
  3720.  
  3721.           Macros 
  3722.  
  3723.               SOM_ClassLibrary 
  3724.  
  3725.  Example Code 
  3726.  
  3727.                     #include <som.h>
  3728.                     #include <windows.h>
  3729.  
  3730.                     int PASCAL WinMain (HINSTANCE inst,
  3731.                                         WORD ds,
  3732.                                         WORD Heapsize,
  3733.                                         LPSTR cmdLine)
  3734.                     {
  3735.                         ...
  3736.                         SOM_MainProgram ();
  3737.                         ...
  3738.                         /* Rest of main program follows */
  3739.                     }
  3740.  
  3741.  
  3742. ΓòÉΓòÉΓòÉ 2.57. SOM_NoTrace ΓòÉΓòÉΓòÉ
  3743.  
  3744. SOM_NoTrace This macro is used to turn off method debugging. 
  3745.  
  3746.  Syntax 
  3747.  
  3748.                     SOM_NoTrace (<token> className, <token> methodName)
  3749.  
  3750.  Parameters 
  3751.  
  3752.           className (<token>) 
  3753.                     The name of the class for which tracing will be turned off, 
  3754.                     given as a simple token rather than as a quoted string. 
  3755.  
  3756.           methodName (<token>) 
  3757.                     The name of the method for which tracing will be turned 
  3758.                     off, given as a simple token rather than as a quoted 
  3759.                     string. 
  3760.  
  3761.  Remarks 
  3762.  
  3763.           The SOM_NoTrace macro is used to turn off method debugging. Within an 
  3764.           implementation file for a class, before #including the implementation 
  3765.           (.ih or .xih) header file for the class, #define the 
  3766.           <className>MethodDebug macro to be SOM_NoTrace. Then, 
  3767.           <className>MethodDebug will have no effect. 
  3768.  
  3769.  Expansion 
  3770.  
  3771.           The SOM_NoTrace macro has a null (empty) expansion. 
  3772.  
  3773.  Example Code 
  3774.  
  3775.                     #define AnimalMethodDebug(c,m) SOM_NoTrace(c,m)
  3776.                     #include <animal.ih>
  3777.                     /* Now AnimalMethodDebug does nothing */
  3778.  
  3779.  
  3780. ΓòÉΓòÉΓòÉ 2.58. SOM_ParentNumResolve ΓòÉΓòÉΓòÉ
  3781.  
  3782. SOM_ParentNumResolve This macro obtains a pointer to a method procedure from a 
  3783. list of method tables.  It is used by C and C++ implementation bindings to 
  3784. implement parent method calls. 
  3785.  
  3786.  Syntax 
  3787.  
  3788.                     SOM_ParentNumResolve ((<token> introClass, long parentNum,
  3789.                                  somMethodTab parentMtabs, <token> ) methodName)
  3790.  
  3791.  Parameters 
  3792.  
  3793.           introClass ((<token>) 
  3794.                     The name of the class that introduces methodName. This name 
  3795.                     should be given as a simple token, rather than a quoted 
  3796.                     string (for example, Animal. rather than "Animal"). 
  3797.  
  3798.           parentNum (long) 
  3799.                     The position of the desired parent. The first (leftmost) 
  3800.                     parent of a class has position 1. 
  3801.  
  3802.           parentMtabs (somMethodTab) 
  3803.                     A list of parent method tables acquired by invoking the 
  3804.                     somGetPClsMtabs method on a class object. 
  3805.  
  3806.           methodName (<token> )) 
  3807.                     The name of the method to be resolved. This name should be 
  3808.                     given as a simple token, rather than a quoted string (for 
  3809.                     example, setSound rather than "setSound"). 
  3810.  
  3811.  Remarks 
  3812.  
  3813.           This macro invokes the somParentNumResolve function to obtain a 
  3814.           pointer to the static method procedure that implements the specified 
  3815.           method for the specified parent. The method is specified by 
  3816.           indicating the introducing class, IntroClass, and the method name, 
  3817.           methodName. 
  3818.  
  3819.  Expansion 
  3820.  
  3821.           The expansion of the macro produces an expression that is 
  3822.           appropriately typed for application of the evaluated result to the 
  3823.           indicated method's arguments, as illustrated in the Example. 
  3824.  
  3825.  Related Information 
  3826.  
  3827.           Functions 
  3828.  
  3829.               somParentNumResolve 
  3830.  
  3831.           Methods 
  3832.  
  3833.               somGetPClsMtabs 
  3834.  
  3835.  Example Code 
  3836.  
  3837.                     #include <somcls.h>
  3838.  
  3839.                     main()
  3840.                     {
  3841.                      SOMClassMgr * cm = somEnvironmentNew();
  3842.                      somMethodTabs mList = _somGetPClsMtabs(_SOMClass);
  3843.                      SOM_ParentNumResolve(SOMObject, 1, mList, somDumpSelfInt)
  3844.                           (_SOMClass,1);
  3845.                     }
  3846.  
  3847.  
  3848. ΓòÉΓòÉΓòÉ 2.59. SOM_Resolve ΓòÉΓòÉΓòÉ
  3849.  
  3850. SOM_Resolve This macro obtains a pointer to a method procedure. 
  3851.  
  3852. Note:  For backward compatibility, this method does not take an Environment 
  3853. parameter. 
  3854.  
  3855.  Syntax 
  3856.  
  3857.                     RC SOM_Resolve (SOMObject objPtr, <token> className,
  3858.                               <token> methodName)
  3859.  
  3860.  Parameters 
  3861.  
  3862.           objPtr (SOMObject) 
  3863.                     A pointer to the object to which the resolved method 
  3864.                     procedure will be applied. 
  3865.  
  3866.           className (<token>) 
  3867.                     The name of the class that introduces methodName. This name 
  3868.                     should be given as a simple token, rather than a quoted 
  3869.                     string (for example, Animal rather than "Animal"). 
  3870.  
  3871.           methodName (<token>) 
  3872.                     The name of the method to be resolved. This name should be 
  3873.                     given as a simple token, rather than a quoted string (for 
  3874.                     example, setSound rather than "setSound"). 
  3875.  
  3876.  Returns 
  3877.  
  3878.           somMethod (RC) 
  3879.  
  3880.  Remarks 
  3881.  
  3882.           The SOM_Resolve macro invokes the somResolve function to obtain a 
  3883.           pointer to the static method procedure that implements the specified 
  3884.           method for the specified object. This pointer can be used for 
  3885.           efficient repeated casted method invocations on instances of the 
  3886.           class of the object on which the resolution is done, or instances of 
  3887.           subclasses of this class. The name of the class that introduces the 
  3888.           method and the name of the method must be known to use this macro. 
  3889.           Otherwise, use the somResolveByName, somFindMethod or somFindMethodOk 
  3890.           method. 
  3891.  
  3892.           The SOM_Resolve macro can only be used to obtain a method procedure 
  3893.           for a static method (one defined in the IDL specification for a 
  3894.           class); not a dynamic method. Unlike the SOM_ResolveNoCheck macro, 
  3895.           the SOM_Resolve macro performs several consistency checks on the 
  3896.           object pointed to by objPtr. 
  3897.  
  3898.  Expansion 
  3899.  
  3900.           The SOM_Resolve macro uses the className and methodName to construct 
  3901.           the method token for the specified method, then invokes the 
  3902.           somResolve function. Thus, the macro expands to an expression that 
  3903.           represents the entry-point address of the method procedure. This 
  3904.           value can be stored in a variable and used for subsequent invocations 
  3905.           of the method. 
  3906.  
  3907.  Related Information 
  3908.  
  3909.           Macros: 
  3910.  
  3911.               SOM_ResolveNoCheck 
  3912.  
  3913.           Functions: 
  3914.  
  3915.               somResolve 
  3916.               somClassResolve 
  3917.               somResolveByName 
  3918.  
  3919.           Methods: 
  3920.  
  3921.               somFindMethod 
  3922.               somFindMethodOk 
  3923.               somDispatch 
  3924.               somClassDispatch 
  3925.  
  3926.  Example Code 
  3927.  
  3928.                     Animal myObj = AnimalNew();
  3929.                     somMethodProc *procPtr;
  3930.                     procPtr = SOM_Resolve(myObj, Animal, setSound);
  3931.                     /* note that procPtr will need to be typecast when it is used */
  3932.  
  3933.  
  3934. ΓòÉΓòÉΓòÉ 2.60. SOM_ResolveNoCheck ΓòÉΓòÉΓòÉ
  3935.  
  3936. SOM_ResolveNoCheck This macro obtains a pointer to a method procedure, without 
  3937. doing consistency checks. 
  3938.  
  3939.  Syntax 
  3940.  
  3941.                     somMethodPtr SOM_ResolveNoCheck (SOMObject objPtr, <token> className,
  3942.                                         <token> methodName)
  3943.  
  3944.  Parameters 
  3945.  
  3946.           objPtr (SOMObject) 
  3947.                     A pointer to the object to which the resolved method 
  3948.                     procedure will be applied. 
  3949.  
  3950.           className (<token>) 
  3951.                     The name of the class that introduces methodName. This name 
  3952.                     should be given as a simple token, rather than a quoted 
  3953.                     string (for example, Animal rather than "Animal"). 
  3954.  
  3955.           methodName (<token>) 
  3956.                     The name of the method to be resolved. This name should be 
  3957.                     given as a simple token, rather than a quoted string (for 
  3958.                     example, setSound rather than "setSound"). 
  3959.  
  3960.  Returns 
  3961.  
  3962.           rc (somMethodPtr) 
  3963.  
  3964.  Remarks 
  3965.  
  3966.           The SOM_ResolveNoCheck macro invokes the somResolve function to 
  3967.           obtain a pointer to the method procedure that implements the 
  3968.           specified method for the specified object. This pointer can be used 
  3969.           for efficient repeated invocations of the same method on the same 
  3970.           type of objects. The name of the class that introduces the method and 
  3971.           the name of the method must be known at compile time. Otherwise, use 
  3972.           the somFindMethod or somFindMethodOk method. 
  3973.  
  3974.           The SOM_ResolveNoCheck macro can only be used to obtain a method 
  3975.           procedure for a static method (one defined in the IDL specification 
  3976.           for a class) and not a method added to a class at run time. Unlike 
  3977.           the SOM_Resolve macro, the SOM_ResolveNoCheck macro does not perform 
  3978.           any consistency checks on the object pointed to by objPtr. 
  3979.  
  3980.  Expansion 
  3981.  
  3982.           The SOM_ResolveNoCheck macro uses the className and methodName to 
  3983.           construct an expression whose value is the method token for the 
  3984.           specified method, then invokes the somResolve function. Thus, the 
  3985.           macro expands to an expression that represents the entry-point 
  3986.           address of the method procedure. This value can be stored in a 
  3987.           variable and used for subsequent invocations of the method. 
  3988.  
  3989.  Related Information 
  3990.  
  3991.           Macros: 
  3992.  
  3993.               SOM_Resolve 
  3994.  
  3995.           Functions: 
  3996.  
  3997.               somResolve 
  3998.               somClassResolve 
  3999.               somResolveByName 
  4000.  
  4001.           Methods: 
  4002.  
  4003.               somDispatch 
  4004.               somClassDispatch 
  4005.               somFindMethod 
  4006.               somFindMethodOk 
  4007.  
  4008.  Example Code 
  4009.  
  4010.                     Animal myObj = AnimalNew();
  4011.                     somMethodProc *procPtr;
  4012.                     procPtr = SOM_ResolveNoCheck(myObj, Animal, setSound)
  4013.  
  4014.  
  4015. ΓòÉΓòÉΓòÉ 2.61. SOM_SubstituteClass ΓòÉΓòÉΓòÉ
  4016.  
  4017. SOM_SubstituteClass This macro provides a convenience macro for invoking the 
  4018. somSubstituteClass method. 
  4019.  
  4020.  Syntax 
  4021.  
  4022.                     SOM_SubstituteClass (<token> oldClass, <token> newClass)
  4023.  
  4024.  Parameters 
  4025.  
  4026.           oldClass (<token>) 
  4027.                     The name of the class to be substituted, given as a simple 
  4028.                     token rather than a quoted string. 
  4029.  
  4030.           newClass (<token>) 
  4031.                     The name of the class that will replace oldClass, given as 
  4032.                     a simple token rather than a quoted string. 
  4033.  
  4034.  Remarks 
  4035.  
  4036.           The method somSubstituteClass requires existing class objects as 
  4037.           arguments. Therefore, this macro first assures that the classes named 
  4038.           oldClass and newClass exist, and then calls the method 
  4039.           somSubstituteClass with these class objects as arguments. 
  4040.  
  4041.  Related Information 
  4042.  
  4043.           Methods 
  4044.  
  4045.               somSubstituteClass 
  4046.  
  4047.  Example Code 
  4048.  
  4049.                     See the method somSubstituteClass.
  4050.  
  4051.  
  4052. ΓòÉΓòÉΓòÉ 2.62. SOM_Test ΓòÉΓòÉΓòÉ
  4053.  
  4054. SOM_Test This macro tests whether a boolean condition is true; if not, a fatal 
  4055. error is raised. 
  4056.  
  4057.  Syntax 
  4058.  
  4059.                     void SOM_Test (boolean expression)
  4060.  
  4061.  Parameters 
  4062.  
  4063.           expression (boolean) 
  4064.                     The boolean expression to test. 
  4065.  
  4066.  Returns 
  4067.  
  4068.           rc (void) 
  4069.  
  4070.  Remarks 
  4071.  
  4072.           The SOM_Test macro tests the specified boolean expression: 
  4073.  
  4074.               If the expression is TRUE and SOM_AssertLevel is set to a value 
  4075.                greater than zero, then an information message is output. 
  4076.  
  4077.               If the expression is FALSE, an error message is output and the 
  4078.                process is terminated. 
  4079.  
  4080.                Note:  The SOM_TestC macro is similar, except that it only 
  4081.                outputs a warning message in this situation. 
  4082.  
  4083.           External (Global) Data 
  4084.  
  4085.                        long SOM_AssertLevel;  /* default is 0 */
  4086.  
  4087.  Expansion 
  4088.  
  4089.           The SOM_Test macro tests the specified boolean expression. If the 
  4090.           expression is TRUE and SOM_AssertLevel is set to a value greater than 
  4091.           zero, then an information message is output. If the expression is 
  4092.           FALSE, an error message is output and the process is terminated. 
  4093.  
  4094.  Related Information 
  4095.  
  4096.           Macros: 
  4097.  
  4098.               SOM_Expect 
  4099.               SOM_Assert 
  4100.               SOM_TestC 
  4101.  
  4102.  Example Code 
  4103.  
  4104.                     #include <som.h>
  4105.                     main()
  4106.                     {
  4107.                        SOM_AssertLevel = 1;
  4108.                        SOM_Test(1=1);
  4109.                     }
  4110.  
  4111.  
  4112. ΓòÉΓòÉΓòÉ 2.63. SOM_TestC ΓòÉΓòÉΓòÉ
  4113.  
  4114. SOM_TestC This macro tests whether a boolean condition is true; if not, a 
  4115. warning message is output. 
  4116.  
  4117.  Syntax 
  4118.  
  4119.                     void SOM_TestC (boolean expression)
  4120.  
  4121.  Parameters 
  4122.  
  4123.           expression (boolean) 
  4124.                     The boolean expression to test. 
  4125.  
  4126.  Returns 
  4127.  
  4128.           rc (void) 
  4129.  
  4130.  Remarks 
  4131.  
  4132.           The SOM_TestC macro tests the specified boolean expression: 
  4133.  
  4134.               If the expression is TRUE and SOM_AssertLevel is set to a value 
  4135.                greater than zero, then an information message is output. 
  4136.  
  4137.               If the expression is FALSE and SOM_WarnLevel is set to a value 
  4138.                greater than zero, then a warning message is output. 
  4139.  
  4140.                Note:  The SOM_Test macro is similar, except that it raises a 
  4141.                fatal error in this situation. 
  4142.  
  4143.           External (Global) Data 
  4144.  
  4145.                        long SOM_AssertLevel;  /* default is 0 */
  4146.                        long SOM_WarnLevel;    /* default is 0 */
  4147.  
  4148.  Expansion 
  4149.  
  4150.           The SOM_TestC macro tests the specified boolean expression. If the 
  4151.           expression is TRUE and SOM_AssertLevel is set to a value greater than 
  4152.           zero, then an information message is output. If the expression is 
  4153.           FALSE and SOM_WarnLevel is set to a value greater than zero, a 
  4154.           warning message is output. 
  4155.  
  4156.  Related Information 
  4157.  
  4158.           Macros: 
  4159.  
  4160.               SOM_Expect 
  4161.               SOM_Assert 
  4162.               SOM_Test 
  4163.  
  4164.  Example Code 
  4165.  
  4166.                     #include <som.h>
  4167.                     main()
  4168.                     {
  4169.                        SOM_WarnLevel = 1;
  4170.                        SOM_TestC(1=1);
  4171.                     }
  4172.  
  4173.  
  4174. ΓòÉΓòÉΓòÉ 2.64. SOM_UninitEnvironment ΓòÉΓòÉΓòÉ
  4175.  
  4176. SOM_UninitEnvironment This macro uninitializes a local Environment structure. 
  4177.  
  4178.  Syntax 
  4179.  
  4180.                     void SOM_UninitEnvironment (Environment *env)
  4181.  
  4182.  Parameters 
  4183.  
  4184.           env (Environment *) 
  4185.  
  4186.  Returns 
  4187.  
  4188.           rc (void) 
  4189.  
  4190.  Remarks 
  4191.  
  4192.           The SOM_UninitEnvironment macro uninitializes a locally declared 
  4193.           Environment structure. 
  4194.  
  4195.  Expansion 
  4196.  
  4197.           The SOM_UninitEnvironment invokes the somExceptionFree function on 
  4198.           the specified Environment structure. 
  4199.  
  4200.  Related Information 
  4201.  
  4202.           Macros: 
  4203.  
  4204.               SOM_DestroyLocalEnvironment 
  4205.               SOM_InitEnvironment 
  4206.  
  4207.  Example Code 
  4208.  
  4209.                     Environment ev;
  4210.                     SOM_InitEnvironment(&ev);
  4211.                     _myMethod(obj, &ev);
  4212.                     ...
  4213.                     SOM_UninitEnvironment(&ev);
  4214.  
  4215.  
  4216. ΓòÉΓòÉΓòÉ 2.65. SOM_WarnMsg ΓòÉΓòÉΓòÉ
  4217.  
  4218. SOM_WarnMsg This macro reports a warning message. 
  4219.  
  4220.  Syntax 
  4221.  
  4222.                     void SOM_WarnMsg (string msg)
  4223.  
  4224.  Parameters 
  4225.  
  4226.           msg (string) 
  4227.                     The warning message to be output. 
  4228.  
  4229.  Returns 
  4230.  
  4231.           rc (void) 
  4232.  
  4233.  Remarks 
  4234.  
  4235.           If SOM_WarnLevel is set to a value greater than zero, the SOM_WarnMsg 
  4236.           macro prints the specified message, along with the filename and line 
  4237.           number where the macro was invoked. 
  4238.  
  4239.  Expansion 
  4240.  
  4241.           If SOM_WarnLevel is set to a value greater than zero, the SOM_WarnMsg 
  4242.           macro prints the specified message, along with the filename and line 
  4243.           number where the macro was invoked. 
  4244.  
  4245.  Related Information 
  4246.  
  4247.           Methods: 
  4248.  
  4249.               SOM_Error 
  4250.  
  4251.  
  4252. ΓòÉΓòÉΓòÉ 2.66. SOMClass ΓòÉΓòÉΓòÉ
  4253.  
  4254. SOMClass 
  4255.  
  4256.  File stem: somcls 
  4257.  
  4258.  Base 
  4259.  
  4260.           SOMObject 
  4261.  
  4262.  Metaclass 
  4263.  
  4264.           SOMClass 
  4265.           (SOMClass is the only class with itself as metaclass.) 
  4266.  
  4267.  Ancestor Classes 
  4268.  
  4269.                     SOMObject
  4270.  
  4271.  Description 
  4272.  
  4273.           SOMClass is the root class for all SOM metaclasses. That is, all SOM 
  4274.           metaclasses must be subclasses of SOMClass or some other class 
  4275.           derived from it. It defines the essential behavior common to all SOM 
  4276.           classes. In particular, it provides a suite of methods for 
  4277.           initializing class objects, generic methods for manufacturing 
  4278.           instances of those classes, and methods that dynamically obtain or 
  4279.           update information about a class and its methods at run time. 
  4280.  
  4281.           Just as all SOM classes are expected to have SOMObject  (or a class 
  4282.           derived from SOMObject) as their base class, all SOM classes are 
  4283.           expected to have SOMClass  or a class derived from SOMClass as their 
  4284.           metaclass. Metaclasses define "class" methods (sometimes called 
  4285.           "factory" methods or "constructors") that manufacture objects from 
  4286.           any class object that is defined as an instance of the metaclass. 
  4287.  
  4288.           To define your own class methods, define your own metaclass by 
  4289.           subclassing SOMClass or one of its subclasses. Three methods that 
  4290.           SOMClass inherits and overrides from SOMObject are typically 
  4291.           overridden by any metaclass that introduces instance data  somInit, 
  4292.           somUninit, and somDumpSelfInt. The new methods introduced in SOMClass 
  4293.           that are frequently overridden are somNew, somRenew, and 
  4294.           somClassReady. (See the descriptions of these methods for further 
  4295.           information.) 
  4296.  
  4297.           Other reasons for creating a new metaclass include tracking object 
  4298.           instances, automatic garbage collection, interfacing to a persistent 
  4299.           object store, or providing/managing information that is global to a 
  4300.           set of object instances. 
  4301.  
  4302.  Types 
  4303.  
  4304.                        typedef sequence <SOMClass> SOMClassSequence;
  4305.  
  4306.                        struct somOffsetInfo  {
  4307.                           SOMClass          cls;
  4308.                           long              offset
  4309.                           };
  4310.                        typedef sequence <somOffsetInfo> SOMOffsets;
  4311.  
  4312.  New Methods 
  4313.  
  4314.           Attributes 
  4315.  
  4316.                        readonly attribute somOffsets somInstanceDataOffsets
  4317.  
  4318.           _get_somInstanceDataOffsets returns a sequence of structures, each of 
  4319.           which indicates an ancestor of the receiver class (or the receiver 
  4320.           class itself) and the offset to the beginning of the instance data 
  4321.           introduced by the indicated class in an instance of the receiver 
  4322.           class. The somOffsets information can be used in conjunction with 
  4323.           information derived from calls to a SOM Interface Repository to 
  4324.           completely determine the layout of SOM objects at runtime. 
  4325.  
  4326.           C++ Example 
  4327.  
  4328.                     #include <somcls.xh>
  4329.                     main()
  4330.                     {
  4331.                        int i;
  4332.                        SOMClassMgr *scm = somEnvironmentNew();
  4333.                        somOffsets so = _SOMClass->_get_somInstanceDataOffsets();
  4334.                        for (i=0; i
  4335.                           printf("In an instance of SOMClass, %s data starts at %d\n",
  4336.                                     so._buffer╤ìiΓêÖ->cls->somGetName(),
  4337.                                     so._buffer╤ìiΓêÖ->offset);
  4338.                     }
  4339.  
  4340.  Introduced Methods 
  4341.  
  4342.           The following list shows all the SOMClass introduced methods. 
  4343.  
  4344.           Group: Instance Creation (Factory) 
  4345.  
  4346.               somAllocate 
  4347.               somDeallocate 
  4348.               somNew 
  4349.               somNewNoInit 
  4350.               somRenew 
  4351.               somRenewNoInit 
  4352.               somRenewNoInitNoZero 
  4353.               somRenewNoZero 
  4354.  
  4355.           Group: Initialization/Termination 
  4356.  
  4357.               somAddDynamicMethod 
  4358.               somClassReady 
  4359.  
  4360.           Group: Access 
  4361.  
  4362.               somGetInstancePartSize 
  4363.               somGetInstanceSize 
  4364.               somGetInstanceToken 
  4365.               somGetMemberToken 
  4366.               somGetMethodData, 
  4367.               somGetMethodDescriptor 
  4368.               somGetMethodIndex 
  4369.               somGetMethodToken 
  4370.               somGetName 
  4371.               somGetNthMethodData 
  4372.               somGetNthMethodInfo 
  4373.               somGetNumMethods 
  4374.               somGetNumStaticMethods 
  4375.               somGetParents 
  4376.               somGetVersionNumbers 
  4377.  
  4378.           Group: Testing 
  4379.  
  4380.               somCheckVersion 
  4381.               somDescendedFrom 
  4382.               somSupportsMethod 
  4383.  
  4384.           Group: Dynamic 
  4385.  
  4386.               somFindMethod 
  4387.               somFindMethodOk 
  4388.               somFindSMethod 
  4389.               somFindSMethodId 
  4390.               somFindSMethodOk 
  4391.               somLookupmethod 
  4392.  
  4393.  Overridden Methods 
  4394.  
  4395.           The following list shows all the methods overridden by the SOMClass 
  4396.           class. These methods are overridden in order to modify the behavior 
  4397.           defined by an ancestor class. 
  4398.  
  4399.               somDumpSelfInt 
  4400.               somDefaultInit 
  4401.               somDestruct 
  4402.  
  4403.  Deprecated Methods 
  4404.  
  4405.           Use of the methods listed below is discouraged. There are three 
  4406.           reasons for this: 
  4407.  
  4408.           First, these methods are used in constructing classes, and this 
  4409.           capability is provided by the function somBuildClass. Class 
  4410.           construction in SOM is currently a fairly complex activity, and it is 
  4411.           likely to become even more so as the SOMobjects kernel evolves. To 
  4412.           avoid breaking source code that constructs classes, you are advised 
  4413.           to always use somBuildClass to build SOM classes. Note that the SOM 
  4414.           language bindings always use somBuildClass. 
  4415.  
  4416.           Second, these methods are used for customizing aspects of SOM 
  4417.           classes, such as method resolution and object creation. Doing this 
  4418.           requires that metaclasses override various methods introduced by 
  4419.           SOMClass. However, if this is done without the Cooperation Framework 
  4420.           that implements the SOM Metaclass Framework, SOMobjects cannot 
  4421.           guarantee that applications will function correctly. Unfortunately, 
  4422.           the Cooperation Framework (while available to SOM users as an 
  4423.           experimental feature) is not officially supported by the SOMobjects 
  4424.           Toolkit. So, this is another reason why the following methods are 
  4425.           deprecated. 
  4426.  
  4427.           Finally, some of these methods are now obsolete, so it seems 
  4428.           appropriate that their use be discouraged. 
  4429.  
  4430.               somAddStaticMethod 
  4431.               somGetApplyStub 
  4432.               somGetClassData 
  4433.               somGetClassMtab 
  4434.               somGetInstanceOffset 
  4435.               somGetMethodOffset 
  4436.               somGetParent 
  4437.               somGetPCIsMtab 
  4438.               somGetPCIsMtabs 
  4439.               somGetRdStub 
  4440.               somInitClass 
  4441.               somInitMIClass 
  4442.               somOverrideMtab 
  4443.               somOverrideSMethod 
  4444.               somSetClassData 
  4445.               somSetMethodDescriptor 
  4446.               _get_somDirectInitClasses attribute 
  4447.               _set_somDirectInitClasses attribute 
  4448.  
  4449.  
  4450. ΓòÉΓòÉΓòÉ 2.67. somAddDynamicMethod ΓòÉΓòÉΓòÉ
  4451.  
  4452. somAddDynamicMethod 
  4453.  
  4454. This method adds a new dynamic instance method to a class. Dynamic methods are 
  4455. not part of the declared interface to a class of objects, and are therefore not 
  4456. supported by implementation and usage bindings. Instead, dynamic methods 
  4457. provide a way to dynamically add new methods to a class of objects during 
  4458. execution. SOM provides no standard protocol for informing a user of the 
  4459. existence of dynamic methods and the arguments they take. Dynamic methods must 
  4460. be invoked using name-lookup or dispatch resolution. 
  4461.  
  4462. Note:  For backward compatibility, this method does not take an Environment 
  4463. parameter. 
  4464.  
  4465.  Syntax 
  4466.  
  4467.                     void somAddDynamicMethod (SOMClass receiver, somId methodId,
  4468.                                     somId methodDescriptor,
  4469.                                     somMethodPtr method,
  4470.                                     somMethodPtr applyStub)
  4471.  
  4472.  Parameters 
  4473.  
  4474.           receiver (SOMClass) 
  4475.                     A pointer to a SOM class object. 
  4476.  
  4477.           methodId (somId) 
  4478.                     A somId that names the method. 
  4479.  
  4480.           methodDescriptor (somId) 
  4481.                     A somId appropriate for requesting information concerning 
  4482.                     the method from the SOM IR. This is currently of the form 
  4483.                     <className>: :<methodName>. 
  4484.  
  4485.           method (somMethodPtr) 
  4486.                     A pointer to the procedure that will implement the new 
  4487.                     method. The first argument of this procedure is the address 
  4488.                     of the object on which it is being invoked. 
  4489.  
  4490.           applyStub (somMethodPtr) 
  4491.                     A pointer to a procedure that returns nothing and receives 
  4492.                     as arguments: a method receiver; an address where the 
  4493.                     return value from the method call is to be stored; a 
  4494.                     pointer to a method procedure; and a va_list containing the 
  4495.                     arguments to the method. The applyStub procedure (which is 
  4496.                     usually called by somDispatch must unload its va_list 
  4497.                     argument into separate variables of the correct type for 
  4498.                     the method, invoke its procedure argument on these 
  4499.                     variables, and then copy the result of the procedure 
  4500.                     invocation to the address specified by the return value 
  4501.                     argument. 
  4502.  
  4503.  Returns 
  4504.  
  4505.           rc (void) 
  4506.  
  4507.  Remarks 
  4508.  
  4509.           The somAddDynamicMethod method adds a new dynamic instance method to 
  4510.           the receiving class. This involves recording the method's ID, 
  4511.           descriptor, method procedure (specified by method), and apply stub in 
  4512.           the receiving class's method data. 
  4513.  
  4514.           The arguments to this method should be non-null and obey the 
  4515.           requirements expressed below. This is the responsibility of the 
  4516.           implementor of a class, who in general has no knowledge of whether 
  4517.           clients of this class will require use of the applyStub argument. 
  4518.  
  4519.  Original Class 
  4520.  
  4521.           SOMClass 
  4522.  
  4523.  Related Methods 
  4524.  
  4525.           Methods 
  4526.  
  4527.               somGetMethodDescriptor 
  4528.  
  4529.  Example Code 
  4530.  
  4531.                     /* New dynamic method "newMethod1" for class "XXX" */
  4532.                     static char *somMN_newMethod1 = "newMethod1";
  4533.                     static somId somId_newMethod1 = &somMN_newMethod1;
  4534.                     static char *somDS_newMethod1 = odq.XXX::newMethod1";
  4535.                     static somId somDI_newMethod1 = &somDS_newMethod1;
  4536.  
  4537.                     static void SOMLINK somAP_newMethod1(SOMObject somSelf,
  4538.                                                          void *__retVal,
  4539.                                                          somMethodProc *__methodPtr,
  4540.                                                          va_list __ap)
  4541.                     {
  4542.                     void* __somSelf = va_arg(__ap, SOMObject);
  4543.  
  4544.                     int arg1 = va_arg(__ap, int);
  4545.                     SOM_IgnoreWarning(__retVal);
  4546.                     ((somTD_SOMObject_newMethod1) __methodPtr) (__somSelf, arg1);
  4547.                     }
  4548.                     main()
  4549.                     {
  4550.                     _somAddDynamicMethod (
  4551.                        XXXClassData.classObject,           /* Receiver (class object) */
  4552.                        somId_newMethod1,                   /* method name somId */
  4553.                        somDI_newMethod1,                   /* method descriptor somId */
  4554.                        (somMethodProc%rbl.*) newMethod1,       /* method procedure */
  4555.                        (somMethodProc *) somAP&newMethod1); /* method apply stub */
  4556.                     }
  4557.  
  4558.  
  4559. ΓòÉΓòÉΓòÉ 2.68. somAllocate ΓòÉΓòÉΓòÉ
  4560.  
  4561. somAllocate 
  4562.  
  4563. This method supports class-specific memory allocation for class instances. It 
  4564. cannot be overridden. 
  4565.  
  4566. For backward compatibility, this method does not take an Environment parameter. 
  4567.  
  4568.  Syntax 
  4569.  
  4570.                     string somAllocate (SOMClass receiver, long size)
  4571.  
  4572.  Parameters 
  4573.  
  4574.           receiver (SOMClass) 
  4575.                     A pointer to the class object whose memory allocation 
  4576.                     method is desired. 
  4577.  
  4578.           size (long) 
  4579.                     The number of bytes to be allocated. 
  4580.  
  4581.  Returns 
  4582.  
  4583.           rc (string) 
  4584.  
  4585.                     string          A pointer to the first byte of the 
  4586.                                     allocated memory region. 
  4587.                     NULL            If sufficient memory is not available. 
  4588.  
  4589.  Remarks 
  4590.  
  4591.           When building a class, the somBuildClass function is responsible for 
  4592.           registering the procedure that will be executed when this method is 
  4593.           invoked on the class. The default procedure registered by 
  4594.           somBuildClass uses the SOMMalloc function, but the IDL modifier 
  4595.           somallocate can be used in the SOM IDL class implementation section 
  4596.           to indicate a different procedure. Users of this method should be 
  4597.           sure to use the dual method, somDeallocate, to free allocated 
  4598.           storage. Also, if the IDL modifier somallocate is used to indicate a 
  4599.           special allocation routine, the IDL modifier somdeallocate should be 
  4600.           used to indicate a dual procedure to be called when the somDeallocate 
  4601.           method is invoked. 
  4602.  
  4603.  Original Class 
  4604.  
  4605.           SOMClass 
  4606.  
  4607.  Related Methods 
  4608.  
  4609.           Methods 
  4610.  
  4611.               somDeallocate 
  4612.  
  4613.  Example Code 
  4614.  
  4615.                     #include <som.xh>
  4616.                     #<somcls.xh>
  4617.                     main()
  4618.                     {
  4619.                        SOMClassMgr *cm = somEnvironmentNew();
  4620.                        /* Use SOMClass's instance allocation method */
  4621.                        string newRegion =  _SOMClass->somAllocate(20);
  4622.                     }
  4623.  
  4624.  
  4625. ΓòÉΓòÉΓòÉ 2.69. somCheckVersion ΓòÉΓòÉΓòÉ
  4626.  
  4627. somCheckVersion 
  4628.  
  4629. This method checks a class for compatibility with the specified major and minor 
  4630. version numbers. Not generally overridden. 
  4631.  
  4632. Note:  For backward compatibility, this method does not take an Environment 
  4633. parameter. 
  4634.  
  4635.  Syntax 
  4636.  
  4637.                     boolean somCheckVersion (SOMClass receiver, long majorVersion,
  4638.                                    long minorVersion)
  4639.  
  4640.  Parameters 
  4641.  
  4642.           receiver (SOMClass) 
  4643.                     A pointer to the SOM class whose version information should 
  4644.                     be checked. 
  4645.  
  4646.           majorVersion (long) 
  4647.                     This value usually changes only when a significant 
  4648.                     enhancement or incompatible change is made to a class. 
  4649.  
  4650.           minorVersion (long) 
  4651.                     This value changes whenever minor enhancements or fixes are 
  4652.                     made to a class. Class implementors usually maintain 
  4653.                     downward compatibility across changes in the minorVersion 
  4654.                     number. 
  4655.  
  4656.  Returns 
  4657.  
  4658.           rc (boolean) 
  4659.  
  4660.                     1        Returns 1 (true) if the implementation of this 
  4661.                              class is compatible with the specified major and 
  4662.                              minor version number. 
  4663.                     0        Returns 0 (false) if the implementation of this 
  4664.                              class is not compatible with the specified major 
  4665.                              and minor version number. 
  4666.  
  4667.  Remarks 
  4668.  
  4669.           This method checks the receiving class for compatibility with the 
  4670.           specified major and minor version numbers. An implementation is 
  4671.           compatible with the specified version numbers if it has the same 
  4672.           major version number and a minor version number that is equal to or 
  4673.           greater than minorVersion. The version number pair (0,0) is 
  4674.           considered to match any version. 
  4675.  
  4676.           This method is called automatically after creating a class object to 
  4677.           verify that a dynamically loaded class definition is compatible with 
  4678.           a client application. 
  4679.  
  4680.  Original Class 
  4681.  
  4682.           SOMClass 
  4683.  
  4684.  Example Code 
  4685.  
  4686.                     #include <animal.h>
  4687.                     main()
  4688.                     {
  4689.                        Animal myAnimal;
  4690.                        myAnimal = AnimalNew();
  4691.  
  4692.                        if (_somCheckVersion(_Animal, 0, 0))
  4693.                           somPrintf("Animal IS compatible with 0.0\n");
  4694.                        else
  4695.                           somPrintf("Animal IS NOT compatible with 0.0\n");
  4696.  
  4697.                        if (_somCheckVersion(_Animal, 1, 1))
  4698.                           somPrintf("Animal IS compatible with 1.1\n");
  4699.                        else
  4700.                           somPrintf("Animal IS NOT compatible with 1.1\n";
  4701.  
  4702.                        _somFree(myAnimal);
  4703.                        }
  4704.  
  4705.           Assuming that the implementation of Animal is version 1.0, this 
  4706.           program produces the following output: 
  4707.  
  4708.                     Animal IS compatible with 0.0
  4709.                     Animal IS NOT compatible with 1.1
  4710.  
  4711.  
  4712. ΓòÉΓòÉΓòÉ 2.70. somClassReady ΓòÉΓòÉΓòÉ
  4713.  
  4714. somClassReady 
  4715.  
  4716. This method indicates that a class has been constructed and is ready for normal 
  4717. use. Designed to be overridden. 
  4718.  
  4719. For backward compatibility, this method does not take an Environment parameter. 
  4720.  
  4721.  Syntax 
  4722.  
  4723.                     void somClassReady (SOMClass receiver)
  4724.  
  4725.  Parameters 
  4726.  
  4727.           receiver (SOMClass) 
  4728.                     A pointer to the class object that should be registered. 
  4729.  
  4730.  Returns 
  4731.  
  4732.           rc (void) 
  4733.  
  4734.  Remarks 
  4735.  
  4736.           This method is invoked automatically by the somBuildClass function 
  4737.           after constructing and initializing a class object. The default 
  4738.           implementation of this method provided by SOMClass simply registers 
  4739.           the newly constructed class with SOMClassMgrObject. Metaclasses can 
  4740.           override this method to augment class construction with additional 
  4741.           registration protocol. 
  4742.  
  4743.           To have special processing done when a class object is created, you 
  4744.           must define a metaclass for the class that overrides this method. The 
  4745.           final statement in any overriding method should invoke the parent 
  4746.           method to ensure that the class is properly registered with 
  4747.           SOMClassMgrObject. Users of the C and C++ implementation bindings for 
  4748.           SOM classes should never invoke this method directly; it is invoked 
  4749.           automatically during class construction. 
  4750.  
  4751.  Original Class 
  4752.  
  4753.           SOMClass 
  4754.  
  4755.  
  4756. ΓòÉΓòÉΓòÉ 2.71. somDeallocate ΓòÉΓòÉΓòÉ
  4757.  
  4758. somDeallocate 
  4759.  
  4760. This method frees memory originally allocated by the somAllocate method from 
  4761. the same class object. It cannot be overridden. 
  4762.  
  4763. For backward compatibility, this method does not take an Environment parameter. 
  4764.  
  4765.  Syntax 
  4766.  
  4767.                     void somDeallocate (SOMClass receiver, string memPtr)
  4768.  
  4769.  Parameters 
  4770.  
  4771.           receiver (SOMClass) 
  4772.                     A pointer to the class object whose somAllocate was 
  4773.                     originally used to allocate the memory now to be freed. 
  4774.  
  4775.           memPtr (string) 
  4776.                     A pointer to the first byte of the region of memory that is 
  4777.                     to be freed. 
  4778.  
  4779.  Returns 
  4780.  
  4781.           rc (void) 
  4782.  
  4783.  Remarks 
  4784.  
  4785.           The somDeallocate method is intended for use to free memory allocated 
  4786.           using its dual method, somAllocate. When building a class, the 
  4787.           somBuildClass function is responsible for registering the procedure 
  4788.           that will be executed when this method is invoked on the class. The 
  4789.           default procedure regisistered by somBuildClass uses the SOMFree 
  4790.           function, but the IDL modifier somdeallocate can be used in the SOM 
  4791.           IDL class implementation section to indicate a different procedure. 
  4792.           Users of this method should be sure that the dual method, 
  4793.           somAllocate, was originally used to allocate storage. Also, if the 
  4794.           IDL modifier somdeallocate is used to indicate a special deallocation 
  4795.           routine, the IDL modifier somallocate should be used to indicate a 
  4796.           dual procedure to be called when somAllocate is invoked. 
  4797.  
  4798.  Original Class 
  4799.  
  4800.           SOMClass 
  4801.  
  4802.  Related Methods 
  4803.  
  4804.           Methods 
  4805.  
  4806.               somAllocate 
  4807.  
  4808.  
  4809. ΓòÉΓòÉΓòÉ 2.72. somDescendedFrom ΓòÉΓòÉΓòÉ
  4810.  
  4811. somDescendedFrom 
  4812.  
  4813. This method tests whether one class is derived from another. Not generally 
  4814. overridden. 
  4815.  
  4816. For backward compatibility, this method does not take an Environment parameter. 
  4817.  
  4818.  Syntax 
  4819.  
  4820.                     boolean somDescendedFrom (SOMClass receiver, SOMClass aClassObj)
  4821.  
  4822.  Parameters 
  4823.  
  4824.           receiver (SOMClass) 
  4825.                     A pointer to the class object to be tested. 
  4826.  
  4827.           aClassObj (SOMClass) 
  4828.                     A pointer to the potential ancestor class. 
  4829.  
  4830.  Returns 
  4831.  
  4832.           rc (boolean) 
  4833.  
  4834.                     1        Returns 1 (true) if receiver is derived from 
  4835.                              aClassObj. 
  4836.                     0        Returns 0 (false) if receiver is not derived from 
  4837.                              aClassObj. 
  4838.  
  4839.  Remarks 
  4840.  
  4841.           This method tests whether the receiver class is derived from a given 
  4842.           class. For programs that use classes as types, this method can be 
  4843.           used to ascertain whether the type of one object is a subtype of 
  4844.           another. 
  4845.  
  4846.           This method considers a class object to be descended from itself. 
  4847.  
  4848.  Original Class 
  4849.  
  4850.           SOMClass 
  4851.  
  4852.  Related Methods 
  4853.  
  4854.           Methods 
  4855.  
  4856.               somIsA 
  4857.               somIsInstanceOf 
  4858.  
  4859.  Example Code 
  4860.  
  4861.                     #include <dog.h>
  4862.                     /* --------------------------------------------
  4863.                        Note: Dog is a subclass of Animal.
  4864.                        -------------------------------------------- */
  4865.                     main()
  4866.                     {
  4867.                       AnimalNewClass(0,0);
  4868.                       DogNewClass(0,0);
  4869.  
  4870.                       if (_somDescendedFrom (_Dog, _Animal))
  4871.                          somPrintf("Dog IS descended from Animal\n");
  4872.                       else
  4873.                           somPrintf("Dog is NOT descended from Animal\n");
  4874.                       if (_somDescendedFrom (_Animal, _Dog))
  4875.                          somPrintf("Animal IS descended from Dog\n");
  4876.                       else
  4877.                          somPrintf("Animal is NOT descended from Dog\n");
  4878.  
  4879.           This program produces the following output: 
  4880.  
  4881.                     Dog IS descended from Animal
  4882.                     Animal is NOT descended from Dog
  4883.  
  4884.  
  4885. ΓòÉΓòÉΓòÉ 2.73. somFindMethod ΓòÉΓòÉΓòÉ
  4886.  
  4887. somFindMethod 
  4888.  
  4889. This method finds the method procedure for a method and indicates whether it 
  4890. represents a static method or a dynamic method. Not generally overridden. 
  4891.  
  4892. For backward compatibility, this method does not take an Environment parameter. 
  4893.  
  4894.  Syntax 
  4895.  
  4896.                     boolean somFindMethod (SOMClass receiver, somId methodId,
  4897.                                  somMethodPtr m)
  4898.  
  4899.  Parameters 
  4900.  
  4901.           receiver (SOMClass) 
  4902.                     A pointer to the class object whose method is desired. 
  4903.  
  4904.           methodId (somId) 
  4905.                     An ID that represents the name of the desired method. The 
  4906.                     somIdFromString function can used to obtain an ID from the 
  4907.                     method's name. 
  4908.  
  4909.           m (somMethodPtr) 
  4910.                     A pointer to the location in memory where a pointer to the 
  4911.                     specified method's procedure should be stored. The method 
  4912.                     stores a NULL pointer in this location (if the method does 
  4913.                     not exist) or a value that can be called. 
  4914.  
  4915.  Returns 
  4916.  
  4917.           rc (boolean) 
  4918.  
  4919.                     TRUE           Returns TRUE when the method procedure can 
  4920.                                    be called directly and FALSE when the method 
  4921.                                    procedure is a dispatch function. 
  4922.                     FALSE          Returns FALSE when the method procedure is a 
  4923.                                    dispatch function. 
  4924.  
  4925.  Remarks 
  4926.  
  4927.           This method performs name-lookup method resolution, determines the 
  4928.           method procedure appropriate for performing the indicated method on 
  4929.           instances of the receiving class, and loads m with the method 
  4930.           procedure address. For static methods, method procedure resolution is 
  4931.           done using the instance method table of the receiving class. 
  4932.  
  4933.           Name-lookup resolution must be used to invoke dynamic methods. Also, 
  4934.           name-lookup can be useful when different classes introduce methods of 
  4935.           the same name, signature, and desired semantics, but it is not known 
  4936.           until runtime which of these classes should be used as a type for the 
  4937.           objects on which the method is to be invoked. If the signature of a 
  4938.           method is a not known, then method procedures cannot be be used 
  4939.           directly, and the somDispatch method can be used after dynamically 
  4940.           discovering the signature to allow the correct arguments can be 
  4941.           placed on a va_list. 
  4942.  
  4943.           As with any method that returns procedure pointers, this method 
  4944.           allows repeated invocations of the same method procedure to be 
  4945.           programmed. If this is done, it up to the programmer to prevent 
  4946.           runtime errors by assuring that each invocation is performed either 
  4947.           on an instance of the class used to resolve the method procedure or 
  4948.           of some class derived from it. Whenever using SOM method procedure 
  4949.           pointers, it is necessary to indicate the arguments to be passed and 
  4950.           the use of system linkage to the compiler, so it can generate a 
  4951.           correct procedure call. The way this is done depends on the compiler 
  4952.           and the system being used. However, C and C++ usage bindings provide 
  4953.           an appropriate typedef for static methods. The name of the typedef is 
  4954.           based on the name of the class that introduces the method, as 
  4955.           illustrated in the example below. 
  4956.  
  4957.           If the class does not support the specified method, then *m is set to 
  4958.           NULL and the return value is meaningless. Otherwise, the returned 
  4959.           result is true if the indicated method was a static method. 
  4960.  
  4961.  Original Class 
  4962.  
  4963.           SOMClass 
  4964.  
  4965.  Related Methods 
  4966.  
  4967.           Methods 
  4968.  
  4969.               somFindSMethod 
  4970.               somFindSMethodOK 
  4971.               somSupportsMethod 
  4972.               somDispatch, 
  4973.               somClassDispatch 
  4974.  
  4975.           Functions 
  4976.  
  4977.               somApply 
  4978.               somResolve 
  4979.               somClassResolve 
  4980.               somResolveByName 
  4981.               somParentNumResolve 
  4982.  
  4983.           Macros 
  4984.  
  4985.               SOM_Resolve 
  4986.               SOM_ResolveNoCheck 
  4987.               SOM_ParentNumResolve 
  4988.  
  4989.  Example Code 
  4990.  
  4991.           Assuming that the Animal class introduces the method setSound, the 
  4992.           type name for the setSound method procedure type will be 
  4993.           somTD_Animal_setSound, as illustrated in the Example. 
  4994.  
  4995.                     #include <animal.h>
  4996.                     void main()
  4997.                     {
  4998.                        Animal myAnimal;
  4999.                        somId somId_setSound;
  5000.                        somTD_Animal_setSound methodPtr;
  5001.                        Environment *ev = somGetGlobalEnvironment();
  5002.  
  5003.                        myAnimal = AnimalNew();
  5004.                     /* -----------------------------------
  5005.                        Note: Next three lines are equivalent to
  5006.                            _setSound(myAnimal, ev, "Roar!!!");
  5007.                        ----------------------------------- */
  5008.                        somId_setSound = somIdFromString("setSound");
  5009.                        _somFindMethod (_somGetClass(myAnimal),
  5010.                                         somId_setSound, &methodPtr);
  5011.                        methodPtr(myAnimal, ev, "Roar!!!");
  5012.                     /* ----------------------------------- */
  5013.                        _display(myAnimal, ev);
  5014.                        _somFree(myAnimal);
  5015.                     }
  5016.                     /*
  5017.                     Program Output:
  5018.                     This Animal says
  5019.                     Roar!!!
  5020.                     */
  5021.  
  5022.  
  5023. ΓòÉΓòÉΓòÉ 2.74. somFindMethodOk ΓòÉΓòÉΓòÉ
  5024.  
  5025. somFindMethodOk 
  5026.  
  5027. This method finds the method procedure for a method and indicates whether it 
  5028. represents a static method or a dynamic method. Not generally overridden. 
  5029.  
  5030. For backward compatibility, this method does not take an Environment parameter. 
  5031.  
  5032.  Syntax 
  5033.  
  5034.                     boolean somFindMethodOk (SOMClass receiver, somId methodId,
  5035.                                    somMethodPtr m)
  5036.  
  5037.  Parameters 
  5038.  
  5039.           receiver (SOMClass) 
  5040.                     A pointer to the class object whose method is desired. 
  5041.  
  5042.           methodId (somId) 
  5043.                     An ID that represents the name of the desired method. The 
  5044.                     somIdFromString function can used to obtain an ID from the 
  5045.                     method's name. 
  5046.  
  5047.           m (somMethodPtr) 
  5048.                     A pointer to the location in memory where a pointer to the 
  5049.                     specified method's procedure should be stored. Both methods 
  5050.                     store a NULL pointer in this location (if the method does 
  5051.                     not exist) or a value that can be called. 
  5052.  
  5053.  Returns 
  5054.  
  5055.           rc (boolean) 
  5056.  
  5057.                     TRUE           Returns TRUE when the method procedure can 
  5058.                                    be called directly and FALSE when the method 
  5059.                                    procedure is a dispatch function. 
  5060.                     FALSE          Returns FALSE when the method procedure is a 
  5061.                                    dispatch function. 
  5062.  
  5063.  Remarks 
  5064.  
  5065.           This method performs name-lookup method resolution, determines the 
  5066.           method procedure appropriate for performing the indicated method on 
  5067.           instances of the receiving class, and loads m with the method 
  5068.           procedure address. For static methods, method procedure resolution is 
  5069.           done using the instance method table of the receiving class. 
  5070.  
  5071.           Name-lookup resolution must be used to invoke dynamic methods. Also, 
  5072.           name-lookup can be useful when different classes introduce methods of 
  5073.           the same name, signature, and desired semantics, but it is not known 
  5074.           until runtime which of these classes should be used as a type for the 
  5075.           objects on which the method is to be invoked. If the signature of a 
  5076.           method is a not known, then method procedures cannot be be used 
  5077.           directly, and the somDispatch method can be used after dynamically 
  5078.           discovering the signature to allow the correct arguments can be 
  5079.           placed on a va_list. 
  5080.  
  5081.           As with any method that returns procedure pointers, this method 
  5082.           allows repeated invocations of the same method procedure to be 
  5083.           programmed. If this is done, it up to the programmer to prevent 
  5084.           runtime errors by assuring that each invocation is performed either 
  5085.           on an instance of the class used to resolve the method procedure or 
  5086.           of some class derived from it. Whenever using SOM method procedure 
  5087.           pointers, it is necessary to indicate the arguments to be passed and 
  5088.           the use of system linkage to the compiler, so it can generate a 
  5089.           correct procedure call. The way this is done depends on the compiler 
  5090.           and the system being used. However, C and C++ usage bindings provide 
  5091.           an appropriate typedef for static methods. The name of the typedef is 
  5092.           based on the name of the class that introduces the method, as 
  5093.           illustrated in the example below. 
  5094.  
  5095.           Unlike the somFindMethod method, if the class does not support the 
  5096.           specified method, the somFindMethodOk method raises an error and 
  5097.           halts execution. 
  5098.  
  5099.           If the class does not support the specified method, then *m is set to 
  5100.           NULL and the return value is meaningless. Otherwise, the returned 
  5101.           result is true if the indicated method was a static method. 
  5102.  
  5103.  Original Class 
  5104.  
  5105.           SOMClass 
  5106.  
  5107.  Related Methods 
  5108.  
  5109.           Methods 
  5110.  
  5111.               somFindSMethod 
  5112.               somFindSMethodOK 
  5113.               somSupportsMethod 
  5114.               somDispatch, 
  5115.               somClassDispatch 
  5116.  
  5117.           Functions 
  5118.  
  5119.               somApply 
  5120.               somResolve 
  5121.               somClassResolve 
  5122.               somResolveByName 
  5123.               somParentNumResolve 
  5124.  
  5125.           Macros 
  5126.  
  5127.               SOM_Resolve 
  5128.               SOM_ResolveNoCheck 
  5129.               SOM_ParentNumResolve 
  5130.  
  5131.  Example Code 
  5132.  
  5133.           Assuming that the Animal class introduces the method setSound, the 
  5134.           type name for the setSound method procedure type will be 
  5135.           somTD_Animal_setSound, as illustrated in the Example. 
  5136.  
  5137.                     #include <animal.h>
  5138.                     void main()
  5139.                     {
  5140.                        Animal myAnimal;
  5141.                        somId somId_setSound;
  5142.                        somTD_Animal_setSound methodPtr;
  5143.                        Environment *ev = somGetGlobalEnvironment();
  5144.  
  5145.                        myAnimal = AnimalNew();
  5146.                     /* -----------------------------------
  5147.                        Note: Next three lines are equivalent to
  5148.                            _setSound(myAnimal, ev, "Roar!!!");
  5149.                        ----------------------------------- */
  5150.                        somId_setSound = somIdFromString("setSound");
  5151.                        _somFindMethod (_somGetClass(myAnimal),
  5152.                                         somId_setSound, &methodPtr);
  5153.                        methodPtr(myAnimal, ev, "Roar!!!");
  5154.                     /* ----------------------------------- */
  5155.                        _display(myAnimal, ev);
  5156.                        _somFree(myAnimal);
  5157.                     }
  5158.                     /*
  5159.                     Program Output:
  5160.                     This Animal says
  5161.                     Roar!!!
  5162.                     */
  5163.  
  5164.  
  5165. ΓòÉΓòÉΓòÉ 2.75. somFindSMethod ΓòÉΓòÉΓòÉ
  5166.  
  5167. somFindSMethod 
  5168.  
  5169. This method finds the method procedure for a static method. Not generally 
  5170. overridden. 
  5171.  
  5172. For backward compatibility, this method does not take an Environment parameter. 
  5173.  
  5174.  Syntax 
  5175.  
  5176.                     somMethodPtr somFindSMethod (SOMClass receiver, somId methodId)
  5177.  
  5178.  Parameters 
  5179.  
  5180.           receiver (SOMClass) 
  5181.                     A pointer to a class object. 
  5182.  
  5183.           methodId (somId) 
  5184.                     A somId representing the name of the desired method. 
  5185.  
  5186.  Returns 
  5187.  
  5188.           rc (somMethodPtr) 
  5189.  
  5190.                     This method returns a pointer to the method procedure that 
  5191.                     supports the specified method for the class. 
  5192.  
  5193.  Remarks 
  5194.  
  5195.           This method performs name-lookup resolution in a similar fashion to 
  5196.           somFindMethod and somFindMethodOK, but are restricted to static but 
  5197.           is restricted to static methods. See the description of somFindMethod 
  5198.           for a discussion of name-lookup method resolution. Because this 
  5199.           method is restricted to resolving static methods, its interface is 
  5200.           slightly different from the somFindMethod interface; a method 
  5201.           procedure pointer is returned when lookup is successful; otherwise 
  5202.           NULL is returned. 
  5203.  
  5204.           The somFindSMethodOk method is identical to this method except that, 
  5205.           with somFindSMethodOk, an error is raised if the indicated static 
  5206.           method is not defined for the receiving class, and execution is 
  5207.           halted. 
  5208.  
  5209.  Original Class 
  5210.  
  5211.           SOMClass 
  5212.  
  5213.  Related Methods 
  5214.  
  5215.           Methods 
  5216.  
  5217.               somFindMethod 
  5218.               somFindMethodOk 
  5219.  
  5220.  Example Code 
  5221.  
  5222.                     See the somFindMethod method example.
  5223.  
  5224.  
  5225. ΓòÉΓòÉΓòÉ 2.76. somFindSMethodOk ΓòÉΓòÉΓòÉ
  5226.  
  5227. somFindSMethodOk 
  5228.  
  5229. This method finds the method procedure for a static method. Not generally 
  5230. overridden. 
  5231.  
  5232. For backward compatibility, this method does not take an Environment parameter. 
  5233.  
  5234.  Syntax 
  5235.  
  5236.                     somMethodPtr somFindSMethodOk (SOMClass receiver,
  5237.                                       somId methodId)
  5238.  
  5239.  Parameters 
  5240.  
  5241.           receiver (SOMClass) 
  5242.                     A pointer to a class object. 
  5243.  
  5244.           methodId (somId) 
  5245.                     A somId representing the name of the desired method. 
  5246.  
  5247.  Returns 
  5248.  
  5249.           rc (somMethodPtr) 
  5250.  
  5251.                     This method returns a pointer to the method procedure that 
  5252.                     supports the specified method for the class. 
  5253.  
  5254.  Remarks 
  5255.  
  5256.           This method performs name-lookup resolution in a similar fashion to 
  5257.           somFindMethod and somFindMethodOK, but are restricted to static but 
  5258.           is restricted to static methods. See the description of somFindMethod 
  5259.           for a discussion of name-lookup method resolution. Because this 
  5260.           method is restricted to resolving static methods, its interface is 
  5261.           slightly different from the somFindMethod interface; a method 
  5262.           procedure pointer is returned when lookup is successful; otherwise 
  5263.           NULL is returned. 
  5264.  
  5265.           This method is identical to somFindSMethod, except that an error is 
  5266.           raised if the indicated static method is not defined for the 
  5267.           receiving class, and execution is halted. 
  5268.  
  5269.  Original Class 
  5270.  
  5271.           SOMClass 
  5272.  
  5273.  Related Methods 
  5274.  
  5275.           Methods 
  5276.  
  5277.               somFindMethod 
  5278.               somFindMethodOk 
  5279.  
  5280.  Example Code 
  5281.  
  5282.                     See the somFindMethod method example.
  5283.  
  5284.  
  5285. ΓòÉΓòÉΓòÉ 2.77. somGetInstancePartSize ΓòÉΓòÉΓòÉ
  5286.  
  5287. somGetInstancePartSize 
  5288.  
  5289. This method returns the total size of the instance data structure introduced by 
  5290. a class. Not generally overridden. 
  5291.  
  5292. For backward compatibility, this method does not take an Environment parameter. 
  5293.  
  5294.  Syntax 
  5295.  
  5296.                     long somGetInstancePartSize (SOMClass receiver)
  5297.  
  5298.  Parameters 
  5299.  
  5300.           receiver (SOMClass) 
  5301.                     A pointer to the class object whose instance data size is 
  5302.                     desired. 
  5303.  
  5304.  Returns 
  5305.  
  5306.           rc (long) 
  5307.  
  5308.                     bytes          Returns the size, in bytes, of the instance 
  5309.                                    variables introduced by this class. This 
  5310.                                    does not include the size of instance 
  5311.                                    variables introduced by this class's 
  5312.                                    ancestor or descendent classes. 
  5313.                     0              Returns 0 if a class introduces no instance 
  5314.                                    variables. 
  5315.  
  5316.  Remarks 
  5317.  
  5318.           This method returns the amount of space needed in an object of the 
  5319.           specified class or any of its subclasses to contain the instance 
  5320.           variables introduced by the class. 
  5321.  
  5322.  Original Class 
  5323.  
  5324.           SOMClass 
  5325.  
  5326.  Related Methods 
  5327.  
  5328.           Methods 
  5329.  
  5330.               somGetInstanceSize 
  5331.  
  5332.  Example Code 
  5333.  
  5334.                     #include <animal.h>
  5335.                     main()
  5336.                     {
  5337.                       Animal myAnimal;
  5338.                       SOMClass animalClass;
  5339.                       int instanceSize;
  5340.                       int instanceOffset;
  5341.                       int instancePartSize;
  5342.  
  5343.                       myAnimal = AnimalNew ();
  5344.                       animalClass = _somGetClass (myAnimal);
  5345.                       instanceSize = _somGetInstanceSize (animalClass);
  5346.                       instanceOffset = _somGetInstanceOffset (animalClass);
  5347.                       instancePartSize = _somGetInstancePartSize (animalClass);
  5348.                       somPrintf ("Instance Size: %d\n", instanceSize);
  5349.                       somPrintf ("Instance Offset: %d\n", instanceOffset);
  5350.                       somPrintf ("Instance Part Size: %d\n", instancePartSize);
  5351.                       _somFree (myAnimal);
  5352.                     }
  5353.                     /*
  5354.                     Output from this program:
  5355.                     Instance Size: 8
  5356.                     Instance Offset: 0
  5357.                     Instance Part Size: 4
  5358.                     */
  5359.  
  5360.  
  5361. ΓòÉΓòÉΓòÉ 2.78. somGetInstanceSize ΓòÉΓòÉΓòÉ
  5362.  
  5363. somGetInstanceSize 
  5364.  
  5365. This method returns the size of an instance of a class. Not generally 
  5366. overridden. 
  5367.  
  5368. For backward compatibility, this method does not take an Environment parameter. 
  5369.  
  5370.  Syntax 
  5371.  
  5372.                     long somGetInstanceSize (SOMClass receiver)
  5373.  
  5374.  Parameters 
  5375.  
  5376.           receiver (SOMClass) 
  5377.                     A pointer to the class object whose instance size is 
  5378.                     desired. 
  5379.  
  5380.  Returns 
  5381.  
  5382.           rc (long) 
  5383.  
  5384.                     bytes          Returns the size, in bytes, of each instance 
  5385.                                    of this class. This includes the space 
  5386.                                    required for instance variables introduced 
  5387.                                    by this class and all of its ancestor 
  5388.                                    classes. 
  5389.  
  5390.  Remarks 
  5391.  
  5392.           This method returns the total amount of space needed in an instance 
  5393.           of the specified class. 
  5394.  
  5395.  Original Class 
  5396.  
  5397.           SOMClass 
  5398.  
  5399.  Related Methods 
  5400.  
  5401.           Methods 
  5402.  
  5403.               somGetInstancePartSize 
  5404.  
  5405.  Example Code 
  5406.  
  5407.                     #include <animal.h>
  5408.                     main()
  5409.                     {
  5410.                       Animal myAnimal;
  5411.                       SOMClass animalClass;
  5412.                       int instanceSize;
  5413.                       int instanceOffset;
  5414.                       int instancePartSize;
  5415.  
  5416.                            myAnimal = AnimalNew ();
  5417.                       animalClass = _somGetClass (myAnimal);
  5418.                       instanceSize = _somGetInstanceSize (animalClass);
  5419.                       instanceOffset = _somGetInstanceOffset (animalClass);
  5420.                       instancePartSize = _somGetInstancePartSize (animalClass);
  5421.                       somPrintf ("Instance Size: %d\n", instanceSize);
  5422.                       somPrintf ("Instance Offset: %d\n", instanceOffset);
  5423.                       somPrintf ("Instance Part Size: %d\n", instancePartSize);
  5424.                       _somFree (myAnimal);
  5425.                     }
  5426.                     /*
  5427.                     Output from this program:
  5428.                     Instance Size: 8
  5429.                     Instance Offset: 0
  5430.                     Instance Part Size: 4
  5431.                     */
  5432.  
  5433.  
  5434. ΓòÉΓòÉΓòÉ 2.79. somGetInstanceToken ΓòÉΓòÉΓòÉ
  5435.  
  5436. somGetInstanceToken 
  5437.  
  5438. This method returns a data access token for the instance data introduced by a 
  5439. class. 
  5440.  
  5441. For backward compatibility, this method does not take an Environment parameter. 
  5442.  
  5443.  Syntax 
  5444.  
  5445.                     somDToken somGetInstanceToken (SOMClass receiver)
  5446.  
  5447.  Parameters 
  5448.  
  5449.           receiver (SOMClass) 
  5450.                     A pointer to a SOMClass object. 
  5451.  
  5452.  Returns 
  5453.  
  5454.           rc (somDToken) 
  5455.  
  5456.                     Returns a data token for the beginning of the instance data 
  5457.                     introduced by the receiver. 
  5458.  
  5459.  Remarks 
  5460.  
  5461.           This method returns a data token "pointing" to the beginning of the 
  5462.           instance data introduced by the receiving class. This token can be 
  5463.           passed to the function somDataResolve  to locate this instance data 
  5464.           within an an instance of the receiver class or any class derived from 
  5465.           it. Also the instance data token for a class can be passed to the 
  5466.           class method somGetMemberToken to get a data token for a specific 
  5467.           instance variables introduced by the class (if the relative offset of 
  5468.           this instance variable is known). This approach is used by C and C++ 
  5469.           implementation bindings to support public instance data for OIDL 
  5470.           classes (IDL classes currently have no public instance data). 
  5471.  
  5472.           A data token for the instance data introduced by a class is required 
  5473.           by method procedures that access data introduced by the method 
  5474.           procedure's defining class. For classes declared using OIDL and IDL, 
  5475.           the needed token is stored in the auxiliary class data structure, 
  5476.           which is an external data structure made statically available by the 
  5477.           C and C++ language bindings as <className>CClassData.instanceToken. 
  5478.           Thus, this method call is not generally used by C and C++ class 
  5479.           implementors of classes declared using OIDL or IDL. 
  5480.  
  5481.  Original Class 
  5482.  
  5483.           SOMClass 
  5484.  
  5485.  Related Methods 
  5486.  
  5487.           Functions 
  5488.  
  5489.               somDataResolve 
  5490.  
  5491.           Methods 
  5492.  
  5493.               somGetInstanceSize 
  5494.               somGetInstancePartSize 
  5495.               somGetMemberToken 
  5496.  
  5497.  
  5498. ΓòÉΓòÉΓòÉ 2.80. somGetMemberToken ΓòÉΓòÉΓòÉ
  5499.  
  5500. somGetMemberToken 
  5501.  
  5502. This method returns an access token for an instance variable. This method is 
  5503. not generally overridden. 
  5504.  
  5505. For backward compatibility, this method does not take an Environment parameter. 
  5506.  
  5507.  Syntax 
  5508.  
  5509.                     somDToken somGetMemberToken (SOMClass receiver,
  5510.                                       long memberOffset,
  5511.                                       somDToken instanceToken)
  5512.  
  5513.  Parameters 
  5514.  
  5515.           receiver (SOMClass) 
  5516.                     A pointer to a SOMClass object. 
  5517.  
  5518.           memberOffset (long) 
  5519.                     A 32-bit integer representing the offset of the required 
  5520.                     data member. 
  5521.  
  5522.           instanceToken (somDToken) 
  5523.                     A token, obtained from somGetInstanceToken, that identifies 
  5524.                     the introduced portion of the class. 
  5525.  
  5526.  Returns 
  5527.  
  5528.           rc (somDToken) 
  5529.  
  5530.                     Returns an access token for the specified data member. 
  5531.  
  5532.  Remarks 
  5533.  
  5534.           This method returns an access token for the data member at offset 
  5535.           memberOffset within the block of instance data identified by instance 
  5536.           token. The returned token can subsequently be passed to the 
  5537.           somDataResolve function to locate the data member. 
  5538.  
  5539.           Typically, only the code that implements a class declared using OIDL 
  5540.           requires access to this method, and this code is normally provided by 
  5541.           implementation bindings. Thus C and C++ programmers do not normally 
  5542.           invoke this method. 
  5543.  
  5544.  Original Class 
  5545.  
  5546.           SOMClass 
  5547.  
  5548.  Related Methods 
  5549.  
  5550.           Functions 
  5551.  
  5552.               somDataResolve 
  5553.  
  5554.           Methods 
  5555.  
  5556.               somGetInstanceSize 
  5557.               somGetInstancePartSize 
  5558.               somGetInstanceToken 
  5559.  
  5560.  
  5561. ΓòÉΓòÉΓòÉ 2.81. somGetMethodData ΓòÉΓòÉΓòÉ
  5562.  
  5563. somGetMethodData 
  5564.  
  5565. This method returns method information for a specified method, which must have 
  5566. been introduced by the receiver class or an ancestor of that class. Not 
  5567. generally overridden. 
  5568.  
  5569. For backward compatibility, this method does not take an Environment parameter. 
  5570.  
  5571.  Syntax 
  5572.  
  5573.                     boolean somGetMethodData (SOMClass receiver, somId methodId,
  5574.                                    somMethodData md)
  5575.  
  5576.  Parameters 
  5577.  
  5578.           receiver (SOMClass) 
  5579.                     A pointer to the class that produced the index value. 
  5580.  
  5581.           methodId (somId) 
  5582.                     A somId for the method's name. 
  5583.  
  5584.           md (somMethodData) 
  5585.                     A pointer to a somMethodData structure. 
  5586.  
  5587.  Returns 
  5588.  
  5589.           rc (boolean) 
  5590.  
  5591.                     true           Returns boolean true if successful. 
  5592.                     false          Returns false if not successful. 
  5593.  
  5594.  Remarks 
  5595.  
  5596.           This method loads a somMethodData structure with data describing the 
  5597.           method identified by the passed methodId. If methodId does not 
  5598.           identify a method known to the receiver, then false is returned; 
  5599.           otherwise, true is returned after loading the somMethodData structure 
  5600.           with data corresponding to the indicated method. 
  5601.  
  5602.  Original Class 
  5603.  
  5604.           SOMClass 
  5605.  
  5606.  Related Methods 
  5607.  
  5608.           Data Structures 
  5609.  
  5610.               somMethodData (somapi.h) 
  5611.  
  5612.           Methods 
  5613.  
  5614.               somGetMethodIndex 
  5615.               somGetMethodData 
  5616.               somGetNthMethodInfo 
  5617.  
  5618.  Example Code 
  5619.  
  5620.  
  5621.                     #include <somcls.xh>
  5622.  
  5623.                     main
  5624.                     {
  5625.                        somEnvironmentNew();
  5626.                        somId gmiId = somIdFromString("somGetMethodIndex");
  5627.                        somMethodData md;
  5628.                        boolean rc = _SOMClass->somGetMethodData(gmiId, &md);
  5629.                        SOM_Test(rc && somCompareIds(gmiId, md.id);
  5630.                     }
  5631.  
  5632.  
  5633. ΓòÉΓòÉΓòÉ 2.82. somGetMethodDescriptor ΓòÉΓòÉΓòÉ
  5634.  
  5635. somGetMethodDescriptor 
  5636.  
  5637. This method returns the method descriptor for a method. Not generally 
  5638. overridden. 
  5639.  
  5640. For backward compatibility, this method does not take an Environment parameter. 
  5641.  
  5642.  Syntax 
  5643.  
  5644.                     somId somGetMethodDescriptor (SOMClass receiver, somId methodId)
  5645.  
  5646.  Parameters 
  5647.  
  5648.           receiver (SOMClass) 
  5649.                     A pointer to a SOMClass. 
  5650.  
  5651.           methodId (somId) 
  5652.                     A somId method descriptor. 
  5653.  
  5654.  Returns 
  5655.  
  5656.           rc (somId) 
  5657.  
  5658.                     Returns a somId method descriptor. 
  5659.  
  5660.  Remarks 
  5661.  
  5662.           This method returns the method descriptor for a specified method of a 
  5663.           class. (A method descriptor is a somId that represents the identifier 
  5664.           of an attribute definition or a method definition in the SOM 
  5665.           Interface Repository. It contains information about the method's 
  5666.           return type and the types of its arguments.) If the class object does 
  5667.           not support the indicated method, NULL is returned. 
  5668.  
  5669.  Original Class 
  5670.  
  5671.           SOMClass 
  5672.  
  5673.  Related Methods 
  5674.  
  5675.           Methods 
  5676.  
  5677.               somAddDynamicMethod 
  5678.               somGetNthMethodInfo 
  5679.               somGetMethodData 
  5680.               somGetNthMethodData 
  5681.  
  5682.  Example Code 
  5683.  
  5684.                     somId myMethodDescriptor;
  5685.                     myMethodDescriptor = _somGetMethodDescriptor(_Animal,
  5686.                                                     somIdFromString("setSound"));
  5687.  
  5688.  
  5689. ΓòÉΓòÉΓòÉ 2.83. somGetMethodIndex ΓòÉΓòÉΓòÉ
  5690.  
  5691. somGetMethodIndex 
  5692.  
  5693. This method returns a class-specific index for a method. Not generally 
  5694. overridden. 
  5695.  
  5696. For backward compatibility, this method does not take an Environment parameter. 
  5697.  
  5698.  Syntax 
  5699.  
  5700.                     long somGetMethodIndex (SOMClass receiver, somId methodId)
  5701.  
  5702.  Parameters 
  5703.  
  5704.           receiver (SOMClass) 
  5705.                     A pointer to a SOMClass object. 
  5706.  
  5707.           methodId (somId) 
  5708.                     A somId method ID. 
  5709.  
  5710.  Returns 
  5711.  
  5712.           rc (long) 
  5713.  
  5714.                     long         Returns a positive long if successful. 
  5715.                     -1           Returns a -1 if not successful. 
  5716.  
  5717.  Remarks 
  5718.  
  5719.           This method returns an index that can be used in subsequent calls to 
  5720.           the same receiving class to determine information about the indicated 
  5721.           (static or dynamic) method, via the methods somGetNthMethodData and 
  5722.           somGetNthMethodInfo. The method must be appropriate for use on an 
  5723.           instance of the receiver class;  otherwise, a -1 is returned. The 
  5724.           index of a method can change over time if dynamic methods are added 
  5725.           to the receiver class or its ancestors. Thus, in dynamic 
  5726.           multi-threaded environments, a critical region should be used to 
  5727.           bracket the use of this method and of subsequent requests for method 
  5728.           information based on the returned index. 
  5729.  
  5730.  Original Class 
  5731.  
  5732.           SOMClass 
  5733.  
  5734.  Related Methods 
  5735.  
  5736.           Data Structures 
  5737.  
  5738.               somMethodData (somapi.h) 
  5739.  
  5740.           Methods 
  5741.  
  5742.               somGetNthMethodData 
  5743.               somGetNthMethodInfo 
  5744.  
  5745.  Example Code 
  5746.  
  5747.                     #include <somcls.xh>
  5748.                     main
  5749.                     {
  5750.                        somEnvironmentNew();
  5751.                        somId gmiId = somIdFromString("somGetMethodIndex");
  5752.                        long index = _SOMClass->somGetMethodIndex(gmiId);
  5753.                        somMethodData md;
  5754.                        boolean rc = _SOMClass->somGetNthMethodData(index,&md);
  5755.                        SOM_Test(rc && somCompareIds(gmiId, md.id));
  5756.                     }
  5757.  
  5758.  
  5759. ΓòÉΓòÉΓòÉ 2.84. somGetMethodToken ΓòÉΓòÉΓòÉ
  5760.  
  5761. somGetMethodToken 
  5762.  
  5763. This method returns a method access token for static method. Not generally 
  5764. overridden. 
  5765.  
  5766. For backward compatibility, this method does not take an Environment parameter. 
  5767.  
  5768.  Syntax 
  5769.  
  5770.                     somMToken somGetMethodToken (SOMClass receiver,
  5771.                                       somId methodId)
  5772.  
  5773.  Parameters 
  5774.  
  5775.           receiver (SOMClass) 
  5776.                     A pointer to a SOMClass object. 
  5777.  
  5778.           methodId (somId) 
  5779.                     A somId identifying a method. 
  5780.  
  5781.  Returns 
  5782.  
  5783.           rc (somMToken) 
  5784.  
  5785.                     Returns a somMToken method access token. 
  5786.  
  5787.  Remarks 
  5788.  
  5789.           This method returns a method access token for a static method with 
  5790.           the specified id that was introduced by the receiver class or an 
  5791.           ancestor of the receiver class. This method token can be passed to 
  5792.           the somResolve function (or one of the other offset-based method 
  5793.           resolution functions) to select a method procedure pointer from a 
  5794.           method table of an object whose class is the same as, or is derived 
  5795.           from the class that introduced the method. 
  5796.  
  5797.           The example below assumes that the class Animal introduces the method 
  5798.           setSound. 
  5799.  
  5800.  Original Class 
  5801.  
  5802.           SOMClass 
  5803.  
  5804.  Related Methods 
  5805.  
  5806.           Functions 
  5807.  
  5808.               somResolve 
  5809.               somClassResolve 
  5810.               somParentNumResolve 
  5811.  
  5812.           Methods 
  5813.  
  5814.               somGetNthMethodInfo 
  5815.               somGetMethodData 
  5816.  
  5817.  Example Code 
  5818.  
  5819.                     #include < >
  5820.                     main() {
  5821.                     somMToken tok;
  5822.                     Animal myAnimal;
  5823.                     somTD_Animal_setSound methodPtr; /* use typedef from animal.h */
  5824.                     Environment *ev = somGetGlobalEnvironment();
  5825.                     myAnimal = AnimalNew();
  5826.  
  5827.                     /* next 3 lines equivalent to _setSound(myAnimal, ev, "Roar!!!"); */
  5828.                     tok = _ somGetMethodToken(_Animal, somIdFromString("setSound"));
  5829.                     methodPtr = (somTD_Animal_setSound)somResolve(myAnimal, tok);
  5830.                     methodPtr(myAnimal, ev, "Roar!!!");
  5831.                     _display(myAnimal, ev);
  5832.                     _somFree(myAnimal);
  5833.                     }
  5834.  
  5835.  
  5836. ΓòÉΓòÉΓòÉ 2.85. somGetname ΓòÉΓòÉΓòÉ
  5837.  
  5838. somGetname 
  5839.  
  5840. This method returns the name of a class. Not generally overridden. 
  5841.  
  5842. For backward compatibility, this method does not take an Environment parameter. 
  5843.  
  5844.  Syntax 
  5845.  
  5846.                     string somGetname (SOMClass receiver)
  5847.  
  5848.  Parameters 
  5849.  
  5850.           receiver (SOMClass) 
  5851.                     The class whose name is desired. 
  5852.  
  5853.  Returns 
  5854.  
  5855.           rc (string) 
  5856.                     Returns a pointer to the name of the class. 
  5857.  
  5858.  Remarks 
  5859.  
  5860.           This method returns the address of a zero-terminated string that 
  5861.           gives the name of the receiving class. This name may be used as a 
  5862.           RepositoryId in the Repository_lookup_id method (described in the SOM 
  5863.           Interface Repository Framework section) to obtain the IDL interface 
  5864.           definition that corresponds to the receiving class. 
  5865.  
  5866.           The returned name is not necessarily the same as the statically known 
  5867.           class name used by a programmer to gain access to the class object 
  5868.           (e.g., via the method somFindClass). This is because the method 
  5869.           somSubstituteClass may have been used to "shadow" the class having 
  5870.           the static name used by the programmer. 
  5871.  
  5872.           Also, when the interface to a class's instances is defined within an 
  5873.           IDL module, the returned name will not directly correspond to the 
  5874.           names of the procedures and macros made available by C and C++ usage 
  5875.           bindings for accessing class objects (e.g., the <className>NewClass 
  5876.           procedure, or the _<className> macro). This is because the token used 
  5877.           in constructing the names of these procedures and macros uses an 
  5878.           underscore character to separate the module name from the interface 
  5879.           name, while the actual name of the corresponding class uses two colon 
  5880.           characters instead of an underscore for this purpose. 
  5881.  
  5882.           This method is not generally overridden. The returned address is 
  5883.           valid until the class object is unregistered or freed. 
  5884.  
  5885.  Original Class 
  5886.  
  5887.           SOMClass 
  5888.  
  5889.  Related Methods 
  5890.  
  5891.           Methods 
  5892.  
  5893.               Repository_lookup_id 
  5894.               somSubstituteClass 
  5895.               somFindClass 
  5896.  
  5897.  Example Code 
  5898.  
  5899.                     #include <animal.h>   /* assume Animal defined in th        e Zoo module */
  5900.                     #include <string.h>
  5901.                     main()
  5902.                     {
  5903.                       string className = Zoo_AnimalNewClass(0,0)->somGetName();
  5904.                       SOM_Test(!strcmp(  className, "Zoo::Animal"));
  5905.                     }
  5906.  
  5907.  
  5908. ΓòÉΓòÉΓòÉ 2.86. somGetNthMethodData ΓòÉΓòÉΓòÉ
  5909.  
  5910. somGetNthMethodData 
  5911.  
  5912. This method returns method information for the nth (static or dynamic) method 
  5913. known to a given class. Not generally overridden. 
  5914.  
  5915. For backward compatibility, this method does not take an Environment parameter. 
  5916.  
  5917.  Syntax 
  5918.  
  5919.                     boolean somGetNthMethodData (SOMClass receiver, long index,
  5920.                                      somMethodData md)
  5921.  
  5922.  Parameters 
  5923.  
  5924.           receiver (SOMClass) 
  5925.                     A pointer to the class that produced the index value. 
  5926.  
  5927.           index (long) 
  5928.                     An index returned as a result of a previous call of 
  5929.                     somGetMethodIndex. 
  5930.  
  5931.           md (somMethodData) 
  5932.                     A pointer to a somMethodData structure. 
  5933.  
  5934.  Returns 
  5935.  
  5936.           rc (boolean) 
  5937.  
  5938.                     true           Returns boolean true if successful. 
  5939.                     false          Returns false if not successful. 
  5940.  
  5941.  Remarks 
  5942.  
  5943.           This method loads a somMethodData structure with data describing the 
  5944.           method identified by the passed index. The index must have been 
  5945.           produced by a previous call to exactly the same receiver class; the 
  5946.           same method will in general have different indexes in different 
  5947.           classes. If the index does not identify a method known to this class, 
  5948.           then false is returned; otherwise, true is returned after loading the 
  5949.           somMethodData structure with data corresponding to the indicated 
  5950.           method. 
  5951.  
  5952.  Related Methods 
  5953.  
  5954.           Data Structures somMethodData (somapi.h) 
  5955.  
  5956.           Methods 
  5957.  
  5958.               somGetMethodIndex 
  5959.               somGetMethodData 
  5960.               somGetNthMethodInfo 
  5961.  
  5962.  Example Code 
  5963.  
  5964.                     #include <somcls.xh>
  5965.                     main
  5966.                     {
  5967.                        somEnvironmentNew();
  5968.                        somId gmiId = somIdFromString("somGetMethodIndex");
  5969.                        long index = _SOMClass->somGetMethodIndex(gmiId);
  5970.                        somMethodData md;
  5971.                        boolean rc = _SOMClass->somGetNthMethodData(index,&md);
  5972.                        SOM_Test(rc && somCompareIds(gmiId, md.id));
  5973.                     }
  5974.  
  5975.  
  5976. ΓòÉΓòÉΓòÉ 2.87. somGetNthMethodInfo ΓòÉΓòÉΓòÉ
  5977.  
  5978. somGetNthMethodInfo 
  5979.  
  5980. This method returns the somId of the nth (static or dynamic) method known to a 
  5981. given class. Also loads a somId with a descriptor for the method. Not generally 
  5982. overridden. 
  5983.  
  5984. For backward compatibility, this method does not take an Environment parameter. 
  5985.  
  5986.  Syntax 
  5987.  
  5988.                     somId somGetNthMethodInfo (SOMClass receiver, long index,
  5989.                                    somId descriptor)
  5990.  
  5991.  Parameters 
  5992.  
  5993.           receiver (SOMClass) 
  5994.                     A pointer to the class from which the index was obtained 
  5995.                     using method somGetMethodIndex. 
  5996.  
  5997.           index (long) 
  5998.                     The nth method known to this class, whose method descriptor 
  5999.                     is desired. 
  6000.  
  6001.           descriptor (somId) 
  6002.                     A pointer to a somId that will be loaded with a somId for 
  6003.                     the descriptor. 
  6004.  
  6005.  Returns 
  6006.  
  6007.           rc (somId) 
  6008.  
  6009.                     somID          Returns the somId for the indicated method, 
  6010.                                    if a method with the indicated index is 
  6011.                                    known to the receiver. 
  6012.                     NULL           Returns NULL if a method with the indicated 
  6013.                                    index is not known to the receiver. 
  6014.  
  6015.  Remarks 
  6016.  
  6017.           This method returns the identifier of a method, and loads the somId 
  6018.           whose address is passed with the somId of the method descriptor. 
  6019.           Method descriptors are used to support access to information stored 
  6020.           in a SOM Interface Repository. 
  6021.  
  6022.  Original Class 
  6023.  
  6024.           SOMClass 
  6025.  
  6026.  Related Methods 
  6027.  
  6028.           Classes 
  6029.  
  6030.               Repository (repostry.idl) 
  6031.  
  6032.           Methods 
  6033.  
  6034.               somGetMethodIndex 
  6035.               somGetNthMethodData 
  6036.  
  6037.  Example Code 
  6038.  
  6039.                     #include <somcls.xh>
  6040.                     main()
  6041.                     {
  6042.                       somEnvironmentNew();
  6043.                       somId descriptor, icId = somIdFromSring("somGetMethodIndex");
  6044.                       long ndx = _SOMClass->somGetMethodIndex(icId);
  6045.                       somMethodData md;
  6046.                       boolean rc = _SOMClass->somGetNthMethodData(index,&md);
  6047.                       SOM_Test(rc && somCompareIds(gmiId, md.id));
  6048.                     }
  6049.  
  6050.  
  6051. ΓòÉΓòÉΓòÉ 2.88. somGetNumMethods ΓòÉΓòÉΓòÉ
  6052.  
  6053. somGetNumMethods 
  6054.  
  6055. This method returns the number of methods available for a class of objects. Not 
  6056. generally overridden. 
  6057.  
  6058. For backward compatibility, this method does not take an Environment parameter. 
  6059.  
  6060.  Syntax 
  6061.  
  6062.                     long somGetNumMethods (SOMClass receiver)
  6063.  
  6064.  Parameters 
  6065.  
  6066.           receiver (SOMClass) 
  6067.                     A pointer to the class object whose instance method count 
  6068.                     is desired. 
  6069.  
  6070.  Returns 
  6071.  
  6072.           rc (long) 
  6073.                     Returns the total number of methods that are currently 
  6074.                     available for the receiving class. 
  6075.  
  6076.  Remarks 
  6077.  
  6078.           This method returns the number of methods currently supported by the 
  6079.           specified class, including inherited methods (both static and 
  6080.           dynamic). 
  6081.  
  6082.           The value that this method returns is the total number of methods 
  6083.           currently known to the receiving class as being applicable to its 
  6084.           instances. This includes both static and dynamic methods, whether 
  6085.           defined in this class or inherited from an ancestor class. 
  6086.  
  6087.  Original Class 
  6088.  
  6089.           SOMClass 
  6090.  
  6091.  Related Methods 
  6092.  
  6093.           Methods 
  6094.  
  6095.               somGetNumStaticMethods 
  6096.  
  6097.  Example Code 
  6098.  
  6099.                     #include <animal.h>
  6100.                     main()
  6101.                     {
  6102.                         long numMethods;
  6103.  
  6104.                         AnimalNewClass(Animal_MajorVersion, Animal_MinorVersion);
  6105.                         numMethods = _somGetNumMethods(_Animal);
  6106.                         somPrintf("Number of methods supported by class: %d\n",
  6107.                                                                      numMethods);
  6108.                     }
  6109.  
  6110.  
  6111. ΓòÉΓòÉΓòÉ 2.89. somGetNumStaticMethods ΓòÉΓòÉΓòÉ
  6112.  
  6113. somGetNumStaticMethods 
  6114.  
  6115. This method obtains the number of static methods available for a class of 
  6116. objects. Not generally overridden. 
  6117.  
  6118. For backward compatibility, this method does not take an Environment parameter. 
  6119.  
  6120.  Syntax 
  6121.  
  6122.                     long somGetNumStaticMethods (SOMClass receiver)
  6123.  
  6124.  Parameters 
  6125.  
  6126.           receiver (SOMClass) 
  6127.                     A pointer to the class object whose static method count is 
  6128.                     desired. 
  6129.  
  6130.  Returns 
  6131.  
  6132.           rc (long) 
  6133.                     Returns the total number of static methods that are 
  6134.                     available for instances of the receiving class. 
  6135.  
  6136.  Remarks 
  6137.  
  6138.           This method returns the number of static methods available in the 
  6139.           specified class, including inherited ones. Static methods are those 
  6140.           that are represented by entries in the class's instance method table, 
  6141.           and which can be invoked using method tokens and offset resolution. 
  6142.  
  6143.  Original Class 
  6144.  
  6145.           SOMClass 
  6146.  
  6147.  Related Methods 
  6148.  
  6149.           Methods 
  6150.  
  6151.               somGetNumMethods 
  6152.  
  6153.  Example Code 
  6154.  
  6155.                     #include <animal.h>
  6156.                     main()
  6157.                     {
  6158.                         long numMethods;
  6159.  
  6160.                         AnimalNewClass(Animal_MajorVersion, Animal_MinorVersion);
  6161.                         numMethods = _somGetNumStaticMethods(_Animal);
  6162.                         somPrintf("Number of static methods supported by class: %d\n",
  6163.                                      numMethods);
  6164.                     }
  6165.  
  6166.  
  6167. ΓòÉΓòÉΓòÉ 2.90. somGetParents ΓòÉΓòÉΓòÉ
  6168.  
  6169. somGetParents This method gets a pointer to a class's parent (direct base) 
  6170. classes. Not generally overridden.  Note: For backward compatibility, this 
  6171. method does not take an Environment parameter. 
  6172.  
  6173.  Syntax 
  6174.  
  6175.                     SOMClassSequence somGetParents (SOMObject receiver)
  6176.  
  6177.  Parameters 
  6178.  
  6179.           receiver (SOMObject) 
  6180.                     A pointer to the class whose parent (base) classes are 
  6181.                     desired. 
  6182.  
  6183.  Returns 
  6184.  
  6185.           rc (SOMClassSequence) 
  6186.                     The somGetParents method returns a sequence of pointers to 
  6187.                     the parents of the receiver, or NULL otherwise (in the case 
  6188.                     of SOMObject). The sequence of parents is in left-to-right 
  6189.                     order. 
  6190.  
  6191.  Remarks 
  6192.  
  6193.           The somGetparents method returns a sequence containing pointers to 
  6194.           the parents of the receiver. 
  6195.  
  6196.  Original Class 
  6197.  
  6198.           SOMClass 
  6199.  
  6200.  Related Methods 
  6201.  
  6202.           Methods 
  6203.  
  6204.               somGetClass 
  6205.  
  6206.  Example Code 
  6207.  
  6208.                     /* Note: Dog is a single-inheritance subclass of Animal. */
  6209.                     #include <dog.idl>
  6210.                     main ()
  6211.                     {
  6212.                        Dog myDog;
  6213.                        SOMClass dogClass;
  6214.                        SOMClassSequence parents;
  6215.                        char *parentName;
  6216.                        int i;
  6217.  
  6218.                        myDog = DogNew();
  6219.                        dogClass = _somGetClass(myDog);
  6220.                        parents = _somGetPaarents(dogClass);
  6221.                        for (i=0; i<parents._length; i++)
  6222.                           somprintf("-- parent %d is %s\n", i;
  6223.                                    _somGetName(parents._buffer[i]));
  6224.                        _somFree(myDog);
  6225.                     }
  6226.                     /*
  6227.                     Output from this program:
  6228.                     -- parent 0 is Animal
  6229.                     */
  6230.  
  6231.  
  6232. ΓòÉΓòÉΓòÉ 2.91. somGetVersionNumbers ΓòÉΓòÉΓòÉ
  6233.  
  6234. somGetVersionNumbers 
  6235.  
  6236. This method gets the major and minor version numbers of a class. Not generally 
  6237. overridden. 
  6238.  
  6239. For backward compatibility, this method does not take an Environment parameter. 
  6240.  
  6241.  Syntax 
  6242.  
  6243.                     void somGetVersionNumbers (SOMClass receiver, long majorVersion,
  6244.                                    long minorVersion)
  6245.  
  6246.  Parameters 
  6247.  
  6248.           receiver (SOMClass) 
  6249.                     A pointer to a class object. 
  6250.  
  6251.           majorVersion (long) 
  6252.                     A pointer where the major version number is to be stored. 
  6253.  
  6254.           minorVersion (long) 
  6255.                     A pointer where the minor version number is to be stored. 
  6256.  
  6257.  Returns 
  6258.  
  6259.           rc (void) 
  6260.  
  6261.  Remarks 
  6262.  
  6263.           This method returns, via its output parameters, the major and minor 
  6264.           version numbers of the class specified by receiver. The class object 
  6265.           must have already been created (because the class object is the 
  6266.           receiver of the method). 
  6267.  
  6268.  Original Class 
  6269.  
  6270.           SOMClass 
  6271.  
  6272.  Related Methods 
  6273.  
  6274.           Methods 
  6275.  
  6276.               somCheckVersion 
  6277.  
  6278.  Example Code 
  6279.  
  6280.                     #include <som.h>
  6281.  
  6282.                     main() {
  6283.  
  6284.                       long major, minor;
  6285.                       SOMClass myClass;
  6286.  
  6287.                       somEnvironmentNew();
  6288.                       myClass = _somFindClass(SOMClassMgrObject,
  6289.                                            somIdFromString("Animal"), 0, 0);
  6290.                       _somGetVersionNumbers(myClass, &major, &minor);
  6291.                       somPrintf("The version numbers are %i and %i.\n", major, minor);
  6292.                     }
  6293.  
  6294.  
  6295. ΓòÉΓòÉΓòÉ 2.92. somLookupMethod ΓòÉΓòÉΓòÉ
  6296.  
  6297. somLookupMethod Performs name-look method resolution. Not generally overridden. 
  6298.  
  6299. For backward compatibility, this method does not take an Environment parameter. 
  6300.  
  6301.  Syntax 
  6302.  
  6303.                     somMethodPtr somLookupMethod (SOMClass receiver,
  6304.                                       somId methodId)
  6305.  
  6306.  Parameters 
  6307.  
  6308.           receiver (SOMClass) 
  6309.                     A pointer to the class whose instance method for the 
  6310.                     indicated method is desired. 
  6311.  
  6312.           methodId (somId) 
  6313.                     A somId of the method whose method-procedure pointer is 
  6314.                     needed. 
  6315.  
  6316.  Returns 
  6317.  
  6318.           rc (somMethodPtr) 
  6319.                     A pointer to the method procedure that supports the method 
  6320.                     indicated by methodId. Or, if the method is not supported 
  6321.                     by the receiving class, then an error is returned, and 
  6322.                     execution is halted. 
  6323.  
  6324.  Remarks 
  6325.  
  6326.           The somLookupMethod method uses name-lookup resolution to return the 
  6327.           address of the method procedure that supports the indicated method on 
  6328.           instances of the receiver class. The method may be either static or 
  6329.           dynamic. The SOM C and C++ usage bindings support name-lookup method 
  6330.           resolution by invoking somLookupMethod on the class of the object on 
  6331.           which a name-lookup method invocation is made. 
  6332.  
  6333.           The somLookupMethod method is like somFindSMethodOK except that 
  6334.           dynamic methods can also be returned. If the method is not supported 
  6335.           by the receiving class, then an error is returned and execution is 
  6336.           halted. To check the existence of a method, somFindMethod can be 
  6337.           used. 
  6338.  
  6339.           As always, in order to use a method procedure pointer such as that 
  6340.           returned by somLookupMethod, it is necessary to typecast the 
  6341.           procedure pointer so that the compiler can create the correct 
  6342.           procedure call. This means that a programmer making explicit use of 
  6343.           this method must either know the signature of the identified method, 
  6344.           and from this create a typedef indicating system linkage and the 
  6345.           appropriate argument and return types, or make use of an existing 
  6346.           typedef provided by C or C++ usage bindings for a SOM class that 
  6347.           introduces a static method with the desired signature. 
  6348.  
  6349.  Original Class 
  6350.  
  6351.           SOMClass 
  6352.  
  6353.  Related Methods 
  6354.  
  6355.           Methods 
  6356.  
  6357.               somFindSMethod 
  6358.               somFindSMethodOk 
  6359.               somFindMethod 
  6360.               somFindMethodOk 
  6361.  
  6362.  Example Code 
  6363.  
  6364.                     #include <somcls.xh>
  6365.                     #include <somcm.xh>
  6366.                     void main()
  6367.                     {
  6368.                        somId fcpId = somIdFromString("somFindClass")
  6369.                        somId animalId = somIdFromString("Animal");
  6370.                        SOMClassMgr *cm = somEnvironmentNew();
  6371.                        somTD_SOMClassMgr_somFindClass findclassproc =
  6372.                              (somTD_SOMClassMgr_somFindClass)
  6373.                                  _SOMClassMgr->somLookupMethod(fcpId);
  6374.                        SOMClass *aCls = findclassproc(cm,animalId,0,0);
  6375.                        ...
  6376.                        somFree(fcpId);
  6377.                        somFree(animalId);
  6378.                     }
  6379.  
  6380.  
  6381. ΓòÉΓòÉΓòÉ 2.93. somNew ΓòÉΓòÉΓòÉ
  6382.  
  6383. somNew This method creates a new instance of a class. 
  6384.  
  6385. For backward compatibility, this method does not take an Environment parameter. 
  6386.  
  6387.  Syntax 
  6388.  
  6389.                     SOMObject somNew (SOMClass receiver)
  6390.  
  6391.  Parameters 
  6392.  
  6393.           receiver (SOMClass) 
  6394.                     A pointer to the class object that is to create a new 
  6395.                     instance. 
  6396.  
  6397.  Returns 
  6398.  
  6399.           rc (SOMObject) 
  6400.                     A pointer to the newly created SOMObject object, or NULL. 
  6401.  
  6402.  Remarks 
  6403.  
  6404.           The somNew and somNewNoInit methods create a new instance of the 
  6405.           receiving class. Space is allocated as necessary to hold the new 
  6406.           object. 
  6407.  
  6408.           When either of these methods is applied to a class, the result is a 
  6409.           new instance of that class. If the receiver class is SOMClass or a 
  6410.           class derived from SOMClass, the new object will be a class object; 
  6411.           otherwise, the new object will not be a class object. The somNew 
  6412.           method invokes the somDefaultInit method on the newly created object. 
  6413.           The somNewNoInit method does not. 
  6414.  
  6415.           Either method can fail to allocate enough memory to hold a new object 
  6416.           and, if so, NULL is returned. 
  6417.  
  6418.           The SOM Compiler generates convenience macros for creating instances 
  6419.           of each class, for use by C and C++ programmers. These macros can be 
  6420.           used in place of this method. 
  6421.  
  6422.  Original Class 
  6423.  
  6424.           SOMClass 
  6425.  
  6426.  Related Methods 
  6427.  
  6428.           Methods 
  6429.  
  6430.               somRenew 
  6431.  
  6432.  Example Code 
  6433.  
  6434.                     #include <animal.h>
  6435.  
  6436.                     void main()
  6437.                     {    Animal myAnimal;
  6438.                     /*------------------------------------------
  6439.                     Note:  next 2 lines are functionally equivalent to
  6440.                              myAnimal = AnimalNew();
  6441.                     ----------------------------------------- */
  6442.                         /* Create class object: */
  6443.                         AnimalNewClass(Animal_MajorVersion, AnimalMinorVersion);
  6444.                         myAnimal = _somNew(_Animal);  /* Create instance of Animal cls */
  6445.                         /* ... */
  6446.                         _somFree(myAnimal);       /* Free instance of Animal */
  6447.                      }
  6448.  
  6449.  
  6450. ΓòÉΓòÉΓòÉ 2.94. somNewNoInit ΓòÉΓòÉΓòÉ
  6451.  
  6452. somNewNoInit This method creates a new instance of a class. 
  6453.  
  6454. For backward compatibility, this method does not take an Environment parameter. 
  6455.  
  6456.  Syntax 
  6457.  
  6458.                     SOMObject somNewNoInit (SOMClass receiver)
  6459.  
  6460.  Parameters 
  6461.  
  6462.           receiver (SOMClass) 
  6463.                     A pointer to the class object that is to create a new 
  6464.                     instance. 
  6465.  
  6466.  Returns 
  6467.  
  6468.           rc (SOMObject) 
  6469.                     A pointer to the newly created SOMObject object, or NULL. 
  6470.  
  6471.  Remarks 
  6472.  
  6473.           The somNew and somNewNoInit methods create a new instance of the 
  6474.           receiving class. Space is allocated as necessary to hold the new 
  6475.           object. 
  6476.  
  6477.           When either of these methods is applied to a class, the result is a 
  6478.           new instance of that class. If the receiver class is SOMClass or a 
  6479.           class derived from SOMClass, the new object will be a class object; 
  6480.           otherwise, the new object will not be a class object.  The somNew 
  6481.           method invokes the somDefaultInit method on the newly created object. 
  6482.           The somNewNoInit method does not. 
  6483.  
  6484.           Either method can fail to allocate enough memory to hold a new object 
  6485.           and, if so, NULL is returned. 
  6486.  
  6487.           The SOM Compiler generates convenience macros for creating instances 
  6488.           of each class, for use by C and C++ programmers. These macros can be 
  6489.           used in place of this method. 
  6490.  
  6491.  Original Class 
  6492.  
  6493.           SOMClass 
  6494.  
  6495.  Related Methods 
  6496.  
  6497.           Methods 
  6498.  
  6499.               somRenew 
  6500.  
  6501.  Example Code 
  6502.  
  6503.                     #include <animal.h>
  6504.  
  6505.                     void main()
  6506.                     {    Animal myAnimal;
  6507.                     /*------------------------------------------
  6508.                     Note:  next 2 lines are functionally equivalent to
  6509.                              myAnimal = AnimalNew();
  6510.                     ----------------------------------------- */
  6511.                         /* Create class object: */
  6512.                         AnimalNewClass(Animal_MajorVersion, AnimalMinorVersion);
  6513.                         myAnimal = _somNew(_Animal);  /* Create instance of Animal cls */
  6514.                         /* ... */
  6515.                         _somFree(myAnimal);       /* Free instance of Animal */
  6516.                      }
  6517.  
  6518.  
  6519. ΓòÉΓòÉΓòÉ 2.95. somRenew ΓòÉΓòÉΓòÉ
  6520.  
  6521. somRenew This method creates a new object instance using a passed block of 
  6522. storage. 
  6523.  
  6524. For backward compatibility, this method does not take an Environment parameter. 
  6525.  
  6526.  Syntax 
  6527.  
  6528.                     SOMObject somRenew (SOMClass receiver, somToken memPtr)
  6529.  
  6530.  Parameters 
  6531.  
  6532.           receiver (SOMClass) 
  6533.                     A pointer to the class object that is to create the new 
  6534.                     instance. 
  6535.  
  6536.           memPtr (somToken) 
  6537.                     A pointer to the space to be used to construct a new 
  6538.                     object. 
  6539.  
  6540.  Returns 
  6541.  
  6542.           rc (SOMObject) 
  6543.                     The value of newObject is returned, which is now a pointer 
  6544.                     to a valid, initialized object. 
  6545.  
  6546.  Remarks 
  6547.  
  6548.           The somRenew method creates a new instance of the receiving class by 
  6549.           setting the appropriate location in the passed memory block to the 
  6550.           receiving class's instance method table. Unlike somNew, these "Renew" 
  6551.           methods use the space pointed to by memPtr rather than allocating new 
  6552.           space for the object. The somRenew method automatically 
  6553.           re-initializes the object by first zeroing the object's memory, and 
  6554.           then invoking somDefaultInit; somRenewNoInit zeros memory, but does 
  6555.           not invoke somDefaultInit. somRenewNoInitNoZero only sets the method 
  6556.           table pointer; while somRenewNoZero calls somDefaultInit, but does 
  6557.           not zero memory first. 
  6558.  
  6559.           No check is made to ensure that the passed pointer addresses enough 
  6560.           space to hold an instance of the receiving class. The caller can 
  6561.           determine the amount of space necessary by using the 
  6562.           somGetInstanceSize method. 
  6563.  
  6564.           The C bindings produced by the SOM Compiler contain a macro that is a 
  6565.           convenient shorthand for _somRenew(_className). 
  6566.  
  6567.  Original Class 
  6568.  
  6569.           SOMClass 
  6570.  
  6571.  Related Methods 
  6572.  
  6573.           Methods 
  6574.  
  6575.               somGetInstanceSize 
  6576.               somDefaultInit 
  6577.               somNew 
  6578.  
  6579.  Example Code 
  6580.  
  6581.                     #include <animal.h>
  6582.  
  6583.                     main()
  6584.                     {
  6585.                       void *myAnimalCluster;
  6586.                       Animal animals[5];
  6587.                       SOMClass animalClass;
  6588.                       int animalSize, i;
  6589.  
  6590.                       animalClass =
  6591.                           AnimalNewClass(Animal_MajorVersion,Animal_MinorVersion);
  6592.                       animalSize = _somGetInstanceSize (animalClass);
  6593.                       /* Round up to double-word multiple */
  6594.                       animalSize = ((animalSize+3)/4)*4;
  6595.                       /*
  6596.                        * Next line allocates room for 5 objects
  6597.                        * in a "cluster" with a single memory-
  6598.                        * allocation operation.
  6599.                        */
  6600.                       myAnimalCluster = SOMMalloc (5*animalSize);
  6601.                       /*
  6602.                        * The for-loop that follows creates 5 initialized
  6603.                        * Animal instances within the memory cluster.
  6604.                        */
  6605.                       for (i=0; i
  6606.                          animals[i] =
  6607.                          _somRenew(animalClass, myAnimalCluster+(i*animalSize));
  6608.                       /* Uninitialize the animals explicitly: */
  6609.                       for (i=0; i
  6610.                          _somUninit(animals[i]);
  6611.                       /*
  6612.                        * Finally, the next line frees all 5 animals
  6613.                        * with one operation.
  6614.                        */
  6615.                       SOMFree (myAnimalCluster);
  6616.                     }
  6617.  
  6618.  
  6619. ΓòÉΓòÉΓòÉ 2.96. somRenewNoInit ΓòÉΓòÉΓòÉ
  6620.  
  6621. somRenewNoInit This method creates a new object instance using a passed block 
  6622. of storage. 
  6623.  
  6624. For backward compatibility, this method does not take an Environment parameter. 
  6625.  
  6626.  Syntax 
  6627.  
  6628.                     SOMObject somRenewNoInit (SOMClass receiver, somToken memPtr)
  6629.  
  6630.  Parameters 
  6631.  
  6632.           receiver (SOMClass) 
  6633.                     A pointer to the class object that is to create the new 
  6634.                     instance. 
  6635.  
  6636.           memPtr (somToken) 
  6637.                     A pointer to the space to be used to construct a new 
  6638.                     object. 
  6639.  
  6640.  Returns 
  6641.  
  6642.           rc (SOMObject) 
  6643.                     The value of newObject is returned, which is now a pointer 
  6644.                     to a valid, initialized object. 
  6645.  
  6646.  Remarks 
  6647.  
  6648.           The somRenew method creates a new instance of the receiving class by 
  6649.           setting the appropriate location in the passed memory block to the 
  6650.           receiving class's instance method table. Unlike somNew, these "Renew" 
  6651.           methods use the space pointed to by memPtr rather than allocating new 
  6652.           space for the object. The somRenew method automatically 
  6653.           re-initializes the object by first zeroing the object's memory, and 
  6654.           then invoking somDefaultInit; somRenewNoInit zeros memory, but does 
  6655.           not invoke somDefaultInit. somRenewNoInitNoZero only sets the method 
  6656.           table pointer; while somRenewNoZero calls somDefaultInit, but does 
  6657.           not zero memory first. 
  6658.  
  6659.           No check is made to ensure that the passed pointer addresses enough 
  6660.           space to hold an instance of the receiving class. The caller can 
  6661.           determine the amount of space necessary by using the 
  6662.           somGetInstanceSize method. 
  6663.  
  6664.           The C bindings produced by the SOM Compiler contain a macro that is a 
  6665.           convenient shorthand for _somRenew(_className). 
  6666.  
  6667.  Original Class 
  6668.  
  6669.           SOMClass 
  6670.  
  6671.  Related Methods 
  6672.  
  6673.           Methods 
  6674.  
  6675.               somGetInstanceSize 
  6676.               somDefaultInit 
  6677.               somNew 
  6678.  
  6679.  Example Code 
  6680.  
  6681.                     #include <animal.h>
  6682.  
  6683.                     main()
  6684.                     {
  6685.                       void *myAnimalCluster;
  6686.                       Animal animals[5];
  6687.                       SOMClass animalClass;
  6688.                       int animalSize, i;
  6689.  
  6690.                       animalClass =
  6691.                           AnimalNewClass(Animal_MajorVersion,Animal_MinorVersion);
  6692.                       animalSize = _somGetInstanceSize (animalClass);
  6693.                       /* Round up to double-word multiple */
  6694.                       animalSize = ((animalSize+3)/4)*4;
  6695.                       /*
  6696.                        * Next line allocates room for 5 objects
  6697.                        * in a "cluster" with a single memory-
  6698.                        * allocation operation.
  6699.                        */
  6700.                       myAnimalCluster = SOMMalloc (5*animalSize);
  6701.                       /*
  6702.                        * The for-loop that follows creates 5 initialized
  6703.                        * Animal instances within the memory cluster.
  6704.                        */
  6705.                       for (i=0; i
  6706.                          animals[i] =
  6707.                          _somRenew(animalClass, myAnimalCluster+(i*animalSize));
  6708.                       /* Uninitialize the animals explicitly: */
  6709.                       for (i=0; i
  6710.                          _somUninit(animals[i]);
  6711.                       /*
  6712.                        * Finally, the next line frees all 5 animals
  6713.                        * with one operation.
  6714.                        */
  6715.                       SOMFree (myAnimalCluster);
  6716.                     }
  6717.  
  6718.  
  6719. ΓòÉΓòÉΓòÉ 2.97. somRenewNoInitNoZero ΓòÉΓòÉΓòÉ
  6720.  
  6721. somRenewNoInitNoZero This method creates a new object instance using a passed 
  6722. block of storage. 
  6723.  
  6724. For backward compatibility, this method does not take an Environment parameter. 
  6725.  
  6726.  Syntax 
  6727.  
  6728.                     SOMObject somRenewNoInitNoZero (SOMClass receiver,
  6729.                                        somToken memPtr)
  6730.  
  6731.  Parameters 
  6732.  
  6733.           receiver (SOMClass) 
  6734.                     A pointer to the class object that is to create the new 
  6735.                     instance. 
  6736.  
  6737.           memPtr (somToken) 
  6738.                     A pointer to the space to be used to construct a new 
  6739.                     object. 
  6740.  
  6741.  Returns 
  6742.  
  6743.           rc (SOMObject) 
  6744.                     The value of newObject is returned, which is now a pointer 
  6745.                     to a valid, initialized object. 
  6746.  
  6747.  Remarks 
  6748.  
  6749.           The somRenew method creates a new instance of the receiving class by 
  6750.           setting the appropriate location in the passed memory block to the 
  6751.           receiving class's instance method table. Unlike somNew, these "Renew" 
  6752.           methods use the space pointed to by memPtr rather than allocating new 
  6753.           space for the object. The somRenew method automatically 
  6754.           re-initializes the object by first zeroing the object's memory, and 
  6755.           then invoking somDefaultInit; somRenewNoInit zeros memory, but does 
  6756.           not invoke somDefaultInit. somRenewNoInitNoZero only sets the method 
  6757.           table pointer; while somRenewNoZero calls somDefaultInit, but does 
  6758.           not zero memory first. 
  6759.  
  6760.           No check is made to ensure that the passed pointer addresses enough 
  6761.           space to hold an instance of the receiving class. The caller can 
  6762.           determine the amount of space necessary by using the 
  6763.           somGetInstanceSize method. 
  6764.  
  6765.           The C bindings produced by the SOM Compiler contain a macro that is a 
  6766.           convenient shorthand for _somRenew(_className). 
  6767.  
  6768.  Original Class 
  6769.  
  6770.           SOMClass 
  6771.  
  6772.  Related Methods 
  6773.  
  6774.           Methods 
  6775.  
  6776.               somGetInstanceSize 
  6777.               somDefaultInit 
  6778.               somNew 
  6779.  
  6780.  Example Code 
  6781.  
  6782.                     #include <animal.h>
  6783.  
  6784.                     main()
  6785.                     {
  6786.                       void *myAnimalCluster;
  6787.                       Animal animals[5];
  6788.                       SOMClass animalClass;
  6789.                       int animalSize, i;
  6790.  
  6791.                       animalClass =
  6792.                           AnimalNewClass(Animal_MajorVersion,Animal_MinorVersion);
  6793.                       animalSize = _somGetInstanceSize (animalClass);
  6794.                       /* Round up to double-word multiple */
  6795.                       animalSize = ((animalSize+3)/4)*4;
  6796.                       /*
  6797.                        * Next line allocates room for 5 objects
  6798.                        * in a "cluster" with a single memory-
  6799.                        * allocation operation.
  6800.                        */
  6801.                       myAnimalCluster = SOMMalloc (5*animalSize);
  6802.                       /*
  6803.                        * The for-loop that follows creates 5 initialized
  6804.                        * Animal instances within the memory cluster.
  6805.                        */
  6806.                       for (i=0; i
  6807.                          animals[i] =
  6808.                          _somRenew(animalClass, myAnimalCluster+(i*animalSize));
  6809.                       /* Uninitialize the animals explicitly: */
  6810.                       for (i=0; i
  6811.                          _somUninit(animals[i]);
  6812.                       /*
  6813.                        * Finally, the next line frees all 5 animals
  6814.                        * with one operation.
  6815.                        */
  6816.                       SOMFree (myAnimalCluster);
  6817.                     }
  6818.  
  6819.  
  6820. ΓòÉΓòÉΓòÉ 2.98. somRenewNoZero ΓòÉΓòÉΓòÉ
  6821.  
  6822. somRenewNoZero This method creates a new object instance using a passed block 
  6823. of storage. 
  6824.  
  6825. For backward compatibility, this method does not take an Environment parameter. 
  6826.  
  6827.  Syntax 
  6828.  
  6829.                     SOMObject somRenewNoZero (SOMClass receiver, somToken memPtr)
  6830.  
  6831.  Parameters 
  6832.  
  6833.           receiver (SOMClass) 
  6834.                     A pointer to the class object that is to create the new 
  6835.                     instance. 
  6836.  
  6837.           memPtr (somToken) 
  6838.                     A pointer to the space to be used to construct a new 
  6839.                     object. 
  6840.  
  6841.  Returns 
  6842.  
  6843.           rc (SOMObject) 
  6844.                     The value of newObject is returned, which is now a pointer 
  6845.                     to a valid, initialized object. 
  6846.  
  6847.  Remarks 
  6848.  
  6849.           The somRenew method creates a new instance of the receiving class by 
  6850.           setting the appropriate location in the passed memory block to the 
  6851.           receiving class's instance method table. Unlike somNew, these "Renew" 
  6852.           methods use the space pointed to by memPtr rather than allocating new 
  6853.           space for the object. The somRenew method automatically 
  6854.           re-initializes the object by first zeroing the object's memory, and 
  6855.           then invoking somDefaultInit; somRenewNoInit zeros memory, but does 
  6856.           not invoke somDefaultInit. somRenewNoInitNoZero only sets the method 
  6857.           table pointer; while somRenewNoZero calls somDefaultInit, but does 
  6858.           not zero memory first. 
  6859.  
  6860.           No check is made to ensure that the passed pointer addresses enough 
  6861.           space to hold an instance of the receiving class. The caller can 
  6862.           determine the amount of space necessary by using the 
  6863.           somGetInstanceSize method. 
  6864.  
  6865.           The C bindings produced by the SOM Compiler contain a macro that is a 
  6866.           convenient shorthand for _somRenew(_className). 
  6867.  
  6868.  Original Class 
  6869.  
  6870.           SOMClass 
  6871.  
  6872.  Related Methods 
  6873.  
  6874.           Methods 
  6875.  
  6876.               somGetInstanceSize 
  6877.               somDefaultInit 
  6878.               somNew 
  6879.  
  6880.  Example Code 
  6881.  
  6882.                     #include <animal.h>
  6883.  
  6884.                     main()
  6885.                     {
  6886.                       void *myAnimalCluster;
  6887.                       Animal animals[5];
  6888.                       SOMClass animalClass;
  6889.                       int animalSize, i;
  6890.  
  6891.                       animalClass =
  6892.                           AnimalNewClass(Animal_MajorVersion,Animal_MinorVersion);
  6893.                       animalSize = _somGetInstanceSize (animalClass);
  6894.                       /* Round up to double-word multiple */
  6895.                       animalSize = ((animalSize+3)/4)*4;
  6896.                       /*
  6897.                        * Next line allocates room for 5 objects
  6898.                        * in a "cluster" with a single memory-
  6899.                        * allocation operation.
  6900.                        */
  6901.                       myAnimalCluster = SOMMalloc (5*animalSize);
  6902.                       /*
  6903.                        * The for-loop that follows creates 5 initialized
  6904.                        * Animal instances within the memory cluster.
  6905.                        */
  6906.                       for (i=0; i
  6907.                          animals[i] =
  6908.                          _somRenew(animalClass, myAnimalCluster+(i*animalSize));
  6909.                       /* Uninitialize the animals explicitly: */
  6910.                       for (i=0; i
  6911.                          _somUninit(animals[i]);
  6912.                       /*
  6913.                        * Finally, the next line frees all 5 animals
  6914.                        * with one operation.
  6915.                        */
  6916.                       SOMFree (myAnimalCluster);
  6917.                     }
  6918.  
  6919.  
  6920. ΓòÉΓòÉΓòÉ 2.99. somSupportsMethod ΓòÉΓòÉΓòÉ
  6921.  
  6922. somSupportsMethod This method returns a boolean indicating whether instances of 
  6923. a class respond to a given (static or dynamic) method. 
  6924.  
  6925. For backward compatibility, this method does not take an Environment parameter. 
  6926.  
  6927.  Syntax 
  6928.  
  6929.                     boolean somSupportsMethod (SOMClass receiver, somId methodId)
  6930.  
  6931.  Parameters 
  6932.  
  6933.           receiver (SOMClass) 
  6934.                     A pointer to the class object to be tested. 
  6935.  
  6936.           methodId (somId) 
  6937.                     An ID that represents the name of the method. 
  6938.  
  6939.  Returns 
  6940.  
  6941.           rc (boolean) 
  6942.                     Returns 1 (true) if instances of the specified class 
  6943.                     support the specified method, and 0 (false) otherwise. 
  6944.  
  6945.  Remarks 
  6946.  
  6947.           The somSupportsMethod method determines if instances of the specified 
  6948.           class respond to the specified (static or dynamic) method. 
  6949.  
  6950.  Original Class 
  6951.  
  6952.           SOMClass 
  6953.  
  6954.  Related Methods 
  6955.  
  6956.           Methods 
  6957.  
  6958.               somRespondsTo 
  6959.  
  6960.  Example Code 
  6961.  
  6962.                     /* ------------------------------------------------
  6963.                        Note:  animal supports a setSound method;
  6964.                               animal does not support a doTrick method.
  6965.                        ------------------------------------------------ */
  6966.                     #include <animal.h>
  6967.                     main()
  6968.                     {
  6969.                       SOMClass animalClass;
  6970.                       char *methodName1 = "setSound";
  6971.                       char *methodName2 = "doTrick";
  6972.                       animalClass =
  6973.                           AnimalNewClass(Animal_MajorVersion, Animal_MinorVersion);
  6974.                       if (_somSupportsMethod(animalClass,
  6975.                                              somIdFromString(methodName1)))
  6976.                           somPrintf("Animals respond to %s\n", methodName1);
  6977.                       if (_somSupportsMethod(animalClass,
  6978.                                               somIdFromString(methodName2)))
  6979.                           somPrintf("Animals respond to %s\n", methodName2);
  6980.                     }
  6981.  
  6982.                     /*
  6983.                     Output from this program:
  6984.                     Animals respond to setSound
  6985.                     */
  6986.  
  6987.  
  6988. ΓòÉΓòÉΓòÉ 2.100. SOMClassMgr ΓòÉΓòÉΓòÉ
  6989.  
  6990. SOMClassMgr 
  6991.  
  6992.  File stem: somcm 
  6993.  
  6994.  Base 
  6995.  
  6996.           SOMObject 
  6997.  
  6998.  Metaclass 
  6999.  
  7000.           SOMClass 
  7001.  
  7002.  Ancestor Classes 
  7003.  
  7004.                     SOMObject
  7005.  
  7006.  Description 
  7007.  
  7008.           One instance of SOMClassMgr is created automatically during SOM 
  7009.           initialization. This instance (pointed to by the global variable, 
  7010.           SOMClassMgrObject ) acts as a run-time registry for all SOM class 
  7011.           objects that exist within the current process and assists in the 
  7012.           dynamic loading and unloading of class libraries. 
  7013.  
  7014.           You can subclass SOMClassMgr to augment the functionality of its 
  7015.           registry. To have an instance of your subclass replace the 
  7016.           SOM-supplied SOMClassMgrObject, use the somMergeInto method to place 
  7017.           the existing registry information from SOMClassMgrObject into your 
  7018.           new class-manager object. 
  7019.  
  7020.           Types 
  7021.  
  7022.  
  7023.                     interface Repository;
  7024.                     SOMClass *SOMClassArray;
  7025.  
  7026.           Attributes 
  7027.  
  7028.           Listed below is each available attribute with its corresponding type 
  7029.           in parentheses, followed by a description of its purpose. 
  7030.  
  7031.           somInterfaceRepository (Repository) 
  7032.               The SOM Interface Repository object. If the Interface Repository 
  7033.               is not available or cannot be initialized, this attribute returns 
  7034.               NULL. When your program finishes using the Repository object, it 
  7035.               should call the somDestruct method to release the reference, 
  7036.               using a non-zero value for the doFree parameter. 
  7037.  
  7038.           somRegisteredClasses (sequence<SOMClass>) 
  7039.               This is a "readonly" attribute that returns a sequence containing 
  7040.               all of the class objects registered in the current process. When 
  7041.               you have finished using the returned sequence, you should free 
  7042.               the sequence's buffer using SOMFree. Here is a fragment of code 
  7043.               written in C that illustrates the proper use of this attribute: 
  7044.  
  7045.                             sequence(SOMClass) clsList;
  7046.  
  7047.                             clsList = SOMClassMgr__get_somRegisteredClasses (SOMClassMgrObject);
  7048.                             somPrintf ("Currently registered classes:\n");
  7049.                             for (i=0; i<clsList._length; i++)
  7050.                                somPrintf ("\t%s\n", SOMClass_somGetName (clsList._buffer[i]));
  7051.                             SOMFree (clsList._buffer);
  7052.  
  7053.  New Methods 
  7054.  
  7055.           The following list shows all the SOMClassMgr methods. 
  7056.  
  7057.           Group: Basic Functions: 
  7058.  
  7059.               somLoadClassFile 
  7060.               somLocateClassFile 
  7061.               somRegisterClass 
  7062.               somUnloadClassFile 
  7063.               somUnregisterClass 
  7064.  
  7065.           Group: Access: 
  7066.  
  7067.               somGetInitFunction 
  7068.               somGetRelatedClasses 
  7069.  
  7070.           Group: Dynamic: 
  7071.  
  7072.               somClassFormId 
  7073.               somFindClass 
  7074.               somFindClsInFile 
  7075.               somMergeInto 
  7076.               somSubstituteClass 
  7077.  
  7078.  Overridden Methods 
  7079.  
  7080.           The following list shows all the methods overridden by the 
  7081.           SOMClassMgr class. These methods are overridden in order to modify 
  7082.           the behavior defined by an ancestor class. 
  7083.  
  7084.               somDumpSelfInt 
  7085.               somInit 
  7086.               somUninit 
  7087.  
  7088.  
  7089. ΓòÉΓòÉΓòÉ 2.101. somClassFromId ΓòÉΓòÉΓòÉ
  7090.  
  7091. somClassFromId This method finds a class object, given its somId, if it already 
  7092. exists. Does not load the class. 
  7093.  
  7094. For backward compatibility, this method does not take an Environment parameter. 
  7095.  
  7096.  Syntax 
  7097.  
  7098.                     SOMClass somClassFromId (SOMClassMgr receiver, somId classId)
  7099.  
  7100.  Parameters 
  7101.  
  7102.           receiver (SOMClassMgr) 
  7103.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7104.                     user-supplied subclass of SOMClassMgr). 
  7105.  
  7106.           classId (somId) 
  7107.                     The somId of the class. This can be obtained from the name 
  7108.                     of the class using the somIdFromString function. 
  7109.  
  7110.  Returns 
  7111.  
  7112.           rc (SOMClass) 
  7113.                     Returns a pointer to the class, or  NULL if the class 
  7114.                     object does not yet exist. 
  7115.  
  7116.  Remarks 
  7117.  
  7118.           Finds a class object, given its somId, if it already exists. Does not 
  7119.           load the class. 
  7120.  
  7121.           Use the somClassFromId method instead of somFindClass when you do not 
  7122.           want the class to be automatically loaded if it does not already 
  7123.           exist in the current process. 
  7124.  
  7125.  Original Class 
  7126.  
  7127.           SOMClassMgr 
  7128.  
  7129.  Related Methods 
  7130.  
  7131.           Methods 
  7132.  
  7133.               somFindClass 
  7134.               somFindClsInFile 
  7135.  
  7136.  Example Code 
  7137.  
  7138.                     #include <som.h>
  7139.  
  7140.                     main () {
  7141.                         SOMClass myClass;
  7142.                         char *myClassName = "Animal";
  7143.                         somId animalId;
  7144.  
  7145.                         somEnvironmentNew ();
  7146.                         animalId = somIdFromString (myClassName);
  7147.                         myClass = SOMClassMgr_somClassFromId (SOMClassMgrObject,
  7148.                                                                                  animalId);
  7149.                         if (!myClass)
  7150.                             somPrintf ("Class %s has not been loaded.\n", myClassName);
  7151.                         SOMFree (animalId);
  7152.                             }
  7153.  
  7154.           This program produces the following output: 
  7155.  
  7156.                     Class Animal has not yet been loaded.
  7157.  
  7158.  
  7159. ΓòÉΓòÉΓòÉ 2.102. somFindClass ΓòÉΓòÉΓòÉ
  7160.  
  7161. somFindClass This method finds the class object for a class. 
  7162.  
  7163. For backward compatibility, this method does not take an Environment parameter. 
  7164.  
  7165.  Syntax 
  7166.  
  7167.                     SOMClass somFindClass (SOMClassMgr receiver, somId classId,
  7168.                                  long majorVersion, long minorVersion)
  7169.  
  7170.  Parameters 
  7171.  
  7172.           receiver (SOMClassMgr) 
  7173.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7174.                     user-supplied subclass of SOMClassMgr). 
  7175.  
  7176.           classId (somId) 
  7177.                     The somId representing the name of the class. 
  7178.  
  7179.           majorVersion (long) 
  7180.                     The class's major version number. 
  7181.  
  7182.           minorVersion (long) 
  7183.                     The class's minor version number. 
  7184.  
  7185.  Returns 
  7186.  
  7187.           rc (SOMClass) 
  7188.                     A pointer to the requested class object, or  NULL if the 
  7189.                     class could not be found or created. 
  7190.  
  7191.  Remarks 
  7192.  
  7193.           The somFindClass method returns the class object for the specified 
  7194.           class. This method first uses somLocateClassFile (see paragraph 
  7195.           below) to obtain the name of the file where the class's code resides, 
  7196.           then uses somFindClsInFile. 
  7197.  
  7198.           If the requested class has not yet been created, the somFindClass 
  7199.           method attempts to load the class dynamically by loading its 
  7200.           dynamically linked library and invoking its "new class" procedure. 
  7201.  
  7202.           The somLocateClassFile method uses the following steps: 
  7203.  
  7204.             1. If the entry in the Interface Repository for the class specified 
  7205.                by classId contains a dllname modifier, this value is used as 
  7206.                the file name for loading the library. (For information about 
  7207.                the dllname modifier, refer to the topic "Modifier statements" 
  7208.                in Chapter 4, "SOM IDL and the SOM Compiler," of the SOM 
  7209.                Programming Guide. 
  7210.  
  7211.             2. In the absence of a dllname modifier, the class name is assumed 
  7212.                to be the file name for the library. Use the somFindClsInFile 
  7213.                method if you wish to explicitly pass the file name as an 
  7214.                argument. 
  7215.  
  7216.           If majorVersion and minorVersion  are not both zero, they are used to 
  7217.           check the class version information against the caller's 
  7218.           expectations. An implementation is compatible with the specified 
  7219.           version numbers if it has the same major version number and a minor 
  7220.           version number that is equal to or greater than minorVersion. 
  7221.  
  7222.  Original Class 
  7223.  
  7224.           SOMClassMgr 
  7225.  
  7226.  Related Methods 
  7227.  
  7228.           Methods 
  7229.  
  7230.               somFindClsInFile 
  7231.               somLocateClassFile 
  7232.  
  7233.  Example Code 
  7234.  
  7235.                     #include <som.h>
  7236.  
  7237.                     /*
  7238.                      *  This program creates a class object
  7239.                      *  (from a DLL) without requiring the
  7240.                      *  usage binding file (.h or .xh) for
  7241.                      *  the class.
  7242.                      */
  7243.  
  7244.                     void main ()
  7245.                     {
  7246.                         SOMClass myClass;
  7247.                         somId animalId;
  7248.  
  7249.                         somEnvironmentNew ();
  7250.                         animalId = somIdFromString ("Animal");
  7251.  
  7252.                     /*  The next statement is equivalent to:
  7253.                      *    #include "animal.h"
  7254.                      *    myClass = AnimalNewClass (0, 0);
  7255.                      */
  7256.                         myClass = SOMClassMgr_somFindClass (SOMClassMgrObject,
  7257.                                                                      animalId, 0, 0);
  7258.                         if (myClass)
  7259.                             somPrintf ("myClass: %s\n", SOMClass_somGetName (myClass));
  7260.                         else
  7261.                             somPrintf ("Class %s could not be dynamically loaded\n",
  7262.                                                            somStringFromId (animalId));
  7263.                         SOMFree (animalId);
  7264.                     }
  7265.  
  7266.  
  7267. ΓòÉΓòÉΓòÉ 2.103. somFindClsInFile ΓòÉΓòÉΓòÉ
  7268.  
  7269. somFindClsInFile This method finds a class object for a class. 
  7270.  
  7271. For backward compatibility, this method does not take an Environment parameter. 
  7272.  
  7273.  Syntax 
  7274.  
  7275.                     SOMClass somFindClsInFile (SOMClassMgr receiver, somId classId,
  7276.                                    long majorVersion, long minorVersion,
  7277.                                    string file)
  7278.  
  7279.  Parameters 
  7280.  
  7281.           receiver (SOMClassMgr) 
  7282.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7283.                     user-supplied subclass of SOMClassMgr). 
  7284.  
  7285.           classId (somId) 
  7286.                     The somId representing the name of the class. 
  7287.  
  7288.           majorVersion (long) 
  7289.                     The class's major version number. 
  7290.  
  7291.           minorVersion (long) 
  7292.                     The class's minor version number. 
  7293.  
  7294.           file (string) 
  7295.                     A string representing the filename to be used if dynamic 
  7296.                     loading is required. 
  7297.  
  7298.  Returns 
  7299.  
  7300.           rc (SOMClass) 
  7301.                     A pointer to the requested class object, or NULL if the 
  7302.                     class could not be found or created. 
  7303.  
  7304.  Remarks 
  7305.  
  7306.           The somFindClsInFile method returns the class object for the 
  7307.           specified class. This method is the same as somFindClass except that 
  7308.           the caller provides the filename to be used if dynamic loading is 
  7309.           needed. 
  7310.  
  7311.           If the requested class has not yet been created the somFindClsInFile 
  7312.           method attempts to load the class dynamically by loading the 
  7313.           specified library and invoking its "new class" procedure. 
  7314.  
  7315.           If majorVersion and minorVersion are not both zero, they are used to 
  7316.           check the class version information against the caller's 
  7317.           expectations. An implementation is compatible with the specified 
  7318.           version numbers if it has the same major version number and a minor 
  7319.           version number that is equal to or greater than minorVersion. 
  7320.  
  7321.  Original Class 
  7322.  
  7323.           SOMClassMgr 
  7324.  
  7325.  Related Methods 
  7326.  
  7327.           Methods 
  7328.  
  7329.               somFindClass 
  7330.  
  7331.  Example Code 
  7332.  
  7333.                     #include <som.h>
  7334.                      /*                                            */
  7335.                      /*  This program loads a class and creates    */
  7336.                      /*  an instance of it without requiring the   */
  7337.                      /*  binding (.h) file for the class.          */
  7338.                      /*                                            */
  7339.                     void main()
  7340.                     {
  7341.                        SOMObject myAnimal;
  7342.                        SOMClass animalClass;
  7343.                        char *animalName = "Animal";
  7344.  
  7345.                             /*
  7346.                              * Filenames will be different for AIX and OS/2
  7347.                              * Set animalfile to "C:\\MYDLLS\\ANIMAL.DLL" for OS/2.
  7348.                              * Set animalfile to "/mydlls/animal.dll" for AIX.
  7349.                              */
  7350.  
  7351.                        char *animalFile = "/mydlls/animal.dll";     /* AIX filename */
  7352.  
  7353.                        somEnvironmentNew();
  7354.                        animalClass = _somFindClsInFile (SOMClassMgrObject,
  7355.                                                         somIdFromString(animalName),
  7356.                                                         0, 0,
  7357.                                                         animalFile);
  7358.                        myAnimal = _somNew (animalClass);
  7359.                        somPrintf("The class of myAnimal is %s.\.n",
  7360.                            _somGetClassName(myAnimal));
  7361.                        _somFree(myAnimal);
  7362.                     }
  7363.                        /*   Output from this program:  */
  7364.                        /*   The class of myAnimal is Animal. */
  7365.  
  7366.  
  7367. ΓòÉΓòÉΓòÉ 2.104. somGetInitFunction ΓòÉΓòÉΓòÉ
  7368.  
  7369. somGetInitFunction This method obtains the name of the function that 
  7370. initializes the SOM classes in a class library. 
  7371.  
  7372. For backward compatibility, this method does not take an Environment parameter. 
  7373.  
  7374.  Syntax 
  7375.  
  7376.                     string somGetInitFunction (SOMClassMgr receiver)
  7377.  
  7378.  Parameters 
  7379.  
  7380.           receiver (SOMClassMgr) 
  7381.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7382.                     user-supplied subclass of SOMClassMgr). 
  7383.  
  7384.  Returns 
  7385.  
  7386.           rc (string) 
  7387.                     Returns a string that names the initialization function of 
  7388.                     class libraries. By default, this name is the value of the 
  7389.                     global variable SOMClassInitFuncName, the default value of 
  7390.                     which is SOMInitModule. 
  7391.  
  7392.  Remarks 
  7393.  
  7394.           The somGetInitFunction method supplies the name of the initialization 
  7395.           function for OS/2 class libraries (DLLs) that contain more than one 
  7396.           SOM class. The default implementation returns the value of the global 
  7397.           variable SOMClassInitFuncName, which by default is set to the value 
  7398.           "SOMInitModule". 
  7399.  
  7400.           For AIX, the name of the class initialization function is not 
  7401.           important, since AIX class libraries should always be constructed as 
  7402.           shared libraries with a designated entry point which can be executed 
  7403.           automatically by the loader when the class is loaded.  Consequently, 
  7404.           the result of this method is not significant on AIX. 
  7405.  
  7406.           Similarly, if an OS/2 class library (DLL) has been constructed with a 
  7407.           DLL initialization function assigned by the linker, you can choose to 
  7408.           invoke the <className>NewClass functions for all of the classes in 
  7409.           the DLL during DLL initialization. In this case (as on AIX), there is 
  7410.           no need to export a "SOMInitModule" function. On the other hand, if 
  7411.           your compiler does not provide a convenient mechanism for creating a 
  7412.           DLL initialization function, you can elect to export a function named 
  7413.           "SOMInitModule" (or whatever name is ultimately returned by the 
  7414.           somGetInitFunction method). 
  7415.  
  7416.           The OS/2 SOMClassMgrObject, after loading a class library, will 
  7417.           invoke the method somGetInitFunction to obtain the name of a possible 
  7418.           initialization function. If this name has been exported by the class 
  7419.           library just loaded, the SOMClassMgrObject calls this function to 
  7420.           initialize the classes in the library. If the name has not been 
  7421.           exported by the DLL, the SOMClassMgrObject then looks for an exported 
  7422.           name of the form <className>NewClass, where <className> is the name 
  7423.           of the class supplied with the method that caused the DLL to be 
  7424.           loaded. If the DLL exports this name, it is invoked to create the 
  7425.           named class. 
  7426.  
  7427.           On Windows, the SOM class manager does not call SOMInitModule. It 
  7428.           must be called from the default Windows DLL initialization function, 
  7429.           LibMain. This call is made indirectly through the SOM_ClassLibrary 
  7430.           macro. 
  7431.  
  7432.           Regardless of the technique employed, the SOMClassMgrObject expects 
  7433.           that all classes packaged in a single class library will be created 
  7434.           during this sequence. 
  7435.  
  7436.           This method is generally not invoked directly by users. User-defined 
  7437.           subclasses of SOMClassMgr, however, can override this method. 
  7438.  
  7439.  Original Class 
  7440.  
  7441.           SOMClassMgr 
  7442.  
  7443.  Related Methods 
  7444.  
  7445.           Methods 
  7446.  
  7447.               somFindClass 
  7448.               somFindClsInFile 
  7449.  
  7450.           Functions 
  7451.  
  7452.               SOMInitModule 
  7453.  
  7454.           Macros 
  7455.  
  7456.               SOM_ClassLibrary 
  7457.  
  7458.  
  7459. ΓòÉΓòÉΓòÉ 2.105. somGetRelatedClasses ΓòÉΓòÉΓòÉ
  7460.  
  7461. somGetRelatedClasses This method returns an array of class objects that were 
  7462. all registered during the dynamic loading of a class. 
  7463.  
  7464. For backward compatibility, this method does not take an Environment parameter. 
  7465.  
  7466.  Syntax 
  7467.  
  7468.                     SOMClass *somGetRelatedClasses (SOMClassMgr receiver,
  7469.                                       SOMClass classObj)
  7470.  
  7471.  Parameters 
  7472.  
  7473.           receiver (SOMClassMgr) 
  7474.                     Usually a pointer to SOMClassMgrObject, or a pointer to an 
  7475.                     instance of a user-defined subclass of SOMClassMgr. 
  7476.  
  7477.           classObj (SOMClass) 
  7478.                     A pointer to a SOMClass object. 
  7479.  
  7480.  Returns 
  7481.  
  7482.           rc (SOMClass *) 
  7483.                     Returns a pointer to an array of pointers to class objects, 
  7484.                     or NULL, if the specified class was not dynamically loaded. 
  7485.  
  7486.  Remarks 
  7487.  
  7488.           The somGetRelatedClasses method returns an array of class objects 
  7489.           that were all registered during the dynamic loading of the specified 
  7490.           class. These classes are considered to define an affinity group. Any 
  7491.           class is a member of at most one affinity group. The affinity group 
  7492.           returned by this call is the one containing the class identified by 
  7493.           the classObj parameter. 
  7494.  
  7495.           The first element in the array is either the class that caused the 
  7496.           group to be loaded, or the special value -1, which means that the 
  7497.           class manager is currently in the process of unregistering and 
  7498.           deleting the affinity group (only class-manager objects would ever 
  7499.           see this value). The remainder of the array consists of pointers to 
  7500.           class objects, ordered in reverse chronological sequence to that in 
  7501.           which they were originally registered. This list includes the given 
  7502.           argument, classObj, as one of its elements, as well as the class that 
  7503.           caused the group to be loaded (also given by the first element of the 
  7504.           array). The array is terminated by a NULL pointer as the last 
  7505.           element. 
  7506.  
  7507.           Use SOMFree to release the array when it is no longer needed. If the 
  7508.           supplied class was not dynamically loaded, it is not a member of any 
  7509.           affinity group and NULL is returned. 
  7510.  
  7511.  Original Class 
  7512.  
  7513.           SOMClassMgr 
  7514.  
  7515.  Related Methods 
  7516.  
  7517.           Methods 
  7518.  
  7519.               somGetInitFunction 
  7520.  
  7521.  Example Code 
  7522.  
  7523.                     #include <som.h>
  7524.                     SOMClass myClass, *relatedClasses;
  7525.                     string className;
  7526.                     long i;
  7527.  
  7528.                     className = SOMClass_somGetName (myClass));
  7529.                     relatedClasses = SOMClassMgr_somGetRelatedClasses
  7530.                                                     (SOMClassMgrObject, myClass);
  7531.                     if (relatedClasses && *relatedClasses) {
  7532.                         somPrintf ("Class=%s, related classes are: ", className);
  7533.                         for (i=1; relatedClasses[i]; i++)
  7534.                             somPrintf ("%s ",SOMClass_somGetName (relatedClasses[i]));
  7535.                         somPrintf ("\n");
  7536.                         somPrintf ("Class that caused loading was %s\n",
  7537.                             relatedClasses[0] == (SOMClass) -1 ? "-1" :
  7538.                                 SOMClass_somGetName (relatedClasses[0]));
  7539.                         SOMFree (relatedClasses);
  7540.                     } else
  7541.                         somPrintf ("No classes related to %s\n", className);
  7542.  
  7543.  
  7544. ΓòÉΓòÉΓòÉ 2.106. somLoadClassFile ΓòÉΓòÉΓòÉ
  7545.  
  7546. somLoadClassFile This method dynamically loads a class. 
  7547.  
  7548. For backward compatibility, this method does not take an Environment parameter. 
  7549.  
  7550.  Syntax 
  7551.  
  7552.                     SOMClass somLoadClassFile (SOMClassMgr receiver, somID classId,
  7553.                                     long majorVersion, long minorVersion,
  7554.                                     string file)
  7555.  
  7556.  Parameters 
  7557.  
  7558.           receiver (SOMClassMgr) 
  7559.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7560.                     user-supplied subclass of SOMClassMgr). 
  7561.  
  7562.           classId (somID) 
  7563.                     The somId representing the name of the class to load. 
  7564.  
  7565.           majorVersion (long) 
  7566.                     The major version number used to check the compatibility of 
  7567.                     the class's implementation with the caller's expectations. 
  7568.  
  7569.           minorVersion (long) 
  7570.                     The minor version number used to check the compatibility of 
  7571.                     the class's implementation with the caller's expectations. 
  7572.  
  7573.           file (string) 
  7574.                     The name of the dynamically linked library file containing 
  7575.                     the class. The name can be either a simple, unqualified 
  7576.                     name (without any extension) or a fully qualified (or path) 
  7577.                     file name, as appropriate for your operating system. For 
  7578.                     example, on OS/2, file could be 
  7579.                     c:\myhome\myapp\basename.dll or else basename (but not 
  7580.                     basename.dll). 
  7581.  
  7582.  Returns 
  7583.  
  7584.           rc (SOMClass) 
  7585.                     Returns a pointer to the class object, or NULL if the class 
  7586.                     could not be loaded or the class object could not be 
  7587.                     created. 
  7588.  
  7589.  Remarks 
  7590.  
  7591.           The SOMClassMgr object uses the somLoadClassFile method to load a 
  7592.           class dynamically during the execution of somFindClass or 
  7593.           somFindClsInFile. A SOM class object representing the class is 
  7594.           expected to be created and registered as a result of this method. 
  7595.  
  7596.           The somLoadClassFile method can be overridden to load or create 
  7597.           classes dynamically using your own mechanisms.  If you simply wish to 
  7598.           change the name of the procedure that is called to initialize the 
  7599.           classes in a library, override somGetInitFunction  instead. 
  7600.  
  7601.           This method is provided to permit user-created subclasses of 
  7602.           SOMClassMgr to handle the loading of classes by overriding this 
  7603.           method. Do not invoke this method directly; instead, use somFindClass 
  7604.           or somFindClsInFile. 
  7605.  
  7606.  Original Class 
  7607.  
  7608.           SOMClassMgr 
  7609.  
  7610.  Related Methods 
  7611.  
  7612.           Methods 
  7613.  
  7614.               somFindClass 
  7615.               somFindClsInFile 
  7616.               somGetInitFunction 
  7617.               somUnloadClassFile 
  7618.  
  7619.  
  7620. ΓòÉΓòÉΓòÉ 2.107. somLocateClassFile ΓòÉΓòÉΓòÉ
  7621.  
  7622. somLocateClassFile This method determines the file that holds a class to be 
  7623. dynamically loaded. 
  7624.  
  7625. For backward compatibility, this method does not take an Environment parameter. 
  7626.  
  7627.  Syntax 
  7628.  
  7629.                     string somLocateClassFile (SOMClassMgr receiver, somId classId,
  7630.                                    long majorVersion, long minorVersion)
  7631.  
  7632.  Parameters 
  7633.  
  7634.           receiver (SOMClassMgr) 
  7635.                     Usually SOMClassMgrObject (or a pointer to an instance of a 
  7636.                     user-supplied subclass of SOMClassMgr). 
  7637.  
  7638.           classId (somId) 
  7639.                     The somId representing the name of the class to locate. 
  7640.  
  7641.           majorVersion (long) 
  7642.                     The major version number used to check the compatibility of 
  7643.                     the class's implementation with the caller's expectations. 
  7644.  
  7645.           minorVersion (long) 
  7646.                     The minor version number used to check the compatibility of 
  7647.                     the class's implementation with the caller's expectations. 
  7648.  
  7649.  Returns 
  7650.  
  7651.           rc (string) 
  7652.                     Returns the name of the file containing the class. 
  7653.  
  7654.  Remarks 
  7655.  
  7656.           The SOMClassMgr object uses the somLocateClassFile method when 
  7657.           executing somFindclass to obtain the name of a file to use when 
  7658.           dynamically loading a class. The default implementation consults the 
  7659.           Interface Repository for the value of the dllname modifier of the 
  7660.           class; if no dllname modifier was specified, the method simply 
  7661.           returns the class name as the expected filename. 
  7662.  
  7663.           If you override the somLocateClassFile method in a user-supplied 
  7664.           subclass of SOMClassMgr, the name you return can be either a simple, 
  7665.           unqualified name without any extension or a fully-qualified file 
  7666.           name. Generally speaking, you would not invoke this method directly. 
  7667.           It is provided to permit customization of subclasses of SOMClassMgr 
  7668.           through overriding. 
  7669.  
  7670.  Original Class 
  7671.  
  7672.           SOMClassMgr 
  7673.  
  7674.  Related Methods 
  7675.  
  7676.           Methods 
  7677.  
  7678.               somFindClass 
  7679.               somFindClsInFile 
  7680.               somGetInitFunction 
  7681.               somLoadClassFile 
  7682.               somUnloadClassFile 
  7683.  
  7684.  
  7685. ΓòÉΓòÉΓòÉ 2.108. somMergeInto ΓòÉΓòÉΓòÉ
  7686.  
  7687. somMergeInto 
  7688.  
  7689. This method transfers SOM class registry information to another SOMClassMgr 
  7690. instance. 
  7691.  
  7692. Note:  For backward compatibility, this method does not take an Environment 
  7693. parameter. 
  7694.  
  7695.  Syntax 
  7696.  
  7697.                     void somMergeInto (SOMClassMgr receiver, SOMClassMgr target)
  7698.  
  7699.  Parameters 
  7700.  
  7701.           receiver (SOMClassMgr) 
  7702.                     Usually SOMClassMgrObject  (or a pointer to an instance of 
  7703.                     a user-supplied subclass of SOMClassMgr). 
  7704.  
  7705.           target (SOMClassMgr) 
  7706.                     A pointer to another instance of SOMClassMgr or one of its 
  7707.                     subclasses. 
  7708.  
  7709.  Returns 
  7710.  
  7711.           rc (void) 
  7712.  
  7713.  Remarks 
  7714.  
  7715.           The somMergeInto method transfers the SOMClassMgr registry 
  7716.           information from one object to another. The target object is required 
  7717.           to be an instance of SOMClassMgr or one of its subclasses. At the 
  7718.           completion of this operation, the target object can function as a 
  7719.           replacement for the receiver. The receiver object (which is then in a 
  7720.           newly uninitialized state) is placed in a mode where all methods 
  7721.           invoked on it will be delegated to the target object. If the 
  7722.           receiving object is the instance pointed to by the global variable 
  7723.           SOMClassMgrObject, then SOMClassMgrObject is reassigned to point to 
  7724.           the target object. 
  7725.  
  7726.           Subclasses of SOMClassMgr that override the somMergeInto method 
  7727.           should transfer their section of the class manager object from the 
  7728.           target to the receiver, then invoke their parent's somMergeInto 
  7729.           method as the final step. 
  7730.  
  7731.           Invoke this method only if you are creating your own subclass of 
  7732.           SOMClassMgr. You can invoke somMergeInto from an initializer for your 
  7733.           new class manager. 
  7734.  
  7735.  Original Class 
  7736.  
  7737.           SOMClassMgr 
  7738.  
  7739.  Example Code 
  7740.  
  7741.                     // === IDL For the New Class Manager ===
  7742.  
  7743.                     #include <somcm.idl>
  7744.  
  7745.                     interface NewCM  :  SOMClassMgr {
  7746.                             implementation   {
  7747.                                     somDefaultInit:  override;
  7748.                            };
  7749.                     };
  7750.  
  7751.                     // === C++ implementation for NewCM ===
  7752.  
  7753.                     #define SOM_Module_merge_Source
  7754.                     #include "merge.xih"
  7755.                     SOM_Scope void SOMLINK somDefaultInit(NewCM *somSelf,
  7756.                                                                             somInitCtrl* ctrl)
  7757.                     {
  7758.                             NewCMData *somThis;   /* set in BeginInitializer */
  7759.                             somInitCtrl globalCtrl;
  7760.                             somBooleanVector myMask;
  7761.                             NewCMMethodDebug ("NewCM","somDefaultInit");
  7762.                             NewCM_BeginInitializer_somDefaultInit;
  7763.  
  7764.                             NewC_Init_SOMClassMgr_somDefaultInit(somSelf, ctrl);
  7765.  
  7766.                             /*
  7767.                              *  local NewCM initialization code added by programmer
  7768.                              */
  7769.  
  7770.                             SOMClassMgrObject->somMergeInto(somSelf);
  7771.                     }
  7772.  
  7773.  
  7774.                     // === C++ test program ===
  7775.  
  7776.                     #include <merge.xh>
  7777.                     main()
  7778.                     {
  7779.                             NewCM *ncm = new NewCM;
  7780.                             SOMClassMgrObject->somDumpSelf(0);
  7781.                     }
  7782.  
  7783.                     // === Output from test program ===
  7784.  
  7785.                     {An instance of class NewCM at address 20084388
  7786.                      1 classIdSpaceSize:  3200
  7787.                      1 classIdHashTableSize:  397
  7788.                      1 loadAffinity:  0
  7789.                      1 nextLoadAffinity:  1
  7790.                      1 IR Class:  00000000,  IR Object:  00000000
  7791.                      1          -Class-- -Token-- Aff Seq ---Id--- Name
  7792.                      1 ╤ì    0ΓêÖ 20077A48 00000000 000 001 2008260C SOMObject
  7793.                      1 ╤ì    1ΓêÖ 2007FB38 00000000 000 000 200825EC SOMClassMgr
  7794.                      1 ╤ì    2ΓêÖ 20083B08 00000000 000 004 2008436C NewCM
  7795.                      1 ╤ì    3ΓêÖ 20077BD8 00000000 000 002 2008262C SOMClass
  7796.                      1 ╤ì    4ΓêÖ 20082668 00000000 000 003 2008315C
  7797.                      SOMParentDerivedMetaclass
  7798.                     }
  7799.  
  7800.  
  7801. ΓòÉΓòÉΓòÉ 2.109. somRegisterClass ΓòÉΓòÉΓòÉ
  7802.  
  7803. somRegisterClass 
  7804.  
  7805. This method adds a class object to the SOM run-time class registry. 
  7806.  
  7807. Note:  For backward compatibility, this method does not take an Environment 
  7808. parameter. 
  7809.  
  7810.  Syntax 
  7811.  
  7812.                     void somRegisterClass (SOMClassMgr receiver, SOMClass classObj)
  7813.  
  7814.  Parameters 
  7815.  
  7816.           receiver (SOMClassMgr) 
  7817.                     Usually SOMClassMgrObject  (or a pointer to an instance of 
  7818.                     a user-supplied subclass of SOMClassMgr). 
  7819.  
  7820.           classObj (SOMClass) 
  7821.                     A pointer to the class object to add to the SOM class 
  7822.                     registry. 
  7823.  
  7824.  Returns 
  7825.  
  7826.           rc (void) 
  7827.  
  7828.  Remarks 
  7829.  
  7830.           The somRegisterClass method adds a class object to the SOM run-time 
  7831.           class registry maintained by SOMClassMgrObject. 
  7832.  
  7833.           All SOM run-time class objects should be registered with the 
  7834.           SOMClassMgrObject. This is done automatically during the execution of 
  7835.           the somClassReady method as class objects are created. 
  7836.  
  7837.  Original Class 
  7838.  
  7839.           SOMClassMgr 
  7840.  
  7841.  Related Methods 
  7842.  
  7843.           Methods: 
  7844.  
  7845.               somUnregisterClass 
  7846.  
  7847.  
  7848. ΓòÉΓòÉΓòÉ 2.110. somSubstituteClass ΓòÉΓòÉΓòÉ
  7849.  
  7850. somSubstituteClass 
  7851.  
  7852. This method causes the somFindClass, somFindClsInFile, and somClassFromId 
  7853. methods to substitute one class for another. 
  7854.  
  7855. Note:  For backward compatibility, this method does not take an Environment 
  7856. parameter. 
  7857.  
  7858.  Syntax 
  7859.  
  7860.                     long somSubstituteClass (SOMClassMgr receiver, string origClassName,
  7861.                                   string newClassName)
  7862.  
  7863.  Parameters 
  7864.  
  7865.           receiver (SOMClassMgr) 
  7866.                     Usually SOMClassMgrObject  or a pointer to an instance of a 
  7867.                     user-defined subclass of SOMClassMgr. 
  7868.  
  7869.           origClassName (string) 
  7870.                     A NULL terminated string containing the old class name. 
  7871.  
  7872.           newClassName (string) 
  7873.                     A NULL terminated string containing the new class name. 
  7874.  
  7875.  Returns 
  7876.  
  7877.           rc (long) 
  7878.                     The somSubstituteClass method returns a value of zero to 
  7879.                     indicate success; a non-zero value indicates an error was 
  7880.                     detected. 
  7881.  
  7882.  Remarks 
  7883.  
  7884.           The somSubstituteClass method causes the somFindClass, 
  7885.           somFindClsInFile, and somClassFromId methods to return the class 
  7886.           named newClassName whenever they would normally return the class 
  7887.           named origClassName. This effectively results in class newClassName 
  7888.           replacing or substituting for class origClassName. For example, the 
  7889.           <origClassName>New macro will subsequently create instances of 
  7890.           newClassName. 
  7891.  
  7892.           Some restrictions are enforced to ensure that this works well. Both 
  7893.           class origClassName and class newClassName must have been already 
  7894.           registered before issuing this method, and newClass must be an 
  7895.           immediate child of origClass. In addition (although not enforced), no 
  7896.           instances should exist of either class at the time this method is 
  7897.           invoked. 
  7898.  
  7899.           A convenience macro (SOM_SubstituteClass) is provided for C or C++ 
  7900.           users. In one operation, it creates both the old and the new class 
  7901.           and then substitutes the new one in place of the old. The use of both 
  7902.           the somSubstituteClass method and the SOM_SubstituteClass macro is 
  7903.           illustrated in the example below. 
  7904.  
  7905.  Original Class 
  7906.  
  7907.           SOMClassMgr 
  7908.  
  7909.  Related Methods 
  7910.  
  7911.           Methods: 
  7912.  
  7913.               somClassFromId 
  7914.               somFindClass 
  7915.               somFindClsInFile 
  7916.               somMergeInto 
  7917.  
  7918.  Example Code 
  7919.  
  7920.                     #include <student.h>
  7921.                     #include <mystud.h>
  7922.  
  7923.                     /* Macro form */
  7924.                     SOM_SubstituteClass (Student, MyStudent);
  7925.                     /* Direct use of the method, equivalent to
  7926.                      * the macro form above.
  7927.                      */
  7928.                     {
  7929.                     SOMClass origClass, replacementClass;
  7930.  
  7931.                     origClass = StudentNewClass (Student_MajorVersion,
  7932.                                                             Student_MinorVersion);
  7933.                     replacementClass = MyStudentNewClass (MyStudent_MajorVersion,
  7934.                                                           MyStudent_MinorVersion);
  7935.                     SOMClassMgr_somSubstituteClass (
  7936.                         SOMClass_somGetName (origClass),
  7937.                         SOMClass_somGetName (replacementClass));
  7938.                     }
  7939.  
  7940.  
  7941. ΓòÉΓòÉΓòÉ 2.111. somUnloadClassFile ΓòÉΓòÉΓòÉ
  7942.  
  7943. somUnloadClassFile 
  7944.  
  7945. This method unloads a dynamically loaded class and frees the class's object. 
  7946.  
  7947. Note:  For backward compatibility, this method does not take an Environment 
  7948. parameter. 
  7949.  
  7950.  Syntax 
  7951.  
  7952.                     long somUnloadClassFile (SOMClassMgr receiver, SOMClass class)
  7953.  
  7954.  Parameters 
  7955.  
  7956.           receiver (SOMClassMgr) 
  7957.                     Usually SOMClassMgrObject  (or a pointer to an instance of 
  7958.                     a user-supplied subclass of SOMClassMgr). 
  7959.  
  7960.           class (SOMClass) 
  7961.                     A pointer to the class to be unloaded. 
  7962.  
  7963.  Returns 
  7964.  
  7965.           rc (long) 
  7966.                     The somUnloadClassFile method returns 0 if the class was 
  7967.                     successfully unloaded; otherwise, it returns a 
  7968.                     system-specific non-zero error code from either the OS/2 
  7969.                     DosFreeModule or the AIX unload system call. 
  7970.  
  7971.  Remarks 
  7972.  
  7973.           The somUnregisterClass method uses the somUnloadClassFile method to 
  7974.           unload a dynamically loaded class. This releases the class's code and 
  7975.           unregisters all classes in the same affinity group. (Use 
  7976.           somGetRelatedClasses to find out which other classes are in the same 
  7977.           affinity group.) 
  7978.  
  7979.           The class object is freed whether or not the class' s shared library 
  7980.           could be unloaded. If the class was not registered, an error 
  7981.           condition is raised and SOMError is invoked. This method is provided 
  7982.           to permit user-created subclasses of SOMClassMgr  to handle the 
  7983.           unloading of classes by overriding this method. Do not invoke this 
  7984.           method directly; instead, invoke somUnregisterClass. 
  7985.  
  7986.  Original Class 
  7987.  
  7988.           SOMClassMgr 
  7989.  
  7990.  Related Methods 
  7991.  
  7992.           Methods: 
  7993.  
  7994.               somLoadClassFile 
  7995.               somRegisterClass 
  7996.               somUnregisterClass 
  7997.               somGetRelatedClasses 
  7998.  
  7999.  
  8000. ΓòÉΓòÉΓòÉ 2.112. somUnregisterClass ΓòÉΓòÉΓòÉ
  8001.  
  8002. somUnregisterClass 
  8003.  
  8004. This method removes a class object from the SOM run-time class registry. 
  8005.  
  8006. Note:  For backward compatibility, this method does not take an Environment 
  8007. parameter. 
  8008.  
  8009.  Syntax 
  8010.  
  8011.                     long somUnregisterClass (SOMClassMgr receiver, SOMClass class)
  8012.  
  8013.  Parameters 
  8014.  
  8015.           receiver (SOMClassMgr) 
  8016.                     Usually SOMClassMgrObject  (or a pointer to an instance of 
  8017.                     a user-supplied subclass of SOMClassMgr). 
  8018.  
  8019.           class (SOMClass) 
  8020.                     A pointer to the class to be unregistered. 
  8021.  
  8022.  Returns 
  8023.  
  8024.           rc (long) 
  8025.                     The somUnregisterClass method returns 0 for a successful 
  8026.                     completion, or non-zero to denote failure. 
  8027.  
  8028.  Remarks 
  8029.  
  8030.           The somUnregisterClass method unregisters a SOM class and frees the 
  8031.           class object. If the class was dynamically loaded, it is also 
  8032.           unloaded using somUnloadClassFile (which causes its entire affinity 
  8033.           group to be unloaded as well). 
  8034.  
  8035.  Original Class 
  8036.  
  8037.           SOMClassMgr 
  8038.  
  8039.  Related Methods 
  8040.  
  8041.           Methods: 
  8042.  
  8043.               somLoadClassFile 
  8044.               somRegisterClass 
  8045.               somUnloadClassFile 
  8046.  
  8047.  Example Code 
  8048.  
  8049.                     #include <som.h>
  8050.  
  8051.                     void main ()
  8052.                     {
  8053.                         long rc;  /* Return code */
  8054.                         SOMClass animalClass;
  8055.  
  8056.                         /* The next 2 lines declare a static form of somId */
  8057.                         string animalClassName = "Animal";
  8058.                         somId animalId = &animalClassName;
  8059.  
  8060.                         somEnvironmentNew ();
  8061.                         animalClass = SOMClassMgr_somFindClass (SOMClassMgrObject,
  8062.                                                                     animalId, 0, 0);
  8063.                         if (!animalClass) {
  8064.                            somPrintf ("Could not load class.\n");
  8065.                            return;
  8066.                         }
  8067.                         rc = SOMClassMgr_somUnregisterClass (SOMClassMgrObject,
  8068.                                                                        animalClass);
  8069.                         if (rc)
  8070.                             somPrintf ("Could not unregister class, error code: %ld.\n",
  8071.                                                                                     rc);
  8072.                         else
  8073.                             somPrintf ("Class successfully unloaded.\n");
  8074.                     }
  8075.  
  8076.  
  8077. ΓòÉΓòÉΓòÉ 2.113. SOMObject ΓòÉΓòÉΓòÉ
  8078.  
  8079. SOMObject 
  8080.  
  8081.  File stem: somobj 
  8082.  
  8083.  Base 
  8084.  
  8085.           None. 
  8086.  
  8087.  Metaclass 
  8088.  
  8089.           SOMClass 
  8090.  
  8091.  Ancestor Classes 
  8092.  
  8093.                     None
  8094.  
  8095.  Description 
  8096.  
  8097.           SOMObject is the root class for all SOM classes. That is, all SOM 
  8098.           classes must be subclasses of SOMObject or of some other class 
  8099.           derived from SOMObject. SOMObject introduces no instance data, so 
  8100.           objects whose classes inherit from SOMObject  incur no size increase. 
  8101.           They do inherit a suite of methods that provide the behavior required 
  8102.           of all SOM objects. Three of these methods are typically overridden 
  8103.           by any subclass that has instance data- somDefaultInit, somDestruct, 
  8104.           and somDumpSelfInt. See the descriptions of these methods for further 
  8105.           information. 
  8106.  
  8107.  New Methods 
  8108.  
  8109.           The following list shows all the SOMObject methods. 
  8110.  
  8111.           Group: Initialization/Termination: 
  8112.  
  8113.               somFree 
  8114.               somDefaultInit 
  8115.               somDestruct 
  8116.               somInit 
  8117.               somUninit 
  8118.               somDefaultAssign 
  8119.               somDefaultConstAssign 
  8120.               somDefaultConstCopyInit 
  8121.               somDefaultCopyInit 
  8122.  
  8123.           Group: Access: 
  8124.  
  8125.               somGetClass 
  8126.               somGetClassName 
  8127.               somGetSize 
  8128.  
  8129.           Group: Testing: 
  8130.  
  8131.               somIsA 
  8132.               somIsInstanceOf 
  8133.               somRespondsTo 
  8134.  
  8135.           Group: Dynamic: 
  8136.  
  8137.               somDispatchA 
  8138.               somDispatchD 
  8139.               somDispatchL 
  8140.               somDispatchV 
  8141.               somDispatch 
  8142.               somClassDispatch 
  8143.               somCastObj 
  8144.               somResetObj 
  8145.  
  8146.           Group: Developer Support: 
  8147.  
  8148.               somDumpSelf 
  8149.               somDumpSelfInt 
  8150.               somPrintSelf 
  8151.  
  8152.  Overridden Methods 
  8153.  
  8154.           There are currently no overridden methods defined for the SOMObject 
  8155.           class. 
  8156.  
  8157.  
  8158. ΓòÉΓòÉΓòÉ 2.114. somCastObj ΓòÉΓòÉΓòÉ
  8159.  
  8160. somCastObj This method changes the behavior of an object to that defined by any 
  8161. ancestor of the true class of the object. 
  8162.  
  8163.  Syntax 
  8164.  
  8165.                     boolean somCastObj (SOMObject receiver, SOMClass ancestor)
  8166.  
  8167.  Parameters 
  8168.  
  8169.           receiver (SOMObject) 
  8170.                     A pointer to an object of type SOMObject. 
  8171.  
  8172.           ancestor (SOMClass) 
  8173.                     A pointer to a class that is an ancestor of the actual 
  8174.                     class of the receiver. 
  8175.  
  8176.  Returns 
  8177.  
  8178.           rc (boolean) 
  8179.  
  8180.                     TRUE           Returns 1 (TRUE) if the operation is 
  8181.                                    successful. 
  8182.                     FALSE          Returns 0 (false) if the operation is not 
  8183.                                    successful. The operation fails if ancestor 
  8184.                                    is not actually an ancestor of the class of 
  8185.                                    the object. 
  8186.  
  8187.  Remarks 
  8188.  
  8189.           This method changes the behavior of an object so that its behavior 
  8190.           will be that of an instance of the indicated ancestor class (with 
  8191.           respect to any method supported by the ancestor). The behavior of the 
  8192.           object on methods not supported by the ancestor remains unchanged. 
  8193.  
  8194.           This operation actually changes the class of the object (since an 
  8195.           object's behavior is defined by its class). The name of the new class 
  8196.           is derived from the initial name of the object's class and the name 
  8197.           of the ancestor class, as illustrated in the Example. 
  8198.  
  8199.           This method may be used on an object multiple times, always with the 
  8200.           restriction that the ancestor class whose behavior is selected is 
  8201.           actually an ancestor of the true (original) class of the object. 
  8202.  
  8203.  Original Class 
  8204.  
  8205.           SOMObject 
  8206.  
  8207.  Related Methods 
  8208.  
  8209.           Methods 
  8210.  
  8211.               somResetObj 
  8212.  
  8213.  Example Code 
  8214.  
  8215.                     #include <som.h>
  8216.                     main()
  8217.                     {
  8218.                        SOMClassMgr cm = somEnvironmentNew();
  8219.                        SOM_Test(1 == _somCastObj(cm, _SOMObject));
  8220.                        _somDumpSelf(cm, 0));
  8221.                        SOM_Test(1 == _somResetObj(cm));
  8222.                        _somDumpSelf(cm, 0);
  8223.                     }
  8224.  
  8225.                     /* output:
  8226.                      *  {An instance of class SOMClassMgr->SOMObject
  8227.                      *   at address 20061268
  8228.                      *  }
  8229.                      *  {An instance of class SOMClassMgr at address 20061268
  8230.                      *   ... <SOMClassMgr State Information> ...
  8231.                      *  }
  8232.                      */
  8233.  
  8234.  
  8235. ΓòÉΓòÉΓòÉ 2.115. somDefaultAssign ΓòÉΓòÉΓòÉ
  8236.  
  8237. somDefaultAssign This method provides support for an object-assignment 
  8238. operator. May be overridden, but, if appropriate, somDefaultConstAssign should 
  8239. be overridden instead. 
  8240.  
  8241.  Syntax 
  8242.  
  8243.                     void somDefaultAssign (SOMObject receiver, somInitCtrl ctrl,
  8244.                                  SOMObject fromObj)
  8245.  
  8246.  Parameters 
  8247.  
  8248.           receiver (SOMObject) 
  8249.                     A pointer to an object of an arbitrary SOM class, S. 
  8250.  
  8251.           ctrl (somInitCtrl) 
  8252.                     A pointer to a somInitCtrl structure, or NULL. 
  8253.  
  8254.           fromObj (SOMObject) 
  8255.                     A pointer to an object of class S or some class descended 
  8256.                     from S. 
  8257.  
  8258.  Returns 
  8259.  
  8260.           rc (void) 
  8261.  
  8262.  Remarks 
  8263.  
  8264.           In C++, assignment to an object of class "X" is accomplished by using 
  8265.           (an appropriate overloading of) the assignment operator provided by 
  8266.           "X". To make assignment available on all SOM objects, SOMObject 
  8267.           provides the somDefaultAssign and somDefaultConstAssign methods. The 
  8268.           default behavior of these methods is that they do a shallow copy of 
  8269.           data from one object to another. Users should generally use the 
  8270.           somDefaultAssign method for doing object assignment. 
  8271.  
  8272.           When a shallow copy is not appropriate for the data introduced by a 
  8273.           class, and it is possible to perform the copy without modifying 
  8274.           fromObj, it is recommended that the class implementor override the 
  8275.           somDefaultConstAssign method for that class. 
  8276.  
  8277.           The considerations important to overriding somDefaultAssign are 
  8278.           similar to those described in the SOM Programming Guide for 
  8279.           overriding somDefaultInit. (See "Initializing and Uninitializing 
  8280.           Objects" in Chapter 5, "Implementing Classes in SOM.") The basic 
  8281.           difference between somDefaultInit and somDefaultAssign is that the 
  8282.           latter method takes an object (fromObj) as a source argument for 
  8283.           assignment of values to the receiver. 
  8284.  
  8285.  Original Class 
  8286.  
  8287.           SOMObject 
  8288.  
  8289.  Related Methods 
  8290.  
  8291.           Methods 
  8292.  
  8293.               somDefaultInit 
  8294.               somDefaultConstAssign 
  8295.               somDefaultCopyInit 
  8296.               somDefaultConstCopyInit 
  8297.  
  8298.  Example Code 
  8299.  
  8300.                     // C++ SOMObjects Toolkit Code
  8301.                     #include <Y.xh>
  8302.  
  8303.                     main()
  8304.                     {
  8305.                             X *x = new X;
  8306.                             Y *y = new Y;  // assume Y is derived from X
  8307.                             x->somDefaultAssign(0,y)
  8308.                             //  the x object has now been assigned values from y
  8309.                     }
  8310.  
  8311.  
  8312. ΓòÉΓòÉΓòÉ 2.116. somDefaultConstAssign ΓòÉΓòÉΓòÉ
  8313.  
  8314. somDefaultConstAssign Provides support for a "const" object-assignment 
  8315. operator. Designed to be overridden. 
  8316.  
  8317.  Syntax 
  8318.  
  8319.                     void somDefaultConstAssign (SOMObject receiver, somInitCtrl ctrl,
  8320.                                     SOMObject fromObj)
  8321.  
  8322.  Parameters 
  8323.  
  8324.           receiver (SOMObject) 
  8325.                     A pointer to an object of an arbitrary SOM class, S. 
  8326.  
  8327.           ctrl (somInitCtrl) 
  8328.                     A pointer to a somInitCtrl structure, or NULL. 
  8329.  
  8330.           fromObj (SOMObject) 
  8331.                     A pointer to an object of class S or some class descended 
  8332.                     from S. 
  8333.  
  8334.  Returns 
  8335.  
  8336.           rc (void) 
  8337.  
  8338.  Remarks 
  8339.  
  8340.           In C++, assignment to an object of class "X" is accomplished by using 
  8341.           (an appropriate overloading of) the assignment operator provided by 
  8342.           "X". To make assignment available on all SOM objects, SOMObject 
  8343.           introduces the somDefaultAssign and somDefaultConstAssign methods. 
  8344.           The default behavior of these methods is to perform a shallow copy of 
  8345.           data from one object to another. When this default is not appropriate 
  8346.           for a class, and it is possible to perform the copy without modifying 
  8347.           fromObj, it is recommended that the class implementor override the 
  8348.           somDefaultConstAssign method. 
  8349.  
  8350.           Generally, an object user should use the somDefaultAssign method to 
  8351.           perform object assignment. 
  8352.  
  8353.           The considerations important to overriding somDefaultConstAssign are 
  8354.           similar to those described in the SOM Programming Guide for 
  8355.           overriding somDefaultInit. (See "Initializing and Uninitializing 
  8356.           Objects" in Chapter 5, "Implementing Classes in SOM.") The basic 
  8357.           difference between somDefaultInit and somDefaultConstAssign is that 
  8358.           the latter method takes an object (fromObj) as an argument that is to 
  8359.           be copied. 
  8360.  
  8361.  Original Class 
  8362.  
  8363.           SOMObject 
  8364.  
  8365.  Related Methods 
  8366.  
  8367.           Methods 
  8368.  
  8369.               somDefaultInit 
  8370.               somDefaultAssign 
  8371.               somDefaultCopyInit 
  8372.               somDefaultConstCopyInit 
  8373.  
  8374.  Example Code 
  8375.  
  8376.                     // IDL for a class that overrides somDefaultConstAssign
  8377.                     #include <X.idl>
  8378.  
  8379.                     interface Y : X  {
  8380.                             implementation  {
  8381.                                     somDefaultConstAssign: override, init;
  8382.                             };
  8383.                     };
  8384.  
  8385.  
  8386. ΓòÉΓòÉΓòÉ 2.117. somDefaultConstCopyInit ΓòÉΓòÉΓòÉ
  8387.  
  8388. somDefaultConstCopyInit This method provides support for passing objects as 
  8389. call-by-value object parameters in methods introduced by DTS C++ classes. 
  8390. Designed to be overridden. 
  8391.  
  8392.  Syntax 
  8393.  
  8394.                     void somDefaultConstCopyInit (SOMObject receiver, somInitCtrl ctrl,
  8395.                                      SOMObject fromObj)
  8396.  
  8397.  Parameters 
  8398.  
  8399.           receiver (SOMObject) 
  8400.                     A pointer to an uninitialized object of an arbitrary SOM 
  8401.                     class, S. 
  8402.  
  8403.           ctrl (somInitCtrl) 
  8404.                     A pointer to a somInitCtrl structure, or NULL. 
  8405.  
  8406.           fromObj (SOMObject) 
  8407.                     A pointer to an object of class S or some class descended 
  8408.                     from S. 
  8409.  
  8410.  Returns 
  8411.  
  8412.           rc (void) 
  8413.  
  8414.  Remarks 
  8415.  
  8416.           The somDefaultConstCopyInit method would be called a "copy 
  8417.           constructor" in C++. In SOM, this concept is supported using an 
  8418.           object initializer that accepts the object to be copied as an 
  8419.           argument. Copy constructors are used in C++ to pass objects by value. 
  8420.           They initialize one object by making it be a copy of another object. 
  8421.           In SOM, objects are always passed by reference, so arguments to DTS 
  8422.           C++ methods that receive call-by-value object parameters are actually 
  8423.           passed by reference. But, to correctly support the semantics of DTS 
  8424.           C++ call-by-value arguments, it is necessary to actually pass a copy 
  8425.           of the intended argument. A copy constructor can be used to make this 
  8426.           copy. 
  8427.  
  8428.           The default behavior provided by somDefaultConstCopyInit is to do a 
  8429.           shallow copy of each ancestor class's introduced instance variables. 
  8430.           The object being copied is not changed. When a shallow copy is not 
  8431.           appropriate, and it is possible to avoid changing fromObj, a class 
  8432.           implementor should override somDefaultConstCopyInit (for example, to 
  8433.           do a deep copy for certain variables), but should respect the 
  8434.           constraint of not modifying the object being copied. 
  8435.  
  8436.           In general, object users should use somDefaultCopyInit to copy an 
  8437.           object. 
  8438.  
  8439.           The considerations important to overriding somDefaultConstCopyInit 
  8440.           are similar to those described in the SOM Programming Guide for 
  8441.           overriding somDefaultInit. (See "Initializing and Uninitializing 
  8442.           Objects" in Chapter 5, "Implementing Classes in SOM.") The basic 
  8443.           difference between somDefaultInit and somDefaultConstCopyInit is that 
  8444.           the latter method takes an object (fromObj) as an argument that is to 
  8445.           be copied. 
  8446.  
  8447.  Original Class 
  8448.  
  8449.           SOMObject 
  8450.  
  8451.  Related Methods 
  8452.  
  8453.           Methods 
  8454.  
  8455.               somDefaultInit 
  8456.               somDefaultCopyInit 
  8457.               somDefaultAssign 
  8458.               somDefaultConstAssign 
  8459.  
  8460.  Example Code 
  8461.  
  8462.                     // IDL for a class that overrides somDefaultConstCopyInit
  8463.                     interface X : SOMObject
  8464.                     {
  8465.                             implementation {
  8466.                                     somDefaultConstCopyInit: override, init;
  8467.                             };
  8468.                     };
  8469.  
  8470.  
  8471. ΓòÉΓòÉΓòÉ 2.118. somDefaultCopyInit ΓòÉΓòÉΓòÉ
  8472.  
  8473. somDefaultCopyInit This method provides support for call-by-value object 
  8474. parameters in methods introduced by DTS C++ classes. May be overridden, but, if 
  8475. appropriate, somDefaultConstCopyInit should be overridden instead. 
  8476.  
  8477.  Syntax 
  8478.  
  8479.                     void somDefaultCopyInit (SOMObject receiver, somInitCtrl ctrl,
  8480.                                   SOMObject fromObj)
  8481.  
  8482.  Parameters 
  8483.  
  8484.           receiver (SOMObject) 
  8485.                     A pointer to an uninitialized object of an arbitrary SOM 
  8486.                     class, S. 
  8487.  
  8488.           ctrl (somInitCtrl) 
  8489.                     A pointer to a somInitCtrl structure, or NULL. 
  8490.  
  8491.           fromObj (SOMObject) 
  8492.                     A pointer to an object of class S or some class descended 
  8493.                     from S. 
  8494.  
  8495.  Returns 
  8496.  
  8497.           rc (void) 
  8498.  
  8499.  Remarks 
  8500.  
  8501.           The somDefaultCopyInit method would be called a "copy constructor" in 
  8502.           C++. In SOM, this concept is supported using an object initializer 
  8503.           that accepts the object to be copied as an argument. Copy 
  8504.           constructors are used in C++ to pass objects by value. They 
  8505.           initialize one object by making it be a copy of another object. In 
  8506.           SOM, objects are always passed by reference, so arguments to DTS C++ 
  8507.           methods that receive call-by-value object parameters are actually 
  8508.           passed by reference. But, to correctly support the semantics of DTS 
  8509.           C++ call-by-value arguments, it is necessary to actually pass a copy 
  8510.           of the intended argument. In general, somDefaultCopyInit should be 
  8511.           used to make this copy. 
  8512.  
  8513.           The default behavior provided by somDefaultCopyInit is to do a 
  8514.           shallow copy of each ancestor class's introduced instance variables. 
  8515.           However, a class may always override this default behavior (for 
  8516.           example, to do a deep copy for certain variables). If it is possible 
  8517.           to avoid modification of fromObj when doing the copy, the method 
  8518.           somDefaultConstCopyInit should be overridden for this purpose. Only 
  8519.           if this is not possible (and shallow copy is not appropriate) would 
  8520.           it be appropriate to override somDefaultCopyInit. 
  8521.  
  8522.           The considerations important to overriding somDefaultCopyInit are 
  8523.           similar to those described in the SOM Programming Guide for 
  8524.           overriding somDefaultInit. (See "Initializing and Uninitializing 
  8525.           Objects" in Chapter 5, "Implementing Classes in SOM.") The basic 
  8526.           difference between somDefaultInit and somDefaultCopyInit is that the 
  8527.           latter method takes an object (fromObj) as an argument that is to be 
  8528.           copied. 
  8529.  
  8530.  Original Class 
  8531.  
  8532.           SOMObject 
  8533.  
  8534.  Related Methods 
  8535.  
  8536.           Methods 
  8537.  
  8538.               somDefaultInit 
  8539.               somDefaultConstCopyInit 
  8540.               somDefaultAssign 
  8541.               somDefaultConstAssign 
  8542.  
  8543.  Example Code 
  8544.  
  8545.                     // IDL produced by a DTS C++ compiler for a DTS C++ class
  8546.                     interface X : SOMObject
  8547.                     {
  8548.                             void foo(in SOMClass arg);
  8549.                             implementation {
  8550.                                     foo: cxxdecl = "void foo(SOMClass arg)";  //  !! call-by-value
  8551.                             };
  8552.                     };
  8553.  
  8554.                     // C++ SOMObjects Toolkit Code
  8555.                     #include <X.xh>
  8556.                     #include <somcls.xh>
  8557.                     main()
  8558.                     {
  8559.                             X *x = new X;
  8560.                             SOMClass *arg = _SOMClass->somNewNoInit();
  8561.                             // make arg be a copy of the X class object
  8562.                             arg->somDefaultCopyInit(0,_X);
  8563.                             x->foo(arg);   // call foo with the copy
  8564.                     }
  8565.  
  8566.  
  8567. ΓòÉΓòÉΓòÉ 2.119. somDefaultInit ΓòÉΓòÉΓòÉ
  8568.  
  8569. somDefaultInit This method initializes instance variables and attributes in a 
  8570. newly created object. Replaces somInit as the preferred method for default 
  8571. object initialization. For performance reasons, it is recommended that 
  8572. somDefaultInit always be overridden by classes. 
  8573.  
  8574.  Syntax 
  8575.  
  8576.                     void somDefaultInit (SOMObject receiver, somInitCtrl ctrl)
  8577.  
  8578.  Parameters 
  8579.  
  8580.           receiver (SOMObject) 
  8581.                     A pointer to an object of type SOMObject. 
  8582.  
  8583.           ctrl (somInitCtrl) 
  8584.                     A pointer to a somInitCtrl data structure. SOMobjects uses 
  8585.                     this data structure to control the initialization of the 
  8586.                     ancestor classes, thereby ensuring that no ancestor class 
  8587.                     receives multiple initialization calls. A pointer to a 
  8588.                     class that is an ancestor of the actual class of the 
  8589.                     receiver. 
  8590.  
  8591.  Returns 
  8592.  
  8593.           rc (void) 
  8594.  
  8595.  Remarks 
  8596.  
  8597.           Every SOM class is expected to support a set of initializer methods. 
  8598.           This set will always include somDefaultInit, whether or not the class 
  8599.           explicitly overrides somDefaultInit. All other initializer methods 
  8600.           for a class must be explicitly introduced by the class. 
  8601.  
  8602.           The purpose of an initializer method supported by a class is first to 
  8603.           invoke initializer methods of ancestor classes (those ancestors that 
  8604.           are the class's directinitclasses) and then to place the instance 
  8605.           variables and attributes introduced by the class into some consistent 
  8606.           state by loading them with appropriate values. The result is that, 
  8607.           when an object is initialized, each class that contributes to its 
  8608.           implementation will run some initializer method. The somDefaultInit 
  8609.           method may or may not be among the initializers used to initialize a 
  8610.           given object, but it is always available for this purpose. 
  8611.  
  8612.           Thus, the somDefaultInit method may be invoked on a newly created 
  8613.           object to initialize its instance variables and attributes. The 
  8614.           somDefaultInit method is more efficient than somInit (the method it 
  8615.           replaces), and it also prevents multiple initializer calls to 
  8616.           ancestor classes. The somInit method is now considered obsolete when 
  8617.           writing new code, although somInit is still supported. 
  8618.  
  8619.           To override somDefaultInit, the implementation section of the class's 
  8620.           .idl file should include somDefaultInit with the override and init 
  8621.           modifiers specified. (The init modifier signifies that the method is 
  8622.           an initializer method.) No additional coding is required for the 
  8623.           resulting somDefaultInit stub procedure in the implementation 
  8624.           template file, unless the class implementor wishes to customize 
  8625.           object initialization in some way. 
  8626.  
  8627.           If the .idl file does not explicitly override somDefaultInit, then by 
  8628.           default a generic method procedure for somDefaultInit will be 
  8629.           provided by the SOMobjects Toolkit. If invoked, this generic method 
  8630.           procedure first invokes somDefaultInit on the appropriate ancestor 
  8631.           classes, and then (for consistency with earlier versions of 
  8632.           SOMobjects) calls any somInit code that may have been provided by the 
  8633.           class (if somInit was overridden). Because the generic procedure for 
  8634.           somDefaultInit is less efficient than the stub procedure that is 
  8635.           provided when somDefaultInit is overridden, it is recommended that 
  8636.           the .idl file always override somDefaultInit. 
  8637.  
  8638.           Note:  It is not appropriate to override both somDefaultInit and 
  8639.           somInit. If this is done, the somInit code will not be executed. The 
  8640.           best way to convert an old class that overrides somInit to use of the 
  8641.           more efficient somDefaultInit (if this is desired) is as follows: (1) 
  8642.           Replace the somInit override in the class's .idl file with an 
  8643.           override for somDefaultInit, (2) run the implementation template 
  8644.           emitter to produce a stub procedure for somDefaultInit, and then (3) 
  8645.           simply call the class's somInit procedure directly (not using a 
  8646.           method invocation) from the somDefaultInit method procedure. 
  8647.  
  8648.           As mentioned above, the object#initialization framework supported by 
  8649.           SOMobjects allows a class to support additional initializer methods 
  8650.           besides somDefaultInit. These additional initializers will typically 
  8651.           include special#purpose arguments, so that objects of the class can 
  8652.           be initialized with special capabilities or characteristics. For each 
  8653.           new initializer method, the implementation section must include the 
  8654.           method name with the init modifier. Also, the directinitclasses 
  8655.           modifier can be used if, for some reason, the class implementor wants 
  8656.           to control the order in which ancestor initializers are executed. 
  8657.  
  8658.           Note:  It is recommended that the method name for an initializer 
  8659.           method include the class name as a prefix. A newly defined 
  8660.           initializer method will include an implicit Environment argument if 
  8661.           the class does not use a callstyle=oidl modifier. There may be 
  8662.           constraints associated with modification of the procedure stubs for 
  8663.           initializers. 
  8664.  
  8665.  Original Class 
  8666.  
  8667.           SOMObject 
  8668.  
  8669.  Related Methods 
  8670.  
  8671.           Methods 
  8672.  
  8673.               somDestruct 
  8674.  
  8675.  Example Code 
  8676.  
  8677.                     // SOM IDL
  8678.                     #include <Animal.idl>
  8679.  
  8680.                     interface Dog : Animal
  8681.                     {
  8682.                         implementation {
  8683.                             releaseorder: ;
  8684.                                 somDefaultInit: override, init;
  8685.                             };
  8686.                     };
  8687.  
  8688.                     (null)
  8689.                     Original Class
  8690.  
  8691.  
  8692. ΓòÉΓòÉΓòÉ 2.120. somDestruct ΓòÉΓòÉΓòÉ
  8693.  
  8694. somDestruct This method uninitializes the receiving object, and (if so 
  8695. directed) frees object storage after uninitialization has been completed. 
  8696. Replaces somUninit as the preferred method for uninitializing objects. For 
  8697. performance reasons, it is recommended that somDestruct always be overridden. 
  8698. Not normally invoked directly by object clients. 
  8699.  
  8700.  Syntax 
  8701.  
  8702.                     void somDestruct (SOMObject receiver, octet dofree,
  8703.                               somDestructCtrl ctrl)
  8704.  
  8705.  Parameters 
  8706.  
  8707.           receiver (SOMObject) 
  8708.                     A pointer to an object. 
  8709.  
  8710.           dofree (octet) 
  8711.                     A boolean indicating whether the caller wants the object 
  8712.                     storage freed after uninitialization of the current class 
  8713.                     has been completed. Passing 1 (true) indicates the object 
  8714.                     storage should be freed. 
  8715.  
  8716.           ctrl (somDestructCtrl) 
  8717.                     A pointer to a somDestructCtrl data structure. SOMobjects 
  8718.                     uses this data structure to control the uninitialization of 
  8719.                     the ancestor classes, thereby ensuring that no ancestor 
  8720.                     class receives multiple uninitialization calls. If a user 
  8721.                     invokes somDestruct on an object directly, a NULL (that is, 
  8722.                     zero) ctrl pointer can be passed. This instructs the 
  8723.                     receiving code to obtain a somDestructCtrl data structure 
  8724.                     from the class of the object. 
  8725.  
  8726.  Returns 
  8727.  
  8728.           rc (void) 
  8729.  
  8730.  Remarks 
  8731.  
  8732.           Every class must support the somDestruct method. This is accomplished 
  8733.           either by overriding somDestruct (in which case a specialized stub 
  8734.           procedure will be generated in the implementation template file), or 
  8735.           else SOMobjects will automatically provide a generic procedure that 
  8736.           implements somDestruct for the class. The generic procedure calls 
  8737.           somUninit (if this was overridden) to perform local uninitialization, 
  8738.           then completes execution of the method appropriately. 
  8739.  
  8740.           Because the specialized stub procedure generated by the template 
  8741.           emitter is more efficient than the generic procedure provided when 
  8742.           somDestruct is not overridden, it is recommended that somDestruct 
  8743.           always be overridden. The stub procedure that is generated in this 
  8744.           case requires no modification for correct operation. The only 
  8745.           modification appropriate within this stub procedure is to 
  8746.           uninitialize locally introduced instance variables. See Section 5.5, 
  8747.           `Initializing and Unitializing Objects,' of the SOM Programming Guide 
  8748.           for further details. 
  8749.  
  8750.           Uninitialization with somDestruct executes as follows: For any given 
  8751.           class in the ancestor chain, somDestruct first uninitializes that 
  8752.           class's introduced instance variables (if this is appropriate), and 
  8753.           then calls the next ancestor class's implementation of somDestruct, 
  8754.           passing 0 (that is, false) as the interim dofree argument. Then, 
  8755.           after all ancestors of the given class have been uninitialized, if 
  8756.           the class's own somDestruct method were originally invoked with 
  8757.           dofree as 1 (that is, true), then that object's storage is released. 
  8758.  
  8759.           Note:  It is not appropriate to override both somDestruct and 
  8760.           somUninit. If this is done, the somUninit code will not be executed. 
  8761.           The best way to convert an old class that overrides somUninit to use 
  8762.           of the more efficient somDestruct (if this is desired) is as follows: 
  8763.           (1) Replace the somUninit override in the class's .idl file with an 
  8764.           override for somDestruct, (2) run the emitter to produce a stub 
  8765.           procedure for somDestruct in the implementation template file, and 
  8766.           then (3) simply call the class's somUninit procedure directly (not 
  8767.           using a method invocation) from the somDestruct procedure. 
  8768.  
  8769.  Original Class 
  8770.  
  8771.           SOMObject 
  8772.  
  8773.  Related Methods 
  8774.  
  8775.           Functions 
  8776.  
  8777.               somDefaultInit 
  8778.  
  8779.  Example Code 
  8780.  
  8781.                     // SOM IDL
  8782.                     #include <Animal.idl>
  8783.  
  8784.                     interface Dog : Animal
  8785.                     {
  8786.                         implementation {
  8787.                             releaseorder: ;
  8788.                                 somDestruct: override;
  8789.                             };
  8790.                     };
  8791.  
  8792.  
  8793. ΓòÉΓòÉΓòÉ 2.121. somDispatch ΓòÉΓòÉΓòÉ
  8794.  
  8795. somDispatch Invokes a method using dispatch method resolution. The somDispatch 
  8796. method is designed to be overridden. The somClassDispatch method is not 
  8797. generally overridden. 
  8798.  
  8799. For backward compatibility, this method does not take an Environment parameter. 
  8800.  
  8801.  Syntax 
  8802.  
  8803.                     boolean somDispatch (SOMObject receiver, somToken retValue,
  8804.                                 somID methodId, va_list args)
  8805.  
  8806.  Parameters 
  8807.  
  8808.           receiver (SOMObject) 
  8809.                     A pointer to the object whose class will be used for method 
  8810.                     resolution by somDispatch. 
  8811.  
  8812.           retValue (somToken) 
  8813.                     The address of the area in memory where the result of the 
  8814.                     invoked method procedure is to be stored. The caller is 
  8815.                     responsible for allocating enough memory to hold the result 
  8816.                     of the specified method. When dispatching methods that 
  8817.                     return no result (i.e., void), a NULL may be passed as this 
  8818.                     argument. 
  8819.  
  8820.           methodId (somID) 
  8821.                     A somId identifying the method to be invoked. A string 
  8822.                     representing the method name can be converted to a somId 
  8823.                     using the somIdFromString function. 
  8824.  
  8825.           args (va_list) 
  8826.                     A va_list containing the arguments to be passed to the 
  8827.                     method identified by methodId. The arguments  must include 
  8828.                     a pointer to the target object as the first entry. As a 
  8829.                     convenience for C and C++ programmers, SOM's language 
  8830.                     bindings provide a varargs invocation macro for va_list 
  8831.                     methods (such as somDispatch and somClassDispatch). The 
  8832.                     example below illustrates this. 
  8833.  
  8834.  Returns 
  8835.  
  8836.           rc (boolean) 
  8837.                     A boolean representing whether or not the method was 
  8838.                     successfully dispatched is returned. The reason for this is 
  8839.                     that somDispatch and somClassDispatch use the function 
  8840.                     somApply to invoke the resolved method procedure, and 
  8841.                     somApply requires an apply stub for successful execution. 
  8842.                     In support of old class binaries SOM does not consider a 
  8843.                     NULL apply stub to be an error. As a result, somApply may 
  8844.                     fail. If this happens, then false is returned; otherwise 
  8845.                     true is returned. 
  8846.  
  8847.  Remarks 
  8848.  
  8849.           somDispatch and somClassDispatch perform method resolution to select 
  8850.           a method procedure, and then invoke this procedure on args. The 
  8851.           somSelf argument for the selected method procedure (called the target 
  8852.           object, below, to distinguish it from the receiver of the somDispatch 
  8853.           or somClassDispatch method call)  is the first argument included in 
  8854.           the va_list, args. 
  8855.  
  8856.           For somDispatch, method resolution is performed using the class of 
  8857.           the receiver; for somClassDispatch, method resolution is performed 
  8858.           using the argument class, clsObj. Because somClassDispatch uses 
  8859.           clsObj for method resolution, a programmer invoking somDispatch or 
  8860.           somClassDispatch should assure that the class of the target object is 
  8861.           either derived from or is identical to the class used for method 
  8862.           resolution; otherwise, a runtime error will likely result when the 
  8863.           target object is passed to the resolved procedure. Although not 
  8864.           necessary, the receiver is usually also the target object. 
  8865.  
  8866.           The somDispatch and somClassDispatch  methods supersede the 
  8867.           somDispatchX methods. Unlike the somDispatchX methods, which are 
  8868.           restricted to few return types, the somDispatch and somClassDispatch 
  8869.           methods make no assumptions concerning the result returned by the 
  8870.           method to be invoked. Thus, somDispatch and somClassDispatch can be 
  8871.           used to invoke methods that return structures. The somDispatchX 
  8872.           methods now invoke somDispatch, so overriding somDispatch serves to 
  8873.           override the somDispatchX methods as well. 
  8874.  
  8875.  Original Class 
  8876.  
  8877.           SOMObject 
  8878.  
  8879.  Related Methods 
  8880.  
  8881.           Functions 
  8882.  
  8883.               somApply 
  8884.  
  8885.  Example Code 
  8886.  
  8887.           Given class Key that has an attribute keyval of type long and an 
  8888.           overridden method for somPrintSelf that prints the value of the 
  8889.           attribute (as well as the information printed by SOMObject's 
  8890.           implementation of somPrintSelf), the following client code invokes 
  8891.           methods on Key objects using somDispatch and somClassDispatch. (The 
  8892.           Key class was defined with the callstyle=oidl class modifier, so the 
  8893.           Environment argument is not required of its methods.) 
  8894.  
  8895.                     #include <key.h>
  8896.  
  8897.                     main()
  8898.                     {
  8899.                       SOMObject obj;
  8900.                       long k1 = 7, k2;
  8901.                       Key *myKey = KeyNew();
  8902.                       somVaBuf vb;
  8903.                       va_list push, args;
  8904.  
  8905.                       somId setId = somIdFromString("_set_keyval");
  8906.                       somId getId = somIdFromString("_get_keyval");
  8907.                       somId prtId = somIdFromString("somPrintSelf");
  8908.  
  8909.                       vb = (somVaBuf)somVaBuf_create(NULL, 0);
  8910.                       somVaBuf_add(vb, (char *)&myKey, tk_ulong);
  8911.                       somVaBuf_add(vb, (char *)&k1, tk_long);
  8912.                       somVaBuf_get_valist(vb, &args);
  8913.  
  8914.  
  8915.                       /* va_list invocation of setkey and getkey */
  8916.                       SOMObject_somDispatch(myKey, (somToken *)0, setId, args);
  8917.                       somVaBuf_get_valist(vb, &args);
  8918.                       SOMObject_somDispatch(myKey, (somToken *)&k2, getId, args);
  8919.                       printf("va_list _set_keyval and _get_keyval: %i\n", k2);
  8920.  
  8921.                       /* varargs invocation of setkey and getkey */
  8922.                       _somDispatch(myKey, (somToken *)0, setId, myKey, k1);
  8923.                       _somDispatch(myKey, (somToken *)&k2, getId, myKey);
  8924.                       printf("varargs _set_keyval and _get_keyval: %i\n", k2);
  8925.  
  8926.                       /* illustrate somClassDispatch "casting" (use varargs form) */
  8927.                       printf("somPrintSelf on myKey as a Key:\n");
  8928.                       _somClassDispatch(myKey, _Key, (somToken *)&obj, prtId, myKey, 0);
  8929.  
  8930.                       printf("somPrintSelf on myKey as a SOMObject:\n");
  8931.                       _somClassDispatch(myKey, _SOMObject, (somToken *)&obj, prtId, myKey, 0);
  8932.  
  8933.                       SOMFree(setId);
  8934.                       SOMFree(getId);
  8935.                       SOMFree(prtId);
  8936.                       _somFree(myKey);
  8937.  
  8938.                       somVaBuf_destroy(vb);
  8939.                     }
  8940.  
  8941.           This program produces the following output: 
  8942.  
  8943.                     va_list _set_keyval and _get_keyval: 7
  8944.                     varargs _set_keyval and _get_keyval: 7
  8945.                     somPrintSelf on myKey as a Key:
  8946.                     {An instance of class Key at address 2005B2F8}
  8947.                         -- with key value 7
  8948.                     somPrintSelf on myKey as a SOMObject:
  8949.                     {An instance of class Key at address 2005B2F8}
  8950.  
  8951.  
  8952. ΓòÉΓòÉΓòÉ 2.122. somClassDispatch ΓòÉΓòÉΓòÉ
  8953.  
  8954. somClassDispatch Invokes a method using dispatch method resolution. The 
  8955. somDispatch method is designed to be overridden. The somClassDispatch method is 
  8956. not generally overridden. 
  8957.  
  8958. For backward compatibility, this method does not take an Environment parameter. 
  8959.  
  8960.  Syntax 
  8961.  
  8962.                     boolean somClassDispatch (SOMObject receiver, SOMClass clsObj,
  8963.                                    somToken retValue, somID methodId,
  8964.                                    va_list args)
  8965.  
  8966.  Parameters 
  8967.  
  8968.           receiver (SOMObject) 
  8969.                     A pointer to the object whose class will be used for method 
  8970.                     resolution by somDispatch. 
  8971.  
  8972.           clsObj (SOMClass) 
  8973.                     A pointer to the class  that will be used for method 
  8974.                     resolution by somClassDispatch. 
  8975.  
  8976.           retValue (somToken) 
  8977.                     The address of the area in memory where the result of the 
  8978.                     invoked method procedure is to be stored. The caller is 
  8979.                     responsible for allocating enough memory to hold the result 
  8980.                     of the specified method. When dispatching methods that 
  8981.                     return no result (i.e., void), a NULL may be passed as this 
  8982.                     argument. 
  8983.  
  8984.           methodId (somID) 
  8985.                     A somId identifying the method to be invoked. A string 
  8986.                     representing the method name can be converted to a somId 
  8987.                     using the somIdFromString function. 
  8988.  
  8989.           args (va_list) 
  8990.                     A va_list containing the arguments to be passed to the 
  8991.                     method identified by methodId. The arguments  must include 
  8992.                     a pointer to the target object as the first entry. As a 
  8993.                     convenience for C and C++ programmers, SOM's language 
  8994.                     bindings provide a varargs invocation macro for va_list 
  8995.                     methods (such as somDispatch and somClassDispatch). The 
  8996.                     example below illustrates this. 
  8997.  
  8998.  Returns 
  8999.  
  9000.           rc (boolean) 
  9001.                     A boolean representing whether or not the method was 
  9002.                     successfully dispatched is returned. The reason for this is 
  9003.                     that somDispatch and somClassDispatch use the function 
  9004.                     somApply to invoke the resolved method procedure, and 
  9005.                     somApply requires an apply stub for successful execution. 
  9006.                     In support of old class binaries SOM does not consider a 
  9007.                     NULL apply stub to be an error. As a result, somApply may 
  9008.                     fail. If this happens, then false is returned; otherwise 
  9009.                     true is returned. 
  9010.  
  9011.  Remarks 
  9012.  
  9013.           somDispatch and somClassDispatch perform method resolution to select 
  9014.           a method procedure, and then invoke this procedure on args. The 
  9015.           somSelf argument for the selected method procedure (called the target 
  9016.           object, below, to distinguish it from the receiver of the somDispatch 
  9017.           or somClassDispatch method call)  is the first argument included in 
  9018.           the va_list, args. 
  9019.  
  9020.           For somDispatch, method resolution is performed using the class of 
  9021.           the receiver; for somClassDispatch, method resolution is performed 
  9022.           using the argument class, clsObj. Because somClassDispatch uses 
  9023.           clsObj for method resolution, a programmer invoking somDispatch or 
  9024.           somClassDispatch should assure that the class of the target object is 
  9025.           either derived from or is identical to the class used for method 
  9026.           resolution; otherwise, a runtime error will likely result when the 
  9027.           target object is passed to the resolved procedure. Although not 
  9028.           necessary, the receiver is usually also the target object. 
  9029.  
  9030.           The somDispatch and somClassDispatch  methods supersede the 
  9031.           somDispatchX methods. Unlike the somDispatchX methods, which are 
  9032.           restricted to few return types, the somDispatch and somClassDispatch 
  9033.           methods make no assumptions concerning the result returned by the 
  9034.           method to be invoked. Thus, somDispatch and somClassDispatch can be 
  9035.           used to invoke methods that return structures. The somDispatchX 
  9036.           methods now invoke somDispatch, so 
  9037.  
  9038.                      verriding somDispatch serves to override the
  9039.           somDispatchX methods as well. 
  9040.  
  9041.  Original Class 
  9042.  
  9043.           SOMObject 
  9044.  
  9045.  Related Methods 
  9046.  
  9047.           Functions 
  9048.  
  9049.               somApply 
  9050.  
  9051.  Example Code 
  9052.  
  9053.           Given class Key that has an attribute keyval of type long and an 
  9054.           overridden method for somPrintSelf that prints the value of the 
  9055.           attribute (as well as the information printed by SOMObject's 
  9056.           implementation of somPrintSelf), the following client code invokes 
  9057.           methods on Key objects using somDispatch and somClassDispatch. (The 
  9058.           Key class was defined with the callstyle=oidl class modifier, so the 
  9059.           Environment argument is not required of its methods.) 
  9060.  
  9061.                     #include <key.h>
  9062.  
  9063.                     main()
  9064.                     {
  9065.                       SOMObject obj;
  9066.                       long k1 = 7, k2;
  9067.                       Key *myKey = KeyNew();
  9068.                       somVaBuf vb;
  9069.                       va_list push, args;
  9070.  
  9071.                       somId setId = somIdFromString("_set_keyval");
  9072.                       somId getId = somIdFromString("_get_keyval");
  9073.                       somId prtId = somIdFromString("somPrintSelf");
  9074.  
  9075.                       vb = (somVaBuf)somVaBuf_create(NULL, 0);
  9076.                       somVaBuf_add(vb, (char *)&myKey, tk_ulong);
  9077.                       somVaBuf_add(vb, (char *)&k1, tk_long);
  9078.                       somVaBuf_get_valist(vb, &args);
  9079.  
  9080.  
  9081.                       /* va_list invocation of setkey and getkey */
  9082.                       SOMObject_somDispatch(myKey, (somToken *)0, setId, args);
  9083.                       somVaBuf_get_valist(vb, &args);
  9084.                       SOMObject_somDispatch(myKey, (somToken *)&k2, getId, args);
  9085.                       printf("va_list _set_keyval and _get_keyval: %i\n", k2);
  9086.  
  9087.                       /* varargs invocation of setkey and getkey */
  9088.                       _somDispatch(myKey, (somToken *)0, setId, myKey, k1);
  9089.                       _somDispatch(myKey, (somToken *)&k2, getId, myKey);
  9090.                       printf("varargs _set_keyval and _get_keyval: %i\n", k2);
  9091.  
  9092.                       /* illustrate somClassDispatch "casting" (use varargs form) */
  9093.                       printf("somPrintSelf on myKey as a Key:\n");
  9094.                       _somClassDispatch(myKey, _Key, (somToken *)&obj, prtId, myKey, 0);
  9095.  
  9096.                       printf("somPrintSelf on myKey as a SOMObject:\n");
  9097.                       _somClassDispatch(myKey, _SOMObject, (somToken *)&obj, prtId, myKe
  9098.  
  9099.                       SOMFree(setId);
  9100.                       SOMFree(getId);
  9101.                       SOMFree(prtId);
  9102.                       _somFree(myKey);
  9103.  
  9104.                       somVaBuf_destroy(vb);
  9105.                     }
  9106.  
  9107.           This program produces the following output: 
  9108.  
  9109.                     va_list _set_keyval and _get_keyval: 7
  9110.                     varargs _set_keyval and _get_keyval: 7
  9111.                     somPrintSelf on myKey as a Key:
  9112.                     {An instance of class Key at address 2005B2F8}
  9113.                         -- with key value 7
  9114.                     somPrintSelf on myKey as a SOMObject:
  9115.                     {An instance of class Key at address 2005B2F8}
  9116.  
  9117.  
  9118. ΓòÉΓòÉΓòÉ 2.123. somDumpSelf ΓòÉΓòÉΓòÉ
  9119.  
  9120. somDumpSelf This method writes out a detailed description of the receiving 
  9121. object. Intended for use by object clients. Not generally overridden. Note: For 
  9122. backward compatibility, this method does not take and Environment parameter. 
  9123.  
  9124.  Syntax 
  9125.  
  9126.                     void somDumpSelf (SOMObject receiver, long level)
  9127.  
  9128.  Parameters 
  9129.  
  9130.           receiver (SOMObject) 
  9131.                     A pointer to the object to be dumped. 
  9132.  
  9133.           level (long) 
  9134.                     The nesting level for describing compound objects. It must 
  9135.                     be greater than or equal to 0. All lines in the description 
  9136.                     will be preceded by "2 * level" spaces. 
  9137.  
  9138.  Returns 
  9139.  
  9140.           rc (void) 
  9141.  
  9142.  Remarks 
  9143.  
  9144.           The somDumpSelf method performs some initial setup, and then invokes 
  9145.           the somDumpSelfInt method to write a detailed description of the 
  9146.           receiver, including its state. 
  9147.  
  9148.  Original Class 
  9149.  
  9150.           SOMOBject 
  9151.  
  9152.  Related Methods 
  9153.  
  9154.           Methods 
  9155.  
  9156.               somDumpSelfInt 
  9157.  
  9158.  
  9159. ΓòÉΓòÉΓòÉ 2.124. somDumpSelfInt ΓòÉΓòÉΓòÉ
  9160.  
  9161. somDumpSelfInt This method outputs the internal state of an object. Intended to 
  9162. be overridden by class implementors. Not intended to be directly invoked by 
  9163. object clients. 
  9164.  
  9165. For backward compatibility, this method does not take an Environment parameter. 
  9166.  
  9167.  Syntax 
  9168.  
  9169.                     void somDumpSelfInt (SOMObject receiver, long level)
  9170.  
  9171.  Parameters 
  9172.  
  9173.           receiver (SOMObject) 
  9174.                     A pointer to the object to be dumped. 
  9175.  
  9176.           level (long) 
  9177.                     The nesting level for describing compound objects. It must 
  9178.                     be greater than or equal to 0. All lines in the description 
  9179.                     should be preceded by "2* level" spaces. 
  9180.  
  9181.  Returns 
  9182.  
  9183.           rc (void) 
  9184.  
  9185.  Remarks 
  9186.  
  9187.           The somDumpSelfInt method should be overridden by a class 
  9188.           implementor, to write out the instance data stored in an object. This 
  9189.           method is invoked by the somDumpSelf method, which is used by object 
  9190.           clients to output the state of an object. 
  9191.  
  9192.           The procedure used to override this method for a new class  should 
  9193.           begin by calling the parent class form of this method on each of the 
  9194.           class parents, and should then write a description of the instance 
  9195.           variables introduced by new class. This will result in a description 
  9196.           of all the class's instance variables. The C and C++ implementation 
  9197.           bindings provide a convenient macro for performing parent method 
  9198.           calls on all parents, as illustrated below. 
  9199.  
  9200.           The character output routine pointed to by SOMOutCharRoutine should 
  9201.           be used for output. The somLPrintf function is especially convenient 
  9202.           for this, since level is handled appropriately. 
  9203.  
  9204.  Original Class 
  9205.  
  9206.           SOMObject 
  9207.  
  9208.  Related Methods 
  9209.  
  9210.           Methods 
  9211.  
  9212.               somDumpSelf 
  9213.               somPrintSelf 
  9214.  
  9215.  Example Code 
  9216.  
  9217.           Below is a method overriding somDumpSelfInt for class "List", which 
  9218.           has two attributes, val (which is a long) and next  (which is a 
  9219.           pointer to a "List" object). 
  9220.  
  9221.                     SOM_Scope void   SOMLINK somDumpSelfInt(List somSelf, int level)
  9222.                     {
  9223.                         ListData *somThis = ListGetData(somSelf);
  9224.                         Environment *ev = somGetGlobalEnvironment();
  9225.  
  9226.                         List_parents_somDumpSelfInt(somSelf, level);
  9227.                         somLPrintf(level, "This item: %i\n", __get_val(somSelf, ev);
  9228.                         somLPrintf(level, "Next item: \n");
  9229.                         if (__get_next(somSelf, ev) != (List) NULL)
  9230.                             _somDumpSelfInt(__get_next(somSelf, ev), level+1);
  9231.                         else
  9232.                             somLPrintf(level+1, "NULL\n");
  9233.                     }
  9234.  
  9235.           Below is a client program that invokes the somDumpSelf method on 
  9236.           "List" objects. 
  9237.  
  9238.                     #include <list.h>
  9239.  
  9240.                     main()
  9241.                     {
  9242.                        List L1, L2;
  9243.                        long x = 7, y = 13;
  9244.                        Environment *ev = somGetGlobalEnvironment();
  9245.  
  9246.                        L1 = ListNew();
  9247.                        L2 = ListNew();
  9248.                        __set_val(L1, ev, x);
  9249.                        __set_next(L1, ev, (List) NULL);
  9250.                        __set_val(L2, ev, y);
  9251.                        __set_next(L2, ev, L1);
  9252.  
  9253.                        _somDumpSelf(L2,0);
  9254.  
  9255.                        _somFree(L1);
  9256.                        _somFree(L2);
  9257.                     }
  9258.  
  9259.           Below is the output produced by this program: 
  9260.  
  9261.                     {An instance of class List at 0x2005EA8
  9262.                      This item: 13
  9263.                      Next item:
  9264.                        1 This item: 7
  9265.                        1 Next item:
  9266.                          2 NULL
  9267.                     }
  9268.  
  9269.  
  9270. ΓòÉΓòÉΓòÉ 2.125. somFree ΓòÉΓòÉΓòÉ
  9271.  
  9272. somFree This method releases the storage used by an object. Intended for use by 
  9273. object clients. Not generally overridden. 
  9274.  
  9275. For backward compatibility, this method does not take an Environment parameter. 
  9276.  
  9277.  Syntax 
  9278.  
  9279.                     void somFree (SOMObject receiver)
  9280.  
  9281.  Parameters 
  9282.  
  9283.           receiver (SOMObject) 
  9284.                     A pointer to the object to be freed. 
  9285.  
  9286.  Returns 
  9287.  
  9288.           rc (void) 
  9289.  
  9290.  Remarks 
  9291.  
  9292.           The somFree method releases the storage containing the receiver 
  9293.           object by calling the method somDeallocate. No future references 
  9294.           should be made to the receiver once this is done. The somFree method 
  9295.           calls somDestruct to allow storage pointed to by the object to be 
  9296.           freed. 
  9297.  
  9298.           The somFree method should not be called on objects created by 
  9299.           somRenew, thus the method is normally only used by code that also 
  9300.           created the object. 
  9301.  
  9302.           Note:  SOM also supplies a macro, SOMFree, which is used to free a 
  9303.           block of memory. This macro should not be used on objects. 
  9304.  
  9305.  Original Class 
  9306.  
  9307.           SOMObject 
  9308.  
  9309.  Related Methods 
  9310.  
  9311.           Methods 
  9312.  
  9313.               somNew 
  9314.               somNewNoInit 
  9315.               somDestruct 
  9316.  
  9317.           Functions 
  9318.  
  9319.               SOMFree 
  9320.  
  9321.  Example Code 
  9322.  
  9323.                     #include <animal.h>
  9324.  
  9325.                     void main()
  9326.                     {
  9327.                        Animal myAnimal;
  9328.                        /*
  9329.                         * Create an object.
  9330.                         */
  9331.                        myAnimal = AnimalNew();
  9332.  
  9333.                        /* ... */
  9334.  
  9335.                        /* Free it when finished. */
  9336.                        _somFree(myAnimal);
  9337.                     }
  9338.  
  9339.  
  9340. ΓòÉΓòÉΓòÉ 2.126. somGetClass ΓòÉΓòÉΓòÉ
  9341.  
  9342. somGetClass This method returns a pointer to an object's class object. Not 
  9343. generally overridden. 
  9344.  
  9345. For backward compatibility, this method does not take an Environment parameter. 
  9346.  
  9347.  Syntax 
  9348.  
  9349.                     SOMClass somGetClass (SOMObject receiver)
  9350.  
  9351.  Parameters 
  9352.  
  9353.           receiver (SOMObject) 
  9354.                     A pointer to the object whose class is desired. 
  9355.  
  9356.  Returns 
  9357.  
  9358.           rc (SOMClass) 
  9359.                     A pointer to the object's class object. This return value 
  9360.                     is cast as a (SOMClass*). In C++, you may have to 
  9361.                     explicitly cast this to a pointer of a specific class type 
  9362.                     (when different from SOMClass). 
  9363.  
  9364.  Remarks 
  9365.  
  9366.           somGetClass obtains a pointer to the receiver's class object. The 
  9367.           somGetClass method is typically not overridden. 
  9368.  
  9369.           Important Note:  For C and C++ programmers, SOM provides a 
  9370.           SOM_GetClass macro that performs the same function. This macro should 
  9371.           only be used only when absolutely necessary (i.e., when a method call 
  9372.           on the object is not possible), since it bypasses whatever semantics 
  9373.           may be intended for the somGetClass method by the implementor of the 
  9374.           receiver's class. Even class implementors do not know whether a 
  9375.           special semantics for this method is inherited from ancestor classes. 
  9376.           If you are unsure of whether the method or the macro is appropriate, 
  9377.           you should use the method call. 
  9378.  
  9379.  Original Class 
  9380.  
  9381.           SOMObject 
  9382.  
  9383.  Related Methods 
  9384.  
  9385.           Methods 
  9386.  
  9387.               SOM_GetClass 
  9388.  
  9389.  Example Code 
  9390.  
  9391.                     #include <animal.h>
  9392.                     main()
  9393.                     {
  9394.                       Animal myAnimal;
  9395.                       int numMethods;
  9396.                       SOMClass animalClass;
  9397.  
  9398.                       myAnimal = AnimalNew ();
  9399.                       animalClass = _somGetClass (myAnimal);
  9400.                       SOM_Test(animalClass == _Animal);
  9401.                     }
  9402.  
  9403.  
  9404. ΓòÉΓòÉΓòÉ 2.127. somGetClassName ΓòÉΓòÉΓòÉ
  9405.  
  9406. somGetClassName This method returns the name of the class of an object. Not 
  9407. generally overridden. 
  9408.  
  9409. For backward compatibility, this method does not take an Environment parameter. 
  9410.  
  9411.  Syntax 
  9412.  
  9413.                     string somGetClassName (somObject receiver)
  9414.  
  9415.  Parameters 
  9416.  
  9417.           receiver (somObject) 
  9418.                     A pointer to the object whose class name is desired. 
  9419.  
  9420.  Returns 
  9421.  
  9422.           rc (string) 
  9423.                     Returns a pointer to the name of the class. 
  9424.  
  9425.  Remarks 
  9426.  
  9427.           The somGetClassName method returns a pointer to a zero-terminated 
  9428.           string that gives the name of the class of an object. 
  9429.  
  9430.           This method is not generally overridden; it simply invokes somGetName 
  9431.           on the class of the receiver. Refer to somGetName for more 
  9432.           information on the returned string. 
  9433.  
  9434.  Original Class 
  9435.  
  9436.           SOMObject 
  9437.  
  9438.  Related Methods 
  9439.  
  9440.           Methods 
  9441.  
  9442.               somGetName 
  9443.  
  9444.  Example Code 
  9445.  
  9446.                     #include <animal.h>
  9447.                     main()
  9448.                     {
  9449.                       Animal myAnimal;
  9450.                       SOMClass animalClass;
  9451.                       char *className;
  9452.  
  9453.                       myAnimal = AnimalNew();
  9454.                       className = _somGetClassName(myAnimal);
  9455.                       somPrintf("Class name: %s\n", className);
  9456.                       _somFree(myAnimal);
  9457.                     }
  9458.                     /*
  9459.                     Output from this program:
  9460.                     Class name:  Animal
  9461.                     */
  9462.  
  9463.  
  9464. ΓòÉΓòÉΓòÉ 2.128. somGetSize ΓòÉΓòÉΓòÉ
  9465.  
  9466. somGetSize This method returns the size of an object. Not generally overridden. 
  9467.  
  9468. For backward compatibility, this method does not take an Environment parameter. 
  9469.  
  9470.  Syntax 
  9471.  
  9472.                     long somGetSize (SOMObject receiver)
  9473.  
  9474.  Parameters 
  9475.  
  9476.           receiver (SOMObject) 
  9477.                     A pointer to the object whose size is desired. 
  9478.  
  9479.  Returns 
  9480.  
  9481.           rc (long) 
  9482.                     Returns the size, in bytes, of the receiver. 
  9483.  
  9484.  Remarks 
  9485.  
  9486.           The somGetSize method returns the total amount of contiguous space 
  9487.           used by the receiving object. 
  9488.  
  9489.           The value returned reflects only the amount of storage needed to hold 
  9490.           the SOM representation of the object. The object might actually be 
  9491.           using or managing additional space outside of this area. 
  9492.  
  9493.           The somGetSize method is not generally overridden. 
  9494.  
  9495.  Original Class 
  9496.  
  9497.           SOMObject 
  9498.  
  9499.  Related Methods 
  9500.  
  9501.           Methods 
  9502.  
  9503.               somGetInstancePartSize 
  9504.               somGetInstanceSize 
  9505.  
  9506.  Example Code 
  9507.  
  9508.                     #include <animal.h>
  9509.                     void main()
  9510.                     {
  9511.                        Animal myAnimal;
  9512.                        long animalSize;
  9513.                        myAnimal = AnimalNew();
  9514.                        animalSize = _somGetSize(myAnimal);
  9515.                        somPrintf("Size of animal (in bytes): %d\n", animalSize);
  9516.                        _somFree(myAnimal);
  9517.                     }
  9518.                     /*
  9519.                     Output from this program:
  9520.                     Size of animal (in bytes): 8
  9521.                     */
  9522.  
  9523.  
  9524. ΓòÉΓòÉΓòÉ 2.129. somInit ΓòÉΓòÉΓòÉ
  9525.  
  9526. somInit This method initializes instance variables or attributes in a newly 
  9527. created object. Designed to be overridden. Note:  The newer somDefaultInit 
  9528. method is suggested instead. 
  9529.  
  9530. For backward compatibility, this method does not take an Environment parameter. 
  9531.  
  9532.  Syntax 
  9533.  
  9534.                     void somInit (SOMObject receiver)
  9535.  
  9536.  Parameters 
  9537.  
  9538.           receiver (SOMObject) 
  9539.                     A pointer to the object to be initialized. 
  9540.  
  9541.  Returns 
  9542.  
  9543.           rc (void) 
  9544.  
  9545.  Remarks 
  9546.  
  9547.           The somInit method is invoked to cause a newly created object to 
  9548.           initialize its instance variables or attributes. 
  9549.  
  9550.           Note:  The newer somDefaultInit method performs object initialization 
  9551.           more efficiently and is now the preferred approach for overriding 
  9552.           initialization in an implementation file. (The somInit method still 
  9553.           executes correctly as before.) 
  9554.  
  9555.           Because instances of SOMObject do not have any instance data, the 
  9556.           default implementation does nothing. It is provided as a convenience 
  9557.           to class implementors so that initialization of objects can be done 
  9558.           in a uniform way across all classes (by overriding somInit). This 
  9559.           method is called automatically by somNew during object creation. 
  9560.  
  9561.           A companion method, somUninit, is called whenever an object is freed. 
  9562.           These two methods should be designed to work together, with somInit 
  9563.           priming an object for its first use, and somUninit preparing the 
  9564.           object for subsequent release. 
  9565.  
  9566.           If objects of your class contain instance variables or attributes, 
  9567.           override the somInit method to initialize the instance variables or 
  9568.           attributes when instances of the class are created. When overriding 
  9569.           this method, always call all parent (base) classes' versions of this 
  9570.           method beforedoing your own initialization, as follows: 
  9571.  
  9572.           1. The overriding implementation should invoke the parent method for 
  9573.           each parent. For users of the C or C++ implementation bindings, this 
  9574.           can be done in either of two ways: (a) by calling a _parents_ macro 
  9575.           (which automatically invokes all parent methods) or (b) by calling 
  9576.           the _parent_ parentName>_ macro on each parent separately. 
  9577.  
  9578.           For more information on parent method calls, see the topic "Extending 
  9579.           the Implementation Template" in Chapter 5, "Implementing Classes in 
  9580.           SOM," of the SOM Programming Guide. 
  9581.  
  9582.           2. The code must be written so that it can be executed multiple times 
  9583.           without harm on the same object. This is necessary because, under 
  9584.           multiple inheritance, parent method calls that progress up the 
  9585.           inheritance hierarchy may encounter the same ancestor class more than 
  9586.           once (where different inheritance paths "join" when followed 
  9587.           backward). A check can be made to determine whether a particular 
  9588.           invocation of somInit  is the first on a given object by examining 
  9589.           the contents of its instance variables; all the instance variables 
  9590.           and attributes of a newly created SOM object are set to zero before 
  9591.           somInit is invoked on that object. 
  9592.  
  9593.           More information and examples on object initialization (especially 
  9594.           regarding the somDefaultInit method) are given in the topic 
  9595.           "Initializing and Uninitializing Objects" in Chapter 5, "Implementing 
  9596.           Classes in SOM," of the SOM Programming Guide. 
  9597.  
  9598.  Original Class 
  9599.  
  9600.           SOMObject 
  9601.  
  9602.  Related Methods 
  9603.  
  9604.           Methods 
  9605.  
  9606.               somDefaultInit 
  9607.               somNew 
  9608.               somRenew 
  9609.               somDestruct 
  9610.               somUninit 
  9611.  
  9612.  Example Code 
  9613.  
  9614.           Below is the implementation for a class Animal that introduces an 
  9615.           attribute sound of type string and overrides somInit and somUninit, 
  9616.           along with a main program that creates and then frees an instance of 
  9617.           class Animal. 
  9618.  
  9619.                     #define Animal_Class_Source
  9620.                      #include <animal.ih>
  9621.                      #include <string.h>
  9622.  
  9623.                      SOM_Scope void SOMLINK somInit (Animal somSelf)
  9624.                      {
  9625.                           AnimalData *somThis = AnimalGetData (somSelf);
  9626.                           Environment *ev = somGetGlobalEnvironment();
  9627.                           Animal_parents_somInit (somSelf);
  9628.                           if (!__get_sound(somSelf, ev)) {
  9629.                              __set_sound(somSelf, ev, SOMMalloc(100));
  9630.                              strcpy (__get_sound(somSelf, ev), "Unknown Noise");
  9631.                              somPrintf ("New Animal Initialized\n");
  9632.                           }
  9633.                      }
  9634.  
  9635.                      SOM_Scope void SOMLINK somUninit (Animal somSelf)
  9636.                       {
  9637.                           AnimalData *somThis = AnimalGetData (somSelf);
  9638.                           Environment *ev = somGetGlobalEnvironment();
  9639.                           if (__get_sound(somSelf, ev)) {
  9640.                             SOMFree(__get_sound(somSelf, ev);
  9641.                             __set_sound(somSelf, ev, (char*)0);
  9642.                             somPrintf ("Animal Uninitialized\n");
  9643.                             Animal_parents_somUninit (somSelf);
  9644.                           }
  9645.                     }
  9646.  
  9647.                     /* main program */
  9648.                        #include <animal.h>
  9649.                        void main()
  9650.                        {
  9651.                           Animal myAnimal;
  9652.                           myAnimal = AnimalNew ();
  9653.                           _somFree (myAnimal);
  9654.                        }
  9655.  
  9656.                     /*
  9657.                     Program output:
  9658.                     New Animal Initialized
  9659.                     Animal Uninitialized
  9660.                     */
  9661.  
  9662.  
  9663. ΓòÉΓòÉΓòÉ 2.130. somIsA ΓòÉΓòÉΓòÉ
  9664.  
  9665. somIsA This method tests whether an object is an instance of a given class or 
  9666. of one of its descendant classes. Not generally overridden. 
  9667.  
  9668. For backward compatibility, this method does not take an Environment parameter. 
  9669.  
  9670.  Syntax 
  9671.  
  9672.                     boolean somIsA (SOMObject receiver, SOMClass aClass)
  9673.  
  9674.  Parameters 
  9675.  
  9676.           receiver (SOMObject) 
  9677.                     A pointer to the object to be tested. 
  9678.  
  9679.           aClass (SOMClass) 
  9680.                     A pointer to the class that the object should be tested 
  9681.                     against. 
  9682.  
  9683.  Returns 
  9684.  
  9685.           rc (boolean) 
  9686.                     Returns 1 (true) if the receiving object is an instance of 
  9687.                     the specified class or (unlike somIsInstanceOf) of any of 
  9688.                     its descendant classes, and 0 (false) otherwise. 
  9689.  
  9690.  Remarks 
  9691.  
  9692.           Use the somIsA method to determine if an object can be treated like 
  9693.           an instance of aClass. SOM guarantees that if somIsA returns true, 
  9694.           then the receiver will respond to all (static or dynamic) methods 
  9695.           supported by aClass. 
  9696.  
  9697.  Original Class 
  9698.  
  9699.           SOMObject 
  9700.  
  9701.  Related Methods 
  9702.  
  9703.           Methods 
  9704.  
  9705.               somIsDescendedFrom 
  9706.               somIsInstanceOf 
  9707.               somRespondsTo 
  9708.               somSupportsMethod 
  9709.  
  9710.  Example Code 
  9711.  
  9712.                     #include <dog.h>
  9713.                     /* ----------------------------------
  9714.                        Note:  Dog is derived from Animal.
  9715.                        ---------------------------------- */
  9716.                     main()
  9717.                     {
  9718.                       Animal myAnimal;
  9719.                       Dog myDog;
  9720.                       SOMClass animalClass;
  9721.                       SOMClass dogClass;
  9722.  
  9723.                       myAnimal = AnimalNew();
  9724.                       myDog = DogNew();
  9725.                       animalClass = _somGetClass (myAnimal);
  9726.                       dogClass = _somGetClass (myDog);
  9727.                       if (_somIsA (myDog, animalClass))
  9728.                          somPrintf ("myDog IS an Animal\n");
  9729.                       else
  9730.                          somPrintf ("myDog IS NOT an Animal\n");
  9731.                       if (_somIsA (myAnimal, dogClass))
  9732.                          somPrintf ("myAnimal IS a Dog\n");
  9733.                       else
  9734.                          somPrintf ("myAnimal IS NOT a Dog\n");
  9735.                       _somFree (myAnimal);
  9736.                       _somFree (myDog);
  9737.                     }
  9738.                     /*
  9739.                     Output from this program:
  9740.                     myDog IS an Animal
  9741.                     myAnimal IS NOT a Dog
  9742.                     */
  9743.  
  9744.  
  9745. ΓòÉΓòÉΓòÉ 2.131. somIsInstanceOf ΓòÉΓòÉΓòÉ
  9746.  
  9747. somIsInstanceOf This method determines whether an object is an instance of a 
  9748. specific class. Not generally overridden. 
  9749.  
  9750. For backward compatibility, this method does not take an Environment parameter. 
  9751.  
  9752.  Syntax 
  9753.  
  9754.                     boolean somIsInstanceOf (SOMObject receiver, SOMClass aClass)
  9755.  
  9756.  Parameters 
  9757.  
  9758.           receiver (SOMObject) 
  9759.                     A pointer to the object to be tested. 
  9760.  
  9761.           aClass (SOMClass) 
  9762.                     A pointer to the class that the object should be an 
  9763.                     instance of. 
  9764.  
  9765.  Returns 
  9766.  
  9767.           rc (boolean) 
  9768.                     Returns 1 (true) if the receiving object is an instance of 
  9769.                     the specified class, and 0 (false) otherwise. 
  9770.  
  9771.  Remarks 
  9772.  
  9773.           Use the somIsInstanceOf method to determine if an object is an 
  9774.           instance of a specific class. This method tests an object for 
  9775.           inclusion in one specific class. It is equivalent to the expression: 
  9776.  
  9777.                     (aClass == somGetClass (receiver))
  9778.  
  9779.  Original Class 
  9780.  
  9781.           SOMObject 
  9782.  
  9783.  Related Methods 
  9784.  
  9785.           Methods 
  9786.  
  9787.               somDescendedFrom 
  9788.               somIsA 
  9789.  
  9790.  Example Code 
  9791.  
  9792.                     #include <dog.h>
  9793.                     /* ----------------------------------
  9794.                        Note:  Dog is derived from Animal.
  9795.                        ---------------------------------- */
  9796.                     main()
  9797.                     {
  9798.                       Animal myAnimal;
  9799.                       Dog myDog;
  9800.                       SOMClass animalClass;
  9801.                       SOMClass dogClass;
  9802.  
  9803.                       myAnimal = AnimalNew ();
  9804.                       myDog = DogNew ();
  9805.                       animalClass = _somGetClass (myAnimal);
  9806.                       dogClass = _somGetClass (myDog);
  9807.                       if (_somIsInstanceOf (myDog, animalClass))
  9808.                          somPrintf ("myDog is an instance of Animal\n");
  9809.                       if (_somIsInstanceOf (myDog, dogClass))
  9810.                          somPrintf ("myDog is an instance of Dog\n");
  9811.                       if (_somIsInstanceOf (myAnimal, animalClass))
  9812.                          somPrintf ("myAnimal is an instance of Animal\n");
  9813.                       if (_somIsInstanceOf (myAnimal, dogClass))
  9814.                          somPrintf ("myAnimal is an instance of Dog\n");
  9815.                       _somFree (myAnimal);
  9816.                       _somFree (myDog);
  9817.                     }
  9818.                     /*
  9819.                     Output from this program:
  9820.                     myDog is an instance of Dog
  9821.                     myAnimal is an instance of Animal
  9822.                     */
  9823.  
  9824.  
  9825. ΓòÉΓòÉΓòÉ 2.132. somPrintSelf ΓòÉΓòÉΓòÉ
  9826.  
  9827. somPrintSelf This method outputs a brief description that identifies the 
  9828. receiving object. Designed to be overridden. 
  9829.  
  9830. Note:  For backward compatibility, this method does not take an Environment 
  9831. parameter. 
  9832.  
  9833.  Syntax 
  9834.  
  9835.                     SOMObject somPrintSelf (SOMObject receiver)
  9836.  
  9837.  Parameters 
  9838.  
  9839.           receiver (SOMObject) 
  9840.                     A pointer to the object to be described. 
  9841.  
  9842.  Returns 
  9843.  
  9844.           rc (SOMObject) 
  9845.                     Returns a pointer to the receiver object as its result. 
  9846.  
  9847.  Remarks 
  9848.  
  9849.           somPrintSelf should output a brief string containing key information 
  9850.           useful to identify the receiver object, rather than a complete dump 
  9851.           of the receiver object state as provided by somDumpSelfInt. The 
  9852.           somPrintSelf method should use the character output routine 
  9853.           SOMOutCharRoutine (or any of the somPrintf functions) for this 
  9854.           purpose. The default implementation outputs the name of the receiver 
  9855.           object's class and the receiver's address in memory. 
  9856.  
  9857.           Because the most specific identifying information for an object will 
  9858.           often be found within instance data introduced by the class of an 
  9859.           object, it is likely that a class implementor that overrides this 
  9860.           method will not need to invoke parent methods in order to provide a 
  9861.           useful string identifying the receiver object. 
  9862.  
  9863.  Original Class 
  9864.  
  9865.           SOMObject 
  9866.  
  9867.  Related Methods 
  9868.  
  9869.           Methods 
  9870.  
  9871.               somDumpSelf 
  9872.               somDumpSelfInt 
  9873.  
  9874.  Example Code 
  9875.  
  9876.                     #include <animal.h>
  9877.                     main()
  9878.                     {
  9879.                       Animal myAnimal;
  9880.                       myAnimal = AnimalNew ();
  9881.                       /* ... */
  9882.                       _somPrintSelf (myAnimal);
  9883.                       _somFree (myAnimal);
  9884.                     }
  9885.                     /*
  9886.                     Output from this program:
  9887.  
  9888.                     {An instance of class Animal at address 0001CEC0}
  9889.                     */
  9890.  
  9891.  
  9892. ΓòÉΓòÉΓòÉ 2.133. somResetObj ΓòÉΓòÉΓòÉ
  9893.  
  9894. somResetObj Resets an object's class to its true class after use of the 
  9895. somCastObj method. 
  9896.  
  9897.  Syntax 
  9898.  
  9899.                     boolean somResetObj (SOMObject receiver)
  9900.  
  9901.  Parameters 
  9902.  
  9903.           receiver (SOMObject) 
  9904.                     A pointer to a SOM object. 
  9905.  
  9906.  Returns 
  9907.  
  9908.           rc (boolean) 
  9909.                     The somResetObj method returns 1 (TRUE) always. 
  9910.  
  9911.  Remarks 
  9912.  
  9913.           The somResetObj method resets an object's class to its true class 
  9914.           after use of the somCastObj method. 
  9915.  
  9916.  Original Class 
  9917.  
  9918.           SOMObject 
  9919.  
  9920.  Related Methods 
  9921.  
  9922.           Methods 
  9923.  
  9924.               somCastObj 
  9925.  
  9926.  Example Code 
  9927.  
  9928.                     #include <som.h>
  9929.                     main()
  9930.                     {
  9931.                        SOMClassMgr cm = somEnvironmentNew();
  9932.                        SOM_Test(1 == _somCastObj(cm, _SOMObject));
  9933.                        _somDumpSelf(cm, 0));
  9934.                        SOM_Test(1 == _somResetObj(cm));
  9935.                        _somDumpSelf(cm, 0);
  9936.                     }
  9937.  
  9938.                     (null)
  9939.                     /* output:
  9940.                      *  {An instance of class SOMClassMgr->SOMObject
  9941.                      *   at address 20061268
  9942.                      *  }
  9943.                      *  {An instance of class SOMClassMgr at address 20061268
  9944.                      *   ... <SOMClassMgr State Information> ...
  9945.                      *  }
  9946.                      */
  9947.  
  9948.  
  9949. ΓòÉΓòÉΓòÉ 2.134. somRespondsTo ΓòÉΓòÉΓòÉ
  9950.  
  9951. somRespondsTo This method tests whether the receiving object supports a given 
  9952. method. Not generally overridden. Note:  For backward compatibility, this 
  9953. method does not take an Environment parameter. 
  9954.  
  9955.  Syntax 
  9956.  
  9957.                     boolean somRespondsTo (SOMObject receiver, somId methodId)
  9958.  
  9959.  Parameters 
  9960.  
  9961.           receiver (SOMObject) 
  9962.                     A pointer to the object to be tested. 
  9963.  
  9964.           methodId (somId) 
  9965.                     A somId that represents the name of the desired method. 
  9966.  
  9967.  Returns 
  9968.  
  9969.           rc (boolean) 
  9970.                     Returns TRUE if the specified method can be invoked on the 
  9971.                     receiving object, and FALSE otherwise. 
  9972.  
  9973.  Remarks 
  9974.  
  9975.           The somRespondsTo method tests whether a specific (static or dynamic) 
  9976.           method can be invoked on the receiver object. This test is equivalent 
  9977.           to determining whether the class of the receiver supports the 
  9978.           specified method on its instances. 
  9979.  
  9980.  Original Class 
  9981.  
  9982.           SOMObject 
  9983.  
  9984.  Related Methods 
  9985.  
  9986.           Methods 
  9987.  
  9988.               somSupportsMethod 
  9989.  
  9990.  Example Code 
  9991.  
  9992.                     /* -----------------------------------------
  9993.                        Note:  Animal supports a setSound method;
  9994.                        Animal does not support a doTrick method.
  9995.                        ----------------------------------------- */
  9996.                     #include <animal.h>
  9997.                     main()
  9998.                     {
  9999.                       Animal myAnimal;
  10000.                       char *methodName1 = "setSound";
  10001.                       char *methodName2 = "doTrick";
  10002.  
  10003.                       myAnimal = AnimalNew();
  10004.                       if (_somRespondsTo(myAnimal, SOM_IdFromString(methodName1)))
  10005.                          somPrintf("myAnimal responds to %s\n", methodName1);
  10006.                       if (_somRespondsTo(myAnimal, SOM_IdFromString(methodName2)))
  10007.                          somPrintf("myAnimal responds to %s\n", methodName2);
  10008.                       _somFree(myAnimal);
  10009.                     }
  10010.                     /*
  10011.                     Output from this program:
  10012.                     myAnimal responds to setSound
  10013.                     */
  10014.  
  10015.  
  10016. ΓòÉΓòÉΓòÉ 2.135. somUninit ΓòÉΓòÉΓòÉ
  10017.  
  10018. somUninit This method un-initializes the receiving object. Designed to be 
  10019. overridden by class implementors. Not normally invoked directly by object 
  10020. clients. 
  10021.  
  10022. Note:  For backward compatibility, this method does not take an Environment 
  10023. parameter. 
  10024.  
  10025.  Syntax 
  10026.  
  10027.                     void somUninit (SOMObject receiver)
  10028.  
  10029.  Parameters 
  10030.  
  10031.           receiver (SOMObject) 
  10032.                     A pointer to the object to be un-initialized. 
  10033.  
  10034.  Returns 
  10035.  
  10036.           rc (void) 
  10037.  
  10038.  Remarks 
  10039.  
  10040.           The somUninit method performs the inverse of object initialization. 
  10041.           Class implementors that introduce instance data that points to 
  10042.           allocated storage should override somUninit so allocated storage can 
  10043.           be freed when an object is freed. 
  10044.  
  10045.           This method is called automatically by somFree to clean up anything 
  10046.           necessary (such as extra storage dynamically allocated to the object) 
  10047.           before somFree releases the storage allocated to the object itself. 
  10048.  
  10049.           Code responsible for freeing an object must first know that there 
  10050.           will be no further references to this object. Once this is known, 
  10051.           this code would normally invoke somFree (which calls somUninit). In 
  10052.           cases where somRenew was used to create an object instance, however, 
  10053.           somFree cannot be called (e.g., the storage containing the object may 
  10054.           simply be a location on the stack), and in this case, somUninit must 
  10055.           be called explicitly. 
  10056.  
  10057.           When overriding this method, always call the parent-class versions of 
  10058.           this method after doing your own un-initialization. Furthermore, just 
  10059.           as with somInit, because your method may be called multiple times 
  10060.           (due to multiple inheritance),  you should zero out references to 
  10061.           memory that is freed, and check for zeros before freeing memory and 
  10062.           calling the parent methods. 
  10063.  
  10064.  Original Class 
  10065.  
  10066.           SOMObject 
  10067.  
  10068.  Related Methods 
  10069.  
  10070.           Methods 
  10071.  
  10072.               somInit 
  10073.               somNew 
  10074.               somRenew 
  10075.  
  10076.  Example Code 
  10077.  
  10078.           Following is the implementation for a class Animal  that introduces 
  10079.           an attribute sound of type string and overrides  somInit and 
  10080.           somUninit, along with a main program that creates and then frees an 
  10081.           instance of class Animal. 
  10082.  
  10083.                     #define Animal_Class_Source
  10084.                     #include <animal.ih>
  10085.                     #include <string.h>
  10086.  
  10087.                     SOM_Scope void SOMLINK somInit (Animal somSelf)
  10088.                      {
  10089.                          AnimalData *somThis = AnimalGetData (somSelf);
  10090.                          Environment *ev = somGetGlobalEnvironment();
  10091.                          Animal_parents_somInit (somSelf);
  10092.                          if (!__get_sound(somSelf, ev)) {
  10093.                             __set_sound(somSelf, ev, SOMMalloc(100));
  10094.                             strcpy (__get_sound(somSelf, ev), "Unknown Noise");
  10095.                             somPrintf ("New Animal Initialized\n");
  10096.                          }
  10097.                      }
  10098.  
  10099.                     SOM_Scope void SOMLINK  somUninit (Animal somSelf)
  10100.                      {
  10101.                          AnimalData *somThis = AnimalGetData (somSelf);
  10102.                          Environment *ev = somGetGlobalEnvironment();
  10103.                          if (__get_sound(somSelf, ev)) {
  10104.                             SOMFree(__get_sound(somSelf, ev);
  10105.                             __set_sound(somSelf, ev, (char*)0);
  10106.                             somPrintf ("Animal Uninitialized\n");
  10107.                             Animal_parents_somUninit (somSelf);
  10108.                          }
  10109.                      }
  10110.                     /* main program */
  10111.                        #include <animal.h>
  10112.                        void main()
  10113.                        {
  10114.                           Animal myAnimal;
  10115.                           myAnimal = AnimalNew ();
  10116.                           _somFree (myAnimal);
  10117.                        }
  10118.  
  10119.                     /*
  10120.                     Program output:
  10121.                     New Animal Initialized
  10122.                     Animal Uninitialized
  10123.                     */
  10124.  
  10125.  
  10126. ΓòÉΓòÉΓòÉ 3. DSOM Framework Reference ΓòÉΓòÉΓòÉ
  10127.  
  10128.  
  10129. DSOM Framework Class Organization
  10130.  
  10131.  
  10132. ΓòÉΓòÉΓòÉ 3.1. A note on DSOM and CORBA ΓòÉΓòÉΓòÉ
  10133.  
  10134. Distributed SOM (DSOM) is a framework which supports access to objects in a 
  10135. distributed application. DSOM can be viewed as both: 
  10136.  
  10137.      an extension to basic SOM facilities 
  10138.  
  10139.      an implementation of the "Object Request Broker" (ORB) technology defined 
  10140.       by the Object Management Group (OMG), in the Common Object Request Broker 
  10141.       Architecture (CORBA) specification and standard, Revision 1.1. The CORBA 
  10142.       1.1 specification is published by x/Open and the Object Management Group 
  10143.       (OMG). 
  10144.  
  10145.       Note:  Portions of this discussion of DSOM pertain to Workgroup DSOM only 
  10146.              and are not supported by this Windows version of the product. 
  10147.              References to topics such as ORB, CORBA, and selection of servers 
  10148.              do not apply to this version. These discussions are presented here 
  10149.              to provide a more complete understanding of DSOM in general. 
  10150.  
  10151.  One of the primary contributions of CORBA is the specification of basic 
  10152.  runtime interfaces for writing portable, distributable object-oriented 
  10153.  applications. SOM and DSOM implement those runtime interfaces, according to 
  10154.  the CORBA specification. 
  10155.  
  10156.  In addition to the published CORBA 1.1 interfaces, it was necessary for to 
  10157.  DSOM introduce several of its own interfaces, in those areas where: 
  10158.  
  10159.      CORBA 1.1 did not specify the full interface (e.g., ImplementationDef, 
  10160.       Principal) 
  10161.  
  10162.      CORBA 1.1 did not address the function specified by the interface (e.g., 
  10163.       "lifecycle" services for object creation and deletion) 
  10164.  
  10165.      the functionality of a CORBA 1.1 interface has been enhanced by DSOM. 
  10166.  
  10167.  Any such interfaces have been noted on the reference page for each DSOM class. 
  10168.  
  10169.  
  10170. ΓòÉΓòÉΓòÉ 3.2. A note on method naming conventions ΓòÉΓòÉΓòÉ
  10171.  
  10172. The SOM Toolkit frameworks (including DSOM) and CORBA have slightly different 
  10173. conventions for naming methods. Methods introduced by the SOM Toolkit 
  10174. frameworks use prefixes to indicate the framework to which each method belongs, 
  10175. and use capitalization to separate words in the method names (for example, 
  10176. somdFindServer). Methods introduced by CORBA have no prefixes, are all lower 
  10177. case, and use underscores to separate words in the method names (such as, 
  10178. impl_is_ready). 
  10179.  
  10180. DSOM, more than the other SOM Toolkit frameworks, uses a mix of both 
  10181. conventions. The method and class names introduced by CORBA 1.1 are implemented 
  10182. as specified, for application portability. Methods introduced by DSOM to 
  10183. enhance a CORBA-defined class also use the CORBA naming style. The SOM Toolkit 
  10184. convention for method naming is used for non-CORBA classes which are introduced 
  10185. by DSOM. 
  10186.  
  10187.  
  10188. ΓòÉΓòÉΓòÉ 3.3. get_next_response ΓòÉΓòÉΓòÉ
  10189.  
  10190. get_next_response This function returns the next Request object to complete, 
  10191. after starting multiple requests in parallel. 
  10192.  
  10193.  Syntax 
  10194.  
  10195.                     ORBStatus get_next_response (Environment *env, Flags response_flags,
  10196.                                      Request *req)
  10197.  
  10198.  Parameters 
  10199.  
  10200.           env (Environment *) 
  10201.                     A pointer to the Environment structure for the caller. 
  10202.  
  10203.           response_flags (Flags) 
  10204.                     A Flags (unsigned long) variable, used to indicate whether 
  10205.                     the caller wants to wait for the next request to complete 
  10206.                     (0), or not wait (RESP_NO_WAIT). 
  10207.  
  10208.           req (Request *) 
  10209.                     A pointer to a Request object variable. The address of the 
  10210.                     next Request object which completes is returned in the 
  10211.                     Request variable. 
  10212.  
  10213.  Returns 
  10214.  
  10215.           rc (ORBStatus) 
  10216.                     May return a non-zero ORBStatus value, which indicates a 
  10217.                     DSOM error code. (DSOM error codes are listed in Appendix A 
  10218.                     of the SOM Programming Guide.) 
  10219.  
  10220.  Remarks 
  10221.  
  10222.           The get_next_response function returns a pointer to the next Request 
  10223.           object to complete after starting multiple requests in parallel. This 
  10224.           is a synchronization function used in conjunction with the 
  10225.           send_multiple_requests function. There is no specific order in which 
  10226.           requests will complete. 
  10227.  
  10228.           If the response_flags field is set to 0, this function will not 
  10229.           return until the next request completion. If the caller does not want 
  10230.           to become blocked, the RESP_NO_WAIT flag should be specified. 
  10231.  
  10232.  Related Information 
  10233.  
  10234.           Functions 
  10235.  
  10236.               send_multiple_requests 
  10237.  
  10238.           Methods 
  10239.  
  10240.               send 
  10241.               get_response 
  10242.               invoke 
  10243.  
  10244.  Example Code 
  10245.  
  10246.           See the example for the send_multiple_requests function. 
  10247.  
  10248.  
  10249. ΓòÉΓòÉΓòÉ 3.4. ORBfree ΓòÉΓòÉΓòÉ
  10250.  
  10251. ORBfree Frees the memory of return values and out arguments that was allocated 
  10252. by DSOM on behalf of the caller of a remote method. 
  10253.  
  10254.  Syntax 
  10255.  
  10256.                     void ORBfree (void *ptr)
  10257.  
  10258.  Parameters 
  10259.  
  10260.           ptr (void *) 
  10261.                     A pointer to memory that has been dynamically allocated by 
  10262.                     DSOM for a method return value or out argument. 
  10263.  
  10264.  Returns 
  10265.  
  10266.           rc (void) 
  10267.  
  10268.  Remarks 
  10269.  
  10270.           The ORBfree function is used to free memory for method return values 
  10271.           or out arguments which are placed in memory allocated by DSOM (versus 
  10272.           the calling program) on behalf of the caller of a remote method. For 
  10273.           example, strings, arrays, sequence buffers, and "any" values are 
  10274.           returned in memory which is dynamically-allocated by DSOM. 
  10275.  
  10276.           By contrast, memory that DSOM allocates on behalf of the receiver of 
  10277.           a remote method (such as, for an object-owned in parameter) should be 
  10278.           freed using the SOM kernel's SOMFree function rather than ORBfree. 
  10279.  
  10280.           This function is described in section 5.16, "Argument Passing 
  10281.           Considerations", and section 5.17, "Return Result Passing 
  10282.           Considerations", of the CORBA 1.1 specification. 
  10283.  
  10284.  Related Information 
  10285.  
  10286.           Functions 
  10287.  
  10288.               SOMD_NoORBfree 
  10289.               SOMFree (in SOM kernel) 
  10290.  
  10291.  Example Code 
  10292.  
  10293.                     #include  <somd.h>
  10294.                     #include  <myobject.h>     /* provided by user */
  10295.  
  10296.                     MyObject obj;
  10297.                     Environment ev;
  10298.                     string str;
  10299.  
  10300.                     /* assume myMethod has the following IDL declaration
  10301.                     * in the MyObject interface:
  10302.                     *
  10303.                     *    void myMethod(out string s);
  10304.                     */
  10305.                     _myMethod(obj, &ev, &str);
  10306.                     ...
  10307.                     /* free storage */
  10308.                     ORBfree(str);
  10309.  
  10310.  
  10311. ΓòÉΓòÉΓòÉ 3.5. send_multiple_requests ΓòÉΓòÉΓòÉ
  10312.  
  10313. send_multiple_requests This function initiates multiple Requests in parallel. 
  10314.  
  10315.  Syntax 
  10316.  
  10317.                     ORBStatus send_multiple_requests (Request reqs, Environment *env,
  10318.                                        long count, Flags invoke_flags)
  10319.  
  10320.  Parameters 
  10321.  
  10322.           reqs (Request) 
  10323.                     The address of an array of Requests objects which are to be 
  10324.                     initiated in parallel. 
  10325.  
  10326.           env (Environment *) 
  10327.                     A pointer to the Environment structure for the caller. 
  10328.  
  10329.           count (long) 
  10330.                     The number of Request objects in reqs. 
  10331.  
  10332.           invoke_flags (Flags) 
  10333.                     A Flags (unsigned long) value, used to indicate the 
  10334.                     following options: 
  10335.  
  10336.                     INV_NO_RESPONSE              Indicates the caller does not 
  10337.                                                  intend to get any results or 
  10338.                                                  out parameter values from any 
  10339.                                                  of the requests. The requests 
  10340.                                                  can be treated as if they are 
  10341.                                                  oneway operations. 
  10342.                     INV_TERM_ON_ERR              If one of the requests causes 
  10343.                                                  an error, the remaining 
  10344.                                                  requests are not sent. 
  10345.  
  10346.                                                  The above flag values may be 
  10347.                                                  "or"-ed together. 
  10348.  
  10349.  Returns 
  10350.  
  10351.           rc (ORBStatus) 
  10352.                     May return a non-zero ORBStatus value, which indicates a 
  10353.                     DSOM error code. (DSOM error codes are listed in Appendix A 
  10354.                     of the SOM Programming Guide.) 
  10355.  
  10356.  Remarks 
  10357.  
  10358.           The send_multiple_requests function initiates multiple Requests "in 
  10359.           parallel". (The actual degree of parallelism is system dependent.) 
  10360.           Each Request object is created using the create_request method, 
  10361.           defined on SOMDClientProxy. Like the send method, this function 
  10362.           returns to the caller immediately without waiting for the Requests to 
  10363.           finish. The caller waits for the request responses using the 
  10364.           get_next_response function. 
  10365.  
  10366.           This function is described in section 6.3, "Deferred Synchronous 
  10367.           Routines", of the CORBA 1.1 specification. 
  10368.  
  10369.  Related Information 
  10370.  
  10371.           Functions 
  10372.  
  10373.               get_next_response 
  10374.  
  10375.           Methods 
  10376.  
  10377.               send 
  10378.               get_response 
  10379.               invoke 
  10380.  
  10381.  Example Code 
  10382.  
  10383.                     #include  <somd.h>
  10384.  
  10385.                     /* sum a set of values in parallel */
  10386.                     int parallel_sum(Environment *ev, int n, SOMDObject *objs)
  10387.                     {
  10388.                        int index, sum = 0;
  10389.                        Request *next;
  10390.                        Request *reqs = (Request*) SOMMalloc(n *sizeof(Request));
  10391.                        NamedValue *results = (NamedValue*)
  10392.                                            SOMMalloc(n * sizeof(Namedvalue));
  10393.  
  10394.                        for (i=0; i < n; i++)
  10395.                           (void) _create_request((Context *)NULL, "_get_count", NULL,
  10396.                                               &(result[i]), &(reqs[i]), (Flags)0);
  10397.  
  10398.                        (void)  send_multiple_requests(reqs, ev, n, (Flags)0);
  10399.  
  10400.                        for (i=0, i < n; i++)  {
  10401.                           (void)  get_next_response(ev, (Flags)0, &next);
  10402.                           index = (next - reqs);
  10403.                           sum += *((int*)results[index].argument._value);
  10404.                     }
  10405.  
  10406.                        return(sum);
  10407.                     }
  10408.  
  10409.  
  10410. ΓòÉΓòÉΓòÉ 3.6. somdExceptionFree ΓòÉΓòÉΓòÉ
  10411.  
  10412. somdExceptionFree Frees the memory held by the exception structure within an 
  10413. Environment structure, regardless of whether the exception was returned by a 
  10414. local or a remote method call. 
  10415.  
  10416.  Syntax 
  10417.  
  10418.                     void somdExceptionFree (Environment *env)
  10419.  
  10420.  Parameters 
  10421.  
  10422.           env (Environment *) 
  10423.                     The Environment structure whose exception information is to 
  10424.                     be freed. 
  10425.  
  10426.  Returns 
  10427.  
  10428.           rc (void) 
  10429.  
  10430.  Remarks 
  10431.  
  10432.           The somdExceptionFree function frees the memory held by the exception 
  10433.           structure within an Environment structure, regardless of whether the 
  10434.           exception was returned by a local or a remote method call. 
  10435.  
  10436.           When a DSOM client program invokes a remote method and the method 
  10437.           returns an exception in the Environment structure, it is the client's 
  10438.           responsibility to free the exception. This is done by calling either 
  10439.           exception_free or somdExceptionFree on the Environment structure in 
  10440.           which the exception was returned. (The two functions are equivalent. 
  10441.           The exception_free function name is #defined in the som.h or som.xh 
  10442.           file to provide strict CORBA compliance of function names.) There is 
  10443.           a similar function, somExceptionFree, available for SOM programmers; 
  10444.           DSOM programmers, however, can use somdExceptionFree to free all 
  10445.           exceptions (regardless of whether they were returned from a local or 
  10446.           a remote method call). 
  10447.  
  10448.  Related Information 
  10449.  
  10450.           Functions 
  10451.  
  10452.               somExceptionFree 
  10453.               somExceptionID 
  10454.               somExceptionValue 
  10455.               somSetExceptionException 
  10456.               All SOM Kernel Functions 
  10457.  
  10458.           Data Structures 
  10459.  
  10460.               Environment 
  10461.  
  10462.  Example Code 
  10463.  
  10464.                     X_foo(x, ev, 23);  /* make a remote method call */
  10465.                     if (ev->major != NO_EXCEPTION)
  10466.                     {
  10467.                         printf("foo exception = %s\n", somExceptionId(ev));
  10468.  
  10469.                         /* ... handle exception ... */
  10470.  
  10471.                         somdExceptionFree(ev);  /* free exception */
  10472.                     }
  10473.  
  10474.  
  10475. ΓòÉΓòÉΓòÉ 3.7. SOMD_Init ΓòÉΓòÉΓòÉ
  10476.  
  10477. SOMD_Init This function initializes DSOM in the calling process. 
  10478.  
  10479.  Syntax 
  10480.  
  10481.                     void SOMD_Init (Environment *env)
  10482.  
  10483.  Parameters 
  10484.  
  10485.           env (Environment *) 
  10486.                     A pointer to the Environment structure for the method 
  10487.                     caller. 
  10488.  
  10489.  Returns 
  10490.  
  10491.           rc (void) 
  10492.  
  10493.  Remarks 
  10494.  
  10495.           Initializes DSOM in the calling process. This function should be 
  10496.           called before any other DSOM functions or methods. This function 
  10497.           should only be invoked (a) at the beginning of a DSOM program (client 
  10498.           or server), to initialize the program, or (b) after SOMD_Uninit has 
  10499.           been invoked, to reinitialize the program. If the program has already 
  10500.           been initialized with SOMD_Init, then invoking SOMD_Init again has no 
  10501.           effect. 
  10502.  
  10503.           An effect of calling SOMD_Init is that the global variables 
  10504.           SOMD_ObjectMgr, SOMD_ImplRepObject, and SOMD_ORBObject, are 
  10505.           initialized with pointers to the (single) instances of the 
  10506.           SOMDObjectMgr, ImplRepository, and ORB objects. 
  10507.  
  10508.           The global variables SOMD_ObjectMgr, SOMD_ImplRepObject, and 
  10509.           SOMD_ORBObject are set implicitly. 
  10510.  
  10511.           See Chapter 6 on DSOM in the SOM Programming Guide. 
  10512.  
  10513.  Example Code 
  10514.  
  10515.                     #include  <somd.h>
  10516.  
  10517.                     Environment ev;
  10518.  
  10519.                     /* initialize Environment */
  10520.                     SOM_InitEnvironment(&ev);
  10521.  
  10522.                     /* initialize DSOM runtime */
  10523.                     SOMD_Init(&ev);
  10524.                     ...
  10525.  
  10526.                     /* Free DSOM resources */
  10527.                     SOMD_Uninit(&ev);
  10528.  
  10529.  
  10530. ΓòÉΓòÉΓòÉ 3.8. SOMD_NoORBfree ΓòÉΓòÉΓòÉ
  10531.  
  10532. SOMD_NoORBfree This function specifies to DSOM that the client program will use 
  10533. the SOMFree function to free memory allocated by DSOM, rather than using the 
  10534. ORBfree function. 
  10535.  
  10536.  Syntax 
  10537.  
  10538.                     void SOMD_NoORBfree ()
  10539.  
  10540.  Parameters 
  10541.  
  10542.                     None. 
  10543.  
  10544.  Returns 
  10545.  
  10546.           rc (void) 
  10547.  
  10548.  Remarks 
  10549.  
  10550.           The SOMD_NoORBfree function is used in a DSOM client program to 
  10551.           specify to DSOM that the client program will use the SOMFree function 
  10552.           to free memory allocated by DSOM, rather than using the ORBfree 
  10553.           function. 
  10554.  
  10555.           Typically, a DSOM client program will use SOMFree to free memory 
  10556.           returned from local method calls and ORBfree to free memory returned 
  10557.           from remote method calls. The SOMD_NoORBfree function allows 
  10558.           programmers to use a single function (SOMFree) to free blocks of 
  10559.           memory, regardless of whether they were allocated locally or by DSOM 
  10560.           in response to a remote method call. 
  10561.  
  10562.           SOMD_NoORBfree, if used, should be called just after calling 
  10563.           SOMD_Init in the client program. In response to this call, DSOM will 
  10564.           not keep track of the memory it allocates for the client. Instead, it 
  10565.           will assume that the client program will be responsible for walking 
  10566.           all data structures returned from remote method calls, calling 
  10567.           SOMFree for each block of memory within. 
  10568.  
  10569.  Related Information 
  10570.  
  10571.           Functions 
  10572.  
  10573.               ORBfree 
  10574.               SOMFree 
  10575.  
  10576.  Example Code 
  10577.  
  10578.                     SOMD_Init();
  10579.                     SOMD_NoORBfree();
  10580.  
  10581.                     /* rest of client program */
  10582.  
  10583.  
  10584. ΓòÉΓòÉΓòÉ 3.9. SOMD_RegisterCallback ΓòÉΓòÉΓòÉ
  10585.  
  10586. SOMD_RegisterCallback This function registers a callback function for handling 
  10587. DSOM request events. 
  10588.  
  10589.  Syntax 
  10590.  
  10591.                     void SOMD_RegisterCallback (SOMEEMan emanObj,
  10592.                                     EMRegProc *func)
  10593.  
  10594.  Parameters 
  10595.  
  10596.           emanObj (SOMEEMan) 
  10597.                     A pointer to an instance of SOMEEman, the Event Manager 
  10598.                     object. 
  10599.  
  10600.           func (EMRegProc *) 
  10601.                     A pointer to an event handler function which will be called 
  10602.                     by EMan whenever a DSOM request arrives. This function must 
  10603.                     have the following prototype (equivalent to the EMRegProc 
  10604.                     type defined in "eman.h"): 
  10605.  
  10606.                                         #ifdef __OS2__
  10607.                                          #pragma linkage( func, system)
  10608.                                         #endif
  10609.  
  10610.  
  10611.                                         void SOMLINK func (SOMEEvent event, void *eventData)
  10612.                                         /* On Windows, using the SOMLINK keywork precludes
  10613.                                          * the support of multiple instances. */
  10614.  
  10615.  Returns 
  10616.  
  10617.           rc (void) 
  10618.  
  10619.  Remarks 
  10620.  
  10621.           When writing event-driven applications where there are event sources 
  10622.           other than DSOM requests (e.g., user input, mouse clicks, etc.), DSOM 
  10623.           cannot be given exclusive control of the "main loop," such as when 
  10624.           execute_request_loop is called. Instead, the application should use 
  10625.           the Event Manager (EMan) framework to register and process all 
  10626.           application events. 
  10627.  
  10628.           The SOMD_RegisterCallback function is used to register a 
  10629.           user-supplied DSOM event handler function with EMan. The caller need 
  10630.           only supply an address of the event handler function, and the 
  10631.           instance of the EMan object -- the details of registration are 
  10632.           implemented by SOMD_RegisterCallback. 
  10633.  
  10634.           Callback functions should have the SOMLINK keyword explicitly 
  10635.           specified, except on Windows. Using an explicit SOMLINK keyword on 
  10636.           Windows will preclude the ability of an application to support 
  10637.           multiple instances. 
  10638.  
  10639.           Note:  The function SOMD_RegisterCallback must be declared with 
  10640.           "system linkage" on OS/2. 
  10641.  
  10642.           See Chapter 9 of the SOM Programming Guide for a description of the 
  10643.           Event Manager (EMan) framework, for writing event-driven 
  10644.           applications. 
  10645.  
  10646.  Example Code 
  10647.  
  10648.                     #include  <somd.h>
  10649.                     #include  <eman.h>
  10650.  
  10651.                     #ifdef __OS2__
  10652.                      #pragma linkage(SOMD*RegisterCallback, system)
  10653.                      #pragma linkage(DSOMEventCallBack, system)
  10654.                     #endif
  10655.  
  10656.                     /* On Windows, this example would omit the SOMLINK keyword. */
  10657.  
  10658.                     void SOMLINK DSOMEventCallBack (SOMEEvent event, void *eventData)
  10659.                     {
  10660.                        Environment ev;
  10661.                        SOM_InitEnvironment(&ev);
  10662.  
  10663.                        _execute_request_loop (SOMD_SOMOAObject, &ev, SOMD_NO_WAIT);
  10664.                     }
  10665.  
  10666.                     main()
  10667.                     {
  10668.  
  10669.                        ...
  10670.                        eman = SOMEEmanNew();
  10671.                        SOMD_RegisterCallback(eman, DSOMEventCallBack);
  10672.  
  10673.                        _someProcessEvents(eman, &ev);   /* main loop */
  10674.                        ...
  10675.  
  10676.                     }
  10677.  
  10678.  
  10679. ΓòÉΓòÉΓòÉ 3.10. SOMD_Uninit ΓòÉΓòÉΓòÉ
  10680.  
  10681. SOMD_Uninit This function frees system resources allocated for use by DSOM. 
  10682.  
  10683.  Syntax 
  10684.  
  10685.                     void SOMD_Uninit (Environment *env)
  10686.  
  10687.  Parameters 
  10688.  
  10689.           env (Environment *) 
  10690.                     A pointer to the Environment structure for the method 
  10691.                     caller. 
  10692.  
  10693.  Returns 
  10694.  
  10695.           rc (void) 
  10696.  
  10697.  Remarks 
  10698.  
  10699.           Frees system resources (shared memory segments, semaphores, etc.) 
  10700.           allocated to the calling process for use by DSOM. This function 
  10701.           should be called before a process exits, to ensure system resources 
  10702.           are reused. 
  10703.  
  10704.           No DSOM functions or methods should be called after SOMD_Uninit has 
  10705.           been called. After SOMD_Uninit is called, the program can be 
  10706.           reinitialized by calling SOMD_Init. (SOMD_Uninit would then need to 
  10707.           be called again before program termination, to uninitialize the 
  10708.           program.) 
  10709.  
  10710.           See Chapter 6 on DSOM in the SOM Programming Guide. 
  10711.  
  10712.  Example Code 
  10713.  
  10714.                     #include  <somd.h>
  10715.  
  10716.                     Environment ev;
  10717.  
  10718.                     /* initialize Environment */
  10719.                     SOM_InitEnvironment(&ev);
  10720.  
  10721.                     /* initialize DSOM runtime */
  10722.                     SOMD_Init(&ev);
  10723.                     ...
  10724.                     /* Free DSOM resources */
  10725.                     SOMD_Uninit(&ev);
  10726.  
  10727.  
  10728. ΓòÉΓòÉΓòÉ 3.11. Context_delete Macro ΓòÉΓòÉΓòÉ
  10729.  
  10730. Context_delete Macro This macro deletes a Context object. 
  10731.  
  10732.  Syntax 
  10733.  
  10734.                     ORBStatus Context_delete Macro (Context ctxobj, Environment *env,
  10735.                                        Flags del_flag)
  10736.  
  10737.  Parameters 
  10738.  
  10739.           ctxobj (Context) 
  10740.                     A pointer to the Context object to be deleted. 
  10741.  
  10742.           env (Environment *) 
  10743.                     A pointer to the Environment structure for the caller. 
  10744.  
  10745.           del_flag (Flags) 
  10746.                     A bitmask (unsigned long). If the flag 
  10747.                     CTX_DELETE_DESCENDANTS is specified, the macro deletes the 
  10748.                     specified Context object and all of its descendant Context 
  10749.                     objects. A zero value indicates that the flag is not set. 
  10750.  
  10751.  Returns 
  10752.  
  10753.           rc (ORBStatus) 
  10754.  
  10755.  Remarks 
  10756.  
  10757.           This macro deletes the specified Context object. This macro maps to 
  10758.           the destroy method of the Context class. 
  10759.  
  10760.  Expansion 
  10761.  
  10762.           Context_destroy ( ctxobj, env, del_flag ) 
  10763.  
  10764.  Related Information 
  10765.  
  10766.           Methods 
  10767.  
  10768.               Context_destroy 
  10769.  
  10770.  Example Code 
  10771.  
  10772.                     #include <somd.h>
  10773.  
  10774.                     Environment ev;
  10775.                     Context cxt, newcxt;
  10776.                     long rc;
  10777.                     ...
  10778.                     /* get the process' default Context */
  10779.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  10780.  
  10781.                     /* make newcxt a child Context of the default Context (cxt) */
  10782.                     rc = _create_child(cxt, &ev, "myContext", &newcxt);
  10783.                     ...
  10784.                     /* assuming no descendent Contexts have been
  10785.                      * created from newcxt, we can destroy newcxt with flags=0
  10786.                      */
  10787.                     rc = Context_delete(newcxt, &ev, (Flags) 0);
  10788.  
  10789.  
  10790. ΓòÉΓòÉΓòÉ 3.12. Request_delete Macro ΓòÉΓòÉΓòÉ
  10791.  
  10792. Request_delete Macro This macro deletes the memory allocated by the ORB for a 
  10793. Request object. 
  10794.  
  10795.  Syntax 
  10796.  
  10797.                     ORBStatus Request_delete Macro (Request reqobj, Environment *env)
  10798.  
  10799.  Parameters 
  10800.  
  10801.           reqobj (Request) 
  10802.                     A pointer to the Request object to be deleted. 
  10803.  
  10804.           env (Environment *) 
  10805.                     A pointer to the Environment structure for the caller. 
  10806.  
  10807.  Returns 
  10808.  
  10809.           rc (ORBStatus) 
  10810.  
  10811.  Remarks 
  10812.  
  10813.           This macro deletes the specified Request object and all associated 
  10814.           memory. This macro maps to the destroy method of the Request class. 
  10815.  
  10816.  Expansion 
  10817.  
  10818.           Request_destroy ( reqobj, env ) 
  10819.  
  10820.  Related Information 
  10821.  
  10822.           Methods 
  10823.  
  10824.               Request_destroy 
  10825.  
  10826.  Example Code 
  10827.  
  10828.                     #include <somd.h>
  10829.                     #include <repostry.h>
  10830.                     #include <intfacdf.h>
  10831.                     #include <foo.h>   /* provided by user */
  10832.  
  10833.                     /* assume following method declaration in interface Foo:
  10834.                      *    long methodLong  (in long inLong,inout long inoutLong);
  10835.                      * then the following code sends a request to execute the call:
  10836.                      *  result = methodLong(fooObj, &ev, 100,200);
  10837.                      * using the DII without waiting for the result. Then, later,
  10838.                      * waits for and then uses the result.
  10839.                      */
  10840.                     Environment ev;
  10841.                     NVList arglist;
  10842.                     long rc;
  10843.                     Foo fooObj;
  10844.                     Request reqObj;
  10845.                     NamedValue result;
  10846.  
  10847.                     /* see the Example code for invoke to see how the request
  10848.                      * is built
  10849.                      */
  10850.  
  10851.                     /* Create the Request, reqObj */
  10852.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  10853.                                          arglist, &result, &reqObj, (Flags)0);
  10854.  
  10855.                     /* Finally, send the request */
  10856.                     rc = _send(reqObj, &ev, (Flags)0);
  10857.  
  10858.                     /* do some work, i.e. don't wait for the result */
  10859.  
  10860.                     /* wait here for the result of the request */
  10861.                     rc = _get_response(reqObj, &ev, (Flags)0);
  10862.  
  10863.                     /* use the result */
  10864.                     if (result->argument._value == 9600) {...}
  10865.  
  10866.                     /* throw away the reqObj */
  10867.                     Request_delete(reqObj, &ev);
  10868.  
  10869.  
  10870. ΓòÉΓòÉΓòÉ 3.13. BOA ΓòÉΓòÉΓòÉ
  10871.  
  10872. BOA 
  10873.  
  10874.  File stem: boa 
  10875.  
  10876.  Base 
  10877.  
  10878.           SOMObject 
  10879.  
  10880.  Metaclass 
  10881.  
  10882.           SOMMSingleInstance 
  10883.  
  10884.  Ancestor Class 
  10885.  
  10886.                     SOMObject
  10887.  
  10888.  Subclass 
  10889.  
  10890.                     SOMOA
  10891.  
  10892.  Description 
  10893.  
  10894.           The Basic Object Adapter (BOA) defines the basic interfaces that a 
  10895.           server process uses to access services of an Object Request Broker 
  10896.           like DSOM. The BOA defines methods for creating and exporting object 
  10897.           references, registering implementations, activating implementations 
  10898.           and authenticating requests. 
  10899.  
  10900.           For more information on the Basic Object Adapter, refer to Chapter 9 
  10901.           in the CORBA 1.1 specification. 
  10902.  
  10903.           Note:  DSOM treats the BOA interface as an abstract class, which 
  10904.           merely defines basic runtime interfaces (introduced in the CORBA 
  10905.           specification) but does not implement those interfaces. Thus, there 
  10906.           is no point in instantiating a BOA object. If a BOA object is 
  10907.           created, any methods invoked on it will return a NO_IMPLEMENT 
  10908.           exception. Instead, the SOM Object Adapter (SOMOA) subclass provides 
  10909.           DSOM implementations for BOA methods. When a BOA method is invoked on 
  10910.           the SOMOA object, the desired behavior will occur. 
  10911.  
  10912.  New methods 
  10913.  
  10914.           The following list shows all the BOA methods. 
  10915.  
  10916.               change_implementation 
  10917.               create 
  10918.               deactivate_impl 
  10919.               deactivate_obj 
  10920.               dispose 
  10921.               get_id 
  10922.               get_principal 
  10923.               impl_is_ready 
  10924.               obj_is_ready 
  10925.               set_exception 
  10926.  
  10927.  Overridden methods 
  10928.  
  10929.           There are currently no overridden methods defined for the BOA class. 
  10930.  
  10931.  
  10932. ΓòÉΓòÉΓòÉ 3.14. change_implementation ΓòÉΓòÉΓòÉ
  10933.  
  10934. change_implementation This method changes the implementation associated with 
  10935. the referenced object. (Not implemented.) 
  10936.  
  10937.  Syntax 
  10938.  
  10939.                     void change_implementation (BOA receiver, Environment *env,
  10940.                                     SOMDObject obj, ImplementationDef impl)
  10941.  
  10942.  Parameters 
  10943.  
  10944.           receiver (BOA) 
  10945.                     A pointer to a BOA (SOMOA) object for the server. 
  10946.  
  10947.           env (Environment *) 
  10948.                     A pointer to the Environment structure for the method 
  10949.                     caller. 
  10950.  
  10951.           obj (SOMDObject) 
  10952.                     A pointer to the SOMDObject object which refers to the 
  10953.                     application object whose implementation is to be changed. 
  10954.  
  10955.           impl (ImplementationDef) 
  10956.                     A pointer to the ImplementationDef object representing the 
  10957.                     new implementation of the application object. 
  10958.  
  10959.  Returns 
  10960.  
  10961.           rc (void) 
  10962.                     The SOMOA implementation always returns a NO_IMPLEMENT 
  10963.                     exception, with a minor code of SOMDERROR_NotImplemented. 
  10964.  
  10965.  Remarks 
  10966.  
  10967.           The change_implementation method is defined by the CORBA 
  10968.           specification, but has a null implementation in DSOM. This method 
  10969.           always returns a NO_IMPLEMENT exception. 
  10970.  
  10971.           In CORBA 1.1, the change_implementation method is provided to allow 
  10972.           an application to change the implementation definition of an object. 
  10973.  
  10974.           However, in DSOM, the ImplementationDef identifies the server which 
  10975.           implements an object. In these terms, changing an object's 
  10976.           implementation (i.e., server) would result in a change in the 
  10977.           object's location. In DSOM, moving objects from one server to another 
  10978.           is considered an application-specific task, and hence, no default 
  10979.           implementation is provided. 
  10980.  
  10981.           It is possible, however, to change the program which implements an 
  10982.           object's server, or change the class library which implements an 
  10983.           object's class. To modify the program associated with an 
  10984.           ImplementationDef, use the update_impldef method defined on 
  10985.           ImplRepository. To change the implementation of an object's class, 
  10986.           replace the corresponding class library with a new 
  10987.           (upward-compatible) one. 
  10988.  
  10989.  Original Class 
  10990.  
  10991.           BOA 
  10992.  
  10993.  
  10994. ΓòÉΓòÉΓòÉ 3.15. create ΓòÉΓòÉΓòÉ
  10995.  
  10996. create This method creates a "reference" for a local application object which 
  10997. can be exported to remote clients. 
  10998.  
  10999.  Syntax 
  11000.  
  11001.                     SOMDObject create (BOA receiver, Environment *env,
  11002.                                ReferenceData id, InterfaceDef intf,
  11003.                                ImplementationDef impl)
  11004.  
  11005.  Parameters 
  11006.  
  11007.           receiver (BOA) 
  11008.                     A pointer to a BOA (SOMOA) object for the server. 
  11009.  
  11010.           env (Environment *) 
  11011.                     A pointer to the Environment structure for the method 
  11012.                     caller. 
  11013.  
  11014.           id (ReferenceData) 
  11015.                     A pointer to the ReferenceData structure containing 
  11016.                     application-specific information describing the target 
  11017.                     object. 
  11018.  
  11019.           intf (InterfaceDef) 
  11020.                     A pointer to the InterfaceDef object which describes the 
  11021.                     interface of the target object. 
  11022.  
  11023.           impl (ImplementationDef) 
  11024.                     A pointer to the ImplementationDef object which describes 
  11025.                     the application (server) process which implements the 
  11026.                     target object. 
  11027.  
  11028.  Returns 
  11029.  
  11030.           rc (SOMDObject) 
  11031.                     Returns a pointer to a SOMDObject which refers to a local 
  11032.                     application object. 
  11033.  
  11034.  Remarks 
  11035.  
  11036.           The create method creates a SOMDObject  which is used as a 
  11037.           "reference" to a local application object. An object reference is 
  11038.           simply an object which is used to refer to another target object -- 
  11039.           one may think of it as an "id",  "link", or "handle." Object 
  11040.           references are important in DSOM in that their values can be 
  11041.           externalized (i.e., can be represented in a string form) for 
  11042.           transmission between processes, storage in files, and so on. In DSOM, 
  11043.           the proxy objects in client processes are remote object references. 
  11044.  
  11045.           File somdtype.idl contains the specification: typedef 
  11046.           sequence<octet,1024> ReferenceData. To create an object reference, 
  11047.           the caller specifies the  ImplementationDef of the calling process, 
  11048.           the InterfaceDef of the target application object, and up to 1024 
  11049.           bytes of ReferenceData which is used by the application to identify 
  11050.           and activate the application object. When subsequent method calls 
  11051.           specify the object reference as a parameter, the application will use 
  11052.           the reference to find and/or activate the referenced object. 
  11053.  
  11054.           Note that (as specified in CORBA 1.1) each call to create returns a 
  11055.           unique object reference, even if the same parameters are used in 
  11056.           subsequent calls. For each reference, the ReferenceData is stored in 
  11057.           the reference data file (and backup file, if any) for the server. 
  11058.  
  11059.           The SOMOA class introduces a change_id method which allows a server 
  11060.           to modify the ReferenceData of one of its references. (The change_id 
  11061.           method is not in the CORBA 1.1 specification.) 
  11062.  
  11063.           Ownership of the returned SOMDObjectis transferred to the caller. 
  11064.  
  11065.  Original Class 
  11066.  
  11067.           BOA 
  11068.  
  11069.  Related Methods 
  11070.  
  11071.           Methods 
  11072.  
  11073.               change_id 
  11074.               create_constant 
  11075.               create_SOM_ref 
  11076.               dispose 
  11077.               get_id 
  11078.  
  11079.  Example Code 
  11080.  
  11081.                     #include  <somd.h>
  11082.                     #include  <repostry.h>
  11083.                     #include  <intfacdf.h>
  11084.  
  11085.                     Environment ev;
  11086.                     ReferenceData id;
  11087.                     InterfaceDef intfdef;
  11088.                     SOMDObject objref;
  11089.                     string fname; /* a file name to be saved with reference */
  11090.                     ...
  11091.                     /* create the id for the reference */
  11092.                     id._maximum = id._length = strlen(fname)+1;
  11093.                     id._buffer = (string) SOMMalloc(strlen(fname)+1);
  11094.                     strcpy(id._buffer,fname);
  11095.  
  11096.                     /* get the interface def object for interface Foo*/
  11097.                     intfdef = _lookup_id(SOM_InterfaceRepository, &ev, "Foo");
  11098.  
  11099.                     objref =  _create(SOMD_SOMOAObject,
  11100.                                     &ev, id, intfdef, SOMD_ImplDefObject);
  11101.                     ...
  11102.  
  11103.  
  11104. ΓòÉΓòÉΓòÉ 3.16. deactivate_impl ΓòÉΓòÉΓòÉ
  11105.  
  11106. deactivate_impl This method indicates that a server implementation is no longer 
  11107. ready to process requests. 
  11108.  
  11109.  Syntax 
  11110.  
  11111.                     void deactivate_impl (BOA receiver, Environment *env,
  11112.                                 ImplementationDef impl)
  11113.  
  11114.  Parameters 
  11115.  
  11116.           receiver (BOA) 
  11117.                     A pointer to a BOA (SOMOA) object for the server. 
  11118.  
  11119.           env (Environment *) 
  11120.                     A pointer to the Environment structure for the method 
  11121.                     caller. 
  11122.  
  11123.           impl (ImplementationDef) 
  11124.                     A pointer to the ImplementationDef object representing the 
  11125.                     implementation to be deactivated. 
  11126.  
  11127.  Returns 
  11128.  
  11129.           rc (void) 
  11130.  
  11131.  Remarks 
  11132.  
  11133.           The deactivate_impl method indicates that the implementation is no 
  11134.           longer ready to process requests. 
  11135.  
  11136.  Original Class 
  11137.  
  11138.           BOA 
  11139.  
  11140.  Related Methods 
  11141.  
  11142.           Methods 
  11143.  
  11144.               impl_is_ready 
  11145.               activate_imple_failed 
  11146.               execute_request_loop 
  11147.               execute_next_request 
  11148.  
  11149.  Example Code 
  11150.  
  11151.                     #include  <somd.h>
  11152.  
  11153.                     ORBStatus rc;
  11154.  
  11155.                     /* server initialization code ... */
  11156.  
  11157.                     /* signal DSOM that server is ready */
  11158.                     _impl_is_ready(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  11159.  
  11160.                     for(rc = 0;rc==0;) {
  11161.                         rc = _execute_next_request(SOMD_SOMOAObject, &ev, waitFlag);
  11162.                         /* perform app specific code between messages here, e.g.,*/
  11163.                         numMessagesProcessed++;
  11164.                     }
  11165.  
  11166.                     /* signal DSOM that server is deactivated */
  11167.                     _deactivate_impl(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  11168.  
  11169.  
  11170. ΓòÉΓòÉΓòÉ 3.17. deactivate_obj ΓòÉΓòÉΓòÉ
  11171.  
  11172. deactivate_obj This method indicates that an object server is no longer ready 
  11173. to process requests. (Not implemented.) 
  11174.  
  11175.  Syntax 
  11176.  
  11177.                     void deactivate_obj (BOA receiver, Environment *env,
  11178.                                 SOMDObject obj)
  11179.  
  11180.  Parameters 
  11181.  
  11182.           receiver (BOA) 
  11183.                     A pointer to a BOA (SOMOA) object for the server. 
  11184.  
  11185.           env (Environment *) 
  11186.                     A pointer to the Environment structure for the method 
  11187.                     caller. 
  11188.  
  11189.           obj (SOMDObject) 
  11190.                     A pointer to a SOMDObject which identifies the object 
  11191.                     (server) to be deactivated. 
  11192.  
  11193.  Returns 
  11194.  
  11195.           rc (void) 
  11196.  
  11197.  Remarks 
  11198.  
  11199.           The deactivate_obj method is defined by the CORBA specification, but 
  11200.           has a null implementation in DSOM. This method always returns a 
  11201.           NO_IMPLEMENT exception. 
  11202.  
  11203.           CORBA 1.1 distinguishes between servers that implement many objects 
  11204.           ("shared"), versus qervers that implement a single object 
  11205.           ("unshared"). The deactivate_obj method is meant to be used by 
  11206.           unshared servers, to indicate that the object (i.e., server) is no 
  11207.           longer ready to process requests. 
  11208.  
  11209.           DSOM does not distinguish between servers that implement a single 
  11210.           object versus servers that implement multiple objects, so this method 
  11211.           has no implementation. 
  11212.  
  11213.  Original Class 
  11214.  
  11215.           BOA 
  11216.  
  11217.  Related Methods 
  11218.  
  11219.           Methods 
  11220.  
  11221.               deactivate_impl 
  11222.               impl_is_ready 
  11223.               obj_is_ready 
  11224.  
  11225.  
  11226. ΓòÉΓòÉΓòÉ 3.18. dispose ΓòÉΓòÉΓòÉ
  11227.  
  11228. dispose This method destroys an object reference. 
  11229.  
  11230.  Syntax 
  11231.  
  11232.                     void dispose (BOA receiver, Environment *env, SOMDObject obj)
  11233.  
  11234.  Parameters 
  11235.  
  11236.           receiver (BOA) 
  11237.                     A pointer to a BOA object for the server. 
  11238.  
  11239.           env (Environment *) 
  11240.                     A pointer to the Environment structure for the method 
  11241.                     caller. 
  11242.  
  11243.           obj (SOMDObject) 
  11244.                     A pointer to the object reference to be destroyed. 
  11245.  
  11246.  Returns 
  11247.  
  11248.           rc (void) 
  11249.  
  11250.  Remarks 
  11251.  
  11252.           The dispose method disposes of an object reference. 
  11253.  
  11254.  Original Class 
  11255.  
  11256.           BOA 
  11257.  
  11258.  Related Methods 
  11259.  
  11260.           Methods 
  11261.  
  11262.               create 
  11263.               create_constant 
  11264.               create_SOM_ref 
  11265.               get_id 
  11266.  
  11267.  Example Code 
  11268.  
  11269.                     #include  <somd.h>
  11270.                     #include  <repostry.h>
  11271.                     #include  <intfacdf.h>
  11272.  
  11273.                     SOMDObject objref;
  11274.                     ReferenceData id;
  11275.                     InterfaceDef intfdef;
  11276.                     ...
  11277.                     objref =
  11278.                      _create(SOMD_SOMOAObject, &ev, id, intfdef, SOMD_ImplDefObject);
  11279.                     ...
  11280.                     _dispose(SOMD_SOMOAObject, &ev, objref);
  11281.  
  11282.  
  11283. ΓòÉΓòÉΓòÉ 3.19. get_id ΓòÉΓòÉΓòÉ
  11284.  
  11285. get_id This method returns reference data associated with the referenced 
  11286. object. 
  11287.  
  11288.  Syntax 
  11289.  
  11290.                     ReferenceData get_id (BOA receiver, Environment *env,
  11291.                                  SOMDObject obj)
  11292.  
  11293.  Parameters 
  11294.  
  11295.           receiver (BOA) 
  11296.                     A pointer to  a BOA (SOMOA) object for the server. 
  11297.  
  11298.           env (Environment *) 
  11299.                     A pointer to the Environment structure for the method 
  11300.                     caller. 
  11301.  
  11302.           obj (SOMDObject) 
  11303.                     A pointer to a SOMDObject object for which to return the 
  11304.                     ReferenceData. 
  11305.  
  11306.  Returns 
  11307.  
  11308.           rc (ReferenceData) 
  11309.                     Returns a ReferenceData structure associated with the 
  11310.                     referenced object. 
  11311.  
  11312.  Remarks 
  11313.  
  11314.           The get_id method returns the reference data associated with the 
  11315.           referenced object. 
  11316.  
  11317.  Original Class 
  11318.  
  11319.           BOA 
  11320.  
  11321.  Related Methods 
  11322.  
  11323.           Methods 
  11324.  
  11325.               create 
  11326.               create_constant 
  11327.               dispose 
  11328.  
  11329.  Example Code 
  11330.  
  11331.                     #include  <somd.h>
  11332.                     #include  <repostry.h>
  11333.                     #include  <intfacdf.h>
  11334.  
  11335.                     SOMDObject objref;
  11336.                     ReferenceData id1, id2;
  11337.                     InterfaceDef intfdef;
  11338.                     ...
  11339.                     objref =
  11340.                      _create(SOMD_SOMOAObject,&ev, id1, intfdef, SOMD_ImplDefObject);
  11341.                     ...
  11342.                     /* get the ReferenceData from a SOMDObject */
  11343.                     id2 =  _get_id(SOMD_SOMOAObject, &ev, objref);
  11344.  
  11345.  
  11346. ΓòÉΓòÉΓòÉ 3.20. get_principal ΓòÉΓòÉΓòÉ
  11347.  
  11348. get_principal This method returns the ID of the principal that issued the 
  11349. request. 
  11350.  
  11351.  Syntax 
  11352.  
  11353.                     Principal get_principal (BOA receiver, Environment *env,
  11354.                                  SOMDObject obj, Environment *req_ev)
  11355.  
  11356.  Parameters 
  11357.  
  11358.           receiver (BOA) 
  11359.                     A pointer to a BOA (SOMOA) object for the server. 
  11360.  
  11361.           env (Environment *) 
  11362.                     A pointer to the Environment structure for the method 
  11363.                     caller. 
  11364.  
  11365.           obj (SOMDObject) 
  11366.                     A pointer to the object reference which is the target of 
  11367.                     the method call. 
  11368.  
  11369.           req_ev (Environment *) 
  11370.                     A pointer to the Environment object passed as input to the 
  11371.                     request. 
  11372.  
  11373.  Returns 
  11374.  
  11375.           rc (Principal) 
  11376.                     Returns a pointer to a Principal object which identifies 
  11377.                     the user and host from which a request originated. 
  11378.  
  11379.  Remarks 
  11380.  
  11381.           The get_principal method returns the ID of the principal that issued 
  11382.           a request. 
  11383.  
  11384.  Original Class 
  11385.  
  11386.           BOA 
  11387.  
  11388.  Related Methods 
  11389.  
  11390.           Classes 
  11391.  
  11392.               Principal 
  11393.  
  11394.  Example Code 
  11395.  
  11396.                     #include  <somd.h>
  11397.  
  11398.                     /* assumed context: inside a method implementation */
  11399.                     void methodBody(SOMObject *somSelf, Environment *ev, ...)
  11400.                     {
  11401.                        Principal p;
  11402.                        SOMDObject selfRef;
  11403.                        Environment localev;
  11404.  
  11405.                        SOMInitEnvironment(&localev);
  11406.  
  11407.                        /* get a reference to myself from the server object */
  11408.                        selfRef =
  11409.                          somdRefFromSOMObj(SOMD_ServerObject, &ev, somSelf);
  11410.  
  11411.                        /* get principal information from the SOMOA */
  11412.                        p =  _get_principal(SOMD_SOMOAObject, &localev, selfRef, ev);
  11413.  
  11414.                        printf("user = %s, host = %s\n",
  11415.                              __get_userName(p), __get_hostName(p));
  11416.                        ...
  11417.                     }
  11418.  
  11419.  
  11420. ΓòÉΓòÉΓòÉ 3.21. impl_is_ready ΓòÉΓòÉΓòÉ
  11421.  
  11422. impl_is_ready This method indicates that the implementation is ready to process 
  11423. requests. 
  11424.  
  11425.  Syntax 
  11426.  
  11427.                     void impl_is_ready (BOA receiver, Environment *env,
  11428.                                ImplementationDef impl)
  11429.  
  11430.  Parameters 
  11431.  
  11432.           receiver (BOA) 
  11433.                     A pointer to a BOA (SOMOA) object for the server. 
  11434.  
  11435.           env (Environment *) 
  11436.                     A pointer to the Environment structure for the method 
  11437.                     caller. 
  11438.  
  11439.           impl (ImplementationDef) 
  11440.                     A pointer to the ImplementationDef object indicating which 
  11441.                     implementation is ready. 
  11442.  
  11443.  Returns 
  11444.  
  11445.           rc (void) 
  11446.  
  11447.  Remarks 
  11448.  
  11449.           The impl_is_ready method Indicates that the implementation is ready 
  11450.           to process requests. 
  11451.  
  11452.  Original Class 
  11453.  
  11454.           BOA 
  11455.  
  11456.  Related Methods 
  11457.  
  11458.           Methods 
  11459.  
  11460.               deactivate_impl 
  11461.               activate_impl_failed 
  11462.               obj_is_ready 
  11463.               execute_request_loop 
  11464.               execute_next_request 
  11465.  
  11466.  Example Code 
  11467.  
  11468.                     #include  <somd.h>   /* needed by all servers */
  11469.  
  11470.                     main(int argc, char **argv)
  11471.                     {
  11472.                        Environment ev;
  11473.                        SOM_InitEnvironment(&ev);
  11474.  
  11475.                        /* Initialize the DSOM run-time environment */
  11476.                        SOMD_Init(&ev);
  11477.  
  11478.                        /* Retrieve its ImplementationDef from the Implementation
  11479.                           Repository by passing its implementation ID as a key */
  11480.                        SOMD_ImplDefObject =
  11481.                           _find_impldef(SOMD_ImplRepObject, &ev, argv[1]);
  11482.  
  11483.                        /* Tell DSOM that the server is ready to process requests */
  11484.                        _impl_is_ready(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  11485.                        ...
  11486.                     }
  11487.  
  11488.  
  11489. ΓòÉΓòÉΓòÉ 3.22. obj_is_ready ΓòÉΓòÉΓòÉ
  11490.  
  11491. obj_is_ready Indicates that an object (server) is ready to process requests. 
  11492. (Not implemented.) 
  11493.  
  11494.  Syntax 
  11495.  
  11496.                     void obj_is_ready (BOA receiver, Environment *env, SOMDObject obj,
  11497.                                ImplementationDef impl)
  11498.  
  11499.  Parameters 
  11500.  
  11501.           receiver (BOA) 
  11502.                     A pointer to a BOA (SOMOA) object for the server. 
  11503.  
  11504.           env (Environment *) 
  11505.                     A pointer to the Environment structure for the method 
  11506.                     caller. 
  11507.  
  11508.           obj (SOMDObject) 
  11509.                     A pointer to a SOMDObject which identifies the object 
  11510.                     (server) which is ready. 
  11511.  
  11512.           impl (ImplementationDef) 
  11513.                     A pointer to the ImplementationDef object representing the 
  11514.                     object that is ready. 
  11515.  
  11516.  Returns 
  11517.  
  11518.           rc (void) 
  11519.  
  11520.  Remarks 
  11521.  
  11522.           The obj_is_ready method is defined by the CORBA specification, but 
  11523.           has a null implementation in DSOM. This method always returns a 
  11524.           NO_IMPLEMENT exception. 
  11525.  
  11526.           CORBA 1.1 distinguishes between servers that implement many objects 
  11527.           ("shared"), versus servers that implement a single object 
  11528.           ("unshared"). The obj_is_ready method is meant to be used by unshared 
  11529.           servers, to indicate that the object (i.e., server) is ready to 
  11530.           process requests. 
  11531.  
  11532.           DSOM does not distinguish between servers that implement a single 
  11533.           object versus servers that implement multiple objects, so this method 
  11534.           has no implementation. 
  11535.  
  11536.  Original Class 
  11537.  
  11538.           BOA 
  11539.  
  11540.  Related Methods 
  11541.  
  11542.           Methods 
  11543.  
  11544.               impl_is_ready 
  11545.               deactivate_impl 
  11546.               deactivate_obj 
  11547.               activate_impl_failed 
  11548.  
  11549.  
  11550. ΓòÉΓòÉΓòÉ 3.23. set_exception ΓòÉΓòÉΓòÉ
  11551.  
  11552. set_exception This method returns an exception to a client. 
  11553.  
  11554.  Syntax 
  11555.  
  11556.                     void set_exception (BOA receiver, Environment *env,
  11557.                                exception_type major, string except_name,
  11558.                                void *param)
  11559.  
  11560.  Parameters 
  11561.  
  11562.           receiver (BOA) 
  11563.                     A pointer to a BOA (SOMOA) object for the server. 
  11564.  
  11565.           env (Environment *) 
  11566.                     A pointer to the Environment structure for the method 
  11567.                     caller. 
  11568.  
  11569.           major (exception_type) 
  11570.                     One of the exception types NO_EXCEPTION, USER_EXCEPTION, or 
  11571.                     SYSTEM_EXCEPTION. 
  11572.  
  11573.           except_name (string) 
  11574.                     A string representing the exception type identifier. 
  11575.  
  11576.           param (void *) 
  11577.                     A pointer to the associated data. 
  11578.  
  11579.  Returns 
  11580.  
  11581.           rc (void) 
  11582.  
  11583.  Remarks 
  11584.  
  11585.           The set_exception method returns an exception to the client. The 
  11586.           major parameter can have one of three possible values: 
  11587.  
  11588.           NO_EXCEPTION     Indicates a normal outcome of the operation. It is 
  11589.                            not necessary to invoke set_exception to indicate a 
  11590.                            normal outcome; it is the default behavior if the 
  11591.                            method simply returns. 
  11592.  
  11593.           USER_EXCEPTION   Indicates a user-defined exception. 
  11594.  
  11595.           SYSTEM_EXCEPTION Indicates a system-defined exception. 
  11596.  
  11597.  Original Class 
  11598.  
  11599.           BOA 
  11600.  
  11601.  Example Code 
  11602.  
  11603.                     #include  <somd.h>
  11604.                     #include  <myobject.h>    /* provided by user */
  11605.  
  11606.                     /* assuming following IDL declarations in the MyObject interface:
  11607.                      *    exception foo;
  11608.                      *    void myMethod() raises (BadCall);
  11609.                      * then within the implementation of myMethod, the
  11610.                      * following call can raise a BadCall exception: */
  11611.  
  11612.                     _set_exception(SOMD_SOMOAObject,
  11613.                                    &ev, USER_EXCEPTION, ex_MyObject_BadCall, NULL);
  11614.  
  11615.  
  11616. ΓòÉΓòÉΓòÉ 3.24. Context ΓòÉΓòÉΓòÉ
  11617.  
  11618. Context 
  11619.  
  11620.  File stem: cntxt 
  11621.  
  11622.  Base 
  11623.  
  11624.           SOMObject 
  11625.  
  11626.  Metaclass 
  11627.  
  11628.           SOMClass 
  11629.  
  11630.  Ancestor Classes 
  11631.  
  11632.                     SOMObject
  11633.  
  11634.  Description 
  11635.  
  11636.           The Context class implements the CORBA Context object described in 
  11637.           section 6.5 beginning on page 116 of CORBA 1.1. A Context object 
  11638.           contains a list of properties, each consisting of a name and a string 
  11639.           value associated with that name. Context objects are created/accessed 
  11640.           by the get_default_context method defined in the ORB object. 
  11641.  
  11642.  New methods 
  11643.  
  11644.           The following list shows all the Context methods. 
  11645.  
  11646.               create_child 
  11647.               delete_values 
  11648.               destroy* 
  11649.               get_values 
  11650.               set_one_value 
  11651.               set_values 
  11652.  
  11653.           (* The destroy method was defined as delete in CORBA 1.1, which 
  11654.           conflicts with the delete operator in C++. However, there is a 
  11655.           Context_delete macro defined for CORBA compatibility.) 
  11656.  
  11657.  Overridden methods 
  11658.  
  11659.           The following list shows all the methods overridden by the Context 
  11660.           class. These methods are overridden in order to modify the behavior 
  11661.           defined by an ancestor class. 
  11662.  
  11663.               somInit 
  11664.  
  11665.  
  11666. ΓòÉΓòÉΓòÉ 3.25. create_child ΓòÉΓòÉΓòÉ
  11667.  
  11668. create_child This method creates a child of a Context object. 
  11669.  
  11670.  Syntax 
  11671.  
  11672.                     ORBStatus create_child (Context receiver, Environment *env,
  11673.                                   Identifier ctx_name, Context child_ctx)
  11674.  
  11675.  Parameters 
  11676.  
  11677.           receiver (Context) 
  11678.                     A pointer to the Context object for which a child is to be 
  11679.                     created. 
  11680.  
  11681.           env (Environment *) 
  11682.                     A pointer to the Environment structure for the method 
  11683.                     caller. 
  11684.  
  11685.           ctx_name (Identifier) 
  11686.                     The name of the child Context to be created. 
  11687.  
  11688.           child_ctx (Context) 
  11689.                     The address where a pointer to the created child Context 
  11690.                     object is to be stored. 
  11691.  
  11692.  Returns 
  11693.  
  11694.           rc (ORBStatus) 
  11695.                     Returns an ORBStatus value representing the return code 
  11696.                     from the operation. 
  11697.  
  11698.  Remarks 
  11699.  
  11700.           The create_child method creates a child Context object. 
  11701.  
  11702.           The returned Context object is chained to its parent. That is, 
  11703.           searches on the child Context object will look in the parent (and so 
  11704.           on, up the Contexttree), if necessary, for matching property names. 
  11705.  
  11706.  Original Class 
  11707.  
  11708.           Context 
  11709.  
  11710.  Example Code 
  11711.  
  11712.                     #include  <somd.h>
  11713.  
  11714.                     Environment ev;
  11715.                     Context cxt, newcxt;
  11716.                     long rc;
  11717.                     ...
  11718.                     /* get the process' default Context */
  11719.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  11720.                     /* make newcxt a child Context of the default Context (cxt) */
  11721.                     rc =  _create_child(cxt, &ev, "myContext", &newcxt);
  11722.  
  11723.  
  11724. ΓòÉΓòÉΓòÉ 3.26. delete_values ΓòÉΓòÉΓòÉ
  11725.  
  11726. delete_values This method deletes property value(s). 
  11727.  
  11728.  Syntax 
  11729.  
  11730.                     ORBStatus delete_values (Context receiver, Environment *env,
  11731.                                   Identifier prop_name)
  11732.  
  11733.  Parameters 
  11734.  
  11735.           receiver (Context) 
  11736.                     A pointer to the Context object from which values will be 
  11737.                     deleted. 
  11738.  
  11739.           env (Environment *) 
  11740.                     A pointer to the Environment structure for the method 
  11741.                     caller. 
  11742.  
  11743.           prop_name (Identifier) 
  11744.                     An identifier specifying the property value(s) to be 
  11745.                     deleted. 
  11746.  
  11747.  Returns 
  11748.  
  11749.           rc (ORBStatus) 
  11750.                     Returns an ORBStatus value representing the return code 
  11751.                     from the operation. 
  11752.  
  11753.  Remarks 
  11754.  
  11755.           The delete_values method deletes the specified property value(s) from 
  11756.           a Context object. If prop_name has a trailing wildcard 
  11757.           character("*"), then all property names that match will be deleted. 
  11758.  
  11759.           Search scope is always limited to the specified Context object. 
  11760.  
  11761.           If no matching property is found, an exception is returned. 
  11762.  
  11763.  Original Class 
  11764.  
  11765.           Context 
  11766.  
  11767.  Related Methods 
  11768.  
  11769.           Methods 
  11770.  
  11771.               set_one_value 
  11772.               set_values 
  11773.               get_values 
  11774.  
  11775.  Example Code 
  11776.  
  11777.                     #include  <somd.h>
  11778.  
  11779.                     Environment ev;
  11780.                     Context cxt, newcxt;
  11781.                     long rc;
  11782.                     ...
  11783.                     /* get the process' default Context */
  11784.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  11785.                     /* make newcxt a child Context of the default Context (cxt) */
  11786.                     rc = _create_child(cxt, &ev, "myContext", &newcxt);
  11787.                     rc = _set_one_value(newcxt, &ev, "username", "joe");
  11788.                     ...
  11789.                     rc =  _delete_values(newcxt, &ev, "username");
  11790.  
  11791.  
  11792. ΓòÉΓòÉΓòÉ 3.27. destroy ΓòÉΓòÉΓòÉ
  11793.  
  11794. destroy This method deletes a Context object. 
  11795.  
  11796.  Syntax 
  11797.  
  11798.                     ORBStatus destroy (Context receiver, Environment *env, Flags del_flag)
  11799.  
  11800.  Parameters 
  11801.  
  11802.           receiver (Context) 
  11803.                     A pointer to the Context object to be deleted. 
  11804.  
  11805.           env (Environment *) 
  11806.                     A pointer to the Environment structure for the method 
  11807.                     caller. 
  11808.  
  11809.           del_flag (Flags) 
  11810.                     A bitmask (unsigned long). If the option flag 
  11811.                     CTX_DELETE_DESCENDENTS is specified, the method deletes the 
  11812.                     indicated Context object and all of its descendent Context 
  11813.                     objects. Or, a zero value indicates the flag is not set. 
  11814.  
  11815.  Returns 
  11816.  
  11817.           rc (ORBStatus) 
  11818.                     Returns an ORBStatus value representing the return code 
  11819.                     from the operation. 
  11820.  
  11821.  Remarks 
  11822.  
  11823.           The destroy method deletes the specified Context object. 
  11824.  
  11825.           Note:  This method is called "delete" in the CORBA 1.1 specification. 
  11826.           However, the word "delete" is a reserved operator in C++, so the name 
  11827.           "destroy"was chosen as an alternative. For CORBA compatibility, a 
  11828.           macro defining Context_delete as an alias for destroy has been 
  11829.           included in the C header files. 
  11830.  
  11831.  Original Class 
  11832.  
  11833.           Context 
  11834.  
  11835.  Example Code 
  11836.  
  11837.                     #include  <somd.h>
  11838.  
  11839.                     Environment ev;
  11840.                     Context cxt, newcxt;
  11841.                     long rc;
  11842.                     ...
  11843.                     /* get the process' default Context */
  11844.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  11845.                     /* make newcxt a child Context of the default Context (cxt) */
  11846.                     rc =  _create_child(cxt, &ev, "myContext", &newcxt);
  11847.                     ...
  11848.                     /* assuming no descendent Contexts have been
  11849.                      * created from newcxt, we can destroy newcxt with flags=0
  11850.                      */
  11851.                     rc =  _destroy(newcxt, &ev, (Flags) 0);
  11852.  
  11853.  
  11854. ΓòÉΓòÉΓòÉ 3.28. get_values ΓòÉΓòÉΓòÉ
  11855.  
  11856. get_values This method retrieves the specified property values. 
  11857.  
  11858.  Syntax 
  11859.  
  11860.                     ORBStatus get_values (Context receiver, Environment *env,
  11861.                                  Identifier start_scope, Flags op_flags,
  11862.                                  Identifier prop_name, NVList values)
  11863.  
  11864.  Parameters 
  11865.  
  11866.           receiver (Context) 
  11867.                     A pointer to the Context object from which the properties 
  11868.                     are to be retrieved. 
  11869.  
  11870.           env (Environment *) 
  11871.                     A pointer to the Environment structure for the method 
  11872.                     caller. 
  11873.  
  11874.           start_scope (Identifier) 
  11875.                     An Identifier specifying the name of the Context object at 
  11876.                     which search for the properties should commence. 
  11877.  
  11878.           op_flags (Flags) 
  11879.                     This parameter is currently not used (the 
  11880.                     CTX_RESTRICT_SCOPE flag is currently not supported); 
  11881.                     callers can simply pass zero. object. 
  11882.  
  11883.           prop_name (Identifier) 
  11884.                     An Identifier specifying the name of the property value(s) 
  11885.                     to return. 
  11886.  
  11887.           values (NVList) 
  11888.                     The address to store a pointer to the resulting NVList 
  11889.                     object. 
  11890.  
  11891.  Returns 
  11892.  
  11893.           rc (ORBStatus) 
  11894.                     Returns an ORBStatus value representing the return code 
  11895.                     from the operation. 
  11896.  
  11897.  Remarks 
  11898.  
  11899.           The get_values method retrieves the specified Context property 
  11900.           values(s). If prop_name has a trailing wildcard character("*"), then 
  11901.           all matching properties and their values are returned. OWNERSHIP of 
  11902.           the returned NVList object is transferred to the caller. 
  11903.  
  11904.           If no properties are found, an error is returned and no property list 
  11905.           is returned. 
  11906.  
  11907.           Scope indicates the level at which to initiate the search for the 
  11908.           specified properties. If a property is not found at the indicated 
  11909.           level, the search continues up the Context object tree until a match 
  11910.           is found or all Context objects in the chain have been exhausted. 
  11911.  
  11912.           If scope name is omitted, the search begins with the specified 
  11913.           Context object. If the specified scope name is not found, an 
  11914.           exception is returned. 
  11915.  
  11916.  Original Class 
  11917.  
  11918.           Context 
  11919.  
  11920.  Related Methods 
  11921.  
  11922.           Methods 
  11923.  
  11924.               set_one_value 
  11925.               set_values 
  11926.               delete_values 
  11927.  
  11928.  Example Code 
  11929.  
  11930.                     #include  <somd.h>
  11931.  
  11932.                     Environment ev;
  11933.                     Context cxt1, cxt2;
  11934.                     string *cxt1props;
  11935.                     long rc, i, numprops;
  11936.                     NVList nvp;
  11937.                     ...
  11938.                     for (i= numprops; i > 0; i--) {
  11939.                      /* get the value of the *cxt1props property from cxt1 */
  11940.                      rc =  _get_values(cxt1, &ev, NULL, (Flags) 0, *cxt1props, &nvp);
  11941.                      /* and if found then update cxt2 with that name-value pair */
  11942.                      if (rc == 0) rc = _set_values(cxt2, &ev, nvp);
  11943.                      _free(nvp,&ev);
  11944.                      cxt1props++;
  11945.                     }
  11946.  
  11947.  
  11948. ΓòÉΓòÉΓòÉ 3.29. set_one_value ΓòÉΓòÉΓòÉ
  11949.  
  11950. set_one_value This method adds a single property to the specified Context 
  11951. object. 
  11952.  
  11953.  Syntax 
  11954.  
  11955.                     ORBStatus set_one_value (Context receiver, Environment *env,
  11956.                                    Identifier prop_name, string value)
  11957.  
  11958.  Parameters 
  11959.  
  11960.           receiver (Context) 
  11961.                     A pointer to the Context object to which the value is to be 
  11962.                     added. 
  11963.  
  11964.           env (Environment *) 
  11965.                     A pointer to the Environment structure for the method 
  11966.                     caller. 
  11967.  
  11968.           prop_name (Identifier) 
  11969.                     The name of the property to be added. The prop_name should 
  11970.                     not end in an asterisk (*). 
  11971.  
  11972.           value (string) 
  11973.                     The value of the property to be added. 
  11974.  
  11975.  Returns 
  11976.  
  11977.           rc (ORBStatus) 
  11978.                     Returns an ORBStatus value representing the return code 
  11979.                     from the operation. 
  11980.  
  11981.  Remarks 
  11982.  
  11983.           The set_one_value method adds a single property to the specified 
  11984.           Context object. 
  11985.  
  11986.  Original Class 
  11987.  
  11988.           Context 
  11989.  
  11990.  Related Methods 
  11991.  
  11992.           Methods 
  11993.  
  11994.               set_values 
  11995.               get_values 
  11996.               delete_values 
  11997.  
  11998.  Example Code 
  11999.  
  12000.                     #include  <somd.h>
  12001.                     Environment ev;
  12002.                     Context cxt, newcxt;
  12003.                     long rc;
  12004.  
  12005.                     /* get the process' default Context */
  12006.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  12007.                     /* make newcxt a child Context of the default Context (cxt) */
  12008.                     rc = _create_child(cxt, &ev, "myContext", &newcxt);
  12009.                     rc = _set_one_value(newcxt, &ev, "username", "joe");
  12010.  
  12011.  
  12012. ΓòÉΓòÉΓòÉ 3.30. set_values ΓòÉΓòÉΓòÉ
  12013.  
  12014. set_values This method adds/changes one or more property values in the 
  12015. specified Context object. 
  12016.  
  12017.  Syntax 
  12018.  
  12019.                     ORBStatus set_values (Context receiver, Environment *env,
  12020.                                  NVList values)
  12021.  
  12022.  Parameters 
  12023.  
  12024.           receiver (Context) 
  12025.                     A pointer to the Context object for which the properties 
  12026.                     are to be set. 
  12027.  
  12028.           env (Environment *) 
  12029.                     A pointer to the Environment structure for the method 
  12030.                     caller. 
  12031.  
  12032.           values (NVList) 
  12033.                     A pointer to an NVList object containing the properties to 
  12034.                     be set. 
  12035.  
  12036.  Returns 
  12037.  
  12038.           rc (ORBStatus) 
  12039.                     Returns an ORBStatus value representing the return code 
  12040.                     from the operation. 
  12041.  
  12042.  Remarks 
  12043.  
  12044.           The set_values method sets one or more property values in the 
  12045.           specified Context object. In the NVList, the flags field must be set 
  12046.           to zero and the TypeCode field associated with an attribute value 
  12047.           must be TC_string. 
  12048.  
  12049.  Original Class 
  12050.  
  12051.           Context 
  12052.  
  12053.  Related Methods 
  12054.  
  12055.           Methods 
  12056.  
  12057.               set_one_value 
  12058.               get_values 
  12059.               delete_values 
  12060.  
  12061.  Example Code 
  12062.  
  12063.                     #include  <somd.h>
  12064.  
  12065.                     Environment ev;
  12066.                     Context cxt1, cxt2;
  12067.                     string *cxt1props;
  12068.                     long rc, i, numprops;
  12069.                     NVList nvp;
  12070.                     ...
  12071.                     for (i= numprops; i > 0; i--) {
  12072.                      /* get the value of the *cxt1props property from cxt1 */
  12073.                      rc = _get_values(cxt1, &ev, NULL, (Flags) 0, *cxt1props, &nvp);
  12074.                      /* and if found then update cxt2 with that name-value pair */
  12075.                      if (rc == 0) rc =  _set_values(cxt2, &ev, nvp);
  12076.                      _free(nvp,&ev);
  12077.                      cxt1props++;
  12078.                     }
  12079.  
  12080.  
  12081. ΓòÉΓòÉΓòÉ 3.31. ImplementationDef ΓòÉΓòÉΓòÉ
  12082.  
  12083. ImplementationDef 
  12084.  
  12085.  File stem: impldef 
  12086.  
  12087.  Base 
  12088.  
  12089.           SOMObject 
  12090.  
  12091.  Metaclass 
  12092.  
  12093.           SOMClass 
  12094.  
  12095.  Ancestor Classes 
  12096.  
  12097.                     SOMObject
  12098.  
  12099.  Description 
  12100.  
  12101.           The ImplementationDef class defines attributes necessary for the DSOM 
  12102.           daemon to find and activate the implementation of an object. 
  12103.  
  12104.           Note:  * Details of the ImplementationDef object are not currently 
  12105.           defined in the CORBA 1.1 specification; the attributes which have 
  12106.           been defined are required by DSOM. 
  12107.  
  12108.           Attributes 
  12109.  
  12110.           Listed below is each available attribute, with its corresponding type 
  12111.           in parentheses, followed by a description of its purpose: 
  12112.  
  12113.           impl_id (string) 
  12114.                Contains the DSOM-generated identifier for a server 
  12115.                implementation. 
  12116.  
  12117.           impl_alias (string) 
  12118.                Contains the "alias" (user-friendly name) for a server 
  12119.                implementation. 
  12120.  
  12121.           impl_program (string) 
  12122.                Contains the name of the program or command file which will be 
  12123.                executed when a process for this server is started automatically 
  12124.                by somdd. If the full pathname is not specified, the directories 
  12125.                specified in the  PATH environment variable will be searched for 
  12126.                the named program or command file. 
  12127.  
  12128.                Optionally, the server program can be run under control of a 
  12129.                "shell" or debugger, by specifying the shell or debugger name 
  12130.                first, followed by the name of the server program. (A space 
  12131.                separates the two program names.)  For example, 
  12132.  
  12133.                               dbx myserver
  12134.  
  12135.                Servers that are started automatically by somdd will always be 
  12136.                passed their impl_id as the first parameter. 
  12137.  
  12138.           impl_flags (Flags) 
  12139.                Contains a bit-vector of flags used to identify server options. 
  12140.                Currently, the IMPLDEF_MULTI_THREAD flag indicates that each 
  12141.                request should be executed on a separate thread. 
  12142.                IMPLDEF_DISABLE_SVR indicates that the server process has been 
  12143.                disabled from starting. IMPLDEF_NONSTOPPABLE indicates that the 
  12144.                server cannot be shutdown by using the dsom stop or dsom restart 
  12145.                commands (see "The `dsom' server manager utility" in Chapter 6 
  12146.                of the SOM Programming Guide) or by using the corresponding 
  12147.                methods of the SOMDServerMgr class (somdShutdownServer and 
  12148.                somdRestartServer). IMPLDEF_IMPLID_SET indicates that the 
  12149.                impl_id attribute has already been set when the 
  12150.                ImplementationDef object is passed to the 
  12151.                ImplRepository::add_impldef method. The 
  12152.                ImplRepository::add_impldef method normally generates the 
  12153.                impl_id attribute before storing the ImplementationDef object in 
  12154.                the Implementation Repository. 
  12155.  
  12156.           impl_server_class (string) 
  12157.                Contains the name of the SOMDServer class or subclass created by 
  12158.                the server process. 
  12159.  
  12160.           impl_refdata_file (string) 
  12161.                Contains the full pathname of the file used to store 
  12162.                ReferenceData for the server. 
  12163.  
  12164.           impl_refdata_bkup (string) 
  12165.                Contains the full pathname of the backup mirror file used to 
  12166.                store ReferenceData for the server. 
  12167.  
  12168.           impl_hostname (string) 
  12169.                Contains the hostname of the machine where the server is 
  12170.                located. 
  12171.  
  12172.           Note: 
  12173.  
  12174.           Currently, when stored in the Implementation Repository, file names 
  12175.           used in ImplementationDefs are limited to 255 bytes. Implementations 
  12176.           aliases used in ImplementationDefs are limited to 50 bytes. Class 
  12177.           names used in ImplementationDefs are limited to 50 bytes. Hostnames 
  12178.           are limited to 32 bytes. 
  12179.  
  12180.  New methods 
  12181.  
  12182.           There are currently no new methods defined for the ImplementationDef 
  12183.           class. 
  12184.  
  12185.  Overridden methods 
  12186.  
  12187.           There are currently no overridden methods defined for the 
  12188.           ImplementationDef class. 
  12189.  
  12190.  
  12191. ΓòÉΓòÉΓòÉ 3.32. ImplRepository ΓòÉΓòÉΓòÉ
  12192.  
  12193. ImplRepository 
  12194.  
  12195.  File stem: implrep 
  12196.  
  12197.  Base 
  12198.  
  12199.           SOMObject 
  12200.  
  12201.  Metaclass 
  12202.  
  12203.           SOMMSingleInstance 
  12204.  
  12205.  Ancestor Classes 
  12206.  
  12207.                     SOMObject
  12208.  
  12209.  Description 
  12210.  
  12211.           The ImplRepository class defines operations necessary to query and 
  12212.           update the DSOM Implementation Repository. 
  12213.  
  12214.           Note:  * The Implementation Repository is described in concept in the 
  12215.           CORBA 1.1 specification, but no standard interfaces have been 
  12216.           defined. These interfaces have all been introduced by DSOM. In 
  12217.           addition to using the following interfaces, the DSOM Implementation 
  12218.           Repository can be queried and updated using the regimpl tool. 
  12219.  
  12220.  New methods 
  12221.  
  12222.           The following list shows all the ImplRepository methods. 
  12223.  
  12224.               add_class_to_impldef 
  12225.               add_impldef 
  12226.               delete_impldef 
  12227.               find_all_impldefs 
  12228.               find_classes_by_impldef 
  12229.               find_impldef 
  12230.               find_impldef_by_alias 
  12231.               find_impldef_by_class 
  12232.               remove_class_from_all 
  12233.               remove_class_from_impldef 
  12234.               update_impldef 
  12235.  
  12236.  Overridden methods 
  12237.  
  12238.           The following list shows all the methods overridden by the 
  12239.           ImplRepository class. These methods are overridden in order to modify 
  12240.           the behavior defined by an ancestor class. 
  12241.  
  12242.               somInit 
  12243.               somUninit 
  12244.  
  12245.  
  12246. ΓòÉΓòÉΓòÉ 3.33. add_class_to_impldef ΓòÉΓòÉΓòÉ
  12247.  
  12248. add_class_to_impldef This method associates a class with a server. 
  12249.  
  12250.  Syntax 
  12251.  
  12252.                     void add_class_to_impldef (ImplRepository receiver, Environment *env,
  12253.                                    ImplId implid, string classname)
  12254.  
  12255.  Parameters 
  12256.  
  12257.           receiver (ImplRepository) 
  12258.                     A pointer to the ImplRepository object. 
  12259.  
  12260.           env (Environment *) 
  12261.                     A pointer to the Environment structure for the method 
  12262.                     caller. 
  12263.  
  12264.           implid (ImplId) 
  12265.                     The ImplId identifier for the ImplementationDef of the 
  12266.                     desired server. 
  12267.  
  12268.           classname (string) 
  12269.                     A string identifying the class name. 
  12270.  
  12271.  Returns 
  12272.  
  12273.           rc (void) 
  12274.                     An exception is returned if there was an error updating the 
  12275.                     Implementation Repository. 
  12276.  
  12277.  Remarks 
  12278.  
  12279.           Associates a class, identified by name, with a server, identified by 
  12280.           its ImplId. This type of association is used to lookup server 
  12281.           implementations via the find_impldef_by_class method. 
  12282.  
  12283.  Original Class 
  12284.  
  12285.           ImplRepository 
  12286.  
  12287.  Example Code 
  12288.  
  12289.                     #include  <somd.h>
  12290.  
  12291.                     Environment ev;
  12292.                     SOMDServer server;
  12293.                     ImplementationDef impldef;
  12294.                     ImplId implid;
  12295.                     ...
  12296.                     server = _somdFindServerByName(SOMD_ObjectMgr,&ev,"stackServer");
  12297.                     impldef = _get_implementation(server,&ev);
  12298.                     implid = __get_impl_id(impldef,&ev);
  12299.                     _add_class_to_impldef(SOMD_ImplRepObject,&ev,implid , "Queue");
  12300.  
  12301.  
  12302. ΓòÉΓòÉΓòÉ 3.34. add_impldef ΓòÉΓòÉΓòÉ
  12303.  
  12304. add_impldef This method adds an implementation definition to the Implementation 
  12305. Repository. 
  12306.  
  12307.  Syntax 
  12308.  
  12309.                     void add_impldef (ImplRepository receiver, Environment *env,
  12310.                               ImplementationDef impldef)
  12311.  
  12312.  Parameters 
  12313.  
  12314.           receiver (ImplRepository) 
  12315.                     A pointer to  the ImplRepository object. 
  12316.  
  12317.           env (Environment *) 
  12318.                     A pointer to the Environment structure for the method 
  12319.                     caller. 
  12320.  
  12321.           impldef (ImplementationDef) 
  12322.                     A pointer to the ImplementationDef object to add to the 
  12323.                     Implementation Repository. 
  12324.  
  12325.  Returns 
  12326.  
  12327.           rc (void) 
  12328.                     An exception is returned if there was an error updating the 
  12329.                     Implementation Repository. 
  12330.  
  12331.  Remarks 
  12332.  
  12333.           Adds the specified ImplementationDef object to the Implementation 
  12334.           Repository. 
  12335.  
  12336.           Note:  Unless the impl_flags attribute of the given ImplementationDef 
  12337.           object contains the IMPLDEF_IMPLID_SET flag, the impl_id attribute of 
  12338.           the ImplementationDef object is ignored, and a new impl_id value is 
  12339.           created for the newly added ImplementationDef object. 
  12340.  
  12341.  Original Class 
  12342.  
  12343.           ImplRepository 
  12344.  
  12345.  Example Code 
  12346.  
  12347.                     #include  _somd.h>
  12348.  
  12349.                     Environment ev;
  12350.                     ImplementationDef impldef;
  12351.                     ...
  12352.                     impldef = ImplementationDefNew();
  12353.                     __set_impl_program(impldef,&ev,"/u/servers/myserver");
  12354.                     /* set more of the impldef's attributes here */
  12355.                     ...
  12356.                     _add_impldef(SOMD_ImplRepObject,&ev,impldef);
  12357.  
  12358.  
  12359. ΓòÉΓòÉΓòÉ 3.35. delete_impldef ΓòÉΓòÉΓòÉ
  12360.  
  12361. delete_impldef This method deletes an implementation definition from the 
  12362. Implementation Repository. 
  12363.  
  12364.  Syntax 
  12365.  
  12366.                     void delete_impldef (ImplRepository receiver, Environment *env,
  12367.                                 ImplId implid)
  12368.  
  12369.  Parameters 
  12370.  
  12371.           receiver (ImplRepository) 
  12372.                     A pointer to  the ImplRepository object. 
  12373.  
  12374.           env (Environment *) 
  12375.                     A pointer to the Environment structure for the method 
  12376.                     caller. 
  12377.  
  12378.           implid (ImplId) 
  12379.                     The ImplId that identifies the server implementation of 
  12380.                     interest. 
  12381.  
  12382.  Returns 
  12383.  
  12384.           rc (void) 
  12385.                     An exception is returned if there was an error updating the 
  12386.                     Implementation Repository. 
  12387.  
  12388.  Remarks 
  12389.  
  12390.           Deletes the specified ImplementationDef object from the 
  12391.           Implementation Repository. 
  12392.  
  12393.  Original Class 
  12394.  
  12395.           ImplRepository 
  12396.  
  12397.  Example Code 
  12398.  
  12399.                     #include  <somd.h>
  12400.  
  12401.                     Environment ev;
  12402.                     ImplementationDef impldef;
  12403.                     ...
  12404.                     impldef =
  12405.  
  12406.                     _find_impldef_by_name(SOMD_ImplRepObject,&ev,"stackServer");
  12407.                     _delete_impldef(SOMD_ImplRepObject,&ev,__get_impl _id(impldef,&ev));
  12408.  
  12409.  
  12410. ΓòÉΓòÉΓòÉ 3.36. find_all_impldefs ΓòÉΓòÉΓòÉ
  12411.  
  12412. find_all_impldefs This method returns all the implementation definitions in the 
  12413. Implementation Repository. 
  12414.  
  12415.  Syntax 
  12416.  
  12417.                     ORBStatus find_all_impldefs (ImplRepository receiver,
  12418.                                     Environment *env,
  12419.                                     sequence<ImplementationDefs> outimpldefs)
  12420.  
  12421.  Parameters 
  12422.  
  12423.           receiver (ImplRepository) 
  12424.                     A pointer to an object of class ImplRepository. 
  12425.  
  12426.           env (Environment *) 
  12427.                     A pointer to the Environment structure for the calling 
  12428.                     method. 
  12429.  
  12430.           outimpldefs (sequence<ImplementationDefs>) 
  12431.                     A sequence of ImplementationDefs is returned. 
  12432.  
  12433.  Returns 
  12434.  
  12435.           rc (ORBStatus) 
  12436.                     A zero is returned to indicate success; otherwise, a DSOM 
  12437.                     error code is returned. 
  12438.  
  12439.  Remarks 
  12440.  
  12441.           The find_all_impldefs method searches the Implementation Repository 
  12442.           and returns all the ImplementationDef objects in it. 
  12443.  
  12444.  Original Class 
  12445.  
  12446.           ImplRepository 
  12447.  
  12448.  Example Code 
  12449.  
  12450.                     #include <somd.h>
  12451.  
  12452.                     Environment ev;
  12453.                     sequence (ImplementationDef) impldefs;
  12454.  
  12455.                     ...
  12456.  
  12457.                     find_all_impldefs(SOMD_ImplRepObject, &ev, &impldefs);
  12458.  
  12459.  
  12460. ΓòÉΓòÉΓòÉ 3.37. find_classes_by_impldef ΓòÉΓòÉΓòÉ
  12461.  
  12462. find_classes_by_impldef This method returns a sequence of class names 
  12463. associated with a server. 
  12464.  
  12465.  Syntax 
  12466.  
  12467.                     sequence<string> find_classes_by_impldef (ImplRepository receiver,
  12468.                                            Environment *env, ImplId implid)
  12469.  
  12470.  Parameters 
  12471.  
  12472.           receiver (ImplRepository) 
  12473.                     A pointer to the ImplRepository object. 
  12474.  
  12475.           env (Environment *) 
  12476.                     A pointer to the Environment structure for the method 
  12477.                     caller. 
  12478.  
  12479.           implid (ImplId) 
  12480.                     The ImplId that identifies the server implementation of 
  12481.                     interest. 
  12482.  
  12483.  Returns 
  12484.  
  12485.           rc (sequence<string>) 
  12486.                     A sequence of strings is returned. Ownership of the 
  12487.                     sequence structure, the string array buffer, and the 
  12488.                     strings themselves is transferred to the caller. 
  12489.  
  12490.                     An exception is returned if there was an error reading the 
  12491.                     Implementation Repository. 
  12492.  
  12493.  Remarks 
  12494.  
  12495.           Searches the class index and returns the sequence of class names 
  12496.           supported by a server with the specified implid. 
  12497.  
  12498.  Original Class 
  12499.  
  12500.           ImplRepository 
  12501.  
  12502.  Example Code 
  12503.  
  12504.                     #include  <somd.h>
  12505.  
  12506.                     Environment ev;
  12507.                     SOMDServer server;
  12508.                     ImplementationDef impldef;
  12509.                     ImplId implid;
  12510.                     sequence(string) classes;
  12511.                     ...
  12512.                     server = _find_server_by_name(SOMD_ObjectMgr,&ev,"stackServer");
  12513.                     impldef = _get_implementation(server,&ev);
  12514.                     implid = __get_impl_id(impldef,&ev);
  12515.                     classes = _find_classes_by_impldef(SOMD_ImplRepObject,&ev,implid);
  12516.  
  12517.  
  12518. ΓòÉΓòÉΓòÉ 3.38. find_impldef ΓòÉΓòÉΓòÉ
  12519.  
  12520. find_impldef This method returns a server implementation definition given its 
  12521. ID. 
  12522.  
  12523.  Syntax 
  12524.  
  12525.                     ImplementationDef find_impldef (ImplRepository receiver,
  12526.                                       Environment *env, ImplId implid)
  12527.  
  12528.  Parameters 
  12529.  
  12530.           receiver (ImplRepository) 
  12531.                     A pointer to the ImplRepository object. 
  12532.  
  12533.           env (Environment *) 
  12534.                     A pointer to the Environment structure for the method 
  12535.                     caller. 
  12536.  
  12537.           implid (ImplId) 
  12538.                     The ImplId of the desired ImplementationDef. 
  12539.  
  12540.  Returns 
  12541.  
  12542.           rc (ImplementationDef) 
  12543.                     A copy of the desired ImplementationDef object is returned. 
  12544.                     Ownership of the object is transferred to the caller. 
  12545.  
  12546.                     An exception is returned if there was an error reading the 
  12547.                     Implementation Repository. 
  12548.  
  12549.  Remarks 
  12550.  
  12551.           Finds and returns the ImplementationDef object whose ID is implid. 
  12552.  
  12553.  Original Class 
  12554.  
  12555.           ImplRepository 
  12556.  
  12557.  Example Code 
  12558.  
  12559.                     #include  <somd.h>
  12560.  
  12561.                     main(int argc, char **argv)
  12562.                     {
  12563.                        Environment ev;
  12564.                        SOM_InitEnvironment(&ev);
  12565.  
  12566.                        /* Initialize the DSOM run-time environment */
  12567.                        SOMD_Init(&ev);
  12568.  
  12569.                        /* Retrieve its ImplementationDef from the Implementation
  12570.                           Repository by passing its implementation ID as a key */
  12571.                        SOMD_ImplDefObject =
  12572.                           _find_impldef(SOMD_ImplRepObject, &ev, argv[1]);
  12573.  
  12574.                        /* Tell DSOM that the server is ready to process requests */
  12575.                        _impl_is_ready(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  12576.                        ...
  12577.                     }
  12578.  
  12579.  
  12580. ΓòÉΓòÉΓòÉ 3.39. find_impldef_by_alias ΓòÉΓòÉΓòÉ
  12581.  
  12582. find_impldef_by_alias This method returns a server implementation definition 
  12583. given its user-friendly alias. 
  12584.  
  12585.  Syntax 
  12586.  
  12587.                     ImplementationDef find_impldef_by_alias (ImplRepository receiver,
  12588.                                           Environment *env, string alias_name)
  12589.  
  12590.  Parameters 
  12591.  
  12592.           receiver (ImplRepository) 
  12593.                     A pointer to the ImplRepository object. 
  12594.  
  12595.           env (Environment *) 
  12596.                     A pointer to the Environment structure for the method 
  12597.                     caller. 
  12598.  
  12599.           alias_name (string) 
  12600.                     User-friendly name used to identify the implementation. 
  12601.  
  12602.  Returns 
  12603.  
  12604.           rc (ImplementationDef) 
  12605.                     A copy of the desired ImplementationDef object is returned. 
  12606.                     Ownership of the object is transferred to the caller. 
  12607.  
  12608.                     An exception is returned if there was an error reading the 
  12609.                     Implementation Repository. 
  12610.  
  12611.  Remarks 
  12612.  
  12613.           Finds and returns the ImplementationDef object whose alias is 
  12614.           alias_name. 
  12615.  
  12616.  Original Class 
  12617.  
  12618.           ImplRepository 
  12619.  
  12620.  Example Code 
  12621.  
  12622.                     #include  <somd.h>
  12623.  
  12624.                     Environment ev;
  12625.                     ImplementationDef impldef;
  12626.                     ...
  12627.                     impldef =
  12628.                        _find_impldef_by_alias(SOMD_ImplRepObject,&ev,"stack Server");
  12629.                     _delete_impldef(SOMD_ImplRepObject,&ev,__get_impl_id(impl def,&ev));
  12630.  
  12631.  
  12632. ΓòÉΓòÉΓòÉ 3.40. find_impldef_by_class ΓòÉΓòÉΓòÉ
  12633.  
  12634. find_impldef_by_class This method returns a sequence of implementation 
  12635. definitions for servers that are associated with a specified class. 
  12636.  
  12637.  Syntax 
  12638.  
  12639.                     sequence<ImplementationDef> find_impldef_by_class
  12640.                                      (ImplRepository receiver,
  12641.                                       Environment *env, string classname)
  12642.  
  12643.  Parameters 
  12644.  
  12645.           receiver (ImplRepository) 
  12646.                     A pointer to the ImplRepository object. 
  12647.  
  12648.           env (Environment *) 
  12649.                     A pointer to the Environment structure for the method 
  12650.                     caller. 
  12651.  
  12652.           classname (string) 
  12653.                     A string whose value is the class name of interest. 
  12654.  
  12655.  Returns 
  12656.  
  12657.           rc (sequence<ImplementationDef>) 
  12658.                     Copiess of all ImplementationDef objects are returned in a 
  12659.                     sequence. Ownership of the sequence structure, the object 
  12660.                     array buffer, and the objects themselves is transfered to 
  12661.                     the caller. 
  12662.  
  12663.                     An exception is returned if there was an error reading the 
  12664.                     Implementation Repository. 
  12665.  
  12666.  Remarks 
  12667.  
  12668.           Returns a sequence of ImplementationDefs for those servers that have 
  12669.           registered an association with a specified class. Typically, a server 
  12670.           will be associated with the classes it knows how to implement by 
  12671.           registering its known classes via the add_class_to_impldef method. 
  12672.  
  12673.  Original Class 
  12674.  
  12675.           ImplRepository 
  12676.  
  12677.  Example Code 
  12678.  
  12679.                     #include  <somd.h>
  12680.  
  12681.                     Environment ev;
  12682.                     sequence(ImplementationDef) impldefs;
  12683.                     ...
  12684.                     impldef =
  12685.                        _find_impldef_by_class(SOMD_ImplRepObject,&ev,"Stack");
  12686.  
  12687.  
  12688. ΓòÉΓòÉΓòÉ 3.41. remove_class_from_all ΓòÉΓòÉΓòÉ
  12689.  
  12690. remove_class_from_all This method removes the association of a particular class 
  12691. from all servers. 
  12692.  
  12693.  Syntax 
  12694.  
  12695.                     void remove_class_from_all (ImplRepository receiver,
  12696.                                     Environment *env, string className)
  12697.  
  12698.  Parameters 
  12699.  
  12700.           receiver (ImplRepository) 
  12701.                     A pointer to an object of class ImplRepository. 
  12702.  
  12703.           env (Environment *) 
  12704.                     A pointer to the Environment structure for the calling 
  12705.                     method. 
  12706.  
  12707.           className (string) 
  12708.                     A string whose value is the class name of interest. 
  12709.  
  12710.  Returns 
  12711.  
  12712.           rc (void) 
  12713.  
  12714.  Remarks 
  12715.  
  12716.           The remove_class_from_all method removes the className from all of 
  12717.           the ImplementationDefs. 
  12718.  
  12719.  Original Class 
  12720.  
  12721.           ImplRepository 
  12722.  
  12723.  Example Code 
  12724.  
  12725.                     #include <somd.h>
  12726.  
  12727.                     Environment ev;
  12728.                     ...
  12729.                     remove_class_from_all(SOMD_ImplRepObject, &ev, "Stack");
  12730.  
  12731.  
  12732. ΓòÉΓòÉΓòÉ 3.42. remove_class_from_impldef ΓòÉΓòÉΓòÉ
  12733.  
  12734. remove_class_from_impldef This method removes the association of a particular 
  12735. class with a server. 
  12736.  
  12737.  Syntax 
  12738.  
  12739.                     void remove_class_from_impldef (ImplRepository receiver,
  12740.                                       Environment *env, ImplId implid,
  12741.                                       string classname)
  12742.  
  12743.  Parameters 
  12744.  
  12745.           receiver (ImplRepository) 
  12746.                     A pointer to the ImplRepository object. 
  12747.  
  12748.           env (Environment *) 
  12749.                     A pointer to the Environment structure for the method 
  12750.                     caller. 
  12751.  
  12752.           implid (ImplId) 
  12753.                     A pointer to an ImplRepository object. 
  12754.  
  12755.           classname (string) 
  12756.                     A string whose value is the class name of interest. 
  12757.  
  12758.  Returns 
  12759.  
  12760.           rc (void) 
  12761.                     An exception is returned if there was an error updating the 
  12762.                     Implementation Repository. 
  12763.  
  12764.  Remarks 
  12765.  
  12766.           Removes the specified class name from the set of class names 
  12767.           associated with the server implementation identified by implid. 
  12768.  
  12769.  Original Class 
  12770.  
  12771.           ImplRepository 
  12772.  
  12773.  Example Code 
  12774.  
  12775.                     #include  <somd.h>
  12776.  
  12777.                     Environment ev;
  12778.                     SOMDServer server;
  12779.                     ImplementationDef impldef;
  12780.                     ImplId implid;
  12781.                     ...
  12782.                     server = _find_server_by_name(SOMD_ObjectMgr,&ev,"stackServer");
  12783.                     impldef = _get_implementation(server,&ev);
  12784.                     implid = __get_impl_id(impldef,&ev);
  12785.                     _remove_class_from_impldef(SOMD_ImplRepObject,
  12786.                                                &ev,implid,"Queue");
  12787.  
  12788.  
  12789. ΓòÉΓòÉΓòÉ 3.43. update_impldef ΓòÉΓòÉΓòÉ
  12790.  
  12791. update_impldef This method updates an implementation definition in the 
  12792. Implementation Repository. 
  12793.  
  12794.  Syntax 
  12795.  
  12796.                     void update_impldef (ImplRepository receiver, Environment *env,
  12797.                                 ImplementationDef impldef)
  12798.  
  12799.  Parameters 
  12800.  
  12801.           receiver (ImplRepository) 
  12802.                     A pointer to  the ImplRepository object. 
  12803.  
  12804.           env (Environment *) 
  12805.                     A pointer to the Environment structure for the method 
  12806.                     caller. 
  12807.  
  12808.           impldef (ImplementationDef) 
  12809.                     A pointer to an ImplementationDef object, whose values are 
  12810.                     to be saved in the Implementation Repository. 
  12811.  
  12812.  Returns 
  12813.  
  12814.           rc (void) 
  12815.                     An exception is returned if there was an error updating the 
  12816.                     Implementation Repository. 
  12817.  
  12818.  Remarks 
  12819.  
  12820.           Replaces the state of the specified ImplementationDef object in the 
  12821.           Implementation Repository. The ID of the impldef determines which 
  12822.           object gets updated in the Implementation Repository. 
  12823.  
  12824.  Original Class 
  12825.  
  12826.           ImplRepository 
  12827.  
  12828.  Example Code 
  12829.  
  12830.                     #include  _somd.h>
  12831.                     Environment ev;
  12832.                     SOMDObject objref;
  12833.                     ImplementationDef impldef;
  12834.                     ...
  12835.                     impldef = _get_implementation(objref,&ev);
  12836.                     __set_impl_program(impldef,&ev,"/u/joe/bin/myserver");
  12837.                     _update_impldef(SOMD_ImplRepObject,&ev,impldef);
  12838.  
  12839.  
  12840. ΓòÉΓòÉΓòÉ 3.44. NVList ΓòÉΓòÉΓòÉ
  12841.  
  12842. NVList 
  12843.  
  12844.  File stem: nvlist 
  12845.  
  12846.  Base 
  12847.  
  12848.           SOMObject 
  12849.  
  12850.  Metaclass 
  12851.  
  12852.           SOMClass 
  12853.  
  12854.  Ancestor Classes 
  12855.  
  12856.                     SOMObject
  12857.  
  12858.  Description 
  12859.  
  12860.           The type NamedValue is a standard datatype defined in CORBA (see the 
  12861.           CORBA 1.1 page 106). It can be used either as a parameter type or as 
  12862.           a mechanism for describing arguments to a request. The NVList class 
  12863.           implements the NVList object used for constructing lists composed of 
  12864.           NamedValues. NVLists can be used to describe arguments passed to 
  12865.           request operations or to pass lists of property names and values to 
  12866.           context object routines. Addition information about NVList is 
  12867.           contained in Chapter 6 of the CORBA 1.1 specification. 
  12868.  
  12869.  New methods 
  12870.  
  12871.           The following list shows all the NVList methods. 
  12872.  
  12873.               add_item 
  12874.               free 
  12875.               free_memory 
  12876.               get_count 
  12877.               get_item* 
  12878.               set_item* 
  12879.  
  12880.                (* These methods were added by DSOM to supplement the published 
  12881.                CORBA 1.1 methods.) 
  12882.  
  12883.  Overridden methods 
  12884.  
  12885.           The following list shows all the methods overridden by the NVList 
  12886.           class. These methods are overridden in order to modify the behavior 
  12887.           defined by an ancestor class. 
  12888.  
  12889.               somInit 
  12890.  
  12891.  
  12892. ΓòÉΓòÉΓòÉ 3.45. add_item ΓòÉΓòÉΓòÉ
  12893.  
  12894. add_item This method adds an item to the specified NVList. 
  12895.  
  12896.  Syntax 
  12897.  
  12898.                     ORBStatus add_item (NVList receiver, Environment *env,
  12899.                                 Identifier item_name, TypeCode item_type,
  12900.                                 void *value, long value_len, Flags item_flags)
  12901.  
  12902.  Parameters 
  12903.  
  12904.           receiver (NVList) 
  12905.                     A pointer to the NVList object to which the item will be 
  12906.                     added. 
  12907.  
  12908.           env (Environment *) 
  12909.                     A pointer to the Environment structure for the method 
  12910.                     caller. 
  12911.  
  12912.           item_name (Identifier) 
  12913.                     The name of the item to be added. 
  12914.  
  12915.           item_type (TypeCode) 
  12916.                     The data type of the item to be added. 
  12917.  
  12918.           value (void *) 
  12919.                     A pointer to the value of the item to be added. 
  12920.  
  12921.           value_len (long) 
  12922.                     The length of the item value to be added. 
  12923.  
  12924.           item_flags (Flags) 
  12925.                     A Flags bitmask (unsigned long). The item_flags can be one 
  12926.                     of the following values to indicate parameter direction: 
  12927.  
  12928.                     ARG_IN                     The argument is input only. 
  12929.                     ARG_OUT                    The argument is output only. 
  12930.                     ARG_INOUT                  The argument is input/output. 
  12931.                     IN_COPY_VALUE              An internal copy of the argument 
  12932.                                                is made and used. 
  12933.                     DEPENDENT_LIST             Indicates that a specified 
  12934.                                                sublist must be freed when the 
  12935.                                                parent list is freed. 
  12936.  
  12937.  Returns 
  12938.  
  12939.           rc (ORBStatus) 
  12940.                     Returns an ORBStatus value representing the return code 
  12941.                     from the operation. 
  12942.  
  12943.  Remarks 
  12944.  
  12945.           The add_item method adds an item to the end of the specified list. 
  12946.  
  12947.  Original Class 
  12948.  
  12949.           NVList 
  12950.  
  12951.  Related Methods 
  12952.  
  12953.           Methods 
  12954.  
  12955.               free 
  12956.               free_memory 
  12957.               get_count 
  12958.               get_item 
  12959.               set_item 
  12960.               create_list 
  12961.  
  12962.  Example Code 
  12963.  
  12964.                     #include  <somd.h>
  12965.  
  12966.                     Environment ev;
  12967.                     NVList plist;
  12968.                     ORBStatus rc;
  12969.                     ...
  12970.                     rc = _create_list(SOMD_ORBObject, &ev, 0, &plist);
  12971.                     rc = _add_item(plist, &ev, "firstname", TC_string,"Joe", 3, 0);
  12972.                     rc = _add_item(plist, &ev, "lastname", TC_string,"Schmoe", 5, 0);
  12973.  
  12974.  
  12975. ΓòÉΓòÉΓòÉ 3.46. free ΓòÉΓòÉΓòÉ
  12976.  
  12977. free This method frees a specified NVList. 
  12978.  
  12979.  Syntax 
  12980.  
  12981.                     ORBStatus free (NVLIST receiver, Environment *env)
  12982.  
  12983.  Parameters 
  12984.  
  12985.           receiver (NVLIST) 
  12986.                     A pointer to the NVList object to be freed. 
  12987.  
  12988.           env (Environment *) 
  12989.                     A pointer to the Environment structure for the method 
  12990.                     caller. 
  12991.  
  12992.  Returns 
  12993.  
  12994.           rc (ORBStatus) 
  12995.                     Returns an ORBStatus value representing the return code 
  12996.                     from the operation. 
  12997.  
  12998.  Remarks 
  12999.  
  13000.           The free method frees an NVList object and any associated memory. It 
  13001.           makes an implicit call to the free_memory method. 
  13002.  
  13003.  Original Class 
  13004.  
  13005.           NVList 
  13006.  
  13007.  Related Methods 
  13008.  
  13009.           Functions 
  13010.  
  13011.               ORBfree 
  13012.  
  13013.           Methods 
  13014.  
  13015.               free_memory 
  13016.  
  13017.  Example Code 
  13018.  
  13019.                     #include  <somd.h>
  13020.  
  13021.                     Environment ev;
  13022.                     long nargs;
  13023.                     NVList arglist;
  13024.                     ORBStatus rc;
  13025.                     ...
  13026.                     rc = _create_list(SOMD_ORBObject, &ev, nargs, &arglist);
  13027.                     ...
  13028.                     rc=  _free(arglist,&ev);
  13029.  
  13030.  
  13031. ΓòÉΓòÉΓòÉ 3.47. free_memory ΓòÉΓòÉΓòÉ
  13032.  
  13033. free_memory This method frees any dynamically allocated out-arg memory 
  13034. associated with the specified list. 
  13035.  
  13036.  Syntax 
  13037.  
  13038.                     ORBStatus free_memory (NVList receiver, Environment *env)
  13039.  
  13040.  Parameters 
  13041.  
  13042.           receiver (NVList) 
  13043.                     A pointer to the NVList object whose out-arg memory is to 
  13044.                     be freed. 
  13045.  
  13046.           env (Environment *) 
  13047.                     A pointer to the Environment structure for the method 
  13048.                     caller. 
  13049.  
  13050.  Returns 
  13051.  
  13052.           rc (ORBStatus) 
  13053.                     Returns an ORBStatus value representing the return code 
  13054.                     from the operation. 
  13055.  
  13056.  Remarks 
  13057.  
  13058.           The free_memory method frees any dynamically allocated out-arg memory 
  13059.           associated with the specified list, without freeing the list object 
  13060.           itself. This would be useful when invoking a DII request multiple 
  13061.           times with the same NVList. 
  13062.  
  13063.  Original Class 
  13064.  
  13065.           NVList 
  13066.  
  13067.  Related Methods 
  13068.  
  13069.           Functions 
  13070.  
  13071.               ORBfree 
  13072.  
  13073.           Methods 
  13074.  
  13075.               free 
  13076.  
  13077.  Example Code 
  13078.  
  13079.                     #include  <somd.h>
  13080.                     #include  <repostry.h>
  13081.                     #include  <intfacdf.h>
  13082.                     #include  <foo.h>   /* provided by user */
  13083.  
  13084.                     /* assume following method declaration in interface Foo:
  13085.                      *  long methodLong  (in long inLong,inout long inoutLong);
  13086.                      * then the following code repeatedly invokes a request:
  13087.                      * result = methodLong(fooObj, &ev, 100, 200);
  13088.                      * using the DII.
  13089.                      */
  13090.  
  13091.                     Environment ev;
  13092.                     NVList arglist;
  13093.                     NamedValue result;
  13094.                     long rc;
  13095.                     Foo fooObj;
  13096.                     Request reqObj;
  13097.  
  13098.                     /* See example code for "invoke" to see how the argList is built */
  13099.  
  13100.                     /* Create the Request, reqObj */
  13101.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  13102.                                          arglist, &result, &reqObj, (Flags)0);
  13103.  
  13104.                     /* Repeatedly invoke the Request */
  13105.                     for (;;) {
  13106.                        rc = _invoke(reqObj, &ev, (Flags)0);
  13107.                        ...
  13108.                        rc = _free_memory(arglist,&ev);  /* free out args */
  13109.                     }
  13110.                     ...
  13111.  
  13112.  
  13113. ΓòÉΓòÉΓòÉ 3.48. get_count ΓòÉΓòÉΓòÉ
  13114.  
  13115. get_count This method returns the total number of items allocated for a list. 
  13116.  
  13117.  Syntax 
  13118.  
  13119.                     ORBStatus get_count (NVList receiver, Environment *env, long count)
  13120.  
  13121.  Parameters 
  13122.  
  13123.           receiver (NVList) 
  13124.                     A pointer to the NVList object on which count is desired. 
  13125.  
  13126.           env (Environment *) 
  13127.                     A pointer to the Environment structure for the method 
  13128.                     caller. 
  13129.  
  13130.           count (long) 
  13131.                     A pointer to where the method will store the long integer 
  13132.                     count value. 
  13133.  
  13134.  Returns 
  13135.  
  13136.           rc (ORBStatus) 
  13137.                     Returns an ORBStatus value representing the return code 
  13138.                     from the operation. 
  13139.  
  13140.  Remarks 
  13141.  
  13142.           The get_count method returns the total number of allocated items in 
  13143.           the specified list. 
  13144.  
  13145.  Original Class 
  13146.  
  13147.           NVList 
  13148.  
  13149.  Related Methods 
  13150.  
  13151.           Methods 
  13152.  
  13153.               add_item 
  13154.               get_item 
  13155.               set_item 
  13156.               create_list 
  13157.  
  13158.  Example Code 
  13159.  
  13160.                     #include  <somd.h>
  13161.  
  13162.                     Environment ev;
  13163.                     long nargs, list_size;
  13164.                     NVList arglist;
  13165.                     ORBStatus rc;
  13166.                     ...
  13167.                     rc = _create_list(SOMD_ORBObject, &ev, nargs, &arglist);
  13168.                     ...
  13169.                     rc = _get_count(arglist,&ev,&list_size);
  13170.  
  13171.  
  13172. ΓòÉΓòÉΓòÉ 3.49. get_item ΓòÉΓòÉΓòÉ
  13173.  
  13174. get_item This method returns the contents of a specified list item. 
  13175.  
  13176.  Syntax 
  13177.  
  13178.                     ORBStatus get_item (NVList receiver, Environment *env,
  13179.                                 long item_number, Identifier item_name,
  13180.                                 TypeCode item_type, void *value, long value_len,
  13181.                                 Flags item_flags)
  13182.  
  13183.  Parameters 
  13184.  
  13185.           receiver (NVList) 
  13186.                     A pointer to an NVList object. 
  13187.  
  13188.           env (Environment *) 
  13189.                     A pointer to the Environment structure for the method 
  13190.                     caller. 
  13191.  
  13192.           item_number (long) 
  13193.                     The position (index) of the item in the list. The 
  13194.                     item_number ranges from 0 to n-1, where n  is the total 
  13195.                     number of items in the list. 
  13196.  
  13197.           item_name (Identifier) 
  13198.                     A pointer to where the name of the item should be returned. 
  13199.  
  13200.           item_type (TypeCode) 
  13201.                     A pointer to where the data type of the item should be 
  13202.                     returned. 
  13203.  
  13204.           value (void *) 
  13205.                     A pointer to where a pointer to the value of the item 
  13206.                     should be returned. 
  13207.  
  13208.           value_len (long) 
  13209.                     A pointer to where the length of the item value should be 
  13210.                     returned. 
  13211.  
  13212.           item_flags (Flags) 
  13213.                     A Flags bitmask (unsigned long). The item_flags can be one 
  13214.                     of the following values indicating parameter direction. 
  13215.  
  13216.                     ARG_IN                     The argument is input only. 
  13217.                     ARG_OUT                    The argument is output only. 
  13218.                     ARG_INOUT                  The argument is input/output. 
  13219.                     IN_COPY_VALUE              Indicates a copy of the argument 
  13220.                                                is contained and used by the 
  13221.                                                NVList. 
  13222.                     DEPENDENT_LIST             Indicates that a specified 
  13223.                                                sublist must be freed when the 
  13224.                                                parent list is freed. 
  13225.  
  13226.  Returns 
  13227.  
  13228.           rc (ORBStatus) 
  13229.                     Returns 0 for success, or a DSOM error code for failure 
  13230.                     (often because item_number+1 exceeds the number of items in 
  13231.                     the list). 
  13232.  
  13233.  Remarks 
  13234.  
  13235.           The get_item method gets an item from the specified list. Items are 
  13236.           numbered from 0 through N. The mode flags can be one of the following 
  13237.           values: 
  13238.  
  13239.           The get_item method transfers ownership of storage allocated for the 
  13240.           item value to the caller. 
  13241.  
  13242.  Original Class 
  13243.  
  13244.           NVList 
  13245.  
  13246.  Related Methods 
  13247.  
  13248.           Methods 
  13249.  
  13250.               add_item 
  13251.               set_item 
  13252.               create_list 
  13253.  
  13254.  Example Code 
  13255.  
  13256.                     #include  <somd.h>
  13257.  
  13258.                     Environment ev;
  13259.                     long i, nArgs;
  13260.                     ORBStatus rc;
  13261.                     Identifier name;
  13262.                     TypeCode typeCode;
  13263.                     void *value;
  13264.                     long len;
  13265.                     Flags flags;
  13266.                     NVList argList;
  13267.                     ...
  13268.                     /* get number of args */
  13269.                     rc = _get_count(argList, ev, &nArgs);
  13270.                     for (i = 0; i
  13271.                        /* get item description */
  13272.                        rc =  _get_item(argList,
  13273.                                        &ev,
  13274.                                        i,
  13275.                                        &name,
  13276.                                        &typeCode,
  13277.                                        &value,
  13278.                                        &len,
  13279.                                        &flags);
  13280.                        ...
  13281.                        }
  13282.  
  13283.  
  13284. ΓòÉΓòÉΓòÉ 3.50. set_item ΓòÉΓòÉΓòÉ
  13285.  
  13286. set_item This method sets the contents of an item in a list. 
  13287.  
  13288.  Syntax 
  13289.  
  13290.                     ORBStatus set_item (NVList receiver, Environment *env,
  13291.                                 long item_number, Identifier item_name,
  13292.                                 TypeCode item_type, void *value, long value_len,
  13293.                                 Flags item_flags)
  13294.  
  13295.  Parameters 
  13296.  
  13297.           receiver (NVList) 
  13298.                     A pointer to an NVList which contains the item to be set. 
  13299.  
  13300.           env (Enviornment *) 
  13301.                     A pointer to the Environment structure for the method 
  13302.                     caller. 
  13303.  
  13304.           item_number (long) 
  13305.                     The position (index) of the item in the list. The 
  13306.                     item_number ranges from 0 to n-1, where n  is the total 
  13307.                     number of items in the list. 
  13308.  
  13309.           item_name (Identifier) 
  13310.                     The name of the set item. 
  13311.  
  13312.           item_type (TypeCode) 
  13313.                     The data type of the set item. 
  13314.  
  13315.           value (void *) 
  13316.                     A pointer to the value of the set item. 
  13317.  
  13318.           value_len (long) 
  13319.                     The length of the set item value. 
  13320.  
  13321.           item_flags (Flags) 
  13322.                     A Flags bitmask (unsigned long). The item_flags can be one 
  13323.                     of the following values to indicate parameter direction: 
  13324.  
  13325.                     ARG_IN                     The argument is input only. 
  13326.                     ARG_OUT                    The argument is output only. 
  13327.                     ARG_INOUT                  The argument is input/output. 
  13328.                     IN_COPY_VALUE              Indicates an internal copy of 
  13329.                                                the argument is made and used. 
  13330.                     DEPENDENT_LIST             Indicates that a specified 
  13331.                                                sublist must be freed when the 
  13332.                                                parent list is freed. 
  13333.  
  13334.  Returns 
  13335.  
  13336.           rc (ORBStatus) 
  13337.                     Returns 0 on successful completion or a DSOM error code 
  13338.                     upon failure (often because item_number+1 exceeds the 
  13339.                     number of items in the list). 
  13340.  
  13341.  Remarks 
  13342.  
  13343.           The set_item method sets the contents of an item in the list. 
  13344.  
  13345.  Original Class 
  13346.  
  13347.           NVList 
  13348.  
  13349.  Related Methods 
  13350.  
  13351.           Methods 
  13352.  
  13353.               get_item 
  13354.               add_item 
  13355.               create_list 
  13356.  
  13357.  Example Code 
  13358.  
  13359.                     #include  <somd.h>
  13360.  
  13361.                     Environment ev;
  13362.                     long i, nArgs;
  13363.                     ORBStatus rc;
  13364.                     Identifier name;
  13365.                     TypeCode typeCode;
  13366.                     void *value;
  13367.                     long len;
  13368.                     Flags flags;
  13369.                     NVList argList;
  13370.                     ...
  13371.                     /* get number of args */
  13372.                     rc = _get_count(argList, ev, &nArgs);
  13373.                     for (i = 0; i
  13374.                        /* change item description */
  13375.                        rc =  _set_item(argList,
  13376.                                        &ev,
  13377.                                        i,
  13378.                                        name,
  13379.                                        typeCode,
  13380.                                        value,
  13381.                                        len,
  13382.                                        flags);
  13383.                        ...
  13384.                        }
  13385.  
  13386.  
  13387. ΓòÉΓòÉΓòÉ 3.51. ObjectMgr ΓòÉΓòÉΓòÉ
  13388.  
  13389. ObjectMgr 
  13390.  
  13391.  File stem: om 
  13392.  
  13393.  Base 
  13394.  
  13395.           SOMObject 
  13396.  
  13397.  Metaclass 
  13398.  
  13399.           SOMMSingleInstance 
  13400.  
  13401.  Ancestor Classes 
  13402.  
  13403.                     SOMObject
  13404.  
  13405.  Subclasses 
  13406.  
  13407.           SOMDObjectMgr 
  13408.  
  13409.  Description 
  13410.  
  13411.           The ObjectMgr class provides a uniform, universal abstraction  for 
  13412.           any sort of object manager. Object Request Brokers, persistent 
  13413.           storage managers, and OODBMSs are examples of object managers. 
  13414.  
  13415.           This is an abstract base class, which defines the "core" interface 
  13416.           for an object manager. It provides basic methods that: 
  13417.  
  13418.               Create a new object of a certain class, 
  13419.               Return a (persistent) ID for an object, 
  13420.               Return a reference to an object associated with an ID, 
  13421.               Free an object (i.e., release any local memory associated with 
  13422.                the object without necessarily destroying the object itself), or 
  13423.               Destroy an object. 
  13424.  
  13425.           Note:  The ObjectMgr is an abstract class and should not be 
  13426.           instantiated. Any subclass of ObjectMgr must provide implementations 
  13427.           for all ObjectMgr methods. In DSOM, the class SOMDObjectMgr provides 
  13428.           a DSOM-specific implementation. 
  13429.  
  13430.  New methods 
  13431.  
  13432.           The following list shows all the ObjectMgr instance methods. 
  13433.  
  13434.               somdDestroyObject* 
  13435.               somdGetIdFromObject* 
  13436.               somdGetObjectFromID* 
  13437.               somdNewObject* 
  13438.               somdReleaseObject* 
  13439.  
  13440.           (* This class and its methods were added by DSOM to supplement the 
  13441.           published CORBA 1.1 interfaces.) 
  13442.  
  13443.  
  13444. ΓòÉΓòÉΓòÉ 3.52. somdDestroyObject ΓòÉΓòÉΓòÉ
  13445.  
  13446. somdDestroyObject This method requests destruction of the target object. 
  13447.  
  13448.  Syntax 
  13449.  
  13450.                     void somdDestroyObject (ObjectMgr receiver, Environment *env,
  13451.                                   SOMObject obj)
  13452.  
  13453.  Parameters 
  13454.  
  13455.           receiver (ObjectMgr) 
  13456.                     A pointer to an ObjectMgr object. 
  13457.  
  13458.           env (Environment *) 
  13459.                     A pointer to the Environment structure for the method 
  13460.                     caller. 
  13461.  
  13462.           obj (SOMObject) 
  13463.                     A pointer to the object to be freed. 
  13464.  
  13465.  Returns 
  13466.  
  13467.           rc (void) 
  13468.  
  13469.  Remarks 
  13470.  
  13471.           The somdDestroyObject method indicates that the object manager should 
  13472.           destroy the specified object. Storage associated with the object is 
  13473.           freed. 
  13474.  
  13475.           In DSOM, the SOMDObjectMgr forwards the deletion request to the 
  13476.           remote server, and then frees the local proxy object. 
  13477.  
  13478.  Original Class 
  13479.  
  13480.           ObjectMgr 
  13481.  
  13482.  Related Methods 
  13483.  
  13484.           Methods 
  13485.  
  13486.               somdReleaseObject 
  13487.               somdCreateObject 
  13488.               somdTargetFree 
  13489.               release 
  13490.  
  13491.  Example Code 
  13492.  
  13493.                     #include  <somd.h>
  13494.  
  13495.                     Stack stk;
  13496.                     Environment ev;
  13497.                     SOMDServer server;
  13498.  
  13499.                     SOM_InitEnvironment(&ev);
  13500.                     SOMD_Init(&ev);
  13501.                     StackNewClass(0,0);
  13502.                     server =
  13503.                       _somdFindAnyServerByClass(SOMD_ObjectMgr, &ev,"Stack");
  13504.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  13505.                     ...
  13506.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  13507.  
  13508.  
  13509. ΓòÉΓòÉΓòÉ 3.53. somdGetIdFromObject ΓòÉΓòÉΓòÉ
  13510.  
  13511. somdGetIdFromObject This method returns an ID for an object managed by a 
  13512. specified Object Manager. 
  13513.  
  13514.  Syntax 
  13515.  
  13516.                     string somdGetIdFromObject (ObjectMgr receiver, Environment *env,
  13517.                                     SOMDObject obj)
  13518.  
  13519.  Parameters 
  13520.  
  13521.           receiver (ObjectMgr) 
  13522.                     A pointer to an ObjectMgr object. 
  13523.  
  13524.           env (Environment *) 
  13525.                     A pointer to the Environment structure for the method 
  13526.                     caller. 
  13527.  
  13528.           obj (SOMDObject) 
  13529.                     A pointer to the SOMDObject object for which an ID is 
  13530.                     needed. 
  13531.  
  13532.  Returns 
  13533.  
  13534.           rc (string) 
  13535.                     Returns a string representing the ID of the specified 
  13536.                     object. 
  13537.  
  13538.  Remarks 
  13539.  
  13540.           The somdGetIdFromObject method returns the persistent ID for an 
  13541.           object managed by the specified Object Manager. This ID is 
  13542.           unambiguous-it always refers to the same object. 
  13543.  
  13544.           The somdGetIdFromObject method transfers ownership of storage 
  13545.           allocated for the string to the caller. The caller should free the 
  13546.           result using ORBfree function, rather than the SOMFree function. 
  13547.  
  13548.  Original Class 
  13549.  
  13550.           ObjectMgr 
  13551.  
  13552.  Related Methods 
  13553.  
  13554.           Methods 
  13555.  
  13556.               somdGetObjectFromId 
  13557.  
  13558.  Example Code 
  13559.  
  13560.                     #include  <somd.h>
  13561.                     #include  <car.h>
  13562.  
  13563.                     Environment ev;
  13564.                     Car car;
  13565.                     string somdObjectId;
  13566.                     /*note that "SOMDObject Identifiers" are just strings */
  13567.  
  13568.                     SOM_InitEnvironment(&ev);
  13569.                     SOMD_Init(&ev);
  13570.  
  13571.                     /* create a remote Car object */
  13572.                     car = _somdNewObject(SOMD_ObjectMgr, &ev, "Car", "");
  13573.  
  13574.                     /* save the reference to the object */
  13575.                     somdObjectId = _somdGetIdFromObject(SOMD_ObjectMgr, &ev, car);
  13576.                     FileWrite("/u/joe/mycar", somdObjectId);
  13577.                     ...
  13578.  
  13579.  
  13580. ΓòÉΓòÉΓòÉ 3.54. somdGetObjectFromId ΓòÉΓòÉΓòÉ
  13581.  
  13582. somdGetObjectFromId This method finds and activates an object implemented by a 
  13583. specified object manager, given its ID. 
  13584.  
  13585.  Syntax 
  13586.  
  13587.                     SOMObject somdGetObjectFromId (ObjectMgr receiver,
  13588.                                       Environment *env, string id)
  13589.  
  13590.  Parameters 
  13591.  
  13592.           receiver (ObjectMgr) 
  13593.                     A pointer to an ObjectMgr  object. 
  13594.  
  13595.           env (Environment *) 
  13596.                     A pointer to the Environment structure for the method 
  13597.                     caller. 
  13598.  
  13599.           id (string) 
  13600.                     A string representing an object ID. 
  13601.  
  13602.  Returns 
  13603.  
  13604.           rc (SOMObject) 
  13605.                     Returns a pointer to the object with the specified ID. 
  13606.  
  13607.  Remarks 
  13608.  
  13609.           The somdGetObjectFromId method finds and activates an object 
  13610.           implemented by this object manager, given its ID. 
  13611.  
  13612.           The somdGetObjectFromId method transfers ownership to the caller. 
  13613.  
  13614.  Original Class 
  13615.  
  13616.           ObjectMgr 
  13617.  
  13618.  Related Methods 
  13619.  
  13620.           Methods 
  13621.  
  13622.               somdGetIdFromObject 
  13623.  
  13624.  Example Code 
  13625.  
  13626.                     #include  <somd.h>
  13627.                     #include  <car.h>
  13628.                     Environment ev;
  13629.                     Car car;
  13630.                     string somdObjectId;
  13631.                     ...
  13632.                     /* restore proxy from its string form */
  13633.                     FileRead("/u/joe/mycar", &somdObjectId);
  13634.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  13635.                     ...
  13636.  
  13637.  
  13638. ΓòÉΓòÉΓòÉ 3.55. somdNewObject ΓòÉΓòÉΓòÉ
  13639.  
  13640. somdNewObject This method returns a new object of the named class. 
  13641.  
  13642.  Syntax 
  13643.  
  13644.                     SOMObject somdNewObject (ObjectMgr receiver, Environment *env,
  13645.                                    Identifier objclass, string hints)
  13646.  
  13647.  Parameters 
  13648.  
  13649.           receiver (ObjectMgr) 
  13650.                     A pointer to an ObjectMgr object. 
  13651.  
  13652.           env (Environment *) 
  13653.                     A pointer to the Environment structure for the method 
  13654.                     caller. 
  13655.  
  13656.           objclass (Identifier) 
  13657.                     An Identifier representing the type of the new object. 
  13658.  
  13659.           hints (string) 
  13660.                     A string which may optionally be used to specify special 
  13661.                     creation options. 
  13662.  
  13663.  Returns 
  13664.  
  13665.           rc (SOMObject) 
  13666.                     Returns a SOMObject. Ownership of the new object is 
  13667.                     transferred to the caller. 
  13668.  
  13669.  Remarks 
  13670.  
  13671.           The somdNewObject method returns a new object of the class  specified 
  13672.           by objclass. The hints field is currently ignored by the 
  13673.           SOMDObjectMgr. (This field is designed so that application-specific 
  13674.           creation options can be supplied in a later SOMobjects release.) 
  13675.  
  13676.           In DSOM, the SOMDObjectMgr selects a random server which has 
  13677.           advertised knowledge of the desired class objclass, and forwards the 
  13678.           creation request to that server. If multiple capable servers are 
  13679.           registered in the Implementation Repository, subsequent calls will be 
  13680.           routed to different servers (starting them automatically if 
  13681.           necessary) in order to distribute the load across several servers 
  13682.           where possible. 
  13683.  
  13684.  Original Class 
  13685.  
  13686.           ObjectMgr 
  13687.  
  13688.  Related Methods 
  13689.  
  13690.           Methods 
  13691.  
  13692.               somdDestroyObject 
  13693.               somdReleaseObject 
  13694.  
  13695.  Example Code 
  13696.  
  13697.                     #include  <somd.h>
  13698.                     #include  <stack.h>   /* provided by user */
  13699.  
  13700.                     Stack stk;
  13701.                     Environment ev;
  13702.                     SOMDServer server;
  13703.  
  13704.                     SOM_InitEnvironment(&ev);
  13705.                     SOMD_Init(&&ev);
  13706.                     StackNewClass(0,0);
  13707.                     stk = _somdNewObject(SOMD_ObjectMgr, &ev, "Stack", "");
  13708.                     ...
  13709.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  13710.  
  13711.  
  13712. ΓòÉΓòÉΓòÉ 3.56. somdReleaseObject ΓòÉΓòÉΓòÉ
  13713.  
  13714. somdReleaseObject This method indicates that the client has finished using the 
  13715. object. 
  13716.  
  13717.  Syntax 
  13718.  
  13719.                     void somdReleaseObject (ObjectMgr receiver, Environment *env,
  13720.                                   SOMObject obj)
  13721.  
  13722.  Parameters 
  13723.  
  13724.           receiver (ObjectMgr) 
  13725.                     A pointer to an ObjectMgr object. 
  13726.  
  13727.           env (Environment *) 
  13728.                     A pointer to the Environment structure for the method 
  13729.                     caller. 
  13730.  
  13731.           obj (SOMObject) 
  13732.                     A pointer to the object to be released. 
  13733.  
  13734.  Returns 
  13735.  
  13736.           rc (void) 
  13737.  
  13738.  Remarks 
  13739.  
  13740.           The somdReleaseObject method indicates that the client has finished 
  13741.           using the specified object. This allows the object manager to free 
  13742.           the bookkeeping information associated with the object, if any. The 
  13743.           object may also be passivated, but it is not destroyed. 
  13744.  
  13745.           In DSOM, somdReleaseObject causes the client's proxy for the target 
  13746.           object of interest to be freed; the target object is not freed. 
  13747.  
  13748.  Original Class 
  13749.  
  13750.           ObjectMgr 
  13751.  
  13752.  Related Methods 
  13753.  
  13754.           Methods 
  13755.  
  13756.               somdDestroyObject 
  13757.               somdNewObject 
  13758.               somdTargetFree 
  13759.               release 
  13760.  
  13761.  Example Code 
  13762.  
  13763.                     #include  <somd.h>
  13764.                     #include  <car.h>
  13765.  
  13766.                     Environment ev;
  13767.                     Car car;
  13768.                     string somdObjectId;
  13769.                     ...
  13770.                     /* restore proxy from its string form */
  13771.                     FileRead("/u/joe/mycar", &somdObjectId);
  13772.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  13773.                     ...
  13774.                     _somdReleaseObject(SOMD_ObjectMgr, &ev, car);
  13775.  
  13776.  
  13777. ΓòÉΓòÉΓòÉ 3.57. ORB ΓòÉΓòÉΓòÉ
  13778.  
  13779. ORB 
  13780.  
  13781.  File stem: orb 
  13782.  
  13783.  Base 
  13784.  
  13785.           SOMObject 
  13786.  
  13787.  Metaclass 
  13788.  
  13789.           SOMMSingleInstance 
  13790.  
  13791.  Ancestor Classes 
  13792.  
  13793.                     SOMObject
  13794.  
  13795.  Description 
  13796.  
  13797.           The ORB class implements the CORBA ORB object described in Chapter 8 
  13798.           of the CORBA 1.1 specification. The ORB class defines operations for 
  13799.           converting object references to strings and converting strings to 
  13800.           object references. The ORB also defines operations used by the 
  13801.           Dynamic Invocation Interface for creating lists (NVLists) and 
  13802.           determining the default context. 
  13803.  
  13804.  New methods 
  13805.  
  13806.           The following list shows all the ORB methods. 
  13807.  
  13808.               create_list 
  13809.               create_operation_list 
  13810.               get_default_context 
  13811.               object_to_string 
  13812.               string_to_object 
  13813.  
  13814.  
  13815. ΓòÉΓòÉΓòÉ 3.58. create_list ΓòÉΓòÉΓòÉ
  13816.  
  13817. create_list This method creates an NVList of the specified size. 
  13818.  
  13819.  Syntax 
  13820.  
  13821.                     ORBStatus create_list (ORB receiver, Environment *env, long count,
  13822.                                  NVList new_list)
  13823.  
  13824.  Parameters 
  13825.  
  13826.           receiver (ORB) 
  13827.                     A pointer to the ORB object. 
  13828.  
  13829.           env (Environment *) 
  13830.                     A pointer to the Environment structure for the method 
  13831.                     caller. 
  13832.  
  13833.           count (long) 
  13834.                     An integer representing the number of elements to allocate 
  13835.                     for the list. 
  13836.  
  13837.           new_list (NVList) 
  13838.                     A pointer to the address where the method will store a 
  13839.                     pointer to the allocated NVList object. 
  13840.  
  13841.  Returns 
  13842.  
  13843.           rc (ORBStatus) 
  13844.                     Returns an ORBStatus value representing the return code of 
  13845.                     the operation. 
  13846.  
  13847.  Remarks 
  13848.  
  13849.           Creates an NVList list of the specified size, typically for use in 
  13850.           Requests. 
  13851.  
  13852.           Ownership of the allocated new_list is transferred to the caller. 
  13853.  
  13854.  Original Class 
  13855.  
  13856.           ORB 
  13857.  
  13858.  Related Methods 
  13859.  
  13860.           Methods 
  13861.  
  13862.               create_operation_list 
  13863.  
  13864.  Example Code 
  13865.  
  13866.                     #include  <somd.h>
  13867.  
  13868.                     Environment ev;
  13869.                     long nargs = 5;
  13870.                     NVList arglist;
  13871.                     ORBStatus rc;
  13872.                     ...
  13873.                     rc = _create_list(SOMD_ORBObject, &ev, nargs, &arglist);
  13874.  
  13875.  
  13876. ΓòÉΓòÉΓòÉ 3.59. create_operation_list ΓòÉΓòÉΓòÉ
  13877.  
  13878. create_operation_list This method creates an NVList initialized with the 
  13879. argument descriptions for a given operation. 
  13880.  
  13881.  Syntax 
  13882.  
  13883.                     ORBStatus create_operation_list (ORB receiver, Environment *env,
  13884.                                       operationDef oper,
  13885.                                       NVList new_list)
  13886.  
  13887.  Parameters 
  13888.  
  13889.           receiver (ORB) 
  13890.                     A pointer to the ORB object. 
  13891.  
  13892.           env (Environment *) 
  13893.                     A pointer to the Environment structure for the method 
  13894.                     caller. 
  13895.  
  13896.           oper (OperationDef) 
  13897.                     A pointer to the OperationDef object representing the 
  13898.                     operation for which the NVList is to be initialized. 
  13899.  
  13900.           new_list (NVList) 
  13901.                     A pointer to where the method will store a pointer to the 
  13902.                     resulting argument list. 
  13903.  
  13904.  Returns 
  13905.  
  13906.           rc (ORBStatus) 
  13907.                     Returns an ORBStatus value representing the return code of 
  13908.                     the operation. 
  13909.  
  13910.                     Ownership of the allocated new_list is transferred to the 
  13911.                     caller. 
  13912.  
  13913.  Remarks 
  13914.  
  13915.           Creates an NVList list for the specified operation, for use in 
  13916.           Requests invoking that operation. 
  13917.  
  13918.  Original Class 
  13919.  
  13920.           ORB 
  13921.  
  13922.  Related Methods 
  13923.  
  13924.           Methods 
  13925.  
  13926.               create_list 
  13927.  
  13928.  Example Code 
  13929.  
  13930.                     #include  <somd.h>
  13931.  
  13932.                     Environment ev;
  13933.                     OperationDef opdef;
  13934.                     NVList arglist;
  13935.                     long rc;
  13936.  
  13937.                     /* Get the OperationDef from the Interface Repository. */
  13938.                     opdef = _lookup_id(SOM_InterfaceRepository,
  13939.                                        &ev, "Foo::methodLong");
  13940.                     /* Create a NamedValue list for the operation. */
  13941.                     rc= _create_operation_list(SOMD_ORBObject, &ev, opdef, &arglist);
  13942.  
  13943.  
  13944. ΓòÉΓòÉΓòÉ 3.60. get_default_context ΓòÉΓòÉΓòÉ
  13945.  
  13946. get_default_context This method returns the default process Context object. 
  13947.  
  13948.  Syntax 
  13949.  
  13950.                     ORBStatus get_default_context (ORB receiver, Environment *env,
  13951.                                       Context ctx)
  13952.  
  13953.  Parameters 
  13954.  
  13955.           receiver (ORB) 
  13956.                     A pointer to the ORB object. 
  13957.  
  13958.           env (Environment *) 
  13959.                     A pointer to the Environment structure for the method 
  13960.                     caller. 
  13961.  
  13962.           ctx (Context) 
  13963.                     A pointer to where the method will store a pointer to the 
  13964.                     returned Context object. 
  13965.  
  13966.  Returns 
  13967.  
  13968.           rc (ORBStatus) 
  13969.                     Returns an ORBStatus return code:  0 indicates success, 
  13970.                     while a non-zero value is a DSOM error code (see Chapter 6 
  13971.                     of the SOM Programming Guide). 
  13972.  
  13973.  Remarks 
  13974.  
  13975.           The get_default_context method gets the default process Context 
  13976.           object. 
  13977.  
  13978.           Ownership of the allocated Context object is transferred to the 
  13979.           caller. 
  13980.  
  13981.  Original Class 
  13982.  
  13983.           ORB 
  13984.  
  13985.  Example Code 
  13986.  
  13987.                     #include  <somd.h>
  13988.  
  13989.                     Environment ev;
  13990.                     Context cxt;
  13991.                     long rc;
  13992.                     ...
  13993.                     rc = _get_default_context(SOMD_ORBObject, &ev, &cxt);
  13994.  
  13995.  
  13996. ΓòÉΓòÉΓòÉ 3.61. object_to_string ΓòÉΓòÉΓòÉ
  13997.  
  13998. object_to_string This method converts an object reference to an external form 
  13999. (string) which can be stored outside the ORB. 
  14000.  
  14001.  Syntax 
  14002.  
  14003.                     string object_to_string (ORB receiver, Environment *env,
  14004.                                  SOMDObject obj)
  14005.  
  14006.  Parameters 
  14007.  
  14008.           receiver (ORB) 
  14009.                     A pointer to the ORB object. 
  14010.  
  14011.           env (Environment *) 
  14012.                     A pointer to the Environment structure for the method 
  14013.                     caller. 
  14014.  
  14015.           obj (SOMDObject) 
  14016.                     A pointer to a SOMDObject object representing the reference 
  14017.                     to be converted. 
  14018.  
  14019.  Returns 
  14020.  
  14021.           rc (string) 
  14022.                     Returns a string representing the external (string) form of 
  14023.                     the referenced object. 
  14024.  
  14025.  Remarks 
  14026.  
  14027.           The object_to_string method converts the object reference to a form 
  14028.           (string) which can be stored externally. 
  14029.  
  14030.           Ownership of allocated memory is transferred to the caller. The 
  14031.           caller should free the result using the ORBfree function, rather than 
  14032.           the SOMFree function. 
  14033.  
  14034.  Original Class 
  14035.  
  14036.           ORB 
  14037.  
  14038.  Related Methods 
  14039.  
  14040.           Methods 
  14041.  
  14042.               string_to_object 
  14043.  
  14044.  Example Code 
  14045.  
  14046.                     #include  <somd.h>
  14047.                     #include  <car.h>
  14048.  
  14049.                     Environment ev;
  14050.                     Car car;
  14051.                     string objrefstr;
  14052.  
  14053.                     SOM_InitEnvironment(&ev);
  14054.                     SOMD_Init(&ev);
  14055.  
  14056.                     /* create a remote Car object */
  14057.                     car = _somdNewObject(SOMD_ObjectMgr, &ev, "Car", "");
  14058.  
  14059.                     /* save the reference to the object */
  14060.                     objrefstr = _object_to_string(SOMD_ORBObject, &ev, car);
  14061.                     FileWrite("/u/joe/mycar", objrefstr);
  14062.  
  14063.  
  14064. ΓòÉΓòÉΓòÉ 3.62. string_to_object ΓòÉΓòÉΓòÉ
  14065.  
  14066. string_to_object This method converts an externalized (string) form of an 
  14067. object reference into an object reference. 
  14068.  
  14069.  Syntax 
  14070.  
  14071.                     SOMDObject string_to_object (ORB receiver, Environment *env,
  14072.                                     string str)
  14073.  
  14074.  Parameters 
  14075.  
  14076.           receiver (ORB) 
  14077.                     A pointer to the ORB object. 
  14078.  
  14079.           env (Environment *) 
  14080.                     A pointer to the Environment structure for the method 
  14081.                     caller. 
  14082.  
  14083.           str (string) 
  14084.                     A pointer to a character string representing the 
  14085.                     externalized form of the object reference. 
  14086.  
  14087.  Returns 
  14088.  
  14089.           rc (SOMDObject) 
  14090.                     Returns a SOMDObject object. 
  14091.  
  14092.  Remarks 
  14093.  
  14094.           The string_to_object method converts the externalized (string) form 
  14095.           of an object reference into an object reference. 
  14096.  
  14097.  Original Class 
  14098.  
  14099.           ORB 
  14100.  
  14101.  Related Methods 
  14102.  
  14103.           Methods 
  14104.  
  14105.               object_to_string 
  14106.  
  14107.  Example Code 
  14108.  
  14109.                     #include  <somd.h>
  14110.                     #include  <car.h>
  14111.  
  14112.                     Environment ev;
  14113.                     Car car;
  14114.                     string objrefstr;
  14115.                     ...
  14116.                     /* restore proxy from its string form */
  14117.                     FileRead("/u/joe/mycar", &objrefstr);
  14118.                     car = _string_to_object(SOMD_ORBObject, &ev, objrefstr);
  14119.  
  14120.  
  14121. ΓòÉΓòÉΓòÉ 3.63. Request ΓòÉΓòÉΓòÉ
  14122.  
  14123. Request 
  14124.  
  14125.  File stem: request 
  14126.  
  14127.  Base 
  14128.  
  14129.           SOMObject 
  14130.  
  14131.  Metaclass 
  14132.  
  14133.           SOMClass 
  14134.  
  14135.  Ancestor Classes 
  14136.  
  14137.                     SOMObject
  14138.  
  14139.  Description 
  14140.  
  14141.           The Request class implements the CORBA Request object described in 
  14142.           section 6.2 on page 108 of CORBA 1.1. The Request object is used by 
  14143.           the dynamic invocation interface to dynamically create and issue a 
  14144.           request to a remote object. Request  objects are created by the 
  14145.           create_request method in SOMDObject. 
  14146.  
  14147.  New methods 
  14148.  
  14149.           The following list shows all the Request methods. 
  14150.  
  14151.               add_arg 
  14152.               destroy* 
  14153.               get_response 
  14154.               invoke 
  14155.               send 
  14156.  
  14157.           (* The destroy method was defined as delete in CORBA 1.1, which 
  14158.           conflicts with the delete operator in C++ ** However, there is a 
  14159.           Request_delete macro defined for CORBA compatibility.) 
  14160.  
  14161.  Overridden methods 
  14162.  
  14163.           The following list shows all the methods overridden by the Request 
  14164.           class. These methods are overridden in order to modify the behavior 
  14165.           defined by an ancestor class. 
  14166.  
  14167.               somInit 
  14168.               somUninit 
  14169.  
  14170.  
  14171. ΓòÉΓòÉΓòÉ 3.64. add_arg ΓòÉΓòÉΓòÉ
  14172.  
  14173. add_arg This method incrementally adds an argument to a Request object. 
  14174.  
  14175.  Syntax 
  14176.  
  14177.                     ORBStatus add_arg (Request receiver, Environment *env,
  14178.                                 Identifier name, TypeCode arg_type, void *value,
  14179.                                 long len, Flags arg_flags)
  14180.  
  14181.  Parameters 
  14182.  
  14183.           receiver (Request) 
  14184.                     A pointer to a Request object. 
  14185.  
  14186.           env (Environment *) 
  14187.                     A pointer to the Environment structure for the method 
  14188.                     caller. 
  14189.  
  14190.           name (Identifier) 
  14191.                     An identifier representing the name of the argument to be 
  14192.                     added. 
  14193.  
  14194.           arg_type (TypeCode) 
  14195.                     The typecode for the argument to be added. 
  14196.  
  14197.           value (void *) 
  14198.                     A pointer to the argument value to be added. 
  14199.  
  14200.           len (long) 
  14201.                     The length of the argument. 
  14202.  
  14203.           arg_flags (Flags) 
  14204.                     A Flags bitmask (unsigned long). The arg_flags parameter 
  14205.                     may take one of the following values to indicate parameter 
  14206.                     direction: 
  14207.  
  14208.                     ARG_IN                     The argument is input only. 
  14209.                     ARG_OUT                    The argument is output only. 
  14210.                     INOUT                      The argument is input/output. 
  14211.                     IN_COPY_VALUE              An internal copy of the argument 
  14212.                                                is to be made and used. 
  14213.                     DEPENDENT_LIST             Indicates that a specified 
  14214.                                                sublist must be freed when the 
  14215.                                                parent list is freed. 
  14216.  
  14217.  Returns 
  14218.  
  14219.           rc (ORBStatus) 
  14220.                     Returns an ORBStatus value representing the return code of 
  14221.                     the operation. 
  14222.  
  14223.  Remarks 
  14224.  
  14225.           The add_arg method incrementally adds an argument to a Request 
  14226.           object. The Request object must have been created using the 
  14227.           create_request method with an empty argument list. 
  14228.  
  14229.  Original Class 
  14230.  
  14231.           Request 
  14232.  
  14233.  Example Code 
  14234.  
  14235.                     #include  <somd.h>
  14236.                     #include  <repostry.h>
  14237.                     #include  <intfacdf.h>
  14238.                     #include  <foo.h>   /* provided by user */
  14239.  
  14240.                     /* assume following method declaration in interface Foo:
  14241.                      *      long methodLong  (in long inLong,inout long inoutLong);
  14242.                      * then the following code builds a request to execute the call:
  14243.                      *      result = methodLong(fooObj, &ev, 100,200);
  14244.                      *using the DII.
  14245.                      */
  14246.  
  14247.                     Environment ev;
  14248.                     OperationDef opdef;
  14249.                     Description desc;
  14250.                     OperationDescription *opdesc;
  14251.                     long rc;
  14252.                     long value1 = 100;
  14253.                     long value2 = 200;
  14254.                     Foo fooObj;
  14255.                     Request reqObj;
  14256.                     NamedValue result;
  14257.  
  14258.                     /* Get the OperationDef from the Interface Repository. */
  14259.                     opdef = _lookup_id(SOM_InterfaceRepository,
  14260.                     &ev, "Foo::methodLong");
  14261.  
  14262.                     /* Get the operation description structure. */
  14263.                     desc = _describe(opdef, &ev);
  14264.                     opdesc = (OperationDescription *) desc.value._value;
  14265.  
  14266.                     /* Fill in the TypeCode field for result. */
  14267.                     result.argument._type = opdesc->result;
  14268.  
  14269.                     /* Create the Request, reqObj */
  14270.                     rc = _create_request(fooObj, &ev, (Context* )NULL, "methodLong",
  14271.                                          (NVList *)NULL, &result, &reqObj, (Flags)0);
  14272.  
  14273.                     /* Add arg1 info onto the request */
  14274.                     _add_arg(reqObj, &ev,
  14275.                               "inLong", TC_long, &value1, sizeof(long), (Flags)0);
  14276.                     /* Add arg2 info onto the request */
  14277.                     _add_arg(reqObj, &ev,
  14278.                               "inoutLong", TC_long, &value2, sizeof(long), (Flags)0);
  14279.  
  14280.  
  14281. ΓòÉΓòÉΓòÉ 3.65. destroy ΓòÉΓòÉΓòÉ
  14282.  
  14283. destroy This method deletes the memory allocated by the ORB for a Request 
  14284. object. 
  14285.  
  14286.  Syntax 
  14287.  
  14288.                     ORBStatus destroy (Request receiver, Environment *env)
  14289.  
  14290.  Parameters 
  14291.  
  14292.           receiver (Request) 
  14293.                     A pointer to a Request object. 
  14294.  
  14295.           env (Environment *) 
  14296.                     A pointer to the Environment structure for the method 
  14297.                     caller. 
  14298.  
  14299.  Returns 
  14300.  
  14301.           rc (ORBStatus) 
  14302.                     Returns an ORBStatus value representing the return code of 
  14303.                     the operation. 
  14304.  
  14305.  Remarks 
  14306.  
  14307.           The destroy method deletes the Request object and all associated 
  14308.           memory. 
  14309.  
  14310.           Note:  This method is called "delete" in the CORBA 1.1 specification. 
  14311.           However, the word "delete" is a reserved operator in C++, so the name 
  14312.           "destroy" was chosen as an alternative. For CORBA compatibility, a 
  14313.           macro defining Request_delete as an alias for destroy has been 
  14314.           included in the C header files. 
  14315.  
  14316.  Original Class 
  14317.  
  14318.           Request 
  14319.  
  14320.  Related Methods 
  14321.  
  14322.           Methods 
  14323.  
  14324.               invoke 
  14325.               send 
  14326.               get_response 
  14327.  
  14328.  Example Code 
  14329.  
  14330.                     #include  <somd.h>
  14331.                     #include  <repostry.h>
  14332.                     #include  <intfacdf.h>
  14333.                     #include  <foo.h>   /* provided by user */
  14334.  
  14335.                     /* assume following method declaration in interface Foo:
  14336.                      *      long methodLong  (in long inLong,inout long inoutLong);
  14337.                      * then the following code  sends a request to execute the call:
  14338.                      *      result = methodLong(fooObj, &ev, 100,200);
  14339.                      * using the DII without waiting for the result. Then, later,
  14340.                      * waits for and then uses the result.
  14341.                      */
  14342.                     Environment ev;
  14343.                     NVList arglist;
  14344.                     long rc;
  14345.                     Foo fooObj;
  14346.                     Request reqObj;
  14347.                     NamedValue result;
  14348.  
  14349.                     /* see the Example code for invoke to see how the request
  14350.                      * is built
  14351.                      */
  14352.  
  14353.                     /* Create the Request, reqObj */
  14354.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  14355.                                          arglist, &result, &reqObj, (Flags)0);
  14356.  
  14357.                     /* Finally, send the request */
  14358.                     rc = _send(reqObj, &ev, (Flags)0);
  14359.  
  14360.                     /* do some work, i.e. don't wait for the result */
  14361.  
  14362.                     /* wait here for the result of the request */
  14363.                     rc = _get_response(reqObj, &ev, (Flags)0);
  14364.  
  14365.                     /* use the result */
  14366.                     if (result->argument._value == 9600) {...}
  14367.  
  14368.                     /* throw away the reqObj */
  14369.                     _destroy(reqObj, &ev);
  14370.  
  14371.  
  14372. ΓòÉΓòÉΓòÉ 3.66. get_response ΓòÉΓòÉΓòÉ
  14373.  
  14374. get_response This method determines whether an asynchronous Request has 
  14375. completed. 
  14376.  
  14377.  Syntax 
  14378.  
  14379.                     ORBStatus get_response (Request receiver, Environment *env,
  14380.                                   Flags response_flags)
  14381.  
  14382.  Parameters 
  14383.  
  14384.           receiver (Request) 
  14385.                     A pointer to a Request object. 
  14386.  
  14387.           env (Environment *) 
  14388.                     A pointer to the Environment structure for the method 
  14389.                     caller. 
  14390.  
  14391.           response_flags (Flags) 
  14392.                     A Flags bitmask (unsigned long) containing control 
  14393.                     information for the get_response method. The response_flags 
  14394.                     argument may have the following value: 
  14395.  
  14396.                     RESP_NO_WAIT             Indicates the caller does not want 
  14397.                                              to wait for a response. 
  14398.  
  14399.  Returns 
  14400.  
  14401.           rc (ORBStatus) 
  14402.                     Returns an ORBStatus value representing the return code of 
  14403.                     the operation. 
  14404.  
  14405.  Remarks 
  14406.  
  14407.           The get_response method determines whether the asynchronous Request 
  14408.           has completed. 
  14409.  
  14410.  Original Class 
  14411.  
  14412.           Request 
  14413.  
  14414.  Related Methods 
  14415.  
  14416.           Methods 
  14417.  
  14418.               invoke 
  14419.               send 
  14420.  
  14421.           Macros 
  14422.  
  14423.               Request_delete 
  14424.  
  14425.  Example Code 
  14426.  
  14427.                     #include  <somd.h>
  14428.                     #include  <repostry.h>
  14429.                     #include  <intfacdf.h>
  14430.                     #include  <foo.h>   /* provided by user */
  14431.  
  14432.                     /* assume following method declaration in interface Foo:
  14433.                      *      long methodLong  (in long inLong,inout long inoutLong);
  14434.                      * then the following code  sends a request to execute the call:
  14435.                      *      result = methodLong(fooObj, &ev, 100,200);
  14436.                      * using the DII without waiting for the result. Then, later,
  14437.                      * waits for and then uses the result.
  14438.                      */
  14439.  
  14440.                     Environment ev;
  14441.                     NVList arglist;
  14442.                     long rc;
  14443.                     Foo fooObj;
  14444.                     Request reqObj;
  14445.                     NamedValue result;
  14446.  
  14447.                     /* see the Example code for invoke to see how the request
  14448.                      * is built
  14449.                      */
  14450.  
  14451.                     /* Create the Request, reqObj */
  14452.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  14453.                                          arglist, &result, &reqObj, (Flags)0);
  14454.  
  14455.                     /* Finally, send the request */
  14456.                     rc = _send(reqObj, &ev, (Flags)0);
  14457.  
  14458.                     /* do some work, i.e. don't wait for the result */
  14459.  
  14460.                     /* wait here for the result of the request */
  14461.                     rc = _get_response(reqObj, &ev, (Flags)0);
  14462.  
  14463.                     /* use the result */
  14464.                     if (result->argument._value == 9600) {...}
  14465.  
  14466.  
  14467. ΓòÉΓòÉΓòÉ 3.67. invoke ΓòÉΓòÉΓòÉ
  14468.  
  14469. invoke This method invokes a Request synchronously, waiting for the response. 
  14470.  
  14471.  Syntax 
  14472.  
  14473.                     ORBStatus invoke (Request receiver, Environment *env,
  14474.                                Flags invoke_flags)
  14475.  
  14476.  Parameters 
  14477.  
  14478.           receiver (Request) 
  14479.                     A pointer to a Request object. 
  14480.  
  14481.           env (Environment *) 
  14482.                     A pointer to the Environment structure for the method 
  14483.                     caller. 
  14484.  
  14485.           invoke_flags (Flags) 
  14486.                     A Flags bitmask (unsigned long) representing control 
  14487.                     information for the invoke method. There are currently no 
  14488.                     flags defined for the invoke method. 
  14489.  
  14490.  Returns 
  14491.  
  14492.           rc (ORBStatus) 
  14493.                     Returns an ORBStatus value representing the return code of 
  14494.                     the operation. 
  14495.  
  14496.  Remarks 
  14497.  
  14498.           The invoke method sends a Request synchronously, waiting for the 
  14499.           response. 
  14500.  
  14501.  Original Class 
  14502.  
  14503.           Request 
  14504.  
  14505.  Related Methods 
  14506.  
  14507.           Methods 
  14508.  
  14509.               send 
  14510.               get_response 
  14511.  
  14512.           Macros 
  14513.  
  14514.               Request_delete 
  14515.  
  14516.  Example Code 
  14517.  
  14518.                     #include  <somd.h>
  14519.                     #include  <repostry.h>
  14520.                     #include  <intfacdf.h>
  14521.                     #include  <foo.h>   /* provided by user */
  14522.  
  14523.                     /* assume following method declaration in interface Foo:
  14524.                      *      long methodLong  (in long inLong,inout long inoutLong);
  14525.                      * then the following code builds and then  invokes
  14526.                      * a request to execute the call:
  14527.                      *      result = methodLong(fooObj, &ev, 100,200);
  14528.                      * using the DII.
  14529.                      */
  14530.  
  14531.                     Environment ev;
  14532.                     OperationDef opdef;
  14533.                     Description desc;
  14534.                     OperationDescription *opdesc;
  14535.                     NVList arglist;
  14536.                     long rc;
  14537.                     long value1 = 100;
  14538.                     long value2 = 200;
  14539.                     Foo fooObj;
  14540.                     Request reqObj;
  14541.                     NamedValue result;
  14542.                     Identifier name;
  14543.                     TypeCode tc;
  14544.                     void *dummy;
  14545.                     long dummylen;
  14546.                     Flags flags;
  14547.  
  14548.                     /* Get the OperationDef from the Interface Repository. */
  14549.                     opdef = _lookup_id(SOM_InterfaceRepository,
  14550.                                        &ev, "Foo::methodLong");
  14551.  
  14552.                     /* Create a NamedValue list for the operation. */
  14553.                     rc= _create_operation_list(SOMD_ORBObject, &ev, opdef, &arglist);
  14554.  
  14555.                     /* Insert arg1 info into arglist */
  14556.                     _get_item(arglist, &ev,
  14557.                               0, &name, &tc, &dummy, &dummylen, &flags);
  14558.                     _set_item(arglist,&ev,0, name, tc, &value1, sizeof(long), flags);
  14559.  
  14560.                     /* Insert arg2 info into arglist */
  14561.                     _get_item(arglist, &ev,
  14562.                               1, &name, &tc, &dummy, &dummylen, &flags);
  14563.                     _set_item(arglist,&ev,1, name, tc, &value2, sizeof(long), flags);
  14564.  
  14565.                     /* Get the operation description structure. */
  14566.                     desc = _describe(opdef, &ev);
  14567.                     opdesc = (OperationDescription *) desc.value._value;
  14568.                     /* Fill in the TypeCode field for result. */
  14569.                     result.argument._type = opdesc->result;
  14570.  
  14571.                     /* Create the Request, reqObj */
  14572.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  14573.                                          arglist, &result, &reqObj, (Flags)0);
  14574.  
  14575.                     /* Finally, invoke the request */
  14576.                     rc = _invoke(reqObj, &ev, (Flags)0);
  14577.  
  14578.                     /* Print results */
  14579.                     printf("result: %d, value2: %d\n",
  14580.                            *(long*)(result.argument._value),
  14581.                            value2);
  14582.  
  14583.  
  14584. ΓòÉΓòÉΓòÉ 3.68. send ΓòÉΓòÉΓòÉ
  14585.  
  14586. send This method invokes a Request asynchronously. 
  14587.  
  14588.  Syntax 
  14589.  
  14590.                     ORBStatus send (Request receiver, Environment *env,
  14591.                               Flags invoke_flags)
  14592.  
  14593.  Parameters 
  14594.  
  14595.           receiver (Request) 
  14596.                     A pointer to a Request object. 
  14597.  
  14598.           env (Environment *) 
  14599.                     A pointer to the Environment structure for the method 
  14600.                     caller. 
  14601.  
  14602.           invoke_flags (Flags) 
  14603.                     A Flags bitmask (unsigned long) containing send method 
  14604.                     control information. The argument invoke_flags can  have 
  14605.                     the following value. 
  14606.  
  14607.                     INV_NO_RESPONSE              Indicates that the invoker 
  14608.                                                  does not intend to wait for a 
  14609.                                                  response, nor does it expect 
  14610.                                                  any of the output arguments 
  14611.                                                  (inout or out) to be updated. 
  14612.  
  14613.  Returns 
  14614.  
  14615.           rc (ORBStatus) 
  14616.                     Returns an ORBStatus value representing the return code 
  14617.                     from the operation. 
  14618.  
  14619.  Remarks 
  14620.  
  14621.           The send method invokes the Request  asynchronously. The response 
  14622.           must eventually be checked by invoking either the get_response method 
  14623.           or the get_next_response function. 
  14624.  
  14625.  Original Class 
  14626.  
  14627.           Request 
  14628.  
  14629.  Related Methods 
  14630.  
  14631.           Methods 
  14632.  
  14633.               invoke 
  14634.               get_response 
  14635.  
  14636.           Macros 
  14637.  
  14638.               Request_delete 
  14639.  
  14640.  Example Code 
  14641.  
  14642.                     #include  <somd.h>
  14643.                     #include  <repostry.h>
  14644.                     #include  <intfacdf.h>
  14645.                     #include  <foo.h>   /* provided by user */
  14646.  
  14647.                     /* assume following method declaration in interface Foo:
  14648.                      *      long methodLong (in long inLong,inout long inoutLong);
  14649.                      * then the following code sends
  14650.                      *      a request to execute the call:
  14651.                      * result = methodLong(fooObj, &ev, 100,200);
  14652.                      * using the DII.
  14653.                      */
  14654.  
  14655.                     Environment ev;
  14656.                     NVList arglist;
  14657.                     long rc;
  14658.                     Foo fooObj;
  14659.                     Request reqObj;
  14660.                     NamedValue result;
  14661.  
  14662.                     /* see the Example code for invoke to see how the request
  14663.                      * is built
  14664.                      */
  14665.  
  14666.                     /* Create the Request, reqObj */
  14667.                     rc = _create_request(fooObj, &ev, (Context *)NULL,"methodLong",
  14668.                                                        arglist, &result, &reqObj, (Flags)0);
  14669.  
  14670.                     /* Finally, send the request */
  14671.                     rc = _send(reqObj, &ev, (Flags)0);
  14672.  
  14673.  
  14674. ΓòÉΓòÉΓòÉ 3.69. SOMDClientProxy ΓòÉΓòÉΓòÉ
  14675.  
  14676. SOMDClientProxy 
  14677.  
  14678.  File stem: somdcprx 
  14679.  
  14680.  Base 
  14681.  
  14682.           SOMDObject 
  14683.  
  14684.  Metaclass 
  14685.  
  14686.           SOMClass 
  14687.  
  14688.  Ancestor Classes 
  14689.  
  14690.                     SOMObject
  14691.                        SOMDObject
  14692.  
  14693.  Description 
  14694.  
  14695.           The SOMDClientProxy class implements DSOM proxy objects in Clients. 
  14696.           SOMDClientProxy overrides the usual somDispatch methods with versions 
  14697.           that build a DSOM Request for remote invocation and dispatch it to 
  14698.           the remote object. It is intended that the implementation of this 
  14699.           "generic" proxy class will be used to derive specific proxy classes 
  14700.           via multiple inheritance. The remote dispatch method is inherited 
  14701.           from this client proxy class, while the desired interface and 
  14702.           language bindings are inherited from the target class (but not the 
  14703.           implementation). 
  14704.  
  14705.                     SOMDClientProxy   Animal
  14706.                         Γöé       Γöé
  14707.                         ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  14708.                             Γöé
  14709.                          Animal_Proxy
  14710.  
  14711.  New methods 
  14712.  
  14713.           The following list shows all the SOMDClientProxy methods. 
  14714.  
  14715.               somdProxyFree* 
  14716.               somdProxyGetClass* 
  14717.               somdProxyGetClassName* 
  14718.               somdTargetFree* 
  14719.               somdTargetGetClass* 
  14720.               somdTargetGetClassName* 
  14721.               somdReleaseResources* 
  14722.  
  14723.           (* This class and its methods were added by DSOM to supplement the 
  14724.           published CORBA'1.1 interfaces.) 
  14725.  
  14726.  Overridden methods 
  14727.  
  14728.           The following list shows all the methods overridden by the 
  14729.           SOMDClientProxy class. These methods are overridden in order to 
  14730.           modify the behavior defined by an ancestor class. 
  14731.  
  14732.               create_request 
  14733.               create_request_args 
  14734.               is_proxy 
  14735.               release 
  14736.               somDispatch 
  14737.               somDispatchA 
  14738.               somDispatchD 
  14739.               somDispatchL 
  14740.               somDispatchV 
  14741.               somFree 
  14742.               somGetClass 
  14743.               somGetClassName 
  14744.               somInit 
  14745.               somUninit 
  14746.  
  14747.  
  14748. ΓòÉΓòÉΓòÉ 3.70. somdProxyFree ΓòÉΓòÉΓòÉ
  14749.  
  14750. somdProxyFree This method executes somFree on the local proxy object. 
  14751.  
  14752.  Syntax 
  14753.  
  14754.                     void somdProxyFree (SOMDClientProxy receiver, Environment *env)
  14755.  
  14756.  Parameters 
  14757.  
  14758.           receiver (SOMDClientProxy) 
  14759.                     A pointer to the SOMDClientProxy object. 
  14760.  
  14761.           env (Environment *) 
  14762.                     A pointer to the Environment structure for the method 
  14763.                     caller. 
  14764.  
  14765.  Returns 
  14766.  
  14767.           rc (void) 
  14768.  
  14769.  Remarks 
  14770.  
  14771.           The somdProxyFree method executes the somFree method call on the 
  14772.           local proxy object. This method has been provided when the 
  14773.           application program wants to be explicit about freeing the proxy 
  14774.           object vs. the target object. 
  14775.  
  14776.  Original Class 
  14777.  
  14778.           SOMDClientProxy 
  14779.  
  14780.  Related Methods 
  14781.  
  14782.           Methods 
  14783.  
  14784.               release 
  14785.               somdReleaseObject 
  14786.  
  14787.  Example Code 
  14788.  
  14789.                     #include  <somd.h>
  14790.                     #include  <car.h>
  14791.  
  14792.                     Environment ev;
  14793.                     Car car;
  14794.                     string somdObjectId;
  14795.                     ...
  14796.                     /* restore proxy from its string form */
  14797.                     FileRead("/u/joe/mycar", &somdObjectId);
  14798.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  14799.                     ...
  14800.                     _somdProxyFree(car, &ev);
  14801.  
  14802.  
  14803. ΓòÉΓòÉΓòÉ 3.71. somdProxyGetClass ΓòÉΓòÉΓòÉ
  14804.  
  14805. somdProxyGetClass This method returns the class object for the local proxy 
  14806. object. 
  14807.  
  14808.  Syntax 
  14809.  
  14810.                     SOMClass somdProxyGetClass (SOMDClientProxy receiver,
  14811.                                      Environment *env)
  14812.  
  14813.  Parameters 
  14814.  
  14815.           receiver (SOMDClientProxy) 
  14816.                     A pointer to the SOMDClientProxy object. 
  14817.  
  14818.           env (Environment *) 
  14819.                     A pointer to the Environment structure for the method 
  14820.                     caller. 
  14821.  
  14822.  Returns 
  14823.  
  14824.           rc (SOMClass) 
  14825.                     Returns a pointer to the class object for the local proxy 
  14826.                     object. 
  14827.  
  14828.  Remarks 
  14829.  
  14830.           The somdProxyGetClass method executes the somGetClass method call on 
  14831.           the local proxy object and returns a pointer to the proxy's class 
  14832.           object. This method has been provided when the application program 
  14833.           wants to be explicit about getting the class object for the proxy 
  14834.           objectvs. the target object. 
  14835.  
  14836.  Original Class 
  14837.  
  14838.           SOMDClientProxy 
  14839.  
  14840.  Example Code 
  14841.  
  14842.                     #include  <somd.h>
  14843.                     #include  <car.h>
  14844.  
  14845.                     Environment ev;
  14846.                     Car car;
  14847.                     SOMClass carProxyClass;
  14848.                     string somdObjectId;
  14849.                     ...
  14850.                     /* restore proxy from its string form */
  14851.                     FileRead("/u/joe/mycar", &somdObjectId);
  14852.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  14853.                     ...
  14854.                     carProxyClass = _somdProxyGetClass(car, &ev);
  14855.  
  14856.  
  14857. ΓòÉΓòÉΓòÉ 3.72. somdProxyGetClassName ΓòÉΓòÉΓòÉ
  14858.  
  14859. somdProxyGetClassName This method returns the class name for the local proxy 
  14860. object. 
  14861.  
  14862.  Syntax 
  14863.  
  14864.                     string somdProxyGetClassName (SOMDClientProxy receiver,
  14865.                                       Environment *env)
  14866.  
  14867.  Parameters 
  14868.  
  14869.           receiver (SOMDClientProxy) 
  14870.                     A pointer to the SOMDClientProxy object for the desired 
  14871.                     remote target object. 
  14872.  
  14873.           env (Environment *) 
  14874.                     A pointer to the Environment structure for the method 
  14875.                     caller. 
  14876.  
  14877.  Returns 
  14878.  
  14879.           rc (string) 
  14880.                     Returns a string containing the class name of the local 
  14881.                     proxy object. 
  14882.  
  14883.  Remarks 
  14884.  
  14885.           The somdProxyGetClassName method executes the somGetClassName method 
  14886.           call on the local proxy object and returns the proxy's class name. 
  14887.           This method has been provided when the application program wants to 
  14888.           be explicit about  getting the class name of the proxy object vs. the 
  14889.           target object. 
  14890.  
  14891.  Original Class 
  14892.  
  14893.           SOMDClientProxy 
  14894.  
  14895.  Example Code 
  14896.  
  14897.                     #include  <somd.h>
  14898.                     #include
  14899.  
  14900.                     Environment ev;
  14901.                     Car car;
  14902.                     string carProxyClassName;
  14903.                     string somdObjectId;
  14904.                     ...
  14905.                     /* restore proxy from its string form */
  14906.                     FileRead("/u/joe/mycar", &somdObjectId);
  14907.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  14908.                     ...
  14909.                     carProxyClassName = _somdProxyGetClassName(car, &ev);
  14910.  
  14911.  
  14912. ΓòÉΓòÉΓòÉ 3.73. somdReleaseResources ΓòÉΓòÉΓòÉ
  14913.  
  14914. somdReleaseResources This method instructs a proxy object to release any memory 
  14915. it is holding as a result of a remote method invocation in which a parameter or 
  14916. result was designated as "object-owned". 
  14917.  
  14918.  Syntax 
  14919.  
  14920.                     void somdReleaseResources (SOMDClientProxy receiver,
  14921.                                     Environment *env)
  14922.  
  14923.  Parameters 
  14924.  
  14925.           receiver (SOMDClientProxy) 
  14926.                     A pointer to the SOMDClientProxy object to release 
  14927.                     resources. 
  14928.  
  14929.           env (Environment *) 
  14930.                     A pointer to the Environment structure for the method call. 
  14931.  
  14932.  Returns 
  14933.  
  14934.           rc (void) 
  14935.  
  14936.  Remarks 
  14937.  
  14938.           The somdReleaseResources method instructs a proxy object to release 
  14939.           any memory it is holding as a result of a remote method invocation in 
  14940.           which a parameter or result was designated as "object-owned". 
  14941.  
  14942.           When a DSOM client program makes a remote method invocation, via a 
  14943.           proxy, and the method being invoked has an object-owned parameter or 
  14944.           return result, the client-side memory associated with the 
  14945.           parameter/result will be owned by the caller's proxy, and the 
  14946.           server-side memory will be owned by the remote object. The memory 
  14947.           owned by the caller's proxy will be freed when the proxy is released 
  14948.           by the client program. (The time at which the server-side memory will 
  14949.           be freed depends on the implementation of the remote object.) 
  14950.  
  14951.           A DSOM client can also instruct a proxy object to free all memory 
  14952.           that it owns on behalf of the client without releasing the proxy 
  14953.           (assuming that the client program is finished using the object-owned 
  14954.           memory), by invoking the somdReleaseResources method on the proxy 
  14955.           object. Calling somdReleaseResources can prevent unused memory from 
  14956.           accumulating in a proxy. 
  14957.  
  14958.           For example, consider a client program repeatedly invoking a remote 
  14959.           method "get_string", which returns a string that is designated (in 
  14960.           SOM IDL) as "object-owned". The proxy on which the method is invoked 
  14961.           will store the memory associated with all of the returned strings, 
  14962.           even if the strings are not unique, until the proxy is released. If 
  14963.           the client program only uses the last result returned from 
  14964.           "get_string", then unused memory accumulates in the proxy. The client 
  14965.           program can prevent this by invoking somdReleaseResources on the 
  14966.           proxy object periodically (for example, each time it finishes using 
  14967.           the result of the last "get_string" call). 
  14968.  
  14969.  Original Class 
  14970.  
  14971.           SOMDClientProxy 
  14972.  
  14973.  Related Methods 
  14974.  
  14975.           Methods 
  14976.  
  14977.               release 
  14978.  
  14979.  Example Code 
  14980.  
  14981.                     string mystring;
  14982.                     ...
  14983.                     /* remote invocation of get_string on proxy x,
  14984.                      * where method get_string has the SOM IDL modifier
  14985.                      * "object_owns_result".
  14986.                      */
  14987.                     mystring = X_get_string(x, ev);
  14988.  
  14989.                     /* ... use mystring ... */
  14990.  
  14991.                     /* when finished using mystring, instruct the
  14992.                      * proxy that it can free it.
  14993.                      */
  14994.                     _somdReleaseResources(x, ev);
  14995.  
  14996.  
  14997. ΓòÉΓòÉΓòÉ 3.74. somdTargetFree ΓòÉΓòÉΓòÉ
  14998.  
  14999. somdTargetFree This method forwards the somFree method call to the remote 
  15000. target object. 
  15001.  
  15002.  Syntax 
  15003.  
  15004.                     void somdTargetFree (SOMDClientProxy receiver, Environment *env)
  15005.  
  15006.  Parameters 
  15007.  
  15008.           receiver (SOMDClientProxy) 
  15009.                     A pointer to the SOMDClientProxy object for the desired 
  15010.                     remote target object. 
  15011.  
  15012.           env (Environment *) 
  15013.                     A pointer to the Environment structure for the method 
  15014.                     caller. 
  15015.  
  15016.  Returns 
  15017.  
  15018.           rc (void) 
  15019.  
  15020.  Remarks 
  15021.  
  15022.           The somdTargetFree method forwards the somFree method call to the 
  15023.           remote target object. This method has been provided when the 
  15024.           application program wants to be explicit about freeing the remote 
  15025.           target object vs. the proxy object. 
  15026.  
  15027.  Original Class 
  15028.  
  15029.           SOMDClientProxy 
  15030.  
  15031.  Related Methods 
  15032.  
  15033.           Methods 
  15034.  
  15035.               release 
  15036.               somdDestroyObject 
  15037.  
  15038.  Example Code 
  15039.  
  15040.                     #include  <somd.h>
  15041.                     #include  <car.h>
  15042.  
  15043.                     Environment ev;
  15044.                     Car car;
  15045.                     string somdObjectId;
  15046.                     ...
  15047.                     /* restore proxy from its string form */
  15048.                     FileRead("/u/joe/mycar", &somdObjectId);
  15049.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  15050.                     ...
  15051.                     _somdTargetFree(car, &ev);
  15052.  
  15053.  
  15054. ΓòÉΓòÉΓòÉ 3.75. somdTargetGetClass ΓòÉΓòÉΓòÉ
  15055.  
  15056. somdTargetGetClass This method returns (a proxy for) the class object for the 
  15057. remote target object. 
  15058.  
  15059.  Syntax 
  15060.  
  15061.                     SOMClass somdTargetGetClass (SOMDClientProxy receiver,
  15062.                                      Environment *env)
  15063.  
  15064.  Parameters 
  15065.  
  15066.           receiver (SOMDClientProxy) 
  15067.                     A pointer to the SOMDClientProxy object for the desired 
  15068.                     remote target object. 
  15069.  
  15070.           env (Environment *) 
  15071.                     A pointer to the Environment structure for the method 
  15072.                     caller. 
  15073.  
  15074.  Returns 
  15075.  
  15076.           rc (SOMClass) 
  15077.                     Returns a pointer to the class object for the remote target 
  15078.                     object. 
  15079.  
  15080.  Remarks 
  15081.  
  15082.           The somdTargetGetClass method forwards the somGetClass method call to 
  15083.           the remote target object and returns a pointer to the class object 
  15084.           for that object. This method has been provided when the application 
  15085.           program wants to be explicit about getting the class object for the 
  15086.           remote target object vs. the local proxy. 
  15087.  
  15088.  Original Class 
  15089.  
  15090.           SOMDClientProxy 
  15091.  
  15092.  Related Methods 
  15093.  
  15094.           Methods 
  15095.  
  15096.               somdProxyGetClass 
  15097.  
  15098.  Example Code 
  15099.  
  15100.                     #include  <somd.h>
  15101.                     #include  <car.h>
  15102.  
  15103.                     Environment ev;
  15104.                     Car car;
  15105.                     SOMClass carClass;
  15106.                     string somdObjectId;
  15107.                     ...
  15108.                     /* restore proxy from its string form */
  15109.                     FileRead("/u/joe/mycar", &somdObjectId);
  15110.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  15111.                     ...
  15112.                     carClass = _somdTargetGetClass(car, &ev);
  15113.  
  15114.  
  15115. ΓòÉΓòÉΓòÉ 3.76. somdTargetGetClassName ΓòÉΓòÉΓòÉ
  15116.  
  15117. somdTargetGetClassName This method returns the class name for the remote target 
  15118. object. 
  15119.  
  15120.  Syntax 
  15121.  
  15122.                     string somdTargetGetClassName (SOMDClientProxy receiver,
  15123.                                       Environment *env)
  15124.  
  15125.  Parameters 
  15126.  
  15127.           receiver (SOMDClientProxy) 
  15128.                     A pointer to the SOMDClientProxy object for the desired 
  15129.                     remote target object. 
  15130.  
  15131.           env (Environment *) 
  15132.                     A pointer to the Environment structure for the method 
  15133.                     caller. 
  15134.  
  15135.  Returns 
  15136.  
  15137.           rc (string) 
  15138.                     Returns a string containing the class name of the remote 
  15139.                     target object. 
  15140.  
  15141.  Remarks 
  15142.  
  15143.           The somdTargetGetClassName method forwards the somGetClassName method 
  15144.           call to the remote target object and returns the class name for that 
  15145.           object. This method has been provided when the application program 
  15146.           wants to be explicit about  getting the class name of the remote 
  15147.           target object vs. the proxy object. 
  15148.  
  15149.  Original Class 
  15150.  
  15151.           SOMDClientProxy 
  15152.  
  15153.  Related Methods 
  15154.  
  15155.           Methods 
  15156.  
  15157.               somdProxyGetClassName 
  15158.  
  15159.  Example Code 
  15160.  
  15161.                     #include  <somd.h>
  15162.                     #include  <car.h>
  15163.  
  15164.                     Environment ev;
  15165.                     Car car;
  15166.                     string carClassName;
  15167.                     string somdObjectId;
  15168.                     ...
  15169.                     /* restore proxy from its string form */
  15170.                     FileRead("/u/joe/mycar", &somdObjectId);
  15171.                     car = _somdGetObjectFromId(SOMD_ObjectMgr, &ev, somdObjectId);
  15172.                     ...
  15173.                     carClassName = _somdTargetGetClassName(car, &ev);
  15174.  
  15175.  
  15176. ΓòÉΓòÉΓòÉ 3.77. SOMDObject ΓòÉΓòÉΓòÉ
  15177.  
  15178. SOMDObject 
  15179.  
  15180.  File stem: somdobj 
  15181.  
  15182.  Base 
  15183.  
  15184.           SOMObject 
  15185.  
  15186.  Metaclass 
  15187.  
  15188.           SOMClass 
  15189.  
  15190.  Ancestor Classes 
  15191.  
  15192.                     SOMObject
  15193.  
  15194.  Description 
  15195.  
  15196.           The SOMDObject class implements the methods that can be applied to 
  15197.           all CORBA object references:  e.g., get_implementation, 
  15198.           get_interface, is_nil, duplicate, and release. In the CORBA 1.1 
  15199.           specification, these methods are described in Chapter 8. 
  15200.  
  15201.           In DSOM, there is also another derivation of this class: 
  15202.           SOMDClientProxy. This subclass inherits the implementation of 
  15203.           SOMDObject, but extends it by overriding somDispatch with a "remote 
  15204.           dispatch" method, and caches the binding to the server process. 
  15205.           Whenever a remote object is accessed, it is represented in the client 
  15206.           process by a SOMDClientProxy object. 
  15207.  
  15208.  New methods 
  15209.  
  15210.           The following list shows all the SOMDObject methods. 
  15211.  
  15212.               create_request 
  15213.               create_request_args* 
  15214.               duplicate 
  15215.               get_implementation 
  15216.               get_interface 
  15217.               is_constant* 
  15218.               is_nil 
  15219.               is_proxy* 
  15220.               is_SOM_ref* 
  15221.               release 
  15222.  
  15223.                (* These methods were added by DSOM to supplement the published 
  15224.                CORBA 1.1 interfaces.) 
  15225.  
  15226.  Overridden methods 
  15227.  
  15228.           The following list shows all the methods overridden by the SOMDObject 
  15229.           class. These methods are overridden in order to modify the behavior 
  15230.           defined by an ancestor class. 
  15231.  
  15232.               somInit 
  15233.               somUninit 
  15234.               somDumpSelfInt 
  15235.  
  15236.  
  15237. ΓòÉΓòÉΓòÉ 3.78. create_request ΓòÉΓòÉΓòÉ
  15238.  
  15239. create_request This method creates a request to execute a particular operation 
  15240. on the referenced object. 
  15241.  
  15242.  Syntax 
  15243.  
  15244.                     ORBStatus create_request (SOMDObject receiver, Environment *env,
  15245.                                    Context ctx, Identifier operation,
  15246.                                    NVList arg_list, NamedValue result,
  15247.                                    Request request, Flags req_flags)
  15248.  
  15249.  Parameters 
  15250.  
  15251.           receiver (SOMDObject) 
  15252.                     A pointer to a SOMDObject object. 
  15253.  
  15254.           env (Environment *) 
  15255.                     A pointer to the Environment structure for the method 
  15256.                     caller. 
  15257.  
  15258.           ctx (Context) 
  15259.                     A pointer to the Context object of the requested operation. 
  15260.  
  15261.           operation (Identifier) 
  15262.                     The name of the operation to be performed on the target 
  15263.                     object, receiver. 
  15264.  
  15265.           arg_list (NVList) 
  15266.                     A pointer to a list of arguments (NVList). If this argument 
  15267.                     is NULL, the argument list can be assembled by repeated 
  15268.                     calls to the add_arg method on the Request object created 
  15269.                     by calling this method. 
  15270.  
  15271.           result (NamedValue) 
  15272.                     A pointer to a NamedValue structure where the result of 
  15273.                     applying operation to receiver should be stored. 
  15274.  
  15275.           request (Request) 
  15276.                     A pointer to storage for the address of the created Request 
  15277.                     object. 
  15278.  
  15279.           req_flags (Flags) 
  15280.                     A Flags bitmask (unsigned long) that may contain the 
  15281.                     following flag value: 
  15282.  
  15283.                     OUT_LIST_MEMORY              Indicates that any out-arg 
  15284.                                                  memory is associated with the 
  15285.                                                  argument list. When the list 
  15286.                                                  structure is freed, any 
  15287.                                                  associated out-arg memory is 
  15288.                                                  also freed. If 
  15289.                                                  OUT_LIST_MEMORY is specified, 
  15290.                                                  an argument list must also 
  15291.                                                  have been specified on the 
  15292.                                                  create_request call. 
  15293.  
  15294.  Returns 
  15295.  
  15296.           rc (ORBStatus) 
  15297.                     Returns an ORBStatus value as the status code for the 
  15298.                     request. 
  15299.  
  15300.  Remarks 
  15301.  
  15302.           The create_request method creates a request to execute a particular 
  15303.           operation on the referenced object. For more information on the 
  15304.           create_request call, see CORBA 1.1 page 109. 
  15305.  
  15306.           In DSOM, this method is meaningful only when invoked on a 
  15307.           SOMDClientProxy  object. If invoked on a SOMDObject which is not a 
  15308.           client proxy, an exception is returned. 
  15309.  
  15310.  Original Class 
  15311.  
  15312.           SOMDObject 
  15313.  
  15314.  Related Methods 
  15315.  
  15316.           Methods 
  15317.  
  15318.               create_request_args 
  15319.               create_list 
  15320.               create_operation_list 
  15321.  
  15322.  Example Code 
  15323.  
  15324.                     #include  <somd.h>
  15325.                     #include  <repostry.h>
  15326.                     #include  <intfacdf.h>
  15327.                     #include  <foo.h>   /* provided by user */
  15328.  
  15329.                     /* assume following method declaration in interface Foo:
  15330.                      *      long methodLong  (in long inLong,inout long inoutLong);
  15331.                      * then the following code builds a request to execute the call:
  15332.                      *      result = methodLong(fooObj, &ev, 100,200);
  15333.                      *using the DII.
  15334.                      */
  15335.                     Environment ev;
  15336.                     OperationDef opdef;
  15337.                     Description desc;
  15338.                     OperationDescription *opdesc;
  15339.                     NVList arglist;
  15340.                     long rc;
  15341.                     long value1 = 100;
  15342.                     long value2 = 200;
  15343.                     Foo fooObj;
  15344.                     Request reqObj;
  15345.                     NamedValue result;
  15346.                     Identifier name;
  15347.                     TypeCode tc;
  15348.                     void *dummy;
  15349.                     long dummylen;
  15350.                     Flags flags;
  15351.  
  15352.                     /* Get the OperationDef from the Interface Repository. */
  15353.                     opdef = _lookup_id(SOM_InterfaceRepository,
  15354.                                        &ev, "Foo::methodLong");
  15355.  
  15356.                     /* Create a NamedValue list for the operation. */
  15357.                     rc= _create_operation_list
  15358.                                      (SOMD_ORBObject, &ev, opdef, &arglist);
  15359.  
  15360.                     /* Insert arg1 info into arglist */
  15361.                     _get_item(arglist, &ev,
  15362.                               0, &name, &tc, &dummy, &dummylen, &flags);
  15363.                     _set_item(arglist,&ev,0, name, tc, &value1, sizeof(long), flags);
  15364.  
  15365.                     /* Insert arg2 info into arglist */
  15366.                     _get_item(arglist, &ev,
  15367.                               1, &name, &tc, &dummy, &dummylen, &flags);
  15368.                     _set_item(arglist,&ev,1, name, tc, &value2, sizeof(long), flags);
  15369.  
  15370.                     /* Get the operation description structure. */
  15371.                     desc = _describe(opdef, &ev);
  15372.                     opdesc = (OperationDescription *) desc.value._value;
  15373.  
  15374.                     /* Fill in the TypeCode field for result. */
  15375.                     result.argument._type = opdesc->result;
  15376.  
  15377.                     /* Finally, create the Request, reqObj */
  15378.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  15379.                                                        arglist, &result, &reqObj, (Flags)0);
  15380.  
  15381.  
  15382. ΓòÉΓòÉΓòÉ 3.79. create_request_args ΓòÉΓòÉΓòÉ
  15383.  
  15384. create_request_args This method creates an argument list appropriate for the 
  15385. specified operation. 
  15386.  
  15387.  Syntax 
  15388.  
  15389.                     ORBStatus create_request_args (SOMDObject receiver,
  15390.                                       Environment *env, Identifier operation,
  15391.                                       NVList arg_list, NamedValue result)
  15392.  
  15393.  Parameters 
  15394.  
  15395.           receiver (SOMDObject) 
  15396.                     A pointer to the SOMDObject  object to create the request. 
  15397.  
  15398.           env (Environment *) 
  15399.                     A pointer to the Environment structure for the method 
  15400.                     caller. 
  15401.  
  15402.           operation (Identifier) 
  15403.                     The Identifier of the operation for which the argument list 
  15404.                     is being created. 
  15405.  
  15406.           arg_list (NVList) 
  15407.                     A pointer to the location where the method will store a 
  15408.                     pointer to the resulting argument list. 
  15409.  
  15410.           result (NamedValue) 
  15411.                     A pointer to the NamedValue  structure which will be used 
  15412.                     to hold the result. The  result's type field is filled in 
  15413.                     with the TypeCode of the expected result. 
  15414.  
  15415.  Returns 
  15416.  
  15417.           rc (ORBStatus) 
  15418.                     Returns an ORBStatus value representing the return code of 
  15419.                     the request. 
  15420.  
  15421.  Remarks 
  15422.  
  15423.           The create_request_args method creates the appropriate arg_list 
  15424.           (NVList) for the specified operation. It is similar in function to 
  15425.           the create_operation_list method. Its value is that it also creates 
  15426.           the result structure whereas create_operation_list does not. 
  15427.  
  15428.           In DSOM, this method is meaningful only when invoked on a 
  15429.           SOMDClientProxy object. If invoked on a SOMDObject which is not a 
  15430.           client proxy, an exception is returned. 
  15431.  
  15432.  Original Class 
  15433.  
  15434.           SOMDObject 
  15435.  
  15436.  Related Methods 
  15437.  
  15438.           Methods 
  15439.  
  15440.               duplicate 
  15441.               release 
  15442.               create_request 
  15443.               create_operation_list 
  15444.  
  15445.  Example Code 
  15446.  
  15447.                     #include  <somd.h>
  15448.                     #include  <repostry.h>
  15449.                     #include  <intfacdf.h>
  15450.                     #include  <foo.h>   /* provided by user */
  15451.  
  15452.                     /* assume following method declaration in interface Foo:
  15453.                      *      long methodLong  (in long inLong,inout long inoutLong);
  15454.                      * then the following code builds a request to execute the call:
  15455.                      *      result = methodLong(fooObj, &ev, 100,200);
  15456.                      * using the DII.
  15457.                      */
  15458.  
  15459.                     Environment ev;
  15460.                     OperationDef opdef;
  15461.                     Description desc;
  15462.                     OperationDescription *opdesc;
  15463.                     NVList arglist;
  15464.                     long rc;
  15465.                     long value1 = 100;
  15466.                     long value2 = 200;
  15467.                     Foo fooObj;
  15468.                     Request reqObj;
  15469.                     NamedValue result;
  15470.                     Identifier name;
  15471.                     TypeCode tc;
  15472.                     void *dummy;
  15473.                     long dummylen;
  15474.                     Flags flags;
  15475.  
  15476.                     /* Get the OperationDef from the Interface Repository. */
  15477.                     opdef = _lookup_id(SOM_InterfaceRepository,
  15478.                                        &ev, "Foo::methodLong");
  15479.                     /* Create a NamedValue list for the operation. */
  15480.                     rc= _create_request_args(fooObj, &ev,
  15481.                                              "methodLong", &arglist, &result);
  15482.  
  15483.                     /* Insert arg1 info into arglist */
  15484.                     _get_item(arglist, &ev,
  15485.                               0, &name, &tc, &dummy, &dummylen, &flags);
  15486.                     _set_item(arglist,&ev,0, name, tc, &value1, sizeof(long), flags);
  15487.  
  15488.                     /* Insert arg2 info into arglist */
  15489.                     _get_item(arglist, &ev,
  15490.                               1, &name, &tc, &dummy, &dummylen, &flags);
  15491.                     _set_item(arglist,&ev,1, name, tc, &value2, sizeof(long), flags);
  15492.  
  15493.                     /* Finally, create the Request, reqObj */
  15494.                     rc = _create_request(fooObj, &ev, (Context *)NULL, "methodLong",
  15495.                                                        arglist, &result, &reqObj, (Flags)0);
  15496.  
  15497.  
  15498. ΓòÉΓòÉΓòÉ 3.80. duplicate ΓòÉΓòÉΓòÉ
  15499.  
  15500. duplicate This method makes a duplicate of an object reference. 
  15501.  
  15502.  Syntax 
  15503.  
  15504.                     SOMDObject duplicate (SOMDObject receiver, Environment *env)
  15505.  
  15506.  Parameters 
  15507.  
  15508.           receiver (SOMDObject) 
  15509.                     A pointer to a SOMDObject object. 
  15510.  
  15511.           env (Environment *) 
  15512.                     A pointer to the Environment structure for the method 
  15513.                     caller. 
  15514.  
  15515.  Returns 
  15516.  
  15517.           rc (SOMDObject) 
  15518.                     Returns a SOMDObject that is a duplicate of the receiver. 
  15519.                     Ownership of the returned object is transferred to the 
  15520.                     caller. 
  15521.  
  15522.  Remarks 
  15523.  
  15524.           The duplicate method makes a duplicate of the object reference. The 
  15525.           release method should be called to free the object. 
  15526.  
  15527.  Original Class 
  15528.  
  15529.           SOMDObject 
  15530.  
  15531.  Related Methods 
  15532.  
  15533.           Methods 
  15534.  
  15535.               release 
  15536.               create 
  15537.               create_constant 
  15538.               create_SOM_ref 
  15539.  
  15540.  Example Code 
  15541.  
  15542.                     #include  <somd.h>
  15543.  
  15544.                     Environment ev;
  15545.                     SOMObject obj;
  15546.                     SOMDObject objref1, objref2;
  15547.                     ...
  15548.                     objref1 = _create_SOM_ref(SOMD_SOMOAObject, &ev, obj);
  15549.                     objref2 = _duplicate(objref1,&ev);
  15550.                     ...
  15551.                     _release(objref2,&ev);
  15552.  
  15553.  
  15554. ΓòÉΓòÉΓòÉ 3.81. get_implementation ΓòÉΓòÉΓòÉ
  15555.  
  15556. get_implementation This method returns the implementation definition for the 
  15557. referenced object. 
  15558.  
  15559.  Syntax 
  15560.  
  15561.                     ImplementationDef get_implementation (SOMDObject receiver,
  15562.                                           Environment *env)
  15563.  
  15564.  Parameters 
  15565.  
  15566.           receiver (SOMDObject) 
  15567.                     A pointer to a SOMDObject object. 
  15568.  
  15569.           env (Environment *) 
  15570.                     A pointer to the Environment structure for the method 
  15571.                     caller. 
  15572.  
  15573.  Returns 
  15574.  
  15575.           rc (ImplementationDef) 
  15576.                     Returns the ImplementationDef object for the receiver. 
  15577.                     Ownership of the returned object is transferred to the 
  15578.                     caller. 
  15579.  
  15580.  Remarks 
  15581.  
  15582.           The get_implementation method returns the implementation definition 
  15583.           object for the referenced object. 
  15584.  
  15585.  Original Class 
  15586.  
  15587.           SOMDObject 
  15588.  
  15589.  Related Methods 
  15590.  
  15591.           Methods 
  15592.  
  15593.               get_interface 
  15594.  
  15595.  Example Code 
  15596.  
  15597.                     #include  <somd.h>
  15598.  
  15599.                     long flags;
  15600.                     Environment ev;
  15601.                     SOMDObject objref;
  15602.                     ImplementationDef impldef;
  15603.                     ...
  15604.                     impldef = _get_implementation(objref,&ev);
  15605.                     flags = __get_impl_flags(impldef,&ev);
  15606.  
  15607.  
  15608. ΓòÉΓòÉΓòÉ 3.82. get_interface ΓòÉΓòÉΓòÉ
  15609.  
  15610. get_interface This method returns the interface definition object for the 
  15611. referenced object. 
  15612.  
  15613.  Syntax 
  15614.  
  15615.                     InterfaceDef get_interface (SOMDObject receiver, Environment *env)
  15616.  
  15617.  Parameters 
  15618.  
  15619.           receiver (SOMDObject) 
  15620.                     A pointer to a SOMDObject object. 
  15621.  
  15622.           env (Environment *) 
  15623.                     A pointer to the Environment structure for the method 
  15624.                     caller. 
  15625.  
  15626.  Returns 
  15627.  
  15628.           rc (InterfaceDef) 
  15629.                     Returns a pointer to the InterfaceDef object associated 
  15630.                     with the reference receiver. Ownership of the  InterfaceDef 
  15631.                     object is passed to the caller. 
  15632.  
  15633.  Remarks 
  15634.  
  15635.           The get_interface method returns the interface definition object for 
  15636.           the referenced object. 
  15637.  
  15638.  Original Class 
  15639.  
  15640.           SOMDObject 
  15641.  
  15642.  Related Methods 
  15643.  
  15644.           Methods 
  15645.  
  15646.               get_implementation 
  15647.  
  15648.  Example Code 
  15649.  
  15650.                     #include  <somd.h>
  15651.                     #include  <repostry.h>
  15652.                     #include  <intfacdf.h>
  15653.  
  15654.                     Environment ev;
  15655.                     SOMDObject objref;
  15656.                     InterfaceDef intf;
  15657.                     ...
  15658.                     intf = _get_interface(objref,&ev);
  15659.  
  15660.  
  15661. ΓòÉΓòÉΓòÉ 3.83. is_constant ΓòÉΓòÉΓòÉ
  15662.  
  15663. is_constant This method tests to see if the object reference is a constant 
  15664. (i.e., its ReferenceData is a constant value associated with the reference). 
  15665.  
  15666.  Syntax 
  15667.  
  15668.                     boolean is_constant (SOMDObject receiver, Environment *env)
  15669.  
  15670.  Parameters 
  15671.  
  15672.           receiver (SOMDObject) 
  15673.                     A pointer to a SOMDObject object. 
  15674.  
  15675.           env (Environment *) 
  15676.                     A pointer to the Environment structure for the method 
  15677.                     caller. 
  15678.  
  15679.  Returns 
  15680.  
  15681.           rc (boolean) 
  15682.                     Returns TRUE if the object reference was generated by 
  15683.                     create_constant, Otherwise, is_constant returns FALSE. 
  15684.  
  15685.  Remarks 
  15686.  
  15687.           The is_constant method tests to see if the object reference was 
  15688.           created using the create_constant method in the SOMOA class. 
  15689.  
  15690.  Related Methods 
  15691.  
  15692.           Methods 
  15693.  
  15694.               create 
  15695.               create_constant 
  15696.               is_nil 
  15697.               is_proxy 
  15698.               is_SOM_ref 
  15699.  
  15700.  Example Code 
  15701.  
  15702.                     #include  <somd.h>
  15703.  
  15704.                     Environment ev;
  15705.                     SOMDObject objref;
  15706.                     ...
  15707.  
  15708.                     /* This code might be part of the code
  15709.                      * that overrides the somdSOMObjFromRef method, i.e.
  15710.                      * in an implementation of a subclass of SOMDServer called
  15711.                      * myServer
  15712.                      */
  15713.  
  15714.                     if (_is_constant(objref, &ev))
  15715.                     id = _get_id(objref, &ev);
  15716.  
  15717.                     ...
  15718.  
  15719.  
  15720. ΓòÉΓòÉΓòÉ 3.84. is_nil ΓòÉΓòÉΓòÉ
  15721.  
  15722. is_nil This method tests to see if the object reference is nil. 
  15723.  
  15724.  Syntax 
  15725.  
  15726.                     boolean is_nil (SOMDObject receiver, Environment *env)
  15727.  
  15728.  Parameters 
  15729.  
  15730.           receiver (SOMDObject) 
  15731.                     A pointer to a SOMDObject object. 
  15732.  
  15733.           env (Environment *) 
  15734.                     A pointer to the Environment structure for the method 
  15735.                     caller. 
  15736.  
  15737.  Returns 
  15738.  
  15739.           rc (boolean) 
  15740.                     Returns TRUE if the object reference is empty. Otherwise, 
  15741.                     is_nil returns FALSE. 
  15742.  
  15743.  Remarks 
  15744.  
  15745.           The is_nil method tests to see if the specified object reference is 
  15746.           nil. 
  15747.  
  15748.  Related Methods 
  15749.  
  15750.           Methods 
  15751.  
  15752.               create 
  15753.               is_constant 
  15754.               is_proxy 
  15755.               is_SOM_ref 
  15756.  
  15757.  Example Code 
  15758.  
  15759.                     #include  <somd.h>
  15760.                     Environment ev;
  15761.                     SOMDObject objref;
  15762.                     SOMObject somobj;
  15763.                     ...
  15764.                     /* This code might be part of the code
  15765.                      * that overrides the somdSOMObjFromRef method, i.e.
  15766.                      * in an implementation of a subclass of SOMDServer called
  15767.                      * myServer
  15768.                      */
  15769.                     if (_is_nil(objref, &ev) &bxv.&bxv.
  15770.                         _somIsA(objref, SOMDClientProxyNewClass(0, 0)) &bxv.&bxv.
  15771.                         _is_SOM_ref(objref, &ev)) {
  15772.                       somobj = myServer_parent_SOMDServer_somdSOMObjFromRef
  15773.                                (somSelf, &ev, objref);
  15774.                     }
  15775.                     else {
  15776.                       /* do the myServer-specific stuff to create/find somobj here */
  15777.                     }
  15778.                     return somobj;
  15779.  
  15780.  
  15781. ΓòÉΓòÉΓòÉ 3.85. is_proxy ΓòÉΓòÉΓòÉ
  15782.  
  15783. is_proxy This method tests to see if the object reference is a proxy. 
  15784.  
  15785.  Syntax 
  15786.  
  15787.                     boolean is_proxy (SOMDObject receiver, Environment *env)
  15788.  
  15789.  Parameters 
  15790.  
  15791.           receiver (SOMDObject) 
  15792.                     A pointer to a SOMDObject object. 
  15793.  
  15794.           env (Environment *) 
  15795.                     A pointer to the Environment structure for the method 
  15796.                     caller. 
  15797.  
  15798.  Returns 
  15799.  
  15800.           rc (boolean) 
  15801.                     Returns TRUE if the object reference is a proxy object. 
  15802.                     Otherwise, is_proxy returns FALSE. 
  15803.  
  15804.  Remarks 
  15805.  
  15806.           The is_proxy method tests to see if the specified object reference is 
  15807.           a proxy object. 
  15808.  
  15809.  Original Class 
  15810.  
  15811.           SOMDObject 
  15812.  
  15813.  Related Methods 
  15814.  
  15815.           Methods 
  15816.  
  15817.               is_nil 
  15818.               is_constant 
  15819.               is_SOM_ref 
  15820.               string_to_object 
  15821.  
  15822.  Example Code 
  15823.  
  15824.                     #include  <somd.h>
  15825.  
  15826.                     SOMDObject objref;
  15827.                     Environment ev;
  15828.                     Context ctx;
  15829.                     NVlist arglist;
  15830.                     NamedValue result;
  15831.                     Request reqObj;
  15832.                     ...
  15833.                     if (_is_proxy(objref, &ev)) {
  15834.                         /* create a remote request for target object */
  15835.                     ...
  15836.                        rc = _create_request(obj, &ev, ctx,
  15837.                                             "testMethod", arglist, &result, &reqObj,
  15838.                                             (Flags)0);
  15839.                     }
  15840.                     ...
  15841.  
  15842.  
  15843. ΓòÉΓòÉΓòÉ 3.86. is_SOM_ref ΓòÉΓòÉΓòÉ
  15844.  
  15845. is_SOM_ref This method tests to see if the object reference is a simple 
  15846. reference to a SOM object. 
  15847.  
  15848.  Syntax 
  15849.  
  15850.                     boolean is_SOM_ref (SOMDObject receiver, Environment *env)
  15851.  
  15852.  Parameters 
  15853.  
  15854.           receiver (SOMDObject) 
  15855.                     A pointer to a SOMDObject object. 
  15856.  
  15857.           env (Environment *) 
  15858.                     A pointer to the Environment structure for the method 
  15859.                     caller. 
  15860.  
  15861.  Returns 
  15862.  
  15863.           rc (boolean) 
  15864.                     Returns TRUE if the object reference is a simple 
  15865.                     (transient) reference to a SOM object. Otherwise, 
  15866.                     is_SOM_ref returns FALSE. 
  15867.  
  15868.  Remarks 
  15869.  
  15870.           The is_SOM_ref method tests to see if the specified object reference 
  15871.           is a simple (transient) reference to a SOM object. 
  15872.  
  15873.  Original Class 
  15874.  
  15875.           SOMDObject 
  15876.  
  15877.  Related Methods 
  15878.  
  15879.           Methods 
  15880.  
  15881.               create_SOM_ref 
  15882.               get_SOM_object 
  15883.               is_proxy 
  15884.               is_nil 
  15885.               is_constant 
  15886.  
  15887.  Example Code 
  15888.  
  15889.                     #include  <somd.h>
  15890.  
  15891.                     SOMDObject objref;
  15892.                     Environment ev;
  15893.                     SOMObject obj;
  15894.                     ...
  15895.                     if (_is_SOM_ref(objref, &ev))
  15896.                         /* we know objref is a simple reference, so we can ... */
  15897.                         obj = _get_SOM_object(SOMD_SOMOAObject, &ev, objref);
  15898.                     ...
  15899.  
  15900.  
  15901. ΓòÉΓòÉΓòÉ 3.87. release ΓòÉΓòÉΓòÉ
  15902.  
  15903. release This method releases the memory associated with the specified object 
  15904. reference. 
  15905.  
  15906.  Syntax 
  15907.  
  15908.                     void release (SOMDObject receiver, Environment *env)
  15909.  
  15910.  Parameters 
  15911.  
  15912.           receiver (SOMDObject) 
  15913.                     A pointer to a SOMDObject object. 
  15914.  
  15915.           env (Environment *) 
  15916.                     A pointer to the Environment structure for the method 
  15917.                     caller. 
  15918.  
  15919.  Returns 
  15920.  
  15921.           rc (void) 
  15922.  
  15923.  Remarks 
  15924.  
  15925.           The release method releases the memory associated with the object 
  15926.           reference. 
  15927.  
  15928.  Original Class 
  15929.  
  15930.           SOMDObject 
  15931.  
  15932.  Related Methods 
  15933.  
  15934.           Methods 
  15935.  
  15936.               duplicate 
  15937.               somdReleaseObject 
  15938.               somdReleaseResources 
  15939.               somdProxyFree 
  15940.               create 
  15941.               create_constant 
  15942.               create_SOM_ref 
  15943.  
  15944.  Example Code 
  15945.  
  15946.                     #include  <somd.h>
  15947.  
  15948.                     SOMDObject objref;
  15949.                     Environment ev;
  15950.                     SOMObject obj;
  15951.                     ...
  15952.                     objref = _create_SOM_ref(SOMD_SOMOAObject, &ev, obj);
  15953.                     ...
  15954.                     _release(objref, &ev);
  15955.  
  15956.  
  15957. ΓòÉΓòÉΓòÉ 3.88. SOMDObjectMgr ΓòÉΓòÉΓòÉ
  15958.  
  15959. SOMDObjectMgr 
  15960.  
  15961.  File stem: somdom 
  15962.  
  15963.  Base 
  15964.  
  15965.           ObjectMgr 
  15966.  
  15967.  Metaclass 
  15968.  
  15969.           SOMMSingleInstance 
  15970.  
  15971.  Ancestor Classes 
  15972.  
  15973.                     ObjectMgr
  15974.                        SOMObject
  15975.  
  15976.  Description 
  15977.  
  15978.           The SOMDObjectMgr class is derived from ObjectMgr class and provides 
  15979.           the DSOM implementations for the ObjectMgr methods. 
  15980.  
  15981.           Attributes 
  15982.  
  15983.           Listed below is an available SOMDObjectMgr attribute, with its 
  15984.           corresponding type in parentheses, followed by a description of its 
  15985.           purpose: 
  15986.  
  15987.           somd21somFree (boolean) 
  15988.               Determines whether or not somFree, when invoked on a proxy 
  15989.               object, will free the proxy object along with the remote object. 
  15990.               The default value is FALSE, indicating that only the remote 
  15991.               object will be freed when somFree is invoked on a proxy object. 
  15992.               Setting this attribute to TRUE as part of client-program 
  15993.               initialization, for example, 
  15994.  
  15995.                             __set_somd21somdFree(SOMD_ObjectMgr, ev, TRUE);
  15996.               has the effect that all subsequent invocations of somFree on 
  15997.               proxy objects will free both the remote object and the proxy. 
  15998.  
  15999.  New methods 
  16000.  
  16001.           The following list shows all the SOMDObjectMgr methods. 
  16002.  
  16003.               somdFindAnyServerByClass* 
  16004.               somdFindServer* 
  16005.               somdFindServersByClass* 
  16006.               somdFindServerByName* 
  16007.  
  16008.           (* This class and its methods were added by DSOM to supplement the 
  16009.           published CORBA 1.1 interfaces.) 
  16010.  
  16011.  Overridden methods 
  16012.  
  16013.           The following list shows all the methods overridden by the 
  16014.           SOMDObjectMgr class. These methods are overridden in order to modify 
  16015.           the behavior defined by an ancestor class. 
  16016.  
  16017.               somdDestroyObject 
  16018.               somdGetIdFromObject 
  16019.               somdGetObjectFromId 
  16020.               somdNewObject 
  16021.               somdReleaseObject 
  16022.               somInit 
  16023.  
  16024.  
  16025. ΓòÉΓòÉΓòÉ 3.89. somdFindAnyServerByClass ΓòÉΓòÉΓòÉ
  16026.  
  16027. somdFindAnyServerByClass This method finds a server capable of creating the 
  16028. specified object. 
  16029.  
  16030.  Syntax 
  16031.  
  16032.                     SOMDServer somdFindAnyServerByClass (SOMDObjectMgr receiver,
  16033.                                           Environment *env,
  16034.                                           Identifier objclass)
  16035.  
  16036.  Parameters 
  16037.  
  16038.           receiver (SOMDObjectMgr) 
  16039.                     A pointer to a SOMDObjectMgr object. 
  16040.  
  16041.           env (Environment *) 
  16042.                     A pointer to the Environment structure for the method 
  16043.                     caller. 
  16044.  
  16045.           objclass (Identifier) 
  16046.                     An Identifier specifying the class of the object the server 
  16047.                     needs to be able to create. 
  16048.  
  16049.  Returns 
  16050.  
  16051.           rc (SOMDServer) 
  16052.                     Returns a pointer to a SOMDServer proxy. If no server can 
  16053.                     be found in the Implementation Repository that implements 
  16054.                     the specified class, NULL is returned. 
  16055.  
  16056.  Remarks 
  16057.  
  16058.           The somdFindAnyServerByClass method finds a server capable of 
  16059.           creating an object of the specified type with the specified 
  16060.           properties. 
  16061.  
  16062.  Original Class 
  16063.  
  16064.           SOMDObjectMgr 
  16065.  
  16066.  Related Methods 
  16067.  
  16068.           Methods 
  16069.  
  16070.               SomdFindServersByClass 
  16071.               somdFindServer 
  16072.               somdFindServerByName 
  16073.  
  16074.  Example Code 
  16075.  
  16076.                     #include  <somd.h>
  16077.                     #include  <stack.h>   /* provided by user */
  16078.  
  16079.                     Stack stk;
  16080.                     Environment ev;
  16081.                     SOMDServer server;
  16082.  
  16083.                     SOM_InitEnvironment(&ev);
  16084.                     SOMD_Init(&ev);
  16085.                     StackNewClass(0,0);
  16086.                     server =
  16087.                       _somdFindAnyServerByClass(SOMD_ObjectMgr, &ev, "Stack");
  16088.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16089.                     ...
  16090.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  16091.  
  16092.  
  16093. ΓòÉΓòÉΓòÉ 3.90. somdFindServer ΓòÉΓòÉΓòÉ
  16094.  
  16095. somdFindServer This method finds a server, given its ImplementationDef ID. 
  16096.  
  16097.  Syntax 
  16098.  
  16099.                     SOMDServer somdFindServer (SOMDObjectMgr receiver,
  16100.                                     Environment *env, ImplId serverid)
  16101.  
  16102.  Parameters 
  16103.  
  16104.           receiver (SOMDObjectMgr) 
  16105.                     A pointer to a SOMDObjectMgr object. 
  16106.  
  16107.           env (Environment *) 
  16108.                     A pointer to the Environment structure for the method 
  16109.                     caller. 
  16110.  
  16111.           serverid (ImplId) 
  16112.                     An ImplId string which identifies the ImplementationDef of 
  16113.                     the desired server. 
  16114.  
  16115.  Returns 
  16116.  
  16117.           rc (SOMDServer) 
  16118.                     Returns a pointer to a SOMDServer proxy. 
  16119.  
  16120.  Remarks 
  16121.  
  16122.           The somdFindServerByName  method finds a server capable of creating 
  16123.           an object of the specified type with the specified properties. 
  16124.  
  16125.  Original Class 
  16126.  
  16127.           SOMDObjectMgr 
  16128.  
  16129.  Related Methods 
  16130.  
  16131.           Methods 
  16132.  
  16133.               somdFindServerByName 
  16134.               somdFindServersByClass 
  16135.               somdAnyFindServerByClass 
  16136.  
  16137.  Example Code 
  16138.  
  16139.                     #include  <somd.h>
  16140.                     #include  <stack.h>   /* provided by user */
  16141.  
  16142.                     Stack stk;
  16143.                     Environment ev;
  16144.                     SOMDServer server;
  16145.                     ImplId implid;
  16146.  
  16147.                     SOM_InitEnvironment(&ev);
  16148.                     SOMD_Init(&ev);
  16149.                     StackNewClass(0,0);
  16150.                     server = _somdFindServer(SOMD_ObjectMgr, &ev, implid);
  16151.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16152.                     ...
  16153.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  16154.  
  16155.  
  16156. ΓòÉΓòÉΓòÉ 3.91. somdFindServerByName ΓòÉΓòÉΓòÉ
  16157.  
  16158. somdFindServerByName This method finds a server given its ImplementationDef 
  16159. name (alias). 
  16160.  
  16161.  Syntax 
  16162.  
  16163.                     SOMDServer somdFindServerByName (SOMDObjectMgr receiver,
  16164.                                         Environment *env,
  16165.                                         string servername)
  16166.  
  16167.  Parameters 
  16168.  
  16169.           receiver (SOMDObjectMgr) 
  16170.                     A pointer to a SOMDObjectMgr object. 
  16171.  
  16172.           env (Environment *) 
  16173.                     A pointer to the Environment structure for the method 
  16174.                     caller. 
  16175.  
  16176.           servername (string) 
  16177.                     A string which specifies the name of the ImplementationDef 
  16178.                     of the desired server. 
  16179.  
  16180.  Returns 
  16181.  
  16182.           rc (SOMDServer) 
  16183.                     Returns a pointer to a SOMDServer proxy. 
  16184.  
  16185.  Remarks 
  16186.  
  16187.           The somdFindServerByName method finds a server with the specified 
  16188.           name. 
  16189.  
  16190.  Original Class 
  16191.  
  16192.           SOMDObjectMgr 
  16193.  
  16194.  Related Methods 
  16195.  
  16196.           Methods 
  16197.  
  16198.               somdFindServer 
  16199.               somdFindServersByClass 
  16200.               somdAnyFindServerByClass 
  16201.  
  16202.  Example Code 
  16203.  
  16204.                     #include  <somd.h>
  16205.                     #include  <stack.h>   /* provided by user */
  16206.  
  16207.                     Stack stk;
  16208.                     Environment ev;
  16209.                     SOMDServer server;
  16210.  
  16211.                     SOM_InitEnvironment(&ev);
  16212.                     SOMD_Init(&ev);
  16213.                     StackNewClass(0,0);
  16214.                     server =
  16215.                            _somdFindServerByName(SOMD_ObjectMgr, &ev, "stackServer");
  16216.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16217.                     ...
  16218.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  16219.  
  16220.  
  16221. ΓòÉΓòÉΓòÉ 3.92. somdFindServersByClass ΓòÉΓòÉΓòÉ
  16222.  
  16223. somdFindServersByClass This method finds all servers capable of creating a 
  16224. particular object. 
  16225.  
  16226.  Syntax 
  16227.  
  16228.                     sequence<SOMDServer> somdFindServersByClass (SOMDObjectMgr receiver,
  16229.                                                Environment *env,
  16230.                                                Identifier objclass)
  16231.  
  16232.  Parameters 
  16233.  
  16234.           receiver (SOMDObjectMgr) 
  16235.                     A pointer to a SOMDObjectMgr object. 
  16236.  
  16237.           env (Environment *) 
  16238.                     A pointer to the Environment structure for the method 
  16239.                     caller. 
  16240.  
  16241.           objclass (Identifier) 
  16242.                     An Identifier representing the type of the object the 
  16243.                     server needs to be able to create. 
  16244.  
  16245.  Returns 
  16246.  
  16247.           rc (sequence<SOMDServer>) 
  16248.                     Returns a sequence of SOMDServer objects capable of 
  16249.                     creating the specified object. 
  16250.  
  16251.  Remarks 
  16252.  
  16253.           The somdFindServersByClass method finds all servers capable of 
  16254.           creating a particular object with the specified properties. 
  16255.  
  16256.  Original Class 
  16257.  
  16258.           SOMDObjectMgr 
  16259.  
  16260.  Related Methods 
  16261.  
  16262.           Methods 
  16263.  
  16264.               somdFindServer 
  16265.               somdFindServerByName 
  16266.               somdFindAnyServerByClass 
  16267.  
  16268.  Example Code 
  16269.  
  16270.                     #include  <somd.h>
  16271.                     #include  <stack.h>   /* provided by user */
  16272.  
  16273.                     Stack stk;
  16274.                     Environment ev;
  16275.                     sequence(SOMDServer) servers;
  16276.                     SOMDServer server;
  16277.                     SOMDServer chooseServer(sequence(SOMDServer) servers);
  16278.  
  16279.                     SOM_InitEnvironment(&ev);
  16280.                     SOMD_Init(&ev);
  16281.                     StackNewClass(0,0);
  16282.                     servers = _somdFindServersByClass(SOMD_ObjectMgr, &ev, "Stack");
  16283.                     server = chooseServer(servers);
  16284.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16285.                     ...
  16286.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  16287.  
  16288.  
  16289. ΓòÉΓòÉΓòÉ 3.93. SOMDServer ΓòÉΓòÉΓòÉ
  16290.  
  16291. SOMDServer 
  16292.  
  16293.  File stem: somdserv 
  16294.  
  16295.  Base 
  16296.  
  16297.           SOMObject 
  16298.  
  16299.  Metaclass 
  16300.  
  16301.           SOMMSingleInstance 
  16302.  
  16303.  Ancestor Classes 
  16304.  
  16305.                     SOMObject
  16306.  
  16307.  Description 
  16308.  
  16309.           The SOMDServer class is a base class that defines and implements 
  16310.           methods for managing objects in a DSOM server process. This includes 
  16311.           methods for the creation and deletion of SOM objects, and for getting 
  16312.           the SOM class object for a specified class. The SOMDServer class also 
  16313.           defines and implements methods for the mapping between object 
  16314.           references (SOMDObjects) and SOM objects, and dispatching methods on 
  16315.           objects. 
  16316.  
  16317.           Application-specific methods for managing application objects can be 
  16318.           introduced in subclasses of SOMDServer. 
  16319.  
  16320.  New methods 
  16321.  
  16322.           The following list shows all the SOMDServer methods. 
  16323.  
  16324.               somdCreateObj* 
  16325.               somdDeleteObj* 
  16326.               somdDispatchMethod* 
  16327.               somdGetClassObj* 
  16328.               somdObjReferencesCached* 
  16329.               somdRefFromSOMObj* 
  16330.               somdSOMObjFromRef* 
  16331.  
  16332.           (* This class and its methods were added by DSOM to supplement the 
  16333.           published CORBA 1.1 interfaces.) 
  16334.  
  16335.  
  16336. ΓòÉΓòÉΓòÉ 3.94. somdCreateObj ΓòÉΓòÉΓòÉ
  16337.  
  16338. somdCreateObj This method creates an object of the specified class. 
  16339.  
  16340.  Syntax 
  16341.  
  16342.                     SOMObject somdCreateObj (SOMDServer receiver, Environment *env,
  16343.                                    Identifier objclass, string hints)
  16344.  
  16345.  Parameters 
  16346.  
  16347.           receiver (SOMDServer) 
  16348.                     A pointer to a SOMDServer object capable of creating a 
  16349.                     instance of the specified class. 
  16350.  
  16351.           env (Environment *) 
  16352.                     A pointer to the Environment structure for the method 
  16353.                     caller. 
  16354.  
  16355.           objclass (Identifier) 
  16356.                     The class of the object for which an instance is to be 
  16357.                     created. 
  16358.  
  16359.           hints (string) 
  16360.                     A string which may optionally be used to specify special 
  16361.                     creation options. 
  16362.  
  16363.  Returns 
  16364.  
  16365.           rc (SOMObject) 
  16366.                     Returns a SOMObject of the class specified by objclass. 
  16367.  
  16368.  Remarks 
  16369.  
  16370.           The somdCreateObj method creates an object of the specified class. 
  16371.  
  16372.  Original Class 
  16373.  
  16374.           SOMDServer 
  16375.  
  16376.  Example Code 
  16377.  
  16378.                     #include  <somd.h>
  16379.                     #include  <stack.h>   /* provided by user */
  16380.  
  16381.                     Stack stk;
  16382.                     Environment ev;
  16383.                     SOMDServer server;
  16384.  
  16385.                     SOM_InitEnvironment(&ev);
  16386.                     SOMD_Init(&ev);
  16387.                     StackNewClass(0,0);
  16388.                     server =
  16389.                       _somdFindServerByName(SOMD_ObjectMgr, &ev,"stackServer");
  16390.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16391.                     ...
  16392.                     _somdDestroyObject(SOMD_ObjectMgr, &ev, stk);
  16393.  
  16394.  
  16395. ΓòÉΓòÉΓòÉ 3.95. somdDeleteObj ΓòÉΓòÉΓòÉ
  16396.  
  16397. somdDeleteObj This method deletes the specified object. 
  16398.  
  16399.  Syntax 
  16400.  
  16401.                     void somdDeleteObj (SOMDServer receiver, Environment *env,
  16402.                                 SOMObject somobj)
  16403.  
  16404.  Parameters 
  16405.  
  16406.           receiver (SOMDServer) 
  16407.                     A pointer to a SOMDServer object. 
  16408.  
  16409.           env (Environment *) 
  16410.                     A pointer to the Environment structure for the method 
  16411.                     caller. 
  16412.  
  16413.           somobj (SOMObject) 
  16414.                     An object "managed" by the server object. 
  16415.  
  16416.  Returns 
  16417.  
  16418.           rc (void) 
  16419.  
  16420.  Remarks 
  16421.  
  16422.           The somdDeleteObj method deletes the specified object. 
  16423.  
  16424.  Original Class 
  16425.  
  16426.           SOMDServer 
  16427.  
  16428.  Example Code 
  16429.  
  16430.                     #include  <somd.h>
  16431.                     #include  <stack.h>   /* provided by user */
  16432.  
  16433.                     Stack stk;
  16434.                     Environment ev;
  16435.                     SOMDServer server;
  16436.  
  16437.                     SOM_InitEnvironment(&ev);
  16438.                     SOMD_Init(&ev);
  16439.                     StackNewClass(0,0);
  16440.                     server =
  16441.                       _somdFindServerByName(SOMD_ObjectMgr, &ev,"stackServer");
  16442.                     stk = _somdCreateObj(server, &ev, "Stack", "");
  16443.                     ...
  16444.                     _somdDeleteObj(server, &ev, stk);
  16445.  
  16446.  
  16447. ΓòÉΓòÉΓòÉ 3.96. somdDispatchMethod ΓòÉΓòÉΓòÉ
  16448.  
  16449. somdDispatchMethod This method dispatches a method on the specified SOM object. 
  16450.  
  16451.  Syntax 
  16452.  
  16453.                     void somdDispatchMethod (SOMDServer receiver, Environment *env,
  16454.                                    SOMObject somobj, somToken retValue,
  16455.                                    somId methodId, va_list ap)
  16456.  
  16457.  Parameters 
  16458.  
  16459.           receiver (SOMDServer) 
  16460.                     A pointer to a SOMDServer object. 
  16461.  
  16462.           env (Environment *) 
  16463.                     A pointer to the Environment structure for the method 
  16464.                     caller. 
  16465.  
  16466.           somobj (SOMObject) 
  16467.                     A pointer to an object "managed" by the server object. 
  16468.  
  16469.           retValue (somToken) 
  16470.                     A pointer to the storage area allocated to hold the method 
  16471.                     result value, if any. 
  16472.  
  16473.           methodId (somId) 
  16474.                     A somId for the name of the method which is to be 
  16475.                     dispatched. 
  16476.  
  16477.           ap (va_list) 
  16478.                     A pointer to a va_list array of arguments to the method 
  16479.                     call. 
  16480.  
  16481.  Returns 
  16482.  
  16483.           rc (void) 
  16484.                     Returns a result, if any, in the storage whose address is 
  16485.                     in retValue. 
  16486.  
  16487.  Remarks 
  16488.  
  16489.           The somdDispatchMethod method is used to intercept method calls on 
  16490.           objects in a server. When a request arrives, the request parameters 
  16491.           are extracted from the message, and the target object is resolved. 
  16492.           Then, the SOMOA dispatches the method call on the target object using 
  16493.           the somdDispatchMethod method. 
  16494.  
  16495.           The default implementation will call somDispatch on the target object 
  16496.           with the parameters as specified. This method can be overridden to 
  16497.           intercept and process the method calls before they are dispatched. 
  16498.  
  16499.  Original Class 
  16500.  
  16501.           SOMDServer 
  16502.  
  16503.  Example Code 
  16504.  
  16505.                     #include  <somd.h>
  16506.  
  16507.                     /* overridden somdDispatchMethod */
  16508.                     void somdDispatchMethod(SOMDServer *somself, Environment *ev,
  16509.                                                        SOMObject *somobj, somToken *retValue,
  16510.                                                        somId methodId, va_list ap)
  16511.                     {
  16512.                        printf("dispatching %s on %x\n", SOM_StringFromId(methodId),
  16513.                              somobj);
  16514.                        SOMObject_somDispatch(somobj, ev, retValue, methodId, ap);
  16515.                     }
  16516.  
  16517.  
  16518. ΓòÉΓòÉΓòÉ 3.97. somdGetClassObj ΓòÉΓòÉΓòÉ
  16519.  
  16520. somdGetClassObj This method creates a class object for the specified class. 
  16521.  
  16522.  Syntax 
  16523.  
  16524.                     SOMClass somdGetClassObj (SOMDServer receiver, Environment *env,
  16525.                                    Identifier objclass)
  16526.  
  16527.  Parameters 
  16528.  
  16529.           receiver (SOMDServer) 
  16530.                     A pointer to a SOMDServer object. 
  16531.  
  16532.           env (Environment *) 
  16533.                     A pointer to the Environment structure for the method 
  16534.                     caller. 
  16535.  
  16536.           objclass (Identifier) 
  16537.                     An identifier specifying the type of the class object to be 
  16538.                     created. 
  16539.  
  16540.  Returns 
  16541.  
  16542.           rc (SOMClass) 
  16543.                     Returns a SOMClass object of the type specified. 
  16544.  
  16545.  Remarks 
  16546.  
  16547.           The somdGetClassObj method creates a class object of the specified 
  16548.           type. 
  16549.  
  16550.  Original Class 
  16551.  
  16552.           SOMDServer 
  16553.  
  16554.  Example Code 
  16555.  
  16556.                     #include  <somd.h>
  16557.                     #include  <stack.h>   /* provided by user */
  16558.  
  16559.                     SOMClass stkclass;
  16560.                     Environment ev;
  16561.                     SOMDServer server;
  16562.  
  16563.                     SOM_InitEnvironment(&ev);
  16564.                     SOMD_Init(&ev);
  16565.                     StackNewClass(0,0);
  16566.                     server =
  16567.                       _somdFindServerByName(SOMD_ObjectMgr, &ev,"stackServer");
  16568.                     stkclass =  _somdGetClassObj(server, &ev, "Stack", "");
  16569.  
  16570.  
  16571. ΓòÉΓòÉΓòÉ 3.98. somdObjReferencesCached ΓòÉΓòÉΓòÉ
  16572.  
  16573. somdObjReferencesCached This method indicates whether a server object retains 
  16574. ownership of the object references it creates via the somdRefFromSOMObj method. 
  16575.  
  16576.  Syntax 
  16577.  
  16578.                     boolean somdObjReferencesCached (SOMDServer receiver,
  16579.                                         Environment *env)
  16580.  
  16581.  Parameters 
  16582.  
  16583.           receiver (SOMDServer) 
  16584.                     A pointer to an object of class SOMDServer. 
  16585.  
  16586.           env (Environment *) 
  16587.                     A pointer to the Environment structure for the calling 
  16588.                     method. 
  16589.  
  16590.  Returns 
  16591.  
  16592.           rc (boolean) 
  16593.  
  16594.                     FALSE          Returns FALSE by default. 
  16595.                     TRUE           Overriding implementations may return TRUE 
  16596.                                    to indicate that a subclass of SOMDServer 
  16597.                                    implements object reference caching. 
  16598.  
  16599.  Remarks 
  16600.  
  16601.           This method indicates whether a server object retains ownership of 
  16602.           the object references it creates via the somdRefFromSOMObj method. 
  16603.           The default implementation returns FALSE, meaning that the server 
  16604.           turns over ownership of the object references it creates to the 
  16605.           caller. Subclasses of SOMDServer that implement object reference 
  16606.           caching should override this method to return TRUE. 
  16607.  
  16608.  Original Class 
  16609.  
  16610.           SOMDServer 
  16611.  
  16612.  Related Methods 
  16613.  
  16614.           Methods 
  16615.  
  16616.               somdRefFromSOMObj 
  16617.  
  16618.  Example Code 
  16619.  
  16620.                     SOMDobject objref;
  16621.                     objref = _somdRefFromSOMObj(serverObj, ev, myobj);
  16622.                     ...
  16623.                     /* code to use objref */
  16624.                     ...
  16625.                     if (!_somdObjReferencesCached(serverObj, ev))
  16626.                         _release(objref, ev);
  16627.  
  16628.  
  16629. ΓòÉΓòÉΓòÉ 3.99. somdRefFromSOMObj ΓòÉΓòÉΓòÉ
  16630.  
  16631. somdRefFromSOMObj This method returns an object reference corresponding to the 
  16632. specified SOM object. 
  16633.  
  16634.  Syntax 
  16635.  
  16636.                     SOMDObject somdRefFromSOMObj (SOMDServer receiver,
  16637.                                        Environment *env,
  16638.                                        SOMObject somobj)
  16639.  
  16640.  Parameters 
  16641.  
  16642.           receiver (SOMDServer) 
  16643.                     A pointer to a SOMDServer  object. 
  16644.  
  16645.           env (Environment *) 
  16646.                     A pointer to the Environment structure for the method 
  16647.                     caller. 
  16648.  
  16649.           somobj (SOMObject) 
  16650.                     A pointer to the SOM object for which a DSOM reference is 
  16651.                     to be created. 
  16652.  
  16653.  Returns 
  16654.  
  16655.           rc (SOMDObject) 
  16656.                     Returns a DSOM reference (that is, a SOMDObject) for the 
  16657.                     SOM object specified. 
  16658.  
  16659.  Remarks 
  16660.  
  16661.           The somdRefFromSOMObj method creates a simple (transient) reference 
  16662.           to a SOM object. This method is called by SOMOA as part of converting 
  16663.           the results of a local method call into a result message for a remote 
  16664.           client. 
  16665.  
  16666.           By default the somdRefFromSOMObj method turns over ownership of the 
  16667.           object reference it creates to the caller. However, if a subclass of 
  16668.           SOMDServer overrides somdRefFromSOMObj to implement object reference 
  16669.           caching, then that subclass should also override the method 
  16670.           somdObjReferencesCached to report that caching by returning TRUE. 
  16671.  
  16672.  Original Class 
  16673.  
  16674.           SOMDServer 
  16675.  
  16676.  Related Methods 
  16677.  
  16678.           Methods 
  16679.  
  16680.               somdObjReferencesCached 
  16681.  
  16682.  Example Code 
  16683.  
  16684.                     #include  <somd.h>
  16685.                     #include  <stack.ih> /* user-generated */
  16686.  
  16687.                     SOMDObject objref;
  16688.                     Environment ev;
  16689.                     SOMObject obj;
  16690.                     ...
  16691.                     /* myServer specific code up here */
  16692.                     ...
  16693.                     /* one might want to make this call as part of the code
  16694.                      * that overrides the somdRefFromSOMObj method, i.e.
  16695.                      * in an implementation of a subclass of SOMDServer called
  16696.                      * myServer
  16697.                      */
  16698.                     objref =
  16699.                      myServer_parent_SOMDServer_somdRefFromSOMObj(somSelf, &ev, obj);
  16700.  
  16701.  
  16702. ΓòÉΓòÉΓòÉ 3.100. somdSOMObjFromRef ΓòÉΓòÉΓòÉ
  16703.  
  16704. somdSOMObjFromRef This method returns the SOM object corresponding to the 
  16705. specified object reference. 
  16706.  
  16707.  Syntax 
  16708.  
  16709.                     SOMObject somdSOMObjFromRef (SOMDServer receiver,
  16710.                                       Environment *env,
  16711.                                       SOMDObject objref)
  16712.  
  16713.  Parameters 
  16714.  
  16715.           receiver (SOMDServer) 
  16716.                     A pointer to a SOMDServer  object. 
  16717.  
  16718.           env (Environment *) 
  16719.                     A pointer to the Environment structure for the method 
  16720.                     caller. 
  16721.  
  16722.           objref (SOMDObject) 
  16723.                     A pointer to the DSOM object reference to the SOM object. 
  16724.  
  16725.  Returns 
  16726.  
  16727.           rc (SOMObject) 
  16728.                     Returns the SOM object associated with the supplied DSOM 
  16729.                     reference. 
  16730.  
  16731.  Remarks 
  16732.  
  16733.           The somdSOMObjFromRef method returns the SOM object associated with 
  16734.           the DSOM object reference, objref. This method is called by SOMOA  as 
  16735.           part of converting a remote request into a local method call on an 
  16736.           object. 
  16737.  
  16738.  Original Class 
  16739.  
  16740.           SOMDServer 
  16741.  
  16742.  Example Code 
  16743.  
  16744.                     #include  <somd.h>
  16745.                     #include  <stack.ih>  /* user-generated */
  16746.  
  16747.                     SOMDObject objref;
  16748.                     Environment ev;
  16749.                     SOMObject obj;
  16750.                     ...
  16751.                     /* myServer specific code up here */
  16752.                     ...
  16753.                     /* one might want to make this call as part of the code
  16754.                      * that overrides the somdRefFromSOMObj method, i.e.
  16755.                      * in an implementation of a subclass of SOMDServer called
  16756.                      * myServer
  16757.                      */
  16758.                     obj =
  16759.                     myServer_parent_SOMDServer_somdSOMObjFromRef(somSelf,&ev,objref);
  16760.  
  16761.  
  16762. ΓòÉΓòÉΓòÉ 3.101. SOMDServerMgr ΓòÉΓòÉΓòÉ
  16763.  
  16764. SOMDServerMgr 
  16765.  
  16766.  File stem: somoa 
  16767.  
  16768.  Base 
  16769.  
  16770.           SOMObject 
  16771.  
  16772.  Metaclass 
  16773.  
  16774.           SOMClass 
  16775.  
  16776.  Ancestor Classes 
  16777.  
  16778.           SOMOBject 
  16779.  
  16780.  Description 
  16781.  
  16782.           The SOMDServerMgr class provides a programmatic interface to manager 
  16783.           server processes. At present, the server processes that can be 
  16784.           managed are limited to those present in the Implementation 
  16785.           Repository. The choice of Implementation Repository is determined by 
  16786.           the environment variable SOMDDIR. 
  16787.  
  16788.  New methods 
  16789.  
  16790.           The following list shows all the SOMDServerMgr methods. 
  16791.  
  16792.               somdDisableServer 
  16793.               somdEnableServer 
  16794.               somdIsServerEnabled 
  16795.               somdListServer 
  16796.               somdRestartServer 
  16797.               somdShutdownServer 
  16798.               somdStartServer 
  16799.  
  16800.  
  16801. ΓòÉΓòÉΓòÉ 3.102. somdDisableServer ΓòÉΓòÉΓòÉ
  16802.  
  16803. somdDisableServer This method disables a server process from starting until it 
  16804. is explicitly enabled again. 
  16805.  
  16806.  Syntax 
  16807.  
  16808.                     ORBStatus somdDisableServer (SOMDServerMgr receiver,
  16809.                                      Environment *env, string server_alias)
  16810.  
  16811.  Parameters 
  16812.  
  16813.           receiver (SOMDServerMgr) 
  16814.                     A pointer to an object of class SOMDServerMgr. 
  16815.  
  16816.           env (Environment *) 
  16817.                     A pointer to the Environment structure for the calling 
  16818.                     method. 
  16819.  
  16820.           server_alias (string) 
  16821.                     The implementation alias of the server to be disabled. 
  16822.  
  16823.  Returns 
  16824.  
  16825.           rc (ORBStatus) 
  16826.                     Returns 0 for success or a DSOM error code for failure. 
  16827.  
  16828.  Remarks 
  16829.  
  16830.           The somdDisableServer method disables the server process associated 
  16831.           with the server alias. Once a server process has been disabled, it 
  16832.           cannot be restarted until it is explicitly enabled again. Initially, 
  16833.           all server processes are enabled by default. Note:  If the server 
  16834.           process to be disabled is currently running, then it is first stopped 
  16835.           before disabling. If the method is unsuccessful in stopping the 
  16836.           server, the disable method fails. 
  16837.  
  16838.  Original Class 
  16839.  
  16840.           SOMDServerMgr 
  16841.  
  16842.  Related Methods 
  16843.  
  16844.           Methods 
  16845.  
  16846.               somdEnableServer 
  16847.  
  16848.  Example Code 
  16849.  
  16850.                     #include <somd.h>
  16851.                     #include <servmgr.h>
  16852.  
  16853.                     SOMDServerMgr servmgr;
  16854.                     string  server_alias = "MyServer";
  16855.                     ORBStatus rc;
  16856.                     Environment e;
  16857.  
  16858.                     SOM_InitEnvironment(&e);
  16859.                     SOMD_Init(&e);
  16860.                     servmgr = SOMDServerMgrNew();
  16861.                     rc = _somdDisableServer(servmgr, &e, server_alias);
  16862.  
  16863.  
  16864. ΓòÉΓòÉΓòÉ 3.103. somdEnableServer ΓòÉΓòÉΓòÉ
  16865.  
  16866. somdEnableServer This method enables a server process so that it can be started 
  16867. when required. Initially, all server processes are enabled by default. 
  16868.  
  16869.  Syntax 
  16870.  
  16871.                     ORBStatus somdEnableServer (SOMDServerMgr receiver,
  16872.                                      Environment *env, string server_alias)
  16873.  
  16874.  Parameters 
  16875.  
  16876.           receiver (SOMDServerMgr) 
  16877.                     A pointer to an object of class SOMDServerMgr. 
  16878.  
  16879.           env (Environment *) 
  16880.                     A pointer to the Environment structure for the calling 
  16881.                     method. 
  16882.  
  16883.           server_alias (string) 
  16884.                     The implementation alias of the server to be enabled. 
  16885.  
  16886.  Returns 
  16887.  
  16888.           rc (ORBStatus) 
  16889.                     Returns 0 for success or a DSOM error code for failure. 
  16890.  
  16891.  Remarks 
  16892.  
  16893.           The somdEnableServer method enables a server process associated with 
  16894.           the server alias. Initially, all server processes are enabled by 
  16895.           default. Server processes can be disabled by using the 
  16896.           somdDisableServer method. 
  16897.  
  16898.  Original Class 
  16899.  
  16900.           SOMDServerMgr 
  16901.  
  16902.  Related Methods 
  16903.  
  16904.           Methods 
  16905.  
  16906.               somdDisableServer 
  16907.  
  16908.  Example Code 
  16909.  
  16910.                     SOMDServerMgr servmgr;
  16911.                     string  server_alias = "MyServer";
  16912.                     ORBStatus rc;
  16913.                     Environment e;
  16914.  
  16915.                     SOM_InitEnvironment(&e);
  16916.                     SOMD_Init(&e);
  16917.                     servmgr = SOMDServerMgrNew();
  16918.  
  16919.                     /* disable the server */
  16920.                     rc = _somdDisableServer(servmgr, &e, server_alias);
  16921.  
  16922.                     /*  do some processing */
  16923.  
  16924.                     /* enable the server */
  16925.                     rc = _somdEnableServer(servmgr, &e, server_alias);
  16926.  
  16927.  
  16928. ΓòÉΓòÉΓòÉ 3.104. somdIsServerEnabled ΓòÉΓòÉΓòÉ
  16929.  
  16930. somdIsServerEnabled This method determines whether a server process is enabled 
  16931. or not. 
  16932.  
  16933.  Syntax 
  16934.  
  16935.                     boolean somdIsServerEnabled (SOMDServerMgr receiver,
  16936.                                      Environment *env,
  16937.                                      ImlementationDef impldef)
  16938.  
  16939.  Parameters 
  16940.  
  16941.           receiver (SOMDServerMgr) 
  16942.                     A pointer to an object of class SOMDServerMgr. 
  16943.  
  16944.           env (Environment *) 
  16945.                     A pointer to the Environment structure for the calling 
  16946.                     method. 
  16947.  
  16948.           impldef (ImlementationDef) 
  16949.                     A pointer to the ImplementationDef object for the server, 
  16950.                     obtained using the find_impldef_by_alias method when it is 
  16951.                     invoked on the global SOMD_ImplRepObject. 
  16952.  
  16953.  Returns 
  16954.  
  16955.           rc (boolean) 
  16956.                     Returns TRUE if the server is enabled; otherwise, FALSE is 
  16957.                     returned. 
  16958.  
  16959.  Remarks 
  16960.  
  16961.           The somdIsServerEnabled method returns a boolean corresponding to the 
  16962.           current state (enabled/disabled) of the server process. 
  16963.  
  16964.  Original Class 
  16965.  
  16966.           SOMDServerMgr 
  16967.  
  16968.  Related Methods 
  16969.  
  16970.           Methods 
  16971.  
  16972.               somDisableServer 
  16973.               somEnableServer 
  16974.  
  16975.  Example Code 
  16976.  
  16977.                     #include <somd.h>
  16978.                     #include <servmgr.h>
  16979.  
  16980.                     SOMDServerMgr servmgr;
  16981.                     ImplementationDef impldef;
  16982.                     string  server_alias = "MyServer";
  16983.                     boolean rc;
  16984.                     Environment e;
  16985.  
  16986.                     SOM_InitEnvironment(&e);
  16987.                     SOMD_Init(&e);
  16988.  
  16989.                     impldef = _find_impldef_by_alias(SOMD_ImplRepObject,
  16990.                                                        &e, server_alias);
  16991.                     servmgr = SOMDServerMgrNew();
  16992.  
  16993.                     /* if server is disabled then enable it*/
  16994.                     if (!_somdIsServerEnabled(servmgr, &e, impldef))
  16995.                         rc = _somdEnableServer(servmgr, &e, server_alias)          ;
  16996.  
  16997.  
  16998. ΓòÉΓòÉΓòÉ 3.105. somdListServer ΓòÉΓòÉΓòÉ
  16999.  
  17000. somdListServer This method queries the state of a server process. 
  17001.  
  17002.  Syntax 
  17003.  
  17004.                     ORBStatus somdListServer (SOMDServerMgr receiver,
  17005.                                    Environment *env, string server_alias)
  17006.  
  17007.  Parameters 
  17008.  
  17009.           receiver (SOMDServerMgr) 
  17010.                     A pointer to an object of class SOMDServerMgr. 
  17011.  
  17012.           env (Environment *) 
  17013.                     A pointer to the Environment structure for the calling 
  17014.                     method. 
  17015.  
  17016.           server_alias (string) 
  17017.                     The implementation alias of the server to be listed. 
  17018.  
  17019.  Returns 
  17020.  
  17021.           rc (ORBStatus) 
  17022.                     Returns 0 if the server process is running; otherwise, a 
  17023.                     DSOM error code is returned. 
  17024.  
  17025.  Remarks 
  17026.  
  17027.           The somdListServer method is invoked to query the status of the 
  17028.           server process associated with the server alias. If the server 
  17029.           process is running, the return code will be 0 indicating success. 
  17030.  
  17031.  Original Class 
  17032.  
  17033.           SOMDServerMgr 
  17034.  
  17035.  Example Code 
  17036.  
  17037.                     #include <somd.h>
  17038.                     #include <servmgr.h>
  17039.  
  17040.                     SOMDServerMgr servmgr;
  17041.                     string  server_alias = "MyServer";
  17042.                     ORBStatus rc;
  17043.                     Environment e;
  17044.  
  17045.                     SOM_InitEnvironment(&e);
  17046.                     SOMD_Init(&e);
  17047.                     servmgr = SOMDServerMgrNew();
  17048.                     rc = _somdListServer(servmgr, &e, server_alias);
  17049.                     if (!rc)                        /* server is running */
  17050.                         rc = _somdShutdownServer(servmgr, &e, server_alias);
  17051.                     else if (rc == SOMDERROR_ServerNotFound)
  17052.                                                 /* server is not running */
  17053.                         rc = _somdStartServer(servmgr, &e, server_alias);
  17054.  
  17055.  
  17056. ΓòÉΓòÉΓòÉ 3.106. somdRestartServer ΓòÉΓòÉΓòÉ
  17057.  
  17058. somdRestartServer This method restarts a server process. 
  17059.  
  17060.  Syntax 
  17061.  
  17062.                     ORBStatus somdRestartServer (SOMDServerMgr receiver,
  17063.                                      Environment *env, string server_alias)
  17064.  
  17065.  Parameters 
  17066.  
  17067.           receiver (SOMDServerMgr) 
  17068.                     A pointer to an object of class SOMDServerMgr. 
  17069.  
  17070.           env (Environment *) 
  17071.                     A pointer to the Environment structure for the calling 
  17072.                     method. 
  17073.  
  17074.           server_alias (string) 
  17075.                     The implementation alias of the server to be restarted. 
  17076.  
  17077.  Returns 
  17078.  
  17079.           rc (ORBStatus) 
  17080.                     Returns 0 for success or a DSOM error code for failure. 
  17081.  
  17082.  Remarks 
  17083.  
  17084.           The somdRestartServer method is invoked to restart a server process. 
  17085.           If the server process currently exists, it will be stopped and 
  17086.           started again. If the server process does not exist, a new server 
  17087.           process will still be started. If the server process cannot be 
  17088.           stopped and/or started for any reason, the method returns a DSOM 
  17089.           error code. 
  17090.  
  17091.           Note: If the designated server is registered in the Implementation 
  17092.           Repository (on the server's machine) as "nonstoppable" (via the 
  17093.           regimpl "-n" option), then the method will return an error. 
  17094.  
  17095.  Original Class 
  17096.  
  17097.           SOMDServerMgr 
  17098.  
  17099.  Example Code 
  17100.  
  17101.                     #include <somd.h>
  17102.                     #include <servmgr.h>
  17103.  
  17104.                     SOMDServerMgr servmgr;
  17105.                     string  server_alias = "MyServer";
  17106.                     ORBStatus rc;
  17107.                     Environment e;
  17108.  
  17109.                     SOM_InitEnvironment(&e);
  17110.                     SOMD_Init(&e);
  17111.                     servmgr = SOMDServerMgrNew();
  17112.                     rc = _somdRestartServer(servmgr, &e, server_alias);
  17113.  
  17114.  
  17115. ΓòÉΓòÉΓòÉ 3.107. somdShutdownServer ΓòÉΓòÉΓòÉ
  17116.  
  17117. somdShutdownServer This method stops a server process. 
  17118.  
  17119.  Syntax 
  17120.  
  17121.                     ORBStatus somdShutdownServer (SOMDServerMgr receiver,
  17122.                                       Environment *env, string server_alias)
  17123.  
  17124.  Parameters 
  17125.  
  17126.           receiver (SOMDServerMgr) 
  17127.                     A pointer to an object of class SOMDServerMgr. 
  17128.  
  17129.           env (Environment *) 
  17130.                     A pointer to the Environment structure for the calling 
  17131.                     method. 
  17132.  
  17133.           server_alias (string) 
  17134.                     The implementation alias of the server to be stopped. 
  17135.  
  17136.  Returns 
  17137.  
  17138.           rc (ORBStatus) 
  17139.                     Returns 0 for success or a DSOM error code for failure. 
  17140.  
  17141.  Remarks 
  17142.  
  17143.           The somdShutdownServer method is invoked to stop a server process. If 
  17144.           the server process corresponding to the server alias exists, it will 
  17145.           be stopped and a code indicating success is returned. 
  17146.  
  17147.           Note: If the designated server is registered in the Implementation 
  17148.           Repository (on the server's machine) as "nonstoppable" (via the 
  17149.           regimpl "-n" option), then this method will return an error. 
  17150.  
  17151.           Note:  On AIX, this method will fail to stop the server process if 
  17152.           the process owner executing this method is not the same as that of 
  17153.           either the server process or root. 
  17154.  
  17155.  Original Class 
  17156.  
  17157.           SOMDServerMgr 
  17158.  
  17159.  Example Code 
  17160.  
  17161.                     #include <somd.h>
  17162.                     #include <servmgr.h>
  17163.  
  17164.                     SOMDServerMgr servmgr;
  17165.                     string  server_alias = "MyServer";
  17166.                     ORBStatus rc;
  17167.                     Environment e;
  17168.  
  17169.                     SOM_InitEnvironment(&e);
  17170.                     SOMD_Init(&e);
  17171.                     servmgr = SOMDServerMgrNew();
  17172.                     rc = _somdShutdownServer(servmgr, &e, server_alias);
  17173.  
  17174.  
  17175. ΓòÉΓòÉΓòÉ 3.108. somdStartServer ΓòÉΓòÉΓòÉ
  17176.  
  17177. somdStartServer This method starts a server process. 
  17178.  
  17179.  Syntax 
  17180.  
  17181.                     ORBStatus somdStartServer (SOMDServerMgr receiver,
  17182.                                     Environment *env, string server_alias)
  17183.  
  17184.  Parameters 
  17185.  
  17186.           receiver (SOMDServerMgr) 
  17187.                     A pointer to an object of class SOMDServerMgr. 
  17188.  
  17189.           env (Environment *) 
  17190.                     A pointer to the Environment structure for the calling 
  17191.                     method. 
  17192.  
  17193.           server_alias (string) 
  17194.                     The implementation alias of the server to be started. 
  17195.  
  17196.  Returns 
  17197.  
  17198.           rc (ORBStatus) 
  17199.                     Returns 0 for success or a DSOM error code for failure. 
  17200.  
  17201.  Remarks 
  17202.  
  17203.           The somdStartServer method is invoked to start a server process. If 
  17204.           the server process does not exist, the server process is started and 
  17205.           the code indicating success is returned. If the server process 
  17206.           already exists, then the return code will still indicate success and 
  17207.           the server process will be undisturbed. 
  17208.  
  17209.  Original Class 
  17210.  
  17211.           SOMDServerMgr 
  17212.  
  17213.  Example Code 
  17214.  
  17215.                     #include <somd.h>
  17216.                     #include <servmgr.h>
  17217.  
  17218.                     SOMDServerMgr servmgr;
  17219.                     string  server_alias = "MyServer";
  17220.                     ORBStatus rc;
  17221.                     Environment e;
  17222.  
  17223.                     SOM_InitEnvironment(&e);
  17224.                     SOMD_Init(&e);
  17225.                     servmgr = SOMDServerMgrNew();
  17226.                     rc = _somdStartServer(servmgr, &e, server_alias);
  17227.  
  17228.  
  17229. ΓòÉΓòÉΓòÉ 3.109. SOMOA ΓòÉΓòÉΓòÉ
  17230.  
  17231. SOMOA 
  17232.  
  17233.  File stem: somoa 
  17234.  
  17235.  Base 
  17236.  
  17237.           BOA 
  17238.  
  17239.  Metaclass 
  17240.  
  17241.           SOMMSingleInstance 
  17242.  
  17243.  Ancestor Classes 
  17244.  
  17245.                     BOA
  17246.                        SOMOBject
  17247.  
  17248.  Description 
  17249.  
  17250.           The SOMOA class is DSOM's basic object adapter. SOMOA is a subclass 
  17251.           of the abstract BOA class, and provides implementations of all the 
  17252.           BOA methods. The SOMOA class also introduces methods for receiving 
  17253.           and dispatching requests on SOM objects. SOMOA provides some 
  17254.           additional methods for creating and managing object references. 
  17255.  
  17256.  New methods 
  17257.  
  17258.           The following list shows all the SOMOA methods. 
  17259.  
  17260.               activate_impl_failed* 
  17261.               change_id* 
  17262.               create_constant* 
  17263.               create_SOM_ref* 
  17264.               execute_next_request* 
  17265.               execute_request_loop* 
  17266.               get_SOM_object* 
  17267.  
  17268.           (* This class and its methods were added by DSOM to supplement the 
  17269.           published CORBA 1.1 interfaces.) 
  17270.  
  17271.  Overridden methods 
  17272.  
  17273.           The following list shows all the methods overridden by the SOMOA 
  17274.           class. These methods are overridden in order to modify the behavior 
  17275.           defined by an ancestor class. 
  17276.  
  17277.               change_implementation 
  17278.               create 
  17279.               deactivate_impl 
  17280.               deactivate_obj 
  17281.               dispose 
  17282.               get_id 
  17283.               get_principal 
  17284.               impl_is_ready 
  17285.               obj_is_ready 
  17286.               set_exception 
  17287.               somInit 
  17288.               somUninit 
  17289.  
  17290.  
  17291. ΓòÉΓòÉΓòÉ 3.110. activate_impl_failed ΓòÉΓòÉΓòÉ
  17292.  
  17293. activate_impl_failed This message sends a message to the DSOM daemon indicating 
  17294. that a server did not activate. 
  17295.  
  17296.  Syntax 
  17297.  
  17298.                     void activate_impl_failed (SOMOA receiver, Environment *env,
  17299.                                   ImplementationDef implDef, long rc)
  17300.  
  17301.  Parameters 
  17302.  
  17303.           receiver (SOMOA) 
  17304.                     A pointer to the SOMOA object that attempted to activate 
  17305.                     the implementation. 
  17306.  
  17307.           env (Environment *) 
  17308.                     A pointer to the Environment structure for the method 
  17309.                     caller. 
  17310.  
  17311.           implDef (ImplementationDef) 
  17312.                     A pointer to the ImplementationDef object representing the 
  17313.                     implementation that failed to activate. 
  17314.  
  17315.           rc (long) 
  17316.                     A return code designating the reason for failure. 
  17317.  
  17318.  Returns 
  17319.  
  17320.           rc (void) 
  17321.  
  17322.  Remarks 
  17323.  
  17324.           The activate_impl_failed  method sends a message to the DSOM daemon 
  17325.           (somdd) indicating that the server did not activate. 
  17326.  
  17327.  Original Class 
  17328.  
  17329.           SOMOA 
  17330.  
  17331.  Example Code 
  17332.  
  17333.                     #include  <somd.h>   /* needed by all servers */
  17334.                     main(int argc, char **argv)
  17335.                     {
  17336.                        Environment ev;
  17337.                        SOM_InitEnvironment(&ev);
  17338.  
  17339.                        /* Initialize the DSOM run-time environment */
  17340.                        SOMD_Init(&ev);
  17341.  
  17342.                        /* Retrieve its ImplementationDef from the Implementation
  17343.                           Repository by passing its implementation ID as a key */
  17344.                        SOMD_ImplDefObject =
  17345.                           _find_impldef(SOMD_ImplRepObject, &ev, argv[1]);
  17346.  
  17347.                        /* create the SOMOA */
  17348.                        SOMD_SOMOAObject = SOMOANew();
  17349.                     ...
  17350.                     /* suppose something went wrong with server initialization */
  17351.                     ...
  17352.                     /* tell the daemon (via SOMOA) that activation failed */
  17353.                     _activate_impl_failed(SOMD_SOMOAObject,
  17354.                                           &ev, SOMD_ImplDefObject, rc);
  17355.  
  17356.  
  17357. ΓòÉΓòÉΓòÉ 3.111. change_id ΓòÉΓòÉΓòÉ
  17358.  
  17359. change_id This method changes the reference data associated with an object. 
  17360.  
  17361.  Syntax 
  17362.  
  17363.                     void change_id (SOMOA receiver, Environment *env,
  17364.                              SOMDObject objref, ReferenceData id)
  17365.  
  17366.  Parameters 
  17367.  
  17368.           receiver (SOMOA) 
  17369.                     A pointer to  the SOMOA object managing the implementation. 
  17370.  
  17371.           env (Environment *) 
  17372.                     A pointer to the Environment structure for the method 
  17373.                     caller. 
  17374.  
  17375.           objref (SOMDObject) 
  17376.                     A pointer to the SOMDObject  which identifies the object. 
  17377.  
  17378.           id (ReferenceData) 
  17379.                     A pointer to the ReferenceData  structure representing the 
  17380.                     object to be created. 
  17381.  
  17382.  Returns 
  17383.  
  17384.           rc (void) 
  17385.  
  17386.  Remarks 
  17387.  
  17388.           The change_id changes the ReferenceData associated with the object 
  17389.           identified by objref. The ReferenceData previously stored in the 
  17390.           SOMOA's reference data table is replaced with the value of id. The 
  17391.           new ID cannot be larger than the maximum size of the original 
  17392.           ReferenceData (usually specified as 1024 bytes). 
  17393.  
  17394.  Example Code 
  17395.  
  17396.                     #include  <somd.h>
  17397.                     #include  <repostry.h>
  17398.                     #include  <intfacdf.h>
  17399.  
  17400.                     SOMDObject objref;
  17401.                     ReferenceData id1, id2;
  17402.                     InterfaceDef intfdef;
  17403.                     ...
  17404.                     objref = _create(SOMD_SOMOAObject, &ev, id1,
  17405.                              intfdef, SOMD_ImplDefObject);
  17406.                     ...
  17407.                     /* change the ReferenceData associated with a SOMDObject */
  17408.                     _change_id(SOMD_SOMOAObject, &ev, objref, id2);
  17409.  
  17410.  
  17411. ΓòÉΓòÉΓòÉ 3.112. create_constant ΓòÉΓòÉΓòÉ
  17412.  
  17413. create_constant This method creates a "constant" object reference. 
  17414.  
  17415.  Syntax 
  17416.  
  17417.                     SOMDObject create_constant (SOMOA receiver, Environment *env,
  17418.                                     ReferenceData id, InterfaceDef intf,
  17419.                                     ImplementationDef impl)
  17420.  
  17421.  Parameters 
  17422.  
  17423.           receiver (SOMOA) 
  17424.                     A pointer to the SOMOA object managing the implementation. 
  17425.  
  17426.           env (Environment *) 
  17427.                     A pointer to the Environment structure for the method 
  17428.                     caller. 
  17429.  
  17430.           id (ReferenceData) 
  17431.                     A pointer to the ReferenceData structure containing 
  17432.                     application-specific information describing the target 
  17433.                     object. 
  17434.  
  17435.           intf (InterfaceDef) 
  17436.                     A pointer to the InterfaceDef object which describes the 
  17437.                     interface of the target object. 
  17438.  
  17439.           impl (ImplementationDef) 
  17440.                     A pointer to the ImplementationDef object which describes 
  17441.                     the application (server) process which implements the 
  17442.                     target object. 
  17443.  
  17444.  Returns 
  17445.  
  17446.           rc (SOMDObject) 
  17447.                     Returns a pointer to a SOMDObject. Ownership of the new 
  17448.                     object reference is transferred to the caller. 
  17449.  
  17450.  Remarks 
  17451.  
  17452.           The create_constant method is a variant of the create method. Like 
  17453.           create, it creates an object reference for an object with the 
  17454.           specified interface and associates the supplied ReferenceData with 
  17455.           the object reference. The ReferenceData can later be retrieved using 
  17456.           the get_id method. Unlike create, this method creates a "contant" 
  17457.           reference whose ID value cannot be changed. (See the change_id method 
  17458.           of SOMOA.) This is because the ID is maintained as a constant part of 
  17459.           the object reference state, versus stored in the reference data table 
  17460.           for the server. 
  17461.  
  17462.           This method would be used whenever the application prefers not to 
  17463.           maintain an object's ReferenceData in the server's reference data 
  17464.           table. 
  17465.  
  17466.  Original Class 
  17467.  
  17468.           SOMOA 
  17469.  
  17470.  Related Methods 
  17471.  
  17472.           Methods 
  17473.  
  17474.               create 
  17475.               create_SOM_ref 
  17476.               dispose 
  17477.               get_id 
  17478.               is_constant 
  17479.  
  17480.  Example Code 
  17481.  
  17482.                     #include  <somd.h>
  17483.                     #include  <repostry.h>
  17484.                     #include  <intfacdf.h>
  17485.  
  17486.                     Environment ev;
  17487.                     ReferenceData id;
  17488.                     InterfaceDef intfdef;
  17489.                     SOMDObject objref;
  17490.                     string fname; /* file name to be saved with reference */
  17491.                     ...
  17492.                     /* create the id for the reference */
  17493.                     id._maximum = id._length = strlen(fname)+1;
  17494.                     id._buffer = (string) SOMMalloc(strlen(fname)+1);
  17495.                     strcpy(id._buffer,fname);
  17496.  
  17497.                     /* get the interface def object for interface Foo*/
  17498.                     intfdef = _lookup_id(SOM_InterfaceRepository, &ev, "Foo");
  17499.  
  17500.                     objref = _create_constant(SOMD_SOMOAObject,
  17501.                                      &ev, id, intfdef, SOMD_ImplDefObject);
  17502.  
  17503.  
  17504. ΓòÉΓòÉΓòÉ 3.113. create_SOM_ref ΓòÉΓòÉΓòÉ
  17505.  
  17506. create_SOM_ref This method creates a simple, transient DSOM reference to a SOM 
  17507. object. 
  17508.  
  17509.  Syntax 
  17510.  
  17511.                     SOMDObject create_SOM_ref (SOMOA receiver, Environment *env,
  17512.                                     SOMObject somobj,
  17513.                                     ImplementationDef impl)
  17514.  
  17515.  Parameters 
  17516.  
  17517.           receiver (SOMOA) 
  17518.                     A pointer to  the SOMOA object managing the implementation. 
  17519.  
  17520.           env (Environment *) 
  17521.                     A pointer to the Environment structure for the method 
  17522.                     caller. 
  17523.  
  17524.           somobj (SOMObject) 
  17525.                     A pointer to the local SOMObject to be referenced. 
  17526.  
  17527.           impl (ImplementationDef) 
  17528.                     A pointer to the ImplementationDef of the calling server 
  17529.                     process. 
  17530.  
  17531.  Returns 
  17532.  
  17533.           rc (SOMDObject) 
  17534.                     Returns a pointer to a SOMDObject. Ownership of the new 
  17535.                     object reference is transferred to the caller. 
  17536.  
  17537.  Remarks 
  17538.  
  17539.           The create_SOM_ref method creates a simple DSOM reference 
  17540.           (SOMDObject) for a local SOM object. The reference is "special" in 
  17541.           that there is no explicit ReferenceData associated with the object. 
  17542.           Also, this object reference is only valid while the target SOM object 
  17543.           exists. 
  17544.  
  17545.           The SOMObject associated with the SOM_ref can be retrieved via the 
  17546.           get_SOM_object method. The is_SOM_ref method of SOMDObject can be 
  17547.           used to tell if the reference was created using create_SOM_ref or 
  17548.           not. 
  17549.  
  17550.  Original Class 
  17551.  
  17552.           SOMOA 
  17553.  
  17554.  Related Methods 
  17555.  
  17556.           Methods 
  17557.  
  17558.               get_SOM_object 
  17559.               is_SOM_ref 
  17560.  
  17561.  Example Code 
  17562.  
  17563.                     #include  <somd.h>
  17564.  
  17565.                     SOMDObject objref;
  17566.                     Environment ev;
  17567.                     SOMObject obj;
  17568.                     ...
  17569.                     /* one might want to make this call as part of the code
  17570.                      * that overrides the somdRefFromSOMObj method, i.e.
  17571.                      * in an implementation of a subclass of SOMDServer.
  17572.                      */
  17573.                     objref = _create_SOM_ref(SOMD_SOMOAObject, &ev,
  17574.                                                                                  obj, SOMD_ImplDefObject);
  17575.  
  17576.  
  17577. ΓòÉΓòÉΓòÉ 3.114. execute_next_request ΓòÉΓòÉΓòÉ
  17578.  
  17579. execute_next_request This method receives a request message, executes the 
  17580. request, and returns to the caller. 
  17581.  
  17582.  Syntax 
  17583.  
  17584.                     ORBStatus execute_next_request (SOMOA receiver, Environment *env,
  17585.                                        Flags waitFlag)
  17586.  
  17587.  Parameters 
  17588.  
  17589.           receiver (SOMOA) 
  17590.                     A pointer to the SOMOA object managing the implementation. 
  17591.  
  17592.           env (Environment *) 
  17593.                     A pointer to the Environment structure for the method 
  17594.                     caller. 
  17595.  
  17596.           waitFlag (Flags) 
  17597.                     A Flags value (unsigned long) indicating whether the method 
  17598.                     should block if there is no message pending (SOMD_WAIT) or 
  17599.                     return with an error (SOMD_NO_WAIT). 
  17600.  
  17601.  Returns 
  17602.  
  17603.           rc (ORBStatus) 
  17604.                     Returns an ORBStatus value representing the return value 
  17605.                     for the operation. SOMDERROR_NoMessages is returned if the 
  17606.                     method is invoked with SOMD_NO_WAIT and no message is 
  17607.                     available. 
  17608.  
  17609.  Remarks 
  17610.  
  17611.           The execute_next_request method receives the next request message, 
  17612.           executes the request, and sends the result to the caller. 
  17613.  
  17614.           If the server's ImplementationDef indicates the server is 
  17615.           multithreaded (the impl_flags has the IMPLDEF_MULTI_THREAD flag set), 
  17616.           each request will be run by SOMOA in a separate thread. 
  17617.  
  17618.  Original Class 
  17619.  
  17620.           SOMOA 
  17621.  
  17622.  Related Methods 
  17623.  
  17624.           Methods 
  17625.  
  17626.               execute_request_loop 
  17627.  
  17628.  Example Code 
  17629.  
  17630.                     #include  <somd.h>
  17631.  
  17632.                     /* server initialization code ... */
  17633.                     SOM_InitEnvironment(&ev);
  17634.  
  17635.                     /* signal DSOM that server is ready */
  17636.                     _impl_is_ready(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  17637.  
  17638.                     while (ev._major == NO_EXCEPTION) {
  17639.                         (void)_execute_next_request(SOMD_SOMOAObject,&ev,SOMD_WAIT );
  17640.                         /* perform appl-specific code between messages here, e.g.,*/
  17641.                         numMessagesProcessed++;
  17642.                     }
  17643.  
  17644.  
  17645. ΓòÉΓòÉΓòÉ 3.115. execute_request_loop ΓòÉΓòÉΓòÉ
  17646.  
  17647. execute_request_loop This method receives a request message, executes the 
  17648. request, and returns the result to the calling client. 
  17649.  
  17650.  Syntax 
  17651.  
  17652.                     ORBStatus execute_request_loop (SOMOA receiver, Environment *env,
  17653.                                        Flags waitFlag)
  17654.  
  17655.  Parameters 
  17656.  
  17657.           receiver (SOMOA) 
  17658.                     A pointer to  the SOMOA object managing the implementation. 
  17659.  
  17660.           env (Environment *) 
  17661.                     A pointer to the Environment structure for the method 
  17662.                     caller. 
  17663.  
  17664.           waitFlag (Flags) 
  17665.                     A Flags bitmask (unsigned long) indicating whether the 
  17666.                     method should block (SOMD_WAIT) or return to the caller 
  17667.                     (SOMD_NO_WAIT) when there is no request message pending. 
  17668.  
  17669.  Returns 
  17670.  
  17671.           rc (ORBStatus) 
  17672.                     May return an OBJ_ADAPTER exception which contains an DSOM 
  17673.                     error code for the operation. SOMDERROR_NoMessages is 
  17674.                     returned as an ORBStatus code if the method is invoked with 
  17675.                     SOMD_NO_WAIT and no message is pending. 
  17676.  
  17677.  Remarks 
  17678.  
  17679.           The execute_request_loop method initiates a loop that waits for a 
  17680.           request message, executes the request, and returns the result to the 
  17681.           client who invoked the request. When called with the SOMD_WAIT flag, 
  17682.           this method loops infinitely (or until an error). When called with 
  17683.           the SOMD_NO_WAIT flag, this method loops as long as it finds a 
  17684.           request message to process. 
  17685.  
  17686.           The SOMD_NO_WAIT flag is useful when writing event-driven 
  17687.           applications where there are event sources other than DSOM requests 
  17688.           (e.g., user input, etc.). In this case, DSOM cannot be given 
  17689.           exclusive control. Instead, a DSOM event handler can be written using 
  17690.           the SOMD_NO_WAIT option, to process all pending requests before 
  17691.           returning control to the event manager. 
  17692.  
  17693.           If the server's ImplementationDef indicates the server is 
  17694.           multithreaded (the impl_flags has the IMPLDEF_MULTI_THREAD flag set), 
  17695.           each request will be run by SOMOA in a separate thread (OS/2 only). 
  17696.  
  17697.           See Chapter 9 of the SOM Programming Guide for a description of the 
  17698.           Event Manager (EMan) framework, for writing event-driven 
  17699.           applications. 
  17700.  
  17701.  Original Class 
  17702.  
  17703.           SOMOA 
  17704.  
  17705.  Related Methods 
  17706.  
  17707.           Functions 
  17708.  
  17709.               SOMD_RegisterCallback 
  17710.  
  17711.           Methods 
  17712.  
  17713.               execute_next_request 
  17714.  
  17715.  Example Code 
  17716.  
  17717.                     #include  <somd.h>
  17718.  
  17719.                     /* server initialization code ... */
  17720.                     ...
  17721.                     _impl_is_ready(SOMD_SOMOAObject, &ev, SOMD_ImplDefObject);
  17722.  
  17723.                     /* turn control over to SOMOA */
  17724.                     (void) _execute_request_loop(SOMD_SOMOAObject, &ev,SOMD_WAIT);
  17725.  
  17726.  
  17727. ΓòÉΓòÉΓòÉ 3.116. get_SOM_object ΓòÉΓòÉΓòÉ
  17728.  
  17729. get_SOM_object Get the SOM object associated with a simple DSOM reference. 
  17730.  
  17731.  Syntax 
  17732.  
  17733.                     SOMObject get_SOM_object (SOMOA receiver, Environment *env,
  17734.                                    SOMDObject somref)
  17735.  
  17736.  Parameters 
  17737.  
  17738.           receiver (SOMOA) 
  17739.                     A pointer to  the SOMOA object managing the implementation. 
  17740.  
  17741.           env (Environment *) 
  17742.                     A pointer to the Environment structure for the method 
  17743.                     caller. 
  17744.  
  17745.           somref (SOMDObject) 
  17746.                     A pointer to a SOMDObject created by the create_SOM_ref 
  17747.                     method. 
  17748.  
  17749.  Returns 
  17750.  
  17751.           rc (SOMObject) 
  17752.                     Returns the SOM object associated with the reference. 
  17753.  
  17754.  Remarks 
  17755.  
  17756.           The get_SOM_object method returns the SOM object associated with a 
  17757.           reference created by the create_SOM_ref method. 
  17758.  
  17759.  Original Class 
  17760.  
  17761.           SOMOA 
  17762.  
  17763.  Related Methods 
  17764.  
  17765.           Methods 
  17766.  
  17767.               create_SOM_ref 
  17768.               is_SOM_ref 
  17769.  
  17770.  Example Code 
  17771.  
  17772.                     #include  <somd.h>
  17773.  
  17774.                     SOMDObject objref;
  17775.                     Environment ev;
  17776.                     SOMObject obj;
  17777.                     ...
  17778.                     if (_is_SOM_ref(objref, &ev))
  17779.                         /* we know objref is a simple reference, so we can ... */
  17780.                         obj = _get_SOM_object(SOMD_SOMOAObject, &ev,objref);
  17781.                     ...
  17782.  
  17783.  
  17784. ΓòÉΓòÉΓòÉ 4. Interface Repository Framework Reference ΓòÉΓòÉΓòÉ
  17785.  
  17786.  
  17787. Interface Repository Framework Class Organization
  17788.  
  17789.  
  17790. ΓòÉΓòÉΓòÉ 4.1. AttributeDef ΓòÉΓòÉΓòÉ
  17791.  
  17792. AttributeDef 
  17793.  
  17794.  File stem: attribdf 
  17795.  
  17796.  Base 
  17797.  
  17798.           Contained 
  17799.  
  17800.  Metaclass 
  17801.  
  17802.           SOMClass 
  17803.  
  17804.  Ancestor Classes 
  17805.  
  17806.                     Contained
  17807.                        SOMOBject
  17808.  
  17809.  Description 
  17810.  
  17811.           Types 
  17812.  
  17813.                     enum  AttributeMode   {NORMAL, READONLY};
  17814.  
  17815.                     struct  AttributeDescription   {
  17816.                         Identifier      name;
  17817.                         RepositoryId    id;
  17818.                         RepositoryId    defined_in;
  17819.                         TypeCode        type;
  17820.                         AttributeMode   mode;
  17821.                     };
  17822.  
  17823.           The describe method, inherited from Contained, returns an 
  17824.           AttributeDescription structure in the "value" member of the 
  17825.           Description structure (defined in the Contained class). 
  17826.  
  17827.           Attributes 
  17828.  
  17829.           Listed below is each available attribute, with its corresponding type 
  17830.           in parentheses, followed by a description of its purpose: 
  17831.  
  17832.           type (TypeCode) 
  17833.               The TypeCode that represents the type of the attribute. The 
  17834.               TypeCode returned by the "_get_" form of the type attribute is 
  17835.               contained in the receiving AttributeDef object, which retains 
  17836.               ownership. Hence, the returned TypeCode should not be freed. To 
  17837.               obtain a separate copy, use the TypeCode_copy operation. The 
  17838.               "_set_" form of the attribute makes a private copy of the 
  17839.               TypeCode you supply, to keep in the receiving object. You retain 
  17840.               ownership of the passed TypeCode. 
  17841.  
  17842.           mode (AttributeMode) 
  17843.               The AttributeMode of the attribute (NORMAL or READONLY). 
  17844.  
  17845.  New methods 
  17846.  
  17847.           There are currently no new methods defined for the AttributeDef 
  17848.           class. 
  17849.  
  17850.  Overridden methods 
  17851.  
  17852.           The following list shows all the methods overridden by the 
  17853.           AttributeDef class. These methods are overridden in order to modify 
  17854.           the behavior defined by an ancestor class. 
  17855.  
  17856.               somInit 
  17857.               somUninit 
  17858.               somDumpSelf 
  17859.               somDumpSelfInit 
  17860.               describe 
  17861.  
  17862.  
  17863. ΓòÉΓòÉΓòÉ 4.2. ConstantDef ΓòÉΓòÉΓòÉ
  17864.  
  17865. ConstantDef 
  17866.  
  17867.  File stem: constdef 
  17868.  
  17869.  Base 
  17870.  
  17871.           Contained 
  17872.  
  17873.  Metaclass 
  17874.  
  17875.           SOMClass 
  17876.  
  17877.  Ancestor Classes 
  17878.  
  17879.                     Contained
  17880.                        SOMObject
  17881.  
  17882.  Description 
  17883.  
  17884.           Types 
  17885.  
  17886.                     struct ConstantDescription   {
  17887.                     Identifier    name;
  17888.                     RepositoryId  id;
  17889.                     RepositoryId  defined_in;
  17890.                     TypeCode      type;
  17891.                     any value;
  17892.                     };
  17893.  
  17894.           The describe method, inherited from Contained, returns a 
  17895.           ConstantDescription structure in the "value" member of the 
  17896.           Description structure (defined in the Contained class). 
  17897.  
  17898.           Attributes 
  17899.  
  17900.           Listed below is each available attribute, with its corresponding type 
  17901.           in parentheses, followed by a description of its purpose: 
  17902.  
  17903.           type (TypeCode) 
  17904.               The TypeCode that represents the type of constant. The TypeCode 
  17905.               returned by the "_get_" form of the type attribute is contained 
  17906.               in the receiving ConstantDef object, which retains ownership. 
  17907.               Hence, the returned TypeCode should not be freed. To obtain a 
  17908.               separate copy, use the TypeCode_copy operation. The "_set_" form 
  17909.               of the attribute makes a private copy of the TypeCode you supply, 
  17910.               to keep in the receiving object. You retain ownership of the 
  17911.               passed TypeCode. 
  17912.  
  17913.           value (any) 
  17914.               The value of the constant. 
  17915.  
  17916.  New methods 
  17917.  
  17918.           There are currently no new methods defined for the ConstantDef class. 
  17919.  
  17920.  Overridden methods 
  17921.  
  17922.           The following list shows all the methods overridden by the 
  17923.           ConstantDef class. These methods are overridden in order to modify 
  17924.           the behavior defined by an ancestor class. 
  17925.  
  17926.               somInit 
  17927.               somUninit 
  17928.               somDumpSelf 
  17929.               somDumpSelfInt 
  17930.               describe 
  17931.  
  17932.  
  17933. ΓòÉΓòÉΓòÉ 4.3. Contained ΓòÉΓòÉΓòÉ
  17934.  
  17935. Contained 
  17936.  
  17937.  File stem: containd 
  17938.  
  17939.  Base 
  17940.  
  17941.           SOMObject 
  17942.  
  17943.  Metaclass 
  17944.  
  17945.           SOMClass 
  17946.  
  17947.  Ancestor Classes 
  17948.  
  17949.                     SOMObject
  17950.  
  17951.  Description 
  17952.  
  17953.           Types 
  17954.  
  17955.                          typedef  string       RepositoryId;
  17956.                           struct       Description   {
  17957.                           Identifier   name;
  17958.                           any          value;
  17959.                                 };
  17960.  
  17961.           Attributes 
  17962.  
  17963.           All attributes of the Contained class provide access to information 
  17964.           kept within the receiving object. The "_get_" form of the attribute 
  17965.           returns a memory reference that is only valid as long as the 
  17966.           receiving object has not been freed (using _somFree). The "_set_" 
  17967.           form of the attribute makes a (deep) copy of your data and places it 
  17968.           in the receiving object. You retain ownership of all memory 
  17969.           references passed using the "_set_" attributes. 
  17970.  
  17971.           Listed below is each available attribute, with its corresponding type 
  17972.           in parentheses, followed by a description of its purpose: 
  17973.  
  17974.           name  (Identifier) 
  17975.               A simple name that identifies the Contained object within its 
  17976.               containment hierarchy. The name may not be unique outside of the 
  17977.               containment hierarchy; thus it may require qualification by 
  17978.               ModuleDef name and/or InterfaceDef name. 
  17979.  
  17980.           id  (RepositoryId) 
  17981.               The value of the "id" field of the Contained object. This is a 
  17982.               string that uniquely identifies any object in the IR; thus it 
  17983.               needs no qualification. Note that RepositoryIds have no 
  17984.               relationship to the SOM type somId. 
  17985.  
  17986.           defined_in  (RepositoryId) 
  17987.               The value of the "defined_in" field of the Contained object. This 
  17988.               ID uniquely identifies the container where the Contained object 
  17989.               is defined. Objects without global scope that do not appear 
  17990.               within any other object are, by default, placed in the Repository 
  17991.               object. 
  17992.  
  17993.           somModifiers  (sequence <somModifier>) 
  17994.               The somModifiers attribute is a sequence containing all modifiers 
  17995.               associated with the object in the "implementation" section of the 
  17996.               SOM IDL file where the receiving object is defined. 
  17997.  
  17998.               Note:  This attribute is a SOM-unique extension of the Interface 
  17999.               Repository; it is not stipulated by the CORBA specification. 
  18000.  
  18001.  New methods 
  18002.  
  18003.           The following list shows all the Contained methods. 
  18004.  
  18005.               within 
  18006.               describe 
  18007.  
  18008.  Overridden methods 
  18009.  
  18010.           The following list shows all the methods overridden by the Contained 
  18011.           class. These methods are overridden in order to modify the behavior 
  18012.           defined by an ancestor class. 
  18013.  
  18014.               somFree 
  18015.               somInit 
  18016.               somUninit 
  18017.               somDumpSelf 
  18018.               somDumpSelfInt 
  18019.  
  18020.  
  18021. ΓòÉΓòÉΓòÉ 4.4. describe ΓòÉΓòÉΓòÉ
  18022.  
  18023. describe This method returns a structure containing information defined in the 
  18024. IDL specification that corresponds to a specified Contained object in the 
  18025. Interface Repository. 
  18026.  
  18027.  Syntax 
  18028.  
  18029.                     Description describe (Contained receiver, Environment *env)
  18030.  
  18031.  Parameters 
  18032.  
  18033.           receiver (Contained) 
  18034.                     A pointer to the Contained object in the Interface 
  18035.                     Repository for which a Description is needed. 
  18036.  
  18037.           env (Environment *) 
  18038.                     A pointer to the Environment structure for the caller. 
  18039.  
  18040.  Returns 
  18041.  
  18042.           rc (Description) 
  18043.                     Returns a structure of type Description containing 
  18044.                     information defined in the IDL specification of the 
  18045.                     receiving object. 
  18046.  
  18047.  Remarks 
  18048.  
  18049.           The describe method returns a structure containing information 
  18050.           defined in the IDL specification of a Contained object. The specified 
  18051.           object represents a component of an IDL interface (class) definition 
  18052.           maintained within the Interface Repository. 
  18053.  
  18054.           When finished using the information in the returned Description 
  18055.           structure, the client code must release the storage allocated for it. 
  18056.           To free the associated storage, use a call similar to this: 
  18057.  
  18058.                     if (desc.value._value)
  18059.                          SOMFree (desc.value._value);
  18060.  
  18061.                     CAUTION:
  18062.           The describe method returns pointers to elements within objects (for 
  18063.           example, name). Thus, the somFree method should  not be used to 
  18064.           release any of these objects while the describe information is still 
  18065.           needed. 
  18066.  
  18067.           The "name" field of the Description is the name of the type of 
  18068.           description. The "name" values are from the following set: 
  18069.  
  18070.                     {"ModuleDescription", "InterfaceDescription", "AttributeDescription",
  18071.                     "OperationDescription", "ParameterDescription", "TypeDescription",
  18072.                     "ConstantDescription", "ExceptionDescription"}
  18073.  
  18074.           The "value" field is a structure of type any whose "_value" field is 
  18075.           a pointer to a structure of the type named by the "name" field of the 
  18076.           Description. This structure provides all of the information contained 
  18077.           in the IDL specification of the receiver. For example, if the 
  18078.           describe method is invoked on an object of type AttributeDef, the 
  18079.           "name" field of the returned Description will contain the identifier 
  18080.           "AttributeDescription" and the "value" field will contain an any 
  18081.           structure whose "_value" field is a pointer to an 
  18082.           AttributeDescription structure. 
  18083.  
  18084.  Original Class 
  18085.  
  18086.           Contained 
  18087.  
  18088.  Related Methods 
  18089.  
  18090.           Methods 
  18091.  
  18092.               within 
  18093.  
  18094.  Example Code 
  18095.  
  18096.                     #include <containd.h>
  18097.                     #include <attribdf.h>
  18098.                     #include <somtc.h>
  18099.  
  18100.                     ...
  18101.                     AttributeDef attr; /* An AttributeDef object (also a Contained) */
  18102.                     Description desc; /* .value field will be an AttributeDescription */
  18103.                     AttributeDescription *ad;
  18104.                     Environment *ev;
  18105.  
  18106.                     ...
  18107.                     desc = Contained_describe (attr, ev);
  18108.                     ad = (AttributeDescription *) desc.value._value;
  18109.                     printf ("Attribute name: %s, defined in: %s\n",
  18110.                              ad->name, ad->defined_in);
  18111.                     printf ("Attribute type: ");
  18112.                     TypeCode_print (ad->type, ev);
  18113.                     printf ("Attribute mode: %s\n", ad->mode == AttributeDef_READONLY ?
  18114.                             "READONLY" : "NORMAL");
  18115.                     SOMFree (desc.value._value); /* Finished with describe output */
  18116.                     SOMObject_somFree (attr);    /* Finished with AttributeDef object */
  18117.  
  18118.  
  18119. ΓòÉΓòÉΓòÉ 4.5. within ΓòÉΓòÉΓòÉ
  18120.  
  18121. within This method returns a list of objects (in the Interface Repository) that 
  18122. contain a specified Contained object. 
  18123.  
  18124.  Syntax 
  18125.  
  18126.                     sequence <container> within (Contained receiver, Environment *env)
  18127.  
  18128.  Parameters 
  18129.  
  18130.           receiver (Contained) 
  18131.                     A pointer to a Contained object for which containing 
  18132.                     objects are needed. 
  18133.  
  18134.           env (Environment *) 
  18135.                     A pointer to the Environment structure for the caller. 
  18136.  
  18137.  Returns 
  18138.  
  18139.           rc (sequence <container>) 
  18140.                     Returns a sequence of Container objects that contain the 
  18141.                     specified Contained object. 
  18142.  
  18143.  Remarks 
  18144.  
  18145.           The within method returns a sequence of objects within the Interface 
  18146.           Repository that contain the specified Contained object. If the 
  18147.           receiving object is an InterfaceDef or ModuleDef, it can only be 
  18148.           contained by the object that defines it. Other objects can be 
  18149.           contained by objects that define or inherit them. 
  18150.  
  18151.           If the object is global in scope, the sequence returned by within 
  18152.           will have its _length field set to zero. 
  18153.  
  18154.           When finished using the sequence returned by this method, the client 
  18155.           code is responsible for releasing each of the Containers in the 
  18156.           sequence and freeing the sequence buffer. In C, this can be 
  18157.           accomplished as follows: 
  18158.  
  18159.                     if (seq._length) {
  18160.                         long i;
  18161.                         for (i=0; i
  18162.                              _somFree (seq._buffer[i]); /* Release each Container obj */
  18163.                         SOMFree (seq._buffer);        /* Release the sequence buffer */
  18164.                     }
  18165.  
  18166.  Original Class 
  18167.  
  18168.           Contained 
  18169.  
  18170.  Related Methods 
  18171.  
  18172.           Methods 
  18173.  
  18174.               describe 
  18175.  
  18176.  Example Code 
  18177.  
  18178.                     #include <containd.h>
  18179.                     #include <containr.h>
  18180.  
  18181.                     ...
  18182.                     Contained anObj;
  18183.                     Environment *ev;
  18184.                     sequence(Container) sc;
  18185.                     long i;
  18186.                     ...
  18187.                     sc = Contained_within (anObj, ev);
  18188.                     printf ("%s is contained in (or inherited by):\n",
  18189.                          Contained__get_name (anObj, ev));
  18190.                     for (i=0; i
  18191.                          printf ("\t%s\n",
  18192.                              Contained__get_name ((Contained) sc._buffer[i], ev));
  18193.                          SOMObject_somFree (sc._buffer[i]);
  18194.                     }
  18195.                     if (sc._length)
  18196.                          SOMFree (sc._buffer);
  18197.  
  18198.  
  18199. ΓòÉΓòÉΓòÉ 4.6. Container ΓòÉΓòÉΓòÉ
  18200.  
  18201. Container 
  18202.  
  18203.  File stem: containr 
  18204.  
  18205.  Base 
  18206.  
  18207.           SOMObject 
  18208.  
  18209.  Metaclass 
  18210.  
  18211.           SOMClass 
  18212.  
  18213.  Ancestor Classes 
  18214.  
  18215.                     SOMObject
  18216.  
  18217.  Description 
  18218.  
  18219.           Types 
  18220.  
  18221.                     typedef  string InterfaceName;
  18222.                     // Valid values for InterfaceName are limited to the following set:
  18223.                     //  {"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef",
  18224.                     //   "ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"}
  18225.  
  18226.                     struct ContainerDescription  {
  18227.                        Contained  * contained_object;
  18228.                        Identifier  name;
  18229.                        any   value;
  18230.                     };
  18231.  
  18232.  New methods 
  18233.  
  18234.           The following list shows all the Container methods. 
  18235.  
  18236.               contents 
  18237.               lookup_name 
  18238.               describe_contents 
  18239.  
  18240.  Overridden methods 
  18241.  
  18242.           The following list shows all the methods overridden by the Container 
  18243.           class. These methods are overridden in order to modify the behavior 
  18244.           defined by an ancestor class. 
  18245.  
  18246.               somInit 
  18247.               somUninit 
  18248.               somDumpSelf 
  18249.               somDumpSelfInt 
  18250.  
  18251.  
  18252. ΓòÉΓòÉΓòÉ 4.7. contents ΓòÉΓòÉΓòÉ
  18253.  
  18254. contents This method returns a sequence indicating the objects contained within 
  18255. a specified Container object of the Interface Repository. 
  18256.  
  18257.  Syntax 
  18258.  
  18259.                     sequence<Contained> contents (Container receiver, Environment *env,
  18260.                                       InterfaceName limit_type,
  18261.                                       boolean exclude_inherited)
  18262.  
  18263.  Parameters 
  18264.  
  18265.           receiver (Container) 
  18266.                     A pointer to a Container object whose contained objects are 
  18267.                     needed. 
  18268.  
  18269.           env (Environment *) 
  18270.                     A pointer to the Environment structure for the caller. 
  18271.  
  18272.           limit_type (InterfaceName) 
  18273.                     The name of one interface type (see the valid list above) 
  18274.                     or "all", to specify what type of objects the contents 
  18275.                     method should search for. 
  18276.  
  18277.           exclude_inherited (boolean) 
  18278.                     A boolean value:  TRUE to exclude any inherited objects, or 
  18279.                     FALSE to include all objects. 
  18280.  
  18281.  Returns 
  18282.  
  18283.           rc (sequence<Contained>) 
  18284.                     Returns a sequence of pointers to objects contained within 
  18285.                     the specified Container object. 
  18286.  
  18287.  Remarks 
  18288.  
  18289.           The contents method returns a list of objects contained by the 
  18290.           specified Container object. Each object represents a component of an 
  18291.           IDL interface (class) definition maintained within the Interface 
  18292.           Repository. 
  18293.  
  18294.           The contents method is used to navigate through the hierarchy of 
  18295.           objects within the Interface Repository. Starting with the Repository 
  18296.           object, this method can list all of the objects in the Repository, 
  18297.           then all of the objects within the ModuleDef objects, then all within 
  18298.           the InterfaceDef objects, and so on. 
  18299.  
  18300.           If the "limit_type" is set to "all", objects of all interface types 
  18301.           are returned; otherwise, only objects of the requested interface type 
  18302.           are returned. Valid values for InterfaceName are limited to the 
  18303.           following set: 
  18304.  
  18305.                     {"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef",
  18306.                     "ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"}
  18307.  
  18308.           If "exclude_inherited" is set to TRUE, any inherited objects will not 
  18309.           be returned. 
  18310.  
  18311.           When finished using the sequence returned by this method, the client 
  18312.           code is responsible for releasing each of the objects in the sequence 
  18313.           and freeing the sequence buffer. In C, this can be accomplished as 
  18314.           follows: 
  18315.  
  18316.                     if (seq._length) {
  18317.                         long i;
  18318.                         for (i=0; i <seq._length;i++)
  18319.                            SOMObject_somFree (seq._buffer[i]); /* Release each object */
  18320.                         SOMFree (seq._buffer);                 /* Release the buffer  */
  18321.                     }
  18322.  
  18323.  Original Class 
  18324.  
  18325.           Container 
  18326.  
  18327.  Related Methods 
  18328.  
  18329.           Methods 
  18330.  
  18331.               lookup_name 
  18332.               describe_contents 
  18333.  
  18334.  Example Code 
  18335.  
  18336.                     #include <containr.h>
  18337.  
  18338.                     ...
  18339.  
  18340.                     Container anObj;
  18341.                     Environment *ev;
  18342.                     sequence(Contained) sc;
  18343.                     long i;
  18344.  
  18345.                     ...
  18346.  
  18347.                     sc = Container_contents (anObj, ev, "all", TRUE);
  18348.                     printf ("%s contains the following objects:\n",
  18349.                         SOMObject_somIsA (anObj, _Contained) ?
  18350.                             Contained__get_name ((Contained) anObj, ev) :
  18351.                             "The Interface Repository");
  18352.                     for (i=0; i <seq._length;i++) {
  18353.                         printf ("\t%s\n",
  18354.                             Contained__get_name (sc._buffer[i], ev));
  18355.                         SOMObject_somFree (sc._buffer[i]);
  18356.                     }
  18357.                     if (sc._length)
  18358.                         SOMFree (sc._buffer);
  18359.                     else
  18360.                         printf ("\t[none]\n");
  18361.  
  18362.  
  18363. ΓòÉΓòÉΓòÉ 4.8. describe_contents ΓòÉΓòÉΓòÉ
  18364.  
  18365. describe_contents This method returns a sequence of descriptions of the objects 
  18366. contained within a specified Container object of the Interface Repository. 
  18367.  
  18368.  Syntax 
  18369.  
  18370.                     sequence <ContainerDescription> describe_contents (Container receiver,
  18371.                                                 Environment *env,
  18372.                                                 InterfaceName limit_type,
  18373.                                                 boolean exclude_inherited,
  18374.                                                 long max_returned_objs)
  18375.  
  18376.  Parameters 
  18377.  
  18378.           receiver (Container) 
  18379.                     A pointer to a Container object whose contained object 
  18380.                     descriptions are needed. 
  18381.  
  18382.           env (Environment *) 
  18383.                     A pointer to the Environment structure for the caller. 
  18384.  
  18385.           limit_type (InterfaceName) 
  18386.                     The name of one interface type (see the valid list above) 
  18387.                     or "all", to specify what type of objects the 
  18388.                     describe_contents method should return. 
  18389.  
  18390.           exclude_inherited (boolean) 
  18391.                     A boolean value:  TRUE to exclude any inherited objects, or 
  18392.                     FALSE to include all objects. 
  18393.  
  18394.           max_returned_objs (long) 
  18395.                     A long integer indicating the maximum number of objects to 
  18396.                     be returned by the method, or -1 to indicate no limit is 
  18397.                     set. 
  18398.  
  18399.  Returns 
  18400.  
  18401.           rc (sequence <ContainerDescription>) 
  18402.                     Returns a sequence of ContainerDescription structures, one 
  18403.                     for each object contained within the specified Container 
  18404.                     object. Each ContainerDescription structure has a 
  18405.                     "contained_object" field, which points to the contained 
  18406.                     object, as well as "name" and "value" fields, which are the 
  18407.                     result of the describe method. 
  18408.  
  18409.  Remarks 
  18410.  
  18411.           The describe_contents method combines the operations of the contents 
  18412.           method and the describe method. That is, for each object returned by 
  18413.           the contents operation, the description of the object is returned by 
  18414.           invoking its describe operation. Each object represents a component 
  18415.           of an IDL interface (class) definition maintained within the 
  18416.           Interface Repository. 
  18417.  
  18418.           If the "limit_type" is set to "all", objects of all interface types 
  18419.           are returned; otherwise, only objects of the requested interface type 
  18420.           are returned. Valid values for InterfaceName are limited to the 
  18421.           following set: 
  18422.  
  18423.                     {"AttributeDef", "ConstantDef", "ExceptionDef", "InterfaceDef",
  18424.                     "ModuleDef", "ParameterDef", "OperationDef", "TypeDef", "all"}
  18425.  
  18426.           If "exclude_inherited" is set to TRUE, any inherited objects will not 
  18427.           be returned. 
  18428.  
  18429.           The "max_returned_objs" argument is used to limit the number of 
  18430.           objects that can be returned. If "max_returned_objs" is set to -1, 
  18431.           the results for all contained objects will be returned. 
  18432.  
  18433.           When finished using the sequence returned by this method, the client 
  18434.           code is responsible for freeing the "value._value" field in each 
  18435.           description, releasing each of the objects in the sequence, and 
  18436.           freeing the sequence buffer. In C, this can be accomplished as 
  18437.           follows: 
  18438.  
  18439.                     if (seq._length) {
  18440.                         long i;
  18441.                         for (i=0; i <seq._length;i++) {
  18442.                             if (seq._buffer[i].value._value)
  18443.                                                         /* Release each description */
  18444.                                 SOMFree (seq._buffer[i].value._value);
  18445.                             SOMObject_somFree (seq._buffer[i].contained_object);
  18446.                                                           /* Release each object */
  18447.                         }
  18448.                         SOMFree (seq._buffer);            /* Release the buffer  */
  18449.                     }
  18450.  
  18451.  Original Class 
  18452.  
  18453.           Container 
  18454.  
  18455.  Related Methods 
  18456.  
  18457.           Methods 
  18458.  
  18459.               contents 
  18460.               describe 
  18461.               lookup_name 
  18462.  
  18463.  Example Code 
  18464.  
  18465.                     #include <containr.h>
  18466.  
  18467.                     ...
  18468.  
  18469.                     Container anObj;
  18470.                     Environment *ev;
  18471.                     sequence(ContainerDescription) sc;
  18472.                     long i;
  18473.  
  18474.                     ...
  18475.  
  18476.                     sc = Container_describe_contents (anObj, ev, "all", FALSE, -1L);
  18477.                     printf ("%s defines or inherits the following objects:\n",
  18478.                         SOMObject_somIsA (anObj, _Contained) ?
  18479.                             Contained__get_name ((Contained) anObj, ev) :
  18480.                             "The Interface Repository");
  18481.                     for (i=0; i
  18482.                          printf ("\t%s\n", sc._buffer[i].name);
  18483.                          if (sc._buffer[i].value._value)
  18484.                              SOMFree (sc._buffer[i].value._value);
  18485.                          SOMObject_somFree (sc._buffer[i].contained_object);
  18486.                     }
  18487.                     if (sc._length)
  18488.                         SOMFree (sc._buffer);
  18489.                     else
  18490.                         printf ("\t[none]\n");
  18491.  
  18492.  
  18493. ΓòÉΓòÉΓòÉ 4.9. lookup_name ΓòÉΓòÉΓòÉ
  18494.  
  18495. lookup_name This method locates an object by name within a specified Container 
  18496. object of the Interface Repository, or within objects contained in the 
  18497. Container object. 
  18498.  
  18499.  Syntax 
  18500.  
  18501.                     sequence<Contained> lookup_name (Container receiver,
  18502.                                         Environment *env, Identifier search_name,
  18503.                                         long levels_to_search, InterfaceName limit_type,
  18504.                                         boolean exclude_inherited)
  18505.  
  18506.  Parameters 
  18507.  
  18508.           receiver (Container) 
  18509.                     A pointer to a Container object in which to locate the 
  18510.                     object. 
  18511.  
  18512.           env (Environment *) 
  18513.                     A pointer to the Environment structure for the caller. 
  18514.  
  18515.           search_name (Identifier) 
  18516.                     The name of the object to be located. 
  18517.  
  18518.           levels_to_search (long) 
  18519.                     A long having the value 1 or -1. 
  18520.  
  18521.           limit_type (InterfaceName) 
  18522.                     The name of one interface type (see the valid list above) 
  18523.                     or "all", to specify what type of object to search for. 
  18524.  
  18525.           exclude_inherited (boolean) 
  18526.                     A boolean value:  TRUE to exclude an object when it is 
  18527.                     inherited, or FALSE to return the object from wherever it 
  18528.                     is found. 
  18529.  
  18530.  Returns 
  18531.  
  18532.           rc (sequence<Contained>) 
  18533.                     Returns a sequence of pointers to objects of the given name 
  18534.                     contained within the specified Container object, or within 
  18535.                     objects contained in the Container object. 
  18536.  
  18537.  Remarks 
  18538.  
  18539.           The lookup_name method locates an object by name within a specified 
  18540.           Container object, or within objects contained in the Container 
  18541.           object. The "search_name" specifies the name of the object to be 
  18542.           found. Each object represents a component of an IDL interface (class) 
  18543.           definition maintained within the Interface Repository. 
  18544.  
  18545.           The "levels_to_search" argument controls whether the lookup is 
  18546.           constrained to the specified Container object or whether objects 
  18547.           contained within the Container object are also searched. The 
  18548.           "levels_to_search" value should be -1 to search the Container and all 
  18549.           contained objects; it should be 1 to search only the Container 
  18550.           itself. 
  18551.  
  18552.           If "limit_type" is set to "all", the lookup locates an object of the 
  18553.           specified name with any interface type; otherwise, the search locates 
  18554.           the object only if it has the designated interface type. Valid values 
  18555.           for InterfaceName are limited to the following set: 
  18556.  
  18557.                     {"AttributeDef", "ConstantDef", "ExceptionDef",
  18558.                     "InterfaceDef", "ModuleDef", "ParameterDef",
  18559.                     "OperationDef", "TypeDef", "all"}
  18560.  
  18561.           If "exclude_inherited" is set to TRUE, any inherited objects will not 
  18562.           be returned. 
  18563.  
  18564.           When finished using the sequence returned by this method, the client 
  18565.           code is responsible for releasing each of the objects in the sequence 
  18566.           and freeing the sequence buffer. In C, this can be accomplished as 
  18567.           follows: 
  18568.  
  18569.                     if (seq._length) {
  18570.                         long i;
  18571.                         for (i=0; i <seq._length;i++) {
  18572.                             SOMObject_somFree (seq._buffer[i]);
  18573.                                                              /* Release each object */
  18574.                         SOMFree (seq._buffer);               /* Release the buffer  */
  18575.                         }
  18576.  
  18577.  Original Class 
  18578.  
  18579.           Container 
  18580.  
  18581.  Related Methods 
  18582.  
  18583.           Methods 
  18584.  
  18585.               contents 
  18586.               describe_contents 
  18587.  
  18588.  Example Code 
  18589.  
  18590.                     #include <containr.h>
  18591.                     #include <containd.h>
  18592.                     #include <repostry.h>
  18593.  
  18594.                     ...
  18595.  
  18596.                     Container repo;
  18597.                     Environment *ev;
  18598.                     sequence(Contained) sc;
  18599.                     long i;
  18600.                     Identifier nameToFind;
  18601.  
  18602.                     ...
  18603.  
  18604.                     repo = (Container) RepositoryNew ();
  18605.                     sc = Container_lookup_name (repo, ev, nameToFind, -1, "all", TRUE);
  18606.                     printf ("%d object%s found:\n",
  18607.                               sc._length, sc._length == 1 ? "" : "s");
  18608.                     for (i=0; i <seq._length;i++) {
  18609.                         printf ("\t%s\n",
  18610.                             Contained__get_id (sc._buffer[i], ev));
  18611.                         SOMObject_somFree (sc._buffer[i]);
  18612.                     }
  18613.                     if (sc._length)
  18614.                         SOMFree (sc._buffer);
  18615.  
  18616.  
  18617. ΓòÉΓòÉΓòÉ 4.10. ExceptionDef ΓòÉΓòÉΓòÉ
  18618.  
  18619. ExceptionDef 
  18620.  
  18621.  File stem: excptdef 
  18622.  
  18623.  Base 
  18624.  
  18625.           Contained 
  18626.  
  18627.  Metaclass 
  18628.  
  18629.           SOMClass 
  18630.  
  18631.  Ancestor Classes 
  18632.  
  18633.                     Contained
  18634.                        SOMObject
  18635.  
  18636.  Description 
  18637.  
  18638.           Types 
  18639.  
  18640.                     struct ExceptionDescription  {
  18641.                         Identifier      name;
  18642.                         RepositoryId    id;
  18643.                         RepositoryId    defined_in;
  18644.                         TypeCode        type;
  18645.                     };
  18646.  
  18647.           The describe method, inherited from Contained, returns an 
  18648.           ExceptionDescription structure in the "value" member of the 
  18649.           Description structure (defined in the Contained class). 
  18650.  
  18651.           Attributes 
  18652.  
  18653.           Listed below is each available attribute, with its corresponding type 
  18654.           in parentheses, followed by a description of its purpose: 
  18655.  
  18656.           type (TypeCode) 
  18657.               The TypeCode that represents the type of the exception. The 
  18658.               TypeCode returned by the "_get_" form of the type attribute is 
  18659.               contained in the receiving ExceptionDef object, which retains 
  18660.               ownership. Hence, the returned TypeCode should not be freed. To 
  18661.               obtain a separate copy, use the TypeCode_copy operation. The 
  18662.               "_set_" form of the attribute makes a private copy of the 
  18663.               TypeCode you supply, to keep in the receiving object. You retain 
  18664.               ownership of the passed TypeCode. 
  18665.  
  18666.  New methods 
  18667.  
  18668.           There are currently no new methods defined for the ExceptionDef 
  18669.           class. 
  18670.  
  18671.  Overridden methods 
  18672.  
  18673.           The following list shows all the methods overridden by the 
  18674.           ExceptionDef class. These methods are overridden in order to modify 
  18675.           the behavior defined by an ancestor class. 
  18676.  
  18677.               somInit 
  18678.               somUninit 
  18679.               somDumpSelf 
  18680.               somDumpSelfInt 
  18681.               describe 
  18682.  
  18683.  
  18684. ΓòÉΓòÉΓòÉ 4.11. InterfaceDef ΓòÉΓòÉΓòÉ
  18685.  
  18686. InterfaceDef 
  18687.  
  18688.  File stem: intfacdf 
  18689.  
  18690.  Base 
  18691.  
  18692.                     Contained
  18693.                     Container
  18694.  
  18695.  Metaclass 
  18696.  
  18697.           SOMClass 
  18698.  
  18699.  Ancestor Classes 
  18700.  
  18701.                     Contained
  18702.                         Container
  18703.                           SOMObject
  18704.  
  18705.  Description 
  18706.  
  18707.           Types 
  18708.  
  18709.                     struct FullInterfaceDescription   {
  18710.                         Identifier    name;
  18711.                         RepositoryId  id;
  18712.                         RepositoryId  defined_in;
  18713.                         sequence<OperationDef::OperationDescription> operation;
  18714.                         sequence<AttributeDef::AttributeDescription> attributes;
  18715.                     };
  18716.  
  18717.                     struct InterfaceDescription   {
  18718.                         Identifier    name;
  18719.                         RepositoryId  id;
  18720.                         RepositoryId  defined_in;
  18721.                     };
  18722.  
  18723.           The describe method, inherited from Contained, returns an 
  18724.           InterfaceDescription structure in the "value" member of the 
  18725.           Description structure (defined in the Contained class). The 
  18726.           describe_contents method, inherited from Container, returns a 
  18727.           sequence of these Description structures, each carrying a reference 
  18728.           to an InterfaceDescription structure in its "value" member. 
  18729.  
  18730.           Implementation note  The two sequences "OperationDescription" and 
  18731.           "AttributeDescription" are built dynamically within the 
  18732.           FullInterfaceDescription structure, due to the InterfaceDef class's 
  18733.           inheritance from the Contained class. 
  18734.  
  18735.           Attributes 
  18736.  
  18737.           All attributes of the InterfaceDef class provide access to 
  18738.           information kept within the receiving InterfaceDef object. The 
  18739.           "_get_" form of the attribute returns a memory reference that is only 
  18740.           valid as long as the receiving object has not been freed (using 
  18741.           _somFree). The "_set_" form of the attribute makes a (deep) copy of 
  18742.           your data and places it in the receiving InterfaceDef object. You 
  18743.           retain ownership of all memory references passed using the "_set_" 
  18744.           attribute forms. 
  18745.  
  18746.           Listed below is each available attribute, with its corresponding type 
  18747.           in parentheses, followed by a description of its purpose: 
  18748.  
  18749.           base_interfaces (sequence <RepositoryId>) 
  18750.               The sequence of RepositoryIds for all of the interfaces that the 
  18751.               receiving interface inherits. 
  18752.  
  18753.           instanceData (TypeCode) 
  18754.               The TypeCode of a structure whose members are the internal 
  18755.               instance variables, if any, described in the SOM implementation 
  18756.               section of the interface. 
  18757.  
  18758.               Note:  This attribute is a SOM-unique extension of the Interface 
  18759.               Repository; it is not stipulated by the CORBA specifications. 
  18760.  
  18761.  New methods 
  18762.  
  18763.           The following list shows all the InterfaceDef methods. 
  18764.  
  18765.               describe_interface 
  18766.  
  18767.  Overridden methods 
  18768.  
  18769.           The following list shows all the methods overridden by the 
  18770.           InterfaceDef class. These methods are overridden in order to modify 
  18771.           the behavior defined by an ancestor class. 
  18772.  
  18773.               somInit 
  18774.               somUninit 
  18775.               somDumpSelf 
  18776.               somDumpSelfInt 
  18777.               within 
  18778.               describe 
  18779.  
  18780.  
  18781. ΓòÉΓòÉΓòÉ 4.12. describe_interface ΓòÉΓòÉΓòÉ
  18782.  
  18783. describe_interface This method returns (from the Interface Repository) a 
  18784. description of all the methods and attributes of an interface definition. 
  18785.  
  18786.  Syntax 
  18787.  
  18788.                     FullInterfaceDescription describe_interface (InterfaceDef receiver,
  18789.                                             Environment *env)
  18790.  
  18791.  Parameters 
  18792.  
  18793.           receiver (InterfaceDef) 
  18794.                     A pointer to an object of class InterfaceDef representing 
  18795.                     the Interface Repository object where an interface 
  18796.                     definition is stored. 
  18797.  
  18798.           env (Environment *) 
  18799.                     A pointer where the method can return exception information 
  18800.                     if an error is encountered. 
  18801.  
  18802.  Returns 
  18803.  
  18804.           rc (FullInterfaceDescription) 
  18805.                     Returns a description of all the methods and attributes of 
  18806.                     an interface definition that are held in the Interface 
  18807.                     Repository. 
  18808.  
  18809.  Remarks 
  18810.  
  18811.           The describe_interface method returns a description of all the 
  18812.           methods and attributes of an interface definition that are held in 
  18813.           the Interface Repository. 
  18814.  
  18815.           When finished using the FullInterfaceDescription returned by this 
  18816.           method, the client code is responsible for freeing the _buffer fields 
  18817.           of the two sequences it contains. In C, this can be accomplished as 
  18818.           follows: 
  18819.  
  18820.                     if (fid.operation._length)
  18821.                         SOMFree (fid.operation._buffer);        /* Release the buffer */
  18822.                     if (fid.attributes._length)
  18823.                         SOMFree (fid.attributes._buffer);       /* Release the buffer */
  18824.  
  18825.  Original Class 
  18826.  
  18827.           InterfaceDef 
  18828.  
  18829.  Example Code 
  18830.  
  18831.                     #include <intfacdf.h>
  18832.  
  18833.                     ...
  18834.  
  18835.                     InterfaceDef idef;
  18836.                     Environment *ev;
  18837.                     FullInterfaceDescription fid;
  18838.                     long i;
  18839.  
  18840.                     ...
  18841.                     fid = InterfaceDef_describe_interface (idef, ev);
  18842.                     printf ("The %s interface has the following
  18843.                     attributes:\n",
  18844.                         Contained__get_name ((Contained) idef, ev));
  18845.                     if (!fid.attributes._length)
  18846.                         printf ("\t[none]\n");
  18847.                     else {
  18848.                         for (i=0; i <fid.attributes._length;i++) {
  18849.                             printf ("\t%s\n",
  18850.                     fid.attributes._buffer[i].name);
  18851.                         SOMFree (fid.attributes._buffer);
  18852.                     }
  18853.                     printf ("and the following methods:\n")
  18854.                     if (!fid.operation._length)
  18855.                         printf ("\t[none]\n");
  18856.                     else {
  18857.                         for (i=0; i <fid.attributes._length;i++) {
  18858.                             printf ("\t%s\n", fid.operation._buffer[i].name);
  18859.                         SOMFree (fid.operation._buffer);
  18860.                     }
  18861.  
  18862.  
  18863. ΓòÉΓòÉΓòÉ 4.13. ModuleDef ΓòÉΓòÉΓòÉ
  18864.  
  18865. ModuleDef 
  18866.  
  18867.  File stem: moduledf 
  18868.  
  18869.  Base 
  18870.  
  18871.                     Contained
  18872.                     Container
  18873.  
  18874.  Metaclass 
  18875.  
  18876.           SOMClass 
  18877.  
  18878.  Ancestor Classes 
  18879.  
  18880.                     Contained
  18881.                         Container
  18882.                           SOMObject
  18883.  
  18884.  Description 
  18885.  
  18886.           Types 
  18887.  
  18888.                     struct ModuleDescription {
  18889.                         Identifier    name;
  18890.                         RepositoryId  id;
  18891.                         RepositoryId  defined_in;
  18892.                     };
  18893.  
  18894.           The describe method, inherited from Contained, returns a 
  18895.           ModuleDescription structure in the "value" member of the Description 
  18896.           structure (defined in the Contained class). The describe_contents 
  18897.           method, inherited from Container, returns a sequence of these 
  18898.           Description structures, each carrying a reference to a 
  18899.           ModuleDescription structure in its "value" member. 
  18900.  
  18901.  New methods 
  18902.  
  18903.           There are currently no new methods defined for the ModuleDef class. 
  18904.  
  18905.  Overridden methods 
  18906.  
  18907.           The following list shows all the methods overridden by the ModuleDef 
  18908.           class. These methods are overridden in order to modify the behavior 
  18909.           defined by an ancestor class. 
  18910.  
  18911.               somInit 
  18912.               somUninit 
  18913.               somDumpSelf 
  18914.               somDumpSelfInt 
  18915.               describe 
  18916.               within 
  18917.  
  18918.  
  18919. ΓòÉΓòÉΓòÉ 4.14. OperationDef ΓòÉΓòÉΓòÉ
  18920.  
  18921. OperationDef 
  18922.  
  18923.  File stem: operatdf 
  18924.  
  18925.  Base 
  18926.  
  18927.                     Contained
  18928.                     Container
  18929.  
  18930.  Metaclass 
  18931.  
  18932.           SOMClass 
  18933.  
  18934.  Ancestor Classes 
  18935.  
  18936.                     Contained
  18937.                         Container
  18938.                           SOMObject
  18939.  
  18940.  Description 
  18941.  
  18942.           Types 
  18943.  
  18944.                     typedef  Identifier  ContextIdentifier;
  18945.                     enum  OperationMode   { NORMAL, ONEWAY };
  18946.  
  18947.                     struct  OperationDescription   {
  18948.                         Identifier      name;
  18949.                         RepositoryId    id;
  18950.                         RepositoryId    defined_in;
  18951.                         TypeCode        result;
  18952.                         OperationMode   mode;
  18953.                         sequence <ContextIdentifier>  contexts;
  18954.                         sequence <ParameterDef::ParameterDescription>  parameter;
  18955.                         sequence < ExceptionDef::ExceptionDescription>  exceptions;
  18956.                     };
  18957.  
  18958.           The describe method, inherited from Contained, returns an 
  18959.           OperationDescription structure in the "value" member of the 
  18960.           Description structure (defined in the Contained class). The 
  18961.           describe_contents method, inherited from Container, returns a 
  18962.           sequence of these Description structures, each carrying a reference 
  18963.           to an OperationDescription structure in its "value" member. 
  18964.  
  18965.           Attributes 
  18966.  
  18967.           Listed below is each available attribute, with its corresponding type 
  18968.           in parentheses, followed by a description of its purpose: 
  18969.  
  18970.           result  (TypeCode) 
  18971.               The TypeCode that represents the type of the operation (method). 
  18972.               The TypeCode returned by the "_get_" form of the type attribute 
  18973.               is contained in the receiving OperationDef object, which retains 
  18974.               ownership. Hence, the returned TypeCode should not be freed. To 
  18975.               obtain a separate copy, use the TypeCode_copy operation. The 
  18976.               "_set_" form of the attribute makes a private copy of the 
  18977.               TypeCode you supply, to keep in the receiving object. You retain 
  18978.               ownership of the passed TypeCode. 
  18979.  
  18980.           mode (OperationMode) 
  18981.               The OperationMode of the operation (method), either NORMAL or 
  18982.               ONEWAY. 
  18983.  
  18984.           contexts (sequence <ContextIdentifier>) 
  18985.               The list of ContextIdentifiers associated with the operation 
  18986.               (method). The "_get_" form of the attribute returns a sequence 
  18987.               whose buffer is owned by the receiving OperationDef object. You 
  18988.               should not free it. The "_set_" form of the attribute makes a 
  18989.               (deep) copy of the passed sequence; you retain ownership of the 
  18990.               original storage. 
  18991.  
  18992.  New methods 
  18993.  
  18994.           There are currently no new methods defined for the OperationDef 
  18995.           class. 
  18996.  
  18997.  Overridden methods 
  18998.  
  18999.           The following list shows all the methods overridden by the 
  19000.           OperationDef class. These methods are overridden in order to modify 
  19001.           the behavior defined by an ancestor class. 
  19002.  
  19003.               somInit 
  19004.               somUninit 
  19005.               somDumpSelf 
  19006.               somDumpSelfInt 
  19007.               describe 
  19008.  
  19009.  
  19010. ΓòÉΓòÉΓòÉ 4.15. ParameterDef ΓòÉΓòÉΓòÉ
  19011.  
  19012. ParameterDef 
  19013.  
  19014.  File stem: paramdef 
  19015.  
  19016.  Base 
  19017.  
  19018.           Contained 
  19019.  
  19020.  Metaclass 
  19021.  
  19022.           SOMClass 
  19023.  
  19024.  Ancestor Classes 
  19025.  
  19026.                     Contained
  19027.                         SOMObject
  19028.  
  19029.  Description 
  19030.  
  19031.           Types 
  19032.  
  19033.                     enum  ParameterMode  { IN, OUT, INOUT };
  19034.  
  19035.                     struct ParameterDescription {
  19036.                         Identifier      name;
  19037.                         RepositoryId    id;
  19038.                         RepositoryId    defined_in;
  19039.                         TypeCode        type;
  19040.                         ParameterMode   mode;
  19041.                     };
  19042.  
  19043.           The describe method, inherited from Contained, returns a 
  19044.           ParameterDescription structure in the "value" member of the 
  19045.           Description structure (defined in the Contained class). 
  19046.  
  19047.           Attributes 
  19048.  
  19049.           Listed below is each available attribute, with its corresponding type 
  19050.           in parentheses, followed by a description of its purpose: 
  19051.  
  19052.           type (TypeCode) 
  19053.               The TypeCode that represents the type of the parameter. The 
  19054.               TypeCode returned by the "_get_" form of the type attribute is 
  19055.               contained in the receiving ParameterDef object, which retains 
  19056.               ownership. Hence, the returned TypeCode should not be freed. To 
  19057.               obtain a separate copy, use the TypeCode_copy operation. The 
  19058.               "_set_" form of the attribute makes a private copy of the 
  19059.               TypeCode you supply, to keep in the receiving object. You retain 
  19060.               ownership of the passed TypeCode. 
  19061.  
  19062.           mode (ParameterMode) 
  19063.               The ParameterMode of the parameter (IN, OUT, or INOUT). 
  19064.  
  19065.  New methods 
  19066.  
  19067.           There are currently no new methods defined for the ParameterDef 
  19068.           class. 
  19069.  
  19070.  Overridden methods 
  19071.  
  19072.           The following list shows all the methods overridden by the 
  19073.           ParameterDef class. These methods are overridden in order to modify 
  19074.           the behavior defined by an ancestor class. 
  19075.  
  19076.               somInit 
  19077.               somUninit 
  19078.               somDumpSelf 
  19079.               somDumpSelfInt 
  19080.               describe 
  19081.  
  19082.  
  19083. ΓòÉΓòÉΓòÉ 4.16. Repository ΓòÉΓòÉΓòÉ
  19084.  
  19085. Repository 
  19086.  
  19087.  File stem: repostry 
  19088.  
  19089.  Base 
  19090.  
  19091.           Container 
  19092.  
  19093.  Metaclass 
  19094.  
  19095.           SOMClass 
  19096.  
  19097.  Ancestor Classes 
  19098.  
  19099.                     Container
  19100.                         SOMObject
  19101.  
  19102.  Description 
  19103.  
  19104.           Types 
  19105.  
  19106.                     struct RepositoryDescription  {
  19107.                         Identifier  name;
  19108.                         RepositoryId  id;
  19109.                         RepositoryId  defined_in;
  19110.                     };
  19111.  
  19112.           The inherited describe_contents method returns an instance of the 
  19113.           RepositoryDescription structure in the "value" member of the 
  19114.           Description structure defined in the Container interface. 
  19115.  
  19116.  New methods 
  19117.  
  19118.           The following list shows all the Repository methods. 
  19119.  
  19120.               lookup_id 
  19121.               lookup_modifier 
  19122.               release_cache 
  19123.  
  19124.  Overridden methods 
  19125.  
  19126.           The following list shows all the methods overridden by the Repository 
  19127.           class. These methods are overridden in order to modify the behavior 
  19128.           defined by an ancestor class. 
  19129.  
  19130.               describe_contents 
  19131.               somInit 
  19132.               somUninit 
  19133.               somFree 
  19134.               somDumpSelf 
  19135.               somDumpSelfInt 
  19136.  
  19137.  
  19138. ΓòÉΓòÉΓòÉ 4.17. lookup_id ΓòÉΓòÉΓòÉ
  19139.  
  19140. lookup_id This method returns the object having a specified RepositoryId. 
  19141.  
  19142.  Syntax 
  19143.  
  19144.                     Contained lookup_id (Repository receiver, Environment *env,
  19145.                                 RepositoryId search_id)
  19146.  
  19147.  Parameters 
  19148.  
  19149.           receiver (Repository) 
  19150.                     A pointer to an object of class Repository representing 
  19151.                     SOM's Interface Repository. 
  19152.  
  19153.           env (Environment *) 
  19154.                     A pointer where the method can return exception information 
  19155.                     if an error is encountered. 
  19156.  
  19157.           search_id (RepositoryId) 
  19158.                     An ID value of type RepositoryId that uniquely identifies 
  19159.                     the desired object in the Interface Repository. 
  19160.  
  19161.  Returns 
  19162.  
  19163.           rc (Contained) 
  19164.                     Returns the Contained object that has the specified 
  19165.                     RepositoryId. 
  19166.  
  19167.  Remarks 
  19168.  
  19169.           The lookup_id method returns the object having a RepositoryId given 
  19170.           by the specified search_id argument. The returned object represents a 
  19171.           component of an IDL interface (class) definition maintained within 
  19172.           the Interface Repository. 
  19173.  
  19174.           When finished using the object returned by this method, the client 
  19175.           code is responsible for releasing it, using the somFree method. 
  19176.  
  19177.  Original Class 
  19178.  
  19179.           Repository 
  19180.  
  19181.  Related Methods 
  19182.  
  19183.           Methods 
  19184.  
  19185.               lookup_modifier 
  19186.               lookup_name 
  19187.               contents 
  19188.               within 
  19189.  
  19190.  Example Code 
  19191.  
  19192.                     #include <containd.h>
  19193.                     #include <repostry.h>
  19194.  
  19195.                     ...
  19196.  
  19197.                     Repository repo;
  19198.                     Environment *ev;
  19199.                     Contained c;
  19200.                     RepositoryId objectToFind;
  19201.  
  19202.                     ...
  19203.  
  19204.                     repo = RepositoryNew ();
  19205.                     c = Repository_lookup_id (repo, ev, objectToFind);
  19206.                     if (c) {
  19207.                         printf ("lookup_id found object of type: %s, named: %s\n",
  19208.                             SOMObject_somGetClassName (c), Contained__get_name (c, ev));
  19209.                         SOMObject_somFree (c);
  19210.                     }
  19211.  
  19212.  
  19213. ΓòÉΓòÉΓòÉ 4.18. lookup_modifier ΓòÉΓòÉΓòÉ
  19214.  
  19215. lookup_modifier Returns the value of a given SOM modifier for a specified 
  19216. object [that is, for an object that is a component of an IDL interface (class) 
  19217. definition maintained within the Interface Repository]. 
  19218.  
  19219.  Syntax 
  19220.  
  19221.                     string lookup_modifier (Repository receiver, Environment *env,
  19222.                                  RepositoryId id, string modifier)
  19223.  
  19224.  Parameters 
  19225.  
  19226.           receiver (Repository) 
  19227.                     A pointer to an object of class Repository representing 
  19228.                     SOM's Interface Repository. 
  19229.  
  19230.           env (Environment *) 
  19231.                     A pointer where the method can return exception information 
  19232.                     if an error is encountered. 
  19233.  
  19234.           id (RepositoryId) 
  19235.                     The RepositoryId of the object whose modifier value is 
  19236.                     needed. 
  19237.  
  19238.           modifier (string) 
  19239.                     The name of a specific (SOM or user-specified) modifier 
  19240.                     whose string value is needed. 
  19241.  
  19242.  Returns 
  19243.  
  19244.           rc (string) 
  19245.                     The lookup_modifier method returns the string value of the 
  19246.                     given SOM modifier for an object with the specified 
  19247.                     RepositoryId, if it exists. If an existing modifier has no 
  19248.                     value, a zero-length string value is returned. If the 
  19249.                     object cannot be found, then NULL (or zero) is returned. 
  19250.  
  19251.                     When the string value is no longer needed, client code must 
  19252.                     free the space for the string (using SOMFree). 
  19253.  
  19254.  Remarks 
  19255.  
  19256.           The lookup_modifier method returns the string value of the given SOM 
  19257.           modifier for an object with the specified RepositoryId within the 
  19258.           Interface Repository. For a discussion of SOM modifiers, see the 
  19259.           topic "Modifier statements" in Chapter 4, "SOM IDL and The SOM 
  19260.           Compiler," of the SOM Programming Guide. 
  19261.  
  19262.           If the object with the given RepositoryId does not exist or does not 
  19263.           possess the modifier, then NULL (or zero) is returned. If the object 
  19264.           exists but the specified modifier does not have a value, a 
  19265.           zero-length string value is returned. 
  19266.  
  19267.           Note:  The lookup_modifier method is not stipulated by the CORBA 
  19268.           specifications; it is a SOM-unique extension to the Interface 
  19269.           Repository. 
  19270.  
  19271.  Original Class 
  19272.  
  19273.           Repository 
  19274.  
  19275.  Related Methods 
  19276.  
  19277.           Methods 
  19278.  
  19279.               lookup_id 
  19280.               lookup_name 
  19281.  
  19282.  Example Code 
  19283.  
  19284.                     #include <repostry.h>
  19285.  
  19286.                     ...
  19287.  
  19288.                     Repository repo;
  19289.                     Environment *ev;
  19290.                     RepositoryId objectId;
  19291.                     string filestem;i
  19292.  
  19293.                     ...
  19294.  
  19295.                     repo = RepositoryNew ();
  19296.                     filestem = Repository_lookup_modifier (repo, ev, objectId,
  19297.                                                                          "filestem");
  19298.                     if (filestem) {
  19299.                         printf
  19300.                             ("The %s object's filestem modifier has the value \"%s\"\n",
  19301.                                 objectId, filestem);
  19302.                         SOMFree (filestem);
  19303.                     } else
  19304.                         printf ("No filestem modifier could be found for %s\n",
  19305.                                 objectId);
  19306.  
  19307.  
  19308. ΓòÉΓòÉΓòÉ 4.19. release_cache ΓòÉΓòÉΓòÉ
  19309.  
  19310. release_cache This method permits the Repository object to release the memory 
  19311. occupied by Interface Repository objects that have been implicitly referenced. 
  19312.  
  19313.  Syntax 
  19314.  
  19315.                     void release_cache (Repository receiver, Environment *env)
  19316.  
  19317.  Parameters 
  19318.  
  19319.           receiver (Repository) 
  19320.                     A pointer to an object of class Repository representing 
  19321.                     SOM's Interface Repository. 
  19322.  
  19323.           env (Environment *) 
  19324.                     A pointer where the method can return exception information 
  19325.                     if an error is encountered. 
  19326.  
  19327.  Returns 
  19328.  
  19329.           rc (void) 
  19330.  
  19331.  Remarks 
  19332.  
  19333.           This method allows the Repository object to release the memory 
  19334.           occupied by implicitly referenced Interface Repository objects. Some 
  19335.           methods (such as describe_contents and lookup_name) may cause some 
  19336.           objects to be instantiated that are not directly accessible through 
  19337.           object references that have been returned to the user. These objects 
  19338.           are kept in an internal Interface Repository cache until the 
  19339.           release_cache method is used to free them. The internal cache 
  19340.           continuously replenishes itself over time as the need arises. 
  19341.  
  19342.           See the section entitled "A word about memory management" in the 
  19343.           Interface Repository Framework in the SOM Programming Guide. 
  19344.  
  19345.  Original Class 
  19346.  
  19347.           Repository 
  19348.  
  19349.  Example Code 
  19350.  
  19351.                     #include <repostry.h>
  19352.  
  19353.                     ...
  19354.  
  19355.                     Repository repo;
  19356.                     Environment *ev;
  19357.                     sequence(ContainerDescription) scd;
  19358.  
  19359.                     ...
  19360.  
  19361.                     scd = Container_describe_contents (
  19362.                           (Container) repo, ev, "TypeDef", TRUE, -1);
  19363.                     Repository_release_cache (repo, ev);
  19364.  
  19365.  
  19366. ΓòÉΓòÉΓòÉ 4.20. TypeDef ΓòÉΓòÉΓòÉ
  19367.  
  19368. TypeDef 
  19369.  
  19370.  File stem: typedef 
  19371.  
  19372.  Base 
  19373.  
  19374.           Contained 
  19375.  
  19376.  Metaclass 
  19377.  
  19378.           SOMClass 
  19379.  
  19380.  Ancestor Classes 
  19381.  
  19382.                     Contained
  19383.                         SOMObject
  19384.  
  19385.  Description 
  19386.  
  19387.           Types 
  19388.  
  19389.                     struct      TypeDescription         {
  19390.                     Identifier    name;
  19391.                     RepositoryId  id;
  19392.                     RepositoryId  defined_in;
  19393.                     TypeCode      type;
  19394.                     };
  19395.  
  19396.           The describe method, inherited from Contained, returns a 
  19397.           TypeDescription structure in the "value" member of the Description 
  19398.           structure (defined in the Contained class). 
  19399.  
  19400.           Attributes 
  19401.  
  19402.           Listed below is each available attribute, with its corresponding type 
  19403.           in parentheses, followed by a description of its purpose: 
  19404.  
  19405.           type (TypeCode) 
  19406.               The TypeCode that represents the type of the typedef. The 
  19407.               TypeCode returned by the "_get_" form of the type attribute is 
  19408.               contained in the receiving TypeDef object, which retains 
  19409.               ownership. Hence, the returned TypeCode should not be freed. To 
  19410.               obtain a separate copy, use the TypeCode_copy operation. The 
  19411.               "_set_" form of the attribute makes a private copy of the 
  19412.               TypeCode you supply, to keep in the receiving object. You retain 
  19413.               ownership of the passed TypeCode. 
  19414.  
  19415.  New methods 
  19416.  
  19417.           There are currently no new methods defined for the TypeDef class. 
  19418.  
  19419.  Overridden methods 
  19420.  
  19421.           The following list shows all the methods overridden by the TypeDef 
  19422.           class. These methods are overridden in order to modify the behavior 
  19423.           defined by an ancestor class. 
  19424.  
  19425.               somInit 
  19426.               somUninit 
  19427.               somDumpSelf 
  19428.               somDumpSelfInt 
  19429.               describe 
  19430.  
  19431.  
  19432. ΓòÉΓòÉΓòÉ 4.21. TypeCode_alignment ΓòÉΓòÉΓòÉ
  19433.  
  19434. TypeCode_alignment This function supplies the alignment value for a given 
  19435. TypeCode. 
  19436.  
  19437.  Syntax 
  19438.  
  19439.                     short TypeCode_alignment (TypeCode tc, Environment *env)
  19440.  
  19441.  Parameters 
  19442.  
  19443.           tc (TypeCode) 
  19444.                     The TypeCode whose alignment information is desired. 
  19445.  
  19446.           env (Environment *) 
  19447.                     A pointer to an Environment structure. 
  19448.  
  19449.  Returns 
  19450.  
  19451.           rc (short) 
  19452.                     A short integer containing the alignment value. 
  19453.  
  19454.  Remarks 
  19455.  
  19456.           This function returns the alignment information associated with the 
  19457.           given TypeCode. The alignment value is a short integer that should 
  19458.           evenly divide any memory address where an instance of the type 
  19459.           described by the TypeCode will occur. 
  19460.  
  19461.  Related Information 
  19462.  
  19463.           Functions 
  19464.  
  19465.               TypeCodeNew 
  19466.               TypeCode_equal 
  19467.               TypeCode_kind 
  19468.               TypeCode_param_count 
  19469.               TypeCode_parameter 
  19470.               TypeCode_setAlignment 
  19471.               TypeCode_size 
  19472.               TypeCode_free 
  19473.               TypeCode_print 
  19474.  
  19475.  
  19476. ΓòÉΓòÉΓòÉ 4.22. TypeCode_copy ΓòÉΓòÉΓòÉ
  19477.  
  19478. TypeCode_copy This function creates a new copy of a given TypeCode. 
  19479.  
  19480.  Syntax 
  19481.  
  19482.                     TypeCode TypeCode_copy (TypeCode tc, Environment *env)
  19483.  
  19484.  Parameters 
  19485.  
  19486.           tc (TypeCode) 
  19487.                     The TypeCode to be copied. 
  19488.  
  19489.           env (Environment *) 
  19490.                     A pointer to an Environment structure. The CORBA standard 
  19491.                     mandates the use of this structure as a standard way to 
  19492.                     return exception information when an error condition is 
  19493.                     detected. 
  19494.  
  19495.  Returns 
  19496.  
  19497.           rc (TypeCode) 
  19498.                     A new TypeCode with no internal references to any 
  19499.                     previously existing TypeCodes or strings. If a copy cannot 
  19500.                     be created successfully, the value NULL is returned. No 
  19501.                     exceptions are raised by this function. 
  19502.  
  19503.  Remarks 
  19504.  
  19505.           The TypeCode_copy function creates a new copy of a given TypeCode. 
  19506.           TypeCodes are complex data structures whose actual representation is 
  19507.           hidden and may contain internal references to strings and other 
  19508.           TypeCodes. The copy created by this function is guaranteed not to 
  19509.           refer to any previously existing TypeCodes or strings, and hence can 
  19510.           be used long after the original TypeCode is freed or released 
  19511.           (TypeCodes are typically contained in Interface Repository objects 
  19512.           whose memory resources are released by the _somFree method). 
  19513.  
  19514.           All of the memory used to construct the TypeCode copy is allocated 
  19515.           dynamically and should be subsequently freed only by using the 
  19516.           TypeCode_free function. 
  19517.  
  19518.           This function is a SOM-unique extension to the CORBA standard. 
  19519.  
  19520.  Related Information 
  19521.  
  19522.           Functions 
  19523.  
  19524.               TypeCodeNew 
  19525.               TypeCode_alignment 
  19526.               TypeCode_equal 
  19527.               TypeCode_kind 
  19528.               TypeCode_param_count 
  19529.               TypeCode_parameter 
  19530.               TypeCode_size 
  19531.               TypeCode_free 
  19532.               TypeCode_print 
  19533.               TypeCode_setAlignment 
  19534.  
  19535.  
  19536. ΓòÉΓòÉΓòÉ 4.23. TypeCode_equal ΓòÉΓòÉΓòÉ
  19537.  
  19538. TypeCode_equal This function compares two TypeCodes for equality. 
  19539.  
  19540.  Syntax 
  19541.  
  19542.                     boolean TypeCode_equal (TypeCode tc, Environment *env,
  19543.                                   TypeCode tc2)
  19544.  
  19545.  Parameters 
  19546.  
  19547.           tc (TypeCode) 
  19548.                     One of the TypeCodes to be compared. 
  19549.  
  19550.           env (Environment *) 
  19551.                     A pointer to an Environment structure. The CORBA standard 
  19552.                     mandates the use of this structure as a standard way to 
  19553.                     return exception information when an error condition is 
  19554.                     detected. 
  19555.  
  19556.           tc2 (TypeCode) 
  19557.                     The other TypeCode to be compared. 
  19558.  
  19559.  Returns 
  19560.  
  19561.           rc (boolean) 
  19562.                     Returns TRUE (1) if the TypeCodes tc and tc2 describe the 
  19563.                     same data type, with the same alignment. Otherwise, FALSE 
  19564.                     (0) is returned. No exceptions are raised by this function. 
  19565.  
  19566.  Remarks 
  19567.  
  19568.           The TypeCode_equal function can be used to determine if two distinct 
  19569.           TypeCodes describe the same underlying abstract data type. 
  19570.  
  19571.  Related Information 
  19572.  
  19573.           Functions 
  19574.  
  19575.               TypeCodeNew 
  19576.               TypeCode_alignment 
  19577.               TypeCode_kind 
  19578.               TypeCode_param_count 
  19579.               TypeCode_parameter 
  19580.               TypeCode_copy 
  19581.               TypeCode_free 
  19582.               TypeCode_print 
  19583.               TypeCode_setAlignment 
  19584.               TypeCode_size 
  19585.  
  19586.  
  19587. ΓòÉΓòÉΓòÉ 4.24. TypeCode_free ΓòÉΓòÉΓòÉ
  19588.  
  19589. TypeCode_free This function destroys a given TypeCode by freeing all of the 
  19590. memory used to represent it. 
  19591.  
  19592.  Syntax 
  19593.  
  19594.                     void TypeCode_free (TypeCode tc, Environment *env)
  19595.  
  19596.  Parameters 
  19597.  
  19598.           tc (TypeCode) 
  19599.                     The TypeCode to be freed. 
  19600.  
  19601.           env (Environment *) 
  19602.                     A pointer to an Environment structure. The CORBA standard 
  19603.                     mandates the use of this structure as a standard way to 
  19604.                     return exception information when an error condition is 
  19605.                     detected. 
  19606.  
  19607.  Returns 
  19608.  
  19609.           rc (void) 
  19610.  
  19611.  Remarks 
  19612.  
  19613.           The TypeCode_free function destroys a given TypeCode by freeing all 
  19614.           of the memory used to represent it. TypeCodes obtained from the 
  19615.           TypeCode_copy or TypeCodeNew functions should be freed using 
  19616.           TypeCode_free. TypeCodes contained in Interface Repository objects 
  19617.           should never be freed. Their memory is released when a _somFree 
  19618.           method releases the Interface Repository object. 
  19619.  
  19620.           The TypeCode_free operation has no effect on TypeCode constants. 
  19621.           TypeCode constants are static TypeCodes declared in the header file 
  19622.           "somtcnst.h" or generated in files emitted by the SOM Compiler. Since 
  19623.           TypeCode constants may be used interchangeably with dynamically 
  19624.           created TypeCodes, it is not considered an error to attempt to free a 
  19625.           TypeCode constant with the TypeCode_free function. 
  19626.  
  19627.           This function is a SOM-unique extension to the CORBA standard. 
  19628.  
  19629.  Related Information 
  19630.  
  19631.           Functions 
  19632.  
  19633.               TypeCodeNew 
  19634.               TypeCode_alignment 
  19635.               TypeCode_equal 
  19636.               TypeCode_kind 
  19637.               TypeCode_param_count 
  19638.               TypeCode_parameter 
  19639.               TypeCode_size 
  19640.               TypeCode_copy 
  19641.               TypeCode_print 
  19642.               TypeCode_setAlignment 
  19643.  
  19644.  
  19645. ΓòÉΓòÉΓòÉ 4.25. TypeCode_kind ΓòÉΓòÉΓòÉ
  19646.  
  19647. TypeCode_kind This function categorizes the abstract data type described by a 
  19648. TypeCode. 
  19649.  
  19650.  Syntax 
  19651.  
  19652.                     TCKind TypeCode_kind (TypeCode tc, Environment *env)
  19653.  
  19654.  Parameters 
  19655.  
  19656.           tc (TypeCode) 
  19657.                     The TypeCode whose TCKind categorization is requested. 
  19658.  
  19659.           env (Environment *) 
  19660.                     A pointer to an Environment structure. 
  19661.  
  19662.                     The CORBA standard mandates the use of this structure as a 
  19663.                     standard way to return exception information when an error 
  19664.                     condition is detected. 
  19665.  
  19666.  Returns 
  19667.  
  19668.           rc (TCKind) 
  19669.                     Returns one of the enumerators listed in the TCKind 
  19670.                     enumeration shown below. No exceptions are raised by this 
  19671.                     function. enum TCKind { tk_null, tk_void, tk_short, 
  19672.                     tk_long, tk_ushort, 
  19673.  
  19674.                                                tk_ulong, tk_float, tk_double, tk_boolean, tk_char,
  19675.                                                tk_octet, tk_any, tk_TypeCode, tk_Principal,
  19676.                                                tk_objref, tk_struct, tk_union, tk_enum, tk_string,
  19677.                                                tk_sequence, tk_array, tk_pointer, tk_self,
  19678.                                                tk_foreign
  19679.                                               };
  19680.  
  19681.  
  19682.  
  19683.  Remarks 
  19684.  
  19685.           The TypeCode_kind function can be used to classify a TypeCode into 
  19686.           one of the categories listed in the TCKind enumeration. Based on the 
  19687.           "kind" classification, a TypeCode may contain 0 or more additional 
  19688.           parameters to fully describe the underlying data type. 
  19689.  
  19690.           TypeCode information per TCKind category indicates the number and 
  19691.           function of these additional parameters. TCKind entries not listed in 
  19692.           the table are basic data types and do not have any additional 
  19693.           parameters. The designation "N" refers to the number of members in a 
  19694.           struct or union, or the number of enumerators in an enum. 
  19695.  
  19696.                     ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  19697.                     Γöé Table 1. TypeCode information per TCKind category                                   Γöé
  19698.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19699.                     Γöé TCKIND      Γöé  PARAMETERS  Γöé TYPE     Γöé FUNCTION                               Γöé
  19700.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19701.                     Γöé TK_OBJREF    Γöé    1    Γöé STRING    Γöé The ID of the corresponding INTERFACEDEF in the Interface      Γöé
  19702.                     Γöé         Γöé        Γöé        Γöé Repository                              Γöé
  19703.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19704.                     Γöé TK_STRUCT    Γöé    2N+1   Γöé STRING    Γöé The name of the STRUCT.                       Γöé
  19705.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19706.                     Γöé         Γöé        Γöé            ΓöÇΓöÇΓöÇΓöÇΓöÇ next 2 repeat for each member ΓöÇΓöÇΓöÇΓöÇΓöÇ           Γöé
  19707.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19708.                     Γöé         Γöé        Γöé STRING    Γöé The name of the STRUCT member.                    Γöé
  19709.                     Γöé         Γöé        Γöé TYPECODE   Γöé The type of the STRUCT member.                    Γöé
  19710.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19711.                     Γöé TK_UNION     Γöé    3N+2   Γöé STRING    Γöé The name of the UNION.                        Γöé
  19712.                     Γöé         Γöé        Γöé TYPECODE   Γöé The type of the discriminator.                    Γöé
  19713.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19714.                     Γöé         Γöé        Γöé            ΓöÇΓöÇΓöÇΓöÇΓöÇ next 3 repeat for each member ΓöÇΓöÇΓöÇΓöÇΓöÇ           Γöé
  19715.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19716.                     Γöé         Γöé        Γöé LONG     Γöé The label value                           Γöé
  19717.                     Γöé         Γöé        Γöé STRING    Γöé The name of the member.                       Γöé
  19718.                     Γöé         Γöé        Γöé TYPECODE   Γöé The type of the member.                       Γöé
  19719.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19720.                     Γöé TK_ENUM     Γöé    N+1    Γöé STRING    Γöé The name of the ENUM.                        Γöé
  19721.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19722.                     Γöé         Γöé        Γöé            ΓöÇΓöÇΓöÇ next repeats for each enumerator ΓöÇΓöÇΓöÇΓöÇ           Γöé
  19723.                     Γöé         Γöé        Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19724.                     Γöé         Γöé        Γöé STRING    Γöé The name of the enumerator.                     Γöé
  19725.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19726.                     Γöé TK_STRING    Γöé    1    Γöé LONG     Γöé The maximum string length or 0.                   Γöé
  19727.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19728.                     Γöé TK_SEQUENCE   Γöé    2    Γöé TYPECODE   Γöé The type of element in the sequence.                 Γöé
  19729.                     Γöé         Γöé        Γöé LONG     Γöé The maximum number of elements or 0.                 Γöé
  19730.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19731.                     Γöé TK_ARRAY     Γöé    2    Γöé TYPECODE   Γöé The type of element in the ARRAY.                  Γöé
  19732.                     Γöé         Γöé        Γöé LONG     Γöé The maximum number of elements.                   Γöé
  19733.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19734.                     Γöé TK_POINTER*   Γöé    1    Γöé TYPECODE   Γöé The type of the referenced datum.                  Γöé
  19735.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19736.                     Γöé TK_SELF*     Γöé    1    Γöé STRING    Γöé The name of the referenced enclosing STRUCT or UNION.        Γöé
  19737.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö╝ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19738.                     Γöé TK_FOREIGN*   Γöé    3    Γöé STRING    Γöé The name of the foreign type.                    Γöé
  19739.                     Γöé         Γöé        Γöé STRING    Γöé The implementation context.                     Γöé
  19740.                     Γöé         Γöé        Γöé LONG     Γöé The size of an instance.                       Γöé
  19741.                     Γö£ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöñ
  19742.                     Γöé * The TCKIND values TK_POINTER, TK_SELF, and TK_FOREIGN are SOM-unique extensions to the CORBA standard.  They are  Γöé
  19743.                     Γöé provided to permit TYPECODES to describe types that cannot be expressed in standard IDL.               Γöé
  19744.                     Γöé                                                            Γöé
  19745.                     Γöé The TK_POINTER TYPECODE contains only one parameter-a TYPECODE which describes the data type that the pointer refer- Γöé
  19746.                     Γöé ences.  The TK_SELF TYPECODE is used to describe a "self-referential" structure or union without introducing     Γöé
  19747.                     Γöé unbounded recursion in the TYPECODE.  For example, the following C struct:                      Γöé
  19748.                     Γöé                                                            Γöé
  19749.                     Γöé  struct node {                                                    Γöé
  19750.                     Γöé    long count;                                                   Γöé
  19751.                     Γöé    struct node *next;                                                Γöé
  19752.                     Γöé    };                                                        Γöé
  19753.                     Γöé                                                            Γöé
  19754.                     Γöé could be described with a TYPECODE created as follows:                                Γöé
  19755.                     Γöé                                                            Γöé
  19756.                     Γöé  TypeCode tcForNode;                                                 Γöé
  19757.                     Γöé  tcForNode = TypeCodeNew (tk_struct, "node",                                     Γöé
  19758.                     Γöé    "count", TypeCodeNew (tk_long),                                         Γöé
  19759.                     Γöé    "next", TypeCodeNew (tk_pointer,                                        Γöé
  19760.                     Γöé    TypeCodeNew (tk_self, "node")));                                        Γöé
  19761.                     Γöé                                                            Γöé
  19762.                     Γöé The TK_FOREIGN TYPECODE provides a more general escape mechanism, allowing TYPECODEs to be created that partially   Γöé
  19763.                     Γöé describe non-IDL types.  Since these foreign TYPECODEs carry only a partial description of a type, the "implementa-  Γöé
  19764.                     Γöé tion context" parameter can be used by a non-IDL execution environment to recognize other types that are known or   Γöé
  19765.                     Γöé understood in that environment.  See the section entitled "Using the tk_foreign TypeCode" in Chapter 7 of the SOM   Γöé
  19766.                     Γöé Programming Guide for more information about using foreign TYPECODES in SOM IDL files.                Γöé
  19767.                     Γöé                                                            Γöé
  19768.                     Γöé Note that the use of self-referential structures, pointers, or foreign types is beyond the scope of the CORBA     Γöé
  19769.                     Γöé standard, and may result in a loss of portability or distributability in client code.                 Γöé
  19770.                     ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  19771.  
  19772.  Original Class 
  19773.  
  19774.           TypeDef 
  19775.  
  19776.  Related Information 
  19777.  
  19778.           Functions: 
  19779.  
  19780.               TypeCodeNew 
  19781.               TypeCode_alignment 
  19782.               TypeCode_equal 
  19783.               TypeCode_param_count 
  19784.               TypeCode_parameter 
  19785.               TypeCode_copy 
  19786.               TypeCode_free 
  19787.               TypeCode_print 
  19788.               TypeCode_setAlignment 
  19789.               TypeCode_size 
  19790.  
  19791.  
  19792. ΓòÉΓòÉΓòÉ 4.26. TypeCodeNew ΓòÉΓòÉΓòÉ
  19793.  
  19794. TypeCodeNew This function creates a new TypeCode instance. 
  19795.  
  19796.  Syntax 
  19797.  
  19798.                     TypeCode TypeCodeNew (TCKind tag, string interfaceID, string name,
  19799.                                    string mbrName, string EnumId,
  19800.                                    string structOrUnionName, long maxLength,
  19801.                                    long length, long flag, long labelValue,
  19802.                                    TypeCode mbrTC, TypeCode swTC,
  19803.                                    TypeCode seqTC, TypeCode arrayTC,
  19804.                                    TypeCode ptrTC, string typename,
  19805.                                    string impCtx, long instSize,
  19806.                                    TCKind allOtherTagValues)
  19807.  
  19808.  Parameters 
  19809.  
  19810.           tag (TCKind) 
  19811.                     The type or category of TypeCode to create. The actual 
  19812.                     parameters that follow are variable in number and type, 
  19813.                     depending on the value of the tag paramater.  (There are no 
  19814.                     implicit parameters in this function.)  See the remarks 
  19815.                     section for the syntax form appropriate for each kind of 
  19816.                     TCKind tag. 
  19817.  
  19818.           interfaceID (string) 
  19819.                     A string containing the fully-qualified interface name that 
  19820.                     is the subject of an object reference type. 
  19821.  
  19822.           name (string) 
  19823.                     A string that gives the name of a struct, union, or enum. 
  19824.  
  19825.           mbrName (string) 
  19826.                     A string that gives the name of a struct or union member 
  19827.                     element. 
  19828.  
  19829.           EnumId (string) 
  19830.                     A string that gives the name of an enum enumerator. 
  19831.  
  19832.           structOrUnionName (string) 
  19833.                     A string that gives the name of a struct or union that has 
  19834.                     been previously named in the current TypeCode and is the 
  19835.                     subject of a self-referential pointer type. See the 
  19836.                     footnote on tk_self in Table 1 for an example of what this 
  19837.                     means and how it is applied. 
  19838.  
  19839.           maxLength (long) 
  19840.                     The maximum permitted length of a string or a sequence. The 
  19841.                     value 0 (zero) means that the string or sequence is 
  19842.                     considered unbounded. 
  19843.  
  19844.           length (long) 
  19845.                     The maximum number of elements that can be stored in an 
  19846.                     array. All IDL arrays are bounded, hence a value of zero 
  19847.                     denotes an array of zero elements. 
  19848.  
  19849.           flag (long) 
  19850.                     One of the following constant values used to distinguish a 
  19851.                     labeled case in an IDL discriminated union switch statement 
  19852.                     from the default case: 
  19853.  
  19854.                                         TCREGULAR_CASE - The value 1
  19855.                                         TCDEFAULT_CASE - The value 2
  19856.  
  19857.           labelValue (long) 
  19858.                     The actual value associated with a regular labeled case in 
  19859.                     an IDL discriminated union switch statement. If preceded by 
  19860.                     the argument TCDEFAULT_CASE, the value zero should be used. 
  19861.  
  19862.           mbrTC (TypeCode) 
  19863.                     A TypeCode that represents the data type of a struct or 
  19864.                     union member. 
  19865.  
  19866.           swTC (TypeCode) 
  19867.                     A TypeCode that represents the data type of the 
  19868.                     discriminator in an IDL union statement. 
  19869.  
  19870.           seqTC (TypeCode) 
  19871.                     A TypeCode that describes the data type of the elements in 
  19872.                     a sequence. 
  19873.  
  19874.           arrayTC (TypeCode) 
  19875.                     A TypeCode that describes the data type of the elements of 
  19876.                     an array. 
  19877.  
  19878.           ptrTC (TypeCode) 
  19879.                     A TypeCode that describes the data type referenced by a 
  19880.                     pointer. 
  19881.  
  19882.           typename (string) 
  19883.                     A string that provides the name of a foreign type. 
  19884.  
  19885.           impCtx (string) 
  19886.                     A string that identifies an implementation context where a 
  19887.                     foreign type is understood. 
  19888.  
  19889.           instSize (long) 
  19890.                     A long that holds the size of a foreign type instance. If 
  19891.                     the size is variable or is not known, the value zero should 
  19892.                     be used. 
  19893.  
  19894.           allOtherTagValues (TCKind) 
  19895.                     One of the values: tk_null, tk_void, tk_short, tk_long, 
  19896.                     tk_ushort, tk_ulong, tk_float, tk_double, tk_boolean, 
  19897.                     tk_char, tk_octet, tk_any, tk_TypeCode, or Tk_Principal. 
  19898.                     All of these tags represent basic IDL data types that do 
  19899.                     not require any other descriptive parameters. 
  19900.  
  19901.  Returns 
  19902.  
  19903.           rc (TypeCode) 
  19904.                     A new TypeCode instance, or NULL if the new instance could 
  19905.                     not be created. 
  19906.  
  19907.  Remarks 
  19908.  
  19909.           The TypeCodeNew function creates a new instance of a TypeCode from 
  19910.           the supplied parameters. TypeCodes are complex data structures whose 
  19911.           actual representation is hidden. The number and types of arguments 
  19912.           required by TypeCodeNew varies depending on the value of the first 
  19913.           argument. The syntax for all of the valid invocation sequences are as 
  19914.           follows: 
  19915.  
  19916.                     TyepCodeNew(tk_objref, string interfaceld);
  19917.                     TypeCodeNew(tk_string, long maxLength);
  19918.                     TypeCodeNew(tk_sequence, TypeCode seqTC, long maxLength);
  19919.                     TypeCodeNew(tk_array, TypeCodearrayTC, long length);
  19920.                     TypeCodeNew(tk_pointer, TypeCode ptrTC);
  19921.                     TypeCodeNew(tk_self, string structOrUnionName);
  19922.                     TypeCodeNew(tk_foreign, string typename, string impCtx, long instSize);
  19923.                     TypeCodeNew(tk_struct, string name, string mbrname,
  19924.                     TypeCode mbrTC,[...,]
  19925.                     [mbrName and mbrTC repeat as needed]
  19926.                     NULL);
  19927.                     TypeCodeNew (tk_union, string name, TypeCode swTC,
  19928.                     longflag, long labelValue, string
  19929.                     mbrName, TypeCode mbrTC,[...,]
  19930.                     [flag, labelValue, mbrName and mbrTC repeat as needed]
  19931.                     NULL);
  19932.                     TypeCodeNew(tk_enum, string name, string enumld,[...,]
  19933.                     [enumlds repeat as needed]
  19934.                     NULL);
  19935.                     TypeCodeNew(TCKindall OtherTAgValues);
  19936.  
  19937.           All TypeCodes created by TypeCodeNew should be destroyed (when no 
  19938.           longer needed) using the TypeCode_free function. 
  19939.  
  19940.           This function is a SOM-unique extension to the CORBA standard. 
  19941.  
  19942.  Related Information 
  19943.  
  19944.           Functions 
  19945.  
  19946.               TypeCode_alignment 
  19947.               TypeCode_copy 
  19948.               TypeCode_equal 
  19949.               TypeCode_free 
  19950.               TypeCode_kind 
  19951.               TypeCode_param_count 
  19952.               TypeCode_parameter 
  19953.               TypeCode_print 
  19954.               TypeCode_size 
  19955.               TypeCode_setAlignment 
  19956.  
  19957.  
  19958. ΓòÉΓòÉΓòÉ 4.27. TypeCode_param_count ΓòÉΓòÉΓòÉ
  19959.  
  19960. TypeCode_param_count This function obtains the number of parameters available 
  19961. in a given TypeCode. 
  19962.  
  19963.  Syntax 
  19964.  
  19965.                     long TypeCode_param_count (TypeCode tc, Environment *env)
  19966.  
  19967.  Parameters 
  19968.  
  19969.           tc (TypeCode) 
  19970.                     The TypeCode whose parameter count is desired. 
  19971.  
  19972.           env (Environment *) 
  19973.                     A pointer to an Environment structure. The CORBA standard 
  19974.                     mandates the use of this structure as a standard way to 
  19975.                     return exception information when an error condition is 
  19976.                     detected. 
  19977.  
  19978.  Returns 
  19979.  
  19980.           rc (long) 
  19981.                     Returns the actual number of parameters associated with the 
  19982.                     given TypeCode, in accordance with Table 1. No exceptions 
  19983.                     are raised by this function. 
  19984.  
  19985.  Remarks 
  19986.  
  19987.           The TypeCode_param_count function can be used to obtain the actual 
  19988.           number of parameters contained in a specified TypeCode. Each TypeCode 
  19989.           contains sufficient parameters to fully describe its underlying 
  19990.           abstract data type. Refer to Table 1. 
  19991.  
  19992.  Related Information 
  19993.  
  19994.           Functions 
  19995.  
  19996.               TypeCodeNew 
  19997.               TypeCode_alignment 
  19998.               TypeCode_equal 
  19999.               TypeCode_kind 
  20000.               TypeCode_parameter 
  20001.               TypeCode_copy 
  20002.               TypeCode_free 
  20003.               TypeCode_print 
  20004.               TypeCode_size 
  20005.               TypeCode_setAlignment 
  20006.  
  20007.  
  20008. ΓòÉΓòÉΓòÉ 4.28. TypeCode_parameter ΓòÉΓòÉΓòÉ
  20009.  
  20010. TypeCode_parameter This function obtains a specified parameter from a given 
  20011. TypeCode. 
  20012.  
  20013.  Syntax 
  20014.  
  20015.                     any TypeCode_parameter (TypeCode tc, Environment *env, long index)
  20016.  
  20017.  Parameters 
  20018.  
  20019.           tc (TypeCode) 
  20020.                     The TypeCode whose parameter is desired. 
  20021.  
  20022.           env (Environment *) 
  20023.                     A pointer to an Environment structure. The CORBA standard 
  20024.                     mandates the use of this structure as a standard way to 
  20025.                     return exception information when an error condition is 
  20026.                     detected. 
  20027.  
  20028.           index (long) 
  20029.                     The number of the desired parameter. Parameters are 
  20030.                     numbered from 0 to N-1, where N is the value returned by 
  20031.                     the Typecode_param_count function. 
  20032.  
  20033.  Returns 
  20034.  
  20035.           rc (any) 
  20036.                     Returns the requested parameter in the form of an any. This 
  20037.                     function raises the Bounds exception if the value of the 
  20038.                     index exceeds the number of parameters available in the 
  20039.                     given TypeCode. Because the values exist within the 
  20040.                     specified TypeCode, you should not free the results 
  20041.                     returned from this function. 
  20042.  
  20043.                     A bounds exception is also raised if this function is 
  20044.                     called on any of the IDL basic data types (see note above). 
  20045.  
  20046.                     An any is a basic IDL data type that is represented as the 
  20047.                     following structure in C or C++: 
  20048.  
  20049.                                         typedef struct any {
  20050.                                             TypeCode _type;
  20051.                                             void *   _value;
  20052.                                         } any;
  20053.  
  20054.                     Since all TypeCode parameters have one of only three types 
  20055.                     (string, TypeCode, or long), the _type member will always 
  20056.                     be set to TC_string, TC_TypeCode, or TC_long, as 
  20057.                     appropriate. The _value member always points to the actual 
  20058.                     parameter datum. For example, the following code can be 
  20059.                     used to extract the name of a structure from a TypeCode of 
  20060.                     kind tk_struct in C: 
  20061.  
  20062.                                         #include <repostry.h>  /* Interface Repository class */
  20063.                                         #include <typedef.h>   /* Interface Repository TypeDef class */
  20064.                                         #include <somtcnst.h>  /* TypeCode constants */
  20065.                                         TypeCode x;
  20066.                                         Environment *ev = somGetGlobalEnvironment ();
  20067.                                         TypeDef aTypeDefObj;
  20068.                                         sequence(Contained) sc;
  20069.                                         any parm;
  20070.                                         string name;
  20071.                                         Repository repo;
  20072.  
  20073.                                         ...
  20074.  
  20075.                                         /* 1st, obtain a TypeCode from an Interface Repository object,
  20076.                                          * or use a TypeCode constant.
  20077.                                          */
  20078.  
  20079.                                         repo = RepositoryNew ();
  20080.                                         sc = _lookup_name (repo, ev,
  20081.                                              "AttributeDescription", -1, "TypeDef", TRUE);
  20082.                                         if (sc._length) {
  20083.                                             aTypeDefObj = sc._buffer[0];
  20084.                                             x = __get_type (aTypeDefObj, ev);
  20085.                                             }
  20086.                                         else
  20087.                                             x = TC_AttributeDescription;
  20088.  
  20089.                                         if (TypeCode_kind (x, ev) == tk_struct) {
  20090.                                             parm = TypeCode_parameter (x, ev, 0); /* Get structure name */
  20091.                                             if (TypeCode_kind (parm._type, ev) != tk_string) {
  20092.                                                 printf ("Error, unexpected TypeCode: ");
  20093.                                                 TypeCode_print (parm._type, ev);
  20094.                                             } else {
  20095.                                                 name = *((string *)parm._value);
  20096.                                                 printf ("The struct name is %s\n", name);
  20097.                                             }
  20098.                                         } else {
  20099.                                             printf ("TypeCode is not a tk_struct: ");
  20100.                                             TypeCode_print (x, ev);
  20101.                                         }
  20102.  
  20103.  Remarks 
  20104.  
  20105.           The TypeCode_parameter function can be used to obtain any of the 
  20106.           parameters contained in a given TypeCode. Refer to Table 1 for a list 
  20107.           of the number and type of parameters associated with each category of 
  20108.           TypeCode. 
  20109.  
  20110.           Note: This function should not be used for any of the IDL basic data 
  20111.           types (that is, any types in the TCKind enumeration that are not 
  20112.           listed in table 1 under the TypeCode_Kind function). 
  20113.  
  20114.  Related Information 
  20115.  
  20116.           Functions 
  20117.  
  20118.               TypeCodeNew 
  20119.               TypeCode_alignment 
  20120.               TypeCode_equal 
  20121.               TypeCode_kind 
  20122.               TypeCode_param_count 
  20123.               TypeCode_copy 
  20124.               TypeCode_free 
  20125.               TypeCode_print 
  20126.               TypeCode_size 
  20127.               TypeCode_setAlignment 
  20128.  
  20129.  
  20130. ΓòÉΓòÉΓòÉ 4.29. TypeCode_print ΓòÉΓòÉΓòÉ
  20131.  
  20132. TypeCode_print This function writes all of the information contained in a given 
  20133. TypeCode to "stdout". 
  20134.  
  20135.  Syntax 
  20136.  
  20137.                     void TypeCode_print (TypeCode tc, Environment *env)
  20138.  
  20139.  Parameters 
  20140.  
  20141.           tc (TypeCode) 
  20142.                     The TypeCode to be examined. 
  20143.  
  20144.           env (Environment *) 
  20145.                     A pointer to an Environment structure. The CORBA standard 
  20146.                     mandates the use of this structure as a standard way to 
  20147.                     return exception information when an error condition is 
  20148.                     detected. 
  20149.  
  20150.  Returns 
  20151.  
  20152.           rc (void) 
  20153.  
  20154.  Remarks 
  20155.  
  20156.           The TypeCode_print function can be used during program debugging to 
  20157.           inspect the contents of a TypeCode. It prints (in a human-readable 
  20158.           format) all of the information contained in the TypeCode. The format 
  20159.           of the information shown by TypeCode_print is the same form that 
  20160.           could be used by a C programmer to code the corresponding TypeCodeNew 
  20161.           function call to create the TypeCode. 
  20162.  
  20163.           This function is a SOM-unique extension to the CORBA standard. 
  20164.  
  20165.  Related Information 
  20166.  
  20167.           Functions 
  20168.  
  20169.               TypeCodeNew 
  20170.               TypeCode_alignment 
  20171.               TypeCode_equal 
  20172.               TypeCode_kind 
  20173.               TypeCode_param_count 
  20174.               TypeCode_parameter 
  20175.               TypeCode_copy 
  20176.               TypeCode_free 
  20177.               TypeCode_size 
  20178.               TypeCode_setAlignment 
  20179.  
  20180.  
  20181. ΓòÉΓòÉΓòÉ 4.30. TypeCode_setAlignment ΓòÉΓòÉΓòÉ
  20182.  
  20183. TypeCode_setAlignment This function sets the alignment value for a given 
  20184. TypeCode. 
  20185.  
  20186.  Syntax 
  20187.  
  20188.                     void TypeCode_setAlignment (TypeCode tc, Environment *env,
  20189.                                      short alignment)
  20190.  
  20191.  Parameters 
  20192.  
  20193.           tc (TypeCode) 
  20194.                     The TypeCode to receive the new alignment value. 
  20195.  
  20196.           env (Environment *) 
  20197.                     A pointer to an Environment structure. 
  20198.  
  20199.           alignment (short) 
  20200.                     A short integer that specifies the alignment value. 
  20201.  
  20202.  Returns 
  20203.  
  20204.           rc (void) 
  20205.  
  20206.  Related Information 
  20207.  
  20208.           Functions 
  20209.  
  20210.               TypeCodeNew 
  20211.               TypeCode_alignment 
  20212.               TypeCode_equal 
  20213.               TypeCode_kind 
  20214.               TypeCode_param_count 
  20215.               TypeCode_parameter 
  20216.               TypeCode_size 
  20217.               TypeCode_free 
  20218.               TypeCode_print 
  20219.  
  20220.  
  20221. ΓòÉΓòÉΓòÉ 4.31. TypeCode_size ΓòÉΓòÉΓòÉ
  20222.  
  20223. TypeCode_size This function provides the size of an instance of the abstract 
  20224. data type described by a given TypeCode. 
  20225.  
  20226.  Syntax 
  20227.  
  20228.                     long TypeCode_size (TypeCode tc, Environment *env)
  20229.  
  20230.  Parameters 
  20231.  
  20232.           tc (TypeCode) 
  20233.                     The TypeCode whose instance size is desired. 
  20234.  
  20235.           env (Environment *) 
  20236.                     A pointer to an Environment structure. The CORBA standard 
  20237.                     mandates the use of this structure as a standard way to 
  20238.                     return exception information when an error condition is 
  20239.                     detected. 
  20240.  
  20241.  Returns 
  20242.  
  20243.           rc (long) 
  20244.                     The amount of memory needed to hold an instance of the data 
  20245.                     type described by a given TypeCode. No exceptions are 
  20246.                     raised by this function. 
  20247.  
  20248.  Remarks 
  20249.  
  20250.           The TypeCode_size function is used to obtain the size of an instance 
  20251.           of the abstract data type described by a given TypeCode. 
  20252.  
  20253.           This function is a SOM-unique extension to the CORBA standard. 
  20254.  
  20255.  Related Information 
  20256.  
  20257.           Funtions 
  20258.  
  20259.               TypeCodeNew 
  20260.               TypeCode_alignment 
  20261.               TypeCode_equal 
  20262.               TypeCode_kind 
  20263.               TypeCode_param_count 
  20264.               TypeCode_parameter 
  20265.               TypeCode_copy 
  20266.               TypeCode_free 
  20267.               TypeCode_print 
  20268.               TypeCode_setAlignment 
  20269.  
  20270.  
  20271. ΓòÉΓòÉΓòÉ 5. Metaclass Framework Reference ΓòÉΓòÉΓòÉ
  20272.  
  20273.  
  20274. Metaclass class organization
  20275.  
  20276.  
  20277. ΓòÉΓòÉΓòÉ 5.1. SOMMBeforeAfter Metaclass ΓòÉΓòÉΓòÉ
  20278.  
  20279. SOMMBeforeAfter Metaclass 
  20280.  
  20281.  File stem: sombacls 
  20282.  
  20283.  Description 
  20284.  
  20285.           SOMMBeforeAfteris a metaclass that defines two methods 
  20286.           (sommBeforeMethod and sommAfterMethod) which are invoke before and 
  20287.           after each invocation of every instance method. SOMMBeforeAfter is 
  20288.           designed to be subclassed. Within the subclass, each of the two 
  20289.           methods should be overridden with a method procedure appropriate to 
  20290.           the particular application. The before and after methods are invoked 
  20291.           on instances (ordinary objects) of a class whose metaclass is the 
  20292.           subclass (or child) of SOMMBeforeAfter, whenever any method 
  20293.           (inherited  or introduced) of the class is invoked. 
  20294.  
  20295.           Caution: The somDefaultInit and somFree methods are among th methods 
  20296.           that get before/after behavior. This implies that the following two 
  20297.           obligations are imposed on the programmer of a SOMMBeforeAfter class. 
  20298.           First, your implementation must guard against calling the 
  20299.           sommBeforeMethod before somDefaultInit has executed, when the object 
  20300.           is not yet fully initialized. Second, the implementation must guard 
  20301.           against calling sommAfterMethod after somFree at which time the 
  20302.           object no longer exists. 
  20303.  
  20304.  New methods 
  20305.  
  20306.           None 
  20307.  
  20308.  Overridden methods 
  20309.  
  20310.           somDefaultInit, somInitMIClass 
  20311.  
  20312.  
  20313. ΓòÉΓòÉΓòÉ 5.2. sommAfterMethod ΓòÉΓòÉΓòÉ
  20314.  
  20315. sommAfterMethod Specifies a method that is automatically called after execution 
  20316. of each client Method. 
  20317.  
  20318.  Syntax 
  20319.  
  20320.                     void sommAfterMethod (SOMMBeforeAfter receiver,
  20321.                                  Environment *env, SOMObject object,
  20322.                                  somId methodId, void *returnedvalue,
  20323.                                  va_list ap)
  20324.  
  20325.  Parameters 
  20326.  
  20327.           receiver (SOMMBeforeAfter) 
  20328.                     A pointer to an object (class) of metaclass SOMMBeforeAfter 
  20329.                     representing the class object that supports the method 
  20330.                     (such as, "myMethod") for which the "after" method will 
  20331.                     apply. 
  20332.  
  20333.           env (Environment *) 
  20334.                     A pointer where the method can return exception information 
  20335.                     if an error is encountered. The dispatch method of 
  20336.                     SOMMBeforeAfter sets this parameter to NULL before 
  20337.                     dispatching the first sommBeforeMethod. 
  20338.  
  20339.           object (SOMObject) 
  20340.                     A pointer to the instance of the receiver on which the 
  20341.                     method is invoked. 
  20342.  
  20343.           methodId (somId) 
  20344.                     The SOM ID of the method (such as, "myMethod") that was 
  20345.                     invoked. 
  20346.  
  20347.           returnedvalue (void *) 
  20348.                     A pointer to the value returned by invoking the method 
  20349.                     ("myMethod") on an object. 
  20350.  
  20351.           ap (va_list) 
  20352.                     The list of input arguments to the method ("myMethod"). 
  20353.  
  20354.  Returns 
  20355.  
  20356.           rc (void) 
  20357.  
  20358.  Remarks 
  20359.  
  20360.           The sommAfterMethod specifies a method that is automatically called 
  20361.           after execution of each client method. The sommAfterMethod method is 
  20362.           introduced in the SOMMBeforeAfter metaclass. The default 
  20363.           implementation does nothing until it is overridden. The 
  20364.           sommAfterMethod method is not called directly by the user. To define 
  20365.           the desired "after" method, sommAfterMethod must be overridden in a 
  20366.           metaclass that is a subclass (child) of the SOMMBeforeAfter 
  20367.           metaclass. 
  20368.  
  20369.           Caution:  somFree is among the methods that get before/after 
  20370.           behavior, which implies that the following obligation is imposed on 
  20371.           the programmer of a sommAfterMethod. Specifically, care must be taken 
  20372.           to guard against sommAfterMethod being called after somFree, at which 
  20373.           time the object no longer exists. 
  20374.  
  20375.           The following figure shows an invocation of "myMethod" on "myObject". 
  20376.           Because "myObject" is an instance of a class whose metaclass is a 
  20377.           subclass of SOMMBeforeAfter, "myMethod" is followed by an invocation 
  20378.           of sommAfterMethod (which is shown in smaller type to denote that the 
  20379.           user does not actually code the method). The adjacent figure 
  20380.           illustrates the meaning of the parameters to sommAfterMethod. 
  20381.  
  20382.  Original Class 
  20383.  
  20384.           SOMMBeforeAfter 
  20385.  
  20386.  Related Methods 
  20387.  
  20388.           Methods 
  20389.  
  20390.               sommBeforeMethod 
  20391.  
  20392.  
  20393. ΓòÉΓòÉΓòÉ 5.3. sommBeforeMethod ΓòÉΓòÉΓòÉ
  20394.  
  20395. sommBeforeMethod Specifies a method that is automatically called before 
  20396. execution of each client method. 
  20397.  
  20398.  Syntax 
  20399.  
  20400.                     boolean sommBeforeMethod (SOMMBeforeAfter receiver,
  20401.                                     Environment *env, SOMObject object,
  20402.                                     somID methodId, va_list ap)
  20403.  
  20404.  Parameters 
  20405.  
  20406.           receiver (SOMMBeforeAfter) 
  20407.                     A pointer to an object (class) of metaclass SOMMBeforeAfter 
  20408.                     representing the class object that supports the method 
  20409.                     (such as, "myMethod") for which the "before" method will 
  20410.                     apply. 
  20411.  
  20412.           env (Environment *) 
  20413.                     A pointer where the method can return exception information 
  20414.                     if an error is encountered. The dispatch method of 
  20415.                     SOMMBeforeAfter sets this parameter to NULL before 
  20416.                     dispatching the first sommBeforeMethod. 
  20417.  
  20418.           object (SOMObject) 
  20419.                     A pointer to the instance of the receiver on which the 
  20420.                     method is invoked. 
  20421.  
  20422.           methodId (somID) 
  20423.                     The SOM Id of the method (such as, "myMethod") that was 
  20424.                     invoked. 
  20425.  
  20426.           ap (va_list) 
  20427.                     The list of input arguments to the method ("myMethod"). 
  20428.  
  20429.  Returns 
  20430.  
  20431.           rc (boolean) 
  20432.                     A boolean that indicates whether or not before/after 
  20433.                     dispatching should continue. If the value is TRUE, normal 
  20434.                     before/after dispatching continues. If the value is FALSE, 
  20435.                     the dispatching skips to the sommAfterMethod associated 
  20436.                     with the preceding sommBeforeMethod. This implies that the 
  20437.                     sommBeforeMethod must do any post-processing that might 
  20438.                     otherwise be done by the sommAfterMethod. Because 
  20439.                     before/after methods are paired within a SOMMBeforeAfter 
  20440.                     metaclass, this designe liminates the complexity of 
  20441.                     communicating to the sommAfterMethod that the 
  20442.                     sommBeforeMethod returned FALSE. 
  20443.  
  20444.  Remarks 
  20445.  
  20446.           The sommBeforeMethod specifies a method that is automatically called 
  20447.           before execution of each client method. The sommBeforeMethod method 
  20448.           is not called directly by the user. To define the desired "before" 
  20449.           method, sommBeforeMethod must be overridden in a metaclass that is a 
  20450.           subclass (child) of SOMMBeforeAfter. The default implementation does 
  20451.           nothing until it is overridden. 
  20452.  
  20453.           Caution:  somDefaultInit is among the methods that get before/after 
  20454.           behavior, which implies that the following obligation is imposed on 
  20455.           the programmer of a sommBeforeMethod. Specifically, care must be 
  20456.           taken to guard against sommBeforeMethod being called before the 
  20457.           somDefaultInit method has executed and the object is not yet fully 
  20458.           initialized. 
  20459.  
  20460.           The following figure shows an invocation of "myMethod" on "myObject". 
  20461.           Because "myObject" is an instance of a class whose metaclass is a 
  20462.           subclass of SOMMBeforeAfter, "myMethod" is preceded by an invocation 
  20463.           of sommBeforeMethod (which is shown in smaller type to denote that 
  20464.           the user does not actually code the method). The adjacent figure 
  20465.           illustrates the meaning of the parameters to sommBeforeMethod. 
  20466.  
  20467.  Original Class 
  20468.  
  20469.           SOMMBeforeAfter 
  20470.  
  20471.  Related Methods 
  20472.  
  20473.           Methods 
  20474.  
  20475.               sommAfterMethod 
  20476.  
  20477.  
  20478. ΓòÉΓòÉΓòÉ 5.4. SOMMSingleInstance ΓòÉΓòÉΓòÉ
  20479.  
  20480. SOMMSingleInstance 
  20481.  
  20482.  File stem: snglicls 
  20483.  
  20484.  Base 
  20485.  
  20486.           SOMClass 
  20487.  
  20488.  Metaclass 
  20489.  
  20490.           SOMClass 
  20491.  
  20492.  Ancestor Classes 
  20493.  
  20494.                     SOMClass
  20495.                         SOMObject
  20496.  
  20497.  Description 
  20498.  
  20499.           SOMMSingleInstance is a metaclass provided with the SOM Toolkit. It 
  20500.           can be specified as the metaclass when defining a class for which 
  20501.           only one instance can ever be created. The first call to 
  20502.           <className>New in C, the new operator in C++, or the somNew method 
  20503.           creates the one possible instance of the class. Thereafter, any 
  20504.           subsequent "new" calls return the first (and only) instance. 
  20505.           SOMMSingleInstance is thread safe. 
  20506.  
  20507.           Alternatively, the method sommGetSingleInstance can be used to 
  20508.           accomplish the same purpose. The method offers an advantage in that 
  20509.           the call site explicitly shows that something special is occurring 
  20510.           and that a new object is not necessarily being created. 
  20511.  
  20512.  New methods 
  20513.  
  20514.           The following list shows all the SOMMSingleInstance methods. 
  20515.  
  20516.               sommGetSingleInstance 
  20517.  
  20518.  Overridden methods 
  20519.  
  20520.           The following list shows all the methods overridden by the 
  20521.           SOMMSingleInstance class. These methods are overridden in order to 
  20522.           modify the behavior defined by an ancestor class. 
  20523.  
  20524.               somInit 
  20525.               somNew 
  20526.  
  20527.  
  20528. ΓòÉΓòÉΓòÉ 5.5. sommGetSingleInstance ΓòÉΓòÉΓòÉ
  20529.  
  20530. sommGetSingleInstance This method gets the one instance of a specified class 
  20531. for which only a single instance can exist. 
  20532.  
  20533.  Syntax 
  20534.  
  20535.                     SOMObject sommGetSingleInstance (SOMMSingleInstance receiver,
  20536.                                        Environment *env)
  20537.  
  20538.  Parameters 
  20539.  
  20540.           receiver (SOMMSingleInstance) 
  20541.                     A pointer to an object (class) whose metaclass is 
  20542.                     SOMMSingleInstance (or is a subclass of it). 
  20543.  
  20544.           env (Environment *) 
  20545.                     A pointer where the method can return exception information 
  20546.                     if an error is encountered. 
  20547.  
  20548.  Returns 
  20549.  
  20550.           rc (SOMObject) 
  20551.                     Returns a pointer to the single instance of the specified 
  20552.                     class. 
  20553.  
  20554.  Remarks 
  20555.  
  20556.           The sommGetSingleInstance method gets a pointer to the one instance 
  20557.           of a class for which only a single instance can exist. A class can 
  20558.           have only a single instance when its metaclass is the 
  20559.           SOMMSingleInstance metaclass (or is a subclass of it). 
  20560.  
  20561.           The first call to <className>New in C, the new operator in C++, or 
  20562.           the somNew method creates the one possible instance of the class. 
  20563.           Thereafter, any subsequent "new" calls return the first (and only) 
  20564.           instance. Using the sommGetSingleInstance method, however, offers an 
  20565.           advantage in that the call site explicitly shows that something 
  20566.           special is occurring and that a new object is not necessarily being 
  20567.           created. (That is, the sommGetSingleInstance method creates the 
  20568.           single instance if it does not already exist.) 
  20569.  
  20570.  Original Class 
  20571.  
  20572.           SOMMGetSingleInstance 
  20573.  
  20574.  Example Code 
  20575.  
  20576.                     x1  = XXXNew();
  20577.                     x2  = XXXNew();
  20578.                     assert( x1 == x2 );
  20579.                     x3 = _sommGetSingleInstance(  _somGetClass( x1 ), env );
  20580.                     assert( x2 == x3 );
  20581.  
  20582.           Note that the method sommGetSingleInstance is invoked on the class 
  20583.           object, because sommGetSingleInstance is a method introduced by the 
  20584.           metaclass SOMMSingleInstance. 
  20585.  
  20586.  
  20587. ΓòÉΓòÉΓòÉ 5.6. SOMMTraced Metaclass ΓòÉΓòÉΓòÉ
  20588.  
  20589. SOMMTraced Metaclass 
  20590.  
  20591.  File stem: somtrcls 
  20592.  
  20593.  Base 
  20594.  
  20595.           Base Class 
  20596.  
  20597.  Ancestor Classes 
  20598.  
  20599.                     SOMMBeforeAfter, SOMClass, SOMObject
  20600.  
  20601.  Description 
  20602.  
  20603.           SOMMTraced is a metaclass that facilitates tracing of method 
  20604.           invocations. Whenever a method (inherited or introduced) is invoked 
  20605.           on an instance (simple object) of a class whose metaclass is 
  20606.           SOMMTraced, a message prints to standard output giving the method 
  20607.           parameters; then, after completion, a second message prints giving 
  20608.           the returned value. 
  20609.  
  20610.           There is one more step for using SOMMTraced: nothing print unless the 
  20611.           environment variable SOMM_TRACED is set. If it is set to the empty 
  20612.           string, all traced classes print. If the environment variable 
  20613.           SOMM_TRACED is not the empty string, it should be set to the list of 
  20614.           names of classes that should be traced. For example, for csh users, 
  20615.           the following command turns on printing of the trace for "Collie" and 
  20616.           "Chihuahua", but not for any other traced class: 
  20617.  
  20618.           setenv SOMM_TRACED "Collie Chihuahua" 
  20619.  
  20620.           SOMMTraced is thread-safe. 
  20621.  
  20622.           Attributes 
  20623.  
  20624.           Boolean SOMMTraceIsOn.  This attribute indicates whether or not 
  20625.           tracing is turned on for a class.  This gives dynamic control over 
  20626.           the trace facility. 
  20627.  
  20628.  New methods 
  20629.  
  20630.           None 
  20631.  
  20632.  Overridden methods 
  20633.  
  20634.           somInitMIClass, sommBeforeMethod, sommAfterMethod 
  20635.  
  20636.  
  20637. ΓòÉΓòÉΓòÉ 6. Event Management Framework Reference ΓòÉΓòÉΓòÉ
  20638.  
  20639.  
  20640. Event Management Framework Class Organization
  20641.  
  20642.  
  20643. ΓòÉΓòÉΓòÉ 6.1. SOMEClientEvent ΓòÉΓòÉΓòÉ
  20644.  
  20645. SOMEClientEvent 
  20646.  
  20647.  File stem: clientev 
  20648.  
  20649.  Base 
  20650.  
  20651.           SOMEEvent 
  20652.  
  20653.  Metaclass 
  20654.  
  20655.           SOMClass 
  20656.  
  20657.  Ancestor Classes 
  20658.  
  20659.                     SOMEEvent
  20660.                         SOMObject
  20661.  
  20662.  Description 
  20663.  
  20664.           This class describes generic client events within the Event Manager. 
  20665.           Client Events are defined, created, processed and destroyed entirely 
  20666.           by the application. The application can queue several types of client 
  20667.           events with EMan. When a client event occurs, EMan passes an instance 
  20668.           of this class to the callback routine. The callback can query this 
  20669.           object about its type and obtain any event-specific information. 
  20670.  
  20671.  New methods 
  20672.  
  20673.           The following list shows all the SOMEClientEvent methods. 
  20674.  
  20675.               somevGetEventClientData 
  20676.               somevGetEventClientType 
  20677.               somevSetEventClientData 
  20678.               somevSetEventClientType 
  20679.  
  20680.  Overridden methods 
  20681.  
  20682.           The following list shows all the methods overridden by the 
  20683.           SOMEClientEvent class. These methods are overridden in order to 
  20684.           modify the behavior defined by an ancestor class. 
  20685.  
  20686.               somInit 
  20687.  
  20688.  
  20689. ΓòÉΓòÉΓòÉ 6.2. somevGetEventClientData ΓòÉΓòÉΓòÉ
  20690.  
  20691. somevGetEventClientData This method returns the user-defined data associated 
  20692. with a client event. 
  20693.  
  20694.  Syntax 
  20695.  
  20696.                     void * somevGetEventClientData (SOMEClientEvent receiver,
  20697.                                        Environment *env)
  20698.  
  20699.  Parameters 
  20700.  
  20701.           receiver (SOMEClientEvent) 
  20702.                     A pointer to an object of class SOMEClientEvent. 
  20703.  
  20704.           env (Environment *) 
  20705.                     A pointer to the Environment structure for the calling 
  20706.                     method. 
  20707.  
  20708.  Returns 
  20709.  
  20710.           rc (void *) 
  20711.                     A pointer to user-defined client event data. 
  20712.  
  20713.  Remarks 
  20714.  
  20715.           This method returns the user-defined data (if any) associated with 
  20716.           the Client Event object. This associated data for a given client 
  20717.           event type is passed to EMan at the time of registration. 
  20718.  
  20719.  Original Class 
  20720.  
  20721.           SOMEClientEvent 
  20722.  
  20723.  Related Methods 
  20724.  
  20725.           Methods 
  20726.  
  20727.               somevSetEventClientData 
  20728.  
  20729.  
  20730. ΓòÉΓòÉΓòÉ 6.3. somevGetEventClientType ΓòÉΓòÉΓòÉ
  20731.  
  20732. somevGetEventClientType This method returns the type name of a client event. 
  20733.  
  20734.  Syntax 
  20735.  
  20736.                     string somevGetEventClientType (SOMEClientEvent receiver,
  20737.                                       Environment *env)
  20738.  
  20739.  Parameters 
  20740.  
  20741.           receiver (SOMEClientEvent) 
  20742.                     A pointer to an object of class SOMEClientEvent. 
  20743.  
  20744.           env (Environment *) 
  20745.                     A pointer to the Environment structure for the calling 
  20746.                     method. 
  20747.  
  20748.  Returns 
  20749.  
  20750.           rc (string) 
  20751.                     A null terminated string identifying the client event type. 
  20752.  
  20753.  Remarks 
  20754.  
  20755.           This method returns the client event type of the Client Event object. 
  20756.           Client event type is a string name assigned to the event by the 
  20757.           application at the time of registering the event. 
  20758.  
  20759.  Original Class 
  20760.  
  20761.           SOMEClientEvent 
  20762.  
  20763.  Related Methods 
  20764.  
  20765.           Methods 
  20766.  
  20767.               somevSetEventClientType 
  20768.  
  20769.  
  20770. ΓòÉΓòÉΓòÉ 6.4. somevSetEventClientData ΓòÉΓòÉΓòÉ
  20771.  
  20772. somevSetEventClientData This method sets the user-defined data of a client 
  20773. event. 
  20774.  
  20775.  Syntax 
  20776.  
  20777.                     void somevSetEventClientData (SOMEClientEvent receiver,
  20778.                                      Environment *env, void *clientData)
  20779.  
  20780.  Parameters 
  20781.  
  20782.           receiver (SOMEClientEvent) 
  20783.                     A pointer to an object of class SOMEClientEvent. 
  20784.  
  20785.           env (Environment *) 
  20786.                     A pointer to the Environment structure for the calling 
  20787.                     method. 
  20788.  
  20789.           clientData (void *) 
  20790.                     A pointer to user-defined data for this client event. 
  20791.  
  20792.  Returns 
  20793.  
  20794.           rc (void) 
  20795.  
  20796.  Remarks 
  20797.  
  20798.           This method sets the user-defined event data (if any) of the Client 
  20799.           Event object. This associated data for a given client event type is 
  20800.           passed to EMan at the time of registration. 
  20801.  
  20802.  Original Class 
  20803.  
  20804.           SOMEClientEvent 
  20805.  
  20806.  Related Methods 
  20807.  
  20808.           Methods 
  20809.  
  20810.               somevGetEventClientData 
  20811.  
  20812.  
  20813. ΓòÉΓòÉΓòÉ 6.5. somevSetEventClientType ΓòÉΓòÉΓòÉ
  20814.  
  20815. somevSetEventClientType This method sets the type name of a client event. 
  20816.  
  20817.  Syntax 
  20818.  
  20819.                     void somevSetEventClientType (SOMEClientEvent receiver,
  20820.                                      Environment *env, string clientType)
  20821.  
  20822.  Parameters 
  20823.  
  20824.           receiver (SOMEClientEvent) 
  20825.                     A pointer to an object of class SOMEClientEvent. 
  20826.  
  20827.           env (Environment *) 
  20828.                     A pointer to the Environment structure for the calling 
  20829.                     method. 
  20830.  
  20831.           clientType (string) 
  20832.                     A null terminated character string identifying the client 
  20833.                     event type. The contents of this string are entirely up to 
  20834.                     the user. However, while using class libraries that also 
  20835.                     use client events one must make sure that there are no name 
  20836.                     collisions. 
  20837.  
  20838.  Returns 
  20839.  
  20840.           rc (void) 
  20841.  
  20842.  Remarks 
  20843.  
  20844.           This method sets the client event type field of the Client Event 
  20845.           object. Client event type is a string name assigned to the event by 
  20846.           the application at the time of registering the event. 
  20847.  
  20848.  Original Class 
  20849.  
  20850.           SOMClientEvent 
  20851.  
  20852.  Related Methods 
  20853.  
  20854.           Methods 
  20855.  
  20856.               somevGetEventClientType 
  20857.  
  20858.  
  20859. ΓòÉΓòÉΓòÉ 6.6. SOMEEMan ΓòÉΓòÉΓòÉ
  20860.  
  20861. SOMEEMan 
  20862.  
  20863.  File stem: eman 
  20864.  
  20865.  Base 
  20866.  
  20867.           SOMObject 
  20868.  
  20869.  Metaclass 
  20870.  
  20871.           SOMMSingleInstance 
  20872.  
  20873.  Ancestor Classes 
  20874.  
  20875.                     SOMObject
  20876.  
  20877.  Description 
  20878.  
  20879.           The Event Manager class (EMan for short) is used to handle several 
  20880.           input events. The main purpose of this class is to provide a service 
  20881.           that can do a blocked (or timed) wait on several event sources 
  20882.           concurrently. Typically, in a main program, one registers an interest 
  20883.           in an event type with EMan and specifies a callback (a procedure or a 
  20884.           method) to be invoked when the event of interest occurs. After all 
  20885.           the necessary registrations are complete, the main program ends with 
  20886.           a call to someProcessEvents in EMan. This call is non-returning. Eman 
  20887.           then waits on all registered event sources. The application is 
  20888.           completely event driven at this point (that is, it does something 
  20889.           only when an event occurs). The control returns to EMan after 
  20890.           processing each event. Further registrations can be done from within 
  20891.           the callback routines. Unregistrations can also be done from within 
  20892.           the callback routines. 
  20893.  
  20894.           For applications that want to have their own main loop, EMan provides 
  20895.           a non-blocking call (the someProcessEvent method), which processes 
  20896.           just one event (if any) and returns to the main loop immediately. 
  20897.           Note that when this call is the only one in the application's main 
  20898.           loop, CPU cycles are wasted in constantly polling for events. In this 
  20899.           situation, the non-returning form of the someProcessEvents call is 
  20900.           preferable. 
  20901.  
  20902.           AIX Specifics: 
  20903.           On AIX this event manager supports Timer, Sink (any file, pipe, 
  20904.           socket, or Message Queue), Client and WorkProc events. 
  20905.  
  20906.           OS/2 Specifics: 
  20907.           On OS/2 this event manager supports Timer, Sink (sockets only), 
  20908.           Client, and WorkProc events. 
  20909.  
  20910.           Thread Safety: 
  20911.  
  20912.           To cope with multi-threaded applications on OS/2, the event-manager 
  20913.           methods are mutually exclusive (that is, at any time only one thread 
  20914.           can be executing inside of EMan). If an application thread needs to 
  20915.           stop EMan from running (that is, to achieve mutual exclusion with 
  20916.           EMan), it can use the two methods someGetEmanSem and 
  20917.           someReleaseEManSem to acquire and release EMan semaphore(s). On AIX, 
  20918.           since AIX does not support threads (at present), calling these two 
  20919.           methods has no effect. 
  20920.  
  20921.  New methods 
  20922.  
  20923.           The following list shows all the SOMEEMan methods. 
  20924.  
  20925.               someGetEmanSem 
  20926.               someReleaseEManSem 
  20927.               someChangeRegData 
  20928.               someProcessEvent 
  20929.               someProcessEvents 
  20930.               someQueueEvent 
  20931.               someRegister 
  20932.               someRegisterEv 
  20933.               someRegisterProc 
  20934.               someShutdown 
  20935.               someUnegister 
  20936.  
  20937.  Overridden methods 
  20938.  
  20939.           The following list shows all the methods overridden by the SOMEEMan 
  20940.           class. These methods are overridden in order to modify the behavior 
  20941.           defined by an ancestor class. 
  20942.  
  20943.               somInit 
  20944.               somUninit 
  20945.  
  20946.  
  20947. ΓòÉΓòÉΓòÉ 6.7. someChangeRegData ΓòÉΓòÉΓòÉ
  20948.  
  20949. someChangeRegData This method changes the registration data associated with a 
  20950. specified registration ID. 
  20951.  
  20952.  Syntax 
  20953.  
  20954.                     void someChangeRegData (SOMEEMan receiver, Environment *env,
  20955.                                    long registrationId,
  20956.                                    SOMEEMRegisterData registerData)
  20957.  
  20958.  Parameters 
  20959.  
  20960.           receiver (SOMEEMan) 
  20961.                     A pointer to an object of class SOMEEMan. 
  20962.  
  20963.           env (Environment *) 
  20964.                     A pointer to the Environment structure for the calling 
  20965.                     method. 
  20966.  
  20967.           registrationId (long) 
  20968.                     The registration ID of the event interest whose data is 
  20969.                     being changed. 
  20970.  
  20971.           registerData (SOMEEMRegisterData) 
  20972.                     A pointer to the registration data object whose contents 
  20973.                     will replace the existing registration information with 
  20974.                     EMan. 
  20975.  
  20976.  Returns 
  20977.  
  20978.           rc (void) 
  20979.  
  20980.  Remarks 
  20981.  
  20982.           This method is called to change the registration data associated with 
  20983.           an existing registration of EMan. The existing registration is 
  20984.           identified by the registrationId parameter. This ID must be the one 
  20985.           returned by EMan when the event interest was originally registered 
  20986.           with EMan. Further, the registration must be active (that is, it must 
  20987.           not have been unregistered). The result of providing a non-existent 
  20988.           or invalid registration ID is a "no op". 
  20989.  
  20990.  Original Class 
  20991.  
  20992.           SOMEEMan 
  20993.  
  20994.  Related Methods 
  20995.  
  20996.           Methods 
  20997.  
  20998.               someRegister 
  20999.               SomeRegisterEv 
  21000.               SomeRegisterProc 
  21001.  
  21002.  Example Code 
  21003.  
  21004.                     #include <eman.h>
  21005.                     SOMEEMan *EManPtr;
  21006.                     SOMEEMRegisterData *data;
  21007.                     Environment *Ev;
  21008.                     long RegId;
  21009.  
  21010.                             ...
  21011.                     _someChangeRegData(EManPtr, Ev, RegId, data);
  21012.  
  21013.  
  21014. ΓòÉΓòÉΓòÉ 6.8. someGetEManSem ΓòÉΓòÉΓòÉ
  21015.  
  21016. someGetEManSem This method acquires EMan semaphore(s) to achieve mutual 
  21017. exclusion with EMan's activity. 
  21018.  
  21019.  Syntax 
  21020.  
  21021.                     void someGetEManSem (SOMEEMan receiver, Environment *env)
  21022.  
  21023.  Parameters 
  21024.  
  21025.           receiver (SOMEEMan) 
  21026.                     A pointer to an object of class SOMEEMan. 
  21027.  
  21028.           env (Environment *) 
  21029.                     A pointer to the Environment structure for the calling 
  21030.                     method. 
  21031.  
  21032.  Returns 
  21033.  
  21034.           rc (void) 
  21035.  
  21036.  Remarks 
  21037.  
  21038.           When EMan is used on OS/2, multiple threads can invoke methods on 
  21039.           EMan concurrently. EMan protects its internal data by acquiring SOM 
  21040.           toolkit semaphore(s). The same semaphore(s) are made available to 
  21041.           users of EMan through the methods someGetEManSem and 
  21042.           someReleaseEManSem. If an application desires to prevent EMan event 
  21043.           processing from interfering with its own activity (in another thread, 
  21044.           of course), then it can call the someGetEManSem method and acquire 
  21045.           EMan semaphore(s). EMan activity will resume when the application 
  21046.           thread releases the same semaphore(s) by calling someReleaseEManSem. 
  21047.  
  21048.           Callers should not hold this semaphore for too long, since it 
  21049.           essentially stops EMan activity for that duration and may cause EMan 
  21050.           to miss some important event processing. The maximum duration for 
  21051.           which one can hold this semaphore depends on how frequently EMan must 
  21052.           process events. 
  21053.  
  21054.           On AIX, calling this method has no effect. 
  21055.  
  21056.  Original Class 
  21057.  
  21058.           SOMEEMan 
  21059.  
  21060.  Related Methods 
  21061.  
  21062.           Methods 
  21063.  
  21064.               someReleaseEManSem 
  21065.  
  21066.  Example Code 
  21067.  
  21068.                     #include <eman.h>
  21069.                     SOMEEMan *EManPtr;
  21070.                     Environment *Ev;
  21071.  
  21072.                          ...
  21073.                     _someGetEManSem(EManPtr, Ev);
  21074.                       /* Do the work that needs mutual exclusion with EMan */
  21075.                     _someReleaseEManSem(EManPtr, Ev);
  21076.  
  21077.  
  21078. ΓòÉΓòÉΓòÉ 6.9. someProcessEvent ΓòÉΓòÉΓòÉ
  21079.  
  21080. someProcessEvent This method processes one event. 
  21081.  
  21082.  Syntax 
  21083.  
  21084.                     void someProcessEvent (SOMEEMan receiver, Environment *env,
  21085.                                   unsigned long mask)
  21086.  
  21087.  Parameters 
  21088.  
  21089.           receiver (SOMEEMan) 
  21090.                     A pointer to an object of class SOMEEMan. 
  21091.  
  21092.           env (Environment *) 
  21093.                     A pointer to the Environment structure for the calling 
  21094.                     method. 
  21095.  
  21096.           mask (unsigned long) 
  21097.                     A bit mask indicating the types of events to look for and 
  21098.                     process. 
  21099.  
  21100.  Returns 
  21101.  
  21102.           rc (void) 
  21103.  
  21104.  Remarks 
  21105.  
  21106.           Processes one event. This call is non-blocking. If there are no 
  21107.           events to process it returns immediately. The mask specifies which 
  21108.           events to process. The mask is formed by OR'ing the bit constants 
  21109.           specified in "eventmsk.h". 
  21110.  
  21111.  Original Class 
  21112.  
  21113.           SOMEEMan 
  21114.  
  21115.  Related Methods 
  21116.  
  21117.           Methods 
  21118.  
  21119.               someProcessEvents 
  21120.               someRegister 
  21121.               someRegisterProc 
  21122.               someRegisterEv 
  21123.  
  21124.  Example Code 
  21125.  
  21126.                     #include <eman.h>
  21127.  
  21128.                     main()
  21129.                     {
  21130.                     Environment *testEnv = somGetGlobalEnvironment();
  21131.                     SOMEEMan *some_gEMan = SOMEEManNew();
  21132.                     /* Do some registrations */
  21133.                        ...
  21134.                     while (1) {
  21135.                             _someProcessEvent(some_gEMan,  testEnv,
  21136.                                                     EMProcessTimerEvent Γöé
  21137.                                                     EMProcessSinkEvent Γöé
  21138.                                                     EMProcessClientEvent );
  21139.                             /***  Do other main loop work, if needed. ***/
  21140.                     }
  21141.                     } /* end of main */
  21142.  
  21143.  
  21144. ΓòÉΓòÉΓòÉ 6.10. someProcessEvents ΓòÉΓòÉΓòÉ
  21145.  
  21146. someProcessEvents This method processes infinite events. 
  21147.  
  21148.  Syntax 
  21149.  
  21150.                     void someProcessEvents (SOMEEMan receiver, Environment *env)
  21151.  
  21152.  Parameters 
  21153.  
  21154.           receiver (SOMEEMan) 
  21155.                     A pointer to an object of class SOMEEMan. 
  21156.  
  21157.           env (Environment *) 
  21158.                     A pointer to the Environment structure for the calling 
  21159.                     method. 
  21160.  
  21161.  Returns 
  21162.  
  21163.           rc (void) 
  21164.  
  21165.  Remarks 
  21166.  
  21167.           This call loops forever waiting for events and dispatching them. The 
  21168.           only way this can be broken is by calling someShutdown in a callback 
  21169.           routine. It is a programming error to call this method without having 
  21170.           registered interest in any events with EMan. Typically, a call to 
  21171.           this method is the last statement in an application's main program. 
  21172.  
  21173.  Original Class 
  21174.  
  21175.           SOMEEMan 
  21176.  
  21177.  Related Methods 
  21178.  
  21179.           Methods 
  21180.  
  21181.               someProcessEvent 
  21182.               someRegister 
  21183.               someRegisterProc 
  21184.               someRegisterEv 
  21185.  
  21186.  Example Code 
  21187.  
  21188.                     #include <eman.h>
  21189.  
  21190.                     main()
  21191.                     {
  21192.                     Environment *testEnv = somGetGlobalEnvironment();
  21193.                     SOMEEMan *some_gEMan = SOMEEManNew();
  21194.                      /* Do some registrations */
  21195.                        ...
  21196.                     _someProcessEvents(some_gEMan,  testEnv);
  21197.                     } /* end of main */
  21198.  
  21199.  
  21200. ΓòÉΓòÉΓòÉ 6.11. someQueueEvent ΓòÉΓòÉΓòÉ
  21201.  
  21202. someQueueEvent This method enqueues the specified client event. 
  21203.  
  21204.  Syntax 
  21205.  
  21206.                     void someQueueEvent (SOMEEMan receiver, Environment *env,
  21207.                                  SOMEClientEvent event)
  21208.  
  21209.  Parameters 
  21210.  
  21211.           receiver (SOMEEMan) 
  21212.                     A pointer to an object of class SOMEEMan. 
  21213.  
  21214.           env (Environment *) 
  21215.                     A pointer to the Environment structure for the calling 
  21216.                     method. 
  21217.  
  21218.           event (SOMEClientEvent) 
  21219.  
  21220.  Returns 
  21221.  
  21222.           rc (void) 
  21223.  
  21224.  Remarks 
  21225.  
  21226.           Client events are defined, created, processed and destroyed by the 
  21227.           application. EMan simply provides a means to enqueue and dequeue 
  21228.           client events. Client events can be used in several ways. For 
  21229.           example, if an application component wants to handle an input message 
  21230.           arriving on a socket at a later time than when it arrives, it can 
  21231.           receive the message in the socket callback routine, create a client 
  21232.           event out of it, and queue it with EMan. EMan can be asked for the 
  21233.           client event at a later time when the application is ready to handle 
  21234.           it. Client events can also be useful to hide the origin of event 
  21235.           sources (that is, the original event handlers receive the events and 
  21236.           create client events in their place). 
  21237.  
  21238.           Dequeue is not a user-visible operation. Once a client event is 
  21239.           queued, only EMan can dequeue it. 
  21240.  
  21241.  Original Class 
  21242.  
  21243.           SOMEEMan 
  21244.  
  21245.  Example Code 
  21246.  
  21247.                     #include <eman.h>
  21248.                     SOMEClientEvent *clientEvent1;
  21249.  
  21250.                     clientEvent1 = SOMEClientEventNew();
  21251.                     /* create a client event of type "ClientType1" */
  21252.                     _somevSetEventClientType( clientEvent1, testEnv, "ClientType1" );
  21253.                     _somevSetEventClientData( clientEvent1, testEnv, "Test Msg");
  21254.                       ...
  21255.  
  21256.                     /* whenever it is desired to cause this client event to happen,
  21257.                        call someQueueEvent Method with this clientEvent */
  21258.                     _someQueueEvent(some_gEMan, env, clientEvent1);
  21259.  
  21260.  
  21261. ΓòÉΓòÉΓòÉ 6.12. someRegister ΓòÉΓòÉΓòÉ
  21262.  
  21263. someRegister This method registers an object/method pair with EMan, given a 
  21264. specified registerData object. 
  21265.  
  21266.  Syntax 
  21267.  
  21268.                     long someRegister (SOMEEMan receiver, Environment *env,
  21269.                                SOMEEMRegisterData registerData,
  21270.                                SOMObject targetObject, string targetMethod,
  21271.                                void *targetData)
  21272.  
  21273.  Parameters 
  21274.  
  21275.           receiver (SOMEEMan) 
  21276.                     A pointer to an object of class SOMEEMan. 
  21277.  
  21278.           env (Environment *) 
  21279.                     A pointer to the Environment structure for the calling 
  21280.                     method. 
  21281.  
  21282.           registerData (SOMEEMRegisterData) 
  21283.                     A pointer to the registration data object that contains all 
  21284.                     the necessary information about the event for which an 
  21285.                     interest is being registered with EMan. 
  21286.  
  21287.           targetObject (SOMObject) 
  21288.                     A pointer to the object that is the target of the callback 
  21289.                     method. 
  21290.  
  21291.           targetMethod (string) 
  21292.                     The name of the callback method. 
  21293.  
  21294.           targetData (void *) 
  21295.                     A pointer to a data structure to be passed to the callback 
  21296.                     method when the event occurs. 
  21297.  
  21298.  Returns 
  21299.  
  21300.           rc (long) 
  21301.                     The registration ID. 
  21302.  
  21303.  Remarks 
  21304.  
  21305.           This method allows for registering an event of interest with EMan, 
  21306.           with an object method as the callback. It is assumed that the target 
  21307.           method has been declared as using OIDL callstyle. The event of 
  21308.           interest and its details are filled in a registration data object 
  21309.           registerData. The information about the callback routine is indicated 
  21310.           by targetObject and targetMethod. 
  21311.  
  21312.           A mismatch between the target method's callstyle and the registration 
  21313.           method used (that is, someRegister vs. someRegisterEv) can result in 
  21314.           unpredictable results. Also see the callstyle modifier of the SOM 
  21315.           Interface Definition Language described in Chapter 4 "SOM IDL and the 
  21316.           SOM Compiler" of the SOM Programming Guide 
  21317.  
  21318.           Note:  The target method is called using name-lookup method 
  21319.           resolution. 
  21320.  
  21321.  Original Class 
  21322.  
  21323.           SOMEEMan 
  21324.  
  21325.  Related Methods 
  21326.  
  21327.           Methods 
  21328.  
  21329.               someRegisterEv 
  21330.               someRegisterProc 
  21331.               someUnRegister 
  21332.  
  21333.  Example Code 
  21334.  
  21335.                     #include <eman.h>
  21336.                     #include <emobj.h>
  21337.  
  21338.                     Environment *testEnv = somGetGlobalEnvironment();
  21339.                     some_gEMan = SOMEEManNew();         /* create an EMan object */
  21340.                     data = SOMEEMRegisterDataNew( ); /* create a reg data object */
  21341.                     target = EMObjectNew();    /* create a target object */
  21342.  
  21343.                     /* reRegister a timer event */
  21344.                     _someClearRegData( data, env );
  21345.                     _someSetRegDataEventMask( data, env, EMTimerEvent, NULL );
  21346.                     _someSetRegDataTimerInterval( data, env, 100 );
  21347.                     regId1 = _someRegister( some_gEMan, env, data, target,
  21348.                                             "eventMethod", "Timer 100" );
  21349.  
  21350.  
  21351. ΓòÉΓòÉΓòÉ 6.13. someRegisterEv ΓòÉΓòÉΓòÉ
  21352.  
  21353. someRegisterEv This method registers the (object, method, Environment 
  21354. parameter) combination of a callback with EMan, given a specified registerData 
  21355. object. 
  21356.  
  21357.  Syntax 
  21358.  
  21359.                     long someRegisterEv (SOMEEMan receiver, Environment *env,
  21360.                                 SOMEEMRegisterData registerData,
  21361.                                 SOMObject targetObject,
  21362.                                 Environment callbackEv, string targetMethod,
  21363.                                 void *targetData)
  21364.  
  21365.  Parameters 
  21366.  
  21367.           receiver (SOMEEMan) 
  21368.                     A pointer to an object of class SOMEEMan. 
  21369.  
  21370.           env (Environment *) 
  21371.                     A pointer to the Environment structure for the calling 
  21372.                     method. 
  21373.  
  21374.           registerData (SOMEEMRegisterData) 
  21375.                     A pointer to registration data object that contains all the 
  21376.                     necessary information about the event for which an interest 
  21377.                     is being registered with EMan. 
  21378.  
  21379.           targetObject (SOMObject) 
  21380.                     A pointer to the object which is the target of the callback 
  21381.                     method 
  21382.  
  21383.           callbackEv (Environment) 
  21384.                     A pointer to the Environment structure to be passed to the 
  21385.                     callback method 
  21386.  
  21387.           targetMethod (string) 
  21388.                     The name of the callback method. 
  21389.  
  21390.           targetData (void *) 
  21391.                     A pointer to a data structure to be passed to the callback 
  21392.                     method when the event occurs. 
  21393.  
  21394.  Returns 
  21395.  
  21396.           rc (long) 
  21397.                     The registration ID. 
  21398.  
  21399.  Remarks 
  21400.  
  21401.           This method allows for registering an event interest with EMan with 
  21402.           an object method as callback. The callbackEv is used as the 
  21403.           environment pointer when EMan makes the callback. It is assumed that 
  21404.           the target method has been declared as using IDL callstyle. The event 
  21405.           of interest and its details are filled in a registration data object 
  21406.           registerData. The information about the callback routine is indicated 
  21407.           by targetObject and targetMethod. 
  21408.  
  21409.           A mismatch in the target method's callstyle and the registration 
  21410.           method called (someRegister vs. someRegisterEv) can result in 
  21411.           unpredictable results. Also see the callstyle modifier of the SOM 
  21412.           Interface Definition Language described in Chapter 4 "SOM IDL and the 
  21413.           SOM Compiler" of the SOM Programming Guide. 
  21414.  
  21415.           Note:  The target method is called using name-lookup method 
  21416.           resolution. 
  21417.  
  21418.  Original Class 
  21419.  
  21420.           SOMEEMan 
  21421.  
  21422.  Related Methods 
  21423.  
  21424.           Methods 
  21425.  
  21426.               someRegister 
  21427.               someRegisterProc 
  21428.               someUnRegister 
  21429.  
  21430.  Example Code 
  21431.  
  21432.                     #include <eman.h>
  21433.                     #include <emobj.h>
  21434.  
  21435.                     Environment *testEnv = somGetGlobalEnvironment();
  21436.                     Environment *targetEv = somGetGlobalEnvironment();
  21437.                     some_gEMan = SOMEEManNew();         /* create an EMan object */
  21438.                     data = SOMEEMRegisterDataNew( ); /* create a reg data object */
  21439.                     target = EMObjectNew();    /* create a target object */
  21440.  
  21441.                     /* reRegister a timer event */
  21442.                     _someClearRegData( data, env );
  21443.                     _someSetRegDataEventMask( data, env, EMTimerEvent, NULL );
  21444.                     _someSetRegDataTimerInterval( data, env, 100 );
  21445.                     regId1 = _someRegisterEv( some_gEMan,env, data, target,targetEv,
  21446.                                             "eventMethod", "Timer 100" );
  21447.                      /* eventMethod of target is assumed to use callstyle=idl */
  21448.  
  21449.  
  21450. ΓòÉΓòÉΓòÉ 6.14. someRegisterProc ΓòÉΓòÉΓòÉ
  21451.  
  21452. someRegisterProc This method registers the procedure with EMan given the 
  21453. specified registerData. 
  21454.  
  21455.  Syntax 
  21456.  
  21457.                     long someRegisterProc (SOMEEMan receiver, Environment *env,
  21458.                                  SOMEEMRegisterData registerData,
  21459.                                  EMRegProc *targetProcedure, void *targetData)
  21460.  
  21461.  Parameters 
  21462.  
  21463.           receiver (SOMEEMan) 
  21464.                     A pointer to an object of class SOMEEMan. 
  21465.  
  21466.           env (Environment *) 
  21467.                     A pointer to the Environment structure for the calling 
  21468.                     method. 
  21469.  
  21470.           registerData (SOMEEMRegisterData) 
  21471.                     A pointer to registration data object that contains all the 
  21472.                     necessary information about the event for which an interest 
  21473.                     is being registered with EMan. 
  21474.  
  21475.           targetProcedure (EMRegProc *) 
  21476.                     A pointer to the procedure (callback) that is called when 
  21477.                     the registered event occurs. 
  21478.  
  21479.           targetData (void *) 
  21480.  
  21481.  Returns 
  21482.  
  21483.           rc (long) 
  21484.                     The registration ID. 
  21485.  
  21486.  Original Class 
  21487.  
  21488.           SOMEEMan 
  21489.  
  21490.  Related Methods 
  21491.  
  21492.           Methods 
  21493.  
  21494.               someRegister 
  21495.               someRegisterEv 
  21496.               someUnRegister 
  21497.  
  21498.  Example Code 
  21499.  
  21500.                     #include <eman.h>
  21501.  
  21502.                     void MyCallBack(SOMEEvent *event, void *somedata){
  21503.                      ...
  21504.                     }
  21505.  
  21506.                     Environment *testEnv = somGetGlobalEnvironment();
  21507.                     some_gEMan = SOMEEManNew();         /* create an EMan object */
  21508.                     data = SOMEEMRegisterDataNew( ); /* create a reg data object */
  21509.  
  21510.                     /* reRegister a timer event */
  21511.                     _someClearRegData( data, env );
  21512.                     _someSetRegDataEventMask( data, env, EMTimerEvent, NULL );
  21513.                     _someSetRegDataTimerInterval( data, env, 100 );
  21514.                     regId1 = _someRegisterProc( some_gEMan, env, data,
  21515.                                             MyCallBack, "Timer 100" );
  21516.  
  21517.  
  21518. ΓòÉΓòÉΓòÉ 6.15. someReleaseEManSem ΓòÉΓòÉΓòÉ
  21519.  
  21520. someReleaseEManSem This method releases the semaphore obtained by the 
  21521. someGetEManSem method. 
  21522.  
  21523.  Syntax 
  21524.  
  21525.                     void someReleaseEManSem (SOMEEMan receiver, Environment *env)
  21526.  
  21527.  Parameters 
  21528.  
  21529.           receiver (SOMEEMan) 
  21530.                     A pointer to an object of class SOMEEMan. 
  21531.  
  21532.           env (Environment *) 
  21533.                     A pointer to the Environment structure for the calling 
  21534.                     method. 
  21535.  
  21536.  Returns 
  21537.  
  21538.           rc (void) 
  21539.  
  21540.  Remarks 
  21541.  
  21542.           When EMan is used on OS/2, multiple threads can invoke methods on 
  21543.           EMan concurrently. EMan protects its internal data by acquiring SOM 
  21544.           toolkit semaphore(s). The same semaphore(s) are made available to 
  21545.           users of EMan through the methods someGetEManSem and 
  21546.           someReleaseEManSem. If an application desires to prevent EMan's event 
  21547.           processing from interfering with its own activity (in another thread, 
  21548.           of course), then it can call the someGetEManSem method and acquire 
  21549.           EMan semaphore(s). EMan activity will resume when the application 
  21550.           thread releases the same semaphore(s) by calling someReleaseEManSem. 
  21551.  
  21552.           Callers should not hold this semaphore for too long, since it 
  21553.           essentially stops EMan activity for that duration and may cause EMan 
  21554.           to miss some important event processing. The maximum duration for 
  21555.           which one can hold this semaphore depends on how frequently EMan must 
  21556.           process events. 
  21557.  
  21558.           On AIX, calling this method has no effect. 
  21559.  
  21560.  Original Class 
  21561.  
  21562.           SOMEEMan 
  21563.  
  21564.  Related Methods 
  21565.  
  21566.           Methods 
  21567.  
  21568.               someGetEManSem 
  21569.  
  21570.  Example Code 
  21571.  
  21572.                     #include <eman.h>
  21573.                     SOMEEMan *EManPtr;
  21574.                     Environment *Ev;
  21575.  
  21576.                         ...
  21577.                     _someGetEManSem(EManPtr, Ev);
  21578.                       /* Do the work that needs mutual exclusion with EMan */
  21579.                     _someReleaseEManSem(EManPtr, Ev);
  21580.  
  21581.  
  21582. ΓòÉΓòÉΓòÉ 6.16. someShutdown ΓòÉΓòÉΓòÉ
  21583.  
  21584. someShutdown This method shuts down an EMan event loop. (That is, this makes 
  21585. the someProcessEvents return!) 
  21586.  
  21587.  Syntax 
  21588.  
  21589.                     void someShutdown (SOMEEMan receiver, Environment *env)
  21590.  
  21591.  Parameters 
  21592.  
  21593.           receiver (SOMEEMan) 
  21594.                     A pointer to an object of class SOMEEMan. 
  21595.  
  21596.           env (Environment *) 
  21597.                     A pointer to the Environment structure for the calling 
  21598.                     method. 
  21599.  
  21600.  Returns 
  21601.  
  21602.           rc (void) 
  21603.  
  21604.  Remarks 
  21605.  
  21606.           This can be called from a callback routine to break the 
  21607.           someProcessEvents loop. 
  21608.  
  21609.  Original Class 
  21610.  
  21611.           SOMEEMan 
  21612.  
  21613.  Related Methods 
  21614.  
  21615.           Methods 
  21616.  
  21617.               someProcessEvents 
  21618.  
  21619.  Example Code 
  21620.  
  21621.                     #include <eman.h>
  21622.                     SOMEEMan *some_gEMan;
  21623.  
  21624.                     void MyCallBack(SOMEEvent *event, void *somedata){
  21625.                      ...
  21626.                     _someShutdown(some_gEMan, env);
  21627.                     }
  21628.                     main()
  21629.                     {
  21630.                     Environment *testEnv = somGetGlobalEnvironment();
  21631.                     SOMEEMan *some_gEMan = SOMEEManNew();
  21632.                      /* Do some registrations. At least one involving MyCallBack */
  21633.                        ...
  21634.                     _someProcessEvents(some_gEMan,  testEnv);
  21635.                     }
  21636.  
  21637.  
  21638. ΓòÉΓòÉΓòÉ 6.17. someUnRegister ΓòÉΓòÉΓòÉ
  21639.  
  21640. someUnRegister This method unregisters the event interest associated with a 
  21641. specified registrationId within EMan. 
  21642.  
  21643.  Syntax 
  21644.  
  21645.                     void someUnRegister (SOMEEMan receiver, Environment *env,
  21646.                                 long registrationId)
  21647.  
  21648.  Parameters 
  21649.  
  21650.           receiver (SOMEEMan) 
  21651.                     A pointer to an object of class SOMEEMan. 
  21652.  
  21653.           env (Environment *) 
  21654.                     A pointer to the Environment structure for the calling 
  21655.                     method. 
  21656.  
  21657.           registrationId (long) 
  21658.                     The registration ID of the event that needs to be 
  21659.                     unregistered. 
  21660.  
  21661.  Returns 
  21662.  
  21663.           rc (void) 
  21664.  
  21665.  Remarks 
  21666.  
  21667.           When an application is no longer interested in a given event, it can 
  21668.           unregister the event interest from EMan. EMan will stop making 
  21669.           callbacks on this event, even if the event source continues to be 
  21670.           active and generates events. 
  21671.  
  21672.  Original Class 
  21673.  
  21674.           SOMEEMan 
  21675.  
  21676.  Related Methods 
  21677.  
  21678.           Methods 
  21679.  
  21680.               someRegister 
  21681.               someRegisterEv 
  21682.               someRegisterProc 
  21683.  
  21684.  Example Code 
  21685.  
  21686.                     #include <eman.h>
  21687.                     long regId1;
  21688.  
  21689.                      ...
  21690.                     /* Register a timer */
  21691.                     regId1 = _someRegisterEv( some_gEMan,env, data, target,targetEv,
  21692.                                             "eventMethod", "Timer 100" );
  21693.  
  21694.                      ...
  21695.                     /* Unregister the timer */
  21696.                     _someUnRegister(some_gEMan, env, regId1);
  21697.  
  21698.  
  21699. ΓòÉΓòÉΓòÉ 6.18. SOMEEMRegisterData ΓòÉΓòÉΓòÉ
  21700.  
  21701. SOMEEMRegisterData 
  21702.  
  21703.  File stem: emregdat 
  21704.  
  21705.  Base 
  21706.  
  21707.           SOMObject 
  21708.  
  21709.  Metaclass 
  21710.  
  21711.           SOMClass 
  21712.  
  21713.  Ancestor Classes 
  21714.  
  21715.                     SOMClass
  21716.                        WPObject
  21717.  
  21718.  Description 
  21719.  
  21720.           This class is used for holding registration information for event 
  21721.           types to be registered with EMan.  EMan extracts all needed 
  21722.           information from this object and saves the information in its 
  21723.           internal data structures.  An instance of this class must be created, 
  21724.           properly initialized, and passed to the registration methods of EMan 
  21725.           for registering interest in any kind of event. 
  21726.  
  21727.  New methods 
  21728.  
  21729.           The following list shows all the SOMEEMRegisterData methods. 
  21730.  
  21731.               someClearRegData 
  21732.               someSetRegDataClientType 
  21733.               someSetRegDataEventMask 
  21734.               someSetRegDataSink 
  21735.               someSetRegDataSinkMask 
  21736.               someSetRegDataTimerCount 
  21737.               someSetRegDataTimerInterval 
  21738.  
  21739.  Overriding methods 
  21740.  
  21741.           The following list shows all the methods overridden by the 
  21742.           SOMEEMRegisterData class. These methods are overridden in order to 
  21743.           modify the behavior defined by an ancestor class. 
  21744.  
  21745.               somInit 
  21746.               somUnInit 
  21747.  
  21748.  
  21749. ΓòÉΓòÉΓòÉ 6.19. someClearRegData ΓòÉΓòÉΓòÉ
  21750.  
  21751. someClearRegData 
  21752.  
  21753. This method clears the registration data. 
  21754.  
  21755. This method initializes all fields of a RegData object to their default values. 
  21756.  
  21757.  Syntax 
  21758.  
  21759.                     void someClearRegData (SOMEEMRegisterData receiver,
  21760.                                   Environment *env)
  21761.  
  21762.  Parameters 
  21763.  
  21764.           receiver (SOMEEMRegisterData) 
  21765.                     A pointer to an object of class  SOMEEMRegisterData. 
  21766.  
  21767.           env (Environment *) 
  21768.                     A pointer to the Environment structure for the calling 
  21769.                     method. 
  21770.  
  21771.  Returns 
  21772.  
  21773.           rc (void) 
  21774.  
  21775.  Original Class 
  21776.  
  21777.           SOMEEMRegisterData 
  21778.  
  21779.  
  21780. ΓòÉΓòÉΓòÉ 6.20. someSetRegDataClientType ΓòÉΓòÉΓòÉ
  21781.  
  21782. someSetRegDataClientType 
  21783.  
  21784. This method sets the type name for a client event. 
  21785.  
  21786.  Syntax 
  21787.  
  21788.                     void someSetRegDataClientType (SOMEEMRegisterData receiver,
  21789.                                       Environment *env, string clientType)
  21790.  
  21791.  Parameters 
  21792.  
  21793.           receiver (SOMEEMRegisterData) 
  21794.                     A pointer to an object of class SOMEEMRegisterData. 
  21795.  
  21796.           env (Environment *) 
  21797.                     A pointer to the Environment structure for the calling 
  21798.                     method. 
  21799.  
  21800.           clientType (string) 
  21801.                     A null-terminated character string identifying the client 
  21802.                     event type. The contents of this string are entirely up to 
  21803.                     the user. However, while using class libraries that also 
  21804.                     use client events, one must make sure that there are no 
  21805.                     name collisions. 
  21806.  
  21807.  Returns 
  21808.  
  21809.           rc (void) 
  21810.  
  21811.  Remarks 
  21812.  
  21813.           Client events are defined, created, processed, and destroyed entirely 
  21814.           by the application. The application can queue several types of client 
  21815.           events with EMan. This method sets the client event type field of the 
  21816.           registration data object. Thus, this information is communicated to 
  21817.           EMan, helping it deal with enqueueing and dequeing the different 
  21818.           client events. 
  21819.  
  21820.  Original Class 
  21821.  
  21822.           SOMEEMRegisterData 
  21823.  
  21824.  Related Methods 
  21825.  
  21826.           Methods: 
  21827.  
  21828.               someClearRegData 
  21829.  
  21830.  
  21831. ΓòÉΓòÉΓòÉ 6.21. someSetRegDataEventMask ΓòÉΓòÉΓòÉ
  21832.  
  21833. someSetRegDataEventMask 
  21834.  
  21835. This method sets the generic event mask within the registration data using NULL 
  21836. terminated event type list. 
  21837.  
  21838.  Syntax 
  21839.  
  21840.                     void someSetRegDataEventMask (SOMEEMRegisterData receiver,
  21841.                                       Environment *env, long eventType,
  21842.                                       va_list ap)
  21843.  
  21844.  Parameters 
  21845.  
  21846.           receiver (SOMEEMRegisterData) 
  21847.                     A pointer to an object of class SOMEEMRegisterData. 
  21848.  
  21849.           env (Environment *) 
  21850.                     A pointer to the Environment structure for the calling 
  21851.                     method. 
  21852.  
  21853.           eventType (long) 
  21854.                     A bit constant indicating the type of event being 
  21855.                     registered with EMan. 
  21856.  
  21857.           ap (va_list) 
  21858.                     Additional event types (usually  NULL). 
  21859.  
  21860.  Returns 
  21861.  
  21862.           rc (void) 
  21863.  
  21864.  Remarks 
  21865.  
  21866.           This allows setting the event mask within the registration data 
  21867.           object. Essentially, this tells EMan what kind of event is being 
  21868.           registered with it. The event type list is a series of constants 
  21869.           defined in eventmsk.h. Although the current interface supports a 
  21870.           NULL terminated list of event types, currently each registration with 
  21871.           EMan names only one event type. Thus, one usually gives only one 
  21872.           named constant as the event type and follows it with a  NULL 
  21873.           parameter. 
  21874.  
  21875.  Original Class 
  21876.  
  21877.           SOMEEMRegisterData 
  21878.  
  21879.  Related Methods 
  21880.  
  21881.           Methods: 
  21882.  
  21883.               someSetRegDataSink 
  21884.               someClearRegData 
  21885.  
  21886.  Example Code 
  21887.  
  21888.                     #include <eman.h>
  21889.                     long regId1;
  21890.                     int msgsock;
  21891.  
  21892.                      ...
  21893.                     /* Register msgsock socket with EMan for further communication */
  21894.                     _someClearRegData( data, env );
  21895.                     _someSetRegDataEventMask( data, env, EMSinkEvent, NULL );
  21896.                     /* The above call enables EMan to know (during registration) that
  21897.                     we are talking about a Sink Event */
  21898.                     _someSetRegDataSink( data, env, msgsock );
  21899.                     _someSetRegDataSinkMask( data, env, EMInputReadMask);
  21900.  
  21901.                     regId = _someRegisterProc( some_gEMan, env, data,
  21902.                                             ReadSocketAndPrint, "READMSG" );
  21903.  
  21904.  
  21905. ΓòÉΓòÉΓòÉ 6.22. someSetRegDataSink ΓòÉΓòÉΓòÉ
  21906.  
  21907. someSetRegDataSink 
  21908.  
  21909. This method sets the file descriptor (or socket ID, or message queue ID) for 
  21910. the sink event. 
  21911.  
  21912.  Syntax 
  21913.  
  21914.                     void someSetRegDataSink (SOMEEMRegisterData receiver,
  21915.                                    Environment *env, long sink)
  21916.  
  21917.  Parameters 
  21918.  
  21919.           receiver (SOMEEMRegisterData) 
  21920.                     A pointer to an object of class SOMEEMRegisterData. 
  21921.  
  21922.           env (Environment *) 
  21923.                     A pointer to the Environment structure for the calling 
  21924.                     method. 
  21925.  
  21926.           sink (long) 
  21927.                     An integer value indicating the file descriptor for 
  21928.                     input/output. It can also be a socket ID, pipe ID or a 
  21929.                     message queue ID. 
  21930.  
  21931.  Returns 
  21932.  
  21933.           rc (void) 
  21934.  
  21935.  Remarks 
  21936.  
  21937.           This method enables setting the true type of an event object. 
  21938.           Typically, a subclass of Event calls this method (or overrides this 
  21939.           method) to set the event type to indicate its true class(type). 
  21940.  
  21941.  Original Class 
  21942.  
  21943.           SOMEEMRegisterData 
  21944.  
  21945.  Related Methods 
  21946.  
  21947.           Methods: 
  21948.  
  21949.               someClearRegData 
  21950.  
  21951.  
  21952. ΓòÉΓòÉΓòÉ 6.23. someSetRegDataSinkMask ΓòÉΓòÉΓòÉ
  21953.  
  21954. someSetRegDataSinkMask 
  21955.  
  21956. This method sets the sink mask within the registration data object. 
  21957.  
  21958.  Syntax 
  21959.  
  21960.                     void someSetRegDataSinkMask (SOMEEMRegisterData receiver,
  21961.                                      Environment *env,
  21962.                                      unsigned long sinkmask)
  21963.  
  21964.  Parameters 
  21965.  
  21966.           receiver (SOMEEMRegisterData) 
  21967.                     A pointer to an object of class SOMEEMRegisterData. 
  21968.  
  21969.           env (Environment *) 
  21970.                     A pointer to the Environment structure for the calling 
  21971.                     method. 
  21972.  
  21973.           sinkmask (unsigned long) 
  21974.                     A bit mask indicating the types of events of interest on a 
  21975.                     given sink. 
  21976.  
  21977.  Returns 
  21978.  
  21979.           rc (void) 
  21980.  
  21981.  Remarks 
  21982.  
  21983.           The sink mask within the registration data allows one to express 
  21984.           interest in different events of the same event source. For example, 
  21985.           using this mask one can express interest in being notified when there 
  21986.           is input for reading, when the resource is ready for writing output, 
  21987.           or just when exceptions occur. 
  21988.  
  21989.  Original Class 
  21990.  
  21991.           SOMEEMRegisterData 
  21992.  
  21993.  Related Methods 
  21994.  
  21995.           Methods: 
  21996.  
  21997.               someSetRegDataSink 
  21998.               someClearRegData 
  21999.  
  22000.  Example Code 
  22001.  
  22002.                     #include <eman.h>
  22003.                     long regId1;
  22004.                     int msgsock;
  22005.  
  22006.                      ...
  22007.                     /* Register msgsock socket with EMan for further communication */
  22008.                     _someClearRegData( data, env );
  22009.                     _someSetRegDataEventMask( data, env, EMSinkEvent, NULL );
  22010.                     _someSetRegDataSink( data, env, msgsock );
  22011.                     _someSetRegDataSinkMask( data, env,
  22012.                                              EMInputReadMaskΓöéEMInputExceptMask);
  22013.                     /* The above call expresses interest in knowing when there is
  22014.                      input to be read from the socket and when there is an exception
  22015.                     condition associated with this socket. */
  22016.                     regId = _someRegisterProc( some_gEMan, env, data,
  22017.                                             ReadSocketAndPrint, "READMSG" );
  22018.  
  22019.  
  22020. ΓòÉΓòÉΓòÉ 6.24. someSetRegDataTimerCount ΓòÉΓòÉΓòÉ
  22021.  
  22022. someSetRegDataTimerCount 
  22023.  
  22024. This method sets the number of times the timer will trigger, within the 
  22025. registration data. 
  22026.  
  22027.  Syntax 
  22028.  
  22029.                     void someSetRegDataTimerCount (SOMEEMRegisterData receiver,
  22030.                                        Environment *env, long count)
  22031.  
  22032.  Parameters 
  22033.  
  22034.           receiver (SOMEEMRegisterData) 
  22035.                     A pointer to an object of class SOMEEMRegisterData. 
  22036.  
  22037.           env (Environment *) 
  22038.                     A pointer to the Environment structure for the calling 
  22039.                     method. 
  22040.  
  22041.           count (long) 
  22042.                     An integer indicating the number of times the timer event 
  22043.                     has to occur. 
  22044.  
  22045.  Returns 
  22046.  
  22047.           rc (void) 
  22048.  
  22049.  Remarks 
  22050.  
  22051.           The someSetRegDataTimerCount method sets the number of times the 
  22052.           timer will trigger, within the registration data. The default 
  22053.           behavior is for the timer to trigger indefinitely. 
  22054.  
  22055.  Original Class 
  22056.  
  22057.           SOMEEMRegisterData 
  22058.  
  22059.  Related Methods 
  22060.  
  22061.           Methods: 
  22062.  
  22063.               someClearRegData 
  22064.  
  22065.  Example Code 
  22066.  
  22067.                     #include <eman.h>
  22068.                     long regId1;
  22069.  
  22070.                      ...
  22071.                     /* Register a timer */
  22072.                     _someClearRegData( data, env );
  22073.                     _someSetRegDataEventMask( data, env, EMTimerEvent, NULL );
  22074.                     _someSetRegDataTimerInterval( data, env, 100 );
  22075.                     _someSetRegDataTimerCount(data, env, 1);
  22076.                     /* make this a one time timer event */
  22077.                     regId1 =  _someRegister( some_gEMan,env, data, target,
  22078.                                              "eventMethod", "Timer 100" );
  22079.  
  22080.  
  22081. ΓòÉΓòÉΓòÉ 6.25. someSetRegDataTimerInterval ΓòÉΓòÉΓòÉ
  22082.  
  22083. someSetRegDataTimerInterval 
  22084.  
  22085. This method sets the timer interval within the registration data. 
  22086.  
  22087.  Syntax 
  22088.  
  22089.                     void someSetRegDataTimerInterval (SOMEEMRegisterData receiver,
  22090.                                         Environment *env, long interval)
  22091.  
  22092.  Parameters 
  22093.  
  22094.           receiver (SOMEEMRegisterData) 
  22095.                     A pointer to an object of class SOMEEMRegisterData. 
  22096.  
  22097.           env (Environment *) 
  22098.                     A pointer to the Environment structure for the calling 
  22099.                     method. 
  22100.  
  22101.           interval (long) 
  22102.                     An integer indicating the timer interval in milliseconds. 
  22103.  
  22104.  Returns 
  22105.  
  22106.           rc (void) 
  22107.  
  22108.  Remarks 
  22109.  
  22110.           This call allows setting the timer interval (in milliseconds) within 
  22111.           the registration data object. 
  22112.  
  22113.  Original Class 
  22114.  
  22115.           SOMEEMRegisterData 
  22116.  
  22117.  Related Methods 
  22118.  
  22119.           Methods: 
  22120.  
  22121.               someClearRegData 
  22122.  
  22123.  Example Code 
  22124.  
  22125.                     #include <eman.h>
  22126.                     long regId1;
  22127.  
  22128.                      ...
  22129.                     /* Register a timer */
  22130.                     _someClearRegData( data, env );
  22131.                     _someSetRegDataEventMask( data, env, EMTimerEvent, NULL );
  22132.                     _someSetRegDataTimerInterval( data, env, 100 );
  22133.                     /* Sets the timer interval to 100 milliseconds */
  22134.                     regId1 = _someRegister( some_gEMan,env, data, target,
  22135.                                             "eventMethod", "Timer 100" );
  22136.  
  22137.  
  22138. ΓòÉΓòÉΓòÉ 6.26. SOMEEvent ΓòÉΓòÉΓòÉ
  22139.  
  22140. SOMEEvent 
  22141.  
  22142.  File stem: event 
  22143.  
  22144.  Base 
  22145.  
  22146.           SOMObject 
  22147.  
  22148.  Metaclass 
  22149.  
  22150.           SOMClass 
  22151.  
  22152.  Ancestor Classes 
  22153.  
  22154.                     SOMClass
  22155.                        SOMObject
  22156.  
  22157.  Description 
  22158.  
  22159.           This is the base class for all generic events within the Event 
  22160.           Manager.  It simply temestamps an event before it is passed to a 
  22161.           callback routine.  The event type is set to the true type by a 
  22162.           subclass.  The types currently used by the Event Management Framework 
  22163.           are defined in eventmsk.h.  Any subclass of this class must avoid 
  22164.           name and value collisions with eventmsk.h. 
  22165.  
  22166.  New methods 
  22167.  
  22168.           The following list shows new methods defined for the SOMEEvent class. 
  22169.  
  22170.               somevGetEventTime 
  22171.               somevGetEventType 
  22172.               somevSetEventTime 
  22173.               somevSetEventType 
  22174.  
  22175.  Overridden methods 
  22176.  
  22177.           The following list shows all the methods overridden by the SOMEEvent 
  22178.           class. These methods are overridden in order to modify the behavior 
  22179.           defined by an ancestor class. 
  22180.  
  22181.               somInit 
  22182.  
  22183.  
  22184. ΓòÉΓòÉΓòÉ 6.27. somevGetEventTime ΓòÉΓòÉΓòÉ
  22185.  
  22186. somevGetEventTime Returns the time of the generic event in milliseconds. 
  22187.  
  22188.  Syntax 
  22189.  
  22190.                     unsigned long somevGetEventTime (SOMEEvent receiver,
  22191.                                         Environment *env)
  22192.  
  22193.  Parameters 
  22194.  
  22195.           receiver (SOMEEvent) 
  22196.                     A pointer to an object of class SOMEEvent. 
  22197.  
  22198.           env (Environment *) 
  22199.                     A pointer to the Environment structure for the calling 
  22200.                     method. 
  22201.  
  22202.  Returns 
  22203.  
  22204.           rc (unsigned long) 
  22205.                     An event timestamp in milliseconds. 
  22206.  
  22207.  Remarks 
  22208.  
  22209.           Eman timestamps every event before dispatching it. The current time 
  22210.           is obtained from the operating system (for example, using a 
  22211.           `gettimeofday' call), is converted to milliseconds, and is given as 
  22212.           the value of the timestamp. When this function is called, the event 
  22213.           timestamp is returned. 
  22214.  
  22215.  Original Class 
  22216.  
  22217.           SOMEEvent 
  22218.  
  22219.  Related Methods 
  22220.  
  22221.           Methods 
  22222.  
  22223.               somevSetEventTime 
  22224.  
  22225.  
  22226. ΓòÉΓòÉΓòÉ 6.28. somevGetEventType ΓòÉΓòÉΓòÉ
  22227.  
  22228. somevGetEventType Returns the type of the generic event. 
  22229.  
  22230.  Syntax 
  22231.  
  22232.                     unsigned long somevGetEventType (SOMEEvent receiver,
  22233.                                         Environment *env)
  22234.  
  22235.  Parameters 
  22236.  
  22237.           receiver (SOMEEvent) 
  22238.                     A pointer to an object of class SOMEEvent. 
  22239.  
  22240.           env (Environment *) 
  22241.                     A pointer to the Environment structure for the calling 
  22242.                     method. 
  22243.  
  22244.  Returns 
  22245.  
  22246.           rc (unsigned long) 
  22247.                     A type value (an integer constant defined in eventmsk.h). 
  22248.  
  22249.  Remarks 
  22250.  
  22251.           This method returns the true type of a given event object (for 
  22252.           example, to identify the particular subclass of the event object). 
  22253.           The type is an integer valued constant defined in eventmsk.h. 
  22254.  
  22255.  Original Class 
  22256.  
  22257.           SOMEEvent 
  22258.  
  22259.  Related Methods 
  22260.  
  22261.           Methods 
  22262.  
  22263.               somevSetEventType 
  22264.  
  22265.  
  22266. ΓòÉΓòÉΓòÉ 6.29. somevSetEventTime ΓòÉΓòÉΓòÉ
  22267.  
  22268. somevSetEventTime Sets the time of the generic event (time is in milliseconds). 
  22269.  
  22270.  Syntax 
  22271.  
  22272.                     void somevSetEventTime (SOMEEvent receiver, Environment *env,
  22273.                                   unsigned long time)
  22274.  
  22275.  Parameters 
  22276.  
  22277.           receiver (SOMEEvent) 
  22278.                     A pointer to an object of class SOMEEvent. 
  22279.  
  22280.           env (Environment *) 
  22281.                     A pointer to the Environment structure for the calling 
  22282.                     method. 
  22283.  
  22284.           time (unsigned long) 
  22285.  
  22286.  Returns 
  22287.  
  22288.           rc (void) 
  22289.  
  22290.  Remarks 
  22291.  
  22292.           EMan timestamps every event before dispatching it. The current time 
  22293.           is obtained from the operating system (for example, using a 
  22294.           `gettimeofday' call),  converted to milliseconds, and is given as the 
  22295.           value of the timestamp. When an event occurs, EMan sets the timestamp 
  22296.           of the event by calling this method. 
  22297.  
  22298.  Original Class 
  22299.  
  22300.           SOMEEvent 
  22301.  
  22302.  Related Methods 
  22303.  
  22304.           Methods 
  22305.  
  22306.               somevGetEventTime 
  22307.  
  22308.  
  22309. ΓòÉΓòÉΓòÉ 6.30. somevSetEventType ΓòÉΓòÉΓòÉ
  22310.  
  22311. somevSetEventType Sets the type of the generic event. 
  22312.  
  22313.  Syntax 
  22314.  
  22315.                     void somevSetEventType (SOMEEvent receiver, Environment *env,
  22316.                                   unsigned long type)
  22317.  
  22318.  Parameters 
  22319.  
  22320.           receiver (SOMEEvent) 
  22321.                     A pointer to an object of class SOMEEvent. 
  22322.  
  22323.           env (Environment *) 
  22324.                     A pointer to the Environment structure for the calling 
  22325.                     method. 
  22326.  
  22327.           type (unsigned long) 
  22328.                     An integer value indicating the type of the event (a 
  22329.                     constant defined in eventmsk.h). 
  22330.  
  22331.  Returns 
  22332.  
  22333.           rc (void) 
  22334.  
  22335.  Remarks 
  22336.  
  22337.           This method enables setting the true type of an event object. 
  22338.           Typically, a subclass of SOMEEvent calls this method (or overrides 
  22339.           this method) to set the event type to indicate its true type. 
  22340.  
  22341.  Original Class 
  22342.  
  22343.           SOMEEvent 
  22344.  
  22345.  Related Methods 
  22346.  
  22347.           Methods 
  22348.  
  22349.               somevGetEventType 
  22350.  
  22351.  
  22352. ΓòÉΓòÉΓòÉ 6.31. SOMESinkEvent ΓòÉΓòÉΓòÉ
  22353.  
  22354. SOMESinkEvent 
  22355.  
  22356.  File stem: sinkev 
  22357.  
  22358.  Base 
  22359.  
  22360.           SOMEEvent 
  22361.  
  22362.  Metaclass 
  22363.  
  22364.           SOMClass 
  22365.  
  22366.  Ancestor Classes 
  22367.  
  22368.                     SOMEEvent
  22369.                        SOMObject
  22370.  
  22371.  Description 
  22372.  
  22373.           This class describes a sink event that is generated by EMan when it 
  22374.           notices activity on a registered sink. On AIX, a sink refers to any 
  22375.           file descriptor ( file open for reading or writing), any pipe 
  22376.           descriptor, a socket ID or a message queue ID. On OS/2, a sink refers 
  22377.           to a socket ID. One can register for three types of interest in a 
  22378.           sink: Read interest, Write interest, and Exception interest. (See 
  22379.           eventmsk.h file to determine the appropriate bit constants and see 
  22380.           method someSetRegDataSinkMask for their use.) 
  22381.  
  22382.           EMan passes an instance of this class as a parameter to the callback 
  22383.           registered for Sink Events. The callback can query the instance for 
  22384.           some information on the sink. 
  22385.  
  22386.  New methods 
  22387.  
  22388.           The following list shows all the SOMESinkEvent methods. 
  22389.  
  22390.               somevGetEventSink 
  22391.               somevSetEventSink 
  22392.  
  22393.  Overridden methods 
  22394.  
  22395.           The following list shows all the methods overridden by the 
  22396.           SOMESinkEvent class. These methods are overridden in order to modify 
  22397.           the behavior defined by an ancestor class. 
  22398.  
  22399.               somInit 
  22400.  
  22401.  
  22402. ΓòÉΓòÉΓòÉ 6.32. somevGetEventSink ΓòÉΓòÉΓòÉ
  22403.  
  22404. somevGetEventSink This method returns the sink, or source of I/O, of the 
  22405. generic sink event. 
  22406.  
  22407.  Syntax 
  22408.  
  22409.                     long somevGetEventSink (SOMESinkEvent receiver, Environment *env)
  22410.  
  22411.  Parameters 
  22412.  
  22413.           receiver (SOMESinkEvent) 
  22414.                     A pointer to an object of class SOMESinkEvent. 
  22415.  
  22416.           env (Environment *) 
  22417.                     A pointer to the Environment structure for the calling 
  22418.                     method. 
  22419.  
  22420.  Returns 
  22421.  
  22422.           rc (long) 
  22423.                     An integer value indicating the file descriptor for 
  22424.                     input/output. It can also be a socket ID, pipe ID or a 
  22425.                     message queue ID. 
  22426.  
  22427.  Remarks 
  22428.  
  22429.           The sink ID in the SinkEvent is returned. For message queues it is 
  22430.           the queue ID, for files it is the file descriptor, for sockets it is 
  22431.           the socket ID, and for pipes it is the pipe descriptor. 
  22432.  
  22433.  Original Class 
  22434.  
  22435.           SOMESinkEvent 
  22436.  
  22437.  Related Methods 
  22438.  
  22439.           Methods: 
  22440.  
  22441.               somevSetEventSink 
  22442.  
  22443.  
  22444. ΓòÉΓòÉΓòÉ 6.33. somevSetEventSink ΓòÉΓòÉΓòÉ
  22445.  
  22446. somevSetEventSink 
  22447.  
  22448. This method sets the sink, or source of I/O, of the generic sink event. 
  22449.  
  22450.  Syntax 
  22451.  
  22452.                     void somevSetEventSink (SOMESinkEvent receiver, Environment *env,
  22453.                                   long sink)
  22454.  
  22455.  Parameters 
  22456.  
  22457.           receiver (SOMESinkEvent) 
  22458.                     A pointer to an object of class SOMESinkEvent. 
  22459.  
  22460.           env (Environment *) 
  22461.                     A pointer to the Environment structure for the calling 
  22462.                     method. 
  22463.  
  22464.           sink (long) 
  22465.                     An integer value indicating the file descriptor for 
  22466.                     input/output. It can also be a socket ID, pipe ID, or a 
  22467.                     message queue ID. 
  22468.  
  22469.  Returns 
  22470.  
  22471.           rc (void) 
  22472.  
  22473.  Remarks 
  22474.  
  22475.           The sink ID in the SinkEvent is set. For message queues, it is the 
  22476.           queue ID; for files it is the file descriptor; for sockets it is the 
  22477.           socket ID; and for pipes it is the pipe descriptor. 
  22478.  
  22479.  Original Class 
  22480.  
  22481.           SOMESinkEvent 
  22482.  
  22483.  Related Methods 
  22484.  
  22485.           Methods: 
  22486.  
  22487.               somevGetEventSink 
  22488.  
  22489.  
  22490. ΓòÉΓòÉΓòÉ 6.34. SOMETimerEvent ΓòÉΓòÉΓòÉ
  22491.  
  22492. SOMETimerEvent 
  22493.  
  22494.  File stem: timerev 
  22495.  
  22496.  Base 
  22497.  
  22498.           SOMEEvent 
  22499.  
  22500.  Metaclass 
  22501.  
  22502.           SOMClass 
  22503.  
  22504.  Ancestor Classes 
  22505.  
  22506.                     SOMEEvent
  22507.                        SOMObject
  22508.  
  22509.  Description 
  22510.  
  22511.           This class describes a timer event that is generated by EMan when any 
  22512.           of its registered timers pops. 
  22513.  
  22514.           EMan passes an instance of this class as a parameter to the callbacks 
  22515.           registered for Timer Events. The callback can query the instance for 
  22516.           information on the timer interval and on any generic event 
  22517.           properties. 
  22518.  
  22519.  New methods 
  22520.  
  22521.           The following list shows all the SOMETimerEvent methods. 
  22522.  
  22523.               somevGetEventInterval 
  22524.               somevSetEventInterval 
  22525.  
  22526.  Overridden methods 
  22527.  
  22528.           The following list shows all the methods overridden by the 
  22529.           SOMETimerEvent class. These methods are overridden in order to modify 
  22530.           the behavior defined by an ancestor class. 
  22531.  
  22532.               somInit 
  22533.  
  22534.  
  22535. ΓòÉΓòÉΓòÉ 6.35. somevGetEventInterval ΓòÉΓòÉΓòÉ
  22536.  
  22537. somevGetEventInterval This method returns the interval of the generic timer 
  22538. event (time in milliseconds). 
  22539.  
  22540.  Syntax 
  22541.  
  22542.                     void somevGetEventInterval (SOMETimerEvent receiver,
  22543.                                     Environment *env)
  22544.  
  22545.  Parameters 
  22546.  
  22547.           receiver (SOMETimerEvent) 
  22548.                     A pointer to an object of class SOMETimerEvent. 
  22549.  
  22550.           env (Environment *) 
  22551.                     A pointer to the Environment structure for the calling 
  22552.                     method. 
  22553.  
  22554.  Returns 
  22555.  
  22556.           rc (void) 
  22557.                     The interval time in milliseconds. 
  22558.  
  22559.  Remarks 
  22560.  
  22561.           The somevGetEventInterval method returns the interval of the generic 
  22562.           timer event (time in milliseconds). 
  22563.  
  22564.  Original Class 
  22565.  
  22566.           SOMETimerEvent 
  22567.  
  22568.  Related Methods 
  22569.  
  22570.           Methods 
  22571.  
  22572.               somevSetEventInterval 
  22573.  
  22574.  
  22575. ΓòÉΓòÉΓòÉ 6.36. somevSetEventInterval ΓòÉΓòÉΓòÉ
  22576.  
  22577. somevSetEventInterval This method sets the interval of the generic timer event 
  22578. (in milliseconds). 
  22579.  
  22580.  Syntax 
  22581.  
  22582.                     void somevSetEventInterval (SOMETimerEvent receiver,
  22583.                                     Environment *env, long interval)
  22584.  
  22585.  Parameters 
  22586.  
  22587.           receiver (SOMETimerEvent) 
  22588.                     A pointer to an object of class SOMETimerEvent. 
  22589.  
  22590.           env (Environment *) 
  22591.                     A pointer to the Environment structure for the calling 
  22592.                     method. 
  22593.  
  22594.           interval (long) 
  22595.                     The timer interval in milliseconds. 
  22596.  
  22597.  Returns 
  22598.  
  22599.           rc (void) 
  22600.  
  22601.  Remarks 
  22602.  
  22603.           The somevSetEventInterval method sets the interval of the generic 
  22604.           timer event (in milliseconds). 
  22605.  
  22606.  Original Class 
  22607.  
  22608.           SOMETimerEvent 
  22609.  
  22610.  Related Methods 
  22611.  
  22612.           Methods 
  22613.  
  22614.               somevGetEventInterval 
  22615.  
  22616.  
  22617. ΓòÉΓòÉΓòÉ 6.37. SOMEWorkProcEvent ΓòÉΓòÉΓòÉ
  22618.  
  22619. SOMEWorkProcEvent 
  22620.  
  22621.  File stem: workprev 
  22622.  
  22623.  Base 
  22624.  
  22625.           SOMEEvent 
  22626.  
  22627.  Metaclass 
  22628.  
  22629.           SOMClass 
  22630.  
  22631.  Ancestor Classes 
  22632.  
  22633.                     SOMEEvent
  22634.                        SOMObject
  22635.  
  22636.  Description 
  22637.  
  22638.           This class describes a work procedure event object. It currently has 
  22639.           no methods of its own. However, it sets the event type in its super 
  22640.           class to say "EMWorkProcEvent" to help identify itself. These events 
  22641.           are created and dispatched by EMan when a work procedure (something 
  22642.           that the application wants to run when no other events are happening) 
  22643.           is registered with EMan. 
  22644.  
  22645.           EMan passes an instance of this class as a parameter to the callback 
  22646.           registered for WorkProc Events. 
  22647.  
  22648.  New methods 
  22649.  
  22650.           There are currently no new methods defined for the SOMEWorkProcEvent 
  22651.           class. 
  22652.  
  22653.  Overridden methods 
  22654.  
  22655.           The following list shows all the methods overridden by the 
  22656.           SOMEWorkProcEvent class. These methods are overridden in order to 
  22657.           modify the behavior defined by an ancestor class. 
  22658.  
  22659.               somInit 
  22660.