merging the tips sections.

Signed-off-by: Kristof Szabados <Kristof.Szabados@ericsson.com>

usrguide/java_referenceguide/14-tips_&_troubleshooting.adoc → usrguide/java_referenceguide/13-tips_&_troubleshooting.adoc

@@ -4,6 +4,22 @@
 
 Information not fitting in any of the previous chapters is given in this chapter.
 
+== Type Aliasing
+
+Type aliasing in TTCN–3 means that you can assign an alternative name to an existing type. The syntax is similar to a subtype definition, but the subtype restriction tag (value list or length restriction) is missing.
+
+`type MyType MyAlternativeName;`
+
+The type aliasing is implemented in the test executor, and it translates this TTCN–3 definition to a Java class extension.
+
+`public static class MyAlternativeName extends MyType { }`
+
+`public static class MyAlternativeName_template extends MyType_template { }`
+
+To keep in line with the C side, a semantic error will be reported when a port allows sending or receiving both of the types.
+
+As a work-around to this problem you can repeat the definition of the original type using the alternative name instead of type aliasing. In this case two differently named, but identical classes will be generated and the polymorphism problem will not occur.
+
 [[using-external-c-functions-in-ttcn-3-test-suites]]
 == Using External Java Functions in TTCN–3 Test Suites
 
@@ -83,7 +99,7 @@ Using templates as formal parameters in external functions is possible, but not
 
 The formal parameters of external TTCN–3 functions are mapped to Java function parameters according to the following table:
 
-.TTCN–3 formal parameters and their {cpp} equivalents
+.TTCN–3 formal parameters and their Java equivalents
 
 [cols=",",options="header",]
 |==============================================
@@ -246,6 +262,64 @@ TTCN_Logger.begin_event(Severity.DEBUG_UNQUALIFIED);
 		}
 ----
 
+[[reusing-logged-values-or-templates-in-ttcn-3-code]]
+== Reusing Logged Values or Templates in TTCN–3 Code
+
+Writing templates can be time-consuming task. To save some time and work, you can use the logs of the messages already sent or received to write templates.
+
+If you would like to use a logged value in TTCN–3 code, then using the `logformat` utility (see the section 13.3 of the TITAN User Guide [13] about this utility) you have to follow these steps:
+
+. Start a text editor and open the (formatted) log file and the TTCN–3 source file.
+. Select and copy the desired value from the log file.
+. Paste the value at the corresponding position in the TTCN–3 code.
+. Finally, make the following changes:
++
+* The enumerated values are followed by their numerical equivalents within parentheses. Delete them including the parentheses.
++
+* If an octetstring value contains only visible ASCII characters, then the hexadecimal octetstring notation is followed by its character string representation between quotation marks and parentheses. Delete the character string (including the parentheses).
++
+* If a `record`, `set`, `record of` or `set of` value contains no fields or elements, then the logformat utility changes the value from `{}` to `{(empty)}` in the log. Delete the word (empty) (including parentheses).
+
+[[using-the-ttcn-3-preprocessing-functionality]]
+== Using the TTCN-3 Preprocessing Functionality
+
+NOTE: This feature, as preprocessors in general, should be avoided if not absolutely necessary.
+
+The Designer has some support for preprocessing preprocessable files according to the rules of the C preprocessor.
+
+The options governing how preprocessable files inside a project are preprocessed can be set via right clicking on the project and selecting "Properties"/"TITAN Java Project Properties" and in the window that appears on the "TTCN-3 Preprocessor" page and its sub-pages.
+
+* On the `Symbols (define, undefine)` page it is possible to define or undefine symbols that will be available for the preprocessor.
+
+* On the `Include directories` page it is possible to set a list of folders which will be used to find `#includ` -ed files, during preprocessing.
+
+Tips for using the preprocessor:
+
+* Don't. The preprocessor feature should only be used when absolutely necessary.
+
+** Several preprocessor features are used to generate or hide parts of the source code. This can make it harder for people to understand the code. Makes the use of advanced refactoring features unsafe.
+
+** The extra cost of preprocesing adds to the duration of the build process.
+
+** As several preprocessing feature are used to hide information from the tools, and external factors (like environmental variables, files included from outside) can have an effect on the result ... any modification will trigger a preprocessing of all the `.ttcnpp` files, the semantic checking of all modules directly or indirectly importing them, and probably the re-generation of the affected modules.
+
+* On the Java side there is no intermediate file generated as all of the processing steps are done in-memory for performance reasons.
+
+There are minor issues when precompiling TTCN-3 code with the preprocessor, these are resulting from the differences between the C and TTCN-3 languages. Tips for writing the `.ttcnpp` files:
+
+* Do not define the B, O and H macros, these letters are used as part of the bitstring, octetstring and hexstring tokens in TTCN-3, but the preprocessor will replace them.
+
+* There are some predefined macros in the preprocessor which will be always replaced, do not use any TTCN-3 identifier identical to these. These macros start with double underscore followed by uppercase letters. Some of the most common macros which might be useful:
+
+** – *FILE* This macro expands to the name of the current input file, in the form of a C string constant.
+** – *LINE* This macro expands to the current input line number, in the form of a decimal integer constant.
+** – *DATE* This macro expands to a string constant that describes the date on which the preprocessor is being run.
+** – *TIME* This macro expands to a string constant that describes the time at which the preprocessor is being run.
+
+When writing preprocessor directives keep in mind that within the directive the C preprocessor syntax is in use, not the TTCN-3. Operators such as `defined` or || can be used.
+
+Watch out for macro pitfalls, some well known are: side effects, misnesting, and operator precedence problems.
+
 == Error Recovery during Test Execution
 
 If a fatal error is encountered in the Test Port, you should throw a `TtcnError` exception to do the error handling. It has the following prototype in the Base Library:

