Na2009 enus devi_11

Chapter 11: Codeunits

11-1

CHAPTER 11: CODEUNITS Objectives

The objectives are:

• Understand the concepts of codeunits. • Provide an overview of designing codeunits. • Provide an overview using codeunits. • Define Variables, Text Constants and Functions in a Codeunit. • Use the SMTP Mail codeunit.

Introduction Codeunits are like containers for code. One benefit of codeunits is that they can hold functions that are used repeatedly throughout large application projects. This enables the functions to be easily incorporated instead of having to rewrite the same lines of code. In addition, there are several standard codeunits that can be used to enrich application features, such as codeunit 400, SMTP Mail.

Microsoft Official Training Materials for Microsoft Dynamics ® Your use of this content is subject to your current services agreement

C/SIDE Introduction in Microsoft Dynamics® NAV 2009

11-2

Codeunit Fundamentals C/AL code can be stored in a form, report, or other objects. In simple applications, the general approach is to place the code in the object that calls the functions. However, as applications grow, developers often find that the same functions are used repeatedly throughout the applications.

Instead of declaring the same functions over and over again, it is useful to define them just once. This is where the C/SIDE codeunits become useful. Think of a codeunit as a container for C/AL code to be used in many application objects. In codeunits, developers can define functions, global variables, and temporary tables.

Functions

A function is a sequence of C/AL statements that developers define to create new functionality. Each function that is created in a codeunit is displayed as a separate trigger, known as a function trigger, and it has its own set of statements. A codeunit can be thought of as a container for multiple functions.

Local Variables

Within each function, developers can define local variables. A local variable's scope is limited to the function in which it is defined.

Global Variables

A global variable's scope covers all the functions in the codeunit.

Temporary Tables

A temporary table is actually a record variable which has the Temporary property set to Yes. It resembles an actual table, but it is not stored in the database. Temporary tables are mainly used as structured variables that hold data temporarily while developers work on it.

Triggers

All codeunits include two default triggers known as Documentation and OnRun. In the Documentation trigger, developers can add optional information about the code such as the purpose of the codeunit, a version number, and more. In the OnRun trigger, developers can include code that they want the system to execute when the codeunit is run.

NOTE: A codeunit can be run by using <CodeunitVariableName>.Run. When a codeunit is run, the code which is written in the OnRun trigger is executed.



11-3

Design Codeunits Codeunits are designed in the C/AL Editor which is accessed directly from the Object Designer.

Use the C/AL Editor

The C/AL Editor is where code is viewed and modified. The following shortcut keys can be used when working in the C/AL Editor.

Shortcut Key

Description

CTRL+ X Cut the selected text to the clipboard.

CTRL+ C Copy the selected text to the clipboard.

CTRL+ V Paste the text on the clipboard into the codeunit in the cursor position.

CTRL + F Open the Find window and search for text.

Use the C/AL Symbol Menu

The C/AL Symbol Menu can be accessed from the C/AL Editor. Use the C/AL Symbol Menu to get an overview of:

• All variables defined in the codeunit. • All C/AL functions.

Open the C/AL Symbol Menu by clicking View, C/AL Symbol Menu or pressing F9.

FIGURE 11.1 THE C/AL SYMBOL MENU



11-4

The information in the C/AL Symbol Menu is divided into columns. The column on the left shows all defined variable names and function categories. The second column shows the sub-categories, and the third column, on the right shows the functions in the selected category. Observe the syntax in the bottom of the window, and click the OK or the Apply button to make C/SIDE insert this string in the C/AL Editor. Clicking the OK button closes the Symbol Menu window automatically, but clicking the Apply button leaves it open.

In some cases, for example, when a control on a form is a subform or when a field is a BLOB field, there are more than three columns. Use the right arrow button to scroll the Symbol Menu columns to the right, and the left arrow button to scroll them to the left.

Use Codeunits By using codeunits, developers eliminate the need to duplicate code and make the code easier to maintain. If the same code is used repeatedly in pages or reports, create a function in a codeunit and access it by using the following syntax:

<CodeunitVariableName>.<FunctionName>

Accessing Codeunits

