Returns the number of columns of the TabularData Object.
Parameters
[out] pVal: Address of the long integer used to return the number of columns.
Remarks
This number does not include the RECORD_ID column. If a table TABLE1 is defined by FIELD1, FIELD2, and FIELD3, get_ColumnCount returns 3, even though there are 4 columns : RECORD_ID, FIELD1, FIELD2, and FIELD3.
6.3 get_RowCount
Returns the number of rows of the TabularData Object
Parameters
[out] pVal: Address of the long integer used to return the number of rows.
Remarks
The first row is row number 0 and it contains the TabularData Object field names. If a table TABLE1 has no record, 0 is returned. The actual contents of the table starts at row number 1. GetValue(0, 1) returns FIELD1, which is the name of the column number 1 (read in row number 0). GetValue(0, 0) returns RECORD_ID, which is the name of the column number 0 (read in row number 0). GetValue(1, 1) returns the value for column FIELD1 (number 1) in row number 1.
6.4 Edit
Puts a row into edition mode.
Parameters
[in] iRow: The long integer used to specify the row number to put into edition mode.
Remarks
Once a row is put into edition mode, it is possible to change the row contents by using SetValue. Update is used to commit the row changes.
radius = records.GetValue(i, 11)
HRESULT get_ColumnCount(long *pVal);
HRESULT get_RowCount(long *pVal);
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
6.5 AddNew
Adds a new empty row to the TabularData Object. The row added is put into edition mode.
6.6 Update
Commits a row changes and puts the row from edition mode to normal mode.
Parameters
[out] piRow: The long integer pointer used to return the number of the row that was in edition mode. If the method Edit started the editing, the same iRow as in Edit is returned. If it was AddNew method, the number is the row number where the new record has been added.
Remarks
At one point in time, only one record can be put into edition mode. This method must be called once after each Edit and
AddNew. Editing another record without updating the previous one will throw an error. Edit/Update cannot be mixed up for
different records, neither can be AddNew/Update.
6.7 Delete
Deletes a record.
Parameters
[in] iRow: The long integer used to specify the row number of the record to delete.
Remarks
A valid iRow number is any integer, such that 0 < iRow <= RowCount. Deletion can fail if the record to delete is related to another one. For instance an antenna from the table "ANTENNAS" cannot be deleted if it is being used by a transmitter from the table "TRANSMITTERS".
Even if the record deletion doesn’t break integrity relations between tables, deleting a record may involve updating other tables or records.
For instance, be careful when using this method with the "TRANSMITTERS" table and the "TRXs" table. If you delete one TRX, you want to edit the "TRANSMITTERS" table in order to update the field "NUM_TRX".
6.8 GetValue
Returns a value of a column for a given row.
Don’t forget to call this method before a call to SetValue and to call Update to commit the changes in the row.
HRESULT AddNew();
Don’t forget to call this method before a call to SetValue and to call Update to actually add the new row.
HRESULT Update(long *piRow);
Parameters
[in] iRow: The long integer used to specify the row number.
[in] iCol: The VARIANT used to specify a column. When iCol is of type VT_I4, iCol is interpreted as a column number. When iCol is of type VT_BSTR, iCol is interpreted as a column name.
[out] pVal: Address of the VARIANT used to return the column value.
Remarks
A valid iRow number is any integer, such that 0< iRow<= RowCount. A valid iCol is either an integer such that 0< iCol <= Colum-
nCount or a string containing the name of an existing column.
The column names are not case sensitive.
You should never assume that the type of the returned VARIANT is the one you expect. For instance, a VARIANT of type VT_NULL may be returned when the value of the column is the "Null" value. You should explicitly convert the returned VARI- ANT to the type you expect and handle conversion errors.
When using a TabularData Object to access database tables, please refer to the Atoll Administrator Manual for the available column names, types, units, and to check if the column specification allows for "Null" values. For site coordinates values, please refer to the Atoll Technical Reference Guide for coordinate systems and units. Site coordinates are expressed in the internal coordinate system of the Atoll document.
Example
6.9 SetValue
Sets the value of a column for the row being edited or added.
Parameters
[in] iCol: The VARIANT used to specify a column.
[in] newVal: The VARIANT used to specify the column value.
Remarks
A valid iCol is either an integer such that 0 < iCol <= ColumnCount or a string containing the name of an existing column. The column names are not case sensitive.
You must have previously called Edit or AddNew to specify the row to edit before writing the column value.If this method is used for a large number of records, it is recommended to get the column numbers beforehand and then to use the SetValue method with this number and not with a VARIANT of type VT_BSTR. This will run faster. To get the column number, you can search the row number 0 for the field name you want to use.
Example
This example increments all the TXLOSSES of all the transmitters in the active document by 1 dB. HRESULT GetValue(long iRow, const VARIANT iCol, VARIANT *pVal);
Set sites = app.ActiveDocument.GetRecords(“Sites”) For i = 1 To sites.ColumnCount
colName = sites.GetValue(0, i) Next
HRESULT SetValue(const VARIANT iCol, const VARIANT newVal);
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
Instead, we could have used:
Updating the main contour of the focus zone: Dim i
Dim txLosses
Set doc = app.ActiveDocument
Set transmitters = doc.GetRecords(“Transmitters”) For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, “LOSSES”) transmitters.Edit(i) transmitters.SetValue(“LOSSES”, txLosses + 1) transmitters.Update Next For i = 1 To transmitters.RowCount txLosses = transmitters.GetValue(i, 12) transmitters.Edit(i) transmitters.SetValue(12, txLosses + 1) transmitters.Update Next
Public Sub WriteZone() Set doc = ActiveDocument
Set zones = doc.GetRecords("Zones", true) row = zones.Find(0, "NAME", atoEQ, "FocusZone") Dim pts(3,1) pts(0,0) = 555000 pts(0,1) = 2188000 pts(1,0) = 600000 pts(1,1) = 2188000 pts(2,0) = 600000 pts(2,1) = 2140000 pts(3,0) = 555000 pts(3,1) = 2140000
6.10 GetPrimaryKey
Returns the value of the primary key for a given row number.
Parameters
[in] iRow: The row number.
[out] pVal: Address of the VARIANT used to return the primary key.
Remarks
A valid iRow number is an integer whose value is greater than zero or equal to zero and lower than or equal to the row count of the TabularData object. Most of TabularData objects have a primary key. If no primary key is defined, the value of the column RECORD_ID for the row iRow is returned. When the TabularData object primary key is made of several columns, the type of the variant returned is a one dimension VARIANT array, of type VT_ARRAY|VT_VARIANT, and VARIANT array values are the values of the columns defining the primary key. Otherwise, the VARIANT returned is the value of the column used to define the primary key.
When 0 is used for the iRow parameter, the names of the columns defining the primary key are returned. The variant returned is of type VT_BSTR or VT_ARRAY|VT_VARIANT with variants of type VT_BSTR, whether the primary key is made of one or several columns, respectively.
6.11 FindPrimaryKey
Searches the row whose primary key equals the input value and returns the row number of the row found. If no row is found, returns –1.
Parameters
[in] val: The VARIANT used to specify the key value to search for.
[out] iRow: Address of the long integer used to return the number of the row whose primary key equals val. If no row is found, -1 is returned.
Remarks
When the primary key is made of several columns, the input variant must be of type VT_ARRAY|VT_VARIANT.
6.12 Find
Searches a column for a value. zones.Edit row
zones.SetValue "POINTS", pts zones.Update
End Sub
HRESULT GetPrimaryKey(long iRow, VARIANT* pVal);
HRESULT FindPrimaryKey(VARIANT val, long* iRow);
HRESULT Find( long iRowStart, const VARIANT iCol,
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] iRowStart: The long integer used to specify the row number from which the value will be searched for. [in] iCol: The VARIANT used to specify the column number or the column name that will be searched.
[in] op: The atoCompareOp enumeration value used to specify the search criteria (greater than, less than, equal to, etc). [in] value: The VARIANT used to specify the value to search.
[out] piRow: The long integer pointer used to return the row number of the first row matching the search criteria. –1 is returned if no row is found.
Remarks
Patch iRowStart inside a loop in order to scan several rows matching the search criteria.
This method should be used only for a few searches, because on the Atoll side, this method scans the rows one after the other and can be very time consuming.
If the column is the primary key of the TabularData Object, use FindPrimaryKey instead. For repetitive search operations, use a collection (map) of all the rows and write your own filter.
Example
In this example, we search for all transmitters whose LOSSES are equal to 2, and replace them with 3.
6.13 GetFormattedValue
Returns a column value formatted as a string. enum AtoCompareOp op, const VARIANT value, long* piRow
);
Dim transmitters Dim iRow
Const atoEQ = 0
Set transmitters = ActiveDocument.GetRecords(“Transmitters”, False) iRow = 0
While iRow <> -1
iRow = transmitters.Find(iRow + 1, "LOSSES", atoEQ, 2) If iRow <> -1 Then transmitters.Edit(iRow) transmitters.SetValue("LOSSES", 3) transmitters.Update End If Wend
Parameters
[in] Row: The row number.
• A valid iRow number is an integer whose value is greater than zero or equal to zero, and lower than or equal to the row count of the TabularData object.
[in] iCol: The VARIANT used to define the column.
• When iCol variant type if VT_I4, iCol is interpreted as a column number. A valid column number is an integer whose value is greater than zero or equal to zero, and lower than or equal to the column count of the TabularData object. • When iCol variant type if VT_BSTR, iCol is interpreted as a column name. Column names are not case sensitive. [out] pVal: Address of a BSTR string used to return the formatted value.
Remarks
When 0 is used for the iRow parameter, the title of the column specified by iCol is returned. The title of a column is localized and may be shown to a user, as opposed to the column name.
6.14 CancelUpdate
Cancels a pending update. This method may be called after Edit or AddNew to cancel the operation.
6.15 get_ColumnNumber
Returns a column number.
Parameters
[in] vColName: The VARIANT used to specify the name of the column. [ou] pCol: Address of the long integer used to return column number.
Remarks
It is faster to read data from tables using the column number instead of the column name. It also works for linked fields. For instance you can write:
6.16 get_CanEdit
Checks if rows can be modified.
HRESULT GetFormattedValue(long iRow, const VARIANT iCol, BSTR *pVal);
HRESULT CancelUpdate();
HRESULT get_ColumnNumber(const VARIANT vColName, long *pCol);
Set sites = doc.GetRecords("SITES", False) colLatitude = sites.ColumnNumber("LATITUDE") For i = 1 To sites.RowCount
latitude = sites.GetValue i, colLatitude Next
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be modified or not.
Remarks
If VARIANT_FALSE is returned, then the Edit operation on this table is undefined.
6.17 get_CanAddNew
Checks if rows can be added.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be added or not.
Remarks
If VARIANT_FALSE is returned, then the AddNew operation on this table is undefined.
6.18 get_CanFilterSort
Checks if rows can be filtered or sorted.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be filtered or sorted.
Remarks
If VARIANT_FALSE is returned, then the Filter and Sort operations on this table are undefined.
6.19 get_Filter
Returns the filter currently set on the table.
Parameters
[out] : pvCriteria: Address of the VARIANT used to return the filter previously set on the table.
Remarks
Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted rows.
6.20 put_Filter
Filters the table data according to a filter criteria.
HRESULT get_CanAddNew(VARIANT_BOOL *pVal);
HRESULT get_CanFilterSort(VARIANT_BOOL *pVal);
HRESULT get_Filter(VARIANT *pvCriteria);
Parameters
[in] vCriteria: The VARIANT used to specify the filter criteria. When vCriteria is of type VT_I4, it is interpreted as an AtoRow-
Filter enumeration value. When vCriteria is of type VT_BSTR, it is interpreted as a filter string. Filter strings are what can be
seen in the Atoll "Table" tab properties for record folders, when using advanced filtering. Please refer to the Atoll User Manual for more information about advanced filtering on data.
Remarks
Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted rows.
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the filter interactively in an Atoll session.
To remove any previous filter, call this method either with atoRowFilterNone value or with an empty string.
When the Atoll document is not connected to a database, atoRowFilterModifiedOrNew and atoRowFilterDeleted are not available.
6.21 get_Sort
Returns the sort order currently set on the table.
Parameters
[in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is "Descending".
Remarks
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort order interactively in an Atoll session.
To remove any previous sort order, call this method with an empty string.
Example
HRESULT get_Sort(VARIANT *pvCriteria);
Private Sub PrintTransmittersTable(transmRec, infoMsg) For nRow = 1 To transmRec.RowCount
LogMessage infoMsg & ": " & transmRec.GetValue(nRow, "TX_ID") Next
End Sub Sub Main
Set t = ActiveDocument.GetRecords("transmitters", False) ‘ Sort ascending according to the "SITE_NAME" database field t.Sort = "SITE_NAME"
PrintTransmitterTables t, "Sort = SITE_NAME"
‘ Sort descending according to the "SITE_NAME" database field t.Sort = "SITE_NAME DESC"
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
6.22 put_Sort
Sorts the table data.
Parameters
[in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is "Descending".
Remarks
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort order interactively in an Atoll session.
To remove any previous sort order, call this method with an empty string.
Example
See "get_Sort" on page 91.
6.23 GetOriginalValue
Returns an original field value.
Parameters
[in] iRow: The long integer used to specify a row number.
[in] iCol: The VARIANT used to specify a column name or a column number. [out] pVal: Address of VARIANT used to return the original column value.
Remarks
The original value, as opposed to the current value return by GetValue, is the value retrieved from the database when the
Atoll document has been refreshed for the last time.
If the row is unmodified, the original value is the same as the current value.
If the row is deleted the current value is the null value and the original value is the value just before the row was deleted.
6.24 get_RowStatus
Returns a row status.
Parameters
[in] iRow: The long integer used to specify a row number.
[out] pVal: Address of the AtoRowStatus enumeration value used to return the row status. End Sub
HRESULT put_Sort(const VARIANT vCriteria);
HRESULT GetOriginalValue(long iRow, const VARIANT iCol, VARIANT *pVal);
Remarks
When an Atoll document is open from a database, row statuses are set to atoRowStatusUnmodified and original values are set for all row columns.
When the document is archived or refreshed from the database, row statuses are set to atoRowStatusUnmodified and all columns original values are set for rows that have been archived or refreshed.
When a new row is created, the row status is set to atoRowStatusNew and the original value for all columns are set to the null value.
When a row is modified, the row status is set to atoRowStatusModified. If you revert the row changes, the row status is set to atoRowStatusUnmodified.
When a row is deleted, the row status is set to atoRowStatusDeleted, the row column values are set to the null value, and the original column values are the column values just before the row was deleted.
6.25 get_Columns
Returns table columns definition.
Parameters
[out] ppVal:
Address of the ITabularData interface pointer used to return a tabular data object holding the table columns definition:
6.26 GetValues
Returns a sub-table of the Tabular Data Object.
HRESULT get_Columns(ITabularData** ppVal);
Column Name Type Description
LEGEND String The display name of the column
NAME String The database name of the column
TYPE Integer
The data type of the column. Valid values are: 0=Text 1=Short integer 2=Long integer 3=Single 4=Double 5=True/False 6=Date/Time 7=Currency;
SIZE Integer The size, in bytes, for a column of TYPE 0 (Text).
DEFAULT Variant
The default value of the column. The type of the variant depends on the type of the column, as indicated by TYPE.
May be Null.
FORMATTED_DEFAULT String The default value of the column, formatted as a string.
GROUP String The name of the database field group the column belongs to.
ISCUSTOMFIELD Boolean Whether the column is a user column (True), or not (False).
CHOICELIST_TYPE Integer Whether a column of TYPE 0(Text) content values are restricted to the values specified in CHOICELIST_VALUES.
Atoll 3.3.2 Task Automation Guide
Chapter 6: TabularData Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] rows: A reference to a VARIANT used to specify the rows to retrieve.
The type of the rows input VARIANT may be:
VT_EMPTY:
An empty VARIANT is used to specify that all the table rows must be returned.
VT_ARRAY | VT_VARIANT:
1-dimension array of VARIANTs, with VARIANTs of type VT_I4 is used to specify one or several rows. A valid row number is any integer, such that 1 <= row number <= RowCount.
[in] columns: A reference to a VARIANT used to specify the columns to retrieve.
The type of the columns input VARIANT may be:
VT_EMPTY:
An empty VARIANT is used to specify that all the table columns must be returned.
VT_ARRAY | VT_VARIANT:
1-dimension array of VARIANTs, with VARIANTs of type VT_I4 or VT_BSTR, is used to specify one or several columns either by