The Microsoft Dynamics AX type system doesn’t have a single base type from which all types ultimately derive. However, the anytype type imitates a base type for all types. Variables of the anytype type function like value types when they are assigned a value type variable and like reference types when they are assigned a reference type variable. You can use the SysAnyType class to explicitly box all types, including value types, and make them function like reference types.

The anytype type, shown in the following code sample, is syntactic sugar that allows methods to accept any type as a parameter or allows a method to return different types:

static str queryRange(anytype _from, anytype _to)
{
    return SysQuery::range(_from,_to);
}

You can declare variables by using anytype. However, the underlying data type of an anytype variable is set to match the first assignment, and you can’t change its type afterward, as shown here:

anytype a = 1;
print strfmt("%1 = %2", typeof(a), a); //Integer = 1
a = "text";
print strfmt("%1 = %2", typeof(a), a); //Integer = 0

The common type is the base type of all record types. Like the anytype type, record types are context-dependent types whose variables can be used as though they reference single records or as a record cursor that can iterate over a set of database records.

By using the common type, you can cast one record type to another (possibly incompatible) record type, as shown in this example:

//customer = vendor; //Compile error
common = customer;
vendor = common;     //Accepted

Tables in Microsoft Dynamics AX also support inheritance and polymorphism. This capability offers a type-safe method of sharing commonalities such as methods and fields between tables. It is possible to override table methods but not table fields. A base table can be marked as abstract or final through the table’s properties.

Table maps defined in the AOT are a type-safe method of capturing commonalities between record types across type hierarchies, and you should use them to prevent incompatible record assignments. A table map defines fields and methods that safely operate on one or more record types.

The compiler doesn’t validate method calls on the common type. For example, the compiler accepts the following method invocation, even though the method doesn’t exist:

common.nonExistingMethod();

For this reason, you should use reflection to confirm that the method on the common type exists before you invoke it, as shown in this example. For more information, see Chapter 20.

if (tableHasMethod(new DictTable(common.tableId), identifierStr(existingMethod)))
{
    common.existingMethod();
}

The built-in object type is a weak reference type whose variables reference objects that are instances of class or interface types in the Microsoft Dynamics AX class hierarchy.

The type system allows you to implicitly cast base type objects to derived type objects and to cast derived type objects to base type objects, as shown here:

baseClass = derivedClass;
derivedClass = baseClass;

The object type allows you to use the assignment operator and cast one class type to another, incompatible class type, as shown in the following code. The probable result of this action, however, is a run-time exception when your code encounters an object of an unexpected type.

Object myObject;
//myBinaryIO = myTextIO; //Compile error
myObject = myTextIO;
mybinaryIO = myObject;   //Accepted

Use the is and as operators instead of the assignment operator to prevent these incompatible type casts. The is operator determines if an instance is of a particular type, and the as operator casts an instance as a particular type, or null if they are not compatible. The is and as operators work on class and table types.

myTextIO = myObject as TextIO;
if (myBinaryIO is TextIO)
{
}

You can use the object type for late binding to methods, similar to the dynamic keyword in C#. Keep in mind that a run-time error will occur if the method invoked doesn’t exist.

myObject.lateBoundMethod();

You use the AOT to create extended data types that model concrete data values and data hierarchies. For example, the Name extended data type is a string, and the CustName and VendName extended data types extend the Name data type.

The X++ language supports extended data types but doesn’t offer type checking according to the hierarchy of extended data types. X++ treats any extended data type as its primitive type; therefore, code such as the following is allowed:

CustName customerName;
FileName fileName = customerName;

When used properly, extended data types improve the readability of X++ code. It’s easier to understand the intended use of a CustName data type than a string data type, even if both are used to declare string variables.

Extended data types are more than just type definitions that make X++ code more readable. On each extended data type, you can also specify how the system displays values of this type to users. Further, you can specify a reference to a table. The reference enables the form’s rendering engine to automatically build lookup forms for form controls by using the extended data type, even when the form controls are not bound to a data source. On string-based extended data types, you can specify the maximum string size of the type. The database layer uses the string size to define the underlying columns for fields that use the extended data type. Defining the string size in only one place makes it easy to change.