By using the previous method, functions in any application objects (not just codeunits) can be accessed by writing the name of the variable that represents the application object followed by the name of the function.

Codeunits can be accessed through codeunit variables either by explicitly declaring a variable of type Codeunit or by setting the RunObject property, such as in an action on a page, to a codeunit. A codeunit variable does not contain a codeunit, but only a reference to a codeunit. More than one codeunit variable can refer to the same codeunit, as shown in the following illustration.

FIGURE 11.2 THE RELATION BETWEEN CODEUNIT VARIABLES AND THE CODEUNIT



11-5

Codeunits may contain internal variables defined as global variables. These variables are not accessible directly from code outside the codeunit, but they can be accessed through user-defined functions on the codeunit.

Whenever a codeunit variable is used for the first time, a new instance of the codeunit is created, that is, a new set of internal variables is initialized so that different codeunit variables use different sets of internal variables.

Codeunits Assignment

Codeunits can be treated as objects. One codeunit variable can be assigned to another codeunit variable. This creates a new reference to the same codeunit instance. In other words, the codeunit variables then use the same set of internal variables.

CLEAR on Codeunits

When using the function CLEAR on a codeunit variable that has a reference to a codeunit instance with two or more references, it deletes the reference to the codeunit and not the actual codeunit instance. In other words, the codeunit stays intact and can still be used by other codeunit variables that may be assigned a reference to this codeunit.

To delete a codeunit instance, clear all references to the codeunit with the CLEAR function. To clear the internal variables in a codeunit, use the CLEARALL function from a user-defined function within the codeunit. When a local codeunit variable goes out of scope, meaning that it is no longer used by the codeunit, it is automatically cleared.

Single Instance Codeunits

In some cases, only one instance of a codeunit must exist. This means that all the codeunit variables of a particular codeunit use the same set of variables. When the SingleInstance property of the codeunit is set to Yes, all the codeunit variables for that codeunit use the same instance, and this allows developers to create global variables.

NOTE: It is recommended to avoid using global variables for most code. However, in certain situations, it may be necessary to use them, for example, to ensure that only one instance of an external variable is used.

A single instance codeunit is instantiated when it is used for the first time. Other codeunit instances (codeunits that do not have the SingleInstance property set to Yes) are deleted when the last codeunit variable that uses that codeunit instance goes out of scope. However, single instance codeunits remain instantiated until the current company is closed from the Microsoft Dynamics® NAV client.



11-6

Codeunits Limitations

Global variables and temporary tables in a codeunit cannot be accessed directly from other application objects. The only way to access these values is through functions which are created in the codeunit (user-defined functions.)

All C/AL functions can be used in a codeunit, although, a function name cannot be the same name as a built-in function. Two or more user-defined functions cannot have the same name, unless they are part of different application objects.

Demonstration: Define Variables, Text Constants and Functions in a Codeunit

The following steps show how to add global variables, text constants and functions in the C/AL Globals window.

1. In the Object Designer's Codeunit list, click the New button. The C/AL Editor opens.

2. Click View, C/AL Globals to open the C/AL Globals window.

Add Global Variables

To add global variables:

1. Click the Variables tab in the C/AL Globals window. 2. Type the Name and DataType to add global variables.

NOTE: If the data type selected corresponds to an application object, select a subtype, that is, the name of a specific object in the database. If the data type selected is a Text or Code, define a length for the variable. The default length is ten characters for Code, and 30 for Text. If the data type selected is OCX or Automation, also select a subtype.

Add Text Constants

To add text constants:

1. Click the Text Constants tab in the C/AL Globals window. 2. Type the Name and ConstValue to add text constants.

Add Functions

To add functions:

1. Click the Functions tab in the C/AL Globals window. 2. Type the Name to add functions. 3. Click the Locals button to define the parameters, return value, and

local variables for each function. The C/AL Locals window opens.



11-7

4. Click the Parameters tab to define parameters. o For each parameter, specify the calling method, a name, and a

data type. The subtype and length are optional depending on the data type.

o The calling method can be specified as Var which means that the parameter is passed by reference rather than by value. The value of a variable can only be changed by a function when it is passed to the function by reference.

