blob: 932c82919eb97a4d5ea99de4da7f9abaadef4e7d [file] [log] [blame]
Author: József Gyürüsi
Version: 32/198 17-CNL 113 512, Rev. B
Date: 2012-09-10
= EPTF CLL DataSource, User Guide
:author: József Gyürüsi
:revnumber: 32/198 17-CNL 113 512, Rev. B
:revdate: 2012-09-10
== About This Document
=== How to Read This Document
This is the User Guide for the DataSource of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). TitanSim CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>. This document should be read together with the Function Description of the DataSource feature <<_5, [5]>>. For more information on the TitanSim CLL, consult the User's Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.
== System Requirements
In order to use the DataSource feature the system requirements listed in TitanSim CLL User Guide <<_4, [4]>> should be fulfilled.
= DataSource
== Compilation Dependencies
The EPTF CLL DataSource API includes the following files:
* __EPTF_CLL_DataSource_Definitions.ttcn__ - Definitions for DataSource
* __EPTF_CLL_DataSource_Functions.ttcn__ - Function definitions for DataSource
* __EPTF_CLL_DataSourceClient_Functions.ttcn__ - Function definitions for DataSourceClient.
* __EPTF_CLL_DataSource_ExternalFunctions.ttcn__ - Implementations of external functions.
== Usage Dependencies
The DataSource feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. To use the DataSource the user has to obtain the respective files from the following features:
* `Base`
* `CommandLineInterface`
* `Common`
* `HashMap`
* `Logging`
* `Semaphore`
* `Variable`
DataSource also requires files from:
* `TCCUsefulFunctions_CNL113472`
* `Protocol Module XTDP_CNL113663`
= Workflow
== Installation
Since `EPTF_CLL_DataSource` is used as a part of the TTCN-3 test environment this requires TTCN-3 Test Executor to be installed before any operation of these functions. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.
If not otherwise noted in the respective sections, the following are needed to use `EPTF_CLL_DataSource`:
* Copy the files listed in Section <<usage_dependencies, Usage Dependencies>> to the directory of the test suite or create symbolic links to them.
* Import the DataSource demo or write your own application using DataSource
* Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, [2]>>.
* Edit the configuration file according to your needs, see following section <<configuration, Configuration>>.
== Configuration
The executable test program behavior is determined via the run-time configuration file. This is a simple text file, which contains various sections. The usual suffix of configuration files is _.cfg_. For further information on the configuration file see <<_2, [2]>>.
This DataSource feature defines TTCN-3 module parameters as defined in <<_2, [2]>>, clause 4. Actual values of these parameters – when no default value or a different from the default actual value wished to be used – shall be given in the `[MODULE_PARAMETERS]` section of the configuration file.
This DataSource feature defines the following module parameters:
* `tsp_EPTF_DataSource_maxWaitTime := 10.0`
* `tsp_EPTF_DataSource_subscriptionMode := realtime`
* `tsp_EPTF_DataSource_refreshRate := -1`
Default values for the default refresh rate and subscription mode arguments of the `f_EPTF_DataSource_getData` function.
== Runtime Test Configuration Design (Deployment)
Any component in the runtime configuration can extend the `EPTF_DataSource_CT` or the `EPTF_DataSourceClient_CT` components. Even a single component can extend both component types at the same time.
= DataSource Usage
== Initialization
The DataSource and DataSourceClient features have to be initialized before use.
== Registration of Data Sources
The data source client then registers the data source with the feature name and the PTC name. The PTC name has to be the Base selfName. At registration a handler function has to be given. The role of this handler function is to return the EPTF Variable name of a given data specified by the `dataElement` and `params` arguments of the handler function.
== Data Access
After the data sources are registered on the DataSourceClient, the values of the data can be retrieved on the DataSource or the DataSourceClient component by the `getData` function. This function returns the name of the variable on the local component that stores the value of the data. The refresh period can be set at the first time when the `getData` function is called with appropriate data.
To check the presence of a dataSource, the function checkData can be used. This function does not perform variable subscription so the returned variable name might not exist even if the returned error code is `_zero_`. The `getData` function can be used to create the subscription also.
The conditions in data source have to be registered too. They have also a handler function which returns true or false if the condition is fulfilled for the given parameters or not. An error code is also retuned (`_0_` for no error, non-zero for error).
After the condition is registered on the DataSourceClient, the value of the condition can be retrieved on the DataSource component by the `getCondition` function. This function returns the Boolean value of the condition and the error code.
== DataSource with Command Line Interface Support
To be able to execute DataSource commands from the Telnet command line interface, the `DataSource_CLI` should be initialized. The `DataSource_CLI_CT` is an extension of the DataSource with command line interface support. It acts as a `CLI_Client` and registers the DataSource commands to the main CLI component. After initialization the DataSource commands can be used from the telnet CLI terminal.
Before accessing any dataElement from the CLI, their sources should be registered already otherwise the command will fail to retrieve the data.
= Examples
The "demo" directory of the deliverable contains the following example:
* __EPTF_CLL_DataSource_Demo.ttcn__
== Demo Module
There is a demo for the DataSource feature. It shows how the DataSource feature can be used.
The `MTC` is the main data source component. It is a data source client at the same time. Another PTC is created as a datasource client. Both clients register data sources, and the main data source component checks the data value.
In another test case the DataSource CLI is initialized. The `MTC` is the main CLI component as well. This demo test case can be used to try the Command Line Interface and execute DataSource commands in it. The telnet command can be used to connect to the Command Line Interface. The port number to connect to is given in the CFG file.
= Terminology
*TitanSim Core (Load) Library(CLL):* +
It is that part of the TitanSim software that is totally project independent. (I.e., which is not protocol-, or application-dependent). The TitanSim CLL is to be supplied and supported by the TCC organization. Any TitanSim CLL development is to be funded centrally by Ericsson.
= Abbreviations
CLI:: Command Line Interface
CLL:: Core Load Library
EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework
TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>.
= References
[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
The Testing and Test Control Notation version 3. Part 1: Core Language
[2] User Guide for the TITAN TTCN-3 Test Executor
[3] TitanSim CLL for TTCN-3 toolset with TITAN, Function Specification
[4] TitanSim CLL for TTCN-3 toolset with TITAN, User Guide
[5] EPTF CLL DataSource, Function Description
[6] TitanSim CLL for TTCN-3 toolset with TITAN +[Reference Guide]