Creating an ITEX Access Application

This chapter is intended to be an introduction to how to create an ITEX Access application, and it is expected to be read sequentially. As ITEX Access is a C++ application programmers interface, this chapter will contain several ITEX Access applications written in C++. The chapter includes general ITEX Access application concepts as well as specific examples.

For reference, the test suite that is used as input to the various ITEX Access applications, is included in TTCN-GR form at the end of this chapter together with the source code for each example.

Note:  UNIX only ITEX Access is only available on UNIX.

Table of Contents 

• ITEX Access
• General Concepts
• The ITEX Access Application
• Basic Methods
• Traversing the Access Tree
• Examples
• The Identifiers
• Context
• Translating TTCN
• Summary
• Solutions to the Examples
• Makefile
• Solution 1
• Solution 2
• Solution 3
• Solution 4

ITEX Access

ITEX Access is a C++ application programmers interface. It is a platform for writing applications related to TTCN test suites such as:

• Executable test suites
• Interpreters
• Encoders and decoders
• Reporters

ITEX Access is meant to be used by executable test suite developers, translator developers as well as test result analyzers.

In order to make this chapter as complete as possible and thereby cover as many different ITEX Access application domains as we can, this chapter contains several different examples, each described in its own section. However, before we start with the examples, we will explain some general concepts that apply to every ITEX Access application.

Note:  This chapter is an ITEX Access primer and is not intended to provide a chapter in C++ programming.

General Concepts

The ITEX Access Application

An ITEX Access application is typically an application that produces some kind of output during the traversing of an Access tree. The Access tree, tree for short, is a tree oriented representation of a test suite. This tree is stored in the database <TestSuite>.itex where <TestSuite> is the user given name of the database.

The first section introduces the basic methods. These include the main function and how to initialize a test suite in an ITEX Access application. The second section describes how the traversing is done.

Basic Methods

When executing an ITEX Access application there are some basic methods that have to be applied before and after traversing the tree. First of all, to be able to get all the definitions needed, the header files ITEXAccessClasses.hh and ITEXAccessVisitor.hh have to be included. These files must be included in all ITEX Access applications as shown below:

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

Once this is done, we need to create an instance of the AccessSuite class. This can be done as follows:

AccessSuite suite;

The AccessSuite class can be seen as a handle to the Access tree and the symbol table. It will be used for opening and closing the database and for finding specific, named Access objects stored in the symbol table.

To open a database for reading, the following method has to be called:

Boolean open_ok = suite.open( arg );

where arg is a string containing the name of the database that shall be opened. This method must always be applied to the database before traversing the Access tree. The method returns a boolean value stating whether the database could be opened or not. To close a database the following method must be called:

Boolean close_ok = suite.close();

This method requires no database name to be given as the database that will be closed is associated with suite. The method returns a boolean value stating whether the database could be closed or not. Below is a generic ITEX Access main function where argv[1] contains the name of the database:

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

int main( int argc, char **argv )
{
  AccessSuite suite;
  
  if ( suite.open( argv[ 1 ] ) )             // OK open database?
    {
      // Write your Access application here
      // Typically start the traverser

     if ( suite.close( ) )                                // OK close database?
       return 1;      
     else                                 // Error close database!
       return 0;
     }
   else                              //Error open database!
       return -1; 
}

Traversing the Access Tree

The traversing of a test suite is the "engine" that actually drives the ITEX Access application to execute.

The previous section was only concerned with opening and closing of the database. This section will describe and explain the different methods that ITEX Access provides for starting the actual ITEX Access application, i.e. starting the traversing from different nodes in the Access tree.

To be able to allow the user to traverse the tree in a simple way, ITEX Access provides a visitor class that can be customized in a flexible way by the user. The class is called AccessVisitor and provides different ways of traversing.

In all the examples discussed in the following sub sections, we assume that we have a global instance of the class AccessSuite called suite, a global instance of the class AccessVisitor called visitor and that a test suite has been opened as described in the previous section.

