Commit 07aba108 authored by balaskoa's avatar balaskoa
Browse files

Editorial changes in the documentation


Signed-off-by: default avatarbalaskoa <Jeno.Balasko@ericsson.com>
Change-Id: I20d0fc71b56bc44667269ec64ee6795a69513bb3
parent f439c66a
......@@ -22,7 +22,8 @@ If you have defined a TTCN–3 port type that you intend to use for internal com
WARNING: In this case you must not link the object file obtained from a previous Test Port skeleton to your executable test suite.
In the following we introduce two port type definitions: one for a message based and another one for a procedure based port. In our further examples we will refer to the test port skeletons generated according to these definitions given within the module called `MyModule`.
In the following we introduce two port type definitions: one for a message based and another one for a procedure based port.
In our further examples we will refer to the test port skeletons generated according to these definitions given within the module called `MyExample`.
== Message-based Example
......@@ -179,7 +180,7 @@ void MyMessagePort::outgoing_send(const CHARSTRING& /*send_par*/)
== Procedure-based Example
The definition of `MyProcedurePort` in module `MyModule`:
The definition of `MyProcedurePort` in module `MyExample`:
[source]
----
type port MyProcedurePort procedure
......@@ -190,7 +191,7 @@ type port MyProcedurePort procedure
};
----
The signature definitions are imported from a module called `MyModule2`, `noblock` is not used and exceptions are used so that every member function of the port class is generated for this example. If the keyword `noblock` is used the compiler will optimize code generation by not generating outgoing reply, incoming reply member functions and their argument types. If the signature has no exception outgoing raise, incoming exception member functions and related types will not be generated.
The signature definitions are imported from a module called `MyExample`, `noblock` is not used and exceptions are used so that every member function of the port class is generated for this example. If the keyword `noblock` is used the compiler will optimize code generation by not generating outgoing reply, incoming reply member functions and their argument types. If the signature has no exception outgoing raise, incoming exception member functions and related types will not be generated.
The port type `MyProcedurePort` can handle `call`, `getreply` and `catch` operations referencing the signatures `outProc` and `inoutProc`, and it can handle `getcall`, `reply` and `raise` operations referencing the signatures `inProc` and `inoutProc`.
......@@ -210,9 +211,9 @@ The generated skeleton header file (that is, `MyProcedurePort.hh`) will look as
#ifndef MyProcedurePort_HH
#define MyProcedurePort_HH
#include "MyModule.hh"
#include "MyExample.hh"
namespace MyModule {
namespace MyExample {
class MyProcedurePort : public MyProcedurePort_BASE {
public:
......@@ -261,7 +262,7 @@ The generated skeleton source file for `MyProcedurePort` (that is, `MyProcedureP
#include "MyProcedurePort.hh"
namespace MyModule {
namespace MyExample {
MyProcedurePort::MyProcedurePort(const char *par_port_name)
: MyProcedurePort_BASE(par_port_name)
......@@ -627,15 +628,15 @@ incoming_message(const CHARSTRING& incoming_par);
Receiving operations on procedure based ports is similar to receiving messages on message based ports. The difference is that there are different overloaded incoming functions for call, reply and raise operations called `incoming_call`, `incoming_reply` and `incoming_exception`, respectively. The event handler (when called) must recognize the type of operation on receiving and call one of these functions accordingly with one of the internal representations of the signature (see <<5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc #additional-non-standard-functions, Additional Non-Standard Functions>>).
In the examplefootnote:[In the example the signatures were defined in a different TTCN–3 module named MyModule2, as a consequence all types defined in that module must be prefixed with the {cpp} namespace name of that module.] the class `MyProcedurePort_BASE` has the following member functions for incoming operations:
In the examplefootnote:[In the example the signatures were defined in a different TTCN–3 module named MyExample, as a consequence all types defined in that module must be prefixed with the {cpp} namespace name of that module.] the class `MyProcedurePort_BASE` has the following member functions for incoming operations:
[source]
----
incoming_call(const MyModule2::inProc_call& incoming_par);
incoming_call(const MyModule2::inoutProc_call& incoming_par);
incoming_reply(const MyModule2::outProc_reply& incoming_par);
incoming_reply(const MyModule2::inoutProc_reply& incoming_par);
incoming_exception(const MyModule2::outProc_exception& incoming_par);
incoming_exception(const MyModule2::inoutProc_exception& incoming_par);
incoming_call(const MyExample::inProc_call& incoming_par);
incoming_call(const MyExample::inoutProc_call& incoming_par);
incoming_reply(const MyExample::outProc_reply& incoming_par);
incoming_reply(const MyExample::inoutProc_reply& incoming_par);
incoming_exception(const MyExample::outProc_exception& incoming_par);
incoming_exception(const MyExample::inoutProc_exception& incoming_par);
----
For example, if the event handler receives a call operation that refers to the signature called `inoutProc`, it has to fill the parameters of an instance of the class `inoutProc_call` with the received data. Then it has to call the function `incoming_call` with this object to place the operation into the queue of the port.
......@@ -701,34 +702,34 @@ If an `address` value was specified in the `to` clause of the corresponding TTCN
The outgoing operations of procedure based ports are also generated in the same way if the `address` extension is specified. These functions will also have an extra parameter. Based on our example, these will have the following form:
[source]
----
void outgoing_call(const MyModule2::outProc_call& call_par,
void outgoing_call(const MyExample::outProc_call& call_par,
const ADDRESS *destination_address);
void outgoing_call(const MyModule2::inoutProc_call& call_par,
void outgoing_call(const MyExample::inoutProc_call& call_par,
const ADDRESS *destination_address);
void outgoing_reply(const MyModule2::inProc_reply& reply_par,
void outgoing_reply(const MyExample::inProc_reply& reply_par,
const ADDRESS *destination_address);
void outgoing_reply(const MyModule2::inoutProc_reply& reply_par,
void outgoing_reply(const MyExample::inoutProc_reply& reply_par,
const ADDRESS *destination_address);
void outgoing_raise(const MyModule2::inProc_exception& raise_exception,
void outgoing_raise(const MyExample::inProc_exception& raise_exception,
const ADDRESS *destination_address);
void outgoing_raise(const MyModule2::inoutProc_exception& raise_exception,
void outgoing_raise(const MyExample::inoutProc_exception& raise_exception,
const ADDRESS *destination_address);
----
The other difference is in the `incoming_message` member function of class `MyMessagePort_BASE`, and in the incoming member functions of class `MyProcedurePort_BASE`. These have an extra parameter, which is a pointer to an `ADDRESS` value. The default value is set the NULL pointer. In our example of `MyMessagePort_BASE`:
[source]
----
void incoming_call(const MyModule2::inProc_call& incoming_par,
void incoming_call(const MyExample::inProc_call& incoming_par,
const ADDRESS *sender_address = NULL);
void incoming_call(const MyModule2::inoutProc_call& incoming_par,
void incoming_call(const MyExample::inoutProc_call& incoming_par,
const ADDRESS *sender_address = NULL);
void incoming_reply(const MyModule2::outProc_reply& incoming_par,
void incoming_reply(const MyExample::outProc_reply& incoming_par,
const ADDRESS *sender_address = NULL);
void incoming_reply(const MyModule2::inoutProc_reply& incoming_par,
void incoming_reply(const MyExample::inoutProc_reply& incoming_par,
const ADDRESS *sender_address = NULL);
void incoming_exception(const MyModule2::outProc_exception& incoming_par,
void incoming_exception(const MyExample::outProc_exception& incoming_par,
const ADDRESS *sender_address = NULL);
void incoming_exception(const MyModule2::inoutProc_exception& incoming_par,
void incoming_exception(const MyExample::inoutProc_exception& incoming_par,
const ADDRESS *sender_address = NULL);
----
......@@ -758,7 +759,9 @@ This section summarizes only the differences from the normal Test Port API:
* The Test Port header file must not include the generated header file of the corresponding TTCN–3 module. The common header file of the Base Library called TTCN3.hh shall be included instead. The source file of the Test Port may include any header file without restriction.
* The member functions of the Test Port may refer to {cpp} classes that are generated from user-defined message types and signatures. To avoid compilation failures the declarations of the referenced classes must be added to the beginning of the header file. At the moment the Test Port skeleton generator has a limitation that it cannot collect the class declarations from the port type, so they must be added manually. Please note that if a message type or signature is imported from another module the corresponding class declaration must be put into the appropriate namespace.
* The member functions of the Test Port may refer to {cpp} classes that are generated from user-defined message types and signatures.
To avoid compilation failures the declarations of the referenced classes must be added to the beginning of the header file.
At the moment the Test Port skeleton generator has a limitation that it cannot collect the class declarations from the port type, so they must be added manually. Please note that if a message type or signature is imported from another module the corresponding class declaration must be put into the appropriate namespace.
The following example shows the generated Test Port skeleton of a provider port type.
......@@ -791,7 +794,7 @@ Header file `MyMessagePort.hh`:
#include <TTCN3.hh>
// Note: Header file MyModule.hh must not be included into this file!
// Note: Header file MyExample.hh must not be included into this file!
// Class declarations were added manually
namespace MyOtherModule {
......@@ -799,7 +802,7 @@ namespace MyOtherModule {
class MyMessageType;
}
namespace MyModule {
namespace MyExample {
// signature MySignature was defined locally
class MySignature_call;
......@@ -851,9 +854,9 @@ Source file `MyMessagePort.cc`:
// add your member functions here.
#include "MyProviderPort.hh"
#include "MyModule.hh"
#include "MyExample.hh"
namespace MyModule {
namespace MyExample {
MyProviderPort_PROVIDER::MyProviderPort_PROVIDER(const char *par_port_name)
: PORT(par_port_name)
......
......@@ -8,11 +8,16 @@ The TTCN–3 language elements of the test suite are individually mapped into mo
[[mapping-of-names-and-identifiers]]
== Mapping of Names and Identifiers
In order to identify the TTCN–3 language elements in the generated {cpp} program properly, the names of test suite are translated to {cpp} identifiers according to the following simple rules.
In order to identify the TTCN–3 language elements in the generated {cpp} program properly,
the names of test suite are translated to {cpp} identifiers according to the following simple rules.
If the TTCN–3 identifier does not contain any underscore (_) character, its equivalent {cpp} identifier will be the same. For example, the TTCN–3 variable `MyVar` will be translated to a {cpp} variable called `MyVar`.
If the TTCN–3 identifier does not contain any underscore (_) character,
its equivalent {cpp} identifier will be the same.
For example, the TTCN–3 variable `MyVar` will be translated to a {cpp} variable called `MyVar`.
If the TTCN–3 identifier contains one or more underscore characters, each underscore character will be duplicated in the {cpp} identifier. So the TTCN–3 identifier `My_Long_Name` will be mapped to a {cpp} identifier called `My\__Long__Name`.
If the TTCN–3 identifier contains one or more underscore characters,
each underscore character will be duplicated in the {cpp} identifier.
So the TTCN–3 identifier `My_Long_Name` will be mapped to a {cpp} identifier called `My\__Long__Name`.
The idea behind this name mapping is that we may freely use the {cpp} identifiers containing one underscore character in the generated code and in the Test Ports as well. Otherwise name clashes can always happen because the name space of TTCN–3 and {cpp} is identical. Furthermore, the generated {cpp} language elements fulfill the condition that the scope of a translated {cpp} identifier is identical as the scope of the original TTCN–3 identifier.
......@@ -32,12 +37,14 @@ The compiler generates a {cpp} namespace for every TTCN–3 and ASN.1 module. Al
The definitions of the TTCN–3 Base Library do not use any namespace.
When accessing a {cpp} entity that belongs to a different module than the referring Test Port or external function is in the reference has to be prefixed with the namespace of the referenced module. For example, to access the {cpp} class that realizes type `MyType` defined in `MyModule1` from a Test Port that belongs to module `MyModule2` the reference shall be written as `MyModule1::MyType`.
When accessing a {cpp} entity that belongs to a different module than the referring Test Port or external function is in the reference has to be prefixed with the namespace of the referenced module. For example, to access the {cpp} class that realizes type `MyType` defined in module `MyExample1` from a Test Port that belongs to module `MyExample2` the reference shall be written as `MyExample1::MyType`.
[[predefined-ttcn-3-data-types]]
== Predefined TTCN–3 Data Types
There are some basic data types in TTCN–3 that have no equivalent data types in language C/{cpp} (for example bitstring, verdicttype). Other types have {cpp} equivalent, but the TTCN–3 executor must know whether a variable has a valid value or not because sending an unbound value must result in a dynamic test case error. Thus, in the TTCN–3 Base Library all basic data types of TTCN–3 were implemented as {cpp} classes. This section describes the member functions of these classes.
There are some basic data types in TTCN–3 that have no equivalent data types in language C/{cpp} (for example bitstring, verdicttype). Other types have {cpp} equivalent, but the TTCN–3 executor must know whether a variable has a valid value or not because sending an unbound value must result in a dynamic test case error.
Thus, in the TTCN–3 Base Library all basic data types of TTCN–3 were implemented as {cpp} classes.
This section describes the member functions of these classes.
=== `Integer`
......@@ -1935,6 +1942,12 @@ The class representing the exceptions of a signature (remote procedure) is simil
|`void log() const` |Puts the contents of the exception into the log.
|===================================================================================================================================================================================================================================
If an exception type is a user-defined type the field name will be constructed from the {cpp} namespace name of the module that the exception type resides in and the name of the {cpp} class that realizes the exception type. The two identifiers are glued together using a single underscore character. Please note that the namespace name is always present in the identifiers, even if the exception type is defined in the same module as the signature.
If an exception type is a user-defined type the field name will be constructed from the {cpp} namespace name of the module
that the exception type resides in and the name of the {cpp} class that realizes the exception type.
The two identifiers are glued together using a single underscore character.
Please note that the namespace name is always present in the identifiers,
even if the exception type is defined in the same module as the signature.
For example, if exception type `My_Record` is defined in module `My_Module` the respective field access functions will be named as `My\__Module_My__Record_field` and the associated enum value will be `MyProc_exception::ALT_My__Module_My__Record`.
For example, if exception type `My_Record` is defined in module `My_Module`
the respective field access functions will be named as `My\__Module_My__Record_field` and
the associated enum value will be `MyProc_exception::ALT_My\__Module_My__Record`.
......@@ -32,14 +32,14 @@ There are the standard library functions as well as other libraries in the {cpp}
Since version 1.4.pl1 the semantic analyzer of the compiler checks the import statements thoroughly. Therefore one cannot use the virtual {cpp} modules as before: {cpp} functions must be defined as external functions to be accessible from TTCN–3 modules.
For example, the following definitions make two {cpp} functions accessible from TTCN–3 module `MyModule` and from any other module that imports `MyModule`.
For example, the following definitions make two {cpp} functions accessible from TTCN–3 module `MyExample` and from any other module that imports `MyExample`.
[[example-ttcn-3-module-mymodule-ttcn]]
=== Example TTCN–3 Module (MyModule.ttcn)
[[example-ttcn-3-module-MyExample-ttcn]]
=== Example TTCN–3 Module (MyExample.ttcn)
[source]
----
module MyModule {
module MyExample {
[...]
external function MyFunction(integer par1, in octetstring par2)
return bitstring;
......@@ -49,7 +49,7 @@ module MyModule {
}
----
The compiler will translate those external function definitions to {cpp} function prototypes in the generated header file `MyModule.hh`:
The compiler will translate those external function definitions to {cpp} function prototypes in the generated header file `MyExample.hh`:
[source]
----
......
......@@ -40,7 +40,7 @@ ifdef::env-github,backend-html5[]
* link:3-logger_plug-ins.adoc[Logger Plug-ins]
* link:4-encoding_and_decoding.adoc[Encoding and Decoding]
* link:5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc[Mapping TTCN–3 Data Types to {cpp} Constructs]
* link:6-tips_&_troubleshooting.adoc[Tips & Troubleshooting]
* link:6-tips_and_troubleshooting.adoc[Tips & Troubleshooting]
* link:7-references.adoc[References]
* link:8-abbreviations.adoc[Abbreviations]
endif::[]
......@@ -52,7 +52,7 @@ include::2-test_ports.adoc[leveloffset=+1]
include::3-logger_plug-ins.adoc[leveloffset=+1]
include::4-encoding_and_decoding.adoc[leveloffset=+1]
include::5-mapping_ttcn3_data_types_to_c++_constructs.adoc[leveloffset=+1]
include::6-tips_&_troubleshooting.adoc[leveloffset=+1]
include::6-tips_and_troubleshooting.adoc[leveloffset=+1]
include::7-references.adoc[leveloffset=+1]
include::8-abbreviations.adoc[leveloffset=+1]
endif::[]
......@@ -58,12 +58,12 @@ This section describes the automatically generated `Makefile`, its structure, th
=== `Makefile` Generation
The `Makefile` for a project can be generated using the generator tool `ttcn3_Makefile gen` footnote:[Up to version 1.6pl4 Makefile generation was part of the compiler (using the -M option).]. A project usually consists of some TTCN–3 and ASN.1 modules and at least one test port and results in an executable test suite.
The `Makefile` for a project can be generated using the Makefile generator tool `ttcn3_makefilegen` footnote:[Up to version 1.6pl4 Makefile generation was part of the compiler (using the -M option).]. A project usually consists of some TTCN–3 and ASN.1 modules and at least one test port and results in an executable test suite.
`Makefile` generation is performed with the following command syntax:
[source,subs="+quotes"]
** $TTCN3_DIR/bin/ttcn3_Makefilegen [options] <Main module> {Module}* {Test_Port}* {Other_File}* **
** $TTCN3_DIR/bin/ttcn3_makefilegen [options] <Main module> {Module}* {Test_Port}* {Other_File}* **
* `[options]` can be one or more of the options that are listed in the TITAN Programmer's Technical Reference for link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[TITAN Programmer's Technical Reference for TITAN TTCN-3 Test Executor].
......@@ -81,7 +81,7 @@ For detailed content of the generated `Makefile`, refer to <<Makefile-Structure,
Before generating the `Makefile` the `Makefile` generator tries to figure out the file name, module type and module name for each argument automatically. It uses some heuristics which yield correct results in most cases, but not always. Typically, the algorithm works perfectly with shell wildcards. For example, if all source files reside in the same directory the following command will generate the right `Makefile`:
`*$TTCN3_DIR/bin/ttcn3_Makefilegen *.ttcn *.asn *.c**`
`*$TTCN3_DIR/bin/ttcn3_makefilegen *.ttcn *.asn *.c**`
The `Makefile` generator looks for an existing file for each argument. It tries the given argument without any suffix, then the following list of suffixes are tried in this order: `.ttcn`, `.ttcn3`, `.3mp`, `.ttcnpp`, `.ttcnin`, `.asn`, `.asn1`, `.cc`, `.c`, `.hh`, `.h`, `.cfg`, `.prj`. Once a file is found, the `Makefile` generator tries to guess its type as described below. If no suitable file is found for a given argument the `Makefile` generator prints an error message and exits.
......@@ -179,7 +179,7 @@ This section presents the internal structure of the generated `Makefile`.
For example, the following command will generate a `Makefile` for TTCN–3 test suite "Hello, world!", which can be found in binary distribution:
`*$TTCN3_DIR/bin/ttcn3_`Makefile`gen -gs MyExample.ttcn PCOType.cc MyExample.cfg*`
`*$TTCN3_DIR/bin/ttcn3_makefilegen -gs MyExample.ttcn PCOType.cc MyExample.cfg*`
The `Makefile` generator creates the `Makefile` with the following content:
[source]
......@@ -513,4 +513,10 @@ In parallel mode use `*-lttcn3-parallel-dynamic*` instead of
When running the executable, add the directory `$TTCN3_DIR/lib` to the system library path (which is specified in `/etc/ld.so.conf` on most of UNIX systems) or simply add it to the environment variable `LD_LIBRARY_PATH`.
From version 1.8pl2, `ttcn3_Makefilegen` supports the generation of (per module) shared objects. If this option is enabled with the `-l` command line switch, the project’s working directory (together with the central storage directories, if applicable) should be added to `LD_LIBRARY_PATH` in addition to `$TTCN3_DIR/lib`. Otherwise, the resulting executable may not run. If moving the executable from one machine to another, all the generated shared object (.so) files should be copied as well. For more information about the `–l` command line switch, please consult the link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[TITAN Programmer's Technical Reference for TITAN TTCN-3 Test Executor].
From version 1.8pl2, `ttcn3_makefilegen` supports the generation of (per module) shared objects. If this option is enabled with the `-l` command line switch,
the project’s working directory (together with the central storage directories,
if applicable) should be added to `LD_LIBRARY_PATH` in addition to `$TTCN3_DIR/lib`.
Otherwise, the resulting executable may not run.
If moving the executable from one machine to another,
all the generated shared object (.so) files should be copied as well.
For more information about the `-l` command line switch, please consult the link:https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide[TITAN Programmer's Technical Reference for TITAN TTCN-3 Test Executor].
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment