From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/ic/doc/html/.gitignore | 0 lib/ic/doc/man1/.gitignore | 0 lib/ic/doc/man3/.gitignore | 0 lib/ic/doc/pdf/.gitignore | 0 lib/ic/doc/src/CORBA_Environment_alloc.xml | 142 +++ lib/ic/doc/src/Makefile | 320 ++++++ lib/ic/doc/src/book.gif | Bin 0 -> 1081 bytes lib/ic/doc/src/book.xml | 49 + lib/ic/doc/src/c-part.xml | 40 + lib/ic/doc/src/ch_basic_idl.xml | 163 +++ lib/ic/doc/src/ch_c_client.xml | 149 +++ lib/ic/doc/src/ch_c_corba_env.xml | 385 +++++++ lib/ic/doc/src/ch_c_mapping.xml | 892 ++++++++++++++++ lib/ic/doc/src/ch_c_server.xml | 148 +++ lib/ic/doc/src/ch_erl_genserv.xml | 205 ++++ lib/ic/doc/src/ch_erl_plain.xml | 175 ++++ lib/ic/doc/src/ch_ic_protocol.xml | 233 +++++ lib/ic/doc/src/ch_introduction.xml | 148 +++ lib/ic/doc/src/ch_java.xml | 737 +++++++++++++ lib/ic/doc/src/erl-part.xml | 38 + lib/ic/doc/src/fascicules.xml | 18 + lib/ic/doc/src/ic.gif | Bin 0 -> 17015 bytes lib/ic/doc/src/ic.xml | 469 +++++++++ lib/ic/doc/src/ic_c_protocol.xml | 158 +++ lib/ic/doc/src/ic_clib.xml | 246 +++++ lib/ic/doc/src/java-part.xml | 37 + lib/ic/doc/src/make.dep | 24 + lib/ic/doc/src/notes.gif | Bin 0 -> 2005 bytes lib/ic/doc/src/notes.xml | 444 ++++++++ lib/ic/doc/src/old_notes.xml | 1565 ++++++++++++++++++++++++++++ lib/ic/doc/src/part.xml | 45 + lib/ic/doc/src/part_notes.xml | 37 + lib/ic/doc/src/ref_man.gif | Bin 0 -> 1530 bytes lib/ic/doc/src/ref_man.xml | 38 + lib/ic/doc/src/summary.html.src | 1 + lib/ic/doc/src/user_guide.gif | Bin 0 -> 1581 bytes 36 files changed, 6906 insertions(+) create mode 100644 lib/ic/doc/html/.gitignore create mode 100644 lib/ic/doc/man1/.gitignore create mode 100644 lib/ic/doc/man3/.gitignore create mode 100644 lib/ic/doc/pdf/.gitignore create mode 100644 lib/ic/doc/src/CORBA_Environment_alloc.xml create mode 100644 lib/ic/doc/src/Makefile create mode 100644 lib/ic/doc/src/book.gif create mode 100644 lib/ic/doc/src/book.xml create mode 100644 lib/ic/doc/src/c-part.xml create mode 100644 lib/ic/doc/src/ch_basic_idl.xml create mode 100644 lib/ic/doc/src/ch_c_client.xml create mode 100644 lib/ic/doc/src/ch_c_corba_env.xml create mode 100644 lib/ic/doc/src/ch_c_mapping.xml create mode 100644 lib/ic/doc/src/ch_c_server.xml create mode 100644 lib/ic/doc/src/ch_erl_genserv.xml create mode 100644 lib/ic/doc/src/ch_erl_plain.xml create mode 100644 lib/ic/doc/src/ch_ic_protocol.xml create mode 100644 lib/ic/doc/src/ch_introduction.xml create mode 100644 lib/ic/doc/src/ch_java.xml create mode 100644 lib/ic/doc/src/erl-part.xml create mode 100644 lib/ic/doc/src/fascicules.xml create mode 100644 lib/ic/doc/src/ic.gif create mode 100644 lib/ic/doc/src/ic.xml create mode 100644 lib/ic/doc/src/ic_c_protocol.xml create mode 100644 lib/ic/doc/src/ic_clib.xml create mode 100644 lib/ic/doc/src/java-part.xml create mode 100644 lib/ic/doc/src/make.dep create mode 100644 lib/ic/doc/src/notes.gif create mode 100644 lib/ic/doc/src/notes.xml create mode 100644 lib/ic/doc/src/old_notes.xml create mode 100644 lib/ic/doc/src/part.xml create mode 100644 lib/ic/doc/src/part_notes.xml create mode 100644 lib/ic/doc/src/ref_man.gif create mode 100644 lib/ic/doc/src/ref_man.xml create mode 100644 lib/ic/doc/src/summary.html.src create mode 100644 lib/ic/doc/src/user_guide.gif (limited to 'lib/ic/doc') diff --git a/lib/ic/doc/html/.gitignore b/lib/ic/doc/html/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/ic/doc/man1/.gitignore b/lib/ic/doc/man1/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/ic/doc/man3/.gitignore b/lib/ic/doc/man3/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/ic/doc/pdf/.gitignore b/lib/ic/doc/pdf/.gitignore new file mode 100644 index 0000000000..e69de29bb2 diff --git a/lib/ic/doc/src/CORBA_Environment_alloc.xml b/lib/ic/doc/src/CORBA_Environment_alloc.xml new file mode 100644 index 0000000000..909379d6dc --- /dev/null +++ b/lib/ic/doc/src/CORBA_Environment_alloc.xml @@ -0,0 +1,142 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CORBA_Environment_alloc + + + + 1998-12-01 + A +
+ CORBA_Environment_alloc + Allocation function for the CORBA_Environement struct + +

The CORBA_Environment_alloc() function is the + function used to allocate and initiate the CORBA_Environment + structure.

+ + + + CORBA_Environment *CORBA_Environment_alloc(inbufsz, outbufsz) + Initialize communication + + int inbufsz; + int outbufsz; + + +

This function is used to create and initiate the CORBA_Environment + structure. In particular, it is used to dynamically allocate a CORBA_Environment + structure and set the default values for the structure's fields.

+

inbufsize is the wished size of input buffer.

+

outbufsize is the wished size of output buffer.

+

CORBA_Environment is the CORBA 2.0 state structure used by the + generated stub.

+

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.

+

To free the space allocated by CORBA_Environment_alloc/2 :

+ + +

First call CORBA_free for the input and output buffers.

+ + +

After freeing the buffer space, call CORBA_free for the CORBA_Environment space.

+ + + + + + +
+ The CORBA_Environment structure +

Here is the complete definition of the CORBA_Environment structure, + defined in file ic.h :

