<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- CORBA_Environment C Structure</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/ic-4.2.31.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>ic</strong><br><strong>User's Guide</strong><br><small>Version 4.2.31</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="Using the IC Compiler" expanded="false">Using the IC Compiler<ul>
<li><a href="ch_introduction.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_introduction.html#id62832">Introduction</a></li>
<li title="Compilation of IDL Files"><a href="ch_introduction.html#id60118">Compilation of IDL Files</a></li>
</ul>
</li>
<li id="no" title="OMG IDL" expanded="false">OMG IDL<ul>
<li><a href="ch_basic_idl.html">
Top of chapter
</a></li>
<li title="OMG IDL - Overview"><a href="ch_basic_idl.html#id61149">OMG IDL - Overview</a></li>
</ul>
</li>
<li id="no" title="IC Protocol" expanded="false">IC Protocol<ul>
<li><a href="ch_ic_protocol.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_ic_protocol.html#id66622">Introduction</a></li>
<li title="Language mappings and IDL operations"><a href="ch_ic_protocol.html#id63114">Language mappings and IDL operations</a></li>
<li title="IC Protocol"><a href="ch_ic_protocol.html#id64104">IC Protocol</a></li>
<li title="Gen_server Protocol"><a href="ch_ic_protocol.html#id65537">Gen_server Protocol</a></li>
<li title="Erlang Distribution Protocol"><a href="ch_ic_protocol.html#id65584">Erlang Distribution Protocol</a></li>
</ul>
</li>
<li id="no" title="Using the Plain Erlang Back-end" expanded="false">Using the Plain Erlang Back-end<ul>
<li><a href="ch_erl_plain.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_plain.html#id63664">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_plain.html#id63678">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_plain.html#id63697">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_plain.html#id63754">An Example</a></li>
</ul>
</li>
<li id="no" title="Using the Erlang Generic Server Back-end" expanded="false">Using the Erlang Generic Server Back-end<ul>
<li><a href="ch_erl_genserver.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_erl_genserver.html#id63935">Introduction</a></li>
<li title="Compiling the Code"><a href="ch_erl_genserver.html#id63953">Compiling the Code</a></li>
<li title="Writing the Implementation File"><a href="ch_erl_genserver.html#id63977">Writing the Implementation File</a></li>
<li title="An Example"><a href="ch_erl_genserver.html#id69038">An Example</a></li>
</ul>
</li>
<li id="no" title="IDL to C mapping" expanded="false">IDL to C mapping<ul>
<li><a href="ch_c_mapping.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_mapping.html#id69337">Introduction</a></li>
<li title="C Mapping Characteristics"><a href="ch_c_mapping.html#id69440">C Mapping Characteristics</a></li>
<li title="Basic OMG IDL Types"><a href="ch_c_mapping.html#id69638">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_c_mapping.html#id70147">Constructed OMG IDL Types</a></li>
<li title="OMG IDL Constants"><a href="ch_c_mapping.html#id71595">OMG IDL Constants</a></li>
<li title="OMG IDL Operations"><a href="ch_c_mapping.html#id71622">OMG IDL Operations</a></li>
<li title="Exceptions"><a href="ch_c_mapping.html#id71884">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_c_mapping.html#id71897">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for the C-client"><a href="ch_c_mapping.html#id71908">Summary of Argument/Result Passing for the C-client</a></li>
<li title="Supported Memory Allocation Functions"><a href="ch_c_mapping.html#id73513">Supported Memory Allocation Functions</a></li>
<li title="Special Memory Deallocation Functions"><a href="ch_c_mapping.html#id73642">Special Memory Deallocation Functions</a></li>
<li title="Exception Access Functions"><a href="ch_c_mapping.html#id73681">Exception Access Functions</a></li>
<li title="Special Types"><a href="ch_c_mapping.html#id73720">Special Types</a></li>
<li title="A Mapping Example"><a href="ch_c_mapping.html#id73844">A Mapping Example</a></li>
</ul>
</li>
<li id="no" title="The C Client Back-end" expanded="false">The C Client Back-end<ul>
<li><a href="ch_c_client.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_client.html#id73982">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_client.html#id74007">Generated Stub Files</a></li>
<li title="C Interface Functions"><a href="ch_c_client.html#id74057">C Interface Functions</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_client.html#id74134">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_client.html#id74198">An Example</a></li>
</ul>
</li>
<li id="no" title="The C Server Back-end" expanded="false">The C Server Back-end<ul>
<li><a href="ch_c_server.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_c_server.html#id74326">Introduction</a></li>
<li title="Generated Stub Files"><a href="ch_c_server.html#id74352">Generated Stub Files</a></li>
<li title="C Skeleton Functions"><a href="ch_c_server.html#id74402">C Skeleton Functions</a></li>
<li title="The Server Loop"><a href="ch_c_server.html#id74461">The Server Loop</a></li>
<li title="Generating, Compiling and Linking"><a href="ch_c_server.html#id74488">Generating, Compiling and Linking</a></li>
<li title="An Example"><a href="ch_c_server.html#id74553">An Example</a></li>
</ul>
</li>
<li id="loadscrollpos" title="CORBA_Environment C Structure" expanded="true">CORBA_Environment C Structure<ul>
<li><a href="ch_c_corba_env.html">
Top of chapter
</a></li>
<li title="C Structure"><a href="ch_c_corba_env.html#id74686">C Structure</a></li>
<li title="The CORBA Compatibility Part"><a href="ch_c_corba_env.html#id74758">The CORBA Compatibility Part</a></li>
<li title="The External Part"><a href="ch_c_corba_env.html#id74811">The External Part</a></li>
<li title="The Internal Part"><a href="ch_c_corba_env.html#id74944">The Internal Part</a></li>
<li title="Creating and Initiating the CORBA_Environment Structure"><a href="ch_c_corba_env.html#id75066">Creating and Initiating the CORBA_Environment Structure</a></li>
<li title="Setting System Exceptions"><a href="ch_c_corba_env.html#id75376">Setting System Exceptions</a></li>
</ul>
</li>
<li id="no" title="IDL to Java language Mapping" expanded="false">IDL to Java language Mapping<ul>
<li><a href="ch_java.html">
Top of chapter
</a></li>
<li title="Introduction"><a href="ch_java.html#id75488">Introduction</a></li>
<li title="Specialties in the Mapping"><a href="ch_java.html#id75549">Specialties in the Mapping</a></li>
<li title="Basic OMG IDL Types"><a href="ch_java.html#id75576">Basic OMG IDL Types</a></li>
<li title="Constructed OMG IDL Types"><a href="ch_java.html#id75983">Constructed OMG IDL Types</a></li>
<li title="Mapping for Constants"><a href="ch_java.html#id76049">Mapping for Constants</a></li>
<li title="Invocations of Operations"><a href="ch_java.html#id76060">Invocations of Operations</a></li>
<li title="Exceptions"><a href="ch_java.html#id76110">Exceptions</a></li>
<li title="Access to Attributes"><a href="ch_java.html#id76123">Access to Attributes</a></li>
<li title="Summary of Argument/Result Passing for Java"><a href="ch_java.html#id76134">Summary of Argument/Result Passing for Java</a></li>
<li title="Communication Toolbox"><a href="ch_java.html#id76192">Communication Toolbox</a></li>
<li title="The Package com.ericsson.otp.ic"><a href="ch_java.html#id76492">The Package com.ericsson.otp.ic</a></li>
<li title="The Term Class"><a href="ch_java.html#id76892">The Term Class</a></li>
<li title="Stub File Types"><a href="ch_java.html#id77170">Stub File Types</a></li>
<li title="Client Stub Initialization, Methods Exported"><a href="ch_java.html#id77234">Client Stub Initialization, Methods Exported</a></li>
<li title="Server Skeleton Initialization, Server Stub Implementation, Methods Exported"><a href="ch_java.html#id77415">Server Skeleton Initialization, Server Stub Implementation, Methods Exported</a></li>
<li title="A Mapping Example"><a href="ch_java.html#id77546">A Mapping Example</a></li>
<li title="Running the Compiled Code"><a href="ch_java.html#id77630">Running the Compiled Code</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>9 CORBA_Environment C Structure</h1>
<a name="corbaenv"></a>
<p>This chapter describes the CORBA_Environment C structure.</p>
<h3><a name="id74686">9.1
C Structure</a></h3>
<p>Here is the complete definition of the CORBA_Environment
C structure, defined in file "ic.h" : </p>
<div class="example"><pre>
/* 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;
</pre></div>
<p>The structure is divided into three parts:</p>
<ul>
<li>
<p>The CORBA Compatibility part, demanded by the standard OMG
IDL mapping v2.0.</p>
</li>
<li>
<p>The external implementation part used for generated
client/server code.</p>
</li>
<li>
<p>The internal part useful for those who wish to define their
own functions.</p>
</li>
</ul>
<h3><a name="id74758">9.2
The CORBA Compatibility Part</a></h3>
<p>Contains only one field <span class="code">_major</span> defined as a
CORBA_Exception_type. The CORBA_Exception type is an integer
which can be one of:</p>
<ul>
<li>
<p><strong>CORBA_NO_EXCEPTION</strong>, by default equal to 0, can be
set by the application programmer to another value.</p>
</li>
<li>
<p><strong>CORBA_SYSTEM_EXCEPTION</strong>, by default equal to -1, can
be set by the application programmer to another value.</p>
</li>
</ul>
<p>The current definition of these values are:</p>
<div class="example"><pre>
#define CORBA_NO_EXCEPTION 0
#define CORBA_SYSTEM_EXCEPTION -1
</pre></div>
<h3><a name="id74811">9.3
The External Part</a></h3>
<p>This part contains the following fields:</p>
<ul>
<li>
<p>int <strong>_fd</strong> - a file descriptor returned from
erl_connect. Used for connection setting.</p>
</li>
<li>
<p>char* <strong>_inbuf</strong> - 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>
</li>
<li>
<p>int <strong>_inbufsz</strong> - 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>
</li>
<li>
<p>int <strong>_outbufsz</strong> - 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>
</li>
<li>
<p>char* <strong>_outbuf</strong> - 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>
</li>
<li>
<p>int <strong>_memchunk</strong> - 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>
</li>
<li>
<p>char <strong>regname[256]</strong> - a registered name for a process. </p>
</li>
<li>
<p>erlang_pid* <strong>_to_pid</strong> - an Erlang process identifier,
is only used if the registered_name parameter is the empty
string.</p>
</li>
<li>
<p>erlang_pid* <strong>_from_pid</strong> - your own process id so the
answer can be returned.</p>
</li>
</ul>
<h3><a name="id74944">9.4
The Internal Part</a></h3>
<p>This part contains the following fields:</p>
<ul>
<li>
<p>int <strong>_iin</strong> - Index for input buffer. Initially set
to zero. Updated to agree with the length of the received
encoded message.</p>
</li>
<li>
<p>int <strong>_iout</strong> - Index for output buffer Initially set
to zero. Updated to agree with the length of the message
encoded to the communication counterpart.</p>
</li>
<li>
<p>char <strong>_operation[256]</strong> - Pointer for operation name.
Set to the operation to be called.</p>
</li>
<li>
<p>int <strong>_received</strong> - Used to count parameters.
Initially set to zero.</p>
</li>
<li>
<p>erlang_pid <strong>_caller</strong> - Used to identify the caller.
Initiated to a value that identifies the caller.</p>
</li>
<li>
<p>erlang_ref <strong>_unique</strong> - Used to identify the call.
Set to a default value in the case of generated functions.</p>
</li>
<li>
<p>CORBA_char* <strong>_exc_id</strong> - Exception id field.
Initially set to NULL to agree with the initial value of
_major (CORBA_NO_EXCEPTION).</p>
</li>
<li>
<p>void* <strong>_exc_value</strong> - Exception value field Initially
set to <strong>NULL</strong> to agree with the initial value of
_major (CORBA_NO_EXCEPTION).</p>
</li>
</ul>
<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>
<h3><a name="id75066">9.5
Creating and Initiating the CORBA_Environment Structure</a></h3>
<p>There are two ways to set the CORBA_Environment structure:</p>
<ul>
<li>
<p>Manually</p>
<p>The following default values must be set to the
CORBA_Environment *<strong>ev</strong> fields, when buffers for
input/output should have the size <strong>inbufsz</strong>/
<strong>outbufsz</strong>:</p>
<ul>
<li>
<p><strong>ev->_inbufsz</strong> = <strong>inbufsz</strong>;</p>
<p>The value for this field can be between 0 and maximum
size of a signed integer.</p>
</li>
<li>
<p><strong>ev->_inbuf</strong> = malloc(<strong>inbufsz</strong>);</p>
<p>The size of the allocated buffer must be equal to the
value of its corresponding index, _inbufsz.</p>
</li>
<li>
<p><strong>ev->_outbufsz</strong> = <strong>outbufsz</strong>;</p>
<p>The value for this field can be between 0 and maximum
size of a signed integer.</p>
</li>
<li>
<p><strong>ev->_outbuf</strong> = malloc(<strong>outbufsz</strong>);</p>
<p>The size of the allocated buffer must be equal to the
value of its corresponding index, _outbufsz.</p>
</li>
<li>
<p><strong>ev->_memchunk</strong> = <strong>__OE_MEMCHUNK__</strong>;</p>
<p>Please note that __OE_MEMCHUNK__ is equal to
<strong>1024</strong>, you can set this value to a value bigger
than 32 yourself.</p>
</li>
<li>
<p><strong>ev->_to_pid</strong> = <strong>NULL</strong>;</p>
</li>
<li>
<p><strong>ev->_from_pid</strong> = <strong>NULL</strong>;</p>
</li>
</ul>
<p></p>
</li>
<li>
<p>By using the <strong>CORBA_Environment_alloc</strong>/2 function. </p>
<p>The CORBA_Environment_alloc function is defined as:</p>
<div class="example"><pre>
CORBA_Environment *CORBA_Environment_alloc(int inbufsz,
int outbufsz);
</pre></div>
<p>where:</p>
<ul>
<li>
<p><strong>inbufsz</strong> is the desired size of input buffer</p>
</li>
<li>
<p><strong>outbufsz</strong> is the desired size of output
buffer</p>
</li>
<li>
<p>return value is a <strong>pointer</strong> to an allocated and
initialized <strong>CORBA_Environment</strong> structure.</p>
<p></p>
</li>
</ul>
<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>
<ul>
<li>
<p>First call CORBA_free for the input and output buffers.</p>
</li>
<li>
<p>After freeing the buffer space, call CORBA_free for
the CORBA_Environment space.</p>
</li>
</ul>
</li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Remember to set the fields <strong>_fd</strong>, <strong>_regname</strong>,
<strong>*_to_pid</strong> and/or <strong>*_from_pid</strong> to the
appropriate application values. These are not automatically
set by the stubs.</p>
</p></div>
</div>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<p>Never assign static buffers to the buffer pointers. Never set
the <strong>_memchunk</strong> field to a value less than
<strong>32</strong>.</p>
</p></div>
</div>
<h3><a name="id75376">9.6
Setting System Exceptions</a></h3>
<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>
<ul>
<li>
<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>
</li>
<li>
<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>
<div class="example"><pre>
#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"
</pre></div>
</li>
</ul>
<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>
</div>
<div class="footer">
<hr>
<p>Copyright © 1998-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
704
