You can pass repository structures as parameters when using xfNetLink Java or xfNetLink .NET. xfNetLink supports passing structures of primitive, date, and time types; structures with embedded structures (that is, groups or struct data types) or embedded arrays; arrays of structures; and enumeration types within structures. User-defined fields are generally treated as strings, except for some specific datetime formats. See Appendix B: Data Type Mapping for xfNetLink Java and Appendix C: Data Type Mapping for xfNetLink .NET for complete information on supported data types and for details on how repository field data types are mapped from Synergy to xfNetLink.
Regardless of whether you create a JAR file or an assembly, during the component generation process, the repository structure becomes a class (named with the structure name), and each field in the structure becomes a property of that class. (In xfNetLink .NET, you can choose to generate repository structure fields as properties or as public fields. See Creating a Synergy/DE .NET Component project or Generating C# classes with gencs.)
By default, the repository field name becomes the property name. For xfNetLink .NET, if there is a dollar ($) character in the field name, it is changed to an underscore (_). You can change the default naming behavior by specifying an alternate name in the “Alt name” field (on the Display tab) in Repository. Then, indicate you want to use the alternate name by selecting the “Use alternate field names” option in the Component Information dialog box in Workbench, or by specifying the -n option when you run genxml from the command line.
When using structures with xfNetLink, the sum of the sizes of the fields in the structure must always equal the total size of the structure as calculated by Repository. (This value displays at the bottom of the Field Definitions list in Repository.) Similarly, the sum of the sizes of the fields in a group must equal the size of the group (if the group size is declared). In most circumstances, this will not be an issue. The only time it is likely to become a problem is when you are using the Excluded by Web flag (see Using the “Excluded by Web” flag).
|
If you intend to attribute your Synergy code and use the XML file generated by dbl2xml to populate the SMC, structures passed as ordinary parameters and as arrays must be defined as structfields in your Synergy code. See structure for more information on structfields. Structures passed as ArrayLists and structure collections are identified by attributes. See Using attributes to define Synergy methods. |
For more information on using structures, refer to the topic for your client:
If your Java or .NET client passes structures as parameters, and you want to also use an xfNetLink Synergy client, you can do so without altering your server-side code. Simply create a separate SMC entry for the Synergy server routine and define the parameter as an alpha rather than a structure.
How overlays are handled
If your structure definition in Repository includes overlays, you can either accept the default behavior or explicitly indicate which fields should be included/excluded with the “Excluded by Web” flag. The explanations below apply to both structures and groups.
The default behavior
By default, the way your fields are defined in Repository determines which fields will be accessible to someone using your Synergy component. The structure is read from the top down, and the “real” fields (overlaid fields)—rather than the overlays—are used. To determine whether you can use your repository structures as they are currently defined, you need to first determine which fields you want to make available in your client application.
For example, if you have this structure in your repository
customer
firstname ,a20
mi ,a1
lastname ,a30
name ,a51 @ firstname
the default behavior enables you to access the firstname, mi, and lastname fields from your client application. For example:
Customer.Firstname Customer.Mi Customer.Lastname
However, if you have this structure in your repository
customer
name ,a51
firstname ,a20 @ name
mi ,a1 @ name + 20
lastname ,a30 @ name + 21
the default behavior enables you to access only the name field from your client application. For example:
Customer.Name
Using the “Excluded by Web” flag
If the default behavior is undesirable, you can use the “Excluded by Web” flag in Repository to explicitly indicate which fields are included/excluded. (See Basic field information for information on this flag.) Fields for which the Excluded by Web flag is set will not be included in your Synergy component. Once you select the Excluded by Web flag for a field in a structure, genxml will cease to use the default behavior for that structure and will honor the Excluded by Web flag instead.
|
The Excluded by Web flag is intended for use only with overlays and overlaid fields. Do not attempt to use it with other repository fields. If you do, you’ll see the error “Structure name size (##) must equal the sum of the field sizes (##)” when you run genxml or try to export from the SMC. See Synergex KnowledgeBase article 2493 for more information on this error. |
The sum of the sizes of the selected fields must always equal the size of the entire structure as calculated by Repository. Note that Repository does not recalculate the structure size when you exclude fields with the Excluded by Web flag. (The structure size, as calculated by Repository, is displayed at the bottom of the Field Definitions list; see Displaying the Field Definitions list.)
For example, if you have this structure in your repository
customer
name ,a51
firstname ,a20 @ name
mi ,a1 @ name + 20
lastname ,a30 @ name + 21
and you want to be able to access the firstname, mi, and lastname fields like this from your client application
Customer.Firstname Customer.Mi Customer.Lastname
you would set the Excluded by Web flag for the name field.
To prepare structures for passing as parameters
| 1. | Define the structure in the repository or use an existing structure. See Working with Structures and Working with Fields for instructions. |
| 2. | If your structures include overlays, decide how you want to handle them and set the “Excluded by Web” flag if necessary. |
| 3. | If you are attributing your code and using the XML file output by dbl2xml to populate the SMC, .INCLUDE the repository structure in your Synergy source code and define the structure as a structfield. See Using attributes to define Synergy methods. |
| 4. | If you are using the MDU to populate the SMC, |
- Specify the repository when you start the Method Definition Utility (MDU). See Using the MDU to define Synergy methods.
- Select the structures when you define parameters in the MDU. See step 1 in To define parameters.
If you include structures in your parameter definitions in the SMC, and then later alter those structures in Repository, they are not automatically updated in the SMC. You can use the MDU’s Verify Catalog utility to update the structure sizes. See Verifying repository structure sizes and enumerations for more information.
| 5. | When you create your Synergy component, specify the repository in the Component Information dialog box in Workbench or on the command line when running genxml. For details, refer to the topic for your client: |
- Java, see Creating Java Class Wrappers.
- .NET, see Creating Synergy .NET Assemblies.
