Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 | Name | a | b | c | d
--- | --- | --- | --- | --- | ---
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

- FRM_UNKNOWN Indicates an unknown value.
- E_FRM_SKIP Indicates an empty table cell.
- FRM_SET_MODE Indicates the SET modus (test data is to be entered).
- FRM_CHK_MODE Indicates the CHECK modus (test data is to be verified).
- FRM_GEN_MODE Indicates the GENERATE modus (test data is to be generated).
- FRM_COL_IDX The default title of the INDEX column.
- FRM_COL_NAME The default title of the NAME column.

Method Summary
`int` | `FRM_close(in tid, in drop)` Closes the given table and frees occupied memory.
`int` | `FRM_close_all(in drop)` Closes all open tables.
`int` | `FRM_close_all_except(inout[] xtabs, in drop)` Closes all open tables except the specified ones.
`int` | `FRM_exec(in tid, in test)` Executes the content of the next cell.
`int` | `FRM_GEN_print(in tid, in gui_obj, in val, in rc)` This function was used for generating test data in GEN mode.
`int` | `FRM_GEN_set(in tid, in test, in gui_obj, in val, in rc)` #???# #???#
`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.
`int` | `FRM_get_block(in tid, in idx, out x, out y, out[] arr)` Returns a two-dimensional block from the table as array.
`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.
`int` | `FRM_get_current_row(in tid, out row)` Retrieves the active row of a data table.
`int` | `FRM_get_mode(in tid)` Returns the active frame mode.
`int` | `FRM_get_name(in tid)` Returns the table name of the corresponding tid or empty string ("") if tid unknown.
`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.
`int` | `FRM_get_parameters(in tid, out params, out count)` Returns a list of all loaded parameters in a FRM data table.
`int` | `FRM_get_row_count(in tid, out count)` Retrieves the number of rows in a data table.
`int` | `FRM_get_tid(in table)` Returns the table ID of the corresponding table or empty string ("") if table unknown.
`int` | `FRM_getvar(in tid, in var, out val)` Retrieves the value of a given FRM variable <var>.
`int` | `FRM_has_next(in tid, in test)` Indicates whether the cell in the next row contains data or not.
`int` | `FRM_idx(in tid, in idx, out row)` Positions the focus to the row specified by its name <idx>.
`int` | `FRM_init_block(in tid, in test, in idx, inout mode)` Performs the initialisation for the given test block.
`int` | `FRM_is_modified(in tid)` Reports whether a given table is modified or not.
`int` | `FRM_is_open(in tid)` Reports whether a given table is open or not.
`int` | `FRM_is_parameter(in tid, in param)` Returns whether a parameter in a data table is valid.
`int` | `FRM_is_row(in tid, in row)` Indicates whether a given <row> exists in the given <tid>.
`int` | `FRM_is_table_open(in table, out tid)` Reports whether a given table is open or not.
`int` | `FRM_load_gui(in tid, in gui)` Loads a GUI map <gui> in scope of the specified <tid>.
`int` | `FRM_load_lib(in tid, in lib, in p1, in p2)` Loads a library <lib> in scope of the specified <tid>.
`int` | `FRM_load_test(in tid, in test)` Loads an individual column (test) into an already opened data table.
`int` | `FRM_next_row(in tid)` Changes the active row in a data table to the next row.
`int` | `FRM_open(in table, in tests, out tid)` Opens a data lt;table> and loads the desired <test>s (columns).
`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.
`int` | `FRM_save(in tid)` Saves the given table.
`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.
`int` | `FRM_set_mode(in tid, in mode)` Sets the active frame mode.
`int` | `FRM_set_row(in tid, in row)` Sets the active row in a data table.
`int` | `FRM_set_val(in tid, in param, in val)` Sets a value in the current row of the data table.
`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.
`int` | `FRM_setvar(in tid, in var, in val)` Allocates a new or overwrites an existing variable <var> with the initial value <val>.
`int` | `FRM_skip(in tid, in rows)` Skips the given number of rows.
`int` | `FRM_val(in tid, in param)` Returns the value of a parameter in the active row in a data table.
`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.

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 | Name | a | b | c | d
  --- | --- | --- | --- | --- | ---
  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

Overview | Package | Class | Use | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD