~rdoering/ubuntu/karmic/erlang/fix-535090

<?xml version="1.0" encoding="latin1" ?>

<!DOCTYPE chapter SYSTEM "chapter.dtd">

 

<chapter>

  <header>

    <copyright>

      <year>1998</year>

      <year>2008</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.

 

  The Initial Developer of the Original Code is Ericsson AB.

    </legalnotice>

 

    <title>The C Server Back-end</title>

    <prepared></prepared>

    <docno></docno>

    <date>2004-01-14</date>

    <rev>C</rev>

  </header>

 

  <section>

    <title>Introduction</title>

    <p>With the option <c>{be, c_server}</c> 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 <c>erl_interface</c> functions for defining the hidden

      node and for establishing connections to other Erlang nodes.</p>

  </section>

 

  <section>

    <title>Generated Stub Files</title>

    <p>The generated stub files are:</p>

    <list type="bulleted">

      <item>

        <p>For each IDL interface, a C source file, the name of which

          is <c><![CDATA[<Scoped Interface Name>__s.c]]></c>. Each operation of the

          IDL interface is mapped to a C function (with scoped name)

          in that file;</p>

      </item>

      <item>

        <p>C source files that contain functions for type conversion,

          memory allocation, and data encoding/decoding;</p>

      </item>

      <item>

        <p>C header files that contain function prototypes and type

          definitions.</p>

      </item>

    </list>

    <p>All C functions are exported (i.e. not declared static).</p>

  </section>

 

  <section>

    <title>C Skeleton Functions</title>

    <p>For each IDL operation a C skeleton function is generated, the

      prototype of which is <c><![CDATA[int <Scoped Function Name>__exec(<Interface Object> oe_obj, CORBA_Environment *oe_env)]]></c>, where <c><![CDATA[<Interface Object>]]></c>, and

      <c>CORBA_Environment</c> are of the same type as for the

      generated C client stubs code.</p>

    <p>Each <c><![CDATA[<Scoped Function Name>__exec()]]></c> function calls the

      call-back function</p>

    <p><c><![CDATA[<Scoped Function Name>_rs* <Scoped Function Name>__cb(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env)]]></c></p>

    <p>where the arguments are of the same type as those generated for

      C client stubs. </p>

    <p>The return value <c><![CDATA[<Scoped Function Name>_rs* ]]></c> is a pointer

      to a function with the same signature as the call-back function

      <c><![CDATA[<Scoped Function Name>_cb]]></c>, and is called after the call-back

      function has been evaluated (provided that the pointer is not equal

      to <c>NULL</c>). </p>

  </section>

 

  <section>

    <title>The Server Loop</title>

    <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

      <c>__exec</c> function. For that purpose the IC library function

      <c>oe_server_receive()</c> function can be used.</p>

  </section>

 

  <section>

    <title>Generating, Compiling and Linking</title>

    <p>To generate the C server skeletons type the following in an

      appropriate shell:</p>

    <p><c>erlc -I ICROOT/include "+{be, c_server}"  File.idl</c>,</p>

    <p>where <c>ICROOT</c> is the root of the IC application. The

      <c>-I ICROOT/include</c> is only needed if <c>File.idl</c>

      refers to <c>erlang.idl</c>.</p>

    <p>When compiling a generated C skeleton file, the directories

      <c>ICROOT/include</c> and <c>EICROOT/include</c>, have to be

      specified as include directories, where <c>EIROOT</c> is the

      root directory of the Erl_interface application.</p>

    <p>When linking object files the <c>EIROOT/lib</c> and

      <c>ICROOT/priv/lib</c> directories have to be specified. </p>

  </section>

 

  <section>

    <title>An Example</title>

    <p>In this example the IDL specification file "random.idl" is used

      for generating C server skeletons (the file is contained in the IC

      <c>/examples/c-server</c> directory):</p>

    <code type="none">

module rmod {

 

  interface random {

 

    double produce();

 

    oneway void init(in long seed1, in long seed2, in long seed3);

 

  };

 

};        </code>

    <p>Generate the C server skeletons:</p>

    <code type="none">

erlc '+{be, c_server}' random.idl

Erlang IDL compiler version X.Y.Z        </code>

    <p>Six files are generated. </p>

    <p>Compile the C server skeletons:</p>

    <p>Please read the <c>ReadMe</c> file in the

      <c>examples/c-server</c> directory.</p>

    <p>In the same directory you can find all the code for this

      example.  In particular you will find the <c>server.c</c> file

      that contains all the additional code that must be written to

      obtain a complete server.</p>

    <p>In the <c>examples/c-server</c> directory you will also find

      source code for an Erlang client, which can be used for testing

      the C server.</p>

  </section>

</chapter>