usrguide/java_referenceguide/9-tips_&_troubleshooting.adoc

-= Tips & Troubleshooting
-:toc:
-
-This chapter deals with various topics, which could not have been assigned to any of the previous chapters.
-
-== Type Aliasing
-
-Type aliasing in TTCN–3 means that you can assign an alternative name to an existing type. The syntax is similar to a subtype definition, but the subtype restriction tag (value list or length restriction) is missing.
-
-`type MyType MyAlternativeName;`
-
-The type aliasing is implemented in the test executor, and it translates this TTCN–3 definition to a Java class extension.
-
-`public static class MyAlternativeName extends MyType { }`
-
-`public static class MyAlternativeName_template extends MyType_template { }`
-
-To keep in line with the C side, a semantic error will be reported when a port allows sending or receiving both of the types.
-
-As a work-around to this problem you can repeat the definition of the original type using the alternative name instead of type aliasing. In this case two differently named, but identical classes will be generated and the polymorphism problem will not occur.
-
-[[reusing-logged-values-or-templates-in-ttcn-3-code]]
-== Reusing Logged Values or Templates in TTCN–3 Code
-
-Writing templates can be time-consuming task. To save some time and work, you can use the logs of the messages already sent or received to write templates.
-
-If you would like to use a logged value in TTCN–3 code, then using the `logformat` utility (see the section 13.3 of the TITAN User Guide [13] about this utility) you have to follow these steps:
-
-. Start a text editor and open the (formatted) log file and the TTCN–3 source file.
-. Select and copy the desired value from the log file.
-. Paste the value at the corresponding position in the TTCN–3 code.
-. Finally, make the following changes:
-+
-* The enumerated values are followed by their numerical equivalents within parentheses. Delete them including the parentheses.
-+
-* If an octetstring value contains only visible ASCII characters, then the hexadecimal octetstring notation is followed by its character string representation between quotation marks and parentheses. Delete the character string (including the parentheses).
-+
-* If a `record`, `set`, `record of` or `set of` value contains no fields or elements, then the logformat utility changes the value from `{}` to `{(empty)}` in the log. Delete the word (empty) (including parentheses).
-
-[[using-the-ttcn-3-preprocessing-functionality]]
-== Using the TTCN-3 Preprocessing Functionality
-
-NOTE: This feature, as preprocessors in general, should be avoided if not absolutely necessary.
-
-The Designer has some support for preprocessing preprocessable files according to the rules of the C preprocessor.
-
-The options governing how preprocessable files inside a project are preprocessed can be set via right clicking on the project and selecting "Properties"/"TITAN Java Project Properties" and in the window that appears on the "TTCN-3 Preprocessor" page and its sub-pages.
-
-* On the `Symbols (define, undefine)` page it is possible to define or undefine symbols that will be available for the preprocessor.
-
-* On the `Include directories` page it is possible to set a list of folders which will be used to find `#includ` -ed files, during preprocessing.
-
-Tips for using the preprocessor:
-
-* Don't. The preprocessor feature should only be used when absolutely necessary.
-
-** Several preprocessor features are used to generate or hide parts of the source code. This can make it harder for people to understand the code. Makes the use of advanced refactoring features unsafe.
-
-** The extra cost of preprocesing adds to the duration of the build process.
-
-** As several preprocessing feature are used to hide information from the tools, and external factors (like environmental variables, files included from outside) can have an effect on the result ... any modification will trigger a preprocessing of all the `.ttcnpp` files, the semantic checking of all modules directly or indirectly importing them, and probably the re-generation of the affected modules.
-
-* On the Java side there is no intermediate file generated as all of the processing steps are done in-memory for performance reasons.
-
-There are minor issues when precompiling TTCN-3 code with the preprocessor, these are resulting from the differences between the C and TTCN-3 languages. Tips for writing the `.ttcnpp` files:
-
-* Do not define the B, O and H macros, these letters are used as part of the bitstring, octetstring and hexstring tokens in TTCN-3, but the preprocessor will replace them.
-
-* There are some predefined macros in the preprocessor which will be always replaced, do not use any TTCN-3 identifier identical to these. These macros start with double underscore followed by uppercase letters. Some of the most common macros which might be useful:
-
-** – *FILE* This macro expands to the name of the current input file, in the form of a C string constant.
-** – *LINE* This macro expands to the current input line number, in the form of a decimal integer constant.
-** – *DATE* This macro expands to a string constant that describes the date on which the preprocessor is being run.
-** – *TIME* This macro expands to a string constant that describes the time at which the preprocessor is being run.
-
-When writing preprocessor directives keep in mind that within the directive the C preprocessor syntax is in use, not the TTCN-3. Operators such as `defined` or || can be used.
-
-Watch out for macro pitfalls, some well known are: side effects, misnesting, and operator precedence problems.

