Repository structures passed as parameters to your Synergy methods are included in your Synergy assembly as classes. There will be a separate class for each structure, named with the structure name. The fields in the repository structure will become either properties of the structure class or public fields (if you ran gencs with the -g option or selected “Fields” for “Generate structure members as” in Workbench).
|
See Appendix C: Data Type Mapping for xfNetLink .NET for details on how data types for structure fields are mapped from Synergy to .NET. |
When you generate structure members as properties, fields that are flagged as read-only in Repository will be generated as read-only properties and will therefore have a “get” method but no “set” method. The read-only flag is not honored when you generate structure members as public fields.
For example, say you have this repository structure, which is passed as a parameter to the login() method.
user
fname ,a25
lname ,a25
maxrate ,d18.2
group address ,a
street ,a20
city ,a20
state ,a2
zip ,d9
endgroup
In your assembly, you’ll see a class named “User” with the properties/fields Fname, Lname, Maxrate, and Address. You’ll also see a class named “Address” in the assembly. This class represents the Address group within the User structure. (Fields defined as struct data type in the repository are treated the same as group fields.) The Address class has four properties/fields—Street, City, State, and Zip. Under normal circumstances, you won’t need to access the Address class directly. When you instantiate a new User object, an Address object is automatically instantiated.
|
|
By default, the properties/fields are named with the repository field names. If a field name contains a dollar ($) character, it is changed to an underscore (_). ($ is not a valid character in a C# identifier.) If this substitution causes a name collision, you’ll need to use an alternate field name in Repository. See Passing structures as parameters for details on overriding the default naming behavior. |
To access the properties/fields, instantiate an object for the User class and assign values to the properties/fields as shown in the examples below.
In C#:
User myData = new User(); myData.Fname = "Mickey"; myData.Lname = "Franklin"; myData.Maxrate = 150.00; myData.Address.Street = "2330 Gold Meadow Way"; myData.Address.City = "Gold River"; myData.Address.State = "CA"; myData.Address.Zip = 956704471;
In VB:
Dim myData As New User() myData.Fname = "Mickey" myData.Lname = "Franklin" myData.Maxrate = 150.00 myData.Address.Street = "2330 Gold Meadow Way" myData.Address.City = "Gold River" myData.Address.State = "CA" myData.Address.Zip = 956704471
Then, pass the myData object when you call the login() method.
In C#:
int retVal = 0; retVal = userSess.login(userID, password, myData);
In VB:
Dim retVal As Integer retVal = userSess.login(userID, password, myData)
For more information on passing structures as parameters, and for details on how overlays are handled, see Passing structures as parameters.
Using the Clone() and Equals() methods
Your generated structure class includes the utility methods Clone() and Equals(). The Clone() method creates an exact duplicate (including data) of the class on which it is called. The Equals() method tests whether the data in two structure classes is the same.
In the example below we show how to clone a structure class and then compare it to the original.
//Instantiate an instance of Mystruct class Mystruct Client = new Mystruct(); //Fill data fields of the class Client.Fname = “Fred”; Client.Lname = “Friendly”; Client.ID = “FF1234”; //Call Clone method on Client class to create duplicate. Mystruct Client2 = Client.Clone(); . . //Do some processing here . //Call Equals method on cloned class, passing the original // class. bool isEqual = Client2.Equals(Client);
See also Structure methods.
Using the Changed property
You can use the Changed property to determine whether data in a structure class has changed since the structure class was created or was returned to the client from the server. The Changed property is included in structure classes when structure members are generated as properties (rather than fields).
The Changed property returns a Boolean value of true if the value of any property’s data field in the structure class has been changed by calling the set method. If no values have changed, it returns false. If you need to test whether a specific field has changed, use either the Clone() and Equals() methods or the Original property.
For example,
//Instantiate an instance of Mystruct class Mystruct Client = new Mystruct(); //Check for changes in the structure’s data bool isChanged = Client.Changed(); if (isChanged); . . //Do something here if returns true .
You can use the Original property to store a copy of a structure within the object. The Original property is included in structure classes when you use the gencs -r option; it is null when created and remains so unless you use it.
The Original property serves a function similar to that of the Clone() method, in that it enables you to compare a copy of a structure with the original to see which (if any) fields have changed. (By contrast, the Changed property simply tells you that something in the structure class has changed.) The difference is that using the Original property stores the copy within the object, whereas with the Clone() method, the copy is separate. This means Original is useful if you need to pass the object to another method while maintaining the copy of the structure. If you continue to use the object after the original structure has served its purpose, you may want to set Original back to null to free up memory.
In the example below, we save a copy of the Client structure class, then check later to see if a field has changed.
//Instantiate an instance of Mystruct class Mystruct Client = new Mystruct(); //Fill data fields of the class Client.Fname = “Fred”; Client.Lname = “Friendly”; Client.ID = “FF1234”; //Use Clone method to populate Original property. Client.Original = Client.Clone(); . . //Do some processing here . //Get original structure MyStruct ClientOrig = Client.Original; //Check to see if ID has changed If ClientOrig.ID == Client.ID; . . //Do something here if changed .
