As you may already know, the Structured Data Type is the GeneXus object for defining complex data structures.
But, how and where do we define the structure of this object?
By using the SDT Editor. In order to display this editor, we need to create a new SDT object, or just open an existing one.
While creating a SDT object, you may define a multilevel structure, quite similar to the transactions structure. Each level can have one or more members (elements or items). These members may be classified into:
- Simple Elements
- Compound Elements (also composed by other elements).
In this article you will find:
While defining a member (element) in a SDT design, you must specify the following:
- Name property: to identify the element. There cannot be two elements defined with the same name.
- Data Type property: you may select between GeneXus basic types (Numeric, Character, etc), Domains, another already defined SDT.
- Is Collection property: to indicate whether the element has multiple instances (it can be repeated) or not. It has two possible values: True or False
Look at the following image:
While working with SDTs you can define some properties related to each kind of element, in order to have control over the SDT serialization to different formats, such as XML. When working with a simple element (a member) you will see the following XML properties:
These properties allow you to have control over the XML that will be generated.
XmlType Property
This property may have one of the following values:
- Element: Is the default value. The element (member) will be serialized as an XML Element.
- Attribute: The member will appear as an XML attribute but in the last level of the parent element.
- CData: The member will be serialized as an element with a CDATA. It is usually used with values that contain XML.
- Value: The member will be the Value of the parent Element.
XML Namespace property
XML Namespace =
They are those elements defining a new element group, a new collection, or a group of simple elements.
Different bullets, in the editor, identify the compound elements. Let's see them:
Identifies a member in an SDT.
Identifies a collection
Identifies a structure, a group of simple elements
Compound elements have the same properties as do simple elements, but the Data Type property is not enabled.
In the following example you can see a Structured Data Type named Customers with some simple and compound elements:
Now look at the corresponding Properties windows:
When a substructure defines a collection, besides the data type created with the SDT name, there will be another data type created with Name.SubstructureName, and they will be selectable as data types in any variable definition. This means that two data types will be created. Following with our example, while defining variables in a procedure, you may see:
Let's stop and take a look again at the image of the Collection properties window. Can you see the Collection Serialization property?
The purpose of this property is to help solve the problem of how to serialize a collection. Its possible values are:
- Wrapped: Default value. Includes the collection start/end tag.
- Sequence: Will serialize as a plain sequence of collection elements.
As any other editor, the SDT editor allows you to define actions over each kind of element by right-clicking on:
- Structured Data Type
- Collection
- Member
Drag and drop: You can select a Transaction from the Folder View and drop it into the SDT structure. The Transaction structure will be added to the SDT structure.
By right-clicking on a Structured Data Type you will see the following secondary menu:
- Insert Member: Allows you to insert a new member (element) to the SDT structure.
- References: Displays which objects refer to the SDT object
- History: Displays all modifications done to the SDT object (version, name, date, user)
- Properties: Displays the Properties window.
- Locate in Folder View: Shows you where the SDT object is located within the Folder View.
Note: When you need to insert a new member in the structure, you may use the corresponding option in this secondary menu shown above, or you may also drag the attribute to the structure. Look at the following image:
Another method for inserting members in the SDT structure is to use the Insert Menu from the GeneXus main toolbar.
The available menu options are :
- Insert Attribute : inserts a member with the same name and with type based on the selected attribute
- Insert Domain : inserts a member with the same name and with type based on the selected domain
- Insert Object (only transactions can be selected) : inserts one member for each attribute in the transaction structure, with the same name and type based on it. Note: If the description of an attribute of the transaction changes, it also changes in the SDT structure (as since GeneXus 15 upgrade 3).
If the focus is on the SDT structure root, the new members added with the Insert menu will be placed on the end of the structure, if the focus is on one existing member, the new member will be added inmediately after the selected one.
By right-clicking on a Collection you will see the following secondary menu:
- Delete: Deletes the Collection.
- Move Items Up: Moves the Collection up in the SDT structure.
- Move Items Down: Moves the Collection down in the SDT structure.
- Indent: Adds the selected collection under a new collection.
- Unindent: Takes the selected collection away from its container collection.
- Insert Member: Allows you to insert a new member to the collection.
- Insert Sibling Substructure: Allows you to define a substructure under the SDT structure (under Customers, in the example above).
- Properties: Displays the Properties window.
By right-clicking on a Substructure you will see a secondary menu quite similar to the Collection menu:
By right-clicking on a Member you will see a secondary menu quite similar to the Collection menu:
1) Suppose that you have the following SDT:
You want to generate the following XML:
Richard Smith
Susan Flynn
So, you will need to set the following values to the corresponding properties:
- XmlType property in Id member: attribute
- XmlType property in Name member: value
2) Suppose that you have now defined an SDT like the one below:
The collection may be serialized as follows:
Montevideo Rocha ...
In this case the Collection Serialization property must be specified as: Wrapped
Or as:
Montevideo Rocha ...
In this case the Collection Serialization property must be specified as: Sequence
By working with the SDT Editor you may define collections as shown in the following image:
However, you will not be able to define a collection based on any Data Type (Numeric, Character, another SDT data type, BC, etc). In order to solve this situation you must work with Collection Domains, or you may even define a Collection Variable based on the corresponding Data Type, as shown below.
Recursive SDTs Implementing SDT Collections
User controls, SDTs and Data Providers