Traversing from the Root of the Tree

As ITEX Access can be seen as a huge tree, the basic method for traversing will be to start traversing from the root. This will result in a traversing that will traverse the full Access tree starting from top. This is performed by calling the method:

Boolean root_ok = visitor.Visit( suite );

It is an error to try to traverse a database that has not been previously opened.

Traversing by Reference

In some cases it is desirable to start traversing from a specific table, i.e. a test case or a type definition. ITEX Access provides means for this in terms of using its symbol table.

The symbol table handles global entities, that is elements that must be globally unique within a test suite according to the TTCN standard (9646-3). Such elements are all variable names, all type names, all test case names, etc.

To start traversing the Access tree from a specific element, ITEX Access provides a simple solution divided into four steps:

1. The first step is to get a handle to the symbol table:



AccessNode node = suite.find( name );

This method will return a handle to the symbol table.

2. The second step is to verify that this handle holds an element present in the symbol table. This is performed by applying the following method:



Boolean symbol_table_ok = node.ok();

3. Assuming that the argument name was a global name in the test suite, we still do not know what kind of element it is. It could for example be a TTCN PDU type definition, a test case or a test step. The handle to the symbol table provides a method for finding the Access type of its corresponding element. The third step will be to ask the symbol table what type its corresponding element has:



Choices::Choice type = node.choice();

This method will return an enumerated value of type Choices::Choice revealing the type of the element. As there are several different Access types, this type check is best solved in a switch statements. Assuming that the name can be either a test case or a TTCN PDU type definition, the following switch statement will detect that.



switch( node.choice( ) )
{
  case Choices::c_TTCN_PDU_TypeDef:
      //
      // do something
      //
      break;
  case Choices::c_TestCase:
      //
      // do something else
      //
      break;
  default:
      //
      // do something default
      //
      break;
}



4. The fourth step is to call the corresponding traverser function.

Below is a complete example that will traverse a test suite starting from a specific element. The example assumes that the function main( ) is called with two arguments where the first is the name of the database and the second is the name of the element that the traversing shall start from. This application can only handle TTCN PDU type definitions and test cases.



int main( int argc, char **argv )
{
  AccessSuite suite;
  AccessVisitor visitor;

  if ( suite.open( argv[ 1 ] ) )             // OK open database?
    {
      //Get the handle

      AccessNode node = suite.find( arg[ 2 ] );      

      if ( node.ok( ) )                              // Handle ok?
        visitor.Visit( node );
      else                               // Error in symbol table
        return -2
      
      if ( suite.close( ) )                               // OK close database?
      return 1;      
      else                              // Error close database!
      return 0;
     }
   else                                     // Error open database!
     return -1; 
}

Examples

This section provides all the examples in this chapter. It starts with a simple ITEX Access application and continues from there. Every example is discussed in its own subsection. In each subsection, only the interesting parts are discussed. A complete solution to every example can be found in Solutions to the Examples.

Every ITEX Access application can be seen as an application providing a solution to a problem. These problems are related to TTCN test suites in general, such as reporters or style checkers, encoders and decoders. Therefore, every example in this chapter will be preceded with a small discussion of the actual problem that the corresponding ITEX Access application shall solve. Of course, the problems discussed in this chapter will mainly be of a fictive nature, but they will reflect the simplicity of ITEX Access and the different implementation techniques and methods that ITEX Access provides.

In all examples, we assume that there exist a global instance of the class AccessSuite called suite, a global instance of the class AccessVisitor called visitor and that a test suite has been opened.

The Identifiers

Objective

In every test suite there exists a set of identifiers. The objective of this example is to print out every identifier present in the test suite.

Solution 1

Every identifier present in an Access tree will be represented as an Access node of type Identifier. The solution will therefore only include one user defined method in the visitor class instance that, when entering the node Identifier, prints the content of that class. In this case it is the name of the identifier. The method is provided below.

