Constructing date values

Sometimes you have to construct at date at runtime with part of the date based on user input. Like when you have to summarize transactions for a given year.

Ax has a built-in function for this but all too often I see people resorting to convoluted string conversions to achieve the goal. Please don’t, it’s harder to read, more error prone and less efficient. Use mkDate() instead.

So instead of writing something like this:

static void Job1(Args _args)
{
    int givenYear = 2009; // Value acquired somewhere outside the method
 
    date fromDate, toDate;
    ;
 
    fromDate    = str2date("1/1/" + int2str(2009), 123);
    toDate      = str2date("1/1/" + int2str(2009), 123);
}

Write this:

static void Job1(Args _args)
{
    int givenYear = 2009;  // Value acquired somewhere outside the method
 
    date fromDate, toDate;
    ;
 
    fromDate    = mkDate(1, 1, givenYear);
    toDate      = mkDate(31, 12, givenYear);
}

To me, the most important advantage of mkDate() is clarity. Using string conversions distracts from the actual task of constructing a date. Additionally because all arguments to mkDate() are integers it’s easy to do input validation or build a whole bunch of date values in a loop, e.g. every first of every month.

Detecting default values

So I haven’t posted in a long time. I finally fixed some technical issues on the blog and upgraded to a recent version of WordPress. Let’s start with a quick tip to warm up 🙂

As you know X++ supports methods with default values. In Ax it’s possible to detect when such a default value was used at runtime with prmIsDefault(). To see this for yourself, create a class with a method like this:

void someMethod(int i = 1)
{
    ;
 
    if (prmIsDefault(i))
    {
        info('Default');
    }
    else
    {
        info('Value given');
    }
}

And call it from another method.

    o.someMethod();
    o.someMethod(1);

Even though the value is the same in both cases a different info message will be displayed.

Now you may be wondering how this can be useful. Some scenarios:

  • Avoiding expensive operations if the default value was used
  • Avoiding unwanted initializations
  • Dealing with customizations that require extra parameters in standard Ax classes

If you do a search for prmIsDefault() in the AOT you will see it’s used often. Classes with the Ax prefix are the most obvious example. Because getters and setters are rolled into a single method it’s necessary to know if the method was used as a getter or a setter and keep track of modified fields.

Changing properties of AOT objects in code

A while ago I wrote about reflection in Dynamics Ax. In the article I mentioned that it was also possible to modify the AOT and that I’d give some examples. Well, I kind of forgot. Sorry about that. Todd Hensley was kind enough to remind me of that promise and presented an interesting example problem.

I have a list of tables where I want to set the ClusterIndex to be the same as the PrimaryIndex.

I’ve been able to loop through an array of the table names, look them up using DictTable, and examine the PrimaryIndex and ClusterIndex values.

But I can’t figure out how I would say:
myTable.clusterIndex = myTable.primaryIndex;

The properties all appear to be read-only.

Any ideas?

Thank you for the question and, yes, I do have an idea.

Enter the TreeNode

The key to solving this is knowing that there is more than one way to do reflection. As Todd found out, the Dictionary API is read-only. But the TreeNode API is not.

TreeNode is exactly what its name says: a node in a tree.
I can hear you thinking: “Nodes? Tree? What are you talking about?”

I’m talking about the Application Object Tree. The AOT has a bunch of nodes and a TreeNode object can represent any one of those nodes, like Forms, a class method or a table.

Whenever you’re using the AOT, clicking on an object and setting properties you’re using TreeNodes. And the best part is you can do it in code too!

Getting the node

Enough talk. Time to show the code. First you need to get hold of a node. Let’s use CustTable as an example.

    TreeNode    node = TreeNode::findNode(@'Data dictionaryTablesCustTable');
    ;
    info(node.treeNodePath());
    info(node.AOTname());

As you can see, you need to enter the path similar to the way you open the nodes AOT. If findNode() fails it will return null.

Once you have the node the fun starts. In this case I’m just dumping something in the infolog to show you it works.

Properties

Now let’s do what we really want. We’re going to set the primary index as the cluster index.

    TreeNode    node = TreeNode::findNode(@'Data dictionaryTablesCustTable');
 
    str indexName;
 
    #Properties
    ;
 
    indexName = node.AOTgetProperty(#PropertyPrimaryIndex);
    node.AOTsetProperty(#PropertyClusterIndex, indexName);
    node.AOTsave();
 
    node.treeNodeRelease();
    node = null;

There are a couple of things to explain here. First of all the macro #Properties contains the names of all properties you can read and write. These are the same as what you get in the property window. Use the macro instead of literal strings, it’s safer and doesn’t violate best practices.

Next you can see there is a set of methods to get and set properties. After modifying anything you need to save the changes, just like you would when changing an AOT object in the property window. TreeNode works just like doing it manually.

Finally you need to release the memory held by the TreeNode. The garbage collector cannot clean up TreeNode objects by itself. It needs a little help from you by calling treeNodeRelease() when you’re done. In this example nothing bad would happen if you don’t. However, if you run this in a loop a few thousand times Ax will run out of memory. Not something you really want.

Fitting it in with DictTable

Todd already did a lot of work with DictTable to find the tables he needs to change. And now I tell him DictTable won’t cut it. Not really helping.

Not all is lost. DictTable has a method to get a TreeNode object. How convenient. If we change the above example to start with a DictTable object we end up with this:

    SysDictTable    dictTable;
    TreeNode        node;
 
    str indexName;
 
    #Properties
    ;
 
    dictTable = SysDictTable::newTableId(tableNum(CustTable));
 
    node = dictTable.treeNode();
 
    indexName = node.AOTgetProperty(#PropertyPrimaryIndex);
    node.AOTsetProperty(#PropertyClusterIndex, indexName);
    node.AOTsave();
 
    node.treeNodeRelease();
    node = null;

This can be adapted to fit in a loop over several tables and Todd’s problem is solved.

You can do a lot more fun stuff with the TreeNode API. I’ll cover that in another installment. I won’t forget this time. I promise 🙂

Also, if you have questions or ideas for articles don’t hesitate to let me know.

A quick fix for unbalanced TTS

During development you may encounter one of these.
Unbalanced TTS error

This usually leaves your Ax session in an unusable state that you can’t close properly. However, there’s no need to get out the big guns and kill the process with the Task Manager.

Instead, if possible, open the AOT and run this job:

static void resetTTS(Args _args)
{
    while (appl.ttsLevel() > 0)
        ttsAbort;
}

It simply rolls back any pending transactions until the TTS level is back at zero. Now, this doesn’t fix the cause of the problem but it makes life easier trying to iron out the bug.

Dealing with containers

The X++ container is a powerful and somewhat odd datatype. It’s like an array but supports different data types in the same instance and it can grow infinitely large. Also containers don’t have methods like real objects; you need to call special functions and pass your container to them.

Many data structures in X++ are serialized (packed) into containers before they’re sent across the network or stored in the database. The entire SysLastValue framework runs on it.

Unfortunately this kind of flexibility is often abused. It’s very easy to abuse containers and I see it happen too often. In this article I’ll go over some good practices for containers. I won’t go into basics of containers. You can find basic documentation on MSDN (methods starting with con).

Appending to containers

Most of the time you want to append something to a container. Typically I come across code like this:

for (i=1; i<=maxNum; i++)
{
    con = conIns(con, i, theValue);
}

Don’t do that. The conIns() function is slow because it copies the original container to a new one before returning.

The above should be rewritten as:

for (i=1; i<=maxNum; i++)
{
    con += theValue;
}

It’s a lot faster and easier to read as well.

Only use conIns() if there’s no other option, i.e. for inserting values not at the end. Even adding elements to the front of the container is slow because the existing container is still copied. If at all possible write your code in such a way that you only append elements using +=. This is the fastest way to do it as it modifies the original container in place. And it’s easier to read as well.

Initialising

Whenever you’re going to insert a fixed set of variables into the container you can add them all at once. A typical example when writing something to a file.

while(someCondition)
{
    con = conNull();
    con += 1;
    con += someValue;
    con += otherValue;
    con += "X";
    outFile.write(con);
}

This is works but there’s a better way. You can assign a bunch of values to the container in a single line. Try this instead:

while(someCondition)
{
     con = [1, someValue, otherValue, "X"];
     outFile.write(con);
}

This is a contrived example and often the complexity filling the container can be pushed into a separate method. Usually hiding details like that increases readability of the code. It isn’t always possible to do it like this but simplify your code whenever possible.

Extracting values

The above trick works the other way around too. You can write this:

a = conPeek(con, 1);
b = conPeek(con, 2);
c = conPeek(con, 3);

This can be done in a simpler way:

[a, b, c] = con;

Bonus points if you can explain this:

[a, b] = [b, a];

Passed by reference

Containers are a primitive data type in Ax, so they’re passed by value. That means containers will be copied when passed as a function argument. Keep that in mind when you’re dealing with containers that can become large. For small containers the performance hit is negligible but at some point you’re going to notice it.

Don’t mimic other data structures with containers

Too often I see a mess of containers that could be replaced by a much more appropriate data structure.

Although it’s very easy and tempting to use containers for everything, again, it’s not a good idea. Other developers may have a hard time understanding these ad hoc data structures. Even understanding your own code can be a problem if you haven’t worked on it for a while.

There are alternatives to containers. Take a look at the Foundation Classes. They’re somewhat like the .NET collections. You can use a List, Map, Set, Array and Struct. They can be packed into containers when necessary.

If all variables are of the same type, consider using a List (ordered) or Set (unordered). If you need to track related values use Maps (key/value pairs) or Structs (supports different complex types). Please don’t use nested containers or keep values together in several containers at the same index. It’s hard to read and easy to break.

X++ method call performance

Microsoft’s recommendations for performance optimizations are interesting:

  • Calls between tiers (client/server) are slow.
  • Method calls are expensive. Try to reduce the number of calls. For example, don’t call the same method several times if you can store a value from the method and instead use that value.

These statements are probably true but as with all good advice it is important to know the context in which it makes sense. How slow is slow and how expensive is expensive? And should you worry about it? Let’s find out.

Test cases

In X++ there are different kinds of methods and different ways to call them. There are some interesting cases I can think of right away.

  • Static versus instance methods
  • Staying on the same tier versus calling methods across tiers
  • Calling a method on an object of a supertype (Object) instead of the exact subtype
  • Calling a method through reflection (SysDict* classes)

Test setup

Methods calls may be slow, but they’re certainly not slow enough to accurately measure the time of a single call. Repeating the exact same call a large number of times should average out any measurement errors.

The timing code is basically this:

        timer.start(1);
        for (i=1; i&lt;=maxLoop; ++i)
        {
            // method call here
        }
        timer.stop(1);

Note that the loop overhead will be included in the measurement as well. This is not really a problem because we will use the same setup for all test cases, replacing the loop body. We’re not interested in exactly how long it takes to call a method, only in performance of the cases relative to each other. Absolute execution times depend on the configuration of the system while relative differences don’t change much between different setups. It’s a bit crude but I think it will suffice.

MaxLoop is set at 100,000 and all cases are executed sequentially. To further minimize the effect of other random system activity, all tests are repeated 20 times. This means every method call is executed 2 million times. This should give a pretty good indication of relative performance.

Overhead, e.g. for constructing object, is placed outside the timer statements. All methods are empty, take no input and return nothing. That means there’s nothing but the call going on. I’m assuming that the compiler will not perform any optimizations, like inlining functions. If it does, we should see weird results.

If you want to try this yourself get the full source here (4.0 SP2).

The results

After running the test I got these results.

#CaseAvg. time (ms) for 100,000 calls
1No method (empty loop)481
2Instance method client2,347
3Instance method server14,809
4Static method client2,298
5Static method server14,825
6SysDictClass3,095
7Call on Object on client2,367

As expected they confirm the Best Practice recommendations. Calling a method on the same tier in a loop is about 3 times slower than an empty loop. It doesn’t really matter if it’s an instance or static method, or if the variable is of the generic Object type. The values are too close together to be statistically significant.

SysDictClass is a bit slower. That makes sense because it uses 2 methods: callObject() on SysDictClass and the method on the object itself. Surprisingly it is a lot faster than twice the value of calling an object method on the same tier. It is closer to a combination of no method and a method call on the same tier. If I had to guess I would say it is because callObject() is a method in the kernel, written in C/C++ instead of X++. Maybe there is less overhead in dealing with kernel functions. Too bad we can’t include an empty kernel method in the test to verify this.

Finally, this proves methods calls across tiers are slow. Extremely slow compared to anything else. In this setup crossing a tier is about 6 to 7 times slower than staying on the same tier. Keep in mind that these methods do not take any input and return nothing. Also, the AOS and client are on the same machine. In real code with parameters, return types and network latency it will be worse.

Conclusion

The optimization guidelines are correct. Now should you worry about it and avoid methods? Generally not. Breaking up code in methods improves readability of the code. Adding too many temporary variables to avoid calling the same method again can become annoying too. Usually a programmer’s time is more important (and more expensive) than execution time. It’s not worth it to optimize everything.

If you stay on the same tier you can do a lot of method calls per second. Unlike this test setup, real methods have code that takes time to execute as well The time spent performing the actual method call will be insignificant in most situations. Readability and clean design trumps performance. If X++ would support some function inlining we could have the best of both worlds with minimal effort.

When crossing from client to server or vice versa, things are more complicated. As the results show this causes a significant performance hit. From the start your code should be designed to minimize traffic between tiers. A single call won’t hurt but often bad code contains a lot of subsequent calls to objects that live on the other tier, like when constructing an object and setting it up with accessor methods. In these cases it’s better to use containers and provide methods to pass all data in a single call. Simple client/server optimizations can make a huge difference. Improvements in this area are something users could actually notice themselves.

Installing Dynamics Ax 4.0 SP1 and SP2 side by side

When a new service pack is released I like to install it next to all the other versions I have on my machine. This makes it easy to test new service packs and compare it to previous versions. In 3.0 this was quite easy to do because you could choose which directory you wanted to upgrade. The new installation procedure and requirements for version 4.0 makes this a lot harder. Fortunately it’s not entirely impossible.

The installer doesn’t give you much choice about what to upgrade, so you’ll have to copy files and modify registry keys manually. Below are the steps to make it work on my machine. Beware that this setup is not something you should do on a production environment because it’s not supported by MBS. Don’t try this if you don’t feel comfortable editing the Windows registry.

I’m starting with SP1 because I don’t have to support environments without a service pack. This procedure probably works for a regular 4.0 as well. Everything is installed on a single machine, starting from scratch.

  1. Install SP1 database, client, server, and application. I used Client, Application, and Server. Pick a good name for the AOS (I used DAX_401). Don’t start it yet.
  2. Copy the three directories. I used Client SP1, Application SP1, and Server SP1. You should have 6 directories now.
  3. Modify permissions on the SP1 directories to give the account the AOS uses all permissions except for Full Access and Special Permissions. The default account is Network Service.
  4. Delete the DAX_401 AOS files and install a second SP1 AOS in the Server directory. You need to do this to get the necessary registry entries. I named the instance DAX_402.
  5. Install a second SP1 database or copy the one created during the first installation.
  6. Install SP2. This will upgrade the everything created in step 1.
  7. With the config utilities, create server and client configurations. At this point the SP2 part should work.
  8. Open Regedit and search for the key HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesAOS$01. This is the service information SP1 AOS. Change the ImagePath key to point to the executable in Server SP1. In the Management Console for Windows services the path to the executable for AOS01 should point to the SP1 directory.
  9. In Regedit, go to HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesDynamics Server4.01. Below this are the server configurations. Several keys have a path that point to the SP2 directories for application and server. Change everything to the SP1 directory.
  10. The SP1 AOS should now work.
  11. Optionally, create shortcuts to the SP1 and SP2 clients. The SP2 client is backward compatible. It can connect to an SP1 AOS but it the SP2 AOS won’t accept SP1 clients.

I don’t know if it’s possible to have 2 versions of the Business connector. I upgraded mine to SP2. Like the client it will probably be able to connect to an SP1 application.

If you’re not interested in using the SP1 binaries you can probably copy an SP1 application to the SP2 Appl directory and configure the AOS to use the old application. I haven’t tested it yet so I don’t know if it actually works.

The lone semicolon

Something that confuses and annoys people when they’re learning X++, is the semicolon after variable declarations.

As you know all local variables have to be declared at the start of the function and statements are placed after that. Then comes the important part: don’t forget to always put a semicolon on a single line before the first statement.

If you don’t, your code might not compile. Sometimes it will, sometimes it won’t. And code that works now can be broken later, without touching it. A semicolon is not always required, but instead of worrying if it’s required, it’s easier to make a habit of just writing it. Even if you don’t have any local variables. Unfortunately even standard X++ code doesn’t always have this.

The reason you need that extra semicolon is because the compiler can’t always see where the variable declarations end. If you don’t help a little, it will make a guess. And it’s not very good at guessing.

While the compiler is analyzing the code it checks if the first word on a line matches the name of a type (AOT object). If it’s a type name the compiler treats the line as a variable declaration. In this case a variable name should be next.

If the first word is not a variable the compiler considers the line to be the start of a statement. In some cases it treats statements as class declarations and that causes compiler errors.

Let me explain this with some examples from the standard application (4.0 SP1). This is a method from the BOMSearch class.

server static BOMSearch newProdTable(ProdTable prodTable)
{
    BOMSearch BOMSearch = new BOMSearch(
                            prodTable.BOMId,
                            prodTable.BOMDate,
                            prodTable.ItemId,
                            prodTable.inventDim().ConfigId,
                            false);
    ;
    BOMSearch.init();
 
    return BOMSearch;
}

If you remove the semicolon from line 9 you will get an error on the next line. The first line is never a problem for the compiler: a variable BOMSearch of type BOMSearch is created.

Next the compiler sees the word BOMSearch and figures, ‘I know that, it’s a class name. So this must be a variable declaration. But what’s with the .init()? That’s not allowed here.’

And there’s the compilation error.

This method from CustTable is an example of bad standard code.

void initFromCustGroup(CustGroup _custGroup)
{
    this.PaymTermId = _custGroup.PaymTermId;
    this.PaymSched  = PaymTerm::find(this.PaymTermId).PaymSched;
}

‘What do you mean, bad code? This is standard Axapta. It works just fine!’.
Yes it does… for now. Create an EDT named this and compile again. It’s broken for the same reason as the previous example.

To avoid headaches, repeat after me: always put a semicolon on a single line before the first statement.

Too bad the compiler isn’t smarter. A Best Practice check would be nice too.

The X++ way to getters and setters

This one is for all those who are new to X++ development. When learning OO programming we’re told that encapsulation is important. Data members (variables) should be hidden and any access should go through methods. Then the typical combination of getters and setters is introduced. You’re supposed to write methods for each thing you want to expose: getSomething() and setSomething(someValue).

In X++ we do this too… with a twist. For starters, all data members of a class (variables in the ClassDeclaration) are protected. So only the class itself and subclasses can access them directly. This means X++ forces you to write methods to access data from outside the class hierarchy. Unlike other mainstream languages such as Java, C# or C++ there is nothing you can do about it. Keywords such as private, protected or public are simply not allowed in a ClassDeclaration.

And there’s more, there are no getters and setters either. It’s not that writing getters and setters is impossible, it’s just not the way things are done. Everything is rolled into a single method, with a name starting with parm. Sometimes they’re called property methods or parm-methods.

A typical example looks like this:

CustAccount parmCustAccount(CustAccount _custAccount = custAccount)
{
    ;
    custAccount = _custAccount;
    return custAccount;
}

It may look confusing but it is actually quite simple. If you use it as a setter, the new value is passed to the object’s data member (custAccount) and the return value is never used. When used as a getter, _custAccount gets the current data member as a default value and this value is eventually returned.

The important thing is that you can use it just like getters and setters you might know. Instead of getCustAccount(), use parmCustAccount(). Instead of setCustAccount(‘1234’), use parmCustAccount(‘1234’).

I recommend you do it this way for any new classes you create. This is something I need to point out in code reviews with new X++ developers all the time. You could argue that the function does two things and in theory it should only do one thing. That’s true. However, this is a minor offense that will not make or break your application. Adhering to the existing code style is important too. Being consistent improves overall readability and usability of the code. When in Rome do as the Romans do.

A quick tip for enums

When you’re creating a new base enum consider using multiples of 10 for values. This makes extending enums a lot easier, especially if it indicates some kind of status. Those of you who once programmed in BASIC, or any other language with line numbers, can probably guess where I’m going with this. My apologies for any painful flashbacks this may trigger.

Suppose you’re creating an interface with another system. It turns out you need a new enum, MessageStatus. Values are assigned automatically, so Received = 0, Started = 1, Processed = 2, and Archived = 3.

Of course, at some point you need to do different things depending on the status. Let’s say you have written this function.

boolean isOpen(MessageStatus _status)
{
    return _status &lt; MessageStatus::Processed;
}

This is a simple way to indicate at which point the message is no longer considered open. Standard Dynamics Ax contains similar examples, e.g. with the inventory status (StatusIssue and StatusReceipt).

Your message handling system goes live and works perfectly. Users are happy, birds are singing, the sun is shining.

After a while users decide they need a verification step before moving to Started. You extend the enum and end up with MessageStatus::Verified = 4. And now things are broken. Verified messages aren’t handled correctly.

You need to check all places where the status is used. You run across the isOpen() method and change it.

boolean isOpen(MessageStatus _status)
{
    return _status &lt; MessageStatus::Processed || _status == MessageStatus::Verified;
}

Not so readable anymore but it works. For now. Things can get out of hand quickly if more than 1 status is added.

This could have been avoided from the start if the enum elements were assigned specific values.

Received 10
Started 20
Processed 30
Archived 40

Adding a new step somewhere in the middle is easy. Create Verified with value 15 and isOpen() doesn’t need to be modified.

Now you may think this is a great idea (It is. Thank you.) but don’t go changing all your enums now. Changing values means you also need to modify all fields that use it, as they still contain the old numbers. This is the reason you need to think about enum values in advance. Once a system is deployed, it’s usually better to leave these things as they are to avoid even more trouble.

In practice starting with multiples of 10 is enough to deal with any reasonable modifications. I have yet to run into a situation where a gap of 9 values isn’t enough. Unfortunately standard Dynamics Ax enums have continuous values starting at 0. If you need to insert something in between you still have to check all code that covers a range of enum elements.