The X++ language has built-in support for querying and manipulating database data. The syntax for database statements is similar to Structured Query Language (SQL), and this section assumes that you’re familiar with SQL. The following code shows how a select statement is used to return only the first selected record from the MyTable database table and how the data in the record’s myField field is printed:

static void myJob(Args _args)
{
     MyTable myTable;
     select firstOnly * from myTable where myTable.myField1 == "value";
     print myTable.myField2;
     pause;
}

The “* from” part of the select statement in the example is optional. You can replace the asterisk (*) character with a comma-separated field list, such as myField2, myField3. You must define all fields, however, on the selection table model element, and only one selection table is allowed immediately after the from keyword. The where expression in the select statement can include any number of logical and relational operators. The firstOnly keyword is optional and can be replaced by one or more of the optional keywords. Table 4-4 describes all possible keywords. For more information about database-related keywords, see Chapter 17.

while select crosscompany:companies myTable { }

while select validTimeState(fromDate, toDate) myTable { }

The following code example demonstrates how to use a table index clause to suggest the index that a database server should use when querying tables. The Microsoft Dynamics AX runtime appends an order by clause and the index fields to the first select statement’s database query. Records are thus ordered by the index. The Microsoft Dynamics AX runtime can insert a query hint into the second select statement’s database query, if the hint is feasible to use.

static void myJob(Args _args)
{
    MyTable1 myTable1;
    MyTable2 myTable2;

    while select myTable1
        index myIndex1
    {
        print myTable1.myField2;
    }

    while select myTable2
        index hint myIndex2
    {
        print myTable2.myField2;
    }
    pause;
}

The following code example demonstrates how the results from a select query can be ordered and grouped. The first select statement specifies that the resulting records must be sorted in ascending order based on myField1 values and then in descending order based on myField2 values. The second select statement specifies that the resulting records must be grouped by myField1 values and then sorted in descending order.

static void myJob(Args _args)
{
    MyTable myTable;

    while select myTable
        order by Field1 asc, Field2 desc
    {
        print myTable.myField;
    }
    while select myTable
        group by Field1 desc
    {
        print myTable.Field1;
    }
    pause;
}

The following code demonstrates use of the avg and count aggregate functions in select statements. The first select statement averages the values in the myField column and assigns the result to the myField field. The second select statement counts the number of records the selection returns and assigns the result to the myField field.

static void myJob(Args _args)
{
     MyTable myTable;

     select avg(myField) from myTable;
     print myTable.myField;

     select count(myField) from myTable;
     print myTable.myField;
     pause;
}

Table 4-5 Describes the aggregate functions supported in X++ select statements.

The following code example demonstrates how tables are joined with join conditions. The first select statement joins two tables by using an equality join condition between fields in the tables. The second select statement joins three tables to illustrate how you can nest join conditions and use an exists operator as an existence test with a join condition. The second select statement also demonstrates how you can use a group by sort in join conditions. In fact, the join condition can comprise multiple nested join conditions because the syntax of the join condition is the same as the body of a select statement.

static void myJob(Args _args)
{
     MyTable1 myTable1;
     MyTable2 myTable2;


     MyTable3 myTable3;

     select myField from myTable1
        join myTable2
           where myTable1.myField1=myTable2.myField1;
     print myTable1.myField;

     select myField from myTable1
        join myTable2
          group by myTable2.myField1
          where myTable1.myField1=myTable2.myField1
             exists join myTable3
                where myTable1.myField1=myTable3.mField2;
     print myTable1.myField;
     pause;
}

Table 4-6 describes the exists operator and the other join operators that can be used in place of the exists operator in the preceding example.

The following example demonstrates use of the while select statement that increments the myTable variable’s record cursor on each loop:

static void myJob(Args _args)
{
     MyTable myTable;

     while select myTable
     {
         Print myTable.myField;
     }
}