usrguide/java_referenceguide/JavaReferenceGuide.adoc

@@ -58,14 +58,13 @@ ifdef::env-github,backend-html5[]
 * link:6-the_run-time_configuration_file.adoc[The Run-time Configuration File]
 * link:7-code_coverage_of_ttcn-3_modules.adoc[Code Coverage of TTCN-3 Modules]
 * link:8-the_ttcn-3_debugger.adoc[The TTCN-3 Debugger]
-* link:9-tips_&_troubleshooting.adoc[Tips & Troubleshootings]
-* link:10-test_ports.adoc[Test Ports]
-* link:11-logger_plug-ins.adoc[Logger Plug-ins]
-* link:12-encoding_and_decoding.adoc[Encoding and Decoding]
-* link:13-mapping_ttcn3_data_types_to_java_constructs.adoc[Mapping TTCN–3 Data Types to {cpp} Constructs]
-* link:14-tips_&_troubleshooting.adoc[Tips & Troubleshooting]
-* link:15-references.adoc[References]
-* link:16-abbreviations.adoc[Abbreviations]
+* link:9-test_ports.adoc[Test Ports]
+* link:10-logger_plug-ins.adoc[Logger Plug-ins]
+* link:11-encoding_and_decoding.adoc[Encoding and Decoding]
+* link:12-mapping_ttcn3_data_types_to_java_constructs.adoc[Mapping TTCN–3 Data Types to {cpp} Constructs]
+* link:13-tips_&_troubleshooting.adoc[Tips & Troubleshooting]
+* link:14-references.adoc[References]
+* link:15-abbreviations.adoc[Abbreviations]
 endif::[]
 
 
@@ -78,12 +77,11 @@ include::5-compiling_ttcn3_and_asn1_modules.adoc[leveloffset=+1]
 include::6-the_run-time_configuration_file.adoc[leveloffset=+1]
 include::7-code_coverage_of_ttcn-3_modules.adoc[leveloffset=+1]
 include::8-the_ttcn-3_debugger.adoc[leveloffset=+1]
-include::9-tips_&_troubleshooting.adoc[leveloffset=+1]
-include::10-test_ports.adoc[leveloffset=+1]
-include::11-logger_plug-ins.adoc[leveloffset=+1]
-include::12-encoding_and_decoding.adoc[leveloffset=+1]
-include::13-mapping_ttcn3_data_types_to_java_constructs.adoc[leveloffset=+1]
-include::14-tips_&_troubleshooting.adoc[leveloffset=+1]
-include::15-references.adoc[leveloffset=+1]
-include::16-abbreviations.adoc[leveloffset=+1]
+include::9-test_ports.adoc[leveloffset=+1]
+include::10-logger_plug-ins.adoc[leveloffset=+1]
+include::11-encoding_and_decoding.adoc[leveloffset=+1]
+include::12-mapping_ttcn3_data_types_to_java_constructs.adoc[leveloffset=+1]
+include::13-tips_&_troubleshooting.adoc[leveloffset=+1]
+include::14-references.adoc[leveloffset=+1]
+include::15-abbreviations.adoc[leveloffset=+1]
 endif::[]