+ +/* 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; + + +

Remember to set the field values _fd , _regname , *_to_pid and/or + *_from_pid to the appropriate application values. These are not automatically + set by the stubs.

+ + +

Never assign static buffers to the buffer pointers, never set the _memchunk field to + a value less than 32.

+ +
+ +
+ SEE ALSO +

ic(3)

+
+ + + + diff --git a/lib/ic/doc/src/Makefile b/lib/ic/doc/src/Makefile new file mode 100644 index 0000000000..fff930d745 --- /dev/null +++ b/lib/ic/doc/src/Makefile @@ -0,0 +1,320 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1998-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(IC_VSN) +APPLICATION=ic +# ---------------------------------------------------- +# Include dependency +# ---------------------------------------------------- + +ifndef DOCSUPPORT +include make.dep +endif + +# ---------------------------------------------------- +# Java specific +# ---------------------------------------------------- +JAVADOC=javadoc +JAVA_INCL_ROOT = $(ERL_TOP)/lib/jinterface/priv/ +JAVA_SRC_ROOT = $(ERL_TOP)/lib/ic/java_src/ +JAVA_CLASS_SUBDIR = com/ericsson/otp/ic/ + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = ic.xml \ + ic_clib.xml \ + ic_c_protocol.xml + +XML_PART_FILES = part.xml \ + part_notes.xml + +XML_CHAPTER_FILES = \ + ch_introduction.xml \ + ch_basic_idl.xml \ + ch_ic_protocol.xml \ + ch_erl_plain.xml \ + ch_erl_genserv.xml \ + ch_c_mapping.xml \ + ch_c_client.xml \ + ch_c_server.xml \ + ch_c_corba_env.xml \ + ch_java.xml \ + notes.xml + +BOOK_FILES = book.xml + +GIF_FILES = \ + book.gif \ + notes.gif \ + ref_man.gif \ + user_guide.gif + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info +EXTRA_FILES = summary.html.src \ + $(DEFAULT_GIF_FILES) \ + $(DEFAULT_HTML_FILES) \ + $(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html) + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +ifdef DOCSUPPORT + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +else + +TEX_FILES_BOOK = \ + $(BOOK_FILES:%.xml=%.tex) +TEX_FILES_REF_MAN = $(XML_REF3_FILES:%.xml=%.tex) \ + $(XML_APPLICATION_FILES:%.xml=%.tex) +TEX_FILES_USERS_GUIDE = \ + $(XML_CHAPTER_FILES:%.xml=%.tex) + +TOP_PDF_FILE = $(APPLICATION)-$(VSN).pdf +TOP_PS_FILE = $(APPLICATION)-$(VSN).ps + +$(TOP_PDF_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< | $(DISTILL) $(DISTILL_FLAGS) > $@ + +$(TOP_PS_FILE): book.dvi ../../vsn.mk + $(DVI2PS) $(DVIPS_FLAGS) -f $< > $@ + +endif + +JAVA_SOURCE_FILES = \ + Holder.java \ + BooleanHolder.java \ + ByteHolder.java \ + CharHolder.java \ + DoubleHolder.java \ + FloatHolder.java \ + IntHolder.java \ + LongHolder.java \ + ShortHolder.java \ + StringHolder.java \ + Environment.java \ + Any.java \ + AnyHelper.java \ + AnyHolder.java \ + TypeCode.java \ + TCKind.java \ + Pid.java \ + PidHolder.java \ + PidHelper.java \ + Ref.java \ + RefHolder.java \ + RefHelper.java \ + Port.java \ + PortHolder.java \ + PortHelper.java \ + Term.java \ + TermHolder.java \ + TermHelper.java + + +JD_INDEX_HTML_FILES = \ + allclasses-frame.html \ + allclasses-noframe.html \ + deprecated-list.html \ + index-all.html \ + overview-tree.html \ + stylesheet.css \ + help-doc.html \ + index.html \ + package-list \ + serialized-form.html \ + constant-values.html + +JD_GIF_FILES = \ + ../html/java/resources/inherit.gif + + +PACK_DIR = com/ericsson/otp/ic +JAVA_SOURCE_DIR = ../../java_src/$(PACK_DIR) + +JD_PACK_HTML_FILES = \ + package-frame.html \ + package-summary.html \ + package-tree.html + +JAVADOC_PACK_HTML_FILES = \ + $(JAVA_SOURCE_FILES:%.java=../html/java/$(PACK_DIR)/%.html) \ + $(JD_PACK_HTML_FILES:%=../html/java/$(PACK_DIR)/%) + +JAVADOC_INDEX_HTML_FILES = $(JD_INDEX_HTML_FILES:%=../html/java/%) + +JAVADOC_GENERATED_FILES = $(JAVADOC_PACK_HTML_FILES) $(JAVADOC_INDEX_HTML_FILES) + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +CLASSPATH = $(JAVA_SRC_ROOT):$(JAVA_INCL_ROOT) + +XML_FLAGS += +DVIPS_FLAGS += +JAVADOCFLAGS = \ + -classpath $(CLASSPATH) \ + -d ../doc/html/java \ + -windowtitle "Package com.ericsson.otp.ic version $(IC_VSN)" \ + -public \ + -footer "
Copyright © 1991-2007 Ericsson AB
" + + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +ifdef DOCSUPPORT + +docs: pdf html man $(JAVADOC_GENERATED_FILES) + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +else + +ifeq ($(DOCTYPE),pdf) +docs: pdf +else +ifeq ($(DOCTYPE),ps) +docs: ps +else +docs: html $(JAVADOC_GENERATED_FILES) gifs man +endif +endif + +pdf: $(TOP_PDF_FILE) + +ps: $(TOP_PS_FILE) + +html: $(HTML_FILES) + +clean clean_docs clean_tex: + rm -f $(TEX_FILES_USERS_GUIDE) $(TEX_FILES_REF_MAN) $(TEX_FILES_BOOK) + rm -f $(HTML_FILES) $(MAN3_FILES) + rm -f $(TOP_PDF_FILE) $(TOP_PS_FILE) + rm -f errs core *~ *xmls_output *xmls_errs $(LATEX_CLEAN) + rm -rf ../html/java/* + +endif + +$(JAVADOC_GENERATED_FILES): + @(cd ../../java_src; $(JAVADOC) $(JAVADOCFLAGS) com.ericsson.otp.ic) + +man: $(MAN3_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +$(INDEX_TARGET): $(INDEX_SRC) ../../vsn.mk + sed -e 's;%VSN%;$(VSN);' $< > $@ + +debug opt: + + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +ifdef DOCSUPPORT + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + (/bin/cp -rf $(HTMLDIR) $(RELSYSDIR)/doc) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + +else + +ifeq ($(DOCTYPE),pdf) +release_docs_spec: pdf + $(INSTALL_DIR) $(RELEASE_PATH)/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELEASE_PATH)/pdf +else +ifeq ($(DOCTYPE),ps) +release_docs_spec: ps + $(INSTALL_DIR) $(RELEASE_PATH)/ps + $(INSTALL_DATA) $(TOP_PS_FILE) $(RELEASE_PATH)/ps +else +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(GIF_FILES) $(EXTRA_FILES) $(HTML_FILES) \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/resources + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson/otp + $(INSTALL_DIR) $(RELSYSDIR)/doc/html/java/com/ericsson/otp/ic + $(INSTALL_DATA) $(JAVADOC_INDEX_HTML_FILES) \ + $(RELSYSDIR)/doc/html/java + $(INSTALL_DATA) $(JD_GIF_FILES) \ + $(RELSYSDIR)/doc/html/java/resources + $(INSTALL_DATA) $(JAVADOC_PACK_HTML_FILES) \ + $(RELSYSDIR)/doc/html/java/com/ericsson/otp/ic + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3_FILES) $(RELEASE_PATH)/man/man3 + +endif +endif + +endif + + +release_spec: + + diff --git a/lib/ic/doc/src/book.gif b/lib/ic/doc/src/book.gif new file mode 100644 index 0000000000..94b3868792 Binary files /dev/null and b/lib/ic/doc/src/book.gif differ diff --git a/lib/ic/doc/src/book.xml b/lib/ic/doc/src/book.xml new file mode 100644 index 0000000000..f83bb1c632 --- /dev/null +++ b/lib/ic/doc/src/book.xml @@ -0,0 +1,49 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ic + + + 1998-09-29 + 4.0.4 + book.sgml +
+ + + ic + + + + + + + + + + + + + + + + diff --git a/lib/ic/doc/src/c-part.xml b/lib/ic/doc/src/c-part.xml new file mode 100644 index 0000000000..91c81c8ef3 --- /dev/null +++ b/lib/ic/doc/src/c-part.xml @@ -0,0 +1,40 @@ + + + + +
+ + 2002 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + IDL to C language Mapping + + + 2002-06-25 + A +
+ +

IDL to C

+ + + + + + + diff --git a/lib/ic/doc/src/ch_basic_idl.xml b/lib/ic/doc/src/ch_basic_idl.xml new file mode 100644 index 0000000000..d993fa3594 --- /dev/null +++ b/lib/ic/doc/src/ch_basic_idl.xml @@ -0,0 +1,163 @@ + + + + +
+ + 20022009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + OMG IDL + + + 2002-07-15 + + ch_basic_idl.xml +
+ +
+ OMG IDL - Overview +

The purpose of OMG IDL, Interface Definition Language, mapping + is to act as translator between platforms and languages. An IDL + specification is supposed to describe data types, object types etc.

+

Since the C and Java 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., CORBA, 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.

+ +
+ Reserved Compiler Names and Keywords +

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.

+

IC reserves all identifiers starting with OE_ and oe_ + for internal use.

+

Note also, that an identifier in IDL can contain alphabetic, + digits and underscore characters, but the first character + must be alphabetic. +

+

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.

+

The OMG defines a set of reserved words, shown below, for use as keywords. + These may not be used as, for example, identifiers.

+ + + abstract + double + local + raises + typedef + + + any + exception + long + readonly + unsigned + + + attribute + enum + module + sequence + union + + + boolean + factory + native + short + ValueBase + + + case + FALSE + Object + string + valuetype + + + char + fixed + octet + struct + void + + + const + float + oneway + supports + wchar + + + context + in + out + switch + wstring + + + custom + inout + private + TRUE + + + + default + interface + public + truncatable + + + OMG IDL keywords +
+

The keywords listed above must be written exactly as shown. Any usage + of identifiers that collide with a keyword is illegal. For example, + long is a valid keyword; Long and LONG are + illegal as keywords and identifiers. But, since the OMG must be able + to expand the IDL grammar, it is possible to use Escaped Identifiers. For example, it is not unlikely that native + have been used in IDL-specifications as identifiers. One option is to + change all occurrences to myNative. 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 _. The following IDL-code is illegal:

+ +typedef string native; +interface i { + void foo(in native Arg); + }; +}; + +

With Escaped Identifiers the code will look like:

+ +typedef string _native; +interface i { + void foo(in _native Arg); + }; +}; + +
+
+ + diff --git a/lib/ic/doc/src/ch_c_client.xml b/lib/ic/doc/src/ch_c_client.xml new file mode 100644 index 0000000000..7d4f8ec91a --- /dev/null +++ b/lib/ic/doc/src/ch_c_client.xml @@ -0,0 +1,149 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + The C Client Back-end + + + 2004-01-14 + C + ch_c_client.xml +
+ +
+ Introduction +

With the option {be, c_client} the IDL Compiler generates + C client stubs according to the IDL to C mapping, on top of the + Erlang distribution and gen_server protocols.

+

The developer has to write additional code, that together with + the generated C client stubs, form a hidden Erlang node. That + additional code uses erl_interface functions for defining + the hidden node, and for establishing connections to other + Erlang nodes.

+
+ +
+ Generated Stub Files +

The generated stub files are:

+ + +

For each IDL interface, a C source file, the name of which + is .c]]>. Each operation of the + IDL interface is mapped to a C function (with scoped name) + in that file;

+ + +

C source files that contain functions for type conversion, + memory allocation, and data encoding/decoding;

+ + +

C header files that contain function prototypes and type + definitions.

+ + +

All C functions are exported (i.e. not declared static).

+
+ +
+ C Interface Functions +

For each IDL operation a C interface function is + generated, the prototype of which is:

+

( oe_obj, , CORBA_Environment *oe_env);]]>

+

where

+ + +

]]> is the value to be returned as defined + by the IDL specification;

+ + +

oe_obj]]> is the client interface + object;

+ + +

]]> is a list of parameters of the + operation, defined in the same order as defined by the IDL + specification;

+ + +

CORBA_Environment *oe_env is a pointer to the current + client environment. It contains the current file descriptor, + the current input and output buffers, etc. For details see + CORBA_Environment C Structure.

+ + +
+ +
+ Generating, Compiling and Linking +

To generate the C client stubs type the following in an + appropriate shell:

+

,

+

where ICROOT is the root of the IC application. The + -I ICROOT/include is only needed if File.idl + refers to erlang.idl.

+

When compiling a generated C stub file, the directories + ICROOT/include and EICROOT/include, have to be + specified as include directories, where EIROOT is the + root directory of the Erl_interface application.

+

When linking object files the EIROOT/lib and + ICROOT/priv/lib directories have to be specified.

+
+ +
+ An Example +

In this example the IDL specification file "random.idl" is used + for generating C client stubs (the file is contained in the IC + /examples/c-client directory):

+ +

Generate the C client stubs:

+ + + +

Six files are generated.

+

Compile the C client stubs:

+

Please read the ReadMe file att the + examples/c-client directory

+

In the same + directory you can find all the code for this example.

+

In particular you will find the client.c file that contains + all the additional code that must be written to obtain a complete + client.

+

In the examples/c-client directory you will also find + source code for an Erlang server, which can be used for testing + the C client.

+
+ + + diff --git a/lib/ic/doc/src/ch_c_corba_env.xml b/lib/ic/doc/src/ch_c_corba_env.xml new file mode 100644 index 0000000000..557eeffdd4 --- /dev/null +++ b/lib/ic/doc/src/ch_c_corba_env.xml @@ -0,0 +1,385 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + CORBA_Environment C Structure + + + 2003-12-15 + PC1 + ch_c_corba_env.xml +
+ +

This chapter describes the CORBA_Environment C structure.

+ +
+ C Structure +

Here is the complete definition of the CORBA_Environment + C structure, defined in file "ic.h" :

+ +/* 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; + +

The structure is divided into three parts:

+ + +

The CORBA Compatibility part, demanded by the standard OMG + IDL mapping v2.0.

+ + +

The external implementation part used for generated + client/server code.

+ + +

The internal part useful for those who wish to define their + own functions.

+ + +
+ +
+ The CORBA Compatibility Part +

Contains only one field _major defined as a + CORBA_Exception_type. The CORBA_Exception type is an integer + which can be one of:

+ + +

CORBA_NO_EXCEPTION, by default equal to 0, can be + set by the application programmer to another value.

+ + +

CORBA_SYSTEM_EXCEPTION, by default equal to -1, can + be set by the application programmer to another value.

+ + +

The current definition of these values are:

+ + #define CORBA_NO_EXCEPTION 0 + #define CORBA_SYSTEM_EXCEPTION -1 + +
+ +
+ The External Part +

This part contains the following fields:

+ + +

int _fd - a file descriptor returned from + erl_connect. Used for connection setting.

+ + +

char* _inbuf - 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.

+ + +

int _inbufsz - 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

+ + +

int _outbufsz - start size of output buffer. The + value of this field can change under runtime in case of + input buffer expansion to fit larger messages

+ + +

char* _outbuf - 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.

+ + +

int _memchunk - 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.

+ + +

char regname[256] - a registered name for a process.

+ + +

erlang_pid* _to_pid - an Erlang process identifier, + is only used if the registered_name parameter is the empty + string.

+ + +

erlang_pid* _from_pid - your own process id so the + answer can be returned.

+ + +
+ +
+ The Internal Part +

This part contains the following fields:

+ + +

int _iin - Index for input buffer. Initially set + to zero. Updated to agree with the length of the received + encoded message.

+ + +

int _iout - Index for output buffer Initially set + to zero. Updated to agree with the length of the message + encoded to the communication counterpart.

+ + +

char _operation[256] - Pointer for operation name. + Set to the operation to be called.

+ + +

int _received - Used to count parameters. + Initially set to zero.

+ + +

erlang_pid _caller - Used to identify the caller. + Initiated to a value that identifies the caller.

+ + +

erlang_ref _unique - Used to identify the call. + Set to a default value in the case of generated functions.

+ + +

CORBA_char* _exc_id - Exception id field. + Initially set to NULL to agree with the initial value of + _major (CORBA_NO_EXCEPTION).

+ + +

void* _exc_value - Exception value field Initially + set to NULL to agree with the initial value of + _major (CORBA_NO_EXCEPTION).

+ + +

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.

+
+ +
+ Creating and Initiating the CORBA_Environment Structure +

There are two ways to set the CORBA_Environment structure:

+ + +

Manually

+

The following default values must be set to the + CORBA_Environment *ev fields, when buffers for + input/output should have the size inbufsz/ + outbufsz:

+ + +

ev->_inbufsz = inbufsz;

+

The value for this field can be between 0 and maximum + size of a signed integer.

+ + +

ev->_inbuf = malloc(inbufsz);

+

The size of the allocated buffer must be equal to the + value of its corresponding index, _inbufsz.

+ + +

ev->_outbufsz = outbufsz;

+

The value for this field can be between 0 and maximum + size of a signed integer.

+ + +

ev->_outbuf = malloc(outbufsz);

+

The size of the allocated buffer must be equal to the + value of its corresponding index, _outbufsz.

+ + +

ev->_memchunk = __OE_MEMCHUNK__;

+

Please note that __OE_MEMCHUNK__ is equal to + 1024, you can set this value to a value bigger + than 32 yourself.

+ + +

ev->_to_pid = NULL;

+ + +

ev->_from_pid = NULL;

+ + +

+ + +

By using the CORBA_Environment_alloc/2 function.

+

The CORBA_Environment_alloc function is defined as:

+ +\\011 CORBA_Environment *CORBA_Environment_alloc(int inbufsz, + int outbufsz); + +

where:

+ + +

inbufsz is the desired size of input buffer

+ + +

outbufsz is the desired size of output + buffer

+ + +

return value is a pointer to an allocated and + initialized CORBA_Environment structure.

+

+ + +

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.

+

To free the space allocated by CORBA_Environment_alloc/2:

+ + +

First call CORBA_free for the input and output buffers.

+ + +

After freeing the buffer space, call CORBA_free for + the CORBA_Environment space.

+ + + + + +

Remember to set the fields _fd, _regname, + *_to_pid and/or *_from_pid to the + appropriate application values. These are not automatically + set by the stubs.

+ + +

Never assign static buffers to the buffer pointers. Never set + the _memchunk field to a value less than + 32.

+ +
+ +
+ Setting System Exceptions +

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:

+ + +

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.

+ + +

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" :

+ + #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" + + + +

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"

+
+ + + diff --git a/lib/ic/doc/src/ch_c_mapping.xml b/lib/ic/doc/src/ch_c_mapping.xml new file mode 100644 index 0000000000..58b026ee78 --- /dev/null +++ b/lib/ic/doc/src/ch_c_mapping.xml @@ -0,0 +1,892 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IDL to C mapping + + + 2002-08-06 + PB1 + ch_c_mapping.xml +
+ +
+ Introduction +

The IC C mapping (used by the C client and C server back-ends) follows + the OMG C Language Mapping Specification.

+

The C mapping supports the following:

+ + +

All OMG IDL basic types except long double and any.

+ + +

All OMG IDL constructed types.

+ + +

OMG IDL constants.

+ + +

Operations with passing of parameters and receiving of + results. inout parameters are not supported.

+ + +

The following is not supported: +

+ + +

Access to attributes.

+ + +

User defined exceptions.

+

+ + +

User defined objects.

+

+ + +
+ +
+ C Mapping Characteristics + +
+ Reserved Names +

The IDL compiler reserves all identifiers starting with + OE_ and oe_ for internal use.

+
+ +
+ Scoped Names +

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 op1 defined in interface + I1 which is defined in module M1 would be + written as M1::I1::op1 in IDL and as M1_I1_op1 + in C.

+ +

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.

+ +
+ +
+ Generated Files +

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(.h), and the + other file is a C source code file (.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]]>.

+

For example:

+ lseq; + + interface i1 { + ... + }; + ... +}; + ]]> +

XXX This is C client specific. + Will produce the files oe_spec.h and + oe_spec.c for the top scope level. Then the files + m1.h and m1.c for the module m1 and + files m1_i1.h and m1_i1.c for the interface + i1. The typedef will produce oe_code_m1_lseq.c.

+

The header file contains type definitions for all + struct types and sequences and constants in the IDL file. The + c file contains all operation stubs if the the scope is an interface.

+

In addition to the scope-related files a C source file will + be generated for encoding operations of all struct and + sequence types.

+
+
+ +
+ Basic OMG IDL Types +

The mapping of basic types is as follows.

+ + + OMG IDL type + C type + Mapped to C type + + + float + CORBA_float + float + + + double + CORBA_double + double + + + short + CORBA_short + short + + + unsigned short + CORBA_unsigned_short + unsigned short + + + long + CORBA_long + long + + + long long + CORBA_long_long + long + + + unsigned long + CORBA_unsigned_long + unsigned long + + + unsigned long long + CORBA_unsigned_long_long + unsigned long + + + char + CORBA_char + char + + + wchar + CORBA_wchar + unsigned long + + + boolean + CORBA_boolean + unsigned char + + + octet + CORBA_octet + char + + + any + Not supported + + + + long double + Not supported + + + + Object + Not supported + + + + void + void + void + + OMG IDL Basic Types +
+

XXX Note that several mappings are not according to OMG C Language + mapping.

+
+ +
+ Constructed OMG IDL Types +

Constructed types have mappings as shown in the following table.

+ + + OMG IDL type + Mapped to C type + + + string + CORBA_char* + + + wstring + CORBA_wchar* + + + struct + struct + + + union + union + + + enum + enum + + + sequence + struct (see below) + + + array + array + + OMG IDL Constructed Types +
+

An OMG IDL sequence (an array of variable length),

+ NAME; + ]]> +

is mapped to a C struct as follows:

+ +/* C */ +typedef struct { + CORBA_unsigned_long _maximum; + CORBA_unsigned_long _length; + C_TYPE* _buffer; +} C_NAME; + +

where C_TYPE is the mapping of IDL_TYPE, and where + C_NAME is the scoped name of NAME.

+
+ +
+ OMG IDL Constants +

An IDL constant is mapped to a C constant through a C + #define macro, where the name of the macro is scoped. + Example:

+ +// IDL +module M1 { + const long c1 = 99; +}; + +

results in the following:

+ +/* C */ +#define M1_c1 99 + +
+ +
+ OMG IDL Operations +

An OMG IDL operation is mapped to C function. Each C operation + function has two mandatory parameters: a first parameter of + interface object type, and a last parameter of + environment type.

+

+

In a C operation function the the in and out + parameters are located between the first and last parameters + described above, and they appear in the same order as in the IDL + operation declaration.

+

Notice that inout parameters are not supported.

+

+

The return value of an OMG IDL operation is mapped to a + corresponding return value of the C operation function.

+

Mandatory C operation function parameters:

+ + CORBA_Object oe_obj - the first parameter of a C + operation function. This parameter is required by the OMG C Language Mapping Specification, but in the current + implementation there is no particular use for it. + +

CORBA_Environment* oe_env - the last parameter of a C + operation function. The parameter is defined in the C header + file ic.h and has the following public fields:

+ + +

CORBA_Exception_type _major - indicates if an + operation invocation was successful which will be one of + the following:

+ + CORBA_NO_EXCEPTION + CORBA_SYSTEM_EXCEPTION + + + int _fd - a file descriptor returned from + erl_connect function. + int _inbufsz - size of input buffer. + char* _inbuf - pointer to a buffer used for + input. + int _outbufsz - size of output buffer. + char* _outbuf - pointer to a buffer used for + output. + +

int _memchunk - 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.

+ + char regname[256] - a registered name for a + process. + erlang_pid* _to_pid - an Erlang process + identifier, is only used if the registered_name parameter + is the empty string. + erlang_pid* _from_pid - your own process id so + the answer can be returned + +

Beside the public fields, other private fields + are internally used but are not mentioned here.

+ + +

Example:

+ +// IDL +interface i1 { + long op1(in long a); + long op2(in string s, out long count); +}; + +

Is mapped to the following C functions

+ +/* 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) +{ + ... +} + + + +
+ Operation Implementation +

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:

+ + Argument mappings + Result values + Structure + Usage + Exception handling + +
+
+ +
+ Exceptions +

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.

+
+ +
+ Access to Attributes +

Not Supported

+
+ +
+ Summary of Argument/Result Passing for the C-client +

The user-defined parameters can only be in or out + parameters, as + inout parameters are not supported.

+

This table summarize the types a client passes as arguments to + a stub, and receives as a result.

+ + + OMG IDL type + In + Out + Return + + + short + CORBA_short + CORBA_short* + CORBA_short + + + long + CORBA_long + CORBA_long* + CORBA_long + + + long long + CORBA_long_long + CORBA_long_long* + CORBA_long_long + + + unsigned short + CORBA_unsigned_short + CORBA_unsigned_short* + CORBA_unsigned_short + + + unsigned long + CORBA_unsigned_long + CORBA_unsigned_long* + CORBA_unsigned_long + + + unsigned long long + CORBA_unsigned_long_long + CORBA_unsigned_long_long* + CORBA_unsigned_long_long + + + float + CORBA_float + CORBA_float* + CORBA_float + + + double + CORBA_double + CORBA_double* + CORBA_double + + + boolean + CORBA_boolean + CORBA_boolean* + CORBA_boolean + + + char + CORBA_char + CORBA_char* + CORBA_char + + + wchar + CORBA_wchar + CORBA_wchar* + CORBA_wchar + + + octet + CORBA_octet + CORBA_octet* + CORBA_octet + + + enum + CORBA_enum + CORBA_enum* + CORBA_enum + + + struct, fixed + struct* + struct* + struct + + + struct, variable + struct* + struct** + struct* + + + union, fixed + union* + union* + union + + + union, variable + union* + union** + union* + + + string + CORBA_char* + CORBA_char** + CORBA_char* + + + wstring + CORBA_wchar* + CORBA_wchar** + CORBA_wchar* + + + sequence + sequence* + sequence** + sequence* + + + array, fixed + array + array + array_slice* + + + array, variable + array + array_slice** + array_slice* + + Basic Argument and Result passing +
+

A client is responsible for providing storage of all arguments passed + as in arguments.

+ + + OMG IDL type + Out + Return + + + short + 1 + 1 + + + long + 1 + 1 + + + long long + 1 + 1 + + + unsigned short + 1 + 1 + + + unsigned long + 1 + 1 + + + unsigned long long + 1 + 1 + + + float + 1 + 1 + + + double + 1 + 1 + + + boolean + 1 + 1 + + + char + 1 + 1 + + + wchar + 1 + 1 + + + octet + 1 + 1 + + + enum + 1 + 1 + + + struct, fixed + 1 + 1 + + + struct, variable + 2 + 2 + + + string + 2 + 2 + + + wstring + 2 + 2 + + + sequence + 2 + 2 + + + array, fixed + 1 + 3 + + + array, variable + 3 + 3 + + Client argument storage responsibility +
+ + + Case + Description + + + 1 + Caller allocates all necessary storage, except that which may be encapsulated and managed within the parameter itself. + + + 2 + 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. + + + 3 + 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. + + Argument passing cases +
+

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.

+
+ +
+ Supported Memory Allocation Functions + + +

CORBA_Environment can be allocated from the user by calling + CORBA_Environment_alloc().

+

The interface for this function is

+

CORBA_Environment *CORBA_Environment_alloc(int inbufsz, int outbufsz);

+

where :

+ + +

inbufsz is the desired size of input buffer

+ + +

outbufsz is the desired size of output buffer

+ + +

return value is a pointer to an allocated and initialized + CORBA_Environment structure

+

+ + + + +

Strings can be allocated from the user by calling CORBA_string_alloc().

+

The interface for this function is

+

CORBA_char *CORBA_string_alloc(CORBA_unsigned_long len);

+

where :

+ + +

len is the length of the string to be allocated.

+ + + + +

Thus far, no other type allocation function is supported.

+
+ +
+ Special Memory Deallocation Functions + + +

void CORBA_free(void *storage)

+

This function will free storage allocated by the stub.

+ + +

void CORBA_exception_free(CORBA_environment *ev)

+

This function will free storage allocated under exception propagation.

+ + +
+ +
+ Exception Access Functions + + +

CORBA_char *CORBA_exception_id(CORBA_Environment *ev)

+

This function will return raised exception identity.

+ + +

void *CORBA_exception_value(CORBA_Environment *ev)

+

This function will return the value of a raised exception.

+ + +
+ +
+ Special Types + + +

The erlang binary type has some special features.

+

+

While the erlang::binary idl type has the same C-definition as + a generated sequence of octets :

+ binary; +\011 +\011 }; + ]]> +

it provides a way on sending trasparent data between C and Erlang.

+

The C-definition (ic.h) for an erlang binary is :

+ +\011 typedef struct { +\011 CORBA_unsigned_long _maximum; +\011 CORBA_unsigned_long _length; +\011 CORBA_octet* _buffer; +\011 } erlang_binary; /* ERLANG BINARY */ + +

The differences (between erlang::binary and ]]>) are :

+ + +

on the erlang side the user is sending/receiving typical + built in erlang binaries, using term_to_binary() / binary_to_term() + to create / extract binary structures.

+ + +

no encoding/decoding functions are generated

+ + +

the underlying protocol is more efficient than usual sequences of + octets

+ + +

The erlang binary IDL type is defined in erlang.idl, while it's + C definition is located in the ic.h header file, both in the + /include]]> directory. + The user will have to include the file erlang.idl in order to use the + erlang::binary type.

+ + +
+ +
+ A Mapping Example +

+ + 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.

+ +// The source IDL file: stack.idl + +struct s { + long l; + string s; +}; + +interface stack { + void push(in s val); + s pop(); +}; + +

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. +

+

stack.c

+ + +void push(stack oe_obj, s val, CORBA_Environment* oe_env) { + ... +} + + +s* pop(stack oe_obj, CORBA_Environment* oe_env) { + ... +} + +

oe_stack.h

+ +#ifndef OE_STACK_H +#define OE_STACK_H + + +/*------------------------------------------------------------ + * Struct definition: s + */ +typedef struct { + long l; + char *s; +} s; + + + +#endif + +

stack.h just contains an include statement of oe_stack.h.

+

oe_code_s.c

+ + +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) { + ... +} + +

The only files that are really important are the .h + files and the stack.c file.

+
+ + diff --git a/lib/ic/doc/src/ch_c_server.xml b/lib/ic/doc/src/ch_c_server.xml new file mode 100644 index 0000000000..c66ae85fa3 --- /dev/null +++ b/lib/ic/doc/src/ch_c_server.xml @@ -0,0 +1,148 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + The C Server Back-end + + + 2004-01-14 + C + ch_c_server.xml +
+ +
+ Introduction +

With the option {be, c_server} the IDL Compiler generates + C server skeletons according to the IDL to C mapping, on top of + the Erlang distribution and gen_server protocols.

+

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 erl_interface functions for defining the hidden + node and for establishing connections to other Erlang nodes.

+
+ +
+ Generated Stub Files +

The generated stub files are:

+ + +

For each IDL interface, a C source file, the name of which + is __s.c]]>. Each operation of the + IDL interface is mapped to a C function (with scoped name) + in that file;

+ + +

C source files that contain functions for type conversion, + memory allocation, and data encoding/decoding;

+ + +

C header files that contain function prototypes and type + definitions.

+ + +

All C functions are exported (i.e. not declared static).

+
+ +
+ C Skeleton Functions +

For each IDL operation a C skeleton function is generated, the + prototype of which is __exec( oe_obj, CORBA_Environment *oe_env)]]>, where ]]>, and + CORBA_Environment are of the same type as for the + generated C client stubs code.

+

Each __exec()]]> function calls the + call-back function

+

_rs* __cb( oe_obj, , CORBA_Environment *oe_env)]]>

+

where the arguments are of the same type as those generated for + C client stubs.

+

The return value _rs* ]]> is a pointer + to a function with the same signature as the call-back function + _cb]]>, and is called after the call-back + function has been evaluated (provided that the pointer is not equal + to NULL).

+
+ +
+ The Server Loop +

The developer has to implement code for establishing connections + with other Erlang nodes, code for call-back functions and restore + functions.

+

+

In addition, the developer also has to implement code for a + server loop, that receives messages and calls the relevant + __exec function. For that purpose the IC library function + oe_server_receive() function can be used.

+
+ +
+ Generating, Compiling and Linking +

To generate the C server skeletons type the following in an + appropriate shell:

+

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

+

where ICROOT is the root of the IC application. The + -I ICROOT/include is only needed if File.idl + refers to erlang.idl.

+

When compiling a generated C skeleton file, the directories + ICROOT/include and EICROOT/include, have to be + specified as include directories, where EIROOT is the + root directory of the Erl_interface application.

+

When linking object files the EIROOT/lib and + ICROOT/priv/lib directories have to be specified.

+
+ +
+ An Example +

In this example the IDL specification file "random.idl" is used + for generating C server skeletons (the file is contained in the IC + /examples/c-server directory):

+ +module rmod { + + interface random { + + double produce(); + + oneway void init(in long seed1, in long seed2, in long seed3); + + }; + +}; +

Generate the C server skeletons:

+ +erlc '+{be, c_server}' random.idl +Erlang IDL compiler version X.Y.Z +

Six files are generated.

+

Compile the C server skeletons:

+

Please read the ReadMe file in the + examples/c-server directory.

+

In the same directory you can find all the code for this + example. In particular you will find the server.c file + that contains all the additional code that must be written to + obtain a complete server.

+

In the examples/c-server directory you will also find + source code for an Erlang client, which can be used for testing + the C server.

+
+ + + diff --git a/lib/ic/doc/src/ch_erl_genserv.xml b/lib/ic/doc/src/ch_erl_genserv.xml new file mode 100644 index 0000000000..972eff7c17 --- /dev/null +++ b/lib/ic/doc/src/ch_erl_genserv.xml @@ -0,0 +1,205 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Using the Erlang Generic Server Back-end + + + 98-08-06 + B + ch_erl_genserver.xml +
+ +
+ Introduction +

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 gen_server. Orber's User's Guide + contain a more detailed description of IDL to Erlang mapping.

+
+ +
+ Compiling the Code +

The ic:gen/2 function can be called from the command + line as follows:

+

+ +shell> erlc "+{be, erl_genserv}" MyFile.idl + +
+ +
+ Writing the Implementation File +

For each IDL interface ]]> defined in the IDL file :

+ + Create the corresponding Erlang file that will hold the + Erlang implementation of the IDL definitions. + Call the implementation file after the scope of the IDL interface, + followed by the suffix _impl. + Export the implementation functions. + +

For each function defined in the IDL interface :

+ + 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. + When using the function, follow the mapping described in chapter 2. + +
+ +
+ An Example +

In this example, a file random.idl generates code for the Erlang + gen_server back-end:

+ +// 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); + + }; +}; + +

When the file "random.idl" is compiled (e.g., shell> erlc "+{be, erl_genserv}" random.idl) + 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 + rmod_random.erl is the most important. This module exports two kinds of + operations:

+ + Administrative - used when, for example, creating and + terminating the server. + IDL dependent - operations defined in the IDL + specification. In this case, produce and init. + + +
+ Administrative Operations +

To create a new server instance, one of the following functions should + be used:

+ + oe_create/0/1/2 - create a new instance of the object. + Accepts Env and RegName, 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 + gen_server parameter ServerName. If Env is + left out, an empty list will be passed. + oe_create_link/0/1/2 - similar to oe_create/0/1/2, + but create a linked server. + typeID/0 - returns the scooped id compliant with the + OMG standard. In this case the string + "IDL:rmod/random:1.0". + stop/1 - asynchronously terminate the server. The required + argument is the return value from any of the start functions. + +
+ +
+ IDL Dependent Operations +

Operations can either be synchronous or asynchronous + (i.e., oneway). These are, respectively, mapped to + gen_server:call/2/3 and gen_server:cast/2. + Consult the gen_server documentation for valid return values.

+

The IDL dependent operations in this example are listed below. + The first argument must be the whatever the create operation returned.

+ + init(ServerReference, Seed1, Seed2, Seed3) - initialize + the random number generator. + produce(ServerReference) - generate a new random number. + +
+

If the compile option timeout is used a timeout must be added + (e.g., produce(ServerReference, 5000)). For more information, see + the gen_server documentation.

+ +
+ Implementation Module +

The implementation module shall, unless the compile option + impl is used, be named rmod_random_impl.erl. + and could look like this:

+ +-module('rmod_random_impl'). +%% Mandatory gen_server operations +-export([init/1, terminate/2, code_change/3]). +%% Add if 'handle_info' compile option used +-export([handle_info/2]). +%% API defined in IDL specification +-export([produce/1,init/4]). + +%% Mandatory operations +init(Env) -> + {ok, []}. + +terminate(From, Reason) -> + ok. + +code_change(OldVsn, State, Extra) -> + {ok, State}. + +%% Optional +handle_info(Info, State) -> + {noreply, NewState}. + +%% IDL specification +produce(State) -> + case catch random:uniform() of +\\011{'EXIT',_} -> +\\011 {stop, normal, "random:uniform/0 - EXIT", State}; +\\011RUnif -> + {reply, RUnif, State} + end. + + +init(State, S1, S2, S3) -> + case catch random:seed(S1, S2, S3) of +\\011{'EXIT',_} -> +\\011 {stop, normal, State}; +\\011_ -> + {noreply, State} + end. + +

Compile the code and run the example:

+ 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> + ]]> +
+
+ + + diff --git a/lib/ic/doc/src/ch_erl_plain.xml b/lib/ic/doc/src/ch_erl_plain.xml new file mode 100644 index 0000000000..36de46f624 --- /dev/null +++ b/lib/ic/doc/src/ch_erl_plain.xml @@ -0,0 +1,175 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Using the Plain Erlang Back-end + + + 98-05-06 + B + ch_erl_plain.xml +
+ +
+ Introduction +

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.

+
+ +
+ Compiling the Code +

In the Erlang shell type :

+

ic:gen(, [{be, erl_plain}])]]>.

+
+ +
+ Writing the Implementation File +

For each IDL interface ]]> defined in the IDL file:

+ + Create the corresponding Erlang file that will hold the + Erlang implementation of the IDL definitions. + Call the implementation file after the scope of the IDL interface, + followed by the suffix _impl. + Export the implementation functions. + +

For each function defined in the IDL interface :

+ + 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. + When using the function, follow the mapping described in chapter 2. + +
+ +
+ An Example +

+ + In this example, a file "random.idl" is generates code for the plain Erlang + back-end :

+ + +

Main file : "plain.idl"

+ +\011 +module rmod { + + interface random { + + double produce(); + + oneway void init(in long seed1, in long seed2, in long seed3); + + }; + +}; + + + +

Compile the file :

+ + 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> + +

+

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 + rmod_random.erl is important :. + +

+ + +

Erlang file for interface : "rmod_random.erl"

+ + +-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). + + + +

The implementation file should be called rmod_random_impl.erl + and could look like this:

+ + -module('rmod_random_impl'). + + -export([produce/0,init/3]). + + + produce() -> + random:uniform(). + + + init(S1,S2,S3) -> + random:seed(S1,S2,S3). + +

Compiling the code :

+ +2> make:all(). +Recompile: rmod_random +Recompile: oe_random +Recompile: rmod_random_impl +up_to_date + +

+

Running the example :

+ +3> rmod_random:init(1,2,3). +ok +4> rmod_random:produce(). +1.97963e-4 +5> + +
+ + diff --git a/lib/ic/doc/src/ch_ic_protocol.xml b/lib/ic/doc/src/ch_ic_protocol.xml new file mode 100644 index 0000000000..678fdc766c --- /dev/null +++ b/lib/ic/doc/src/ch_ic_protocol.xml @@ -0,0 +1,233 @@ + + + + +
+ + 20032009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IC Protocol + + + 2003-12-11 + PA1 + ch_ic_protocol.xml +
+

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. +

+ +
+ Introduction +

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). +

+

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. +

+

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. +

+
+ +
+ Language mappings and IDL operations + +
+ IDL Operations +

An IDL operation is declared as follows:

+ +\011[oneway] RetType Op(in IType1 I1, in IType2 I2, ..., in ITypeN IN, +\011out OType1 O1, out OType2 O2, ..., out OTypeM OM) +\011N, M = 0, 1, 2, ...\011\011(2.1.1) + +

`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. +

+

The types can be any basic types or derived types declared in the + IDL specification of which the operation declaration is a part. +

+

If the RetType has the special name `void' there is no return + value (but there might still be result values O1, 02, ..., OM). +

+

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. +

+

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. +

+

Otherwise the operation is a call, i.e. it is confirmed (or else + an exception is raised). +

+

Note carefully that an operation declared without `oneway' is + always a call, even if RetType is `void' and M = 0. +

+
+ +
+ Language Mappings +

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. +

+

Excerpt from "6.4 Basic OMG IDL Types" in the Orber User's Guide: +

+ + +

Functions with return type void will return the atom ok.

+ + +

Excerpt from "6.13 Invocations of Operations" in the Orber User's + Guide: +

+ + +

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.

+ + +

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').

+
+
+ +
+ IC Protocol +

Given the operation declaration (2.1.1) the IC protocol maps to + messages as follows, defined in terms of Erlang terms. +

+ +
+ Call (Request/Reply, i.e. not oneway) + + request:\011\011 Op\011\011\011atom()\011\011N = 0\011 +\011\011\011 {Op, I1, I2, ..., IN}\011tuple()\011\011N > 0 +\011\011\011\011\011\011\011\011(3.1.1) + + reply:\011\011 Ret\011\011\011\011\011M = 0 +\011\011\011 {Ret, O1, O2, ..., OM}\011\011\011M > 0 +\011\011\011\011\011\011\011\011(3.1.2) +

Notice: 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'). +

+
+ +
+ Cast (oneway) + + + notification:\011Op\011\011\011atom()\011\011N = 0 +\011\011\011{Op, I1, I2, ..., IN}\011tuple()\011\011N > 0 +\011\011\011\011\011\011\011\011(3.2.1) +

(There is of course no return message). +

+
+
+ +
+ Gen_server Protocol +

Most of the IC generated code deals with encoding and decoding the + gen_server protocol. +

+ +
+ Call + + + request:\011{'$gen_call', {self(), Ref}, Request}\011\011(4.1.1) + + reply:\011{Ref, Reply}\011\011\011\011\011(4.1.2) +

where Request and Reply are the messages defined in the previous + chapter. +

+
+ +
+ Cast + + notification: {'$gen_cast', Notification}\011\011(4.2.1) +

where Notification is the message defined in the previous chapter. +

+
+
+ +
+ Erlang Distribution Protocol +

Messages (of interest here) between Erlang nodes are of the form:

+ + Len(4), Type(1), CtrlBin(N), MsgBin(M)\011\011\011(5.1) +

Type is equal to 112 = PASS_THROUGH. +

+

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. +

+

CtrlBin (of interest here) contains the SEND and REG_SEND control + messages, which are binary forms of the Erlang terms

+ +\011{2, Cookie, ToPid} ,\011\011\011\011\011(5.2) +

and

+ +\011{6, FromPid, Cookie, ToName} ,\011\011\011\011(5.3) +

respectively. +

+

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. +

+

The MsgBin(N) is the "real" message, i.e. of the form described + in the previous section. +

+
+ + diff --git a/lib/ic/doc/src/ch_introduction.xml b/lib/ic/doc/src/ch_introduction.xml new file mode 100644 index 0000000000..898d2a732a --- /dev/null +++ b/lib/ic/doc/src/ch_introduction.xml @@ -0,0 +1,148 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Using the IC Compiler + + + 2002-08-02 + PB1 + ch_introduction.xml +
+ +
+ Introduction +

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.

+

The first group consists of a CORBA back-end:

+ + IDL to Erlang CORBA + +

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 + Orber application User's Guide and manuals for + further details.

+ + +

The second group consists of a simple Erlang back-end:

+ + IDL to plain Erlang + +

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.

+

This back-end can be considered a short-circuit version of + the IDL to Erlang gen_server back-end (see further below).

+ + +

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 + erl_interface and jinterface for C and Java, + respectively.

+

All back-ends of the third group generate code compatible with + the Erlang gen_server behavior protocol. Thus generated client + code corresponds to call() or cast() of an Erlang + gen_server. Similarly, generated server code corresponds + to handle_call() or handle_cast() of an Erlang + gen_server.

+

The back-ends of the third group are: +

+ + IDL to Erlang gen_server + +

Client stubs and server skeletons are generated. Data types + are mapped according to the IDL to Erlang mapping described + in the Orber User's Guide.

+

+ + IDL to C client + +

Client stubs are generated. The mapping of data types is + described further on in the C client part of this guide.

+ + IDL to C server + +

Server skeletons are generated. The mapping of data types is + described further on in the C server part of this guide.

+ + IDL to Java + +

Client stubs and server skeletons are generated. The mapping + of data types is described further on in the Java part of + this guide.

+ + +
+ +
+ Compilation of IDL Files +

The IC compiler is invoked by executing the generic erlc + compiler from a shell:

+ +%> erlc +'{be,BackEnd}' File.idl + +

where BackEnd is according to the table below, and + File.idl is the IDL file to be compiled.

+ + + Back-end + BackEndoption + + + IDL to CORBA + erl_corba + + + IDL to CORBA template + erl_template + + + IDL to plain Erlang + erl_plain + + + IDL to Erlang gen_server + erl_genserv + + + IDL to C client + c_client + + + IDL to C server + c_server + + + IDL to Java + java + + Compiler back-ends and options +
+

For more details on IC compiler options consult the ic(3) manual page.

+
+ + diff --git a/lib/ic/doc/src/ch_java.xml b/lib/ic/doc/src/ch_java.xml new file mode 100644 index 0000000000..831850f211 --- /dev/null +++ b/lib/ic/doc/src/ch_java.xml @@ -0,0 +1,737 @@ + + + + +
+ + 19992009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IDL to Java language Mapping + + + 98-09-24 + A + ch_java.xml +
+ +
+ Introduction +

This chapter describes the mapping of OMG IDL constructs to the Java + programming language for the generation of native Java - Erlang + communication.

+

This language mapping defines the following:

+ + +

All OMG IDL basic types

+ + +

All OMG IDL constructed types

+ + +

References to constants defined in OMG IDL

+ + +

Invocations of operations, including passing of + parameters and receiving of result

+ + +

Access to attributes

+ + +
+ +
+ Specialties in the Mapping + +
+ Names Reserved by the Compiler +

The IDL compiler reserves all identifiers starting with + OE_ and oe_ for internal use.

+
+
+ +
+ Basic OMG IDL Types +

The mapping of basic types are according to the standard. All basic types have + a special Holder class.

+ + + OMG IDL type + Java type + + + float + float + + + double + double + + + short + short + + + unsigned short + short + + + long + int + + + long long + long + + + unsigned long + long + + + unsigned long long + long + + + char + char + + + wchar + char + + + boolean + boolean + + + octet + octet + + + string + java.lang.String + + + wstring + java.lang.String + + + any + Any + + + long double + Not supported + + + Object + Not supported + + + void + void + + OMG IDL basic types +
+
+ +
+ Constructed OMG IDL Types +

All constructed types are according to the standard with three (3) major exceptions.

+

+ + +

The IDL Exceptions are not implemented in this Java mapping.

+

+ + +

The functions used for read/write to streams, defined in Helper functions + are named unmarshal (instead for read) and marshal (instead for write).

+

+ + +

The streams used in Helper functions are OtpInputStream for + input and OtpOutputStream for output.

+

+ + +
+ +
+ Mapping for Constants +

Constants are mapped according to the standard.

+
+ +
+ Invocations of Operations +

Operation invocation is implemented according to the standard. + The implementation is in the class Stub.java]]> which implements + the interface in .java]]>.

+ +test._iStub client; + +client.op(10); + + +
+ Operation Implementation +

The server is implemented through extension of the class + ImplBase.java]]> and implementation of all the methods in the + interface.

+ +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; + } + +} + +
+
+ +
+ Exceptions +

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.

+
+ +
+ Access to Attributes +

Attributes are supported according to the standard.

+
+ +
+ Summary of Argument/Result Passing for Java +

All types (in, out or inout) of user defined parameters are supported + in the Java mapping. This is also the case in the Erlang mappings but not in the C + mapping. inout parameters are not supported in the C mapping so if you are going to + do calls to or from a C program inout cannot be used in the IDL specifications.

+

out and inout parameters must be of Holder types. There is a jar file ( ic.jar) + with Holder classes for the basic types in the ic application. This library is in the directory + /priv]]>.

+
+ +
+ Communication Toolbox +

The generated client and server stubs use the classes + defined in the jinterface package to communicate + with other nodes. + The most important classes are :

+ + +

OtpInputStream which is the stream class used for incoming message storage

+

+ + +

OtpOutputStream which is the stream class used for outgoing message storage

+

+ + +

OtpErlangPid which is the process identification class used to identify processes inside + a java node.

+

The recommended constructor function for the OtpErlangPid is + OtpErlangPid(String node, int id, int serial, int creation) where :

+

+ + +

String node, is the name of the node where this process runs.

+

+ + +

int id, is the identification number for this identity.

+

+ + +

int serial, internal information, must be an 18-bit integer.

+

+ + +

int creation, internal information, must have value in range 0..3.

+

+ + + + +

OtpConnection which is used to define a connection between nodes.

+

While the connection object is stub side constructed in client stubs, it is + returned after calling the accept function from an OtpErlangServer object + in server stubs. + The following methods used for node connection :

+

+ + +

OtpInputStream receiveBuf(), which returns the incoming streams that + contain the message arrived.

+

+ + +

void sendBuf(OtpErlangPid client, OtpOutputStream reply), which sends + a reply message (in an OtpOutputStream form) to the client node.

+

+ + +

void close(), which closes a connection.

+

+ + + + +

OtpServer which is used to define a server node.

+

The recommended constructor function for the OtpServer is :

+

+ + +

OtpServer(String node, String cookie). where :

+

+ + +

node is the requested name for the new java node, + represented as a String object.

+

+ + +

cookie is the requested cookie name for the new java node, + represented as a String object.

+

+ + + + +

The following methods used for node registration and connection acceptance :

+

+ + +

boolean publishPort(), which registers the server node to epmd daemon.

+

+ + +

OtpConnection accept(), which waits for a connection and returns the + OtpConnection object which is unique for each client node.

+

+ + + + +
+ +
+ The Package com.ericsson.otp.ic +

The package com.ericsson.otp.ic + contains a number of java classes specially designed for the IC generated java-back-ends :

+ + +

Standard java classes defined through OMG-IDL java mapping :

+ + +

BooleanHolder

+ + +

ByteHolder

+ + +

CharHolder

+ + +

ShortHolder

+ + +

IntHolder

+ + +

LongHolder

+ + +

FloatHolder

+ + +

DoubleHolder

+ + +

StringHolder

+ + +

Any, + AnyHelper, + AnyHolder

+ + +

TypeCode

+ + +

TCKind

+

+ + + + +

Implementation-dependant classes :

+ + +

Environment

+ + +

Holder

+

+ + + + +

Erlang compatibility classes :

+ + +

Pid, + PidHelper, + PidHolder

+

The Pid class originates from OtpErlangPid and is used to + represent the Erlang built-in pid type, a process's identity. + PidHelper and PidHolder are helper respectively holder classes for Pid.

+

+ + +

Ref, + RefHelper, + RefHolder

+

The Ref class originates from OtpErlangRef and is used to + represent the Erlang built-in ref type, an Erlang reference. + RefHelper and RefHolder are helper respectively holder classes for Ref.

+

+ + +

Port, + PortHelper, + PortHolder

+

The Port class originates from OtpErlangPort and is used to + represent the Erlang built-in port type, an Erlang port. + PortHelper and PortHolder are helper respectively holder classes for Port.

+

+ + +

Term, + TermHelper, + TermHolder

+

The Term class originates from Any and is used to + represent the Erlang built-in term type, an Erlang term. + TermHelper and TermHolder are helper respectively holder classes for Term.

+

+ + +

To use the Erlang build-in classes, you will have to include the file erlang.idl + located under $OTPROOT/lib/ic/include.

+ + +
+ +
+ The Term Class +

The Term class is intended to represent the Erlang term generic type. + It extends the Any class and it is basically used in the same way as + in the Any type.

+

The big difference between Term and Any is the use of guard methods + instead of TypeCode 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 :

+ + +

boolean isAtom() returns true if the Term is an OtpErlangAtom, false otherwise

+

+ + +

boolean isConstant() returns true if the Term is neither an OtpErlangList nor an OtpErlangTuple, false otherwise

+

+ + +

boolean isFloat() returns true if the Term is an OtpErlangFloat, false otherwise

+

+ + +

boolean isInteger() returns true if the Term is an OtpErlangInt, false otherwise

+

+ + +

boolean isList() returns true if the Term is an OtpErlangList, false otherwise

+

+ + +

boolean isString() returns true if the Term is an OtpErlangString, false otherwise

+

+ + +

boolean isNumber() returns true if the Term is an OtpErlangInteger or an OtpErlangFloat, false otherwise

+

+ + +

boolean isPid() returns true if the Term is an OtpErlangPid or Pid, false otherwise

+

+ + +

boolean isPort() returns true if the Term is an OtpErlangPort or Port, false otherwise

+

+ + +

boolean isReference() returns true if the Term is an OtpErlangRef, false otherwise

+

+ + +

boolean isTuple() returns true if the Term is an OtpErlangTuple, false otherwise

+

+ + +

boolean isBinary() returns true if the Term is an OtpErlangBinary, false otherwise

+

+ + +
+ +
+ Stub File Types +

For each interface, three (3) stub/skeleton files are generated :

+ + +

A java interface file, named after the idl interface.

+

+ + +

A client stub file, named after the convention Stub]]> + which implements the java interface. Example : _stackStub.java

+

+ + +

A server stub file, named after the convention ImplBase]]> + which implements the java interface. Example : _stackImplBase.java

+

+ + +
+ +
+ Client Stub Initialization, Methods Exported +

The recommended constructor function for client stubs accepts four (4) parameters :

+

+ + +

String selfNode, the node identification name to be used in the new + client node.

+

+ + +

String peerNode, the node identification name where the client process is running.

+

+ + +

String cookie, the cookie to be used.

+

+ + +

Object server, where the java Object can be one of:

+

+ + +

OtpErlangPid, the server's process identity under the node where the server + process is running.

+

+ + +

String, the server's registered name under the node where the server + process is running.

+

+ + + + +

The methods exported from the generated client stub are :

+

+ + +

void __disconnect(), which disconnects the server connection.

+

+ + +

void __reconnect(), which disconnects the server connection if open, + and then connects to the same peer.

+

+ + +