You must use the ttsBegin, ttsCommit, and ttsAbort transaction statements to modify records in tables and to insert records into tables. The ttsBegin statement marks the beginning of a database transaction block; ttsBegin-ttsCommit transaction blocks can be nested. The ttsBegin statements increment the transaction level; the ttsCommit statements decrement the transaction level. The outermost block decrements the transaction level to zero and commits all database inserts and updates performed since the first ttsBegin statement to the database. The ttsAbort statement rolls back all database inserts, updates, and deletions performed since the ttsBegin statement. Table 4-7 provides examples of these transaction statements for single records and operations and for set-based (multiple-record) operations.

The last example in Table 4-7 demonstrates the method RowCount. Its purpose is to get the count of records that are affected by set-based operations; namely, insert_recordset, update_recordset, and delete_from.

By using RowCount, it is possible to save one round-trip to the database in certain application scenarios; for example, when implementing insert-or-update logic.

MyTable myTable;
Int64 numberOfRecordsAffected;

ttsBegin;
delete_from myTable
    where myTable.id == "001";
numberOfRecordsAffected = myTable.RowCount();
ttsCommit;

MyTable myTable;

ttsBegin;
myTable.id = "new id";
myTable.myField = "new value";
myTable.insert();
ttsCommit;

MyTable1 myTable1;
MyTable2 myTable2;
int64 numberOfRecordsAffected;

ttsBegin;
insert_recordset myTable2 ( myField1, myField2 )
    select myField1, myField2 from myTable1;
numberOfRecordsAffected = myTable.RowCount();
ttsCommit;

MyTable myTable;

ttsBegin;
select forUpdate myTable;
myTable.myField = "new value";
myTable.update();
ttsCommit;

boolean b = true;

ttsBegin;
if ( b == true )
    ttsCommit;
else
    ttsAbort;

MyTable myTable;
int64 numberOfRecordsAffected;

ttsBegin;
update_recordset myTable setting
    myField1 = "value1",
    myField2 = "value2"
    where myTable.id == "001";
numberOfRecordsAffected = myTable.RowCount();
ttsCommit;

It is a best practice to use the X++ exception handling framework instead of programmatically halting a transaction by using the ttsAbort statement. An exception (other than the update conflict and duplicate key exceptions) thrown inside a transaction block halts execution of the block, and all of the inserts and updates performed since the first ttsBegin statement are rolled back. Throwing an exception has the additional advantage of providing a way to recover object state and maintain the consistency of database transactions. Inside the catch block, you can use the retry statement to run the try block again. The following example demonstrates throwing an exception inside a database transaction block:

static void myJob(Args _args)
{
    MyTable myTable;
    boolean state = false;

    try
    {
        ttsBegin;

        update_recordset myTable setting
            myField = "value"
            where myTable.id == "001";
        if(state==false)
        {
            throw error("Error text");
        }
        ttsCommit;
    }
    catch(Exception::Error)
    {
        state = true;
        retry;
    }
}

The throw statement throws an exception that causes the database transaction to halt and roll back. Code execution can’t continue inside the scope of the transaction, so the runtime ignores try and catch statements when inside a transaction. This means that an exception thrown inside a transaction can be caught only outside the transaction, as shown here:

static void myJob(Args _args)
{
    try
    {
        ttsBegin;
        try
        {
            ...
            throw error("Error text");
        }
        catch  //Will never catch anything
        {
        }
        ttsCommit;
    }
    catch(Exception::Error)
    {
        print "Got it";
        pause;
    }
    catch
    {
        print "Unhandled Exception";
        pause;
    }
}

Although a throw statement takes the exception enumeration as a parameter, using the error method to throw errors is considered best practice. The try statement’s catch list can contain more than one catch block. The first catch block in the example catches error exceptions. The retry statement jumps to the first statement in the outer try block. The second catch block catches all exceptions not caught by catch blocks earlier in the try statement’s catch list. Table 4-8 describes the Microsoft Dynamics AX system Exception data type enumerations that can be used in try-catch statements.

