FRM
Class emos_frm_lib


public class emos_frm_lib

# This library provides the low-level interface to data tables. You can use the function from this library as replacement to standard ddt-functions even if you don't need other nice FRM feaures.

Here we implement our own ddt-interface and add plenty of other functions which make this interface very powerful. This library maintains a set of internal buffers which hold the table data and numerous other information. One of the "side-effects" (but since WR 6.0 one of the most important features) is the ability to use the same table from more than one main test within the same chain.

The most important feature of this interface is that you may also index table rows by some unique name (very much the same as you index columns by defining their names in the first row). For this to work the table MUST contain two columns named "IDX" and "Name". To index a row you need to define some name in the Name-column and place an "x" in the IDX-column.

For example imagine a table "Tab.xls" with the following content:
IDX Nameabcd
x Block1 1 2 3 4
  1 1x1 1x2 1x3 1x4
  2 1x1 2x2 3x3 4x4
x Block2 x y z  
  a ax ay az  
  b bx by bz  
  c cx cy cz  
You could use functions such as

FRM_get_cell( "Tab.xls", "b", "Block1", val );

to retreive "2" in variable val no matter what row used to be active before.

From then on you could use

FRM_get_next( "Tab.xls", "b", val );

to retreive "1x2" in variable val and so on.

PUBLIC VARIABLES


Method Summary
 intFRM_close(in tid, in drop)
          Closes the given table and frees occupied memory.
 intFRM_close_all(in drop)
          Closes all open tables.
 intFRM_close_all_except(inout[] xtabs, in drop)
          Closes all open tables except the specified ones.
 intFRM_exec(in tid, in test)
          Executes the content of the next cell.
 intFRM_GEN_print(in tid, in gui_obj, in val, in rc)
          This function was used for generating test data in GEN mode.
 intFRM_GEN_set(in tid, in test, in gui_obj, in val, in rc)
          #???# #???#
 intFRM_get(in tid, in test, out val, in row)
          Returns the content of the cell specified by the given column name and, optionally, with the row number.
 intFRM_get_block(in tid, in idx, out x, out y, out[] arr)
          Returns a two-dimensional block from the table as array.
 intFRM_get_cell(in tid, in test, in idx, out val)
          Returns the content of the cell specified by the given row (idx) and column (test) names.
 intFRM_get_current_row(in tid, out row)
          Retrieves the active row of a data table.
 intFRM_get_mode(in tid)
          Returns the active frame mode.
 intFRM_get_name(in tid)
          Returns the table name of the corresponding tid or empty string ("") if tid unknown.
 intFRM_get_next(in tid, in test, out val)
          Returns the content of the cell from the given column (test) and the row following the currently active row.
 intFRM_get_parameters(in tid, out params, out count)
          Returns a list of all loaded parameters in a FRM data table.
 intFRM_get_row_count(in tid, out count)
          Retrieves the number of rows in a data table.
 intFRM_get_tid(in table)
          Returns the table ID of the corresponding table or empty string ("") if table unknown.
 intFRM_getvar(in tid, in var, out val)
          Retrieves the value of a given FRM variable <var>.
 intFRM_has_next(in tid, in test)
          Indicates whether the cell in the next row contains data or not.
 intFRM_idx(in tid, in idx, out row)
          Positions the focus to the row specified by its name <idx>.
 intFRM_init_block(in tid, in test, in idx, inout mode)
          Performs the initialisation for the given test block.
 intFRM_is_modified(in tid)
          Reports whether a given table is modified or not.
 intFRM_is_open(in tid)
          Reports whether a given table is open or not.
 intFRM_is_parameter(in tid, in param)
          Returns whether a parameter in a data table is valid.
 intFRM_is_row(in tid, in row)
          Indicates whether a given <row> exists in the given <tid>.
 intFRM_is_table_open(in table, out tid)
          Reports whether a given table is open or not.
 intFRM_load_gui(in tid, in gui)
          Loads a GUI map <gui> in scope of the specified <tid>.
 intFRM_load_lib(in tid, in lib, in p1, in p2)
          Loads a library <lib> in scope of the specified <tid>.
 intFRM_load_test(in tid, in test)
          Loads an individual column (test) into an already opened data table.
 intFRM_next_row(in tid)
          Changes the active row in a data table to the next row.
 intFRM_open(in table, in tests, out tid)
          Opens a data lt;table> and loads the desired <test>s (columns).
 intFRM_rc(in rc, in func, in tid, in test, in val)
          In case of <rc> != E_OK this function formats an tl_step-message from the given parameters.
 intFRM_save(in tid)
          Saves the given table.
 intFRM_set(in tid, in test, in val, in row)
          Saves the given value (val) in the cell specified by the column name (test) and, optinally, the row number.
 intFRM_set_mode(in tid, in mode)
          Sets the active frame mode.
 intFRM_set_row(in tid, in row)
          Sets the active row in a data table.
 intFRM_set_val(in tid, in param, in val)
          Sets a value in the current row of the data table.
 intFRM_set_val_by_row(in tid, in row, in param, in val)
          Sets a value in a specified row of the data table.
 intFRM_setvar(in tid, in var, in val)
          Allocates a new or overwrites an existing variable <var> with the initial value <val>.
 intFRM_skip(in tid, in rows)
          Skips the given number of rows.
 intFRM_val(in tid, in param)
          Returns the value of a parameter in the active row in a data table.
 intFRM_val_by_row(in tid, in row, in param)
          Returns the value of a parameter in the specified row in a data table.

