api technical reference for titan ttcn-3 test...

API Technical Reference for TITANTTCN-3 Test Executor

Jenő Balaskó

Version 6/198 17-CRL 113 200/7, Rev. A, 2020-05-29

Table of Contents1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1. Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.2. Target Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.3. Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2. Test Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.1. Generating the Skeleton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2. Message-based Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.3. Procedure-based Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.4. Test Port Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.4.1. Constructor and Destructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.4.2. Parameter Setting Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2.4.3. Map and Unmap Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.4.4. Start and Stop Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

2.4.5. Outgoing Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.4.6. Incoming Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.4.7. Additional Functions and Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.5. Support of address Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.6. Provider Port Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

2.7. Tips and Tricks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.7.1. Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.7.2. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

2.8. Setting timestamps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

2.8.1. Incoming operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

2.8.2. Outgoing operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

3. External Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4. Logger Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.1. Implementing Logger Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

4.2. Building Logger Plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

4.3. Event Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

4.4. Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

5. Encoding and Decoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5.1. The Common API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5.1.1. TTCN_EncDec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5.1.2. TTCN_Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5.1.3. Invoking the Coding Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

5.2. BER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5.2.1. Error Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

5.2.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

5.2.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

5.3. RAW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45


5.3.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

5.3.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

5.4. TEXT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48


5.4.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.4.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

5.5. XML Encoding (XER) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50


5.5.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

5.5.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

5.6. JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52


5.6.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.6.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

5.7. OER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55


5.7.2. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

5.7.3. Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

6. Mapping TTCN–3 Data Types to C++ Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

6.1. Mapping of Names and Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

6.2. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

6.3. Predefined TTCN–3 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

6.3.1. Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

6.3.2. Float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

6.3.3. Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

6.3.4. Verdicttype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

6.3.5. Bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

6.3.6. Hexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

6.3.7. Octetstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

6.3.8. Char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

6.3.9. Charstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

6.3.10. Universal char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

6.3.11. Universal charstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

6.3.12. Object Identifier Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

6.3.13. Component References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

6.3.14. Empty Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

6.4. Compound Data Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

6.4.1. Record and Set Type Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

6.4.2. Union Type Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

6.4.3. Record of Type Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

6.4.4. Set of Type Construct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

6.4.5. Enumerated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

6.4.6. The address Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

6.5. Predefined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

6.5.1. Integer to character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

6.5.2. Character to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.3. Integer to universal character. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.4. Universal character to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.5. Bitstring to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.6. Hexstring to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.7. Octetstring to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.8. Charstring to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

6.5.9. Integer to bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.10. Integer to hexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.11. Integer to octetstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.12. Integer to charstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.13. Length of string Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.14. Number of elements in a structured type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.15. The IsPresent Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.16. The IsChosen Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

6.5.17. The regexp Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.18. Bitstring to charstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.19. Hexstring to charstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.20. Octetstring to character string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.21. Character string to octetstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.22. Bitstring to hexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.23. Hexstring to octetstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.24. Bitstring to octetstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6.5.25. Hexstring to bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.26. Octetstring to hexstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.27. Octetstring to bitstring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.28. Integer to float . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.29. Float to integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.30. The Random Number Generator Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.31. The Substring Function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

6.5.32. Character string to float. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.5.33. The Replace Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.5.34. Octetstring to character string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.5.35. Character string to octetstring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.5.36. The Decompose Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

6.5.37. Additional Non-Standard Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

6.6. Using the Signature Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

6.6.1. The Representation of the Input Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

6.6.2. The Output Parameters and Return Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

6.6.3. Representation of Signature Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

6.7. Object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

7. Tips & Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

7.1. Migrating Existing C++ Code to the Naming Rules of Version 1.7 . . . . . . . . . . . . . . . . . . . . . . . . . 124

7.2. Using External C++ Functions in TTCN–3 Test Suites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

