Microsoft Dynamics NAV 7 Programming Cookbook - Second Edition

The TODAY keyword returns the date and the TIME keyword returns the time from the NAV Server system.

In the case of the older version of the NAV client—specifically the classic client—the date and time are taken from the client computer, which allows users to manipulate the system clock as per their personal requirement.

You can also retrieve the system date and time all at once using the CURRENTDATETIME function. The date and time can be extracted using the DT2DATE and DT2TIME functions respectively.

The change log is a base NAV module that allows you to track changes to specific fields in tables. The following code can be found in the 423, Change Log Management codeunit in the InsertLogEntry() method:

ChangeLogEntry.INIT;
ChangeLogEntry."Date and Time" := CURRENTDATETIME;
ChangeLogEntry.Time := DT2TIME(ChangeLogEntry."Date and Time");

Here, instead of using the WORKDATE function, we use the CURRENTDATETIME function and then extract the time using the DT2TIME function. The system designers can just do the following setup:

ChangeLogEntry.Date := TODAY;
ChangeLogEntry.Time := TIME;

The advantage of using CURRENTDATETIME over TODAY and TIME is minimal. CURRENTDATETIME makes one request to the system while the second method makes two. It is possible that another operation or thread on the client machine could take over between retrieving the date and time from the computer; however, this is very unlikely. The operations could also take place right before and after midnight, generating some very strange data. The requirements for your modification will determine which method is best suited, but generally CURRENTDATETIME is the correct method to use.

To understand WORKDATE, we have used two more keywords in this recipe. The work date is a date internal to the NAV system. This date is returned using the WORKDATE keyword. It can be changed at any time by the user. The next date is TODAY; it's a keyword to retrieve the present date that provides the date from the system. In the end, we used the TIME keyword, which provides current time information from the system clock.

The following code can be found in the 38, Purchase Header table, in the UpdateCurrencyFactor() method:

IF "Posting Date" <> 0D THEN
CurrencyDate := "Posting Date"
ELSE
CurrencyDate := WORKDATE;

Looking at this code snippet, we can see that if a user has not provided any specific posting date, the system will assign the value WORKDATE as the default value for the posting date.

The Date2DMY function is a basic feature of NAV. The first parameter is a date variable. This parameter can be retrieved from the system using TODAY or WORKDATE. Additionally, a hardcoded date such as 01312010D or a field from a table, such as Sales Header or Order Date can be used as a first parameter. The second parameter is an integer that tells the function which part of the date to return. This number can be 1, 2, or 3, and corresponds to the day, month, and year (DMY) respectively.

The following code can be found in the 485, Business Chart Buffer table in the UpdateCurrencyFactor() method of the GetNumberOfYears() function:

EXIT(DATE2DMY(ToDate,3) - DATE2DMY(FromDate,3));

This function has two parameters of type date and it returns the value in integer. The basic usage of this function is to calculate the duration between two dates in terms of years.

The CALCDATE() function takes in two parameters: a calculation formula and a starting date. The calculation formula is a string that tells the function how to calculate the new date. The second parameter tells the function which date it should start with. A new date is returned by this function, so the value must be assigned to a variable.

The following units can be used in the calculation formula:

These units may be different depending on what language version NAV is running under.

You have two options to place the number before the unit. It can either be a standard number ranging between 1 and 9 or the letter C, which stands for current. These units can be added and subtracted to determine a new date based on any starting date.

Calculation formulas can become very complex. The best way to fully understand them is to write your own formulas to see the results. Start out with basic formulas such as 1M + 2W - 1D and move on to more complex ones, such as –CY + 2Q - 1W.

The following code is part of the CalcNumberOfPeriods() function of the 485, Business Chart Buffer table:

"Period Length"::Week:
  NumberOfPeriods := (CALCDATE('<-CW>',ToDate)- CALCDATE('<CW>',FromDate)) DIV 7;

The preceding code snippet will return the difference between two dates in terms of weeks. <-CW> will provide a week start date of ToDate whereas <CW> will provide a week end day of FromDate. The difference between the calculated days will be divided by 7 to get the total number of weeks.

For more details on CALCDATE, visit the following URL:

http://msdn.microsoft.com/en-us/library/dd301368(v=nav.70).aspx

The FORMAT function takes one to three parameters. The first parameter is required and can be of almost any type: date, time, integer, decimal, and so on. This parameter is returned as a string.

The second parameter is the length of the string to be returned. The default, zero, means that the entire string will be returned, a positive number tells the function to return a string of exactly that length, and a negative number returns a string not larger than that length.

There are two options for the third, and final, parameter. One is a number, representing a predefined format you want to use for the string, and the other is a literal string. In the example, we used the actual format string. The text contained in the angular brackets (< >) will be parsed and replaced with the data in the first parameter.

The following code can be found on the OnValidate() trigger of the Starting Date field from the 50, Accounting Period table:

Name := FORMAT("Starting Date",0,Text000);

In the preceding code, Text000 is a text constant and carries the <Month Text> value. This code will return month of "Starting Date" in text format.

An array is a single variable that holds multiple values. The values are accessed using an integer index. The index is passed within square brackets ([ ]).

Open the 365, Format Address codeunit. Notice that the first function, FormatAddr, has a parameter that is an array. This is the basic function that all of the address formats use. It is rather long, so we will discuss only a few parts of it here.