Method Detail

FRM_close

public int FRM_close(in tid, in drop)
Closes the given table and frees occupied memory.

NOTE! If table was modified, it is automatically saved before closing.

Parameters:
tid (in) table - ID
drop (in) (optional) - TRUE: do not save changes (default: FALSE)

FRM_close_all

public int FRM_close_all(in drop)
Closes all open tables. By default it automatically saves the changes. You can override this by setting <drop> to TRUE.
Parameters:
drop (in) (optional) - TRUE: do not save changes (default: FALSE)

FRM_close_all_except

public int FRM_close_all_except(inout[] xtabs, in drop)
Closes all open tables except the specified ones. By default it automatically saves the changes. You can override this by setting <drop> to TRUE.
Parameters:
xtabs[] (inout) array - of table names which are NOT to be closed
drop (in) (optional) - TRUE: do not save changes (default: FALSE)

FRM_exec

public int FRM_exec(in tid, in test)
Executes the content of the next cell.
Parameters:
tid (in) table - ID
rows (in) column - name

FRM_GEN_print

public int FRM_GEN_print(in tid, in gui_obj, in val, in rc)
This function was used for generating test data in GEN mode. It appends the test data into a file named "gen.txt" located in the WR temp directory.

NOTE! Since implementing the save capability for FRM-tables (effectively modifying test date in place) this function is not used any more.

Parameters:
tid (in) table - ID
gui_obj - (in) name of the affected GUI object
value (in) value - contained in that object (test data)
rc (in) return - code received by retreiving the test date (if not E_OK, then a special message is formatted instead of the test data).

FRM_GEN_set

public int FRM_GEN_set(in tid, in test, in gui_obj, in val, in rc)
#???# #???#
Returns: #???#

FRM_get

public int FRM_get(in tid, in test, out val, in row)
Returns the content of the cell specified by the given column name and, optionally, with the row number.

A cell which is supposed to be ignored (an empy cell, a cell that contains no data), is indicated with E_FRM_SKIP. If an empty string ("") needs to be used as test data, then the cell must contain one of the following two strings <<cler>> or <<leer>> (including angle brackets).

NOTE! If row is not defined, the current row is used.

Parameters:
tid (in) table - ID
test (in) test - (column) name
val (out) the - fetched value
row (in) (optional) - row number (default: current row)
Returns: E_OK: operation successful, value returned E_FRM_SKIP: operation successful, no value returned anything else: operation failed

FRM_get_block

public int FRM_get_block(in tid, in idx, out x, out y, out[] arr)
Returns a two-dimensional block from the table as array.

To define a block in the test table you must format it in a special way. An example of one such table follows.
IDX Nameabcd
x Block1 1 2 3 4
  1 1x1 1x2 1x3 1x4
  2 1x1 2x2 3x3 4x4
  <<END>>      