o When the calling method is not specified as Var, only a copy of the variable is passed to the function. If the function changes that value, the change affects only the copy and not the variable itself.

5. Click the Return Value tab to define the return value for the function.

6. Type a name for the return value, and select a return type from the drop-down list. Select a length, but only if the return type is text or code.

7. Click the Variables tab to define local variables. 8. For each local variable, specify the name and data type.

NOTE: If the data type selected corresponds to an application object, select a subtype, that is, the name of a specific object in the database. If the data type selected is a Text or Code, define a length for the variable. The default length is ten characters for Code, and 30 for Text. If the data type selected is OCX or Automation, also select a subtype.

9. Click the Text Constants tab to define text constants for the function.

10. Type the Name and ConstValue to add text constants.

SMTP One other feature of Microsoft Dynamics NAV 2009 is the ability to send e-mail by using Simple Mail Transfer Protocol (SMTP). Unlike sending e-mail programmatically by using Mail Application Programming Interface (MAPI), sending e-mail by using SMTP does not require an e-mail client and account to be configured on the server.



11-8

SMTP Mail Setup

Before using the SMTP functionality, the SMTP server and account information must be provided by using the SMTP Mail Setup window (form / page 409).

FIGURE 11.3 THE SMTP MAIL SETUP FORM

With the SMTP server information in place, the functions defined in the SMTP Mail codeunit (codeunit 400) can be used.

SMTP Mail Codeunit

The SMTP Mail codeunit defines the following functions:

• CreateMessage • Send • AddRecipients • AddCC • AddBCC • AppendBody • AddAttachment • CheckValidEmailAddresses • CheckValidEmailAddress



11-9

For simple e-mail, only the first two functions are necessary. The CreateMessage function is used to configure the message, and the Send function performs the actual sending. For example, assuming that codeunit 400 is declared as a global variable named SMTPCU, the following code sends a simple e-mail message:

SMTPCU.CreateMessage( 'CRONUS International Ltd.', '[email protected]' (mailto:'[email protected]'), '[email protected]' (mailto:'[email protected]'), 'Issue Status', 'Your issue has been resolved', FALSE); SMTPCU.Send;

Several functions can be used after the CreateMessage function and before the Send function, to append additional information to the message. These functions are as follows:

Function Description

AddRecipients This function is used if there are more receiver e-mail addresses than the one that fit into the 1024 characters allowed for the Recipients parameter in the CreateMessage function.

AddCC This function is used to add carbon copy recipients.

AddBCC This function is used to add blind carbon copy recipients.

AppendBody This function is used if the message body is longer than the 1024 characters allowed in the Body parameter in the CreateMessage function.

AddAttachment This function is used to provide the path of the file to be attached in the e-mail message.

The last two functions are used to check whether a text string is for a valid e-mail address or is for valid multiple e-mail addresses.

Summary Codeunits are application objects that are primarily used as containers for code to ease development and code management. They are created and modified in the C/AL Editor. Unlike other objects, a codeunit can be set as a single instance object so that every variable that refers to it refers to the same instance of the codeunit. There are several standard codeunits that can be used to enrich application features, such as codeunit 400, SMTP Mail.



11-10

Test Your Knowledge 1. What triggers are available in every codeunit? 2. What key can be pressed to open the Symbol Menu? 3. What must be done to call a function in a codeunit from another

object? 4. Can two codeunit variables refer to the same instance of a codeunit? 5. Can two codeunit variables declared in the same object refer to

different instances of a codeunit? 6. What change needs to be made to a codeunit variable to point to the

same instance of a codeunit as another codeunit variable? 7. What function can be used to make a codeunit variable point to a

new instance of a codeunit? 8. If a codeunit is designed as a single instance codeunit, can two

codeunit variables refer to different instances of that codeunit? 9. What is the correct way to address a global variable of a codeunit

from an object that has a variable, called CU, for that codeunit? 10. Can a function named Power be created in a codeunit?



11-11

Quick Interaction: Lessons Learned Take a moment and write down three key points you have learned from this chapter

1.

2.

3.



11-12


Technology

Na2009 enus devi_11