diff options
Diffstat (limited to 'lib/ic/doc/src')
32 files changed, 6906 insertions, 0 deletions
diff --git a/lib/ic/doc/src/CORBA_Environment_alloc.xml b/lib/ic/doc/src/CORBA_Environment_alloc.xml new file mode 100644 index 0000000000..909379d6dc --- /dev/null +++ b/lib/ic/doc/src/CORBA_Environment_alloc.xml @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <header> + <copyright> + <year>1998</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>CORBA_Environment_alloc</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>1998-12-01</date> + <rev>A</rev> + </header> + <lib>CORBA_Environment_alloc</lib> + <libsummary>Allocation function for the CORBA_Environement struct</libsummary> + <description> + <p>The <em>CORBA_Environment_alloc()</em> function is the + function used to allocate and initiate the <em>CORBA_Environment</em> + structure.</p> + </description> + <funcs> + <func> + <name><ret>CORBA_Environment *</ret><nametext>CORBA_Environment_alloc(inbufsz, outbufsz)</nametext></name> + <fsummary>Initialize communication</fsummary> + <type> + <v>int inbufsz;</v> + <v>int outbufsz;</v> + </type> + <desc> + <p>This function is used to create and initiate the <c>CORBA_Environment</c> + structure. In particular, it is used to dynamically allocate a CORBA_Environment + structure and set the default values for the structure's fields. </p> + <p><em>inbufsize</em> is the wished size of input buffer.</p> + <p><em>outbufsize</em> is the wished size of output buffer.</p> + <p><em>CORBA_Environment</em> is the CORBA 2.0 state structure used by the + generated stub.</p> + <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> + </desc> + </func> + </funcs> + + <section> + <title>The CORBA_Environment structure</title> + <p>Here is the complete definition of the CORBA_Environment structure, + defined in file <em>ic.h</em> : </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> + <note> + <p>Remember to set the field values <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>SEE ALSO</title> + <p>ic(3)</p> + </section> + +</cref> + + diff --git a/lib/ic/doc/src/Makefile b/lib/ic/doc/src/Makefile new file mode 100644 index 0000000000..fff930d745 --- /dev/null +++ b/lib/ic/doc/src/Makefile @@ -0,0 +1,320 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1998-2009. All Rights Reserved. +# +# 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. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(IC_VSN) +APPLICATION=ic +# ---------------------------------------------------- +# Include dependency +# ---------------------------------------------------- + +ifndef DOCSUPPORT +include make.dep +endif + +# ---------------------------------------------------- +# Java specific +# ---------------------------------------------------- +JAVADOC=javadoc +JAVA_INCL_ROOT = $(ERL_TOP)/lib/jinterface/priv/ +JAVA_SRC_ROOT = $(ERL_TOP)/lib/ic/java_src/ +JAVA_CLASS_SUBDIR = com/ericsson/otp/ic/ + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = ic.xml \ + ic_clib.xml \ + ic_c_protocol.xml + +XML_PART_FILES = part.xml \ + part_notes.xml + +XML_CHAPTER_FILES = \ + ch_introduction.xml \ + ch_basic_idl.xml \ + ch_ic_protocol.xml \ + ch_erl_plain.xml \ + ch_erl_genserv.xml \ + ch_c_mapping.xml \ + ch_c_client.xml \ + ch_c_server.xml \ + ch_c_corba_env.xml \ + ch_java.xml \ + notes.xml + +BOOK_FILES = book.xml + +GIF_FILES = \ + book.gif \ + notes.gif \ + ref_man.gif \ + user_guide.gif + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info +EXTRA_FILES = summary.html.src \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +ifdef DOCSUPPORT + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +else + +TEX_FILES_BOOK = \ + $(BOOK_FILES:%.xml=%.tex) +TEX_FILES_REF_MAN = $(XML_REF3_FILES:%.xml=%.tex) \ + $(XML_APPLICATION_FILES:%.xml=%.tex) +TEX_FILES_USERS_GUIDE = \ + $(XML_CHAPTER_FILES:%.xml=%.tex) + +TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf +TOP_PS_FILE = $(APPLICATION)-$(VSN).ps + +$(TOP_PDF_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@ + +$(TOP_PS_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@ + +endif + +JAVA_SOURCE_FILES = \ + Holder.java \ + BooleanHolder.java \ + ByteHolder.java \ + CharHolder.java \ + DoubleHolder.java \ + FloatHolder.java \ + IntHolder.java \ + LongHolder.java \ + ShortHolder.java \ + StringHolder.java \ + Environment.java \ + Any.java \ + AnyHelper.java \ + AnyHolder.java \ + TypeCode.java \ + TCKind.java \ + Pid.java \ + PidHolder.java \ + PidHelper.java \ + Ref.java \ + RefHolder.java \ + RefHelper.java \ + Port.java \ + PortHolder.java \ + PortHelper.java \ + Term.java \ + TermHolder.java \ + TermHelper.java + + +JD_INDEX_HTML_FILES = \ + allclasses-frame.html \ + allclasses-noframe.html \ + deprecated-list.html \ + index-all.html \ + overview-tree.html \ + stylesheet.css \ + help-doc.html \ + index.html \ + package-list \ + serialized-form.html \ + constant-values.html + +JD_GIF_FILES = \ + ../html/java/resources/inherit.gif + + +PACK_DIR = com/ericsson/otp/ic +JAVA_SOURCE_DIR = ../../java_src/$(PACK_DIR) + +JD_PACK_HTML_FILES = \ + package-frame.html \ + package-summary.html \ + package-tree.html + +JAVADOC_PACK_HTML_FILES = \ + $(JAVA_SOURCE_FILES:%.java=../html/java/$(PACK_DIR)/%.html) \ + $(JD_PACK_HTML_FILES:%=../html/java/$(PACK_DIR)/%) + +JAVADOC_INDEX_HTML_FILES = $(JD_INDEX_HTML_FILES:%=../html/java/%) + +JAVADOC_GENERATED_FILES = $(JAVADOC_PACK_HTML_FILES) $(JAVADOC_INDEX_HTML_FILES) + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +CLASSPATH = $(JAVA_SRC_ROOT):$(JAVA_INCL_ROOT) + +XML_FLAGS += +DVIPS_FLAGS += +JAVADOCFLAGS = \ + -classpath $(CLASSPATH) \ + -d ../doc/html/java \ + -windowtitle "Package com.ericsson.otp.ic version $(IC_VSN)" \ + -public \ + -footer "<CENTER><FONT SIZE=-1>Copyright © 1991-2007 Ericsson AB<BR> </FONT> </CENTER>" + + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +ifdef DOCSUPPORT + +docs: pdf html man $(JAVADOC_GENERATED_FILES) + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +else + +ifeq ($(DOCTYPE),pdf) +docs: pdf +else +ifeq ($(DOCTYPE),ps) +docs: ps +else +docs: html $(JAVADOC_GENERATED_FILES) gifs man +endif +endif + +pdf: $(TOP_PDF_FILE) + +ps: $(TOP_PS_FILE) + +html: $(HTML_FILES) + +clean clean_docs clean_tex: + rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK) + rm -f $(HTML_FILES) $(MAN3_FILES) + rm -f $(TOP_PDF_FILE) $(TOP_PS_FILE) + rm -f errs core *~ *xmls_output *xmls_errs $(LATEX_CLEAN) + rm -rf ../html/java/* + +endif + +$(JAVADOC_GENERATED_FILES): + @(cd ../../java_src; $(JAVADOC) $(JAVADOCFLAGS) com.ericsson.otp.ic) + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +$(INDEX_TARGET): $(INDEX_SRC) ../../vsn.mk + sed -e 's;%VSN%;$(VSN);' $< > $@ + +debug opt: + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +ifdef DOCSUPPORT + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + (/bin/cp -rf $(HTMLDIR) $(RELSYSDIR)/doc) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + +else + +ifeq ($(DOCTYPE),pdf) +release_docs_spec: pdf + $(INSTALL_DIR) $(RELEASE_PATH)/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf +else +ifeq ($(DOCTYPE),ps) +release_docs_spec: ps + $(INSTALL_DIR) $(RELEASE_PATH)/ps + $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps +else +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/resources + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson/otp + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson/otp/ic + $(INSTALL_DATA) $(JAVADOC_INDEX_HTML_FILES) \ + $(RELSYSDIR)/doc/html/java + $(INSTALL_DATA) $(JD_GIF_FILES) \ + $(RELSYSDIR)/doc/html/java/resources + $(INSTALL_DATA) $(JAVADOC_PACK_HTML_FILES) \ + $(RELSYSDIR)/doc/html/java/com/ericsson/otp/ic + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + +endif +endif + +endif + + +release_spec: + + diff --git a/lib/ic/doc/src/book.gif b/lib/ic/doc/src/book.gif Binary files differnew file mode 100644 index 0000000000..94b3868792 --- /dev/null +++ b/lib/ic/doc/src/book.gif diff --git a/lib/ic/doc/src/book.xml b/lib/ic/doc/src/book.xml new file mode 100644 index 0000000000..f83bb1c632 --- /dev/null +++ b/lib/ic/doc/src/book.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>1998</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</title> + <prepared></prepared> + <docno></docno> + <date>1998-09-29</date> + <rev>4.0.4</rev> + <file>book.sgml</file> + </header> + <insidecover> + </insidecover> + <pagetext>ic</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + diff --git a/lib/ic/doc/src/c-part.xml b/lib/ic/doc/src/c-part.xml new file mode 100644 index 0000000000..91c81c8ef3 --- /dev/null +++ b/lib/ic/doc/src/c-part.xml @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part> + <header> + <copyright> + <year>2002</year> + <year>2007</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>IDL to C language Mapping</title> + <prepared></prepared> + <docno></docno> + <date>2002-06-25</date> + <rev>A</rev> + </header> + <description> + <p>IDL to C</p> + </description> + <include file="ch_c_mapping"></include> + <include file="ch_c_client"></include> + <include file="ch_c_server"></include> + <include file="ch_c_corba_env"></include> +</part> + diff --git a/lib/ic/doc/src/ch_basic_idl.xml b/lib/ic/doc/src/ch_basic_idl.xml new file mode 100644 index 0000000000..d993fa3594 --- /dev/null +++ b/lib/ic/doc/src/ch_basic_idl.xml @@ -0,0 +1,163 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2002</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>OMG IDL</title> + <prepared></prepared> + <docno></docno> + <date>2002-07-15</date> + <rev></rev> + <file>ch_basic_idl.xml</file> + </header> + + <section> + <title>OMG IDL - Overview</title> + <p>The purpose of OMG IDL, <em>Interface Definition Language</em>, mapping + is to act as translator between platforms and languages. An IDL + specification is supposed to describe data types, object types etc.</p> + <p>Since the <c>C</c> and <c>Java</c> IC backends only supports a subset of the + IDL types supported by the other backends, the mapping is divided into + different parts. For more information about IDL to Erlang mapping, + i.e., <c>CORBA</c>, plain Erlang and generic Erlang Server, see the Orber + User's Guide. How to use the plain Erlang and generic Erlang Server is + found in this User's Guide.</p> + + <section> + <title>Reserved Compiler Names and Keywords</title> + <p>The use of some names is strongly discouraged due to + ambiguities. However, the use of some names is prohibited + when using the Erlang mapping , as they are strictly reserved for IC.</p> + <p>IC reserves all identifiers starting with <c>OE_</c> and <c>oe_</c> + for internal use.</p> + <p>Note also, that an identifier in IDL can contain alphabetic, + digits and underscore characters, but the first character + <em>must</em> be alphabetic. + </p> + <p>Using underscores in IDL names can lead to ambiguities + due to the name mapping described above. It is advisable to + avoid the use of underscores in identifiers.</p> + <p>The OMG defines a set of reserved words, shown below, for use as keywords. + These may <em>not</em> be used as, for example, identifiers.</p> + <table> + <row> + <cell align="left" valign="middle">abstract</cell> + <cell align="left" valign="middle">double</cell> + <cell align="left" valign="middle">local</cell> + <cell align="left" valign="middle">raises</cell> + <cell align="left" valign="middle">typedef</cell> + </row> + <row> + <cell align="left" valign="middle">any</cell> + <cell align="left" valign="middle">exception</cell> + <cell align="left" valign="middle">long</cell> + <cell align="left" valign="middle">readonly</cell> + <cell align="left" valign="middle">unsigned</cell> + </row> + <row> + <cell align="left" valign="middle">attribute</cell> + <cell align="left" valign="middle">enum</cell> + <cell align="left" valign="middle">module</cell> + <cell align="left" valign="middle">sequence</cell> + <cell align="left" valign="middle">union</cell> + </row> + <row> + <cell align="left" valign="middle">boolean</cell> + <cell align="left" valign="middle">factory</cell> + <cell align="left" valign="middle">native</cell> + <cell align="left" valign="middle">short</cell> + <cell align="left" valign="middle">ValueBase</cell> + </row> + <row> + <cell align="left" valign="middle">case</cell> + <cell align="left" valign="middle">FALSE</cell> + <cell align="left" valign="middle">Object</cell> + <cell align="left" valign="middle">string</cell> + <cell align="left" valign="middle">valuetype</cell> + </row> + <row> + <cell align="left" valign="middle">char</cell> + <cell align="left" valign="middle">fixed</cell> + <cell align="left" valign="middle">octet</cell> + <cell align="left" valign="middle">struct</cell> + <cell align="left" valign="middle">void</cell> + </row> + <row> + <cell align="left" valign="middle">const</cell> + <cell align="left" valign="middle">float</cell> + <cell align="left" valign="middle">oneway</cell> + <cell align="left" valign="middle">supports</cell> + <cell align="left" valign="middle">wchar</cell> + </row> + <row> + <cell align="left" valign="middle">context</cell> + <cell align="left" valign="middle">in</cell> + <cell align="left" valign="middle">out</cell> + <cell align="left" valign="middle">switch</cell> + <cell align="left" valign="middle">wstring</cell> + </row> + <row> + <cell align="left" valign="middle">custom</cell> + <cell align="left" valign="middle">inout</cell> + <cell align="left" valign="middle">private</cell> + <cell align="left" valign="middle">TRUE</cell> + <cell align="left" valign="middle"></cell> + </row> + <row> + <cell align="left" valign="middle">default</cell> + <cell align="left" valign="middle">interface</cell> + <cell align="left" valign="middle">public</cell> + <cell align="left" valign="middle">truncatable</cell> + <cell align="left" valign="middle"></cell> + </row> + <tcaption>OMG IDL keywords</tcaption> + </table> + <p>The keywords listed above must be written exactly as shown. Any usage + of identifiers that collide with a keyword is illegal. For example, + <em>long</em> is a valid keyword; <em>Long</em> and <em>LONG</em> are + illegal as keywords and identifiers. But, since the OMG must be able + to expand the IDL grammar, it is possible to use <em>Escaped Identifiers</em>. For example, it is not unlikely that <c>native</c> + have been used in IDL-specifications as identifiers. One option is to + change all occurrences to <c>myNative</c>. Usually, it is necessary + to change programming language code that depends upon that IDL as well. + Since Escaped Identifiers just disable type checking (i.e. if it is a reserved + word or not) and leaves everything else unchanged, it is only necessary to + update the IDL-specification. To escape an identifier, simply prefix it + with <c>_</c>. The following IDL-code is illegal:</p> + <code type="none"> +typedef string native; +interface i { + void foo(in native Arg); + }; +}; + </code> + <p>With Escaped Identifiers the code will look like:</p> + <code type="none"> +typedef string _native; +interface i { + void foo(in _native Arg); + }; +}; + </code> + </section> + </section> +</chapter> + diff --git a/lib/ic/doc/src/ch_c_client.xml b/lib/ic/doc/src/ch_c_client.xml new file mode 100644 index 0000000000..7d4f8ec91a --- /dev/null +++ b/lib/ic/doc/src/ch_c_client.xml @@ -0,0 +1,149 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>The C Client Back-end</title> + <prepared></prepared> + <docno></docno> + <date>2004-01-14</date> + <rev>C</rev> + <file>ch_c_client.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>With the option <c>{be, c_client}</c> the IDL Compiler generates + C client stubs 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 client stubs, form a hidden Erlang node. That + additional 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>.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 Interface Functions</title> + <p>For each IDL operation a C interface function is + generated, the prototype of which is:</p> + <p><c><![CDATA[<Return Value> <Scoped Function Name>(<Interface Object> oe_obj, <Parameters>, CORBA_Environment *oe_env);]]></c></p> + <p>where</p> + <list type="bulleted"> + <item> + <p><c><![CDATA[<Return Value>]]></c> is the value to be returned as defined + by the IDL specification;</p> + </item> + <item> + <p><c><![CDATA[<Interface Object> oe_obj]]></c> is the client interface + object;</p> + </item> + <item> + <p><c><![CDATA[<Parameters>]]></c> is a list of parameters of the + operation, defined in the same order as defined by the IDL + specification;</p> + </item> + <item> + <p><c>CORBA_Environment *oe_env</c> is a pointer to the current + client environment. It contains the current file descriptor, + the current input and output buffers, etc. For details see + <seealso marker="ch_c_corba_env#corbaenv">CORBA_Environment C Structure</seealso>.</p> + </item> + </list> + </section> + + <section> + <title>Generating, Compiling and Linking</title> + <p>To generate the C client stubs type the following in an + appropriate shell:</p> + <p><c><![CDATA[erlc -I ICROOT/include "+{be, c_client}" 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 stub 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 client stubs (the file is contained in the IC + <c>/examples/c-client</c> directory):</p> + <code type="none"><![CDATA[ +module rmod { + + interface random { + + double produce(); + + oneway void init(in long seed1, in long seed2, in long seed3); + + }; + +}; ]]></code> + <p>Generate the C client stubs:</p> + + <code type="none"><![CDATA[ +erlc '+{be, c_client}' random.idl +Erlang IDL compiler version X.Y.Z ]]></code> + + <p>Six files are generated. </p> + <p>Compile the C client stubs:</p> + <p>Please read the <c>ReadMe</c> file att the + <c>examples/c-client</c> directory</p> + <p>In the same + directory you can find all the code for this example.</p> + <p>In particular you will find the <c>client.c</c> file that contains + all the additional code that must be written to obtain a complete + client. </p> + <p>In the <c>examples/c-client</c> directory you will also find + source code for an Erlang server, which can be used for testing + the C client.</p> + </section> +</chapter> + + diff --git a/lib/ic/doc/src/ch_c_corba_env.xml b/lib/ic/doc/src/ch_c_corba_env.xml new file mode 100644 index 0000000000..557eeffdd4 --- /dev/null +++ b/lib/ic/doc/src/ch_c_corba_env.xml @@ -0,0 +1,385 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>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"> +\\011 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> + + diff --git a/lib/ic/doc/src/ch_c_mapping.xml b/lib/ic/doc/src/ch_c_mapping.xml new file mode 100644 index 0000000000..58b026ee78 --- /dev/null +++ b/lib/ic/doc/src/ch_c_mapping.xml @@ -0,0 +1,892 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>IDL to C mapping</title> + <prepared></prepared> + <docno></docno> + <date>2002-08-06</date> + <rev>PB1</rev> + <file>ch_c_mapping.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>The IC C mapping (used by the C client and C server back-ends) follows + the <em>OMG C Language Mapping Specification</em>. </p> + <p>The C mapping supports the following:</p> + <list type="bulleted"> + <item> + <p>All OMG IDL basic types except <c>long double</c> and <c>any</c>.</p> + </item> + <item> + <p>All OMG IDL constructed types.</p> + </item> + <item> + <p>OMG IDL constants.</p> + </item> + <item> + <p>Operations with passing of parameters and receiving of + results. <c>inout</c> parameters are not supported.</p> + </item> + </list> + <p>The following is not supported: + </p> + <list type="bulleted"> + <item> + <p>Access to attributes.</p> + </item> + <item> + <p>User defined exceptions.</p> + <p></p> + </item> + <item> + <p>User defined objects.</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>C Mapping Characteristics</title> + + <section> + <title>Reserved Names</title> + <p>The IDL compiler reserves all identifiers starting with + <c>OE_</c> and <c>oe_</c> for internal use.</p> + </section> + + <section> + <title>Scoped Names</title> + <p>The C programmer must always use the global name for a type, + constant or operation. The C global name corresponding to an + OMG IDL global name is derived by converting occurrences of + "::" to underscore, and eliminating the leading "::". So, for + example, an operation <c>op1</c> defined in interface + <c>I1</c> which is defined in module <c>M1</c> would be + written as <c>M1::I1::op1</c> in IDL and as <c>M1_I1_op1</c> + in C.</p> + <warning> + <p>If underscores are used in IDL names it can lead to + ambiguities due to the name mapping described above, + therefore it is advisable to avoid underscores in + identifiers.</p> + </warning> + </section> + + <section> + <title>Generated Files</title> + <p>Two files will be generated for each scope. One set of files + will be generated for each module and each interface scope. + An extra set is generated for those definitions at top + level scope. One of the files is a header file(<c>.h</c>), and the + other file is a C source code file (<c>.c</c>). In addition to these + files a number of C source files will be generated for type encodings, + they are named according to the following template: + <c><![CDATA[oe_code_<type>.c]]></c>.</p> + <p>For example:</p> + <code type="none"><![CDATA[ +// IDL, in the file "spec.idl" +module m1 { + + typedef sequence<long> lseq; + + interface i1 { + ... + }; + ... +}; + ]]></code> + <p>XXX This is C client specific. + Will produce the files <c>oe_spec.h</c> and + <c>oe_spec.c</c> for the top scope level. Then the files + <c>m1.h</c> and <c>m1.c</c> for the module <c>m1</c> and + files <c>m1_i1.h</c> and <c>m1_i1.c</c> for the interface + <c>i1</c>. The typedef will produce <c>oe_code_m1_lseq.c</c>.</p> + <p>The header file contains type definitions for all + <c>struct</c> types and sequences and constants in the IDL file. The + c file contains all operation stubs if the the scope is an interface.</p> + <p>In addition to the scope-related files a C source file will + be generated for encoding operations of all <c>struct</c> and + sequence types.</p> + </section> + </section> + + <section> + <title>Basic OMG IDL Types</title> + <p>The mapping of basic types is as follows.</p> + <table> + <row> + <cell align="left" valign="middle"><em>OMG IDL type</em></cell> + <cell align="left" valign="middle"><em>C type</em></cell> + <cell align="left" valign="middle"><em>Mapped to C type</em></cell> + </row> + <row> + <cell align="left" valign="middle">float</cell> + <cell align="left" valign="middle">CORBA_float</cell> + <cell align="left" valign="middle">float</cell> + </row> + <row> + <cell align="left" valign="middle">double</cell> + <cell align="left" valign="middle">CORBA_double</cell> + <cell align="left" valign="middle">double</cell> + </row> + <row> + <cell align="left" valign="middle">short</cell> + <cell align="left" valign="middle">CORBA_short</cell> + <cell align="left" valign="middle">short</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned short</cell> + <cell align="left" valign="middle">CORBA_unsigned_short</cell> + <cell align="left" valign="middle">unsigned short</cell> + </row> + <row> + <cell align="left" valign="middle">long</cell> + <cell align="left" valign="middle">CORBA_long</cell> + <cell align="left" valign="middle">long</cell> + </row> + <row> + <cell align="left" valign="middle">long long</cell> + <cell align="left" valign="middle">CORBA_long_long</cell> + <cell align="left" valign="middle">long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long</cell> + <cell align="left" valign="middle">unsigned long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long_long</cell> + <cell align="left" valign="middle">unsigned long</cell> + </row> + <row> + <cell align="left" valign="middle">char</cell> + <cell align="left" valign="middle">CORBA_char</cell> + <cell align="left" valign="middle">char</cell> + </row> + <row> + <cell align="left" valign="middle">wchar</cell> + <cell align="left" valign="middle">CORBA_wchar</cell> + <cell align="left" valign="middle">unsigned long</cell> + </row> + <row> + <cell align="left" valign="middle">boolean</cell> + <cell align="left" valign="middle">CORBA_boolean</cell> + <cell align="left" valign="middle">unsigned char</cell> + </row> + <row> + <cell align="left" valign="middle">octet</cell> + <cell align="left" valign="middle">CORBA_octet</cell> + <cell align="left" valign="middle">char</cell> + </row> + <row> + <cell align="left" valign="middle">any</cell> + <cell align="left" valign="middle">Not supported</cell> + <cell align="left" valign="middle"></cell> + </row> + <row> + <cell align="left" valign="middle">long double</cell> + <cell align="left" valign="middle">Not supported</cell> + <cell align="left" valign="middle"></cell> + </row> + <row> + <cell align="left" valign="middle">Object</cell> + <cell align="left" valign="middle">Not supported</cell> + <cell align="left" valign="middle"></cell> + </row> + <row> + <cell align="left" valign="middle">void</cell> + <cell align="left" valign="middle">void</cell> + <cell align="left" valign="middle">void</cell> + </row> + <tcaption>OMG IDL Basic Types</tcaption> + </table> + <p>XXX Note that several mappings are not according to OMG C Language + mapping.</p> + </section> + + <section> + <title>Constructed OMG IDL Types</title> + <p>Constructed types have mappings as shown in the following table.</p> + <table> + <row> + <cell align="left" valign="middle">OMG IDL type</cell> + <cell align="left" valign="middle">Mapped to C type</cell> + </row> + <row> + <cell align="left" valign="middle">string</cell> + <cell align="left" valign="middle">CORBA_char*</cell> + </row> + <row> + <cell align="left" valign="middle">wstring</cell> + <cell align="left" valign="middle">CORBA_wchar*</cell> + </row> + <row> + <cell align="left" valign="middle">struct</cell> + <cell align="left" valign="middle">struct</cell> + </row> + <row> + <cell align="left" valign="middle">union</cell> + <cell align="left" valign="middle">union</cell> + </row> + <row> + <cell align="left" valign="middle">enum</cell> + <cell align="left" valign="middle">enum</cell> + </row> + <row> + <cell align="left" valign="middle">sequence</cell> + <cell align="left" valign="middle">struct (see below)</cell> + </row> + <row> + <cell align="left" valign="middle">array</cell> + <cell align="left" valign="middle">array</cell> + </row> + <tcaption>OMG IDL Constructed Types</tcaption> + </table> + <p>An OMG IDL sequence (an array of variable length), </p> + <code type="none"><![CDATA[ +// IDL +typedef sequence <IDL_TYPE> NAME; + ]]></code> + <p>is mapped to a C struct as follows:</p> + <code type="none"> +/* C */ +typedef struct { + CORBA_unsigned_long _maximum; + CORBA_unsigned_long _length; + C_TYPE* _buffer; +} C_NAME; + </code> + <p>where <c>C_TYPE</c> is the mapping of <c>IDL_TYPE</c>, and where + <c>C_NAME</c> is the scoped name of <c>NAME</c>.</p> + </section> + + <section> + <title>OMG IDL Constants</title> + <p>An IDL constant is mapped to a C constant through a C + <c>#define</c> macro, where the name of the macro is scoped. + Example:</p> + <code type="none"> +// IDL +module M1 { + const long c1 = 99; +}; + </code> + <p>results in the following:</p> + <code type="none"> +/* C */ +#define M1_c1 99 + </code> + </section> + + <section> + <title>OMG IDL Operations</title> + <p>An OMG IDL operation is mapped to C function. Each C operation + function has two mandatory parameters: a first parameter of + <em>interface object</em> type, and a last parameter of + <em>environment</em> type.</p> + <p></p> + <p>In a C operation function the the <c>in</c> and <c>out</c> + parameters are located between the first and last parameters + described above, and they appear in the same order as in the IDL + operation declaration.</p> + <p>Notice that <c>inout</c> parameters are not supported. </p> + <p></p> + <p>The return value of an OMG IDL operation is mapped to a + corresponding return value of the C operation function.</p> + <p>Mandatory C operation function parameters:</p> + <list type="bulleted"> + <item><c>CORBA_Object oe_obj</c> - the first parameter of a C + operation function. This parameter is required by the <em>OMG C Language Mapping Specification</em>, but in the current + implementation there is no particular use for it.</item> + <item> + <p><c>CORBA_Environment* oe_env</c> - the last parameter of a C + operation function. The parameter is defined in the C header + file <c>ic.h</c> and has the following public fields:</p> + <list type="bulleted"> + <item> + <p><c>CORBA_Exception_type _major</c> - indicates if an + operation invocation was successful which will be one of + the following:</p> + <list type="bulleted"> + <item>CORBA_NO_EXCEPTION</item> + <item>CORBA_SYSTEM_EXCEPTION</item> + </list> + </item> + <item>int <em>_fd</em> - a file descriptor returned from + <em>erl_connect</em> function.</item> + <item>int <em>_inbufsz</em> - size of input buffer.</item> + <item>char* <em>_inbuf</em> - pointer to a buffer used for + input.</item> + <item>int <em>_outbufsz</em> - size of output buffer.</item> + <item>char* <em>_outbuf</em> - pointer to a buffer used for + output.</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>char <em>regname[256]</em> - a registered name for a + process.</item> + <item>erlang_pid* <em>_to_pid</em> - an Erlang process + identifier, is only used if the registered_name parameter + is the empty string.</item> + <item>erlang_pid* <em>_from_pid</em> - your own process id so + the answer can be returned</item> + </list> + <p>Beside the public fields, other private fields + are internally used but are not mentioned here. </p> + </item> + </list> + <p>Example:</p> + <code type="none"> +// IDL +interface i1 { + long op1(in long a); + long op2(in string s, out long count); +}; + </code> + <p>Is mapped to the following C functions</p> + <code type="none"> +/* C */ +CORBA_long i1_op1(i1 oe_obj, CORBA_long a, CORBA_Environment* oe_env) +{ + ... +} +CORBA_long i1_op2(i1 oe_obj, CORBA_char* s, CORBA_long *count, +CORBA_Environment* oe_env) +{ + ... +} + </code> + <marker id="op_impl"></marker> + + <section> + <title>Operation Implementation</title> + <p>There is no standard CORBA mapping for the C-server side, + as it is implementation-dependent but built in a similar way. + The current server side mapping is different from the client + side mapping in several ways:</p> + <list type="bulleted"> + <item>Argument mappings</item> + <item>Result values</item> + <item>Structure</item> + <item>Usage</item> + <item>Exception handling</item> + </list> + </section> + </section> + + <section> + <title>Exceptions</title> + <p>Although exception mapping is not implemented, the stubs will + generate CORBA system exceptions in case of operation failure. + Thus, the only exceptions propagated by the system are built in + system exceptions.</p> + </section> + + <section> + <title>Access to Attributes</title> + <p>Not Supported</p> + </section> + + <section> + <title>Summary of Argument/Result Passing for the C-client</title> + <p>The user-defined parameters can only be <c>in</c> or <c>out</c> + parameters, as + <c>inout</c> parameters are not supported.</p> + <p>This table summarize the types a client passes as arguments to + a stub, and receives as a result.</p> + <table> + <row> + <cell align="left" valign="middle">OMG IDL type</cell> + <cell align="left" valign="middle">In</cell> + <cell align="left" valign="middle">Out</cell> + <cell align="left" valign="middle">Return</cell> + </row> + <row> + <cell align="left" valign="middle">short</cell> + <cell align="left" valign="middle">CORBA_short</cell> + <cell align="left" valign="middle">CORBA_short*</cell> + <cell align="left" valign="middle">CORBA_short</cell> + </row> + <row> + <cell align="left" valign="middle">long</cell> + <cell align="left" valign="middle">CORBA_long</cell> + <cell align="left" valign="middle">CORBA_long*</cell> + <cell align="left" valign="middle">CORBA_long</cell> + </row> + <row> + <cell align="left" valign="middle">long long</cell> + <cell align="left" valign="middle">CORBA_long_long</cell> + <cell align="left" valign="middle">CORBA_long_long*</cell> + <cell align="left" valign="middle">CORBA_long_long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned short</cell> + <cell align="left" valign="middle">CORBA_unsigned_short</cell> + <cell align="left" valign="middle">CORBA_unsigned_short*</cell> + <cell align="left" valign="middle">CORBA_unsigned_short</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long*</cell> + <cell align="left" valign="middle">CORBA_unsigned_long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long_long</cell> + <cell align="left" valign="middle">CORBA_unsigned_long_long*</cell> + <cell align="left" valign="middle">CORBA_unsigned_long_long</cell> + </row> + <row> + <cell align="left" valign="middle">float</cell> + <cell align="left" valign="middle">CORBA_float</cell> + <cell align="left" valign="middle">CORBA_float*</cell> + <cell align="left" valign="middle">CORBA_float</cell> + </row> + <row> + <cell align="left" valign="middle">double</cell> + <cell align="left" valign="middle">CORBA_double</cell> + <cell align="left" valign="middle">CORBA_double*</cell> + <cell align="left" valign="middle">CORBA_double</cell> + </row> + <row> + <cell align="left" valign="middle">boolean</cell> + <cell align="left" valign="middle">CORBA_boolean</cell> + <cell align="left" valign="middle">CORBA_boolean*</cell> + <cell align="left" valign="middle">CORBA_boolean</cell> + </row> + <row> + <cell align="left" valign="middle">char</cell> + <cell align="left" valign="middle">CORBA_char</cell> + <cell align="left" valign="middle">CORBA_char*</cell> + <cell align="left" valign="middle">CORBA_char</cell> + </row> + <row> + <cell align="left" valign="middle">wchar</cell> + <cell align="left" valign="middle">CORBA_wchar</cell> + <cell align="left" valign="middle">CORBA_wchar*</cell> + <cell align="left" valign="middle">CORBA_wchar</cell> + </row> + <row> + <cell align="left" valign="middle">octet</cell> + <cell align="left" valign="middle">CORBA_octet</cell> + <cell align="left" valign="middle">CORBA_octet*</cell> + <cell align="left" valign="middle">CORBA_octet</cell> + </row> + <row> + <cell align="left" valign="middle">enum</cell> + <cell align="left" valign="middle">CORBA_enum</cell> + <cell align="left" valign="middle">CORBA_enum*</cell> + <cell align="left" valign="middle">CORBA_enum</cell> + </row> + <row> + <cell align="left" valign="middle">struct, fixed</cell> + <cell align="left" valign="middle">struct*</cell> + <cell align="left" valign="middle">struct*</cell> + <cell align="left" valign="middle">struct</cell> + </row> + <row> + <cell align="left" valign="middle">struct, variable</cell> + <cell align="left" valign="middle">struct*</cell> + <cell align="left" valign="middle">struct**</cell> + <cell align="left" valign="middle">struct*</cell> + </row> + <row> + <cell align="left" valign="middle">union, fixed</cell> + <cell align="left" valign="middle">union*</cell> + <cell align="left" valign="middle">union*</cell> + <cell align="left" valign="middle">union</cell> + </row> + <row> + <cell align="left" valign="middle">union, variable</cell> + <cell align="left" valign="middle">union*</cell> + <cell align="left" valign="middle">union**</cell> + <cell align="left" valign="middle">union*</cell> + </row> + <row> + <cell align="left" valign="middle">string</cell> + <cell align="left" valign="middle">CORBA_char*</cell> + <cell align="left" valign="middle">CORBA_char**</cell> + <cell align="left" valign="middle">CORBA_char*</cell> + </row> + <row> + <cell align="left" valign="middle">wstring</cell> + <cell align="left" valign="middle">CORBA_wchar*</cell> + <cell align="left" valign="middle">CORBA_wchar**</cell> + <cell align="left" valign="middle">CORBA_wchar*</cell> + </row> + <row> + <cell align="left" valign="middle">sequence</cell> + <cell align="left" valign="middle">sequence*</cell> + <cell align="left" valign="middle">sequence**</cell> + <cell align="left" valign="middle">sequence*</cell> + </row> + <row> + <cell align="left" valign="middle">array, fixed</cell> + <cell align="left" valign="middle">array</cell> + <cell align="left" valign="middle">array</cell> + <cell align="left" valign="middle">array_slice*</cell> + </row> + <row> + <cell align="left" valign="middle">array, variable</cell> + <cell align="left" valign="middle">array</cell> + <cell align="left" valign="middle">array_slice**</cell> + <cell align="left" valign="middle">array_slice*</cell> + </row> + <tcaption>Basic Argument and Result passing</tcaption> + </table> + <p>A client is responsible for providing storage of all arguments passed + as <em>in</em> arguments.</p> + <table> + <row> + <cell align="left" valign="middle">OMG IDL type</cell> + <cell align="left" valign="middle">Out</cell> + <cell align="left" valign="middle">Return</cell> + </row> + <row> + <cell align="left" valign="middle">short</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">long</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">long long</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned short</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long long</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">float</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">double</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">boolean</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">char</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">wchar</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">octet</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">enum</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">struct, fixed</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">1</cell> + </row> + <row> + <cell align="left" valign="middle">struct, variable</cell> + <cell align="left" valign="middle">2</cell> + <cell align="left" valign="middle">2</cell> + </row> + <row> + <cell align="left" valign="middle">string</cell> + <cell align="left" valign="middle">2</cell> + <cell align="left" valign="middle">2</cell> + </row> + <row> + <cell align="left" valign="middle">wstring</cell> + <cell align="left" valign="middle">2</cell> + <cell align="left" valign="middle">2</cell> + </row> + <row> + <cell align="left" valign="middle">sequence</cell> + <cell align="left" valign="middle">2</cell> + <cell align="left" valign="middle">2</cell> + </row> + <row> + <cell align="left" valign="middle">array, fixed</cell> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">3</cell> + </row> + <row> + <cell align="left" valign="middle">array, variable</cell> + <cell align="left" valign="middle">3</cell> + <cell align="left" valign="middle">3</cell> + </row> + <tcaption>Client argument storage responsibility</tcaption> + </table> + <table> + <row> + <cell align="left" valign="middle">Case</cell> + <cell align="left" valign="middle">Description</cell> + </row> + <row> + <cell align="left" valign="middle">1</cell> + <cell align="left" valign="middle">Caller allocates all necessary storage, except that which may be encapsulated and managed within the parameter itself.</cell> + </row> + <row> + <cell align="left" valign="middle">2</cell> + <cell align="left" valign="middle">The caller allocates a pointer and passes it by reference to the callee. The callee sets the pointer to point to a valid instance of the parameter's type. The caller is responsible for releasing the returned storage. Following completion of a request, the caller is not allowed to modify any values in the returned storage. To do so the caller must first copy the returned instance into a new instance, then modify the new instance. </cell> + </row> + <row> + <cell align="left" valign="middle">3</cell> + <cell align="left" valign="middle">The caller allocates a pointer to an array slice which has all the same dimensions of the original array except the first, and passes it by reference to the callee. The callee sets the pointer to point to a valid instance of the array. The caller is responsible for releasing the returned storage. Following completion of a request, the caller is not allowed to modify any values in the returned storage. To do so the caller must first copy the returned instance into a new instance, then modify the new instance. </cell> + </row> + <tcaption>Argument passing cases</tcaption> + </table> + <p>The returned storage in case 2 and 3 is allocated as one block of memory + so it is possible to deallocate it with one call of CORBA_free.</p> + </section> + + <section> + <title>Supported Memory Allocation Functions</title> + <list type="bulleted"> + <item> + <p><em>CORBA_Environment</em> can be allocated from the user by calling + <em>CORBA_Environment_alloc()</em>.</p> + <p>The interface for this function is </p> + <p><c>CORBA_Environment *CORBA_Environment_alloc(int inbufsz, int outbufsz);</c></p> + <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> + </item> + <item> + <p>Strings can be allocated from the user by calling <em>CORBA_string_alloc()</em>.</p> + <p>The interface for this function is </p> + <p><c>CORBA_char *CORBA_string_alloc(CORBA_unsigned_long len);</c></p> + <p>where :</p> + <list type="bulleted"> + <item> + <p><em>len</em> is the length of the string to be allocated.</p> + </item> + </list> + </item> + </list> + <p>Thus far, no other type allocation function is supported.</p> + </section> + + <section> + <title>Special Memory Deallocation Functions</title> + <list type="bulleted"> + <item> + <p><c>void CORBA_free(void *storage)</c></p> + <p>This function will free storage allocated by the stub.</p> + </item> + <item> + <p><c>void CORBA_exception_free(CORBA_environment *ev)</c></p> + <p>This function will free storage allocated under exception propagation. </p> + </item> + </list> + </section> + + <section> + <title>Exception Access Functions</title> + <list type="bulleted"> + <item> + <p><c>CORBA_char *CORBA_exception_id(CORBA_Environment *ev)</c></p> + <p>This function will return raised exception identity.</p> + </item> + <item> + <p><c>void *CORBA_exception_value(CORBA_Environment *ev)</c></p> + <p>This function will return the value of a raised exception. </p> + </item> + </list> + </section> + + <section> + <title>Special Types</title> + <list type="bulleted"> + <item> + <p>The erlang binary type has some special features.</p> + <p></p> + <p>While the <c>erlang::binary</c> idl type has the same C-definition as + a generated sequence of octets :</p> + <code type="none"><![CDATA[ +\011 module erlang +\011 { + +\011 .... + +\011 // an erlang binary +\011 typedef sequence<octet> binary; +\011 +\011 }; + ]]></code> + <p>it provides a way on sending trasparent data between C and Erlang.</p> + <p>The C-definition (ic.h) for an erlang binary is :</p> + <code type="none"> +\011 typedef struct { +\011 CORBA_unsigned_long _maximum; +\011 CORBA_unsigned_long _length; +\011 CORBA_octet* _buffer; +\011 } erlang_binary; /* ERLANG BINARY */ + </code> + <p>The differences (between <c>erlang::binary</c> and <c><![CDATA[sequence< octet >]]></c>) are :</p> + <list type="bulleted"> + <item> + <p>on the erlang side the user is sending/receiving typical + built in erlang binaries, using <c>term_to_binary() / binary_to_term()</c> + to create / extract binary structures.</p> + </item> + <item> + <p>no encoding/decoding functions are generated</p> + </item> + <item> + <p>the underlying protocol is more efficient than usual sequences of + octets</p> + </item> + </list> + <p>The erlang binary IDL type is defined in <c>erlang.idl</c>, while it's + C definition is located in the <c>ic.h</c> header file, both in the + <c><![CDATA[IC-< vsn >/include]]></c> directory. + The user will have to include the file <c>erlang.idl</c> in order to use the + <c>erlang::binary</c> type.</p> + </item> + </list> + </section> + + <section> + <title>A Mapping Example</title> + <p> <marker id="stack_idl"></marker> + + This is a small example of a simple stack. There are two + operations on the stack, push and pop. The example shows all + generated files as well as conceptual usage of the stack.</p> + <code type="none"> +// The source IDL file: stack.idl + +struct s { + long l; + string s; +}; + +interface stack { + void push(in s val); + s pop(); +}; + </code> + <p>When this file is compiled it produces four files, two for the + top scope and two for the stack interface scope. The important parts + of the generated C code for the stack API is shown below. <marker id="stack_serv"></marker> +</p> + <p>stack.c</p> + <code type="none"> + +void push(stack oe_obj, s val, CORBA_Environment* oe_env) { + ... +} + + +s* pop(stack oe_obj, CORBA_Environment* oe_env) { + ... +} + </code> + <p>oe_stack.h</p> + <code type="none"> +#ifndef OE_STACK_H +#define OE_STACK_H + + +/*------------------------------------------------------------ + * Struct definition: s + */ +typedef struct { + long l; + char *s; +} s; + + + +#endif + </code> + <p>stack.h just contains an include statement of <c>oe_stack.h</c>.</p> + <p>oe_code_s.c</p> + <code type="none"> + +int oe_sizecalc_s(CORBA_Environment + *oe_env, int* oe_size_count_index, int* oe_size) { + ... +} + +int oe_encode_s(CORBA_Environment *oe_env, s* oe_rec) { + ... +} + +int oe_decode_s(CORBA_Environment *oe_env, char *oe_first, + int* oe_outindex, s *oe_out) { + ... +} + </code> + <p>The only files that are really important are the <c>.h</c> + files and the stack.c file.</p> + </section> +</chapter> + diff --git a/lib/ic/doc/src/ch_c_server.xml b/lib/ic/doc/src/ch_c_server.xml new file mode 100644 index 0000000000..c66ae85fa3 --- /dev/null +++ b/lib/ic/doc/src/ch_c_server.xml @@ -0,0 +1,148 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>The C Server Back-end</title> + <prepared></prepared> + <docno></docno> + <date>2004-01-14</date> + <rev>C</rev> + <file>ch_c_server.xml</file> + </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> + + diff --git a/lib/ic/doc/src/ch_erl_genserv.xml b/lib/ic/doc/src/ch_erl_genserv.xml new file mode 100644 index 0000000000..972eff7c17 --- /dev/null +++ b/lib/ic/doc/src/ch_erl_genserv.xml @@ -0,0 +1,205 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>Using the Erlang Generic Server Back-end</title> + <prepared></prepared> + <docno></docno> + <date>98-08-06</date> + <rev>B</rev> + <file>ch_erl_genserver.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>The mapping of OMG IDL to the Erlang programming language when Erlang + generic server is the back-end of choice is similar to the one used in + the chapter 'OMG IDL Mapping'. + The only difference is in the generated code, a client stub and + server skeleton to an Erlang <c>gen_server</c>. Orber's User's Guide + contain a more detailed description of IDL to Erlang mapping.</p> + </section> + + <section> + <title>Compiling the Code</title> + <p>The <c>ic:gen/2</c> function can be called from the command + line as follows:</p> + <p></p> + <code type="none"> +shell> erlc "+{be, erl_genserv}" MyFile.idl + </code> + </section> + + <section> + <title>Writing the Implementation File</title> + <p>For each IDL interface <c><![CDATA[<interface name>]]></c> defined in the IDL file :</p> + <list type="bulleted"> + <item>Create the corresponding Erlang file that will hold the + Erlang implementation of the IDL definitions. </item> + <item>Call the implementation file after the scope of the IDL interface, + followed by the suffix <c>_impl</c>.</item> + <item>Export the implementation functions.</item> + </list> + <p>For each function defined in the IDL interface :</p> + <list type="bulleted"> + <item>Implement an Erlang function that uses as arguments in the same + order, as the input arguments described in the IDL file, and returns + the value described in the interface.</item> + <item>When using the function, follow the mapping described in chapter 2.</item> + </list> + </section> + + <section> + <title>An Example</title> + <p>In this example, a file <c>random.idl</c> generates code for the Erlang + gen_server back-end:</p> + <code type="none"> +// Filename random.idl +module rmod { + + interface random { + // Generate a new random number + double produce(); + // Initialize random generator + oneway void init(in long seed1, in long seed2, in long seed3); + + }; +}; + </code> + <p>When the file "random.idl" is compiled (e.g., <c>shell> erlc "+{be, erl_genserv}" random.idl</c>) + five files are produced; two for the top scope, two for the interface scope, + and one for the module scope. The header files for top scope and interface + are empty and not shown here. In this case, the stub/skeleton file + <c>rmod_random.erl</c> is the most important. This module exports two kinds of + operations:</p> + <list type="bulleted"> + <item><em>Administrative</em> - used when, for example, creating and + terminating the server.</item> + <item><em>IDL dependent</em> - operations defined in the IDL + specification. In this case, <c>produce</c> and <c>init</c>.</item> + </list> + + <section> + <title>Administrative Operations</title> + <p>To create a new server instance, one of the following functions should + be used:</p> + <list type="bulleted"> + <item><em>oe_create/0/1/2</em> - create a new instance of the object. + Accepts <c>Env</c> and <c>RegName</c>, in that order, as parameters. + The former is passed uninterpreted to the initialization operation + of the call-back module, while the latter must be as the + <c>gen_server</c> parameter <c>ServerName</c>. If <c>Env</c> is + left out, an empty list will be passed.</item> + <item><em>oe_create_link/0/1/2</em> - similar to <c>oe_create/0/1/2</c>, + but create a linked server.</item> + <item><em>typeID/0</em> - returns the scooped id compliant with the + OMG standard. In this case the string + <c>"IDL:rmod/random:1.0"</c>.</item> + <item><em>stop/1</em> - asynchronously terminate the server. The required + argument is the return value from any of the start functions.</item> + </list> + </section> + + <section> + <title>IDL Dependent Operations</title> + <p>Operations can either be synchronous or asynchronous + (i.e., <c>oneway</c>). These are, respectively, mapped to + <c>gen_server:call/2/3</c> and <c>gen_server:cast/2</c>. + Consult the <c>gen_server</c> documentation for valid return values.</p> + <p>The IDL dependent operations in this example are listed below. + The first argument must be the whatever the create operation returned.</p> + <list type="bulleted"> + <item><em>init(ServerReference, Seed1, Seed2, Seed3)</em> - initialize + the random number generator.</item> + <item><em>produce(ServerReference)</em> - generate a new random number.</item> + </list> + </section> + <p>If the compile option <c>timeout</c> is used a timeout must be added + (e.g., <c>produce(ServerReference, 5000)</c>). For more information, see + the <c>gen_server</c> documentation.</p> + + <section> + <title>Implementation Module</title> + <p>The implementation module shall, unless the compile option + <c>impl</c> is used, be named <c>rmod_random_impl.erl</c>. + and could look like this:</p> + <code type="none"> +-module('rmod_random_impl'). +%% Mandatory gen_server operations +-export([init/1, terminate/2, code_change/3]). +%% Add if 'handle_info' compile option used +-export([handle_info/2]). +%% API defined in IDL specification +-export([produce/1,init/4]). + +%% Mandatory operations +init(Env) -> + {ok, []}. + +terminate(From, Reason) -> + ok. + +code_change(OldVsn, State, Extra) -> + {ok, State}. + +%% Optional +handle_info(Info, State) -> + {noreply, NewState}. + +%% IDL specification +produce(State) -> + case catch random:uniform() of +\\011{'EXIT',_} -> +\\011 {stop, normal, "random:uniform/0 - EXIT", State}; +\\011RUnif -> + {reply, RUnif, State} + end. + + +init(State, S1, S2, S3) -> + case catch random:seed(S1, S2, S3) of +\\011{'EXIT',_} -> +\\011 {stop, normal, State}; +\\011_ -> + {noreply, State} + end. + </code> + <p>Compile the code and run the example:</p> + <code type="none"><![CDATA[ +1> make:all(). +Recompile: rmod_random +Recompile: oe_random +Recompile: rmod_random_impl +up_to_date +2> {ok,R} = rmod_random:oe_create(). +{ok,<0.30.0>} +3> rmod_random:init(R, 1, 2, 3). +ok +4> rmod_random:produce(R). +1.97963e-4 +5> + ]]></code> + </section> + </section> +</chapter> + + diff --git a/lib/ic/doc/src/ch_erl_plain.xml b/lib/ic/doc/src/ch_erl_plain.xml new file mode 100644 index 0000000000..36de46f624 --- /dev/null +++ b/lib/ic/doc/src/ch_erl_plain.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>Using the Plain Erlang Back-end</title> + <prepared></prepared> + <docno></docno> + <date>98-05-06</date> + <rev>B</rev> + <file>ch_erl_plain.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>The mapping of OMG IDL to the Erlang programming language when + Plain Erlang + is the back-end of choice is similar to the one used in pure Erlang IDL + mapping. The only difference is on the generated code and the extended + use of pragmas for code generation: IDL functions are translated + to Erlang + module function calls.</p> + </section> + + <section> + <title>Compiling the Code</title> + <p>In the Erlang shell type :</p> + <p>ic:gen(<c><![CDATA[<filename>, [{be, erl_plain}])]]></c>.</p> + </section> + + <section> + <title>Writing the Implementation File</title> + <p>For each IDL interface <c><![CDATA[<interface name>]]></c> defined in the IDL file:</p> + <list type="bulleted"> + <item>Create the corresponding Erlang file that will hold the + Erlang implementation of the IDL definitions. </item> + <item>Call the implementation file after the scope of the IDL interface, + followed by the suffix <c>_impl</c>.</item> + <item>Export the implementation functions.</item> + </list> + <p>For each function defined in the IDL interface :</p> + <list type="bulleted"> + <item>Implement an Erlang function that uses as arguments in the same + order, as the input arguments described in the IDL file, and returns + the value described in the interface.</item> + <item>When using the function, follow the mapping described in chapter 2.</item> + </list> + </section> + + <section> + <title>An Example</title> + <p> <marker id="plain_idl"></marker> + + In this example, a file "random.idl" is generates code for the plain Erlang + back-end :</p> + <list type="bulleted"> + <item> + <p>Main file : "plain.idl"</p> + <code type="none"> +\011 +module rmod { + + interface random { + + double produce(); + + oneway void init(in long seed1, in long seed2, in long seed3); + + }; + +}; + </code> + </item> + </list> + <p>Compile the file :</p> + <code type="none"> + Erlang (BEAM) emulator version 4.9 + + Eshell V4.9 (abort with ^G) + 1> ic:gen(random,[{be, erl_plain}]). + Erlang IDL compiler version 2.5.1 + ok + 2> + </code> + <p></p> + <p>When the file "random.idl" is compiled it produces five files: two for + the top scope, two for the interface scope, and one for the module + scope. The header files for top scope and interface + are empty and not shown here. In this case only the file for the interface + <c>rmod_random.erl</c> is important :. + <marker id="generated files"></marker> +</p> + <list type="bulleted"> + <item> + <p>Erlang file for interface : "rmod_random.erl"</p> + <code type="none"> + +-module(rmod_random). + + + +%% Interface functions +-export([produce/0, init/3]). + +%%------------------------------------------------------------ +%% Operation: produce +%% +%% Returns: RetVal +%% +produce() -> + rmod_random_impl:produce(). + +%%------------------------------------------------------------ +%% Operation: init +%% +%% Returns: RetVal +%% +init(Seed1, Seed2, Seed3) -> + rmod_random_impl:init(Seed1, Seed2, Seed3). + </code> + </item> + </list> + <p>The implementation file should be called <c>rmod_random_impl.erl</c> + and could look like this:</p> + <code type="none"> + -module('rmod_random_impl'). + + -export([produce/0,init/3]). + + + produce() -> + random:uniform(). + + + init(S1,S2,S3) -> + random:seed(S1,S2,S3). + </code> + <p>Compiling the code : </p> + <code type="none"> +2> make:all(). +Recompile: rmod_random +Recompile: oe_random +Recompile: rmod_random_impl +up_to_date + </code> + <p></p> + <p>Running the example : </p> + <code type="none"> +3> rmod_random:init(1,2,3). +ok +4> rmod_random:produce(). +1.97963e-4 +5> + </code> + </section> +</chapter> + diff --git a/lib/ic/doc/src/ch_ic_protocol.xml b/lib/ic/doc/src/ch_ic_protocol.xml new file mode 100644 index 0000000000..678fdc766c --- /dev/null +++ b/lib/ic/doc/src/ch_ic_protocol.xml @@ -0,0 +1,233 @@ +<?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"> +\011[oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN, +\011out OType1 O1, out OType2 O2, ..., out OTypeM OM) +\011N, M = 0, 1, 2, ...\011\011(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:\011\011 Op\011\011\011atom()\011\011N = 0\011 +\011\011\011 {Op, I1, I2, ..., IN}\011tuple()\011\011N > 0 +\011\011\011\011\011\011\011\011(3.1.1) + + reply:\011\011 Ret\011\011\011\011\011M = 0 +\011\011\011 {Ret, O1, O2, ..., OM}\011\011\011M > 0 +\011\011\011\011\011\011\011\011(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:\011Op\011\011\011atom()\011\011N = 0 +\011\011\011{Op, I1, I2, ..., IN}\011tuple()\011\011N > 0 +\011\011\011\011\011\011\011\011(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:\011{'$gen_call', {self(), Ref}, Request}\011\011(4.1.1) + + reply:\011{Ref, Reply}\011\011\011\011\011(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}\011\011(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)\011\011\011(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"> +\011{2, Cookie, ToPid} ,\011\011\011\011\011(5.2) </code> + <p>and</p> + <code type="none"> +\011{6, FromPid, Cookie, ToName} ,\011\011\011\011(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> + diff --git a/lib/ic/doc/src/ch_introduction.xml b/lib/ic/doc/src/ch_introduction.xml new file mode 100644 index 0000000000..898d2a732a --- /dev/null +++ b/lib/ic/doc/src/ch_introduction.xml @@ -0,0 +1,148 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>Using the IC Compiler</title> + <prepared></prepared> + <docno></docno> + <date>2002-08-02</date> + <rev>PB1</rev> + <file>ch_introduction.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>The IC application is an IDL compiler implemented in Erlang. + The IDL compiler generates client stubs and server skeletons. + Several back-ends are supported, and they fall into three main + groups.</p> + <p>The first group consists of a CORBA back-end:</p> + <taglist> + <tag>IDL to Erlang CORBA</tag> + <item> + <p>This back-end is for CORBA communication and implementation, + and the generated code uses the CORBA specific protocol for + communication between clients and servers. See the + <em>Orber</em> application User's Guide and manuals for + further details.</p> + </item> + </taglist> + <p>The second group consists of a simple Erlang back-end:</p> + <taglist> + <tag>IDL to plain Erlang</tag> + <item> + <p>This back-end provides a very simple Erlang client + interface. It can only be used within an Erlang node, + and the communication between client and "server" is + therefore in terms of ordinary function calls. </p> + <p>This back-end can be considered a short-circuit version of + the IDL to Erlang gen_server back-end (see further below).</p> + </item> + </taglist> + <p>The third group consists of backends for Erlang, C, and + Java. The communication between clients and servers is by the + Erlang distribution protocol, facilitated by + <em>erl_interface</em> and <em>jinterface</em> for C and Java, + respectively.</p> + <p>All back-ends of the third group generate code compatible with + the Erlang gen_server behavior protocol. Thus generated client + code corresponds to <c>call()</c> or <c>cast()</c> of an Erlang + <c>gen_server</c>. Similarly, generated server code corresponds + to <c>handle_call()</c> or <c>handle_cast()</c> of an Erlang + <c>gen_server</c>.</p> + <p>The back-ends of the third group are: + </p> + <taglist> + <tag>IDL to Erlang gen_server</tag> + <item> + <p>Client stubs and server skeletons are generated. Data types + are mapped according to the IDL to Erlang mapping described + in the <em>Orber User's Guide</em>.</p> + <p></p> + </item> + <tag>IDL to C client</tag> + <item> + <p>Client stubs are generated. The mapping of data types is + described further on in the C client part of this guide.</p> + </item> + <tag>IDL to C server</tag> + <item> + <p>Server skeletons are generated. The mapping of data types is + described further on in the C server part of this guide.</p> + </item> + <tag>IDL to Java</tag> + <item> + <p>Client stubs and server skeletons are generated. The mapping + of data types is described further on in the Java part of + this guide.</p> + </item> + </taglist> + </section> + + <section> + <title>Compilation of IDL Files</title> + <p>The IC compiler is invoked by executing the generic <c>erlc</c> + compiler from a shell:</p> + <code type="none"> +%> erlc +'{be,BackEnd}' File.idl + </code> + <p>where <c>BackEnd</c> is according to the table below, and + <c>File.idl</c> is the IDL file to be compiled.</p> + <table> + <row> + <cell align="left" valign="middle"><em>Back-end</em></cell> + <cell align="left" valign="middle"><c>BackEnd</c>option</cell> + </row> + <row> + <cell align="left" valign="middle">IDL to CORBA</cell> + <cell align="left" valign="middle"><c>erl_corba</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to CORBA template</cell> + <cell align="left" valign="middle"><c>erl_template</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to plain Erlang</cell> + <cell align="left" valign="middle"><c>erl_plain</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to Erlang gen_server</cell> + <cell align="left" valign="middle"><c>erl_genserv</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to C client</cell> + <cell align="left" valign="middle"><c>c_client</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to C server</cell> + <cell align="left" valign="middle"><c>c_server</c></cell> + </row> + <row> + <cell align="left" valign="middle">IDL to Java</cell> + <cell align="left" valign="middle"><c>java</c></cell> + </row> + <tcaption>Compiler back-ends and options</tcaption> + </table> + <p>For more details on IC compiler options consult the ic(3) manual page.</p> + </section> +</chapter> + diff --git a/lib/ic/doc/src/ch_java.xml b/lib/ic/doc/src/ch_java.xml new file mode 100644 index 0000000000..831850f211 --- /dev/null +++ b/lib/ic/doc/src/ch_java.xml @@ -0,0 +1,737 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1999</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>IDL to Java language Mapping</title> + <prepared></prepared> + <docno></docno> + <date>98-09-24</date> + <rev>A</rev> + <file>ch_java.xml</file> + </header> + + <section> + <title>Introduction</title> + <p>This chapter describes the mapping of OMG IDL constructs to the Java + programming language for the generation of native Java - Erlang + communication. </p> + <p>This language mapping defines the following:</p> + <list type="bulleted"> + <item> + <p>All OMG IDL basic types</p> + </item> + <item> + <p>All OMG IDL constructed types</p> + </item> + <item> + <p>References to constants defined in OMG IDL</p> + </item> + <item> + <p>Invocations of operations, including passing of + parameters and receiving of result</p> + </item> + <item> + <p>Access to attributes</p> + </item> + </list> + </section> + + <section> + <title>Specialties in the Mapping</title> + + <section> + <title>Names Reserved by the Compiler</title> + <p>The IDL compiler reserves all identifiers starting with + <c>OE_</c> and <c>oe_</c> for internal use.</p> + </section> + </section> + + <section> + <title>Basic OMG IDL Types</title> + <p>The mapping of basic types are according to the standard. All basic types have + a special Holder class.</p> + <table> + <row> + <cell align="left" valign="middle">OMG IDL type</cell> + <cell align="left" valign="middle">Java type</cell> + </row> + <row> + <cell align="left" valign="middle">float</cell> + <cell align="left" valign="middle">float</cell> + </row> + <row> + <cell align="left" valign="middle">double</cell> + <cell align="left" valign="middle">double</cell> + </row> + <row> + <cell align="left" valign="middle">short</cell> + <cell align="left" valign="middle">short</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned short</cell> + <cell align="left" valign="middle">short</cell> + </row> + <row> + <cell align="left" valign="middle">long</cell> + <cell align="left" valign="middle">int</cell> + </row> + <row> + <cell align="left" valign="middle">long long</cell> + <cell align="left" valign="middle">long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long</cell> + <cell align="left" valign="middle">long</cell> + </row> + <row> + <cell align="left" valign="middle">unsigned long long</cell> + <cell align="left" valign="middle">long</cell> + </row> + <row> + <cell align="left" valign="middle">char</cell> + <cell align="left" valign="middle">char</cell> + </row> + <row> + <cell align="left" valign="middle">wchar</cell> + <cell align="left" valign="middle">char</cell> + </row> + <row> + <cell align="left" valign="middle">boolean</cell> + <cell align="left" valign="middle">boolean</cell> + </row> + <row> + <cell align="left" valign="middle">octet</cell> + <cell align="left" valign="middle">octet</cell> + </row> + <row> + <cell align="left" valign="middle">string</cell> + <cell align="left" valign="middle">java.lang.String</cell> + </row> + <row> + <cell align="left" valign="middle">wstring</cell> + <cell align="left" valign="middle">java.lang.String</cell> + </row> + <row> + <cell align="left" valign="middle">any</cell> + <cell align="left" valign="middle">Any</cell> + </row> + <row> + <cell align="left" valign="middle">long double</cell> + <cell align="left" valign="middle">Not supported</cell> + </row> + <row> + <cell align="left" valign="middle">Object</cell> + <cell align="left" valign="middle">Not supported</cell> + </row> + <row> + <cell align="left" valign="middle">void</cell> + <cell align="left" valign="middle">void</cell> + </row> + <tcaption>OMG IDL basic types</tcaption> + </table> + </section> + + <section> + <title>Constructed OMG IDL Types</title> + <p>All constructed types are according to the standard with three (3) major exceptions.</p> + <p></p> + <list type="bulleted"> + <item> + <p>The IDL Exceptions are not implemented in this Java mapping.</p> + <p></p> + </item> + <item> + <p>The functions used for read/write to streams, defined in <c>Helper</c> functions + are named unmarshal (instead for read) and marshal (instead for write). </p> + <p></p> + </item> + <item> + <p>The streams used in <c>Helper</c> functions are <c>OtpInputStream</c> for + input and <c>OtpOutputStream</c> for output.</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>Mapping for Constants</title> + <p>Constants are mapped according to the standard.</p> + </section> + + <section> + <title>Invocations of Operations</title> + <p>Operation invocation is implemented according to the standard. + The implementation is in the class <c><![CDATA[_<nterfacename>Stub.java]]></c> which implements + the interface in <c><![CDATA[<nterfacename>.java]]></c>.</p> + <code type="none"> +test._iStub client; + +client.op(10); + </code> + + <section> + <title>Operation Implementation</title> + <p>The server is implemented through extension of the class + <c><![CDATA[_<nterfacename>ImplBase.java]]></c> and implementation of all the methods in the + interface.</p> + <code type="none"> +public class server extends test._iImplBase { + + public void op(int i) throws java.lang.Exception { + System.out.println("Received call op()"); + o.value = i; + return i; + } + +} + </code> + </section> + </section> + + <section> + <title>Exceptions</title> + <p>While exception mapping is not implemented, the stubs will + generate some Java exceptions in case of operation failure. + No exceptions are propagated through the communication.</p> + </section> + + <section> + <title>Access to Attributes</title> + <p>Attributes are supported according to the standard.</p> + </section> + + <section> + <title>Summary of Argument/Result Passing for Java</title> + <p>All types (<c>in</c>, <c>out</c> or <c>inout</c>) of user defined parameters are supported + in the Java mapping. This is also the case in the Erlang mappings but <em>not</em> in the C + mapping. <c>inout</c> parameters are not supported in the C mapping so if you are going to + do calls to or from a C program <c>inout</c> cannot be used in the IDL specifications.</p> + <p><c>out</c> and <c>inout</c> parameters must be of Holder types. There is a jar file ( <c>ic.jar</c>) + with Holder classes for the basic types in the <c>ic</c> application. This library is in the directory + <c><![CDATA[$OTPROOT/lib/ic_<version number>/priv]]></c>.</p> + </section> + + <section> + <title>Communication Toolbox</title> + <p>The generated client and server stubs use the classes + defined in the <c>jinterface</c> package to communicate + with other nodes. + The most important classes are :</p> + <list type="bulleted"> + <item> + <p><c>OtpInputStream</c> which is the stream class used for incoming message storage</p> + <p></p> + </item> + <item> + <p><c>OtpOutputStream</c> which is the stream class used for outgoing message storage</p> + <p></p> + </item> + <item> + <p><c>OtpErlangPid</c> which is the process identification class used to identify processes inside + a java node.</p> + <p>The recommended constructor function for the OtpErlangPid is + <c>OtpErlangPid(String node, int id, int serial, int creation)</c> where :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>String node</c>, is the name of the node where this process runs.</p> + <p></p> + </item> + <item> + <p><c>int id</c>, is the identification number for this identity.</p> + <p></p> + </item> + <item> + <p><c>int serial</c>, internal information, must be an 18-bit integer.</p> + <p></p> + </item> + <item> + <p><c>int creation</c>, internal information, must have value in range 0..3.</p> + <p></p> + </item> + </list> + </item> + <item> + <p><c>OtpConnection</c> which is used to define a connection between nodes.</p> + <p>While the connection object is stub side constructed in client stubs, it is + returned after calling the <c>accept</c> function from an OtpErlangServer object + in server stubs. + The following methods used for node connection :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>OtpInputStream receiveBuf()</c>, which returns the incoming streams that + contain the message arrived.</p> + <p></p> + </item> + <item> + <p><c>void sendBuf(OtpErlangPid client, OtpOutputStream reply)</c>, which sends + a reply message (in an OtpOutputStream form) to the client node.</p> + <p></p> + </item> + <item> + <p><c>void close()</c>, which closes a connection.</p> + <p></p> + </item> + </list> + </item> + <item> + <p><c>OtpServer</c> which is used to define a server node.</p> + <p>The recommended constructor function for the OtpServer is :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>OtpServer(String node, String cookie)</c>. where :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>node</c> is the requested name for the new java node, + represented as a String object.</p> + <p></p> + </item> + <item> + <p><c>cookie</c> is the requested cookie name for the new java node, + represented as a String object.</p> + <p></p> + </item> + </list> + </item> + </list> + <p>The following methods used for node registration and connection acceptance :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>boolean publishPort()</c>, which registers the server node to <c>epmd</c> daemon.</p> + <p></p> + </item> + <item> + <p><c>OtpConnection accept()</c>, which waits for a connection and returns the + OtpConnection object which is unique for each client node.</p> + <p></p> + </item> + </list> + </item> + </list> + </section> + + <section> + <title>The Package com.ericsson.otp.ic</title> + <p>The package <seealso marker="java/com/ericsson/otp/ic/package-summary">com.ericsson.otp.ic</seealso> + contains a number of java classes specially designed for the IC generated java-back-ends :</p> + <list type="bulleted"> + <item> + <p>Standard java classes defined through OMG-IDL java mapping :</p> + <list type="bulleted"> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/BooleanHolder">BooleanHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/ByteHolder">ByteHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/CharHolder">CharHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/ShortHolder">ShortHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/IntHolder">IntHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/LongHolder">LongHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/FloatHolder">FloatHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/DoubleHolder">DoubleHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/StringHolder">StringHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Any">Any</seealso>, + <seealso marker="java/com/ericsson/otp/ic/AnyHelper">AnyHelper</seealso>, + <seealso marker="java/com/ericsson/otp/ic/AnyHolder">AnyHolder</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/TypeCode">TypeCode</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/TCKind">TCKind</seealso></p> + <p></p> + </item> + </list> + </item> + <item> + <p>Implementation-dependant classes :</p> + <list type="bulleted"> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Environment">Environment</seealso></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Holder">Holder</seealso></p> + <p></p> + </item> + </list> + </item> + <item> + <p>Erlang compatibility classes :</p> + <list type="bulleted"> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Pid">Pid</seealso>, + <seealso marker="java/com/ericsson/otp/ic/PidHelper">PidHelper</seealso>, + <seealso marker="java/com/ericsson/otp/ic/PidHolder">PidHolder</seealso></p> + <p>The Pid class originates from <c>OtpErlangPid</c> and is used to + represent the Erlang built-in <c>pid</c> type, a process's identity. + PidHelper and PidHolder are helper respectively holder classes for Pid.</p> + <p></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Ref">Ref</seealso>, + <seealso marker="java/com/ericsson/otp/ic/RefHelper">RefHelper</seealso>, + <seealso marker="java/com/ericsson/otp/ic/RefHolder">RefHolder</seealso></p> + <p>The Ref class originates from <c>OtpErlangRef</c> and is used to + represent the Erlang built-in <c>ref</c> type, an Erlang reference. + RefHelper and RefHolder are helper respectively holder classes for Ref.</p> + <p></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Port">Port</seealso>, + <seealso marker="java/com/ericsson/otp/ic/PortHelper">PortHelper</seealso>, + <seealso marker="java/com/ericsson/otp/ic/PortHolder">PortHolder</seealso></p> + <p>The Port class originates from <c>OtpErlangPort</c> and is used to + represent the Erlang built-in <c>port</c> type, an Erlang port. + PortHelper and PortHolder are helper respectively holder classes for Port.</p> + <p></p> + </item> + <item> + <p><seealso marker="java/com/ericsson/otp/ic/Term">Term</seealso>, + <seealso marker="java/com/ericsson/otp/ic/TermHelper">TermHelper</seealso>, + <seealso marker="java/com/ericsson/otp/ic/TermHolder">TermHolder</seealso></p> + <p>The Term class originates from <c>Any</c> and is used to + represent the Erlang built-in <c>term</c> type, an Erlang term. + TermHelper and TermHolder are helper respectively holder classes for Term.</p> + <p></p> + </item> + </list> + <p>To use the Erlang build-in classes, you will have to include the file <c>erlang.idl</c> + located under <c>$OTPROOT/lib/ic/include</c>.</p> + </item> + </list> + </section> + + <section> + <title>The Term Class</title> + <p>The <c>Term</c> class is intended to represent the Erlang term generic type. + It extends the <c>Any</c> class and it is basically used in the same way as + in the Any type.</p> + <p>The big difference between Term and Any is the use of <c>guard</c> methods + instead of <c>TypeCode</c> to determine the data included in the Term. + This is especially true when the Term's value class cannot be + determined at compilation time. The guard methods found in Term :</p> + <list type="bulleted"> + <item> + <p><c>boolean isAtom()</c> returns <c>true</c> if the Term is an OtpErlangAtom, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isConstant()</c> returns <c>true</c> if the Term is neither an OtpErlangList nor an OtpErlangTuple, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isFloat()</c> returns <c>true</c> if the Term is an OtpErlangFloat, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isInteger()</c> returns <c>true</c> if the Term is an OtpErlangInt, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isList()</c> returns <c>true</c> if the Term is an OtpErlangList, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isString()</c> returns <c>true</c> if the Term is an OtpErlangString, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isNumber()</c> returns <c>true</c> if the Term is an OtpErlangInteger or an OtpErlangFloat, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isPid()</c> returns <c>true</c> if the Term is an OtpErlangPid or Pid, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isPort()</c> returns <c>true</c> if the Term is an OtpErlangPort or Port, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isReference()</c> returns <c>true</c> if the Term is an OtpErlangRef, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isTuple()</c> returns <c>true</c> if the Term is an OtpErlangTuple, <c>false</c> otherwise</p> + <p></p> + </item> + <item> + <p><c>boolean isBinary()</c> returns <c>true</c> if the Term is an OtpErlangBinary, <c>false</c> otherwise</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>Stub File Types</title> + <p>For each interface, three (3) stub/skeleton files are generated :</p> + <list type="bulleted"> + <item> + <p>A java interface file, named after the idl interface.</p> + <p></p> + </item> + <item> + <p>A client stub file, named after the convention <c><![CDATA[_< interface name >Stub]]></c> + which implements the java interface. Example : <c>_stackStub</c>.java</p> + <p></p> + </item> + <item> + <p>A server stub file, named after the convention <c><![CDATA[_< interface name >ImplBase]]></c> + which implements the java interface. Example : <c>_stackImplBase</c>.java</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>Client Stub Initialization, Methods Exported</title> + <p>The recommended constructor function for client stubs accepts four (4) parameters :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>String selfNode</c>, the node identification name to be used in the new + client node.</p> + <p></p> + </item> + <item> + <p><c>String peerNode</c>, the node identification name where the client process is running.</p> + <p></p> + </item> + <item> + <p><c>String cookie</c>, the cookie to be used.</p> + <p></p> + </item> + <item> + <p><c>Object server</c>, where the java Object can be one of:</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>OtpErlangPid</c>, the server's process identity under the node where the server + process is running.</p> + <p></p> + </item> + <item> + <p><c>String</c>, the server's registered name under the node where the server + process is running.</p> + <p></p> + </item> + </list> + </item> + </list> + <p>The methods exported from the generated client stub are :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>void __disconnect()</c>, which disconnects the server connection.</p> + <p></p> + </item> + <item> + <p><c>void __reconnect()</c>, which disconnects the server connection if open, + and then connects to the same peer.</p> + <p></p> + </item> + <item> + <p><c>void __stop()</c>, which sends the standard stop termination call. + When connected to an Erlang server, the server will be terminated. + When connected to a java server, this will set a stop flag that + denotes that the server must be terminated.</p> + <p></p> + </item> + <item> + <p><c>com.ericsson.otp.erlang.OtpErlangRef __getRef()</c>, will return the message reference + received from a server that denotes which call it is referring to. + This is useful when building asynchronous clients.</p> + <p></p> + </item> + <item> + <p><c>java.lang.Object __server()</c>, which returns the server for the current connection.</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>Server Skeleton Initialization, Server Stub Implementation, Methods Exported</title> + <p>The constructor function for server skeleton accepts no parameters.</p> + <p>The server skeleton file contains a server <c>switch</c> which + decodes messages from the input stream and calls implementation + (<c>callback</c>) functions. + As the server skeleton is declared <c>abstract</c>, the application + programmer will have to create a stub class that <c>extends</c> the + skeleton file. In this class, all operations defined in the interface + class, generated under compiling the idl file, are implemented.</p> + <p>The server skeleton file exports the following methods:</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>OtpOutputStrem invoke(OtpInputStream request)</c>, where the input + stream <c>request</c> is unmarshalled, the implementation function is called + and a reply stream is marshalled.</p> + <p></p> + </item> + <item> + <p><c>boolean __isStopped()</c>, which returns true if a stop message is received. + The implementation of the stub should always check if such a message is received + and terminate if so.</p> + <p></p> + </item> + <item> + <p><c>boolean __isStopped(com.ericsson.otp.ic.Environment)</c>, which returns true if + a stop message is received for a certain Environment and Connection. + The implementation of the stub should always check if such a message is received + and terminate if so.</p> + <p></p> + </item> + <item> + <p><c>OtpErlangPid __getCallerPid()</c>, which returns the caller identity for the latest call.</p> + <p></p> + </item> + <item> + <p><c>OtpErlangPid __getCallerPid(com.ericsson.otp.ic.Environment)</c>, which returns the caller + identity for the latest call on a certain Environment.</p> + <p></p> + </item> + <item> + <p><c>java.util.Dictionary __operations()</c>, which returns the operation dictionary which + holds all operations supported by the server skeleton.</p> + <p></p> + </item> + </list> + </section> + + <section> + <title>A Mapping Example</title> + <p> <marker id="stack_idl"></marker> + + This is a small example of a simple stack. There are two + operations on the stack, push and pop. The example shows some of the + generated files.</p> + <code type="none"> +// The source IDL file: stack.idl + +struct s { + long l; + string s; +}; + +interface stack { + void push(in s val); + s pop(); +}; + </code> + <p>When this file is compiled it produces eight files. Three important files + are shown below. <marker id="stack_serv"></marker> +</p> + <p>The public interface is in <em>stack.java</em>.</p> + <code type="none"> + +public interface stack { + +/**** + * Operation "stack::push" interface functions + * + */ + + void push(s val) throws java.lang.Exception; + +/**** + * Operation "stack::pop" interface functions + * + */ + + s pop() throws java.lang.Exception; + +} + </code> + <p>For the IDL struct s three files are generated, a public class in <em>s.java</em>.</p> + <code type="none"> + +final public class s { + // instance variables + public int l; + public java.lang.String s; + + // constructors + public s() {}; + public s(int _l, java.lang.String _s) { + l = _l; + s = _s; + }; + +}; + </code> + <p>A holder class in <em>sHolder.java</em> and a helper class in <em>sHelper.java</em>. + The helper class is used for marshalling.</p> + <code type="none"> + +public class sHelper { + + // constructors + private sHelper() {}; + + // methods + public static s unmarshal(OtpInputStream in) + throws java.lang.Exception { +\011: +\011: + }; + + public static void marshal(OtpOutputStream out, s value) + throws java.lang.Exception { +\011: +\011: + }; + +}; + </code> + </section> + + <section> + <title>Running the Compiled Code</title> + <p>When using the generated java code you must have added + <c><![CDATA[$OTPROOT/lib/ic_<version number>/priv]]></c> and + <c><![CDATA[$OTPROOT/lib/jinterface_<version number>/priv]]></c> to your + <c>CLASSPATH</c> variable to get + basic Holder types and the communication classes.</p> + </section> +</chapter> + diff --git a/lib/ic/doc/src/erl-part.xml b/lib/ic/doc/src/erl-part.xml new file mode 100644 index 0000000000..b5041dce7f --- /dev/null +++ b/lib/ic/doc/src/erl-part.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part> + <header> + <copyright> + <year>2002</year> + <year>2007</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>IDL to Erlang language Mapping</title> + <prepared></prepared> + <docno></docno> + <date>2002-06-25</date> + <rev>A</rev> + </header> + <description> + <p>Tjosan Erlang</p> + </description> + <include file="ch_erl_plain"></include> + <include file="ch_erl_genserv"></include> +</part> + diff --git a/lib/ic/doc/src/fascicules.xml b/lib/ic/doc/src/fascicules.xml new file mode 100644 index 0000000000..0678195e07 --- /dev/null +++ b/lib/ic/doc/src/fascicules.xml @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> + diff --git a/lib/ic/doc/src/ic.gif b/lib/ic/doc/src/ic.gif Binary files differnew file mode 100644 index 0000000000..d78cf7d8ed --- /dev/null +++ b/lib/ic/doc/src/ic.gif diff --git a/lib/ic/doc/src/ic.xml b/lib/ic/doc/src/ic.xml new file mode 100644 index 0000000000..9f48229425 --- /dev/null +++ b/lib/ic/doc/src/ic.xml @@ -0,0 +1,469 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1997</year> + <year>2007</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>ic</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>2004-01-08</date> + <rev>B</rev> + </header> + <module>ic</module> + <modulesummary>The Erlang IDL Compiler</modulesummary> + <description> + <p>The ic module is an Erlang implementation of an OMG IDL + compiler. Depending on the choice of back-end the code will map + to Erlang, C, or Java. The compiler generates client stubs and + server skeletons.</p> + <p>Two kinds of files are generated for each scope: Ordinary code + files and header files. The latter are used for defining record + definitions, while the ordinary files contain the object + interface functions.</p> + </description> + <funcs> + <func> + <name>ic:gen(FileName) -> Result</name> + <name>ic:gen(FileName, [Option]) -> Result</name> + <fsummary>Generate stub and server code according to the OMG CORBA standard.</fsummary> + <type> + <v>Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]}</v> + <v></v> + <v>Option = [ GeneralOption | CodeOption | WarningOption | BackendOption]</v> + <v></v> + <v>GeneralOption = </v> + <v>{outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} |</v> + <v>{preproc_cmd, String()} | {preproc_flags, String()}</v> + <v></v> + <v>CodeOption =</v> + <v>{gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} | {light_ifr, bool()}</v> + <v>this | {this, String()} | {{this, String()}, bool()} |</v> + <v>from | {from, String()} | {{from, String()}, bool()} |</v> + <v>handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} |</v> + <v>timeout | {timeout, String()} | {{timeout, String()}, bool()} |</v> + <v>{scoped_op_calls, bool()} | {scl, bool()} |</v> + <v>{user_protocol, Prefix} |</v> + <v>{c_timeout, SendTimeout, RecvTimeout} |</v> + <v>{c_report, bool()} |</v> + <v>{precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} |</v> + <v>{postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}}</v> + <v></v> + <v>WarningOption =</v> + <v>{'Wall', bool()} | {maxerrs, int() | infinity} |</v> + <v>{maxwarns, int() | infinity} | {nowarn, bool()} |</v> + <v>{warn_name_shadow, bool()} | {pedantic, bool()} |</v> + <v>{silent, bool()}</v> + <v></v> + <v>BackendOption = {be, Backend}</v> + <v></v> + <v>Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java</v> + <v></v> + <v>DirNAme = string() | atom()</v> + <v>FileName = string() | atom()</v> + </type> + <desc> + <p>The tuple <c>{Option, true}</c> can be replaced by + <c>Option</c> for boolean values.</p> + <p>The <c>ic:gen/2</c> function can be called from the command + line as follows:</p> + <p><c>erlc "+Option" ... File.idl</c></p> + <p>Example:</p> + <p><c>erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl</c></p> + </desc> + </func> + </funcs> + + <section> + <title>General options</title> + <taglist> + <tag><em>outdir</em></tag> + <item> + <p>Places all output files in the directory given by the option. + The directory will be created if it does not already exist.</p> + <p>Example option: <c>{outdir, "output/generated"}</c>.</p> + </item> + <tag><em>cfgfile</em></tag> + <item> + <p>Uses <em>FileName</em> as configuration file. Options will + override compiler defaults but can be overridden by command line + options. Default value is <c>".ic_config"</c>.</p> + <p>Example option: <c>{cfgfile, "special.cfg"}</c>.</p> + </item> + <tag><em>use_preproc</em></tag> + <item> + <p>Uses a preprocessor. Default value is true.</p> + </item> + <tag><em>preproc_cmd</em></tag> + <item> + <p>Command string to invoke the preprocessor. The actual + command will be built as + <c>preproc_cmd++preproc_flags++FileName</c></p> + <p>Example option: <c>{preproc_cmd, "erl"})</c>.</p> + <p>Example option: <c>{preproc_cmd, "gcc -x c++ -E"}</c>.</p> + </item> + <tag><em>preproc_flags</em></tag> + <item> + <p>Flags given to the preprocessor.</p> + <p>Example option: <c>{preproc_flags, "-I../include"}</c>.</p> + </item> + </taglist> + </section> + + <section> + <title>Code options</title> + <taglist> + <tag><em>light_ifr</em></tag> + <item> + <p>Currently, the default setting is <c>false</c>. To be able to + use this option Orber must be configured to use Light IFR (see + Orber's User's Guide). When this options is used, the size of the + generated files used to register the API in the IFR DB are minimized.</p> + <p>Example option: <c>{light_ifr, true}</c>.</p> + </item> + <tag><em>gen_hrl</em></tag> + <item> + <p>Generate header files. Default is true.</p> + </item> + <tag><em>serv_last_call</em></tag> + <item> + <p>Makes the last <c>gen_server handle_call</c> either raise a + CORBA exception or just exit plainly. Default is the exception. + </p> + </item> + <tag><em>{{impl, IntfName}, ModName}</em></tag> + <item> + <p>Assumes that the interface with name <em>IntfName</em> is + implemented by the module with name <em>ModName</em> and + will generate calls to the <em>ModName</em> module in the + server behavior. Note that the <em>IntfName</em> must be a + fully scoped name as in <c>"M1::I1"</c>.</p> + <p></p> + </item> + <tag><em>this</em></tag> + <item> + <p>Adds the object reference as the first parameter to the + object implementation functions. This makes the + implementation aware of its own object reference. + <br></br> +The option + comes in three varieties: <c>this</c> which activates the + parameter for all interfaces in the source file, <c>{this, IntfName}</c> which activates the parameter for a specified + interface and <c>{{this, IntfName}, false}</c> which + deactivates the parameter for a specified + interface.</p> + <p>Example option: <c>this)</c> activates the parameter for + all interfaces.</p> + <p>Example option: <c>{this, "M1::I1"}</c> activates the + parameter for all functions of <c>M1::I1</c>.</p> + <p>Example options: <c>[this, {{this, "M1::I2"}, false}]</c> + activates the parameter for all interfaces except + <c>M1::I2</c>.</p> + </item> + <tag><em>from</em></tag> + <item> + <p>Adds the invokers reference as the first parameter to the + object implementation two-way functions. If both + <c>from</c> and <c>this</c> options are used the invokers + reference parameter will be passed as the second + parameter. This makes it possible for the implementation to + respond to a request and continue executing + afterwards. Consult the <c>gen_server</c> and <c>Orber</c> + documentation how this option may be used. <br></br> +The option + comes in three varieties: <c>from</c> which activates the + parameter for all interfaces in the source file, <c>{from, IntfName}</c> which activates the parameter for a specified + interface and <c>{{from, IntfName}, false}</c> which + deactivates the parameter for a specified interface.</p> + <p>Example option: <c>from)</c> activates the parameter for + all interfaces.</p> + <p>Example options: <c>[{from, "M1::I1"}]</c> activates the + parameter for all functions of <c>M1::I1</c>.</p> + <p>Example options: <c>[from, {{from, "M1::I2"}, false}]</c> + activates the parameter for all interfaces except + <c>M1::I2</c>.</p> + </item> + <tag><em>handle_info</em></tag> + <item> + <p>Makes the object server call a function <c>handle_info</c> + in the object implementation module on all unexpected + messages. Useful if the object implementation need to trap + exits.</p> + <p>Example option: <c>handle_info</c> will activates module + implementation <c>handle_info</c> for all interfaces in the + source file.</p> + <p>Example option: <c>{{handle_info, "M1::I1"}, true}</c> + will activates module implementation <c>handle_info</c> for + the specified interface.</p> + <p>Example options: <c>[handle_info, {{handle_info, "M1::I1"}, false}]</c> will generate the <c>handle_info</c> + call for all interfaces except <c>M1::I1</c>.</p> + </item> + <tag><em>timeout</em></tag> + <item> + <p>Used to allow a server response time limit to be set by the user. + This should be a string that represents the scope for the interface + which should have an extra variable for wait time initialization.</p> + <p>Example option: <c>{timeout,"M::I"})</c> produces server + stub which will has an extra timeout parameter in the initialization + function for that interface.</p> + <p>Example option: <c>timeout</c> produces server + stub which will has an extra timeout parameter in the initialization + function for all interfaces in the source file.</p> + <p>Example options: <c>[timeout, {{timeout,"M::I"}, false}]</c> + produces server stub which will has an extra timeout + parameter in the initialization function for all interfaces + except <c>M1::I1</c>.</p> + </item> + <tag><em>scoped_op_calls</em></tag> + <item> + <p>Used to produce more refined request calls to server. When + this option is set to true, the operation name which was + mentioned in the call is scoped. This is essential to avoid + name clashes when communicating with c-servers. This option + is available for the c-client, c-server and the Erlang + gen_server back ends. <c>All</c> of the parts generated by ic + have to agree in the use of this option. Default is + <c>false</c>. </p> + <p>Example options: + <c>[{be,c_genserv},{scoped_op_calls,true}])</c> produces + client stubs which sends "scoped" requests to a gen_server + or a c-server.</p> + </item> + <tag><em>user_protocol</em></tag> + <item> + <p>Used to define a own protocol different from the default + Erlang distribution + gen_server protocol. Currently only + valid for C back-ends. For further details see <seealso marker="ic_c_protocol">IC C protocol</seealso>.</p> + <p>Example options: + <c>[{be,c_client},{user_protocol, "my_special"}])</c> produces + client stubs which use C protocol functions with the prefix + "my_special".</p> + </item> + <tag><em>c_timeout</em></tag> + <item> + <p>Makes sends and receives to have timeouts (C back-ends only). These + timeouts are specified in milliseconds. </p> + <p>Example options: + <c>[{be,c_client},{c_timeout, 10000, 20000}])</c> produces + client stubs which use a 10 seconds send timeout, and a + 20 seconds receive timeout.</p> + </item> + <tag><em>c_report</em></tag> + <item> + <p>Generates code for writing encode/decode errors to <c>stderr</c> (C back-ends only). + timeouts are specified in milliseconds. </p> + <p>Example options: + <c>[{be,c_client}, c_report])</c>.</p> + </item> + <tag><em>scl</em></tag> + <item> + <p>Used for compatibility with previous compiler versions up + to <c>3.3</c>. Due to better semantic checks on enumerants, + the compiler discovers name clashes between user defined + types and enumerant values in the same name space. By + enabling this option the compiler turns off the extended + semantic check on enumerant values. Default is + <c>false</c>. </p> + <p>Example option: <c>{scl,true}</c></p> + </item> + <tag><em>precond</em></tag> + <item> + <p>Adds a precondition call before the call to the operation + implementation on the server side.</p> + <p>The option comes in three varieties: <c>{precond, {M, F}}</c> which activates the call for operations in all + interfaces in the source file, <c>{{precond, IntfName}, {M, F}}</c> which activates the call for all operations in a + specific interface and <c>{{precond, OpName}, {M, F}}</c> + which activates the call for a specific operation.</p> + <p>The precondition function has the following signature + <c>m:f(Module, Function, Args)</c>.</p> + <p>Example option: <c>{precond, {mod, fun}}</c> adds the call + of m:f for all operations in the idl file.</p> + <p>Example options: <c>[{{precond, "M1::I"}, {mod, fun}}]</c> + adds the call of <c>m:f</c> for all operations in the + interface <c>M1::I1</c>.</p> + <p>Example options: <c>[{{precond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation + <c>M1::I::Op</c>.</p> + </item> + <tag><em>postcond</em></tag> + <item> + <p>Adds a postcondition call after the call to the operation + implementation on the server side. </p> + <p>The option comes in three varieties: <c>{postcond, {M, F}}</c> which activates the call for operations in all + interfaces in the source file, <c>{{postcond, IntfName}, {M, F}}</c> which activates the call for all operations in a + specific interface and <c>{{postcond, OpName}, {M, F}}</c> + which activates the call for a specific operation.</p> + <p>The postcondition function has the following signature + <c>m:f(Module, Function, Args, Result)</c>.</p> + <p>Example option: <c>{postcond, {mod, fun}}</c> adds the call + of m:f for all operations in the idl file.</p> + <p>Example options: <c>[{{postcond, "M1::I"}, {mod, fun}}]</c> + adds the call of <c>m:f</c> for all operations in the + interface <c>M1::I1</c>.</p> + <p>Example options: <c>[{{postcond, "M1::I::Op"}, {mod, fun}}]</c> adds the call of <c>m:f</c> for the operation + <c>M1::I::Op</c>.</p> + </item> + </taglist> + </section> + + <section> + <title>Warning options</title> + <taglist> + <tag><em>'Wall'</em></tag> + <item> + <p>The option activates all reasonable warning messages in + analogy with the gcc -Wall option. Default value is true.</p> + </item> + <tag><em>maxerrs</em></tag> + <item> + <p>The maximum numbers of errors that can be detected before + the compiler gives up. The option can either have an integer + value or the atom <c>infinity</c>. Default number is 10.</p> + </item> + <tag><em>maxwarns</em></tag> + <item> + <p>The maximum numbers of warnings that can be detected before + the compiler gives up. The option can either have an integer + value or the atom <c>infinity</c>. Default value is + infinity.</p> + </item> + <tag><em>nowarn</em></tag> + <item> + <p>Suppresses all warnings. Default value is false.</p> + </item> + <tag><em>warn_name_shadow</em></tag> + <item> + <p>Warning appears whenever names are shadowed due to + inheritance; for example, if a type name is redefined from a + base interface. Note that it is illegal to overload + operation and attribute names as this causes an error to be + produced. Default value is true. </p> + </item> + <tag><em>pedantic</em></tag> + <item> + <p>Activates all warning options. Default value is false.</p> + </item> + <tag><em>silent</em></tag> + <item> + <p>Suppresses compiler printed output. Default value is false.</p> + </item> + </taglist> + </section> + + <section> + <title>Back-End options</title> + <p>Which back-end IC will generate code for is determined by the supplied + <c>{be,atom()}</c> option. If left out, <c>erl_corba</c> is used. + Currently, IC support the following back-ends:</p> + <taglist> + <tag><em>erl_corba</em></tag> + <item> + <p>This option switches to the IDL generation for CORBA.</p> + </item> + <tag><em>erl_template</em></tag> + <item> + <p>Generate CORBA call-back module templates for each interface in the target + IDL file. Note, will overwrite existing files.</p> + </item> + <tag><em>erl_plain</em></tag> + <item> + <p>Will produce plain Erlang modules which contain functions that + map to the corresponding interface functions on the input file.</p> + </item> + <tag><em>erl_genserv</em></tag> + <item> + <p>This is an IDL to Erlang generic server generation option.</p> + </item> + <tag><em>c_client</em></tag> + <item> + <p>Will produce a C client to the generic Erlang server.</p> + </item> + <tag><em>c_server</em></tag> + <item> + <p>Will produce a C server switch with functionality of a + generic Erlang server.</p> + </item> + <tag><em>java</em></tag> + <item> + <p>Will produce Java client stubs and server skeletons with + functionality of a generic Erlang server.</p> + </item> + <tag><em>c_genserv</em></tag> + <item> + <p>Deprecated. Use <c>c_client</c> instead.</p> + </item> + </taglist> + </section> + + <section> + <title>Preprocessor</title> + <p>The IDL compiler allows several preprocessors to be used, the + <c>Erlang IDL preprocessor</c> or other standard <c>C</c> preprocessors. + Options can be used to provide extra flags such as include + directories to the preprocessor. The build in the Erlang IDL + preprocessor is used by default, but any standard C preprocessor + such as <c>gcc</c> is adequate.</p> + <p>The preprocessor command is formed by appending the prepoc_cmd + to the preproc_flags option and then appending the input IDL + file name.</p> + </section> + + <section> + <title>Configuration</title> + <p>The compiler can be configured in two ways:</p> + <list type="ordered"> + <item> + <p>Configuration file</p> + </item> + <item> + <p>Command line options</p> + </item> + </list> + <p>The configuration file is optional and overrides the compiler + defaults and is in turn overridden by the command line options. + The configuration file shall contain options in the form of + Erlang terms. The configuration file is read using + <c>file:consult</c>.</p> + <p>An example of a configuration file, note the "." after each + line.</p> + <code type="none"> +{outdir, gen_dir}. +{{impl, "M1::M2::object"}, "obj"}. + </code> + </section> + + <section> + <title>Output files</title> + <p>The compiler will produce output in several files depending on + scope declarations found in the IDL file. At most + three file types will be generated for each scope (including the top scope), + depending on the compiler back-end and the compiled interface. + Generally, the output per interface will be a header file (<c>.hrl</c>/ + <c>.h</c>) and one or more Erlang/C files (<c>.erl</c>/<c>.c</c>). + Please look at the language mapping for each back-end for details.</p> + <p>There will be at least one set of files for an IDL file, for the + file level scope. Modules and interfaces also have their own set + of generated files.</p> + </section> + +</erlref> + diff --git a/lib/ic/doc/src/ic_c_protocol.xml b/lib/ic/doc/src/ic_c_protocol.xml new file mode 100644 index 0000000000..f895fe0723 --- /dev/null +++ b/lib/ic/doc/src/ic_c_protocol.xml @@ -0,0 +1,158 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <header> + <copyright> + <year>2004</year> + <year>2007</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>IC C Protocol Functions</title> + <prepared></prepared> + <docno></docno> + <date>2004-04-06</date> + <rev>A</rev> + </header> + <lib>ic_c_protocol</lib> + <libsummary>IC C Protocol Functions</libsummary> + <description> + <p>This manual page lists some of the functions of the IC C runtime + library that are used internally for the IC protocol. + </p> + <p>The listed functions are used internally by generated C client + and server code. They are documented here for <em>the advanced user</em> that want to replace the default protocol (Erlang + distribution + gen_server) by his own protocol, For each set of + client or sever functions below with prefix <c>oe</c>, the user + has to implement his own set of functions, the names of which + are obtained by replacing the <c>oe</c> prefix by <c>Prefix</c>. + The <c>Prefix</c> has to be set with the option + <c>{user_protocol, Prefix}</c> at compile time.</p> + <p>The following terminology is used (reflected in names of + functions): a <em>notification</em> is a message send from + client to server, without any reply back (i.e. a + <em>oneway</em> operation); a <em>request</em> is a message sent + from client to server, and where a <em>reply</em> message is + sent back from the server to the client.</p> + <p>In order to understand how the functions work and what they do + the user <em>must</em> study their implementation in the IC C + library (source file is <c>ic.c</c>), and also consider how they + are used in the C code of ordinary generated client stubs or + server skeletons.</p> + <p></p> + </description> + + <section> + <title>Client Protocol Functions</title> + <p>The following functions are used internally by generated C + client code.</p> + </section> + <funcs> + <func> + <name><ret>int</ret><nametext>oe_prepare_notification_encoding(CORBA_Environment *env)</nametext></name> + <fsummary>Prepare client notification encoding.</fsummary> + <desc> + <p>The result of this function is the beginning of a binary of + in external format of the tuple <c>{'$gen_cast', X}</c> where + <c>X</c> is not yet filled in. </p> + <p>In generated client code this function is the first to be called + in the encoding function for each oneway operation.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>oe_send_notification(CORBA_Environment *env)</nametext></name> + <name><ret>int</ret><nametext>oe_send_notification_tmo(CORBA_Environment *env, unsigned int send_ms)</nametext></name> + <fsummary>Send client notification.</fsummary> + <desc> + <p>Sends a client notification to a server according to the + Erlang distribution + gen_server protocol.</p> + <p>The <c>send_ms</c> parameter specified a timeout in milliseconds.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>oe_prepare_request_encoding(CORBA_Environment *env)</nametext></name> + <fsummary>Prepare client request encoding.</fsummary> + <desc> + <p>The result of this function is the beginning of a binary in + the external format of the tuple <c>{'$gen_call', {Pid, Ref}, X}</c> where <c>X</c> is not yet filled in.</p> + <p>In generated client code this function is the first to be called + in the encoding function for each twoway operation.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>oe_send_request_and_receive_reply(CORBA_Environment *env)</nametext></name> + <name><ret>int</ret><nametext>oe_send_request_and_receive_reply_tmo(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms)</nametext></name> + <fsummary>Send client request and receive reply.</fsummary> + <desc> + <p>Sends a client request and receives the reply according to + the Erlang distribution + gen_server protocol. This function + calls the <c>oe_prepare_reply_decoding</c> function in order + to obtain the gen_server reply. + </p> + <p><c>send_ms</c> and <c>recv_ms</c> specify timeouts for send + and receive, respectively, in milliseconds.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>oe_prepare_reply_decoding(CORBA_Environment *env)</nametext></name> + <fsummary>Prepare client decoding of reply.</fsummary> + <desc> + <p>Decodes the binary version of the tuple <c>{Ref, X}</c>, + where <c>X</c> is to be decoded later by the specific client + decoding function.</p> + </desc> + </func> + </funcs> + + <section> + <title>Server Protocol Functions</title> + <p>The following functions are used internally by generated C + server code.</p> + </section> + <funcs> + <func> + <name><ret>int</ret><nametext>oe_prepare_request_decoding(CORBA_Environment *env)</nametext></name> + <fsummary>Prepare server decoding of request.</fsummary> + <desc> + <p>Decodes the binary version of the tuple <c>{'$gen_cast', Op}</c> (<c>Op</c> an atom), or the tuple <c>{'$gen_cast', {Op, X}}</c>, where <c>Op</c> is the operation name, and + where <c>X</c> is to be decoded later by the specific + operation decoding function; or</p> + <p>decodes the binary version of the tuple <c>{'$gen_call', {Pid, Ref}, Op}</c> (<c>Op</c> an atom), or the tuple + <c>{'$gen_call', {Pid, Ref}, {Op, X}}</c>, where <c>Op></c> + is the operation name, and <c>X</c> is to be decode later by + the specific operation decoding function.</p> + </desc> + </func> + <func> + <name><ret>int</ret><nametext>oe_prepare_reply_encoding(CORBA_Environment *env)</nametext></name> + <fsummary>Prepare server encoding of reply.</fsummary> + <desc> + <p>Encodes the beginning of the binary version of the tuple + <c>{{Ref,X}</c>, where <c>X</c> is to be filled in by the + specific server encoding function.</p> + </desc> + </func> + </funcs> + + <section> + <title>SEE ALSO</title> + <p>ic(3), ic_clib(3), <seealso marker="ch_ic_protocol">IC Protocol</seealso></p> + </section> + +</cref> + diff --git a/lib/ic/doc/src/ic_clib.xml b/lib/ic/doc/src/ic_clib.xml new file mode 100644 index 0000000000..b557c4b5f6 --- /dev/null +++ b/lib/ic/doc/src/ic_clib.xml @@ -0,0 +1,246 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE cref SYSTEM "cref.dtd"> + +<cref> + <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 C Library Functions</title> + <prepared></prepared> + <docno></docno> + <date>2003-12-16</date> + <rev>PB1</rev> + </header> + <lib>ic_clib</lib> + <libsummary>IC C Library Functions</libsummary> + <description> + <p>This manual page lists some of the functions in the IC C runtime + library. </p> + </description> + + <section> + <title>Allocation and Deallocation Functions</title> + <p>The following functions are used for allocating and + deallocating a <em>CORBA_Environment</em> structure.</p> + </section> + <funcs> + <func> + <name><ret>CORBA_Environment*</ret><nametext>CORBA_Environment_alloc(int inbufsz, int outbufsz)</nametext></name> + <fsummary>Allocate environment data.</fsummary> + <desc> + <p>This function is used to allocate and initiate the + <c>CORBA_Environment</c> structure. In particular, it is used + to dynamically allocate a CORBA_Environment structure and set + the default values for the structure's fields.</p> + <p><em>inbufsize</em> is the initial size of the input + buffer.</p> + <p><em>outbufsize</em> is the initial size of the output + buffer.</p> + <p><em>CORBA_Environment</em> is the CORBA 2.0 state structure + used by the generated stub.</p> + <p>This function will set all needed default values and + allocate buffers the lengths of which are 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() do + as follows.</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> + </desc> + </func> + <func> + <name><ret>void</ret><nametext>CORBA_free(void *p)</nametext></name> + <fsummary>Free any allocated data.</fsummary> + <desc> + <p>Frees allocated space pointed to by <c>p</c>.</p> + </desc> + </func> + <func> + <name><ret>CORBA_char*</ret><nametext>CORBA_string_alloc(CORBA_unsigned_long len)</nametext></name> + <fsummary>Allocate a string.</fsummary> + <desc> + <p>Allocates a (simple) CORBA character string of length <c>len + 1</c>.</p> + </desc> + </func> + <func> + <name><ret>CORBA_wchar*</ret><nametext>CORBA_wstring_alloc(CORBA_unsigned_long len)</nametext></name> + <fsummary>Allocate a wide string.</fsummary> + <desc> + <p>Allocates a CORBA wide string of length <c>len + 1</c>.</p> + </desc> + </func> + </funcs> + + <section> + <title>Exception Functions</title> + <p>Functions for retrieving exception ids and values, and for setting + exceptions. </p> + </section> + <funcs> + <func> + <name><ret>CORBA_char*</ret><nametext>CORBA_exception_id(CORBA_Environment *env)</nametext></name> + <fsummary>Get exception identity.</fsummary> + <desc> + <p>Returns the exception identity if an exception is set, otherwise + it returns <c>NULL</c>.</p> + </desc> + </func> + <func> + <name><ret>void*</ret><nametext>CORBA_exception_value(CORBA_Environment *env)</nametext></name> + <fsummary>Get exception value.</fsummary> + <desc> + <p>Returns the exception value, if an exception is set, otherwise + it returns <c>NULL</c>.</p> + </desc> + </func> + <func> + <name><ret>void</ret><nametext>CORBA_exc_set(CORBA_Environment *env, CORBA_exception_type Major, CORBA_char *Id, CORBA_char *Value)</nametext></name> + <fsummary>Set exception.</fsummary> + <desc> + <p>Sets the exception type, exception identity, and exception value + in the environment pointed to by <c>env</c>.</p> + </desc> + </func> + </funcs> + + <section> + <title>Server Reception</title> + <p>The following function is provided for convenience. </p> + </section> + <funcs> + <func> + <name><ret>int</ret><nametext>oe_server_receive(CORBA_Environment *env, oe_map_t *map)</nametext></name> + <name><ret>int</ret><nametext>oe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map, unsigned int send_ms, unsigned int recv_ms)</nametext></name> + <fsummary>Server receive of notification or request, and sending of reply (in case of request).</fsummary> + <desc> + <p>Provides a loop that receives one message, executes the + operation in question, and in case of a two-way operation + sends a reply.</p> + <p><c>send_ms</c> and <c>recv_ms</c> specify timeout values + in milliseconds for send and receive, respectively.</p> + </desc> + </func> + </funcs> + + <section> + <title>Generic Execution Switch and Map Merging</title> + <p>Function for searching for server operation function, and for + calling it if found. Function for merging maps (see the include + file <c>ic.h</c> for definitions). </p> + </section> + <funcs> + <func> + <name><ret>int</ret><nametext>oe_exec_switch(CORBA_Object obj, CORBA_Environment *env, oe_map_t *map)</nametext></name> + <fsummary>Search for server operation and execute it.</fsummary> + <desc> + <p>Search for server operation and execute it.</p> + </desc> + </func> + <func> + <name><ret>oe_map_t*</ret><nametext>oe_merge_maps(oe_map_t *maps, int size)</nametext></name> + <fsummary>Merge an array of server maps to one single map.</fsummary> + <desc> + <p>Merge an array of server maps to one single map.</p> + </desc> + </func> + </funcs> + + <section> + <title>The CORBA_Environment structure</title> + <p>Here is the complete definition of the CORBA_Environment structure, + defined in file <em>ic.h</em>: </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> + <note> + <p>Always set the field values <em>_fd</em>, <em>_regname</em>, + <em>_to_pid</em> and/or <em>*_from_pid</em> to appropriate + application values. These are not automatically set by the + stubs.</p> + </note> + <warning> + <p>Never assign static buffers to the buffer pointers, and never + set the <em>_memchunk</em> field to a value less than + <em>32</em>.</p> + </warning> + </section> + + <section> + <title>SEE ALSO</title> + <p>ic(3), ic_c_protocol(3) + </p> + </section> + +</cref> + diff --git a/lib/ic/doc/src/java-part.xml b/lib/ic/doc/src/java-part.xml new file mode 100644 index 0000000000..69cc0f026c --- /dev/null +++ b/lib/ic/doc/src/java-part.xml @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part> + <header> + <copyright> + <year>2002</year> + <year>2007</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>IDL to Java language Mapping</title> + <prepared></prepared> + <docno></docno> + <date>2002-06-25</date> + <rev>A</rev> + </header> + <description> + <p></p> + </description> + <include file="ch_java"></include> +</part> + diff --git a/lib/ic/doc/src/make.dep b/lib/ic/doc/src/make.dep new file mode 100644 index 0000000000..64694ee85a --- /dev/null +++ b/lib/ic/doc/src/make.dep @@ -0,0 +1,24 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex c-part.tex ch_basic_idl.tex ch_c_client.tex \ + ch_c_corba_env.tex ch_c_mapping.tex ch_c_server.tex \ + ch_erl_genserv.tex ch_erl_plain.tex ch_ic_protocol.tex \ + ch_introduction.tex ch_java.tex erl-part.tex \ + ic.tex ic_c_protocol.tex ic_clib.tex java-part.tex \ + ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + diff --git a/lib/ic/doc/src/notes.gif b/lib/ic/doc/src/notes.gif Binary files differnew file mode 100644 index 0000000000..e000cca26a --- /dev/null +++ b/lib/ic/doc/src/notes.gif diff --git a/lib/ic/doc/src/notes.xml b/lib/ic/doc/src/notes.xml new file mode 100644 index 0000000000..c4314d8cc1 --- /dev/null +++ b/lib/ic/doc/src/notes.xml @@ -0,0 +1,444 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>1998</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>IDL Compiler Release Notes</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>2004-04-06</date> + <rev>AC</rev> + <file>notes.xml</file> + </header> + + <section> + <title>IC 4.2.23</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p> + The documentation is now built with open source tools (xsltproc and fop) + that exists on most platforms. One visible change is that the frames are removed.</p> + <p> + Own Id: OTP-8201 Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.22</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The 64-bit version of libic was not compiled with the -fPIC flag.</p> + <p>Own id: OTP-8088</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.21</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The function print_erlang_binary (oe_ei_code_erlang_binary.c) + updated to avoid compiler warning.</p> + <p>Own id: OTP-7982</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.20</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Updated file headers.</p> + <p>Own id: OTP-7837</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.19</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Documentation source included in open source releases.</p> + <p>Own id: OTP-7595</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.18</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Insufficient buffer allocated when passing wide strings + using the C backend on a 64-bit architecture.</p> + <p>Own Id: OTP-7313 Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.17</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Updated file headers.</p> + <p>Own id: OTP-7011</p> + </item> + <item> + <p>IC no longer use the obsolete function file:rawopen/2.</p> + <p>Own id: OTP-7182</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.16</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Added links to classes inherited from Jinterface in the + User's Guide.</p> + <p>Own Id: OTP-6965 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.15</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>If an inherited function name begun with a capital letter + the generated stub/skeleton oe_tc/1 function was incorrect.</p> + <p>Own Id: OTP-6855 Aux Id:</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.14</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The documentation source has been converted from SGML to XML.</p> + <p>Own Id: OTP-6754 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.13</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Minor Makefile changes.</p> + <p>Own Id: OTP-6701 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.12</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Dead code was deleted from the following modules: + ic_cclient, ic_code, ic_cserver, ic_erlbe, ic_java_type, + ic_noc, ic_plainbe, ic_pp, ic_pragma, icscan, icstruct, + ictype, icunion.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.11</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Changed code generation to avoid warnings such as unused + variables.</p> + <p>Own Id: OTP-5930 Aux Id: </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.10</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The FD_SETSIZE limit has been increased to 2048 for + VxWorks/PPC603.</p> + <p>Own Id: OTP-5395 Aux Id: seq9751</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.9</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>In C back-ends, the compiler crashed when generating C code + for error reports when a scoped name was used as a type + in a union.</p> + <p>Own Id: OTP-5375 Aux Id: seq9740 </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.8</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>In C back-ends, when decoding a sequence of "small" + integers, which from Erlang is sent as a string (i.e. + each element between 0 and 255), each string element was + considered to be of signed character type. Each such + element is now correctly treated as an unsigned character + type.</p> + <p>Own Id: OTP-5205 Aux Id: seq9241 </p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.7</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>A new compiler option <c>c_report</c> has been introduced + for C back-ends (client and server). If that option is + set, encoding/decoding errors will be reported to + <c>stderr</c>.</p> + <p>Own Id: OTP-4977</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.6</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The size of modules, used then registering data in the + IFR DB (e.g., oe_MyModule:oe_register()), can be minimized + if the compile option light_ifr is used and Orber is + configured to use Light IFR. Requires that orber-3.5.1, or + later, is used.</p> + <p>Own Id: OTP-5036</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>The compile option <c>multiple_be</c> is no longer supported.</p> + <p>Own Id: OTP-5049</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.5</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Send and receive functions with timeouts have been added + to the C back-ends for the standard protocol (i.e. Erlang + distribution + gen_server protocol).</p> + <p>Accordingly a new compiler option <c>{c_timeout, {SendTimeout, RecvTimeout}}</c> has been added. Timeouts + are specified in milliseconds.</p> + <p>A user that want to implement its own protocols with + function timeouts has to implement the following functions.</p> + <p>For C clients the functions <c>int PFX_send_notification(CORBA_Environment *env, unsigned int send_ms)</c>, and <c>int PFX_send_request_and_receive_reply(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms)</c> + have to be additionally implemented, where PFX is the + user defined prefix.</p> + <p>For C servers no additional functions have to be + implemented, but a clone of the <c>int oe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map, unsigned int send_ms, unsigned int recv_ms)</c> + might be handy.</p> + <p>Own Id: OTP-4972</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.4</title> + + <section> + <title>Improvements and new features</title> + <list type="bulleted"> + <item> + <p>The C back-ends has been opened up, so that a user can + define his own protocol, differing from the Erlang + distribution + gen_server protocol. <br></br> + + For C clients it means to replace the library functions + <c>int oe_prepare_notification_encoding(CORBA_Environment *env)</c>, <c>int oe_send_notification(CORBA_Environment *env)</c>, <c>int oe_prepare_request_encoding(CORBA_Environment *env)</c>, + <c>int oe_send_request_and_receive_reply(CORBA_Environment *env)</c>, and <c>int oe_prepare_reply_decoding(CORBA_Environment *env)</c>, + with functions of the same signature, but with the prefix + "oe" replaced by a user defined prefix. + For C servers the functions <c>int oe_prepare_request_decoding(CORBA_Environment *env)</c>, + and <c>int oe_prepare_reply_encoding(CORBA_Environment *env)</c>, are similarly replaced. <br></br> + + The new compiler option <c>{user_protocol, Prefix}</c> has + been added.</p> + <p>Own Id: OTP-4834</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.3</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>In generated code for the C server back-end, the naming scope + was in error for prototypes in C header files for interfaces + inheriting base interfaces.</p> + <p>Own Id: OTP-4881</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>IDL long long and unsigned long long could not + be used in a struct for the Java backend.</p> + <p>All unsigned integer types for the Java backend + had broken marshalling for large values.</p> + <p>Own Id: OTP-4763</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A scoping problem (IC could not find typedefs contained + inherited interfaces) in the C-backend solved.</p> + <p>Own Id: OTP-4758</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The CORBA stub/skeleton-files generated by IC have been improved, + i.e., depending on the IDL-files, reduced the size of the + erl- and beam-files and decreased dependencies off Orber's + Interface Repository. It is necessary to re-compile all IDL-files + and use COS-applications, including Orber, compiled with + IC-4.2.</p> + <p>Own Id: OTP-4576</p> + </item> + </list> + </section> + </section> +</chapter> + diff --git a/lib/ic/doc/src/old_notes.xml b/lib/ic/doc/src/old_notes.xml new file mode 100644 index 0000000000..9ba0262573 --- /dev/null +++ b/lib/ic/doc/src/old_notes.xml @@ -0,0 +1,1565 @@ +<?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>IDL Compiler Release Notes</title> + <prepared></prepared> + <docno></docno> + <checked></checked> + <date>2003-11-19</date> + <rev>AB</rev> + </header> + + <section> + <title>IC 4.1.8</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>IDL-files containing <c>result</c> or <c>Result</c> as, + for example, parameter name, caused an exit with reason + <c>bad_match</c>.</p> + <p>Own Id: OTP-4532</p> + </item> + <item> + <p>Uninitialized variables were used in <c>ic_init_ref</c> for + C backends. </p> + <p>Own Id: OTP-4537 <br></br> + + Aux Id: seq7666, ETOtr17107</p> + </item> + <item> + <p><c>CORBA_Environment_alloc()</c> left some fields + uninitialized in the returned pointer to an + <c>CORBA_Environment</c> for C backends.</p> + <p>Own Id: OTP-4538</p> + </item> + <item> + <p>The function <c>ic_compare_refs()</c> for C backends + could find two unequal references to be equal.</p> + <p>Own Id: OTP-4539</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.7</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Operation names were always scoped in C server backend, + irrespective of the setting of the option + <c>scoped_op_calls</c>.</p> + <p>Own Id: OTP-4521 <br></br> + + Aux Id: seq7643, ETOtr16925</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.6</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>For C backends generated code checks that the + <c>_length</c> field of bounded sequences (i.e. specified + as <c><![CDATA[sequence <TYPE, MAX>]]></c>) does not exceed the + specified maximum length. If so, an exception is raised.</p> + <p>Own Id: OTP-4471</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The <c>_maximum</c> field was not set for sequence structs + generated by the C backends.</p> + <p>Own Id: OTP-4471 <br></br> + + Aux Id: seq7600, ETOtr16308</p> + </item> + <item> + <p>There was a memory leak in C backends in case there was a + decoding error in a sequence with elements of basic type.</p> + <p>Own Id: OTP-4475</p> + </item> + <item> + <p>For for C backends, IDL structs defined within an + interface were not mapped into C structs in appropriate + include files.</p> + <p>Own Id: OTP-4481 <br></br> + + Aux Id: seq7617</p> + </item> + <item> + <p>If the user, incorrectly, trap exit's but did not use the + 'handle_info' compile option it would cause the server to + terminate. The same problem occurred if someone, + illegally, sent a message to the server. It could also + happen for illegal oneway operations.</p> + <p>Own Id: OTP-4488</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Invalid C code was generated for type short. </p> + <p>Own Id: OTP-4450 <br></br> + + Aux Id: seq7582</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.4</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Operation functions inherited by an interface were not + placed in the map table in generated code for the C server + backend. As a result such functions were not found by the + switch function of the interface.</p> + <p>Own Id: OTP-4448 <br></br> + + Aux Id: seq7582</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.3.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A non-ANSI compliant construct in libic.a was changed.</p> + <p>Own Id: -</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.3</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>For Erlang and C back-ends an IC version stamp has been + added to generated source code. This stamp i preserved in + compiled target code.</p> + </item> + <item> + <p>For C backends an <c>assert()</c> expression has been + added to generated code. That expression asserts that the + result of a memory allocation size calculation is strictly + positive. An error will result in a printout and an + <c>abort()</c>. The assertion can be inhibited by defining + the macro <c>NDEBUG</c> (according to ANSI C).</p> + <p>If the assertion is inhibited, and a size calculation error + is detected, an INTERNAL CORBA exception is set. </p> + </item> + <item> + <p>An internal reorganization of C backend generator code has + been done (addition of module <c>ic_cclient</c>). Several + changes has been done in generated C code:</p> + <list type="bulleted"> + <item> + <p>The typedef <c>___generic___</c> has been replaced by + the typedef <c>___exec_function___</c>, which has been + made more strict; for backward compatibility the + <c>___generic___</c> typedef is now an alias for + <c>___exec_function___</c>.</p> + </item> + <item> + <p>Function parameters that are arrays, has been changed + to be pointers to array slices, which are equivalent + according to ANSI C. </p> + </item> + <item> + <p>The storage class specifier <c>extern</c> has been + removed from function prototypes in header files.</p> + </item> + <item> + <p>Redundant type casts have been removed from generated code. + Also some local "generic" variables have been renamed.</p> + </item> + </list> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Module info vsn replaced by app_vsn.</p> + <p>Own Id: OTP-4341</p> + </item> + <item> + <p>IC-4.1.2 disabled the definition of float constants + beginning with a zero (e.g. <c>0.14</c>).</p> + <p>Own Id: OTP-4367</p> + </item> + <item> + <p>IC did not handle constant definitions correctly for + char, string, wchar and wstring.</p> + <p>Own Id: OTP-4067, OTP-3222</p> + </item> + <item> + <p>IC did not recognize all reserved words defined in the + OMG specification (2.3.1). The new keywords are <c>fixed, abstract, custom, factory, local, native, private, public, supports, truncatable, 'ValueBase'</c> and + <c>valuetype</c>. But for now this is only active for the + <c>erl_corba</c> backend and only incorrect usage of + <c>fixed</c>, since this datatype is now supported, + triggers an error for this backend.</p> + <p>Own Id: OTP-4368</p> + </item> + <item> + <p>It was not possible to use wchar or wstring inside a + union body when using the Java backend.</p> + <p>Own Id: + OTP-4365</p> + </item> + <item> + <p>The compile options <c>this</c> and <c>handle_info</c> + did not behave as described in the documentation. The + <c>timeout</c> now behaves as, for example, + <c>handle_info</c>.</p> + <p>Own Id: OTP-4386, OTP-3231</p> + </item> + <item> + <p>If we typedef a sequence, which contains a struct or a union, + the access function <c>id/0</c> returned an incorrect IFR Id + if a prefix pragma was used.</p> + <p>Own Id: OTP-4387</p> + </item> + <item> + <p>If an IDL file contained a prefix pragma, incorrect + IFR-id's was generated in the IFR-registration operation + <c>oe_register</c> for aliases (typedef) and + attributes.</p> + <p>Own Id: OTP-4388, OTP-4392</p> + </item> + <item> + <p>For C back-ends, when encodings/decodings failed, memory + allocated for variable size parameter types was not freed.</p> + <p>Own Id: OTP-4391 + <br></br> +Aux Id: seq7438, ETOtr14009</p> + </item> + <item> + <p>If an IDL file contained a multiple typedef + (e.g. typedef string str1, str2;), the <c>oe_unregister</c> + operation failed to remove all data, in this case str2, + from the IFR.</p> + <p>Own Id: OTP-4393</p> + </item> + <item> + <p>IC did not recognize octet-constants + (e.g. const octet octetmax = 255;).</p> + <p>Own Id: OTP-4400</p> + </item> + <item> + <p>Negative 'long long' constants was not accepted + (e.g. const long long MyConstant = -1;).</p> + <p>Own Id: OTP-4401</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Merging of map's (<em>___map___</em>) using the + <em>___merge___</em> function does not work.</p> + <p>Own Id: OTP-4323</p> + </item> + <item> + <p>Error in generated C decode/encode functions for union's with + discriminator where the union has no value for all discriminator + values. E.g. a union with discriminator boolean where only the + discriminator value TRUE has a corresponding union value. + Here is how such a thing would look in IDL:</p> + <pre> +\011 union OptXList switch(boolean) { +\011 case TRUE: integer val; + }; + </pre> + <p>Own Id: OTP-4322</p> + </item> + <item> + <p>Scoped op calls ('{scoped_op_calls, true}') does not handle + module/function names beginning with capital letter (e.g. + Megaco should be 'Megaco') for oneway operations (handle_cast).</p> + <p>Own Id: OTP-4310</p> + </item> + <item> + <p>A bug is fixed on C-IDL erlang binaries that caused + pointer error when residing inside sequences.</p> + <p>Own Id: OTP-4303</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.1.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>A new option 'multiple_be' is added that allows multiple backend + generation for the same IDL file.</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed on IDL types that contain underscore '_'.</p> + <p>Own Id: OTP-3710</p> + </item> + <item> + <p>A bug is fixed on IDL structs that caused scope confusion + when types and fields of a struct had the same name.</p> + <p>Own Id: OTP-2893</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.7</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The Erlang binary special type is introduced, that + allows efficient transfer of binaries between Erlang and C. </p> + <p>Own Id:OTP-4107</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.6</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed on noc backend which caused generation of erroneous code.</p> + <p>Own Id: OTP-3812</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.5</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The pragma code option is extended to point + specific functions on NOC backend, not only + interfaces.</p> + <p></p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.4</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug in pragma prefix when including IDL files is fixed. + This caused problems for Erlang-corba IFR registrations.</p> + <p>Own Id: OTP-3620</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.3</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Limited support on multiple file module definitions.</p> + <p>The current version supports multiple file module definitions all + backends except the c oriented backends.</p> + <p>Own Id: OTP-3550</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.2</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed on Erlang backends.</p> + <p>The (recently) introduced generation of files + describing sequence and array files were even + true for included interfaces. In the case of + some Erlang backends this were unnecessary.</p> + <p>Own Id: OTP-3485</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>New functionality added on Java and Erl_genserv backends.</p> + <p></p> + <list type="bulleted"> + <item> + <p>On the Java client stub :</p> + <p></p> + <list type="bulleted"> + <item> + <p>The Java client have now one more constructor function, + that allows to continue with an already started connection.</p> + </item> + <item> + <p><c>void __stop()</c> which sends a stop cast call to the server. + While this causes the Erlang server to terminate, it + sets a stop flag to the Java server environment, requesting the + server to terminate.</p> + </item> + <item> + <p><c>void __reconnect()</c> which closes the current client connection + if open and then connects to the same server.</p> + </item> + </list> + <p>The Environment variable is now declared as <c>public</c>. </p> + </item> + <item> + <p>On the Java server skeleton :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>boolean __isStopped()</c> which returns true if a <c>stop</c> + message where received, false otherwise. The user must check if + this function returns true, and in this case exit the implemented + server loop.</p> + </item> + </list> + <p>The Environment variable is now declared as <c>protected</c> which + allows the implementation that extends the stub to access it.</p> + </item> + <item> + <p>On the Erlang gen_server stub :</p> + <p></p> + <list type="bulleted"> + <item> + <p><c>stop(Server)</c> which yields to a cast call to the standard + gen_server <c>stop</c> function. This will always terminate the + Erlang gen_server, while it will set the stop flag for the + Java server stub.</p> + </item> + </list> + </item> + </list> + <p>Own Id: OTP-3433</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 4.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>New types handled by IC.</p> + <p>The following OMG-IDL types are added in this compiler version :</p> + <list type="bulleted"> + <item> + <p>long long</p> + <p>unsigned long long</p> + <p>wchar</p> + <p>wstring</p> + </item> + </list> + <p>Own Id: OTP-3331</p> + <p></p> + </item> + <item> + <p>TypeCode as built in type and access code files for array and sequence types.</p> + <list type="bulleted"> + <item> + <p>As TypeCode is a <c>pseudo</c>-interface, it is now is a built-in type on IC.</p> + </item> + <item> + <p>Access code files which contain information about TypeCode, ID and Name are + now generated for user defined arrays and sequences.</p> + </item> + </list> + <p>Own Id: OTP-3392</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.8.2</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <p>A bug is fixed on preprocessor directive expansion.</p> + <p>When nested #ifdef - #ifndef directives, a bug caused + improper included file expansion. This is fixed by + repairing the preprocessor expansion function.</p> + <p>Own Id: OTP-3472</p> + </section> + </section> + + <section> + <title>IC 3.8.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Build in Erlang types support for java-backends</p> + <p>The built-in Erlang types <c>term, port, ref</c> and <c>pid</c> + are needed in Java backends in order to support an + efficient mapping between the two languages. + The new types are also supported by additional + helpers and holders to match with OMGs Java mapping + As a result of this, the following classes are added to + the <c>com.ericsson.otp.ic</c> interface :</p> + <list type="bulleted"> + <item> + <p><c>Term,TermHelper,TermHolder</c> which represents the + built-in Erlang type <c>term</c></p> + </item> + <item> + <p><c>Ref,RefHelper,RefHolder</c> which represents the + built-in Erlang type <c>ref</c></p> + </item> + <item> + <p><c>Port,PortHelper, PortHolder</c> which represents the + built-in Erlang type <c>port</c></p> + </item> + <item><c>Pid, PidHelper and PidHolder</c> which represents the + built-in Erlang type <c>pid</c></item> + </list> + <p></p> + <p>Own Id: OTP-3348</p> + <p></p> + </item> + <item> + <p>Compile time preprocessor macro variable definitions</p> + <p>The preprocessor lacked possibility to accept user + defined variables other than the one defined in IDL files. + This limited the use of command-ruled IDL specifications. + Now the build-in preprocessor allows the user to set variables + by using the "preproc_flags" option the same way + as using the "gcc" preprocessor.</p> + <p>Supported flags : </p> + <list type="bulleted"> + <item> + <p><c><![CDATA["-D< Variable >"]]></c> which defines a variable</p> + </item> + <item> + <p><c><![CDATA["-U< Variable >"]]></c> which undefines a variable</p> + </item> + </list> + <p></p> + <p>Own Id: OTP-3349</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <p>A bug on comment type expansion is fixed.</p> + <p>The comment type expansion were erroneous when + inherited types (NOC backend). + This is now fixed and the type naming agree with + the scope of the inheritor interface.</p> + <p>Own Id: OTP-3346</p> + </section> + </section> + + <section> + <title>IC 3.8</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The code generated for java backend is optimized + due to use of streams instead for tuple classes + when (un)marshalling message calls. + Support for building clients using asynchronous + client calls and effective multi-threaded servers.</p> + <p>Own Id: OTP-3310</p> + <p></p> + </item> + <item> + <p>The <c>any</c> type is now supported for java backend.</p> + <p>Own Id: OTP-3311</p> + </item> + </list> + </section> + + <section> + <title>A bug on C generated constants is fixed</title> + <p>While the constants are evaluated and behave well when used + inside an IDL specification their C-export were not working properly. + The constant export definitions were not generated well :</p> + <list type="bulleted"> + <item> + <p>the declared C definition were erroneous ( the name did not always agree + with the scope the constant were declared in ).</p> + </item> + <item> + <p>there were no C- definition generated for the c-server backend when + the constants were declared inside an interface.</p> + </item> + </list> + <p>Own Id: OTP-3219</p> + </section> + + <section> + <title>Incompatibilities</title> + <p>Due to optimizations in java backend, the stub initialization and usage + differs than the previous version.</p> + <p>Client stub interface changes:</p> + <list type="bulleted"> + <item> + <p>Client disconnects by calling the <c>__disconnect()</c> function instead + for the old <c>_closeConnection()</c></p> + <p></p> + </item> + <item> + <p>All <c>marshal</c> operation functions have now the interface :</p> + <p><c><![CDATA[void _< OpName >_marshal(Environment<, Param |, Params >)]]></c></p> + <p>instead for</p> + <p><c><![CDATA[OtpErlangTuple _< OpName >_marshal(< Param, | Params, >OtpErlangPid, OtpErlangRef)]]></c></p> + <p></p> + </item> + <item> + <p>All <c>unmarshal</c> operation functions have now the interface :</p> + <p><c><![CDATA[< Ret value > _< OpName >_unmarshal(Environment<, Param |, Params >)]]></c></p> + <p>instead for</p> + <p><c><![CDATA[< Ret value > _< OpName >_unmarshal(< Param, | Params, >OtpErlangTuple, OtpErlangRef)]]></c></p> + <p></p> + </item> + <item> + <p>Call reference extraction is available by the client function :</p> + <p><c>OtpErlangRef __getRef()</c></p> + <p>instead for previous function :</p> + <p><c>OtpErlangRef _getReference(OtpErlangTuple)</c></p> + <p></p> + </item> + </list> + <p>Server skeleton interface changes:</p> + <list type="bulleted"> + <item> + <p>The implementation function no longer have to contain the + two (2) contractor functions (with <c>super()</c>). This is due + to the fact that there is only one contractor function for each + skeleton file :</p> + <p><c><![CDATA[public _< interface name >ImplBase()]]></c></p> + <p></p> + </item> + <item> + <p>The parameter for the caller identity extraction function <c>_getCallerPid</c> + is now an <c>Environment</c> variable instead for an <c>OtpErlangTuple</c>.</p> + <p></p> + </item> + <item> + <p>There is a new <c>invoke</c> function :</p> + <p><c>OtpOutputStream invoke(OtpInputStream)</c></p> + <p>instead for the old one :</p> + <p><c>OtpErlangTuple invoke(OtpErlangTuple)</c></p> + <p></p> + </item> + <item> + <p>The <c>OtpConnection</c> class function used for receiving messages is now :</p> + <p><c>OtpInputStream receiveBuf()</c></p> + <p>instead for the old one :</p> + <p><c>OtpErlangTuple receive()</c></p> + <p></p> + </item> + <item> + <p>The <c>OtpConnection</c> class function used for sending messages is now :</p> + <p><c>void sendBuf(OtpErlangPid, OtpOutputStream)</c></p> + <p>instead for the old one :</p> + <p><c>void send(OtpErlangPid, OtpErlangTuple)</c></p> + <p></p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.7.1</title> + + <section> + <title>Improvements and New Features</title> + <p>Some memory usage optimizations for the compiler were done.</p> + </section> + + <section> + <title>Fixed bugs and malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed when C backend is used.</p> + <p>When C-union with enumerant discriminator, the size + calculation of the discriminator value were erroneous. + This lead to the side effect that only the first case of the + union were allowed. + The error were fixed by fixing the size calculation of + the discriminator. </p> + <p>Own Id: OTP-3215</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.7</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed when C backend is used.</p> + <p>When unions with enumerant discriminator + were decoded, an error encountered in the + union size calculation. </p> + <p>Own Id: OTP-3209</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.6</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed when NOC backend is used.</p> + <p>When several functions with the same name + were found in the included file tree, + a compile time failure occurred.</p> + <p>Own Id: OTP-3203</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.5</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Noc backend optimization</p> + <p>When NOC backend is choosen, the type code + information on the stub functions is reduced + to a single atom "no_tk". + This is the default behavior. The typecode + generation is enabled by the "use_tk" switch.</p> + <p>Own Id: OTP-3196</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>General java backend bug fixes </p> + <p>Protocol errors on user defined structures and + union types are corrected.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.4</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Semantic test enhancements.</p> + <p>The compiler detects now semantic errors when enumerant + values collide with user defined types on the same name scope.</p> + <p>Own Id: OTP-3157 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>General java backend bug-fixes </p> + <p>Several bugs were fixed on user defined types.</p> + <list type="bulleted"> + <item> + <p>Union discriminators work better when + all possible case values are defined.</p> + </item> + <item> + <p>A bug on Interface inherited operations is + fixed that cause errors on generated server switch.</p> + </item> + <item> + <p>Type definitions on included files are better generated. </p> + </item> + </list> + <p>Own Id: OTP-3156 <br></br> +</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.3</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>A new back-end which generates Java code according to the CORBA IDL to Java mapping for + communication with the Erlang distribution protocol has been added to IC. + For the moment there is no support for the Erlang types Pid, Ref, Port and Term + but this will be added later.</p> + <p>Own Id: OTP-2779 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Fixed the bug that the c code backends sometimes generated incorrect code for + struct arguments. They shall always be pointers. </p> + <p>Own Id: OTP-2732 <br></br> +</p> + </item> + <item> + <p>The code generation is fixed so the array parameters now follow the + CORBA V2.0 C mapping.</p> + <p>Own Id: OTP-2873 <br></br> +</p> + </item> + <item> + <p>Fixed the problem that the checking of the numbers of out-parameters always was true.</p> + <p>Own Id: OTP-2944 <br></br> +</p> + </item> + <item> + <p>Fixed the bug that some temporary variables was not declared when c code.</p> + <p>Own Id: OTP-2950 <br></br> +</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.2.2</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Unions are now supported to agree with OMG's C mapping.</p> + <p>Own Id: OTP-2868 <br></br> +</p> + </item> + <item> + <p>There is now a possibility to use pre- and postcondition methods on the server side + for IC generated Corba Objects. The compiler option is documented in the ic reference manual + and an example of how the pre- and postcondition methods should be designed and used is + added to ic example directory (an ReadMe.txt file exists with some instructions for + running the example code).</p> + <p>Own Id: OTP-3068 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The compiler ignores unknown/non supported pragma directives. A warning is raised + while the generated code will then be the same as if the corresponding + (unknown) pragma directive were missing. </p> + <p>Own Id: OTP-3052 <br></br> +</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.2.1</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Wrong C code was generated for limited strings when they where included + from another IDL specification.</p> + <p>Own Id: OTP-3033 <br></br> +</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.2</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The buffers for in/output used by C-stubs are now expandable. + This fixes buffer overflow problems when messages received/sent + do not fit in buffers.</p> + <p>Own Id: OTP-3001 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <p>The CORBA_Environment structure has now two new fields, the buffers for in/output + must now be dynamically allocated.</p> + </section> + </section> + + <section> + <title>IC 3.1.2</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The generated IFR registration function for constants has been fixed + so the parameters are correct.</p> + <p>Own Id: OTP-2856 <br></br> +</p> + </item> + <item> + <p>Error in the C code generation of ONEWAY operations without parameters + The bug was an decoding error in the operation header. The generated code expected one + parameter instead of zero. This is now fixed.</p> + <p>Own Id: OTP-2909 <br></br> +</p> + </item> + <item> + <p>Type problems on floats and booleans fixed.</p> + <p>Erroneous code for runtime checks on float was removed and + the internal format of the data representing the boolean value + is upgraded.</p> + <p>Own Id: OTP-2925 <br></br> +</p> + </item> + <item> + <p>The generated code for arrays of typedefined strings were + erroneous in the C-backends due to a failure in the compiler internal type + checking.</p> + <p>Own Id: OTP-2936 <br></br> +</p> + </item> + <item> + <p>The generated code for typedefined nested sequences were erroneous + in the C-backends. Pointer mismatches caused compilation failure.</p> + <p>Own Id: OTP-2937 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <p>The IDL specifications must be regenerated for C due to changes in the code generation.</p> + <p>One must regenerate IDL specifications for Erlang CORBA if there are constants in the + specification due to previous errors in the IFR registration functions (OTP-2856).</p> + </section> + </section> + + <section> + <title>IC 3.1.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Improvements on error report on unsupported types by</p> + <p>propagating warning when declaring unions in C -backends</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed when arrays that contained variable size data + on C-backends</p> + <p>The compiler generated erroneous code when IDL + defined arrays that contained variable size data such + as strings, variable size structs or sequences.</p> + <p>Own Id: OTP-2900 <br></br> +</p> + </item> + <item> + <p>A bug is fixed when sequences that contained variable size data + on C_backends</p> + <p>The compiler generated erroneous code when IDL + defined arrays that contained variable size data such + as strings, variable size structs or other sequences.</p> + <p>Own Id: OTP-2901 <br></br> +</p> + </item> + <item> + <p>A bug concerning bounded strings on C-backends is fixed.</p> + <p>The compiler generated erroneous code for IDL + defined bounded strings. Syntax errors were generated + in special cases of typdedefined strings.</p> + <p>Own Id: OTP-2898 <br></br> +</p> + </item> + <item> + <p>A runtime error when sequences that contained integer types is fixed.</p> + <p>When C-clients/server that communicated with Erlang clients/servers, + and the data send by Erlang part were a list of small numbers, + the Erlang runtime compacts the list to a string. This caused a + runtime error when sending sequences of integer types and all had + value less than 256.</p> + <p>Own Id: OTP-2899 <br></br> +</p> + </item> + <item> + <p>An OMG IDL - C mapping problem on enumerant values is fixed.</p> + <p>The enumerant values names is now prefixed by the current scope, + as defined in the specification.</p> + <p>Own Id: OTP-2902 <br></br> +</p> + </item> + <item> + <p>A problem when using constants in array declarations is fixed.</p> + <p>Array dimensions declared with constants generated erroneous code.</p> + <p>Own Id: OTP-2864 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>Changes in C-generation on enumerant values.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.1</title> + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug is fixed on the generated structures. </p> + <p>The generated C code for the structures corresponds now + to direct mapping of C-structs. </p> + <p>Own Id: OTP-2843 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>Included structures inside a struct are no longer pointers.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 3.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Interface change for C-backends</p> + <p>Major interface change. The new interface is CORBA 2.0 + compliant.</p> + <p>Own Id: OTP-2845 <br></br> +</p> + </item> + <item> + <p>The C-backends functionality is improved</p> + <list type="bulleted"> + <item> + <p>Due to interface change and some unneeded error + checks,the C-generated code is fairly optimized.</p> + </item> + </list> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Several serious bugs on decoding and memory allocation are fixed. </p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>Interface change on the C-backends</p> + <p>In order to be CORBA 2.0 compatible, the new version + generates fully incompatible C code.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 2.5.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>A new backend is added : C-server</p> + <p>This back-ends can be used to create servers, + compatible to c-clients, and Erlang genserver clients. + The code produced is a collection of functions for + encoding and decoding messages and a switch that coordinates + them. These parts can be used to create other servers as well. + All functions are exported to header files.</p> + <p>Own Id: OTP-2713 <br></br> +</p> + </item> + <item> + <p>The C-client functionality is improved</p> + <list type="bulleted"> + <item> + <p>The static buffer used for input/output is removed along + with the <c>memset</c> function that initiated it. + The new client is at least 20-30 percent faster.</p> + </item> + <item> + <p>The internal structure of the client is changed. + The client functions are now a collection of encoding + and decoding message functions ruled by a specific + call function. While the basic client generated is + a synchronous client, the exported functions + support the implementation of threaded asynchronous + clients.</p> + </item> + <item> + <p>The static buffer used for input/output is remove along + with the <c>memset</c> function that initiated it. + The new client is at least 20-30 percent faster.</p> + </item> + <item> + <p>The code generated is generally improved, warnings are + (almost) eliminated, while no unidentified variable + errors occur.</p> + </item> + <item> + <p>The IDL types unsigned shorts, shorts, floats are supported now.</p> + </item> + <item> + <p>All generated functions are exported in client header files..</p> + </item> + </list> + <p>Own Id: OTP-2712 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Changes in compiler usage and code generation.</title> + <list type="bulleted"> + <item> + <p>A new option is added for the C-server back-end : <c>c_server</c>.</p> + </item> + <item> + <p>A new option is added : <c>scoped_op_calls</c>.</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>A bug oneway operations on erl_corba and erl_genserv that caused + en exit due to internal interface error is fixed. </p> + </item> + <item> + <p>A bug on oneway operations on c_genserv back-end that caused several + variables to be unidentified is fixed. </p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>Interface change on the C-client</p> + <p>The client functions are called with two extra variables, a pointer to + an array of char - used for storage and an integer - the array size</p> + </item> + <item> + <p>The IDL type <c>attribute</c> is disabled, due to some implementation problems.</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 2.1</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The compiler now provides more in depth information (printouts) when errors occur.</p> + <p>In some cases the compiler stops compiling + due to an abnormal exit or incompatible input. + In this situation, a "fatal error" may occur but the compiler will + generate information explaining the problem.</p> + <p>Own Id: OTP-2565 <br></br> +</p> + </item> + </list> + </section> + </section> + + <section> + <title>IC 2.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The IDL compiler is now a separate application and is longer a part of Orber.</p> + </item> + <item> + <p>Pragma handling implementation.</p> + <p>Pragma ID, prefix + and version are implemented to agree with CORBA revision + 2.0. The compiler accepts and applies these on the + behavior of the compiled code. <br></br> + In this implementation, + pragmas are accepted by the parser and applied by the use + of ic_pragma functions. <br></br> + All IFR-identity handling now + passes through pragma table. As pragma handling in OMG-IDL + is affecting the identity of an ifr-object, all identity + handling and registration is now controlled by pragma + functions. A hash table called "pragmatab" contains vital + identity information used under compilation. <br></br> +</p> + <p>There two major pragma categories :</p> + <list type="bulleted"> + <item> + <p>Normal pragmas, are used in the code where + basic definitions and statements appear. </p> + </item> + <item> + <p>Under certain circumstances, ugly pragmas can now + appear inside code, parameter lists, structure + definitions ... etc. <br></br> + It is quite challenging to + allow ugly pragmas, but the effects of unlimited ugly + pragma implementation on the parser can be enormous. + Ugly pragmas can cause the parser source code to + become time consuming and user unreadable. <br></br> + In order + to allow ugly pragmas but not destroy the current + structure of the parser, the use of ugly pragmas is + limited. Multiple pragma directives are allowed + inside parameter lists, unions, exceptions, + enumerated type, structures... as long as they are do not + appear between two keywords or between keywords and + identifiers. </p> + </item> + </list> + <p>The pragma effect is the same for both scope and basic + pragma rules. </p> + <p>When compiling, an IFR-identity + must be looked up several times but by storing identity aliases inside + the pragma table there this an increase in both speed and + flexibility. </p> + <p>Own Id: OTP-2128 <br></br> +</p> + </item> + <item> + <p>Code for interface inheritance registration for the IFR + registration code .</p> + <p>Inherited interfaces can now + be registered as a list of interface descriptions by + entering code for inherited interface registration under + new interface creation. This is achieved by correcting the + function reg2/6 and adding two more functions, + get_base_interfaces/2 and call_fun_str/2 </p> + <p>Own Id: + OTP-2134 <br></br> +</p> + </item> + <item> + <p>IFR registration checks for included IDL files.</p> + <p>All top level definitions (with respect to the scope) - + modules, interfaces, constants, types or exceptions - found + in an IDL file are either defined inside the compiled IDL + file or inside included files. + By having an extended registration of all top level + definitions it becomes possible to simply produce checks + for those included by the current IDL file. + A function call include_reg_test/1 is added in all + OE_* files that checks for IFR-registration on all included + IDL files. The code for that function is added inside the + OE_* file, while the function is called under OE_*:OE_register/0 + operation. </p> + <p>Own Id: OTP-2138 <br></br> +</p> + </item> + <item> + <p>Exception registration under IFR-operation creation.</p> + <p>By entering code for exception registration under operation + creation, the exceptions of an operation can be checked now. + This is done by correcting the function get_exceptions/4 + and adding two more functions, excdef/5 and get_EXC_ID/5 + ( the last two are cooperating with the first one and + all three are defined in the module "ictk" ). </p> + <p>Own Id: OTP-2102 <br></br> +</p> + </item> + <item> + <p>New back-end to IDL compiler : Plain Erlang.</p> + <p>The new back-end just translates IDL specifications + to Erlang module calls. No pragmas are allowed.</p> + <p>Own Id: OTP-2471 <br></br> +</p> + </item> + <item> + <p>New back-end to IDL compiler : generic server.</p> + <p>A new back-end that translates IDL specifications + to a standard OTP generic server.</p> + <p>Own Id: OTP-2482 <br></br> +</p> + </item> + <item> + <p>New back-end to IDL compiler : c client generation</p> + <p>A new back-end that translates IDL specifications + to a C API for accessing servers in Erlang. </p> + <p>Own Id: OTP-1511 <br></br> +</p> + </item> + <item> + <p>All records in generated files reveal own Erlang modules.</p> + <p>In Erlang related back-ends, every structure + which generates definition form is a record, + (such as union, struct, exception.... ). These records are + held in a generated Erlang files which + contain functions that reveal record information. <br></br> + + The Erlang file which contain these functions is + named after the scope of the record (similar + to the generated module and interface files). <br></br> + + Three functions are available :</p> + <list type="bulleted"> + <item> + <p>tc/0 - returns the record type code,</p> + </item> + <item> + <p>id/0 - returns the record id,</p> + </item> + <item> + <p>name - returns the record name.</p> + </item> + </list> + <p>Own Id: OTP-2473 <br></br> +</p> + </item> + <item> + <p>Changes in compiler usage and code generation.</p> + <list type="bulleted"> + <item> + <p>New compilation flags. + New flag be ( = back-end ) which is + used by the compiler to choose back-end. + Default back-end is set to erl_corba.</p> + </item> + <item> + <p>Stub files have an extra function oe_dependency/0 + indicating file dependency. This + helps the user to determine which IDL files should to + be compiled beside the compiled file. </p> + </item> + </list> + <p>Own Id: OTP-2474 <br></br> +</p> + </item> + <item> + <p>The IDL generation for CORBA is changed so standard gen_server return values can be used + from the implementation module. The change is compatible so that old values remain valid.</p> + <p>Own Id: OTP-2485 <br></br> +</p> + </item> + <item> + <p>It's now possible to generate an API to a CORBA object that accepts + timeout values in the calls in the same manner as gen_server. + The option to the compiler is "timeout".</p> + <p>Own Id: OTP-2487 <br></br> +</p> + </item> + </list> + </section> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Empty file generation problem is fixed. + When the IDL module definition did not contain + constant definitions, the generated stub file for that module + definition was empty. After checking the module body, + these files will not be generated anymore.</p> + </item> + </list> + </section> + + <section> + <title>Incompatibilities</title> + <list type="bulleted"> + <item> + <p>Changes in generated files.</p> + <p>Stub-files generated by the compiler had + prefix "OE_" and those used by Orber + had also a register/unregister function + called "OE_register"/"OE_unregister" and + a directive "OE_get_interface" passed + to the gen_server. + This made it difficult/irritating to use, + for example call to the register function + in Orber would appear as shown below:</p> + <list type="bulleted"> + <item> + <p>'OE_filename':'OE_register'().</p> + </item> + </list> + <p>This is changed by using the prefix "oe_" + instead for "OE_" for the above. + A registration call in Orber is now written:</p> + <list type="bulleted"> + <item> + <p>oe_filename:oe_register(). </p> + </item> + </list> + <p>Own Id: OTP-2440 <br></br> +</p> + </item> + </list> + </section> + </section> +</chapter> + diff --git a/lib/ic/doc/src/part.xml b/lib/ic/doc/src/part.xml new file mode 100644 index 0000000000..376a0b3455 --- /dev/null +++ b/lib/ic/doc/src/part.xml @@ -0,0 +1,45 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1998</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 User's Guide</title> + <prepared></prepared> + <docno></docno> + <date>1998-08-07</date> + <rev>2.1</rev> + </header> + <description> + <p>The <em>IC</em> application is an Erlang implementation of an IDL + compiler.</p> + </description> + <xi:include href="ch_introduction.xml"/> + <xi:include href="ch_basic_idl.xml"/> + <xi:include href="ch_ic_protocol.xml"/> + <xi:include href="ch_erl_plain.xml"/> + <xi:include href="ch_erl_genserv.xml"/> + <xi:include href="ch_c_mapping.xml"/> + <xi:include href="ch_c_client.xml"/> + <xi:include href="ch_c_server.xml"/> + <xi:include href="ch_c_corba_env.xml"/> + <xi:include href="ch_java.xml"/> +</part> + diff --git a/lib/ic/doc/src/part_notes.xml b/lib/ic/doc/src/part_notes.xml new file mode 100644 index 0000000000..0aac643c7d --- /dev/null +++ b/lib/ic/doc/src/part_notes.xml @@ -0,0 +1,37 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1998</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>Idl Compiler Release Notes</title> + <prepared></prepared> + <docno></docno> + <date>1998-05-06</date> + <rev>2.1</rev> + </header> + <description> + <p>The IDL + Compiler Application is an Erlang implementation of a compiler for the IDL language. + </p> + </description> + <xi:include href="notes.xml"/> +</part> + diff --git a/lib/ic/doc/src/ref_man.gif b/lib/ic/doc/src/ref_man.gif Binary files differnew file mode 100644 index 0000000000..b13c4efd53 --- /dev/null +++ b/lib/ic/doc/src/ref_man.gif diff --git a/lib/ic/doc/src/ref_man.xml b/lib/ic/doc/src/ref_man.xml new file mode 100644 index 0000000000..153b25c609 --- /dev/null +++ b/lib/ic/doc/src/ref_man.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>1998</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 Reference Manual</title> + <prepared></prepared> + <docno></docno> + <date>2003-12-16</date> + <rev>PB1</rev> + </header> + <description> + <p>The <em>IC</em> application is an Erlang implementation of an IDL + compiler.</p> + </description> + <xi:include href="ic.xml"/> + <xi:include href="ic_clib.xml"/> + <xi:include href="ic_c_protocol.xml"/> +</application> + diff --git a/lib/ic/doc/src/summary.html.src b/lib/ic/doc/src/summary.html.src new file mode 100644 index 0000000000..cb92e51791 --- /dev/null +++ b/lib/ic/doc/src/summary.html.src @@ -0,0 +1 @@ +IDL compiler diff --git a/lib/ic/doc/src/user_guide.gif b/lib/ic/doc/src/user_guide.gif Binary files differnew file mode 100644 index 0000000000..e6275a803d --- /dev/null +++ b/lib/ic/doc/src/user_guide.gif |