x Block2 x y z  
  a ax ay az  
  b bx by bz  
  c cx cy cz  
  <<END>>        

Parameters:
tid (in) table - ID
idx (in) block - index
x (out) nomber - of columns
y (out) number - of rows
arr[] (out) values
Returns: E_OK: operation succesfull, values returned !E_OK: operation failed

FRM_get_cell

public int FRM_get_cell(in tid, in test, in idx, out val)
Returns the content of the cell specified by the given row (idx) and column (test) names.

A cell which is supposed to be ignored (an empy cell, a cell that contains no data), is indicated with E_FRM_SKIP. If an empty string ("") needs to be used as test data, then the cell must contain one of the following two strings <<cler>> or <<leer>> (including angle brackets).

NOTE! For this to work the <idx> must be the content of some row in FRM_COL_NAME marked with "x" in FRM_COL_IDX.

Parameters:
tid (in) table - ID
test (in) test - (column) name
idx (in) row - name (index)
val (out) the - fetched value
Returns: E_OK: operation successful, value returned E_FRM_SKIP: operation successful, no value returned anything else: operation failed

FRM_get_current_row

public int FRM_get_current_row(in tid, out row)
Retrieves the active row of a data table.
Parameters:
tid (in) table - ID
row - (out) number of the active row (starting with 1)
Returns: E_OK: success; active row returned !E_OK: failure; active row not returned

FRM_get_mode

public int FRM_get_mode(in tid)
Returns the active frame mode.
Parameters:
tid (in) table - ID
Returns: currently active mode (FRM_SET_MODE/FRM_CHK_MODE/FRM_GEN_MODE) or E_FILE_NOT_OPEN: table not open

FRM_get_name

public int FRM_get_name(in tid)
Returns the table name of the corresponding tid or empty string ("") if tid unknown.
Parameters:
tid (in) table - ID
Returns: table name orempty string

FRM_get_next

public int FRM_get_next(in tid, in test, out val)
Returns the content of the cell from the given column (test) and the row following the currently active row.

A cell which is supposed to be ignored (an empy cell, a cell that contains no data), is indicated with E_FRM_SKIP. If an empty string ("") needs to be used as test data, then the cell must contain one of the following two strings <<cler>> or <<leer>> (including angle brackets).

NOTE! This routine modifies the currently active row. It does this before fetching the value. If an attemp is made to fatch the value beyond the last row, E_OUT_OF_RANGE is returned.

Parameters:
tid (in) table - ID
test (in) test - (column) name
val (out) the - fetched value
Returns: E_OK: operation successful, value returned E_FRM_SKIP: operation successful, no value returned anything else: operation failed

FRM_get_parameters

public int FRM_get_parameters(in tid, out params, out count)
Returns a list of all loaded parameters in a FRM data table.

NOTE!

Does NOT return columns IDX and name because they are always there. For this reason the number returned is the number of all (loaded) parameters minus 2.

Parameters:
tid (in) table - ID
params - (out) column titles (tab-separated)
count - (out) nomber of loaded columns (excluding IDX and Name)
Returns: E_OK: success; params and count provided !E_OK: faliure; params and count not provided

FRM_get_row_count

public int FRM_get_row_count(in tid, out count)
Retrieves the number of rows in a data table.
Parameters:
tid (in) table - ID
count - (out) number of rows in the data table
Returns: E_OK: success; <count> returned !E_OK: failure; <count> not returned

FRM_get_tid

public int FRM_get_tid(in table)
Returns the table ID of the corresponding table or empty string ("") if table unknown.
Parameters:
table (in) table - name
Returns: table ID orempty string

FRM_getvar

public int FRM_getvar(in tid, in var, out val)
Retrieves the value of a given FRM variable <var>. A scope of the variable depends on the given <tid> name.

NOTE! If it equals to "" the scope of the variable is is Frame-global. Otherwise the variable has table-scope. If table is closed, all variables in its scope are automatically unloaded. Global varables are unloaded only with FRM_close_all().