void __stop(), 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.

+

+ + +

com.ericsson.otp.erlang.OtpErlangRef __getRef(), will return the message reference + received from a server that denotes which call it is referring to. + This is useful when building asynchronous clients.

+

+ + +

java.lang.Object __server(), which returns the server for the current connection.

+

+ + +
+ +
+ Server Skeleton Initialization, Server Stub Implementation, Methods Exported +

The constructor function for server skeleton accepts no parameters.

+

The server skeleton file contains a server switch which + decodes messages from the input stream and calls implementation + (callback) functions. + As the server skeleton is declared abstract, the application + programmer will have to create a stub class that extends the + skeleton file. In this class, all operations defined in the interface + class, generated under compiling the idl file, are implemented.

+

The server skeleton file exports the following methods:

+

+ + +

OtpOutputStrem invoke(OtpInputStream request), where the input + stream request is unmarshalled, the implementation function is called + and a reply stream is marshalled.

+

+ + +

boolean __isStopped(), 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.

+

+ + +

boolean __isStopped(com.ericsson.otp.ic.Environment), 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.

+

+ + +

OtpErlangPid __getCallerPid(), which returns the caller identity for the latest call.

+

+ + +

OtpErlangPid __getCallerPid(com.ericsson.otp.ic.Environment), which returns the caller + identity for the latest call on a certain Environment.

+

+ + +

java.util.Dictionary __operations(), which returns the operation dictionary which + holds all operations supported by the server skeleton.

+

+ + +
+ +
+ A Mapping Example +

+ + 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.

+ +// The source IDL file: stack.idl + +struct s { + long l; + string s; +}; + +interface stack { + void push(in s val); + s pop(); +}; + +

When this file is compiled it produces eight files. Three important files + are shown below. +

+

The public interface is in stack.java.

+ + +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; + +} + +

For the IDL struct s three files are generated, a public class in s.java.

+ + +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; + }; + +}; + +

A holder class in sHolder.java and a helper class in sHelper.java. + The helper class is used for marshalling.

+ + +public class sHelper { + + // constructors + private sHelper() {}; + + // methods + public static s unmarshal(OtpInputStream in) + throws java.lang.Exception { +\011: +\011: + }; + + public static void marshal(OtpOutputStream out, s value) + throws java.lang.Exception { +\011: +\011: + }; + +}; + +
+ +
+ Running the Compiled Code +

When using the generated java code you must have added + /priv]]> and + /priv]]> to your + CLASSPATH variable to get + basic Holder types and the communication classes.

+
+ + diff --git a/lib/ic/doc/src/erl-part.xml b/lib/ic/doc/src/erl-part.xml new file mode 100644 index 0000000000..b5041dce7f --- /dev/null +++ b/lib/ic/doc/src/erl-part.xml @@ -0,0 +1,38 @@ + + + + +
+ + 2002 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + IDL to Erlang language Mapping + + + 2002-06-25 + A +
+ +

Tjosan Erlang

+ + + + + diff --git a/lib/ic/doc/src/fascicules.xml b/lib/ic/doc/src/fascicules.xml new file mode 100644 index 0000000000..0678195e07 --- /dev/null +++ b/lib/ic/doc/src/fascicules.xml @@ -0,0 +1,18 @@ + + + + + + User's Guide + + + Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/lib/ic/doc/src/ic.gif b/lib/ic/doc/src/ic.gif new file mode 100644 index 0000000000..d78cf7d8ed Binary files /dev/null and b/lib/ic/doc/src/ic.gif differ diff --git a/lib/ic/doc/src/ic.xml b/lib/ic/doc/src/ic.xml new file mode 100644 index 0000000000..9f48229425 --- /dev/null +++ b/lib/ic/doc/src/ic.xml @@ -0,0 +1,469 @@ + + + + +
+ + 1997 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + ic + + + + 2004-01-08 + B +
+ ic + The Erlang IDL Compiler + +

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.

+

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.

+ + + + ic:gen(FileName) -> Result + ic:gen(FileName, [Option]) -> Result + Generate stub and server code according to the OMG CORBA standard. + + Result = ok | error | {ok, [Warning]} | {error, [Warning], [Error]} + + Option = [ GeneralOption | CodeOption | WarningOption | BackendOption] + + GeneralOption = + {outdir, String()} | {cfgfile, String()} | {use_preproc, bool()} | + {preproc_cmd, String()} | {preproc_flags, String()} + + CodeOption = + {gen_hrl, bool()} | {serv_last_call, exception | exit} | {{impl, String()}, String()} | {light_ifr, bool()} + this | {this, String()} | {{this, String()}, bool()} | + from | {from, String()} | {{from, String()}, bool()} | + handle_info | {handle_info, String()} | {{handle_info, String()}, bool()} | + timeout | {timeout, String()} | {{timeout, String()}, bool()} | + {scoped_op_calls, bool()} | {scl, bool()} | + {user_protocol, Prefix} | + {c_timeout, SendTimeout, RecvTimeout} | + {c_report, bool()} | + {precond, {atom(), atom()}} | {{precond, String()} {atom(), atom()}} | + {postcond, {atom(), atom()}} | {{postcond, String()} {atom(), atom()}} + + WarningOption = + {'Wall', bool()} | {maxerrs, int() | infinity} | + {maxwarns, int() | infinity} | {nowarn, bool()} | + {warn_name_shadow, bool()} | {pedantic, bool()} | + {silent, bool()} + + BackendOption = {be, Backend} + + Backend = erl_corba | erl_template | erl_plain | erl_genserv | c_client | c_server | java + + DirNAme = string() | atom() + FileName = string() | atom() + + +

The tuple {Option, true} can be replaced by + Option for boolean values.

+

The ic:gen/2 function can be called from the command + line as follows:

+

erlc "+Option" ... File.idl

+

Example:

+

erlc "+{be,c_client}" '+{outdir, "../out"}' File.idl

+ + + + +
+ General options + + outdir + +

Places all output files in the directory given by the option. + The directory will be created if it does not already exist.

+

Example option: {outdir, "output/generated"}.

+ + cfgfile + +

Uses FileName as configuration file. Options will + override compiler defaults but can be overridden by command line + options. Default value is ".ic_config".

+

Example option: {cfgfile, "special.cfg"}.

+ + use_preproc + +

Uses a preprocessor. Default value is true.

+ + preproc_cmd + +

Command string to invoke the preprocessor. The actual + command will be built as + preproc_cmd++preproc_flags++FileName

+

Example option: {preproc_cmd, "erl"}).

+

Example option: {preproc_cmd, "gcc -x c++ -E"}.

+ + preproc_flags + +

Flags given to the preprocessor.

+

Example option: {preproc_flags, "-I../include"}.

+ + +
+ +
+ Code options + + light_ifr + +

Currently, the default setting is false. 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.

+

Example option: {light_ifr, true}.

+ + gen_hrl + +

Generate header files. Default is true.

+ + serv_last_call + +

Makes the last gen_server handle_call either raise a + CORBA exception or just exit plainly. Default is the exception. +

+ + {{impl, IntfName}, ModName} + +

Assumes that the interface with name IntfName is + implemented by the module with name ModName and + will generate calls to the ModName module in the + server behavior. Note that the IntfName must be a + fully scoped name as in "M1::I1".

+

+ + this + +

Adds the object reference as the first parameter to the + object implementation functions. This makes the + implementation aware of its own object reference. +

+The option + comes in three varieties: this which activates the + parameter for all interfaces in the source file, {this, IntfName} which activates the parameter for a specified + interface and {{this, IntfName}, false} which + deactivates the parameter for a specified + interface.

+

Example option: this) activates the parameter for + all interfaces.

+

Example option: {this, "M1::I1"} activates the + parameter for all functions of M1::I1.

+

Example options: [this, {{this, "M1::I2"}, false}] + activates the parameter for all interfaces except + M1::I2.

+ + from + +

Adds the invokers reference as the first parameter to the + object implementation two-way functions. If both + from and this 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 gen_server and Orber + documentation how this option may be used.

+The option + comes in three varieties: from which activates the + parameter for all interfaces in the source file, {from, IntfName} which activates the parameter for a specified + interface and {{from, IntfName}, false} which + deactivates the parameter for a specified interface.

+

Example option: from) activates the parameter for + all interfaces.

+

Example options: [{from, "M1::I1"}] activates the + parameter for all functions of M1::I1.

+

Example options: [from, {{from, "M1::I2"}, false}] + activates the parameter for all interfaces except + M1::I2.

+ + handle_info + +

Makes the object server call a function handle_info + in the object implementation module on all unexpected + messages. Useful if the object implementation need to trap + exits.

+

Example option: handle_info will activates module + implementation handle_info for all interfaces in the + source file.

+

Example option: {{handle_info, "M1::I1"}, true} + will activates module implementation handle_info for + the specified interface.

+

Example options: [handle_info, {{handle_info, "M1::I1"}, false}] will generate the handle_info + call for all interfaces except M1::I1.

+ + timeout + +

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.

+

Example option: {timeout,"M::I"}) produces server + stub which will has an extra timeout parameter in the initialization + function for that interface.

+

Example option: timeout produces server + stub which will has an extra timeout parameter in the initialization + function for all interfaces in the source file.

+

Example options: [timeout, {{timeout,"M::I"}, false}] + produces server stub which will has an extra timeout + parameter in the initialization function for all interfaces + except M1::I1.

+ + scoped_op_calls + +

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. All of the parts generated by ic + have to agree in the use of this option. Default is + false.

+

Example options: + [{be,c_genserv},{scoped_op_calls,true}]) produces + client stubs which sends "scoped" requests to a gen_server + or a c-server.

+ + user_protocol + +

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 IC C protocol.

+

Example options: + [{be,c_client},{user_protocol, "my_special"}]) produces + client stubs which use C protocol functions with the prefix + "my_special".

+ + c_timeout + +

Makes sends and receives to have timeouts (C back-ends only). These + timeouts are specified in milliseconds.

+

Example options: + [{be,c_client},{c_timeout, 10000, 20000}]) produces + client stubs which use a 10 seconds send timeout, and a + 20 seconds receive timeout.

+ + c_report + +

Generates code for writing encode/decode errors to stderr (C back-ends only). + timeouts are specified in milliseconds.

+

Example options: + [{be,c_client}, c_report]).

+ + scl + +

Used for compatibility with previous compiler versions up + to 3.3. 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 + false.

+

Example option: {scl,true}

+ + precond + +

Adds a precondition call before the call to the operation + implementation on the server side.

+

The option comes in three varieties: {precond, {M, F}} which activates the call for operations in all + interfaces in the source file, {{precond, IntfName}, {M, F}} which activates the call for all operations in a + specific interface and {{precond, OpName}, {M, F}} + which activates the call for a specific operation.

+

The precondition function has the following signature + m:f(Module, Function, Args).

+

Example option: {precond, {mod, fun}} adds the call + of m:f for all operations in the idl file.

+

Example options: [{{precond, "M1::I"}, {mod, fun}}] + adds the call of m:f for all operations in the + interface M1::I1.

+

Example options: [{{precond, "M1::I::Op"}, {mod, fun}}] adds the call of m:f for the operation + M1::I::Op.

+ + postcond + +

Adds a postcondition call after the call to the operation + implementation on the server side.

+

The option comes in three varieties: {postcond, {M, F}} which activates the call for operations in all + interfaces in the source file, {{postcond, IntfName}, {M, F}} which activates the call for all operations in a + specific interface and {{postcond, OpName}, {M, F}} + which activates the call for a specific operation.

+

The postcondition function has the following signature + m:f(Module, Function, Args, Result).

+

Example option: {postcond, {mod, fun}} adds the call + of m:f for all operations in the idl file.

+

Example options: [{{postcond, "M1::I"}, {mod, fun}}] + adds the call of m:f for all operations in the + interface M1::I1.

+

Example options: [{{postcond, "M1::I::Op"}, {mod, fun}}] adds the call of m:f for the operation + M1::I::Op.

+ + +
+ +
+ Warning options + + 'Wall' + +

The option activates all reasonable warning messages in + analogy with the gcc -Wall option. Default value is true.

+ + maxerrs + +

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 infinity. Default number is 10.

+ + maxwarns + +

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 infinity. Default value is + infinity.

+ + nowarn + +

Suppresses all warnings. Default value is false.

+ + warn_name_shadow + +

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.

+ + pedantic + +

Activates all warning options. Default value is false.

+ + silent + +

Suppresses compiler printed output. Default value is false.

+ + +
+ +
+ Back-End options +

Which back-end IC will generate code for is determined by the supplied + {be,atom()} option. If left out, erl_corba is used. + Currently, IC support the following back-ends:

+ + erl_corba + +

This option switches to the IDL generation for CORBA.

+ + erl_template + +

Generate CORBA call-back module templates for each interface in the target + IDL file. Note, will overwrite existing files.

+ + erl_plain + +

Will produce plain Erlang modules which contain functions that + map to the corresponding interface functions on the input file.

+ + erl_genserv + +

This is an IDL to Erlang generic server generation option.

+ + c_client + +

Will produce a C client to the generic Erlang server.

+ + c_server + +

Will produce a C server switch with functionality of a + generic Erlang server.

+ + java + +

Will produce Java client stubs and server skeletons with + functionality of a generic Erlang server.

+ + c_genserv + +

Deprecated. Use c_client instead.

+ + +
+ +
+ Preprocessor +

The IDL compiler allows several preprocessors to be used, the + Erlang IDL preprocessor or other standard 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 gcc is adequate.

+

The preprocessor command is formed by appending the prepoc_cmd + to the preproc_flags option and then appending the input IDL + file name.

+
+ +
+ Configuration +

The compiler can be configured in two ways:

+ + +

Configuration file

+ + +

Command line options

+ + +

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 + file:consult.

+

An example of a configuration file, note the "." after each + line.

+ +{outdir, gen_dir}. +{{impl, "M1::M2::object"}, "obj"}. + +
+ +
+ Output files +

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 (.hrl/ + .h) and one or more Erlang/C files (.erl/.c). + Please look at the language mapping for each back-end for details.

+

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.

+
+ + + diff --git a/lib/ic/doc/src/ic_c_protocol.xml b/lib/ic/doc/src/ic_c_protocol.xml new file mode 100644 index 0000000000..f895fe0723 --- /dev/null +++ b/lib/ic/doc/src/ic_c_protocol.xml @@ -0,0 +1,158 @@ + + + + +
+ + 2004 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + IC C Protocol Functions + + + 2004-04-06 + A +
+ ic_c_protocol + IC C Protocol Functions + +

This manual page lists some of the functions of the IC C runtime + library that are used internally for the IC protocol. +

+

The listed functions are used internally by generated C client + and server code. They are documented here for the advanced user 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 oe, the user + has to implement his own set of functions, the names of which + are obtained by replacing the oe prefix by Prefix. + The Prefix has to be set with the option + {user_protocol, Prefix} at compile time.

+

The following terminology is used (reflected in names of + functions): a notification is a message send from + client to server, without any reply back (i.e. a + oneway operation); a request is a message sent + from client to server, and where a reply message is + sent back from the server to the client.

+

In order to understand how the functions work and what they do + the user must study their implementation in the IC C + library (source file is ic.c), and also consider how they + are used in the C code of ordinary generated client stubs or + server skeletons.

+

+ + +
+ Client Protocol Functions +

The following functions are used internally by generated C + client code.

+
+ + + intoe_prepare_notification_encoding(CORBA_Environment *env) + Prepare client notification encoding. + +

The result of this function is the beginning of a binary of + in external format of the tuple {'$gen_cast', X} where + X is not yet filled in.

