Mertech Structure Analyzer - Dynamically Describe Structures in DataFlex

The Mertech Structure Analyzer  is a new open-source  tool  that gives DataFlex developers the ability to  dynamically describe and access  data structures.

When dealing with structures, DataFlex developers often  want to be able to dump or load a structure to XML or some other format.  DataFlex has support for turning a structure into what is called a ValueTree,  which are quite useful  when you're trying to iterate over structured data. 

However, ValueTrees  cannot provide any information about the  names of the structure elements and their data types.   This makes it difficult to use structures in scenarios where dynamically describing structures is very useful, such as  using in Dictionaries, associative arrays, or hash tables.

Mertech's new helper class is able to provide developers with both an XML dump that describes a structure along with an easy to use datatype you can access that describes structures as well. We've even been able to develop for this first version the ability to get the value of a structure element dynamically! Using this new class is very easy. As an example, let's look at this bit of code:

Struct tCustomer
   Integer Customer_Number
   String Name
   String Address
   String City
   String State
   String Zip
   String Phone_Number
   String Fax_Number
   String Email_Address
   Number Credit_Limit
   Number Purchases
   Number Balance
   String Comments
   String Status
End_Struct

Struct tOrderDetail
   Integer Detail_Number
   String Item_ID
   String Description
   Integer Qty_Ordered
   Number Price
   Number Extended_Price
   Integer Deleted
End_Struct

Struct tOrder
   tCustomer Customer
   Integer Order_Number
   DateTime Order_Date
   String Terms
   String Ship_Via
   String Ordered_By
   String Salesperson_Id
   Number Order_Total
   Integer Last_Detail_Num
   tOrderDetail[] a_Details
End_Struct

You'll notice that we have a tOrder, which in our case is the main structure we're going to look at. It contains a member called Customer of type tCustomer and an array of order details of the type tOrderDetail. You can of course access items inside of this structure easily in VDF:

move anOrder.Customer.Email_Address to email
move anOrder.a_Details[2].Price to item2_price

But what if you wanted to work with a variable that could contain ANY structure? What if you don't know at compile time what the name of a member element is? Say for instance that you want to dynamically map element names from the structure to field names in a DD or something similar. Your first thought might be to something like this:

Get_Attribute DF_FIELD_NAME Of hTable iColumn To sColumn
move (eval("anOrder.a_Details[i]." + sColumn)) to item2_price

However,  the Dataflex expression evaluator doesn't work on structured datatypes. In addition, there is no way to iterate over the data in a structure dynamically. This can on occasion be very useful to do. For instance, if you wanted to write out to an XML file a structure dynamically that includes the names of each field (and information about the datatypes as well). Using our new class, all of these are trivially easy operations. All you need to do to make use of this class is include the cMertechStructAnalyzer.pkg file in your applications ".SRC" file. An oStructAnalyzer object will be created for you. Making use of this object is very easy. If you'd like to get back an XML description of a type just do is:

Get AnalyzeStructureXML of oStructAnalyzer "tOrderDetail" to sXML

We've created some helper functions that allow you to get back an easy to iterate description of a structure as well:

Get AnalyzeStructure of oStructAnalyzer "tOrder" to tGenericStruct

The tGenericStruct returned above is a structure we created to help describe other structures (unlike the tValueTree which is meant to store the content of a structure/array/primitive):

Struct tMemberElement
 String memberName
 String memberType
 Boolean isArray
 Variant subStructure
End_Struct

Struct tStructure
 String structName
 tMemberElement[] memberElement
End_Struct

This tStructure and tMemberElement makes it very easy to create loops that can look at not only the description of a structure, but also the content. So, going back to our prior attempt to use eval, using the Mertech Structure Analyzer allows us to retrieve the value very easily:

Get_Attribute DF_FIELD_NAME Of hTable iColumn To sColumn
Get MemberValue of oStructAnalyzer "tOrder" ("a_Details[2]." + sColumn) anOrder to retVal

As you can see, this command even supports traversing into arrays of structures and structures that contain member elements that are also structures. The parameters are very simple: the name of structure type, the member you're interested in retrieving, and the actual structure variable itself. The implementation of this MemberValue function makes use of ValueTree's and our tStructure to iterate over a structure variable and return the value of a structure member.

What happens if the member you're interested in retrieving is also a structure itself? Well, for now it will return that portion of the ValueTree, but in the future we may extend this class to support return structures as well. Another limitation to be aware of is related to recursive structures. In this first version you can analyze a recursive structure, but you can't retrieve data inside of the recursive part of a structure.

This class is being provided free of charge and you are welcome to use it in your product, to extend it's functionality, whatever use you see fit. We ask only that you keep our copyright notice at the top of the cMertechStructAnalyzer.pkg file.

Please feel free to contact us if you find a bug (or even better if you fix a bug!), or if you have any questions or suggestions about the use of this class.