Parameters:
tid (in) table - ID (scope) or "" for global variables
var (in) variable - name
val (out) value - retrieved
Returns: E_OK: success !E_OK: failure

FRM_has_next

public int FRM_has_next(in tid, in test)
Indicates whether the cell in the next row contains data or not.
Parameters:
tid (in) table - ID
test (in) test - (column) name
Returns: TRUE: next row contains data FALSE: next row contains no data

FRM_idx

public int FRM_idx(in tid, in idx, out row)
Positions the focus to the row specified by its name <idx>. If successful, the <row> number is returned.

NOTE! The row must be indexed.

Parameters:
tid (in) table - ID
idx (in) row - name/index
row (out) row - number
Returns: E_OK: success !E_OK: failure

FRM_init_block

public int FRM_init_block(in tid, in test, in idx, inout mode)
Performs the initialisation for the given test block.
Parameters:
tid (in) table - ID
test (in) column - name
idx (in) block - name (row index)
mode (in) (optional) - frame mode (default: FRM_SET_MODE)
Returns: E_OK: success E_FRM_SKIP: block schould be ignored (valid only for FRM_GEN_MODE) E_FRM_INIT_BLOCK: failure

FRM_is_modified

public int FRM_is_modified(in tid)
Reports whether a given table is modified or not.
Parameters:
tid (in) table - ID
Returns: TRUE: table is modified FALSE: table is not modified

FRM_is_open

public int FRM_is_open(in tid)
Reports whether a given table is open or not.
Parameters:
tid (in) table - ID
Returns: TRUE: table is open FALSE: table is not open

FRM_is_parameter

public int FRM_is_parameter(in tid, in param)
Returns whether a parameter in a data table is valid.
Parameters:
tid (in) table - ID
param - (in) The parameter name to check in the data table.
Returns: E_OK: parameter is valid E_NOT_PARAMETER: parameter is invalid else: other error

FRM_is_row

public int FRM_is_row(in tid, in row)
Indicates whether a given <row> exists in the given <tid>.
Parameters:
tid (in) table - ID
row - (in) row number to be evaluated
Returns: E_OK: row number is valid E_OUT_OF_RANGE: row number is invalid else: other error

FRM_is_table_open

public int FRM_is_table_open(in table, out tid)
Reports whether a given table is open or not.
Parameters:
table (in) table - name
Returns: TRUE: table is open FALSE: table is not open

FRM_load_gui

public int FRM_load_gui(in tid, in gui)
Loads a GUI map <gui> in scope of the specified <tid>.

NOTE! If table is closed, all GUI maps in its scope are automatically unloaded.

Parameters:
tid (in) table - ID
gui (in) GUI - map name (full path)
Returns: E_OK: success !E_OK: failure

FRM_load_lib

public int FRM_load_lib(in tid, in lib, in p1, in p2)
Loads a library <lib> in scope of the specified <tid>.

NOTE! If table is closed, all libraries in its scope are automatically unloaded.

Parameters:
tid (in) table - ID
lib (in) library - name (full path)
p1 (in) (optional) - first parameter to underlying reload statement
p2 (in) (optional) - second parameter to underlying reload statement
Returns: E_OK: success !E_OK: failure

FRM_load_test

public int FRM_load_test(in tid, in test)
Loads an individual column (test) into an already opened data table.
Parameters:
tid (in) table - ID
test (in) column - name to be loaded
Returns: E_OK: success !E_OK: failure

FRM_next_row

public int FRM_next_row(in tid)
Changes the active row in a data table to the next row.
Parameters:
tid (in) table - ID
Returns: E_OK: success; active row changed !E_OK: failure; active row not changed

FRM_open

public int FRM_open(in table, in tests, out tid)
Opens a data lt;table> and loads the desired <test>s (columns).

NOTE

This routine returns the tid (table ID). Unlike the ddt_ you have to use this id when calling other FRM functions.

Parameters:
table (in) name - of the data table
tests (in) list - of columns (comma-separated)
tid (out) table - ID
Returns: E_OK: success !E_OK: failure

FRM_rc