UpdateConflict and DuplicateKeyException are the only data exceptions that a Microsoft Dynamics AX application can handle inside a transaction. Specifically, with DuplicateKeyException, the database transaction isn’t rolled back, and the application is given a chance to recover. DuplicateKeyException facilitates application scenarios (such as Master Planning) that perform batch processing and handles duplicate key exceptions without aborting the transaction in the midst of the resource-intensive processing operation.

The following example illustrates the usage of DuplicateKeyException:

static void DuplicateKeyExceptionExample(Args _args)
{
    MyTable myTable;

    ttsBegin;
    myTable.Name = "Microsoft Dynamics AX";
    myTable.insert();
    ttsCommit;

    ttsBegin;
    try
    {
        myTable.Name = "Microsoft Dynamics AX";
        myTable.insert();
    }
    catch(Exception::DuplicateKeyException)
    {
        info(strfmt("Transaction level: %1", appl.ttsLevel()));
        info(strfmt("%1 already exists.", myTable.Name));
        info(strfmt("Continuing insertion of other records"));
    }
    ttsCommit;
}

In the preceding example, the catch block handles the duplicate key exception. Notice that the transaction level is still 1, indicating that the transaction hasn’t aborted and the application can continue processing other records.

The X++ language includes statements that allow interoperability (interop) with .NET CLR assemblies and COM components. The Microsoft Dynamics AX runtime achieves this interoperability by providing Dynamics AX object wrappers around external objects and by dispatching method calls from the Microsoft Dynamics AX object to the wrapped object.

You can write X++ statements for CLR interoperability by using one of two methods: strong typing or weak typing. Strong typing is recommended because it is type safe and less error prone than weak typing, and it results in code that is easier to read. The MorphX X++ editor also provides IntelliSense as you type.

The examples in this section use the .NET System.Xml assembly, which is added as an AOT references node. (See Chapter 1, for a description of programming model elements.) The programs are somewhat verbose because the compiler doesn’t support method invocations on CLR return types and because CLR types must be identified by their fully qualified name. For example, the expression System.Xml.XmlDocument is the fully qualified type name for the .NET Framework XML document type.

The following example demonstrates strongly typed CLR interoperability with implicit type conversions from Microsoft Dynamics AX strings to CLR strings in the string assignment statements and shows how CLR exceptions are caught in X++:

static void myJob(Args _args)
{
   System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
   System.Xml.XmlElement rootElement;
   System.Xml.XmlElement headElement;
   System.Xml.XmlElement docElement;
   System.String xml;
   System.String docStr = 'Document';
   System.String headStr = 'Head';
   System.Exception ex;
   str errorMessage;

   try
   {
       rootElement = doc.CreateElement(docStr);
       doc.AppendChild(rootElement);
       headElement = doc.CreateElement(headStr);
       docElement = doc.get_DocumentElement();
       docElement.AppendChild(headElement);
       xml = doc.get_OuterXml();
       print ClrInterop::getAnyTypeForObject(xml);
       pause;
   }
   catch(Exception::CLRError)
   {
       ex = ClrInterop::getLastException();
       if( ex )
       {
           errorMessage = ex.get_Message();
           info( errorMessage );
       }
   }
}

The following example illustrates how static CLR methods are invoked by using the X++ static method accessor ::.

static void myJob(Args _args)
{
    System.Guid g = System.Guid::NewGuid();
}

The following example illustrates the support for CLR arrays:

static void myJob(Args _args)
{
    System.Int32 [] myArray = new System.Int32[100]();

    myArray.SetValue(1000, 0);
    print myArray.GetValue(0);
}

X++ supports passing parameters by reference to CLR methods. Changes that the called method makes to the parameter also change the caller variable’s value. When non-object type variables are passed by reference, they are wrapped temporarily in an object. This operation is often called boxing and is illustrated in the following example:

static void myJob(Args _args)
{
    int myVar = 5;

    MyNamespace.MyMath::Increment(byref myVar);

    print myVar;   // prints 6
}

The called method could be implemented in C# like this:

// Notice: This example is C# code
static public void Increment(ref int value)
{
    value++;
}

The second method of writing X++ statements for CLR uses weak typing. The following example shows CLR types that perform the same steps as in the first CLR interoperability example. In this case, however, all references are validated at run time, and all type conversions are explicit.

static void myJob(Args _args)
{
   ClrObject doc = new ClrObject('System.Xml.XmlDocument'),
   ClrObject docStr;

   ClrObject rootElement;
   ClrObject headElement;
   ClrObject docElement;
   ClrObject xml;

   docStr = ClrInterop::getObjectForAnyType('Document'),
   rootElement = doc.CreateElement(docStr);
   doc.AppendChild(rootElement);
   headElement = doc.CreateElement('Head'),
   docElement = doc.get_DocumentElement();
   docElement.AppendChild(headElement);
   xml = doc.get_OuterXml();
   print ClrInterop::getAnyTypeForObject(xml);
   pause;
}

The first statement in the preceding example demonstrates the use of a static method to convert X++ primitive types to CLR objects. The print statement shows the reverse, converting CLR value types to X++ primitive types. Table 4-9 lists the value type conversions that Microsoft Dynamics AX supports.

The preceding code example also demonstrates the X++ method syntax used to access CLR object properties, such as get_DocumentElement. The CLR supports several operators that are not supported in X++. Table 4-10 lists the supported CLR operators and the alternative method syntax.

The following features of CLR can’t be used with X++:

The following code example demonstrates COM interoperability with the XML document type in the Microsoft XML Core Services (MSXML) 6.0 COM component. The example assumes that you’ve installed MSXML. The MSXML document is first instantiated and wrapped in a Microsoft Dynamics AX COM object wrapper. A COM variant wrapper is created for a COM string. The direction of the variant is put into the COM component. The root element and head element variables are declared as COM objects. The example shows how to fill a string variant with an X++ string and then use the variant as an argument to a COM method, loadXml. The statement that creates the head element demonstrates how the Microsoft Dynamics AX runtime automatically converts Microsoft Dynamics AX primitive objects into COM variants.

static void Job2(Args _args)
{
    COM doc = new COM('Msxml2.DomDocument.6.0'),
    COMVariant rootXml =
               new COMVariant(COMVariantInOut::In,COMVariantType::VT_BSTR);
    COM rootElement;
    COM headElement;

    rootXml.bStr('<Root></Root>'),
    doc.loadXml(rootXml);
    rootElement = doc.documentElement();
    headElement = doc.createElement('Head'),
    rootElement.appendChild(headElement);
    print doc.xml();
    pause;
}

To set and get a class field from outside the class, you should implement a parameter method. The parameter method should have the same name as the field and be prefixed with parm. Parameter methods come in two flavors: get-only and get/set.

public class Employee
{
    EmployeeName name;

    public EmployeeName parmName(EmployeeName _name = name)
    {
        name = _name;
        return name;
    }
}

The purpose of the constructor encapsulation pattern is to enable Liskov’s class substitution principle. In other words, with constructor encapsulation, you can replace an existing class with a customized class without using the layering system. Just as in the layering system, this pattern enables changing the logic in a class without having to update any references to the class. Be careful to avoid overlayering because it often causes upgrade conflicts.

Classes that have a static construct method follow the constructor encapsulation pattern. The construct method should instantiate the class and immediately return the instance. The construct method must be static and shouldn’t take any parameters.

When parameters are required, you should implement the static new methods. These methods call the construct method to instantiate the class and then call the parameter methods to set the parameters. In this case, the construct method should be private:

public class Employee
{
    ...
    protected void new()
    {
    }

    protected static Employee construct()
    {
        return new Employee();
    }

    public static Employee newName(EmployeeName name)
    {
        Employee employee = Employee::construct();

        employee.parmName(name);
        return employee;
    }
}