void Trav::VisitIdentifier( const Identifier& Me )
{
  printf( "Identifier %s\n", (const char*) Me );
}

This method will be called from ITEX Access every time the traverser enters the Identifier node. The name Identifier is the name of the Access node and the prefix tag Visit means that this is a visiting method.

As the task of an ITEX Access application is to traverse a test suite according to the traverser and call possibly user defined functions or methods, we need to create a traverser that will use the default traversing, but have the desired small change. This is done by sub classing as follows:

class Trav : public AccessVisitor
{
public:
  void VisitIdentifier( const Identifier& id );
};

As identifiers are present everywhere in the Access tree, no change to the traversing order needs to be done. The default traverser will be used and the traversing will start from root.

The full solution is found in Solution 1.

Context

Objective

When executing the previous example, all identifiers in the given test suite will be printed. By looking at the output one might think that there should not be so many identifiers in the test suite, but the way in which the grammars are specified (both TTCN and ASN.1), nearly every grammar rule ends in a identifier. This example will explain the importance of calling the user defined function at their correct place, or to be more specific, in its right context.

Let us assume, with the previous example in mind, that we want to distinguish between TTCN PDU type definition identifiers and TTCN PDU constraint identifiers (the rest is of no concern). This can be achieved in several different ways. Below are two different solutions to this problem.

Solution 2

This first solution, looking at each identifiers type, will be implemented in the visiting method used in the previous example. However, it has to be extended to look at each identifier type and only print the appropriate ones. The updated method is found below.

void Trav::VisitIdentifier( const Identifier& Me )
{
  switch( Me.choice( ) ) 
    {
      case Choices::c_TTCN_PDU:
        printf( "Identifier `%s' is a TTCN PDU type\n",
                (const char*) Me );
        break;

      case Choices::c_TTCN_PDU_Cons:
        printf( "Identifier `%s' is a TTCN PDU constraint\n",
                (const char*) Me );
        break;

      default:
        break;
    }
}

Solution 3

The second solution will replace the used method with two new ones. The first method will print out every TTCN PDU type definition identifier. This will be done in the method VisitTTCN_PDU_TypeDef. The second, VisitTTCN_PDU_Constraint, will print out every TTCN PDU constraint identifier. In each method the Identifier Access node is reached by explicit addressing, that is, explicitly naming the path to the Access node Identifier. Their corresponding definitions are supplied below.

 void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
  printf( "Identifier `%s' is a TTCN PDU type\n",
           (const char*) Me.pdu_Id( ).pdu_IdAndFullId( )
           .pdu_Identifier( ) );
}

void Trav::VisitTTCN_PDU_Constraint( const TTCN_PDU_Constraint& Me)
{
  printf( "Identifier `%s' is a TTCN PDU constraint\n",
          (const char*) Me.consId( ).consIdAndParList( ).
          .constraintIdentifier( ) );
}

The definition of the visitor object is done as follows:

class Trav : public AccessVisitor
{
public:
  void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& );      
  void VisitTTCN_PDU_Constraint( const TTCN_PDU_Constraint& );
};

Comments

When executing the two examples above with the test suite in the end of this chapter as input, one will find that the output is not equivalent. The first solution will have some more output lines that the second one. By adding the following line to each method, one will detect in which table the identifier was found.

printf( "In table `%s': ", (const char*) Me.table_name() );

One will find that the extra lines of output in the first solution are produced from the Constraints Part and the Dynamic Part. This is true due to the fact that the type identifiers are being used in each constraint and the constraint identifiers are being used in the Constraint Reference column in each test case and test step table.

The full solutions are found in Solution 2 and Solution 3.

Translating TTCN

A very common and useful ITEX Access application is to translate a test suite to another target language. Examples are C, C++, Pascal etc. By doing this translation we can thereby create an executable test suite. To achieve this, one needs a TTCN translator that translates a TTCN test suite to the specific source code. This example will not be a full translator, but will rather show how such a translator can be written by using ITEX Access.