public int FRM_rc(in rc, in func, in tid, in test, in val)
In case of <rc> != E_OK this function formats an tl_step-message from the given parameters. It automatically determines the current row number in the data table.
Parameters:
rc (in) return - code to be evaluated
func (in) name - of the affected function
tid (in) tid - of the affected data table
test (in) name - of the test case from <tid>
val (in) content - of the affected cell from <tid>
Returns: E_OK: success !E_OK: failure

FRM_save

public int FRM_save(in tid)
Saves the given table.

NOTE! This funtion only works with WR 6.0 or higher.

Parameters:
tid (in) table - ID
Returns: E_OK: success !E_OK: failure

FRM_set

public int FRM_set(in tid, in test, in val, in row)
Saves the given value (val) in the cell specified by the column name (test) and, optinally, the row number.

NOTE! The change is not made permanent yet. You must call FRM_save() in order to transfer your changes back to the Excel table.

Parameters:
tid (in) table - ID
test (in) test - name (column)
val (in) value - to be saved
row (in) (optional) - row number (default: current row)
Returns: E_OK: operation successful !E_OK: operation failed

FRM_set_mode

public int FRM_set_mode(in tid, in mode)
Sets the active frame mode.
Parameters:
tid (in) table - ID
mode (in) either - FRM_SET_MODE, FRM_CHK_MODE or FRM_GEN_MODE
Returns: E_OK: mode successfully set E_FILE_NOT_OPEN: table not open E_ILLEGAL_PARAMETER: invalid mode (mode unchanged)

FRM_set_row

public int FRM_set_row(in tid, in row)
Sets the active row in a data table.
Parameters:
tid (in) table - ID
row - (in) row to be set
Returns: E_OK: success; <row> set !E_OK: failure; <row> not set

FRM_set_val

public int FRM_set_val(in tid, in param, in val)
Sets a value in the current row of the data table.
Parameters:
tid (in) table - ID
val (in) value - to be set
param (in) column - name
Returns: E_OK: success; val set E_NOT_PARAMETER: failure; invalid parameter (column) name else: other error

FRM_set_val_by_row

public int FRM_set_val_by_row(in tid, in row, in param, in val)
Sets a value in a specified row of the data table.
Parameters:
tid (in) table - ID
row (in) row - number
param (in) column - name
val (in) the - value to be set
Returns: E_OK: success; val set E_NOT_PARAMETER: failure; invalid parameter (column) name else: other error

FRM_setvar

public int FRM_setvar(in tid, in var, in val)
Allocates a new or overwrites an existing variable <var> with the initial value <val>. A scope of the variable depends on the given <tid> name.

NOTE! If it equals to "" the scope of the variable is is Frame-global. Otherwise the variable has table-scope. If table is closed, all variables in its scope are automatically unloaded. Global varables are unloaded only with FRM_close_all().

Parameters:
tid (in) table - ID (scope) or "" for global variables
var (in) variable - name
val (in) value - to be saved
Returns: E_OK: success !E_OK: failure

FRM_skip

public int FRM_skip(in tid, in rows)
Skips the given number of rows.

NOTE! If rows is not given, one row is skipped. Therefore FRM_skip( tab ); is equivalent to FRM_skip( tab, 1 );. FRM_skip( tab, 0 ); also skips to next row because 0 is taken as the equivalent for "not given".

If rows is negative, the function skips backwards. Therefore FRM_skip( tab, -3 ); jumps for example from row 15 to row 12.

Parameters:
tid (in) table - ID
rows (in) (optional) - number of rows to skip, negative skips backwards
Returns: E_OK: success E_OUT_OF_RANGE: skip beyond table bounaries attempted !anything else: other failure

FRM_val

public int FRM_val(in tid, in param)
Returns the value of a parameter in the active row in a data table.
Parameters:
tid (in) table - ID
param (in) column - name
Returns: E_NOT_PARAMETER: failure; invalid parameter (column) name else: value of the given cell

FRM_val_by_row

public int FRM_val_by_row(in tid, in row, in param)
Returns the value of a parameter in the specified row in a data table.
Parameters:
tid (in) table - ID
row (in) row - number
param (in) column - name
Returns: E_NOT_PARAMETER: failure; invalid parameter (column) name else: value of the given cell