7.2.1. Example TTCN–3 Module (MyExample.ttcn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

7.3. Logging in Test Ports or External Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

7.3.1. Unbuffered Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

7.3.2. Buffered Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

7.3.3. Logging Format of TTCN-3 Values and Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

7.3.4. Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

7.4. Error Recovery during Test Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

7.5. Using UNIX Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

7.6. Mixing C and C++ Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

8. References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

9. Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Abstract

This document describes detailed information on the TITAN Application Programming Interface(API) on C++ level, advanced TTCN–3 programming, and background information on the TITANTTCN–3 Test Executor project.

Copyright

Copyright (c) 2000-2020 Ericsson Telecom ABAll rights reserved. This program and the accompanying materials are made available under theterms of the Eclipse Public License v2.0 that accompanies this distribution, and is available at

https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html.

Disclaimer

The contents of this document are subject to revision without notice due to continued progress inmethodology, design and manufacturing. Ericsson shall have no liability for any error or damage ofany kind resulting from the use of this document.

1

https://www.eclipse.org/org/documents/epl-2.0/EPL-2.0.html

Chapter 1. Introduction

1.1. OverviewThis document describes the TITAN API on C++ level. It is intended for users who write test portimplementation, external function implementation in language C++ and want to use the availableresources of TITAN.

Detailed information can be found on the following topics:

• test ports, the communication link between the TITAN Executor and System Under Test (SUT);

• built-in encoding and decoding functions;

• TTCN-3 data mapping to C++ constructs;

• troubleshooting for common TTCN-3 related issues and problems.

1.2. Target GroupsThis document is intended for advanced users of the TITAN API on C++ level.

1.3. Typographical ConventionsThis document uses the following typographical conventions:

Bold is used to represent graphical user interface (GUI) components such as buttons, menus, menuitems, dialog box options, fields and keywords, as well as menu commands. Bold is also used with’+’ to represent key combinations. For example, Ctrl+Click

The '/' character is used to denote a menu and sub-menu sequence. For example, File / Open.

Monospaced font is used represent system elements such as command and parameter names,program names, path names, URLs, directory names and code examples.

Bold monospaced font is used for commands that must be entered at the Command Line Interface(CLI), For example, ttcn3_start

2

Chapter 2. Test PortsThe C++ source code generated by the Compiler is protocol independent, that is, it does not containany device specific operations. To provide the connection between the executable test suite andSUT, that is, the physical interface of the test equipment[1], a so-called Test Port is needed.

The Test Port is a software library written in C++ language, which is linked to the executable testprogram. It maps the device specific operations to function calls specified in an API. This chapterdescribes the Test Port API in details.

2.1. Generating the SkeletonThe functions of Test Ports must be written by the user who knows the interface between theexecutable test suite and the test equipment. In order to make this development easier, theCompiler can generate Test Port skeletons. A Test Port belongs to one certain TTCN–3 port type, sothe skeleton is generated based on port type definitions.

A Test Port consists of two parts. One part is generated automatically by the Compiler, and it is putinto the generated C++ code. The user has nothing to do with this part.

The other part is a C++ class, which is written mainly by the user. This class can be found in aseparate C++ header and source file (their suffixes are .hh and .cc, respectively). The names of thesource files and the C++ class are identical to the name of the port type. Please note that the namemapping rules described in Mapping of Names and Identifiers also apply to these class and filenames.

During the translation, when the Compiler encounters a port type definition and the –t commandline switch is used, it checks whether the header and source files of Test Port exist in its workingdirectory. If none of them can be found there, the compiler generates the skeleton header andsource files for the corresponding test port automatically. This means, once you have generated(and possibly modified) a skeleton, it will never be overwritten. If you want to re-generate theskeleton, you must rename or remove the existing one.

If the list of message types/signatures of a TTCN-3 port type changes, the list of the Test Port classmember functions also needs to change. If the Test Port skeleton has been generated, it will not bemodified, resulting in build errors (C++ compile errors like "cannot declare variable of abstracttype"/"virtual functions are pure", or linker errors). In this case, the Test Port skeleton files shouldbe renamed/moved, the skeleton generated, and any user-written code should be copied back intothe newly generated source files.

If you have defined a TTCN–3 port type that you intend to use for internal communication only(that is, for sending and receiving messages between TTCN–3 test components), you do not need togenerate and compile an empty Test Port skeleton for that port type. Adding the attribute with{extension "internal"} to the port type definition in the TTCN–3 module disables the generationand use of a Test Port for the port type.

WARNINGIn this case you must not link the object file obtained from a previous Test Portskeleton to your executable test suite.

3

In the following we introduce two port type definitions: one for a message based and another onefor a procedure based port. In our further examples we will refer to the test port skeletonsgenerated according to these definitions given within the module called MyExample.

2.2. Message-based ExampleThe definition of MyMessagePort:

type port MyMessagePort message{ in octetstring; out integer; inout charstring;};

That is, the types integer and charstring can be sent, and octetstring and charstring can be receivedon port MyMessagePort.

The generated skeleton header file (that is, MyMessagePort.hh) will look as follows:

4

// This Test Port skeleton header file was generated by the// TTCN-3 Compiler of the TTCN-3 Test Executor version CRL 113 200/7 R1A// for U-ERICSSON\ethbaat (ethbaat@HU-00000670) on Wed May 11 14:49:55 2020

// Copyright (c) 2000-2020 Ericsson Telecom AB

// You may modify this file. Add your attributes and prototypes of your// member functions here.

#ifndef MyMessagePort_HH#define MyMessagePort_HH

#include "MyExample.hh"

namespace MyExample {

class MyMessagePort : public MyMessagePort_BASE {public: MyMessagePort(const char *par_port_name = NULL); ~MyMessagePort();

void set_parameter(const char *parameter_name, const char *parameter_value);

private: /* void Handle_Fd_Event(int fd, boolean is_readable, boolean is_writable, boolean is_error); */ void Handle_Fd_Event_Error(int fd); void Handle_Fd_Event_Writable(int fd); void Handle_Fd_Event_Readable(int fd); /* void Handle_Timeout(double time_since_last_call); */protected: void user_map(const char *system_port, Map_Params& params); void user_unmap(const char *system_port, Map_Params& params);

void user_start(); void user_stop();

void outgoing_send(const INTEGER& send_par); void outgoing_send(const CHARSTRING& send_par);};

} /* end of namespace */

#endif

And the generated skeleton source file, that is, MyMessagePort.cc, will be the following:

// This Test Port skeleton source file was generated by the

5

// TTCN-3 Compiler of the TTCN-3 Test Executor version CRL 113 200/7 R1A// for U-ERICSSON\ethbaat (ethbaat@HU-00000670) on Wed May 11 14:49:55 2020


// You may modify this file. Complete the body of empty functions and// add your member functions here.

#include "MyMessagePort.hh"


MyMessagePort::MyMessagePort(const char *par_port_name) : MyMessagePort_BASE(par_port_name){

}

MyMessagePort::~MyMessagePort(){

}

void MyMessagePort::set_parameter(const char * /*parameter_name*/, const char * /*parameter_value*/){

}

/*void MyMessagePort::Handle_Fd_Event(int fd, boolean is_readable, boolean is_writable, boolean is_error) {}*/

void MyMessagePort::Handle_Fd_Event_Error(int /*fd*/){

}

void MyMessagePort::Handle_Fd_Event_Writable(int /*fd*/){

}

void MyMessagePort::Handle_Fd_Event_Readable(int /*fd*/){

}

/*void MyMessagePort::Handle_Timeout(double time_since_last_call) {}*/

void MyMessagePort::user_map(const char * /*system_port*/, Map_Params& /*params*/){

6

}

void MyMessagePort::user_unmap(const char * /*system_port*/, Map_Params& /*params*/){

}

void MyMessagePort::user_start(){

}

void MyMessagePort::user_stop(){

}

void MyMessagePort::outgoing_send(const INTEGER& /*send_par*/){

}

void MyMessagePort::outgoing_send(const CHARSTRING& /*send_par*/){

}


2.3. Procedure-based ExampleThe definition of MyProcedurePort in module MyExample:

type port MyProcedurePort procedure{ in inProc; out outProc; inout inoutProc;};

The signature definitions are imported from a module called MyExample, noblock is not used andexceptions 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 generatingoutgoing reply, incoming reply member functions and their argument types. If the signature has noexception outgoing raise, incoming exception member functions and related types will not begenerated.

7

The port type MyProcedurePort can handle call, getreply and catch operations referencing thesignatures outProc and inoutProc, and it can handle getcall, reply and raise operations referencingthe signatures inProc and inoutProc.

The generated skeleton header file (that is, MyProcedurePort.hh) will look as follows:

8

// This Test Port skeleton header file was generated by the// TTCN-3 Compiler of the TTCN-3 Test Executor version 1.7.pre4 build 4// for Csaba Feher (ecsafeh@ehubuux110) on Tue Jul 29 18:53:35 2008



#ifndef MyProcedurePort_HH#define MyProcedurePort_HH

#include "MyExample.hh"


class MyProcedurePort : public MyProcedurePort_BASE {public: MyProcedurePort(const char *par_port_name = NULL); ~MyProcedurePort();


private: /* void Handle_Fd_Event(int fd, boolean is_readable, boolean is_writable, boolean is_error); */ void Handle_Fd_Event_Error(int fd); void Handle_Fd_Event_Writable(int fd); void Handle_Fd_Event_Readable(int fd); /* void Handle_Timeout(double time_since_last_call); */protected: void user_map(const char *system_port, Map_Params& params); void user_unmap(const char *system_port, Map_Params& params);


void outgoing_call(const outProc_call& call_par); void outgoing_call(const inoutProc_call& call_par); void outgoing_reply(const inProc_reply& reply_par); void outgoing_reply(const inoutProc_reply& reply_par);};


#endif

The generated skeleton source file for MyProcedurePort (that is, MyProcedurePort.cc) will be thefollowing:

9

// This Test Port skeleton source file was generated by the// TTCN-3 Compiler of the TTCN-3 Test Executor version 1.7.pre4 build 4// for Csaba Feher (ecsafeh@ehubuux110) on Tue Jul 29 18:53:35 2008


// You may modify this file. Complete the body of empty functions and// add your member functions here.

#include "MyProcedurePort.hh"


MyProcedurePort::MyProcedurePort(const char *par_port_name) : MyProcedurePort_BASE(par_port_name){

}

MyProcedurePort::~MyProcedurePort(){

}

void MyProcedurePort::set_parameter(const char *parameter_name, const char *parameter_value){

}

/*void MyProcedurePort::Handle_Fd_Event(int fd, boolean is_readable, boolean is_writable, boolean is_error) {}*/

void MyProcedurePort::Handle_Fd_Event_Error(int fd){

}

void MyProcedurePort::Handle_Fd_Event_Writable(int fd){

}

void MyProcedurePort::Handle_Fd_Event_Readable(int fd){

}

/*void MyProcedurePort::Handle_Timeout(double time_since_last_call) {}*/

10

void MyProcedurePort::user_map(const char *system_port, Map_Params& params){

}

void MyProcedurePort::user_unmap(const char *system_port, Map_Params& params){

}

void MyProcedurePort::user_start(){

}

void MyProcedurePort::user_stop(){

}

void MyProcedurePort::outgoing_call(const outProc_call& call_par){

}

void MyProcedurePort::outgoing_call(const inoutProc_call& call_par){

}

void MyProcedurePort::outgoing_reply(const inProc_reply& reply_par){

}

void MyProcedurePort::outgoing_reply(const inoutProc_reply& reply_par){

}


2.4. Test Port FunctionsThis section summarizes all possible member functions of the Test Port class. All of these functionsexist in the skeleton, but their bodies are empty.

The identical functions of both port types are:

• the constructor and the destructor

11

• the parameter setting function

• the map and unmap function

• the start and stop function

• descriptor event and timeout handler(s)

• some additional functions and attributes

The functions above will be described using an example of message based ports (MyMessagePort, alsointroducing the functions specific to message based port types). Using these functions is identical(or very similar) in procedure based Test Ports.

Functions specific to message based ports:

• send functions: outgoing send

• incoming functions: incoming message

• Functions specific to procedure based ports:

• outgoing functions: outgoing call, outgoing reply, outgoing raise

• incoming functions: incoming call, incoming reply, incoming exception

Both test port types can use the same logging and error handling mechanism, and the handling ofincoming operations on port MyProcedurePort is similar to receiving messages on port MyMessagePort(regarding the event handler).

2.4.1. Constructor and Destructor

The Test Port class belongs to a TTCN–3 port type, and its instances implement the functions of theport instances. That is, each Test Port instance belongs to the port of a TTCN–3 test component. Thenumber of TTCN–3 component types, port types and port instances is not limited; you may haveseveral Test Port classes and several instances of a given Test Port class in one test suite.

The Test Port instances are global and static objects. This means, their constructor and destructor iscalled before and after the test execution (that is, before the main function starts and after the mainfunction finishes). The name of a Test Port object is composed of the name of the correspondingcomponent type and the name of the port instance within the component type.

In case of parallel test execution, each TTCN–3 test component process has its own Test Portinstances of all ports defined in all component types within the entire test suite. Of course, only theTest Ports of the active component type are used, the member functions of other inactive Test Portinstances (except constructor and destructor) will never be called. Since all Test Port instances arestatic, their constructor and destructor is called only once on each host and in the Host Controllerprocess (outside its main function). The test component processes (that is, the child processes ofHost Controller) will get a copy of the initialized Test Port instances and no constructor will becalled again.

The Test Port class is derived from an abstract base class which can be found in the generated code.The base class implements, for instance, the queue of incoming messages.

The constructor takes one parameter containing the name of the port instance in a NUL character

12

terminated string. This string shall be passed further to the constructor of the base class as it can befound in the skeleton code. The default argument for the test port name is a NULL pointer, which isused when the test port object is a member of a port array.

WARNING

In case of port arrays the name of the test port is set after the constructor iscompleted. So the name of the test port should not be used in the constructor.The port name is always set correctly when any other member function iscalled.

The destructor does nothing by default. If some dynamically allocated attributes are added to thetest port class, one should free the memory and release all resources in the destructor.

WARNING

As the constructor and the destructor are called outside of main function, becareful when writing them. For instance, there is no way for error recovery;exit(3) call may result in a segmentation fault. If file descriptors are opened(and kept opened) here, the fork(2) system call of Host Controller will onlymultiply the file descriptors and not the kernel file structure. Therefore systemand library calls should be avoided here.

2.4.2. Parameter Setting Function

Test Port parameters[2] shall contain information which is independent from the TTCN3 test suite.These values shall not be used in the test suite at all. You can define them as TTCN–3 constants ormodule parameters, but these definitions are useless and redundant, and they must always bepresent when the Test Port is used.

For instance, using Test Port parameters can be used to convey configuration data (that is, someoptions or extra information that is necessary for correct operation) or lower protocol layeraddresses (for example, IP addresses).

Test Port parameters shall be specified by the user of executable tests in section[TESTPORT_PARAMETERS] of the run-time configuration file (see section [TESTPORT_PARAMETERS] inProgrammer’s Technical Reference). The parameters are maintained for each test port instanceseparately; wildcards can be used as well. In the latter case the parameter is passed to all Test Portmatching the wildcard.

Each Test Port parameter must have a name, which must be unique within the Test Port only. Thename must be a valid identifier, that is, it must begin with a letter and must containalphanumerical characters only.

All Test Port parameter values are interpreted by the test executor as character strings. Quotationmarks must be used when specifying the parameter values in the configuration file. Theinterpretation of parameter values is up to you: you can use some of them as symbolic values,numbers, IP addresses or anything that you want.

Before the test execution begins, all parameters belonging to the Test Port are passed to the TestPort by the runtime environment of the test executor using the function set_parameter. It is a virtualfunction, that is, this function may be removed from the header and source file if there are noparameters. Its default ancestor does nothing and ignores all parameters.

13

https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide

Each parameter is passed to the Test Port one-by-one separately[3], the two arguments ofset_parameter contain the name and value of the corresponding parameter, respectively, in NULcharacter terminated strings. If the parameter values are needed in further operations, backupcopies must be made of them because the string will disappear after the calling function returns.

It is warmly recommended that the Test Port parameter handling functions be fool-proof. Forinstance, the Test Port should produce a proper error message (for example by calling TTCN_error) ifa mandatory parameter is missing instead of causing segmentation fault. Repeated setting of thesame parameter should produce warnings for the user (for example by using the functionTTCN_warning) and not memory leaks.

NOTE

On the MTC, in both single and parallel modes, the handling of Test Port parametersis a bit different from that on PTCs. The parameters are passed only to active ports,but the component type of MTC (thus the set of active ports) depends on the runs onclause of the test case that is currently being executed. It would be difficult for theruntime environment to check at the beginning of each test case whether thecorresponding MTC component type has already been active during a previous testcase run. Therefore all Test Port parameters belonging to the active ports of the MTCare passed to the set_parameter function at the beginning of every test case. The TestPorts of MTC shall be prepared to receive the same parameters several times (withthe same values, of course) if more than one test case is being executed.

If system related Test Port parameters are used in the run-time configuration file (that is, thekeyword system is used as component identifier), the parameters are passed to your Test Portduring the execution of TTCN–3 map operations, but before calling your user_map function. Pleasenote that in this case the port identifier of the configuration file refers to the port of the test systeminterface that your port is mapped to and not the name of your TTCN–3 port.

The name and exact meaning of all supported parameters must be specified in the userdocumentation of the Test Port.

2.4.3. Map and Unmap Functions

The run-time environment of the TTCN–3 executor knows nothing about the communicationtowards SUT, thus, it is the user’s responsibility to establish and terminate the connection with SUT.The TTCN–3 language uses two operations to control these connections, map and unmap.

For this purpose, the Test Port class provides two member functions, user_map and user_unmap. Thesefunctions are called by the test executor environment when performing TTCN–3 map and unmapoperations, respectively.

The map and unmap operations take two pairs of component references and ports as arguments.These operations are correct only if one of the arguments refer to a port of a TTCN–3 testcomponent while the other port corresponds to SUT. This aspect of correctness is verified by therun-time environment, but the existence of a system port is not checked.

The port names of the system are converted to NUL character terminated strings and passed tofunctions user_map and user_unmap as parameters. Unlike other identifiers, the underscorecharacters in these port names are not translated.

14

If these system port names should be reused later, the entire strings (and not only the pointers)must be saved in the internal memory structures since the string values will disappear after theuser_map or user_unmap finishes.

NOTE

in TTCN–3 it is not allowed to map a test component port to several system ports atthe same time. The run-time environment, however, is not so strict and allows thisto handle transient states during configuration changes. In this case messages cannot be sent to SUT even with explicit addressing, but the reception of messages ispermitted. When putting messages into the input queue of the port, it is notimportant for the test executor (even for the TTCN–3 language) which port of thesystem the message is received from.

The execution of TTCN–3 test component that requested the mapping or unmapping is suspendeduntil your user_map or user_unmap functions finish. Therefore it is not allowed to block unnecessarilythe test execution within these functions.

When the Test Port detects an error situation during the establishment or termination of thephysical connection towards the SUT, the function TTCN_error shall be used to indicate the failure. Ifthe error occurs within user_map the run-time environment will assume that the connection withSUT is not established thus it will not call user_unmap to destroy the mapping during the errorrecovery procedure. If user_map fails, it is the Test Port writer’s responsibility to release all allocatedresources and bring the object variables into a stable state before calling TTCN_error. Withinuser_unmap the errors should be handled in a more robust way. After a minor failure it is better toissue a warning and continue the connection termination instead of panicking. TTCN_error shall becalled only to indicate critical errors. If user_unmap is interrupted with an error the run-timeenvironment assumes that the mapping has been terminated, that is, user_unmap will not be calledagain.

NOTEif either user_map or user_unmap fails, the error is indicated on the initiator testcomponent as well; that is, the respective map or unmap operation will also fail anderror recovery procedure will start on that component.

Parameters of the Map and Unmap Functions

Parameters can be sent to the user_map and user_unmap functions from TTCN code using the paramclause of the map and unmap operations.

The 'user_map` and user_unmap functions have a parameter of type Map_Params, which contains thestring representations of the in and inout parameters of the map/unmap operation. The stringrepresentations of out parameters are empty strings (as these are considered as being unbound at thebeginning of the map/unmap operation). After the user_map or user_unmap function ends and themapping/unmapping is concluded, the final values (string representations) of out and inoutparameters in the Map_Params object are sent back to the mapping/unmapping requestor.

The following member functions can be used to obtain or set data in the Map_Params object:

unsigned int get_nof_params() const

15

Returns the number of parameters in the object. This will either be zero (if the map or unmapoperation had no param clause) or the number of parameters specified in the system port typedefinition’s map param or unmap param clause.

const CHARSTRING& get_param(unsigned int p_index) const

Returns the string representation of the parameter at index p_index. This method shall be used toretrieve the values of in and inout parameters. The parameter indices start at 0. The order of theparameters is the same as their order of declaration. Default values of parameters areautomatically set by the runtime environment before the user_map/user_unmap call. The stringrepresentations retrieved with this function can be converted back to the parameter’s TTCN-3 typewith the predefined function string_to_ttcn.

void set_param(unsigned int p_index, const CHARSTRING& p_param)

Sets the string representation of the parameter at index p_index to the string p_param. This methodshall be used to set the final values of out and inout parameters. The string representation of aTTCN-3 value can be obtained using the predefined function ttcn_to_string. If the final value of anout or inout parameter is an empty string, then the variable used as parameter will remainunchanged. Otherwise its new value will be calculated by applying string_to_ttcn on the stringvalue set in the user_map or user_unmap function (this could cause dynamic test case errors if thestring representation is invalid).

Usage example:

Port type:

type port MyPort message { ... map param(in MyInParType in_par, inout MyInOutParType inout_par, out MyOutParTypeout_par)}

user_map function in port implementation:

16

void MyPort::user_map(const char * system_port, Map_Params& params){ if (params.get_nof_params() != 0) { // there were map parameters

// extract 'in' and 'inout' parameters MyInParType in_par; string_to_ttcn(params.get_param(0), in_par); MyInOutParType inout_par; string_to_ttcn(params.get_param(1), inout_par); MyOutParType out_par; // remains unbound

// do mapping ...

// update 'out' and 'inout' parameters params.set_param(1, ttcn_to_string(inout_par)); params.set_param(2, ttcn_to_string(out_par)); } else { // there were no map parameters

// do mapping ... }}

2.4.4. Start and Stop Functions

The Test Port class has two member functions: user_start and user_stop. These functions are calledwhen executing port start and port stop operations, respectively. The functions have noparameters and return types.

These functions are called through a stub in the base class, which registers the current state of theport (whether it is started or not). So user_start will never be called twice without calling user_stopor vice versa.

WARNING

From version 1.2.pl0 on (according to the latest TTCN–3 standard) all ports oftest components are started implicitly immediately after creation. Suchoperations must not be put in a user_start function blocking the execution fora longer period. This not only hangs the new PTC but the also component thatperformed the create operation (usually the MTC). All ports are stopped at theend of test cases or at PTC termination, even if stop statements are missing.

In functions user_start and user_stop the device should be initialized or shut down towards SUT(that is, the communications socket). Also the event handler should be installed or uninstalled (seelater).

17

2.4.5. Outgoing Operations

Outgoing operations are send (specific to message based ports); call, reply, and raise (specific toprocedure based ports).

Send Functions

The Test Port class has an overloaded function called outgoing_send for each outgoing message type.This function will be called when a message is sent on the port and it should be routed to thesystem (that is, SUT) according to the addressing semantics[4] of TTCN–3. The messages (implicitly orexplicitly) addressed to other test components are handled inside the test executor; the Test Portshave nothing to do with them. The function outgoing_send will be also called if the port has neitherconnections nor mappings, but a message is sent on it.

The only parameter of outgoing_send contains a read-only reference to the message in the internaldata representation format of the test executor. The access methods for internal data types aredescribed in XML Encoding (XER). The test port writer should encode and send the messagetowards SUT. For information on how to use the standard encoding functions like BER, pleaseconsult Logger Plug-ins. Sending a message on a not started port causes a dynamic test case error.In this case outgoing_send will not be called.

Call, Reply and Raise Functions

The procedure based Test Port class has overloaded functions called outgoing_call, outgoing_replyand outgoing_raise for each call, reply and raise operations, respectively. One of these functionswill be called when a port-operation is addressing the system (that is, SUT using the to systemstatement).

The only parameter of these functions is an internal representation of the signature parameters(and possibly its return value) or the exceptions it may raise. The signature classes are described inUsing the Signature Classes.

2.4.6. Incoming Operations

Incoming operations are receive incoming messages (specific to message based ports); call, replyand exception (specific to procedure based ports).

Descriptor Event and Timeout Handlers

The handling of incoming messages (or operations) is more difficult than sending. The executabletest program has two states. In the first state, it executes the operations one by one as specified inthe test suite (for example, it evaluates expressions, calls functions, sends messages, etc.). In theother state it waits for the response from SUT or for a timer to expire. This happens when theexecution reaches a blocking statement, that is, one of a stand-alone receive, done, timeoutstatements or an alt construct.

After reaching a blocking statement, the test executor evaluates the current snapshot of its timerand port queues and tries to match it with the reached statements and templates. If the matchingfails, the executor sleeps until something happens to its timers or ports. After waking up, it re-evaluates its snapshot and tries to match it again. The last two steps are repeated until the executor

18

finds the first matching statement. If the test executor realizes that its snapshot can never matchthe reached TTCN–3 statements, it causes a dynamic test case error. This mechanism prevents itfrom infinite blocking.

The test executor handles its timers itself, but it does not know anything about the communicationwith SUT. So each Test Port instance should inform the snapshot handler of the executor what kindof event the Test Port is waiting for. The event can be either the reception of data on one or morefile descriptors or a timeout (when polling is used) or both of them.

When the test executor reaches a blocking statement and any condition – for which the Test Portwaits – is fulfilled, the event handler will be called. First one has to get the incoming message oroperation from the operating system. After that, one has to decode it (and possibly decide its type).Finally, if the internal data structure is built, one has to put it into the queue of the port. This can bedone using the member function incoming_message if it is a message, and using incoming_call,incoming_reply or incoming_exception if it is an operation.

The execution must not be blocked in event handler functions; these must return immediatelywhen the message or operation processing is ready. In other words, always use non-blocking recv()system calls. In the case when the messages are fragmented (for instance, when testing TCP basedapplication layer protocols, such as HTTP), intermediate buffering should be performed in the TestPort class.

Event and timeout handling interface introduced in TITAN version 1.7.pl4

This descriptor event and timeout handling interface is the preferred interface for new Test Portdevelopment.

There are two possibilities to be notified about available events:

• Either the Handle_Fd_Event function has to be implemented, or

• Handle_Fd_Event_Readable, Handle_Fd_Event_Writable, and Handle_Fd_Event_Error.

Using Handle_Fd_Event allows receiving all events of a descripor in one function call. Using the otherthree event handler functions allows creating a more structured code.

All these functions are virtual. The unused event handler functions have to be left un-overridden.(When using the second alternative and the Test Port does not wait for all types of events (readable,writable, error) the handlers of the events – for which the Test Port does not wait – can be left un-overridden.)

The following functions can be used to add events to and remove events from the set of events forwhich the Test Port waits:

void Handler_Add_Fd(int fd, Fd_Event_Type event_mask = EVENT_ALL);void Handler_Add_Fd_Read(int fd);void Handler_Add_Fd_Write(int fd);void Handler_Remove_Fd(int fd, Fd_Event_Type event_mask = EVENT_ALL);void Handler_Remove_Fd_Read(int fd);void Handler_Remove_Fd_Write(int fd);

19

The first parameter in all of these functions is the file descriptor. Possible values of the event_maskare EVENT_RD, EVENT_WR, EVENT_ERR and combinations of these using bitwise or: "|".

Timeout notification can be received with the Handle_Timeout function. The parameter of thefunction indicates the time elapsed in seconds since its last call of this function or the latestmodification of the timer (whichever occurred later).

The timer can be set with the following function:

void Handler_Set_Timer(double call_interval, boolean is_timeout = TRUE, boolean call_anyway = TRUE, boolean is_periodic = TRUE);

call_interval is measured in seconds and specifies the time after which the Handle_Timeout functionwill be called. To stop the timer call_interval value: 0.0 has to be given.

is_timeout specifies if the timer has to be stopped when event handler is called. call_anyway ismeaningful when is_timeout is set to TRUE. In this case call_anyway indicates if the Handle_Timeoutfunction has to be called when event handler is called before the timer would expire. If call_anywayis TRUE the timeout handler will be called after the call of the event handlers and the timer will bestopped. is_periodic indicates if the timer has to be restarted instead of stopping when timerexpires or event handler is called and is_timeout and call_anyway are both TRUE.

Event handler for Test Ports developed for 1.7pl3 and earlier versions of TITAN

There is only one event handler function in each Test Port class called Event_Handler, which is avirtual member function. The run-time environment calls it when an incoming event arrives. Youcan install or uninstall the event handler by calling the following inherited member functions:

void Install_Handler(const fd_set *read_fds, const fd_set *write_fds, const fd_set *error_fds, double call_interval);void Uninstall_Handler();

Install_Handler installs the event handler according to its parameters. It takes four arguments,three pointers pointing to bitmasks of file descriptors and a timeout value. Some of the parameterscan be ignored, but ignoring all at the same time is not permitted.

The bitmasks are interpreted in the same way as in the select system call. They can be set using themacros FD_ZERO, FD_SET and FD_CLR. If the pointer is NULL, the bitmask is treated as zero. For furtherdetails see the manual page of select(2) or select(3).

The call interval value is measured in seconds. It means that the event handler function will becalled when the time elapsed since its last call reaches the given value. This parameter is ignoredwhen its value is set to zero or negative.

If you want to change your event mask parameters, you may simply call the functionInstall_Handler again (calling of Uninstall_Handler is not necessary).

Uninstall_Handler will uninstall your previously installed event handler. The stop port operation

20

also uninstalls the event handler automatically. The event handler may be installed or uninstalledin any Test Port member function, even in the event handler itself.

The prototype of the event handler function is the following:

void Event_Handler(const fd_set *r_fds, const fd_set *w_fds, const fd_set *e_fds, double time_since_last_call);

The function Event_Handler has four parameters. The first three of them are pointers to bitmasks offile descriptors as described above. They are the bitwise AND combination of bitmasks you havegiven to Install_Handler and the bitmasks given back by the last call of select. They can be usefulwhen waiting for data from many file descriptors, for example when handling more than one SUTmappings simultaneously, because there is no need to issue a select call again within the eventhandler.

NOTE

the pointers can be never NULL, they point to a valid memory area even if there areno file descriptors set in the bitmask. The last parameter contains the time elapsedsince the last call of the event handler measured in seconds. This value is alwayscalculated even if the call interval has not been set. If the Event_Handler is called thefirst time since its last installation, the time is measured from the call ofInstall_Handler.[5]

Receiving messages

The member function incoming_message of message based ports can be used to put an incomingmessage in the queue of the port. There are different polymorphic functions for each incomingmessage type. These functions are inherited from the base class. The received messages are loggedwhen they are put into the queue and not when they are processed by the test suite[6].

In our example the class MyMessagePort_BASE has the following member functions:

incoming_message(const OCTETSTRING& incoming_par);incoming_message(const CHARSTRING& incoming_par);

Receiving calls, replies and exceptions

Receiving operations on procedure based ports is similar to receiving messages on message basedports. The difference is that there are different overloaded incoming functions for call, reply andraise operations called incoming_call, incoming_reply and incoming_exception, respectively. Theevent handler (when called) must recognize the type of operation on receiving and call one of thesefunctions accordingly with one of the internal representations of the signature (see Additional Non-Standard Functions).

In the example[7] the class MyProcedurePort_BASE has the following member functions for incomingoperations:

21

6-mapping_ttcn3_data_types_to_c++_constructs.adoc .pdf#additional-non-standard-functions

6-mapping_ttcn3_data_types_to_c++_constructs.adoc .pdf#additional-non-standard-functions

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 calledinoutProc, it has to fill the parameters of an instance of the class inoutProc_call with the receiveddata. Then it has to call the function incoming_call with this object to place the operation into thequeue of the port.

The following table shows the relation between the direction of the message type or signature inthe port type definition and the incoming/outgoing functions that can be used. MyPort in the tableheader refers to MyMessagePort or MyProcedurePort in the example depending on the type of the port(message based or procedure based).

Table 1. Outgoing and incoming operations

MyPort::outgoing_ MyPort BASE::incoming_

send call reply raise message call reply exception

messagetype

in ○ ○ ○ ○ ● ○ ○ ○

out ● ○ ○ ○ ○ ○ ○ ○

inout ● ○ ○ ○ ● ○ ○ ○

signature

in ○ ○ ● ● ○ ● ○ ○

out ○ ● ○ ○ ○ ○ ● ●

inout ○ ● ● ● ○ ● ● ●

● supported

○ not supported

2.4.7. Additional Functions and Attributes

Any kind of attributes or member functions may be added to the Test Port. A file descriptor, whichyou communicate on, is almost always necessary. Names not interfering with the identifiersgenerated by the Compiler can be used in the header file (for example, the names containing oneunderscore character). Avoid using global variables because you may get confused when more thanone instances of the Test Port run simultaneously. Any kind of software libraries may be used in theTest Port as well, but included foreign header files may cause name clashes between the library andthe generated code.

In addition, the following protected attributes of ancestor classes are available:

Table 2. Protected attributes

22

Name Type Meaning

is_startedboolean

Indicates whether the Test Portis started.

handler_installedboolean

Indicates whether the eventhandler is installed.

port_name

const char*

Contains the name of the TestPort instance. (NUL characterterminated string)

Underscore characters are not duplicated in port name. In case of port array member instances thename string looks like this: "Myport_array[5]".

2.5. Support of address TypeThe special user-defined TTCN–3 type address can be used for addressing entities inside the SUT onports mapped to the system component. Since the majority of Test Ports does not need TTCN–3addressing and in order to keep the Test Port API backward compatible the support of address typeis disabled by default. To enable addressing on a particular port type the extension attribute"address" must be added to the TTCN–3 port type definition. In addition to component referencesthis extension will allow the usage address values or variables in the to or from clauses and senderredirects of port operations.

In order to use addressing, a type named address shall be defined in the same TTCN–3 module asthe corresponding port type. Address types defined in other modules of the test suite do not affectthe operation of the port type. It is possible to link several Test Ports that use different types foraddressing SUT into the same executable test suite.

Test Ports that support SUT addressing have a slightly different API, which is considered whengenerating Test Port skeleton. This section summarizes only the differences from the normal API.

In the communication operations the test port author is responsible for handling the addressinformation associated with the message or the operation. In case of an incoming message oroperation the value of the received address will be stored in the port queue together with thereceived message or operation.

The generated code for the port skeleton of message based ports will be the same, exceptoutgoing_send member function, which has an extra parameter pointing to an ADDRESS value. Withthe example given in Test Port Functions:

void outgoing_send(const INTEGER& send_par, const ADDRESS *destination_address);void outgoing_send(const CHARSTRING& send_par, const ADDRESS *destination_address);

If an address value was specified in the to clause of the corresponding TTCN–3 send operation thesecond argument of outgoing_send points to that value. Otherwise it is set to the NULL pointer. The

23

Test Port code shall be prepared to handle both cases.

The outgoing operations of procedure based ports are also generated in the same way if the addressextension is specified. These functions will also have an extra parameter. Based on our example,these will have the following form:

void outgoing_call(const MyExample::outProc_call& call_par, const ADDRESS *destination_address);void outgoing_call(const MyExample::inoutProc_call& call_par, const ADDRESS *destination_address);void outgoing_reply(const MyExample::inProc_reply& reply_par, const ADDRESS *destination_address);void outgoing_reply(const MyExample::inoutProc_reply& reply_par, const ADDRESS *destination_address);void outgoing_raise(const MyExample::inProc_exception& raise_exception, const ADDRESS *destination_address);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 inthe 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 ofMyMessagePort_BASE:

void incoming_call(const MyExample::inProc_call& incoming_par, const ADDRESS *sender_address = NULL);void incoming_call(const MyExample::inoutProc_call& incoming_par, const ADDRESS *sender_address = NULL);void incoming_reply(const MyExample::outProc_reply& incoming_par, const ADDRESS *sender_address = NULL);void incoming_reply(const MyExample::inoutProc_reply& incoming_par, const ADDRESS *sender_address = NULL);void incoming_exception(const MyExample::outProc_exception& incoming_par, const ADDRESS *sender_address = NULL);void incoming_exception(const MyExample::inoutProc_exception& incoming_par, const ADDRESS *sender_address = NULL);

If the event handler of the Test Port can determine the source address where the message or theoperation is coming from, it shall pass a pointer to the incoming function, which points to avariable that stores the address value. The given address value is not modified by the run-timeenvironment and a copy of it is created when the message or the operation is appended to the portqueue. If the event handler is unable to determine the sender address the default NULL pointer shallbe passed as second argument.

The address value stored in the port queue is used in receive, trigger, getcall, getreply, catch andcheck port operations: it is matched with the from clause and/or stored into the variable given in thesender redirect. If the receiving operation wants to use the address information of the first elementin the port queue, but the Test Port has not supplied it a dynamic testcase error will occur.

24

2.6. Provider Port TypesTest Ports that belong to port types marked with extension attribute "provider" have a slightlydifferent API. Such port types are used to realize dual-faced ports, the details of which can be foundin section "Dual-faced ports" in the Programmer’s Technical Reference.

The purpose of this API is to allow the re-use of the Test Port class with other port types markedwith attribute user or with ports with translation capability (Methods for Testing and Specification(MTS); The Testing and Test Control Notation version 3; TTCN-3 Language Extensions: Configurationand Deployment Support). The user port types may have different lists of incoming and outgoingmessage types. The transformations between incoming and outgoing messages, which are specifiedentirely by the attribute of the user port type, are done independently of the Test Port. The Test Portneeds to support the sending and reception of message types that are listed in the provider porttype.

The provider port can be accessed through the port which maps to the port with provider attribute.The get_provider_port() is a member function of the PORT class:

PORT* get_provider_port();

This function is useful when a reference to the provider type is needed. It returns the provider porttype for user ports and ports with translation capability. Otherwise returns NULL. The functioncauses dynamic testcase error when the port has more than one mapping, or the port has bothmappings and connections. The function’s return value must be manually cast to the correctprovider port type.

This section summarizes only the differences from the normal Test Port API:

• The name of the Test Port class is suffixed with the string _PROVIDER (for exampleMyMessagePort_PROVIDER instead of MyMessagePort).

• The base class of the Test Port is class PORT, which is part of the Base Library. Please note thatnormal Test Ports are also derived from class PORT, but indirectly through an intermediate classwith suffix _BASE.

• The member functions that handle incoming messages and procedure-based operations (that isincoming_message, incoming_call, incoming_reply and incoming_exception) must be defined in theheader file as pure virtual functions. These functions will be implemented in variousdescendant classes differently.

• The Test Port header file must not include the generated header file of the correspondingTTCN–3 module. The common header file of the Base Library called TTCN3.hh shall be includedinstead. The source file of the Test Port may include any header file without restriction.

• The member functions of the Test Port may refer to C++ classes that are generated from user-defined message types and signatures. To avoid compilation failures the declarations of thereferenced classes must be added to the beginning of the header file. At the moment the TestPort skeleton generator has a limitation that it cannot collect the class declarations from theport type, so they must be added manually. Please note that if a message type or signature isimported from another module the corresponding class declaration must be put into the

25


https://www.etsi.org/deliver/etsi_es/202700_202799/202781/01.04.01_60/es_202781v010401p.pdf



appropriate namespace.

The following example shows the generated Test Port skeleton of a provider port type.

Port type definition in TTCN–3 :

type port MyProviderPort mixed { inout MyMessage, MySignature;} with { extension "provider" }

Header file MyMessagePort.hh:

// This Test Port skeleton header file was generated by the// TTCN-3 Compiler of the TTCN-3 Test Executor version 1.7.pl0// for Janos Zoltan Szabo (ejnosza@EG70E00202E46JR)// on Wed Mar 7 18:14:33 2007



#ifndef MyProviderPort_HH#define MyProviderPort_HH

#include <TTCN3.hh>

// Note: Header file MyExample.hh must not be included into this file!// Class declarations were added manually

namespace MyOtherModule { // type MyMessageType was imported from MyOtherModule class MyMessageType;}


// signature MySignature was defined locallyclass MySignature_call;class MySignature_reply;class MySignature_exception;class MyProviderPort_PROVIDER : public PORT {public: MyProviderPort_PROVIDER(const char *par_port_name = NULL); ~MyProviderPort_PROVIDER();

26


void Event_Handler(const fd_set *read_fds, const fd_set *write_fds, const fd_set *error_fds, double time_since_last_call);

protected: void user_map(const char *system_port); void user_unmap(const char *system_port);


void outgoing_send(const MyOtherModule::MyMessage& send_par); void outgoing_call(const MySignature_call& call_par); void outgoing_reply(const MySignature_reply& reply_par); void outgoing_raise(const MySignature_exception& raise_exception); virtual void incoming_message( const MyOtherModule::MyMessage& incoming_par) = 0; virtual void incoming_call(const MySignature_call& incoming_par) = 0; virtual void incoming_reply(const MySignature_reply& incoming_par) = 0; virtual void incoming_exception( const MySignature_exception& incoming_par) = 0;};


Source file MyMessagePort.cc:

// This Test Port skeleton source file was generated by the// TTCN-3 Compiler of the TTCN-3 Test Executor version 1.7.pl0// for Janos Zoltan Szabo (ejnosza@EG70E00202E46JR)// on Wed Mar 7 18:14:33 2007// Copyright (c) 2000-2020 Ericsson Telecom AB// You may modify this file. Complete the body of empty functions and// add your member functions here.

#include "MyProviderPort.hh"#include "MyExample.hh"


MyProviderPort_PROVIDER::MyProviderPort_PROVIDER(const char *par_port_name) : PORT(par_port_name){}

MyProviderPort_PROVIDER::~MyProviderPort_PROVIDER(){

27

}

void MyProviderPort_PROVIDER::set_parameter(const char *parameter_name, const char *parameter_value){}

void MyProviderPort_PROVIDER::Event_Handler(const fd_set *read_fds, const fd_set *write_fds, const fd_set *error_fds, double time_since_last_call){}

void MyProviderPort_PROVIDER::user_map(const char *system_port){}

void MyProviderPort_PROVIDER::user_unmap(const char *system_port){}

void MyProviderPort_PROVIDER::user_start(){}

void MyProviderPort_PROVIDER::user_stop(){}

void MyProviderPort_PROVIDER::outgoing_send( const MyOtherModule::MyMessage& send_par){}

void MyProviderPort_PROVIDER::outgoing_call( const MySignature_call& call_par){}

void MyProviderPort_PROVIDER::outgoing_reply( const MySignature_reply& reply_par){}

void MyProviderPort_PROVIDER::outgoing_raise( const MySignature_exception& raise_exception){}


28

2.7. Tips and TricksThe following sections deal with logging and error handling in Test Ports.

2.7.1. Logging

Test Ports may record important events in the Test Executor log during sending/receiving orencoding/decoding messages. Such log messages are also good for debugging fresh code.

The Test Port member functions may call the functions of class TTCN_Logger. These functions aredetailed in Logging in Test Ports or External Functions.

If there are many points in the Test Port code that want to log something, it can be a good practiceto write a common log function in the Test Port class. We show here an example function, whichtakes its arguments as the standard C function printf and forwards the message to the TestExecutor’s logger:

#include <stdarg.h>// using in other member functions:// log("The value of i: %d", i);void MyPortType::log(const char *fmt, ...){ // this flag can be a class member, which is configured through a // test port parameter if (logging_is_enabled) { va_list ap; va_start(ap, fmt); TTCN_Logger::begin_event(TTCN_DEBUG); TTCN_Logger::log_event("Example Test Port (%s): ", get_name()); TTCN_Logger::log_event_va_list(fmt, ap); TTCN_Logger::end_event(); va_end(ap); }}

2.7.2. Error Handling

None of the Test Port member functions have return value like a status code. If a function returnsnormally, the run-time environment assumes that it has performed its task successfully. Thehandling of run-time errors is done in a special way, using C++ exceptions. This simplifies theprogram code because the return values do not have to be checked everywhere and dynamicallycreated complex error messages can be used if necessary.

If any kind of fatal error is encountered anywhere in the Test Port, the following function should becalled:

void TTCN_error(const char *err_msg, …);

29

7-tips_&_troubleshooting.pdf#logging-in-test-ports-or-external-functions

Its parameter should contain the description of the error in a NUL terminated string in the format ofprintf(3). You may pass further parameters to TTCN_error, if necessary. The function throws anexception, so it never returns. The exception is usually caught at the end of the test case or PTCfunction that is being executed. In case of error, the verdict of the component is set to error and theexecution of the test case or PTC function terminates immediately.

The exception class is called TC_Error. For performance reasons this is a trivial (empty) class, that is,it does not contain the error message in a string. The error string is written into the log file byTTCN_error immediately. Such type of exception should never be caught or thrown directly. If youwant to implement your own error handling and error recovery routines you had better use yourown classes as exceptions.

If you write your own error reporting function you can add automatically the name of the portinstance to all of your error messages. This makes the fault analysis for the end-users easier. In thefollowing example the error message will occupy two consecutive lines in the log since we can passonly one format string to TTCN_error.

void MyPortType::error(const char *msg, ...){ va_list ap; va_start(ap, msg); TTCN_Logger::begin_event(TTCN_ERROR); TTCN_Logger::log_event("Example Test Port (%s): ", get_name()); TTCN_Logger::log_event_va_list(msg, ap); TTCN_Logger::end_event(); va_end(ap); TTCN_error("Fatal error in Example Test Port %s (see above).", get_name());}

There is another function for denoting warnings (that is, events that are not so critical) with thesame parameter list as TTCN_error:

void TTCN_warning(const char *warning_msg, …);

This function puts an entry in the executor’s log with severity TTCN_WARNING. In contrast toTTCN_error, after logging the given message TTCN_warning returns and your test port can continuerunning.

2.8. Setting timestampsIn order to use the timestamp redirects (→ timestamp) described in chapter 5 of the TTCN-3 standardextension TTCN-3 Performance and Real Time Testing (ETSI ES 202 782 V1.3.1, [16]) the test portwriter needs to add extra code to set the timestamps for the incoming and outgoing port operationsof each port with the realtime clause.

30

2.8.1. Incoming operations

The timestamps of incoming port operations (receive, trigger, getcall, getreply, catch and check)need to be set when the incoming message or procedure is added to the queue.

The member functions incoming_message, incoming_call, incoming_reply and incoming_exception(which add the message/procedure to the queue) have an optional float parameter calledtimestamp, if the test port was declared with the realtime clause.

The value given to this parameter will be the one stored in the variable referenced in thetimestamp redirect, if the operation has a timestamp redirect (otherwise the value is ignored).

It is recommended that this parameter be set to the current test system time, which can be queriedwith TTCN_Runtime::now(), or to a float variable that was set to the current test system time earier inthe function.

Examples:

incoming_message(my_message, TTCN_Runtime::now());

FLOAT reply_time = TTCN_Runtime::now();

...

incoming_reply(my_reply, reply_time);

2.8.2. Outgoing operations

The timestamps of outgoing port operations (send, call, reply, raise) need to be set in the memberfunctions outgoing_send, outgoing_call, outgoing_reply and outgoing_raise.

These functions have a float pointer parameter called timestamp_redirect, if the test port wasdeclared with the realtime clause.

The value pointed to by this parameter will be the one stored in the variable referenced in thetimestamp redirect, if the operation has a timestamp redirect.

If it does not have a timestamp redirect, then this pointer parameter will be NULL. Because of this,the parameter must always have a null pointer check before it is assigned a value.

It is recommended that the value pointed to by the parameter be set to the current test system time,which can be queried with TTCN_Runtime::now().

Example:

31

if (timestamp_redirect != NULL) { *timestamp_redirect = TTCN_Runtime::now();}

NOTE

Because of this extra parameter, adding or removing the realtime clause from a portwill cause already-written C++ code for the port to no longer compile. In these casesthe new parameters must be manually added or removed from the mentionedfunctions, or the user-written code copied to newly-generated test port skeletons.

[1] The test equipment not necessarily requires a special hardware; it can even be a simple PC with an Ethernet interface.

[2] Test Port parameters have been introduced in version 1.1.pl3

[3] If the same parameter of the same port instance is specified several times in the configuration file, the function set_parameterwill also be called several times.

[4] That is, the port has exactly one mapping and either the port has no connections or the message is explicitly addressed by a send(…) to system statement.

[5] In versions of Test Executor older than 1.1 the event handler function had no parameters. If you want to upgrade a test portdeveloped for older versions, you should insert this formal parameter list to your event handler both in Test Port header andsource file. Otherwise the compilation of Test Port will fail.

[6] Note that if the port has connections as well, the messages coming from other test components will also be inserted into thesame queue independently from the event handler.

[7] In the example the signatures were defined in a different TTCN–3 module named MyExample, as a consequence all typesdefined in that module must be prefixed with the C++ namespace name of that module.

32

Chapter 3. External ClassesThere is currently no C++ skeleton generator for external classes, so any external classes have to beimplemented manually.

External class implementation must abide by the following rules:

• The file name, where the external class is declared, must be the name of the external classfollowed by .hh. Please note that the name mapping rules described in Mapping of Names andIdentifiers also apply to the class and file name. The implementations of class methods can be inany C++ source file that is linked to the executable test suite.

• The new .hh file must include the generated header file of the TTCN-3 module containing theexternal class declaration.

• The include to the new .hh file is already in the desired namespace in the generated C++ code, sono further namespaces are needed around the external class declaration.

• The external class must inherit the built-in C++ class OBJECT (object in TTCN-3).

• The C++ equivalents of all functions in the TTCN-3 external function declaration must be virtual.

• The class must also have a virtual destructor (even if it is empty).

• For more information about function parameters and return values of class types see ObjectReferences.

3.1. ExampleExample.ttcn:

type external class ExternalClass { public external function f_ext(in integer x) return charstring; external function f_ext2(inout OtherClass p);}

ExternalClass.hh:

33

#include "Example.hh"

#ifndef EXTERNALCLASS_HH#define EXTERNALCLASS_HH

// NOTE: no namespace specification needed, since the 'include' command is// already in the desired namespace!

class ExternalClass : public OBJECT {public: virtual CHARSTRING f__ext(const INTEGER& x);

protected: virtual void f__ext2(OBJECT_REF<OtherClass>& p);

public: virtual ~ExternalClass() { }

// additional members and methods

};

#endif

ExternalClass.cc:

#include "ExternalClass.hh"

namespace Example {

CHARSTRING ExternalClass::f__ext(const INTEGER& x){ // method implementation}

void ExternalClass::f__ext2(OBJECT_REF<OtherClass>& p){ // method implementation}

}

NOTEIf external class methods are implemented in a different C++ file, than thementioned new .hh file (such as ExternalClass.cc in this case), then they need to beplaced in the TTCN-3 module’s namespace.

34

Chapter 4. Logger Plug-ins

4.1. Implementing Logger Plug-insAll logger plug-ins must implement the ILoggerPlugin interface class in ILoggerPlugin.hh in${TTCN3_DIR}/include. Each plug-in should provide some essential information on itself and shouldimplement some basic functions:

The name (name_, plugin_name()) of the plugin. To be able to reference the plugin (for example forconfiguration). Additional information about the plug-in (help_, plugin_help()).

The minimum API version number the plug-in is compatible with (major_version_,major_version(), minor_version_, minor_version()).

Each plug-in must have an initialization (init()) and deinitialization (fini()) routine, which arecalled at the begin and end of the plug-in’s lifecycle. The same functionality can be implemented inthe plug-in’s constructor and destructor as well.

The plug-in could be asked, whether it’s configured or not (is_configured()). For example the file isalready opened, the database connection is set up etc. Depending on this information eventbuffering can be enabled or disabled.

One plug-in should provide log2str() functionality. The is_log2str_capable() function should beoverridden to return true. At the moment it’s not possible to change the default behavior andreturning true will not have an effect except a warning.

The logger plug-ins receive the log events via the log() function. The details about event handlingcan be found in 3.3.

The generated, runtime specific (load-test or function-test) header file TitanLoggerApi.hh needs to beincluded by every logger plug-in depending on the runtime it is compiled for. These header files canbe found in ${TTCN3_DIR}/include/{RT1/RT2}. An example to handle these include files in a loggerplug-in’s code:

#ifndef TITAN_RUNTIME_2

#include ``RT1/TitanLoggerApi.hh''

#else

#include ``RT2/TitanLoggerApi.hh''

#endif

Unfortunately, the dlopen() API is a C API, not a C++ API, but each logger plug-in is a class, whichneeds to be instantiated. To resolve this, the logger plug-ins are always instantiated and destroyedthrough C factory functions. These functions are mandatory for all logger plug-ins and they mustfollow C-style linkage rules. Otherwise, the function names would be mangled by the C++ compiler,

35

using its own, implementation dependent mangling mechanism, and dlsym() and such functionswould not be able to locate the correct symbol in the SOs of the logger plug-ins. These functionslook pretty simple:

#ifdef __cplusplusextern "C"{ ILoggerPlugin *create_plugin() { return new MyPlugin(); } void destroy_plugin(ILoggerPlugin *plugin) { delete plugin; plugin = NULL; }}#endif

4.2. Building Logger Plug-insThe generated, runtime specific (load-test or function-test) header file TitanLoggerApi.hh needs to beincluded by every logger plug-in depending on the runtime it is compiled for. These header files canbe found in ${TTCN3_DIR}/include/{RT1/RT2} and this directory must be present (for example as partof CPPFLAGS in the Makefile) while compiling the logger plug-ins.

To make logger plug-ins dynamically loadable at runtime the logger plug-ins need to be built asshared libraries. Physically SOs (.so) on Unix and Linux platforms, DLLs (.dll) on Cygwin andWindows platforms. A HOWTO on building shared libraries can be found at David A. Wheeler,Program Library HOWTO. A quick summary:

All the sources of the logger plug-ins need to be compiled with –fPIC, for example add CXXFLAGS +=-fPIC into the Makefile or command line.

The linker should be instructed to create a shared library instead of an executable with the –sharedflag. –fPIC is necessary here as well, for example add LDFLAGS += -fPIC –shared in the Makefile orcommand line.

Another thing to keep in mind is that logger plug-ins need to be linked with the dynamically linkedTITAN runtime libraries (for example libttcn3-dynamic.so/libttcn3-parallel-dynamic.so orlibttcn3-rt2-dynamic.so/libttcn3-rt2-parallel-dynamic.so) instead of the static ones (for examplelibttcn3.a/libttcn3-parallel.a or libttcn3-rt2.a/libttcn3-rt2-parallel.a). So, if all possiblecombinations need to be supported by a logger plug-in, all of the four versions need to be built,additionally there are naming rules to simplify making a distinction between them:

• Single mode, load test runtime. File name must end with ".so".

• Single mode, function test runtime. File name must end with "-rt2.so".

• Parallel mode, load test runtime. File name must end with "-parallel.so".

• Parallel mode, function test runtime. File name must end with "-parallel-rt2.so".

The runtime library linked with a logger plug-in must be selected to match the runtime linked withthe test executable that loads it: if the test executable is linked to libttcn3-dynamic.so, then any

36

http://tldp.org/HOWTO/Program-Library-HOWTO/index.html


logger plug-ins must also be linked to libttcn3-dynamic.so and not libttcn3-parallel-dynamic.so orlibttcn3-rt2-dynamic.so. To ensure consistency, only a dynamic runtime library will load a loggerplug-in (because a plug-in is always linked to a dynamic runtime library). If a non-dynamic runtimelibrary is configured to load a logger plug-in, it will cause a runtime error.

Please note that linking a plug-in or any TTCN-3 project with the object files generated from theTitanLoggerApi or TitanLoggerControl internal modules and using the dynamic libraries of TITAN atthe same time is not recommended and it can lead to various runtime errors.

4.3. Event HandlingThe log events are distributed to all active logger plug-ins via a four-parameter callback functionwith the following signature:

void log(const TitanLoggerApi::TitanLogEvent& event, bool log_buffered, bool separate_file, bool use_emergency_mask);

The first parameter event is the event itself, the second parameter log_buffered indicates, whetherthe event is coming from an internal buffer or not, separate_file and use_emergency_mask areconfiguration options for emergency logging. The use_emergency_mask flag indicates that the givenevent is an emergency event and should be handled in a special way by the plug-ins, theseparate_file flag indicates that all the emergency events should be handled separately (forexample written into a separate file). For more details on emergency logging please checkProgrammer’s Technical Reference. In this function, the plug-in can handle the log eventsindividually depending on the event’s type (that is, the alternative selected in the unionevent.logEvent().choice()).

TitanLoggerApi::TitanLogEvent is a generated type defined in TitanLoggerApi.xsd, which can befound in ${TTCN3_DIR}/include. This file contains all the necessary type definitions a logger plug-inshould be aware of. The corresponding header files generated from this XSD file can be found in${TTCN3_DIR}/include/{RT1/RT2}. The mapping between TTCN-3 types and C++ types is defined inMapping TTCN–3 Data Types to C++ Constructs.

4.4. ExecutionWhen a logger plug-in is compiled (the SO is ready) it should be configured in the configuration file.For details check Programmer’s Technical Reference. Additionally, LD_LIBRARY_PATH should containthe directory of the plug-in and ${TTCN3_DIR}/lib as well. If the runtime linker (the loader) is unableto find any of the given logger plug-ins an error will be given.

37


5-mapping_ttcn3_data_types_to_c+\+_constructs.adoc


Chapter 5. Encoding and DecodingThis tool is equipped with several standard encoding/decoding mechanisms. A part of thesefunctions reside in the core library, but the type-dependent part must be generated by the compiler.In order to reduce the code size and compilation time, the code generation for encoding functions(separately for different encoders) can be switched off if they are not needed. For details, seesection "Command line syntax" in the Programmer’s Technical Reference.

To make it easier to use the encoding features, a unified common API was developed. With help ofthis API the behaviour of the test executor in different error situations can be set during coding.There is also a common buffer class. The details of the above mentioned API as well as the specificfeatures of the certain encoders are explained in the following sections.

5.1. The Common APIThe common API for encoders consists of three main parts:

• A dummy class named TTCN_EncDec which encapsulates functions regarding error handling.

• A buffer class named TTCN_Buffer which is used by the encoders to put data in, decoders to getdata from.

• The functions needed to encode and decode values.

5.1.1. TTCN_EncDec

TTCN_EncDec implements error handling functions.

Setting Error Behavior

There are lot of error situations during encoding and decoding. The coding functions can be toldwhat to do if an error arises. To set the behaviour of test executor in a certain error situation thefollowing function is to be invoked:

void TTCN_EncDec::set_error_behavior(error_type_t, error_behavior_t);

WARNINGAs error_type_t and error_behavior_t are enums defined in TTCN_EncDec class,they have to prefixed with the class name and the scope operator (that isTTCN_EncDec::).

The possible values of error_type_t are detailed in the sections describing the different codings.Some common error types are shown in the table below:

Table 3. Common error types

ET_UNDEF Undefined/unknown error.

ET_UNBOUND Encoding of an unbound value.

38


ET_UNDEF Undefined/unknown error.

ET_REPR Representation error (for example, internal representation ofintegral numbers).

ET_ENC_ENUM Encoding of an unknown enumerated value.

ET_DEC_ENUM Decoding of an unknown enumerated value.

ET_INCOMPL_MSG Decode error: incomplete message.

ET_INVAL MSG Decode error: invalid message.

ET_CONSTRAINT The value breaks some constraint.

ET_INTERNAL Internal error. Error behaviour cannot be set for this.

ET_ALL All error type. Usable only when setting error behaviour.

ET_NONE No error.

The possible values of error_behavior_t are shown in the table below:

Table 4. Possible values of error_behavior_t

EB_DEFAULT Sets the default error behaviour for the selected error type.

EB_ERROR Raises an error if the selected error type occurs.

EB_WARNING Gives a warning message but tries to continue the operation.

EB_IGNORE Like warning but without the message.

Getting Error Behavior

There are two functions: one for getting the current setting and one for getting the default settingfor a particular error situation.

error_behavior_t TTCN_EncDec::get_error_behavior(error_type_t);error_behavior_t TTCN_EncDec::get_default_error_behavior(error_type_t);

The using of these functions are straightforward: giving a particular error_type_t the functionreturns the current or default error_behavior_t for that error situation, respectively.

Checking if an Error Occurred

The last coding-related error and its textual description can be retrieved anytime. Before using acoding function, it is advisable to clear the "last error". This can be achieved by the followingmethod:

void TTCN_EncDec::clear_error();

After using some coding functions, it can be checked if an error occurred with this function:

39

error_type_t TTCN_EncDec::get_last_error_type();

This returns the last error, or ET_NONE if there was no error. The string representation of the errorcan be requested with the help of this:

const char* TTCN_EncDec::get_error_str();

WARNING The above two functions do not clear the "last error" flag.

5.1.2. TTCN_Buffer

TTCN Buffer objects are used to store encoded values and to communicate with the codingfunctions. If encoding a value, the result will be put in a buffer, from which can be get. In the otherhand, to decode a value, the encoded octet string must be put in a TTCN_Buffer object, and thedecoding functions get their input from that.

void TTCN_Buffer::clear();

Resets the buffer, cleaning up its content, setting the pointers to the beginning of buffer.

void TTCN_Buffer::rewind();

Rewinds the buffer, that is, sets its reading pointer to the beginning of the buffer.

size_t TTCN_Buffer::get_pos() const;

Returns the (reading) position of the buffer.

void TTCN_Buffer::set_pos(size_t pos);

Sets the (reading) position to pos, or to the end of buffer, if pos > get_len().

size_t TTCN_Buffer::get_len() const;

Returns the amount of bytes in the buffer.

const unsigned char* TTCN_Buffer::get_data() const;

Returns a pointer that points to the beginning of the buffer. You can read out count bytes beginningfrom this address, where count is the value returned by the get_len() member function.

40

size_t TTCN_Buffer::get_read_len() const;

Returns how many bytes are in the buffer to read.

const unsigned char* TTCN_Buffer::get_read_data() const;

Returns a pointer which points to the read position of data in the buffer. count bytes can be read outbeginning from this address, where count is the value returned by the get_read_len() memberfunction.

void TTCN_Buffer::put_c(const unsigned char c);

Appends the byte c to the end of buffer.

void TTCN_Buffer::put_s(const size_t len, const unsigned char *s);

Writes a string of bytes to the end of buffer, where len is the amount of bytes, s is a pointer to thedata to be written.

void TTCN_Buffer::put_os(const OCTETSTRING& os);

Appends the content of the octet string to the buffer.

Sometimes it is useful to copy data directly into a buffer. In this case, the buffer must be told themaximum number of bytes to be written. So the buffer can resize its data area. This can be donewith the following function:

void TTCN_Buffer::get_end(unsigned char*& end_ptr, size_t& end_len);

Parameter end_len is an in-out parameter: you tell how many bytes you want to write, and thereturned value is equal to or greater than the requested. Parameter end_ptr is an out parameter. Soup to end_len bytes can be written beginning from end_ptr. After writing also increase_length()must be called.

void TTCN_Buffer::increase_length(size_t count);

After writing bytes directly to the end of buffer using the pointer returned by get_end() method, thebuffer must be told how many bytes have been written. This can be done by this function.

void TTCN_Buffer::cut();

41

Cuts (removes) the bytes between the beginning of the buffer and the read position. After callingthis, the read position will be the beginning of buffer. As this function manipulates the internaldata, pointers referencing to data inside the buffer will be invalid.

void TTCN_Buffer::cut_end();

Cuts (removes) the bytes between the read position and the end of the buffer. After calling this, theread position remains unchanged (that is, it will point to the end of the truncated buffer). As thisfunction manipulates the internal data, pointers referencing to data inside the buffer will beinvalid.

boolean TTCN_Buffer::contains_complete_TLV();

Returns TRUE if the buffer contains a complete TLV, otherwise it returns FALSE. Useful whendecoding BER streams, and the data is coming in chunks. With the help of this, you can checkbefore decoding whether the message is complete.

5.1.3. Invoking the Coding Functions

Every type class has members like these:

void encode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, ...) const;void decode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, ...);

Parameter p_td is a special type descriptor. Each type has its own descriptor, which contains thename of the type, and a lot of information used by the different encoding mechanisms. The namesof the descriptors come from the name of the types: the appropriate type descriptor for type XXX isXXX_descr_.

Parameter p_buf contains the encoded value. For details about using it, please consult the previoussubsection.

Parameter p_cod is the desired coding mechanism. As coding_t is defined in TTCN_EncDec, its valuemust be prefixed with TTCN_EncDec::. For the time being, this parameter may have one of thefollowing values:

• CT_BER - BER coding;

• CT_RAW - RAW coding;

• CT_TEXT - TEXT coding;

• CT_XER - XML coding;

• CT_JSON - JSON coding;

• CT_OER - OER coding;

42

The optional … parameter(s) are depending on the chosen coding.

5.2. BERThe encoding rules defined in Information TechnologyASN.1 encoding rules: Specification of BasicEncoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished can be used to encodeand/or decode the values of ASN.1 types. There are three methods defined in the referenceddocument: BER, CER and DER (Basic, Canonical and Distinguished Encoding Rules). While the BERgives a lot of options to the sender (that is, to the encoder), the CER and DER select just oneencoding from those allowed by the BER, eliminating all of the sender options. In other words, CER(and also DER) is a subset of BER. Any value encoded by CER or DER can be decoded using BER, butit is not true in the other direction.

In this section it is assumed that the reader has basic knowledge about BER, TLVs, tags, length formsand other items defined in Information TechnologyASN.1 encoding rules: Specification of BasicEncoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished.

This tool is capable of encoding values in CER or DER, and uses the BER while decoding[8]. The tagsare handled quite separated from the types, giving extra freedom to the user when encoding onlyone component of a compound type. Let us suppose we have a large SEQUENCE with automatic tags(that is, context-specific implicit tags 1, 2, …), the third component is "‎[3] Other-sequence". Then wehave the possibility to encode only this field using SEQUENCE-tag. (Implementation details andexamples follow in next sections.)

5.2.1. Error Situations

In addition to error situations mentioned in The Common API, these can occur during BER-coding:

Table 5. BER-coding errors

ET_INCOMPL_ANY Encoding of an ASN ANY value which does not contain a valid BERTLV.

ET_LEN_FORM During decoding: the received message has a non-acceptable lengthform.

ET_TAG During decoding: unexpected tag.

ET_SUPERFL During decoding: superfluous part detected. This can be superfluousTLV at the end of a constructed TLV.

ET_EXTENSION During decoding: there was something in the extension (forexample: in ASN.1 ellipsis). This is not supported in the currentversion.

ET_DEC_DUPFLD While decoding a SET: duplicated field (value for the given fieldalready received).

ET_DEC_MISSFLD While decoding a SET: missing field (value for the given field notreceived).

ET_DEC_OPENTYPE Cannot decode an opentype (broken component relation constraint).

43

https://www.itu.int/rec/T-REC-X.690-200811-S




ET_DEC_UCSTR While decoding a universal charstring: Malformed sequence.

5.2.2. API

The Application Programming Interface for ASN.1 type encoding and decoding is described in thefollowing.

Encoding

void encode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, unsigned int p_BER_coding) const;

The parameter p_cod must be set to TTCN_EncDec::CT_BER. The parameter p_BER_coding is used tochoose between CER and DER.

BER_ENCODE_CER = CER coding.

BER_ENCODE_DER = DER coding.

Decoding

void decode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, unsigned int p_len_form);

The parameter p_cod must be set to TTCN_EncDec::CT_BER. The parameter p_len_form determineswhich length forms are accepted.

• BER_ACCEPT_SHORT

Short form.

• BER_ACCEPT_LONG

Long form.

• BER_ACCEPT_INDEFINITE

Indefinite form.

• BER_ACCEPT_DEFINITE

Short and long form.

• BER_ACCEPT_ALL

All form.

44

5.2.3. Example

Let us assume that we have an ASN.1 module named MyASN which contains a type namedErrorReturn, and we have a TTCN–3 module which imports this type. This module contains also twoports:

type port MyPort1 message

type port MyPort1 message{ out ErrorReturn; in octetstring;}

type port MyPort2 message{ out octetstring; in ErrorReturn;}

Then we can complete the port skeleton generated by the compiler:

void MyPort1::outgoing_send(const MyASN::ErrorReturn& send_par){ TTCN_Buffer buf; send_par.encode(MyASN::ErrorReturn_descr_, buf, TTCN_EncDec::CT_BER, BER_ENCODE_DER); OCTETSTRING encodeddata(buf.get_len(), buf.get_data()); incoming_message(encodeddata);}

void MyPort2::outgoing_send(const OCTETSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_os(send_par); MyASN::ErrorReturn pdu; pdu.decode(MyASN::ErrorReturn_descr_, buf, TTCN_EncDec::CT_BER, BER_ACCEPT_ALL); incoming_message(pdu);}

5.3. RAWYou can use the encoding rules defined in the section "RAW encoder and decoder" in theProgrammer’s Technical Reference to encode and decode the following TTCN–3 types:

45


• boolean

• integer

• float

• bitstring

• octetstring

• charstring

• hexstring

• enumerated

• record

• set

• union

• record of

• set of

The compiler will produce code capable of RAW encoding/decoding for compound types if theyhave at least one variant attribute.When a compound type is only used internally or it is never RAW encoded/decoded then theattribute variant has to be omitted.When a type can be RAW encoded/decoded but with default specification then the empty variantspecification can be used: variant "".


Table 6. RAW-coding errors

ET_LEN_ERR During encoding: Not enough length specified in FIELDLENGTH toencode the value. During decoding: the received message is shorterthan expected.

ET_SIGN_ERR Unsigned encoding of a negative number.

ET_FLOAT_NAN Not a Number float value has been received.

ET_FLOAT_TR The float value will be truncated during double to single precisionconversion.

5.3.2. API

The C++ Application Programming Interface for RAW encoding and decoding is described in thefollowing. It can be used for example in test port implementation, in external functionimplementation.

Encoding

46

void encode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod) const;

