path: root/lib/ic/doc/src/ch_c_corba_env.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>1998</year><year>2016</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>CORBA_Environment C Structure</title>
    <prepared></prepared>
    <docno></docno>
    <date>2003-12-15</date>
    <rev>PC1</rev>
    <file>ch_c_corba_env.xml</file>
  </header>
  <marker id="corbaenv"></marker>
  <p>This chapter describes the CORBA_Environment C structure.</p>

  <section>
    <title>C Structure</title>
    <p>Here is the complete definition of the CORBA_Environment 
      C structure, defined in file "ic.h" : </p>
    <code type="none">
/* Environment definition */
typedef struct {

  /*----- CORBA compatibility part ------------------------*/
  /* Exception tag, initially set to CORBA_NO_EXCEPTION ---*/
  CORBA_exception_type   _major;          

  /*----- External Implementation part - initiated by the user ---*/
  /* File descriptor                                              */
  int                    _fd;             
  /* Size of input buffer                                         */
  int                    _inbufsz;        
  /* Pointer to always dynamically allocated buffer for input     */
  char                  *_inbuf;         
  /* Size of output buffer                                        */
  int                    _outbufsz;       
  /* Pointer to always dynamically allocated buffer for output    */ 
  char                  *_outbuf;        
 /* Size of memory chunks in bytes, used for increasing the output
    buffer, set to >= 32, should be around >= 1024 for performance
    reasons                                                       */ 
 int                    _memchunk;       
 /* Pointer for registered name                                   */
  char                   _regname[256];   
 /* Process identity for caller                                   */
  erlang_pid            *_to_pid;         
  /* Process identity for callee                                  */ 
  erlang_pid            *_from_pid;      

  /*- Internal Implementation part - used by the server/client ---*/
  /* Index for input buffer                                       */
  int                    _iin;            
  /* Index for output buffer                                      */
  int                    _iout;          
  /* Pointer for operation name                                   */
  char                   _operation[256];
   /* Used to count parameters                                    */
  int                    _received;      
  /* Used to identify the caller                                  */
  erlang_pid             _caller;        
 /* Used to identify the call                                     */
  erlang_ref             _unique;         
  /* Exception id field                                           */
  CORBA_char            *_exc_id;        
  /* Exception value field                                        */
   void                  *_exc_value;           

  
} CORBA_Environment; 
    </code>
    <p>The structure is divided into three parts:</p>
    <list type="bulleted">
      <item>
        <p>The CORBA Compatibility part, demanded by the standard OMG
          IDL mapping v2.0.</p>
      </item>
      <item>
        <p>The external implementation part used for generated
          client/server code.</p>
      </item>
      <item>
        <p>The internal part useful for those who wish to define their
          own functions.</p>
      </item>
    </list>
  </section>

  <section>
    <title>The CORBA Compatibility Part</title>
    <p>Contains only one field <c>_major</c> defined as a
      CORBA_Exception_type.  The CORBA_Exception type is an integer
      which can be one of:</p>
    <list type="bulleted">
      <item>
        <p><em>CORBA_NO_EXCEPTION</em>, by default equal to 0, can be
          set by the application programmer to another value.</p>
      </item>
      <item>
        <p><em>CORBA_SYSTEM_EXCEPTION</em>, by default equal to -1, can
          be set by the application programmer to another value.</p>
      </item>
    </list>
    <p>The current definition of these values are:</p>
    <code type="none">
      #define CORBA_NO_EXCEPTION      0
      #define CORBA_SYSTEM_EXCEPTION -1
    </code>
  </section>

  <section>
    <title>The External Part</title>
    <p>This part contains the following fields:</p>
    <list type="bulleted">
      <item>
        <p>int <em>_fd</em> - a file descriptor returned from
          erl_connect.  Used for connection setting.</p>
      </item>
      <item>
        <p>char* <em>_inbuf</em> - pointer to a buffer used for
          input. Buffer size checks are done under runtime that
          prevent buffer overflows.  This is done by expanding the
          buffer to fit the input message.  In order to allow buffer
          reallocation, the output buffer must always be dynamically
          allocated.  The pointer value can change under runtime in
          case of buffer reallocation.</p>
      </item>
      <item>
        <p>int <em>_inbufsz</em> - start size of input buffer.  Used
          for setting the input buffer size under initialization of
          the Erl_Interface function ei_receive_encoded/5.  The value
          of this field can change under runtime in case of input
          buffer expansion to fit larger messages</p>
      </item>
      <item>
        <p>int <em>_outbufsz</em> - start size of output buffer. The
          value of this field can change under runtime in case of
          input buffer expansion to fit larger messages</p>
      </item>
      <item>
        <p>char* <em>_outbuf</em> - pointer to a buffer used for
          output.  Buffer size checks prevent buffer overflows under
          runtime, by expanding the buffer to fit the output message
          in cases of lack of space in buffer. In order to allow
          buffer reallocation, the output buffer must always be
          dynamically allocated.  The pointer value can change under
          runtime in case of buffer reallocation.</p>
      </item>
      <item>
        <p>int <em>_memchunk</em> - expansion unit size for the output
          buffer.  This is the size of memory chunks in bytes used for
          increasing the output in case of buffer expansion. The value
          of this field must be always set to &gt;= 32, should be at
          least 1024 for performance reasons.</p>
      </item>
      <item>
        <p>char <em>regname[256]</em> - a registered name for a process. </p>
      </item>
      <item>
        <p>erlang_pid* <em>_to_pid</em> - an Erlang process identifier,
          is only used if the registered_name parameter is the empty
          string.</p>
      </item>
      <item>
        <p>erlang_pid* <em>_from_pid</em> - your own process id so the
          answer can be returned.</p>
      </item>
    </list>
  </section>

  <section>
    <title>The Internal Part</title>
    <p>This part contains the following fields:</p>
    <list type="bulleted">
      <item>
        <p>int <em>_iin</em> - Index for input buffer.  Initially set
          to zero.  Updated to agree with the length of the received
          encoded message.</p>
      </item>
      <item>
        <p>int <em>_iout</em> - Index for output buffer Initially set
          to zero.  Updated to agree with the length of the message
          encoded to the communication counterpart.</p>
      </item>
      <item>
        <p>char <em>_operation[256]</em> - Pointer for operation name.
          Set to the operation to be called.</p>
      </item>
      <item>
        <p>int <em>_received</em> - Used to count parameters.
          Initially set to zero.</p>
      </item>
      <item>
        <p>erlang_pid <em>_caller</em> - Used to identify the caller.
          Initiated to a value that identifies the caller.</p>
      </item>
      <item>
        <p>erlang_ref <em>_unique</em> - Used to identify the call.
          Set to a default value in the case of generated functions.</p>
      </item>
      <item>
        <p>CORBA_char* <em>_exc_id</em> - Exception id field.
          Initially set to NULL to agree with the initial value of
          _major (CORBA_NO_EXCEPTION).</p>
      </item>
      <item>
        <p>void* <em>_exc_value</em> - Exception value field Initially
          set to <em>NULL</em> to agree with the initial value of
          _major (CORBA_NO_EXCEPTION).</p>
      </item>
    </list>
    <p>The advanced user who defines his own functions has to
      update/support these values in a way similar to how they are
      updated in the generated code.</p>
  </section>

  <section>
    <title>Creating and Initiating the CORBA_Environment Structure</title>
    <p>There are two ways to set the CORBA_Environment structure:</p>
    <list type="bulleted">
      <item>
        <p>Manually</p>
        <p>The following default values must be set to the
          CORBA_Environment *<em>ev</em> fields, when buffers for
          input/output should have the size <em>inbufsz</em>/
          <em>outbufsz</em>:</p>
        <list type="bulleted">
          <item>
            <p><em>ev->_inbufsz</em> = <em>inbufsz</em>;</p>
            <p>The value for this field can be between 0 and maximum
              size of a signed integer.</p>
          </item>
          <item>
            <p><em>ev->_inbuf</em> = malloc(<em>inbufsz</em>);</p>
            <p>The size of the allocated buffer must be equal to the
              value of its corresponding index, _inbufsz.</p>
          </item>
          <item>
            <p><em>ev->_outbufsz</em> = <em>outbufsz</em>;</p>
            <p>The value for this field can be between 0 and maximum
              size of a signed integer.</p>
          </item>
          <item>
            <p><em>ev->_outbuf</em> = malloc(<em>outbufsz</em>);</p>
            <p>The size of the allocated buffer must be equal to the
              value of its corresponding index, _outbufsz.</p>
          </item>
          <item>
            <p><em>ev->_memchunk</em> = <em>__OE_MEMCHUNK__</em>;</p>
            <p>Please note that __OE_MEMCHUNK__ is equal to
              <em>1024</em>, you can set this value to a value bigger
              than 32 yourself.</p>
          </item>
          <item>
            <p><em>ev->_to_pid</em> = <em>NULL</em>;</p>
          </item>
          <item>
            <p><em>ev->_from_pid</em> = <em>NULL</em>;</p>
          </item>
        </list>
        <p></p>
      </item>
      <item>
        <p>By using the <em>CORBA_Environment_alloc</em>/2 function. </p>
        <p>The CORBA_Environment_alloc function is defined as:</p>
        <code type="none">
          CORBA_Environment *CORBA_Environment_alloc(int inbufsz, 
                                                     int outbufsz);
        </code>
        <p>where:</p>
        <list type="bulleted">
          <item>
            <p><em>inbufsz</em> is the desired size of input buffer</p>
          </item>
          <item>
            <p><em>outbufsz</em> is the desired size of output
              buffer</p>
          </item>
          <item>
            <p>return value is a <em>pointer</em> to an allocated and
              initialized <em>CORBA_Environment</em> structure.</p>
            <p></p>
          </item>
        </list>
        <p>This function will set all needed default values and
          allocate buffers equal to the values passed, but will not
          allocate space for the _to_pid and _from_pid fields.</p>
        <p>To free the space allocated by CORBA_Environment_alloc/2:</p>
        <list type="bulleted">
          <item>
            <p>First call CORBA_free for the input and output buffers.</p>
          </item>
          <item>
            <p>After freeing the buffer space, call CORBA_free for
              the CORBA_Environment space.</p>
          </item>
        </list>
      </item>
    </list>
    <note>
      <p>Remember to set the fields <em>_fd</em>, <em>_regname</em>,
        <em>*_to_pid</em> and/or <em>*_from_pid</em> to the
        appropriate application values. These are not automatically
        set by the stubs.</p>
    </note>
    <warning>
      <p>Never assign static buffers to the buffer pointers. Never set
        the <em>_memchunk</em> field to a value less than
        <em>32</em>.</p>
    </warning>
  </section>

  <section>
    <title>Setting System Exceptions</title>
    <p>If the user wishes to set own system exceptions at critical
      positions on the code, it is strongly recommended to use one of
      the current values:</p>
    <list type="bulleted">
      <item>
        <p>CORBA_NO_EXCEPTION upon success.  The value of the _exc_id
          field should be then set to NULL.  The value of the
          _exc_value field should be then set to NULL.</p>
      </item>
      <item>
        <p>CORBA_SYSTEM_EXCEPTION upon system failure.  The value of
          the _exc_id field should be then set to one of the values
          defined in "ic.h" :</p>
        <code type="none">
  #define UNKNOWN          "UNKNOWN"
  #define BAD_PARAM        "BAD_PARAM"
  #define NO_MEMORY        "NO_MEMORY"
  #define IMPL_LIMIT       "IMP_LIMIT"
  #define COMM_FAILURE     "COMM_FAILURE"
  #define INV_OBJREF       "INV_OBJREF"
  #define NO_PERMISSION    "NO_PERMISSION"
  #define INTERNAL         "INTERNAL"
  #define MARSHAL          "MARSHAL"
  #define INITIALIZE       "INITIALIZE"
  #define NO_IMPLEMENT     "NO_IMPLEMENT"
  #define BAD_TYPECODE     "BAD_TYPECODE"
  #define BAD_OPERATION    "BAD_OPERATION"
  #define NO_RESOURCES     "NO_RESOURCES"
  #define NO_RESPONSE      "NO_RESPONSE"
  #define PERSIST_STORE    "PERSIST_STORE"
  #define BAD_INV_ORDER    "BAD_INV_ORDER"
  #define TRANSIENT        "TRANSIENT"
  #define FREE_MEM         "FREE_MEM"
  #define INV_IDENT        "INV_IDENT"
  #define INV_FLAG         "INV_FLAG"
  #define INTF_REPOS       "INTF_REPOS"
  #define BAD_CONTEXT      "BAD_CONTEXT"
  #define OBJ_ADAPTER      "OBJ_ADAPTER"
  #define DATA_CONVERSION  "DATA_CONVERSION"
  #define OBJ_NOT_EXIST    "OBJECT_NOT_EXIST"
        </code>
      </item>
    </list>
    <p>The value of the _exc_value field should be then set to a string
      that explains the problem in an informative way.  The user
      should use the functions CORBA_exc_set/4 and
      CORBA_exception_free/1 to free the exception.
      The user has to use CORBA_exception_id/1 and
      CORBA_exception_value/1 to access exception information.
      Prototypes for these functions are declared in "ic.h"</p>
  </section>
</chapter>