diff options
Diffstat (limited to 'lib/ic/doc/src/ch_c_corba_env.xml')
| -rw-r--r-- | lib/ic/doc/src/ch_c_corba_env.xml | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/lib/ic/doc/src/ch_c_corba_env.xml b/lib/ic/doc/src/ch_c_corba_env.xml new file mode 100644 index 0000000000..557eeffdd4 --- /dev/null +++ b/lib/ic/doc/src/ch_c_corba_env.xml @@ -0,0 +1,385 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights 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 >= 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"> +\\011 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> + + |