Objective

In this example, we will translate TTCN PDU type definitions to C where each PDU will be a unique C type. To achieve this, we need to have some kind of mapping between TTCN and C. One way to do this is to do a case study. First we will look at a TTCN PDU type definition in the table format and from that table extract how the corresponding C representation shall be. Then, a generic representation of all TTCN PDUs in C will be defined. This generic representation will then be implemented in ITEX Access, and thereby a generic TTCN PDU type definition to C translator will be implemented.

Solution 4

Let us have a look at a TTCN PDU type definition in table format. The table below, the TTCN PDU type definition SEND, is taken from the test suite attached to the end of this chapter.

Figure 192 : TTCN PDU Type Definition

A corresponding C representation of the above type could look something like:

typedef struct {
 INTEGER Field_1;
 BOOLEAN Field_2;
} SEND;

That is, a structured type holding the same number of elements as the corresponding TTCN type definition. In this example, no consideration is taken to the PCO type. This is only done for simplicity and can of course be included in the type as well.

As one can see in this example there are a lot similarities between the TTCN definition and the C representation in terms of names of elements and their corresponding type. This helps us define a generic C representation of a TTCN PDU type definition as below:

typedef struct {
 Element1_Type Element1_Name;
 Element2_Type Element2_Name;
 ...
 ElementN_Type ElementN_Name;
} PDU_TypeName;

The type and name of each element is taken from the corresponding names in the TTCN type definition and the type defined is named as in TTCN.

Now, the next step is to implement this generic type in ITEX Access! To do this, we divide the generic C type into three distinct elements; the header, the body and the footer.

The Header and Footer

The visitor method that traverses the TTCN PDU type definitions, will be the one responsible for generating the header and footer of the generated C structure definition. The method may look something like this:

void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
  // Generate the header part

  cout << Me.pdu_Id( ) << "_encode( const ";
  cout << Me.pdu_Id( ) << "& me, char* enc_buf )";
  cout << "\n{" << endl;

  // Traverse fields using default traverser

  AccessVisitor::VisitPDU_FieldDcls( Me.pdu_FieldDcls( ) );

  // Generate the footer part

  cout << "}" << endl;
}

This method will be called every time the traverser enters the Access node TTCN_PDU_TypeDef.

The Body

The body of the type definition, is a collection of rows where each row is translated identically. A row can be translated by defining the following method:

