doc/HashMap/UG/EPTF CLL HashMap, User Guide.adoc

---
Author: József Gyürüsi
Version: 1/198 17-CNL 113 512, Rev. B
Date: 2011-12-06

---
= EPTF CLL HashMap, User Guide
:author: József Gyürüsi
:revnumber: 1/198 17-CNL 113 512, Rev. B
:revdate: 2011-12-06
:toc:

== About This Document

=== How to Read This Document

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

== System Requirements

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

= EPTF CLL HashMap

== Overview

The EPTF CLL HashMap component is a fundamental component that provides acces to a well-tested, industry standard GCC HashMap implementation located in STL. For gcc versions above 4.0 the HashMap feature uses the `std::tr1::unordered_map` library. HashMap is a hashed associate container that associates object of type key with object of type data. Looking up an element in a HashMap by its key is efficient, so HashMap is useful for "dictionaries" where the order of elements is irrelevant. The key in HashMap must be unique.

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

The EPTF CLL HashMap API includes the following files:

* Common files: Common functions and type definitions for all type of hash maps:
** __EPTF_CLL_HashMap_Definitions.ttcn__: Defines the HashMap component
** __EPTF_CLL_HashMap_Functions.ttcn__: Defines general functions like init for all HashMaps.
** __EPTF_CLL_HashMap_ExternalFunctions.hh__: Template functions for all types of HashMap.
* str2int files: The functions using hashmaps containing `<charstring, integer>` `<key, data>` pairs
** __EPTF_CLL_HashMapStr2Int_Functions.ttcn__: This TTCN-3 module contains function definitions to GCC HashMap functions
** __EPTF_CLL_HashMapStr2Int_ExternalFunctions.cc__: This C++ source file contains the implementations of functions to call standard GCC HashMap handling and maintenance functions.
* oct2int files: The functions using hash maps containing `<octetstring, integer>` `<key, data>` pairs
** __EPTF_CLL_HashMapOct2Int_Functions.ttcn__: This TTCN-3 module contains function definitions to GCC HashMap functions
** __EPTF_CLL_HashMapOct2Int_ExternalFunctions.cc__: This C++ source file contains the implementations of functions to call standard GCC HashMap handling and maintenance functions.
* int2int files: The functions using hash maps containing `<integer, integer>` `<key, data>` pairs
** __EPTF_CLL_HashMapInt2Int_Functions.ttcn__: This TTCN-3 module contains function definitions to GCC HashMap functions
** __EPTF_CLL_HashMapInt2Int_ExternalFunctions.cc__: This C++ source file contains the implementations of functions to call standard GCC HashMap handling and maintenance functions.

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

The HashMap feature is part of the TitanSim EPTF Core Load Library (CLL).

It requires files from these CLL features:

* `EPTF_CLL_Base`

== Installation

Since `EPTF_CLL_HashMap` 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_HashMap`:

* Copy the files listed in sections <<description_of_files_in_this_feature, Description of Files in This Feature>> and <<description_of_required_files_from_other_features, Description of Required Files from Other Features>> to the directory of the test suite or create symbolic links to them.
* Import the HashMap demo or write your own application using HashMap.
* 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 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 feature defines no module parameters.

= 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.

`*No HashMap-specific error messages are defined.*`

= 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.

`*Can't create new HashMap. HashMap name is not unique*`

HashMap names must be unique. Creating a HashMap with the name already assigned to another HashMap will cause this warning. New HashMap will not be created.

`*Can't get ID. No HashMap found with this name*`

To get the ID of a wrong HashMap name will cause this warning.

`*Can't get ID. HashMap not deleted. No HashMap found with this name*`

Trying to delete an already deleted HashMap will cause this warning.

`*Can't delete hasmap: No HashMap found with this id*`

Trying to delete an already deleted HashMap by ID will cause this warning.

= Examples

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

* _HashMap.cfg_
* __HashMap_demo.ttcn__

== Configuration File

The used configuration file (_HashMap.cfg_) is for the HashMap example is placed in the demo directory.

== Demo Module

The demo module (__HashMap_demo.ttcn__) illustrates a typical usage of the HashMap feature.

Example 1 shows how to initialize, create, delete and handle a specific HashMap:

[source]
----
Module HashMap_str2int_demo {

  import from EPTF_CLL_str2int_HashMap all;

  testcase tc_HashMap()
    runs on MyMTC_CT
  {

    f_EPTF_str2int_HashMap_Init ();
    var charstring v_first := "my_first_hashmap";
    var integer v_first_int;
    v_first_int := f_EPTF_str2int_HashMap_New (v_first);

    var integer v_first_check;
    var boolean is_first;
    is_first := f_EPTF_str2int_HashMap_GetID(v_first,v_first_check);
    log("The ID of ",v_first,"is ",v_first_check);

    f_EPTF_str2int_HashMap_Delete (v_first);
  }
  control
  {
    execute( tc_HashMap() );
  }
}
----

Example 2 shows how to insert, find elements of HashMap:

[source]
----
Module HashMap_str2int_demo {

  import from EPTF_CLL_str2int_HashMap all;

  testcase tc_HashMap()
    runs on MyMTC_CT
  {

    f_EPTF_str2int_HashMap_Init ();
    var charstring v_first := "my_first_hashmap";
    var integer v_first_int;
    v_first_int := f_EPTF_str2int_HashMap_New (v_first);

    f_EPTF_str2int_HashMap_Insert ( v_first_int,"hello", 11 );
    f_EPTF_str2int_HashMap_Insert ( v_first_int,"world", 22 );

    var integer v_hm_data;
    if ( f_EPTF_str2int_HashMap_Find (v_first_int,"hello", v_hm_data ) )
    {
      log("Reading data from hashmap first, key = hello data: \n", v_hm_data );
    }

    f_EPTF_str2int_HashMap_Erase (v_first_int, "hello" );

    f_EPTF_str2int_HashMap_Delete (v_first);
  }
  control
  {
    execute( tc_HashMap() );
  }
}
----

Example 3 shows how to get and set the size of HashMaps:

[source]
----
Module HashMap_str2int_demo {

  import from EPTF_CLL_str2int_HashMap all;

  testcase tc_HashMap()
    runs on MyMTC_CT
  {

    f_EPTF_str2int_HashMap_Init ();
    var charstring v_first := "my_first_hashmap";
    var integer v_first_int;
    v_first_int := f_EPTF_str2int_HashMap_New (v_first);

    f_EPTF_str2int_HashMap_Insert ( v_first_int,"hello", 11 );
    f_EPTF_str2int_HashMap_Insert ( v_first_int,"world", 22 );

    var integer v_hm_size;
    v_hm_size := f_EPTF_str2int_HashMap_Size (v_first_int);
    log( "Number of elements in hashmap: \n", v_hm_size );

    var float v_max_size;
    v_max_size := f_EPTF_str2int_HashMap_MaxSize (v_first_int);
    log( "Maximum size of hashmap: \n", v_max_size );

    log( "Resizing the hashmap to countain at least 500 empty buckets”);
    f_EPTF_str2int_HashMap_Resize (v_first_int,500);


    f_EPTF_str2int_HashMap_Delete (v_first);
  }
  control
  {
    execute( tc_HashMap() );
  }
}
----

Example 4 shows a while cycle with begin and next functions:

[source]
----
Module HashMap_str2int_demo {

  import from EPTF_CLL_str2int_HashMap all;

  testcase tc_HashMap()
    runs on MyMTC_CT
  {

    f_EPTF_str2int_HashMap_Init ();
    var charstring v_first := "my_first_hashmap";
    var integer v_first_int;
    v_first_int := f_EPTF_str2int_HashMap_New (v_first);

    f_EPTF_str2int_HashMap_Insert ( v_first_int,"hello", 11 );
    f_EPTF_str2int_HashMap_Insert ( v_first_int,"world", 22 );


    var charstring v_readkey:="";
    var boolean v_cycleIsOver:= f_EPTF_str2int_HashMap_Begin(v_first_int, v_readkey);
    if( not v_cycleIsOver )
    {
      log("No elements in hashmap" );
    };

    while (v_cycleIsOver)
    {
      var integer v_hm_data;
      if ( f_EPTF_str2int_HashMap_Find (v_first_int, v_readkey, v_hm_data ) )
      {
        log("key,data pairs: \n", v_readkey," ", v_hm_data );
      }
      v_cycleIsOver := f_EPTF_str2int_HashMap_Next(v_first_int, v_readkey);
  }

    f_EPTF_str2int_HashMap_Delete (v_first);
  }

  control
  {
    execute( tc_HashMap() );
  }
}
----

Example 5 shows the dumping HashMap functions:

[source]
----
Module HashMap_str2int_demo {

  import from EPTF_CLL_str2int_HashMap all;

  testcase tc_HashMap()
    runs on MyMTC_CT
  {

    f_EPTF_str2int_HashMap_Init ();
    var charstring v_first := "my_first_hashmap";
    var integer v_first_int;
    v_first_int := f_EPTF_str2int_HashMap_New (v_first);
    f_EPTF_str2int_HashMap_Init ();
    var charstring v_second := "my_second_hashmap";
    var integer v_second_int;
    v_second_int := f_EPTF_str2int_HashMap_New (v_second);


    f_EPTF_str2int_HashMap_Insert ( v_first_int,"hello", 11 );
    f_EPTF_str2int_HashMap_Insert ( v_first_int,"world", 22 );
    f_EPTF_str2int_HashMap_Insert ( v_second_int,"good", 88 );
    f_EPTF_str2int_HashMap_Insert ( v_second_int,"day", 99 );

    log("Dumping first hashmap by name");
    f_EPTF_str2int_HashMap_Dump(v_first);

    log("Dumping first hashmap by ID");
    f_EPTF_str2int_HashMap_DumpByID(v_first_int);

    log("Dumping all hashmaps");
    f_EPTF_str2int_HashMap_DumpAll();

    f_EPTF_str2int_HashMap_Delete (v_first);
    f_EPTF_str2int_HashMap_Delete (v_second);
  }
  control
  {
    execute( tc_HashMap() );
  }
}
----

= 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.

*HashMap:* +
It is a hashed associate container that associates object of type key with object of type data.

= 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 HashMap Function Description

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