Microsoft Dynamics NAV 2009 Programming Cookbook: Build better business applications with NAV

The TODAY keyword returns the date from the system clock on the client computer. In Windows, the current system time is usually located at the bottom-right corner of the task bar. The same holds true for the system time which is returned by the TIME keyword.

The actual date and time returned depends on which version of the NAV client you are using. In the RoleTailored client, the date and time come from the NAV server. In the Classic client, the date and time come directly from the client computer and users will be able to manipulate the system clock to their advantage if they need to. An example could be a time clock application where a user can clock in, change the system time to eight hours later, clock out, and change it back to the original time.

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.

ChangeLogEntry.INIT;
system timeevents, loggingChangeLogEntry."Date and Time" := CURRENTDATETIME;
ChangeLogEntry.Time := DT2TIME(ChangeLogEntry."Date and Time");

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

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 going to Tools | Work Date.

It is important to understand the difference between the NAV work date and the computer system date. They should be used in specific circumstances. When performing general work in the system, you should almost always use the WORKDATE keyword. In cases where you need to log information and the exact date or time when an action occurred, you should use TODAY and TIME or CURRENTDATETIME.

IF "Document Type" IN ["Document Type"::Order,"Document Type"::Invoice,"Document Type"::Quote] THEN BEGIN
methodInitRecord()"Shipment Date" := WORKDATE;
"Order Date" := WORKDATE;
END;
IF "Document Type" = "Document Type"::"Return Order" THEN
"Order Date" := WORKDATE;
IF NOT ("Document Type" IN ["Document Type"::"Blanket Order","Document Type"::Quote]) AND ("Posting Date" = 0D) THEN
"Posting Date" := WORKDATE;
IF SalesSetup."Default Posting Date" = SalesSetup."Default Posting Date"::"No Date" THEN
"Posting Date" := 0D;
"Document Date" := WORKDATE;

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, a hard-coded date such as 01312010D, or a field from a table such as Sales Header or Order Date.

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.

NAV has a similar function called Date2DWY. It will return the week of the year instead of the month if 2 is passed as the second parameter.

StartingYear := DATE2DMY(StartingDate,3);
EndingYear := DATE2DMY(EndingDate,3);
LeapDays := 0;
IF (DATE2DMY(StartingDate,1) = 29) AND (DATE2DMY(StartingDate,2) = 2) AND (DATE2DMY(EndingDate,1) = 29) AND (DATE2DMY(EndingDate,2) = 2) THEN LeapDays := -1;
ActualYear := StartingYear;
WHILE ActualYear <= EndingYear DO BEGIN LeapDate := (DMY2DATE(28,2,ActualYear) + 1);
IF DATE2DMY(LeapDate,1) = 29 THEN BEGIN
IF (LeapDate >= StartingDate) AND (LeapDate <= EndingDate) THEN
LeapDays := LeapDays + 1;
END;
ActualYear := ActualYear + 1;
END;
EXIT((EndingDate - StartingDate) + 1 - LeapDays);

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. A 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 no 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 brackets (< >) will be parsed and replaced with the data in the first parameter.

There are many predefined formats for dates. The examples listed in the following table are taken from the C/SIDE Reference Guide in the Help menu of the NAV client. Search for "Format Property" to find more information.

AccountingPeriod.RESET;
IF FiscalYear THEN
AccountingPeriod.SETRANGE("New Fiscal Year",TRUE);
AccountingPeriod."Starting Date" := Date;
AccountingPeriod.FIND('=<>');
IF AccountingPeriod."Starting Date" > Date THEN
NextStep := NextStep - 1;
IF NextStep <> 0 THEN
IF AccountingPeriod.NEXT(NextStep) <> NextStep THEN BEGIN
IF NextStep < 0 THEN
Filter := '..' + FORMAT( AccountingPeriod."Starting Date" - 1)
ELSE
Filter := FORMAT(AccountingPeriod."Starting Date") + '..' + FORMAT(12319999D);
Name := '...';
EXIT;
END;
StartDate := AccountingPeriod."Starting Date";
IF FiscalYear THEN
Name := STRSUBSTNO(Text000,FORMAT(DATE2DMY(StartDate,3)))
ELSE
Name := AccountingPeriod.Name;
IF AccountingPeriod.NEXT <> 0 THEN
Filter := FORMAT(StartDate) + '..' + FORMAT(AccountingPeriod."Starting Date" - 1)
ELSE BEGIN
Filter := FORMAT(StartDate) + '..' + FORMAT(12319999D);
Name := Name + '...';
END;

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 ([]).

NAV provides several functions to work with arrays. ARRAYLEN returns the number of dimensions of the array. COPYARRAY will copy all of the values from one array into a new array variable. For a complete list of functions, search the C/SIDE Reference Guide under the Help menu for "Array Functions".

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

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

An Option is a field or variable that stores one value from a selectable list. In a form, this list will appear as a drop-down from which the user can select a value. The list of options is stored as a comma-separated string in the OptionString property.

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

You can also access possible options in other ways. In a database, an Option is stored as an integer. Each Option corresponds to a specific number, starting with the number 1. In this case None=1, Red=2, Green=3, and Blue=4. You could write this code to perform the safe actions:

ColorOption := ColorOption::"1";
option variableworkingCASE ColorOption OF
ColorOption::None: MESSAGE('No Color Selected');
ColorOption::Red: MESSAGE('Red');
ColorOption::Green: MESSAGE('Green');
ColorOption::Blue: MESSAGE('Blue');
END;

To reduce your development time, you can also use a shorthand notation to access the Option values. Again, the following code is exactly the same as that above:

ColorOption := ColorOption::R;
CASE ColorOption OF
ColorOption::None: MESSAGE('No Color Selected');
ColorOption::Red: MESSAGE('Red');
ColorOption::Green: MESSAGE('Green');
ColorOption::Blue: MESSAGE('Blue');
END;

When you close, save, and reopen the codeunit, the Option values will automatically be filled in for you. That is, both of these examples will look exactly like the first example once it has been saved and reopened. It is always best to write the code exactly as you want it to appear.

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;

The EVALUATE() function takes in two parameters. The first is a variable of the type that you want your 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 assign using the := syntax.

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

For a list of all of the functions related to text variables, search for "Text Data Type" in the C/SIDE Reference Guide under the Help menu.

EVALUATE() returns a boolean value when executed. If the conversion is successful, it returns TRUE or 1; otherwise, it returns FALSE or 0. If the function returns FALSE, an error will be generated. If you wish to display the standard system error, you can leave the code as it is, but if you want to handle the error yourself, you must make the following changes:

DateText := '01/01/2010';
IF NOT EVALUATE(DateValue, DateText) THEN
ERROR('Custom Error Message');
MESSAGE('Date: %1', DateValue);

GetIntegerPos(No,StartPos,EndPos);
stringnumber series, incrementingEVALUATE(DecimalNo,COPYSTR(No,StartPos,EndPos - StartPos + 1));
NewNo := FORMAT(DecimalNo + IncrementByNo,0,1);
ReplaceNoText(No,NewNo,0,StartPos,EndPos);

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 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 numeric, we add it to our resulting string.

NAV comes with plenty of built-in string manipulation functions to remove characters, return substrings, find characters within string, and many more. A search in the C/SIDE Reference Guide from the NAV client help menu for string functions will give you a complete list.

Parsing strings has several uses in NAV. Some easy-to-implement examples include checking/converting a phone number to a proper format based on country code, properly capitalizing names, and removing illegal characters.

FOR ArrayIndex := 1 TO 6 DO
Item Tracking ManagementStrArray[ArrayIndex] := '';
Len := STRLEN(IDtext);
Pos := 1;
ArrayIndex := 1;
WHILE NOT (Pos > Len) DO BEGIN
Char := COPYSTR(IDtext,Pos,1);
IF (Char = '"') THEN BEGIN
Write := FALSE;
Count += 1;
END ELSE BEGIN
IF Count = 0 THEN
Write := TRUE
ELSE BEGIN
IF Count MOD 2 = 1 THEN BEGIN
Next := (Char = ';');
Count -= 1;
END ELSE
IF NoWriteSinceLastNext AND (Char = ';') THEN BEGIN
Count -= 2;
Next := TRUE;
END;
Count /= 2;
WHILE Count > 0 DO BEGIN
StrArray[ArrayIndex] += '"';
Count -= 1;
END;
Write := NOT Next;
END;
NoWriteSinceLastNext := Next;
END;
IF Next THEN BEGIN
ArrayIndex += 1;
Next := FALSE;
END;
IF Write THEN
StrArray[ArrayIndex] += Char;
Pos += 1;
END;

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 using standard := syntax.

The following units can be used in the calculation formula:

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

You have two options for the number to place before the unit. This 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 like 1M+2W-1D and move on to more complex ones like — CY+2Q-1W.

IF (CALCDATE(ReminderLevel."Grace Period",ReminderDueDate) <
ReminderHeaderReq."Document Date") AND ((LineLevel <= ReminderTerms."Max. No. of Reminders") OR (ReminderTerms."Max. No. of Reminders" = 0))
THEN BEGIN