void Trav::VisitPDU_FieldDcl( const PDU_FieldDcl& Me )
{
  printf( "  %s %s;\n", 
          (const char*) get_type_str( Me.pdu_FieldType( ), 
          (const char*) get_id( Me.pdu_FieldId( ) );
}

where get_type_str and get_id are two functions returning the type and the name of the element respectively. This method shall be called every time the traverser enters the Access node PDU_FieldDcl.

The full solution is found in Solution 4.

Summary

ITEX Access provides a platform for generating applications in the domain of TTCN, conformance testing and related applications such as translators, interpreters, analyzers, reporters, etc. ITEX Access is a C++ representation of the related grammars that spans the language TTCN. We hope that this chapter has revealed the basis of ITEX Access, the methods it supplies and how easy it is to use. All examples in this chapter have full solutions in Solutions to the Examples.

Solutions to the Examples

This section contains fully implemented solutions to each example given in the Examples. It will also contain the expected output when executing each ITEX Access application with the example test suite as input.

Makefile

This generic Makefile has been used for compilation and linking:

#----------------------------------------------------------
# Name: Makefile
#
# Destcription:
# Generic Makefile for Access applications
# Note that the makefile requires the variable 
# itexaccess to be set.
#----------------------------------------------------------

ACCESS-INCL = $(itexaccess)/include
ACCESS-LIB = $(itexaccess)/lib

TARGET = the name of the target 
OBJS = $(TARGET).o

#------------------------------------------------------

$(TARGET) :      $(OBJS)
      $(CCC) -L$(ACCESS-LIB) -Bstatic -o $@ $(OBJS) -laccess
      strip $@

#------------------------------------------------------

clean :
      /bin/rm $(TARGET) $(OBJS)

#----------------------------------------------------------

.SUFFIXES: .cc .o

.cc.o :
      $(CCC) -I$(ACCESS-INCL) -c -o $@ $<

Solution 1

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
  void VisitIdentifier( const Identifier& id );
};


void Trav::VisitIdentifier( const Identifier& Me )
{
  printf( "Identifier %s\n", (const char*) Me );
}


int main( int /* argc */, char **argv )
{
  AccessSuite suite;

  if( suite.open( argv[ 1 ] ) )   // OK open database?           
   {
      Trav visitor;

      visitor.Visit( suite );

      if( suite.close( ) )      // OK close database?
        return 1;     
      else                      // Error close database!
        return 0;
   }

  else                          // Error open database!
    return -1; 
}

Output

> ./print-ids ../Example_Suite_A.itex
Identifier Example_Suite_A
Identifier Example_Suite_A
Identifier L
Identifier LOWER_PCO
Identifier SEND
Identifier LOWER_PCO
Identifier Field_1
Identifier Field_2
Identifier RECEIVE
Identifier LOWER_PCO
Identifier Field_1
Identifier Field_2
Identifier S1
Identifier SEND
Identifier Field_1
Identifier Field_2
Identifier R1
Identifier RECEIVE
Identifier Field_1
Identifier Field_2
Identifier TEST_CASE_1
Identifier L
Identifier SEND
Identifier S1
Identifier TEST_STEP_1
Identifier TEST_STEP_1
Identifier L
Identifier RECEIVE
Identifier R1
Identifier L
>

Solution 2

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
  void VisitIdentifier( const Identifier& Me );
};


int main( int /* argc */, char **argv )
{
  AccessSuite suite;

  if( suite.open( argv[ 1 ] ) )   // OK open database?           
   {
      Trav visitor;

      visitor.Visit( suite );

      if( suite.close( ) )      // OK close database?
        return 1;     
      else                      // Error close database!
        return 0;
   }

  else                          // Error open database!
    return -1; 
}


void Trav::VisitIdentifier( const Identifier& Me )
{
  switch( Me.choice( ) ) 
    {
      case Choices::c_TTCN_PDU:
        printf( "Identifier `%s' is a TTCN PDU type\n",
                (const char*) Me );
        break;

      case Choices::c_TTCN_PDU_Cons:
        printf( "Identifier `%s' is a TTCN PDU constraint\n",
                (const char*) Me );
        break;

      default:
        break;
    }
}

Output

> ./print-ids ../Example_Suite_A.itex

Identifier `SEND' is a TTCN PDU type
Identifier `RECEIVE' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `SEND' is a TTCN PDU type
Identifier `R1' is a TTCN PDU constraint
Identifier `RECEIVE' is a TTCN PDU type
Identifier `SEND' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `RECEIVE' is a TTCN PDU type
Identifier `R1' is a TTCN PDU constraint
>

Solution 3

Code

#include <access.hh>

void id_pre_TTCN_PDU_TypeDef(const TTCN_PDU_TypeDef& Me);
void id_pre_TTCN_PDU_Constraint(const TTCN_PDU_Constraint& Me);

int main( int /* argc */, char **argv )
{
  AccessSuite suite;

  if( suite->open( argv[ 1 ] ) )   // OK open database?
    {
      // Setup the id writing functions
      pre_TTCN_PDU_TypeDef = id_pre_TTCN_PDU_TypeDef;
      pre_TTCN_PDU_Constraint = id_pre_TTCN_PDU_Constraint;

      // Start traversing from root.
      if( !suite->trav_root() )
        return 1;
      
      if( suite->close() )         // OK close database?
        return 0;
       else                        // Error close database!
        return 2;
    }
  
  else                             // Error open database!
   return -1; 
}


void id_pre_TTCN_PDU_TypeDef(const TTCN_PDU_TypeDef& Me)
{
  printf( "Identifier `%s' is a TTCN PDU type\n",
           (const char*) Me->pdu_Id()->pdu_IdAndFullId()
           ->pdu_Identifier() );
}


