MDM 5.5 API Tips and Tricks – Measurement Fields

The MDM 5.5 API’s provide a complete set of classes and functions for programmatically displaying and updating repository data. Sometimes, though, the use of these API’s is somewhat obscure and the information can be difficult to find in the documentation.

In this first weblog, I will explain how to read and display the data in a Measurement field, and also how to update it in the repository. While in most cases the COM API and Java API are almost identical, in this particular case there are subtle differences, and I will demonstrate the use of both API’s.

For this example, I created a new repository via the MDM Console and added a couple of records to the catalog via the MDM Win32 Client. In the Products table I created just two fields:
Field Name: Name
Field Type: Text

Field Name: Length
Field Type: Measurement, Dimension = Length, Default Unit = centimeters, Decimal Places = 2

COM API
For this example we will use C#. In your project you need to add a reference to the MDMCOM 2.0 Type Library and add using XCATCOMLib; at the start of your file.
The main trick for manipulating Measurement fields via the COM API is to cast the field value to a CharacteristicValue type.
Here is the code:

static void Main(string[] args)
{
     try
     {
          // create a new catalog object
          ICatalog catalog = new CatalogClass();

          // log into the catalog with your own server, port, user and password parameters
          catalog.Login("localhost", 1234, "Admin", "", "English [US]", 5, 5, 10000);
          
          // create a ResultSetDefinition for the Products table
          ResultSetDefinition rsd = new ResultSetDefinitionClass();
          rsd.Table = "Products";
          rsd.Fields.Append("Name", null);
          rsd.Fields.Append("Length", null);

          // create an empty Search object on the Products table
          Search search = new SearchClass();
          search.SearchTable = rsd.Table;

          // read the records in the table
          IResultSet rs = catalog.GetResultSet(search, rsd, "Name", true, 0);
          for( ; !rs.EOF; rs.MoveNext())
          {
               // get the "Name"
               String nameValue = (String) rs.Fields.Item("Name").Value;
               Console.WriteLine(nameValue);

               // get the field "Length"
               Field lengthFld = rs.Fields.Item("Length");
               // get the Length value, and cast it to CharacteristicValue
               CharacteristicValue cv = (CharacteristicValue) lengthFld.Value;

               // format the value for printing
               String formattedValue = cv.GetString(lengthFld.DimensionID, 2, lengthFld.ShowFractions, lengthFld.DefaultUnitID);
               Console.WriteLine("Length = " + formattedValue);

               // update the field
               FieldsClass fields = new FieldsClass();
               FieldClass fieldToUpdate = (FieldClass) lengthFld.Clone();
               cv.Value += 1.00;
               fieldToUpdate.Value = cv;
               fields.Add(fieldToUpdate);
               try
               {
                    catalog.UpdateRecord("Products", rs.ID, rs.ChangeStamp, fields, -1, -1);
                    Console.WriteLine("Update succeeded.");
               }
               catch(Exception ex)
               {
                    // report update failure
                    Console.WriteLine("Update failed: " + ex.Message);
               }
          }
          
          // remember to log out of the catalog when you are finished using it!
          catalog.Logout();
     }
     catch(Exception ex)
     {
          Console.WriteLine(ex.Message);
     }

}

Java API
Unlike the COM API, the Java API provides a Measurement class for using with Measurement fields. Formatting a Measurement value is done via the catalog’s MeasurementManager.
Here is the code: (remember to include MDM4J.jar in your project’s Build Path)

import a2i.common.A2iField;
import a2i.common.A2iFields;
import a2i.common.A2iResultSet;
import a2i.common.CatalogData;
import a2i.common.ResultSetDefinition;
import a2i.core.Measurement;
import a2i.core.StringException;
import a2i.core.Value;
import a2i.generated.MeasurementManager;
import a2i.search.Search;

public class MeasurementFieldDemo
{
     private CatalogData catalogData;
     private MeasurementManager measurementManager;

     public static void main(String[] args)
     {
          MeasurementFieldDemo app = new MeasurementFieldDemo();

          // log into the catalog
          app.login();

          // do your stuff
          app.readAndUpdate();

          // remember to log out when you have finished!
          app.logout();
     }

     private void readAndUpdate()
     {
          // create a ResultSetDefinition on the Products table
          ResultSetDefinition rsd_products;
          rsd_products = new ResultSetDefinition("Products");
          rsd_products.AddField("Name");
          rsd_products.AddField("Length");

          // create an empty Search object
          Search search = new Search(rsd_products.GetTable());
          try
          {
               A2iResultSet rs = catalogData.GetResultSet(search, rsd_products, null, true, 0);
               for (int i = 0; i<rs.GetRecordCount(); i++)
               {
                    // get the "Name" field
                    String name = rs.GetValueAt(i, "Name").GetStringValue();
                    System.out.print("Name: " + name + ", ");

                    // get the "Length" field
                    Measurement meas = rs.GetValueAt(i, "Length").GetMeasurement();

                    // use the MeasurementManager to get the correctly-formatted value
                    String measString =
                         measurementManager.GetString(
                              meas.GetValue(),
                              meas.GetUnitID(),
                              rs.GetFieldAt("Length").GetDimensionID(),
                              rs.GetFieldAt("Length").GetDecimalPlaces(),
                              false,
                              -1);
                    System.out.print("Length = " + measString);
                    System.out.println("");

                    // update the record
                    A2iFields fields = new A2iFields();
                    A2iField field = new A2iField("Length");
                    Measurement newValue = new Measurement();
                    newValue.Copy(meas);
                    newValue.SetValue(meas.GetValue() + 1.00);
                    Value val = new Value();
                    val.Set(newValue);
                    field.SetValue(val);
                    fields.Add(field);
                    catalogData.UpdateRecord("Products", rs.GetIDs().GetAt(i), rs.GetChangeStampAt(i), fields);
                    System.out.println("Update succeeded.");
               }
          }
          catch (StringException e)
          {
               e.printStackTrace();
          }
     }

     private void logout()
     {
          try
          {
               catalogData.Logout();
               System.out.println("Catalog logged out.");
          }
          catch (Exception e)
          {
          }
          finally
          {
               System.out.println("Finished.");
          }
     }

     private void login()
     {
          try
          {
               catalogData.Login("localhost", 1234, "Admin", "", "English [US]", 5, 5, 10000, null);
               System.out.println("Catalog logged in.");
               measurementManager = catalogData.GetMeasurements();
          }
          catch (Exception e)
          {
               System.out.println("Error logging in: " + e.getMessage());
          }
     }

     public MeasurementFieldDemo()
     {
          catalogData = new CatalogData();
     }
}