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 | 386 |
1 files changed, 0 insertions, 386 deletions
diff --git a/lib/ic/doc/src/ch_c_corba_env.xml b/lib/ic/doc/src/ch_c_corba_env.xml deleted file mode 100644 index 1bd829307e..0000000000 --- a/lib/ic/doc/src/ch_c_corba_env.xml +++ /dev/null @@ -1,386 +0,0 @@ -<?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 >= 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> - - |