The parameter p_cod must be set to TTCN_EncDec::CT_RAW.

Decoding

void decode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod);

The parameter p_cod must be set to TTCN_EncDec::CT_RAW.

5.3.3. Example

Let us assume that we have a TTCN–3 module which contains a type named ProtocolPdu, and thismodule contains also two ports:

type port MyPort1 message{ out ProtocolPdu; in octetstring;}

type port MyPort2 message{ out octetstring; in ProtocolPdu;}

Then we can complete the port skeleton generated by the compiler as follows:

47

void MyPort1::outgoing_send(const ProtocolPdu& send_par){ TTCN_Buffer buf; send_par.encode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_RAW); OCTETSTRING encodeddata(buf.get_len(), buf.get_data());

incoming_message(encodeddata);}

void MyPort2::outgoing_send(const OCTETSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_os(send_par); ProtocolPdu pdu; pdu.decode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_RAW);

incoming_message(pdu);}

5.4. TEXTYou can use the encoding rules defined in the section "TEXT encoder, decoder" in the Programmer’sTechnical Reference to encode and decode the following TTCN–3 types:

• boolean

• integer

• charstring

• enumerated

• record

• set

• union

• record of

• set of

The compiler will produce code capable of TEXT encoding/decoding for compound types if theyhave at least one variant attribute or it is used within a compound type which has a TEXT attribute.If you need a compound type that is only used internally or it is never RAW encoded/decoded thenyou have to omit the variant attribute. If you need a type which can be TEXT encoded/decoded butwith default specification then the empty variant specification can be used: variant"TEXT_CODING()".

