diff options
Diffstat (limited to 'lib/ic/doc/src')
| -rw-r--r-- | lib/ic/doc/src/CORBA_Environment_alloc.xml | 143 | ||||
| -rw-r--r-- | lib/ic/doc/src/Makefile | 227 | ||||
| -rw-r--r-- | lib/ic/doc/src/book.xml | 50 | ||||
| -rw-r--r-- | lib/ic/doc/src/c-part.xml | 39 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_basic_idl.xml | 164 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_c_client.xml | 150 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_c_corba_env.xml | 386 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_c_mapping.xml | 893 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_c_server.xml | 149 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_erl_genserv.xml | 206 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_erl_plain.xml | 176 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_ic_protocol.xml | 234 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_introduction.xml | 149 | ||||
| -rw-r--r-- | lib/ic/doc/src/ch_java.xml | 738 | ||||
| -rw-r--r-- | lib/ic/doc/src/erl-part.xml | 37 | ||||
| -rw-r--r-- | lib/ic/doc/src/ic.xml | 468 | ||||
| -rw-r--r-- | lib/ic/doc/src/ic_c_protocol.xml | 157 | ||||
| -rw-r--r-- | lib/ic/doc/src/ic_clib.xml | 247 | ||||
| -rw-r--r-- | lib/ic/doc/src/java-part.xml | 36 | ||||
| -rw-r--r-- | lib/ic/doc/src/notes.xml | 844 | ||||
| -rw-r--r-- | lib/ic/doc/src/part.xml | 46 | ||||
| -rw-r--r-- | lib/ic/doc/src/ref_man.xml | 39 |
22 files changed, 0 insertions, 5578 deletions
diff --git a/lib/ic/doc/src/CORBA_Environment_alloc.xml b/lib/ic/doc/src/CORBA_Environment_alloc.xml deleted file mode 100644 index 357d9c2e8a..0000000000 --- a/lib/ic/doc/src/CORBA_Environment_alloc.xml +++ /dev/null @@ -1,143 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index 118f42b605..0000000000 --- a/lib/ic/doc/src/Makefile +++ /dev/null @@ -1,227 +0,0 @@ -# -# %CopyrightBegin% -# -# Copyright Ericsson AB 1998-2017. All Rights Reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions 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 - -# ---------------------------------------------------- -# 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 - -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 - -XML_FILES = $(BOOK_FILES) $(XML_APPLICATION_FILES) $(XML_REF3_FILES) \ - $(XML_PART_FILES) $(XML_CHAPTER_FILES) - -GIF_FILES = - -# ---------------------------------------------------- - -HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ - $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) - -INFO_FILE = ../../info -EXTRA_FILES = \ - $(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) - -HTML_REF_MAN_FILE = $(HTMLDIR)/index.html - -TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf - -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) -JAVA_OUT_DIR = ../html/java - -JD_PACK_HTML_FILES = \ - package-frame.html \ - package-summary.html \ - package-tree.html - -JAVADOC_PACK_HTML_FILES = \ - $(JAVA_SOURCE_FILES:%.java=$(JAVA_OUT_DIR)/$(PACK_DIR)/%.html) \ - $(JD_PACK_HTML_FILES:%=$(JAVA_OUT_DIR)/$(PACK_DIR)/%) - -JAVADOC_INDEX_HTML_FILES = $(JD_INDEX_HTML_FILES:%=$(JAVA_OUT_DIR)/%) - -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) $< $@ - -ifneq (,$(JAVA)) -docs: pdf html man $(JAVADOC_GENERATED_FILES) -else -docs: pdf html man -endif - -$(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 *~ - -$(JAVADOC_GENERATED_FILES): JAVADOC-GENERATED - -JAVADOC-GENERATED: $(JAVA_SOURCE_FILES:%=$(JAVA_SOURCE_DIR)/%) - @(cd ../../java_src; $(JAVADOC) $(JAVADOCFLAGS) com.ericsson.otp.ic) - >JAVADOC-GENERATED - -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 - -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" - ($(CP) -rf $(HTMLDIR) "$(RELSYSDIR)/doc") - $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3" - $(INSTALL_DATA) $(MAN3_FILES) "$(RELEASE_PATH)/man/man3" - -release_spec: diff --git a/lib/ic/doc/src/book.xml b/lib/ic/doc/src/book.xml deleted file mode 100644 index f6ef824f63..0000000000 --- a/lib/ic/doc/src/book.xml +++ /dev/null @@ -1,50 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE book SYSTEM "book.dtd"> - -<book xmlns:xi="http://www.w3.org/2001/XInclude"> - <header titlestyle="normal"> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index 968dd3135f..0000000000 --- a/lib/ic/doc/src/c-part.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2002</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </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 deleted file mode 100644 index 485a0c44e5..0000000000 --- a/lib/ic/doc/src/ch_basic_idl.xml +++ /dev/null @@ -1,164 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2002</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index e304c8acf4..0000000000 --- a/lib/ic/doc/src/ch_c_client.xml +++ /dev/null @@ -1,150 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index 1bd829307e..0000000000 --- a/lib/ic/doc/src/ch_c_corba_env.xml +++ /dev/null @@ -1,386 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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"> - 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 deleted file mode 100644 index 1ea0ace91f..0000000000 --- a/lib/ic/doc/src/ch_c_mapping.xml +++ /dev/null @@ -1,893 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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[ - module erlang - { - - .... - - // an erlang binary - typedef sequence<octet> binary; - - }; - ]]></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"> - typedef struct { - CORBA_unsigned_long _maximum; - CORBA_unsigned_long _length; - CORBA_octet* _buffer; - } 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 its - 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 deleted file mode 100644 index df25927c90..0000000000 --- a/lib/ic/doc/src/ch_c_server.xml +++ /dev/null @@ -1,149 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index aa162b3652..0000000000 --- a/lib/ic/doc/src/ch_erl_genserv.xml +++ /dev/null @@ -1,206 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 - {'EXIT',_} -> - {stop, normal, "random:uniform/0 - EXIT", State}; - RUnif -> - {reply, RUnif, State} - end. - - -init(State, S1, S2, S3) -> - case catch random:seed(S1, S2, S3) of - {'EXIT',_} -> - {stop, normal, State}; - _ -> - {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 deleted file mode 100644 index 27387d1624..0000000000 --- a/lib/ic/doc/src/ch_erl_plain.xml +++ /dev/null @@ -1,176 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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"> - -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 deleted file mode 100644 index cb64500f6e..0000000000 --- a/lib/ic/doc/src/ch_ic_protocol.xml +++ /dev/null @@ -1,234 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2003</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>IC Protocol</title> - <prepared></prepared> - <docno></docno> - <date>2003-12-11</date> - <rev>PA1</rev> - <file>ch_ic_protocol.xml</file> - </header> - <p>The purpose of this chapter is to explain the bits and bytes of the - IC protocol, which is a composition of the Erlang distribution protocol - and the Erlang/OTP gen_server protocol. If you do not intend to replace - the Erlang distribution protocol, or replace the gen_server protocol, - skip over this chapter. - </p> - - <section> - <title>Introduction</title> - <p>The IDL Compiler (IC) transforms Interface Definition Language - (IDL) specifications files to interface code for Erlang, C, and - Java. The Erlang language mapping is described in the Orber - documentation, while the other mappings are described in the IC - documentation (they are of course in accordance with the CORBA C - and Java language mapping specifications, with some restrictions). - </p> - <p>The most important parts of an IDL specification are the operation - declarations. An operation defines what information a client - provides to a server, and what information (if any) the client - gets back from the server. We consider IDL operations and language - mappings in section 2. - </p> - <p>What we here call the IC protocol, is the description of messages - exchanged between IC end-points (client and servers). It is valid - for all IC back-ends, except the 'erl_plain' and 'erl_corba' - back-ends. - The IC protocol is in turn embedded into the Erlang gen_server - protocol, which is described below. - Finally, the gen_server protocol is embedded in the Erlang - distribution protocol. Pertinent parts of that protocol is - described further below. - </p> - </section> - - <section> - <title>Language mappings and IDL operations</title> - - <section> - <title>IDL Operations</title> - <p>An IDL operation is declared as follows:</p> - <code type="none"> - [oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN, - out OType1 O1, out OType2 O2, ..., out OTypeM OM) - N, M = 0, 1, 2, ... (2.1.1) - </code> - <p>`Op' is the operation name, RetType is the return type, and ITypei, - i = 1, 2, ..., N, and OTypej, j = 1, 2, ..., M, are the `in' types - and `out' types, respectively. The values I1, I2, ..., IN are - provided by the caller, and the value of RetType, and the values - O1, O2, ..., OM, are provided as results to the caller. - </p> - <p>The types can be any basic types or derived types declared in the - IDL specification of which the operation declaration is a part. - </p> - <p>If the RetType has the special name `void' there is no return - value (but there might still be result values O1, 02, ..., OM). - </p> - <p>The `in' and `out' parameters can be declared in any order, but - for clarity we have listed all `in' parameters before the `out' - parameters in the declaration above. - </p> - <p>If the keyword `oneway' is present, the operation is a cast, i.e. - there is no confirmation of the operation, and consequently there - must be no result values: RetType must be equal to `void', and M = - 0 must hold. - </p> - <p>Otherwise the operation is a call, i.e. it is confirmed (or else - an exception is raised). - </p> - <p>Note carefully that an operation declared without `oneway' is - always a call, even if RetType is `void' and M = 0. - </p> - </section> - - <section> - <title>Language Mappings</title> - <p>There are several CORBA Language Mapping specifications. These are - about mapping interfaces to various programming languages. IC - supports the CORBA C and Java mapping specifications, and the - Erlang language mapping specified in the Orber documentation. - </p> - <p>Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide: - </p> - <list type="bulleted"> - <item> - <p>Functions with return type void will return the atom ok.</p> - </item> - </list> - <p>Excerpt from "6.13 Invocations of Operations" in the Orber User's - Guide: - </p> - <list type="bulleted"> - <item> - <p>A function call will invoke an operation. The first parameter - of the function should be the object reference and then all in - and inout parameters follow in the same order as specified in - the IDL specification. The result will be a return value - unless the function has inout or out parameters specified; in - which case, a tuple of the return value, followed by the - parameters will be returned.</p> - </item> - </list> - <p>Hence the function that is mapped from an IDL operation to Erlang - always have a return value (an Erlang function always has). That - fact has influenced the IC protocol, in that there is always a - return value (which is 'ok' if the return type was declared 'void'). </p> - </section> - </section> - - <section> - <title>IC Protocol</title> - <p>Given the operation declaration (2.1.1) the IC protocol maps to - messages as follows, defined in terms of Erlang terms. - </p> - - <section> - <title>Call (Request/Reply, i.e. not oneway)</title> - <code type="none"> - request: Op atom() N = 0 - {Op, I1, I2, ..., IN} tuple() N > 0 - (3.1.1) - - reply: Ret M = 0 - {Ret, O1, O2, ..., OM} M > 0 - (3.1.2)</code> - <p><em>Notice:</em> Even if the RetType of the operation Op is - declared to be 'void', a return value 'ok' is returned in - the reply message. That - return value is of no significance, and is therefore ignored (note - however that a C server back-end returns the atom 'void' instead - of 'ok'). - </p> - </section> - - <section> - <title>Cast (oneway)</title> - <code type="none"> - - notification: Op atom() N = 0 - {Op, I1, I2, ..., IN} tuple() N > 0 - (3.2.1)</code> - <p>(There is of course no return message). - </p> - </section> - </section> - - <section> - <title>Gen_server Protocol</title> - <p>Most of the IC generated code deals with encoding and decoding the - gen_server protocol. - </p> - - <section> - <title>Call</title> - <code type="none"> - - request: {'$gen_call', {self(), Ref}, Request} (4.1.1) - - reply: {Ref, Reply} (4.1.2)</code> - <p>where Request and Reply are the messages defined in the previous - chapter. - </p> - </section> - - <section> - <title>Cast</title> - <code type="none"> - notification: {'$gen_cast', Notification} (4.2.1) </code> - <p>where Notification is the message defined in the previous chapter. - </p> - </section> - </section> - - <section> - <title>Erlang Distribution Protocol</title> - <p>Messages (of interest here) between Erlang nodes are of the form: </p> - <code type="none"> - Len(4), Type(1), CtrlBin(N), MsgBin(M) (5.1) </code> - <p>Type is equal to 112 = PASS_THROUGH. - </p> - <p>CtrlBin and MsgBin are Erlang terms in binary form (as if created - by term_to_binary/1), whence for each of them the first byte is - equal to 131 = VERSION_MAGIC. - </p> - <p>CtrlBin (of interest here) contains the SEND and REG_SEND control - messages, which are binary forms of the Erlang terms</p> - <code type="none"> - {2, Cookie, ToPid} , (5.2) </code> - <p>and</p> - <code type="none"> - {6, FromPid, Cookie, ToName} , (5.3) </code> - <p>respectively. - </p> - <p>The CtrlBin(N) message is read and written by erl_interface code - (C), j_interface code (Java), or the Erlang distribution - implementation, which are invoked from IC generated code. - </p> - <p>The MsgBin(N) is the "real" message, i.e. of the form described - in the previous section. - </p> - </section> -</chapter> - diff --git a/lib/ic/doc/src/ch_introduction.xml b/lib/ic/doc/src/ch_introduction.xml deleted file mode 100644 index 9ac2f96a95..0000000000 --- a/lib/ic/doc/src/ch_introduction.xml +++ /dev/null @@ -1,149 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index a733adaf65..0000000000 --- a/lib/ic/doc/src/ch_java.xml +++ /dev/null @@ -1,738 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1999</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 { - : - : - }; - - public static void marshal(OtpOutputStream out, s value) - throws java.lang.Exception { - : - : - }; - -}; - </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 deleted file mode 100644 index 9c9cb6a574..0000000000 --- a/lib/ic/doc/src/erl-part.xml +++ /dev/null @@ -1,37 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2002</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </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/ic.xml b/lib/ic/doc/src/ic.xml deleted file mode 100644 index 98e8414a4e..0000000000 --- a/lib/ic/doc/src/ic.xml +++ /dev/null @@ -1,468 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1997</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </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 deleted file mode 100644 index ed4f21d661..0000000000 --- a/lib/ic/doc/src/ic_c_protocol.xml +++ /dev/null @@ -1,157 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>2004</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </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 deleted file mode 100644 index 50b20d2ca8..0000000000 --- a/lib/ic/doc/src/ic_clib.xml +++ /dev/null @@ -1,247 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE cref SYSTEM "cref.dtd"> - -<cref> - <header> - <copyright> - <year>2003</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index 14b58a1df5..0000000000 --- a/lib/ic/doc/src/java-part.xml +++ /dev/null @@ -1,36 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2002</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </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/notes.xml b/lib/ic/doc/src/notes.xml deleted file mode 100644 index 217f7ab740..0000000000 --- a/lib/ic/doc/src/notes.xml +++ /dev/null @@ -1,844 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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.4.4.2</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fixed potential buffer overflow bugs in - oe_ei_encode_long/ulong/longlong/ulonglong functions on - 64-bit architectures. These functions expect 32 bit - integers as the IDL type "long" is defined as 32 bits. - But there is nothing preventing user code from "breaking" - the interface and pass larger values on 64-bit - architectures where the C type "long" is 64 bits.</p> - <p> - Own Id: OTP-15179 Aux Id: ERIERL-208 </p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4.4.1</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fixed bug in <c>ic</c> causing potential buffer overrun - in funtion <c>oe_ei_encode_atom</c>. Bug exists since - ic-4.4.4 (OTP-20.3.4).</p> - <p> - Own Id: OTP-15160 Aux Id: ERIERL-191 </p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4.4</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Optimize encoding/decoding for pure 7-bit ascii atoms.</p> - <p> - Own Id: OTP-15023 Aux Id: ERIERL-150 </p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4.3</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> Removed all old unused files in the documentation. - </p> - <p> - Own Id: OTP-14475 Aux Id: ERL-409, PR-1493 </p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4.2</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> Correct bugs when path to mib or idl spec files - contains UTF-8 characters. </p> - <p> - Own Id: OTP-13718 Aux Id: ERL-179 </p> - </item> - <item> - <p> - Update build scripts to not make assumtions about where - env, cp and perl are located.</p> - <p> - Own Id: OTP-13800</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4.1</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Internal changes</p> - <p> - Own Id: OTP-13551</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.4</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Change license text from Erlang Public License to Apache - Public License v2</p> - <p> - Own Id: OTP-12845</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.6</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fix compiler warnings reported by LLVM</p> - <p> - Own Id: OTP-12138</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.5</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> Added Latin-1 code directive in the generated files - to keep old behaviour. Updated IC so it can handle - Unicode characters in the path. </p> - <p> - Own Id: OTP-11783</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.4</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fix two small silent rules omissions. Thanks to Anthony - Ramine.</p> - <p> - Own Id: OTP-11351</p> - </item> - <item> - <p> - Silence warnings (Thanks to Anthony Ramine)</p> - <p> - Own Id: OTP-11517</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.3</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Header and library files from ic and erl_interface are - now installed into usr/{include,lib}. Note that these - directories are unversioned, so the latest installed - version will be the one in the directory.</p> - <p> - Own Id: OTP-11284</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.2</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fixed some compilation warnings on miscellaneous - platforms. Thanks to Anthony Ramine.</p> - <p> - Own Id: OTP-11086</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3.1</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Revert the structs <c>erlang_pid</c>, <c>erlang_port</c> - and <c>erlang_ref</c> as they were before R16A (without - <c>node_org_enc</c>) in order to be backward compatible - with user code that accesses the fields of these structs.</p> - <p> - Own Id: OTP-10885 Aux Id: seq12256 </p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.3</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Misc build updates</p> - <p> - Own Id: OTP-10784</p> - </item> - <item> - <p> - Adapt ic for changes in erl_interface and jinterface due - to utf8 atom support. This change makes ic dependent on - erl_interface-3.7.10 (R16) or later in order to build.</p> - <p> - Own Id: OTP-10785</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.2.31</title> - - <section><title>Fixed Bugs and Malfunctions</title> - <list> - <item> - <p> - Fix bug where the ic pre-processor would ignore - whitespace quoting.</p> - <p> - Own Id: OTP-10109</p> - </item> - <item> - <p> A bug regarding spaces in C function prototypes has - been fixed. (Thanks to Richard O'Keefe.) </p> - <p> - Own Id: OTP-10138</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.2.30</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p> - Add generation of Erlang callback functions to generated - Erlang source code to avoid compiler warnings.</p> - <p> - Own Id: OTP-9998</p> - </item> - </list> - </section> - -</section> - -<section><title>IC 4.2.29</title> - - <section><title>Improvements and New Features</title> - <list> - <item> - <p>Erlang/OTP can now be built using parallel make if you - limit the number of jobs, for instance using '<c>make - -j6</c>' or '<c>make -j10</c>'. '<c>make -j</c>' does not - work at the moment because of some missing - dependencies.</p> - <p> - Own Id: OTP-9451</p> - </item> - </list> - </section> - -</section> - -<section> - <title>IC 4.2.28</title> - - <section> - <title>Fixed Bugs and Malfunctions</title> - <list type="bulleted"> - <item> - <p> - Incorrect use of ets:match changed to ets:match_object.</p> - <p> - Own Id: OTP-9630 </p> - </item> - </list> - </section> - </section> - - <section> - <title>IC 4.2.27</title> - - <section> - <title>Improvements and New Features</title> - <list type="bulleted"> - <item> - <p> - Reduced compile overhead (Thanks to Haitao Li).</p> - <p> - Own Id: OTP-9460 </p> - </item> - </list> - </section> - </section> - - <section> - <title>IC 4.2.26</title> - - <section> - <title>Improvements and New Features</title> - <list type="bulleted"> - <item> - <p> - Partial support for recursive structs and unions. Only available - for the erl_corba backend and requires that Light IFR is used. - I.e. the IC option {light_ifr, true} and that Orber is configured - in such a way that Light IFR is activated. Recursive TypeCode is - currently not supported.</p> - <p> - Own Id: OTP-8868 Aux Id: seq11633</p> - </item> - </list> - </section> - </section> - - <section> - <title>IC 4.2.25</title> - - <section> - <title>Improvements and New Features</title> - <list type="bulleted"> - <item> - <p> - The documentation can now be built and installed without Java.</p> - <p> - Own Id: OTP-8639 Aux Id:</p> - </item> - </list> - </section> - </section> - - <section> - <title>IC 4.2.24</title> - - <section> - <title>Fixed Bugs and Malfunctions</title> - <list type="bulleted"> - <item> - <p>Removed superfluous VT in the documentation.</p> - <p>Own id: OTP-8353 Aux Id:</p> - </item> - <item> - <p>The option c_timeout was not correctly documented.</p> - <p>Own id: OTP-8307 Aux Id: seq11390</p> - </item> - <item> - <p>Removed superfluous backslash in the documentation.</p> - <p>Own id: OTP-8354 Aux Id:</p> - </item> - <item> - <p>The documentation EIX file was not generated.</p> - <p>Own id: OTP-8355 Aux Id:</p> - </item> - </list> - </section> - </section> - - <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/part.xml b/lib/ic/doc/src/part.xml deleted file mode 100644 index 0bb7858745..0000000000 --- a/lib/ic/doc/src/part.xml +++ /dev/null @@ -1,46 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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/ref_man.xml b/lib/ic/doc/src/ref_man.xml deleted file mode 100644 index a6a4f187b3..0000000000 --- a/lib/ic/doc/src/ref_man.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE application SYSTEM "application.dtd"> - -<application xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>1998</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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> - |