This first section determines how the address should be presented based on the country of the user. Variables are initialized depending on which line of the address should carry certain information. These variables will be the indexes of our array.

CASE Country."Contact Address Format" OF
  Country."Contact Address Format"::First:
    BEGIN
      NameLineNo := 2;
      Name2LineNo := 3;
      ContLineNo := 1;
      AddrLineNo := 4;
      Addr2LineNo := 5;
      PostCodeCityLineNo := 6;
      CountyLineNo := 7;
      CountryLineNo := 8;
    END;

Then we will fill in the array values in the following manner:

AddrArray[NameLineNo] := Name;
AddrArray[Name2LineNo] := Name2;
AddrArray[AddrLineNo] := Addr;
AddrArray[Addr2LineNo] := Addr2;

Scroll down and take a look at all of the other functions. You'll see that they all take in an array as the first parameter. It is always a text array of length 90 with eight dimensions. These are the functions you will call when you want to format an address. To use this codeunit correctly, we will need to create an empty array with the specifications listed before and pass it to the correct function. Our array will be populated with the appropriately formatted address data.

An Option is a field or variable that stores one value from a selectable list. In a form, this list will appear as a dropdown from which the user can select a value. The list of options is stored as a comma-separated string in the OptionString property. If we query such stored values from a SQL database, we will receive an integer value representing each option. In our current example, the integer value has been mapped with options, where None = 0, Red = 1, Green = 2, and Blue = 3.

These values are accessed using the variable_name::option_name syntax. The first line of the example assigns one of the possible values (Green) to the variable. Then we use a CASE statement to determine which of the values were selected.

The Option fields are prevalent throughout the NAV system, but most commonly on documents. In NAV, many documents share the same table. For example, sales quotes, orders, invoices, and return orders are all based on the Sales Header table. In order to distinguish between the types, there is an Option field called Document Type. Design the 36, Sales Header table to see the available options for this field.

Now design the 80, Sales-Post codeunit. Examine the OnRun trigger. At the start of the function, you will see the following code:

  CASE "Document Type" OF
  "Document Type"::Order:
    Receive := FALSE;
  "Document Type"::Invoice:
    BEGIN
      Ship := TRUE;
      Invoice := TRUE;
      Receive := FALSE;
    END;
  "Document Type"::"Return Order":
    Ship := FALSE;
  "Document Type"::"Credit Memo":
    BEGIN
      Ship := FALSE;
      Invoice := TRUE;
      Receive := TRUE;
    END;
  END;

This is a common example of how options are used in NAV. You can scroll through the codeunit to find more examples.

The EVALUATE() function takes in two parameters. The first is a variable of the type that we want our value to be converted into. This could be date, time, Boolean, integer, or any other simple data type. This parameter is passed by reference, meaning that the result of the function is stored in that variable. There is no need to do a manual assignment to get a return value.

The second parameter is the string that you need to convert. This text is usually stored in a field or variable, but can also be hardcoded.

The EVALUATE() function is widely used in NAV C/AL code. The following code snippet is taken from the CheckCreditCardData() function of the 825, Do Payment Mgt codeunit:

EVALUATE (IntValue1,FORMAT(TODAY,0,'<Year>'));
EVALUATE (IntValue2,COPYSTR(DOPaymentCreditCard."Expiry Date",3,2));
IF IntValue1 > IntValue2 THEN
  ERROR (Text006, CreditCardNo, DOPaymentCreditCard.FIELDCAPTION ("No."));

Before completing a transaction, the credit card's validity period needs to be checked. The preceding code extracts the year from the current date provided by the TODAY function and the expiry date of the credit card. Both the values are evaluated using the relational operator. If the card has expired, the system will execute a predefined error message in text constant Text006.

A string is actually an array of characters. The same array syntax will be used to access the individual characters of the string.

We start with a FOR loop that begins at the first character, with index 1, and goes on until we reach the end of our string. This is determined using the STRLEN() function, which stands for string length. As the first index is 1, the last index will be N or the number of characters in the string.

Next, we access the character at that index using square brackets. If the character is a number, meaning we want to keep it because it is a numeric value, we add it to our resulting string.

The CheckIBAN function of the 79, Company Information table is a simple example of string manipulation to validate IBAN (International Bank Account Number). IBAN is internationally agreed on and adopted. It consists of up to 34 alphanumeric characters: the first two letters are the country code, then two check digits, and finally a country-specific Basic Bank Account Number. The same is validated by manipulating the input string using various functions. The following code gives you an example for the same:

IF IBANCode = '' THEN
  EXIT;
IBANCode := DELCHR(IBANCode);
Modulus97 := 97;
IF (STRLEN(IBANCode) <= 5) OR (STRLEN(IBANCode) > 34) THEN
  IBANError;
ConvertIBAN(IBANCode);
WHILE STRLEN(IBANCode) > 6 DO
  IBANCode := CalcModulus(COPYSTR(IBANCode,1,6),Modulus97) + COPYSTR(IBANCode,7);
EVALUATE(I,IBANCode);
IF (I MOD Modulus97) <> 1 THEN
  IBANError;

There are a few more functions used to validate the string; such as ConvertIBAN, CalcModulus, and ConvertLetter. These functions can give you a basic idea to write your own code.

For more complex examples, please follow the DecomposeRowID() function in the 6500, Item Tracking Management codeunit. The code evaluates the value stored in the Source RowId field of the 6508, Value Entry Relation table.