DTSheet Object

Description

A sheet in the run-time data table. This object is not a built-in utility object, but can be accessed using one of the following methods or properties:

Note: All methods performed on this object apply to the run-time DataTable object only. Changes to the run-time DataTable object are reflected in the run results, but the design time data table is not affected.

When working with scripted components, the name of the (single) Data Sheet is identical to the name of scripted component. If you save the scripted component with a new name, the name of the data sheet changes accordingly.

Methods and Properties

Method AddParameterAdds the specified parameter (column) to the sheet in the run-time data table, sets the value of the first row to the specified value, and returns the parameter so that you can directly set or retrieve properties of the new parameter in the same statement.
Method DeleteParameterDeletes the specified parameter from the sheet in the run-time data table.
GetCurrentRowReturns the row number of the current (active) row in the run-time Data pane sheet.
GetParameterRetrieves the specified parameter from the run-time Data pane sheet.
GetRowCountReturns the total number of rows in the longest column in the run-time Data pane sheet.
NameReturns the name of the run-time data sheet.
SetCurrentRowSets the specified row as the current (active) row in the run-time data table.
SetNextRowSets the row after the current (active) row as the new current row in the run-time Data pane sheet.
SetPrevRowSets the row above the current (active) row as the new current (active) row in the run-time Data pane sheet.

Back to top

AddParameter Method

Description

Adds the specified parameter (column) to the sheet in the run-time data table, sets the value of the first row to the specified value, and returns the parameter so that you can directly set or retrieve properties of the new parameter in the same statement.

Syntax

DTSheet.AddParameter(ParameterName, Value)

Argument

Type

Description

ParamterName

String

Assigns a name to the new parameter. If another parameter in the sheet has the same name, a number (i.e. '1') will be appended to the assigned ParameterName. If the ParameterName contains illegal characters, the illegal characters will be replaced with '_' characters.

Value

String

Assigns a value to the first row of the parameter.

Return Value

DTParameter Object

The following example uses the AddParameter method to create the new Parameter, "Arrival" within the new sheet, MySheet of the run-time data table, and sets the first cell in the column as "New York". Because the method also returns the newly created parameter, it is possible to use methods or check properties of the new sheet within the same statement.

ParamName=DataTable.AddSheet("MySheet").AddParameter("Arrival", "New York").Name

Note that if a parameter with the name "Arrival" already exists in the sheet, the example above will return "Arrival1" as the actual name assigned to the new parameter.

The example below performs the equivalent of renaming a column (parameter) in the DataTable by copying the data from one column to a new column with a new name, and then deleting the old column.

'add a new column

DataTable.GetSheet("Global").AddParameter "NewColumn","Row1Value"



'copy the cells from the old column into the new column

cnt=DataTable.GetRowCount

For i=1 to cnt

    DataTable.SetCurrentRow(i)

    OldVal=DataTable.Value("OldColumn","Global")

    DataTable.Value("NewColumn","Global")=OldVal

Next 



'delete the old column

DataTable.GetSheet("Global").DeleteParameter("OldColumn")

Back to top

DeleteParameter Method

Description

Deletes the specified parameter from the sheet in the run-time data table.

Syntax

DTSheet.DeleteParameter(ParameterID)

Argument

Type

Description

ParameterID

Variant

Identifies the parameter (column) to be deleted by name or index.

(Index values begin with 1.)

The following example uses the DeleteParameter method to delete the parameter, "Arrival" from the "MySheet" sheet of the run-time data table.

DataTable.GetSheet("MySheet").DeleteParameter("Arrival")

Note that deleting a parameter from the sheet will cause the run to fail if a corresponding parameter exists in a step.

The example below performs the equivalent of renaming a column (parameter) in the DataTable by copying the data from one column to a new column with a new name, and then deleting the old column.

'add a new column

DataTable.GetSheet("Global").AddParameter "NewColumn","Row1Value"



'copy the cells from the old column into the new column

cnt=DataTable.GetRowCount

For i=1 to cnt

    DataTable.SetCurrentRow(i)

    OldVal=DataTable.Value("OldColumn","Global")

    DataTable.Value("NewColumn","Global")=OldVal

Next 



'delete the old column

DataTable.GetSheet("Global").DeleteParameter("OldColumn")

Back to top

GetCurrentRow Method

Description

Returns the row number of the current (active) row in the run-time Data pane sheet.

Syntax

DTSheet.GetCurrentRow

Return Value

Number

The following example uses the GetCurrentRow method to retrieve the row currently being used by the run-time data table and writes it to the report.

row = DataTable.GetSheet("MySheet").GetCurrentRow
Reporter.ReportEvent 1, "Row Number", row

Back to top

GetParameter Method

Description

Retrieves the specified parameter from the run-time Data pane sheet.

Syntax

DTSheet.GetParameter(ParameterID)

Argument

Type

Description

ParameterID

String/Index

Identifies the parameter (column) to be returned by name or index.

(Index values begin with 1.)

Return Value

DTParameter Object.

The following example uses the GetParameter method to return the "Destination" parameter from the run-time Data pane sheet: MySheet.

DataTable.GetSheet("MySheet").GetParameter("Destination")

Back to top

GetParameterCount Method

Description

Returns the total number of parameters (columns) in the run-time Data pane sheet.

Syntax

DTSheet.GetParameterCount

Return Value

Number

The following example uses the GetParameterCount method to find the total number of parameters (columns) in the run-time Data pane sheet (MySheet) and writes it to the report.

paramcount = DataTable.GetSheet("MySheet").GetParameterCount
Reporter.ReportEvent 2, "There are " &paramcount, "columns in the data sheet."

Back to top

GetRowCount Method

Description

Returns the total number of rows in the longest column in the run-time Data pane sheet.

Syntax

DTSheet.GetRowCount

Return Value

Number

The following example uses the GetRowCount method to find the total number of rows in the first column of the run-time Data pane sheet (MySheet) and writes it to the report.

rowcount = DataTable.GetSheet("MySheet").GetRowCount
Reporter.ReportEvent 2, "There are " &rowcount, "rows in the data sheet."

Back to top

Name Property

Description

Returns the name of the run-time data sheet.

Syntax

DTSheet.Name

The following example uses the Name method to return the name of the active run-time data sheet and writes it in the report.

Sheetname = DataTable.LocalSheet.Name
Reporter.ReportEvent 1, "The Active Sheet is", Sheetname

Back to top

SetCurrentRow Method

Description

Sets the specified row as the current (active) row in the run-time data table.

Syntax

DTSheet.SetCurrentRow(RowNumber)

Argument

Type

Description

RowNumber

Number

Indicates the number of the row to set as the active row.

The following example uses the SetCurrentRow method to change the active row to the second row in the MySheet run-time data sheet.

DataTable.GetSheet("MySheet").SetCurrentRow(2)

Back to top

SetNextRow Method

Description

Sets the row after the current (active) row as the new current row in the run-time Data pane sheet.

Note: You can only set a row that contains at least one value. If the current row is the last row in the data table, applying this method sets the first row in the data table as the new current row.

Syntax

DTSheet.SetNextRow

The following example uses the SetNextRow method to change the active row to the next row in the run-time data table.

DataTable.GetSheet("MySheet").SetNextRow

Back to top

SetPrevRow Method

Description

Sets the row above the current (active) row as the new current (active) row in the run-time Data pane sheet.

Syntax

DTSheet.SetPrevRow

The following example uses the SetPrevRow method to change the active row to the previous row in the run-time data sheet.

DataTable.GetSheet("MySheet").SetPrevRow

Back to top

See also: