<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</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>IC Protocol</title>
    <prepared></prepared>
    <docno></docno>
    <date>2003-12-11</date>
    <rev>PA1</rev>
    <file>ch_ic_protocol.xml</file>
  </header>
  <p>The purpose of this chapter is to explain the bits and bytes of the
    IC protocol, which is a composition of the Erlang distribution protocol
    and the Erlang/OTP gen_server protocol. If you do not intend to replace
    the Erlang distribution protocol, or replace the gen_server protocol, 
    skip over this chapter. 
    </p>

  <section>
    <title>Introduction</title>
    <p>The IDL Compiler (IC) transforms Interface Definition Language
      (IDL) specifications files to interface code for Erlang, C, and
      Java. The Erlang language mapping is described in the Orber
      documentation, while the other mappings are described in the IC
      documentation (they are of course in accordance with the CORBA C
      and Java language mapping specifications, with some restrictions).
      </p>
    <p>The most important parts of an IDL specification are the operation
      declarations. An operation defines what information a client
      provides to a server, and what information (if any) the client
      gets back from the server. We consider IDL operations and language
      mappings in section 2.
      </p>
    <p>What we here call the IC protocol, is the description of messages
      exchanged between IC end-points (client and servers). It is valid
      for all IC back-ends, except the 'erl_plain' and 'erl_corba'
      back-ends. 
      The IC protocol is in turn embedded into the Erlang gen_server
      protocol, which is described below.
      Finally, the gen_server protocol is embedded in the Erlang
      distribution protocol. Pertinent parts of that protocol is
      described further below.
      </p>
  </section>

  <section>
    <title>Language mappings and IDL operations</title>

    <section>
      <title>IDL Operations</title>
      <p>An IDL operation is declared as follows:</p>
      <code type="none">
    [oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN,
    out OType1 O1, out OType2 O2, ..., out OTypeM OM)
    N, M = 0, 1, 2, ...        (2.1.1)
      </code>
      <p>`Op' is the operation name, RetType is the return type, and ITypei, 
        i = 1, 2, ..., N, and OTypej, j = 1, 2, ..., M, are the `in' types
        and `out' types, respectively. The values I1, I2, ..., IN are 
        provided by the caller, and the value of RetType, and the values
        O1, O2, ..., OM, are provided as results to the caller. 
        </p>
      <p>The types can be any basic types or derived types declared in the
        IDL specification of which the operation declaration is a part.
        </p>
      <p>If the RetType has the special name `void' there is no return
        value (but there might still be result values O1, 02, ..., OM).
        </p>
      <p>The `in' and `out' parameters can be declared in any order, but
        for clarity we have listed all `in' parameters before the `out'
        parameters in the declaration above.
        </p>
      <p>If the keyword `oneway' is present, the operation is a cast, i.e.
        there is no confirmation of the operation, and consequently there
        must be no result values: RetType must be equal to `void', and M =
        0 must hold.
        </p>
      <p>Otherwise the operation is a call, i.e. it is confirmed (or else
        an exception is raised). 
        </p>
      <p>Note carefully that an operation declared without `oneway' is
        always a call, even if RetType is `void' and M = 0.
        </p>
    </section>

    <section>
      <title>Language Mappings</title>
      <p>There are several CORBA Language Mapping specifications. These are
        about mapping interfaces to various programming languages. IC
        supports the CORBA C and Java mapping specifications, and the
        Erlang language mapping specified in the Orber documentation. 
        </p>
      <p>Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide:
        </p>
      <list type="bulleted">
        <item>
          <p>Functions with return type void will return the atom ok.</p>
        </item>
      </list>
      <p>Excerpt from "6.13 Invocations of Operations" in the Orber User's 
        Guide:
        </p>
      <list type="bulleted">
        <item>
          <p>A function call will invoke an operation. The first parameter
            of the function should be the object reference and then all in
            and inout parameters follow in the same order as specified in
            the IDL specification. The result will be a return value
            unless the function has inout or out parameters specified; in
            which case, a tuple of the return value, followed by the
            parameters will be returned.</p>
        </item>
      </list>
      <p>Hence the function that is mapped from an IDL operation to Erlang
        always have a return value (an Erlang function always has). That
        fact has influenced the IC protocol, in that there is always a
        return value (which is 'ok' if the return type was declared 'void'). </p>
    </section>
  </section>

  <section>
    <title>IC Protocol</title>
    <p>Given the operation declaration (2.1.1) the IC protocol maps to
      messages as follows, defined in terms of Erlang terms.
      </p>

    <section>
      <title>Call (Request/Reply, i.e. not oneway)</title>
      <code type="none">
    request:         Op                      atom()     N = 0    
                    {Op, I1, I2, ..., IN}    tuple()    N > 0
                                                        (3.1.1)

    reply:         Ret                                  M = 0
                   {Ret, O1, O2, ..., OM}               M > 0
                                                        (3.1.2)</code>
      <p><em>Notice:</em> Even if the RetType of the operation Op is 
        declared to be 'void', a return value 'ok' is returned in 
        the reply message. That
        return value is of no significance, and is therefore ignored (note
        however that a C server back-end returns the atom 'void' instead
        of 'ok'). 
        </p>
    </section>

    <section>
      <title>Cast (oneway)</title>
      <code type="none">

    notification:    Op                      atom()     N = 0
                     {Op, I1, I2, ..., IN}   tuple()    N > 0
                                                        (3.2.1)</code>
      <p>(There is of course no return message).
        </p>
    </section>
  </section>

  <section>
    <title>Gen_server Protocol</title>
    <p>Most of the IC generated code deals with encoding and decoding the
      gen_server protocol. 
      </p>

    <section>
      <title>Call</title>
      <code type="none">

    request:    {'$gen_call', {self(), Ref}, Request}   (4.1.1)

    reply:      {Ref, Reply}                            (4.1.2)</code>
      <p>where Request and Reply are the messages defined in the previous
        chapter.
        </p>
    </section>

    <section>
      <title>Cast</title>
      <code type="none">
    notification:    {'$gen_cast', Notification}        (4.2.1)      </code>
      <p>where Notification is the message defined in the previous chapter.
        </p>
    </section>
  </section>

  <section>
    <title>Erlang Distribution Protocol</title>
    <p>Messages (of interest here) between Erlang nodes are of the form: </p>
    <code type="none">
        Len(4), Type(1), CtrlBin(N), MsgBin(M)          (5.1)    </code>
    <p>Type is equal to 112 = PASS_THROUGH. 
      </p>
    <p>CtrlBin and MsgBin are Erlang terms in binary form (as if created
      by term_to_binary/1), whence for each of them the first byte is
      equal to 131 = VERSION_MAGIC.
      </p>
    <p>CtrlBin (of interest here) contains the SEND and REG_SEND control
      messages, which are binary forms of the Erlang terms</p>
    <code type="none">
        {2, Cookie, ToPid} ,                            (5.2)    </code>
    <p>and</p>
    <code type="none">
        {6, FromPid, Cookie, ToName} ,                  (5.3)    </code>
    <p>respectively.
      </p>
    <p>The CtrlBin(N) message is read and written by erl_interface code
      (C), j_interface code (Java), or the Erlang distribution
      implementation, which are invoked from IC generated code. 
      </p>
    <p>The MsgBin(N) is the "real" message, i.e. of the form described
      in the previous section.
      </p>
  </section>
</chapter>

