ddt
Script emos_ddt_access_lib

CompiledModule
  |
  +--emos_ddt_access_lib

This library defines a sequential forward "iterator" (as much as one can emulate a real iterator in a language such as TSL) for data tables (ddt-interface). The main benefits of this iterator are: 1.) you can loop through any table in an uniform way, 2.) you can elegantly define a set of entries to be iterated through, 3.) you can simultaneously have iterators for multiple data tables (ane at a time per table!) 4.) you can use it to iterate anything, not only data tables.

NOTE! To understand how this iterator works use the analogy of selecting pages to be printed in a word-processing program. This sort of dialogs typically allow you to specify the RANGE of pages by connecting a first and the last page in the range with a hyphen (e.g. 3-9 ) and INDIVIDUAL pages by separating them with commas (e.g. 1,5,9,15-17,20). Exactly the same syntax is used with this iterator. So, if you call

		DDT_ACCESS_init( table, "1-3,7,9-11" );

the

		DDT_ACCESS_get_next( table );

will return you the sequence 1,2,3,7,9,10,11. This iterator also accepts non-numeric expressions such as

		DDT_ACCESS_init( table, "foo,bar,anyway" );

Note however that this iterator does not read a data table in any way. So if your table contains following five columns

		aaa;foo;ccc;bar;eee

the expression

		DDT_ACCESS_init( table, "foo-bar" );

will return you "foo-bar" instead of "foo", "ccc", "bar" as you might have expected. If you use alpha names you, should know them in advance, i.e.

		DDT_ACCESS_init( table, "foo,ccc,bar" );

You might think of this as a serious limitation, but once you learn how EMOS uses data tables in its framework, you will probably apreciate the

Tsl

emos_ddt_access_lib.tsl

Function Summary

protected String	col_test_invalid() Test with invalid values
protected String	col_test_valid() Test with valid values
String	DDT_ACCESS_clean(in table) Removes access for the given name and frees the internal buffers.
String	DDT_ACCESS_get_next(in table) Returns the name of the next test to be processed.
String	DDT_ACCESS_has_more(in table) Indicates whether a subsequent call to DDT_ACCESS_get_next() is about to succeed or not.
String	DDT_ACCESS_init(in table, in tests) Initialises the standard access algorithm.
protected String	delete_dimension(inout[] arr, in dim) This function deletes a dimension from a multidimensional array.
protected String	get_range(in from, in to, out x, out y, out b)
protected String	init_count(in table, in tests) Analyses the given string tests and builds an array that contains all individual values that were specified.

Function Detail

DDT_ACCESS_init

public String DDT_ACCESS_init(in table,
                              in tests)

Initialises the standard access algorithm. The tests can be specified with syntax described on library-level (e.g. "1-5,7,9,aaa,xxx,12-35).

Parameters:

table - (in) unique name for the iterator (normaly, name of the data table)

tests - (in) test names (e.g. "1-15" or "1-3,5,7" or "a,b,c", etc.)

Returns:

E_OK: initialisation succeeded !E_OK: invalid test set

DDT_ACCESS_clean

public String DDT_ACCESS_clean(in table)

Removes access for the given name and frees the internal buffers.

Parameters:

table - (in) the name od the iterator (data table)

DDT_ACCESS_has_more

public String DDT_ACCESS_has_more(in table)

Indicates whether a subsequent call to DDT_ACCESS_get_next() is about to succeed or not.

Parameters:

table - (in) the name od the iterator (data table)

Returns:

TRUE: there are still some tests left to be processed FALSE: all tests processed

DDT_ACCESS_get_next

public String DDT_ACCESS_get_next(in table)

Returns the name of the next test to be processed. More specifically, it returns the next available name from the set of names that were specified by the DDT_ACCES_init() command.

Parameters:

table - (in) the name od the iterator (data table)

Returns:

!"": a test name "": error ocurred

init_count

protected String init_count(in table,
                            in tests)

Analyses the given string tests and builds an array that contains all individual values that were specified.

Parameters:

table - (in) table dimension

tests - (in) test names in format (1,3-9)

Returns:

number of tests to be processed

get_range

protected String get_range(in from,
                           in to,
                           out x,
                           out y,
                           out b)

delete_dimension

protected String delete_dimension(inout[] arr,
                                  in dim)

This function deletes a dimension from a multidimensional array.

WARNING!

It will delete ALL dimensions with the same name. For example assume your three-dimensional array "arr" has the following content:

		arr["x",1,"x"] = "x1x";
		arr["x",1,"y"] = "x1y";
		arr["y",1,"x"] = "y1x";
		arr["y",1,"y"] = "y1Y";

then the following command

		delete_dimension( arr, "x" );

will delete everything BUT

		arr["y",1,"y"] = "y1Y";

Parameters:

arr - (inout) array to be processed

dim - (in) dimension(s) to be removed

col_test_valid

protected String col_test_valid()

Test with valid values

col_test_invalid

protected String col_test_invalid()

Test with invalid values