Professional Documents
Culture Documents
Introduction
Sometimes the exact code must be run from different locations. Other times similar code with different variable values must be run from different locations. Writing these codes in a function when they need to be called from different locations not only saves developers' time in development, but also eases developers' tasks in managing and debugging the code. C/SIDE provides many built-in functions in C/AL. These functions can be used in most parts of the application without defining them. They are predefined to achieve certain tasks, such as perform string operations, retrieve a system date, and so on. Understanding C/AL built-in functions and creating custom functions completes developers' skills to build custom application in C/SIDE.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-1
Functions
When the function name, which is known as the identifier, is used, the current program is suspended and the trigger code for the specified function is executed. Using the identifier in this manner "calls" the function. When the trigger code in the called function is completed, the function "returns" to where it is called from. How the function is called determines what happens when it returns. A function can be used as an expression. For example, the following code uses a function named CalculatePrice as an expression:
TotalCost := Quantity * CalculatePrice;
The CalculatePrice function must return a value that is used in evaluating the expression. This return value is then multiplied by the Quantity variable and that result is assigned to the TotalCost variable. A function can also be called by using a function call statement. This statement only calls the function and does not return any value. The following is an example of calling a function named RunFunction:
IF Quantity > 5 THEN RunFunction;
Parameter
A parameter is one or more variables or expressions sent to the function through the function call. The parameter provides information to the function, and the function can modify that information. If a function has parameters, the function identifier has a set of parentheses that follows it. Within these parentheses are one or more parameters. If there is more than one parameter, the parameters are separated by commas.
8-2
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
Pass by Reference
When a parameter is passed to the function and the function modifies that parameter, the parameter is said to be passed by reference. The parameter knows the variable's location in the computer memory, and it passes the computer memory location to the new function. Any changes that the function makes to this kind of parameter are permanent and affect variables in the calling trigger. If a parameter is passed by value, any expression can be used for that parameter. However, if a parameter is passed by reference, a variable must be used for that parameter so that its value can be changed. A variable has a location in memory, whereas an expression or a constant does not.
Built-in Function
A built-in function is a function that is provided within C/SIDE. Its trigger code cannot be viewed, because it is built into C/SIDE. The following table describes some built-in functions: Function Name MESSAGE MAXSTRLEN COPYSTR CLEAR ARRAYLEN Description Displays a message on the screen. Returns the defined length of a string variable. Returns a part of a string. Clears the passed in variable. Returns the number of elements in an array.
Functions such as MESSAGE and CLEAR, have no return value. They can only be called by using a function call statement. Functions such as COPYSTR and MAXSTRLEN return a value, and they can be used in an expression. The CLEAR function changes the passed in parameter. It is an example of pass by reference, whereas the other functions are examples of pass by value.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-3
8-4
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
The syntax of the MESSAGE function is displayed at the bottom of the frame, above the command buttons in the C/AL Symbol Menu window. The MESSAGE function has the following syntax:
MESSAGE(String [, Value1] )
The syntax tells the following: There is no return value. There is one mandatory parameter (String.) There are multiple optional parameters (the square brackets indicate an optional parameter and the ellipsis indicates multiples.)
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-5
The syntax of the ERROR function is displayed. It has the following syntax:
ERROR(String [, Value1] )
The syntax of the ERROR function is identical to that of the MESSAGE function, except for the function identifier and the functionality. When an ERROR function is called in a function call statement, the processing stops with an error condition and the message is displayed in a similar manner as the MESSAGE function.
8-6
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
The syntax of the DATE2DMY function is displayed. It has the following syntax:
Number := DATE2DMY(Date, What)
The syntax tells the following: The function has a return value, that is a number, indicated by the 'Number :=' right before the function identifier. The first parameter (Date) is an expression of type Date. The second parameter (What) is described in more detail in the online Help.
3. Press F1. The online Help opens and displays information for the DATE2DMY function. A complete description of what the function does and what it returns is shown. The What parameter is an integer expression that resolves to one of three values: If it is a 1, this function returns the day of the month. If it is a 2, this function returns the month (from 1 to 12). If it is a 3, this function returns the year (the full 4 digits).
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-7
4. Compile, save, and close the codeunit. The first line in the code uses the TODAY function. This function has no parameters. It always returns the current date from the client's computer operating system, also known as the system date. 5. Run the codeunit and examine the result.
8-8
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
1. What is the value of Comma after the statement labeled Q1 is executed the first time? 2. Is the value of Comma ever less than zero in this code (refer to the statement labeled Q2)? 3. What is the value of UserInput after the statement labeled Q3 is executed the first time? 4. What is the value of Count when the comment line is reached the first time? 5. Suppose that UserInput is redefined so that it is a Text of length 60. Now, what is its value when the MESSAGE function after the comment line is reached?
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-9
Although better, this is not the result desired. Why did it not work? 7. Run this code in a codeunit. Do not forget to define the variables. Make the simplest change possible to address the problem uncovered in question seven. Write down the changes.
GET
The GET function retrieves one record, based on the value of the primary key. For example, if the No. field is the primary key of the Customer table, the GET function can be used as follows:
GET(Customer,'4711');
The result is that the record of customer no. 4711 is retrieved. The GET function produces a run-time error if it fails, and the return value is not inspected by the code. The code can look as follows:
IF GET(Customer,'4711') THEN .... // do some processing ELSE .... // do some error processing
8-10
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
FIND
The differences between the GET function and the FIND function are as follows: The FIND function respects (and is limited by) the current setting of filters. The FIND function can be instructed to look for records where the key value is equal to, larger than, or smaller than the search string. The FIND function can find the first or the last record, given the sorting order defined by the current key.
These features can be used in various ways. When developing applications under a relational database management system, developers frequently have one-tomany relationships between tables. An example is the relations between the Item table that records items, and the Sales Line table that records the detail lines from Sales Orders. A record in the Sales Line table can only be related to one item. But each item can be related to any number of sales line records. An item record in the Item table must not be deleted while there are still open Sales Orders that include the item. The following code sample can be put in the OnDelete trigger of the Item table, and shows how to check for this condition:
SalesOrderLine.SETCURRENTKEY("Document Type",Type,"No."); SalesOrderLine.SETRANGE("Document Type",SalesOrderLine."Document Type"::Order); SalesOrderLine.SETRANGE(Type,SalesOrderLine.Type::Item); SalesOrderLine.SETRANGE("No.","No."); IF SalesOrderLine.FIND('-') THEN ERROR('You cannot delete because there are one or more outstanding sales orders that include this item.');
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-11
The FINDSET function is used to locate the first record of the table. Afterward, the NEXT function is used to step through every record, until there are no more (then, NEXT returns zero.)
SETCURRENTKEY
The SETCURRENTKEY function is used to select a key for a record. This sets the sorting order used for the associated table. It has the following syntax:
[Ok :=] Record.SETCURRENTKEY(Field1, [Field2],...)
Some characteristics of the SETCURRENTKEY function are as follows: Inactive fields are ignored. When searching for a key, C/SIDE selects the first occurrence of the specified field(s).
For example, even if a developer specifies only one field as a parameter when calling SETCURRENTKEY, the key that is actually selected may consist of more fields.
8-12
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
SETRANGE
The SETRANGE function is used to set a delimitation on a field. It sets a simple filter. It has the following syntax:
Record.SETRANGE(Field [,From-Value] [,To-Value]);
The following code sample shows how to use the SETRANGE function:
Customer.SETRANGE("No.",'10000','90000');
This limits the Customer table by selecting only those records where the No. field has a value between 10000 and 90000. The SETRANGE function removes previous filters. If it is used without the From-Value or To-Value parameters, the function can be used to remove any filters that might already be set. If only the From-Value parameter is used, the To-Value parameter is set to the same value as the From-Value parameter.
SETFILTER
The SETFILTER function sets a filter in a more general way than SETRANGE. It has the following syntax:
Record.SETFILTER(Field, String [, Value], ...];
The Field parameter is the name of the field to set a delimitation on. The String parameter is a filter expression that can contain operators and placeholders such as %1, %2 and so on to indicate locations where the system inserts values given as the Value parameters. The following code sample shows how to use the SETFILTER function:
Customer.SETFILTER("No.", '>10000 & <> 20000');
This code selects records where the No. is larger than 10000 and not equal to 20000. The following code sample performs the same thing as the previous one, if the variable Value1 is assigned 10000 and Value2 is assigned 20000:
Customer.SETFILTER("No.",'>%1&<>%2',Value1, Value2);
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-13
The GETRANGEMIN function causes a run-time error if the filter currently in effect is not a range. For example, if a filter is set as follows:
Customer.SETFILTER("No.",'10000|20000|30000');
GETRANGEMAX
The GETRANGEMAX function works like the GETRANGEMIN function, except that it retrieves the maximum value of the delimitation currently in effect.
INSERT
The INSERT function inserts a record in a table. The following code sample shows how to use the INSERT function:
Customer.INIT; Customer."No." := '4711'; Customer.Name := 'John Doe'; Customer.INSERT;
8-14
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
MODIFY
The MODIFY function is used to modify an existing record. Similar to the INSERT function, it returns a Boolean value (TRUE if the record to be modified exists and FALSE otherwise.) The following code sample shows how to use the MODIFY function:
Customer.GET('4711'); Customer.Name := 'Richard Roe'; Customer.MODIFY;
MODIFYALL
The MODIFYALL function is used to do a bulk update of records. It respects the current filters, meaning that developers can perform the update on a specified set of records in a table. The MODIFYALL function does not return any value, nor does it cause an error if the set of records to be changed is empty. The following code sample shows how to use the MODIFYALL function:
Customer.SETRANGE("Salesperson Code",'PS','PS'); Customer.MODIFYALL("Salesperson Code",'JR');
The SETRANGE statement selects the records where the Salesperson Code is PS, and the MODIFYALL function changes these records to have the Salesperson Code set to JR.
DELETE
The DELETE function is used to delete a record from the database. The record to be deleted must be specified, by using the values in the primary key fields, before calling the function. The DELETE function takes filters into consideration. The DELETE function returns a Boolean value (TRUE if the record to be deleted exists and FALSE otherwise.) The following code sample shows how to use the DELETE function:
Customer."No." := '4711'; Customer.DELETE;
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-15
Transactions
Usually, developers do not have to be concerned about transactions and table locking when they develop applications in C/SIDE. There are some situations where developers must lock a table explicitly. For example, if developers inspect data in a table at the beginning of a function, and then use this data to perform various checks and calculations, and finally want to write-back a record, based on the result of this processing, they want the values that are retrieved at the beginning to be consistent with the data in the table now. In short, other users must not be able to update the table while the function is busy doing its calculations.
LOCKTABLE
The solution to keeping others from using a table that is making calculations is to lock the table manually, at the beginning of the function, by using the LOCKTABLE function.
CALCFIELDS
The CALCFIELDS function is used to update FlowFields. FlowFields are automatically updated when they are used as direct source expressions of controls. However, they must be explicitly calculated when they are not. That is, when they are part of a more complex expression.
8-16
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
The CALCFIELDS function calculates the Balance and Balance Due fields by taking account of filter setting and calculations that are defined as the CalcFormula properties of the FlowFields.
CALCSUMS
The CALCSUMS function is used to calculate the sum of one or more fields that are SumIndexFields in the record. For the CALCSUMS function to work, a key that contains the SumIndexFields must be selected as the current key. Similar to the CALCFIELDS function, the CALCSUMS function takes the current filter settings into account when performing the calculation. The following code sample shows the selection of the appropriate key, the filters setting, and the summation.
SETCURRENTKEY("Customer No."); SETRANGE("Customer No.",'10000','50000'); SETRANGE(Date,0D,TODAY); CALCSUMS(Amount);
FIELDERROR
The FIELDERROR function triggers a run-time error after displaying a fieldrelated error message. This function is similar to the ERROR function, but it is easier to use and has some benefits. Most importantly, if the name of a field is changed, for example, translated to another language in the Table Designer, the message from the FIELDERROR function reflects the current name of the field. The following code sample shows how to use the FIELDERROR function:
Item.GET('70000'); IF Class <> 'HARDWARE' THEN FIELDERROR(Class);
This causes an appropriate message to be displayed, depending on whether Class currently is empty or has a value.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-17
FIELDNAME
The FIELDNAME function returns the name of a field. By using the FIELDNAME function, messages that are created are still meaningful even if the field name is later changed. The FIELDNAME function can be used together with the FIELDERROR function. The following code sample shows this construction:
FIELDERROR(Quantity,'must not be less than ' + FIELDNAME("Quantity Shipped"));
INIT
The INIT function initializes a record. If a default value for a field is defined, by the InitValue property, this value is used for the initialization; otherwise, the default value of each data type is used. The INIT function does not initialize the fields of the primary key.
TESTFIELD
The TESTFIELD function is used to test a field against a value. If the values are not the same, the test fails, an error message is displayed, and a run-time error is triggered. This means that any changes made to the record are discarded. If the value to test against is the empty string, the field has to have a value other than blank or zero. The following code sample shows how to use the TESTFIELD function to generate an error message:
Code := 'DK' TESTFIELD(Code,'ZX');
VALIDATE
The VALIDATE function is used to call the OnValidate trigger of a field. The following code sample shows how to use the VALIDATE function to call the OnValidate trigger of the Total Amount field:
VALIDATE("Total Amount");
8-18
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
MESSAGE
The MESSAGE function has the following syntax:
MESSAGE (String [, Value1, ...])
The MESSAGE function is frequently used for debugging, such as displaying values of variables. However, if an error occurs, the process stops and the message is not displayed, because it is run non-modally. If there is no error, the MESSAGE function displays a message to the user, only after the process is completed. The message window remains open until the user clicks the OK button (or presses the ENTER key). Several characters are used for special purposes in the String parameter. The plus character (+) is used to concatenate text. The backslash character (\) is used to start a new line. The % and # symbols can be used as variable placeholders. The percent symbol is used for free format and the pound symbol is for fixed formats.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-19
CONFIRM
The CONFIRM function has the following syntax:
CONFIRM (String [, Default] [, Value1, ...])
The CONFIRM function is similar to the MESSAGE function. It displays a message to the user. The difference is that the CONFIRM function enables the user to answer a question by clicking the Yes or No button and returns a Boolean value (TRUE or FALSE), that corresponds to the user's selection. The CONFIRM function is run modally. Therefore, the system waits for the user's response. The CONFIRM function is frequently used to confirm that the user wants to continue with a process. Microsoft Dynamics NAV uses the CONFIRM functions before posting records. The user is given an opportunity to stop the posting process or to continue. The Default parameter specifies the default button in the message window. If it is FALSE, the No button is set as the default button and is active. If the user only presses ENTER, the function returns a FALSE. If the Default parameter is TRUE, the Yes button is set as the default button instead. The following code sample shows how to use the CONFIRM function:
IF NOT CONFIRM('Do you want to post the Journal Lines?') THEN EXIT; // Otherwise run the posting routine.
8-20
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
The CONFIRM function responses are limited to Yes and No. If other responses are needed, use the STRMENU function.
STRMENU
The STRMENU function has the following syntax:
STRMENU (OptionString [, DefaultNumber])
The STRMENU is used to create and display a menu window with an option group. It returns an integer value of the user's selection. If the DefaultNumber parameter is not set, the first element in the option string is defaulted as the choice, with a value of one. A zero value is returned if ESC is pressed. This indicates no choice by the user. The following code sample shows how to use the STRMENU function:
MESSAGE('Your selection returns the value of %1', STRMENU('Yes, No, N/A'));
ERROR
The ERROR function has the following syntax:
ERROR(String [, Value1, ...])
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-21
String Functions
The following functions enable the developer to manipulate strings: STRPOS COPYSTR PADSTR, STRLEN, MAXSTRLEN LOWERCASE and UPPERCASE CONVERTSTR DELCHR INCSTR SELECTSTR STRCHECKSUM
STRPOS
The following example uses the STRPOS function:
Position := STRPOS(String, SubString)
8-22
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
COPYSTR
The COPYSTR function has the following syntax:
NewString := COPYSTR(String, Position [, Length])
This function is used to copy a substring of any length from a specific position in a string to a new string. If the Length parameter is omitted, the result includes all characters from Position to the end of the string.
PADSTR
The PADSTR function has the following syntax:
NewString := PADSTR(String, Length [, FillCharacter])
This function is used to change the length of a string to another length. If the Length parameter is smaller than the actual length of the string, the string is truncated. Otherwise, it adds the filler characters to the end of the string. If the FillCharacter parameter is omitted, then blanks are added.
STRLEN
The STRLEN function has the following syntax:
Length := STRLEN(String)
This function returns an integer that is the length of the string in the parameter.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-23
Similar to the STRLEN function, the MAXSTRLEN function also returns an integer. However, that integer represents the maximum length defined for that string variable.
CONVERTSTR
The CONVERTSTR function has the following syntax:
NewString := CONVERTSTR(String, FromCharacters, ToCharacters)
This function converts the characters in a string, depending on the characters in the strings FromCharacter and ToCharacters parameters that serve as conversion tables.
DELCHR
The DELCHR function has the following syntax:
NewString := DELCHR(String [, Where] [, Which])
This function is used to delete one or more characters in a string. It can delete characters from either end of the string or all instances throughout the string. This function can be used to trim strings of blanks as follows:
DELCHR(StringVar, '<>', ' ');
INCSTR
The INCSTR function has the following syntax:
NewString := INCRSTR(String)
8-24
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
SELECTSTR
The SELECTSTR function has the following syntax:
NewString := SELECTSTR(Number, CommaString)
This function retrieves a substring from a comma-separated string. The substrings are numbered starting with one.
STRCHECKSUM
The STRCHECKSUM function has the following syntax:
CheckNumber := STRCHECKSUM(String [,WeightString] [, Modulus])
This function is used for various different applications such as bar codes. It calculates a checksum for a string that contains a number.
System Functions
System functions do not require any parameters because they return information that is stored in the system. They include the following: USERID COMPANYNAME TODAY and TIME WORKDATE GETLASTERRORTEXT and CLEARLASTERROR APPLICATIONPATH TEMPORARYPATH
USERID
The following code sample shows how to use the USERID function:
Name := USERID;
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-25
This function returns the current company that is used by the Microsoft Dynamics NAV client.
WORKDATE
The WORKDATE function has the following syntax:
[WorkDate] := WORKDATE([NewDate])
This function returns the current work date or can be used to set the work date. However, according to Microsoft Dynamics NAV standard, the work date must not be changed by code.
APPLICATIONPATH
In some cases, the application must know where the Microsoft Dynamics NAV client is installed on the hard disk. For example, the application might have to read files that are installed with Microsoft Dynamics NAV, such as company setup templates or the End-User License Agreement. The APPLICATIONPATH function returns a string specifying the installation directory, ending with a backslash ("\") and without the executable file. The string cannot exceed 255 characters.
8-26
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
The run time system interprets backslashes as line feeds. Therefore, assuming that Microsoft Dynamics NAV is installed in the default location, the result is as follows:
TEMPORARYPATH
The TEMPORARYPATH function returns the name of the folder where temporary files are created. The TEMPORARYPATH function returns the path and not a file name, so developers can determine the name of the temporary file that is created in the temporary folder. The tradeoff is that there is no guarantee that the name of the file is unique. Temporary files that are created in the temporary folder through the TEMPORARYPATH function are not deleted automatically when they are closed. The following code sample shows how to use the TEMPORARYPATH function:
TempName := TEMPORARYPATH + 'AppTemplate.HTM'; FileCreated := TempFile.CREATE(TempName); IF FileCreated THEN MESSAGE('created file: ' + TempName) ELSE MESSAGE('failed to create file');
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-27
Date Functions
The following functions provide specific information about a given date: DATE2DMY DATE2DWY CALCDATE NORMALDATE CLOSINGDATE
DATE2DMY
The DATE2DMY has the following syntax:
IntegerVar := DATE2DMY(Date, Integer)
This function returns information about the Date parameter, depending on the Integer parameter. Integer value 1 2 3 Usage Returns the day of the month (1-31) Returns the month (1-12) Returns the year (0001-9999)
8-28
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
This function also returns information about the Date parameter, depending on the Integer parameter. Integer value 1 2 3 Usage Returns the day of the week (1-7), where day 1 is Monday Returns the week of the year (1-53) Returns the year (0001-9999)
CALCDATE
The CALCDATE function has the following syntax:
CALCDATE(DateExpression [, Date])
The CALCDATE function is a powerful function. It calculates a new date based on a date expression and a reference date. The following are some examples of a date expression: Date Expression CQ + 1M - 10D -WD2 CM + 30D Usage Last Day of Current Quarter + 1 Month - 10 Days Last second Day of the Week, (last Tuesday) Last Day of Current Month + 30 Days
The following code sample shows how to use the CALCDATE function:
CALCDATE('CM +15D', 030502D);
In this code sample, the CALCDATE function starts with March 5, 2002 as the reference date and goes to the last day of that current month (CM). This brings the calculation to 03/31/02. Then it adds 15 days that results in April 15, 2002. The date expression can be of any length. It must have at least one subexpression. The system interprets the string from left to right, one sub-expression at a time. The sub-expression is either a positive or negative Term value.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-29
The Number is a positive integer. The Unit can be one of the following: Term D WD W M Q P Y Definition Date WeekDay Week Month Quarter Period Year
There is one Prefix, C, that represents the closing date of that period. The closing date for a quarter represents 11:59:59 PM of the last day of the last month in the quarter. Every date, from 01/03/0001 to 12/31/9999 has a corresponding normal date and closing date, used for closing journal entries. To the system, a closing date represents 11:59:59 PM of that date. Closing dates are sorted immediately after the corresponding normal date, but before the next normal date. The letter D indicates a normal date, and C indicates a closing date. The NORMALDATE and CLOSINGDATE functions determine which type of date is being used.
NORMALDATE
The NORMALDATE function has the following syntax:
ReturnDate := NORMALDATE(Date)
This function returns the corresponding normal date of a date. A common location to view this function is in the posting routines. For example, posting dates or invoice dates must be normal dates. The following code sample ensures that only normal dates are posted, by using the NORMALDATE function:
IF "Posting Date" <> NORMALDATE("Posting Date") THEN ERROR('Posting Date cannot be a closing date');
8-30
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
This function is the opposite of the NORMALDATE function. It returns the corresponding closing date of a date.
Number Functions
The majority of number functions are rarely used, except for the ROUND function. The ROUND function is used very frequently when dealing with currency and tax. The number functions include the following: ABS POWER ROUND RANDOMIZE RANDOM
ABS
The ABS function has the following syntax:
NewNumber := ABS(Number)
POWER
The POWER function has the following syntax:
NewNumber := POWER(Number, Power)
This function raises the Number parameter to the Power parameter. It can also be used to calculate roots. For example, to calculate the square root of 16, use POWER(16, 0.5) which returns 4.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-31
This function returns a rounded number. The Precision parameter specifies the precision used when rounding off. The default value is .01, although the settings in the General Ledger Setup affect this. The Direction parameter specifies how to round and has the following options: Direction Parameter = < > Rounding Direction Rounds to the nearest value (default) Rounds down Rounds up
RANDOMIZE
The RANDOMIZE function has the following syntax:
Randomize([Seed])
This function generates a set of random numbers. The Seed parameter is an optional integer value that is used to create a unique set of numbers. The same seed number results in the same set. If the Seed parameter is omitted, the total number of milliseconds since midnight is calculated for the current system time and is used as the seed.
RANDOM
The RANDOM function has the following syntax:
Number := RANDOM(MaxNumber)
This function returns a pseudo-random number between 1 and MaxNumber by using the random number set from the RANDOMIZE function. Until the RANDOMIZE is called again, the RANDOM function chooses a number from the same set of numbers.
Array Functions
Arrays are often used in reports for address and label information. The array functions include the following: ARRAYLEN
8-32
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
ARRAYLEN
The ARRAYLEN function has the following syntax:
Length := ARRAYLEN(Array [, Dimension])
This function returns the total number of elements in an array or the number of elements in a specific dimension of the array. A three-dimensional array has valid dimensions of one, two, and three. If the Dimension parameter is omitted, the return value represents the number of elements in the whole array, and not any dimension.
COMPRESSARRAY
The COMPRESSARRAY function has the following syntax:
[Count :=] COMPRESSARRAY(StringArray)
This function is only useful for text or code arrays. It moves all the non-empty strings of the array to the beginning of the array. The array contains the same number of elements. The empty entries and those that contain only blanks appear at the end of the array. If a return value is handled, it represents the number of non-empty strings the system compressed. A good example of how to use this function is when printing names and addresses. This function is useful to remove blank lines in account statements or from multiline addresses.
COPYARRAY
The COPYARRAY function has the following syntax:
COPYARRAY(NewArray, Array, Position [, Length])
This function copies one or more elements from an array to a new array. The Position parameter specifies the position of the first array element to copy, whereas the optional Length parameter specifies the number of array elements to copy. If the Length parameter is omitted, all array elements from Position to the last element are copied. The COPYARRAY function is only used for onedimensional arrays. It can be used repeatedly to copy more dimensions.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-33
Other Functions
The following functions are several other important functions that are used throughout Microsoft Dynamics NAV: EXIT CLEAR CLEARALL EVALUATE FORMAT
EXIT
The EXIT function has the following syntax:
EXIT (Value)
This function leaves the current function or trigger immediately. If there is a parent function that calls this current function or trigger, the Value parameter of the EXIT function is returned to the calling function. The EXIT function causes no error condition nor does it roll back any data. The following code sample shows how to use the EXIT function:
Function AddTen (Number : Integer) : Integer BEGIN EXIT(Number + 10); MESSAGE('This line is never read.'); END;
CLEAR
The CLEAR function has the following syntax:
CLEAR(Variable)
This function clears the value of a single variable, or all elements of an array, to the following: Variable Type Number String Date Time Boolean Number Clearing Result 0 (zero) Empty string 0D (undefined date) 0T (undefined time) FALSE 0 (zero)
8-34
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
EVALUATE
The EVALUATE function has the following syntax:
[Ok :=] EVALUATE(Variable, String[, Number])
This function converts a string expression into another appropriate data type. The result is assigned to the Variable parameter.
FORMAT
The FORMAT function has the following syntax:
String := FORMAT(Value [, Length] [, FormatNumber | FormatString])
This is a powerful function. At the basic level, it can convert any type of variable to a string variable. The following code sample shows how to use the FORMAT function to convert a decimal variable to a string:
TextVar := FORMAT(DecimalVar);
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-35
Returned string will have the maximum length of Length characters. If Value is less than Length characters, the length of String will equal the length of Value. If Value is an integer that exceeds Length digits, Length asterisks are placed in String. If Value is not an integer and it exceeds Length characters, String is truncated accordingly.
Only one of the next two parameters is used at any time. The FormatNumber parameter specifies the format the system uses. The basic options are as follows: Format Number value 0 1 2 Usage Standard Display Format (the default for all data types) Standard Display Format 2 (edit) C/AL Code Constant Format
Other options are available depending on the data type. The FormatString parameter is a literal string that specifies a format as in the Format property. The Format property describes the various predefined formats in detail, and how to create customized formats. The following code sample shows how to use the FORMAT function:
MESSAGE('The formatted value: %1', FORMAT(-123456.78, 15, 0));
8-36
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
FIGURE 8.11 THE FORMAT FUNCTION MESSAGE('The formatted value: %1', FORMAT(-123456.78, 5, 3)); // Changed Length to 5
When this code is run, the message window displays the following message:
FIGURE 8.12 THE FORMAT FUNCTION MESSAGE('Today is %1', FORMAT(TODAY,0,'<Month Text> <Day>.'));
When this code is run, the message window displays the following message:
Sometimes, negative numbers must be displayed as strings enclosed in parentheses instead of being preceded by a minus sign (-). If these numbers are part of a vertical list of numbers, usually a trailing space must be added at the end of the positive numbers (so that the negative numbers enclosed in parentheses are aligned with the positive numbers).
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-37
The < and > signs are part of the FormatString parameter. For the negative numbers, the parenthesis is inside the single quotation marks. For the positive values, there is a space before the last single quotation mark for alignment. When this code is run, the message window displays the following message:
8-38
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
There are many good reasons to create functions. In fact, when designing code for an object, the first thing to do is determine the major tasks and create, or define, a function for each one. Then, as similar things are organized in different locations, consider adding another function to handle that task. Another reason to create functions, which is specific to C/SIDE, is that functions are one of the main ways to communicate between objects. Variables cannot be shared across objects, but functions can.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-39
Actual Parameter
The actual parameter is used when the function is called. The following example shows an example of calling the DELSTR function:
UserInput := DELSTR(UserInput,Comma,1);
The constant and variables that appear in the parentheses are the actual parameters. There is a one-to-one correspondence between the actual parameters and the formal parameters. The actual parameter UserInput becomes the formal parameter String, the actual parameter Comma becomes the formal parameter Position and the actual parameter 1 becomes the formal parameter Length. Because this code uses a pass-by value for all three parameters, what is actually being passed to the function are the values of the three actual parameters. Therefore, the actual parameters are not changed when the formal parameters are changed inside the function. If the code uses a pass-by reference instead, it passes the variable references (memory addresses) to the function. Then the actual parameters are changed if the corresponding formal parameters are changed inside the function. Because constants cannot be changed, 1 cannot be used as an actual parameter if Length is passed by reference.
Local Function
A local function is a function that can only be called in the object in which it is defined. Any function that is not defined as a local function can be called from other objects and from the object in which it is defined.
8-40
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
For example, create a function named SQUARE that is used to square a value. The following expression results in the Answer variable being assigned the value 29.
Answer := 4 + Square(5);
The SQUARE function trigger code can be written as follows, if the formal parameter is named Param:
EXIT(Param * Param);
The EXIT statement's parameter is the expression that squared the parameter and that is what the function returns to its caller.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-41
The column named Var, an abbreviation for Variable, is used to set this parameter to be passed by reference. A parameter that is passed by reference must be a variable, not an expression. In this case, do not select this column. 9. Close the Accumulate - C/AL Locals window to return to the C/AL Globals window. The definition of the Accumulate function is now completed.
8-42
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-43
Execute Credit Action 2. Click View, C/AL Code to open the C/AL Editor. 3. Locate the OnAction trigger for the Execute Credit action. 4. Type the following code into the OnAction trigger of the action:
IF Quantity = 0 THEN EXIT; Accumulate(-Quantity);
The code in both actions is similar. The only difference is that the Execute Credit action changes the Quantity to negative before calling the functions. This means that users no longer enter negative quantities, instead, they only enter quantities, and then click either the Execute Sale or the Execute Credit action, depending on what kind of transaction it is. 5. Close the C/AL Editor and close the Action Designer. 6. Open the Properties window for the Quantity field control, and set the MinValue property to be 0 (zero). 7. Close the Properties window 8. Compile, save and close the page.
8-44
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
Summary
C/SIDE provides many built-in functions that can be used by developers. These built-in functions are predefined with their syntax. C/SIDE also lets developers create custom functions, to extend their application. Understanding the concepts of functions, when to use built-in functions and when to create custom functions helps developers to efficiently develop custom solutions for Microsoft Dynamics NAV.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-45
8-46
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
2.
3.
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement
8-47
8-48
Microsoft Official Training Materials for Microsoft Dynamics Your use of this content is subject to your current services agreement