48




ET_TOKEN_ERR - The specified token is not found during decoding

5.4.2. API

The Application Programming Interface for TEXT encoding and decoding is described in thefollowing.

Encoding


The parameter p_cod must be set to TTCN_EncDec::CT_TEXT.

Decoding


The parameter p_cod must be set to TTCN_EncDec::CT_TEXT.

5.4.3. Example


type port MyPort1 message{ out ProtocolPdu; in charstring;}

type port MyPort2 message{ out charstring; in ProtocolPdu;}


49

void MyPort1::outgoing_send(const ProtocolPdu& send_par){ TTCN_Buffer buf; send_par.encode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_TEXT); CHARSTRING encodeddata(buf.get_len(), buf.get_data());


void MyPort2::outgoing_send(const CHARSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_cs(send_par); ProtocolPdu pdu; pdu.decode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_TEXT);


5.5. XML Encoding (XER)The encoding rules defined by Methods for Testing and Specification (MTS); The Testing and TestControl Notation version 3. Part 9: Using XML Schema with TTCN–3 European can be used toencode and/or decode values of ASN.1 and TTCN-3 types. This tool is capable of encoding anddecoding Basic XER (BXER), Canonical XER (CXER) and Extended XER (EXER). Values of all ASN.1types can be encoded, but only BXER and CXER are available for them because parsing XMLEncoding Instructions in ASN.1 files is not implemented.

The following built-in TTCN-3 types can be encoded in XML:

• boolean

• integer

• float

• bitstring

• octetstring

• hexstring

• objid

• charstring

• universal charstring

• verdicttype

The following user-defined types can be encoded in XML:

50

https://www.etsi.org/deliver/etsi_ES/201800_201899/20187309/04.05.01_60/es_20187309v040501p.pdf


• enumerated types

• record, set and union types, if all components can be encoded.

• record of and set of types, if the type of the element can be encoded.

The encoder and the decoder are working with XML data encoded in UTF-8 (described in UTF-8, atransformation format of ISO 10646), stored in an object of type TTCN_buffer. Although the contentsof this object can be retrieved (using the overloads of the get_string function) as an instance ofOCTETSTRING, CHARSTRING or UNIVERSAL_CHARSTRING, it is recommended to use only the OCTETSTRINGrepresentation. CHARSTRING is not recommended, because UTF-8 is an 8-bit encoding so the buffermay contain bytes with values over 127, which are not valid characters for a TTCN-3 charstring(which is implemented by CHARSTRING, see Charstring). UNIVERSAL_CHARSTRING must not be usedbecause its internal representation is not UTF-8.


In addition to error situations mentioned in The Common API, the following can occur duringXMLcoding:

Table 7. XER coding errors

ET_TAG Incorrect (unexpected) XML tag found duringdecoding

5.5.2. API

The Application Programming Interface for XML encoding and decoding is described in thefollowing.

Encoding

void encode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, unsigned int p_XER_coding) const;

The parameter p_cod must be set to TTCN_EncDec::CT_XER. The parameter p_XER_coding is used tochoose between BXER, CXER and EXER:

XER_BASIC = Basic XER (BXER)

XER_CANONICAL = Canonical XER (CXER)

XER_EXTENDED = Extended XER (EXER)

Decoding

void decode(const TTCN_Typedescriptor_t& p_td, TTCN_Buffer& p_buf, TTCN_EncDec::coding_t p_cod, unsigned int p_XER_coding);

51

https://tools.ietf.org/html/rfc3629


The parameter p_cod must be set to TTCN_EncDec::CT_XER. The parameter p_XER_coding is used tochoose between BXER, CXER and EXER:

XER_BASIC = Basic XER (BXER)

XER_CANONICAL = Canonical XER (CXER)

XER_EXTENDED = Extended XER (EXER)

5.5.3. Example


void MyPort1::outgoing_send(const ProtocolPdu& send_par){ TTCN_Buffer buf; send_par.encode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_XER, XER_EXTENDED); OCTETSTRING encodeddata(buf.get_len(), buf.get_data());


void MyPort2::outgoing_send(const OCTETSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_os(send_par); ProtocolPdu pdu; pdu.decode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_XER, XER_EXTENDED);


5.6. JSONThe encoding rules defined in the section "JSON Encoder and Decoder" of the Programmer’sTechnical Reference can be used to encode and decode the following TTCN–3 types:

• anytype

• array

• bitstring

• boolean

• charstring

• enumerated

52



• float

• hexstring

• integer

• objid

• octetstring

• record`, set

• record of`, set of

• union

• universal charstring

• verdicttype

The rules also apply to the following ASN.1 types (if imported to a TTCN-3 module):

• ANY

• BIT STRING

• BOOLEAN

• BMPString

• CHOICE, open type (in instances of parameterized types)

• ENUMERATED

• GeneralString

• GraphicString

• IA5String

• INTEGER

• NULL

• NumericString

• OBJECT IDENTIFIER

• OCTET STRING

• PrintableString