To decouple a base class from derived classes, use the SysExtension framework. This framework enables the construction of an instance of a class based on its attributes. This pattern enables add-ons and customizations to add new subclasses without touching the base class or the factory method:

class BaseClass
{
    ...
    public static BaseClass newFromTableName(TableName _tableName)
    {
        SysTableAttribute attribute = new SysTableAttribute(_tableName);

        return SysExtensionAppClassFactory::getClassFromSysAttribute(
            classStr(BaseClass), attribute);
    }
}

[SysTableAttribute(tableStr(MyTable))]
class Subclass extends BaseClass
{
   ...
}

Many classes require the capability to serialize and deserialize themselves. Serialization is an operation that extracts an object’s state into value-type data; deserialization creates an instance from that data.

X++ classes that implement the Packable interface support serialization. The Packable interface contains two methods: pack and unpack. The pack method returns a container with the object’s state; the unpack method takes a container as a parameter and sets the object’s state accordingly. You should include a versioning number as the first entry in the container to make the code resilient to old packed data stored in the database when the implementation changes.

public class Employee implements SysPackable
{
    EmployeeName name;
    #define.currentVersion(1)
    #localmacro.CurrentList
        name
    #endmacro
    ...

    public container pack()
    {
        return [#currentVersion, #currentList];
    }

    public boolean unpack(container packedClass)
    {
        Version version = RunBase::getVersion(packedClass);

        switch (version)
        {
            case #CurrentVersion:
                [version, #CurrentList] = packedClass;
                break;
            default:   //The version number is unsupported
                return false;
        }
        return true;
    }
}

Each table must have the two static methods find and exists. They both take the primary keys of the table as parameters and return the matching record or a Boolean value, respectively. Besides the primary keys, the Find method also takes a Boolean parameter that specifies whether the record should be selected for update.

For the CustTable table, these methods have the following profiles:

static CustTable find(CustAccount _custAccount, boolean _forUpdate = false)
static boolean exist(CustAccount _custAccount)

The Table/Group/All pattern is used to model a polymorphic association to either a specific record in another table, a collection of records in another table, or all records in another table. For example, a record could be associated with a specific item, all items in an item group, or all items.

You implement the Table/Group/All pattern by creating two fields and two relations on the table. By convention, the name of the first field has the suffix Code; for example, ItemCode. This field is modeled using the base enum TableGroupAll. The name of the second field usually has the suffix Relation; for example, ItemRelation. This field is modeled by using the extended data type that is the primary key in the foreign tables. The two relations are of the type Fixed field relation. The first relation specifies that when the Code field equals 0 (TableGroupAll::Table), the Relation field equals the primary key in the foreign master data table. The second relation specifies that when the Code field equals 1 (TableGroupAll::Group), the Relation field equals the primary key in the foreign grouping table.

Figure 4-2 shows an example.

Figure 4-2. A polymorphic association.

The Generic Record Reference pattern is a variation of the Table/Group/All pattern. This pattern is used to model an association to a foreign table. It comes in three flavors: (a) an association to any record in a specific table, (b) an association to any record in a fixed set of specific tables, and (c) an association to any record in any table.

All three flavors of this pattern are implemented by creating a field that uses the RefRecId extended data type.

To model an association to any record in a specific table (flavor a), a relation is created from the RefRecId field to the RecId field of the foreign table, as illustrated in Figure 4-3.

Figure 4-3. An association to a specific table.

For flavors b and c, an additional field is required. This field is created by using the RefTableId extended data type. To model an association to any record in a fixed set of specific tables (flavor b), a relation is created for each foreign table from the RefTableId field to the TableId field of the foreign table, and from the RefRecId field to the RecId field of the foreign table, as shown in Figure 4-4.

Figure 4-4. An association to any record in a fixed set of tables.

To model an association to any record in any table (flavor c), a relation is created from the RefTableId field to the generic table Common TableId field and from the RefRecId field to Common RecId field, as shown in Figure 4-5.

Figure 4-5. An association to any record in any table.