doc/UG/XTDP Protocol Module User Guide.adoc

---
Author: István Kovács
Version: 198 17-CNL 113 663, Rev. C
Date: 2014-06-18

---
= XTDP Protocol Module User Guide
:author: István Kovács
:revnumber: 198 17-CNL 113 663, Rev. C
:revdate: 2014-06-18
:toc:

== How to Read This Document

This is the User Guide for the XTDP protocol module, which is developed for the TTCN-3 Toolset with TITAN.

== Presumed Knowledge

To use this protocol module the knowledge of the TTCN-3 language <<_1, ‎[1]>>, the TITAN Test Executor ‎<<_2, [2]>> and the XML to TTCN-3 mapping <<_4, ‎[4]>> is essential.

== System Requirements

Protocol module is a set of TTCN-3 source code files that can be used as part of TTCN-3 test suites only. So in order to compile and execute a TTCN-3 test suite using the XTDP protocol module the TITAN TTCN-3 Test Executor version R8A (1.8.pl0) or higher must be installed. For installation guide see ‎<<_2, [2]>>.

NOTE: This version of the protocol module is not compatible with TITAN releases earlier than R8A.

= Protocol Module

== Overview

Protocol module implements the message structures of the related protocol in a formalized way, using the standard specification language TTCN-3. This allows definition of test data in TTCN-3 language <<_1, ‎[1]>> and correct encoding/decoding of messages when executing test suites using the Titan TTCN-3 test environment <<_2, ‎[2]>>.

The XTDP protocol module is implemented in the following files:

* __XTDP_EncDecFunctions.ttcn__
* __XTDL.xsdXTDP-Message.xsd__

The XSD files cannot be used directly. These files will be used when creating XTDP messages.

* __ttcn_ericsson_se_xtdp_xtdp_1_0.ttcn__
* __ttcn_ericsson_se_xtdp_xul_1_0.ttcn__
* _UsefulTtcn3Types.ttcn_
* _XSD.ttcn_

NOTE: Any restrictions present in the XSD should be taken into account when assigning values to the types generated form the XSDs. For example the widget IDs, parentWidgetId-s in XTDP messages, should follow the pattern: +
"[a-zA-Z0-9]([a-zA-Z0-9]|_| |\-|\.|/){1,}"

== Installation

The protocol module can be used in developing TTCN-3 test suites using any text editor. However to make the work more efficient a TTCN-3-enabled text editor is recommended (for example `nedit`, `xemacs`). Since the XTDP protocol is used as a part of a TTCN-3 test suite, this requires TTCN-3 Test Executor be installed before the module can be compiled and executed together with other parts of the test suite. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, ‎[2]>>.

== Description of Encoding and Decoding Functions

These functions are generated by the TITAN TTCN-3 Test Executor. Module __XTDP_EncDecFunctions.ttcn__ contains the external function declarations of these functions.

== Configuration

=== Configuration for IPL4asp CNL 113 531

For the IPL4asp CNL 113 531 testport the function `f_XTDP_getMsgLen(…)` can be used for message delineation. For example, if we would like to use the component type definition foo_CT, then a possible implementation of a server port opening can be done as in the function `f_connectToServerGui()` example below.

[source]
----
type component foo_CT {
  port IPL4asp_PT IPL4;
…
}

function f_connectToServerGui(in charstring pl_addr, in integer pl_port)
runs on foo_CT return integer //connId
{
  var integer vl_connId;
  //map
  map(self:IPL4, system:IPL4);
  //connect to GUI
  var Result result:= IPL4asp_PortType.f_IPL4_connect(
    IPL4,
    pl_addr, pl_port,
    "0.0.0.0", 0,
    vl_connId, {tcp := {}})
  if (ispresent(result.errorCode)) {
    log("Connection failed: ",result.errorCode);
    setverdict(fail);
    stop;
  }
  log("Connection open: ",result);
  setverdict(pass);
  vl_connId:= result.connId

  //register message dissector for receiving
  var f_IPL4_getMsgLen fcb_msglen := refers(f_XTDP_getMsgLen);
  f_IPL4_setGetMsgLen(IPL4, vl_connId, fcb_msglen, {})

  return vl_connId;
}
----

=== Configuration for TCPasp CNL 113 347

For the TCPasp CNL 113 347 the message delineation can configured via testport parameters, similarly to the following. Let us assume that the TCP port has been named as "tcp_port".

[source]
----
[TESTPORT_PARAMETERS]
system.tcp_port.packet_hdr_length_offset := "0"
system.tcp_port.packet_hdr_nr_bytes_in_length := "4"
system.tcp_port.packet_hdr_byte_order := "MSB"
----

= Terminology

No specific terminology is used.

= Abbreviations

ETSI:: European Telecommunications Standards Institute

TTCN-3:: Testing and Test Control Notation version 3

XML:: Extensible Markup Language

XSD:: XML Schema Definition

= References

[[_1]]
[1] ETSI ES 201 873-1 v3.1.1 (06/2005) +
The Testing and Test Control Notation version 3. Part 1: Core Language

[[_2]]
[2] TITAN TTCN-3 Test Executor, document survey

[[_3]]
[3] User Documentation for the TITAN TTCN-3 Test Executor

[[_4]]
[4] ETSI ES 201 873-9 V4.1.1 (2009-06) +
ETSI Standard, Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; Part 9: Using XML schema with TTCN-3