• RELATIVE`-OID

• SEQUENCE, SET

• SEQUENCE OF, SET OF

• TeletexString

• UniversalString

• UTF8String

• VideotexString

• VisibleString

53

The compiler will produce code capable of JSON encoding/decoding for compound types if theyhave at least one JSON variant attribute or the encode "JSON" attribute (and, for compound types, allfields and elements of compound types also have a JSON variant attribute or the encode "JSON"attribute).

The encoder and the decoder work with JSON data encoded in UTF-8 (described in UTF-8, atransformation format of ISO 10646), stored in an object of type TTCN_buffer. Although the contentsof this object can be retrieved (using the overloads of the get_string function) as an instance ofOCTETSTRING, CHARSTRING or UNIVERSAL_CHARSTRING, it is recommended to use only the OCTETSTRINGrepresentation. CHARSTRING is not recommended, because UTF-8 is an 8-bit encoding so the buffermay contain bytes with values over 127, which are not valid characters for a TTCN-3 charstring(which is implemented by CHARSTRING, see Charstring). UNIVERSAL_CHARSTRING must not be usedbecause its internal representation is not UTF-8.


There are no extra error situations apart from the ones in The Common API.

5.6.2. API

The Application Programming Interface for JSON encoding and decoding is described in thefollowing.

Encoding


The parameter p_cod must be set to TTCN_EncDec::CT_JSON.

Decoding


The parameter p_cod must be set to TTCN_EncDec::CT_JSON.

5.6.3. Example

Let us assume that we have a TTCN–3 module which contains a type named ProtocolPdu, and thismodule also contains two ports:

54



6-mapping_ttcn3_data_types_to_c+\+_constructs.pdf#Charstring

type port MyPort1 message{ out ProtocolPdu; in octetstring;}

type port MyPort2 message{ out octetstring; in ProtocolPdu;}


void MyPort1::outgoing_send(const ProtocolPdu& send_par){ TTCN_Buffer buf; send_par.encode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_JSON); OCTETSTRING encodeddata(buf.get_len(), buf.get_data());


void MyPort2::outgoing_send(const OCTETSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_os(send_par); ProtocolPdu pdu; pdu.decode(ProtocolPdu_descr_, buf, TTCN_EncDec::CT_JSON);


5.7. OERThe encoding rules defined in the section "OER Encoder and Decoder" of the Programmer’sTechnical Reference can be used to encode and/or decode the values of ASN.1 types.


There are no extra error situations apart from the ones in The Common API.

55



5.7.2. API

The Application Programming Interface for ASN.1 type encoding and decoding is described in thefollowing.

Encoding


The parameter p_cod must be set to TTCN_EncDec::CT_OER.

Decoding


The parameter p_cod must be set to TTCN_EncDec::CT_OER.

5.7.3. Example

Let us assume that we have an ASN.1 module named MyASN which contains a type namedErrorReturn, and we have a TTCN–3 module which imports this type. This module also contains twoports:

type port MyPort1 message{ out ErrorReturn; in octetstring;}

type port MyPort2 message{ out octetstring; in ErrorReturn;}


56

void MyPort1::outgoing_send(const MyASN::ErrorReturn& send_par){ TTCN_Buffer buf; send_par.encode(MyASN::ErrorReturn_descr_, buf, TTCN_EncDec::CT_OER); OCTETSTRING encodeddata(buf.get_len(), buf.get_data()); incoming_message(encodeddata);}

void MyPort2::outgoing_send(const OCTETSTRING& send_par){ TTCN_EncDec::set_error_behavior(TTCN_EncDec::ET_ALL, TTCN_EncDec::EB_WARNING); TTCN_Buffer buf; buf.put_os(send_par); MyASN::ErrorReturn pdu; pdu.decode(MyASN::ErrorReturn_descr_, buf, TTCN_EncDec::CT_OER); incoming_message(pdu);}

[8] Though the decoder can be forced to accept only certain length forms (short, long, indefinite or any combination of these.

57

Chapter 6. Mapping TTCN–3 Data Types toC++ ConstructsThe TTCN–3 language elements of the test suite are individually mapped into more or lessequivalent C++ constructs. The data types are mapped to C++ classes, the test cases become C++functions, and so on. In order to write a Test Port, it is inevitable to be familiar with the internalrepresentation format of TTCN–3 data types and values. This section gives an overview about thedata types and their equivalent C++ constructs.

6.1. Mapping of Names and IdentifiersIn order to identify the TTCN–3 language elements in the generated C++ program properly, thenames of test suite are translated to C++ identifiers according to the following simple rules.

If the TTCN–3 identifier does not contain any underscore (_) character, its equivalent C++ identifierwill be the same. For example, the TTCN–3 variable MyVar will be translated to a C++ variable calledMyVar.

If the TTCN–3 identifier contains one or more underscore characters, each underscore characterwill be duplicated in the C++ identifier. So the TTCN–3 identifier My_Long_Name will be mapped to aC++ identifier called My__Long__Name.

The idea behind this name mapping is that we may freely use the C++ identifiers containing oneunderscore character in the generated code and in the Test Ports as well. Otherwise name clashescan always happen because the name space of TTCN–3 and C++ is identical. Furthermore, thegenerated C++ language elements fulfill the condition that the scope of a translated C++ identifier isidentical as the scope of the original TTCN–3 identifier.

The identifiers that are keywords of C or C++ but not keywords in TTCN–3 are mapped tothemselves, but a single underscore character is appended at the end (for example typedef becomestypedef_). The same rule applies to the all-uppercase identifiers that are used in the Base Library:identifier INTEGER in TTCN–3 becomes INTEGER_ in C++, TRUE [9] is mapped to TRUE_, etc.

Here is the complete list (in alphabetical order) of the identifiers that are handled in such specialway:asm, auto, bitand, bitor, bool, break, case, class, compl, continue, delete, double, enum, explicit,export, friend, inline, int, ischosen, long, main, mutable, namespace, new, operator, private,protected, public, register, short, signed, static, stderr, stdin, stdout, struct, switch, this, throw, try,typedef, typeid, typename, unsigned, using, virtual, void, volatile, ADDRESS, BITSTRING, BOOLEAN,CHAR, CHARSTRING, COMPONENT, DEFAULT, ERROR, FAIL, FALSE, FLOAT, HEXSTRING, INCONC,INTEGER, NONE, OBJID, OCTETSTRING, PASS, PORT, TIMER, TRUE, VERDICTTYPE.

The identifiers that are the names of common preprocessor macros of the C library (such asputchar, errno or NULL) should be avoided in TTCN–3 modules. The name clashes with macros cancause mysterious compilation error messages.

Note that these name mapping rules apply to all TTCN–3 identifiers, including module, Test Port,type, field, variable and function names.

58

WARNINGBy default, from version 1.2.pl0 the compiler does NOT duplicate theunderscores in output file names and file references (for example whenhandling imports).

6.2. NamespacesThe compiler generates a C++ namespace for every TTCN–3 and ASN.1 module. All C++ definitionsthat belong to the module (including Test Port classes and external functions) are placed in thatnamespace. The name of the namespace is derived from the module identifier according to therules described in Mapping of Names and Identifiers.

The definitions of the TTCN–3 Base Library do not use any namespace.

When accessing a C++ entity that belongs to a different module than the referring Test Port orexternal function is in the reference has to be prefixed with the namespace of the referencedmodule. For example, to access the C++ class that realizes type MyType defined in module MyExample1from a Test Port that belongs to module MyExample2 the reference shall be written asMyExample1::MyType.

6.3. Predefined TTCN–3 Data TypesThere are some basic data types in TTCN–3 that have no equivalent data types in language C/C++(for example bitstring, verdicttype). Other types have C++ equivalent, but the TTCN–3 executor mustknow whether a variable has a valid value or not because sending an unbound value must result ina dynamic test case error. Thus, in the TTCN–3 Base Library all basic data types of TTCN–3 wereimplemented as C++ classes. This section describes the member functions of these classes.

6.3.1. Integer

The TTCN–3 type integer is implemented in class INTEGER.The class INTEGER has the following public member functions:

Table 8. Public member functions of the class INTEGER

Member functions Notes

Constructors

INTEGER() Initializes to unbound value.

INTEGER(int) Initializes to a given value.

INTEGER(const INTEGER&) Copy constructor.

explicit INTEGER(const char *) Initializes with the (NULterminated) stringrepresentation of an integer.

Destructor ˜INTEGER()

Assignment operatorsINTEGER() Initializes to unbound value.

INTEGER() Initializes to unbound value.

59

Comparison operators

boolean operator==(int) const Returns TRUE if equals

boolean operator==(constINTEGER&) const

and FALSE otherwise.

boolean operator!=(int) const

boolean operator!=(constINTEGER&) const

boolean operator<(int) const

boolean operator<(constINTEGER&) const

boolean operator⇐(int) const

boolean operator⇐(constINTEGER&) const

boolean operator>(int) const

boolean operator>(constINTEGER&) const

boolean operator>=(int) const

boolean operator>=(constINTEGER&) const

Arithmetic operators

INTEGER operator+() const Unary plus.

INTEGER operator-() const Unary minus.

INTEGER operator+(int) const Addition.

INTEGER operator+(constINTEGER&) const

INTEGER operator-(int) const Subtraction.

INTEGER operator-(constINTEGER&) const

INTEGER operator*(int) const Multiplication.

INTEGER operator*(constINTEGER&) const

INTEGER operator/(int) const Integer division.

INTEGER operator/(constINTEGER&) const

INTEGER& operator++() Incrementation (prefix).

INTEGER& operator—() Decrementation (prefix).

Casting operator operator int() const Returns the value.

60

Other member functions

void log() const Puts the value into log.

boolean is_bound() const Returns whether the value isbound.

void clean_up() Deletes the value, setting it tounbound.

long long intget_long_long_val() const

Returns the value as a long longint.

void set_long_long_val(longlong int)

Sets the given long long intvalue.

The comparison, arithmetic and shifting operators are also available as global functions for thatcase when the left side is int and the right side is INTEGER. Using the value of an unbound variablefor anything will cause dynamic test case error.

The casting operator int() is applicable only to INTEGER objects holding a signed value with at most31 useful bits, since in C/C++ the native int type is 32-bit large including the sign bit. Casting anINTEGER object holding a bigger (for example a 32-bit unsigned) value will result in run-time error.

Please note that if the value stored in an INTEGER object is too big (that is, it cannot be represented asa long long int) the value returned by get_long_long_val() will contain only the lowest sizeof(longlong int) bytes of the original value. Another way to obtain a value of a number having moreuseful bits than 31 is to convert the INTEGER object to its string representation using the int2str()predefined function. Then the string value can be converted to any native integer type using thesscanf() library function or such. The following example demonstrates a common scenario:

unsigned int get_unsigned_int_val(const INTEGER& other_value){ unsigned int ret_val = 0; sscanf((const char *)int2str(), “%u”, &ret_val); return ret_val;}

In addition, the following global functions are available for modulo division. These functions returnthe result of mod and rem operations according to TTCN–3 semantics.

INTEGER mod(const INTEGER& left_operand, const INTEGER& right_operand);INTEGER mod(const INTEGER& left_operand, int right_operand);INTEGER mod(int left_operand, const INTEGER& right_operand);INTEGER mod(int left_operand, int right_operand);

INTEGER rem(const INTEGER& left_operand, const INTEGER& right_operand);INTEGER rem(const INTEGER& left_operand, int right_operand);INTEGER rem(int left_operand, const INTEGER& right_operand);INTEGER rem(int left_operand, int right_operand);

Other operators (global functions):

61

INTEGER operator+(int int_value, const INTEGER& other_value); // AddINTEGER operator-(int int_value, const INTEGER& other_value); // SubtractINTEGER operator*(int int_value, const INTEGER& other_value); // MultiplyINTEGER operator/(int int_value, const INTEGER& other_value); // Divideboolean operator==(int int_value, const INTEGER& other_value); // Equalboolean operator!=(int int_value, const INTEGER& other_value); // Not equalboolean operator<(int int_value, const INTEGER& other_value); // Less thanboolean operator>(int int_value, const INTEGER& other_value); // More than

6.3.2. Float

The TTCN–3 type float is implemented in class FLOAT.The class FLOAT has the following public member functions:

Table 9. Public member functions of the class FLOAT


Constructors

FLOAT() Initializes to unbound value.

FLOAT(double) Initializes to a given value.

FLOAT(const FLOAT&) Copy constructor.

Destructor ˜FLOAT()

Assignment operatorsFLOAT& operator=(double) Assigns the given value

FLOAT& operator=(const FLOAT&) and sets the bound flag.

62


boolean operator==(double)const

Returns TRUE if equals

boolean operator==(constFLOAT&) const


boolean operator!=(double)const

boolean operator!=(constFLOAT&) const

boolean operator<(double)const

boolean operator<(constFLOAT&) const

boolean operator⇐(double)const

boolean operator⇐(constFLOAT&) const

boolean operator>(double)const

boolean operator>(constFLOAT&) const

boolean operator>=(double)const

boolean operator>=(constFLOAT&) const

Arithmetic operators

double operator+() const Unary plus.

double operator-() const Unary minus.

double operator+(double) const Addition.

double operator+(constFLOAT&) const

double operator-(double) const Subtraction.

double operator-(constFLOAT&) const

double operator*(double) const Multiplication.

double operator*(constFLOAT&) const

double operator/(double) const Division.

double operator/(constFLOAT&) const

Casting operator operator double() const Returns the value.

63


void log() const Puts the value into log, either inexponential or decimal dotnotation.



The comparison and arithmetic operators are also available as global functions for that case whenthe left side is double and the right side is FLOAT. Using the value of an unbound variable foranything will cause dynamic test case error.


FLOAT operator+(double double_value, const FLOAT& other_value); // AddFLOAT operator-(double double_value, const FLOAT& other_value); // SubtractFLOAT operator*(double double_value, const FLOAT& other_value); // MultiplyFLOAT operator/(double double_value, const FLOAT& other_value); // Divideboolean operator==(double double_value, const FLOAT& other_value); // Equalboolean operator!=(double double_value, const FLOAT& other_value); // Not equalboolean operator<(double double_value, const FLOAT& other_value); // Less thanboolean operator>(double double_value, const FLOAT& other_value); // More than

6.3.3. Boolean

The TTCN–3 type boolean is implemented in class BOOLEAN.We have introduced an ancillary Cenumerated type called boolean to set and get values. It may have two predefined values: TRUE orFALSE. You may use boolean values in C conditions since FALSE equals to zero and TRUE is not zero.The class BOOLEAN has the following public member functions:

Table 10. Public member functions of the class BOOLEAN


Constructors

BOOLEAN() Initializes to unbound value.

BOOLEAN(boolean) Initializes to a given value.

BOOLEAN(const BOOLEAN&) Copy constructor.

Destructor ˜BOOLEAN()

Assignment operators

BOOLEAN& operator=(boolean) Assigns the given value

BOOLEAN& operator=(constBOOLEAN&)

and sets the bound flag.

64


boolean operator==(boolean)const


boolean operator==(constBOOLEAN&) const


boolean operator!=(boolean)const

Same as XOR.

boolean operator!=(constBOOLEAN&) const

Logical operators

boolean operator!() const Negation (NOT).

boolean operator&&(boolean)const

Logical AND.

boolean operator&&(constBOOLEAN&) const

boolean operator (boolean) const

Logical OR. boolean operator

(const BOOLEAN&) const

boolean operatorˆ(boolean)const

Exclusive or (XOR).

boolean operatorˆ(constBOOLEAN&) const

Casting operator operator boolean() const Returns the value.


void log() const Puts the value into log. Like“TRUE” or “FALSE”.

boolean is_bound() const Returns whether the value isbound


The comparison and logical operators are also available as global functions for that case when theleft side is boolean and the right side is BOOLEAN. Using the value of an unbound variable for anythingwill cause dynamic test case error.


BOOLEAN operator&&(boolean bool_value, const BOOLEAN& other_value); // AndBOOLEAN operator^(boolean bool_value, const BOOLEAN& other_value); // NotBOOLEAN operator||(boolean bool_value, const BOOLEAN& other_value); // Orboolean operator==(boolean bool_value, const BOOLEAN& other_value); // Equalboolean operator!=(boolean bool_value, const BOOLEAN& other_value);// Not equal

65

6.3.4. Verdicttype

The TTCN–3 type verdicttype is implemented in class VERDICTTYPE. We have introduced an ancillaryC enumerated type called verdicttype to set and get values. It may have five predefined values:NONE, PASS, INCONC, FAIL or ERROR. The order of these values is NONE < PASS < INCONC < FAIL < ERROR.The class VERDICTTYPE has the following public member functions:

Table 11. Public member functions of the class VERDICTTYPE


Constructors

VERDICTTYPE() Initializes to unbound value.

VERDICTTYPE(verdicttype) Initializes to a given value.

VERDICTTYPE(constVERDICTTYPE&)

Copy constructor.

Destructor ˜VERDICTTYPE()


VERDICTTYPE&operator=(verdicttype)

Assigns the given value

VERDICTTYPE& operator= (constVERDICTTYPE&)



booleanoperator==(verdicttype) const


boolean operator==(constVERDICTTYPE&) const


boolean operator!=(verdicttype)const

boolean operator!=(constVERDICTTYPE&) const

Casting operator Returns the value. operator verdicttype() const

Returns the value.


Puts the value into log.

void log() const Puts the value into log.

Like “pass” or “fail”. boolean is_bound() const

Returns whether the value isbound.


The comparison operators are also available as global functions for that case when the left side isverdicttype and the right side is VERDICTTYPE. Using the value of an unbound VERDICTTYPE variablefor anything will cause dynamic test case error.

From version 1.2.pl0 there are the following three static member functions in class TTCN_Runtimedefined in the Base Library for getting or modifying the local verdict of the current testcomponents:

66

void TTCN_Runtime::setverdict(verdicttype);void TTCN_Runtime::setverdict(const VERDICTTYPE&);verdicttype TTCN_Runtime::getverdict();

These functions are the C++ equivalents of TTCN–3 setverdict and getverdict operations. Use themonly if your Test Port or C++ function encounters a low-level failure, but it can continue its normaloperation (that is, error recovery is not necessary).


boolean operator==(verdicttype par_value, const VERDICTTYPE& other_value); // Equalboolean operator!=(verdicttype par_value, const VERDICTTYPE& other_value); // Not equal

6.3.5. Bitstring

The equivalent C++ class of TTCN–3 type bitstring is called BITSTRING. The bits of the bit string arestored in an array of unsigned characters. In order to reduce the wasted memory space the bits arepacked together, so each character contains eight bits. The first character contains the first eightbits of the bit string; the second byte contains the bits from the 9th up to the 16th, and so on. Thefirst bit of the bit string is the LSB of the first character; the second bit is the second least significantbit of the first character, and so on. The character array is not terminated with a NUL character andif the length of the bit string is not a multiple of eight, the unused bits of the last character cancontain any value. So the length of the bit string must be always given.

The class BITSTRING has the following public member functions:

Table 12. Public member functions of the class BITSTRING


Constructors

BITSTRING() Initializes to unbound value.

BITSTRING(int n_bits, unsignedchar *bits_ptr)

Initializes from a given lengthand pointer to character array.

BITSTRING(const BITSTRING&) Copy constructor.

BITSTRING(constBITSTRING_ELEMENT&)

Initializes from a singlebitstring element.

Destructor ˜BITSTRING()


BITSTRING& operator=(constBITSTRING&)

Assigns the given value and setsthe bound flag.

BITSTRING& operator=(constBITSTRING_ELEMENT&)

Assigns the given singlebitstring element.

67


boolean operator==(constBITSTRING&) const


boolean operator==(constBITSTRING_ELEMENT&) const


boolean operator!=(constBITSTRING&) const

boolean operator!=(constBITSTRING_ELEMENT&) const

Concatenation operator

BITSTRING operator+(constBITSTRING&) const

Concatenates two bitstrings.

BITSTRING operator+(constBITSTRING_ELEMENT&) const

Concatenates a bitstring and abitstring element.

Index operator

BITSTRING_ELEMENToperator[](int)

Gives access to the givenelement. Indexing begins fromzero. Index overflow causesdynamic test case error.

BITSTRING_ELEMENToperator[](const INTEGER&)

const BITSTRING_ELEMENToperator[](int) const

Gives read-only access to thegiven element.

const BITSTRING_ELEMENToperator[](const INTEGER&)const

Bitwise operators

BITSTRING operator~() const C++ equivalent of operatornot4b. (bitwise negation)

BITSTRING operator&(constBITSTRING&) const

C++ equivalent of operatorand4b. (bitwise and)

BITSTRING operator&(constBITSTRING_ELEMENT&) const

BITSTRING operator (const BITSTRING&) const

C++ equivalent of operatoror4b. (bitwise or)

BITSTRING operator

(const BITSTRING_ELEMENT&)const

BITSTRING operatorˆ(constBITSTRING&) const

C++ equivalent of operatorxor4b. (bitwise xor)

BITSTRING operator^(constBITSTRING_ELEMENT&) const

68

Shifting and rotating operators

BITSTRING operator<<(int)const

C++ equivalent of operator

BITSTRING operator<<(constINTEGER&) const

<<.(shift left)

BITSTRING operator>>(int)const


BITSTRING operator>>(constINTEGER&) const

>>. (shift right)

BITSTRING operator<⇐(int)const


BITSTRING operator<⇐(constINTEGER&) const

< @. (rotate left)

BITSTRING operator>>=(int)const


BITSTRING operator>>=(constINTEGER&) const

@ >. (rotate right)

Casting operatoroperator const unsigned char*()const

Returns a pointer to thecharacter array.


int lengthof() const Returns the length measured inbits.

void log() const Puts the value into log.Example: ’100011’B.

boolean is_bound() const Deletes the value, setting it tounbound

void clean_up()

Using the value of an unbound BITSTRING variable for anything will cause dynamic test case error.

Bitstring element

The C++ class BITSTRING_ELEMENT is the equivalent of the TTCN-3 bitstring’s element type (the resultof indexing a bitstring value). The class does not store the actual bit, only a reference to theoriginal BITSTRING object, an index value and a bound flag.

NOTEchanging the value of the BITSTRING_ELEMENT (through the assignment operator)changes the referenced bit in the original bitstring object.

The class BITSTRING_ELEMENT has the following public member functions:

Table 13. Public member functions of the class BITSTRING_ELEMENT


69

Constructor BITSTRING_ELEMENT(booleanpar_bound_flag, BITSTRING&par_str_val, int par_bit_pos)

Initializes the object with anunbound value or a referenceto a bit in an existringBITSTRING object.


BITSTRING_ELEMENT&operator=(const BITSTRING&)

Sets the referenced bit to thegiven bitstring of length 1.

BITSTRING_ELEMENT&operator=(constBITSTRING_ELEMENT&)

Sets the referenced bit to thegiven bitstring element.


boolean operator==(constBITSTRING&) const

Comparison with a bitstring ora bitstring element (the value ofthe referenced bits is compared,not the references and indexes).

boolean operator==(constBITSTRING_ELEMENT&) const

boolean operator!=(constBITSTRING&) const

boolean operator!=(constBITSTRING_ELEMENT&) const


BITSTRING operator+(constBITSTRING&) const

Concatenates a bitstringelement with a bitstring, or twobitstring elements.

BITSTRING operator+(constBITSTRING_ELEMENT&) const

Bitwise operators

BITSTRING operator~() const C++ equivalent of operatornot4b. (bitwise negation)

BITSTRING operator&(constBITSTRING&) const


BITSTRING operator&(constBITSTRING_ELEMENT&) const

BITSTRING operator (const BITSTRING&) const


BITSTRING operator

(const BITSTRING_ELEMENT&)const

BITSTRING operatorˆ(constBITSTRING&) const


BITSTRING operatorˆ(constBITSTRING_ELEMENT&) const

70


boolean get_bit() const Returns the referenced bit.

void log() const Puts the value into log.Example: '1’B.


Using the value of an unbound BITSTRING_ELEMENT variable for anything will cause dynamic test caseerror.

6.3.6. Hexstring

The equivalent C++ class of TTCN–3 type hexstring is called HEXSTRING. The hexadecimal digits(nibbles) are stored in an array of unsigned characters. In order to reduce the wasted memoryspace two nibbles are packed into one character. The first character contains the first two nibblesof the hexstring, the second byte contains the third and fourth nibbles, and so on. The hexadecimaldigits at odd (first, third, fifth, etc.) positions occupy the lower 4 bits in the characters; the even onesuse the upper 4 bits. The character array is never terminated with a NUL character, so the lengthmust be always given with the pointer. If the hexstring has odd length the unused upper 4 bits ofthe last character may contain any value.

The class HEXSTRING has the following public member functions:

Table 14. Public member functions of the class HEXSTRING


Constructors

HEXSTRING() Initializes to unbound value.

HEXSTRING(int n_nibbles, constunsigned char *nibbles_ptr)

Initializes from a given lengthand pointer to the characterarray.

HEXSTRING(const HEXSTRING&)

HEXSTRING(constHEXSTRING_ELEMENT&)

Destructor ˜HEXSTRING()


HEXSTRING& operator=(constHEXSTRING&)


HEXSTRING& operator=(constHEXSTRING_ELEMENT&)


boolean operator==(constHEXSTRING&) const

Returns TRUE if equals andFALSE otherwise.

boolean operator==(constHEXSTRING_ELEMENT&) const

boolean operator!=(constHEXSTRING&) const

boolean operator!=(constHEXSTRING_ELEMENT&) const

71



HEXSTRING operator+(constHEXSTRING&) const

Concatenates two hexstrings.

HEXSTRING operator+(constHEXSTRING_ELEMENT&) const

Concatenates a hexstring and ahexstring element.

Index operator

HEXSTRING_ELEMENToperator[](int)


HEXSTRING_ELEMENToperator[](const INTEGER&)

const HEXSTRING_ELEMENToperator[](int) const

const HEXSTRING_ELEMENToperator[](const INTEGER&)const

Bitwise operators

HEXSTRING operator~() const C++ equivalent of operatornot4b. (bitwise negation)

HEXSTRING operator&(constHEXSTRING&) const


HEXSTRING operator&(constHEXSTRING_ELEMENT&) const

HEXSTRING operator (const HEXSTRING&) const


HEXSTRING operator

(const HEXSTRING_ELEMENT&)const

HEXSTRING operatorˆ(constHEXSTRING&) const


HEXSTRING operator^(constHEXSTRING_ELEMENT&) const

72



HEXSTRING operator<<(int)const


HEXSTRING operator<<(constINTEGER&) const

<<.(shift left)

HEXSTRING operator>>(int)const


HEXSTRING operator>>(constINTEGER&) const

>>. (shift right)

HEXSTRING operator<⇐(int)const


HEXSTRING operator<⇐(constINTEGER&) const

< @. (rotate left)

HEXSTRING operator>>=(int)const


HEXSTRING operator>>=(constINTEGER&) const

@ >. (rotate right)

Casting operator

operator const unsigned char*()const

Returns a pointer to thecharacter array. The pointermight be NULL if the length is 0.


int lengthof() const Returns the length measured innibbles.

void log() const Puts the value into log.Example: ’5A7’H.



Using the value of an unbound HEXSTRING variable for anything will cause a dynamic test case error.

Hexstring element

The C++ class HEXSTRING_ELEMENT is the equivalent of the TTCN-3 hexstring’s element type (the resultof indexing a hexstring value). The class does not store the actual hexadecimal digit (nibble), only areference to the original HEXSTRING object, an index value and a bound flag.

NOTEchanging the value of the HEXSTRING_ELEMENT (through the assignment operator)changes the referenced nibble in the original hexstring object.

The class HEXSTRING_ELEMENT has the following public member functions:

Table 15. Public member functions of the class HEXSTRING_ELEMENT

73


Constructor

HEXSTRING_ELEMENT(booleanpar_bound_flag, HEXSTRING&par_str_val, intpar_nibble_pos)

Initializes the object with anunbound value or a referenceto a nibble in an existringHEXSTRING object.


HEXSTRING_ELEMENT&operator=(const HEXSTRING&)

Sets the referenced nibble tothe given hexstring of length 1.

HEXSTRING_ELEMENT&operator=(constHEXSTRING_ELEMENT&)

Sets the referenced nibble tothe given hexstring element.


boolean operator==(constHEXSTRING&) const

Comparison with a hexstring ora hexstring element (the valueof the referenced nibbles iscompared, not the referencesand indexes).

boolean operator==(constHEXSTRING_ELEMENT&) const

boolean operator!=(constHEXSTRING&) const

boolean operator!=(constHEXSTRING_ELEMENT&) const


HEXSTRING operator+(constHEXSTRING&) const

Concatenates a hexstringelement with a hexstring, ortwo hexstring elements.

HEXSTRING operator+(constHEXSTRING_ELEMENT&) const

Bitwise operators

HEXSTRING operator~() const C++ equivalent of operatornot4b. (bitwise negation)

HEXSTRING operator&(constHEXSTRING&) const


HEXSTRING operator&(constHEXSTRING_ELEMENT&) const

HEXSTRING operator (const HEXSTRING&) const


HEXSTRING operator

(const HEXSTRING_ELEMENT&)const

HEXSTRING operatorˆ(constHEXSTRING&) const


HEXSTRING operatorˆ(constHEXSTRING_ELEMENT&) const

74


unsigned char get_nibble()const

Returns the referenced nibble(stored in the lower 4 bits of thereturned character).

void log() const Puts the value into log.Example: '8’H.


Using the value of an unbound HEXSTRING_ELEMENT variable for anything will cause dynamic test caseerror.

6.3.7. Octetstring

The equivalent C++ class of TTCN–3 type octetstring is called OCTETSTRING. The octets are stored inan array of unsigned characters. Each character contains one octet; the first character is the firstoctet of the string. The character array is not terminated by a NUL character, so the length of theoctet string must be always given.

The class OCTETSTRING has the following public member functions:

Table 16. Public member functions of the class OCTETSTRING


Constructors

OCTETSTRING() Initializes to unbound value.

OCTETSTRING(int n_octets,const unsigned char*octets_ptr)


OCTETSTRING(constOCTETSTRING&)

Copy constructor.

OCTETSTRING(constOCTETSTRING_ELEMENT&)

Initializes from a singleoctetstring element.

Destructor ˜OCTETSTRING()


OCTETSTRING& operator=(constOCTETSTRING&)


OCTETSTRING& operator=(constOCTETSTRING_ELEMENT&)

Assigns the given octetstringelement.

75



boolean operator==(constOCTETSTRING&) const


boolean operator==(constOCTETSTRING_ELEMENT&)const


boolean operator!=(constOCTETSTRING&) const

boolean operator!=(constOCTETSTRING_ELEMENT&)const


OCTETSTRING operator+(constOCTETSTRING&) const

Concatenates two octetstrings.

OCTETSTRING operator+(constOCTETSTRING_ELEMENT&)const

Concatenates an octetstring andan octetstring element.

OCTETSTRING&operator+=(constOCTETSTRING&) const

Appends an octetstring to thisone.

OCTETSTRING&operator+=(constOCTETSTRING_ELEMENT&)const

Appends an octetstring elementto this octetstring.

Index operator

OCTETSTRING_ELEMENToperator[](int)


OCTETSTRING_ELEMENToperator[](const INTEGER&)

const OCTETSTRING_ELEMENToperator[](int) const


const OCTETSTRING_ELEMENToperator[](const INTEGER&)const

76


Bitwise operators

OCTETSTRING operator˜() const C++ equivalent of operatornot4b.(bitwise negation)

OCTETSTRING operator&(constOCTETSTRING&) const


OCTETSTRING operator&(constOCTETSTRING_ELEMENT&)const

OCTETSTRING operator (const OCTETSTRING&) const


OCTETSTRING operator

(constOCTETSTRING_ELEMENT&)const

OCTETSTRING operatorˆ(constOCTETSTRING&) const


OCTETSTRING operator^(constOCTETSTRING_ELEMENT&)const


OCTETSTRING operator<<(int)const

C++ equivalent of operator <<.

OCTETSTRING operator<<(constINTEGER&) const

(shift left)

OCTETSTRING operator>>(int)const

C++ equivalent of operator >>.

OCTETSTRING operator>>(constINTEGER&) const

(shift right)

OCTETSTRING operator<⇐(int)const

C++ equivalent of operator < @.

OCTETSTRINGoperator<⇐(const INTEGER&)const

(rotate left)

OCTETSTRING operator>>=(int)const

C++ equivalent of operator @ >.

OCTETSTRINGoperator>>=(const INTEGER&)const

(rotate right)

Casting operator

operator const unsigned char*()const

Returns a pointer to thecharacter array. The pointermight be NULL if the length is 0.

77



int lengthof() const Returns the length measured inoctets.

void log() const Puts the value into log. Like’073CF0’O.



Using the value of an unbound OCTETSTRING variable for anything will cause dynamic test case error.

Octetstring element

The C++ class OCTETSTRING_ELEMENT is the equivalent of the TTCN-3 octetstring’s element type (theresult of indexing an octetstring value). The class does not store the actual octet, only a referenceto the original OCTETSTRING object, an index value and a bound flag.

NOTEchanging the value of the OCTETSTRING_ELEMENT (through the assignmentoperator) changes the referenced octet in the original octetstring object.

The class OCTETSTRING_ELEMENT has the following public member functions:

Table 17. Public member functions of the class OCTETSTRING_ELEMENT


Constructor

OCTETSTRING_ELEMENT(booleanpar_bound_flag, OCTETSTRING&par_str_val, int par_octet_pos)

Initializes the object with anunbound value or a referenceto an octet in an existringOCTETSTRING object.


OCTETSTRING_ELEMENT&operator=(const OCTETSTRING&)

Sets the referenced octet to thegiven octetstring of length 1.

OCTETSTRING_ELEMENT&operator=(constOCTETSTRING_ELEMENT&)

Sets the referenced octet to thegiven octetstring element.

78



boolean operator==(constOCTETSTRING&) const

Comparison with an octetstringor an octetstring element (thevalue of the referenced octets iscompared, not the referencesand indexes).

boolean operator==(constOCTETSTRING_ELEMENT&)const

boolean operator!=(constOCTETSTRING&) const

boolean operator!=(constOCTETSTRING_ELEMENT&)const


OCTETSTRING operator+(constOCTETSTRING&) const

Concatenates an octetstringelement with an octetstring, ortwo octetstring elements.

OCTETSTRING operator+(constOCTETSTRING_ELEMENT&)const

Bitwise operators

OCTETSTRING operator~() const C++ equivalent of operator(bitwise negation)

OCTETSTRING operator&(constOCTETSTRING&) const


OCTETSTRING operator&(constOCTETSTRING_ELEMENT&)const

HEXSTRING operator (const OCTETSTRING&) const


OCTETSTRING operator

(constOCTETSTRING_ELEMENT&)const

OCTETSTRING operatorˆ(constOCTETSTRING&) const


OCTETSTRING operatorˆ(constOCTETSTRING_ELEMENT&)const

79



unsigned char get_octet()const

Returns the referenced octet.

void log() const Puts the value into log.Example: '3C’O.


Using the value of an unbound OCTETSTRING_ELEMENT variable for anything will cause dynamic testcase error.

6.3.8. Char

The char type, which has been removed from the TTCN–3 standard, is no longer supported by therun-time environment. The compiler substitutes all occurrences of char type with type charstringautomatically.

To provide partial backward compatibility for older Test Ports that might have used the type char,CHAR is a typedef alias to class CHARSTRING in C++.

6.3.9. Charstring

The equivalent C++ class of TTCN–3 type charstring is called CHARSTRING. The characters are storedin a NUL character terminated array; thus, giving the length in the constructor and other operationsis optional.

The class CHARSTRING has the following public member functions:

Table 18. Public member functions of the class CHARSTRING


Constructors

CHARSTRING() Initializes to unbound value.

CHARSTRING(char) Initializes from a singlecharacter.

CHARSTRING(int n_chars, constchar *chars_ptr)


CHARSTRING(const char*chars_ptr)

Initializes from a givencharacter array. The end isnoted by a NUL character.

CHARSTRING(const CHARSTRING&) Copy constructor.

CHARSTRING(constCHARSTRING_ELEMENT&)

Initializes from a charstringelement.

Destructor ˜CHARSTRING()

80


CHARSTRING& operator=(constCHARSTRING&)


CHARSTRING& operator=(constchar *)

Assigns the NUL terminatedstring.

CHARSTRING& operator=(constCHARSTRING_ELEMENT&)

Assigns the given charstringelement.

CHARSTRING& operator=(constUNIVERSAL_CHARSTRING&)

Assigns the given universalcharstring value.


boolean operator==(constCHARSTRING&) const

Returns TRUE if equals andFALSE otherwise.

boolean operator==(const char*) const

Compares to the NULterminated string.

boolean operator==(constCHARSTRING_ELEMENT&)const

Comparison with a charstringelement.

boolean operator==(constUNIVERSAL_CHARSTRING&)const

Comparison with a universalcharstring.

boolean operator==(constUNIVERSAL_CHARSTRING_ELEMENT&) const

Comparison with a universalcharstring element.

boolean operator!=(constCHARSTRING&) const

boolean operator!=(const char*) const

boolean operator!=(constCHARSTRING_ELEMENT&)const

81


CHARSTRING operator+(constCHARSTRING&) const

Concatenates two charstrings.

CHARSTRING operator+(constchar *) const

Concatenates with a NULterminated string.

CHARSTRING operator+(constCHARSTRING_ELEMENT) const

Concatenates with a charstringelement.

UNIVERSAL_CHARSTRINGoperator+(constUNIVERSAL_CHARSTRING&)const

Concatenates with a universalcharstring.

UNIVERSAL_CHARSTRINGoperator+(constUNIVERSAL_CHARSTRING_ELEMENT&) const

Concatenates with a universalcharstring element.

CHARSTRING operator+=(char) Appends a character.

CHARSTRING operator+=(constchar *)

Appends a NUL terminatedstring.

CHARSTRING operator+=(constCHARSTRING&)

Appends a charstring.

CHARSTRING operator+=(constCHARSTRING_ELEMENT&)

Appends a charstring element.

Index operator

CHARSTRING_ELEMENToperator[](int)


CHARSTRING_ELEMENToperator[](const INTEGER&)

const CHARSTRING_ELEMENToperator[](int) const


const CHARSTRING_ELEMENToperator[](const INTEGER&)const

Rotating operators

CHARSTRING operator<⇐(int)const

C++ equivalent of operator <@.(rotate left)

CHARSTRING operator<⇐(constINTEGER&) const

CHARSTRING operator>>=(int)const

C++ equivalent of operator @ >.(rotate right)

CHARSTRING operator>>=(constINTEGER&) const

82

Casting operator

operator const char*() const Returns a pointer to thecharacter array. The string isalways terminated by NUL.


int lengthof() const Returns the length measured incharacters not including theterminator NUL.

void log() const Puts the value into log.Example: ”abc”.


The comparison, concatenation and rotating operators are also available as global functions forthat case when the left side is const char* and the right side is CHARSTRING.

The log() member function uses single character output for regular characters, but specialcharacters (such as the quotation mark, backslash or newline characters) are printed using theescape sequences of the C language. Non-printable control characters are printed in TTCN–3quadruple notation, where the first three octets are always zero. The concatenation operator (&) isused between the fragments when necessary. Note that the output does not always conform toTTCN–3 Core Language syntax, but it is always recognized by both our compiler and theconfiguration file parser.

Using the value of an unbound CHARSTRING variable for anything will cause dynamic test case error.


boolean operator==(const char* string_value, const CHARSTRING& other_value); // Equalboolean operator==(const char* string_value, const CHARSTRING_ELEMENT& other_value); // Equalboolean operator!=(const char* string_value, const CHARSTRING& other_value); // Not equalboolean operator!=(const char* string_value, const CHARSTRING_ELEMENT& other_value); // Not equalCHARSTRING operator+(const char* string_value, const CHARSTRING& other_value); // ConcatenationCHARSTRING operator+(const char* string_value, const CHARSTRING_ELEMENT& other_value); // Concatenation

Charstring element

The C++ class CHARSTRING_ELEMENT is the equivalent of the TTCN-3 charstring’s element type (theresult of indexing a charstring value). The class does not store the actual character, only a referenceto the original CHARSTRING object, an index value and a bound flag.

NOTEchanging the value of the CHARSTRING_ELEMENT (through the assignment operator)changes the referenced character in the original charstring object.

83

The class CHARSTRING_ELEMENT has the following public member functions:

Table 19. Public member functions of the class CHARSTRING_ELEMENT


Constructor

CHARSTRING_ELEMENT(booleanpar_bound_flag, CHARSTRING&par_str_val, int par_char_pos)

Initializes the object with anunbound value or a referenceto a character in an existringCHARSTRING object.


CHARSTRING_ELEMENT&operator=(const char*)

Sets the referenced character tothe given null-terminated stringof length 1.

CHARSTRING_ELEMENT&operator=(const CHARSTRING&)

Sets the referenced character tothe given charstring of length 1.

CHARSTRING_ELEMENT&operator=(constCHARSTRING_ELEMENT&)

Sets the referenced character tothe given charstring element.

84


boolean operator==(constchar*) const

Comparison with a null-terminated string, a charstring,a universal charstring, acharstring element or auniversal charstring element(when comparing elementtypes, the value of thereferenced characters iscompared, not the referencesand indexes).





boolean operator!=(const char*)const



85


CHARSTRING operator+(constchar*) const

Concatenates this object with anull-terminated string, acharstring, a charstringelement, a universal charstringor a universal charstringelement.


CHARSTRING operator+(constCHARSTRING_ELEMENT&)const




char get_char() const Returns the referencedcharacter.

void log() const Puts the value into log.Example: “a”.


Using the value of an unbound CHARSTRING_ELEMENT variable for anything will cause dynamic testcase error.

6.3.10. Universal char

This obsolete TTCN–3 type is converted automatically to universal charstring in the parser.

6.3.11. Universal charstring

Each character of a universal charstring value is represented in the following C structure definedin the Base Library:

struct universal_char { unsigned char uc_group, uc_plane, uc_row, uc_cell;};

The four components of the quadruple (that is, group, plane, row and cell) are stored in fieldsuc_group, uc_plane, uc_row and uc_cell, respectively. All fields are 8bit unsigned numeric values with

86

the possible value range 0 .. 255.

In case of single-octet characters, which can be also given in TTCN–3 charstring notation (betweenquotation marks), the fields uc_group, uc_plane, uc_row are set to zero. If tuple notation was used foran ASN.1 string value fields uc_row and uc_cell carry the tuple and the others are set to zero.

Except when performing encoding or decoding, the run-time environment does not check whetherthe quadruples used in the following API represent valid character positions according to [8].Moreover, if ASN.1 multi-octet character string values are used, it is not verified whether theelements of such strings are permitted characters of the corresponding string type.

The C++ equivalent of TTCN–3 type universal charstring is implemented in classUNIVERSAL_CHARSTRING. The characters of the string are stored in an array of structureuniversal_char. The array returned by the casting operator is not terminated with a specialcharacter, thus, the length of the string must be always considered when doing operations with thearray. The length of the string, which can be obtained by using member function lengthof(), ismeasured in characters (quadruples) and not bytes.

For the more convenient usage the strings containing only single-octet characters can also be usedwith class UNIVERSAL_CHARSTRING. Therefore some polymorphic member functions and operatorshave variants that take const char* as argument. In these member functions the characters of theNUL character terminated string are implicitly converted to quadruples with group, plane and rowfields set to zero. NULL pointer as argument means the empty string for these functions.

The class UNIVERSAL_CHARSTRING has the following public member functions:

Table 20. Public member functions of the class UNIVERSAL_CHARSTRING


87

Constructors

UNIVERSAL_CHARSTRING() Initializes to unbound value.

UNIVERSAL_CHARSTRING (unsignedchar group, unsigned charplane, unsigned char row,unsigned char cell)

Constructs a string containingone character formed from thegiven quadruple.

UNIVERSAL_CHARSTRING (constuniversal_char&)

Constructs a string containingthe given single character.

UNIVERSAL_CHARSTRING (intn_uchars, const universal_char*uchars_ptr)

Constructs a string from anarray by taking the givennumber of single-octetcharacters.

UNIVERSAL_CHARSTRING (constchar *chars_ptr)

Constructs a string from a NULterminated array of single-octetcharacters.

UNIVERSAL_CHARSTRING (intn_chars, const char*chars_ptr)

Constructs a string from a givennumber of single-octetcharacters.

UNIVERSAL_CHARSTRING (constCHARSTRING&)

Constructs a universalcharstring from a charstringvalue.

UNIVERSAL_CHARSTRING (constCHARSTRING_ELEMENT&)

Constructs a string containingthe given singe charstringelement.

UNIVERSAL_CHARSTRING (constUNIVERSAL_CHARSTRING&)

Copy constructor.

UNIVERSAL_CHARSTRING (constUNIVERSAL_CHARSTRING_ELEMENT&)

Constructs a string containingthe given singe universalcharstring element.

Destructor ˜UNIVERSAL_CHARSTRING()


UNIVERSAL_CHARSTRING&operator= (constUNIVERSAL_CHARSTRING&)

Assigns another string.

UNIVERSAL_CHARSTRING&operator= (constuniversal_char&)

Assigns a single character.

UNIVERSAL_CHARSTRING&operator= (const char*)

Assigns a NUL terminatedsingle-octet string.

UNIVERSAL_CHARSTRING&operator= (const CHARSTRING&)

Assigns a charstring.

UNIVERSAL_CHARSTRING&operator= (constCHARSTRING_ELEMENT&)

Assigns a single charstringelement.

UNIVERSAL_CHARSTRING&operator= (constUNIVERSAL_CHARSTRING_ELEMENT&)

Assigns a single universalcharstring element.

88



Returns TRUE if the strings areidentical or FALSE otherwise.

boolean operator==(constuniversal_char&) const

Compares to a single character.


Compares to a NUL terminatedprintable string.


Compares to a charstring.


Compares to a charstringelement.


Compares to a universalcharstring element.

boolean operator!=(constUNIVERSAL_CHARSTRING&)const

boolean operator!= (constuniversal_char&) const


boolean operator!=(constCHARSTRING&)


boolean operator!=(constUNIVERSAL_CHARSTRING_ELEMENT&) const

89



Concatenates two strings.

UNIVERSAL_CHARSTRINGoperator+(constuniversal_char&) const

Concatenates a single character.

UNIVERSAL_CHARSTRINGoperator+(const char*) const

Concatenates a NUL terminatedsingle-octet string.

UNIVERSAL_CHARSTRINGoperator+(const CHARSTRING&)const

Concatenates a charstring.

UNIVERSAL_CHARSTRINGoperator+(constCHARSTRING_ELEMENT&)const

Concatenates a charstringelement.


Concatenates a universalcharstring element.

Index operator

UNIVERSAL_CHARSTRING_ELEMENT operator[](int)


UNIVERSAL_CHARSTRING_ELEMENT operator[](constINTEGER&)

constUNIVERSAL_CHARSTRING_ELEMENT operator[](int) const


constUNIVERSAL_CHARSTRING_ELEMENT operator[](constINTEGER&) const

90

Rotating operators

UNIVERSAL_CHARSTRINGoperator<⇐(int) const

C++ equivalent of operator <@(rotate left).

UNIVERSAL_CHARSTRINGoperator<⇐(const INTEGER&)const

UNIVERSAL_CHARSTRINGoperator>>=(int) const

C++ equivalent of operator @ >(rotate right).

UNIVERSAL_CHARSTRINGoperator>>=(const INTEGER&)const

Casting operator

operator constuniversal_char*() const

Returns a pointer to the array ofcharacters. There is noterminator character at the end.

UTF-8 encoding and decoding

void encode_utf8(TTCN_Buffer&buf) const

Appends the UTF-8representation of the string tothe given buffer

void decode_utf8(int n_octets,const unsigned char *octets_ptr)


int lengthof() const Returns the length measured incharacters.

`boolean is_bound() const ` Returns whether the value isbound.

void log() const Puts the value into log. Seebelow.


The comparison and concatenation operators are also available as global functions for that casewhen the left operand is a single-octet string (const char*) or a single character (constuniversal_char&) and the right side is UNIVERSAL_CHARSTRING value. Using the value of an unboundUNIVERSAL_CHARSTRING variable for anything causes dynamic test case error.

The UNIVERSAL_CHARSTRING variable used with the decode_utf8() method must be newly constructed(unbound) or clean_up() must have been called, otherwise a memory leak will occur.

The logged printout of universal charstring values is compatible with the TTCN–3 notation for suchstrings. The format to be used depends on the contents of the string. Each character (quadruple) isclassified whether it is directly printable or not. The string is fragmented based on thisclassification. Each fragment consists of either a single non-printable character or a maximal lengthcontiguous sequence of printable characters. The fragments are logged one after another separatedby an & character (concatenation operator). The printable fragments use the normal charstringnotation; the non-printable characters are logged in the TTCN–3 quadruple notation. An emptyuniversal charstring value is represented by a pair of quotation marks (like in case of emptycharstring values).

91

An example printout in the log can be the following. The string consists of two fragments ofprintable characters and a non-printable quadruple, which stands for Hungarian letter "ű":

"Character " & char(0, 0, 1, 113) & " is a letter of Hungarian alphabet"


boolean operator==(const universal_char& left_value, const universal_char& right_value); // Equalboolean operator==(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING& other_value); // Equalboolean operator==(const char* string_value, const UNIVERSAL_CHARSTRING& other_value); // Equalboolean operator==(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // Equalboolean operator==(const char* string_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // Equalboolean operator!=(const universal_char& left_value, const universal_char& right_value); // Not equalboolean operator!=(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING& other_value); // Not equalboolean operator!=(const char* string_value, const UNIVERSAL_CHARSTRING& other_value); // Not equalboolean operator!=(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // Not equalboolean operator!=(const char* string_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // Not equalboolean operator<(const universal_char& left_value, const universal_char& right_value& other_value); // Character comparisonUNIVERSAL_CHARSTRING operator+(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING& other_value); // ConcatenationUNIVERSAL_CHARSTRING operator+(const char* string_value, const UNIVERSAL_CHARSTRING& other_value); // ConcatenationUNIVERSAL_CHARSTRING operator+(const universal_char& uchar_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // ConcatenationUNIVERSAL_CHARSTRING operator+(const char* string_value, const UNIVERSAL_CHARSTRING_ELEMENT& other_value); // Concatenation

Universal charstring element

The C++ class UNIVERSAL_CHARSTRING_ELEMENT is the equivalent of the TTCN-3 universal charstring’selement type (the result of indexing a universal charstring value). The class does not store theactual character, only a reference to the original UNIVERSAL_CHARSTRING object, an index value and abound flag.

NOTEchanging the value of the UNIVERSAL_CHARSTRING_ELEMENT (through the assignmentoperator) changes the referenced character in the original universal charstringobject.

92

The class UNIVERSAL_CHARSTRING_ELEMENT has the following public member functions:

Table 21. Public member functions of the class UNIVERSAL_CHARSTRING_ELEMENT


Constructor

UNIVERSAL_CHARSTRING_ELEMENT(boolean par_bound_flag,UNIVERSAL_CHARSTRING&par_str_val, intpar_uchar_pos)

Initializes the object with anunbound value or a referenceto a character in an existringUNIVERSAL_CHARSTRINGobject.


UNIVERSAL_CHARSTRING_ELEMENT&operator=(constuniversal_char&)

Sets the referenced character tothe given universal character.

UNIVERSAL_CHARSTRING_ELEMENT&operator=(const char*)

UNIVERSAL_CHARSTRING_ELEMENT&operator=(const CHARSTRING&)

UNIVERSAL_CHARSTRING_ELEMENT&operator=(constCHARSTRING_ELEMENT&)

UNIVERSAL_CHARSTRING_ELEMENT&operator=(constUNIVERSAL_CHARSTRING&)

UNIVERSAL_CHARSTRING_ELEMENT&operator=(constUNIVERSAL_CHARSTRING_ELEMENT&)

93


boolean operator==(constuniversal_char&) const

Comparison with a universalcharacter, a null-terminatedstring, a charstring, a universalcharstring, a charstring elementor a universal charstringelement (when comparingelement types, the value of thereferenced characters iscompared, not the referencesand indexes).






boolean operator!=(constuniversal_char&) const




boolean operator!=(constUNIVERSAL_CHARSTRING&)const

boolean operator!=(constUNIVERSAL_CHARSTRING_ELEMENT&) const

94


CHARSTRING operator+(constuniversal_char&) const

Concatenates this object with auniversal character, a null-terminated string, a charstring,a charstring element, auniversal charstring or auniversal charstring element.

CHARSTRING operator+(constchar*) const


CHARSTRING operator+(constCHARSTRING_ELEMENT&)const




const universal_char&get_char() const

Returns the referencedcharacter.

void log() const Puts the value into log.Example: “a” or char(0, 0, 1,113).


Using the value of an unbound UNIVERSAL_CHARSTRING_ELEMENT variable for anything will causedynamic test case error.

6.3.12. Object Identifier Type

The object identifier type of TTCN–3 (objid) is implemented in class OBJID. In the run-timeenvironment the components of object identifier values are represented in NumberForm, that is, ininteger values. The values of components are stored in an array with a given length. The type of thecomponents is specified with a typedef, objid_element. Class OBJID has the following memberfunctions.

Table 22. Public member functions of the class OBJID

95


Constructors

OBJID() Initializes to unbound value.

OBJID(int n_components, constobjid_element *components_ptr)

Initializes the number ofcomponents to n componentsand copies all components froman array of integers starting atcomponents_ptr.

OBJID(int n_components, …) Initializes the number ofcomponents to n_components.The components themselvesshall be given as additionalinteger arguments after eachother, starting with the firstone.

OBJID(const OBJID&) Copy constructor.

Destructor ˜OBJID()

Assignment operatorOBJID& operator=(const OBJID&) Assigns the given value and sets

the bound flag.


boolean operator==(constOBJID&) const

Returns TRUE if the two valuesare equal and FALSE otherwise.

boolean operator!=(constOBJID&) const

Indexing operators

objid_element& operator[](int i) Returns a reference to the i thcomponent.

const objid_element &operator[](int i) const

Returns a read-only referenceto the i th component.

Casting operatoroperator const objid_element*() const

Returns a pointer to the read-only array of components.

Other member functions int lengthof() const Returns the number ofcomponents.

void log() const Puts the value into log inNumberForm. Like this: “objid 04 0 ”.

boolean is_bound() const

Returns whether the value isbound.


NOTEThe constructor with variable number of arguments is useful in situations when thenumber of components is constant and known at compile time.

Using the value of an unbound OBJID variable for anything will cause dynamic test case error.

96

6.3.13. Component References

TTCN–3 variables the types of which are defined as component types are used for storingcomponent references to PTCs. The internal representation of component references are test tooldependent, our test executor handles them as small integer numbers.

All TTCN–3 component types are mapped to the same C++ class, which is called COMPONENT, usingtypedef aliases. We also use an ancillary C type called component, which is defined as an alias for int:

typedef int component;

There are some predefined constants of component references in TTCN–3. These are defined as Cpreprocessor macros in the following way:

Table 23. Predefined component references

TTCN–3 constant Preprocessor symbol Numeric value

null NULL COMPREF 0

mtc MTC COMPREF 1

system SYSTEM COMPREF 2

The class COMPONENT has the following public member functions:

Table 24. Public member functions of the class COMPONENT


Constructors

COMPONENT() Initializes to unbound value.

COMPONENT(component) Initializes to a given value.

COMPONENT(const COMPONENT&) Copy constructor.

Destructor COMPONENT()


COMPONENT&operator=(component)


COMPONENT& operator=(constCOMPONENT&)



booleanoperator==(component) const


boolean operator==(constCOMPONENT&) const


boolean operator!=(component)const

boolean operator!=(constCOMPONENT&) const

Casting operator operator component() const Returns the value.

97


void log() const Puts the value into log indecimal form or in symbolicformat for special constants.Like 3 or mtc.



Component references are managed by MC. All new test components are given a unique referencethat was never used in the test campaign before (not even in a previous test case). The newnumbers are increasing monotonously. The reference of the firstly created component is 3; the nextone will be 4, and so on.

Using the value of an unbound component reference for anything will cause dynamic test caseerror.


boolean operator==(component component_value, const COMPONENT& other_value); // Equalboolean operator!=(component component_value, const COMPONENT& other_value); // Not equal

6.3.14. Empty Types

Empty record and set types are not real built-in types in TTCN–3, but the C++ realization of thesetypes also differs from regular records or sets. The empty types are almost identical to each other,only their names are different. That is why we treat them as predefined types.

Each empty type is defined in a C++ class, which is generated by the compiler. Using separateclasses enables us to differentiate among them in C++ type polymorphism. For example, severalempty types can be defined as incoming or outgoing types on the same TTCN–3 port type.

Let us consider the following TTCN–3 type definition as an example:

type record Dummy {};

The generated class will rely on an enumerated C type null_type, which is defined as follows:

enum null type {NULL VALUE };

The only possible value stands for the TTCN–3 empty record or array value (that is for "{}"), whichis the only possible value of TTCN–3 type Dummy. Note that this type and value is also used in thedefinition of record of and set of type construct.

98

The generated C++ class Dummy will have the following member functions:

Table 25. Public member functions of the class Dummy


Constructors

Dummy() Initializes to unbound value.

Dummy(null type) Initializes to the only possiblevalue.

Dummy(const Dummy&) Copy constructor.

Destructor ˜Dummy()


Dummy& operator=(null type) Assigns the only possible valueand sets the bound flag.

Dummy& operator=(const Dummy&)


boolean operator==(Dummy)const

Returns TRUE if botharguments are bound.

boolean operator==(constDummy&) const

boolean operator!=(address)const

Returns FALSE if botharguments are bound.

boolean operator!=(constDummy&) const


void log() const Puts the value, that is, {}, intolog.



Setting the only possible value is important, because using the value of an unbound variable foranything will cause dynamic test case error.


boolean operator==(null_type null_value, const Dummy& other_value);// Equalboolean operator!=(null_type null_value, const Dummy& other_value);// Not equal

6.4. Compound Data TypesThe user-defined compound data types are implemented in C++ classes. These classes are generatedby the compiler according to type definitions. In contrast with the basic types, these classes can befound in the generated code.

99

6.4.1. Record and Set Type Constructs

The TTCN–3 type constructs record and set are mapped in an identical way to C++. There will be aC++ class for each record type in the generated code. This class builds up the record from its fields.[10] The fields can be either basic or compound types.

Let us consider the following example type definition. The types t1 and t2 can be arbitrary.

type record t3 { t1 f1, t2 f2}

The generated class t3 will have the following public member functions:

Table 26. Public member functions of the class t3


Constructors

t3() Initializes all fields to unboundvalue.

t3(const t1& par_f1, const t2&par_f2)

Initializes from given fieldvalues. The number ofarguments equals to thenumber of fields.

t3(const t3&) Copy constructor.

Destructor ˜t3()

Assignment operator

t3& operator=(const t3&) Assigns the given value andsetsthe bound flag for eachfield.


boolean operator==(const t3&)const

Returns TRUE if all fields areequal and FALSE otherwise.

boolean operator!=(const t3&)const

Field access functions

t1& f1(); t2& f2(); Gives access to the first/secondfield.

const t1& f1() const; const t2&f2() const;

The same, but it gives read-onlyaccess.

100


int size_of() const Returns the size (number offields).

void log() const Puts the value into log. Like { f1:= 5, f2 := ”abc”}.



The record value is unbound if one or more fields of it are unbound. Using the value of an unboundvariable for anything (even for comparison) will cause dynamic test case error.

Optional Fields in Records and Sets

TTCN–3 permits optional fields in record and set type definitions. An optional field does not have tobe always present, it can be omitted. But the omission must be explicitly denoted. Let us change ourlast example to this.

type record t3 { t1 f1, t2 f2 optional}

The optional fields are implemented using a C++ template class called OPTIONAL that creates anoptional value from any type. In the definition of the generated class t3 the type t2 will be replacedby OPTIONAL<t2> everywhere and anything else will not be changed.

The instantiated template class OPTIONAL<t2> will have the following member functions:

Table 27. Table Public member functions of the class OPTIONAL<t2>


101

Constructors

OPTIONAL() Initializes to unbound value.

OPTIONAL(template_selinit_val)

Initializes to omit value, if theargument is OMIT VALUE.

OPTIONAL(const t2& init_val) Initializes to given value.

OPTIONAL(const OPTIONAL&init_val)

Copy constructor.

`template <typename T_tmp> ` Initializes to given value ofdifferent (compatible) type.

OPTIONAL(constOPTIONAL<T_tmp>&)

template <typename T_tmp> Initializes to given optionalvalue of different (compatible)type.

OPTIONAL(const T_tmp&)

Destructor ˜OPTIONAL()


OPTIONAL&operator=(template_sel)

Assigns omit value, if the rightvalue is OMIT VALUE.

OPTIONAL& operator=(constOPTIONAL&)

Assigns the given optionalvalue.

template <typename T_tmp> Assigns the given optional valueof different (compatible) type.

OPTIONAL& operator=(constOPTIONAL<T_tmp>&)

template <typename T_tmp> Assigns the given value ofdifferent (compatible) type.

OPTIONAL& operator=(constT_tmp&)

102


booleanoperator==(template_sel) const

Returns TRUE if the value isomit and the right side is OMITVALUE or FALSE otherwise.

boolean operator==(constOPTIONAL&) const

Returns TRUE if the two valuesare equal or FALSE otherwise.

template <typename T_tmp> Returns TRUE if the two valuesof different (compatible) typesare equal or FALSE otherwise.

booleanoperator!=(template_sel) const

boolean operator!=(constOPTIONAL&) const

template <typename T_tmp>

boolean operator!=(constOPTIONAL<T_tmp>&) const

Casting operators

operator t2&() Gives read-write access to thevalue. If the value was notpreviously present, sets thebound flag true and the valuewill be initialized to unbound.

operator const t2&() const Gives read-only access to thevalue. If the value is notpresent, causes a dynamic testcase error.

Function call operators

t2& operator()() Gives read-write access to thevalue. If the value was notpreviously present, sets thebound flag true and the valuewill be initialized to unbound.

const t2& operator()() const Gives read-only access to thevalue. If the value is notpresent, causes a dynamic testcase error.

103


boolean ispresent() const Returns TRUE if the value ispresent, FALSE if the value isomit or causes dynamic testcase error if the value isunbound.

void log() const Puts the optional value into log.Either ”omit” or the value of t2.



In some member functions of the template class OPTIONAL the enumerated C type template_sel isused. It has many possible values, but in the optional class only OMIT_VALUE can be used, whichstands for the TTCN–3 omit. Usage of other predefined values of template_sel will cause dynamictest case error.

Using the value of an unbound optional field for anything will also cause dynamic test case error.

6.4.2. Union Type Construct

The TTCN–3 type construct union is implemented in a C++ class for each union type in thegenerated code. This class may contain any, but exactly one of its fields. The fields can be eitherbasic or compound types or even identical types.

Let us consider the following example type definition. The types t1 and t2 can be arbitrary.

type union t3 { t1 f1, t2 f2}

An ancillary enumerated type is created in the generated class t3, which represents the selection:

enum union_selection_type { UNBOUND_VALUE = 0, ALT_f1 = 1, ALT_f2 = 2 };

The type t3::union_selection_type is used to distinguish the fields of the union. The predefinedconstant values are generated as t3::ALT_<field name>.

The generated class t3 will have the following public member functions:


104


Constructorst3() Initializes to unbound value.


Destructor ˜t3()

Assignment operator t3& operator=(const t3&) Assigns the given value.



Returns TRUE if the selectionsand field values are equal andFALSE otherwise.



const t1& f1() const Selects and gives access to thefirst field. If other field waspreviously selected, its valuewill be destroyed.

t1& f1() Gives read-only access to thefirst field. If other field isselected, this function willcause a dynamic test case error.So use get_selection() first.

t2& f2()

const t2& f2() const


union_selection_typeget_selection() const

Returns the current selection. Itwill return t3::UNBOUNDVALUE if the value is unbound,t3::ALT_f1 if the first field wasselected, and so on.

void log() const Puts the value into log.Example: { f1 := 5 } or { f2 :="abc" }.



Using the value of an unbound union variable for anything will cause dynamic test case error.

The anytype

The TTCN-3 anytype is implemented as a C++ class named anytype. The class is generated only if anactual anytype access is present in the module. It has the same interface as any other C++ classgenerated for a union, with a few differences:

If a field is a built-in type or the address type, the name used in union_selection_type is the name of

105

the runtime class implementing the type (usually the name of the type in all uppercase).

If a field is a user-defined type, the mapping rules in Mapping of Names and Identifiers aboveapply.

The names of field accessor functions are prefixed with AT_. This is necessary, because otherwisethe accessor function looks like a constructor to C++.

For example, for the following module

module anyuser { type record myrec {}

control { var anytype v_at; }}with { extension “anytype integer, myrec, charstring”}

The generated class name will be "anytype". The union_selection_type enumerated type will be:

enum union_selection_type { UNBOUND_VALUE = 0, ALT_INTEGER = 1, ALT_myrec = 2,ALT_CHARSTRING = 3 };

The field accessor methods will be:

INTEGER& AT_INTEGER();myrec& AT_myrec();CHARSTRING& AT_CHARSTRING();

6.4.3. Record of Type Construct

The TTCN–3 type construct record of makes a variable length sequence from one given type. Thisconstruct is implemented as a C++ class.

Let us consider the following example type definition. The type t1 can be arbitrary.

type record of t1 t2;

This definition will be translated to a C++ class that will be called t2.

There is an enum type called null_type defined in the Base Library that has only one possible value.NULL_VALUE stands for the empty "record of" value, that is, for {}.

106

Class t2 will have the following public member functions:



Constructors

t2() Initializes to unbound value.

t2(null type) Initializes to the empty value.


Destructor ˜t2()

Assignment operatort2& operator=(null type) Assigns the empty value.

t2& operator=(const t2&) Assigns the given value.


boolean operator==(null type)const



boolean operator!=(null type)const


Index operators

t1& operator[](int) Gives access to the givenelement. Indexing begins fromzero. If this element of thevariable was never used before,new (unbound) elements willbe allocated up to (andincluding) this index.

t1& opetator[](const INTEGER&)

const t1& operator[](int) const Gives read-only access to thegiven element. Index overflowcauses dynamic test case error.

const t1& opetator[](constINTEGER&) const

Rotating operators

t2 operator<⇐(int) C++ equivalent of operator <@.(rotate left)

t2 operator<⇐(constINTEGER&)

t2 operator>>=(int) C++ equivalent of operator @>.(rotate right)

t2 operator>>=(constINTEGER&)

Concatenation operator t2 operator+(const t2&) const Concatenates two arrays.

107


int size_of() const Returns the number ofelements, that is, the largestused index plus one and zerofor the empty value.

void set_size(int new_size) Sets the number of elements tothe given value. If the value hasfewer elements new (unbound)elements are allocated at theend. The excess elements at theend are erased if the value hasmore elements than necessary.

t2 substr(int index, intreturncount) const

Returns the section of the arrayspecified by the given startindex and length.

t2 replace(int index, int len,const t2& repl) const

Returns a copy of the array,where the section indicated bythe given start index and lengthis replaced by the given array.

void log() const Puts the value into log. Like {1,2, 3 }.



A record of value is unbound if no value has been assigned to it or it has at least one unboundelement. Using the value of an unbound record of variable for anything will cause dynamic testcase error.

Starting with the largest index improves performance when filling a record of value.


boolean operator==(null_type null_value, const t2& other_value); // Equalboolean operator!=(null_type null_value, const t2& other_value); // Not equal

Pre-generated record of and set of constructs

The C++ classes for the record of and set of constructs of most predefined TTCN-3 types are pre-generated and part of the TITAN runtime. Only a type alias (C++ typedef) is generated for instancesof these types declared in TTCN-3 and ASN.1 modules. There is a class with regular memoryallocation and one with optimized memory allocation pre-generated for each type. These classesare located in the PreGenRecordOf namespace.

Table 30. Pre-generated classes for record of/set of predefined types

108

C++ class name Equivalent type in TTCN-3

PREGEN__RECORD__OF__BOOLEAN record of boolean

PREGEN__RECORD__OF__INTEGER record of integer

PREGEN__RECORD__OF__FLOAT record of float

PREGEN__RECORD__OF__BITSTRING record of bitstring

PREGEN__RECORD__OF__HEXSTRING record of hexstring

PREGEN__RECORD__OF__OCTETSTRING record of octetstring

PREGEN__RECORD__OF__CHARSTRING record of charstring

PREGEN__RECORD__OF__UNIVERSAL__CHARSTRING record of universal charstring

PREGEN__RECORD__OF__BOOLEAN__OPTIMIZED record of boolean with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__INTEGER__OPTIMIZED record of integer with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__FLOAT__OPTIMIZED record of float with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__BITSTRING__OPTIMIZED record of bitstring with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__HEXSTRING__OPTIMIZED record of hexstring with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__OCTETSTRING__OPTIMIZED record of octetstring with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__CHARSTRING__OPTIMIZED record of charstring with { extension"optimize:memalloc" }

PREGEN__RECORD__OF__UNIVERSAL__CHARSTRING__OPTIMIZED

record of universal charstring with {extension "optimize:memalloc" }

PREGEN__SET__OF__BOOLEAN set of boolean

PREGEN__SET__OF__INTEGER set of integer

PREGEN__SET__OF__FLOAT set of float

PREGEN__SET__OF__BITSTRING set of bitstring

PREGEN__SET__OF__HEXSTRING set of hexstring

PREGEN__SET__OF__OCTETSTRING set of octetstring

PREGEN__SET__OF__CHARSTRING set of charstring

PREGEN__SET__OF__UNIVERSAL__CHARSTRING set of universal charstring

PREGEN__SET__OF__BOOLEAN__OPTIMIZED set of boolean with { extension"optimize:memalloc" }

PREGEN__SET__OF__INTEGER__OPTIMIZED set of integer with { extension"optimize:memalloc" }

PREGEN__SET__OF__FLOAT__OPTIMIZED set of float with { extension"optimize:memalloc" }

PREGEN__SET__OF__BITSTRING__OPTIMIZED set of bitstring with { extension"optimize:memalloc" }

PREGEN__SET__OF__HEXSTRING__OPTIMIZED set of hexstring with { extension"optimize:memalloc" }

109

C++ class name Equivalent type in TTCN-3

PREGEN__SET__OF__OCTETSTRING__OPTIMIZED set of octetstring with { extension"optimize:memalloc" }

PREGEN__SET__OF__CHARSTRING__OPTIMIZED set of charstring with { extension"optimize:memalloc" }

PREGEN__SET__OF__UNIVERSAL__CHARSTRING__OPTIMIZED

set OF\ universal charstring with { extension"optimize:memalloc" }

6.4.4. Set of Type Construct

The set of construct of TTCN–3 is implemented similarly to record of. The external interface of thisclass is exactly the same as in case of record of. For more details please see the previous section.

In the internal implementation only the equality operator differs. Unlike in record of, it considersthe unordered property of the set of type construct, that is, it returns TRUE if it is able to findexactly one pair for each element.

The index is a unique identifier for a set of element because the C++ class does not reorder theelements when a new element is added or an element is modified. The copy constructor also keepsthe original order of elements.

6.4.5. Enumerated Types

The TTCN–3 enumerated type construct is implemented as a C++ class with an embedded enum type.

type enumerated Day { Monday (1), Tuesday, Wednesday (3) };

The example above will result in the following, very similar C enum type definition which isembedded in the C++ class Day:

enum enum_type { Monday = 1, Tuesday = 0, Wednesday = 3, UNKNOWN_VALUE = 2, UNBOUND_VALUE = 4 };

The automatic assignment of numeric values is done according to the standard. Note that there aretwo extra enumerated values in C, which stand for the unknown and unbound values. They areused in the conversion functions described below. The compiler assigns the smallest two non-negative integer numbers that are not used by the user-defined enumerated values to the unknownand unbound values.

When using the C enum type and its values from user code the names must be prefixed with the C++class name. The enum type in the above example can be referenced with Day::enum_type, its valuescan be accessed as Day::Monday, Day::Tuesday, and so on.

The class Day will have the following public member functions:

Table 31. Public member functions of the class Day

110


Constructors

Day() Initializes to unbound value.

Day(int) Converts the given numericvalue to Day::enum_type andinitializes to it. Only validvalues are accepted.

Day(enum_type) Initializes to a given value.

Day(const Day&) Copy constructor.

Destructor ˜Day()

Assignment operator

Day& operator=(int) Converts the given numericvalue to Day::enum_type andassigns it. Only valid values areaccepted.

Day& operator=(enum_type) Assigns the given value.

Day& operator=(const Day&)


boolean operator==(enum_type)const


boolean operator==(constDay&) const

boolean operator!=(enum_type)const

boolean operator!=(const Day&)const

boolean operator<(enum_type)const

boolean operator<(const Day&)const

boolean operator⇐(enum_type)const

boolean operator⇐(const Day&)const

boolean operator>(enum_type)const

boolean operator>(const Day&)const

boolean operator>=(enum_type)const

boolean operator>=(constDay&) const

111

Casting operator operator enum_type() const Returns the enum_value.

Static conversion functions

static const char*enum_to_str(enum_type)

See below.

static enum_typestr_to_enum(const char *)

static booleanis_valid_enum(int)

static int enum2int(enum_type);

static int enum2int(const Day&);

Non-static conversion functions

int as_int() const; See below

void from_int(int);

void int2enum(int);


void log() const Puts the value into log. Likethis: Monday



The static member function Day::enum_to_str converts the given parameter of type Day::enum_typeto a NULL terminated C character string. It returns the string "<unknown>", if the input is not avalid value of the TTCN–3 enumerated type. The returned string is read-only, it must not bemodified.

The function Day::str_to_enum does the conversion in the reverse direction. It converts the symbolicenumerated identifier represented by a C character string back to the Day::enum_type equivalent. Itreturns the value Day::UNKNOWN_VALUE if the input string is not the equivalent of any of the possiblevalues in the enumerated type. The behavior of this function is undefined if the input parameterdoes not point to an addressable memory area.

In the above two functions the strings are treated case sensitive and they shall not contain anywhitespace or other characters that are not part of the enumerated value. In case of ASN.1ENUMERATED types the strings used by enum_to_str, str_to_enum and log represent the TTCN–3 view ofthe enumerated value, that is, the hyphenation characters are mapped to a single underscorecharacter. For example, if an ASN.1 enumerated type has a value with name my-enum-value andnumeric value 2, the function enum_to_str will return the string "my_enum_value" if the inputparameter equals to 2. Of course, its C++ equivalent will be my_enum_value with numeric value 2.

Static member function Day::is_valid_enum returns the Boolean value TRUE if there is a definedenumerated value having numeric value equal to the int parameter and FALSE otherwise.

The static member function Day::enum_to_int converts the given parameter of type Day orDay::enum_type to its numeric value. The member function as_int does the same thing for theenumerated instance.

112

The member function int_to_enum initializes the enumerated instance with the enumerated valuehaving numeric value equal to the given int parameter. A dynamic test case error is displayed ifthere is no such enumerated value. The member function from_int does the same thing.

If a value of type int is passed to the constructor or assignment operator the value is accepted onlyif it is a numerical representation of a valid enumerated value, that is, the function is_valid_enumreturns TRUE. A dynamic test case error occurs otherwise.

To avoid run-time errors at the decoding of invalid messages the Test Port writer should use theconstructor or assignment operator in this way:

Day myDayVar;int myIntVar = buffer[position];if (Day::is_valid_enum(myIntVar)) myDayVar = myIntVar;else myDayVar = Day::UNKNOWN_VALUE;

Using the value of an unbound enumerated variable for anything will cause dynamic test caseerror.

6.4.6. The address Type

The special TTCN–3 data type address is represented in C++ as if it was a regular data type. Thename of the equivalent C++ class is ADDRESS. If it is an alias to another (either built-in or user-defined) type then a C++ typedef is used.

6.5. Predefined FunctionsAnnex C of Methods for Testing and Specification (MTS); The Testing and Test Control Notationversion 3. Part 1: Core Language European Telecommunications Standards and Annex B of Methodsfor Testing and Specification (MTS); The Testing and Test Control Notation version 3. Part 7: UsingASN.1 with TTCN–3 European Telecommunications define a couple of predefined functions. Most ofthem perform conversion between the built-in types of TTCN–3. In our test executor these functionsare implemented in the Base Library in C++ language. They are available not only in TTCN–3 , butthey can be called directly from Test Ports as well.

The prototypes for these functions can be found in $TTCN3_DIR/include/Addfunc.hh, but for easiernavigation we list them also in the present document.

The majority of these functions have more than one polymorphic version: when appropriate, oneof them takes literal (built-in) C++ types as arguments instead of the objects of equivalent C++classes. For instance, if the incoming argument is stored in an int variable in your C++ code, youshould not construct a temporary object of class INTEGER because passing an int is faster andproduces smaller binary code. Similarly, the returned type is also literal when it is possible.

6.5.1. Integer to character

113



https://pdfs.semanticscholar.org/33b5/877c85f7fd4f35c7f58c39121358c3652966.pdf



extern CHARSTRING int2char(int value);extern CHARSTRING int2char(const INTEGER& value);

6.5.2. Character to integer

extern int char2int(char value);extern int char2int(const char *value);extern int char2int(const CHARSTRING& value);

6.5.3. Integer to universal character

extern UNIVERSAL_CHARSTRING int2unichar(int value);extern UNIVERSAL_CHARSTRING int2unichar(const INTEGER& value);

6.5.4. Universal character to integer

extern int unichar2int(const universal_char& value);extern int unichar2int(const UNIVERSAL_CHARSTRING& value);

6.5.5. Bitstring to integer

extern INTEGER bit2int(const BITSTRING& value);

6.5.6. Hexstring to integer

extern INTEGER hex2int(const HEXSTRING& value);

6.5.7. Octetstring to integer

extern INTEGER oct2int(const OCTETSTRING& value);

6.5.8. Charstring to integer

extern INTEGER str2int(const char *value);extern INTEGER str2int(const CHARSTRING& value);

114

6.5.9. Integer to bitstring

extern BITSTRING int2bit(const INTEGER& value, const INTEGER& length);

6.5.10. Integer to hexstring

extern HEXSTRING int2hex(const INTEGER& value, const INTEGER& length);

6.5.11. Integer to octetstring

extern OCTETSTRING int2oct(const INTEGER& value, const INTEGER& length);

6.5.12. Integer to charstring

extern CHARSTRING int2str(int value);extern CHARSTRING int2str(const INTEGER& value);

6.5.13. Length of string Type

This function is built into the equivalent C++ classes of all TTCN–3 string types:

int <any_string_type>::lengthof() const;

6.5.14. Number of elements in a structured type

This function is built into the C++ template classes of record of and set of types:

int <any_record_of_or_set_of_type>::size_of() const;

This function is currently not implemented for record and set types.

6.5.15. The IsPresent Function

This function is built into the wrapper C++ template class OPTIONAL:

boolean <any_optional_field>::ispresent() const;

6.5.16. The IsChosen Function

These functions are built into the equivalent C++ classes of TTCN–3 union types:

115

boolean <union_type>::ischosen(<union_type>::union_selection_type checked_selection) const;

6.5.17. The regexp Function

extern CHARSTRING regexp(const CHARSTRING& instr,const CHARSTRING& expression, const INTEGER& groupno);

6.5.18. Bitstring to charstring

extern CHARSTRING bit2str(const BITSTRING& value);

6.5.19. Hexstring to charstring

extern CHARSTRING hex2str(const HEXSTRING& value);

6.5.20. Octetstring to character string

extern CHARSTRING oct2str(const OCTETSTRING& value);

6.5.21. Character string to octetstring

extern OCTETSTRING str2oct(const char *value);extern OCTETSTRING str2oct(const CHARSTRING& value);

6.5.22. Bitstring to hexstring

extern HEXSTRING bit2hex(const BITSTRING& value);

6.5.23. Hexstring to octetstring

extern OCTETSTRING hex2oct(const HEXSTRING& value);

6.5.24. Bitstring to octetstring

extern OCTETSTRING bit2oct(const BITSTRING& value);

116

6.5.25. Hexstring to bitstring

extern BITSTRING hex2bit(const HEXSTRING& value);

6.5.26. Octetstring to hexstring

extern HEXSTRING oct2hex(const OCTETSTRING& value);

6.5.27. Octetstring to bitstring

extern BITSTRING oct2bit(const OCTETSTRING& value);

6.5.28. Integer to float

extern double int2float(int value);extern double int2float(const INTEGER& value);

6.5.29. Float to integer

extern INTEGER float2int(double value);extern INTEGER float2int(const FLOAT& value);

6.5.30. The Random Number Generator Function

The implementation is based on functions srand48 and drand48 of libc.

extern double rnd();extern double rnd(double seed);extern double rnd(const FLOAT& seed);

6.5.31. The Substring Function

Implemented for all string types.

117

extern BITSTRING substr(const BITSTRING& value, const INTEGER& index, const INTEGER& returncount);extern HEXSTRING substr(const HEXSTRING& value, const INTEGER& index, const INTEGER& returncount);extern OCTETSTRING substr(const OCTETSTRING& value, const INTEGER& index, const INTEGER& returncount);extern CHARSTRING substr(const CHARSTRING& value, const INTEGER& index, const INTEGER& returncount);extern UNIVERSAL_CHARSTRING substr(const UNIVERSAL_CHARSTRING& value, const INTEGER& index, const INTEGER& returncount);

6.5.32. Character string to float

extern double str2float(const char *value);extern double str2float(const CHARSTRING& value);

6.5.33. The Replace Function

Implemented for all string types.

extern BITSTRING replace(const BITSTRING& value, const INTEGER& index, const INTEGER& len, const BITSTRING& repl);extern HEXSTRING replace(const HEXSTRING& value, const INTEGER& index, const INTEGER& len, const HEXSTRING& repl);extern OCTETSTRING replace(const OCTETSTRING& value, const INTEGER& index, const INTEGER& len, const OCTETSTRING& repl);extern CHARSTRING replace(const CHARSTRING& value, const INTEGER& index, const INTEGER& len, const CHARSTRING& repl);extern UNIVERSAL_CHARSTRING replace(const UNIVERSAL_CHARSTRING& value, const INTEGER& index, const INTEGER& len, const UNIVERSAL_CHARSTRING& repl);

6.5.34. Octetstring to character string

extern CHARSTRING oct2char(const OCTETSTRING& value);

6.5.35. Character string to octetstring

extern OCTETSTRING char2oct(const char *value);extern OCTETSTRING char2oct(const CHARSTRING& value);

6.5.36. The Decompose Function

Not implemented yet.

118

6.5.37. Additional Non-Standard Functions

extern BITSTRING str2bit(const char *value);extern BITSTRING str2bit(const CHARSTRING& value);extern HEXSTRING str2hex(const char *value);extern HEXSTRING str2hex(const CHARSTRING& value);extern CHARSTRING float2str(double value);extern CHARSTRING float2str(const FLOAT& value);

template<typename TTCN_TYPE>CHARSTRING ttcn_to_string(const TTCN_TYPE& ttcn_data)

template<typename TTCN_TYPE>void string_to_ttcn(const CHARSTRING& ttcn_string, TTCN_TYPE& ttcn_value)

extern UNIVERSAL_CHARSTRING oct2unichar(const OCTETSTRING& invalue);extern UNIVERSAL_CHARSTRING oct2unichar(const OCTETSTRING& invalue, const CHARSTRING& string_encoding);

extern OCTETSTRING unichar2oct(const UNIVERSAL_CHARSTRING& invalue);extern OCTETSTRING unichar2oct(const UNIVERSAL_CHARSTRING& invalue, const CHARSTRING& string_encoding);

extern CHARSTRING get_stringencoding(const OCTETSTRING& encoded__value);extern OCTETSTRING remove_bom(const OCTETSTRING& encoded__value);

extern CHARSTRING encode_base64(const OCTETSTRING& msg, bool use_linebreaks);extern CHARSTRING encode_base64(const OCTETSTRING& msg);extern OCTETSTRING decode_base64(const CHARSTRING& b64);

See the section "Additional predefined functions" in the Programmer"s Technical Reference formore details.

6.6. Using the Signature ClassesA Test Port has three outgoing and three incoming types of operation that require the usage ofsignatures. These are call (getcall), reply (getreply) and raise (catch). Because of this, there arethree representation formats (classes generated by the compiler) of a signature the Test Port writershould be familiar with. This section describes these classes using an example.

Let us suppose the following signature definition:

signature MyProc(in integer inPar, out float outPar, inout bitstring inoutPar) return hexstring exception(charstring, integer, boolean);

The classes generated and needed to write a Test Port using this signature are MyProc_call,

119


MyProc_reply and MyProc_exception. These represent the parameters, the return value and theexception type and value of the signature needed by a call, reply or raise.

For example, if a port uses the signature MyProc as an output remote procedure, the Test Port getsthe outgoing parameters for a call operation towards the system in an instance of the classMyProc_call. In this case the classes MyProc_reply and MyProc_exception are used for placing anincoming reply or raise operation in the queue of the port (using the functions incoming_reply andincoming_exception of the port class).

6.6.1. The Representation of the Input Parameters

The class MyProc_call (using the above example) represents all incoming parameters of thesignature MyProc. It temporary stores the parameters inPar and inoutPar.

The generated class MyProc_call will have the following public member functions:

Table 32. Public member functions of the class MyProc_call


Parameter access functions

INTEGER& inPar() Gives access to parameterinPar.

const INTEGER& inPar() const

BITSTRING& inoutPar() The same, but it gives read-onlyaccess.

const BITSTRING& inoutPar()const

Other member functions void log() const Puts the parameters into log.

The parameters can be accessed via their access functions that have the same names as theparameters (name mapping also applies to these functions).

6.6.2. The Output Parameters and Return Value

The output parameters and return value (if defined) are represented by the class MyProc_reply thathas the following public member functions:

Table 33. Public member functions of the class MyProc_reply


Parameter access functions

FLOAT& outPar()const FLOAT&outPar() const

Gives access to parameteroutPar.

BITSTRING& inoutPar() constBITSTRING& inoutPar() const

The same, but it gives read-onlyaccess.

Access function for return value

HEXSTRING& return value() Gives access to the return value.

const HEXSTRING& returnvalue() const

120

Other member functions void log() const Puts the parameters into log.

The parameters can be accessed by their access functions, and the return value can be accessed viathe function return_value().

6.6.3. Representation of Signature Exceptions

The class representing the exceptions of a signature (remote procedure) is similar to therepresentation of the union data type. Using the above example this class is called MyProc_exception.This class is generated only if the signature has at least one exception type.

Table 34. Public member functions of the class MyProc_exception


Constructors

MyProc_exception() Initializes to unbound value.

MyProc_exception(constMyProc_exception&)

Copy constructor.

Destructor ˜MyProc_exception()

Assignment operatorMyProc_exception&operator=(constMyProc_exception&)

Assigns the given value.


CHARSTRING&CHARSTRING_field()

Selects and gives access to theCHARSTRING field. If other fieldwas previously selected, itsvalue will be destroyed.

constCHARSTRING&CHARSTRING_field() cons

Gives read-only access to theCHARSTRING field. If other fieldis selected, this function willcause dynamic test case error.So use get selection() first.

INTEGER& INTEGER_field()const INTEGER&INTEGER_field() const

BOOLEAN&BOOLEAN_field()constBOOLEAN& BOOLEAN_field()const

121


MyProc_exception::exception_selection_type get_selection()const

Returns the current selection. Itwill return MyProcexception::UNBOUND VALUE ifthe exception is unbound,MyProc exception::ALTCHARSTRING if a charstringvalue is present in theexception, and so on.

void log() const Puts the contents of theexception into the log.

If an exception type is a user-defined type the field name will be constructed from the C++namespace name of the module that the exception type resides in and the name of the C++ classthat realizes the exception type. The two identifiers are glued together using a single underscorecharacter. Please note that the namespace name is always present in the identifiers, even if theexception 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 accessfunctions will be named as My__Module_My__Record_field and the associated enum value will beMyProc_exception::ALT_My__Module_My__Record.

6.7. Object referencesAll function parameters, return values and variables of class type must use the OBJECT_REF wrapperclass, with the class type as its template parameter (e.g. MyClass in TTCN-3 translates toOBJECT_REF<MyClass> in C++). This class contains a pointer to the class object itself, and handles itsreference counting and deallocation.

Accessing members and methods through OBJECT_REF is done through the operator → (as if it were apointer in C++). Methods of OBJECT_REF are accessed through the operator . (see below).

Table 35. Public methods of the template class OBJECT_REF<T>, where T is a class type


Constructors

OBJECT_REF() Initializes to null reference.

OBJECT_REF(null_type) Initializes to null reference.

OBJECT_REF(T*) Initializes to a new object,which needs to be allocatedwith the C++ operator new.

OBJECT_REF(constOBJECT_REF<T>&)

Copy constructor.

template <typename T2>OBJECT_REF(OBJECT_REF<T2>&)

Copy constructor for areference of a different classtype, referring to an object oftype T or a subclass of T.

Destructor ~OBJECT_REF()

122


OBJECT_REF&operator=(null_type)

Assigns the null reference.

OBJECT_REF& operator=(constOBJECT_REF<T>&)

Assigns a reference of T.

template <typename T2>OBJECT_REF&operator=(OBJECT_REF<T2>&)

Assigns a reference of adifferent class type, referring toan object of type T or a subclassof T.


boolean operator==(null_type)const

Returns TRUE if the reference isnull.

boolean operator!=(null_type)const

Returns FALSE if the referenceis null.

boolean operator==(constOBJECT_REF<T>&) const

Returns TRUE if both this andthe parameter refer to the sameobject.

boolean operator!=(constOBJECT_REF<T>&) const

Returns FALSE if both this andthe parameter refer to the sameobject.

Access operators

T* operator*() Returns a pointer to the actualobject.

T* operator→() Accesses the object’s membersand methods.

const T* operator→() const Accesses the object’s constantmembers and methods.

Other methods

void log() const Puts the object (or null) into thelog.

boolean is_bound() const Returns TRUE if the reference isnot null.

boolean is_value() const Returns TRUE if the reference isnot null.

boolean is_present() const Returns TRUE if the reference isnot null.

[9] The built-in verdict and boolean constants in TTCN–3 shall be written with all lowercase letters, such as true or pass. Althoughprevious compiler versions have accepted TRUE or PASS as well, these words are treated by the compiler as regular identifiers asspecified in the standard.

[10] This section deals with the record and set types that have at least one field. See Empty Types for the C++ mapping of emptyrecord and set types.

123

Chapter 7. Tips & TroubleshootingInformation not fitting in any of the previous chapters is given in this chapter.

7.1. Migrating Existing C++ Code to the Naming Rulesof Version 1.7When using the new naming rules[11] the compiler generates a C++ namespace for each TTCN–3 andASN.1 module. The name of the namespace corresponds to the module. The generated C++ entitiesof a module are all placed in its namespace; therefore all the test port or protocol module code mustuse these namespaces.

Rules to follow when writing C++ code:

• When referencing an entity located in a different module its C++ name has to be prefixed withthe namespace name of that module.

• A test port class must be placed into the namespace of its module.

• Encoding and decoding functions must be placed into the namespace of the TTCN–3 module inwhich the external function was defined.

• All C++ entities have to be placed into namespace. An exception to this may be C++ entities usedonly locally; these are defined with the keyword static.

• For convenience the using namespace directive can be used in C++ source files. It is forbidden touse this directive in header files!

• C++ enum types are placed in the scope of their value class; enum types have to be prefixed bythe C++ name of the value class.[12]

7.2. Using External C++ Functions in TTCN–3 TestSuitesSometimes standard library functions[13] are called in the test suite or there is a need for efficientlyimplemented "bit-crunching" functions in the TTCN–3 ATS. In these cases functions to be calledfrom the test suite can be developed in C++.

There are the standard library functions as well as other libraries in the C++ functions. The loggingand error handling facilities of the run-time environment are also available as in case of Test Ports.

Since version 1.4.pl1 the semantic analyzer of the compiler checks the import statementsthoroughly. Therefore one cannot use the virtual C++ modules as before: C++ functions must bedefined as external functions to be accessible from TTCN–3 modules.

For example, the following definitions make two C++ functions accessible from TTCN–3 moduleMyExample and from any other module that imports MyExample.

124

7.2.1. Example TTCN–3 Module (MyExample.ttcn)

module MyExample {[...] external function MyFunction(integer par1, in octetstring par2) return bitstring; external function MyAnotherFunction(inout My_Type par1, out MyAnotherType par2);[...]}

The compiler will translate those external function definitions to C++ function prototypes in thegenerated header file MyExample.hh:

[...] extern BITSTRING MyFunction(const INTEGER& par1, const OCTETSTRING& par2); extern void MyAnotherFunction(My__Type& par1, MyAnotherType& par2);[...]

Both pre-defined and user-defined TTCN–3 data types can be used as parameters and/or returntypes of the C++ functions. The detailed description of the equivalent C++ classes as well as thename mapping rules are described in chapter XML Encoding (XER).

Using templates as formal parameters in external functions is possible, but not recommendedbecause the API of the classes realizing templates is not documented and subject to change withoutnotice.

The formal parameters of external TTCN–3 functions are mapped to C++ function parametersaccording to the following table:

Table 35. TTCN–3 formal parameters and their C++ equivalents

TTCN–3 formal parameter Its C++ equivalent

[in] MyType myPar const MyType& myPar

out MyType myPar MyType& myPar

inout MyType myPar MyType& myPar

[in] template MyType myPar Not recommended.

NOTE

In versions 1.6.pl3 and earlier the in keyword had an extra meaning in formalparameter lists. According to the TTCN–3 standard the parameter definitions MyTypemyPar and in MyType myPar are totally equivalent, but the earlier versions of thecompiler distinguished them. Unless the keyword in was present the compilerpassed the parameter by value (involving a copy constructor call) instead of using aconst reference. That is why it was recommended to use an explicit in keyword inparameter lists of external functions.

Due to the strictness of the TTCN–3 semantic analyzer one cannot use C/C++ data types with

125

external functions as formal parameters or return types, only TTCN–3 and ASN.1 data types areallowed. Similarly, one cannot use pointers as parameters or return values because they have noequivalents in TTCN–3 .

The external functions can be implemented in one or more C++ source files. The generated headerfile that contains the prototypes of the external functions shall be included into each C++ sourcefile. This file makes accessible all built-in data types, the user-defined types of the correspondingTTCN–3 module and all available services of the run-time environment (logging, error handling,etc.).

The name, return type and the parameters of the implemented C++ functions must match exactlythe generated function prototypes or the compilation will fail. The generated function prototype isin the namespace of the module, therefore the implementation of the function has to be placed inthat namespace, too.

7.3. Logging in Test Ports or External FunctionsWhen developing Test Ports or external functions the need may arise for debug messages. Insteadof using printf or fprintf, there is a simple way to put these messages into the log file of testexecutor. This feature can be also useful in case when an error or warning situation is encounteredin the Test Port, especially when decoding an incoming message.

There is a class called TTCN_Logger in the Base Library, which takes care of logging. For historicalreasons it has a static instance (object), which is called TTCN_logger. Since all member functions ofTTCN_Logger are static, they can be and should be called without the logger object. The usage ofobject TTCN_logger should be avoided in newly written code.

The class TTCN_Logger provides some public member functions. Using them any kind of message canbe put into the log file. There are two ways to log a single message, the unbuffered and the bufferedmode.

7.3.1. Unbuffered Mode

In unbuffered mode the message will be put into log immediately as a separate line together with atime stamp. Thus, the entire message must be passed to the logger class at one function call. The logmember function of the logger class should be used. Its prototype is:

static void TTCN_Logger::log(int severity, const char *fmt, …);

The parameter severity is used for filtering the log messages. The allowed values of the parameterare listed in table "First level (coarse) log filtering" in the Programmer’s Technical Reference. Werecommend using in Test Ports only TTCN_WARNING, TTCN_ERROR and TTCN_DEBUG. The parameter fmt is apointer to a format string, which is interpreted as in printf(3). The dots represent the optionaladditional parameters that are referred in format string. There is no need to put a newlinecharacter at the end of format string; otherwise the log file will contain an empty line after yourentry.

Here is an example, which logs an integer value:

126


int myVar = 5;TTCN_Logger::log(TTCN_WARNING, ``myVar = %d'', myVar);

Sometimes the string to be logged is static. In such cases there is no need for printf-style argumentprocessing, which may introduce extra risks if the string contains the character %. The logger classoffers a function for logging a static (or previously assembled) string:

static void TTCN_Logger::log_str(int severity, const char *str);

The function log_str runs significantly faster than log because it bypasses the interpretation of theargument string.

There is another special function for unbuffered mode:

static void TTCN_Logger::log_va_list(int severity, const char *fmt, va_list ap);

The function log_va list resembles to log, but it takes the additional printf arguments in one va_liststructure; va_list is defined in the standard C header file stdarg.h and used in functions withvariable number of arguments.

This function (and especially its buffered mode version, log_event_va_list) is useful if there is aneed for a wrapper function with printf-like syntax, but the message should be passed further toTTCN_Logger. With these functions one can avoid the handling of temporary buffers, which could bea significant performance penalty.

7.3.2. Buffered Mode

As opposite to the unbuffered operation, in buffered mode the logger class stores the messagefragments in a temporary buffer. New fragments can be added after the existing ones. Whenfinished, the fragments can be flushed after each other to the log file as a simple message. Thismode is useful when assembling the message in many functions since the buffer management oflogger class is more efficient than passing the fragments as parameters between the functions.

In buffered mode, the following member functions are available.

begin_event

begin_event creates a new empty event buffer within the logger. You have to pass the severity value,which will be valid for all fragments (the list of possible values can be found in the table "First level(coarse) log filtering" in the Technical Reference. If the logger already has an unfinished eventwhen begin event is called the pending event will be pushed onto an internal stack of the logger.That event can be continued and completed after finishing the newly created event.

static void TTCN_Logger::begin_event(int severity);

127


log_event

log_event appends a new fragment at the end of current buffer. The parameter fmt contains aprintf format string like in unbuffered mode. If you try to add a fragment without initializing thebuffer by calling begin event, your fragment will be discarded and a warning message will belogged.

static void TTCN_Logger::log_event(const char *fmt, …);

log_char

log_char appends the character c at the end of current buffer. Its operation is very fast compared tolog_event.

static void TTCN_Logger::log_char(char c);

log_event_str and log_event_va_list

The functions log_str and log_va_list also have the buffered versions called log_event_str andlog_event_va_list, respectively. Those interpret the parameters as described in case of unbufferedmode.

static void TTCN_Logger::log_event_str(const char *str);static void TTCN_Logger::log_event_va_list(const char *fmt, va_list ap);

OS_error

The function OS_error appends the textual description of the error code stored in global variableerrno at the end of current buffer. Thereafter that variable errno will be set to zero. The functiondoes nothing if the value of errno is already zero. For further information about possible errorcodes and their textual descriptions please consult the manual page of errno(3) and strerror(3).

static void TTCN_Logger::OS_error();

log

The C++ classes of predefined and compound data types are equipped with a member functioncalled log. This function puts the actual value of the variable at the end of current buffer. Unboundvariables and fields are denoted by the symbol <unbound>. The contents of TTCN–3 value objects canbe logged only in buffered mode.

void <any TTCN-3 type>::log() const;

128

end_event

The function end_event flushes the current buffer into the log file as a simple message, then itdestroys the current buffer. If the stack of pending events is not empty the topmost event is poppedfrom the stack and becomes active. The time stamp of each log entry is generated at the end and notat the beginning. If there is no active buffer when end_event is called, a warning message will belogged.

static void TTCN_Logger::end_event();

If an unbuffered message is sent to the logger while the buffer contains a pending event theunbuffered message will be printed to the log immediately and the buffer remains unchanged.

7.3.3. Logging Format of TTCN-3 Values and Templates

TTCN-3 values and templates can be logged in the following formats:

TITAN legacy logger format: this is the default format which has always been used in TITAN

TTCN-3 format: this format has ttcn-3 syntax, thus it can be copied into TTCN-3 source files.

Differences between the formats:

Value/template Legacy format output TTCN-3 format output

Unbound value "<unbound>" "-"

Uninitialized template "<uninitialized template>" "-"

Enumerated value name (number) name

The "-" symbol is the NotUsedSymbol which can be used inside compound values, but when loggingan unbound value which is not inside a record or record of the TTCN-3 output format of the loggeris actually not a legal TTCN-3 value/template because a value or template cannot be set to beunbound. Thus this output format can be copy-pasted from a log file into a ttcn-3 file or to a moduleparameter value in a configuration file only if it semantically makes sense.

The C++ API extensions to change the logging format:A new enum type for the format in TTCN_Logger class:+ enum data_log_format_t { LF_LEGACY,LF_TTCN };Static functions to get/set the format globally:data_log_format_t TTCN_Logger::get_log_format();voidTTCN_Logger::set_log_format(data_log_format_t p_data_log_format);A helper class to use a format until the end of the scope, when used as local variable. This can beused as follows:

129

{ Logger_Format_Scope lfs(TTCN_Logger::LF_TTCN); // sets TTCN-3 log format <log some values and templates>} // end of scope -> the original format is restored

It is recommended to use this helper class because using directly the format setting functions ofTTCN_Logger is more error prone, if the globally used logging format is not restored properly thenlog files might contain values/templates in a mixed/unexpected format.

7.3.4. Examples

The example below demonstrates the combined usage of buffered and unbuffered modes as well asthe working mechanism of the event stack:

TTCN_Logger::begin_event(TTCN_DEBUG);TTCN_Logger::log_event_str("first ");TTCN_Logger::begin_event(TTCN_DEBUG);TTCN_Logger::log_event_str("second ");TTCN_Logger::log_str(TTCN_DEBUG, "third message");TTCN_Logger::log_event_str("message");TTCN_Logger::end_event();TTCN_Logger::log_event_str("message");TTCN_Logger::end_event();

The above code fragment will produce three lines in the log in the following order:

third message second message first message

If the code calls a C++ function that might throw an exception while the logger has an active eventbuffer care must be taken that event is properly finished during stack unwinding. Otherwise thestack of the logger and the call stack of the program will get out of sync. The following exampleillustrates the proper usage of buffered mode with exceptions:

TTCN_Logger::begin_event(TTCN_DEBUG);try { TTCN_Logger::log_event_str("something"); // a function is called from here // that might throw an exception (for example TTCN_error()) TTCN_Logger::log_event_str("something else"); TTCN_Logger::end_event();} catch (...) { // don’t forget about the pending event TTCN_Logger::end_event(); throw;}

130

7.4. Error Recovery during Test ExecutionIf a fatal error is encountered in the Test Port, you should call the function TTCN_error must becalled to do the error handling. It has the following prototype in the Base Library:

void TTCN_error(const char *fmt, …);

The parameter fmt contains the reason of the error in a NUL terminated character string in theformat of a printf format string. If necessary, additional values should be passed to TTCN_error asspecified in the format string. The error handling in the executable test program is implementedusing C++ exceptions so the function TTCN_error never returns; instead, it throws an exception. Theexception value contains an instance of the empty class called TC_Error. This exception is normallycaught at the end of each test case and module control part. After logging the reasonTTCN_Logger::OS error() is called. Finally, the verdict is set to error and the test executor performsan error recovery, so it continues the execution with the next test case.

It is not recommended to use own error recovery combined with the default method (that is,catching this exception).

7.5. Using UNIX SignalsThe UNIX signals may interrupt the normal execution of programs. This may happen when theprogram executes system calls. In this case, when the signal handler is finished the system call willfail and return immediately with an error code.

In the executable test program there are system calls not only in the Base Library, but in Test Portsas well. Since the other Test Ports that you are using may have been written by many developers,one cannot be sure that they are prepared to the effects of signals. So it is recommended to avoidusing signals in Test Ports.

7.6. Mixing C and C++ ModulesModules written in C language may be used in the Test Ports. In this case the C header files must beincluded into the Test Port source code and the object files of the C module must be linked to theexecutable. Using a C compiler to compile the C modules may lead to errors when linking themodules together. This is because the C and C++ compilers use different rules for mapping functionnames to symbol names of the object file to avoid name clashes caused by the C++ polymorphism.There are two possible solutions to solve this problem:

1. Use the same C++ compiler to compile all of your source code (including C modules).

2. If the first one is impossible (when using a third party software that is available in binaryformat only), the definitions of the C header file must be put into an extern "C" block like this.

131

#ifdef __cplusplusextern "C" {#endif

<... your C definitions ...>

#ifdef __cplusplus};#endif

The latter solution does not work with all C++ compilers; it was tested on GNU C++ compiler only.

[11] The new naming rules are used by default; the naming rules can be changed using the compiler command line switch -N.

[12] The enum hack option has become obsolete with the new naming rules.

[13] C language functions cannot be called directly from TTCN–3; you need at least a wrapper function for them.

132

Chapter 8. References• [1] Methods for Testing and Specification (MTS); The Testing and Test Control Notation version

3. Part 1: Core Language European Telecommunications Standards Institute ES 201 873-1Version 4.5.1, April 2013

• [2] Methods for Testing and Specification (MTS); The Testing and Test Control Notation version3. Part 4: TTCN–3 Operational Semantics European Telecommunications Standards Institute. ES201 873-4 Version 4.1.1, June 2009

• [3] Methods for Testing and Specification (MTS); The Testing and Test Control Notation version3. Part 7: Using ASN.1 with TTCN–3 European Telecommunications Standards Institute. ES 201873-7 Version 4.5.1, April 2013

• [4] Methods for Testing and Specification (MTS); The Testing and Test Control Notation version3. Part 9: Using XML Schema with TTCN–3 European Telecommunications Standards Institute.ES 201 873-9 Version 4.5.1, April 2013

• [5] ITU-T, X.690, Information TechnologyASN.1 encoding rules: Specification of Basic EncodingRules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules(DER)International Telecommunication Union, November 2008

• [6] ITU-T, X.693, Information TechnologyASN.1 encoding rules: XML Encoding Rules (XER),November 2008

• [7] ITU-T, X.693 amendment 1, Information Technology ASN.1 encoding rules: XER encodinginstructions and EXTENDED-XER, October 2003

• [8] ISO/IEC 10646-1, Information technology – Universal Multiple-Octet Coded Character Set(UCS) – Part 1: Architecture and Basic Multilingual Plane, Second edition, 200009-15

• [9] RFC3629: UTF-8, a transformation format of ISO 10646

• [10] User Guide for TITAN TTCN-3 Test Executor

• [11] Installation guide for TITAN TTCN-3 Test Executor

• [12] Release Notes for TITAN TTCN-3 Test Executor

• [13] Technical Reference for TITAN TTCN-3 Test Executor

• [14] David A. Wheeler, Program Library HOWTO

• [15] ETSI ES 202 781 V1.4.1. (2015-06 Methods for Testing and Specification (MTS); The Testingand Test Control Notation version 3; TTCN-3 Language Extensions: Configuration andDeployment Support)

• [16] ETSI ES 202 782 V1.3.1. (2015-06 Methods for Testing and Specification (MTS); The Testingand Test Control Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance andReal Time Testing)

133


















https://www.itu.int/rec/T-REC-X.693-200310-S!Amd1

https://www.itu.int/rec/T-REC-X.693-200310-S!Amd1


https://github.com/eclipse/titan.core/blob/master/usrguide/userguide/UserGuide.adoc

https://github.com/eclipse/titan.core/blob/master/usrguide/installationguide/installationguide.adoc/

https://github.com/eclipse/titan.core/blob/master/usrguide/releasenotes/releasenotes.adoc

https://github.com/eclipse/titan.core/tree/master/usrguide/referenceguide/ReferenceGuide.adoc








Chapter 9. AbbreviationsAPI

Application Programming Interface

ASN.1

Abstract Syntax Notation One

ATS

Abstract Test Suite

BER

Basic Encoding Rules (of ASN.1)

BXER

Basic XER

BNF

Backus–Naur Formalism

CER

Canonical Encoding Rules (of ASN.1)

CXER

Canonical XER

DER

Distinguished Encoding Rules (of ASN.1)

ETS

Executable Test Suite

ETSI

European Telecommunications Standards Institute

EXER

Extended XER

GUI

Graphical User Interface

HC

Host Controller

HTML

Hypertext Markup Language

134

HTTP

HyperText Transfer Protocol

IP

Internet Protocol

LSB

Least Significant Byte

MC

Main Controller

MTC

Main (or Master) Test Component

PDU

Protocol Data Unit

pl

Patch Level

PTC

Parallel Test Component

PT

Port Type

SO

Shared Object

SUT

System Under Test

TC

Test Component (either MTC or PTC)

TCC

Test Competence Center

TCP

Transmission Control Protocol

TLV

Tag, Length, Value

TTCN

Tree and Tabular Combined Notation

135

TTCN–2

Tree and Tabular Combined Notation

TTCN–3

Tree and Tabular Combined Notation version 3 (formerly)Testing and Test Control Notation (new resolution)

URL

Universal Resource Locator

XER

XML Encoding Rules for ASN.1

XML

Extensible Markup Language

136

api technical reference for titan ttcn-3 test...

Documents