How to: Use a Map in X++

Article
05/18/2015

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

You need unusual X++ syntax to use an AOT map object in Microsoft Dynamics AX. Some of the X++ statements are late-bound, and errors in them cannot be detected until run time.

Example of Using a Map in X++

The following sections describe the AOT objects for an example of using a map in X++. The objects would be found in the following AOT locations:

AOT > Data Dictionary > Tables
AOT > Data Dictionary > Maps
AOT > Jobs

The Tables

The following table presentation describes the two tables that are used in the example.

Table name	Fields	Methods
TabPhone	brandName batteryVoltage1	public void doubleTheVoltage()
TabClock	brandName batteryVoltage2	public void doubleTheVoltage(str _comment)

TabPhone

brandName

batteryVoltage1

public void doubleTheVoltage()

TabClock

brandName

batteryVoltage2

public void doubleTheVoltage(str _comment)

The Map

The following table presentation is designed to mimic the node hierarchy of the AOT for a map. The MapDevice node would be located under AOT > Data Dictionary > Maps.

MapDevice
	Fields
		brandName batteryVoltage3
	Mappings
		TabClock
			MapDevice.brandName == TabClock.brandName
			MapDevice.batteryVoltage3 == TabClock.batteryVoltage2
		TabPhone
			MapDevice.brandName == TabPhone.brandName
			MapDevice.batteryVoltage3 == TabPhone.batteryVoltage1
	Methods
		public void doubleTheVoltage(str _comment) public int getTheVoltage()

The X++ Job Code

The following X++ job code shows the important lines of code for using a map in X++ code. The comments are discussed in more detail in a section that follows the code.

    // X++ job.
    static void MapJob()
    {
        MapDevice mDevice;
        TabClock tClock;
        TabPhone tPhone;
        ;
        // 1: Call the method as it is implemented on the map.
        mDevice.doubleTheVoltage("Testing");
    
        // 2: Twice, call a method that is defined in the AOT under MapDevice > Methods.
        mDevice.getTheVoltage();
        mDevice.MapDevice::getTheVoltage();
    
        // 3: Activate the TabClock mapping on the map.
        mDevice = tClock;
    
        // 4: Set fields that are defined in the AOT under MapDevice > Fields.
        mDevice.brandName = "Contoso";
        mDevice.batteryVoltage3 = 9;
    
        // 5: Call an inherited method. The toString method returns "Class xRecord".
        print mDevice.toString();
    
        // 6: Call a method that is defined in the AOT only under MapDevice > Methods.
        mDevice.MapDevice::getTheVoltage();
    
        // 7: Call the method as it is implemented on the table.
        mDevice.doubleTheVoltage("Testing");
    }

Elaboration of the X++ Job Comments

The following table presentation discusses the // comments from the previous X++ job code example.

Comment in X++ job	Discussion
// 1: Call the method as it is implemented on the map.	The method name doubleTheVoltage is used in both tables and in the map. No table buffer has yet been assigned to the map. Therefore, this call to mDevice.doubleTheVoltage("Testing") is understood by the X++ runtime engine to refer to the method defined on the map itself. The compiler cannot know whether the call will be valid during run time. The compiler does not know whether a buffer for the TabPhone table will first be assigned to the map variable, which would make the call invalid. Therefore, this is a late-bound call, and final validation of this call occurs at run time.
// 2: Twice, call a method that is defined in the AOT under MapDevice > Methods.	The second of these two calls has the extra segment MapDevice:: in its syntax. Because no table buffer has yet been assigned to the map, this extra segment is optional at this point in the code.
// 3: Activate the TabClock mapping on the map.	The assignment mDevice = tClock succeeds because the map has a mapping for the TabClock table. The fields of the map now reference the values of their corresponding fields in the tClock table buffer.
// 4: Set fields that are defined in the AOT under MapDevice > Fields.	In these assignment statements, the only field names that the map variable can reference are those that appear in the AOT under Maps > MapDevice > Fields. Field names from the table buffer cannot be used.
// 5: Call an inherited method. The toString method returns "Class xRecord".	The toString method is the implementation from the xRecord class.
// 6: Call a method that is defined in the AOT only under MapDevice > Methods.	The method name getTheVoltage occurs only on the map, not on either table in this example. Despite the uniqueness of the method name, the call mDevice.MapDevice::getTheVoltage() to this method must include the segment MapDevice::. This segment would be optional if no table buffer had been assigned to the map.
// 7: Call the method as it is implemented on the table.	The method name doubleTheVoltage occurs on both tables and on the map. From the three available implementations of the method, the implementation that is invoked by mDevice.doubleTheVoltage("Testing") depends on whether a table buffer has been assigned to the map variable. At this point in the code, a table has been assigned to the map. Therefore, the call must contain no additional qualifiers. This called method is implemented on the TabClock table. However, it is not valid to explicitly qualify with the table or mapping name, as in mDevice.TabClock::doubleTheVoltage(“Testing”).

Share via