<!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 -- The C Server Back-end</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="loadscrollpos" title="The C Server Back-end" expanded="true">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="no" title="CORBA_Environment C Structure" expanded="false">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>8 The C Server Back-end</h1>
<h3><a name="id74326">8.1
Introduction</a></h3>
<p>With the option <span class="code">{be, c_server}</span> the IDL Compiler generates
C server skeletons according to the IDL to C mapping, on top of
the Erlang distribution and gen_server protocols.</p>
<p>The developer has to write additional code, that together with
the generated C server skeletons, form a hidden Erlang
node. That additional code contains implementations of call-back
functions that implement the true server functionality, and also
code uses <span class="code">erl_interface</span> functions for defining the hidden
node and for establishing connections to other Erlang nodes.</p>
<h3><a name="id74352">8.2
Generated Stub Files</a></h3>
<p>The generated stub files are:</p>
<ul>
<li>
<p>For each IDL interface, a C source file, the name of which
is <span class="code"><Scoped Interface Name>__s.c</span>. Each operation of the
IDL interface is mapped to a C function (with scoped name)
in that file;</p>
</li>
<li>
<p>C source files that contain functions for type conversion,
memory allocation, and data encoding/decoding;</p>
</li>
<li>
<p>C header files that contain function prototypes and type
definitions.</p>
</li>
</ul>
<p>All C functions are exported (i.e. not declared static).</p>
<h3><a name="id74402">8.3
C Skeleton Functions</a></h3>
<p>For each IDL operation a C skeleton function is generated, the
prototype of which is <span class="code">int <Scoped Function Name>__exec(<Interface Object> oe_obj, CORBA_Environment *oe_env)</span>, where <span class="code"><Interface Object></span>, and
<span class="code">CORBA_Environment</span> are of the same type as for the
generated C client stubs code.</p>
<p>Each <span class="code"><Scoped Function Name>__exec()</span> function calls the
call-back function</p>
<p><span class="code"><Scoped Function Name>_rs* <Scoped Function Name>__cb(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env)</span></p>
<p>where the arguments are of the same type as those generated for
C client stubs. </p>
<p>The return value <span class="code"><Scoped Function Name>_rs* </span> is a pointer
to a function with the same signature as the call-back function
<span class="code"><Scoped Function Name>_cb</span>, and is called after the call-back
function has been evaluated (provided that the pointer is not equal
to <span class="code">NULL</span>). </p>
<h3><a name="id74461">8.4
The Server Loop</a></h3>
<p>The developer has to implement code for establishing connections
with other Erlang nodes, code for call-back functions and restore
functions. </p>
<p></p>
<p>In addition, the developer also has to implement code for a
server loop, that receives messages and calls the relevant
<span class="code">__exec</span> function. For that purpose the IC library function
<span class="code">oe_server_receive()</span> function can be used.</p>
<h3><a name="id74488">8.5
Generating, Compiling and Linking</a></h3>
<p>To generate the C server skeletons type the following in an
appropriate shell:</p>
<p><span class="code">erlc -I ICROOT/include "+{be, c_server}" File.idl</span>,</p>
<p>where <span class="code">ICROOT</span> is the root of the IC application. The
<span class="code">-I ICROOT/include</span> is only needed if <span class="code">File.idl</span>
refers to <span class="code">erlang.idl</span>.</p>
<p>When compiling a generated C skeleton file, the directories
<span class="code">ICROOT/include</span> and <span class="code">EICROOT/include</span>, have to be
specified as include directories, where <span class="code">EIROOT</span> is the
root directory of the Erl_interface application.</p>
<p>When linking object files the <span class="code">EIROOT/lib</span> and
<span class="code">ICROOT/priv/lib</span> directories have to be specified. </p>
<h3><a name="id74553">8.6
An Example</a></h3>
<p>In this example the IDL specification file "random.idl" is used
for generating C server skeletons (the file is contained in the IC
<span class="code">/examples/c-server</span> directory):</p>
<div class="example"><pre>
module rmod {
interface random {
double produce();
oneway void init(in long seed1, in long seed2, in long seed3);
};
}; </pre></div>
<p>Generate the C server skeletons:</p>
<div class="example"><pre>
erlc '+{be, c_server}' random.idl
Erlang IDL compiler version X.Y.Z </pre></div>
<p>Six files are generated. </p>
<p>Compile the C server skeletons:</p>
<p>Please read the <span class="code">ReadMe</span> file in the
<span class="code">examples/c-server</span> directory.</p>
<p>In the same directory you can find all the code for this
example. In particular you will find the <span class="code">server.c</span> file
that contains all the additional code that must be written to
obtain a complete server.</p>
<p>In the <span class="code">examples/c-server</span> directory you will also find
source code for an Erlang client, which can be used for testing
the C server.</p>
</div>
<div class="footer">
<hr>
<p>Copyright © 1998-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
