If an assembly includes a structure collection or an ArrayList of structures created as a DataTable, in addition to the structure class, it will have a class named with the structure name plus “DT”. For example, if the structure is named Struct1, the assembly will have a structure class named Struct1 and a DataTable class named Struct1DT. The TableName property of the DataTable class (DataTable.TableName) uses the structure name.
The generated Synergy DataTable extends the .NET Framework class System.Data.DataTable; consequently, you can use the methods available in that class to retrieve and manipulate data in the table. You can also use the utility methods we supply to manipulate the rows within the DataTable as structure classes. (See DataTable methods and DataTable examples.)
When a DataTable is associated with a structure collection, it must be an “out” parameter, passing data from Synergy to the client. A DataTable associated with an ArrayList parameter can be an “in” parameter or an “out” parameter, but not an “in/out” parameter.
|
We do not recommend using DataTables for extremely complex structures because of the overhead required to flatten out the structure, send it across the wire, and rebuild it on the other end. An example of an extremely complex structure would be a large structure that contains multiple groups, which in turn contain multiple groups, some of which contain arrayed fields. A large number of duplicate names also contributes to a structure’s complexity. |
Rows and columns
Each row in the DataTable consists of a structure class. Each column in the table is a field in that structure, and is named with the repository field name or the alternate field name if “use alternate field names” was selected. (This is the DataColumn.ColumnName property; you should not change this property.)
Characteristics of the structure fields, such as non-nullable and read-only, are carried over to the DataTable. For example, for a non-nullable field, the data column’s AllowDBNull property is set to false, and for a read-only field, the IsReadOnly property is set to true. The default value for a DataTable column is set to the default value for the data type of the column. The default applies when no data is present, such as when a new row is created.
If the repository structure contains a field that is a group or struct data type, it will be included in the same table as its parent structure. The group name and the field name (or alternate field name) are combined to make the column name. For example, if the group field is called Activatedate and has three fields named Month, Day, and Year, the columns would be named thus:
Activatedatemonth Activatedateday Activatedateyear
If a group or struct field contains a subgroup, both the group name and the subgroup name, along with the field name, are concatenated to form the column name. For example, if the above Activatedate group were a subgroup of the Account group, the columns would be named thus:
Accountactivatedatemonth Accountactivatedateday Accountactivatedateyear
If the structure contains an arrayed field, the columns will be named with the field name plus an index position. For example, a three-element array named Phone would result in the following columns:
Phone1 Phone2 Phone3
It is possible that duplicate column names could occur, especially if alternate field names are used. If this happens, a number is appended to the end of the duplicate name to make it unique.
Column caption
In addition to a name, each column also has a caption. (This is the DataColumn.Caption property.) The caption can be used to provide a more descriptive name for the column. If there is a value in the Report hdg (heading) field on the Display tab in Repository, it is used for the caption. If there is no report heading value, the column name is used for the caption. If desired, you can change the Caption property from within your client application.
Primary key column
The primary key for the table (the DataTable.PrimaryKey property) is set to the first key in the repository structure that consists of unique data fields. The PrimaryKey property is an array of DataColumn objects, and may therefore consist of more than one column. If the structure does not have an eligible key, the PrimaryKey property is not set. If desired, you can set or change the Primary key property from within your client application.
Your DataTable includes several utility methods that can be used to extract and manipulate rows in the table as structure classes.
- AddRow(), to insert a row at a specific location or add a row to the end of the table
- GetRow(), to return a single row by position
- GetRows(), to return an ArrayList of all rows
See the DataTable methods for additional information about the DataTable utility methods. You can also use the methods that are part of the System.Data.DataTable class; refer to your .NET documentation. Note that if you cast the Synergy DataTable or assign it to a .NET DataTable, you will lose access to the utility methods mentioned above.
|
|
Adding or removing DataTable columns can cause unexpected results if you then try to treat the rows as structure classes. For example, if you add a column to the table and then call the GetRow() method, the additional column will simply be ignored. If you remove a column and then call any of the utility methods, an error will occur. |
//Instantiate an instance of the MyStructure structure. This is // the structure the DT is associated with. MyStructure Customer = New MyStructure(); //Instantiate an instance of the MyStructure DataTable. MyStructureDT CustomerDT = New MyStructureDT(); //Instantiate an instance of component so that we can call its // methods. xfTest myComp = New xfTest(); //Call method and pass the DataTable to be filled. myFillMethod // has one out parameter. myComp.myFillMethod(ref CustomerDT); //GetRow example //Returns row 1 from the CustomerDT DataTable to the Customer // structure. CustomerDT.GetRow(ref Customer, 1); //AddRow example //Instantiate an instance of the MyStructure structure MyStructure NewCust = New MyStructure; //Put data in the structure NewCust.Fname = “Fred”; NewCust.Lname = “Friendly”; NewCust.ID = “FF1234”; //Call AddRow method, passing the structure and specifying a row // position for the new row. New structure is added to existing // Customer DataTable. CustomerDT.AddRow(NewCust, 8); //GetRows example //Create an array list ArrayList myAL = new ArrayList(); //Call GetRows method on the existing Customer DataTable and // fill the array list. myAL = CustomerDT.GetRows();
