Monday, July 30, 2018

Collection classes

The X++ language syntax provides two compound types: arrays and containers.
They are useful for aggregating values of simpler types. However, you cannot store objects in arrays or containers. 

The Microsoft Dynamics AX collection classes have been designed for storing objects. The classes are implemented in C++ to achieve the maximum performance (they are system classes).

Collection classes were formerly called Foundation classes.

ClassDescriptionData typesAccess
ListValues stored sequentially with ability to add values at the beginning or end of the listAll values must be the same data typeUse ListIterator or ListEnumerator
SetValues stored non-sequentially. Duplicates are not added to the set.All values must be the same data typeUse SetIterator or SetEnumerator
MapValues stored by using a unique key.The key and the value need not be from the same data type.Use MapIterator or MapEnumerator
StructValues stored by using a unique string as a keyThe key must be a string. The values can be of any type.Provide the string key to the value method

List -----
  • A list stores objects of all the same type in a sequential order. 
  • The elements can be any type specified in the Types base enum. 
  • Elements may be added to the beginning or end of the list. 
Usefull list methods:
addEnd(_item) -- Adds _item to the end of the list
addStart(_item) -- Adds _item to the beginning of the list
appendList(_list) -- Adds elements _list to the end of current list
elements                 -- Returns the number of items in the list
getEnumerator -- Returns an enumerator for traversing the list

public void listExample() {
    List listOne;
    List listTwo;
    List combinedList;
    ListEnumerator listEnumerator;
    SalesTable salesTable;

    // Initialize using Types enum
    listOne = new List(Types::String);

    // Initialize using extendedTypeId2Type which does not require
    // knowing the base type
    listTwo = new List(extendedTypeId2Type(extendedTypeNum(SalesId)));

    // Add a and b to list such that order is b,a

    // Add an actual sales id and dummy sales id
    select firstOnly SalesId from salesTable;

    // Print first list
    listEnumerator = listOne.getEnumerator();
    info("List one");
    while (listEnumerator.moveNext()) {

    // Create a new list by combining lists
    combinedList = List::merge(listTwo, listOne);

    // Print combined list
    listEnumerator = combinedList.getEnumerator();
    while (listEnumerator.moveNext()) {

Set :
A set is an unordered collection that contains elements of all the same type and is similar to a mathematical set in that each element must be unique. 
Again, the types are all the possible types of the Types base enum. 
Repeated inserts of a value that is already in the set will have no effect. 
There will be no record of how many such inserts of a duplicate value occurred. 
For example, if a set of Types::Integer contains only the integer 2, repeated calls to the add method with 2 as a parameter will have no effect. No matter how many such calls are made, the set will still only contain the integer 2. 
One possible use of a set is to store RecIds to ignore any duplicate records and insure a process only acts once per record.
Unlike a list, an element can be removed from a set directly without using an iterator. There are also powerful methods that mimic mathematical set operations that allow creation of new sets based on two existing methods. 
Set Methods:
add(_item)                           --------Adds _item to the set
delete(_item)                    --------Removes the passed in item to the set
elements                          ---------Returns the number of items in the set
getEnumerator                 ----------Returns an enumerator for traversing the set
in(_item)                         ----------Returns true if _item is present in the set
difference(_set1, _set2) ----------Returns items that are in _set1 but are not in _set2
intersection(_set1, _set2) ----------Returns a new set that contains only elements present in both _set1 and _set2
union(_set1, _set2)        ----------Returns a new set that contains all the elements of _set1 and _set2.
public void setExample() {
    Set setOne;
    Set setTwo;

    // Inner method for printing sets
    void printSet(Set _set, str _prefix) {
        int i;
        SetEnumerator setEnumerator;
        str output = _prefix;

        setEnumerator = _set.getEnumerator();

        // Add each element to output string 
        while (setEnumerator.moveNext()) {
            output += strfmt(" %1", setEnumerator.current());

    // Declare sets
    setOne = new Set(Types::String);
    setTwo = new Set(Types::String);

    // Fill sets

    // Size of set
    info(strfmt("Size of set one: %1", setOne.elements()));

    // Print sets and the results of set operations
    printSet(setOne, "Set 1");
    printSet(setTwo, "Set 2");
    printSet(Set::difference(setOne, setTwo), "Difference ");
    printSet(Set::intersection(setOne, setTwo), "Intersection ");
    printSet(Set::union(setOne, setTwo), "Union");


A map stores key-value pairs. For each key, there is a corresponding value.
Accessing the corresponding value of a key is a fast operation. 
The keys are unique and are all of the same type. The values do not have to be unique and also are all the same type. As with the other collection classes, the possible types are those specified by the Types base enum. Note that the key types and value types do not need to be the same and typically are not.
Some examples of maps are keys that are RecIds or strings that correspond to a numeric value. Another example is mapping RecIds from one table to a Record of another table, thus quickly and easily creating a fast performing link between two tables without having to use a temp table. The diagram below shows a map with Int64 keys mapping to reals.
Useful map methods are summarized in the table below:
delete(_key)Deletes _key (and thereby its corresponding value) from the map
elementsReturns the number of key-value pairs in the map.
exists(_key)Returns true if _key is present in the map.
insert(_key, _value)Inserts the key value pair with a key of _key and a corresponding value of _value. In other words, lookups for _key will return _value.If _key already existed in the map, the corresponding value of that key is overwritten such that the new mapped value is _value.
lookup(_key)Returns the corresponding value of _key.
One important note is that calling the lookup method for a key that does not exist in the map will cause a runtime error. Therefore, the exists method should always be called first to verify that the key exists.
The MapEnumerator class traverses a map. The key and value are retrieved from the enumerator using the currentKey and currentValue methods.
The code below shows examples of several of the map methods including using an enumerator:
public void mapExample() {
    Map theMap;
    MapEnumerator mapEnumerator;
    real value;

    // Declare map
    theMap = new Map(Types::String, Types::Real);

    // Insert values into the map
    theMap.insert("LOT-01", 42.5);
    theMap.insert("LOT-02", 58.3);

    // Insert new value for LOT-01.  Previous value overwritten.
    theMap.insert("LOT-01", 99.9);

    // Traverse the map
    mapEnumerator = theMap.getEnumerator();
    while (mapEnumerator.moveNext()) {
        info(strfmt("key %1 value %2",

    // Check if key exists
    info(strfmt("Does LOT-01 exist? %1", theMap.exists("LOT-01")));

    info("Checking if LOT-03 exists");
    if (theMap.exists("LOT-03")) {
        // Will not execute this code, so there is no error
        value = theMap.lookup("LOT-03");

    // Will cause run time error: Lookup a key that is not in the map without 
    // first calling exists
    value = theMap.lookup("LOT-03");

    value = 1;
The code above produces the following output:


struct groups information into a single entity. Any of the types of the Types enum can be stored which includes containers, dates, Int64’s, integers, objects, real numbers, records, strings, times, and UTCDateTimes. The diagram of the struct named “custInfo” shows an example struct that collects a string, real number, record, and object into a single entity.
The struct class is one of the simplest collection classes. Using a struct is similar to using a container that has a small number of values at fixed positions (such as the TradeTotals class). One major difference is that a struct is a class while a container is a built-in data type. A struct uses string indexes whereas a container uses numeric indexes. One of the problems with both is that the indexes or keys need to be managed entirely by the developer. For example, in the struct illustrated above, the value “43.58” needs to be accessed by providing the string “invoiced” exactly. Using the string “invoice” will cause a run time error because no value exists for the key “invoice”. For both structs and containers, one way to manage this issue is to access the keys/indexes using #define or methods.
The code below uses a constant for the invoiced but not the other keys. The code shows how to create and fill the struct illustrated above as well as how to iterate through a struct.
public void structExample() {#

    Struct theStruct;
    SalesTable salesTable;
    int i;

    // Create struct
    theStruct = new Struct(
        Types::String, "name",
        Types::Real, #invoiced,
        Types::Record, "order");

    // Fill struct
    theStruct.value("name", "John Smith");
    theStruct.value(#invoiced, 43.58);
    select firstOnly salesTable;
    theStruct.value("order", salesTable);

    // Add a new entry into the struct
    theStruct.add("orderType", SalesTableType::construct(theStruct.value("order")));

    // Print struct information
    info(strFmt("Definition string: %1", theStruct.definitionString()));
    for (i = 1; i <= theStruct.fields(); i++) {
        info(strFmt("Field name: %1 Type: %2",

    // Using exists for a key
    info(strFmt("Exists for key 'xyz'? %1", theStruct.exists("xyz")));
Below is the output produced by the above code:
The sections below outline aspects of collection classes that may apply to more than one collection class.

Iterators vs. Enumerators

Enumerators should always be used to traverse a list, set, or map unless elements need to be deleted. Iterators can fail if they are used on a different tier than the tier where they were created. For example, code will fail if an iterator was created on the client side, but then runs on the server side or vice versa. Also, loop maintenance is easier when using an enumerator since there is no need to advance the iterator as a separate step.
while(iterator.more())     while (enumerator.moveNext())
{                          {;   }
If the client/server problem can be safely avoided, then iterators can be used for deletion. However, there are alternative solutions (potentially expensive) to deleting elements from a collection without using an iterator. For a set, one possibility is putting elements to delete in a second set during traversal and calling the static intersection method. For a map, one could put keys to be deleted in a set, then traverse the set, deleting each key individually.

Pack and Create

All the collection classes mentioned above can be packed into a container using the pack method. A new instance of these classes can then be created using the appropriate static create method.
public void packCreateExample() {
    List aList = new List(Types::Real);
    List aNewList;
    container c;

    // Fill list

    // Pack the list into a container
    c = aList.pack();

    // Create a new list from the packed list
    aNewList = List::create(c);

Uniqueness of Tables and Classes

Special care should be taken if tables or classes need to be unique within the collection classes. This includes elements in a set or keys of a map. If you use a table as a unique key to a map, it seems that RecId is not the field used to determine uniqueness. Instead, non-system fields are checked. One way to bypass this is to add a GUID field to the table (thanks to Justin Wong for pointing this out). For classes it seems that even if two objects have the same values for variables, the objects will be determined to be unique by the collection classes.

Sorting Behavior of Sets and Maps

No matter what order elements are added to a set or keys are added to a map, when using an enumerator to traverse the set or map, the elements are in a sorted order (for string and numeric types). However, the MSDN documentation for the set class states that elements are stored in a set “in a way that facilitates efficient lookup of the elements.” It might not be safe, therefore, to rely on this sorting behavior as it might possibly change in the future.
The code below shows the sorting behavior in a set of reals:
public void setSortingExample() {
    Set set = new Set(Types::Real);
    SetEnumerator setEnumerator;


    setEnumerator = set.getEnumerator();
    while (setEnumerator.moveNext()) {
The result of this code is shown below:


  1. If you are interested in a profession in the medical industry that is very hands on, but does not involve doing surgery or working in an office all day, a physical therapy degree might be just right. Especially geared toward individuals who enjoy physical fitness, sports medicine and helping patients one on one, PT jobs are a great in-between that can be very fun, very rewarding, and make a real difference in other people's lives. While all doctors and medical personnel help people, a physical therapist is frequently the last specialist to... vector positive physics


How to enable the dimension fields based on the Item selected on the form.

[Form] public class KMTShipFromWarehouses extends FormRun {     InventDimCtrl_Frm_EditDimensions        inventDimFormSetup;     /// &l...