void id_pre_TTCN_PDU_Constraint(const TTCN_PDU_Constraint& Me)
{
  printf( "Identifier `%s' is a TTCN PDU constraint\n",
          (const char*) Me->consId()->consIdAndParList()
          ->constraintIdentifier() );
}

Output

> print-ids ../Example_Suite_A.itex

Identifier `SEND' is a TTCN PDU type
Identifier `RECEIVE' is a TTCN PDU type
Identifier `S1' is a TTCN PDU constraint
Identifier `R1' is a TTCN PDU constraint
>

Solution 4

Code

#include <ITEXAccessClasses.hh>
#include <ITEXAccessVisitor.hh>

class Trav : public AccessVisitor
{
public:
  void VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me );
  void VisitPDU_FieldDcl( const PDU_FieldDcl& Me );
};

Astring get_type_str(const AccessNode& n);
Astring get_id(const AccessNode& n);

int main( int /* argc */, char **argv )
{
  AccessSuite suite;

  if( suite.open( argv[ 1 ] ) )   // OK open database?
    {
      Trav visitor;

      visitor.Visit( suite );

      if( suite.close() )         // OK close database?
        return 0;
      else                        // Error close database!
        return 2;
    }
  
  else                            // Error open database!
    return -1;
}


void Trav::VisitTTCN_PDU_TypeDef( const TTCN_PDU_TypeDef& Me )
{
  // Generate the header part

  cout << Me.pdu_Id( ) << "_encode( const ";
  cout << Me.pdu_Id( ) << "& me, char* enc_buf )";
  cout << "\n{" << endl;

  // Traverse fields using default traverser

  AccessVisitor::VisitPDU_FieldDcls( Me.pdu_FieldDcls( ) );

  // Generate the footer part

  cout << "}" << endl;
}


void Trav::VisitPDU_FieldDcl( const PDU_FieldDcl& Me )
{
  printf( "  %s %s;\n", 
          (const char*) get_type_str( Me.pdu_FieldType( ), 
          (const char*) get_id( Me.pdu_FieldId( ) );
}

// Help functions

Astring get_type_str(const AccessNode& n)
{
  switch ( n.choice( ) )
    {
    case Choices::c_PDU_FieldType:
      return n.PDU_FieldType().content();

    default:
      fprintf( stderr, "Bad case in get_type %d\n",
               (int) n.choice( ) );
      abort();
    }
}


Astring get_id(const AccessNode& n)
{
  switch ( n.choice( ) )
    {
      case Choices::c_PDU_FieldId:
           if ( n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
                .choice( )
                == Choices::c_MacroSymbol )
           return n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
                  .macroSymbol( );
        else
           return n.PDU_FieldId( ).pdu_FieldIdOrMacro( )
                  .pdu_FieldIdAndFullId( )    
                  .pdu_FieldIdentifier( );
      
      case Choices::c_PDU_Id:
        return n.PDU_Id( ).pdu_IdAndFullId( )
               .pdu_Identifier( );

      default:
        fprintf( stderr, "Bad case in get_id %d\n",
                 (int) n.choice( ) );
        abort( );
    }
}

Output

> ./pdu2c ../Example_Suite_A.itex

typedef struct {
  INTEGER Field_1;
  BOOLEAN Field_2;
} SEND;

typedef struct {
  INTEGER Field_1;
  BOOLEAN Field_2;
} RECEIVE;
>