doc/NameService/UG/EPTF CLL NameService, User Guide.adoc - titan/titan.Libraries.CLL - Git at Google

 ---
 Author: József Gyürüsi
 Version: 10/198 17-CNL 113 512, Rev. A
 Date: 2007-12-05

 ---
 = EPTF CLL NameService, User Guide
 :author: József Gyürüsi
 :revnumber: 10/198 17-CNL 113 512, Rev. A
 :revdate: 2007-12-05
 :toc:


 == About This Document

 === How to Read This Document

 This is the User Guide for the `NameService` 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 `NameService` feature ‎<<_5, [5]>>. For more information on the TitanSim CLL, consult the Users Guide <<_4, ‎[4]>> and the Function Specification ‎<<_3, [3]>> of the TitanSim.

 == System Requirements

 In order to use the `NameService` feature the system requirements listed in TitanSim CLL User Guide <<_4, ‎[4]>> should be fulfilled.

 = `NameService`

 == Overview

 The EPTF CLL `NameService` component is a fundamental component providing an implementation for name services in TTCN-3 environment. Such name services can be used to query values by name, for example, to query which component stores what resource.

 [[descr_of_files_in_this_feat]]
 == Description of Files in This Feature

 The EPTF CLL `NameService` API includes the following files:

 * `NameService`
 ** __EPTF_CLL_NameService_Definitions.ttcnpp__: This TTCN-3 module contains common type definitions that should be used in all `NameService` Components.
 ** __EPTF_CLL_NameService_Functions.ttcnpp__: This TTCN-3 module contains the implementation of `NameService` main functions.
 ** __EPTF_CLL_NameService_Client_Functions.ttcnpp__: This TTCN-3 module contains the implementation of `NameService` client functions.
 ** _EPTF_CLL_NameService_ExternalFunctions.cc_: This TTCN-3 module contains the c++ implementation of external functions of `NameService`.

 [[desc_req_files_other_feat]]
 == Description of Required Files from Other Features

 The `NameService` feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. The user has to obtain the products/files to be found under the respective feature names:

 * `Base`

 == Installation

 Since EPTF CLL `NameService` 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 `NameService`:

 * Copy the files listed in section <<descr_of_files_in_this_feat, Description of Files in This Feature>> and <<desc_req_files_other_feat, Description of Required Files from Other Features>> to the directory of the test suite or create symbolic links to them.
 * Import the `NameService` demo or write your own application using `NameService`.
 * Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, ‎[2]>>.
 * Edit the config file according to your needs, see following section <<configuration, 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 set of features defines TTCN-3 module parameters as defined in <<_2, ‎[2]>>, clause 4. Actual values of these parameters – when there is no default value or a different from the default actual value to be used – shall be given in the `[MODULE_PARAMETERS]` section of the configuration file.

 The EPTF `NameService` feature does not define any module parameters.

 == Usage

 To use the EPTF `NameService` feature

 * Extend one of your component with the `EPTF_NS_CT` component and initialize it.
 * Extend your component with `EPTF_NS_Client_CT`.
 * call the `init` function of the `NameService` Client to initialize the feature
 * use its public functions to register/query names

 Note, that the `init` function activates the main altstep of the NameService, so it is not necessary to call it explicitly in any of your altsteps.

 Do not access the component variables in `EPTF_NS_CT` and `EPTF_NS_Client_CT` directly! Use the API functions instead.

 = Error Messages

 NOTE: Besides the below described error messages, error messages shown in <<_2, ‎[2]>> or those of other used features or product may also appear.

 `*Unexpected message received from <senderComp>: <msg data>*`

 Unexpected message received on the `NameService` internal interface.

 = Warning Messages

 NOTE: Besides the below described warning messages, warning messages shown in <<_2, ‎[2]>> or those of other used features or product may also appear.

 `*The name already registered in msg: <msg> Original item is at <idx>: <registeredItem>*`

 The name already registered.

 `*The name is not registered in msg: <message>*`

 The name to be deregistered or queried does not exist.

 `*Registration failed for <registerNAck>*`

 The given name cannot be registered

 `*Query failed for name <name>*`

 The name was not found.

 `*–CLEANUP TIMEOUT– Not all responses received for bye messages.*`

 The cleanup not properly performed. The main `NameService` component does not respond. The execution of the current component is forced to terminate. This may result in errors in other components afterwards.

 = Examples

 The "demo" directory of the deliverable contains the following examples:

 * _main.cfg_
 * __EPTF_NameService_test.ttcn__

 == Configuration File

 The used configuration file (_main.cfg_) sets only the parameters in the `[LOGGING]` section. No special configuration is needed.

 == Demo Module

 The demo module __EPTF_NameService_test.ttcn__ illustrates a typical usage of the `NameService` feature.

 The usage of register/deregister/query functions are shown.

 = 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

 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]]
 [1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
 The Testing and Test Control Notation version 3. Part 1: Core Language

 [[_2]]
 [2] User Guide for the TITAN TTCN-3 Test Executor

 [[_3]]
 [3] TitanSim CLL for TTCN-3 toolset with TITAN, Function Specification

 [[_4]]
 [4] TitanSim CLL for TTCN-3 toolset with TITAN, User Guide

 [[_5]]
 [5] EPTF CLL NameService Function Description

 [[_6]]
 [6] TitanSim CLL for TTCN-3 toolset with TITAN, +
 http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]
	---
	Author: József Gyürüsi
	Version: 10/198 17-CNL 113 512, Rev. A
	Date: 2007-12-05

	---
	= EPTF CLL NameService, User Guide
	:author: József Gyürüsi
	:revnumber: 10/198 17-CNL 113 512, Rev. A
	:revdate: 2007-12-05
	:toc:


	== About This Document

	=== How to Read This Document

	This is the User Guide for the `NameService` 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 `NameService` feature ‎<<_5, [5]>>. For more information on the TitanSim CLL, consult the Users Guide <<_4, ‎[4]>> and the Function Specification ‎<<_3, [3]>> of the TitanSim.

	== System Requirements

	In order to use the `NameService` feature the system requirements listed in TitanSim CLL User Guide <<_4, ‎[4]>> should be fulfilled.

	= `NameService`

	== Overview

	The EPTF CLL `NameService` component is a fundamental component providing an implementation for name services in TTCN-3 environment. Such name services can be used to query values by name, for example, to query which component stores what resource.

	[[descr_of_files_in_this_feat]]
	== Description of Files in This Feature

	The EPTF CLL `NameService` API includes the following files:

	* `NameService`
	** __EPTF_CLL_NameService_Definitions.ttcnpp__: This TTCN-3 module contains common type definitions that should be used in all `NameService` Components.
	** __EPTF_CLL_NameService_Functions.ttcnpp__: This TTCN-3 module contains the implementation of `NameService` main functions.
	** __EPTF_CLL_NameService_Client_Functions.ttcnpp__: This TTCN-3 module contains the implementation of `NameService` client functions.
	** _EPTF_CLL_NameService_ExternalFunctions.cc_: This TTCN-3 module contains the c++ implementation of external functions of `NameService`.

	[[desc_req_files_other_feat]]
	== Description of Required Files from Other Features

	The `NameService` feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. The user has to obtain the products/files to be found under the respective feature names:

	* `Base`

	== Installation

	Since EPTF CLL `NameService` 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 `NameService`:

	* Copy the files listed in section <<descr_of_files_in_this_feat, Description of Files in This Feature>> and <<desc_req_files_other_feat, Description of Required Files from Other Features>> to the directory of the test suite or create symbolic links to them.
	* Import the `NameService` demo or write your own application using `NameService`.
	* Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, ‎[2]>>.
	* Edit the config file according to your needs, see following section <<configuration, 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 set of features defines TTCN-3 module parameters as defined in <<_2, ‎[2]>>, clause 4. Actual values of these parameters – when there is no default value or a different from the default actual value to be used – shall be given in the `[MODULE_PARAMETERS]` section of the configuration file.

	The EPTF `NameService` feature does not define any module parameters.

	== Usage

	To use the EPTF `NameService` feature

	* Extend one of your component with the `EPTF_NS_CT` component and initialize it.
	* Extend your component with `EPTF_NS_Client_CT`.
	* call the `init` function of the `NameService` Client to initialize the feature
	* use its public functions to register/query names

	Note, that the `init` function activates the main altstep of the NameService, so it is not necessary to call it explicitly in any of your altsteps.

	Do not access the component variables in `EPTF_NS_CT` and `EPTF_NS_Client_CT` directly! Use the API functions instead.

	= Error Messages

	NOTE: Besides the below described error messages, error messages shown in <<_2, ‎[2]>> or those of other used features or product may also appear.

	`Unexpected message received from <senderComp>: <msg data>`

	Unexpected message received on the `NameService` internal interface.

	= Warning Messages

	NOTE: Besides the below described warning messages, warning messages shown in <<_2, ‎[2]>> or those of other used features or product may also appear.

	`The name already registered in msg: <msg> Original item is at <idx>: <registeredItem>`

	The name already registered.

	`The name is not registered in msg: <message>`

	The name to be deregistered or queried does not exist.

	`Registration failed for <registerNAck>`

	The given name cannot be registered

	`Query failed for name <name>`

	The name was not found.

	`–CLEANUP TIMEOUT– Not all responses received for bye messages.`

	The cleanup not properly performed. The main `NameService` component does not respond. The execution of the current component is forced to terminate. This may result in errors in other components afterwards.

	= Examples

	The "demo" directory of the deliverable contains the following examples:

	* _main.cfg_
	* __EPTF_NameService_test.ttcn__

	== Configuration File

	The used configuration file (_main.cfg_) sets only the parameters in the `[LOGGING]` section. No special configuration is needed.

	== Demo Module

	The demo module __EPTF_NameService_test.ttcn__ illustrates a typical usage of the `NameService` feature.

	The usage of register/deregister/query functions are shown.

	= 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

	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]]
	[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
	The Testing and Test Control Notation version 3. Part 1: Core Language

	[[_2]]
	[2] User Guide for the TITAN TTCN-3 Test Executor

	[[_3]]
	[3] TitanSim CLL for TTCN-3 toolset with TITAN, Function Specification

	[[_4]]
	[4] TitanSim CLL for TTCN-3 toolset with TITAN, User Guide

	[[_5]]
	[5] EPTF CLL NameService Function Description

	[[_6]]
	[6] TitanSim CLL for TTCN-3 toolset with TITAN, +
	http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]