+

In generated client code this function is the first to be called + in the encoding function for each oneway operation.

+ + + + intoe_send_notification(CORBA_Environment *env) + intoe_send_notification_tmo(CORBA_Environment *env, unsigned int send_ms) + Send client notification. + +

Sends a client notification to a server according to the + Erlang distribution + gen_server protocol.

+

The send_ms parameter specified a timeout in milliseconds.

+ + + + intoe_prepare_request_encoding(CORBA_Environment *env) + Prepare client request encoding. + +

The result of this function is the beginning of a binary in + the external format of the tuple {'$gen_call', {Pid, Ref}, X} where X is not yet filled in.

+

In generated client code this function is the first to be called + in the encoding function for each twoway operation.

+ + + + intoe_send_request_and_receive_reply(CORBA_Environment *env) + intoe_send_request_and_receive_reply_tmo(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms) + Send client request and receive reply. + +

Sends a client request and receives the reply according to + the Erlang distribution + gen_server protocol. This function + calls the oe_prepare_reply_decoding function in order + to obtain the gen_server reply. +

+

send_ms and recv_ms specify timeouts for send + and receive, respectively, in milliseconds.

+ + + + intoe_prepare_reply_decoding(CORBA_Environment *env) + Prepare client decoding of reply. + +

Decodes the binary version of the tuple {Ref, X}, + where X is to be decoded later by the specific client + decoding function.

+ + + + +
+ Server Protocol Functions +

The following functions are used internally by generated C + server code.

+
+ + + intoe_prepare_request_decoding(CORBA_Environment *env) + Prepare server decoding of request. + +

Decodes the binary version of the tuple {'$gen_cast', Op} (Op an atom), or the tuple {'$gen_cast', {Op, X}}, where Op is the operation name, and + where X is to be decoded later by the specific + operation decoding function; or

+

decodes the binary version of the tuple {'$gen_call', {Pid, Ref}, Op} (Op an atom), or the tuple + {'$gen_call', {Pid, Ref}, {Op, X}}, where Op> + is the operation name, and X is to be decode later by + the specific operation decoding function.

+ + + + intoe_prepare_reply_encoding(CORBA_Environment *env) + Prepare server encoding of reply. + +

Encodes the beginning of the binary version of the tuple + {{Ref,X}, where X is to be filled in by the + specific server encoding function.

+ + + + +
+ SEE ALSO +

ic(3), ic_clib(3), IC Protocol

+
+ + + diff --git a/lib/ic/doc/src/ic_clib.xml b/lib/ic/doc/src/ic_clib.xml new file mode 100644 index 0000000000..b557c4b5f6 --- /dev/null +++ b/lib/ic/doc/src/ic_clib.xml @@ -0,0 +1,246 @@ + + + + +
+ + 20032009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IC C Library Functions + + + 2003-12-16 + PB1 +
+ ic_clib + IC C Library Functions + +

This manual page lists some of the functions in the IC C runtime + library.

+ + +
+ Allocation and Deallocation Functions +

The following functions are used for allocating and + deallocating a CORBA_Environment structure.

+
+ + + CORBA_Environment*CORBA_Environment_alloc(int inbufsz, int outbufsz) + Allocate environment data. + +

This function is used to allocate and initiate the + CORBA_Environment structure. In particular, it is used + to dynamically allocate a CORBA_Environment structure and set + the default values for the structure's fields.

+

inbufsize is the initial size of the input + buffer.

+

outbufsize is the initial size of the output + buffer.

+

CORBA_Environment is the CORBA 2.0 state structure + used by the generated stub.

+

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.

+

To free the space allocated by CORBA_Environment_alloc() do + as follows.

+ + +

First call CORBA_free for the input and output buffers.

+ + +

After freeing the buffer space, call CORBA_free for the + CORBA_Environment space.

+ + + + + + voidCORBA_free(void *p) + Free any allocated data. + +

Frees allocated space pointed to by p.

+ + + + CORBA_char*CORBA_string_alloc(CORBA_unsigned_long len) + Allocate a string. + +

Allocates a (simple) CORBA character string of length len + 1.

+ + + + CORBA_wchar*CORBA_wstring_alloc(CORBA_unsigned_long len) + Allocate a wide string. + +

Allocates a CORBA wide string of length len + 1.

+ + + + +
+ Exception Functions +

Functions for retrieving exception ids and values, and for setting + exceptions.

+
+ + + CORBA_char*CORBA_exception_id(CORBA_Environment *env) + Get exception identity. + +

Returns the exception identity if an exception is set, otherwise + it returns NULL.

+ + + + void*CORBA_exception_value(CORBA_Environment *env) + Get exception value. + +

Returns the exception value, if an exception is set, otherwise + it returns NULL.

+ + + + voidCORBA_exc_set(CORBA_Environment *env, CORBA_exception_type Major, CORBA_char *Id, CORBA_char *Value) + Set exception. + +

Sets the exception type, exception identity, and exception value + in the environment pointed to by env.

+ + + + +
+ Server Reception +

The following function is provided for convenience.

+
+ + + intoe_server_receive(CORBA_Environment *env, oe_map_t *map) + intoe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map, unsigned int send_ms, unsigned int recv_ms) + Server receive of notification or request, and sending of reply (in case of request). + +

Provides a loop that receives one message, executes the + operation in question, and in case of a two-way operation + sends a reply.

+

send_ms and recv_ms specify timeout values + in milliseconds for send and receive, respectively.

+ + + + +
+ Generic Execution Switch and Map Merging +

Function for searching for server operation function, and for + calling it if found. Function for merging maps (see the include + file ic.h for definitions).

+
+ + + intoe_exec_switch(CORBA_Object obj, CORBA_Environment *env, oe_map_t *map) + Search for server operation and execute it. + +

Search for server operation and execute it.

+ + + + oe_map_t*oe_merge_maps(oe_map_t *maps, int size) + Merge an array of server maps to one single map. + +

Merge an array of server maps to one single map.

+ + + + +
+ The CORBA_Environment structure +

Here is the complete definition of the CORBA_Environment structure, + defined in file ic.h:

+ + /* 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; + + +

Always set the field values _fd, _regname, + _to_pid and/or *_from_pid to appropriate + application values. These are not automatically set by the + stubs.

+ + +

Never assign static buffers to the buffer pointers, and never + set the _memchunk field to a value less than + 32.

+ +
+ +
+ SEE ALSO +

ic(3), ic_c_protocol(3) +

+
+ + + diff --git a/lib/ic/doc/src/java-part.xml b/lib/ic/doc/src/java-part.xml new file mode 100644 index 0000000000..69cc0f026c --- /dev/null +++ b/lib/ic/doc/src/java-part.xml @@ -0,0 +1,37 @@ + + + + +
+ + 2002 + 2007 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + IDL to Java language Mapping + + + 2002-06-25 + A +
+ +

+ + + + diff --git a/lib/ic/doc/src/make.dep b/lib/ic/doc/src/make.dep new file mode 100644 index 0000000000..64694ee85a --- /dev/null +++ b/lib/ic/doc/src/make.dep @@ -0,0 +1,24 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex c-part.tex ch_basic_idl.tex ch_c_client.tex \ + ch_c_corba_env.tex ch_c_mapping.tex ch_c_server.tex \ + ch_erl_genserv.tex ch_erl_plain.tex ch_ic_protocol.tex \ + ch_introduction.tex ch_java.tex erl-part.tex \ + ic.tex ic_c_protocol.tex ic_clib.tex java-part.tex \ + ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + diff --git a/lib/ic/doc/src/notes.gif b/lib/ic/doc/src/notes.gif new file mode 100644 index 0000000000..e000cca26a Binary files /dev/null and b/lib/ic/doc/src/notes.gif differ diff --git a/lib/ic/doc/src/notes.xml b/lib/ic/doc/src/notes.xml new file mode 100644 index 0000000000..c4314d8cc1 --- /dev/null +++ b/lib/ic/doc/src/notes.xml @@ -0,0 +1,444 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IDL Compiler Release Notes + + + + 2004-04-06 + AC + notes.xml +
+ +
+ IC 4.2.23 + +
+ Improvements and New Features + + +

+ 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.

+

+ Own Id: OTP-8201 Aux Id:

+ + +
+
+ +
+ IC 4.2.22 + +
+ Fixed Bugs and Malfunctions + + +

The 64-bit version of libic was not compiled with the -fPIC flag.

+

Own id: OTP-8088

+ + +
+
+ +
+ IC 4.2.21 + +
+ Fixed Bugs and Malfunctions + + +

The function print_erlang_binary (oe_ei_code_erlang_binary.c) + updated to avoid compiler warning.

+

Own id: OTP-7982

+ + +
+
+ +
+ IC 4.2.20 + +
+ Improvements and New Features + + +

Updated file headers.

+

Own id: OTP-7837

+ + +
+
+ +
+ IC 4.2.19 + +
+ Improvements and New Features + + +

Documentation source included in open source releases.

+

Own id: OTP-7595

+ + +
+
+ +
+ IC 4.2.18 + +
+ Fixed Bugs and Malfunctions + + +

Insufficient buffer allocated when passing wide strings + using the C backend on a 64-bit architecture.

+

Own Id: OTP-7313 Aux Id:

+ + +
+
+ +
+ IC 4.2.17 + +
+ Improvements and New Features + + +

Updated file headers.

+

Own id: OTP-7011

+ + +

IC no longer use the obsolete function file:rawopen/2.

+

Own id: OTP-7182

+ + +
+
+ +
+ IC 4.2.16 + +
+ Improvements and New Features + + +

Added links to classes inherited from Jinterface in the + User's Guide.

+

Own Id: OTP-6965 Aux Id:

+ + +
+
+ +
+ IC 4.2.15 + +
+ Fixed Bugs and Malfunctions + + +

If an inherited function name begun with a capital letter + the generated stub/skeleton oe_tc/1 function was incorrect.

+

Own Id: OTP-6855 Aux Id:

+ + +
+
+ +
+ IC 4.2.14 + +
+ Improvements and New Features + + +

The documentation source has been converted from SGML to XML.

+

Own Id: OTP-6754 Aux Id:

+ + +
+
+ +
+ IC 4.2.13 + +
+ Improvements and New Features + + +

Minor Makefile changes.

+

Own Id: OTP-6701 Aux Id:

+ + +
+
+ +
+ IC 4.2.12 + +
+ Improvements and New Features + + +

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.

+ + +
+
+ +
+ IC 4.2.11 + +
+ Improvements and New Features + + +

Changed code generation to avoid warnings such as unused + variables.

+

Own Id: OTP-5930 Aux Id:

+ + +
+
+ +
+ IC 4.2.10 + +
+ Fixed Bugs and Malfunctions + + +

The FD_SETSIZE limit has been increased to 2048 for + VxWorks/PPC603.

+

Own Id: OTP-5395 Aux Id: seq9751

+ + +
+
+ +
+ IC 4.2.9 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-5375 Aux Id: seq9740

+ + +
+
+ +
+ IC 4.2.8 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-5205 Aux Id: seq9241

+ + +
+
+ +
+ IC 4.2.7 + +
+ Improvements and New Features + + +

A new compiler option c_report has been introduced + for C back-ends (client and server). If that option is + set, encoding/decoding errors will be reported to + stderr.

+

Own Id: OTP-4977

+ + +
+
+ +
+ IC 4.2.6 + +
+ Improvements and New Features + + +

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.

+

Own Id: OTP-5036

+ + +
+ +
+ Incompatibilities + + +

The compile option multiple_be is no longer supported.

+

Own Id: OTP-5049

+ + +
+
+ +
+ IC 4.2.5 + +
+ Improvements and New Features + + +

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).

+

Accordingly a new compiler option {c_timeout, {SendTimeout, RecvTimeout}} has been added. Timeouts + are specified in milliseconds.

+

A user that want to implement its own protocols with + function timeouts has to implement the following functions.

+

For C clients the functions int PFX_send_notification(CORBA_Environment *env, unsigned int send_ms), and int PFX_send_request_and_receive_reply(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms) + have to be additionally implemented, where PFX is the + user defined prefix.

+

For C servers no additional functions have to be + implemented, but a clone of the int oe_server_receive_tmo(CORBA_Environment *env, oe_map_t *map, unsigned int send_ms, unsigned int recv_ms) + might be handy.

+

Own Id: OTP-4972

+ + +
+
+ +
+ IC 4.2.4 + +
+ Improvements and new features + + +

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.

+ + For C clients it means to replace the library functions + int oe_prepare_notification_encoding(CORBA_Environment *env), int oe_send_notification(CORBA_Environment *env), int oe_prepare_request_encoding(CORBA_Environment *env), + int oe_send_request_and_receive_reply(CORBA_Environment *env), and int oe_prepare_reply_decoding(CORBA_Environment *env), + with functions of the same signature, but with the prefix + "oe" replaced by a user defined prefix. + For C servers the functions int oe_prepare_request_decoding(CORBA_Environment *env), + and int oe_prepare_reply_encoding(CORBA_Environment *env), are similarly replaced.

+ + The new compiler option {user_protocol, Prefix} has + been added.

+

Own Id: OTP-4834

+ + +
+
+ +
+ IC 4.2.3 + +
+ Fixed Bugs and Malfunctions + + +

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.

+

Own Id: OTP-4881

+ + +
+
+ +
+ IC 4.2.2 + +
+ Fixed Bugs and Malfunctions + + +

IDL long long and unsigned long long could not + be used in a struct for the Java backend.

+

All unsigned integer types for the Java backend + had broken marshalling for large values.

+

Own Id: OTP-4763

+ + +
+
+ +
+ IC 4.2.1 + +
+ Fixed Bugs and Malfunctions + + +

A scoping problem (IC could not find typedefs contained + inherited interfaces) in the C-backend solved.

+

Own Id: OTP-4758

+ + +
+
+ +
+ IC 4.2 + +
+ Improvements and New Features + + +

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.

+

Own Id: OTP-4576

+ + +
+
+ + diff --git a/lib/ic/doc/src/old_notes.xml b/lib/ic/doc/src/old_notes.xml new file mode 100644 index 0000000000..9ba0262573 --- /dev/null +++ b/lib/ic/doc/src/old_notes.xml @@ -0,0 +1,1565 @@ + + + + +
+ + 20032009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IDL Compiler Release Notes + + + + 2003-11-19 + AB +
+ +
+ IC 4.1.8 + +
+ Fixed Bugs and Malfunctions + + +

IDL-files containing result or Result as, + for example, parameter name, caused an exit with reason + bad_match.

+

Own Id: OTP-4532

+ + +

Uninitialized variables were used in ic_init_ref for + C backends.

+

Own Id: OTP-4537

+ + Aux Id: seq7666, ETOtr17107

+ + +

CORBA_Environment_alloc() left some fields + uninitialized in the returned pointer to an + CORBA_Environment for C backends.

+

Own Id: OTP-4538

+ + +

The function ic_compare_refs() for C backends + could find two unequal references to be equal.

+

Own Id: OTP-4539

+ + +
+
+ +
+ IC 4.1.7 + +
+ Fixed Bugs and Malfunctions + + +

Operation names were always scoped in C server backend, + irrespective of the setting of the option + scoped_op_calls.

+

Own Id: OTP-4521

+ + Aux Id: seq7643, ETOtr16925

+ + +
+
+ +
+ IC 4.1.6 + +
+ Improvements and New Features + + +

For C backends generated code checks that the + _length field of bounded sequences (i.e. specified + as ]]>) does not exceed the + specified maximum length. If so, an exception is raised.

+

Own Id: OTP-4471

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

The _maximum field was not set for sequence structs + generated by the C backends.

+

Own Id: OTP-4471

+ + Aux Id: seq7600, ETOtr16308

+ + +

There was a memory leak in C backends in case there was a + decoding error in a sequence with elements of basic type.

+

Own Id: OTP-4475

+ + +

For for C backends, IDL structs defined within an + interface were not mapped into C structs in appropriate + include files.

+

Own Id: OTP-4481

+ + Aux Id: seq7617

+ + +

If the user, incorrectly, trap exit's but did not use the + 'handle_info' compile option it would cause the server to + terminate. The same problem occurred if someone, + illegally, sent a message to the server. It could also + happen for illegal oneway operations.

+

Own Id: OTP-4488

+ + +
+
+ +
+ IC 4.1.5 + +
+ Fixed Bugs and Malfunctions + + +

Invalid C code was generated for type short.

+

Own Id: OTP-4450

+ + Aux Id: seq7582

+ + +
+
+ +
+ IC 4.1.4 +
+ Fixed Bugs and Malfunctions + + +

Operation functions inherited by an interface were not + placed in the map table in generated code for the C server + backend. As a result such functions were not found by the + switch function of the interface.

+

Own Id: OTP-4448

+ + Aux Id: seq7582

+ + +
+
+ +
+ IC 4.1.3.1 + +
+ Fixed Bugs and Malfunctions + + +

A non-ANSI compliant construct in libic.a was changed.

+

Own Id: -

+ + +
+
+ +
+ IC 4.1.3 + +
+ Improvements and New Features + + +

For Erlang and C back-ends an IC version stamp has been + added to generated source code. This stamp i preserved in + compiled target code.

+ + +

For C backends an assert() expression has been + added to generated code. That expression asserts that the + result of a memory allocation size calculation is strictly + positive. An error will result in a printout and an + abort(). The assertion can be inhibited by defining + the macro NDEBUG (according to ANSI C).

+

If the assertion is inhibited, and a size calculation error + is detected, an INTERNAL CORBA exception is set.

+ + +

An internal reorganization of C backend generator code has + been done (addition of module ic_cclient). Several + changes has been done in generated C code:

+ + +

The typedef ___generic___ has been replaced by + the typedef ___exec_function___, which has been + made more strict; for backward compatibility the + ___generic___ typedef is now an alias for + ___exec_function___.

+ + +

Function parameters that are arrays, has been changed + to be pointers to array slices, which are equivalent + according to ANSI C.

+ + +

The storage class specifier extern has been + removed from function prototypes in header files.

+ + +

Redundant type casts have been removed from generated code. + Also some local "generic" variables have been renamed.

+ + + + +
+ +
+ Fixed Bugs and Malfunctions + + +

Module info vsn replaced by app_vsn.

+

Own Id: OTP-4341

+ + +

IC-4.1.2 disabled the definition of float constants + beginning with a zero (e.g. 0.14).

+

Own Id: OTP-4367

+ + +

IC did not handle constant definitions correctly for + char, string, wchar and wstring.

+

Own Id: OTP-4067, OTP-3222

+ + +

IC did not recognize all reserved words defined in the + OMG specification (2.3.1). The new keywords are fixed, abstract, custom, factory, local, native, private, public, supports, truncatable, 'ValueBase' and + valuetype. But for now this is only active for the + erl_corba backend and only incorrect usage of + fixed, since this datatype is now supported, + triggers an error for this backend.

+

Own Id: OTP-4368

+ + +

It was not possible to use wchar or wstring inside a + union body when using the Java backend.

+

Own Id: + OTP-4365

+ + +

The compile options this and handle_info + did not behave as described in the documentation. The + timeout now behaves as, for example, + handle_info.

+

Own Id: OTP-4386, OTP-3231

+ + +

If we typedef a sequence, which contains a struct or a union, + the access function id/0 returned an incorrect IFR Id + if a prefix pragma was used.

+

Own Id: OTP-4387

+ + +

If an IDL file contained a prefix pragma, incorrect + IFR-id's was generated in the IFR-registration operation + oe_register for aliases (typedef) and + attributes.

+

Own Id: OTP-4388, OTP-4392

+ + +

For C back-ends, when encodings/decodings failed, memory + allocated for variable size parameter types was not freed.

+

Own Id: OTP-4391 +

+Aux Id: seq7438, ETOtr14009

+ + +

If an IDL file contained a multiple typedef + (e.g. typedef string str1, str2;), the oe_unregister + operation failed to remove all data, in this case str2, + from the IFR.

+

Own Id: OTP-4393

+ + +

IC did not recognize octet-constants + (e.g. const octet octetmax = 255;).

+

Own Id: OTP-4400

+ + +

Negative 'long long' constants was not accepted + (e.g. const long long MyConstant = -1;).

+

Own Id: OTP-4401

+ + +
+
+ +
+ IC 4.1.2 + +
+ Fixed Bugs and Malfunctions + + +

Merging of map's (___map___) using the + ___merge___ function does not work.

+

Own Id: OTP-4323

+ + +

Error in generated C decode/encode functions for union's with + discriminator where the union has no value for all discriminator + values. E.g. a union with discriminator boolean where only the + discriminator value TRUE has a corresponding union value. + Here is how such a thing would look in IDL:

+ 
+\011    union OptXList switch(boolean) {
+\011       case TRUE: integer  val;
+            };
+
+

Own Id: OTP-4322

+ + +

Scoped op calls ('{scoped_op_calls, true}') does not handle + module/function names beginning with capital letter (e.g. + Megaco should be 'Megaco') for oneway operations (handle_cast).

+

Own Id: OTP-4310

+ + +

A bug is fixed on C-IDL erlang binaries that caused + pointer error when residing inside sequences.

+

Own Id: OTP-4303

+ + +
+
+ +
+ IC 4.1.1 + +
+ Improvements and New Features + + +

A new option 'multiple_be' is added that allows multiple backend + generation for the same IDL file.

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed on IDL types that contain underscore '_'.

+

Own Id: OTP-3710

+ + +

A bug is fixed on IDL structs that caused scope confusion + when types and fields of a struct had the same name.

+

Own Id: OTP-2893

+ + +
+
+ +
+ IC 4.0.7 + +
+ Improvements and New Features + + +

The Erlang binary special type is introduced, that + allows efficient transfer of binaries between Erlang and C.

+

Own Id:OTP-4107

+ + +
+
+ +
+ IC 4.0.6 + +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed on noc backend which caused generation of erroneous code.

+

Own Id: OTP-3812

+ + +
+
+ +
+ IC 4.0.5 + +
+ Improvements and New Features + + +

The pragma code option is extended to point + specific functions on NOC backend, not only + interfaces.

+

+ + +
+
+ +
+ IC 4.0.4 + +
+ Fixed Bugs and Malfunctions + + +

A bug in pragma prefix when including IDL files is fixed. + This caused problems for Erlang-corba IFR registrations.

+

Own Id: OTP-3620

+ + +
+
+ +
+ IC 4.0.3 + +
+ Improvements and New Features + + +

Limited support on multiple file module definitions.

+

The current version supports multiple file module definitions all + backends except the c oriented backends.

+

Own Id: OTP-3550

+ + +
+
+ +
+ IC 4.0.2 +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed on Erlang backends.

+

The (recently) introduced generation of files + describing sequence and array files were even + true for included interfaces. In the case of + some Erlang backends this were unnecessary.

+

Own Id: OTP-3485

+ + +
+
+ +
+ IC 4.0.1 + +
+ Improvements and New Features + + +

New functionality added on Java and Erl_genserv backends.

+

+ + +

On the Java client stub :

+

+ + +

The Java client have now one more constructor function, + that allows to continue with an already started connection.

+ + +

void __stop() which sends a stop cast call to the server. + While this causes the Erlang server to terminate, it + sets a stop flag to the Java server environment, requesting the + server to terminate.

+ + +

void __reconnect() which closes the current client connection + if open and then connects to the same server.

+ + +

The Environment variable is now declared as public.

+ + +

On the Java server skeleton :

+

+ + +

boolean __isStopped() which returns true if a stop + message where received, false otherwise. The user must check if + this function returns true, and in this case exit the implemented + server loop.

+ + +

The Environment variable is now declared as protected which + allows the implementation that extends the stub to access it.

+ + +

On the Erlang gen_server stub :

+

+ + +

stop(Server) which yields to a cast call to the standard + gen_server stop function. This will always terminate the + Erlang gen_server, while it will set the stop flag for the + Java server stub.

+ + + + +

Own Id: OTP-3433

+ + +
+
+ +
+ IC 4.0 + +
+ Improvements and New Features + + +

New types handled by IC.

+

The following OMG-IDL types are added in this compiler version :

+ + +

long long

+

unsigned long long

+

wchar

+

wstring

+ + +

Own Id: OTP-3331

+

+ + +

TypeCode as built in type and access code files for array and sequence types.

+ + +

As TypeCode is a pseudo-interface, it is now is a built-in type on IC.

+ + +

Access code files which contain information about TypeCode, ID and Name are + now generated for user defined arrays and sequences.

+ + +

Own Id: OTP-3392

+ + +
+
+ +
+ IC 3.8.2 +
+ Fixed Bugs and Malfunctions +

A bug is fixed on preprocessor directive expansion.

+

When nested #ifdef - #ifndef directives, a bug caused + improper included file expansion. This is fixed by + repairing the preprocessor expansion function.

+

Own Id: OTP-3472

+
+
+ +
+ IC 3.8.1 + +
+ Improvements and New Features + + +

Build in Erlang types support for java-backends

+

The built-in Erlang types term, port, ref and pid + are needed in Java backends in order to support an + efficient mapping between the two languages. + The new types are also supported by additional + helpers and holders to match with OMGs Java mapping + As a result of this, the following classes are added to + the com.ericsson.otp.ic interface :

+ + +

Term,TermHelper,TermHolder which represents the + built-in Erlang type term

+ + +

Ref,RefHelper,RefHolder which represents the + built-in Erlang type ref

+ + +

Port,PortHelper, PortHolder which represents the + built-in Erlang type port

+ + Pid, PidHelper and PidHolder which represents the + built-in Erlang type pid + +

+

Own Id: OTP-3348

+

+ + +

Compile time preprocessor macro variable definitions

+

The preprocessor lacked possibility to accept user + defined variables other than the one defined in IDL files. + This limited the use of command-ruled IDL specifications. + Now the build-in preprocessor allows the user to set variables + by using the "preproc_flags" option the same way + as using the "gcc" preprocessor.

+

Supported flags :

+ + +

"]]> which defines a variable

+ + +

"]]> which undefines a variable

+ + +

+

Own Id: OTP-3349

+ + +
+ +
+ Fixed Bugs and Malfunctions +

A bug on comment type expansion is fixed.

+

The comment type expansion were erroneous when + inherited types (NOC backend). + This is now fixed and the type naming agree with + the scope of the inheritor interface.

+

Own Id: OTP-3346

+
+
+ +
+ IC 3.8 + +
+ Improvements and New Features + + +

The code generated for java backend is optimized + due to use of streams instead for tuple classes + when (un)marshalling message calls. + Support for building clients using asynchronous + client calls and effective multi-threaded servers.

+

Own Id: OTP-3310

+

+ + +

The any type is now supported for java backend.

+

Own Id: OTP-3311

+ + +
+ +
+ A bug on C generated constants is fixed +

While the constants are evaluated and behave well when used + inside an IDL specification their C-export were not working properly. + The constant export definitions were not generated well :

+ + +

the declared C definition were erroneous ( the name did not always agree + with the scope the constant were declared in ).

+ + +

there were no C- definition generated for the c-server backend when + the constants were declared inside an interface.

+ + +

Own Id: OTP-3219

+
+ +
+ Incompatibilities +

Due to optimizations in java backend, the stub initialization and usage + differs than the previous version.

+

Client stub interface changes:

+ + +

Client disconnects by calling the __disconnect() function instead + for the old _closeConnection()

+

+ + +

All marshal operation functions have now the interface :

+

_marshal(Environment<, Param |, Params >)]]>

+

instead for

+

_marshal(< Param, | Params, >OtpErlangPid, OtpErlangRef)]]>

+

+ + +

All unmarshal operation functions have now the interface :

+

_< OpName >_unmarshal(Environment<, Param |, Params >)]]>

+

instead for

+

_< OpName >_unmarshal(< Param, | Params, >OtpErlangTuple, OtpErlangRef)]]>

+

+ + +

Call reference extraction is available by the client function :

+

OtpErlangRef __getRef()

+

instead for previous function :

+

OtpErlangRef _getReference(OtpErlangTuple)

+

+ + +

Server skeleton interface changes:

+ + +

The implementation function no longer have to contain the + two (2) contractor functions (with super()). This is due + to the fact that there is only one contractor function for each + skeleton file :

+

ImplBase()]]>

+

+ + +

The parameter for the caller identity extraction function _getCallerPid + is now an Environment variable instead for an OtpErlangTuple.

+

+ + +

There is a new invoke function :

+

OtpOutputStream invoke(OtpInputStream)

+

instead for the old one :

+

OtpErlangTuple invoke(OtpErlangTuple)

+

+ + +

The OtpConnection class function used for receiving messages is now :

+

OtpInputStream receiveBuf()

+

instead for the old one :

+

OtpErlangTuple receive()

+

+ + +

The OtpConnection class function used for sending messages is now :

+

void sendBuf(OtpErlangPid, OtpOutputStream)

+

instead for the old one :

+

void send(OtpErlangPid, OtpErlangTuple)

+

+ + +
+
+ +
+ IC 3.7.1 + +
+ Improvements and New Features +

Some memory usage optimizations for the compiler were done.

+
+ +
+ Fixed bugs and malfunctions + + +

A bug is fixed when C backend is used.

+

When C-union with enumerant discriminator, the size + calculation of the discriminator value were erroneous. + This lead to the side effect that only the first case of the + union were allowed. + The error were fixed by fixing the size calculation of + the discriminator.

+

Own Id: OTP-3215

+ + +
+
+ +
+ IC 3.7 +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed when C backend is used.

+

When unions with enumerant discriminator + were decoded, an error encountered in the + union size calculation.

+

Own Id: OTP-3209

+ + +
+
+ +
+ IC 3.6 +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed when NOC backend is used.

+

When several functions with the same name + were found in the included file tree, + a compile time failure occurred.

+

Own Id: OTP-3203

+ + +
+
+ +
+ IC 3.5 + +
+ Improvements and New Features + + +

Noc backend optimization

+

When NOC backend is choosen, the type code + information on the stub functions is reduced + to a single atom "no_tk". + This is the default behavior. The typecode + generation is enabled by the "use_tk" switch.

+

Own Id: OTP-3196

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

General java backend bug fixes

+

Protocol errors on user defined structures and + union types are corrected.

+ + +
+
+ +
+ IC 3.4 + +
+ Improvements and New Features + + +

Semantic test enhancements.

+

The compiler detects now semantic errors when enumerant + values collide with user defined types on the same name scope.

+

Own Id: OTP-3157

+

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

General java backend bug-fixes

+

Several bugs were fixed on user defined types.

+ + +

Union discriminators work better when + all possible case values are defined.

+ + +

A bug on Interface inherited operations is + fixed that cause errors on generated server switch.

+ + +

Type definitions on included files are better generated.

+ + +

Own Id: OTP-3156

+

+ + +
+
+ +
+ IC 3.3 + +
+ Improvements and New Features + + +

A new back-end which generates Java code according to the CORBA IDL to Java mapping for + communication with the Erlang distribution protocol has been added to IC. + For the moment there is no support for the Erlang types Pid, Ref, Port and Term + but this will be added later.

+

Own Id: OTP-2779

+

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

Fixed the bug that the c code backends sometimes generated incorrect code for + struct arguments. They shall always be pointers.

+

Own Id: OTP-2732

+

+ + +

The code generation is fixed so the array parameters now follow the + CORBA V2.0 C mapping.

+

Own Id: OTP-2873

+

+ + +

Fixed the problem that the checking of the numbers of out-parameters always was true.

+

Own Id: OTP-2944

+

+ + +

Fixed the bug that some temporary variables was not declared when c code.

+

Own Id: OTP-2950

+

+ + +
+
+ +
+ IC 3.2.2 + +
+ Improvements and New Features + + +

Unions are now supported to agree with OMG's C mapping.

+

Own Id: OTP-2868

+

+ + +

There is now a possibility to use pre- and postcondition methods on the server side + for IC generated Corba Objects. The compiler option is documented in the ic reference manual + and an example of how the pre- and postcondition methods should be designed and used is + added to ic example directory (an ReadMe.txt file exists with some instructions for + running the example code).

+

Own Id: OTP-3068

+

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

The compiler ignores unknown/non supported pragma directives. A warning is raised + while the generated code will then be the same as if the corresponding + (unknown) pragma directive were missing.

+

Own Id: OTP-3052

+

+ + +
+
+ +
+ IC 3.2.1 +
+ Fixed Bugs and Malfunctions + + +

Wrong C code was generated for limited strings when they where included + from another IDL specification.

+

Own Id: OTP-3033

+

+ + +
+
+ +
+ IC 3.2 +
+ Fixed Bugs and Malfunctions + + +

The buffers for in/output used by C-stubs are now expandable. + This fixes buffer overflow problems when messages received/sent + do not fit in buffers.

+

Own Id: OTP-3001

+

+ + +
+ +
+ Incompatibilities +

The CORBA_Environment structure has now two new fields, the buffers for in/output + must now be dynamically allocated.

+
+
+ +
+ IC 3.1.2 +
+ Fixed Bugs and Malfunctions + + +

The generated IFR registration function for constants has been fixed + so the parameters are correct.

+

Own Id: OTP-2856

+

+ + +

Error in the C code generation of ONEWAY operations without parameters + The bug was an decoding error in the operation header. The generated code expected one + parameter instead of zero. This is now fixed.

+

Own Id: OTP-2909

+

+ + +

Type problems on floats and booleans fixed.

+

Erroneous code for runtime checks on float was removed and + the internal format of the data representing the boolean value + is upgraded.

+

Own Id: OTP-2925

+

+ + +

The generated code for arrays of typedefined strings were + erroneous in the C-backends due to a failure in the compiler internal type + checking.

+

Own Id: OTP-2936

+

+ + +

The generated code for typedefined nested sequences were erroneous + in the C-backends. Pointer mismatches caused compilation failure.

+

Own Id: OTP-2937

+

+ + +
+ +
+ Incompatibilities +

The IDL specifications must be regenerated for C due to changes in the code generation.

+

One must regenerate IDL specifications for Erlang CORBA if there are constants in the + specification due to previous errors in the IFR registration functions (OTP-2856).

+
+
+ +
+ IC 3.1.1 + +
+ Improvements and New Features + + +

Improvements on error report on unsupported types by

+

propagating warning when declaring unions in C -backends

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed when arrays that contained variable size data + on C-backends

+

The compiler generated erroneous code when IDL + defined arrays that contained variable size data such + as strings, variable size structs or sequences.

+

Own Id: OTP-2900

+

+ + +

A bug is fixed when sequences that contained variable size data + on C_backends

+

The compiler generated erroneous code when IDL + defined arrays that contained variable size data such + as strings, variable size structs or other sequences.

+

Own Id: OTP-2901

+

+ + +

A bug concerning bounded strings on C-backends is fixed.

+

The compiler generated erroneous code for IDL + defined bounded strings. Syntax errors were generated + in special cases of typdedefined strings.

+

Own Id: OTP-2898

+

+ + +

A runtime error when sequences that contained integer types is fixed.

+

When C-clients/server that communicated with Erlang clients/servers, + and the data send by Erlang part were a list of small numbers, + the Erlang runtime compacts the list to a string. This caused a + runtime error when sending sequences of integer types and all had + value less than 256.

+

Own Id: OTP-2899

+

+ + +

An OMG IDL - C mapping problem on enumerant values is fixed.

+

The enumerant values names is now prefixed by the current scope, + as defined in the specification.

+

Own Id: OTP-2902

+

+ + +

A problem when using constants in array declarations is fixed.

+

Array dimensions declared with constants generated erroneous code.

+

Own Id: OTP-2864

+

+ + +
+ +
+ Incompatibilities + + +

Changes in C-generation on enumerant values.

+ + +
+
+ +
+ IC 3.1 +
+ Fixed Bugs and Malfunctions + + +

A bug is fixed on the generated structures.

+

The generated C code for the structures corresponds now + to direct mapping of C-structs.

+

Own Id: OTP-2843

+

+ + +
+ +
+ Incompatibilities + + +

Included structures inside a struct are no longer pointers.

+ + +
+
+ +
+ IC 3.0 + +
+ Improvements and New Features + + +

Interface change for C-backends

+

Major interface change. The new interface is CORBA 2.0 + compliant.

+

Own Id: OTP-2845

+

+ + +

The C-backends functionality is improved

+ + +

Due to interface change and some unneeded error + checks,the C-generated code is fairly optimized.

+ + + + +
+ +
+ Fixed Bugs and Malfunctions + + +

Several serious bugs on decoding and memory allocation are fixed.

+ + +
+ +
+ Incompatibilities + + +

Interface change on the C-backends

+

In order to be CORBA 2.0 compatible, the new version + generates fully incompatible C code.

+ + +
+
+ +
+ IC 2.5.1 + +
+ Improvements and New Features + + +

A new backend is added : C-server

+

This back-ends can be used to create servers, + compatible to c-clients, and Erlang genserver clients. + The code produced is a collection of functions for + encoding and decoding messages and a switch that coordinates + them. These parts can be used to create other servers as well. + All functions are exported to header files.

+

Own Id: OTP-2713

+

+ + +

The C-client functionality is improved

+ + +

The static buffer used for input/output is removed along + with the memset function that initiated it. + The new client is at least 20-30 percent faster.

+ + +

The internal structure of the client is changed. + The client functions are now a collection of encoding + and decoding message functions ruled by a specific + call function. While the basic client generated is + a synchronous client, the exported functions + support the implementation of threaded asynchronous + clients.

+ + +

The static buffer used for input/output is remove along + with the memset function that initiated it. + The new client is at least 20-30 percent faster.

+ + +

The code generated is generally improved, warnings are + (almost) eliminated, while no unidentified variable + errors occur.

+ + +

The IDL types unsigned shorts, shorts, floats are supported now.

+ + +

All generated functions are exported in client header files..

+ + +

Own Id: OTP-2712

+

+ + +
+ +
+ Changes in compiler usage and code generation. + + +

A new option is added for the C-server back-end : c_server.

+ + +

A new option is added : scoped_op_calls.

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

A bug oneway operations on erl_corba and erl_genserv that caused + en exit due to internal interface error is fixed.

+ + +

A bug on oneway operations on c_genserv back-end that caused several + variables to be unidentified is fixed.

+ + +
+ +
+ Incompatibilities + + +

Interface change on the C-client

+

The client functions are called with two extra variables, a pointer to + an array of char - used for storage and an integer - the array size

+ + +

The IDL type attribute is disabled, due to some implementation problems.

+ + +
+
+ +
+ IC 2.1 + +
+ Improvements and New Features + + +

The compiler now provides more in depth information (printouts) when errors occur.

+

In some cases the compiler stops compiling + due to an abnormal exit or incompatible input. + In this situation, a "fatal error" may occur but the compiler will + generate information explaining the problem.

+

Own Id: OTP-2565

+

+ + +
+
+ +
+ IC 2.0 + +
+ Improvements and New Features + + +

The IDL compiler is now a separate application and is longer a part of Orber.

+ + +

Pragma handling implementation.

+

Pragma ID, prefix + and version are implemented to agree with CORBA revision + 2.0. The compiler accepts and applies these on the + behavior of the compiled code.

+ In this implementation, + pragmas are accepted by the parser and applied by the use + of ic_pragma functions.

+ All IFR-identity handling now + passes through pragma table. As pragma handling in OMG-IDL + is affecting the identity of an ifr-object, all identity + handling and registration is now controlled by pragma + functions. A hash table called "pragmatab" contains vital + identity information used under compilation.

+

+

There two major pragma categories :

+ + +

Normal pragmas, are used in the code where + basic definitions and statements appear.

+ + +

Under certain circumstances, ugly pragmas can now + appear inside code, parameter lists, structure + definitions ... etc.

+ It is quite challenging to + allow ugly pragmas, but the effects of unlimited ugly + pragma implementation on the parser can be enormous. + Ugly pragmas can cause the parser source code to + become time consuming and user unreadable.

+ In order + to allow ugly pragmas but not destroy the current + structure of the parser, the use of ugly pragmas is + limited. Multiple pragma directives are allowed + inside parameter lists, unions, exceptions, + enumerated type, structures... as long as they are do not + appear between two keywords or between keywords and + identifiers.

+ + +

The pragma effect is the same for both scope and basic + pragma rules.

+

When compiling, an IFR-identity + must be looked up several times but by storing identity aliases inside + the pragma table there this an increase in both speed and + flexibility.

+

Own Id: OTP-2128

+

+ + +

Code for interface inheritance registration for the IFR + registration code .

+

Inherited interfaces can now + be registered as a list of interface descriptions by + entering code for inherited interface registration under + new interface creation. This is achieved by correcting the + function reg2/6 and adding two more functions, + get_base_interfaces/2 and call_fun_str/2

+

Own Id: + OTP-2134

+

+ + +

IFR registration checks for included IDL files.

+

All top level definitions (with respect to the scope) - + modules, interfaces, constants, types or exceptions - found + in an IDL file are either defined inside the compiled IDL + file or inside included files. + By having an extended registration of all top level + definitions it becomes possible to simply produce checks + for those included by the current IDL file. + A function call include_reg_test/1 is added in all + OE_* files that checks for IFR-registration on all included + IDL files. The code for that function is added inside the + OE_* file, while the function is called under OE_*:OE_register/0 + operation.

+

Own Id: OTP-2138

+

+ + +

Exception registration under IFR-operation creation.

+

By entering code for exception registration under operation + creation, the exceptions of an operation can be checked now. + This is done by correcting the function get_exceptions/4 + and adding two more functions, excdef/5 and get_EXC_ID/5 + ( the last two are cooperating with the first one and + all three are defined in the module "ictk" ).

+

Own Id: OTP-2102

+

+ + +

New back-end to IDL compiler : Plain Erlang.

+

The new back-end just translates IDL specifications + to Erlang module calls. No pragmas are allowed.

+

Own Id: OTP-2471

+

+ + +

New back-end to IDL compiler : generic server.

+

A new back-end that translates IDL specifications + to a standard OTP generic server.

+

Own Id: OTP-2482

+

+ + +

New back-end to IDL compiler : c client generation

+

A new back-end that translates IDL specifications + to a C API for accessing servers in Erlang.

+

Own Id: OTP-1511

+

+ + +

All records in generated files reveal own Erlang modules.

+

In Erlang related back-ends, every structure + which generates definition form is a record, + (such as union, struct, exception.... ). These records are + held in a generated Erlang files which + contain functions that reveal record information.

+ + The Erlang file which contain these functions is + named after the scope of the record (similar + to the generated module and interface files).

+ + Three functions are available :

+ + +

tc/0 - returns the record type code,

+ + +

id/0 - returns the record id,

+ + +

name - returns the record name.

+ + +

Own Id: OTP-2473

+

+ + +

Changes in compiler usage and code generation.

+ + +

New compilation flags. + New flag be ( = back-end ) which is + used by the compiler to choose back-end. + Default back-end is set to erl_corba.

+ + +

Stub files have an extra function oe_dependency/0 + indicating file dependency. This + helps the user to determine which IDL files should to + be compiled beside the compiled file.

+ + +

Own Id: OTP-2474

+

+ + +

The IDL generation for CORBA is changed so standard gen_server return values can be used + from the implementation module. The change is compatible so that old values remain valid.

+

Own Id: OTP-2485

+

+ + +

It's now possible to generate an API to a CORBA object that accepts + timeout values in the calls in the same manner as gen_server. + The option to the compiler is "timeout".

+

Own Id: OTP-2487

+

+ + +
+ +
+ Fixed Bugs and Malfunctions + + +

Empty file generation problem is fixed. + When the IDL module definition did not contain + constant definitions, the generated stub file for that module + definition was empty. After checking the module body, + these files will not be generated anymore.

+ + +
+ +
+ Incompatibilities + + +

Changes in generated files.

+

Stub-files generated by the compiler had + prefix "OE_" and those used by Orber + had also a register/unregister function + called "OE_register"/"OE_unregister" and + a directive "OE_get_interface" passed + to the gen_server. + This made it difficult/irritating to use, + for example call to the register function + in Orber would appear as shown below:

+ + +

'OE_filename':'OE_register'().

+ + +

This is changed by using the prefix "oe_" + instead for "OE_" for the above. + A registration call in Orber is now written:

+ + +

oe_filename:oe_register().

+ + +

Own Id: OTP-2440

+

+ + +
+
+ + diff --git a/lib/ic/doc/src/part.xml b/lib/ic/doc/src/part.xml new file mode 100644 index 0000000000..376a0b3455 --- /dev/null +++ b/lib/ic/doc/src/part.xml @@ -0,0 +1,45 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IC User's Guide + + + 1998-08-07 + 2.1 +
+ +

The IC application is an Erlang implementation of an IDL + compiler.

+ + + + + + + + + + + + + diff --git a/lib/ic/doc/src/part_notes.xml b/lib/ic/doc/src/part_notes.xml new file mode 100644 index 0000000000..0aac643c7d --- /dev/null +++ b/lib/ic/doc/src/part_notes.xml @@ -0,0 +1,37 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + Idl Compiler Release Notes + + + 1998-05-06 + 2.1 +
+ +

The IDL + Compiler Application is an Erlang implementation of a compiler for the IDL language. +

+ + + + diff --git a/lib/ic/doc/src/ref_man.gif b/lib/ic/doc/src/ref_man.gif new file mode 100644 index 0000000000..b13c4efd53 Binary files /dev/null and b/lib/ic/doc/src/ref_man.gif differ diff --git a/lib/ic/doc/src/ref_man.xml b/lib/ic/doc/src/ref_man.xml new file mode 100644 index 0000000000..153b25c609 --- /dev/null +++ b/lib/ic/doc/src/ref_man.xml @@ -0,0 +1,38 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + IC Reference Manual + + + 2003-12-16 + PB1 +
+ +

The IC application is an Erlang implementation of an IDL + compiler.

+ + + + + + diff --git a/lib/ic/doc/src/summary.html.src b/lib/ic/doc/src/summary.html.src new file mode 100644 index 0000000000..cb92e51791 --- /dev/null +++ b/lib/ic/doc/src/summary.html.src @@ -0,0 +1 @@ +IDL compiler diff --git a/lib/ic/doc/src/user_guide.gif b/lib/ic/doc/src/user_guide.gif new file mode 100644 index 0000000000..e6275a803d Binary files /dev/null and b/lib/ic/doc/src/user_guide.gif differ -- cgit v1.2.3